Update harnessClk/Rst naming to buildtop | Small docs cleanup

docs/Advanced-Concepts/Chip-Communication.rst

@@ -46,7 +46,7 @@ Using the Tethered Serial Interface (TSI)
 
 By default, Chipyard uses the Tethered Serial Interface (TSI) to communicate with the DUT.
 TSI protocol is an implementation of HTIF that is used to send commands to the RISC-V DUT.
-These TSI commands are simple R/W commands that are able to probe the DUT's memory space.
+These TSI commands are simple R/W commands that are able to access the DUT's memory space.
 During simulation, the host sends TSI commands to a simulation stub in the test harness called ``SimSerial``
 (C++ class) that resides in a ``SimSerial`` Verilog module (both are located in the ``generators/testchipip``
 project).
@@ -59,7 +59,7 @@ Once the serialized transaction is received on the chip, it is deserialized and
 which handles the request.
 In simulation, FESVR resets the DUT, writes into memory the test program, and indicates to the DUT to start the program
 through an interrupt (see :ref:`customization/Boot-Process:Chipyard Boot Process`).
-Using TSI is currently the fastest mechanism to communicate with the DUT in simulation and is also used by FireSim.
+Using TSI is currently the fastest mechanism to communicate with the DUT in simulation (compared to DMI/JTAG) and is also used by FireSim.
 
 Using the Debug Module Interface (DMI)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -173,7 +173,7 @@ The following image shows the DUT with these set of default signals:
 
 In this setup, the serial-link is connected to the TSI/FESVR peripherals while the AXI port is connected
 to a simulated AXI memory.
-However, AXI ports tend to have many signals associated with them so instead of creating an AXI port off the DUT,
+However, AXI ports tend to have many signals, and thus wires, associated with them so instead of creating an AXI port off the DUT,
 one can send the memory transactions over the bi-directional serial-link (``TLSerdesser``) so that the main
 interface to the DUT is the serial-link (which has comparatively less signals than an AXI port).
 This new setup (shown below) is a typical Chipyard test chip setup:
@@ -216,7 +216,7 @@ This is done by the RISC-V soft-core running FESVR, sending TSI commands to a ``
 Once the commands are converted to serialized TileLink, then they can be sent over some medium to the DUT
 (like an FMC cable or a set of wires connecting FPGA outputs to the DUT board).
 Similar to simulation, if the chip requests offchip memory, it can then send the transaction back over the serial-link.
-Then the request can be serviced by the channel of FPGA DRAM.
+Then the request can be serviced by the FPGA DRAM.
 The following image shows this flow:
 
 .. image:: ../_static/images/chip-bringup.png

docs/Advanced-Concepts/Harness-Clocks.rst

@@ -8,8 +8,8 @@ have independent clock domains through diplomacy.
 This implies that some reference clock enters the ``ChipTop`` and then is divided down into
 separate clock domains.
 From the perspective of the ``TestHarness`` module, the ``ChipTop`` clock and reset is
-provided from the harness clock and reset (called ``harnessClock`` and ``harnessReset``).
+provided from a clock and reset called ``buildtopClock`` and ``buildtopReset``.
-In the default case, this ``harnessClock`` and ``harnessReset`` is directly wired to the
+In the default case, this ``buildtopClock`` and ``buildtopReset`` is directly wired to the
 clock and reset IO's of the ``TestHarness`` module.
 However, the ``TestHarness`` has the ability to generate a standalone clock and reset signal
 that is separate from the reference clock/reset of ``ChipTop``.
@@ -32,7 +32,7 @@ Here you can see the ``p(HarnessClockInstantiatorKey)`` is used to request a clo
 
 .. note::
     In the case that the reference clock entering ``ChipTop`` is not the overall reference clock of the simulation
-    (i.e. not the clock/reset coming into the ``TestHarness`` module), the ``harnessClock`` and ``harnessReset`` can
+    (i.e. the clock/reset coming into the ``TestHarness`` module), the ``buildtopClock`` and ``buildtopReset`` can
     differ from the implicit ``TestHarness`` clock and reset. For example, if the ``ChipTop`` reference is 500MHz but an
-    extra harness clock is requested at 1GHz, the ``TestHarness`` implicit clock/reset will be at 1GHz while the ``harnessClock``
+    extra harness clock is requested at 1GHz, the ``TestHarness`` implicit clock/reset will be at 1GHz while the ``buildtopClock``
-    and ``harnessReset`` will be at 500MHz.
+    and ``buildtopReset`` will be at 500MHz.

