FST generation (#19)

* Added support to generate fst for ESSENT which gives 2x speedup and reduces waveform size by 135x

* Update README.md

How to compile and run ESSENT with VCD or FST

* Update README.md

---------

Co-authored-by: Priyanka Dutta <[email protected]>

Author: MSPDUTTA

README.md

@@ -18,6 +18,7 @@ Essent is written in Scala, which runs on the JVM. To run essent, it's easiest t
 + `O2` - Muxes are represented with `if/else` blocks instead of ternary statements `?`. As many signals as possible are pulled into the if or else blocks. If both the if and else blocks will be trivially one statement, the optimization will not be performed.
 + `O3` - Attempts to exploit low activity factors by reusing results from the previous cycle. The design will be partitioned, and each partition will get its own eval function. If none of the inputs to a partition change, its outputs will be reused. These partitions can include state elements.
 
+
 Example invocations:
 
     $ ./essent --help
@@ -55,7 +56,6 @@ int main() {
 }
 ```
 
-
 Compiling everything
 --------------------------------------------------------------------------------
 
@@ -64,9 +64,49 @@ Since essent emits a single header file for a firrtl circuit, the entire simulat
 An example compile command:
 
     $ g++ -O3 -std=c++11 -I./firrtl-sig design-harness.cc -o simulator
-
+    
 On macOS, when using clang, we also found `-fno-slp-vectorize` to improve compile time for large designs, and `-fbracket-depth=1024` allows it to handle designs with deeply nested muxes.
 
+Running with waveform
+--------------------------------------------------------------------------------
+To generate waveform with ESSENT you can choose either format , VCD or FST and then you can view using gtkwave waveform viewer.
+
+```
+Install gtkwave by entering the following commands in the terminal:
+
+sudo apt update
+sudo apt install gtkwave
+```
+Compile: 
++ `withVCD` - This flag enabled generates waveform in VCD format , which can be viewed using gtkwave; disabled by default 
++ `withFST` - This flag enabled generates waveform in FST format , which can be viewed using gtkwave; disabled by default
+
+Example invocations:
+
+```
+    $ ./essent -O3 -withVCD my_design.fir
+```
+
+Requitered update in Harness file:
+
+Before we start the simulation , we need to add the below to the testbench file, which generates the header part of the VCD or FST. 
+
+  top->genWaveHeader();
+   
+Running:
+We do not need any extra argument to run with VCD , it is same as running essent without VCD.
+
+with FST:
+Please install vcd2fst before we run with FST.
+Instead of going into generating FST from scratch, we are using vcd2fst tool to convert our VCD related data into streams and compress parallely to generate 
+in a form of FST format, which is 135x smaller than VCD file. 
+```
+
+clang++ -O3 -std=c++11 -fno-slp-vectorize -fbracket-depth=1024 -Iriscv/include -I../firrtl-sig emulator.cc -o emulator_fst -Lriscv/lib -Wl,-rpath,riscv/lib -lfesvr -lpthread
+
+./emulator_fst dhrystone.riscv | **vcd2fst -p -v /dev/stdin -f** dump_mydesign.fst"
+```
+
 
 Examples
 --------------------------------------------------------------------------------

src/main/scala/ArgsParser.scala

@@ -19,6 +19,7 @@ case class OptFlags(
     partStats: Boolean = false,
     partCutoff: Int = 8,
     withVCD: Boolean = false,
+    withFST: Boolean = false,
     essentLogLevel: String = "warn",
     firrtlLogLevel: String = "warn") {
   def inputFileDir() = firInputFile.getParent
@@ -111,6 +112,12 @@ class ArgsParser {
         removeFlatConnects = false,
         withVCD = true)
     ).text("parameter used for vcd generation")
+
+    opt[Unit]("withFST").abbr("withFST").action( (_, c) => c.copy(
+        removeFlatConnects = false,
+        withVCD = true,
+        withFST = true)
+    ).text("parameter used for vcd generation")
   }
 
   def getConfig(args: Seq[String]): Option[OptFlags] = parser.parse(args, OptFlags())

src/main/scala/Vcd.scala

@@ -240,7 +240,10 @@ class Vcd(circuit: Circuit, initopt: OptFlags, w: Writer, rn: Renamer) {
   def genWaveHeader(): Unit = {
     w.writeLines(1, "void genWaveHeader() {")
     w.writeLines(0, "")
-    w.writeLines(1,s"""outfile = fopen("dump_$topName.vcd","w+");""") 
+    if(opt.withFST) 
+      w.writeLines(1,s"""outfile = fopen("/dev/stdout","w+");""") 
+    else 
+      w.writeLines(1,s"""outfile = fopen("dump_$topName.vcd","w+");""") 
     w.writeLines(2, "time_t timetoday;")
     w.writeLines(2, "time (&timetoday);")
     writeFprintf(""" "%s","$version Essent version 1 $end\n");""")
@@ -312,7 +315,8 @@ class Vcd(circuit: Circuit, initopt: OptFlags, w: Writer, rn: Renamer) {
                  val cleanName = rn.removeDots(name)
                   if(rn.nameToMeta(name).decType != ExtIO && rn.nameToMeta(name).decType != RegSet) {
                     if(!cleanName.contains("$_") && !cleanName.contains("$next") && !cleanName.startsWith("_")) {
-                      compSig(cleanName,rn.vcdOldValue(cleanName))
+                      val temp_str = compSig(cleanName,rn.vcdOldValue(cleanName))
+                      w.writeLines(indentLevel, temp_str)
                        w.writeLines(indentLevel, s""" ${rn.vcdOldValue(cleanName)} = $cleanName;""")
                     }
                   }