Merge pull request #2232 from ucb-bar/ext-gcd-clk

Add option for externally clocked GCD peripheral example

Author: jerryz123

generators/chipyard/src/main/scala/config/AbstractConfig.scala

@@ -61,7 +61,7 @@ class AbstractConfig extends Config(
   new chipyard.iobinders.WithNICIOPunchthrough ++
   new chipyard.iobinders.WithTraceIOPunchthrough ++
   new chipyard.iobinders.WithUARTTSIPunchthrough ++
-  new chipyard.iobinders.WithGCDBusyPunchthrough ++
+  new chipyard.iobinders.WithGCDIOPunchthrough ++
   new chipyard.iobinders.WithNMITiedOff ++
   new chipyard.iobinders.WithOffchipBusSel ++
 

generators/chipyard/src/main/scala/config/MMIOAcceleratorConfigs.scala

@@ -32,6 +32,11 @@ class GCDHLSRocketConfig extends Config(
   new freechips.rocketchip.rocket.WithNHugeCores(1) ++
   new chipyard.config.AbstractConfig)
 
+class GCDExternallyClockedRocketConfig extends Config(
+  new chipyard.example.WithGCD(externallyClocked=true)++
+  new freechips.rocketchip.rocket.WithNHugeCores(1) ++
+  new chipyard.config.AbstractConfig)
+
 // DOC include start: InitZeroRocketConfig
 class InitZeroRocketConfig extends Config(
   new chipyard.example.WithInitZero(0x88000000L, 0x1000L) ++   // add InitZero

generators/chipyard/src/main/scala/example/GCD.scala

@@ -12,15 +12,19 @@ import org.chipsalliance.cde.config.{Parameters, Field, Config}
 import freechips.rocketchip.diplomacy._
 import freechips.rocketchip.regmapper.{HasRegMap, RegField}
 import freechips.rocketchip.tilelink._
-import freechips.rocketchip.util.UIntIsOneOf
+import freechips.rocketchip.util._
 
 // DOC include start: GCD params
 case class GCDParams(
   address: BigInt = 0x4000,
   width: Int = 32,
   useAXI4: Boolean = false,
   useBlackBox: Boolean = true,
-  useHLS: Boolean = false)
+  useHLS: Boolean = false,
+  externallyClocked: Boolean = false
+) {
+  require(!(useAXI4 && useHLS))
+}
 // DOC include end: GCD params
 
 // DOC include start: GCD key
@@ -287,48 +291,104 @@ trait CanHavePeripheryGCD { this: BaseSubsystem =>
   private val pbus = locateTLBusWrapper(PBUS)
 
   // Only build if we are using the TL (nonAXI4) version
-  val gcd_busy = p(GCDKey) match {
+  val (gcd_busy, gcd_clock) = p(GCDKey) match {
     case Some(params) => {
+
+      // If externallyClocked is true, create an input port for the GCD clock.
+      // This clock is distinct from the pbus clock or other internal clocks.
+      // It's defined within InModuleBody as it's a hardware port.
+      val gcd_clock = Option.when(params.externallyClocked) {
+        InModuleBody { IO(Input(Clock())).suggestName("gcd_clock_in") }
+      }
+      // Define the clock source node for the GCD module.
+      val gcdClockNode = if (params.externallyClocked) {
+        // If externally clocked, create a new ClockSourceNode. 
+        // This node acts as the root of the GCD's independent clock domain.
+        val gcdSourceClockNode = ClockSourceNode(Seq(ClockSourceParameters()))
+        InModuleBody {
+          // Connect the ClockSourceNode's output clock to the external gcd_clock input.
+          gcdSourceClockNode.out(0)._1.clock := gcd_clock.get
+          // The reset signal for the GCD's clock domain must be synchronous to the gcd_clock.
+          // ResetCatchAndSync synchronizes the asynchronous pbus reset to the gcd_clock domain.
+          gcdSourceClockNode.out(0)._1.reset := ResetCatchAndSync(gcd_clock.get, pbus.module.reset.asBool)
+        }
+        gcdSourceClockNode
+      } else {
+        // If not externally clocked, the GCD runs on the same clock as the pbus.
+        pbus.fixedClockNode
+      }
+      // Define the type of clock crossing required between the pbus and the GCD module.
+      val gcdCrossing = if (params.externallyClocked) {
+        // If the GCD has its own clock, an AsynchronousCrossing is necessary
+        // to safely transfer data between the pbus clock domain and the GCD clock domain.
+        AsynchronousCrossing()
+      } else {
+        // If the GCD uses the pbus clock, a SynchronousCrossing can be used.
+        SynchronousCrossing()
+      }
+
+      // Instantiate the GCD module (either TL, AXI4, or HLS variant)
       val gcd = if (params.useAXI4) {
         val gcd = LazyModule(new GCDAXI4(params, pbus.beatBytes)(p))
-        gcd.clockNode := pbus.fixedClockNode
+        // Connect the GCD's clock input to our determined gcdClockNode.
+        gcd.clockNode := gcdClockNode
+        // Couple the GCD to the pbus, inserting the necessary clock crossing logic.
         pbus.coupleTo(portName) {
-          gcd.node :=
+          // AXI4InwardClockCrossingHelper handles crossing details for AXI4.
+          AXI4InwardClockCrossingHelper("gcd_crossing", gcd, gcd.node)(gcdCrossing) :=
           AXI4Buffer () :=
           TLToAXI4 () :=
-          // toVariableWidthSlave doesn't use holdFirstDeny, which TLToAXI4() needsx
+          // toVariableWidthSlave doesn't use holdFirstDeny, which TLToAXI4() needs
           TLFragmenter(pbus.beatBytes, pbus.blockBytes, holdFirstDeny = true) := _
         }
         gcd
       } else if (params.useHLS) {
         val gcd = LazyModule(new HLSGCDAccel(params, pbus.beatBytes)(p))
-        gcd.clockNode := pbus.fixedClockNode
-        pbus.coupleTo(portName) { gcd.node := TLFragmenter(pbus.beatBytes, pbus.blockBytes) := _ }
+        // Connect the GCD's clock input to our determined gcdClockNode.
+        gcd.clockNode := gcdClockNode
+        // Couple the GCD to the pbus, inserting the necessary clock crossing logic.
+        pbus.coupleTo(portName) {
+          // TLInwardClockCrossingHelper handles crossing details for TileLink.
+          TLInwardClockCrossingHelper("gcd_crossing", gcd, gcd.node)(gcdCrossing) :=
+          TLFragmenter(pbus.beatBytes, pbus.blockBytes) := _
+        }
         gcd
       } else {
         val gcd = LazyModule(new GCDTL(params, pbus.beatBytes)(p))
-        gcd.clockNode := pbus.fixedClockNode
-        pbus.coupleTo(portName) { gcd.node := TLFragmenter(pbus.beatBytes, pbus.blockBytes) := _ }
+        // Connect the GCD's clock input to our determined gcdClockNode.
+        gcd.clockNode := gcdClockNode
+        // Couple the GCD to the pbus, inserting the necessary clock crossing logic.
+        pbus.coupleTo(portName) {
+          // TLInwardClockCrossingHelper handles crossing details for TileLink.
+          TLInwardClockCrossingHelper("gcd_crossing", gcd, gcd.node)(gcdCrossing) :=
+          TLFragmenter(pbus.beatBytes, pbus.blockBytes) := _
+        }
         gcd
       }
+      // Expose the GCD's busy signal.
       val gcd_busy = InModuleBody {
         val busy = IO(Output(Bool())).suggestName("gcd_busy")
         busy := gcd.module.io.gcd_busy
         busy
       }
-      Some(gcd_busy)
+      // Return the busy signal (always needed if GCD exists) and the optional external clock input.
+      // The Option[Clock] allows the IOBinder (WithGCDIOPunchthrough) to conditionally
+      // create the top-level clock input only when `externallyClocked` is true.
+      // The busy signal is Some(busy) because the entire GCD peripheral itself is optional based on GCDKey.
+      (Some(gcd_busy), gcd_clock)
     }
-    case None => None
+    // If GCDKey is None, the GCD peripheral is not instantiated. Return None for both signals.
+    case None => (None, None)
   }
 }
 // DOC include end: GCD lazy trait
 
 // DOC include start: GCD config fragment
-class WithGCD(useAXI4: Boolean = false, useBlackBox: Boolean = false, useHLS: Boolean = false) extends Config((site, here, up) => {
+class WithGCD(useAXI4: Boolean = false, useBlackBox: Boolean = false, useHLS: Boolean = false, externallyClocked: Boolean = false) extends Config((site, here, up) => {
   case GCDKey => {
     // useHLS cannot be used with useAXI4 and useBlackBox
-    assert(!useHLS || (useHLS && !useAXI4 && !useBlackBox)) 
-    Some(GCDParams(useAXI4 = useAXI4, useBlackBox = useBlackBox, useHLS = useHLS))
+    assert(!useHLS || (useHLS && !useAXI4 && !useBlackBox))
+    Some(GCDParams(useAXI4 = useAXI4, useBlackBox = useBlackBox, useHLS = useHLS, externallyClocked = externallyClocked))
   }
 })
 // DOC include end: GCD config fragment

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

@@ -560,12 +560,42 @@ class WithNMITiedOff extends ComposeIOBinder({
   }
 })
 
-class WithGCDBusyPunchthrough extends OverrideIOBinder({
-  (system: CanHavePeripheryGCD) => system.gcd_busy.map { busy =>
-    val io_gcd_busy = IO(Output(Bool()))
-    io_gcd_busy := busy
-    (Seq(GCDBusyPort(() => io_gcd_busy)), Nil)
-  }.getOrElse((Nil, Nil))
+// This IOBinder connects the signals exposed by the CanHavePeripheryGCD trait
+// to the top-level ports of the chip. It handles both the 'busy' signal and
+// the optional external clock signal.
+class WithGCDIOPunchthrough extends OverrideIOBinder({
+  // The input `system` is expected to mix-in CanHavePeripheryGCD.
+  (system: CanHavePeripheryGCD) => {
+    // `system.gcd_busy` is an Option[Bool] coming from CanHavePeripheryGCD.
+    // It is Some[Bool] if the GCD peripheral is present (GCDKey is Some), and None otherwise.
+    val gcdBusyPort = system.gcd_busy.map { busy =>
+      // If `system.gcd_busy` is Some, create a ChipTop port named "gcd_busy".
+      val io_gcd_busy = IO(Output(Bool())).suggestName("gcd_busy")
+      // Connect the internal busy signal from the GCD module to this ChipTop port.
+      io_gcd_busy := busy
+      // Create a GCDBusyPort entry, (primarily for bookkeeping/reflection in the TestHarness)
+      GCDBusyPort(() => io_gcd_busy)
+    }.toSeq // Convert Option[GCDBusyPort] to Seq[GCDBusyPort] (empty if None)
+
+    // `system.gcd_clock` is an Option[Clock] coming from CanHavePeripheryGCD.
+    // It is Some[Clock] if the GCD peripheral is present AND params.externallyClocked was true.
+    // It is None if the GCD is not present OR if it's configured to use an internal clock.
+    val gcdClockPort = system.gcd_clock.map { clock =>
+      // If `system.gcd_clock` is Some, create a ChipTop port named "gcd_clock_in".
+      // This port will be driven by the external clock source in the test harness or board.
+      val io_gcd_clock = IO(Input(Clock())).suggestName("gcd_clock_in")
+      // Connect this ChipTop input clock port to the internal clock input wire
+      // defined within CanHavePeripheryGCD. 
+      // This is what ultimately drives the GCD's ClockSourceNode.
+      clock := io_gcd_clock
+      // Create a ClockPort entry for bookkeeping/reflection.
+      ClockPort(() => io_gcd_clock, freqMHz = 60.0) // freqMHz used in sims & in the TestHarness
+    }.toSeq // Convert Option[ClockPort] to Seq[ClockPort] (empty if None)
+
+    // Return the sequence of created top-level ports (busy port, and optionally clock port).
+    // No IOCells are generated here.
+    (gcdBusyPort ++ gcdClockPort, Nil)
+  }
 })
 
 class WithOffchipBusSel extends OverrideIOBinder({