subsystem: more bus topology comments

src/main/scala/subsystem/BusTopology.scala

@@ -9,6 +9,7 @@ import freechips.rocketchip.util.Location
 
 // These fields control parameters of the five traditional tilelink bus wrappers.
 //   They continue to exist for backwards compatiblity reasons but could eventually be retired.
+
 case object SystemBusKey extends Field[SystemBusParams]
 case object FrontBusKey extends Field[FrontBusParams]
 case object PeripheryBusKey extends Field[PeripheryBusParams]
@@ -20,6 +21,7 @@ case object MemoryBusKey extends Field[MemoryBusParams]
 //   While they represent some tradtionally popular locations to attach devices,
 //   there is no guarantee that they will exist in subsystems with
 //   dynamically-configured topologies.
+
 class TLBusWrapperLocation(name: String) extends Location[TLBusWrapper](name)
 case object SBUS extends TLBusWrapperLocation("subsystem_sbus")
 case object PBUS extends TLBusWrapperLocation("subsystem_pbus")
@@ -28,27 +30,31 @@ case object MBUS extends TLBusWrapperLocation("subsystem_mbus")
 case object CBUS extends TLBusWrapperLocation("subsystem_cbus")
 case object L2   extends TLBusWrapperLocation("subsystem_l2")
 
-// This case class parameterizes the subsystem in terms of the optional clock-crossings
-//   which are insertable between some of the five traditional tilelink bus wrappers.
-//   They continue to exist for backwards compatiblity reasons but could eventually be retired.
+/** Parameterizes the subsystem in terms of optional clock-crossings
+  *   that are insertable between some of the five traditional tilelink bus wrappers.
+  *   This class exists for backwards compatiblity reasons but could eventually be retired
+  *   in favor of manually filling in crossing types within each custom TLBusWrapperTopology.
+  */
 case class SubsystemCrossingParams(
   sbusToCbusXType: ClockCrossingType = NoCrossing,
   cbusToPbusXType: ClockCrossingType = SynchronousCrossing(),
   fbusToSbusXType: ClockCrossingType = SynchronousCrossing()
 )
 
-// This case class provides a backwards-compatibility parameterization of a subsystem
-//  bus topology that contains the five traditional tilelink bus wrappers.
+// Taken together these case classes provide a backwards-compatibility parameterization
+//  of a bus topology that contains the five traditional tilelink bus wrappers.
 //  Users desiring a different topology are free to define a similar subclass,
 //  or just populate an instance of TLBusWrapperTopology via some other mechanism.
 
+/** Parameterization of a topology containing a single bus named "subsystem_sbus". */
 case class JustOneBusTopologyParams(
   sbus: SystemBusParams,
 ) extends TLBusWrapperTopology(
   instantiations = List((SBUS, sbus)),
   connections = Nil
 )
 
+/** Parameterization of a topology containing three additional, optional buses for attaching MMIO devices. */
 case class HierarchicalBusTopologyParams(
   pbus: PeripheryBusParams,
   fbus: FrontBusParams,
@@ -65,6 +71,7 @@ case class HierarchicalBusTopologyParams(
     (FBUS, SBUS, TLBusWrapperConnection.crossFrom(xTypes.fbusToSbusXType)))
 )
 
+/** Parameterization of a topology containing a banked coherence manager and a bus for attaching memory devices. */
 case class CoherentBusTopologyParams(
   sbus: SystemBusParams, // TODO remove this after better width propagation
   mbus: MemoryBusParams,