From 6387d31c624b5b8b079baf47e6bc03bd6646e666 Mon Sep 17 00:00:00 2001
From: Howard Mao <zhehao.mao@gmail.com>
Date: Thu, 10 Sep 2015 17:33:48 -0700
Subject: [PATCH] add comments and small fixes for NASTI and SMI

---
 junctions/src/main/scala/nasti.scala | 12 +++++++++++-
 junctions/src/main/scala/smi.scala   | 13 ++++++++++---
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/junctions/src/main/scala/nasti.scala b/junctions/src/main/scala/nasti.scala
index 26d198b9..b2282399 100644
--- a/junctions/src/main/scala/nasti.scala
+++ b/junctions/src/main/scala/nasti.scala
@@ -226,6 +226,7 @@ class MemIONASTISlaveIOConverter(cacheBlockOffsetBits: Int) extends MIFModule wi
   io.mem.resp.ready := io.nasti.r.ready
 }
 
+/** Arbitrate among arbN masters requesting to a single slave */
 class NASTIArbiter(val arbN: Int) extends NASTIModule {
   val io = new Bundle {
     val master = Vec.fill(arbN) { new NASTISlaveIO }
@@ -292,7 +293,8 @@ class NASTIArbiter(val arbN: Int) extends NASTIModule {
   } else { io.slave <> io.master.head }
 }
 
-// TODO: More efficient implementation a/la Chisel Stdlib
+/** Locking RR arbiter for NASTI read data channel
+ *  Arbiter locks until last message in channel is sent */
 class NASTIReadDataArbiter(arbN: Int) extends NASTIModule {
   val io = new Bundle {
     val in = Vec.fill(arbN) { Decoupled(new NASTIReadDataChannel) }.flip
@@ -363,6 +365,9 @@ class NASTIErrorSlave extends NASTIModule {
   b_queue.io.deq.ready := io.b.ready && !draining
 }
 
+/** Take a single NASTI master and route its requests to various slaves
+ *  @param addrmap a sequence of base address + memory size pairs,
+ *  on for each slave interface */
 class NASTIRouter(addrmap: Seq[(BigInt, BigInt)]) extends NASTIModule {
   val nSlaves = addrmap.size
 
@@ -437,6 +442,11 @@ class NASTIRouter(addrmap: Seq[(BigInt, BigInt)]) extends NASTIModule {
   io.master.r <> r_arb.io.out
 }
 
+/** Crossbar between multiple NASTI masters and slaves
+ *  @param nMasters the number of NASTI masters
+ *  @param nSlaves the number of NASTI slaves
+ *  @param addrmap a sequence of base - size pairs;
+ *  size of addrmap should be nSlaves */
 class NASTICrossbar(nMasters: Int, nSlaves: Int, addrmap: Seq[(BigInt, BigInt)])
     extends NASTIModule {
   val io = new Bundle {
diff --git a/junctions/src/main/scala/smi.scala b/junctions/src/main/scala/smi.scala
index 2b653bb3..e1955ab1 100644
--- a/junctions/src/main/scala/smi.scala
+++ b/junctions/src/main/scala/smi.scala
@@ -11,6 +11,9 @@ class SMIReq(val dataWidth: Int, val addrWidth: Int) extends Bundle {
     new SMIReq(dataWidth, addrWidth).asInstanceOf[this.type]
 }
 
+/** Simple Memory Interface IO. Used to communicate with PCR and SCR
+ *  @param dataWidth the width in bits of the data field
+ *  @param addrWidth the width in bits of the addr field */
 class SMIIO(val dataWidth: Int, val addrWidth: Int) extends Bundle {
   val req = Decoupled(new SMIReq(dataWidth, addrWidth))
   val resp = Decoupled(Bits(width = dataWidth)).flip
@@ -26,6 +29,7 @@ abstract class SMIPeripheral extends Module {
   lazy val io = new SMIIO(dataWidth, addrWidth).flip
 }
 
+/** A simple sequential memory accessed through SMI */
 class SMIMem(val dataWidth: Int, val memDepth: Int) extends SMIPeripheral {
   // override
   val addrWidth = log2Up(memDepth)
@@ -35,9 +39,6 @@ class SMIMem(val dataWidth: Int, val memDepth: Int) extends SMIPeripheral {
   val ren = io.req.fire() && !io.req.bits.rw
   val wen = io.req.fire() && io.req.bits.rw
 
-  io.resp.valid := Reg(next = ren)
-  io.resp.bits := mem.read(io.req.bits.addr, ren)
-
   when (wen) { mem.write(io.req.bits.addr, io.req.bits.data) }
 
   val resp_valid = Reg(init = Bool(false))
@@ -46,9 +47,14 @@ class SMIMem(val dataWidth: Int, val memDepth: Int) extends SMIPeripheral {
   when (io.req.fire())  { resp_valid := Bool(true) }
 
   io.resp.valid := resp_valid
+  io.resp.bits := mem.read(io.req.bits.addr, ren)
   io.req.ready := !resp_valid
 }
 
+/** Arbitrate among several SMI clients
+ *  @param n the number of clients
+ *  @param dataWidth SMI data width
+ *  @param addrWidth SMI address width */
 class SMIArbiter(val n: Int, val dataWidth: Int, val addrWidth: Int)
     extends Module {
   val io = new Bundle {
@@ -243,6 +249,7 @@ class SMIIONASTIWriteIOConverter(val dataWidth: Int, val addrWidth: Int)
   when (io.b.fire()) { state := s_idle }
 }
 
+/** Convert NASTI protocol to SMI protocol */
 class SMIIONASTISlaveIOConverter(val dataWidth: Int, val addrWidth: Int)
     extends NASTIModule {
   val io = new Bundle {