Add memory mapping documentation

Author: cchaine

docs/CMakeLists.txt

@@ -13,6 +13,11 @@ if(Sphinx_FOUND)
       "${CMAKE_CURRENT_LIST_DIR}/src/assets/wishbone-write.svg"
       "${CMAKE_CURRENT_LIST_DIR}/src/assets/traceability.svg"
       "${CMAKE_CURRENT_LIST_DIR}/src/index.rst"
+      "${CMAKE_CURRENT_LIST_DIR}/src/guide/registers.rst"
+      "${CMAKE_CURRENT_LIST_DIR}/src/spec/content/spi_cr.rst"
+      "${CMAKE_CURRENT_LIST_DIR}/src/spec/content/spi_rxdr.rst"
+      "${CMAKE_CURRENT_LIST_DIR}/src/spec/content/spi_sr.rst"
+      "${CMAKE_CURRENT_LIST_DIR}/src/spec/content/spi_txdr.rst"
       "${CMAKE_CURRENT_LIST_DIR}/src/spec/index.rst"
       "${CMAKE_CURRENT_LIST_DIR}/src/spec/1_introduction.rst"
       "${CMAKE_CURRENT_LIST_DIR}/src/spec/2_overall-description.rst"

docs/src/guide/registers.rst

@@ -14,3 +14,40 @@ Memory Map and Registers
     - Reset value
     - Section/page
 
+  * - 0000_0000h
+    - Status register (SPI_SR)
+    - 32
+    - R
+    - 0000_0000h
+    - :ref:`SPI_SR <GUIDE_SPI_SR>`
+  * - 0000_0004h
+    - Control register (SPI_CR)
+    - 32
+    - R/W
+    - 0000_0000h
+    - :ref:`SPI_CR <GUIDE_SPI_CR>`
+  * - 0000_0008h
+    - Receive Data register (SPI_RXDR)
+    - 32
+    - R
+    - 0000_0000h
+    - :ref:`SPI_RXDR <GUIDE_SPI_RXDR>`
+  * - 0000_000Ch
+    - Transmit Data register (SPI_TXDR)
+    - 32
+    - W
+    - 0000_0000h
+    - :ref:`SPI_TXDR <GUIDE_SPI_TXDR>`
+
+.. _GUIDE_SPI_SR:
+.. include:: ../spec/content/spi_sr.rst
+
+.. _GUIDE_SPI_CR:
+.. include:: ../spec/content/spi_cr.rst
+
+.. _GUIDE_SPI_RXDR:
+.. include:: ../spec/content/spi_rxdr.rst
+
+.. _GUIDE_SPI_TXDR:
+.. include:: ../spec/content/spi_txdr.rst
+

docs/src/spec/3_requirements.rst

@@ -142,6 +142,55 @@ Memory-mapped registers
 
    The following registers shall be implemented and accessible through the wishbone memory interface.
 
+.. list-table::
+  :header-rows: 1
+  :widths: 1 94 1 1 1 1
+  
+  * - Address Offset
+    - Register name
+    - Width (in bits)
+    - Access
+    - Reset value
+    - Section/page
+
+  * - 0000_0000h
+    - Status register (SPI_SR)
+    - 32
+    - R
+    - 0000_0000h
+    - :ref:`SPI_SR <GUIDE_SPI_SR>`
+  * - 0000_0004h
+    - Control register (SPI_CR)
+    - 32
+    - R/W
+    - 0000_0000h
+    - :ref:`SPI_CR <GUIDE_SPI_CR>`
+  * - 0000_0008h
+    - Receive Data register (SPI_RXDR)
+    - 32
+    - R
+    - 0000_0000h
+    - :ref:`SPI_RXDR <GUIDE_SPI_RXDR>`
+  * - 0000_000Ch
+    - Transmit Data register (SPI_TXDR)
+    - 32
+    - W
+    - 0000_0000h
+    - :ref:`SPI_TXDR <GUIDE_SPI_TXDR>`
+
+.. _GUIDE_SPI_SR:
+.. include:: ../spec/content/spi_sr.rst
+
+.. _GUIDE_SPI_CR:
+.. include:: ../spec/content/spi_cr.rst
+
+.. _GUIDE_SPI_RXDR:
+.. include:: ../spec/content/spi_rxdr.rst
+
+.. _GUIDE_SPI_TXDR:
+.. include:: ../spec/content/spi_txdr.rst
+
+
 Non-functional Requirements
 ---------------------------
 

