Add --start-from option (#2273)

Add a new option to the FIRRTL compiler, "--start-from = <form>".  If
used, this will cause the compiler to assume that the input FIRRTL
circuit is already in the specific form.  It will then skip unnecessary
passes given this information.

E.g., if a user requests to run "firrtl -X verilog --start-from low"
then the compiler will only run transforms necessary to get from low
FIRRTL to Verilog.  Transforms necessary for ingesting FIRRTL IR will be
run if needed (checks and type/kind/flow resolution).

To implement this, a CurrentFirrtlStateAnnotation is added.  Advanced
users can use this directly to tell the FIRRTL compiler exactly what
transforms have already been run, including the ability to ignore checks
or type/kind/flow resolution if they so desire.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

1 files changed, 66 insertions, 0 deletions

diff --git a/src/test/scala/firrtl/stage/CurrentFirrtlStateAnnotationSpec.scala b/src/test/scala/firrtl/stage/CurrentFirrtlStateAnnotationSpec.scala
new file mode 100644
index 00000000..121a4e81
--- /dev/null
+++ b/src/test/scala/firrtl/stage/CurrentFirrtlStateAnnotationSpec.scala
@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package firrtl.stage
+
+import firrtl.options.Dependency
+import firrtl.stage.transforms.Compiler
+import firrtl.stage.TransformManager.TransformDependency
+import org.scalatest.flatspec.AnyFlatSpec
+import org.scalatest.matchers.should.Matchers
+
+class CurrentFirrtlStateAnnotationSpec extends AnyFlatSpec with Matchers {
+
+  def getTransforms(input: String): Seq[TransformDependency] = {
+    val currentState = CurrentFirrtlStateAnnotation
+      .options(0)
+      .toAnnotationSeq(input)
+      .collectFirst {
+        case CurrentFirrtlStateAnnotation(currentState) => currentState
+      }
+      .get
+    new Compiler(Forms.VerilogOptimized, currentState).flattenedTransformOrder.map(Dependency.fromTransform)
+  }
+
+  behavior.of("CurrentFirrtlStateAnnotation")
+
+  it should "produce an expected transform order for CHIRRTL -> Verilog" in {
+    getTransforms("chirrtl") should contain(Dependency(firrtl.passes.CheckChirrtl))
+  }
+
+  it should "produce an expected transform order for minimum high FIRRTL -> Verilog" in {
+    val transforms = getTransforms("mhigh")
+    transforms should not contain noneOf(Dependency(firrtl.passes.CheckChirrtl), Dependency(firrtl.passes.InferTypes))
+    transforms should contain(Dependency(firrtl.passes.CheckHighForm))
+  }
+
+  it should "produce an expected transform order for high FIRRTL -> Verilog" in {
+    val transforms = getTransforms("high")
+    transforms should not contain (Dependency[firrtl.transforms.DedupModules])
+    (transforms should contain).allOf(
+      Dependency(firrtl.passes.InferTypes),
+      Dependency[firrtl.passes.ExpandWhensAndCheck]
+    )
+  }
+
+  it should "produce an expected transform order for middle FIRRTL -> Verilog" in {
+    val transforms = getTransforms("middle")
+    transforms should not contain (Dependency[firrtl.passes.ExpandWhensAndCheck])
+    (transforms should contain).allOf(Dependency(firrtl.passes.InferTypes), Dependency(firrtl.passes.LowerTypes))
+  }
+
+  it should "produce an expected transform order for low FIRRTL -> Verilog" in {
+    val transforms = getTransforms("low")
+    transforms should not contain (Dependency(firrtl.passes.LowerTypes))
+    (transforms should contain).allOf(
+      Dependency(firrtl.passes.InferTypes),
+      Dependency(firrtl.passes.CommonSubexpressionElimination)
+    )
+  }
+
+  it should "produce an expected transform order for optimized low FIRRTL -> Verilog" in {
+    val transforms = getTransforms("low-opt")
+    transforms should not contain (Dependency(firrtl.passes.CommonSubexpressionElimination))
+    (transforms should contain).allOf(Dependency(firrtl.passes.InferTypes), Dependency[firrtl.transforms.VerilogRename])
+  }
+
+}