Merge pull request #235 from ucb-bar/howie-docs

Updates and additions to documentation

generators/example/src/main/scala/ConfigMixins.scala

@@ -70,10 +70,12 @@ class WithDTMTop extends Config((site, here, up) => {
 /**
  * Class to specify a top level BOOM and/or Rocket system with PWM
  */
+// DOC include start: WithPWMTop
 class WithPWMTop extends Config((site, here, up) => {
   case BuildTop => (clock: Clock, reset: Bool, p: Parameters) =>
     Module(LazyModule(new TopWithPWMTL()(p)).module)
 })
+// DOC include end: WithPWMTop
 
 /**
  * Class to specify a top level BOOM and/or Rocket system with a PWM AXI4
@@ -157,3 +159,14 @@ class WithMultiRoCCHwacha(harts: Int*) extends Config((site, here, up) => {
     }
   }
 })
+
+// DOC include start: WithInitZero
+class WithInitZero(base: BigInt, size: BigInt) extends Config((site, here, up) => {
+  case InitZeroKey => InitZeroConfig(base, size)
+})
+
+class WithInitZeroTop extends Config((site, here, up) => {
+  case BuildTop => (clock: Clock, reset: Bool, p: Parameters) =>
+    Module(LazyModule(new TopWithInitZero()(p)).module)
+})
+// DOC include end: WithInitZero

generators/example/src/main/scala/InitZero.scala

@@ -0,0 +1,69 @@
+package example
+
+import chisel3._
+import chisel3.util._
+import freechips.rocketchip.subsystem.{BaseSubsystem, CacheBlockBytes}
+import freechips.rocketchip.config.{Parameters, Field}
+import freechips.rocketchip.diplomacy.{LazyModule, LazyModuleImp, IdRange}
+import testchipip.TLHelper
+
+case class InitZeroConfig(base: BigInt, size: BigInt)
+case object InitZeroKey extends Field[InitZeroConfig]
+
+class InitZero(implicit p: Parameters) extends LazyModule {
+  val node = TLHelper.makeClientNode(
+    name = "init-zero", sourceId = IdRange(0, 1))
+
+  lazy val module = new InitZeroModuleImp(this)
+}
+
+class InitZeroModuleImp(outer: InitZero) extends LazyModuleImp(outer) {
+  val config = p(InitZeroKey)
+
+  val (mem, edge) = outer.node.out(0)
+  val addrBits = edge.bundle.addressBits
+  val blockBytes = p(CacheBlockBytes)
+
+  require(config.size % blockBytes == 0)
+
+  val s_init :: s_write :: s_resp :: s_done :: Nil = Enum(4)
+  val state = RegInit(s_init)
+
+  val addr = Reg(UInt(addrBits.W))
+  val bytesLeft = Reg(UInt(log2Ceil(config.size+1).W))
+
+  mem.a.valid := state === s_write
+  mem.a.bits := edge.Put(
+    fromSource = 0.U,
+    toAddress = addr,
+    lgSize = log2Ceil(blockBytes).U,
+    data = 0.U)._2
+  mem.d.ready := state === s_resp
+
+  when (state === s_init) {
+    addr := config.base.U
+    bytesLeft := config.size.U
+    state := s_write
+  }
+
+  when (edge.done(mem.a)) {
+    addr := addr + blockBytes.U
+    bytesLeft := bytesLeft - blockBytes.U
+    state := s_resp
+  }
+
+  when (mem.d.fire()) {
+    state := Mux(bytesLeft === 0.U, s_done, s_write)
+  }
+}
+
+trait HasPeripheryInitZero { this: BaseSubsystem =>
+  implicit val p: Parameters
+
+  val initZero = LazyModule(new InitZero()(p))
+  fbus.fromPort(Some("init-zero"))() := initZero.node
+}
+
+trait HasPeripheryInitZeroModuleImp extends LazyModuleImp {
+  // Don't need anything here
+}

generators/example/src/main/scala/NodeTypes.scala

@@ -0,0 +1,128 @@
+package example
+
+import freechips.rocketchip.config.Parameters
+import freechips.rocketchip.diplomacy._
+import freechips.rocketchip.tilelink._
+import testchipip.TLHelper
+
+// These modules are not meant to be synthesized.
+// They are used as examples in the documentation and are only here
+// to check that they compile.
+
+// DOC include start: MyClient
+class MyClient(implicit p: Parameters) extends LazyModule {
+  val node = TLHelper.makeClientNode(TLClientParameters(
+    name = "my-client",
+    sourceId = IdRange(0, 4),
+    requestFifo = true,
+    visibility = Seq(AddressSet(0x10000, 0xffff))))
+
+  lazy val module = new LazyModuleImp(this) {
+    val (tl, edge) = node.out(0)
+
+    // Rest of code here
+  }
+}
+// DOC include end: MyClient
+
+// DOC include start: MyManager
+class MyManager(implicit p: Parameters) extends LazyModule {
+  val device = new SimpleDevice("my-device", Seq("tutorial,my-device0"))
+  val beatBytes = 8
+  val node = TLHelper.makeManagerNode(beatBytes, TLManagerParameters(
+    address = Seq(AddressSet(0x20000, 0xfff)),
+    resources = device.reg,
+    regionType = RegionType.UNCACHED,
+    executable = true,
+    supportsArithmetic = TransferSizes(1, beatBytes),
+    supportsLogical = TransferSizes(1, beatBytes),
+    supportsGet = TransferSizes(1, beatBytes),
+    supportsPutFull = TransferSizes(1, beatBytes),
+    supportsPutPartial = TransferSizes(1, beatBytes),
+    supportsHint = TransferSizes(1, beatBytes),
+    fifoId = Some(0)))
+
+  lazy val module = new LazyModuleImp(this) {
+    val (tl, edge) = node.in(0)
+  }
+}
+// DOC include end: MyManager
+
+// DOC include start: MyClient1+MyClient2
+class MyClient1(implicit p: Parameters) extends LazyModule {
+  val node = TLHelper.makeClientNode("my-client1", IdRange(0, 1))
+
+  lazy val module = new LazyModuleImp(this) {
+    // ...
+  }
+}
+
+class MyClient2(implicit p: Parameters) extends LazyModule {
+  val node = TLHelper.makeClientNode("my-client2", IdRange(0, 1))
+
+  lazy val module = new LazyModuleImp(this) {
+    // ...
+  }
+}
+// DOC include end: MyClient1+MyClient2
+
+// DOC include start: MyClientGroup
+class MyClientGroup(implicit p: Parameters) extends LazyModule {
+  val client1 = LazyModule(new MyClient1)
+  val client2 = LazyModule(new MyClient2)
+  val node = TLIdentityNode()
+
+  node := client1.node
+  node := client2.node
+
+  lazy val module = new LazyModuleImp(this) {
+    // Nothing to do here
+  }
+}
+// DOC include end: MyClientGroup
+
+// DOC include start: MyManagerGroup
+class MyManager1(beatBytes: Int)(implicit p: Parameters) extends LazyModule {
+  val node = TLHelper.makeManagerNode(beatBytes, TLManagerParameters(
+    address = Seq(AddressSet(0x0, 0xfff))))
+
+  lazy val module = new LazyModuleImp(this) {
+    // ...
+  }
+}
+
+class MyManager2(beatBytes: Int)(implicit p: Parameters) extends LazyModule {
+  val node = TLHelper.makeManagerNode(beatBytes, TLManagerParameters(
+    address = Seq(AddressSet(0x1000, 0xfff))))
+
+  lazy val module = new LazyModuleImp(this) {
+    // ...
+  }
+}
+
+class MyManagerGroup(beatBytes: Int)(implicit p: Parameters) extends LazyModule {
+  val man1 = LazyModule(new MyManager1(beatBytes))
+  val man2 = LazyModule(new MyManager2(beatBytes))
+  val node = TLIdentityNode()
+
+  man1.node := node
+  man2.node := node
+
+  lazy val module = new LazyModuleImp(this) {
+    // Nothing to do here
+  }
+}
+// DOC include end: MyManagerGroup
+
+// DOC include start: MyClientManagerComplex
+class MyClientManagerComplex(implicit p: Parameters) extends LazyModule {
+  val client = LazyModule(new MyClientGroup)
+  val manager = LazyModule(new MyManagerGroup(8))
+
+  manager.node :=* client.node
+
+  lazy val module = new LazyModuleImp(this) {
+    // Nothing to do here
+  }
+}
+// DOC include end: MyClientManagerComplex

generators/example/src/main/scala/PWM.scala

@@ -10,6 +10,7 @@ import freechips.rocketchip.regmapper.{HasRegMap, RegField}
 import freechips.rocketchip.tilelink._
 import freechips.rocketchip.util.UIntIsOneOf
 
+// DOC include start: PWM generic traits
 case class PWMParams(address: BigInt, beatBytes: Int)
 
 class PWMBase(w: Int) extends Module {
@@ -64,19 +65,23 @@ trait PWMModule extends HasRegMap {
     0x08 -> Seq(
       RegField(1, enable)))
 }
+// DOC include end: PWM generic traits
 
+// DOC include start: PWMTL
 class PWMTL(c: PWMParams)(implicit p: Parameters)
   extends TLRegisterRouter(
     c.address, "pwm", Seq("ucbbar,pwm"),
     beatBytes = c.beatBytes)(
       new TLRegBundle(c, _) with PWMBundle)(
       new TLRegModule(c, _, _) with PWMModule)
+// DOC include end: PWMTL
 
 class PWMAXI4(c: PWMParams)(implicit p: Parameters)
   extends AXI4RegisterRouter(c.address, beatBytes = c.beatBytes)(
       new AXI4RegBundle(c, _) with PWMBundle)(
       new AXI4RegModule(c, _, _) with PWMModule)
 
+// DOC include start: HasPeripheryPWMTL
 trait HasPeripheryPWMTL { this: BaseSubsystem =>
   implicit val p: Parameters
 
@@ -88,7 +93,9 @@ trait HasPeripheryPWMTL { this: BaseSubsystem =>
 
   pbus.toVariableWidthSlave(Some(portName)) { pwm.node }
 }
+// DOC include end: HasPeripheryPWMTL
 
+// DOC include start: HasPeripheryPWMTLModuleImp
 trait HasPeripheryPWMTLModuleImp extends LazyModuleImp {
   implicit val p: Parameters
   val outer: HasPeripheryPWMTL
@@ -97,6 +104,7 @@ trait HasPeripheryPWMTLModuleImp extends LazyModuleImp {
 
   pwmout := outer.pwm.module.io.pwmout
 }
+// DOC include end: HasPeripheryPWMTLModuleImp
 
 trait HasPeripheryPWMAXI4 { this: BaseSubsystem =>
   implicit val p: Parameters

generators/example/src/main/scala/RegisterNodeExample.scala

@@ -0,0 +1,181 @@
+// DOC include start: MyDeviceController
+
+import chisel3._
+import chisel3.util._
+import freechips.rocketchip.config.Parameters
+import freechips.rocketchip.diplomacy._
+import freechips.rocketchip.regmapper._
+import freechips.rocketchip.tilelink.TLRegisterNode
+
+class MyDeviceController(implicit p: Parameters) extends LazyModule {
+  val device = new SimpleDevice("my-device", Seq("tutorial,my-device0"))
+  val node = TLRegisterNode(
+    address = Seq(AddressSet(0x10028000, 0xfff)),
+    device = device,
+    beatBytes = 8,
+    concurrency = 1)
+
+  lazy val module = new LazyModuleImp(this) {
+    val bigReg = RegInit(0.U(64.W))
+    val mediumReg = RegInit(0.U(32.W))
+    val smallReg = RegInit(0.U(16.W))
+
+    val tinyReg0 = RegInit(0.U(4.W))
+    val tinyReg1 = RegInit(0.U(4.W))
+
+    node.regmap(
+      0x00 -> Seq(RegField(64, bigReg)),
+      0x08 -> Seq(RegField(32, mediumReg)),
+      0x0C -> Seq(RegField(16, smallReg)),
+      0x0E -> Seq(
+        RegField(4, tinyReg0),
+        RegField(4, tinyReg1)))
+  }
+}
+
+// DOC include end: MyDeviceController
+
+// DOC include start: MyAXI4DeviceController
+import freechips.rocketchip.amba.axi4.AXI4RegisterNode
+
+class MyAXI4DeviceController(implicit p: Parameters) extends LazyModule {
+  val node = AXI4RegisterNode(
+    address = AddressSet(0x10029000, 0xfff),
+    beatBytes = 8,
+    concurrency = 1)
+
+  lazy val module = new LazyModuleImp(this) {
+    val bigReg = RegInit(0.U(64.W))
+    val mediumReg = RegInit(0.U(32.W))
+    val smallReg = RegInit(0.U(16.W))
+
+    val tinyReg0 = RegInit(0.U(4.W))
+    val tinyReg1 = RegInit(0.U(4.W))
+
+    node.regmap(
+      0x00 -> Seq(RegField(64, bigReg)),
+      0x08 -> Seq(RegField(32, mediumReg)),
+      0x0C -> Seq(RegField(16, smallReg)),
+      0x0E -> Seq(
+        RegField(4, tinyReg0),
+        RegField(4, tinyReg1)))
+  }
+}
+// DOC include end: MyAXI4DeviceController
+
+class MyQueueRegisters(implicit p: Parameters) extends LazyModule {
+  val device = new SimpleDevice("my-queue", Seq("tutorial,my-queue0"))
+  val node = TLRegisterNode(
+    address = Seq(AddressSet(0x1002A000, 0xfff)),
+    device = device,
+    beatBytes = 8,
+    concurrency = 1)
+
+  lazy val module = new LazyModuleImp(this) {
+// DOC include start: MyQueueRegisters
+    // 4-entry 64-bit queue
+    val queue = Module(new Queue(UInt(64.W), 4))
+
+    node.regmap(
+      0x00 -> Seq(RegField(64, queue.io.deq, queue.io.enq)))
+// DOC include end: MyQueueRegisters
+  }
+}
+
+class MySeparateQueueRegisters(implicit p: Parameters) extends LazyModule {
+  val device = new SimpleDevice("my-queue", Seq("tutorial,my-queue1"))
+  val node = TLRegisterNode(
+    address = Seq(AddressSet(0x1002B000, 0xfff)),
+    device = device,
+    beatBytes = 8,
+    concurrency = 1)
+
+  lazy val module = new LazyModuleImp(this) {
+    val queue = Module(new Queue(UInt(64.W), 4))
+
+// DOC include start: MySeparateQueueRegisters
+    node.regmap(
+      0x00 -> Seq(RegField.r(64, queue.io.deq)),
+      0x08 -> Seq(RegField.w(64, queue.io.enq)))
+// DOC include end: MySeparateQueueRegisters
+  }
+}
+
+class MyCounterRegisters(implicit p: Parameters) extends LazyModule {
+  val device = new SimpleDevice("my-counters", Seq("tutorial,my-counters0"))
+  val node = TLRegisterNode(
+    address = Seq(AddressSet(0x1002C000, 0xfff)),
+    device = device,
+    beatBytes = 8,
+    concurrency = 1)
+
+  lazy val module = new LazyModuleImp(this) {
+// DOC include start: MyCounterRegisters
+    val counter = RegInit(0.U(64.W))
+
+    def readCounter(ready: Bool): (Bool, UInt) = {
+      when (ready) { counter := counter - 1.U }
+      // (ready, bits)
+      (true.B, counter)
+    }
+
+    def writeCounter(valid: Bool, bits: UInt): Bool = {
+      when (valid) { counter := counter + 1.U }
+      // Ignore bits
+      // Return ready
+      true.B
+    }
+
+    node.regmap(
+      0x00 -> Seq(RegField.r(64, readCounter(_))),
+      0x08 -> Seq(RegField.w(64, writeCounter(_, _))))
+// DOC include end: MyCounterRegisters
+  }
+}
+
+class MyCounterReqRespRegisters(implicit p: Parameters) extends LazyModule {
+  val device = new SimpleDevice("my-counters", Seq("tutorial,my-counters1"))
+  val node = TLRegisterNode(
+    address = Seq(AddressSet(0x1002D000, 0xfff)),
+    device = device,
+    beatBytes = 8,
+    concurrency = 1)
+
+  lazy val module = new LazyModuleImp(this) {
+// DOC include start: MyCounterReqRespRegisters
+    val counter = RegInit(0.U(64.W))
+
+    def readCounter(ivalid: Bool, oready: Bool): (Bool, Bool, UInt) = {
+      val responding = RegInit(false.B)
+
+      when (ivalid && !responding) { responding := true.B }
+
+      when (responding && oready) {
+        counter := counter - 1.U
+        responding := false.B
+      }
+
+      // (iready, ovalid, obits)
+      (!responding, responding, counter)
+    }
+
+    def writeCounter(ivalid: Bool, oready: Bool, ibits: UInt): (Bool, Bool) = {
+      val responding = RegInit(false.B)
+
+      when (ivalid && !responding) { responding := true.B }
+
+      when (responding && oready) {
+        counter := counter + 1.U
+        responding := false.B
+      }
+
+      // (iready, ovalid)
+      (!responding, responding)
+    }
+
+    node.regmap(
+      0x00 -> Seq(RegField.r(64, readCounter(_, _))),
+      0x08 -> Seq(RegField.w(64, writeCounter(_, _, _))))
+// DOC include end: MyCounterReqRespRegisters
+  }
+}

generators/example/src/main/scala/RocketConfigs.scala

@@ -39,12 +39,14 @@ class jtagRocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
 
+// DOC include start: PWMRocketConfig
 class PWMRocketConfig extends Config(
   new WithPWMTop ++                                        // use top with tilelink-controlled PWM
   new WithBootROM ++
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+// DOC include end: PWMRocketConfig
 
 class PWMRAXI4ocketConfig extends Config(
   new WithPWMAXI4Top ++                                    // use top with axi4-controlled PWM
@@ -107,3 +109,13 @@ class Sha3RocketConfig extends Config(
   new freechips.rocketchip.subsystem.WithInclusiveCache ++
   new freechips.rocketchip.subsystem.WithNBigCores(1) ++
   new freechips.rocketchip.system.BaseConfig)
+
+// DOC include start: InitZeroRocketConfig
+class InitZeroRocketConfig extends Config(
+  new WithInitZero(0x88000000L, 0x1000L) ++
+  new WithInitZeroTop ++
+  new WithBootROM ++
+  new freechips.rocketchip.subsystem.WithInclusiveCache ++
+  new freechips.rocketchip.subsystem.WithNBigCores(1) ++
+  new freechips.rocketchip.system.BaseConfig)
+// DOC include end: InitZeroRocketConfig

generators/example/src/main/scala/Top.scala

@@ -30,6 +30,7 @@ class TopModule[+L <: Top](l: L) extends SystemModule(l)
   with DontTouch
 
 //---------------------------------------------------------------------------------------------------------
+// DOC include start: TopWithPWMTL
 
 class TopWithPWMTL(implicit p: Parameters) extends Top
   with HasPeripheryPWMTL {
@@ -39,6 +40,7 @@ class TopWithPWMTL(implicit p: Parameters) extends Top
 class TopWithPWMTLModule(l: TopWithPWMTL) extends TopModule(l)
   with HasPeripheryPWMTLModuleImp
 
+// DOC include end: TopWithPWMTL
 //---------------------------------------------------------------------------------------------------------
 
 class TopWithPWMAXI4(implicit p: Parameters) extends Top
@@ -78,3 +80,14 @@ class TopWithDTM(implicit p: Parameters) extends System
 }
 
 class TopWithDTMModule[+L <: TopWithDTM](l: L) extends SystemModule(l)
+
+//---------------------------------------------------------------------------------------------------------
+// DOC include start: TopWithInitZero
+class TopWithInitZero(implicit p: Parameters) extends Top
+    with HasPeripheryInitZero {
+  override lazy val module = new TopWithInitZeroModuleImp(this)
+}
+
+class TopWithInitZeroModuleImp(l: TopWithInitZero) extends TopModule(l)
+  with HasPeripheryInitZeroModuleImp
+// DOC include end: TopWithInitZero