PLL integration example + FlatChipTop/TestHarness

.github/scripts/defaults.sh

@@ -29,7 +29,7 @@ REMOTE_COURSIER_CACHE=$REMOTE_WORK_DIR/.coursier-cache
 # key value store to get the build groups
 declare -A grouping
 grouping["group-cores"]="chipyard-cva6 chipyard-ibex chipyard-rocket chipyard-hetero chipyard-boom chipyard-sodor chipyard-digitaltop chipyard-multiclock-rocket chipyard-nomem-scratchpad chipyard-spike chipyard-clone"
-grouping["group-peripherals"]="chipyard-dmirocket chipyard-spiflashwrite chipyard-mmios chipyard-nocores chipyard-manyperipherals"
+grouping["group-peripherals"]="chipyard-dmirocket chipyard-spiflashwrite chipyard-mmios chipyard-nocores chipyard-manyperipherals chipyard-chiplike"
 grouping["group-accels"]="chipyard-mempress chipyard-sha3 chipyard-hwacha chipyard-gemmini chipyard-manymmioaccels"
 grouping["group-constellation"]="chipyard-constellation"
 grouping["group-tracegen"]="tracegen tracegen-boom"
@@ -53,6 +53,7 @@ mapping["chipyard-cva6"]=" CONFIG=CVA6Config"
 mapping["chipyard-ibex"]=" CONFIG=IbexConfig"
 mapping["chipyard-spiflashwrite"]=" CONFIG=SmallSPIFlashRocketConfig EXTRA_SIM_FLAGS='+spiflash0=${LOCAL_CHIPYARD_DIR}/tests/spiflash.img'"
 mapping["chipyard-manyperipherals"]=" CONFIG=ManyPeripheralsRocketConfig EXTRA_SIM_FLAGS='+spiflash0=${LOCAL_CHIPYARD_DIR}/tests/spiflash.img'"
+mapping["chipyard-chiplike"]=" CONFIG=ChipLikeQuadRocketConfig verilog"
 mapping["chipyard-cloneboom"]=" CONFIG=Cloned64MegaBoomConfig verilog"
 mapping["chipyard-nocores"]=" CONFIG=NoCoresConfig verilog"
 mapping["tracegen"]=" CONFIG=NonBlockingTraceGenL2Config"

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

@@ -22,8 +22,8 @@ import barstools.iocell.chisel._
 import testchipip._
 
 import chipyard._
-import chipyard.clocking.{HasChipyardPRCI}
-import chipyard.iobinders.{GetSystemParameters, JTAGChipIO, ClockWithFreq}
+import chipyard.clocking.{HasChipyardPRCI, ClockWithFreq}
+import chipyard.iobinders.{GetSystemParameters, JTAGChipIO}
 
 import tracegen.{TraceGenSystemModuleImp}
 import icenet.{CanHavePeripheryIceNIC, SimNetwork, NicLoopback, NICKey, NICIOvonly}
