Add comments to axi4 modules and fix typo.

Minor breaking change: replace PROT_PRIVILEDGED with PROT_PRIVILEGED.

src/main/scala/amba/axi4/AsyncCrossing.scala

@@ -9,6 +9,11 @@ import freechips.rocketchip.tilelink._
 import freechips.rocketchip.subsystem.CrossingWrapper
 import freechips.rocketchip.util._
 
+/**
+  * Source(Master) side for AXI4 crossing clock domain
+  *
+  * @param sync synchronization stages
+  */
 class AXI4AsyncCrossingSource(sync: Option[Int])(implicit p: Parameters) extends LazyModule
 {
   def this(x: Int)(implicit p: Parameters) = this(Some(x))
@@ -29,6 +34,11 @@ class AXI4AsyncCrossingSource(sync: Option[Int])(implicit p: Parameters) extends
   }
 }
 
+/**
+  * Sink(Slave) side for AXI4 crossing clock domain
+  *
+  * @param params async queue params
+  */
 class AXI4AsyncCrossingSink(params: AsyncQueueParams = AsyncQueueParams())(implicit p: Parameters) extends LazyModule
 {
   val node = AXI4AsyncSinkNode(params)
@@ -86,9 +96,15 @@ class AXI4AsyncCrossing(params: AsyncQueueParams = AsyncQueueParams())(implicit
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
+/**
+  * Unit tests for AXI4RAM with Async Crossing
+  * 
+  * topology: AXI4RAM <-< AXI4CrossingSink <-< AXI4CrossingSource <-<
+  *   TLToAXI4 <-< TLRAMModel <-< TLFuzzer
+  */
 class AXI4RAMAsyncCrossing(txns: Int)(implicit p: Parameters) extends LazyModule {
   val model = LazyModule(new TLRAMModel("AsyncCrossing"))
   val fuzz = LazyModule(new TLFuzzer(txns))

src/main/scala/amba/axi4/Buffer.scala

@@ -8,7 +8,11 @@ import freechips.rocketchip.config.Parameters
 import freechips.rocketchip.diplomacy._
 import scala.math.min
 
-// pipe is only used if a queue has depth = 1
+/**
+  * Add buffers to AXI4 channels
+  *
+  * Pipe is only used if a queue has depth = 1
+  */
 class AXI4Buffer(
   aw: BufferParams,
   w:  BufferParams,

src/main/scala/amba/axi4/Bundles.scala

@@ -9,6 +9,9 @@ import freechips.rocketchip.util._
 
 abstract class AXI4BundleBase(params: AXI4BundleParameters) extends GenericParameterizedBundle(params)
 
+/**
+  * Common signals of AW and AR channels of AXI4 protocol
+  */
 abstract class AXI4BundleA(params: AXI4BundleParameters) extends AXI4BundleBase(params)
 {
   val id     = UInt(width = params.idBits)
@@ -32,15 +35,27 @@ abstract class AXI4BundleA(params: AXI4BundleParameters) extends AXI4BundleBase(
   }
 }
 
-// A non-standard bundle that can be both AR and AW
+/**
+  * A non-standard bundle that can be both AR and AW
+  */
 class AXI4BundleARW(params: AXI4BundleParameters) extends AXI4BundleA(params)
 {
   val wen = Bool()
 }
 
+/**
+  * AW channel of AXI4 protocol
+  */
 class AXI4BundleAW(params: AXI4BundleParameters) extends AXI4BundleA(params)
+
+/**
+  * AR channel of AXI4 protocol
+  */
 class AXI4BundleAR(params: AXI4BundleParameters) extends AXI4BundleA(params)
 
+/**
+  * W channel of AXI4 protocol
+  */
 class AXI4BundleW(params: AXI4BundleParameters) extends AXI4BundleBase(params)
 {
   // id ... removed in AXI4
@@ -50,6 +65,9 @@ class AXI4BundleW(params: AXI4BundleParameters) extends AXI4BundleBase(params)
   val user = BundleMap(params.requestFields.filter(_.key.isData))
 }
 
+/**
+  * R channel of AXI4 protocol
+  */
 class AXI4BundleR(params: AXI4BundleParameters) extends AXI4BundleBase(params)
 {
   val id   = UInt(width = params.idBits)
@@ -60,6 +78,9 @@ class AXI4BundleR(params: AXI4BundleParameters) extends AXI4BundleBase(params)
   val last = Bool()
 }
 
+/**
+  * B channel of AXI4 protocol
+  */
 class AXI4BundleB(params: AXI4BundleParameters) extends AXI4BundleBase(params)
 {
   val id   = UInt(width = params.idBits)
@@ -68,6 +89,9 @@ class AXI4BundleB(params: AXI4BundleParameters) extends AXI4BundleBase(params)
   val echo = BundleMap(params.echoFields)
 }
 
+/**
+  * AXI4 protocol bundle
+  */
 class AXI4Bundle(params: AXI4BundleParameters) extends AXI4BundleBase(params)
 {
   val aw = Irrevocable(new AXI4BundleAW(params))

src/main/scala/amba/axi4/Credited.scala

@@ -83,7 +83,7 @@ object AXI4CreditedSink {
   def apply()(implicit p: Parameters): AXI4CreditedSinkNode = apply(CreditedDelay(1, 1))
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class AXI4RAMCreditedCrossing(txns: Int, params: CreditedCrossing)(implicit p: Parameters) extends LazyModule {

src/main/scala/amba/axi4/Delayer.scala

@@ -8,7 +8,11 @@ import freechips.rocketchip.config.Parameters
 import freechips.rocketchip.diplomacy._
 import freechips.rocketchip.tilelink.LFSRNoiseMaker
 
-// q is the probability to delay a request
+/**
+  * Delay AXI4 requests randomly
+  *
+  * @param q the probability to delay a request
+  */
 class AXI4Delayer(q: Double)(implicit p: Parameters) extends LazyModule
 {
   val node = AXI4AdapterNode()

src/main/scala/amba/axi4/Fragmenter.scala

@@ -11,6 +11,9 @@ import freechips.rocketchip.util._
 case object AXI4FragLast extends ControlKey[Bool]("real_last")
 case class AXI4FragLastField() extends SimpleBundleField(AXI4FragLast)(Output(Bool()), false.B)
 
+/**
+  * AXI4 fragmenter. It breaks AXI4 burst transfer to single beat transfers.
+  */
 class AXI4Fragmenter()(implicit p: Parameters) extends LazyModule
 {
   val maxBeats = 1 << AXI4Parameters.lenBits

src/main/scala/amba/axi4/IdIndexer.scala

@@ -31,7 +31,7 @@ class AXI4IdIndexer(idBits: Int)(implicit p: Parameters) extends LazyModule
          aligned   = true,
          maxFlight = Some(0))
       }
-      // Accumluate the names of masters we squish
+      // Accumulate the names of masters we squish
       val names = Array.fill(1 << idBits) { new scala.collection.mutable.HashSet[String]() }
       // Squash the information from original masters into new ID masters
       mp.masters.foreach { m =>

src/main/scala/amba/axi4/Parameters.scala

@@ -9,11 +9,19 @@ import freechips.rocketchip.diplomacy._
 import freechips.rocketchip.util._
 import scala.math.max
 
+/**
+  * Parameters for AXI4 slave
+  *
+  * @param address base address
+  * @param resources device tree resource
+  * @param regionType memory region type
+  * @param executable whether processor can execute from this memory
+  */
 case class AXI4SlaveParameters(
   address:       Seq[AddressSet],
   resources:     Seq[Resource] = Nil,
   regionType:    RegionType.T  = RegionType.GET_EFFECTS,
-  executable:    Boolean       = false, // processor can execute from this memory
+  executable:    Boolean       = false,
   nodePath:      Seq[BaseNode] = Seq(),
   supportsWrite: TransferSizes = TransferSizes.none,
   supportsRead:  TransferSizes = TransferSizes.none,

src/main/scala/amba/axi4/SRAM.scala

@@ -8,8 +8,21 @@ import freechips.rocketchip.diplomacy._
 import freechips.rocketchip.util._
 import freechips.rocketchip.amba._
 
-// Setting wcorrupt=true is not enough to enable the w.user field
-// You must also list AMBACorrupt in your master's requestFields
+/**
+  * AXI4 slave device to provide a RAM storage
+  *
+  * Setting wcorrupt=true is not enough to enable the w.user field
+  * You must also list AMBACorrupt in your master's requestFields
+  *
+  * @param address address range
+  * @param cacheable whether this ram is cacheable
+  * @param executable whether this ram is executable
+  * @param beatBytes number of bytes in each beat
+  * @param devName optional device name
+  * @param errors address ranges where all access should fail
+  * @param wcorrupt enable AMBACorrupt in w.user
+  */
+
 class AXI4RAM(
     address: AddressSet,
     cacheable: Boolean = true,

src/main/scala/amba/axi4/ToTL.scala

@@ -54,8 +54,16 @@ case class AXI4ToTLNode(wcorrupt: Boolean)(implicit valName: ValName) extends Mi
     requestKeys    = (if (wcorrupt) Seq(AMBACorrupt) else Seq()) ++ mp.requestKeys.filter(_ != AMBAProt))
   })
 
-// Setting wcorrupt true is insufficient to enable w.user.corrupt
-// One must additionally provide list it in the AXI4 master's requestFields
+/**
+  * Convert AXI4 master to TileLink.
+  *
+  * You can use this adapter to connect external AXI4 masters to TileLink bus topology.
+  *
+  * Setting wcorrupt=true is insufficient to enable w.user.corrupt.
+  * One must additionally list it in the AXI4 master's requestFields.
+  *
+  * @param wcorrupt enable AMBACorrupt in w.user
+  */
 class AXI4ToTL(wcorrupt: Boolean)(implicit p: Parameters) extends LazyModule
 {
   val node = AXI4ToTLNode(wcorrupt)

src/main/scala/amba/axi4/UserYanker.scala

@@ -9,7 +9,7 @@ import freechips.rocketchip.diplomacy._
 import freechips.rocketchip.util._
 
 /** This adapter prunes all user bit fields of the echo type from request messages,
-  * storing them in queues and echoing them back when matching response messages are recevied.
+  * storing them in queues and echoing them back when matching response messages are received.
   *
   * It also optionally rate limits the number of transactions that can be in flight simultaneously
   * per FIFO domain / A[W|R]ID.

src/main/scala/amba/axi4/Xbar.scala

@@ -10,6 +10,13 @@ import freechips.rocketchip.util._
 import freechips.rocketchip.unittest._
 import freechips.rocketchip.tilelink._
 
+/**
+  * AXI4 Crossbar. It connects multiple AXI4 masters to slaves.
+  *
+  * @param arbitrationPolicy arbitration policy
+  * @param maxFlightPerId maximum inflight transactions per id
+  * @param awQueueDepth queue depth for AW channel
+  */
 class AXI4Xbar(
   arbitrationPolicy: TLArbiter.Policy = TLArbiter.roundRobin,
   maxFlightPerId:    Int = 7,

src/main/scala/amba/axi4/package.scala

@@ -5,6 +5,9 @@ package freechips.rocketchip.amba
 import freechips.rocketchip.diplomacy.{HasClockDomainCrossing, _}
 import freechips.rocketchip.prci.{HasResetDomainCrossing}
 
+/**
+  * Provide bundles, adapters and devices etc for AMBA AXI4 protocol.
+  */
 package object axi4
 {
   type AXI4Node = SimpleNodeHandle[AXI4MasterPortParameters, AXI4SlavePortParameters, AXI4EdgeParameters, AXI4Bundle]

src/main/scala/devices/tilelink/MasterMux.scala

@@ -104,7 +104,7 @@ class MasterMux(uFn: Seq[TLMasterPortParameters] => TLMasterPortParameters)(impl
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLMasterMuxTester(txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/devices/tilelink/TestRAM.scala

@@ -62,7 +62,7 @@ class TLTestRAM(address: AddressSet, executable: Boolean = true, beatBytes: Int
   }
 }
 
-/** Synthesizeable unit testing */
+// Synthesizable unit testing
 import freechips.rocketchip.unittest._
 
 class TLRAMZeroDelay(ramBeatBytes: Int, txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/system/SimAXIMem.scala

@@ -9,7 +9,10 @@ import freechips.rocketchip.config.Parameters
 import freechips.rocketchip.diplomacy._
 import freechips.rocketchip.subsystem.{CanHaveMasterAXI4MMIOPort, CanHaveMasterAXI4MemPort, ExtBus, ExtMem}
 
-/** Memory with AXI port for use in elaboratable test harnesses. */
+/** Memory with AXI port for use in elaboratable test harnesses.
+ * 
+ * Topology: AXIRAM <-< AXI4Buffer <-< AXI4Fragmenter <-< AXI4Xbar <-< AXI4MasterNode
+*/
 class SimAXIMem(edge: AXI4EdgeParameters, size: BigInt, base: BigInt = 0)(implicit p: Parameters) extends SimpleLazyModule {
   val node = AXI4MasterNode(List(edge.master))
   val srams = AddressSet.misaligned(base, size).map { aSet =>
@@ -24,6 +27,9 @@ class SimAXIMem(edge: AXI4EdgeParameters, size: BigInt, base: BigInt = 0)(implic
   val io_axi4 = InModuleBody { node.makeIOs() }
 }
 
+/**
+  * Connect Master AXI4 Mem/MMIO Port to SimAXIMem.
+  */
 object SimAXIMem {
   def connectMMIO(dut: CanHaveMasterAXI4MMIOPort)(implicit p: Parameters): Seq[SimAXIMem] = {
     dut.mmio_axi4.zip(dut.mmioAXI4Node.in).map { case (io, (_, edge)) =>

src/main/scala/tilelink/Arbiter.scala

@@ -129,7 +129,7 @@ object TLArbiter
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 abstract class DecoupledArbiterTest(

src/main/scala/tilelink/AsyncCrossing.scala

@@ -122,7 +122,7 @@ class TLAsyncCrossing(params: AsyncQueueParams = AsyncQueueParams())(implicit p:
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLRAMAsyncCrossing(txns: Int, params: AsynchronousCrossing = AsynchronousCrossing())(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/AtomicAutomata.scala

@@ -301,7 +301,7 @@ object TLAtomicAutomata
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLRAMAtomicAutomata(txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/Credited.scala

@@ -83,7 +83,7 @@ object TLCreditedSink {
   def apply()(implicit p: Parameters): TLCreditedSinkNode = apply(CreditedDelay(1, 1))
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLRAMCreditedCrossing(txns: Int, params: CreditedCrossing)(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/Fragmenter.scala

@@ -338,7 +338,7 @@ object TLFragmenter
   def apply(wrapper: TLBusWrapper)(implicit p: Parameters): TLNode = apply(wrapper.beatBytes, wrapper.blockBytes)
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLRAMFragmenter(ramBeatBytes: Int, maxSize: Int, txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/Fuzzer.scala

@@ -241,7 +241,7 @@ object TLFuzzer
   }
 }
 
-/** Synthesizeable integration test */
+/** Synthesizable integration test */
 import freechips.rocketchip.unittest._
 
 class TLFuzzRAM(txns: Int)(implicit p: Parameters) extends LazyModule

src/main/scala/tilelink/HintHandler.scala

@@ -121,7 +121,7 @@ object TLHintHandler
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 //TODO ensure handler will pass through hints to clients that can handle them themselves

src/main/scala/tilelink/Jbar.scala

@@ -50,7 +50,7 @@ object TLJbar
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLJbarTestImp(nClients: Int, nManagers: Int, txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/RationalCrossing.scala

@@ -118,7 +118,7 @@ class TLRationalCrossing(direction: RationalDirection = Symmetric)(implicit p: P
   }
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLRAMRationalCrossingSource(name: String, txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/SRAM.scala

@@ -331,7 +331,7 @@ object TLRAM
   }
 }
 
-/** Synthesizeable unit testing */
+// Synthesizable unit testing
 import freechips.rocketchip.unittest._
 
 class TLRAMSimple(ramBeatBytes: Int, sramReg: Boolean, txns: Int)(implicit p: Parameters) extends LazyModule {

src/main/scala/tilelink/WidthWidget.scala

@@ -222,7 +222,7 @@ object TLWidthWidget
   def apply(wrapper: TLBusWrapper)(implicit p: Parameters): TLNode = apply(wrapper.beatBytes)
 }
 
-/** Synthesizeable unit tests */
+// Synthesizable unit tests
 import freechips.rocketchip.unittest._
 
 class TLRAMWidthWidget(first: Int, second: Int, txns: Int)(implicit p: Parameters) extends LazyModule {