DFCxx simulation

README.md

@@ -211,9 +211,9 @@ The compiled Utopia HLS executable has a CLI to accept a number of parameters af
 
 For the executable there are three general arguments: `-h,--help`, `-H,--help-all` and `-v,--version` for printing simple and extended help-messages, and printing current executable's version respectively.
 
-Unless neither of the three arguments is used, first argument is the mode which the executable has to function in. Currently there is only one available mode `hls`.
+Unless neither of the three arguments is used, first argument is the mode which the executable has to function in. Currently there are only two available modes: `hls` and `sim`.
 
-The list of arguments for `hls`-mode is presented below:
+`hls` mode is used to translate the provided DFCxx kernel to different output formats. The list of arguments for `hls`-mode is presented below:
 
 * `-h,--help`: *optional* flag; used to print the help-message about other arguments.
 * `--config <PATH>`: *required* filesystem-path option; used to specify the file for a JSON latency configuration file. Its format is presented in *JSON Configuration* section.
@@ -232,6 +232,12 @@ Here is an example of an Utopia HLS CLI call:
 umain hls --config ~/utopia-user/config.json --out-sv ~/outFile.sv --out-dfcir ~/outFile2.mlir -a
 ```
 
+`sim` mode is used to simulate the provided DFCxx kernel. The list of arguments for `sim`-mode is presented below:
+
+* `-h,--help`: *optional* flag; used to print the help-message about other arguments.
+* `--in <PATH>`: *optional* filesystem-path option; used to specify the input file for simulation data (default: `sim.txt`). Its format is presented in *DFCxx Simulation Input Format* section.
+* `--out <PATH>`: *optional* filesystem-path option; used to specify the output VCD file (default: `sim_out.txt`).
+
 ### JSON Configuration
 
 Latency configuration for each computational operation (number of pipeline stages) used in a DFCxx kernel is provided via a JSON file.
@@ -268,6 +274,33 @@ Here is an example of a JSON configuration file, containing latencies for multip
 }
 ```
 
+### DFCxx Simulation Input Format
+
+DFCxx kernels can be simulated to check that they describe computations as expected. The simulation doesn't include scheduling-related characteristics, thus DFCxx concepts like *offsets* are not supported, every computational node has to use **and** accept some value. 
+The format to provide simulation input data is the following:
+
+* input data is divided into blocks separated with a newline character (`\n`) - one block for each clock period
+* every block has a number of lines, each of which has the name of some **input** stream/scalar value and its hex-value (these values do not have a type - it is assumed from the corresponding computational nodes)
+* stream/scalar value name and the value are separated with a single space character (` `)
+* the provided value must be a valid hex-value: with or without `0x`, with either lower- or uppercase letters
+* if some stream/scalar value is present twice or more in the same block - its latest described value is used
+* after the last block **no newline character can be present**
+
+Here is an example of an input simulation file for `MuxMul` kernel, which has two input streams `x` and `ctrl`.
+
+```txt
+x 0x32
+ctrl 0x1
+
+x 0x45
+ctrl 0x0
+
+x 0x56
+ctrl 0x1
+```
+
+In this example, `x` accepts values `50` (`0x32`), `69` (`0x45`) and `86` (`0x56`), while `ctrl` accepts `1`, `0` and `1`. This means that 3 clock periods will be simulated for the provided kernel.
+
 ## Examples
 
 Root subdirectory `examples` contains different examples of DFCxx kernels, `start`-function definitions and JSON configuration files.
@@ -282,7 +315,15 @@ build/src/umain hls --config examples/polynomial2/add_int_2_mul_int3.json -a --o
 
 The execution command is going to pass a JSON configuration file (with 2 and 3 pipeline stages for integer addition
 and multiplication respectively) to Utopia HLS, resulting in the creation of the file `output`, containing a SystemVerilog
-module for Polynomial2 kernel with a greedy ASAP-scheduling.
+module for `Polynomial2` kernel with a greedy ASAP-scheduling.
+
+The same kernel can be simulated with:
+
+```bash
+build/src/umain sim --in examples/polynomial2/sim.txt --out output.vcd
+```
+
+This command uses the simulation data from `sim.txt` file to output a VCD-file `output.vcd`.
 
 ## DFCxx Documentation
 

config.json

@@ -8,5 +8,9 @@
     "out_dfcir"      : "",
     "out_firrtl"     : "",
     "out_dot"        : ""
+  },
+  "sim": {
+    "in"           : "sim.txt",
+    "out"          : "sim_out.txt"
   }
 }

examples/addconst/sim.txt

@@ -0,0 +1,5 @@
+x 0x32
+
+x 0x45
+
+x 0x56

examples/idct/idct.h

