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>

9 files changed, 87 insertions, 39 deletions

diff --git a/src/test/scala/chiselTests/BetterNamingTests.scala b/src/test/scala/chiselTests/BetterNamingTests.scala
index dd17a015..9c309091 100644
--- a/src/test/scala/chiselTests/BetterNamingTests.scala
+++ b/src/test/scala/chiselTests/BetterNamingTests.scala
@@ -90,9 +90,8 @@ class BetterNamingTests extends ChiselFlatSpec {
       }
       WireDefault(3.U)
     }
-    val stage = new ChiselStage
-    val withLits = stage.emitChirrtl(new MyModule(true))
-    val noLits = stage.emitChirrtl(new MyModule(false))
+    val withLits = ChiselStage.emitChirrtl(new MyModule(true))
+    val noLits = ChiselStage.emitChirrtl(new MyModule(false))
     withLits should equal (noLits)
   }
 }
diff --git a/src/test/scala/chiselTests/Clock.scala b/src/test/scala/chiselTests/Clock.scala
index 4b10d3b4..b6c9adc1 100644
--- a/src/test/scala/chiselTests/Clock.scala
+++ b/src/test/scala/chiselTests/Clock.scala
@@ -31,7 +31,7 @@ class ClockSpec extends ChiselPropSpec {
   }
 
   property("Should be able to use withClock in a module with no reset") {
-    val circuit = (new ChiselStage).emitChirrtl(new WithClockAndNoReset)
+    val circuit = ChiselStage.emitChirrtl(new WithClockAndNoReset)
     circuit.contains("reg a : UInt<1>, clock2") should be (true)
   }
 }
diff --git a/src/test/scala/chiselTests/Direction.scala b/src/test/scala/chiselTests/Direction.scala
index 52d7a20b..14977804 100644
--- a/src/test/scala/chiselTests/Direction.scala
+++ b/src/test/scala/chiselTests/Direction.scala
@@ -240,7 +240,7 @@ class DirectionSpec extends ChiselPropSpec with Matchers with Utils {
       assert(DataMirror.directionOf(flippedVecFlipped(index).b) == Direction.Output)
     }
 
-    val emitted: String = (new ChiselStage).emitChirrtl(new MyModule)
+    val emitted: String = ChiselStage.emitChirrtl(new MyModule)
     val firrtl: String = ChiselStage.convert(new MyModule).serialize
 
     // Check that emitted directions are correct.
@@ -307,7 +307,7 @@ class DirectionSpec extends ChiselPropSpec with Matchers with Utils {
       assert(DataMirror.directionOf(vecOutputFlipped(index).b) == Direction.Output)
     }
 
-    val emitted: String = (new ChiselStage).emitChirrtl(new MyModule)
+    val emitted: String = ChiselStage.emitChirrtl(new MyModule)
     val firrtl: String = ChiselStage.convert(new MyModule).serialize
 
     // Check that emitted directions are correct.
