add some more comments to describe the new device system

groundtest/src/main/scala/BusMasterTest.scala

@@ -8,6 +8,13 @@ import uncore.Util._
 import junctions.HasAddrMapParameters
 import cde.Parameters
 
+/**
+ * An example bus mastering devices that writes some preset data to memory.
+ * When it receives an MMIO put request, it starts writing out the data.
+ * When it receives an MMIO get request, it responds with the progress of
+ * the write. A grant data of 1 means it is still writing, grant data 0 
+ * means it has finished.
+ */
 class ExampleBusMaster(implicit val p: Parameters) extends Module
     with HasAddrMapParameters
     with HasTileLinkParameters {

src/main/scala/Devices.scala

@@ -9,14 +9,35 @@ case object ExtraTopPorts extends Field[Parameters => Bundle]
 case object ExtraDevices extends Field[Seq[Device]]
 
 abstract class Device {
+  /** Does this device have an MMIO port? */
   def hasMMIOPort: Boolean
+  /** Does this device have a client port? */
   def hasClientPort: Boolean
+  /**
+   * This function elaborates the hardware for the device and connects
+   * it to the mmio port, client port, and extra top-level ports.
+   *
+   * @param mmioPort The port from the MMIO network that goes to this device.
+   *  If hasMMIOPort is false, this will be None
+   *
+   * @param clientPort The client port provided for this device to make
+   *  requests to the memory system. If hasClientPort is false, this will be None
+   */
   def builder(
     mmioPort: Option[ClientUncachedTileLinkIO],
     clientPort: Option[ClientUncachedTileLinkIO],
     extra: Bundle, p: Parameters): Unit
+  /**
+   * The entry that will be placed into the address map for this device.
+   * If hasMMIOPort is false, you do not need to override this
+   */
   def addrMapEntry: AddrMapEntry =
     throw new UnsupportedOperationException("no addrMapEntry defined")
+
+  /**
+   * Create the config string entry for this device that goes into the
+   * Boot ROM. You generally won't need to override this
+   */
   def makeConfigString(region: MemRegion): String = {
     s"${addrMapEntry.name} {\n" +
     s"  addr 0x${region.start.toString(16)};\n" +

src/main/scala/RocketChip.scala

@@ -242,8 +242,8 @@ class Periphery(implicit val p: Parameters) extends Module
       } else None
 
       val buildParams = p.alterPartial({
-        case InnerTLId => "L2toMMIO"
+        case InnerTLId => "L2toMMIO" // Device MMIO port
-        case OuterTLId => "L1toL2"
+        case OuterTLId => "L1toL2"   // Device client port
       })
 
       device.builder(mmioPort, clientPort, io.extra, buildParams)