Support diplomatic IOBinders

.circleci/defaults.sh

@@ -47,7 +47,7 @@ LOCAL_FIRESIM_DIR=$LOCAL_CHIPYARD_DIR/sims/firesim/sim
 
 # key value store to get the build groups
 declare -A grouping
-grouping["group-cores"]="chipyard-ariane chipyard-rocket chipyard-hetero chipyard-boom chipyard-sodor"
+grouping["group-cores"]="chipyard-ariane chipyard-rocket chipyard-hetero chipyard-boom chipyard-sodor chipyard-digitaltop"
 grouping["group-peripherals"]="chipyard-dmirocket chipyard-blkdev chipyard-spiflashread chipyard-spiflashwrite chipyard-mmios chipyard-lbwif"
 grouping["group-accels"]="chipyard-nvdla chipyard-sha3 chipyard-hwacha chipyard-gemmini chipyard-streaming-fir chipyard-streaming-passthrough"
 grouping["group-tracegen"]="tracegen tracegen-boom"
@@ -59,6 +59,7 @@ mapping["chipyard-rocket"]=""
 mapping["chipyard-dmirocket"]=" CONFIG=dmiRocketConfig"
 mapping["chipyard-lbwif"]=" CONFIG=LBWIFRocketConfig"
 mapping["chipyard-sha3"]=" CONFIG=Sha3RocketConfig"
+mapping["chipyard-digitaltop"]=" TOP=DigitalTop"
 mapping["chipyard-streaming-fir"]=" CONFIG=StreamingFIRRocketConfig"
 mapping["chipyard-streaming-passthrough"]=" CONFIG=StreamingPassthroughRocketConfig"
 mapping["chipyard-hetero"]=" CONFIG=LargeBoomAndRocketConfig"

docs/Customization/IOBinders.rst

@@ -4,7 +4,7 @@ IOBinders and HarnessBinders
 In Chipyard we use special ``Parameters`` keys, ``IOBinders`` and ``HarnessBinders`` to bridge the gap between digital system IOs and TestHarness collateral.
 
 IOBinders
-=========
+---------
 
 The ``IOBinder`` functions are responsible for instantiating IO cells and IOPorts in the ``ChipTop`` layer.
 
@@ -19,7 +19,7 @@ For example, the ``WithUARTIOCells`` IOBinder will, for any ``System`` that migh
    :end-before: DOC include end: WithUARTIOCells
 
 HarnessBinders
-==============
+--------------
 
 The ``HarnessBinder`` functions determine what modules to bind to the IOs of a ``ChipTop`` in the ``TestHarness``. The ``HarnessBinder`` interface is designed to be reused across various simulation/implementation modes, enabling decoupling of the target design from simulation and testing concerns.
 

generators/chipyard/src/main/scala/ChipTop.scala

