[core] Add knownLayers API to BlackBox, ExtModule (#4983)

Add an API to add `knownlayers` specifications to FIRRTL `extmodule`s.
This is a mechanism to declare that an external module was compiled with
support for specific layers.  This then allows a FIRRTL comopiler compiler
to know that it should automatically enable these layers if needed.

In order to make this work, a number of other changes had to be made.

First, move `atModuleBodyEnd` from `RawModule` to `BaseModule`.  This
allows capturing of the `Builder` state when the module closes.  Here,
this is used to capture the layers that are known to the `Builder` if a
module is later converted to a `Definition`.

Second, the default layers are now added to the `Builder` when it starts
as opposed to when it ends.  This allows for the default layers to be
captured by module or external modules and then emitted correctly if
needed (in the `Definition` or as FIRRTL `knownlayers`).

Third, when an `Instance` is created, any layers that it has need to be
added to the `Builder`.  This can arise if a `Definition` is imported via
an annotation and used to create a blackbox which will define additional
`knownlayers`.  If these layers are not added to the FIRRTL circuit, then
this is illegal FIRRTL.

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

Author: seldridge

core/src/main/scala/chisel3/BlackBox.scala

@@ -3,12 +3,15 @@
 package chisel3
 
 import chisel3.experimental.{BaseModule, Param}
+import chisel3.layer.Layer
 import chisel3.internal.BaseBlackBox
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl.ir._
 import chisel3.internal.throwException
 import chisel3.experimental.{SourceInfo, UnlocatableSourceInfo}
 
+import scala.collection.mutable
+
 package internal {
 
   private[chisel3] abstract class BaseBlackBox extends BaseModule {
@@ -17,6 +20,45 @@ package internal {
     // is not possible to properly name EmptyExtModule created from
     // Defintions. See unit test SeparateElaborationSpec #4.a
     private[chisel3] def _isImportedDefinition: Boolean = false
+
+    /** User-provided information about what layers are known to this `BlackBox`.
+      *
+      * E.g., if this was a [[BlackBox]] that points at Verilog built from
+      * _another_ Chisel elaboration, then this would be the layers that were
+      * defined in that circuit.
+      *
+      * @note This will cause the emitted FIRRTL to include the `knownlayer`
+      * keyword on the `extmodule` declaration.
+      */
+    protected def knownLayers: Seq[Layer]
+
+    // Internal tracking of _knownLayers.  This can be appended to with
+    // `addKnownLayer` which happens if you use `addLayer` inside an external
+    // module.
+    private val _knownLayers: mutable.LinkedHashSet[Layer] = mutable.LinkedHashSet.empty[Layer]
+
+    /** Add a layer to list of knownLayers for this module. */
+    private[chisel3] def addKnownLayer(layer: Layer) = {
+      var currentLayer: Layer = layer
+      while (currentLayer != Layer.Root && !_knownLayers.contains(currentLayer)) {
+        val layer = currentLayer
+        val parent = layer.parent
+
+        _knownLayers += layer
+        currentLayer = parent
+      }
+    }
+
+    /** Get the known layers.
+      *
+      * @throw IllegalArgumentException if the module is not closed
+      */
+    private[chisel3] def getKnownLayers: Seq[Layer] = {
+      require(isClosed, "Can't get layers before module is closed")
+      _knownLayers.toSeq
+    }
+
+    knownLayers.foreach(layer.addLayer)
   }
 }
 
@@ -70,9 +112,15 @@ package experimental {
     * }}}
     * @note The parameters API is experimental and may change
     */
