Merge branch 'dev' into unification

Author: ErickOF

.gitignore

@@ -228,3 +228,7 @@ modules/unification/*.png
 tools/datagen/src/imgs/*_grayscale_image*
 tools/datagen/src/imgs/*_noisy_image*
 tools/datagen/src/imgs/*_sobel_*
+
+# Ignore VCD files
+*.vcd
+test

modules/Makefile

@@ -20,26 +20,19 @@ LIBDIR=-L. -L$(SYSTEMC)/lib-linux64
 SOURCES := $(wildcard $(SRCDIR)/*.cpp)
 INCLUDES := $(wildcard $(INCDIR)/*.hpp)
 OBJECTS := $(SOURCES:$(SRCDIR)/%.cpp=$(OBJDIR)/%.o)
-FV_OBJECTS := $(SOURCES:$(SRCDIR)/%.cpp=$(OBJDIR)/%.i)
 
-$(BINDIR)/$(TARGET): $(OBJECTS)
+$(BINDIR)/$(TARGET): clean $(OBJECTS)
 		@$(LD) $(OBJECTS) $(LFLAGS) $(LIBS) $(LIBDIR) -o $@
-		@echo "Linked $@ completed!"
 
 $(OBJECTS): $(OBJDIR)/%.o : $(SRCDIR)/%.cpp
 		@$(CC) $(CFLAGS) $(INCDIR) -c $< -o $@
-		@echo "Compilation $< in $@"
-
-fv_run: $(FV_OBJECTS)
-		cbmc $(FV_OBJECTS) --function sc_main
-
-$(FV_OBJECTS): $(OBJDIR)/%.i : $(SRCDIR)/%.cpp
-		@$(CC) $(CFLAGS) $(INCDIR) -c $< -o $@
-		@echo "FV compilation $< in $@"
 
 .PHONY: clean
 clean:
-		@rm -f $(OBJECTS)
-		@echo "Clean done."
+		@rm -rf obj
+		@rm -f $(TARGET)
+		@mkdir -p obj
+
+compile: $(BINDIR)/$(TARGET)
 
-all: $(BINDIR)/$(TARGET)
+all: compile run

modules/filter/Makefile

@@ -0,0 +1,65 @@
+# Adding stb lib for image handling
+CFLAGS_OPENCV := $(shell pkg-config --cflags opencv4)
+LFLAGS_OPENCV := $(shell pkg-config --libs opencv4)
+
+# Include common Makefile
+include ../Makefile
+
+# Include stb lib for compilation
+CFLAGS += $(CFLAGS_OPENCV)
+LFLAGS += $(LFLAGS_OPENCV)
+
+# 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 modes
+ifdef TEST_MODE_IMAGE
+		CFLAGS += -DTEST_MODE_IMAGE
+		LFLAGS += -DTEST_MODE_IMAGE
+else
+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
+else
+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
+endif # TEST_MODE_ONE_WINDOW_RANDOM
+endif # TEST_MODE_IMAGE
+
+# Defining preprocessor directive for model - by default PV model
+ifdef IPS_FILTER_LT_EN
+		CFLAGS += -DIPS_FILTER_LT_EN
+		LFLAGS += -DIPS_FILTER_LT_EN
+else # IPS_FILTER_AT_EN
+ifdef IPS_FILTER_AT_EN
+		CFLAGS += -DIPS_FILTER_AT_EN
+		LFLAGS += -DIPS_FILTER_AT_EN
+else # IPS_FILTER_CA_EN
+ifdef IPS_FILTER_CA_EN
+		CFLAGS += -DIPS_FILTER_CA_EN
+		LFLAGS += -DIPS_FILTER_CA_EN
+else # IPS_FILTER_PV_EN
+		CFLAGS += -DIPS_FILTER_PV_EN
+		LFLAGS += -DIPS_FILTER_PV_EN
+endif # IPS_FILTER_CA_EN
+endif # IPS_FILTER_AT_EN
+endif # IPS_FILTER_LT_EN
+
+# Run the compiled file
+run:
+		@./test
+
+# Show waveform
+waveform:
+		@gtkwave ips_filter.vcd

modules/filter/README.md

@@ -1,3 +1,73 @@
 # **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.
+
+To compile a specific model, you can use the switches:
+
+* `IPS_FILTER_PV_EN`: Programmer's View model.
+* `IPS_FILTER_LT_EN`: Loosely Timed model.
+* `IPS_FILTER_AT_EN`: Approximately Timed model.
+* `IPS_FILTER_CA_EN`: Cycle Approximate model (pending to be implemented).
+
+### **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**
+
+Since VCD is not generated, this command will not work for the PV model.
+
+```shell
+make waveform
+```

modules/filter/include/ips_filter_at_model.hpp

@@ -0,0 +1,171 @@
+#ifndef IPS_FILTER_AT_MODEL_HPP
+#define IPS_FILTER_AT_MODEL_HPP
+#ifdef IPS_DEBUG_EN
+#include <iostream>
+#endif // IPS_DEBUG_ENi
+#ifdef IPS_DUMP_EN
+#include <sstream>
+#endif // IPS_DUMP_EN
+#include <systemc.h>
+
+
+/**
+ * @brief Filter module.
+ * It takes care of filtering a image/kernel using a median filter or an
+ * equivalent convolution like:
+ *                 | 1/N^2 ... 1/N^2 |   | img(row - N/2, col - N/2) ... img(row + N/2, col + N/2) |
+ * img(row, col) = |  ...  ...  .... | * |            ...            ...            ...            |
+ *                 | 1/N^2 ... 1/N^2 |   | img(row + N/2, col - N/2) ... img(row + N/2, col + N/2) |
+ *
+ * @tparam IN - data type of the inputs
+ * @tparam OUT - data type of the outputs
+ * @tparam N - size of the kernel
+ */
+template <typename IN = sc_uint<8>, typename OUT = sc_uint<8>, uint8_t N = 3>
+SC_MODULE(Filter)
+{
+protected:
+  //----------------------------Internal Variables----------------------------
+#ifdef IPS_DUMP_EN
+  sc_trace_file* wf;
+#endif // IPS_DUMP_EN
+  OUT* kernel;
+
+  // Event to trigger the filter execution
+  sc_event event;
+
+  //-----------------------------Internal Methods-----------------------------
+  void exec_filter();
+  void init();
+
+public:
+  sc_in<IN* > img_window;
+  sc_out<OUT > result;
+  /**
+   * @brief Default constructor for Filter
+   */
+  SC_HAS_PROCESS(Filter);
+#ifdef IPS_DUMP_EN
+  /**
+   * @brief Construct a new Filter object
+   * 
+   * @param name - name of the module
+   * @param wf - waveform file pointer
+   */
+  Filter(sc_core::sc_module_name name, sc_core::sc_trace_file* wf)
+    : sc_core::sc_module(name), wf(wf)
+#else
+  /**
+   * @brief Construct a new Filter object
+   * 
+   * @param name - name of the module
+   */
+  Filter(sc_core::sc_module_name name) : sc_core::sc_module(name)
+#endif // IPS_DUMP_EN
+  {
+    // Calling this method by default since it is no time consumer
+    // It is assumed that this kernel is already loaded in the model
+    // Kernel does not change after synthesis
+    SC_METHOD(init);
+    // Thread waiting for the request
+    SC_THREAD(exec_filter);
+  }
+
+  //---------------------------------Methods---------------------------------
+  void filter();
+};
+
+/**
+ * @brief Execute the image filtering
+ * 
+ */
+template <typename IN, typename OUT, uint8_t N>
+void Filter<IN, OUT, N>::exec_filter()
+{
+  size_t i;
+  size_t j;
+
+  OUT result_tmp;
+
+  while (true)
+  {
+    // Wait to peform the convolution
+    wait(this->event);
+
+    // Default value for the result depending on the output datatype
+    result_tmp = (OUT) 0;
+
+    // Getting the image window to filter
+    IN* img_window_tmp = this->img_window.read();
+
+    // Perform the convolution
+    for (i = 0; i < N; ++i)
+      for (j = 0; j < N; ++j)
+        result_tmp += this->kernel[i * N + j] * ((OUT) img_window_tmp[i * N + j]);
+
+    this->result.write(result_tmp);
+  }
+}
+
+/**
+ * @brief Filtering image
+ * 
+ * @param img_window - image window to filter
+ * @param result - resultant pixel
+ */
+template <typename IN, typename OUT, uint8_t N>
+void Filter<IN, OUT, N>::filter()
+{
+  this->event.notify(DELAY_TIME, SC_NS);
+}
+
+/**
+ * @brief Initializes a kernel of N x N with default value of 1 / (N^2)
+ * 
+ */
+template <typename IN, typename OUT, uint8_t N>
+void Filter<IN, OUT, N>::init()
+{
+  // 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
+  // Print the initialized kernel
+  SC_REPORT_INFO(this->name(), "init 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
+      // Adding the signals to the waveform
+      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;
+  }
+#else
+#ifdef IPS_DUMP_EN
+  size_t i, j;
+
+  for (i = 0; i < N; ++i)
+  {
+    for (j = 0; j < N; ++j)
+    {
+      // Adding the signals to the waveform
+      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
+#endif // IPS_DEBUG_EN
+}
+#endif // IPS_FILTER_AT_MODEL_HPP