@@ -53,17 +53,17 @@ class IDCT : public dfcxx::Kernel {
       DFVariable x7 = (values[kDIM * i + 3]);
 
       DFVariable x8 = (x4 + x5) * W7;
-      x4 = x8 + (W1 - W7) * x4;
-      x5 = x8 - (W1 - W7) * x5;
-      x8 = W3 * (x6 + x7);
-      x6 = x8 - (W3 - W5) * x6;
-      x7 = x8 - (W3 + W5) * x7;
+      x4 = x8 + x4 * (W1 - W7);
+      x5 = x8 - x5 * (W1 + W7);
+      x8 = (x6 + x7) * W3;
+      x6 = x8 - x6 * (W3 - W5);
+      x7 = x8 - x7 * (W3 + W5);
 
       x8 = x0 + x1;
       x0 = x0 - x1;
       x1 = (x3 + x2) * W6;
-      x2 = x1 - (W2 + W6) * x2;
-      x3 = x1 + (W2 - W6) * x3;
+      x2 = x1 - x2 * (W2 + W6);
+      x3 = x1 + x3 * (W2 - W6);
       x1 = x4 + x6;
       x4 = x4 - x6;
       x6 = x5 + x7;
@@ -97,17 +97,17 @@ class IDCT : public dfcxx::Kernel {
       DFVariable x7 = values[kDIM * 3 + i];
 
       DFVariable x8 = ((x4 + x5) * W7) + const4;
-      x4 = (x8 + (W1 - W7) * x4) >> 3;
-      x5 = (x8 - (W1 - W7) * x5) >> 3;
-      x8 = (W3 * (x6 + x7)) + const4;
-      x6 = (x8 - (W3 - W5) * x6) >> 3;
-      x7 = (x8 - (W3 + W5) * x7) >> 3;
+      x4 = (x8 + x4 * (W1 - W7)) >> 3;
+      x5 = (x8 - x5 * (W1 + W7)) >> 3;
+      x8 = ((x6 + x7) * W3) + const4;
+      x6 = (x8 - x6 * (W3 - W5)) >> 3;
+      x7 = (x8 - x7 * (W3 + W5)) >> 3;
 
       x8 = x0 + x1;
       x0 = x0 - x1;
       x1 = ((x3 + x2) * W6) + const4;
-      x2 = (x1 - (W2 + W6) * x2) >> 3;
-      x3 = (x1 + (W2 - W6) * x3) >> 3;
+      x2 = (x1 - x2 * (W2 + W6)) >> 3;
+      x3 = (x1 + x3 * (W2 - W6)) >> 3;
       x1 = x4 + x6;
       x4 = x4 - x6;
       x6 = x5 + x7;
@@ -119,7 +119,7 @@ class IDCT : public dfcxx::Kernel {
       x0 = x0 - x2;
       x2 = (((x4 + x5) * const181) + const128) >> 8;
       x4 = (((x4 - x5) * const181) + const128) >> 8;
-      
+
       values[kDIM * 0 + i] = (x7 + x1) >> 14;
       values[kDIM * 1 + i] = (x3 + x2) >> 14;
       values[kDIM * 2 + i] = (x0 + x4) >> 14;

examples/idct/sim.txt

@@ -0,0 +1,64 @@
+x0 0x0
+x1 0x1
+x2 0x2
+x3 0x3
+x4 0x4
+x5 0x5
+x6 0x6
+x7 0x7
+x8 0x8
+x9 0x9
+x10 0xA
+x11 0xB
+x12 0xC
+x13 0xD
+x14 0xE
+x15 0xF
+x16 0x10
+x17 0x11
+x18 0x12
+x19 0x13
+x20 0x14
+x21 0x15
+x22 0x16
+x23 0x17
+x24 0x18
+x25 0x19
+x26 0x1A
+x27 0x1B
+x28 0x1C
+x29 0x1D
+x30 0x1E
+x31 0x1F
+x32 0x20
+x33 0x21
+x34 0x22
+x35 0x23
+x36 0x24
+x37 0x25
+x38 0x26
+x39 0x27
+x40 0x28
+x41 0x29
+x42 0x2A
+x43 0x2B
+x44 0x2C
+x45 0x2D
+x46 0x2E
+x47 0x2F
+x48 0x30
+x49 0x31
+x50 0x32
+x51 0x33
+x52 0x34
+x53 0x35
+x54 0x36
+x55 0x37
+x56 0x38
+x57 0x39
+x58 0x3A
+x59 0x3B
+x60 0x3C
+x61 0x3D
+x62 0x3E
+x63 0x3F

examples/matrixmul2/sim.txt

@@ -0,0 +1,8 @@
+x11 0x32
+x12 0x64
+x21 0x48
+x22 0x99
+y11 0x1
+y12 0x0
+y21 0x0
+y22 0x1

examples/muxmul/sim.txt

@@ -0,0 +1,8 @@
+x 0x32
+ctrl 0x1
+
+x 0x45
+ctrl 0x0
+
+x 0x56
+ctrl 0x1

examples/polynomial2/sim.txt

@@ -0,0 +1,5 @@
+x 0x32
+
+x 0x45
+
+x 0x56

examples/scalar3/sim.txt

@@ -0,0 +1,6 @@
+x1 0x2
+y1 0x32
+x2 0x3
+y2 0x32
+x3 0x4
+y3 0x32

src/main.cpp

@@ -19,29 +19,42 @@
 
 INITIALIZE_EASYLOGGINGPP
 
+// User-defined function to specify functional behaviour of top-level kernel.
+std::unique_ptr<dfcxx::Kernel> start();
+
 //===-----------------------------------------------------------------------===/
 // High-Level Synthesis
 //===-----------------------------------------------------------------------===/
 
 struct HlsContext {
-  HlsContext(const HlsOptions &options):
-    options(options)
-    {}
+  HlsContext(const HlsOptions &options) : options(options) {}
 
   const HlsOptions &options;
 };
 
-// User-defined function to specify functional behaviour of top-level kernel.
-std::unique_ptr<dfcxx::Kernel> start();
+//===-----------------------------------------------------------------------===/
+// DFCxx Simulation.
+//===-----------------------------------------------------------------------===/
+
+struct SimContext {
+  SimContext(const SimOptions &options): options(options) {}
 
-int hlsMain(HlsContext &context) {
+  const SimOptions &options;
+};
+
+int hlsMain(const HlsContext &context) {
   auto kernel = start();
   bool useASAP = context.options.asapScheduler;
-  kernel->compile(context.options.latConfig,
-                  context.options.outNames,
-                  (useASAP) ? dfcxx::Scheduler::ASAP 
-                            : dfcxx::Scheduler::Linear);
-  return 0;
+  return !kernel->compile(context.options.latConfig,
+                          context.options.outNames,
+                          (useASAP) ? dfcxx::Scheduler::ASAP 
+                                    : dfcxx::Scheduler::Linear);
+}
+
+int simMain(const SimContext &context) {
+  auto kernel = start();
+  return !kernel->simulate(context.options.inFilePath,
+                           context.options.outFilePath);
 }
 
 int main(int argc, char **argv) {
@@ -63,7 +76,10 @@ int main(int argc, char **argv) {
   catch(const CLI::ParseError &e) {
     return options.exit(e);
   }
-
-  HlsContext context(options.hls);
-  return hlsMain(context);
+
+  if (options.hls) {
+    return hlsMain(HlsContext(options.hls));
+  } else {
+    return simMain(SimContext(options.sim));
+  }
 }

src/model/dfcxx/include/dfcxx/DFCXX.h

@@ -9,7 +9,9 @@
 #ifndef DFCXX_H
 #define DFCXX_H
 
-#include "kernel.h"
-#include "typedefs.h"
+#include "dfcxx/kernel.h"
+#include "dfcxx/typedefs.h"
+#include "dfcxx/types/types.h"
+#include "dfcxx/vars/vars.h"
 
 #endif // DFCXX_H

src/model/dfcxx/include/dfcxx/channel.h

@@ -17,7 +17,8 @@ struct Channel {
   Node source;
   Node target;
   unsigned opInd;
-
+
+  Channel() = default;
   Channel(Node source, Node target, unsigned opInd);
 
   bool operator==(const Channel &channel) const;

src/model/dfcxx/include/dfcxx/constant.h

@@ -9,9 +9,7 @@
 #ifndef DFCXX_CONSTANT_H
 #define DFCXX_CONSTANT_H
 
-#include "dfcxx/graph.h"
-#include "dfcxx/kernstorage.h"
-#include "dfcxx/varbuilders/builder.h"
+#include "dfcxx/kernmeta.h"
 
 namespace dfcxx {
 
@@ -21,13 +19,9 @@ class Constant {
   friend Kernel;
 
 private:
-  Graph &graph;
-  GraphHelper helper;
-  VarBuilder &varBuilder;
-  KernStorage &storage;
+  KernMeta &meta;
 
-  Constant(Graph &graph, TypeBuilder &typeBuilder,
-           VarBuilder &varBuilder, KernStorage &storage);
+  Constant(KernMeta &meta);
 
 public:
   DFVariable var(const DFType &type, int64_t value);

src/model/dfcxx/include/dfcxx/control.h

@@ -9,9 +9,7 @@
 #ifndef DFCXX_CONTROL_H
 #define DFCXX_CONTROL_H
 
-#include "dfcxx/graph.h"
-#include "dfcxx/kernstorage.h"
-#include "dfcxx/varbuilders/builder.h"
+#include "dfcxx/kernmeta.h"
 
 #include <initializer_list>
 
@@ -23,13 +21,9 @@ class Control {
   friend Kernel;
 
 private:
-  Graph &graph;
-  GraphHelper helper;
-  VarBuilder &varBuilder;
-  KernStorage &storage;
+  KernMeta &meta;
 
-  Control(Graph &graph, TypeBuilder &typeBuilder,
-          VarBuilder &varBuilder, KernStorage &storage);
+  Control(KernMeta &meta);
 
 public:
   DFVariable mux(DFVariable ctrl, std::initializer_list<DFVariable> args);