Merge pull request #4 from ErickOF/feature-filter_module

Adding filter module and testbench using PV model

Author: ErickOF

.gitignore

@@ -223,3 +223,7 @@ pyrightconfig.json
 tools/datagen/src/imgs/*_grayscale_image*
 tools/datagen/src/imgs/*_noisy_image*
 tools/datagen/src/imgs/*_sobel_*
+
+# Ignore VCD files
+*.vcd
+test

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "stb"]
+	path = stb
+	url = https://github.com/nothings/stb

modules/filter/Makefile

@@ -0,0 +1,42 @@
+# Adding stb lib for image handling
+INCDIR_STB=lib/stb
+INCLUDES_STB := $(wildcard $(INCDIR_STB)/*.h)
+
+# Include common Makefile
+include ../Makefile
+
+# Include stb lib for compilation
+INCLUDES += INCLUDES_STB
+
+# Defining preprocessor directive for debug
+ifdef IPS_DEBUG_EN
+	CFLAGS += -DIPS_DEBUG_EN
+	LFLAGS += -DIPS_DEBUG_EN
+endif # IPS_DEBUG_EN
+
+# Defining preprocessor directive for dumping enable
+ifdef IPS_DUMP_EN
+	CFLAGS += -DIPS_DUMP_EN
+	LFLAGS += -DIPS_DUMP_EN
+endif # IPS_DUMP_EN
+
+# Defining preprocessor directive for test mode one window random
+ifdef TEST_MODE_ONE_WINDOW_RANDOM
+	CFLAGS += -DTEST_MODE_ONE_WINDOW -DTEST_MODE_ONE_WINDOW_RANDOM
+	LFLAGS += -DTEST_MODE_ONE_WINDOW -DTEST_MODE_ONE_WINDOW_RANDOM
+endif # TEST_MODE_ONE_WINDOW_RANDOM
+
+# Defining preprocessor directive for test mode one wildcard normal
+ifdef TEST_MODE_ONE_WINDOW_NORMAL
+	CFLAGS += -DTEST_MODE_ONE_WINDOW -DTEST_MODE_ONE_WINDOW_NORMAL
+	LFLAGS += -DTEST_MODE_ONE_WINDOW -DTEST_MODE_ONE_WINDOW_NORMAL
+endif # TEST_MODE_ONE_WINDOW_NORMAL
+
+
+# Run the compiled file
+run:
+	@./test
+
+# Show waveform
+waveform:
+	@gtkwave ips_filter.vcd

modules/filter/README.md

@@ -1,3 +1,63 @@
 # **Filter Module**
 
-Add compilation instructions
+## **Filter Algorithm: Mean Filter**
+The mean filter algorithm replaces each pixel value with the average of all
+pixel values in an N by N window (N = 3, 5, 7, etc), where the pixel to
+replace is the centering pixel. Assuming that the centering pixel is in (0, 0)
+position:
+
+$
+img(row, col) = \sum_{i = -N/2}^{N/2} {\sum_{j = -N/2}^{-N/2} {img(row + i, col + j)}}
+$
+
+Also, it can computed using a convolution like:
+
+$
+img(row, col) = \begin{bmatrix}
+  \frac{1}{N^{2}} & \dots  & \frac{1}{N^{2}} \\
+  \vdots          & \ddots & \vdots          \\
+  \frac{1}{N^{2}} & \dots  & \frac{1}{N^{2}}
+\end{bmatrix}
+\ast
+\begin{bmatrix}
+  img(row - N/2, col - N/2) & \dots  & img(row + N/2, col + N/2) \\
+  \vdots                    & \ddots & \vdots                     \\
+  img(row + N/2, col - N/2) & \dots  & img(row + N/2, col + N/2)
+\end{bmatrix}
+$
+
+
+## **Usage**
+
+A Makefile is used to compile the testbench and filter module. There are some
+Makefile targets to compile the different modules and tests. By default, the
+PV model is compiled. The available test options are:
+
+* `TEST_MODE_ONE_WINDOW_NORMAL`: Runs only one window with fixed values.
+* `TEST_MODE_ONE_WINDOW_RANDOM`: Runs only one window with random values.
+
+Some additional options can used to debug and dump the waveform:
+
+* `IPS_DEBUG_EN`: Prints the kernel, each window value, and the result.
+* `IPS_DUMP_EN`: Creates a VCD file with each value of the window and kernel,
+ and the result.
+
+### **Compilation**
+Runs the `make` command with the corresponding switches to compile.
+
+For instance, to run only one window in debug mode and dump the signals:
+
+```shell
+make TEST_MODE_ONE_WINDOW_RANDOM=1 IPS_DUMP_EN=1 IPS_DEBUG_EN=1
+```
+
+### **Run**
+
+```shell
+make run
+```
+
+### **Open Waveform**
+```shell
+make waveform
+```

modules/filter/include/ips_filter_at_model.hpp

@@ -0,0 +1,82 @@
+#ifndef IPS_FILTER_FILTER_HPP
+#define IPS_FILTER_FILTER_HPP
+#ifdef IPS_DEBUG_EN
+#include <iostream>
+#endif // IPS_DEBUG_ENi
+#ifdef IPS_DUMP_EN
+#include <sstream>
+#endif // IPS_DUMP_EN
+#include <systemc.h>
+#include <vector>
+
+
+template <typename IN = sc_uint<8>, typename OUT = sc_uint<8>, uint8_t N = 3>
+SC_MODULE(Filter)
+{
+  //-----------------------------Local Variables-----------------------------
+#ifdef IPS_DUMP_EN
+  sc_trace_file* wf;
+#endif // IPS_DUMP_EN
+  OUT* kernel;
+
+  /**
+   * @brief Default constructor for Filter
+   */
+  SC_CTOR(Filter);
+  //template <typename IN, typename OUT, uint8_t N>
+#ifdef IPS_DUMP_EN
+  Filter(sc_core::sc_module_name name, sc_core::sc_trace_file* wf)
+    : sc_core::sc_module(name), wf(wf)
+#else
+  Filter(sc_core::sc_module_name name) : sc_core::sc_module(name)
+#endif // IPS_DUMP_EN
+  {
+    SC_METHOD(init_kernel);
+  }
+
+  //---------------------------------Methods---------------------------------
+  void filter(IN* img_window, OUT& result);
+  void init_kernel();
+};
+
+template <typename IN, typename OUT, uint8_t N>
+void Filter<IN, OUT, N>::filter(IN* img_window, OUT& result)
+{
+  size_t i;
+  size_t j;
+
+  result = (OUT) 0;
+
+  for (i = 0; i < N; ++i)
+    for (j = 0; j < N; ++j)
+      result += this->kernel[i * N + j] * ((OUT) img_window[i * N + j]);
+}
+
+template <typename IN, typename OUT, uint8_t N>
+void Filter<IN, OUT, N>::init_kernel()
+{
+  // Init a kernel of N x N with default value of 1 / (N * N)
+  this->kernel = new OUT[N * N];
+  std::fill_n(this->kernel, N * N, ((OUT) 1) / ((OUT) N * N));
+#ifdef IPS_DEBUG_EN
+  SC_REPORT_INFO(this->name(), "init_kernel result");
+  size_t i, j;
+
+  for (i = 0; i < N; ++i)
+  {
+    for (j = 0; j < N; ++j)
+    {
+      std::cout << "[" << this->kernel[i * N + j] << "]";
+
+#ifdef IPS_DUMP_EN
+      std::ostringstream var_name;
+      var_name << "kernel_" << i << "_" << j;
+      sc_trace(this->wf, this->kernel[i * N + j], var_name.str());
+#endif // IPS_DUMP_EN
+    }
+
+    std::cout << std::endl;
+  }
+#endif // IPS_DEBUG_EN
+}
+#endif // IPS_FILTER_FILTER_HPP