fpga/src/main/scala/arty/HarnessBinders.scala

@@ -32,7 +32,7 @@ class WithArtyJTAGHarnessBinder extends OverrideHarnessBinder({
   (system: HasPeripheryDebug, th: ArtyFPGATestHarness, ports: Seq[Data]) => {
     ports.map {
       case j: JTAGIO =>
-        withClockAndReset(th.harnessClock, th.hReset) {
+        withClockAndReset(th.buildtopClock, th.hReset) {
           val io_jtag = Wire(new JTAGPins(() => new BasePin(), false)).suggestName("jtag")
 
           JTAGPinsFromPort(io_jtag, j)

fpga/src/main/scala/arty/TestHarness.scala

@@ -27,8 +27,8 @@ class ArtyFPGATestHarness(override implicit val p: Parameters) extends ArtyShell
     val dut = Module(lazyDut.module)
   }
 
-  val harnessClock = clock_32MHz
+  val buildtopClock = clock_32MHz
-  val harnessReset = hReset
+  val buildtopReset = hReset
   val success = false.B
 
   val dutReset = dReset

fpga/src/main/scala/vcu118/TestHarness.scala

@@ -121,13 +121,13 @@ class VCU118FPGATestHarnessImp(_outer: VCU118FPGATestHarness) extends LazyRawMod
   val hReset = Wire(Reset())
   hReset := _outer.dutClock.in.head._1.reset
 
-  val harnessClock = _outer.dutClock.in.head._1.clock
+  val buildtopClock = _outer.dutClock.in.head._1.clock
-  val harnessReset = WireInit(hReset)
+  val buildtopReset = WireInit(hReset)
   val dutReset = hReset.asAsyncReset
   val success = false.B
 
-  childClock := harnessClock
+  childClock := buildtopClock
-  childReset := harnessReset
+  childReset := buildtopReset
 
   // harness binders are non-lazy
   _outer.topDesign match { case d: HasTestHarnessFunctions =>

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

@@ -118,7 +118,7 @@ object ClockingSchemeGenerators {
       }
 
       chiptop.harnessFunctions += ((th: HasHarnessSignalReferences) => {
-        clock_io := th.harnessClock
+        clock_io := th.buildtopClock
         Nil })
 
       // return the reference frequency

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

@@ -90,21 +90,21 @@ class WithUARTAdapter extends OverrideHarnessBinder({
 
 class WithSimSPIFlashModel(rdOnly: Boolean = true) extends OverrideHarnessBinder({
   (system: HasPeripherySPIFlashModuleImp, th: HasHarnessSignalReferences, ports: Seq[SPIChipIO]) => {
-    SimSPIFlashModel.connect(ports, th.harnessReset, rdOnly)(system.p)
+    SimSPIFlashModel.connect(ports, th.buildtopReset, rdOnly)(system.p)
   }
 })
 
 class WithSimBlockDevice extends OverrideHarnessBinder({
   (system: CanHavePeripheryBlockDevice, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
-    ports.map { b => SimBlockDevice.connect(b.clock, th.harnessReset.asBool, Some(b.bits)) }
+    ports.map { b => SimBlockDevice.connect(b.clock, th.buildtopReset.asBool, Some(b.bits)) }
   }
 })
 
 class WithBlockDeviceModel extends OverrideHarnessBinder({
   (system: CanHavePeripheryBlockDevice, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
-    ports.map { b => withClockAndReset(b.clock, th.harnessReset) { BlockDeviceModel.connect(Some(b.bits)) } }
+    ports.map { b => withClockAndReset(b.clock, th.buildtopReset) { BlockDeviceModel.connect(Some(b.bits)) } }
   }
 })
 
@@ -112,7 +112,7 @@ class WithLoopbackNIC extends OverrideHarnessBinder({
   (system: CanHavePeripheryIceNIC, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[NICIOvonly]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
     ports.map { n =>
-      withClockAndReset(n.clock, th.harnessReset) {
+      withClockAndReset(n.clock, th.buildtopReset) {
         NicLoopback.connect(Some(n.bits), p(NICKey))
       }
     }
@@ -122,7 +122,7 @@ class WithLoopbackNIC extends OverrideHarnessBinder({
 class WithSimNetwork extends OverrideHarnessBinder({
   (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) }
+    ports.map { n => SimNetwork.connect(Some(n.bits), n.clock, th.buildtopReset.asBool) }
   }
 })
 
@@ -152,23 +152,23 @@ class WithSimAXIMemOverSerialTL extends OverrideHarnessBinder({
 
       ports.map({ port =>
 // DOC include start: HarnessClockInstantiatorEx
-        withClockAndReset(th.harnessClock, th.harnessReset) {
+        withClockAndReset(th.buildtopClock, th.buildtopReset) {
           val memOverSerialTLClockBundle = p(HarnessClockInstantiatorKey).requestClockBundle("mem_over_serial_tl_clock", memFreq)
-          val serial_bits = SerialAdapter.asyncQueue(port, th.harnessClock, th.harnessReset)
+          val serial_bits = SerialAdapter.asyncQueue(port, th.buildtopClock, th.buildtopReset)
           val harnessMultiClockAXIRAM = SerialAdapter.connectHarnessMultiClockAXIRAM(
             system.serdesser.get,
             serial_bits,
             memOverSerialTLClockBundle,
-            th.harnessReset)
+            th.buildtopReset)
 // DOC include end: HarnessClockInstantiatorEx
-          val success = SerialAdapter.connectSimSerial(harnessMultiClockAXIRAM.module.io.tsi_ser, th.harnessClock, th.harnessReset.asBool)
+          val success = SerialAdapter.connectSimSerial(harnessMultiClockAXIRAM.module.io.tsi_ser, th.buildtopClock, th.buildtopReset.asBool)
           when (success) { th.success := true.B }
 
           // connect SimDRAM from the AXI port coming from the harness multi clock axi ram
           (harnessMultiClockAXIRAM.mem_axi4 zip harnessMultiClockAXIRAM.memNode.edges.in).map { case (axi_port, edge) =>
             val memSize = sVal.memParams.size
             val lineSize = p(CacheBlockBytes)
-            val mem = Module(new SimDRAM(memSize, lineSize, BigInt(memFreq.toInt), edge.bundle)).suggestName("simdram")
+            val mem = Module(new SimDRAM(memSize, lineSize, BigInt(memFreq.toLong), edge.bundle)).suggestName("simdram")
             mem.io.axi <> axi_port.bits
             mem.io.clock := axi_port.clock
             mem.io.reset := axi_port.reset
@@ -244,11 +244,11 @@ class WithSimDebug extends OverrideHarnessBinder({
       case d: ClockedDMIIO =>
         val dtm_success = WireInit(false.B)
         when (dtm_success) { th.success := true.B }
-        val dtm = Module(new SimDTM).connect(th.harnessClock, th.harnessReset.asBool, d, dtm_success)
+        val dtm = Module(new SimDTM).connect(th.buildtopClock, th.buildtopReset.asBool, d, dtm_success)
       case j: JTAGIO =>
         val dtm_success = WireInit(false.B)
         when (dtm_success) { th.success := true.B }
-        val jtag = Module(new SimJTAG(tickDelay=3)).connect(j, th.harnessClock, th.harnessReset.asBool, ~(th.harnessReset.asBool), dtm_success)
+        val jtag = Module(new SimJTAG(tickDelay=3)).connect(j, th.buildtopClock, th.buildtopReset.asBool, ~(th.buildtopReset.asBool), dtm_success)
     }
   }
 })
@@ -282,9 +282,9 @@ class WithSerialAdapterTiedOff extends OverrideHarnessBinder({
   (system: CanHavePeripheryTLSerial, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[SerialIO]]) => {
     implicit val p = chipyard.iobinders.GetSystemParameters(system)
     ports.map({ port =>
-      val bits = SerialAdapter.asyncQueue(port, th.harnessClock, th.harnessReset)
+      val bits = SerialAdapter.asyncQueue(port, th.buildtopClock, th.buildtopReset)
-      withClockAndReset(th.harnessClock, th.harnessReset) {
+      withClockAndReset(th.buildtopClock, th.buildtopReset) {
-        val ram = SerialAdapter.connectHarnessRAM(system.serdesser.get, bits, th.harnessReset)
+        val ram = SerialAdapter.connectHarnessRAM(system.serdesser.get, bits, th.buildtopReset)
         SerialAdapter.tieoff(ram.module.io.tsi_ser)
       }
     })
@@ -295,10 +295,10 @@ class WithSimSerial extends OverrideHarnessBinder({
   (system: CanHavePeripheryTLSerial, th: HasHarnessSignalReferences, ports: Seq[ClockedIO[SerialIO]]) => {
     implicit val p = chipyard.iobinders.GetSystemParameters(system)
     ports.map({ port =>
-      val bits = SerialAdapter.asyncQueue(port, th.harnessClock, th.harnessReset)
+      val bits = SerialAdapter.asyncQueue(port, th.buildtopClock, th.buildtopReset)
-      withClockAndReset(th.harnessClock, th.harnessReset) {
+      withClockAndReset(th.buildtopClock, th.buildtopReset) {
-        val ram = SerialAdapter.connectHarnessRAM(system.serdesser.get, bits, th.harnessReset)
+        val ram = SerialAdapter.connectHarnessRAM(system.serdesser.get, bits, th.buildtopReset)
-        val success = SerialAdapter.connectSimSerial(ram.module.io.tsi_ser, th.harnessClock, th.harnessReset.asBool)
+        val success = SerialAdapter.connectSimSerial(ram.module.io.tsi_ser, th.buildtopClock, th.buildtopReset.asBool)
         when (success) { th.success := true.B }
       }
     })

generators/chipyard/src/main/scala/TestHarness.scala

@@ -24,8 +24,8 @@ trait HasTestHarnessFunctions {
 
 trait HasHarnessSignalReferences {
   // clock/reset of the chiptop reference clock (can be different than the implicit harness clock/reset)
-  def harnessClock: Clock
+  def buildtopClock: Clock
-  def harnessReset: Reset
+  def buildtopReset: Reset
   def dutReset: Reset
   def success: Bool
 }
@@ -82,8 +82,8 @@ class TestHarness(implicit val p: Parameters) extends Module with HasHarnessSign
     val success = Output(Bool())
   })
 
-  val harnessClock = Wire(Clock())
+  val buildtopClock = Wire(Clock())
-  val harnessReset = Wire(Reset())
+  val buildtopReset = Wire(Reset())
 
   val lazyDut = LazyModule(p(BuildTop)(p)).suggestName("chiptop")
   val dut = Module(lazyDut.module)
@@ -96,8 +96,8 @@ class TestHarness(implicit val p: Parameters) extends Module with HasHarnessSign
   }
   val refClkBundle = p(HarnessClockInstantiatorKey).requestClockBundle("buildtop_reference_clock", freqMHz * (1000 * 1000))
 
-  harnessClock := refClkBundle.clock
+  buildtopClock := refClkBundle.clock
-  harnessReset := WireInit(refClkBundle.reset)
+  buildtopReset := WireInit(refClkBundle.reset)
   val dutReset = refClkBundle.reset.asAsyncReset
 
   val success = io.success

generators/firechip/src/main/scala/BridgeBinders.scala

@@ -72,11 +72,11 @@ class WithSerialBridge extends OverrideHarnessBinder({
   (system: CanHavePeripheryTLSerial, th: FireSim, ports: Seq[ClockedIO[SerialIO]]) => {
     ports.map { port =>
       implicit val p = GetSystemParameters(system)
-      val bits = SerialAdapter.asyncQueue(port, th.harnessClock, th.harnessReset)
+      val bits = SerialAdapter.asyncQueue(port, th.buildtopClock, th.buildtopReset)
-      val ram = withClockAndReset(th.harnessClock, th.harnessReset) {
+      val ram = withClockAndReset(th.buildtopClock, th.buildtopReset) {
-        SerialAdapter.connectHarnessRAM(system.serdesser.get, bits, th.harnessReset)
+        SerialAdapter.connectHarnessRAM(system.serdesser.get, bits, th.buildtopReset)
       }
-      SerialBridge(th.harnessClock, ram.module.io.tsi_ser, p(ExtMem).map(_ => MainMemoryConsts.globalName))
+      SerialBridge(th.buildtopClock, ram.module.io.tsi_ser, p(ExtMem).map(_ => MainMemoryConsts.globalName))
     }
     Nil
   }
@@ -103,7 +103,7 @@ class WithUARTBridge extends OverrideHarnessBinder({
 class WithBlockDeviceBridge extends OverrideHarnessBinder({
   (system: CanHavePeripheryBlockDevice, th: FireSim, ports: Seq[ClockedIO[BlockDeviceIO]]) => {
     implicit val p: Parameters = GetSystemParameters(system)
-    ports.map { b => BlockDevBridge(b.clock, b.bits, th.harnessReset.asBool) }
+    ports.map { b => BlockDevBridge(b.clock, b.bits, th.buildtopReset.asBool) }
     Nil
   }
 })
@@ -123,18 +123,18 @@ class WithAXIOverSerialTLCombinedBridges extends OverrideHarnessBinder({
         val axiClock = p(ClockBridgeInstantiatorKey).requestClock("mem_over_serial_tl_clock", memFreq)
         val axiClockBundle = Wire(new ClockBundle(ClockBundleParameters()))
         axiClockBundle.clock := axiClock
-        axiClockBundle.reset := ResetCatchAndSync(axiClock, th.harnessReset.asBool)
+        axiClockBundle.reset := ResetCatchAndSync(axiClock, th.buildtopReset.asBool)
 
-        val serial_bits = SerialAdapter.asyncQueue(port, th.harnessClock, th.harnessReset)
+        val serial_bits = SerialAdapter.asyncQueue(port, th.buildtopClock, th.buildtopReset)
 
-        val harnessMultiClockAXIRAM = withClockAndReset(th.harnessClock, th.harnessReset) {
+        val harnessMultiClockAXIRAM = withClockAndReset(th.buildtopClock, th.buildtopReset) {
           SerialAdapter.connectHarnessMultiClockAXIRAM(
             system.serdesser.get,
             serial_bits,
             axiClockBundle,
-            th.harnessReset)
+            th.buildtopReset)
         }
-        SerialBridge(th.harnessClock, harnessMultiClockAXIRAM.module.io.tsi_ser, Some(MainMemoryConsts.globalName))
+        SerialBridge(th.buildtopClock, harnessMultiClockAXIRAM.module.io.tsi_ser, Some(MainMemoryConsts.globalName))
 
         // connect SimAxiMem
         (harnessMultiClockAXIRAM.mem_axi4 zip harnessMultiClockAXIRAM.memNode.edges.in).map { case (axi4, edge) =>
@@ -192,7 +192,7 @@ class WithDromajoBridge extends ComposeHarnessBinder({
 
 class WithTraceGenBridge extends OverrideHarnessBinder({
   (system: TraceGenSystemModuleImp, th: FireSim, ports: Seq[Bool]) =>
-    ports.map { p => GroundTestBridge(th.harnessClock, p)(system.p) }; Nil
+    ports.map { p => GroundTestBridge(th.buildtopClock, p)(system.p) }; Nil
 })
 
 class WithFireSimMultiCycleRegfile extends ComposeIOBinder({

generators/firechip/src/main/scala/FireSim.scala

@@ -195,7 +195,7 @@ class WithFireSimSimpleClocks extends Config((site, here, up) => {
       }
 
       chiptop.harnessFunctions += ((th: HasHarnessSignalReferences) => {
-        reset := th.harnessReset
+        reset := th.buildtopReset
         input_clocks := p(ClockBridgeInstantiatorKey)
           .requestClockRecordMap(rationalClockSpecs.toSeq, p(FireSimBaseClockNameKey), pllConfig.referenceFreqMHz * (1000 * 1000))
         Nil })
@@ -209,9 +209,9 @@ class WithFireSimSimpleClocks extends Config((site, here, up) => {
 class FireSim(implicit val p: Parameters) extends RawModule with HasHarnessSignalReferences {
   freechips.rocketchip.util.property.cover.setPropLib(new midas.passes.FireSimPropertyLibrary())
 
-  val harnessClock = Wire(Clock())
+  val buildtopClock = Wire(Clock())
-  val harnessReset = WireInit(false.B)
+  val buildtopReset = WireInit(false.B)
-  val peekPokeBridge = PeekPokeBridge(harnessClock, harnessReset)
+  val peekPokeBridge = PeekPokeBridge(buildtopClock, buildtopReset)
   def dutReset = { require(false, "dutReset should not be used in Firesim"); false.B }
   def success = { require(false, "success should not be used in Firesim"); false.B }
 
@@ -244,7 +244,7 @@ class FireSim(implicit val p: Parameters) extends RawModule with HasHarnessSigna
     NodeIdx.increment()
   }
 
-  harnessClock := p(ClockBridgeInstantiatorKey).requestClock("buildtop_reference_clock", btFreqMHz.get * (1000 * 1000))
+  buildtopClock := p(ClockBridgeInstantiatorKey).requestClock("buildtop_reference_clock", btFreqMHz.get * (1000 * 1000))
 
   p(ClockBridgeInstantiatorKey).instantiateFireSimClockBridge
 }