@@ -23,12 +23,10 @@ case object BuildSystem extends Field[Parameters => LazyModule]((p: Parameters)
  * drive clock and reset generation
  */
 
-class ChipTop(implicit p: Parameters) extends LazyModule with HasTestHarnessFunctions {
-  // A publicly accessible list of IO cells (useful for a floorplanning tool, for example)
-  val iocells = ArrayBuffer.empty[IOCell]
-
+class ChipTop(implicit p: Parameters) extends LazyModule
+    with HasTestHarnessFunctions with HasIOBinders {
   // The system module specified by BuildSystem
-  val lazySystem = LazyModule(p(BuildSystem)(p)).suggestName("system")
+  lazy val lazySystem = LazyModule(p(BuildSystem)(p)).suggestName("system")
 
   // The implicitClockSinkNode provides the implicit clock and reset for the System
   val implicitClockSinkNode = ClockSinkNode(Seq(ClockSinkParameters(name = Some("implicit_clock"))))
@@ -45,13 +43,6 @@ class ChipTop(implicit p: Parameters) extends LazyModule with HasTestHarnessFunc
     val implicit_clock = implicitClockSinkNode.in.head._1.clock
     val implicit_reset = implicitClockSinkNode.in.head._1.reset
 
-
-    // Note: IOBinders cannot rely on the implicit clock/reset, as this is a LazyRawModuleImp
-    val (_ports, _iocells, _portMap) = ApplyIOBinders(lazySystem, p(IOBinders))
-    // We ignore _ports for now...
-    iocells ++= _iocells
-    portMap ++= _portMap
-
     // Connect the implicit clock/reset, if present
     lazySystem.module match { case l: LazyModuleImp => {
       l.clock := implicit_clock

generators/chipyard/src/main/scala/HarnessBinders.scala

@@ -1,7 +1,7 @@
 package chipyard.harness
 
 import chisel3._
-import chisel3.experimental.{Analog}
+import chisel3.experimental.{Analog, BaseModule}
 
 import freechips.rocketchip.config.{Field, Config, Parameters}
 import freechips.rocketchip.diplomacy.{LazyModule, LazyModuleImpLike}
@@ -31,81 +31,82 @@ case object HarnessBinders extends Field[Map[String, (Any, HasHarnessSignalRefer
   Map[String, (Any, HasHarnessSignalReferences, Seq[Data]) => Seq[Any]]().withDefaultValue((t: Any, th: HasHarnessSignalReferences, d: Seq[Data]) => Nil)
 )
 
-
 object ApplyHarnessBinders {
-  def apply(th: HasHarnessSignalReferences, sys: LazyModule, map: Map[String, (Any, HasHarnessSignalReferences, Seq[Data]) => Seq[Any]], portMap: Map[String, Seq[Data]]) = {
+  def apply(th: HasHarnessSignalReferences, sys: LazyModule, portMap: Map[String, Seq[Data]])(implicit p: Parameters) = {
     val pm = portMap.withDefaultValue(Nil)
-    map.map { case (s, f) => f(sys, th, pm(s)) ++ f(sys.module, th, pm(s)) }
+    p(HarnessBinders).map { case (s, f) => f(sys, th, pm(s)) ++ f(sys.module, th, pm(s)) }
   }
 }
 
-class OverrideHarnessBinder[T, S <: Data](fn: => (T, HasHarnessSignalReferences, Seq[S]) => Seq[Any])(implicit tag: ClassTag[T], ptag: ClassTag[S]) extends Config((site, here, up) => {
-  case HarnessBinders => up(HarnessBinders, site) + (tag.runtimeClass.toString ->
+// The ClassTags here are necessary to overcome issues arising from type erasure
+class HarnessBinder[T, S <: HasHarnessSignalReferences, U <: Data](composer: ((T, S, Seq[U]) => Seq[Any]) => (T, S, Seq[U]) => Seq[Any])(implicit systemTag: ClassTag[T], harnessTag: ClassTag[S], portTag: ClassTag[U]) extends Config((site, here, up) => {
+  case HarnessBinders => up(HarnessBinders, site) + (systemTag.runtimeClass.toString ->
       ((t: Any, th: HasHarnessSignalReferences, ports: Seq[Data]) => {
-        val pts = ports.collect({case p: S => p})
-        require (pts.length == ports.length, s"Port type mismatch between IOBinder and HarnessBinder: ${ptag}")
-        t match {
-          case system: T => fn(system, th, pts)
+        val pts = ports.collect({case p: U => p})
+        require (pts.length == ports.length, s"Port type mismatch between IOBinder and HarnessBinder: ${portTag}")
+        val upfn = up(HarnessBinders, site)(systemTag.runtimeClass.toString)
+        th match {
+          case th: S =>
+            t match {
+              case system: T => composer(upfn)(system, th, pts)
+              case _ => Nil
+            }
           case _ => Nil
         }
       })
   )
 })
 
-class ComposeHarnessBinder[T, S <: Data](fn: => (T, HasHarnessSignalReferences, Seq[S]) => Seq[Any])(implicit tag: ClassTag[T], ptag: ClassTag[S]) extends Config((site, here, up) => {
-  case HarnessBinders => up(HarnessBinders, site) + (tag.runtimeClass.toString ->
-      ((t: Any, th: HasHarnessSignalReferences, ports: Seq[Data]) => {
-        val pts = ports.collect({case p: S => p})
-        require (pts.length == ports.length, s"Port type mismatch between IOBinder and HarnessBinder: ${ptag}")
-        t match {
-          case system: T => up(HarnessBinders, site)(tag.runtimeClass.toString)(system, th, pts) ++ fn(system, th, pts)
-          case _ => Nil
-        }
-      })
-  )
-})
+class OverrideHarnessBinder[T, S <: HasHarnessSignalReferences, U <: Data](fn: => (T, S, Seq[U]) => Seq[Any])
+  (implicit tag: ClassTag[T], thtag: ClassTag[S], ptag: ClassTag[U])
+    extends HarnessBinder[T, S, U]((upfn: (T, S, Seq[U]) => Seq[Any]) => fn)
+
+class ComposeHarnessBinder[T, S <: HasHarnessSignalReferences, U <: Data](fn: => (T, S, Seq[U]) => Seq[Any])
+  (implicit tag: ClassTag[T], thtag: ClassTag[S], ptag: ClassTag[U])
+    extends HarnessBinder[T, S, U]((upfn: (T, S, Seq[U]) => Seq[Any]) => (t, th, p) => upfn(t, th, p) ++ fn(t, th, p))
+
 
 class WithGPIOTiedOff extends OverrideHarnessBinder({
-  (system: HasPeripheryGPIOModuleImp, th: HasHarnessSignalReferences, ports: Seq[Analog]) => {
+  (system: HasPeripheryGPIOModuleImp, th: BaseModule with HasHarnessSignalReferences, ports: Seq[Analog]) => {
     ports.foreach { _ <> AnalogConst(0) }
     Nil
   }
 })
 
 // DOC include start: WithUARTAdapter
 class WithUARTAdapter extends OverrideHarnessBinder({
-  (system: HasPeripheryUARTModuleImp, th: HasHarnessSignalReferences, ports: Seq[UARTPortIO]) => {
+  (system: HasPeripheryUARTModuleImp, th: BaseModule with HasHarnessSignalReferences, ports: Seq[UARTPortIO]) => {
     UARTAdapter.connect(ports)(system.p)
     Nil
   }
 })
 // DOC include end: WithUARTAdapter
 
 class WithSimSPIFlashModel(rdOnly: Boolean = true) extends OverrideHarnessBinder({
-  (system: HasPeripherySPIFlashModuleImp, th: HasHarnessSignalReferences, ports: Seq[SPIChipIO]) => {
+  (system: HasPeripherySPIFlashModuleImp, th: BaseModule with HasHarnessSignalReferences, ports: Seq[SPIChipIO]) => {
     SimSPIFlashModel.connect(ports, th.harnessReset, rdOnly)(system.p)
     Nil
   }
 })
 
 class WithSimBlockDevice extends OverrideHarnessBinder({
-  (system: CanHavePeripheryBlockDevice, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
+  (system: CanHavePeripheryBlockDevice, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
     ports.map { b => SimBlockDevice.connect(b.clock, th.harnessReset.asBool, Some(b.bits)) }
     Nil
   }
 })
 
 class WithBlockDeviceModel extends OverrideHarnessBinder({
-  (system: CanHavePeripheryBlockDevice, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
+  (system: CanHavePeripheryBlockDevice, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
     ports.map { b => withClockAndReset(b.clock, th.harnessReset) { BlockDeviceModel.connect(Some(b.bits)) } }
     Nil
   }
 })
 
 class WithLoopbackNIC extends OverrideHarnessBinder({
-  (system: CanHavePeripheryIceNIC, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[NICIOvonly]]) => {
+  (system: CanHavePeripheryIceNIC, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[NICIOvonly]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
     ports.map { n =>
       withClockAndReset(n.clock, th.harnessReset) {
@@ -117,7 +118,7 @@ class WithLoopbackNIC extends OverrideHarnessBinder({
 })
 
 class WithSimNetwork extends OverrideHarnessBinder({
-  (system: CanHavePeripheryIceNIC, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[NICIOvonly]]) => {
+  (system: CanHavePeripheryIceNIC, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[NICIOvonly]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
     ports.map { n => SimNetwork.connect(Some(n.bits), n.clock, th.harnessReset.asBool) }
     Nil
@@ -168,26 +169,27 @@ class WithSimAXIMMIO extends OverrideHarnessBinder({
 })
 
 class WithTieOffInterrupts extends OverrideHarnessBinder({
-  (system: HasExtInterruptsModuleImp, th: HasHarnessSignalReferences, ports: Seq[UInt]) => {
+  (system: HasExtInterruptsModuleImp, th: BaseModule with HasHarnessSignalReferences, ports: Seq[UInt]) => {
     ports.foreach { _ := 0.U }
     Nil
   }
 })
 
 class WithTieOffL2FBusAXI extends OverrideHarnessBinder({
-  (system: CanHaveSlaveAXI4Port, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[AXI4Bundle]]) => {
+  (system: CanHaveSlaveAXI4Port, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[AXI4Bundle]]) => {
     ports.foreach({ p => p := DontCare; p.bits.tieoff() })
     Nil
   }
 })
 
 class WithSimDebug extends OverrideHarnessBinder({
-  (system: HasPeripheryDebugModuleImp, th: HasHarnessSignalReferences, ports: Seq[Data]) => {
+  (system: HasPeripheryDebug, th: BaseModule with HasHarnessSignalReferences, ports: Seq[Data]) => {
+    implicit val p: Parameters = GetSystemParameters(system)
     ports.map {
       case d: ClockedDMIIO =>
         val dtm_success = WireInit(false.B)
         when (dtm_success) { th.success := true.B }
-        val dtm = Module(new SimDTM()(system.p)).connect(th.harnessClock, th.harnessReset.asBool, d, dtm_success)
+        val dtm = Module(new SimDTM).connect(th.harnessClock, th.harnessReset.asBool, d, dtm_success)
       case j: JTAGIO =>
         val dtm_success = WireInit(false.B)
         when (dtm_success) { th.success := true.B }
@@ -198,7 +200,7 @@ class WithSimDebug extends OverrideHarnessBinder({
 })
 
 class WithTiedOffDebug extends OverrideHarnessBinder({
-  (system: HasPeripheryDebugModuleImp, th: HasHarnessSignalReferences, ports: Seq[Data]) => {
+  (system: HasPeripheryDebug, th: BaseModule with HasHarnessSignalReferences, ports: Seq[Data]) => {
     ports.map {
       case j: JTAGIO =>
         j.TCK := true.B.asClock
@@ -224,7 +226,7 @@ class WithTiedOffDebug extends OverrideHarnessBinder({
 
 
 class WithSerialAdapterTiedOff extends OverrideHarnessBinder({
-  (system: CanHavePeripheryTLSerial, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[SerialIO]]) => {
+  (system: CanHavePeripheryTLSerial, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[SerialIO]]) => {
     implicit val p = chipyard.iobinders.GetSystemParameters(system)
     ports.map({ port =>
       val ram = SerialAdapter.connectHarnessRAM(system.serdesser.get, port, th.harnessReset)
@@ -234,7 +236,7 @@ class WithSerialAdapterTiedOff extends OverrideHarnessBinder({
 })
 
 class WithSimSerial extends OverrideHarnessBinder({
-  (system: CanHavePeripheryTLSerial, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[SerialIO]]) => {
+  (system: CanHavePeripheryTLSerial, th: BaseModule with HasHarnessSignalReferences, ports: Seq[ClockedIO[SerialIO]]) => {
     implicit val p = chipyard.iobinders.GetSystemParameters(system)
     ports.map({ port =>
       val ram = SerialAdapter.connectHarnessRAM(system.serdesser.get, port, th.harnessReset)
@@ -245,14 +247,14 @@ class WithSimSerial extends OverrideHarnessBinder({
 })
 
 class WithTraceGenSuccess extends OverrideHarnessBinder({
-  (system: TraceGenSystemModuleImp, th: HasHarnessSignalReferences, ports: Seq[Bool]) => {
+  (system: TraceGenSystemModuleImp, th: BaseModule with HasHarnessSignalReferences, ports: Seq[Bool]) => {
     ports.map { p => when (p) { th.success := true.B } }
     Nil
   }
 })
 
 class WithSimDromajoBridge extends ComposeHarnessBinder({
-  (system: CanHaveTraceIOModuleImp, th: HasHarnessSignalReferences, ports: Seq[TraceOutputTop]) => {
+  (system: CanHaveTraceIOModuleImp, th: BaseModule with HasHarnessSignalReferences, ports: Seq[TraceOutputTop]) => {
     ports.map { p => p.traces.map(tileTrace => SimDromajoBridge(tileTrace)(system.p)) }
     Nil
   }