-  abstract class ExtModule(val params: Map[String, Param] = Map.empty[String, Param]) extends BaseBlackBox {
+  abstract class ExtModule(
+    val params:                               Map[String, Param] = Map.empty[String, Param],
+    override protected final val knownLayers: Seq[Layer] = Seq.empty[Layer]
+  ) extends BaseBlackBox {
     private[chisel3] override def generateComponent(): Option[Component] = {
       require(!_closed, "Can't generate module more than once")
+
+      evaluateAtModuleBodyEnd()
+
       _closed = true
 
       // Ports are named in the same way as regular Modules
@@ -81,7 +129,7 @@ package experimental {
       val firrtlPorts = getModulePorts.map { case port =>
         Port(port, port.specifiedDirection, UnlocatableSourceInfo)
       }
-      val component = DefBlackBox(this, name, firrtlPorts, SpecifiedDirection.Unspecified, params)
+      val component = DefBlackBox(this, name, firrtlPorts, SpecifiedDirection.Unspecified, params, getKnownLayers)
       _component = Some(component)
       _component
     }
@@ -127,7 +175,10 @@ package experimental {
   * }}}
   * @note The parameters API is experimental and may change
   */
-abstract class BlackBox(val params: Map[String, Param] = Map.empty[String, Param]) extends BaseBlackBox {
+abstract class BlackBox(
+  val params:                               Map[String, Param] = Map.empty[String, Param],
+  override protected final val knownLayers: Seq[Layer] = Seq.empty[Layer]
+) extends BaseBlackBox {
 
   // Find a Record port named "io" for purposes of stripping the prefix
   private[chisel3] lazy val _io: Option[Record] =
@@ -147,6 +198,9 @@ abstract class BlackBox(val params: Map[String, Param] = Map.empty[String, Param
     require(portsSize == 1, "BlackBox must only have one IO, called `io`")
 
     require(!_closed, "Can't generate module more than once")
+
+    evaluateAtModuleBodyEnd()
+
     _closed = true
 
     val io = _io.get
@@ -166,7 +220,7 @@ abstract class BlackBox(val params: Map[String, Param] = Map.empty[String, Param
     val firrtlPorts = namedPorts.map { namedPort =>
       Port(namedPort._2, namedPort._2.specifiedDirection, UnlocatableSourceInfo)
     }
-    val component = DefBlackBox(this, name, firrtlPorts, io.specifiedDirection, params)
+    val component = DefBlackBox(this, name, firrtlPorts, io.specifiedDirection, params, getKnownLayers)
     _component = Some(component)
     _component
   }

core/src/main/scala/chisel3/Layer.scala

@@ -196,6 +196,12 @@ object layer {
       Builder.layers += layer
       currentLayer = parent
     }
+
+    // If this API is used in a BlackBox, then modify it's `knownLayers` member.
+    Builder.currentModule.map {
+      case module: internal.BaseBlackBox => module.addKnownLayer(layer)
+      case _ =>
+    }
   }
 
   /** A type class that describes how to post-process the return value from a layer block. */

core/src/main/scala/chisel3/Module.scala

@@ -10,6 +10,7 @@ import chisel3.internal._
 import chisel3.internal.binding._
 import chisel3.internal.Builder._
 import chisel3.internal.firrtl.ir._
+import chisel3.layer.Layer
 import chisel3.experimental.{requireIsChiselType, BaseModule, SourceInfo, Targetable, UnlocatableSourceInfo}
 import chisel3.properties.{Class, Property}
 import chisel3.reflect.DataMirror
@@ -953,6 +954,90 @@ package experimental {
     localModulePrefix.foreach { prefix =>
       Builder.pushModulePrefix(prefix, localModulePrefixUseSeparator)
     }
+
+    /** Hook to invoke hardware generators after the rest of the Module is constructed.
+    *
+    * This is a power-user API, and should not normally be needed.
+    *
+    * In rare cases, it is necessary to run hardware generators at a late stage, but still within the scope of the
+    * Module. In these situations, atModuleBodyEnd may be used to register such generators. For example:
+    *
+    *  {{{
+    *    class Example extends RawModule {
+    *      atModuleBodyEnd {
+    *        val extraPort0 = IO(Output(Bool()))
+    *        extraPort0 := 0.B
+    *      }
+    *    }
+    *  }}}
+    *
+    * Any generators registered with atModuleBodyEnd are the last code to execute when the Module is constructed. The
+    * execution order is:
+    *
+    *   - The constructors of any super classes or traits the Module extends
+    *   - The constructor of the Module itself
+    *   - The atModuleBodyEnd generators
+    *
+    * The atModuleBodyEnd generators execute in the lexical order they appear in the Module constructor.
+    *
+    * For example:
+    *
+    *  {{{
+    *    trait Parent {
+    *      // Executes first.
+    *      val foo = ...
+    *    }
+    *
+    *    class Example extends Parent {
+    *      // Executes second.
+    *      val bar = ...
+    *
+    *      atModuleBodyEnd {
+    *        // Executes fourth.
+    *        val qux = ...
+    *      }
+    *
+    *      atModuleBodyEnd {
+    *        // Executes fifth.
+    *        val quux = ...
+    *      }
+    *
+    *      // Executes third..
+    *      val baz = ...
+    *    }
+    *  }}}
+    *
+    * If atModuleBodyEnd is used in a Definition, any generated hardware will be included in the Definition. However, it
+    * is currently not possible to annotate any val within atModuleBodyEnd as @public.
+    */
+    protected def atModuleBodyEnd(gen: => Unit): Unit = {
+      _atModuleBodyEnd += { () => gen }
+    }
+    private val _atModuleBodyEnd = new ArrayBuffer[() => Unit]
+
+    protected[chisel3] def evaluateAtModuleBodyEnd(): Unit = _atModuleBodyEnd.foreach(_())
+
+    /** Record the layers in the circuit when this module was created. */
+    private var _layers: Seq[Layer] = null
+
+    atModuleBodyEnd {
+      _layers = Builder.layers.toSeq
+    }
+
+    /** Return the layers for this module after.
+      *
+      * This requires that the module is closed.
+      */
+    private[chisel3] def layers: Seq[Layer] = {
+      require(isClosed, "Can't get layers before module is closed")
+      if (_layers == null) {
+        throw new InternalErrorException(
+          s"a closed BaseModule '$desiredName' has null '_layers': this should be impossible"
+        )
+      }
+      _layers
+    }
+
   }
 }
 

core/src/main/scala/chisel3/RawModule.scala

@@ -22,66 +22,6 @@ import scala.collection.mutable.ArrayBuffer
   */
 abstract class RawModule extends BaseModule {
 
-  /** Hook to invoke hardware generators after the rest of the Module is constructed.
-    *
-    * This is a power-user API, and should not normally be needed.
-    *
-    * In rare cases, it is necessary to run hardware generators at a late stage, but still within the scope of the
-    * Module. In these situations, atModuleBodyEnd may be used to register such generators. For example:
-    *
-    *  {{{
-    *    class Example extends RawModule {
-    *      atModuleBodyEnd {
-    *        val extraPort0 = IO(Output(Bool()))
-    *        extraPort0 := 0.B
-    *      }
-    *    }
-    *  }}}
-    *
-    * Any generators registered with atModuleBodyEnd are the last code to execute when the Module is constructed. The
-    * execution order is:
-    *
-    *   - The constructors of any super classes or traits the Module extends
-    *   - The constructor of the Module itself
-    *   - The atModuleBodyEnd generators
-    *
-    * The atModuleBodyEnd generators execute in the lexical order they appear in the Module constructor.
-    *
-    * For example:
-    *
-    *  {{{
-    *    trait Parent {
-    *      // Executes first.
-    *      val foo = ...
-    *    }
-    *
-    *    class Example extends Parent {
-    *      // Executes second.
-    *      val bar = ...
-    *
-    *      atModuleBodyEnd {
-    *        // Executes fourth.
-    *        val qux = ...
-    *      }
-    *
-    *      atModuleBodyEnd {
-    *        // Executes fifth.
-    *        val quux = ...
-    *      }
-    *
-    *      // Executes third..
-    *      val baz = ...
-    *    }
-    *  }}}
-    *
-    * If atModuleBodyEnd is used in a Definition, any generated hardware will be included in the Definition. However, it
-    * is currently not possible to annotate any val within atModuleBodyEnd as @public.
-    */
-  protected def atModuleBodyEnd(gen: => Unit): Unit = {
-    _atModuleBodyEnd += { () => gen }
-  }
-  private val _atModuleBodyEnd = new ArrayBuffer[() => Unit]
-
   /** Hook to invoke hardware generators after a Module has been constructed and closed.
     *
     * This is useful for running hardware generators after a Module's constructor has run and its Definition is available, while still having access to arguments and definitions in the constructor. The Module itself can no longer be modified at this point.
@@ -223,9 +163,7 @@ abstract class RawModule extends BaseModule {
     }
 
     // Evaluate any atModuleBodyEnd generators.
-    _atModuleBodyEnd.foreach { gen =>
-      gen()
-    }
+    evaluateAtModuleBodyEnd()
 
     _closed = true
 

core/src/main/scala/chisel3/experimental/IntrinsicModule.scala

@@ -6,6 +6,7 @@ import chisel3.SpecifiedDirection
 import chisel3.experimental.{BaseModule, Param}
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl.ir._
+import chisel3.layer.Layer
 
 private[chisel3] abstract class BaseIntrinsicModule(intrinsicName: String) extends BaseModule {
   val intrinsic = intrinsicName
@@ -16,6 +17,7 @@ abstract class IntrinsicModule(intrinsicName: String, val params: Map[String, Pa
     extends BaseIntrinsicModule(intrinsicName) {
   private[chisel3] override def generateComponent(): Option[Component] = {
     require(!_closed, "Can't generate intmodule more than once")
+    evaluateAtModuleBodyEnd()
     _closed = true
 
     // Ports are named in the same way as regular Modules

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

@@ -5,6 +5,7 @@ package chisel3.experimental.hierarchy
 import chisel3.experimental.BaseModule
 import chisel3.internal.{HasId, PseudoModule}
 import chisel3.internal.firrtl.ir.{Component, Ref}
+import chisel3.layer.Layer
 
 /** Represents a Definition root module, when accessing something from a definition
   *
@@ -25,4 +26,5 @@ private[chisel3] class DefinitionClone[T <: BaseModule](val getProto: T) extends
   private[chisel3] def initializeInParent(): Unit = ()
   // Module name is the same as proto's module name
   override def desiredName: String = getProto.name
+  override def layers:      Seq[Layer] = getProto.layers
 }

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

@@ -5,6 +5,7 @@ package chisel3.experimental.hierarchy
 import chisel3.experimental.BaseModule
 import chisel3.internal.PseudoModule
 import chisel3.internal.firrtl.ir.{Component, Ref}
+import chisel3.layer.Layer
 
 /** Represents a module viewed from a different instance context.
   *
@@ -30,4 +31,5 @@ private[chisel3] final class InstanceClone[T <: BaseModule](val getProto: T, val
   override def instanceName = instName()
   // Module name is the same as proto's module name
   override def desiredName: String = getProto.name
+  override def layers:      Seq[Layer] = getProto.layers
 }

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

@@ -6,6 +6,7 @@ import chisel3.experimental.{BaseModule, SourceInfo}
 import chisel3.internal.{HasId, PseudoModule}
 import chisel3.internal.firrtl.ir.{Component, ModuleCloneIO, Ref}
 import chisel3.internal.{throwException, Namespace}
+import chisel3.layer.Layer
 import chisel3._
 
 // Private internal class to serve as a _parent for Data in cloned ports
@@ -26,6 +27,7 @@ private[chisel3] class ModuleClone[T <: BaseModule](val getProto: T)(implicit si
   // Don't generate a component, but point to the one for the cloned Module
   private[chisel3] def generateComponent(): Option[Component] = {
     require(!_closed, "Can't generate module more than once")
+    evaluateAtModuleBodyEnd()
     _closed = true
     _component = getProto._component
     None
@@ -77,4 +79,6 @@ private[chisel3] class ModuleClone[T <: BaseModule](val getProto: T)(implicit si
     _portsRecord.suggestName(seed)
     this
   }
+
+  override def layers: Seq[Layer] = getProto.layers
 }