updated yaml and documentation

efabless · May 7, 2024 · 6ea7e6d · 6ea7e6d
1 parent 8a06db5
commit 6ea7e6d
Show file tree

Hide file tree

Showing 4 changed files with 241 additions and 52 deletions.
diff --git a/EF_PSRAM_CTRL_V2.json b/EF_PSRAM_CTRL_V2.json
diff --git a/EF_PSRAM_CTRL_V2.yaml b/EF_PSRAM_CTRL_V2.yaml
@@ -0,0 +1,135 @@
+---
+info:
+  name: EF_PSRAM_CTRL_V2
+  description: A Controller for Quad I/O SPI PSRAM
+  repo: github.com/efabless/EF_PSRAM_CTRL_V2
+  owner: Efabless Corp.
+  license: Apache 2.0
+  author: Mohamed Shalan
+  email: [email protected]
+  version: v1.0.4
+  date: 7-05-2024
+  category: digital
+  tags:
+    - memory
+    - psram
+  bus:
+    - AHBL
+  type: soft
+  status: verified
+  cell_count:
+    - IP: TBD
+    - AHBL: TBD
+  width: "0.0"
+  height: "0.0"
+  technology: n/a
+  clock_freq_mhz:
+    - IP: TBD
+    - AHBL: TBD
+  digital_supply_voltage: n/a
+  analog_supply_voltage: n/a
+
+external_interface:
+- name: sck
+  port: sck
+  width: 1
+  direction: output
+  description: SPI master output clock 
+- name: ce_n
+  port: ce_n
+  width: 1
+  direction: output 
+  description: SPI Master slave select.
+- name: din
+  port: din
+  width: 4
+  direction: input
+  description: SPI Master data in , slave out 
+- name: dout
+  port: dout
+  width: 4
+  direction: output 
+  description: SPI Master data out , slave in  
+- name: douten
+  port: douten
+  width: 4
+  direction: output 
+  description: SPI Master data out enable 
+
+registers:
+  - name: rd_cmd
+    size: 8
+    mode: w
+    fifo: no
+    offset: 0x0080_0100
+    bit_access: no
+    init: "3"
+    write_port: ""
+    description: RD Command Register
+  - name: wr_cmd
+    size: 8
+    mode: w
+    fifo: no
+    offset: 0x0080_0200
+    bit_access: no
+    init: "2"
+    write_port: ""
+    description: WR Command Register
+  - name: eqpi_cmd
+    size: 8
+    mode: w
+    fifo: no
+    offset: 0x0080_0400
+    bit_access: no
+    init: "35"
+    write_port: ""
+    description: Enter QPI Command Register
+  - name: xqpi_cmd
+    size: 8
+    mode: w
+    fifo: no
+    offset: 0x0080_0800
+    bit_access: no
+    init: "FE"
+    write_port: ""
+    description: Exit QPI Command Register
+  - name: wait_states
+    size: 4
+    mode: w
+    fifo: no
+    offset: 0x0080_1000
+    bit_access: no
+    init: "0"
+    write_port: ""
+    description: Wait States Register
+  - name: mode
+    size: 2
+    mode: w
+    fifo: no
+    offset: 0x0080_2000
+    bit_access: no
+    init: "0"
+    write_port: ""
+    description: I/O Mode Register, {qpi, qspi}
+  - name: enter_qpi
+    size: 1
+    mode: w
+    fifo: no
+    offset: 0x0080_4000
+    bit_access: no
+    init: "0"
+    write_port: ""
+    description: Initiate Enter QPI (EQPI) Mode process Register
+  - name: exit_qpi
+    size: 1
+    mode: w
+    fifo: no
+    offset: 0x0080_8000
+    bit_access: no
+    init: "0"
+    write_port: ""
+    description: Initiate Exit QPI (XQPI) Mode process Register
+clock: HCLK
+reset:
+  name: HRESETn
+  pol: "0"
diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
 # EF_PSRAM_CTRL_V2
+
 Pseudostatic RAM (PSRAM) is DRAM combined with a self-refresh circuit. 
     It appears externally as slower SRAM, albeit with a density/cost advantage 
     over true SRAM, and without the access complexity of DRAM.
@@ -11,34 +12,114 @@ utilizing SPI, QSPI and QPI modes.
 
 The controller was verified against the Verilog model of Microchip M23LC1024 for SPI and QPI modes only.
 
-## Features
+##### Features:
 - Small in size (800 cells)
 - Supports PSRAM or serial SRAM memories up to 8MBytes.
 - Programmable to configure: read/write commands, number of wait states, enter and exist quad i/o commands.
 
