[core] Add initial domain support

Add support for creating domains and domain types.  Add a built-in
ClockDomain type.

This is very basic support initially and many things will not work, namely
connections or compilation of these to anything meaningful.

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

Author: seldridge

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

@@ -126,8 +126,8 @@ package experimental {
       // Ports are named in the same way as regular Modules
       namePorts()
 
-      val firrtlPorts = getModulePorts.map { case port =>
-        Port(port, port.specifiedDirection, UnlocatableSourceInfo)
+      val firrtlPorts = getModulePortsAndLocators.map { case (port, _, associations) =>
+        Port(port, port.specifiedDirection, associations, UnlocatableSourceInfo)
       }
       val component = DefBlackBox(this, name, firrtlPorts, SpecifiedDirection.Unspecified, params, getKnownLayers)
       _component = Some(component)
@@ -217,9 +217,14 @@ abstract class BlackBox(
       port.setRef(ModuleIO(this, _namespace.name(name)), force = true)
     }
 
+    // Note: BlackBoxes, because they have a single `io` cannot currently
+    // support associations because associations require having multiple ports.
+    // If this restriction is lifted, then this code should be updated.
+    require(getAssociations.isEmpty, "BlackBoxes cannot support associations at this time, use an ExtModule")
     val firrtlPorts = namedPorts.map { namedPort =>
-      Port(namedPort._2, namedPort._2.specifiedDirection, UnlocatableSourceInfo)
+      Port(namedPort._2, namedPort._2.specifiedDirection, Seq.empty, UnlocatableSourceInfo)
     }
+
     val component = DefBlackBox(this, name, firrtlPorts, io.specifiedDirection, params, getKnownLayers)
     _component = Some(component)
     _component

core/src/main/scala/chisel3/IO.scala

@@ -1,5 +1,6 @@
 package chisel3
 
+import chisel3.domain
 import chisel3.internal.{throwException, Builder}
 import chisel3.experimental.{noPrefix, requireIsChiselType, SourceInfo}
 import chisel3.properties.{Class, Property}

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

@@ -576,16 +576,23 @@ package experimental {
 
     private val _ports = new ArrayBuffer[(Data, SourceInfo)]()
 
+    private val _associations = new HashMap[Data, LinkedHashSet[Data]]()
+
+    protected[chisel3] def getAssociations: scala.collection.immutable.Map[Data, LinkedHashSet[Data]] =
+      _associations.toMap
+
     // getPorts unfortunately already used for tester compatibility
     protected[chisel3] def getModulePorts: Seq[Data] = {
       require(_closed, "Can't get ports before module close")
       _ports.iterator.collect { case (d: Data, _) => d }.toSeq
     }
 
     // gets Ports along with there source locators
-    private[chisel3] def getModulePortsAndLocators: Seq[(Data, SourceInfo)] = {
+    private[chisel3] def getModulePortsAndLocators: Seq[(Data, SourceInfo, Seq[Data])] = {
       require(_closed, "Can't get ports before module close")
-      _ports.toSeq
+      _ports.toSeq.map { case (port, info) =>
+        (port, info, _associations.get(port).map(_.toSeq).getOrElse(Seq.empty[Data]))
+      }
     }
 
     /** Get IOs that are currently bound to this module.
@@ -608,6 +615,22 @@ package experimental {
 
     protected def portsSize: Int = _ports.size
 
+    /* Associate a port of this module with one or more domains. */
+    final def associate(port: Data, domain: Data, domains: Data*)(implicit si: SourceInfo): Unit = {
+      val allDomains = Seq(domain) ++ domains
+      if (!portsContains(port)) {
+        Builder.error(s"""Unable to associate port '$port' to domains '${allDomains.mkString(
+            ", "
+          )}' because the port does not exist in this module""")(si)
+        println(getModulePorts)
+        return
+      }
+      _associations.updateWith(port) {
+        case Some(acc) => Some(acc ++= allDomains)
+        case None      => Some(LinkedHashSet.empty[Data] ++= allDomains)
+      }
+    }
+
     /** Generates the FIRRTL Component (Module or Blackbox) of this Module.
       * Also closes the module so no more construction can happen inside.
       */
@@ -618,7 +641,7 @@ package experimental {
     private[chisel3] def initializeInParent(): Unit
 
     private[chisel3] def namePorts(): Unit = {
-      for ((port, source) <- getModulePortsAndLocators) {
+      for ((port, source, _) <- getModulePortsAndLocators) {
         port._computeName(None) match {
           case Some(name) =>
             if (_namespace.contains(name)) {
@@ -882,7 +905,7 @@ package experimental {
     private[chisel3] def addSecretIO[A <: Data](iodef: A)(implicit sourceInfo: SourceInfo): A = {
       val name = iodef._computeName(None).getOrElse("secret")
       iodef.setRef(ModuleIO(this, _namespace.name(name)))
-      val newPort = new Port(iodef, iodef.specifiedDirection, sourceInfo)
+      val newPort = new Port(iodef, iodef.specifiedDirection, Seq.empty, sourceInfo)
       if (_closed) {
         _component.get.secretPorts += newPort
       } else secretPorts += newPort
@@ -905,7 +928,9 @@ package experimental {
       * TODO(twigg): Specifically walk the Data definition to call out which nodes
       * are problematic.
       */
-    protected def IO[T <: Data](iodef: => T)(implicit sourceInfo: SourceInfo): T = {
+    protected def IO[T <: Data](iodef: => T)(
+      implicit sourceInfo: SourceInfo
+    ): T = {
       chisel3.IO.apply(iodef)
     }
 

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

@@ -91,7 +91,7 @@ abstract class RawModule extends BaseModule {
   private var _firrtlPorts: Option[Seq[Port]] = None
 
   private[chisel3] def checkPorts(): Unit = {
-    for ((port, source) <- getModulePortsAndLocators) {
+    for ((port, source, _) <- getModulePortsAndLocators) {
       if (port._computeName(None).isEmpty) {
         Builder.error(
           s"Unable to name port $port in $this, " +
@@ -175,8 +175,8 @@ abstract class RawModule extends BaseModule {
       nameId(id)
     }
 
-    val firrtlPorts = getModulePortsAndLocators.map { case (port, sourceInfo) =>
-      Port(port, port.specifiedDirection, sourceInfo)
+    val firrtlPorts = getModulePortsAndLocators.map { case (port, sourceInfo, associations) =>
+      Port(port, port.specifiedDirection, associations, sourceInfo)
     }
     _firrtlPorts = Some(firrtlPorts)
 

core/src/main/scala/chisel3/domain/Domain.scala

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.domain
+
+import chisel3.experimental.SourceInfo
+import chisel3.util.simpleClassName
+
+object Field {
+  sealed trait Type
+
+  object Boolean extends Type
+  object Integer extends Type
+  object String extends Type
+}
+
+abstract class Domain()(implicit val sourceInfo: SourceInfo) { self: Singleton =>
+
+  private[chisel3] def name: String = simpleClassName(this.getClass())
+
+  def fields: Seq[(String, Field.Type)] = Seq.empty
+
+}

core/src/main/scala/chisel3/domain/Type.scala

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.domain
+
+import chisel3.{fromIntToLiteral, Data, Element, Printable, UInt, UnknownWidth, Width}
+import chisel3.experimental.SourceInfo
+import chisel3.internal.{throwException, Builder}
+
+final class Type private (val domain: Domain) extends Element { self =>
+
+  private[chisel3] def _asUIntImpl(first: Boolean)(implicit sourceInfo: SourceInfo): chisel3.UInt = {
+    Builder.error(s"${this._localErrorContext} does not support .asUInt.")
+    0.U
+  }
+
+  override protected def _fromUInt(that: UInt)(implicit sourceInfo: SourceInfo): Data = {
+    Builder.exception(s"${this._localErrorContext} cannot be driven by UInt")
+  }
+
+  override def cloneType: this.type = new Type(domain).asInstanceOf[this.type]
+
+  override def toPrintable: Printable =
+    throwException(s"'domain.Type' does not support hardware printing" + this._errorContext)
+
+  private[chisel3] def width: Width = UnknownWidth
+
+  addDomain(domain)
+
+}
+
+object Type {
+
+  def apply(domain: Domain) = new Type(domain)
+
+}

core/src/main/scala/chisel3/domain/package.scala

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import chisel3.internal.Builder
+
+package object domain {
+
+  def addDomain(domain: Domain) = {
+    Builder.domains += domain
+  }
+
+}

core/src/main/scala/chisel3/domains/ClockDomain.scala

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.domains
+
+import chisel3.domain.{Domain, Field}
+import chisel3.experimental.UnlocatableSourceInfo
+
+object ClockDomain extends Domain()(sourceInfo = UnlocatableSourceInfo) {
+
+  override def fields: Seq[(String, Field.Type)] = Seq(
+    "name" -> Field.String
+  )
+
+}

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

@@ -23,8 +23,8 @@ abstract class IntrinsicModule(intrinsicName: String, val params: Map[String, Pa
     // Ports are named in the same way as regular Modules
     namePorts()
 
-    val firrtlPorts = getModulePorts.map { case port =>
-      Port(port, port.specifiedDirection, UnlocatableSourceInfo)
+    val firrtlPorts = getModulePortsAndLocators.map { case (port, _, associations) =>
+      Port(port, port.specifiedDirection, associations, UnlocatableSourceInfo)
     }
     val component = DefIntrinsicModule(this, name, firrtlPorts, SpecifiedDirection.Unspecified, params)
     _component = Some(component)

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

@@ -133,8 +133,14 @@ object Instance extends SourceInfoDoc {
       require(!_closed, s"Can't generate $desiredName module more than once")
       evaluateAtModuleBodyEnd()
       _closed = true
-      val firrtlPorts = importedDefinition.proto.getModulePortsAndLocators.map { case (port, sourceInfo) =>
-        Port(port, port.specifiedDirection, sourceInfo): @nowarn // Deprecated code allowed for internal use
+      val firrtlPorts = importedDefinition.proto.getModulePortsAndLocators.map {
+        case (port, sourceInfo, associations) =>
+          Port(
+            port,
+            port.specifiedDirection,
+            associations,
+            sourceInfo
+          ): @nowarn // Deprecated code allowed for internal use
       }
       val component =
         DefBlackBox(