Add ChiselPhase, Stop writing files in ChiselStage$ methods, Expand ChiselStage$ helpers (#1566)

* Add ChiselPhase

* Use ChiselPhase in ChiselStage, remove targets

Switch from a one-off PhaseManager inside ChiselStage to actually
using the newly added ChiselPhase. This removes the targets
method (and API) from ChiselStage.

* Stop writing to files in ChiselStage$ methods

Change the ChiselStage companion object methods, elaborate and
convert, to not write files. Under the hood, these are switched from
using ChiselStage (which, like all phases, will write files) to using
ChiselPhase.

* Test that ChiselStage$ methods write no files

Modify existing ChiselStage object method tests to check that no files
are written.

* Expand ChiselStage$ API with more helpers

This adds additional methods to the ChiselStage object for going
directly from a Chisel module to a string including: CHIRRTL, high
FIRRTL IR, Verilog, and SystemVerilog.

Differing from their ChiselStage class counterparts, these take no
arguments other than the module and write no files.

* Add tests of new ChiselStage$ helper methods

* Use ChiselStage object in tests

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

2 files changed, 125 insertions, 17 deletions

diff --git a/src/main/scala/chisel3/stage/ChiselPhase.scala b/src/main/scala/chisel3/stage/ChiselPhase.scala
new file mode 100644
index 00000000..200bc2b6
--- /dev/null
+++ b/src/main/scala/chisel3/stage/ChiselPhase.scala
@@ -0,0 +1,28 @@
+// See LICENSE for license details.
+
+package chisel3.stage
+
+import firrtl.options.{
+  Dependency,
+  Phase,
+  PhaseManager
+}
+import firrtl.options.phases.DeletedWrapper
+
+private[chisel3] class ChiselPhase extends PhaseManager(ChiselPhase.targets) {
+
+  override val wrappers = Seq( (a: Phase) => DeletedWrapper(a) )
+
+}
+
+private[chisel3] object ChiselPhase {
+
+  val targets: Seq[PhaseManager.PhaseDependency] =
+    Seq( Dependency[chisel3.stage.phases.Checks],
+         Dependency[chisel3.stage.phases.AddImplicitOutputFile],
+         Dependency[chisel3.stage.phases.AddImplicitOutputAnnotationFile],
+         Dependency[chisel3.stage.phases.MaybeAspectPhase],
+         Dependency[chisel3.stage.phases.Convert],
+         Dependency[chisel3.stage.phases.MaybeFirrtlStage] )
+
+}
diff --git a/src/main/scala/chisel3/stage/ChiselStage.scala b/src/main/scala/chisel3/stage/ChiselStage.scala
index c201a12c..30723430 100644
--- a/src/main/scala/chisel3/stage/ChiselStage.scala
+++ b/src/main/scala/chisel3/stage/ChiselStage.scala
@@ -2,10 +2,18 @@
 
 package chisel3.stage
 
-import firrtl.{ir => fir, AnnotationSeq, EmittedFirrtlCircuitAnnotation, EmittedVerilogCircuitAnnotation}
+import firrtl.{
+  ir => fir,
+  AnnotationSeq,
+  EmittedFirrtlCircuitAnnotation,
+  EmittedVerilogCircuitAnnotation,
+  HighFirrtlEmitter,
+  VerilogEmitter,
+  SystemVerilogEmitter
+}
 import firrtl.options.{Dependency, Phase, PhaseManager, Shell, Stage, StageError, StageMain}
 import firrtl.options.phases.DeletedWrapper
-import firrtl.stage.{FirrtlCircuitAnnotation, FirrtlCli}
+import firrtl.stage.{FirrtlCircuitAnnotation, FirrtlCli, RunFirrtlTransformAnnotation}
 import firrtl.options.Viewer.view
 
 import chisel3.{ChiselException, RawModule}
@@ -22,16 +30,13 @@ class ChiselStage extends Stage {
 
   val shell: Shell = new Shell("chisel") with ChiselCli with FirrtlCli
 
-  val targets: Seq[Dependency[Phase]] =
-    Seq( Dependency[chisel3.stage.phases.Checks],
-         Dependency[chisel3.stage.phases.AddImplicitOutputFile],
-         Dependency[chisel3.stage.phases.AddImplicitOutputAnnotationFile],
-         Dependency[chisel3.stage.phases.MaybeAspectPhase],
-         Dependency[chisel3.stage.phases.Convert],
-         Dependency[chisel3.stage.phases.MaybeFirrtlStage] )
+  val targets: Seq[PhaseManager.PhaseDependency] = ChiselPhase.targets
 
-  final lazy val phaseManager = new PhaseManager(targets) {
-    override val wrappers = Seq( (a: Phase) => DeletedWrapper(a) )
+  final lazy val phaseManager = {
+    val _targets = targets
+    new ChiselPhase {
+      override val targets = _targets
+    }
   }
 
   def run(annotations: AnnotationSeq): AnnotationSeq = try {
@@ -143,13 +148,13 @@ object ChiselStage {
     * @param gen a call-by-name Chisel module
     */
   def elaborate(gen: => RawModule): cir.Circuit = {
-    val stage = new ChiselStage {
+    val phase = new ChiselPhase {
       override val targets = Seq( Dependency[chisel3.stage.phases.Checks],
                                   Dependency[chisel3.stage.phases.Elaborate] )
     }
 
-    stage
-      .execute(Array("--no-run-firrtl"), Seq(ChiselGeneratorAnnotation(() => gen)))
+    phase
+      .transform(Seq(ChiselGeneratorAnnotation(() => gen), NoRunFirrtlCompilerAnnotation))
       .collectFirst {
         case ChiselCircuitAnnotation(a) => a
       }
@@ -160,7 +165,7 @@ object ChiselStage {
     * @param gen a call-by-name Chisel module
     */
   def convert(gen: => RawModule): fir.Circuit = {
-    val stage = new ChiselStage {
+    val phase = new ChiselPhase {
       override val targets = Seq(
         Dependency[chisel3.stage.phases.Checks],
         Dependency[chisel3.stage.phases.Elaborate],
@@ -170,12 +175,87 @@ object ChiselStage {
         Dependency[chisel3.stage.phases.Convert] )
     }
 
-    stage
-      .execute(Array("--no-run-firrtl"), Seq(ChiselGeneratorAnnotation(() => gen)))
+    phase
+      .transform(Seq(ChiselGeneratorAnnotation(() => gen)))
       .collectFirst {
         case FirrtlCircuitAnnotation(a) => a
       }
       .get
   }
 
+  /** Return a CHIRRTL string for a Chisel module
+    * @param gen a call-by-name Chisel module
+    */
+  def emitChirrtl(gen: => RawModule): String = convert(gen).serialize
+
+  /** Return a FIRRTL string for a Chisel module
+    * @param gen a call-by-name Chisel module
+    */
+  def emitFirrtl(gen: => RawModule): String = {
+    val phase = new PhaseManager(
+      Seq(
+        Dependency[chisel3.stage.phases.Checks],
+        Dependency[chisel3.stage.phases.Elaborate],
+        Dependency[chisel3.stage.phases.AddImplicitOutputFile],
+        Dependency[chisel3.stage.phases.AddImplicitOutputAnnotationFile],
+        Dependency[chisel3.stage.phases.MaybeAspectPhase],
+        Dependency[chisel3.stage.phases.Convert],
+        Dependency[firrtl.stage.phases.Compiler] )
+    )
+
+    phase
+      .transform(Seq(ChiselGeneratorAnnotation(() => gen), RunFirrtlTransformAnnotation(new HighFirrtlEmitter)))
+      .collectFirst {
+        case EmittedFirrtlCircuitAnnotation(a) => a
+      }.get
+      .value
+
+  }
+
+  /** Return a Verilog string for a Chisel module
+    * @param gen a call-by-name Chisel module
+    */
+  def emitVerilog(gen: => RawModule): String = {
+    val phase = new PhaseManager(
+      Seq(
+        Dependency[chisel3.stage.phases.Checks],
+        Dependency[chisel3.stage.phases.Elaborate],
+        Dependency[chisel3.stage.phases.AddImplicitOutputFile],
+        Dependency[chisel3.stage.phases.AddImplicitOutputAnnotationFile],
+        Dependency[chisel3.stage.phases.MaybeAspectPhase],
+        Dependency[chisel3.stage.phases.Convert],
+        Dependency[firrtl.stage.phases.Compiler] )
+    )
+
+    phase
+      .transform(Seq(ChiselGeneratorAnnotation(() => gen), RunFirrtlTransformAnnotation(new VerilogEmitter)))
+      .collectFirst {
+        case EmittedVerilogCircuitAnnotation(a) => a
+      }.get
+      .value
+  }
+
+  /** Return a SystemVerilog string for a Chisel module
+    * @param gen a call-by-name Chisel module
+    */
+  def emitSystemVerilog(gen: => RawModule): String = {
+    val phase = new PhaseManager(
+      Seq(
+        Dependency[chisel3.stage.phases.Checks],
+        Dependency[chisel3.stage.phases.Elaborate],
+        Dependency[chisel3.stage.phases.AddImplicitOutputFile],
+        Dependency[chisel3.stage.phases.AddImplicitOutputAnnotationFile],
+        Dependency[chisel3.stage.phases.MaybeAspectPhase],
+        Dependency[chisel3.stage.phases.Convert],
+        Dependency[firrtl.stage.phases.Compiler] )
+    )
+
+    phase
+      .transform(Seq(ChiselGeneratorAnnotation(() => gen), RunFirrtlTransformAnnotation(new SystemVerilogEmitter)))
+      .collectFirst {
+        case EmittedVerilogCircuitAnnotation(a) => a
+      }.get
+      .value
+  }
+
 }