Add Definition and Instance API (#2045)

This introduces a new experimental API for module instantiation that disentagles
elaborating the definition (or implementation) from instantiation of
a given module. This solves Chisel's longstanding reliance on
"Deduplication" for generating Verilog with multiple instances of the
same module.

The new API resides in package chisel3.experimental.hierarchy. Please
see the hierarchy ScalaDoc, documentation, and tests for examples of
use.

Co-authored-by: Jack Koenig <koenig@sifive.com>
Co-authored-by: Megan Wachs <megan@sifive.com>
Co-authored-by: Schuyler Eldridge <schuyler.eldridge@sifive.com>

1 files changed, 186 insertions, 0 deletions

diff --git a/src/test/scala/chiselTests/experimental/hierarchy/Examples.scala b/src/test/scala/chiselTests/experimental/hierarchy/Examples.scala
new file mode 100644
index 00000000..23b8c9c0
--- /dev/null
+++ b/src/test/scala/chiselTests/experimental/hierarchy/Examples.scala
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chiselTests.experimental.hierarchy
+
+import chisel3._
+import chisel3.util.Valid
+import chisel3.experimental.hierarchy._
+import chisel3.experimental.BaseModule
+
+object Examples {
+  import Annotations._
+  @instantiable
+  class AddOne extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val innerWire = Wire(UInt(32.W))
+    innerWire := in + 1.U
+    out := innerWire
+  }
+  @instantiable
+  class AddOneWithAnnotation extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val innerWire = Wire(UInt(32.W))
+    mark(innerWire, "innerWire")
+    innerWire := in + 1.U
+    out := innerWire
+  }
+  @instantiable
+  class AddOneWithAbsoluteAnnotation extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val innerWire = Wire(UInt(32.W))
+    amark(innerWire, "innerWire")
+    innerWire := in + 1.U
+    out := innerWire
+  }
+  @instantiable
+  class AddTwo extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val definition = Definition(new AddOne)
+    @public val i0: Instance[AddOne] = Instance(definition)
+    @public val i1: Instance[AddOne] = Instance(definition)
+    i0.in := in
+    i1.in := i0.out
+    out := i1.out
+  }
+  @instantiable
+  class AddTwoMixedModules extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    val definition = Definition(new AddOne)
+    @public val i0: Instance[AddOne] = Instance(definition)
+    @public val i1 = Module(new AddOne)
+    i0.in := in
+    i1.in := i0.out
+    out := i1.out
+  }
+  @instantiable
+  class AggregatePortModule extends Module {
+    @public val io = IO(new Bundle {
+      val in = Input(UInt(32.W))
+      val out = Output(UInt(32.W))
+    })
+    io.out := io.in
+  }
+  @instantiable
+  class WireContainer {
+    @public val innerWire = Wire(UInt(32.W))
+  }
+  @instantiable
+  class AddOneWithInstantiableWire extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val wireContainer = new WireContainer()
+    wireContainer.innerWire := in + 1.U
+    out := wireContainer.innerWire
+  }
+  @instantiable
+  class AddOneContainer {
+    @public val i0 = Module(new AddOne)
+  }
+  @instantiable
+  class AddOneWithInstantiableModule extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val moduleContainer = new AddOneContainer()
+    moduleContainer.i0.in := in
+    out := moduleContainer.i0.out
+  }
+  @instantiable
+  class AddOneInstanceContainer {
+    val definition = Definition(new AddOne)
+    @public val i0 = Instance(definition)
+  }
+  @instantiable
+  class AddOneWithInstantiableInstance extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val instanceContainer = new AddOneInstanceContainer()
+    instanceContainer.i0.in := in
+    out := instanceContainer.i0.out
+  }
+  @instantiable
+  class AddOneContainerContainer {
+    @public val container = new AddOneContainer
+  }
+  @instantiable
+  class AddOneWithInstantiableInstantiable extends Module {
+    @public val in  = IO(Input(UInt(32.W)))
+    @public val out = IO(Output(UInt(32.W)))
+    @public val containerContainer = new AddOneContainerContainer()
+    containerContainer.container.i0.in := in
+    out := containerContainer.container.i0.out
+  }
+  @instantiable
+  class Viewer(val y: AddTwo, markPlease: Boolean) {
+    @public val x = y
+    if(markPlease) mark(x.i0.innerWire, "first")
+  }
+  @instantiable
+  class ViewerParent(val x: AddTwo, markHere: Boolean, markThere: Boolean) extends Module {
+    @public val viewer = new Viewer(x, markThere)
+    if(markHere) mark(viewer.x.i0.innerWire, "second")
+  }
+  @instantiable
+  class MultiVal() extends Module {
+    @public val (x, y) = (Wire(UInt(3.W)), Wire(UInt(3.W)))
+  }
+  @instantiable
+  class LazyVal() extends Module {
+    @public val x = Wire(UInt(3.W))
+    @public lazy val y = "Hi"
+  }
+  case class Parameters(string: String, int: Int) extends IsLookupable
+  @instantiable
+  class UsesParameters(p: Parameters) extends Module {
+    @public val y = p
+    @public val x = Wire(UInt(3.W))
+  }
+  @instantiable
+  class HasList() extends Module {
+    @public val y = List(1, 2, 3)
+    @public val x = List.fill(3)(Wire(UInt(3.W)))
+  }
+  @instantiable
+  class HasSeq() extends Module {
+    @public val y = Seq(1, 2, 3)
+    @public val x = Seq.fill(3)(Wire(UInt(3.W)))
+  }
+  @instantiable
+  class HasOption() extends Module {
+    @public val x: Option[UInt] = Some(Wire(UInt(3.W)))
+  }
+  @instantiable
+  class HasVec() extends Module {
+    @public val x = VecInit(1.U, 2.U, 3.U)
+  }
+  @instantiable
+  class HasIndexedVec() extends Module {
+    val x = VecInit(1.U, 2.U, 3.U)
+    @public val y = x(1)
+  }
+  @instantiable
+  class HasSubFieldAccess extends Module {
+    val in = IO(Input(Valid(UInt(8.W))))
+    @public val valid = in.valid
+    @public val bits = in.bits
+  }
+  @instantiable
+  class HasPublicConstructorArgs(@public val int: Int) extends Module {
+    @public val x = Wire(UInt(3.W))
+  }
+  @instantiable
+  class InstantiatesHasVec() extends Module {
+    @public val i0 = Instance(Definition(new HasVec()))
+    @public val i1 = Module(new HasVec())
+  }
+  @instantiable
+  class HasUninferredReset() extends Module {
+    @public val in = IO(Input(UInt(3.W)))
+    @public val out = IO(Output(UInt(3.W)))
+    out := RegNext(in)
+  }
+}