Split IOBinders into IOBinders and HarnessBinders | punch out clocks to harness for simwidgets and bridges

.circleci/defaults.sh

@@ -61,8 +61,8 @@ mapping["chipyard-ariane"]=" CONFIG=ArianeConfig"
 mapping["chipyard-spiflashread"]=" CONFIG=LargeSPIFlashROMRocketConfig"
 mapping["chipyard-spiflashwrite"]=" CONFIG=SmallSPIFlashRocketConfig"
 mapping["chipyard-mmios"]=" CONFIG=MMIORocketConfig verilog"
-mapping["tracegen"]=" CONFIG=NonBlockingTraceGenL2Config TOP=TraceGenSystem"
-mapping["tracegen-boom"]=" CONFIG=BoomTraceGenConfig TOP=TraceGenSystem"
+mapping["tracegen"]=" CONFIG=NonBlockingTraceGenL2Config"
+mapping["tracegen-boom"]=" CONFIG=BoomTraceGenConfig"
 mapping["chipyard-nvdla"]=" CONFIG=SmallNVDLARocketConfig"
 mapping["firesim"]="SCALA_TEST=firesim.firesim.RocketNICF1Tests"
 mapping["firesim-multiclock"]="SCALA_TEST=firesim.firesim.RocketMulticlockF1Tests"

build.sbt

@@ -211,7 +211,7 @@ lazy val midas      = ProjectRef(firesimDir, "midas")
 lazy val firesimLib = ProjectRef(firesimDir, "firesimLib")
 
 lazy val firechip = conditionalDependsOn(project in file("generators/firechip"))