-## Memory Map
+## The wrapped IP
+
+
+ The IP comes with an AHBL Wrapper
+
+### Wrapped IP System Integration
+
+```verilog
+EF_PSRAM_CTRL_V2_ahbl INST (
+        `TB_AHBL_SLAVE_CONN,
+        .sck(sck),
+        .ce_n(ce_n),
+        .din(din),
+        .dout(dout),
+        .douten(douten)
+);
+```
+> **_NOTE:_** `TB_AHBL_SLAVE_CONN is a convenient macro provided by [BusWrap](https://github.com/efabless/BusWrap/tree/main).
+
+## Implementation example  
+
+The following table is the result for implementing the EF_PSRAM_CTRL_V2 IP with different wrappers using Sky130 PDK and [OpenLane2](https://github.com/efabless/openlane2) flow.
+|Module | Number of cells | Max. freq |
+|---|---|---|
+|EF_PSRAM_CTRL_V2|TBD| TBD |
+|EF_PSRAM_CTRL_V2_AHBL|TBD|TBD|
+## The Programmer's Interface
+
+### Memory Map
 |Region|Description|
 |------|-----------|
 |```0x07FF_FFFF - 0x0000_0000```| Data Access |
 |```0x0FFF_FFFF - 0x0800_0000```| Configuration Registers|
-## Configuration Registers
-| Address | Description |
-|---------|-------------|
-|```0x0080_0100```|RD Command Register|
-|```0x0080_0200```|WR Command Register|
-|```0x0080_0400```|Enter QPI Command Register|
-|```0x0080_0800```|Exit QPI Command Register|
-|```0x0080_1000```|Wait States Register|
-|```0x0080_2000```|I/O Mode Register, {qpi, qspi}|
-|```0x0080_4000```|Initiate Enter QPI (EQPI) Mode process Register|
-|```0x0080_8000```|Initiate Exit QPI (XQPI) Mode process Register|
-
-## Operation
+### Registers
+
+|Name|Offset|Reset Value|Access Mode|Description|
+|---|---|---|---|---|
+|rd_cmd|800100|0x00000003|w|RD Command Register|
+|wr_cmd|800200|0x00000002|w|WR Command Register|
+|eqpi_cmd|800400|0x00000035|w|Enter QPI Command Register|
+|xqpi_cmd|800800|0x000000FE|w|Exit QPI Command Register|
+|wait_states|801000|0x00000000|w|Wait States Register|
+|mode|802000|0x00000000|w|I/O Mode Register, {qpi, qspi}|
+|enter_qpi|804000|0x00000000|w|Initiate Enter QPI (EQPI) Mode process Register|
+|exit_qpi|808000|0x00000000|w|Initiate Exit QPI (XQPI) Mode process Register|
+
+### rd_cmd Register [Offset: 0x800100, mode: w]
+
+RD Command Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'rd_cmd', bits:8},{bits: 24}], config: {lanes: 2, hflip: true}} "/>
+
+
+### wr_cmd Register [Offset: 0x800200, mode: w]
+
+WR Command Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'wr_cmd', bits:8},{bits: 24}], config: {lanes: 2, hflip: true}} "/>
+
+
+### eqpi_cmd Register [Offset: 0x800400, mode: w]
+
+Enter QPI Command Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'eqpi_cmd', bits:8},{bits: 24}], config: {lanes: 2, hflip: true}} "/>
+
+
+### xqpi_cmd Register [Offset: 0x800800, mode: w]
+
+Exit QPI Command Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'xqpi_cmd', bits:8},{bits: 24}], config: {lanes: 2, hflip: true}} "/>
+
+
+### wait_states Register [Offset: 0x801000, mode: w]
+
+Wait States Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'wait_states', bits:4},{bits: 28}], config: {lanes: 2, hflip: true}} "/>
+
+
+### mode Register [Offset: 0x802000, mode: w]
+
+I/O Mode Register, {qpi, qspi}
+<img src="https://svg.wavedrom.com/{reg:[{name:'mode', bits:2},{bits: 30}], config: {lanes: 2, hflip: true}} "/>
+
+
+### enter_qpi Register [Offset: 0x804000, mode: w]
+
+Initiate Enter QPI (EQPI) Mode process Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'enter_qpi', bits:1},{bits: 31}], config: {lanes: 2, hflip: true}} "/>
+
+
+### exit_qpi Register [Offset: 0x808000, mode: w]
+
+Initiate Exit QPI (XQPI) Mode process Register
+<img src="https://svg.wavedrom.com/{reg:[{name:'exit_qpi', bits:1},{bits: 31}], config: {lanes: 2, hflip: true}} "/>
+
+
+## The Interface 
+<img src="docs/EF_PSRAM_CTRL_V2_ahbl.svg" width="600"/>
+
+## F/W Usage Guidelines:
 Out of reset, the controller is in the standard SPI mode which is supported by all SPI memories. 
 
 Performing a memory read or a memory write from/to the data region will trigger the corresponding SPI command and is fully transparent to the CPU and it looks like a normal memory/read operation.
 
-### Switch to QPI mode
+##### Switch to QPI mode:
 1) Set RD/WR/Enter QPI/Exit QPI commands by writing to the corresponding configuration registers based on the memory datasheet.
 2) Set the number of wait states used by the read command by writing to the Wait States Register.
 3) Write "1" to the Initiate EQPI Mode process register.
@@ -47,3 +128,11 @@ Performing a memory read or a memory write from/to the data region will trigger
 6) Wait for the memory to switch to quad i/o mode. Consult the datasheet to obtain the latency.
 7) Write "2" to the i/o mode register
 
+## Installation:
+You can either clone repo or use [IPM](https://github.com/efabless/IPM) which is an open-source IPs Package Manager
+* To clone repo:
+```git clone https://github.com/efabless/EF_PSRAM_CTRL_V2```
+* To download via IPM , follow installation guides [here](https://github.com/efabless/IPM/blob/main/README.md) then run 
+```ipm install EF_PSRAM_CTRL```
+### Run cocotb UVM Testbench:
+TBD