diff --git a/src/test/scala/chiselTests/InvalidateAPISpec.scala b/src/test/scala/chiselTests/InvalidateAPISpec.scala
index 5890310e..7aa91528 100644
--- a/src/test/scala/chiselTests/InvalidateAPISpec.scala
+++ b/src/test/scala/chiselTests/InvalidateAPISpec.scala
@@ -12,7 +12,7 @@ import org.scalatest.matchers.should.Matchers
 
 class InvalidateAPISpec extends ChiselPropSpec with Matchers with BackendCompilationUtilities with Utils {
 
-  def myGenerateFirrtl(t: => Module): String = (new ChiselStage).emitChirrtl(t)
+  def myGenerateFirrtl(t: => Module): String = ChiselStage.emitChirrtl(t)
   def compileFirrtl(t: => Module): Unit = {
     val testDir = createTestDirectory(this.getClass.getSimpleName)
 
diff --git a/src/test/scala/chiselTests/MuxSpec.scala b/src/test/scala/chiselTests/MuxSpec.scala
index 71f4cd86..01033384 100644
--- a/src/test/scala/chiselTests/MuxSpec.scala
+++ b/src/test/scala/chiselTests/MuxSpec.scala
@@ -38,35 +38,34 @@ class MuxLookupWrapper(keyWidth: Int, default: Int, mapping: () => Seq[(UInt, UI
 class MuxLookupExhaustiveSpec extends ChiselPropSpec {
   val keyWidth = 2
   val default = 9 // must be less than 10 to avoid hex/decimal mismatches
-  val firrtlLit = s"""UInt<4>("h0$default")"""
-  val stage = new ChiselStage
+  val firrtlLit = s"""UInt<4>("h$default")"""
 
   // Assumes there are no literals with 'UInt<4>("h09")' in the output FIRRTL
   // Assumes no binary recoding in output
 
   val incomplete = () => Seq(0.U -> 1.U, 1.U -> 2.U, 2.U -> 3.U)
   property("The default value should not be optimized away for an incomplete MuxLookup") {
-    stage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, incomplete)) should include (firrtlLit)
+    ChiselStage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, incomplete)) should include (firrtlLit)
   }
 
   val exhaustive = () => (3.U -> 0.U) +: incomplete()
   property("The default value should be optimized away for an exhaustive MuxLookup") {
-    stage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, exhaustive)) should not include (firrtlLit)
+    ChiselStage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, exhaustive)) should not include (firrtlLit)
   }
 
   val overlap = () => (4096.U -> 0.U) +: incomplete()
   property("The default value should not be optimized away for a MuxLookup with 2^{keyWidth} non-distinct mappings") {
-    stage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, overlap)) should include (firrtlLit)
+    ChiselStage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, overlap)) should include (firrtlLit)
   }
 
   val nonLiteral = () => { val foo = Wire(UInt()); (foo -> 1.U) +: incomplete() }
   property("The default value should not be optimized away for a MuxLookup with a non-literal") {
-    stage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, nonLiteral)) should include (firrtlLit)
+    ChiselStage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, nonLiteral)) should include (firrtlLit)
   }
 
   val nonLiteralStillFull = () => { val foo = Wire(UInt()); (foo -> 1.U) +: exhaustive() }
   property("The default value should be optimized away for a MuxLookup with a non-literal that is still full") {
-    stage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, nonLiteralStillFull)) should not include (firrtlLit)
+    ChiselStage.emitChirrtl(new MuxLookupWrapper(keyWidth, default, nonLiteralStillFull)) should not include (firrtlLit)
   }
 
 }
diff --git a/src/test/scala/chiselTests/PrintableSpec.scala b/src/test/scala/chiselTests/PrintableSpec.scala
index 2ac2ad5d..283af640 100644
--- a/src/test/scala/chiselTests/PrintableSpec.scala
+++ b/src/test/scala/chiselTests/PrintableSpec.scala
@@ -38,7 +38,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
     class MyModule extends BasicTester {
       printf(p"An exact string")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("An exact string", Seq())) =>
       case e => fail()
@@ -48,7 +48,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
     class MyModule extends BasicTester {
       printf(p"First " + PString("Second ") + "Third")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("First Second Third", Seq())) =>
       case e => fail()
@@ -59,7 +59,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       val myInt = 1234
       printf(p"myInt = $myInt")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("myInt = 1234", Seq())) =>
       case e => fail()
@@ -70,7 +70,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       val myWire = WireDefault(1234.U)
       printf(p"myWire = ${Decimal(myWire)}")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("myWire = %d", Seq("myWire"))) =>
       case e => fail()
@@ -80,7 +80,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
     class MyModule extends BasicTester {
       printf(Decimal(10.U(32.W)))
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("%d", Seq(lit))) =>
         assert(lit contains "UInt<32>")
@@ -91,7 +91,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
     class MyModule extends BasicTester {
       printf(p"%")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("%%", Seq())) =>
       case e => fail()
@@ -101,7 +101,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
     class MyModule extends BasicTester {
       printf(p"\t")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("\\t", Seq())) =>
       case e => fail()
