## Switched Multi-ported SRAM-based Memories ##
## Ameer  M. S.  Abdelhadi and Guy  G. F.  Lemieux ##
## The University of British Columbia (UBC)  2014 ##
## { ameer.abdelhadi; guy.lemieux } @ gmail.com ##

A fully parameterized and generic Verilog implementation of the suggested modular switched multi-ported SRAM-based memory, together with previous approaches are provided as open source hardware. A run-in-batch flow manager to simulate and synthesize various designs with various parameters in batch using Altera's ModelSim and Quartus is also provided.

**LICENSE:** BSD 3-Clause ("BSD New" or "BSD Simplified") license.

This package is part of a journal paper submission to:  
**ACM Transactions on Reconfigurable Technology and Systems (TRETS); Special Issue on Reconfigurable Components with Source Code.**
  * **Paper title:** Modular Switched Multi-ported SRAM-based Memory
  * **Authors**: Ameer M.S. Abdelhadi and Guy G.F. Lemieux - UBC


---


## CAD Tools Requirements ##
This project has been tested intensively using Altera's Design Suite version 14.0 Specifically:
  1. Quartus II version 14.0 has been used to synthesize the Verilog implementation
  1. ModelSim Altera Edition version 10.0d (modelsim\_ase) has been used to simulate the Verilog implementation.

Furthermore, the run-in-batch synthesis and simulation flow managers have been implemented using C-Shell, hence a /bin/csh should be available in the machine


---


## Files and directories in this package ##
  * **README:** Read this first!
  * **LICENSE:** BSD 3-Clause ("BSD New" or "BSD Simplified") license.
  * **altera.12.0.ubc.csh:** C-shell script: Setup environment variables and Altera 12.0 CAD flow from The University of British Columbia (UBC). Change parameters to your environment if required.
  * **altera.13.1.ubc.csh:** C-shell script: Setup environment variables and Altera 13.1 CAD flow from The University of British Columbia (UBC).
  * **altera.14.0.ubc.csh:** C-shell script: Setup environment variables and Altera 14.0 CAD flow from The University of British Columbia (UBC).
  * **altera.14.0.fab.csh:** C-shell script: Setup environment variables and Altera 14.0 CAD flow from FAbRIC (FPGA Research Infrastructure Cloud); Texas Advanced Computing Center (TACC); UT Austin - https://wikis.utexas.edu/display/fabric/Home
  * **sim:** C-shell script: A run-in-batch simulation flow manager .
  * **syn:** C-shell script: A run-in-batch synthesis  flow manager.
  * **config.vh:** Verilog: Generated by 'syn' script, contains design parameters.
  * **utils.vh:** Verilog: Design pre-compile utilities.
  * **mrram.v:** Verilog: Multiread-RAM based on bank replication using generic dual-ported RAM with optional single-stage or two-stage bypass/ for normal mode ports.
  * **mrram\_swt.v:** Verilog: Multiread-RAM based on bank replication using generic dual-ported RAM with optional single-stage or two-stage bypass and switched read ports support.
  * **dpram.v:** Verilog: Generic dual-ported RAM .
  * **dpram\_bbs.v:** Verilog: Generic dual-ported RAM with optional single-stage or two-stage bypass.
  * **mpram\_reg.v:** Verilog: Generic register-based multiported-RAM. Reading addresses are registered and old data will be read in case of RAW. Implemented in FF's if the number of reading or writing ports exceeds one.
  * **mpram\_xor.v:** Verilog: Multiported-RAM based on XOR implementation.
  * **lvt\_reg.v:** Verilog: Register-based binary-coded LVT (Live-Value-Table).
  * **lvt\_bin.v:** Verilog: Binary-coded I-LVT (Invalidation Live-Value-Table).
  * **lvt\_1ht.v:** Verilog: Onehot-coded I-LVT (Invalidation Live-Value-Table).
  * **mpram\_lvt.v:** Verilog: LVT/I-LVT-based Multiported-RAM for register-base and SRAM-based one-hot/binary-coded I-LVT.
  * **smpram.v:** Verilog: Switched multiported-RAM: register-based, XOR-based ,register-based LVT, SRAM-based binary-coded and one-hot-coded I-LVT.
  * **smpram\_tb.v:** Verilog: Switched multiported-RAM testbench.
  * **smpram.qpf:** Quartus II Project File.
  * **smpram.qsf:** Quartus II Settings File.
  * **sim.res:** A list of simulation results, each run in a separate line, including all architectures.
  * **syn.res:** A list of synthesis results, each run in a separate line, including: frequency, resources usage, and runtime.
  * **log/:** A directory containing Altera's logs and reports.
  * **syn.res.example:** Example synthesis  results.
  * **sim.res.example:** Example simulation results.
  * **log.example.tar.xz:** xz tarball: archived log directory example (for the runs listed in syn.res.example). To extract invoke: tar -xavf log.example.tar.xz


---


## Switched multi-ported RAM module instantiation ##
All **.v &**.vh files in this package should be copied into your work directory. Copy the following instantiation into your Verilog design, change parameters and connectivity to fit your design.

