Implement a SyncReadMem wrapper with explicit read, write, and read/write ports

docs/src/explanations/memories.md

@@ -200,3 +200,51 @@ Chisel memories can be initialized from an external `binary` or `hex` file emitt
 
 For more information, check the experimental docs on [Loading Memories](../appendix/experimental-features#loading-memories) feature.
 
+## SRAM
+
+Chisel provides an API to generate `SRAM` memories, which are currently alternative APIs for `SyncReadMem`. The key difference between the `SRAM` and `SyncReadMem` APIs is the former's capability to declare a specific number of read, write, and read-write memory ports, which are interacted with using explicit bundles.
+
+```scala mdoc:silent
+class ModuleWithSRAM(numReadPorts: Int, numWritePorts: Int, numReadwritePorts: Int) extends Module {
+  val width: Int = 8
+
+  val io = IO(new SRAMInterface(1024, UInt(width.W), numReadPorts, numWritePorts, numReadwritePorts))
+
+  // Generate a SyncReadMem representing an SRAM with an explicit number of read, write, and read-write ports
+  io.mem :<>= SRAM(1024, UInt(width.W), numReadPorts, numWritePorts, numReadwritePorts)
+}
+```
+
+To interact with a desired port, index into the `numReadPorts`, `numWritePorts`, and `numReadwritePorts` signals:
+
+```scala mdoc:silent
+class TopModule extends Module {
+  // Declare a 2 read, 2 write, 2 read-write ported SRAM with 8-bit UInt data members
+  val memModule = Module(new ModuleWithSRAM(2, 2, 2))
+
+  // Whenever we want to read from the first read port
+  mem.io.readPorts(0).address := 100.U
+  mem.io.readPorts(0).enable := true.B
+
+  // Read data is returned one cycle after enable is driven
+  val foo = WireInit(UInt(8.W), mem.io.readPorts(0).data)
+
+  // Whenever we want to write to the second write port
+  mem.io.writePorts(1).address := 5.U
+  mem.io.writePorts(1).enable := true.B
+  mem.io.writePorts(1).data := 12.U
+
+  // Whenever we want to read or write to the third read-write port
+  // Write:
+  mem.io.readwritePorts(2).address := 5.U
+  mem.io.readwritePorts(2).enable := true.B
+  mem.io.readwritePorts(2).isWrite := true.B
+  mem.io.readwritePorts(2).writeData := 100.U
+
+  // Read:
+  mem.io.readwritePorts(2).address := 5.U
+  mem.io.readwritePorts(2).enable := true.B
+  mem.io.readwritePorts(2).isWrite := false.B
+  val bar = WireInit(UInt(8.W), mem.io.readwritePorts(2).readData)
+}
+```

src/main/scala/chisel3/util/SRAM.scala

@@ -72,19 +72,19 @@ class MemoryReadWritePort[T <: Data] private[chisel3] (tpe: T, addrWidth: Int, m
 /** A IO bundle of signals connecting to the ports of a wrapped `SyncReadMem`, as requested by
   * `SRAMInterface.apply`.
   *
+  * @param memSize The size of the memory, used to calculate the address width
   * @tparam tpe The data type of the memory port
-  * @param width The width of the address wires of each port
   * @param numReadPorts The number of read ports
   * @param numWritePorts The number of write ports
   * @param numReadwritePorts The number of read/write ports
   */
 class SRAMInterface[T <: Data](
+  memSize:           BigInt,
   tpe:               T,
-  addrWidth:         Int,
   numReadPorts:      Int,
   numWritePorts:     Int,
   numReadwritePorts: Int,
-  masked:            Boolean)
+  masked:            Boolean = false)
     extends Bundle {
   if (masked) {
     require(
@@ -94,6 +94,8 @@ class SRAMInterface[T <: Data](
   }
   override def typeName: String = s"SRAMInterface_${SRAM.portedness(numReadPorts, numWritePorts, numReadwritePorts)}${if(masked) "_masked" else ""}}_${tpe.typeName}"
 
+  val addrWidth = log2Up(memSize + 1)
+
   val readPorts:  Vec[MemoryReadPort[T]] = Vec(numReadPorts, new MemoryReadPort(tpe, addrWidth))
   val writePorts: Vec[MemoryWritePort[T]] = Vec(numWritePorts, new MemoryWritePort(tpe, addrWidth, masked))
   val readwritePorts: Vec[MemoryReadWritePort[T]] =
@@ -103,7 +105,7 @@ class SRAMInterface[T <: Data](
 object SRAM {
 
   /** Generates a [[SyncReadMem]] within the current module, connected to an explicit number
-    * of read, write, and read/write ports. This SRAM abstraction has both read and write capabilities: that is,
+    * of read, write, and read/write ports. This SRsizeAM abstraction has both read and write capabilities: that is,
     * it contains at least one read accessor (a read-only or read-write port), and at least one write accessor
     * (a write-only or read-write port).
     *
@@ -178,9 +180,7 @@ object SRAM {
       )
     }
 
-    val addrWidth = log2Up(size + 1)
-
-    val _out = Wire(new SRAMInterface(tpe, addrWidth, numReadPorts, numWritePorts, numReadwritePorts, false))
+    val _out = Wire(new SRAMInterface(size, tpe, numReadPorts, numWritePorts, numReadwritePorts))
     val mem = SyncReadMem(size, tpe)
 
     for (i <- 0 until numReadPorts) {
@@ -230,9 +230,7 @@ object SRAM {
       )
     }
 
-    val addrWidth = log2Up(size + 1)
-
-    val _out = Wire(new SRAMInterface(tpe, addrWidth, numReadPorts, numWritePorts, numReadwritePorts, true))
+    val _out = Wire(new SRAMInterface(size, tpe, numReadPorts, numWritePorts, numReadwritePorts, true))
     val mem = SyncReadMem(size, tpe)
 
     for (i <- 0 until numReadPorts) {