1 files changed, 198 insertions, 0 deletions
diff --git a/src/main/scala/chisel3/util/experimental/BoringUtils.scala b/src/main/scala/chisel3/util/experimental/BoringUtils.scala
new file mode 100644
index 00000000..066e924f
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/BoringUtils.scala
@@ -0,0 +1,198 @@
+// See LICENSE for license details.
+
+package chisel3.util.experimental
+
+import chisel3._
+import chisel3.experimental.{ChiselAnnotation, RunFirrtlTransform, annotate}
+import chisel3.internal.{InstanceId, NamedComponent}
+import firrtl.transforms.{DontTouchAnnotation, NoDedupAnnotation}
+import firrtl.passes.wiring.{WiringTransform, SourceAnnotation, SinkAnnotation}
+import firrtl.annotations.{ModuleName, ComponentName}
+
+import scala.concurrent.SyncVar
+import chisel3.internal.Namespace
+
+/** An exception related to BoringUtils
+  * @param message the exception message
+  */
+class BoringUtilsException(message: String) extends Exception(message)
+
+/** Utilities for generating synthesizeable cross module references that
+  * "bore" through the hieararchy. The underlying cross module connects
+  * are handled by FIRRTL's Wiring Transform
+  * ([[firrtl.passes.wiring.WiringTransform]]).
+  *
+  * Consider the following exmple where you want to connect a component in
+  * one module to a component in another. Module `Constant` has a wire
+  * tied to `42` and `Expect` will assert unless connected to `42`:
+  * {{{
+  * class Constant extends Module {
+  *   val io = IO(new Bundle{})
+  *   val x = Wire(UInt(6.W))
+  *   x := 42.U
+  * }
+  * class Expect extends Module {
+  *   val io = IO(new Bundle{})
+  *   val y = Wire(UInt(6.W))
+  *   y := 0.U
+  *   // This assertion will fail unless we bore!
+  *   chisel3.assert(y === 42.U, "y should be 42 in module Expect")
+  * }
+  * }}}
+  *
+  * We can then connect `x` to `y` using [[BoringUtils]] without
+  * modifiying the Chisel IO of `Constant`, `Expect`, or modules that may
+  * instantiate them. There are two approaches to do this:
+  *
+  * 1. Hierarchical boring using [[BoringUtils.bore]]
+  *
+  * 2. Non-hierarchical boring using [[BoringUtils.addSink]]/[[BoringUtils.addSource]]
+  *
+  * ===Hierarchical Boring===
+  *
+  * Hierarchcical boring involves connecting one sink instance to another
+  * source instance in a parent module. Below, module `Top` contains an
+  * instance of `Cosntant` and `Expect`. Using [[BoringUtils.bore]], we
+  * can connect `constant.x` to `expect.y`.
+  *
+  * {{{
+  * class Top extends Module {
+  *   val io = IO(new Bundle{})
+  *   val constant = Module(new Constant)
+  *   val expect = Module(new Expect)
+  *   BoringUtils.bore(constant.x, Seq(expect.y))
+  * }
+  * }}}
+  *
+  * ===Non-hierarchical Boring===
+  *
+  * Non-hierarchical boring involves connections from sources to sinks
+  * that cannot see each other. Here, `x` is described as a source and
+  * given a name, `uniqueId`, and `y` is described as a sink with the same
+  * name. This is equivalent to the hierarchical boring example above, but
+  * requires no modifications to `Top`.
+  *
+  * {{{
+  * class Constant extends Module {
+  *   val io = IO(new Bundle{})
+  *   val x = Wire(UInt(6.W))
+  *   x := 42.U
+  *   BoringUtils.addSource(x, "uniqueId")
+  * }
+  * class Expect extends Module {
+  *   val io = IO(new Bundle{})
+  *   val y = Wire(UInt(6.W))
+  *   y := 0.U
+  *   // This assertion will fail unless we bore!
+  *   chisel3.assert(y === 42.U, "y should be 42 in module Expect")
+  *   BoringUtils.addSink(y, "uniqueId")
+  * }
+  * class Top extends Module {
+  *   val io = IO(new Bundle{})
+  *   val constant = Module(new Constant)
+  *   val expect = Module(new Expect)
+  * }
+  * }}}
+  *
+  * ==Comments==
+  *
+  * Both hierarchical and non-hierarchical boring emit FIRRTL annotations
+  * that describe sources and sinks. These are matched by a `name` key
+  * that indicates they should be wired together. Hierarhical boring
+  * safely generates this name automatically. Non-hierarchical boring
+  * unsafely relies on user input to generate this name. Use of
+  * non-hierarchical naming may result in naming conflicts that the user
+  * must handle.
+  *
+  * The automatic generation of hierarchical names relies on a global,
+  * mutable namespace. This is currently persistent across circuit
+  * elaborations.
+  */
+object BoringUtils {
+  /* A global namespace for boring ids */
+  private val namespace: SyncVar[Namespace] = new SyncVar
+  namespace.put(Namespace.empty)
+
+  /* Get a new name (value) from the namespace */
+  private def newName(value: String): String = {
+    val ns = namespace.take()
+    val valuex = ns.name(value)
+    namespace.put(ns)
+    valuex
+  }
+
+  /* True if the requested name (value) exists in the namespace */
+  private def checkName(value: String): Boolean = namespace.get.contains(value)
+
+  /** Add a named source cross module reference
+    *
+    * @param component source circuit component
+    * @param name unique identifier for this source
+    * @param dedup enable dedupblication of modules (necessary if other
+    * instances exist in the design that are not sources)
+    * @param uniqueName if true, this will use a non-conflicting name from
+    * the global namespace
+    * @return the name used
+    * @note if a uniqueName is not specified, the returned name may differ
+    * from the user-provided name
+    */
+  def addSource(component: NamedComponent, name: String, dedup: Boolean = false, uniqueName: Boolean = false): String = {
+    val id = if (uniqueName) { newName(name) } else { name }
+    val maybeDedup =
+      if (dedup) { Seq(new ChiselAnnotation { def toFirrtl = NoDedupAnnotation(component.toNamed.module) }) }
+      else       { Seq[ChiselAnnotation]()                                                                  }
+    val annotations =
+      Seq(new ChiselAnnotation with RunFirrtlTransform {
+            def toFirrtl = SourceAnnotation(component.toNamed, id)
+            def transformClass = classOf[WiringTransform] },
+          new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(component.toNamed) } ) ++ maybeDedup
+
+    annotations.map(annotate(_))
+    id
+  }
+
+  /** Add a named sink cross module reference. Multiple sinks may map to
+    * the same source.
+    *
+    * @param component sink circuit component
+    * @param name unique identifier for this sink that must resolve to
+    * @param dedup enable deduplication on sink component (necessary if
+    * other instances exist in the design that are not sinks) a source
+    * identifier
+    * @param forceExists if true, require that the provided `name` paramater
+    * already exists in the global namespace
+    * @throws BoringUtilsException if name is expected to exist and it doesn't
+    */
+  def addSink(component: InstanceId, name: String, dedup: Boolean = false, forceExists: Boolean = false): Unit = {
+    if (forceExists && !checkName(name)) {
+      throw new BoringUtilsException(s"Sink ID '$name' not found in BoringUtils ID namespace") }
+    def moduleName = component.toNamed match {
+      case c: ModuleName => c
+      case c: ComponentName => c.module
+      case _ => throw new ChiselException("Can only add a Module or Component sink", null)
+    }
+    val maybeDedup =
+      if (dedup) { Seq(new ChiselAnnotation { def toFirrtl = NoDedupAnnotation(moduleName) }) }
+      else       { Seq[ChiselAnnotation]()                                                    }
+    val annotations =
+      Seq(new ChiselAnnotation with RunFirrtlTransform {
+            def toFirrtl = SinkAnnotation(component.toNamed, name)
+            def transformClass = classOf[WiringTransform] })
+    annotations.map(annotate(_))
+  }
+
+  /** Connect a source to one or more sinks
+    *
+    * @param source a source component
+    * @param sinks one or more sink components
+    * @return the name of the signal used to connect the source to the
+    * sinks
+    * @note the returned name will be based on the name of the source
+    * component
+    */
+  def bore(source: Data, sinks: Seq[Data]): String = {
+    lazy val genName = addSource(source, source.instanceName, true, true)
+    sinks.map(addSink(_, genName, true, true))
+    genName
+  }
+}