```
// instantiate a multiported-RAM
mpram #(
  // parameters
  .MEMD (MEMD ), // positive integer: memory depth
  .DATW (DATW ), // positive integer: data width
  .nRPF (nRPF ), // positive integer: number of fixed (simple) read  ports (nRPF>=1              )
  .nWPF (nWPF ), // positive integer: number of fixed (simple) write ports (nWPF>=0              )
  .nRPS (nRPS ), // positive integer: number of switched       read  ports (nRPS<=nRPF           )
  .nWPS (nWPS ), // positive integer: number of switched       write ports (nWPS>=0; nWPF+nWPS>=1)
  .ARCH (ARCH ), // string: multi-port RAM architecture:
                 //   "AUTO"  : Choose automatically
                 //   "REG"   : Register-based
                 //   "XOR"   : XOR-based
                 //   "LVTREG": Register-based LVT
                 //   "LVTBIN": Binary-coded I-LVT-based
                 //   "LVT1HT": Onehot-coded I-LVT-based
  .BYPS (BYPS ), // string: Bypassing type:
                 //   "WAW": Allow Write-After-Write
                 //   "RAW": New data for Read-after-Write
                 //   "RDW": New data for Read-During-Write
  .FILE (""  )   // text: initialization file, optional
) mpram_inst (
  // ports
  .clk  (clk  ), // clock                                                          - input 
  .rdWr (rdWr ), // switch read/write (write is active low)                        - input 
  .WEnb (WEnb ), // write enables   - packed from nWPF fixed & nWPS switched ports - input : [            (nWPF+nWPS)-1:0]
  .WAddr(WAddr), // write addresses - packed from nWPF fixed & nWPS switched ports - input : [`log2(MEMD)*(nWPF+nWPS)-1:0]
  .WData(WData), // write data      - packed from nWPF fixed & nWPS switched ports - input : [DATW       *(nWPF+nWPS)-1:0]
  .RAddr(RAddr), // read  addresses - packed from nRPF fixed & nRPS switched ports - input : [`log2(MEMD)*(nRPF+nRPS)-1:0]
  .RData(RData)  // read  data      - packed from nRPF fixed & nRPS switched ports - output: [DATW       *(nRPF+nRPS)-1:0]
);
```


---


## `sim`: A Run-in-batch Simulation Flow Manager ##

### USAGE: ###
> `./sim <Depth List> <Width List> <#Write Ports List (Fixed-Switched)> <#Read Ports List (Fixed-Switched)> <Bypass List> <#Cycles> [verbose]`

  * Use a comma delimited list.
    * No spaces.
    * May be surrounded by any brackets (), [], {}, or <>.
  * RAM depth, data width, and simulation cycles are positive integers.
  * Numbers of read and write ports are:
    * Pairs of "fixed-switched" port numbers delimited with hyphen "-", or,
    * Fixed port number only, if switched ports are not required.
      * numbers of read/write ports are integers.
      * #switched\_read\_ports  < =  #fixed\_read\_ports
  * Bypassing type is one of: NON, WAW, RAW, or RDW.
    * NON: No bypassing logic
    * WAW: Allow Write-After-Write
    * RAW: new data for Read-after-Write
    * RDW: new data for Read-During-Write
  * "verbose" is an optional argument; use if verbosed logging is required

### EXAMPLES: ###
  * `./sim 1024 32 1-2 2-2 NON 1000000 verbose`
    * Simulate 1M cycles of a 1K lines RAM, 32 bits width, 1 fixed / 2 switched write & 2 fixed / 2 switched read ports, no bypassing, verbose logging,
  * `./sim 512,1024 8,16,32 2,3,4 1,2,3,4 RAW 1000000`
    * Simulate 1M cycles of RAMs with 512 or 1024 lines, 8, 16, or 32 bits width, 2,3, or 4 fixed write ports, 1,2,3, or 4 fixed read ports, with RAW bypass.

The following files and directories will be created after simulation :
  * sim.res : A list of simulation results, each run in a separate line, including all design styles.


---


## `syn`: A Run-in-batch Synthesis Flow Manager ##
### USAGE: ###
`./syn <Depth List> <Width List> <#Write Ports List (Fixed-Switched)> <#Read Ports List (Fixed-Switched)> <Bypass List> <Architecture List>`
  * Use a comma delimited list.
    * No spaces.
    * May be surrounded by any brackets (), [], {}, or <>.
  * RAM depth, data width, and simulation cycles are positive integers.
  * Numbers of read and write ports are:
    * Pairs of "fixed-switched" port numbers delimited with hyphen "-", or,
    * Fixed port number only, if switched ports are not required.
      * numbers of read/write ports are integers.
      * #switched\_read\_ports  < =  #fixed\_read\_ports
  * Bypassing type is one of: NON, WAW, RAW, or RDW.
    * NON: No bypassing logic
    * WAW: Allow Write-After-Write
    * RAW: new data for Read-after-Write
    * RDW: new data for Read-During-Write
  * Architecture is one of: REG, XOR, LVTREG, LVTBIN, or LVT1HT.
    * REG   : Register-based multi-ported RAM
    * XOR   : XOR-based multi-ported RAM
    * LVTREG: Register-based LVT multi-ported RAM
    * LVTBIN: Binary-coded I-LVT-based multi-ported RAM
    * LVT1HT: Onehot-coded I-LVT-based multi-ported RAM

### EXAMPLES: ###
  * `./syn 1024 32 1-2 2-2 NON XOR`
    * Synthesis a XOR-based RAM with no bypassing, 1K lines RAM, 32 bits width, 1 fixed / 2 switched write and 2 fixed / 2 switched read ports.
  * `./syn 512,1024 16,32 3,4 2,3 RAW,RDW LVTBIN,LVT1HT`
    * Synthesis LVTBIN & LVT1HT RAM with new data RAW & RDW bypassing, 512 & 1024 lines, 16 & 32 data width, 3 & 4 fixed write ports, 2 & 3 fixed read ports.

The following files and directories will be created after compilation:
  * syn.res : A list of results, each run in a separate line, including: frequency, resources usage, and runtime
  * log/    : Altera's logs and reports
