[core] Add Placeholder API

Add an advanced Chisel API which allows for generation of hardware at a
remembered point in the design.  This API allows a user to create an
object of `class Placeholder` which, if used later via its `append`
method, will create hardware at the location where the `Placeholder`
object was created.

This is intended to be used to support certain generator patterns where
hardware must be created _before_ some other hardware, but only after the
other hardware has been built.  E.g., this can be used to support creating
and defining layer-colored probes after constructing a layer block.

Signed-off-by: Schuyler Eldridge <[email protected]>

Author: seldridge

core/src/main/scala/chisel3/Placeholder.scala

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chisel3.experimental.SourceInfo
+import chisel3.internal.Builder
+import chisel3.internal.firrtl.ir
+
+/** A [[Placeholder]] is an _advanced_ API for Chisel generators to generate
+  * additional hardware at a different point in the design.
+  *
+  * For example, this can be used to add a wire _before_ another wire:
+  * {{{
+  * val placeholder = new Placeholder()
+  * val a = Wire(Bool())
+  * val b = placeholder.append {
+  *   Wire(Bool())
+  * }
+  * }}}
+  *
+  * This will generate the following FIRRTL where `b` is declared _before_ `a`:
+  * {{{
+  * wire b : UInt<1>
+  * wire a : UInt<1>
+  * }}}
+  */
+private[chisel3] class Placeholder()(implicit sourceInfo: SourceInfo) {
+
+  private val state = Builder.State.save
+
+  private val placeholder = Builder.pushCommand(new ir.Placeholder(sourceInfo = sourceInfo))
+
+  /** Generate the hardware of the `thunk` and append the result at the point
+    * where this [[Placeholder]] was created.  The return value will be what the
+    * `thunk` returns which enables getting a reference to the generated
+    * hardware.
+    *
+    * @param thunk the hardware to generate and append to the [[Placeholder]]
+    * @return the return value of the `thunk`
+    */
+  def append[A](thunk: => A): A = Builder.State.guard(state) {
+    Builder.currentBlock.get.appendToPlaceholder(placeholder)(thunk)
+  }
+
+}

core/src/main/scala/chisel3/internal/firrtl/Converter.scala

@@ -2,7 +2,7 @@
 
 package chisel3.internal.firrtl
 
-import chisel3._
+import chisel3.{Placeholder => _, _}
 import chisel3.experimental._
 import chisel3.experimental.{NoSourceInfo, SourceInfo, SourceLine, UnlocatableSourceInfo}
 import chisel3.properties.Property
@@ -266,6 +266,8 @@ private[chisel3] object Converter {
       )
     case LayerBlock(info, layer, region) =>
       fir.LayerBlock(convert(info), layer, convert(region, ctx, typeAliases))