modules/filter/include/ips_filter_lt_model.hpp

@@ -0,0 +1,134 @@
+#ifdef TEST_MODE_ONE_WINDOW_RANDOM
+#include <cstdlib>
+#endif // TEST_MODE_ONE_WINDOW_RANDOM
+#ifdef IPS_DUMP_EN
+#include <sstream>
+#endif // IPS_DUMP_EN
+#include <systemc.h>
+
+#define IPS_FILTER_PV_EN
+
+#define IPS_FILTER_KERNEL_SIZE 3
+#define IPS_IN_TYPE_TB float
+#define IPS_OUT_TYPE_TB float
+
+#ifdef IPS_FILTER_AT_EN
+#include "ips_filter_at_model.hpp"
+#elif defined(IPS_FILTER_LT_EN)
+#include "ips_filter_lt_model.hpp"
+#elif defined(IPS_FILTER_PV_EN)
+#include "ips_filter_pv_model.hpp"
+#else
+#error "No IPS_FILTER macro is defined. Please define one of IPS_FILTER_AT_EN, IPS_FILTER_LT_EN, or IPS_FILTER_PV_EN."
+#endif // IPS_FILTER_XX_EN
+
+
+#ifdef TEST_MODE_ONE_WINDOW
+#ifdef IPS_DUMP_EN
+void run_one_window(sc_trace_file* wf)
+#else
+void run_one_window()
+#endif // IPS_DUMP_EN
+{
+#ifdef IPS_DEBUG_EN
+  #ifdef TEST_MODE_ONE_WINDOW_RANDOM
+  SC_REPORT_INFO("TEST_MODE_ONE_WINDOW_NORMAL", "Running test");
+  #elif defined(TEST_MODE_ONE_WINDOW_NORMAL)
+  SC_REPORT_INFO("TEST_MODE_ONE_WINDOW_NORMAL", "Running test");
+  #else
+  SC_REPORT_INFO("TEST_MODE_ONE_WINDOW_DEFAULT", "Running test");
+  #endif // TEST_MODE_ONE_WINDOW_RANDOM
+  SC_REPORT_INFO("Initialize window", "Window value");
+#endif
+
+  // Variables
+  IPS_IN_TYPE_TB *img_window;
+  IPS_OUT_TYPE_TB result;
+
+  // Initialize image window
+  img_window = new IPS_IN_TYPE_TB[IPS_FILTER_KERNEL_SIZE * IPS_FILTER_KERNEL_SIZE];
+
+  for (size_t i = 0; i < IPS_FILTER_KERNEL_SIZE; ++i)
+  {
+    for (size_t j = 0; j < IPS_FILTER_KERNEL_SIZE; ++j)
+    {
+      IPS_IN_TYPE_TB value;
+
+#ifdef TEST_MODE_ONE_WINDOW_RANDOM
+      value = (IPS_IN_TYPE_TB) (rand() % 256);
+#elif defined(TEST_MODE_ONE_WINDOW_NORMAL)
+      value = (IPS_IN_TYPE_TB) (i * IPS_FILTER_KERNEL_SIZE + j);
+#else
+      value = (IPS_IN_TYPE_TB) i;
+#endif // TEST_MODE_ONE_WINDOW
+
+      img_window[i * IPS_FILTER_KERNEL_SIZE + j] = value;
+
+#ifdef IPS_DUMP_EN
+      std::ostringstream var_name;
+      var_name << "img_window_" << i << "_" << j;
+      sc_trace(wf, img_window[i * IPS_FILTER_KERNEL_SIZE + j], var_name.str());
+#endif // IPS_DUMP_EN
+#ifdef IPS_DEBUG_EN
+      std::cout << "[" << img_window[i * IPS_FILTER_KERNEL_SIZE + j] << "]";
+#endif // IPS_DUMP_EN
+    }
+
+#ifdef IPS_DEBUG_EN
+    std::cout << std::endl;
+#endif // IPS_DEBUG_EN
+  }
+
+  // Instantiate filter module and do the connection
+#ifdef IPS_DUMP_EN
+  Filter<IPS_IN_TYPE_TB, IPS_OUT_TYPE_TB, IPS_FILTER_KERNEL_SIZE> filter("filter", wf);
+#else
+  Filter<IPS_IN_TYPE_TB, IPS_OUT_TYPE_TB, IPS_FILTER_KERNEL_SIZE> filter("filter");
+#endif // IPS_DEBUG_EN
+
+  sc_start();
+
+#ifdef IPS_DEBUG_EN
+  std::cout << "Test starting" << std::endl;
+  std::cout << "@" << sc_time_stamp() << std::endl;
+#endif // IPS_DEBUG_EN
+
+  // Apply convolution
+  filter.filter(img_window, result);
+#ifdef IPS_DEBUG_EN
+  SC_REPORT_INFO("TEST_MODE_ONE_WINDOW", "filtering");
+  std::cout << "Result = " << result << std::endl;
+#endif // IPS_DEBUG_EN
+
+#ifdef IPS_DUMP_EN
+  sc_trace(wf, result, "result");
+  sc_start(1, SC_NS);
+#endif // IPS_DUMP_EN
+
+  delete [] img_window;
+}
+#endif // TEST_MODE_ONE_WINDOW
+
+
+int sc_main(int, char*[])
+{
+  // Pass command linke arguments
+  sc_argc();
+  sc_argv();
+
+#ifdef IPS_DUMP_EN
+  // Open VCD file
+  sc_trace_file* wf = sc_create_vcd_trace_file("ips_filter");
+  wf->set_time_unit(1, SC_NS);
+#endif // IPS_DUMP_EN
+
+#ifdef TEST_MODE_ONE_WINDOW
+  run_one_window(wf);
+#endif // TEST_MODE_ONE_WINDOW
+
+#ifdef IPS_DUMP_EN
+  std::cout << "@" << sc_time_stamp() << " Terminating simulation" << std::endl;
+  sc_close_vcd_trace_file(wf);
+#endif // IPS_DUMP_EN
+  return 0;
+}