before/after initial block macros (#1550)

* adding init macros

* fix missing tick

* adding more documentation; fixing up emitter tests

* adding initial-guarding macro test

* prefixing macros with FIRRTL

* cleanup

* typo fix

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

4 files changed, 76 insertions, 6 deletions

diff --git a/src/main/scala/firrtl/Emitter.scala b/src/main/scala/firrtl/Emitter.scala
index 2ebf11b6..84f11eef 100644
--- a/src/main/scala/firrtl/Emitter.scala
+++ b/src/main/scala/firrtl/Emitter.scala
@@ -1029,6 +1029,10 @@ class VerilogEmitter extends SeqTransform with Emitter {
         }
         emit(Seq("`endif"))
         emit(Seq("`ifndef SYNTHESIS"))
+        // User-defined macro of code to run before an initial block
+        emit(Seq("`ifdef FIRRTL_BEFORE_INITIAL"))
+        emit(Seq("`FIRRTL_BEFORE_INITIAL"))
+        emit(Seq("`endif"))
         emit(Seq("initial begin"))
         emit(Seq("  `ifdef RANDOMIZE"))
         emit(Seq("    `ifdef INIT_RANDOM"))
@@ -1054,6 +1058,10 @@ class VerilogEmitter extends SeqTransform with Emitter {
         for (x <- asyncInitials) emit(Seq(tab, x))
         emit(Seq("  `endif // RANDOMIZE"))
         emit(Seq("end // initial"))
+        // User-defined macro of code to run after an initial block
+        emit(Seq("`ifdef FIRRTL_AFTER_INITIAL"))
+        emit(Seq("`FIRRTL_AFTER_INITIAL"))
+        emit(Seq("`endif"))
         emit(Seq("`endif // SYNTHESIS"))
       }
 
diff --git a/src/main/scala/firrtl/util/BackendCompilationUtilities.scala b/src/main/scala/firrtl/util/BackendCompilationUtilities.scala
index 20a65895..91b88090 100644
--- a/src/main/scala/firrtl/util/BackendCompilationUtilities.scala
+++ b/src/main/scala/firrtl/util/BackendCompilationUtilities.scala
@@ -100,14 +100,16 @@ trait BackendCompilationUtilities extends LazyLogging {
     * @param cppHarness C++ testharness to compile/link against
     * @param suppressVcd specifies if VCD tracing should be suppressed
     * @param resourceFileName specifies what filename to look for to find a .f file
+    * @param extraCmdLineArgs list of additional command line arguments
     */
-  def verilogToCpp(
+  def verilogToCppWithExtraCmdLineArgs(
     dutFile: String,
     dir: File,
     vSources: Seq[File],
     cppHarness: File,
     suppressVcd: Boolean = false,
-    resourceFileName: String = firrtl.transforms.BlackBoxSourceHelper.defaultFileListName
+    resourceFileName: String = firrtl.transforms.BlackBoxSourceHelper.defaultFileListName,
+    extraCmdLineArgs: Seq[String] = Seq.empty
   ): ProcessBuilder = {
 
     val topModule = dutFile
@@ -138,6 +140,7 @@ trait BackendCompilationUtilities extends LazyLogging {
       "verilator",
       "--cc", s"${dir.getAbsolutePath}/$dutFile.v"
     ) ++
+      extraCmdLineArgs ++
       blackBoxVerilogList ++
       vSourcesFiltered.flatMap(file => Seq("-v", file.getCanonicalPath)) ++
       Seq("--assert",
@@ -160,6 +163,18 @@ trait BackendCompilationUtilities extends LazyLogging {
     command
   }
 
+  @deprecated("use verilogtoCppWithExtraCmdLineArgs","1.3")
+  def verilogToCpp(
+    dutFile: String,
+    dir: File,
+    vSources: Seq[File],
+    cppHarness: File,
+    suppressVcd: Boolean = false,
+    resourceFileName: String = firrtl.transforms.BlackBoxSourceHelper.defaultFileListName
+  ): ProcessBuilder = {
+    verilogToCppWithExtraCmdLineArgs(dutFile, dir, vSources, cppHarness, suppressVcd, resourceFileName)
+  }
+
   def cppToExe(prefix: String, dir: File): ProcessBuilder =
     Seq("make", "-C", dir.toString, "-j", "-f", s"V$prefix.mk", s"V$prefix")
 
diff --git a/src/test/scala/firrtl/testutils/FirrtlSpec.scala b/src/test/scala/firrtl/testutils/FirrtlSpec.scala
index e14dc78c..8f0241fe 100644
--- a/src/test/scala/firrtl/testutils/FirrtlSpec.scala
+++ b/src/test/scala/firrtl/testutils/FirrtlSpec.scala
@@ -254,7 +254,9 @@ object FirrtlCheckers extends FirrtlMatchers {
   /** Checks that the emitted circuit has the expected line, both will be normalized */
   def containLine(expectedLine: String) = containLines(expectedLine)
 
-  /** Checks that the emitted circuit has the expected lines in order, all lines will be normalized */
+  /** Checks that the emitted circuit contains the expected lines contiguously and in order;
+    * all lines will be normalized
+    */
   def containLines(expectedLines: String*) = new CircuitStateStringsMatcher(expectedLines)
 
   class CircuitStateStringsMatcher(expectedLines: Seq[String]) extends Matcher[CircuitState] {
diff --git a/src/test/scala/firrtlTests/VerilogEmitterTests.scala b/src/test/scala/firrtlTests/VerilogEmitterTests.scala
index 46661595..7adc490f 100644
--- a/src/test/scala/firrtlTests/VerilogEmitterTests.scala
+++ b/src/test/scala/firrtlTests/VerilogEmitterTests.scala
@@ -2,6 +2,8 @@
 
 package firrtlTests
 
+import java.io.File
+
 import firrtl._
 import firrtl.annotations._
 import firrtl.passes._
@@ -10,6 +12,8 @@ import firrtl.transforms.CombineCats
 import firrtl.testutils._
 import firrtl.testutils.FirrtlCheckers._
 
+import scala.sys.process.{Process, ProcessLogger}
+
 class DoPrimVerilog extends FirrtlFlatSpec {
   "Xorr" should "emit correctly" in {
     val compiler = new VerilogCompiler
@@ -384,7 +388,7 @@ class VerilogEmitterSpec extends FirrtlFlatSpec {
     }
   }
 
-  "Initial Blocks" should "be guarded by ifndef SYNTHESIS" in {
+  "Initial Blocks" should "be guarded by ifndef SYNTHESIS and user-defined optional macros" in {
     val input =
       """circuit Test :
         |  module Test :
@@ -398,8 +402,16 @@ class VerilogEmitterSpec extends FirrtlFlatSpec {
         """.stripMargin
     val state = CircuitState(parse(input), ChirrtlForm)
     val result = (new VerilogCompiler).compileAndEmit(state, List())
-    result should containLines ("`ifndef SYNTHESIS", "initial begin")
-    result should containLines ("end // initial", "`endif // SYNTHESIS")
+    result should containLines ("`ifndef SYNTHESIS",
+                                "`ifdef FIRRTL_BEFORE_INITIAL",
+                                "`FIRRTL_BEFORE_INITIAL",
+                                "`endif",
+                                "initial begin")
+    result should containLines ("end // initial",
+                                "`ifdef FIRRTL_AFTER_INITIAL",
+                                "`FIRRTL_AFTER_INITIAL",
+                                "`endif",
+                                "`endif // SYNTHESIS")
   }
 
   "Verilog name conflicts" should "be resolved" in {
@@ -865,3 +877,36 @@ class VerilogDescriptionEmitterSpec extends FirrtlFlatSpec {
     }
   }
 }
+
+class EmittedMacroSpec extends FirrtlPropSpec {
+  property("User-defined macros for before/after initial should be supported") {
+    val prefix = "Printf"
+    val testDir = compileFirrtlTest(prefix, "/features")
+    val harness = new File(testDir, s"top.cpp")
+    copyResourceToFile(cppHarnessResourceName, harness)
+
+    // define macros to print
+    val cmdLineArgs = Seq(
+      "+define+FIRRTL_BEFORE_INITIAL=initial begin $fwrite(32'h80000002, \"printing from FIRRTL_BEFORE_INITIAL macro\\n\"); end",
+      "+define+FIRRTL_AFTER_INITIAL=initial begin $fwrite(32'h80000002, \"printing from FIRRTL_AFTER_INITIAL macro\\n\"); end"
+    )
+
+    verilogToCppWithExtraCmdLineArgs(prefix, testDir, List.empty, harness, extraCmdLineArgs = cmdLineArgs) #&&
+      cppToExe(prefix, testDir) !
+      loggingProcessLogger
+
+    // check for expected print statements
+    var saw_before = false
+    var saw_after = false
+    Process(s"./V${prefix}", testDir) !
+      ProcessLogger(line => {
+        line match {
+          case "printing from FIRRTL_BEFORE_INITIAL macro" => saw_before = true
+          case "printing from FIRRTL_AFTER_INITIAL macro" => saw_after = true
+          case _ => // Do Nothing
+        }
+      })
+
+    assert(saw_before & saw_after)
+  }
+}