Add support for external components. (#4 & #36)

docs/cpuif/internal_protocol.rst

@@ -36,7 +36,8 @@ cpuif_wr_data
 
 cpuif_wr_biten
     Active-high bit-level write-enable strobes.
-    Only asserted bit positions will change the register value during a write transfer.
+    Only asserted bit positions will change the register value during a write
+    transfer.
 
 cpuif_req_stall_rd
     If asserted, and the next pending request is a read operation, then the

docs/index.rst

@@ -31,15 +31,17 @@ Install from `PyPi`_ using pip
 
 
 
-Quick Start
------------
+Quick Start - PeakRDL
+---------------------
 The easiest way is to use the `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_:
 
 .. code-block:: bash
 
-    peakrdl regblock atxmega_spi.rdl -o regblock/ --cpuif apb3-flat
+    peakrdl regblock atxmega_spi.rdl -o regblock/ --cpuif axi4-lite
 
 
+Quick Start - API
+-----------------
 Otherwise if you want, there is a Python API.
 Below is a simple example that demonstrates how to generate a SystemVerilog
 implementation from SystemRDL source.
@@ -49,7 +51,7 @@ implementation from SystemRDL source.
 
     from systemrdl import RDLCompiler, RDLCompileError
     from peakrdl_regblock import RegblockExporter
-    from peakrdl_regblock.cpuif.apb3 import APB3_Cpuif
+    from peakrdl_regblock.cpuif.axi4lite import AXI4Lite_Cpuif
     from peakrdl_regblock.udps import ALL_UDPS
 
     input_files = [
@@ -78,7 +80,7 @@ implementation from SystemRDL source.
     exporter = RegblockExporter()
     exporter.export(
         root, "path/to/output_dir",
-        cpuif_cls=APB3_Cpuif
+        cpuif_cls=AXI4Lite_Cpuif
     )
 
 
@@ -99,8 +101,8 @@ Links
     self
     architecture
     hwif
-    api
     configuring
+    api
     limitations
     licensing
 
@@ -125,6 +127,12 @@ Links
     props/signal
     props/rhs_props
 
+.. toctree::
+    :hidden:
+    :caption: Other SystemRDL Features
+
+    rdl_features/external
+
 .. toctree::
     :hidden:
     :caption: Extended Properties

docs/licensing.rst

@@ -47,4 +47,4 @@ workplace. This is totally OK, as long as you don't start distributing it
 outside your workplace in ways that violate the GPL v3 license.
 
 That said, I'd encourage you to check out the `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_.
-It might already do everything you need.
+It may already do everything you need.

docs/limitations.rst

@@ -6,11 +6,6 @@ supported properties, see the appropriate property listing page in the following
 sections.
 
 
-External Components
--------------------
-Regfiles, registers & fields instantiated using the ``external`` keyword are not supported yet.
-
-
 Alias Registers
 ---------------
 Registers instantiated using the ``alias`` keyword are not supported yet.

docs/rdl_features/external.rst

@@ -0,0 +1,133 @@
+External Components
+===================
+SystemRDL allows some component instances to be defined as "external" elements
+of an address space definition. In the context of this regblock generator,
+the implementation of an external component is left up to the designer. When
+generating the RTL for a regblock, the implementations of external components
+are omitted and instead a user-interface is presented on the
+``hwif_in``/``hwif_out`` i/o structs.
+
+External component signals on the hardware interface closely follow the semantics
+of the :ref:`cpuif_protocol`.
+
+
+Things you should know
+----------------------
+
+* By default external ``hwif_out`` signals are driven combinationally. An
+  optional output retiming stage can be enabled if needed.
+* Due to the uncertain access latency of external components, the regblock will
+  always enforce that only one outstanding transaction to an external component
+  at a time. This is enforced even if the CPUIF is capable of pipelined accesses
+  such as AXI4-Lite.
+
+
+External Registers
+------------------
+External registers can be useful if it is necessary to implement a register that
+cannot easily be expressed using SystemRDL semantics. This could be a unique
+access policy, or FIFO-like push/pop registers.
+
+External registers are annotated as such by using the ``external`` keyword:
+
+.. code-block:: systemrdl
+
+    # An internal register
+    my_reg int_reg;
+
+    # An external register
+    external my_reg ext_reg;
+
+Request
+^^^^^^^
+hwif_out..req
+    When asserted, a read or write transfer will be initiated.
+    Qualifies all other request signals.
+
+    If a register is wide (``regwidth`` > ``accesswidth``), then the
+    ``hwif_out..req`` will consist of multiple bits, representing the access
+    strobe for each sub-word of the register.
+
+hwif_out..req_is_wr
+    If ``1``, denotes that the current transfer is a write. Otherwise transfer is
+    a read.
+
+hwif_out..wr_data
+    Data to be written for the write transfer. This signal is ignored for read
+    transfers.
+
+    The bit-width of this signal always matches the CPUIF's bus width,
+    regardless of the regwidth.
+
+hwif_out..wr_biten
+    Active-high bit-level write-enable strobes.
+    Only asserted bit positions will change the register value during a write
+    transfer.
+
+
+Read Response
+^^^^^^^^^^^^^
+hwif_in..rd_ack
+    Single-cycle strobe indicating a read transfer has completed.
+    Qualifies all other read response signals.
+
+hwif_in..rd_data
+    Read response data.
+
+Write Response
+^^^^^^^^^^^^^^
+hwif_in..wr_ack
+    Single-cycle strobe indicating a write transfer has completed.
+
+
+
+External Blocks
+---------------
+Broader external address regions can be represented by external block-like
+components such as ``addrmap``, ``regfile`` or ``mem`` elements.
+
+To ensure address decoding for external blocks is simple (only requires simple bit-pruning),
+blocks that are external to an exported regblock shall be aligned to their size.
+
+Request
+^^^^^^^
+hwif_out..req
+    When asserted, a read or write transfer will be initiated.
+    Qualifies all other request signals.
+
+hwif_out..addr
+    Byte-address of the transfer.
+
+    Address is always relative to the block's local addressing. i.e: The first
+    byte within an external block is represented as ``hwif_out..addr`` == 0,
+    regardless of the absolute address of the block.
+
+hwif_out..req_is_wr
+    If ``1``, denotes that the current transfer is a write. Otherwise transfer is
+    a read.
+
+hwif_out..wr_data
+    Data to be written for the write transfer. This signal is ignored for read
+    transfers.
+
+    The bit-width of this signal always matches the CPUIF's bus width,
+    regardless of the contents of the block.
+
+hwif_out..wr_biten
+    Active-high bit-level write-enable strobes.
+    Only asserted bit positions will change the register value during a write
+    transfer.
+
+Read Response
+^^^^^^^^^^^^^
+hwif_in..rd_ack
+    Single-cycle strobe indicating a read transfer has completed.
+    Qualifies all other read response signals.
+
+hwif_in..rd_data
+    Read response data.
+
+Write Response
+^^^^^^^^^^^^^^
+hwif_in..wr_ack
+    Single-cycle strobe indicating a write transfer has completed.

docs/udps/extended_swacc.rst

@@ -8,7 +8,7 @@ read and write operations - it is asserted on *all* software accesses.
 Similarly, the spec defines ``swmod`` which gets asserted on software writes,
 but can also get asserted if the field has on-read side-effects.
 
-What if you just wanted a plan and simple strobe that is asserted when software
+What if you just wanted a plain and simple strobe that is asserted when software
 reads or writes a field? The ``rd_swacc`` and ``wr_swacc`` UDPs provide this
 functionality.