Merge pull request #4817 from chipsalliance/mergify/bp/6.x/pr-4816

Deprecate ChiselStage.convert, replace with elaborate (backport #4816)

Author: chiselbot

core/src/main/scala/chisel3/experimental/hierarchy/core/Definition.scala

@@ -69,6 +69,9 @@ final case class Definition[+A] private[chisel3] (private[chisel3] val underlyin
 object Definition extends SourceInfoDoc {
   implicit class DefinitionBaseModuleExtensions[T <: BaseModule](d: Definition[T]) {
 
+    /** The name of the Module definition */
+    def name: String = d.proto.name
+
     /** If this is an instance of a Module, returns the toTarget of this instance
       * @return target of this instance
       */

docs/src/cookbooks/hierarchy.md

@@ -164,7 +164,7 @@ class Top extends Module {
 ```scala mdoc:passthrough
 println("```")
 // Run elaboration so that the println above shows up
-circt.stage.ChiselStage.convert(new Top)
+circt.stage.ChiselStage.elaborate(new Top)
 println("```")
 ```
 

docs/src/explanations/chisel-type-vs-scala-type.md

@@ -60,9 +60,7 @@ class MyModule(gen: () => MyBundle) extends Module {
 
 ```scala mdoc:invisible
 // Just here to compile check the above
-def elaborate(module: => chisel3.RawModule) = {
-  circt.stage.ChiselStage.convert(module)
-}
+import circt.stage.ChiselStage.elaborate
 elaborate(new MyModule(() => new MyBundle(3)))
 ```
 

integration-tests/src/test/scala/chiselTest/util/SparseVecSpec.scala

@@ -341,7 +341,7 @@ class SparseVecSpec extends ChiselFlatSpec with Utils {
 
   "SparseVec error behavior" should "disallow indices large than the size" in {
     val exception = intercept[IllegalArgumentException] {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         new SparseVec(1, UInt(1.W), Seq(0, 1))
       })
     }
@@ -350,7 +350,7 @@ class SparseVecSpec extends ChiselFlatSpec with Utils {
 
   it should "disallow non-unique indices" in {
     val exception = intercept[ChiselException] {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         new SparseVec(2, UInt(1.W), Seq(0, 0))
       })
     }
@@ -359,7 +359,7 @@ class SparseVecSpec extends ChiselFlatSpec with Utils {
 
   it should "disallow a SparseVec write" in {
     val exception = intercept[ChiselException] {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val vec = Wire(new SparseVec(2, UInt(1.W), Seq(0, 1)))
         vec(0.U(1.W)) := 1.U
       })

src/main/scala/circt/stage/ChiselStage.scala

@@ -67,6 +67,27 @@ object ChiselStage {
     )
   )
 
+  /** Run elaboration and return the `ElaboratedCircuit`
+    *
+    * @param gen  a call-by-name Chisel module
+    * @param args additional command line arguments to pass to Chisel
+    * @return     the `ElaboratedCircuit`
+    */
+  def elaborate(
+    gen:  => RawModule,
+    args: Array[String] = Array.empty
+  ): ElaboratedCircuit = {
+    val annos = Seq(
+      ChiselGeneratorAnnotation(() => gen),
+      CIRCTTargetAnnotation(CIRCTTarget.CHIRRTL)
+    ) ++ (new Shell("circt")).parse(args)
+
+    phase
+      .transform(annos)
+      .collectFirst { case a: ChiselCircuitAnnotation => a.elaboratedCircuit }
+      .get
+  }
+
   /** Elaborate a Chisel circuit into a CHIRRTL string */
   def emitCHIRRTL(
     gen:  => RawModule,
@@ -110,6 +131,7 @@ object ChiselStage {
     *
     * @param gen a call-by-name Chisel module
     */
+  @deprecated("Use elaborate or one of the emit* methods instead", "Chisel 6.8.0")
   def convert(
     gen:  => RawModule,
     args: Array[String] = Array.empty

src/test/scala/chisel3/experimental/dataview/ReifySpec.scala

@@ -80,7 +80,7 @@ class ReifySpec extends AnyFunSpec {
   describe("dataview.reify") {
 
     it("should reify single targets and identity for all non-view Elements") {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val wires = (new AllElementsBundle).getElements.map(Wire(_))
 
         // .getElements returns Data so we have to match that these are Elements.
@@ -94,7 +94,7 @@ class ReifySpec extends AnyFunSpec {
     }
 
     it("should reify single targets and identity for all non-view Elements even as children of an Aggregate") {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val bundle = IO(new AllElementsBundle)
 
         // .getElements returns Data so we have to match that these are Elements.
@@ -108,7 +108,7 @@ class ReifySpec extends AnyFunSpec {
     }
 
     it("should reify single targets and identity for all Elements in an Aggregate identity-view") {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val bundle = IO(new AllElementsBundle)
         val view = bundle.viewAs[AllElementsBundle]
 
@@ -126,7 +126,7 @@ class ReifySpec extends AnyFunSpec {
     }
 
     it("should reify single targets and identity for all Elements in an Aggregate non-identity and non-1-1 view") {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val wires = (new AllElementsBundle).getElements.map(Wire(_))
         val view = wires.viewAs[AllElementsBundle]
 
@@ -144,7 +144,7 @@ class ReifySpec extends AnyFunSpec {
     }
 
     it("should distinguish identity views from single-target views (even if the single target is the same type!") {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val vec = IO(Vec(2, UInt(8.W)))
         val view = vec.viewAs[ReversedVec[UInt]]
 
@@ -164,7 +164,7 @@ class ReifySpec extends AnyFunSpec {
     }
 
     it("should correctly reify single-target views despite complex hierarchy") {
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val in0 = IO(Input(UInt(8.W)))
         val in1 = IO(Input(new TargetBundle))
         val view = (in0, in1).viewAs[ViewBundle]
@@ -191,7 +191,7 @@ class ReifySpec extends AnyFunSpec {
       class MyModule extends RawModule {
         @public val ios = (new AllElementsBundle).getElements.map(IO(_))
       }
-      ChiselStage.convert(new RawModule {
+      ChiselStage.elaborate(new RawModule {
 
         val child = Instantiate(new MyModule)
 
@@ -210,7 +210,7 @@ class ReifySpec extends AnyFunSpec {
       class MyModule extends RawModule {
         @public val bundle = IO(new AllElementsBundle)
       }
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val child = Instantiate(new MyModule)
 
         // .getElements returns Data so we have to match that these are Elements.
@@ -229,7 +229,7 @@ class ReifySpec extends AnyFunSpec {
         @public val bundle = IO(new AllElementsBundle)
         @public val view = bundle.viewAs[AllElementsBundle]
       }
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val child = Instantiate(new MyModule)
 
         _reifyIdentityView(child.view) should be(Some(child.bundle))
@@ -251,7 +251,7 @@ class ReifySpec extends AnyFunSpec {
         @public val wires = (new AllElementsBundle).getElements.map(Wire(_))
         @public val view = wires.viewAs[AllElementsBundle]
       }
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val child = Instantiate(new MyModule)
 
         _reifyIdentityView(child.view) should be(None)
@@ -273,7 +273,7 @@ class ReifySpec extends AnyFunSpec {
         @public val vec = IO(Vec(2, UInt(8.W)))
         @public val view = vec.viewAs[ReversedVec[UInt]]
       }
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val child = Instantiate(new MyModule)
         val vec = child.vec
         val view = child.view
@@ -300,7 +300,7 @@ class ReifySpec extends AnyFunSpec {
         @public val in1 = IO(Input(new TargetBundle))
         @public val view = (in0, in1).viewAs[ViewBundle]
       }
-      ChiselStage.convert(new Module {
+      ChiselStage.elaborate(new Module {
         val child = Instantiate(new MyModule)
         val in0 = child.in0
         val in1 = child.in1

src/test/scala/chiselTests/CloneModuleSpec.scala

@@ -4,6 +4,7 @@ package chiselTests
 
 import chisel3._
 import circt.stage.ChiselStage
+import chisel3.aop.Select
 import chisel3.util.{log2Ceil, Decoupled, DeqIO, EnqIO, Queue, QueueIO}
 import chisel3.experimental.CloneModuleAsRecord
 import chisel3.testers.BasicTester
@@ -93,8 +94,9 @@ class CloneModuleSpec extends ChiselPropSpec {
   }
 
   property("QueueClone's cloned queues should share the same module") {
-    val c = ChiselStage.convert(new QueueClone)
-    assert(c.modules.length == 2)
+    val c = ChiselStage.elaborate(new QueueClone)
+    val modules = Select.allDefinitionsOf[RawModule](c.topDefinition)
+    assert(modules.length == 2)
   }
 
   property("Clone of Module should simulate correctly") {
@@ -104,14 +106,15 @@ class CloneModuleSpec extends ChiselPropSpec {
   }
 
   property("Clones of Modules should share the same module") {
-    val c = ChiselStage.convert(new QueueClone(multiIO = true))
-    assert(c.modules.length == 3)
+    val c = ChiselStage.elaborate(new QueueClone(multiIO = true))
+    val modules = Select.allDefinitionsOf[RawModule](c.topDefinition)
+    assert(modules.length == 3)
   }
 
   property("Cloned Modules should annotate correctly") {
     // Hackily get the actually Module object out
     var mod: CloneModuleAsRecordAnnotate = null
-    val res = ChiselStage.convert {
+    val res = ChiselStage.elaborate {
       mod = new CloneModuleAsRecordAnnotate
       mod
     }

src/test/scala/chiselTests/Direction.scala

@@ -8,6 +8,7 @@ import chisel3._
 import chisel3.experimental.{ExtModule, OpaqueType}
 
 import circt.stage.ChiselStage
+import scala.annotation.nowarn
 import scala.collection.immutable.SeqMap
 
 class DirectionedBundle extends Bundle {
@@ -44,6 +45,7 @@ class TopDirectionOutput extends Module {
   io.out := 117.U
 }
 
+@nowarn("msg=method convert in object ChiselStage is deprecated")
 class DirectionSpec extends ChiselPropSpec with Matchers with Utils {
 
   //TODO: In Chisel3 these are actually FIRRTL errors. Remove from tests?

src/test/scala/chiselTests/ReadOnlySpec.scala

@@ -83,7 +83,7 @@ class ReadOnlySpec extends ChiselFlatSpec with Utils {
 
   def check(m: => RawModule)(implicit pos: Position): Unit = {
     val e = the[ChiselException] thrownBy {
-      ChiselStage.convert(m, Array("--throw-on-first-error"))
+      ChiselStage.elaborate(m, Array("--throw-on-first-error"))
     }
     e.getMessage should include("Cannot connect to read-only value")
   }
@@ -263,7 +263,7 @@ class ReadOnlySpec extends ChiselFlatSpec with Utils {
         op(out, z)
       })
       // But note that it's fine if x (not flipped) is readOnly.
-      ChiselStage.convert(new RawModule {
+      ChiselStage.elaborate(new RawModule {
         val x, y = Wire(UInt(8.W))
         val z = (x.readOnly, y).viewAs[BidirectionalBundle]
         val out = IO(new BidirectionalBundle)

src/test/scala/chiselTests/experimental/hierarchy/InstantiateSpec.scala

@@ -10,6 +10,8 @@ import chisel3.experimental.hierarchy._
 import circt.stage.ChiselStage.convert
 import chisel3.experimental.{ExtModule, IntrinsicModule}
 
+import scala.annotation.nowarn
+
 // Note, the instantiable classes must not be inner classes because the materialized WeakTypeTags
 // will be different and they will not give the same hashCode when looking up the Definition in the
 // cache
@@ -184,6 +186,7 @@ class ParameterizedReset(hasAsyncNotSyncReset: Boolean) extends Module {
   override def resetType = if (hasAsyncNotSyncReset) Module.ResetType.Asynchronous else Module.ResetType.Synchronous
 }
 
+@nowarn("msg=method convert in object ChiselStage is deprecated")
 class InstantiateSpec extends ChiselFunSpec with Utils {
 
   import InstantiateSpec._