docs/src/spec/content/spi_cr.rst

@@ -0,0 +1,44 @@
+Control register (SPI_CR)
+""""""""""""""""""""""""""
+
+SPI_CR contains the control for selecting the SPI frequency and controlling the chip select.
+
+.. bitfield::
+    :bits: 32
+    :lanes: 2
+    :vspace: 70
+    :hspace: 700
+
+        [
+            { "name": "CS", "bits": 1},
+            { "name": "reserved", "bits": 15, "type": 1},
+            { "name": "PRESCALER", "bits": 16}
+        ]
+
+|
+
+.. list-table::
+  :header-rows: 1
+  :widths: 1 1 99
+  
+  * - Position
+    - Field
+    - Description
+
+  * - 31-16
+    - Prescaler
+    - *SPI frequency selector*
+
+      The specified SPI frequency is f_spi = (f_sys / (2 * prescaler)).
+  * - 15-1
+    - reserved
+    - *This field is reserved.*
+
+      This read-only field is reserved and always has the value 0.
+  * - 0
+    - CS
+    - *Active-high Chip select*
+
+      0 |tab| Chip-select disabled
+
+      1 |tab| Chip-select enabled

docs/src/spec/content/spi_rxdr.rst

@@ -0,0 +1,36 @@
+Receive Data register (SPI_RXDR)
+"""""""""""""""""""""""""""""""""
+
+.. bitfield::
+    :bits: 32
+    :lanes: 2
+    :vspace: 70
+    :hspace: 700
+
+        [
+            { "name": "RXD", "bits": 8},
+            { "name": "reserved", "bits": 24, "type": 1}
+        ]
+
+|
+
+.. list-table::
+  :header-rows: 1
+  :widths: 1 1 99
+  
+  * - Position
+    - Field
+    - Description
+
+  * - 31-8
+    - reserved
+    - *This field is reserved.*
+
+      This read-only field is reserved and always has the value 0.
+  * - 7-0
+    - RXD
+    - *Receive Data*
+
+      The received data is written to this field.
+      
+      The field is cleared by hardware after being read.

docs/src/spec/content/spi_sr.rst

@@ -0,0 +1,36 @@
+Status register (SPI_SR)
+"""""""""""""""""""""""""
+
+.. bitfield::
+    :bits: 32
+    :lanes: 2
+    :vspace: 70
+    :hspace: 700
+
+        [
+            { "name": "TXE", "bits": 1},
+            { "name": "reserved", "bits": 31, "type": 1}
+        ]
+
+|
+
+.. list-table::
+  :header-rows: 1
+  :widths: 1 1 99
+  
+  * - Position
+    - Field
+    - Description
+
+  * - 31-1
+    - Reserved
+    - *This field is reserved.*
+
+      This read-only field is reserved and always has the value 0.
+  * - 0
+    - TXE
+    - *Transmit register Empty*
+
+      0 |tab| The transmit register is full (being sent)
+
+      1 |tab| The transmit register is empty

docs/src/spec/content/spi_txdr.rst

@@ -0,0 +1,34 @@
+Transmit Data register (SPI_TXDR)
+""""""""""""""""""""""""""""""""""
+
+.. bitfield::
+    :bits: 32
+    :lanes: 2
+    :vspace: 70
+    :hspace: 700
+
+        [
+            { "name": "TXD", "bits": 8},
+            { "name": "reserved", "bits": 24, "type": 1}
+        ]
+
+|
+
+.. list-table::
+  :header-rows: 1
+  :widths: 1 1 99
+  
+  * - Position
+    - Field
+    - Description
+
+  * - 31-8
+    - reserved
+    - *This field is reserved.*
+  * - 7-0
+    - TXD
+    - *Transmit Data*
+
+      Data written to this field is sent through the serial link.
+      
+      The TXE field of the SPI_SR shall be sample before writing again to this field to prevent data loss.