@@ -127,7 +127,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       printf(p"${FullName(myWire.foo)}")
       printf(p"${FullName(myInst.io.fizz)}")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     println(firrtl)
     getPrintfs(firrtl) match {
       case Seq(Printf("foo", Seq()),
@@ -146,7 +146,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       val myInst = Module(new MySubModule)
       printf(p"${myInst.io.fizz}")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("%d", Seq("myInst.io.fizz"))) =>
       case e => fail()
@@ -158,7 +158,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       val mySInt = WireDefault(-1.S)
       printf(p"$myUInt & $mySInt")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("%d & %d", Seq("myUInt", "mySInt"))) =>
       case e => fail()
@@ -170,7 +170,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       myVec foreach (_ := 0.U)
       printf(p"$myVec")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("Vec(%d, %d, %d, %d)",
                Seq("myVec[0]", "myVec[1]", "myVec[2]", "myVec[3]"))) =>
@@ -187,7 +187,7 @@ class PrintableSpec extends AnyFlatSpec with Matchers {
       myBun.bar := 0.U
       printf(p"$myBun")
     }
-    val firrtl = (new ChiselStage).emitChirrtl(new MyModule)
+    val firrtl = ChiselStage.emitChirrtl(new MyModule)
     getPrintfs(firrtl) match {
       case Seq(Printf("AnonymousBundle(foo -> %d, bar -> %d)",
                Seq("myBun.foo", "myBun.bar"))) =>
diff --git a/src/test/scala/chiselTests/ResetSpec.scala b/src/test/scala/chiselTests/ResetSpec.scala
index 9d67637d..84d3985b 100644
--- a/src/test/scala/chiselTests/ResetSpec.scala
+++ b/src/test/scala/chiselTests/ResetSpec.scala
@@ -73,14 +73,14 @@ class ResetSpec extends ChiselFlatSpec with Utils {
   behavior of "Users"
 
   they should "be able to force implicit reset to be synchronous" in {
-    val fir = (new ChiselStage).emitChirrtl(new MultiIOModule with RequireSyncReset {
+    val fir = ChiselStage.emitChirrtl(new MultiIOModule with RequireSyncReset {
       reset shouldBe a [Bool]
     })
     fir should include ("input reset : UInt<1>")
   }
 
   they should "be able to force implicit reset to be asynchronous" in {
-    val fir = (new ChiselStage).emitChirrtl(new MultiIOModule with RequireAsyncReset {
+    val fir = ChiselStage.emitChirrtl(new MultiIOModule with RequireAsyncReset {
       reset shouldBe an [AsyncReset]
     })
     fir should include ("input reset : AsyncReset")
diff --git a/src/test/scala/chiselTests/experimental/verification/VerificationSpec.scala b/src/test/scala/chiselTests/experimental/verification/VerificationSpec.scala
index 521c16a3..53f89a1e 100644
--- a/src/test/scala/chiselTests/experimental/verification/VerificationSpec.scala
+++ b/src/test/scala/chiselTests/experimental/verification/VerificationSpec.scala
@@ -28,8 +28,7 @@ class VerificationSpec extends ChiselPropSpec {
   }
 
   property("basic equality check should work") {
-    val stage = new ChiselStage
-    val fir = stage.emitFirrtl(new VerificationModule)
+    val fir = ChiselStage.emitFirrtl(new VerificationModule)
     val lines = fir.split("\n").map(_.trim)
     assertContains(lines, "cover(clock, _T, UInt<1>(\"h1\"), \"\") @[VerificationSpec.scala 16:15]")
     assertContains(lines, "assume(clock, _T_2, UInt<1>(\"h1\"), \"\") @[VerificationSpec.scala 18:18]")
diff --git a/src/test/scala/chiselTests/stage/ChiselStageSpec.scala b/src/test/scala/chiselTests/stage/ChiselStageSpec.scala
index 21beb48f..9a866edb 100644
--- a/src/test/scala/chiselTests/stage/ChiselStageSpec.scala
+++ b/src/test/scala/chiselTests/stage/ChiselStageSpec.scala
@@ -5,6 +5,8 @@ package chiselTests.stage
 import chisel3._
 import chisel3.stage.ChiselStage
 
+import chiselTests.Utils
+
 import org.scalatest.flatspec.AnyFlatSpec
 import org.scalatest.matchers.should.Matchers
 
@@ -21,7 +23,7 @@ object ChiselStageSpec {
 
 }
 
-class ChiselStageSpec extends AnyFlatSpec with Matchers {
+class ChiselStageSpec extends AnyFlatSpec with Matchers with Utils {
 
   import ChiselStageSpec._
 
@@ -31,32 +33,81 @@ class ChiselStageSpec extends AnyFlatSpec with Matchers {
 
   behavior of "ChiselStage.emitChirrtl"
 
-  it should "return a CHIRRTL string" in new ChiselStageFixture {
-    stage.emitChirrtl(new Foo) should include ("infer mport")
+  it should "return a CHIRRTL string" in {
+    ChiselStage.emitChirrtl(new Foo) should include ("infer mport")
   }
 
   behavior of "ChiselStage.emitFirrtl"
 
-  it should "return a High FIRRTL string" in new ChiselStageFixture {
-    stage.emitFirrtl(new Foo) should include ("mem bar")
+  it should "return a High FIRRTL string" in {
+    ChiselStage.emitFirrtl(new Foo) should include ("mem bar")
   }
 
   behavior of "ChiselStage.emitVerilog"
 
-  it should "return a Verilog string" in new ChiselStageFixture {
-    stage.emitVerilog(new Foo) should include ("endmodule")
+  it should "return a Verilog string" in {
+    ChiselStage.emitVerilog(new Foo) should include ("endmodule")
   }
 
   behavior of "ChiselStage$.elaborate"
 
   it should "generate a Chisel circuit from a Chisel module" in {
-    ChiselStage.elaborate(new Foo)
+    info("no files were written")
+    catchWrites { ChiselStage.elaborate(new Foo) } shouldBe a[Right[_, _]]
   }
 
   behavior of "ChiselStage$.convert"
 
   it should "generate a CHIRRTL circuit from a Chisel module" in {
-    ChiselStage.convert(new Foo)
+    info("no files were written")
+    catchWrites { ChiselStage.convert(new Foo) } shouldBe a[Right[_, _]]
+  }
+
+  behavior of "ChiselStage$.emitChirrtl"
+
+  it should "generate a CHIRRTL string from a Chisel module" in {
+    val wrapped = catchWrites { ChiselStage.emitChirrtl(new Foo) }
+
+    info("no files were written")
+    wrapped shouldBe a[Right[_, _]]
+
+    info("returned string looks like FIRRTL")
+    wrapped.right.get should include ("circuit")
+  }
+
+  behavior of "ChiselStage$.emitFirrtl"
+
+  it should "generate a FIRRTL string from a Chisel module" in {
+    val wrapped = catchWrites { ChiselStage.emitFirrtl(new Foo) }
+
+    info("no files were written")
+    wrapped shouldBe a[Right[_, _]]
+
+    info("returned string looks like FIRRTL")
+    wrapped.right.get should include ("circuit")
+  }
+
+  behavior of "ChiselStage$.emitVerilog"
+
+  it should "generate a Verilog string from a Chisel module" in {
+    val wrapped = catchWrites { ChiselStage.emitVerilog(new Foo) }
+
+    info("no files were written")
+    wrapped shouldBe a[Right[_, _]]
+
+    info("returned string looks like Verilog")
+    wrapped.right.get should include ("endmodule")
+  }
+
+  behavior of "ChiselStage$.emitSystemVerilog"
+
+  it should "generate a SystemvVerilog string from a Chisel module" in {
+    val wrapped = catchWrites { ChiselStage.emitSystemVerilog(new Foo) }
+    info("no files were written")
+    wrapped shouldBe a[Right[_, _]]
+
+    info("returned string looks like Verilog")
+    wrapped.right.get should include ("endmodule")
   }
 
   behavior of "ChiselStage phase ordering"