+    case Placeholder(info, block) =>
+      convert(block, ctx, typeAliases)
   }
 
   /** Convert Chisel IR Commands into FIRRTL Statements

core/src/main/scala/chisel3/internal/firrtl/IR.scala

@@ -337,6 +337,39 @@ private[chisel3] object ir {
   ) extends Definition
   case class DefObject(sourceInfo: SourceInfo, id: HasId, className: String) extends Definition
 
+  class Placeholder(val sourceInfo: SourceInfo) extends Command {
+    private var commandBuilder: mutable.Builder[Command, ArraySeq[Command]] = null
+
+    private var commands: Seq[Command] = null
+
+    private var closed: Boolean = false
+
+    private def close(): Unit = {
+      if (commandBuilder == null)
+        commands = Seq.empty
+      else
+        commands = commandBuilder.result()
+      closed = true
+    }
+
+    def getBuffer: mutable.Builder[Command, ArraySeq[Command]] = {
+      require(!closed, "cannot add more commands to a closed Placeholder")
+      if (commandBuilder == null)
+        commandBuilder = ArraySeq.newBuilder[Command]
+      commandBuilder
+    }
+
+  }
+
+  object Placeholder {
+    def unapply(placeholder: Placeholder): Option[(SourceInfo, Seq[Command])] = {
+      placeholder.close()
+      Some(
+        (placeholder.sourceInfo, placeholder.commands)
+      )
+    }
+  }
+
   class Block(val sourceInfo: SourceInfo) {
     // While building block, commands go into _commandsBuilder.
     private var _commandsBuilder = ArraySeq.newBuilder[Command]
@@ -355,6 +388,14 @@ private[chisel3] object ir {
       _commandsBuilder += c
     }
 
+    def appendToPlaceholder[A](placeholder: Placeholder)(thunk: => A): A = {
+      val oldPoint = _commandsBuilder
+      _commandsBuilder = placeholder.getBuffer
+      val result = thunk
+      _commandsBuilder = oldPoint
+      result
+    }
+
     def close() = {
       if (_commands == null) {
         _commands = _commandsBuilder.result()

src/main/scala-2/chisel3/aop/Select.scala

@@ -44,6 +44,8 @@ object Select {
       case cmd @ LayerBlock(_, _, region) =>
         val head = f.lift(cmd).toSeq
         head ++ collect(region)(f)
+      case cmd @ Placeholder(_, block) =>
+        collect(block)(f)
       case cmd if f.isDefinedAt(cmd) => Some(f(cmd))
       case _                         => None
     }

src/test/scala/chisel3/PlaceholderSpec.scala

@@ -0,0 +1,140 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chiselTests.{ChiselFlatSpec, FileCheck}
+import circt.stage.ChiselStage
+
+class PlaceholderSpec extends ChiselFlatSpec with FileCheck {
+
+  "Placeholders" should "allow insertion of commands" in {
+
+    class Foo extends RawModule {
+
+      val placeholder = new Placeholder()
+
+      val a = Wire(UInt(1.W))
+
+      val b = placeholder.append {
+        Wire(UInt(2.W))
+      }
+
+    }
+
+    generateFirrtlAndFileCheck(new Foo) {
+      s"""|CHECK:      wire b : UInt<2>
+          |CHECK-NEXT: wire a : UInt<1>
+          |""".stripMargin
+    }
+
+  }
+
+  they should "be capable of being nested" in {
+
+    class Foo extends RawModule {
+
+      val placeholder_1 = new Placeholder()
+      val placeholder_2 = placeholder_1.append(new Placeholder())
+
+      val a = Wire(UInt(1.W))
+
+      val b = placeholder_1.append {
+        Wire(UInt(2.W))
+      }
+
+      val c = placeholder_2.append {
+        Wire(UInt(3.W))
+      }
+
+      val d = placeholder_1.append {
+        Wire(UInt(4.W))
+      }
+
+    }
+
+    generateFirrtlAndFileCheck(new Foo) {
+      s"""|CHECK:      wire c : UInt<3>
+          |CHECK-NEXT: wire b : UInt<2>
+          |CHECK-NEXT: wire d : UInt<4>
+          |CHECK-NEXT: wire a : UInt<1>
+          |""".stripMargin
+    }
+
+  }
+
+  they should "emit no statements if empty" in {
+
+    class Foo extends RawModule {
+      val a = new Placeholder()
+    }
+
+    generateFirrtlAndFileCheck(new Foo) {
+      """|CHECK: public module Foo :
+         |CHECK:   skip
+         |""".stripMargin
+    }
+  }
+
+  they should "allow constructing hardware in a parent" in {
+
+    class Bar(placeholder: Placeholder, a: Bool) extends RawModule {
+
+      placeholder.append {
+        val b = Wire(Bool())
+        b :<= a
+      }
+
+    }
+
+    class Foo extends RawModule {
+
+      val a = Wire(Bool())
+      val placeholder = new Placeholder
+
+      val bar = Module(new Bar(placeholder, a))
+
+    }
+
+    generateFirrtlAndFileCheck(new Foo) {
+      """|CHECK:      module Bar :
+         |CHECK-NOT:    {{wire|connect}}
+         |
+         |CHECK:      module Foo :
+         |CHECK:        wire a : UInt<1>
+         |CHECK-NEXT:   wire b : UInt<1>
+         |CHECK-NEXT:   connect b, a
+         |CHECK-NEXT:   inst bar of Bar
+         |""".stripMargin
+    }
+
+  }
+
+  // TODO: This test can be changed to pass in the future in support of advanced
+  // APIs like Providers or an improved BoringUtils.
+  they should "error if constructing hardware in a child" in {
+
+    class Bar extends RawModule {
+
+      val a = Wire(Bool())
+      val placeholder = new Placeholder()
+
+    }
+
+    class Foo extends RawModule {
+
+      val bar = Module(new Bar)
+
+      bar.placeholder.append {
+        val b = Wire(Bool())
+        b :<= bar.a
+      }
+
+    }
+
+    intercept[IllegalArgumentException] { ChiselStage.emitCHIRRTL(new Foo) }.getMessage() should include(
+      "Can't write to module after module close"
+    )
+
+  }
+
+}

src/test/scala/chisel3/SelectSpec.scala

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chisel3.aop.Select
+import chisel3.stage.{ChiselGeneratorAnnotation, DesignAnnotation}
+import chiselTests.ChiselFlatSpec
+
+class SelectSpec extends ChiselFlatSpec {
+
+  "Placeholders" should "be examined" in {
+    class Foo extends RawModule {
+      val placeholder = new Placeholder()
+      val a = Wire(Bool())
+      val b = placeholder.append {
+        Wire(Bool())
+      }
+    }
+    val design = ChiselGeneratorAnnotation(() => {
+      new Foo
+    }).elaborate(1).asInstanceOf[DesignAnnotation[Foo]].design
+    Select.wires(design).size should be(2)
+  }
+
+}