documentation

docs/cpuif/addressing.rst

@@ -1,9 +0,0 @@
-CPU Interface Addressing
-========================
-
-TODO: write about the following:
-
-* cpuif addressing is always 0-based (aka relative to the block's root)
-* It is up to the decoder to handle the offset
-* Address bus width is pruned down
-* recommend that the decoder/interconnect reserve a full ^2 block of addresses to simplify decoding

docs/cpuif/apb3.rst

@@ -1,11 +1,31 @@
-AMBA APB3
-=========
+AMBA 3 APB
+==========
 
-TODO: Describe the following
+Implements the register block using an
+`AMBA 3 APB <https://developer.arm.com/documentation/ihi0024/b/Introduction/About-the-AMBA-3-APB>`_
+CPU interface.
 
-* List of interface signals
+The APB3 CPU interface comes in two i/o port flavors:
 
-    * interface name & modports (link to advanced topics in case user wants to override)
-    * flattened equivalents
+SystemVerilog Interface
+    Class: :class:`peakrdl.regblock.cpuif.apb3.APB3_Cpuif`
 
-* Download link to SV interface definition
+    Interface Definition: :download:`apb3_intf.sv <../../test/lib/cpuifs/apb3/apb3_intf.sv>`
+
+Flattened inputs/outputs
+    Flattens the interface into descrete input and output ports.
+
+    Class: :class:`peakrdl.regblock.cpuif.apb3.APB3_Cpuif_flattened`
+
+
+.. warning::
+    Some IP vendors will incorrectly implement the address signalling
+    assuming word-addresses. (that each increment of ``PADDR`` is the next word)
+
+    For this exporter, values on the interface's ``PADDR`` input are interpreted
+    as byte-addresses. (a 32-bit APB bus increments ``PADDR`` in steps of 4)
+    Although APB protocol does not allow for unaligned transfers, this is in
+    accordance to the official AMBA bus specification.
+
+    Be sure to double-check the interpretation of your interconnect IP. A simple
+    bit-shift operation can be used to correct this if necessary.

docs/cpuif/axi4lite.rst

@@ -1,11 +1,29 @@
 AMBA AXI4-Lite
 ==============
 
-TODO: Describe the following
+Implements the register block using an
+`AMBA AXI4-Lite <https://developer.arm.com/documentation/ihi0022/e/AMBA-AXI4-Lite-Interface-Specification>`_
+CPU interface.
 
-* List of interface signals
+The AXI4-Lite CPU interface comes in two i/o port flavors:
 
-    * interface name & modports (link to advanced topics in case user wants to override)
-    * flattened equivalents
+SystemVerilog Interface
+    Class: :class:`peakrdl.regblock.cpuif.axi4lite.AXI4Lite_Cpuif`
 
-* Download link to SV interface definition
+    Interface Definition: :download:`apb3_intf.sv <../../test/lib/cpuifs/axi4lite/axi4lite_intf.sv>`
+
+Flattened inputs/outputs
+    Flattens the interface into descrete input and output ports.
+
+    Class: :class:`peakrdl.regblock.cpuif.axi4lite.AXI4Lite_Cpuif_flattened`
+
+
+Pipelined Performance
+---------------------
+This implementation of the AXI4-Lite interface supports transaction pipelining
+which can significantly improve performance of back-to-back transfers.
+
+In order to support transaction pipelining, the CPU interface will accept multiple
+concurrent transactions. The number of outstanding transactions allowed is automatically
+determined based on the register file pipeline depth (affected by retiming options),
+and influences the depth of the internal transaction response skid buffer.

docs/cpuif/introduction.rst

@@ -0,0 +1,26 @@
+Introduction
+============
+
+The CPU interface logic layer provides an abstraction between the
+application-specific bus protocol and the internal register file logic.
+When exporting a design, you can select from a variety of popular CPU interface
+protocols. These are described in more detail in the pages that follow.
+
+
+Addressing
+^^^^^^^^^^
+
+The regblock exporter will always generate its address decoding logic using local
+address offsets. The absolute address offset of your device shall be
+handled by your system interconnect, and present addresses to the regblock that
+only include the local offset.
+
+For example, consider a fictional AXI4-Lite device that:
+
+- Consumes 4 kB of address space (``0x000``-``0xFFF``).
+- The device is instantiated in your system at global address ``0x80_0000``-``0x80_0FFF``.
+- After decoding transactions destined to the device, the system interconnect shall
+  ensure that AxADDR values are presented to the device as relative addresses - within
+  the range of ``0x000``-``0xFFF``.
+- If care is taken to align the global address offset to the size of the device,
+  creating a relative address is as simple as pruning down address bits.

docs/cpuif/passthrough.rst

@@ -0,0 +1,9 @@
+CPUIF Passthrough
+=================
+
+This CPUIF mode bypasses the protocol converter stage and directly exposes the
+internal CPUIF handshake signals to the user.
+
+Class: :class:`peakrdl.regblock.cpuif.passthrough.PassthroughCpuif`
+
+For more details on the protocol itself, see: :ref:`cpuif_protocol`.