-  .dependsOn(chipyard, midasTargetUtils, midas, firesimLib % "test->test;compile->compile")
+  .dependsOn(chipyard, midasTargetUtils, midas, iocell, firesimLib % "test->test;compile->compile")
   .settings(
     commonSettings,
     testGrouping in Test := isolateAllTests( (definedTests in Test).value ),

docs/Advanced-Concepts/Debugging-BOOM.rst

@@ -12,11 +12,14 @@ to verify functionality.
 Setting up Dromajo Co-simulation
 --------------------------------------
 
-Dromajo co-simulation is setup to work when two config fragments are added to a BOOM config.
-First, a ``chipyard.config.WithTraceIO`` config fragment must be added so that BOOM's traceport is enabled.
-Second, a ``chipyard.iobinders.WithSimDromajoBridge`` config fragment must be added to
-connect the Dromajo co-simulator to the traceport.
-Once both config fragments are added Dromajo should be enabled.
+Dromajo co-simulation is setup to work when three config fragments are added to a BOOM config.
+
+ * A ``chipyard.config.WithTraceIO`` config fragment must be added so that BOOM's traceport is enabled.
+ * A ``chipyard.iobinders.WithTraceIOPunchthrough`` config fragment must be added to add the ``TraceIO`` to the ``ChipTop``
+ * A ``chipyard.harness.WithSimDromajoBridge`` config fragment must be added to instantiate a Dromajo cosimulator in the ``TestHarness`` and connect it to the ``ChipTop``'s ``TraceIO``
+
+
+Once all config fragments are added Dromajo should be enabled.
 
 To build/run Dromajo with a BOOM design, run your configuration the following make commands:
 

docs/Advanced-Concepts/Top-Testharness.rst

@@ -14,9 +14,9 @@ ChipTop/DUT
 ``ChipTop`` is the top-level module that instantiates the ``System`` submodule, usually an instance of the concrete class ``DigitalTop``.
 The vast majority of the design resides in the ``System``.
 Other components that exist inside the ``ChipTop`` layer are generally IO cells, clock receivers and multiplexers, reset synchronizers, and other analog IP that needs to exist outside of the ``System``.
-The ``IOBinders`` are responsible for instantiating the IO cells and defining the test harness collateral that connects to the top-level ports.
-Most of these types of devices can be instantiated using custom ``IOBinders``, so the provided ``ChipTop`` and ``ChipTopCaughtReset`` classes are sufficient.
-However, if needed, the ``BaseChipTop`` abstract class can be extended for building more custom ``ChipTop`` designs.
+The ``IOBinders`` are responsible for instantiating the IO cells for ``ChipTop`` IO that correspond to IO of the ``System``.
+The ``HarnessBinders`` are responsible for instantiating test harness collateral that connects to the ``ChipTop`` ports.
+Most types of devices and testing collateral can be instantiated using custom ``IOBinders`` and ``HarnessBinders``.
 
 
 System/DigitalTop

docs/Customization/IOBinders.rst

@@ -1,41 +1,45 @@
+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
 =========
 
-In Chipyard we use a special ``Parameters`` key, ``IOBinders`` to instantiate IO cells in the ``ChipTop`` layer and determine what modules to bind to the IOs of a ``ChipTop`` in the ``TestHarness``.
+The ``IOBinder`` functions are responsible for instantiating IO cells and IOPorts in the ``ChipTop`` layer.
+
+``IOBinders`` are typically defined using the ``OverrideIOBinder`` or ``ComposeIOBinder`` macros. An ``IOBInder`` consists of a function matching ``Systems`` with a given trait that generates IO ports and IOCells, and returns a list of generated ports and cells.
+
+For example, the ``WithUARTIOCells`` IOBinder specifies will, for any ``System`` that might have UART ports (``HasPeripheryUARTModuleIMP``, generate ports within the ``ChipTop`` (``ports``) as well as IOCells with the appropriate type and direction (``cells2d``). This function returns a the list of generated ports, and the list of generate IOCells. The list of generated ports is passed to the ``HarnessBinders`` such that they can be connected to ``TestHarness`` devices.
+
 
 .. literalinclude:: ../../generators/chipyard/src/main/scala/IOBinders.scala
    :language: scala
-   :start-after: DOC include start: IOBinders
-   :end-before: DOC include end: IOBinders
+   :start-after: DOC include start: WithUARTIOCells
+   :end-before: DOC include end: WithUARTIOCells
 
+HarnessBinders
+==============
 
-This special key solves the problem of duplicating test-harnesses for each different ``System`` type.
-You could just as well create a custom harness module that attaches IOs explicitly.
-Instead, the ``IOBinders`` key provides a map from Scala traits to attachment behaviors.
-Each ``IOBinder`` returns a tuple of three values: the list of ``ChipTop`` ports created by the ``IOBinder``, the list of all IO cell modules instantiated by the ``IOBinder``, and an optional function to be called inside the test harness.
-This function is responsible for instantiating logic inside the ``TestHarness`` to appropriately drive the ``ChipTop`` IO ports created by the ``IOBinder``.
-Conveniently, because the ``IOBinder`` is generating the port, it may also use the port inside this function, which prevents the ``BaseChipTop`` code from ever needing to access the port ``val``, thus having the ``IOBinder`` house all port specific code.
-This scheme prevents the need to have two separate binder functions for each ``System`` trait.
-When creating custom ``IOBinders`` it is important to use ``suggestName`` to name ports; otherwise Chisel will raise an exception trying to name the IOs.
-The example ``IOBinders`` demonstrate this.
+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 modes, enabling decoupling of the target design from simulation and testing concerns.
 
-As an example, the ``WithGPIOTiedOff`` IOBinder creates IO cells for the GPIO module(s) instantiated in the ``System``, then punches out new ``Analog`` ports for each one.
-The test harness simply ties these off, but additional logic could be inserted to perform some kind of test in the ``TestHarness``.
+ * For SW RTL simulations, the default set of ``HarnessBinders`` instantiate software-simulated models of various devices, for example external memory or UART, and connect those models to the IOs of the ``ChipTop``.
+ * For FireSim simulations, FireSim-specific ``HarnessBinders`` instantiate ``Bridges``, which faciliate cycle-accurate simulation across the simulated chip's IOs. See the FireSim documentation for more details.
+ * In the future, a Chipyard FPGA prototyping flow may use ``HarnessBinders`` to connect ``ChipTop`` IOs to other devices or IOs in the FPGA harness.
 
-.. literalinclude:: ../../generators/chipyard/src/main/scala/IOBinders.scala
-   :language: scala
-   :start-after: DOC include start: WithGPIOTiedOff
-   :end-before: DOC include end: WithGPIOTiedOff
+For FireSim simulations, the ``HarnessBinder`` attach ``Bridge`` modules (See the FireSim documentation for more details). 
 
+Like ``IOBinders``, ``HarnessBinders`` are defined using macros (``OverrideHarnessBinder, ComposeHarnessBinder``), and matches ``Systems`` with a given trait. However, ``HarnessBinders`` are also passed a reference to the ``TestHarness`` (``th: HasHarnessSignalReferences``) and the list of ports generated by the corresponding ``IOBinder`` (``ports: Seq[Data]``).
 
-``IOBinders`` also do not need to create ports. Some ``IOBinders`` can simply insert circuitry inside the ``ChipTop`` layer.
-For example, the ``WithSimAXIMemTiedOff`` IOBinder specifies that any ``System`` which matches ``CanHaveMasterAXI4MemPortModuleImp`` will have a ``SimAXIMem`` connected inside ``ChipTop``.
+For exmaple, the ``WithUARTAdapter`` will connect the UART SW display adapter to the ports generated by the ``WithUARTIOCells`` described earlier, if those ports are present.
 
-.. literalinclude:: ../../generators/chipyard/src/main/scala/IOBinders.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/HarnessBinders.scala
    :language: scala
-   :start-after: DOC include start: WithSimAXIMem
-   :end-before: DOC include end: WithSimAXIMem
+   :start-after: DOC include start: WithUARTAdapter
+   :end-before: DOC include end: WithUARTAdapter
+
+The ``IOBinder`` and ``HarnesBinder`` system is designed to enable decoupling of concerns between target design and simulation ssystem.
 
-These classes are all ``Config`` objects, which can be mixed into the configs to specify IO connection behaviors.
+For a given set of chip IOs, there may be not only multiple simulation platforms ("harnesses", so-to-speak), but also multiple simulation strategies. For example, the choice of whether to connect the backing AXI4 memory port to a accurate DRAM model (``SimDRAM``) or a simple simulated memory model (``SimAXIMem``) is isolated in ``HarnessBinders``, and does not affect target RTL generation.
 
-There are two macros for generating these ``Config``s. ``OverrideIOBinder`` overrides any existing behaviors set for a particular IO in the ``Config`` object. This macro is frequently used because typically top-level IOs drive or are driven by only one source, so a composition of ``IOBinders`` does not make sense. The ``ComposeIOBinder`` macro provides the functionality of not overriding existing behaviors.
+Similarly, for a given simulation platform and strategy, there may be multiple strategies for generating the chip IOs. This target-design configuration is isolated in the ``IOBinders``.

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

@@ -9,7 +9,7 @@ import freechips.rocketchip.subsystem.{BaseSubsystem, SubsystemDriveAsyncClockGr
 import freechips.rocketchip.config.{Parameters, Field}
 import freechips.rocketchip.diplomacy.{LazyModule, LazyModuleImp, LazyRawModuleImp, LazyModuleImpLike}
 import freechips.rocketchip.util.{ResetCatchAndSync}
-import chipyard.iobinders.{IOBinders, TestHarnessFunction, IOBinderTuple}
+import chipyard.iobinders._
 
 import barstools.iocell.chisel._
 
@@ -26,11 +26,9 @@ case object BuildSystem extends Field[Parameters => LazyModule]((p: Parameters)
 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]
-  // A list of functions to call in the test harness
-  val harnessFunctions = ArrayBuffer.empty[TestHarnessFunction]
 
   // The system module specified by BuildSystem
-  val lSystem = LazyModule(p(BuildSystem)(p)).suggestName("system")
+  val lazySystem = LazyModule(p(BuildSystem)(p)).suggestName("system")
 
   // The implicitClockSinkNode provides the implicit clock and reset for the System
   val implicitClockSinkNode = ClockSinkNode(Seq(ClockSinkParameters()))
@@ -50,15 +48,13 @@ class ChipTop(implicit p: Parameters) extends LazyModule with HasTestHarnessFunc
 
     // The implicit clock and reset for the system is also, by convention, used for all the IOBinders
     // TODO: This may not be the right thing to do in all cases
-    withClockAndReset(implicit_clock, implicit_reset) {
-      val (_ports, _iocells, _harnessFunctions) = p(IOBinders).values.flatMap(f => f(lSystem) ++ f(lSystem.module)).unzip3
-      // We ignore _ports for now...
-      iocells ++= _iocells.flatten
-      harnessFunctions ++= _harnessFunctions.flatten
-    }
+    val (_ports, _iocells, _portMap) = ApplyIOBinders(lazySystem, p(IOBinders))
+    // We ignore _ports for now...
+    iocells ++= _iocells
+    portMap ++= _portMap
 
     // Connect the implicit clock/reset, if present
-    lSystem.module match { case l: LazyModuleImp => {
+    lazySystem.module match { case l: LazyModuleImp => {
       l.clock := implicit_clock
       l.reset := implicit_reset
     }}

generators/chipyard/src/main/scala/Clocks.scala

@@ -91,7 +91,7 @@ object ClockingSchemeGenerators {
     chiptop.implicitClockSinkNode := implicitClockSourceNode
 
     // Drive the diplomaticclock graph of the DigitalTop (if present)
-    val simpleClockGroupSourceNode = chiptop.lSystem match {
+    val simpleClockGroupSourceNode = chiptop.lazySystem match {
       case l: BaseSubsystem if (p(SubsystemDriveAsyncClockGroupsKey).isEmpty) => {
         val n = ClockGroupSourceNode(Seq(ClockGroupSourceParameters()))
         l.asyncClockGroupsNode := n
@@ -120,6 +120,7 @@ object ClockingSchemeGenerators {
         }
       }}
 
+
       chiptop.harnessFunctions += ((th: HasHarnessSignalReferences) => {
         clock_io := th.harnessClock
         Nil
@@ -137,7 +138,7 @@ object ClockingSchemeGenerators {
     val implicitClockSourceNode = ClockSourceNode(Seq(ClockSourceParameters()))
     chiptop.implicitClockSinkNode := implicitClockSourceNode
 
-    val simpleClockGroupSourceNode = chiptop.lSystem match {
+    val simpleClockGroupSourceNode = chiptop.lazySystem match {
       case l: BaseSubsystem if (p(SubsystemDriveAsyncClockGroupsKey).isEmpty) => {
         val n = ClockGroupSourceNode(Seq(ClockGroupSourceParameters()))
         l.asyncClockGroupsNode := n

generators/chipyard/src/main/scala/DigitalTop.scala

@@ -33,7 +33,6 @@ class DigitalTop(implicit p: Parameters) extends ChipyardSystem
 class DigitalTopModule[+L <: DigitalTop](l: L) extends ChipyardSystemModule(l)
   with testchipip.CanHaveTraceIOModuleImp
   with testchipip.CanHavePeripheryBlockDeviceModuleImp
-  with testchipip.CanHavePeripherySerialModuleImp
   with sifive.blocks.devices.uart.HasPeripheryUARTModuleImp
   with sifive.blocks.devices.gpio.HasPeripheryGPIOModuleImp
   with sifive.blocks.devices.spi.HasPeripherySPIFlashModuleImp