@@ -154,7 +154,7 @@ class WithSimAXIMemOverSerialTL extends OverrideHarnessBinder({
       ports.map({ port =>
 // DOC include start: HarnessClockInstantiatorEx
         withClockAndReset(th.buildtopClock, th.buildtopReset) {
-          val memOverSerialTLClockBundle = p(HarnessClockInstantiatorKey).requestClockBundle("mem_over_serial_tl_clock", memFreq)
+          val memOverSerialTLClockBundle = th.harnessClockInstantiator.requestClockBundle("mem_over_serial_tl_clock", memFreq)
           val serial_bits = SerialAdapter.asyncQueue(port, th.buildtopClock, th.buildtopReset)
           val harnessMultiClockAXIRAM = SerialAdapter.connectHarnessMultiClockAXIRAM(
             system.serdesser.get,

generators/chipyard/src/main/scala/HarnessClocks.scala

@@ -0,0 +1,96 @@
+package chipyard
+
+import chisel3._
+
+import scala.collection.mutable.{ArrayBuffer, LinkedHashMap}
+import freechips.rocketchip.diplomacy.{LazyModule}
+import org.chipsalliance.cde.config.{Field, Parameters, Config}
+import freechips.rocketchip.util.{ResetCatchAndSync}
+import freechips.rocketchip.prci._
+
+import chipyard.harness.{ApplyHarnessBinders, HarnessBinders}
+import chipyard.iobinders.HasIOBinders
+import chipyard.clocking.{SimplePllConfiguration, ClockDividerN}
+import chipyard.HarnessClockInstantiatorKey
+
+
+// HarnessClockInstantiators are classes which generate clocks that drive
+// TestHarness simulation models and any Clock inputs to the ChipTop
+trait HarnessClockInstantiator {
+  val _clockMap: LinkedHashMap[String, (Double, ClockBundle)] = LinkedHashMap.empty
+
+  // request a clock bundle at a particular frequency
+  def requestClockBundle(name: String, freqRequested: Double): ClockBundle = {
+    val clockBundle = Wire(new ClockBundle(ClockBundleParameters()))
+    _clockMap(name) = (freqRequested, clockBundle)
+    clockBundle
+  }
+
+  // refClock is the clock generated by TestDriver that is
+  // passed to the TestHarness as its implicit clock
+  def instantiateHarnessClocks(refClock: ClockBundle): Unit
+}
+
+// The DividerOnlyHarnessClockInstantiator uses synthesizable clock divisors
+// to approximate frequency ratios between the requested clocks
+class DividerOnlyHarnessClockInstantiator extends HarnessClockInstantiator {
+  // connect all clock wires specified to a divider only PLL
+  def instantiateHarnessClocks(refClock: ClockBundle): Unit = {
+    val sinks = _clockMap.map({ case (name, (freq, bundle)) =>
+      ClockSinkParameters(take=Some(ClockParameters(freqMHz=freq / (1000 * 1000))), name=Some(name))
+    }).toSeq
+
+    val pllConfig = new SimplePllConfiguration("harnessDividerOnlyClockGenerator", sinks)
+    pllConfig.emitSummaries()
+
+    val dividedClocks = LinkedHashMap[Int, Clock]()
+    def instantiateDivider(div: Int): Clock = {
+      val divider = Module(new ClockDividerN(div))
+      divider.suggestName(s"ClockDivideBy${div}")
+      divider.io.clk_in := refClock.clock
+      dividedClocks(div) = divider.io.clk_out
+      divider.io.clk_out
+    }
+
+    // connect wires to clock source
+    for (sinkParams <- sinks) {
+      // bypass the reference freq. (don't create a divider + reset sync)
+      val (divClock, divReset) = if (sinkParams.take.get.freqMHz != pllConfig.referenceFreqMHz) {
+        val div = pllConfig.sinkDividerMap(sinkParams)
+        val divClock = dividedClocks.getOrElse(div, instantiateDivider(div))
+        (divClock, ResetCatchAndSync(divClock, refClock.reset.asBool))
+      } else {
+        (refClock.clock, refClock.reset)
+      }
+
+      _clockMap(sinkParams.name.get)._2.clock := divClock
+      _clockMap(sinkParams.name.get)._2.reset := divReset
+    }
+  }
+}
+
+// The AbsoluteFreqHarnessClockInstantiator uses a Verilog blackbox to
+// provide the precise requested frequency.
+// This ClockInstantiator cannot be synthesized, run in Verilator, or run in FireSim
+// It is useful for VCS/Xcelium-driven RTL simulations
+class AbsoluteFreqHarnessClockInstantiator extends HarnessClockInstantiator {
+  def instantiateHarnessClocks(refClock: ClockBundle): Unit = {
+    val sinks = _clockMap.map({ case (name, (freq, bundle)) =>
+      ClockSinkParameters(take=Some(ClockParameters(freqMHz=freq / (1000 * 1000))), name=Some(name))
+    }).toSeq
+
+    // connect wires to clock source
+    for (sinkParams <- sinks) {
+      val source = Module(new ClockSourceAtFreq(sinkParams.take.get.freqMHz))
+      source.io.power := true.B
+      source.io.gate := false.B
+
+      _clockMap(sinkParams.name.get)._2.clock := source.io.clk
+      _clockMap(sinkParams.name.get)._2.reset := refClock.reset
+    }
+  }
+}
+
+class WithAbsoluteFreqHarnessClockInstantiator extends Config((site, here, up) => {
+  case HarnessClockInstantiatorKey => () => new AbsoluteFreqHarnessClockInstantiator
+})

generators/chipyard/src/main/scala/IOBinders.scala

@@ -425,45 +425,4 @@ class WithDontTouchPorts extends OverrideIOBinder({
   (system: DontTouch) => system.dontTouchPorts(); (Nil, Nil)
 })
 
-class ClockWithFreq(val freqMHz: Double) extends Bundle {
-  val clock = Clock()
-}
-
-class WithDividerOnlyClockGenerator extends OverrideLazyIOBinder({
-  (system: HasChipyardPRCI) => {
-    // Connect the implicit clock
-    implicit val p = GetSystemParameters(system)
-    val implicitClockSinkNode = ClockSinkNode(Seq(ClockSinkParameters(name = Some("implicit_clock"))))
-    system.connectImplicitClockSinkNode(implicitClockSinkNode)
-    InModuleBody {
-      val implicit_clock = implicitClockSinkNode.in.head._1.clock
-      val implicit_reset = implicitClockSinkNode.in.head._1.reset
-      system.asInstanceOf[BaseSubsystem].module match { case l: LazyModuleImp => {
-        l.clock := implicit_clock
-        l.reset := implicit_reset
-      }}
-    }
-
-    // Connect all other requested clocks
-    val referenceClockSource = ClockSourceNode(Seq(ClockSourceParameters()))
-    val dividerOnlyClockGen = LazyModule(new DividerOnlyClockGenerator("buildTopClockGenerator"))
-
-    (system.allClockGroupsNode
-      := dividerOnlyClockGen.node
-      := referenceClockSource)
 
-    InModuleBody {
-      val clock_wire = Wire(Input(new ClockWithFreq(dividerOnlyClockGen.module.referenceFreq)))
-      val reset_wire = Wire(Input(AsyncReset()))
-      val (clock_io, clockIOCell) = IOCell.generateIOFromSignal(clock_wire, "clock", p(IOCellKey))
-      val (reset_io, resetIOCell) = IOCell.generateIOFromSignal(reset_wire, "reset", p(IOCellKey))
-
-      referenceClockSource.out.unzip._1.map { o =>
-        o.clock := clock_wire.clock
-        o.reset := reset_wire
-      }
-
-      (Seq(clock_io, reset_io), clockIOCell ++ resetIOCell)
-    }
-  }
-})

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

@@ -18,9 +18,11 @@ import chipyard.clocking.{SimplePllConfiguration, ClockDividerN}
 
 case object BuildTop extends Field[Parameters => LazyModule]((p: Parameters) => new ChipTop()(p))
 case object DefaultClockFrequencyKey extends Field[Double](100.0) // MHz
+case object HarnessClockInstantiatorKey extends Field[() => HarnessClockInstantiator](() => new DividerOnlyHarnessClockInstantiator)
 
 trait HasHarnessSignalReferences {
   implicit val p: Parameters
+  val harnessClockInstantiator = p(HarnessClockInstantiatorKey)()
   // clock/reset of the chiptop reference clock (can be different than the implicit harness clock/reset)
   var refClockFreq: Double = p(DefaultClockFrequencyKey)
   def setRefClockFreq(freqMHz: Double) = { refClockFreq = freqMHz }
@@ -30,53 +32,6 @@ trait HasHarnessSignalReferences {
   def success: Bool
 }
 
-class HarnessClockInstantiator {
-  private val _clockMap: LinkedHashMap[String, (Double, ClockBundle)] = LinkedHashMap.empty
-
-  // request a clock bundle at a particular frequency
-  def requestClockBundle(name: String, freqRequested: Double): ClockBundle = {
-    val clockBundle = Wire(new ClockBundle(ClockBundleParameters()))
-    _clockMap(name) = (freqRequested, clockBundle)
-    clockBundle
-  }
-
-  // connect all clock wires specified to a divider only PLL
-  def instantiateHarnessDividerPLL(refClock: ClockBundle): Unit = {
-    val sinks = _clockMap.map({ case (name, (freq, bundle)) =>
-      ClockSinkParameters(take=Some(ClockParameters(freqMHz=freq / (1000 * 1000))), name=Some(name))
-    }).toSeq
-
-    val pllConfig = new SimplePllConfiguration("harnessDividerOnlyClockGenerator", sinks)
-    pllConfig.emitSummaries()
-
-    val dividedClocks = LinkedHashMap[Int, Clock]()
-    def instantiateDivider(div: Int): Clock = {
-      val divider = Module(new ClockDividerN(div))
-      divider.suggestName(s"ClockDivideBy${div}")
-      divider.io.clk_in := refClock.clock
-      dividedClocks(div) = divider.io.clk_out
-      divider.io.clk_out
-    }
-
-    // connect wires to clock source
-    for (sinkParams <- sinks) {
-      // bypass the reference freq. (don't create a divider + reset sync)
-      val (divClock, divReset) = if (sinkParams.take.get.freqMHz != pllConfig.referenceFreqMHz) {
-        val div = pllConfig.sinkDividerMap(sinkParams)
-        val divClock = dividedClocks.getOrElse(div, instantiateDivider(div))
-        (divClock, ResetCatchAndSync(divClock, refClock.reset.asBool))
-      } else {
-        (refClock.clock, refClock.reset)
-      }
-
-      _clockMap(sinkParams.name.get)._2.clock := divClock
-      _clockMap(sinkParams.name.get)._2.reset := divReset
-    }
-  }
-}
-
-case object HarnessClockInstantiatorKey extends Field[HarnessClockInstantiator](new HarnessClockInstantiator)
-
 class TestHarness(implicit val p: Parameters) extends Module with HasHarnessSignalReferences {
   val io = IO(new Bundle {
     val success = Output(Bool())
@@ -96,13 +51,13 @@ class TestHarness(implicit val p: Parameters) extends Module with HasHarnessSign
     ApplyHarnessBinders(this, d.lazySystem, d.portMap)
   }
 
-  val refClkBundle = p(HarnessClockInstantiatorKey).requestClockBundle("buildtop_reference_clock", getRefClockFreq * (1000 * 1000))
+  val refClkBundle = harnessClockInstantiator.requestClockBundle("buildtop_reference_clock", getRefClockFreq * (1000 * 1000))
 
   buildtopClock := refClkBundle.clock
   buildtopReset := WireInit(refClkBundle.reset)
 
   val implicitHarnessClockBundle = Wire(new ClockBundle(ClockBundleParameters()))
   implicitHarnessClockBundle.clock := clock
   implicitHarnessClockBundle.reset := reset
-  p(HarnessClockInstantiatorKey).instantiateHarnessDividerPLL(implicitHarnessClockBundle)
+  harnessClockInstantiator.instantiateHarnessClocks(implicitHarnessClockBundle)
 }

generators/chipyard/src/main/scala/clocking/ClockBinders.scala

@@ -0,0 +1,127 @@
+package chipyard.clocking
+
+import chisel3._
+import chisel3.util._
+import chipyard.iobinders.{OverrideLazyIOBinder, GetSystemParameters, IOCellKey}
+import freechips.rocketchip.prci._
+import freechips.rocketchip.diplomacy._
+import freechips.rocketchip.subsystem._
+import freechips.rocketchip.tilelink._
+import barstools.iocell.chisel._
+
+class ClockWithFreq(val freqMHz: Double) extends Bundle {
+  val clock = Clock()
+}
+
+// This uses synthesizable clock divisors to approximate frequency rations
+// between the requested clocks. This is currently the defualt clock generator "model",
+// as it can be used in VCS/Xcelium/Verilator/FireSim
+class WithDividerOnlyClockGenerator extends OverrideLazyIOBinder({
+  (system: HasChipyardPRCI) => {
+    // Connect the implicit clock
+    implicit val p = GetSystemParameters(system)
+    val implicitClockSinkNode = ClockSinkNode(Seq(ClockSinkParameters(name = Some("implicit_clock"))))
+    system.connectImplicitClockSinkNode(implicitClockSinkNode)
+    InModuleBody {
+      val implicit_clock = implicitClockSinkNode.in.head._1.clock
+      val implicit_reset = implicitClockSinkNode.in.head._1.reset
+      system.asInstanceOf[BaseSubsystem].module match { case l: LazyModuleImp => {
+        l.clock := implicit_clock
+        l.reset := implicit_reset
+      }}
+    }
+
+    // Connect all other requested clocks
+    val referenceClockSource = ClockSourceNode(Seq(ClockSourceParameters()))
+    val dividerOnlyClockGen = LazyModule(new DividerOnlyClockGenerator("buildTopClockGenerator"))
+
+    (system.allClockGroupsNode
+      := dividerOnlyClockGen.node
+      := referenceClockSource)
+
+    InModuleBody {
+      val clock_wire = Wire(Input(new ClockWithFreq(dividerOnlyClockGen.module.referenceFreq)))
+      val reset_wire = Wire(Input(AsyncReset()))
+      val (clock_io, clockIOCell) = IOCell.generateIOFromSignal(clock_wire, "clock", p(IOCellKey))
+      val (reset_io, resetIOCell) = IOCell.generateIOFromSignal(reset_wire, "reset", p(IOCellKey))
+
+      referenceClockSource.out.unzip._1.map { o =>
+        o.clock := clock_wire.clock
+        o.reset := reset_wire
+      }
+
+      (Seq(clock_io, reset_io), clockIOCell ++ resetIOCell)
+    }
+  }
+})
+
+// This uses the FakePLL, which uses a ClockAtFreq Verilog blackbox to generate
+// the requested clocks. This also adds TileLink ClockDivider and ClockSelector
+// blocks, which allow memory-mapped control of clock division, and clock muxing
+// between the FakePLL and the slow off-chip clock
+// Note: This will not simulate properly with verilator or firesim
+class WithPLLSelectorDividerClockGenerator extends OverrideLazyIOBinder({
+  (system: HasChipyardPRCI) => {
+    // Connect the implicit clock
+    implicit val p = GetSystemParameters(system)
+    val implicitClockSinkNode = ClockSinkNode(Seq(ClockSinkParameters(name = Some("implicit_clock"))))
+    system.connectImplicitClockSinkNode(implicitClockSinkNode)
+    InModuleBody {
+      val implicit_clock = implicitClockSinkNode.in.head._1.clock
+      val implicit_reset = implicitClockSinkNode.in.head._1.reset
+      system.asInstanceOf[BaseSubsystem].module match { case l: LazyModuleImp => {
+        l.clock := implicit_clock
+        l.reset := implicit_reset
+      }}
+    }
+    val tlbus = system.asInstanceOf[BaseSubsystem].locateTLBusWrapper(system.prciParams.slaveWhere)
+    val baseAddress = system.prciParams.baseAddress
+    val clockDivider  = system.prci_ctrl_domain { LazyModule(new TLClockDivider (baseAddress + 0x20000, tlbus.beatBytes)) }
+    val clockSelector = system.prci_ctrl_domain { LazyModule(new TLClockSelector(baseAddress + 0x30000, tlbus.beatBytes)) }
+    val pllCtrl       = system.prci_ctrl_domain { LazyModule(new FakePLLCtrl    (baseAddress + 0x40000, tlbus.beatBytes)) }
+
+    tlbus.toVariableWidthSlave(Some("clock-div-ctrl")) { clockDivider.tlNode := TLBuffer() }
+    tlbus.toVariableWidthSlave(Some("clock-sel-ctrl")) { clockSelector.tlNode := TLBuffer() }
+    tlbus.toVariableWidthSlave(Some("pll-ctrl")) { pllCtrl.tlNode := TLBuffer() }
+
+    system.allClockGroupsNode := clockDivider.clockNode := clockSelector.clockNode
+
+    // Connect all other requested clocks
+    val slowClockSource = ClockSourceNode(Seq(ClockSourceParameters()))
+    val pllClockSource = ClockSourceNode(Seq(ClockSourceParameters()))
+
+    // The order of the connections to clockSelector.clockNode configures the inputs
+    // of the clockSelector's clockMux. Default to using the slowClockSource,
+    // software should enable the PLL, then switch to the pllClockSource
+    clockSelector.clockNode := slowClockSource
+    clockSelector.clockNode := pllClockSource
+
+    val pllCtrlSink = BundleBridgeSink[FakePLLCtrlBundle]()
+    pllCtrlSink := pllCtrl.ctrlNode
+
+    InModuleBody {
+      val clock_wire = Wire(Input(new ClockWithFreq(80)))
+      val reset_wire = Wire(Input(AsyncReset()))
+      val (clock_io, clockIOCell) = IOCell.generateIOFromSignal(clock_wire, "clock", p(IOCellKey))
+      val (reset_io, resetIOCell) = IOCell.generateIOFromSignal(reset_wire, "reset", p(IOCellKey))
+
+      slowClockSource.out.unzip._1.map { o =>
+        o.clock := clock_wire.clock
+        o.reset := reset_wire
+      }
+
+      // For a real chip you should replace this ClockSourceAtFreqFromPlusArg
+      // with a blackbox of whatever PLL is being integrated
+      val fake_pll = Module(new ClockSourceAtFreqFromPlusArg("pll_freq_mhz"))
+      fake_pll.io.power := pllCtrlSink.in(0)._1.power
+      fake_pll.io.gate := pllCtrlSink.in(0)._1.gate
+
+      pllClockSource.out.unzip._1.map { o =>
+        o.clock := fake_pll.io.clk
+        o.reset := reset_wire
+      }
+
+      (Seq(clock_io, reset_io), clockIOCell ++ resetIOCell)
+    }
+  }
+})