Doc updates

docs/api.rst

@@ -1,5 +1,50 @@
 Exporter API
 ============
 
+If you are not using the `PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_,
+you can still generate regblocks programmaticaly using the exporter API:
+
 .. autoclass:: peakrdl_regblock.RegblockExporter
     :members:
+
+Example
+-------
+Below is a simple example that demonstrates how to generate a SystemVerilog
+implementation from SystemRDL source.
+
+.. code-block:: python
+    :emphasize-lines: 2-4, 29-33
+
+    from systemrdl import RDLCompiler, RDLCompileError
+    from peakrdl_regblock import RegblockExporter
+    from peakrdl_regblock.cpuif.axi4lite import AXI4Lite_Cpuif
+    from peakrdl_regblock.udps import ALL_UDPS
+
+    input_files = [
+        "PATH/TO/my_register_block.rdl"
+    ]
+
+    # Create an instance of the compiler
+    rdlc = RDLCompiler()
+
+    # Register all UDPs that 'regblock' requires
+    for udp in ALL_UDPS:
+        rdlc.register_udp(udp)
+
+    try:
+        # Compile your RDL files
+        for input_file in input_files:
+            rdlc.compile_file(input_file)
+
+        # Elaborate the design
+        root = rdlc.elaborate()
+    except RDLCompileError:
+        # A compilation error occurred. Exit with error code
+        sys.exit(1)
+
+    # Export a SystemVerilog implementation
+    exporter = RegblockExporter()
+    exporter.export(
+        root, "path/to/output_dir",
+        cpuif_cls=AXI4Lite_Cpuif
+    )

docs/configuring.rst

@@ -1,3 +1,5 @@
+.. _peakrdl_cfg:
+
 Configuring PeakRDL-regblock
 ============================
 
@@ -34,3 +36,10 @@ All regblock-specific options are defined under the ``[regblock]`` TOML heading.
         * ``rst_n``
         * ``arst``
         * ``arst_n``
+
+    For example:
+
+    .. code-block:: toml
+
+        [regblock]
+        default_reset = "arst"

docs/cpuif/apb.rst

@@ -27,14 +27,15 @@ CPU interface.
 The APB3 CPU interface comes in two i/o port flavors:
 
 SystemVerilog Interface
-    Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif`
+    * Command line: ``--cpuif apb3``
-
+    * Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
-    Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
+    * Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
-    Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif_flattened`
+    * Command line: ``--cpuif apb3-flat``
+    * Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif_flattened`
 
 
 APB4
@@ -47,11 +48,12 @@ CPU interface.
 The APB4 CPU interface comes in two i/o port flavors:
 
 SystemVerilog Interface
-    Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif`
+    * Command line: ``--cpuif apb4``
-
+    * Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
-    Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
+    * Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
-    Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif_flattened`
+    * Command line: ``--cpuif apb4-flat``
+    * Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif_flattened`

docs/cpuif/avalon.rst

@@ -8,14 +8,15 @@ CPU interface.
 The Avalon interface comes in two i/o port flavors:
 
 SystemVerilog Interface
-    Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif`
+    * Command line: ``--cpuif avalon-mm``
-
+    * Interface Definition: :download:`avalon_mm_intf.sv <../../hdl-src/avalon_mm_intf.sv>`
-    Interface Definition: :download:`avalon_mm_intf.sv <../../hdl-src/avalon_mm_intf.sv>`
+    * Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
-    Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif_flattened`
+    * Command line: ``--cpuif avalon-mm-flat``
+    * Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif_flattened`
 
 
 Implementation Details

docs/cpuif/axi4lite.rst

@@ -10,14 +10,15 @@ CPU interface.
 The AXI4-Lite CPU interface comes in two i/o port flavors:
 
 SystemVerilog Interface
-    Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif`
+    * Command line: ``--cpuif axi4-lite``
-
+    * Interface Definition: :download:`axi4lite_intf.sv <../../hdl-src/axi4lite_intf.sv>`
-    Interface Definition: :download:`axi4lite_intf.sv <../../hdl-src/axi4lite_intf.sv>`
+    * Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
-    Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif_flattened`
+    * Command line: ``--cpuif axi4-lite-flat``
+    * Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif_flattened`
 
 
 Pipelined Performance

docs/cpuif/customizing.rst

@@ -65,7 +65,8 @@ you can define your own.
     in this shall implement a translation between your custom protocol and the
     :ref:`cpuif_protocol`.
 
-    Reminder that this template will be preprocessed using Jinja, so you can use
+    Reminder that this template will be preprocessed using
+    `Jinja <https://jinja.palletsprojects.com>`_, so you can use
     some templating tags to dynamically render content. See the implementations of
     existing CPU interfaces as an example.
 
@@ -75,16 +76,26 @@ you can define your own.
     Define the port declaration string, and provide a reference to your template file.
 
 3. Use your new CPUIF definition when exporting.
-4. If you think the CPUIF protocol is something others might find useful, let me know and I can add it to PeakRDL!
+4. If you think the CPUIF protocol is something others might find useful, let me
+   know and I can add it to PeakRDL!
 
 
-Entry point for the PeakRDL command line tool
+Loading into the PeakRDL command line tool
----------------------------------------------
+------------------------------------------
-To make your custom CPUIF class visible to the `PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_,
+There are two ways to make your custom CPUIF class visible to the
-provide an entry point linkage in your package's ``setup.py``. This advertises
+`PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_.
-your custom CPUIF class to the PeakRDL-regblock tool as a plugin that should be
-loaded, and made available as a command-line option in PeakRDL.
 
+Via the PeakRDL TOML
+^^^^^^^^^^^^^^^^^^^^
+The easiest way to add your cpuif is via the TOML config file. See the
+:ref:`peakrdl_cfg` section for more details.
+
+Via a package's entry point definition
+--------------------------------------
+If you are publishing a collecxtion of PeakRDL plugins as an installable Python
+package, you can advertise them to PeakRDL using an entry point.
+This advertises your custom CPUIF class to the PeakRDL-regblock tool as a plugin
+that should be loaded, and made available as a command-line option in PeakRDL.
 
 .. code-block:: python
     :emphasize-lines: 7-11

docs/cpuif/passthrough.rst

@@ -4,6 +4,7 @@ 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`
+* Command line: ``--cpuif passthrough``
+* Class: :class:`peakrdl_regblock.cpuif.passthrough.PassthroughCpuif`
 
 For more details on the protocol itself, see: :ref:`cpuif_protocol`.

docs/index.rst

@@ -31,59 +31,19 @@ Install from `PyPi`_ using pip
 
 
 
-Quick Start - PeakRDL
+Example
----------------------
+-------
 The easiest way is to use the `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_:
 
 .. code-block:: bash
 
+    # Install the command line tool
+    python3 -m pip install peakrdl
+
+    # Export!
     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.
-
-.. code-block:: python
-    :emphasize-lines: 2-4, 29-33
-
-    from systemrdl import RDLCompiler, RDLCompileError
-    from peakrdl_regblock import RegblockExporter
-    from peakrdl_regblock.cpuif.axi4lite import AXI4Lite_Cpuif
-    from peakrdl_regblock.udps import ALL_UDPS
-
-    input_files = [
-        "PATH/TO/my_register_block.rdl"
-    ]
-
-    # Create an instance of the compiler
-    rdlc = RDLCompiler()
-
-    # Register all UDPs that 'regblock' requires
-    for udp in ALL_UDPS:
-        rdlc.register_udp(udp)
-
-    try:
-        # Compile your RDL files
-        for input_file in input_files:
-            rdlc.compile_file(input_file)
-
-        # Elaborate the design
-        root = rdlc.elaborate()
-    except RDLCompileError:
-        # A compilation error occurred. Exit with error code
-        sys.exit(1)
-
-    # Export a SystemVerilog implementation
-    exporter = RegblockExporter()
-    exporter.export(
-        root, "path/to/output_dir",
-        cpuif_cls=AXI4Lite_Cpuif
-    )
-
-
 Links
 -----
 
@@ -101,9 +61,9 @@ Links
     architecture
     hwif
     configuring
-    api
     limitations
     licensing
+    api
 
 .. toctree::
     :hidden:

docs/props/rhs_props.rst

@@ -53,8 +53,6 @@ Represents the signal that controls the field's hwenable/hwmask behavior.
 
 field -> we/wel
 ^^^^^^^^^^^^^^^
-|EX|
-
 Represents the signal that controls the field's we/wel behavior.
 
 field -> next
@@ -63,11 +61,11 @@ field -> next
 
 field -> reset
 ^^^^^^^^^^^^^^
-|EX|
+Represents the value that was assigned to this property.
 
 field -> resetsignal
 ^^^^^^^^^^^^^^^^^^^^
-|EX|
+Represents the value that was assigned to this property.
 
 --------------------------------------------------------------------------------
 
@@ -81,8 +79,6 @@ Represents the signal that controls the field's counter increment control.
 
 field -> incrsaturate/saturate
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-|EX|
-
 Represents the internal 1-bit event signal that indicates whether the counter is saturated
 at its saturation value.
 
@@ -103,8 +99,6 @@ at its saturation value.
 
 field -> incrthreshold/threshold
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-|EX|
-
 Represents the 1-bit event signal that indicates whether the counter has met or
 exceeded its incrthreshold.
 
@@ -122,8 +116,6 @@ Represents the signal that controls the field's counter decrement control.
 
 field -> decrsaturate
 ^^^^^^^^^^^^^^^^^^^^^
-|EX|
-
 Represents the internal 1-bit event signal that indicates whether the counter is saturated
 at its saturation value.
 
@@ -143,8 +135,6 @@ at its saturation value.
 
 field -> decrthreshold
 ^^^^^^^^^^^^^^^^^^^^^^
-|EX|
-
 Represents the 1-bit event signal that indicates whether the counter has met or
 exceeded its incrthreshold.
 

docs/rdl_features/external.rst

@@ -32,10 +32,10 @@ External registers are annotated as such by using the ``external`` keyword:
 
 .. code-block:: systemrdl
 
-    # An internal register
+    // An internal register
     my_reg int_reg;
 
-    # An external register
+    // An external register
     external my_reg ext_reg;
 
 Request

docs/udps/extended_swacc.rst

@@ -19,7 +19,8 @@ These UDP definitions, along with others supported by PeakRDL-regblock can be
 enabled by compiling the following file along with your design:
 :download:`regblock_udps.rdl <../../hdl-src/regblock_udps.rdl>`.
 
-``rd_swacc``
+.. describe:: rd_swacc
+
     If true, infers an output signal ``hwif_out..rd_swacc`` that is asserted
     when accessed by a software read operation. The output signal is asserted
     on the same clock cycle that the field is being sampled during the software
@@ -34,7 +35,8 @@ enabled by compiling the following file along with your design:
         ]}
 
 
-``wr_swacc``
+.. describe:: wr_swacc
+
     If true, infers an output signal ``hwif_out..wr_swacc`` that is asserted
     as the field is being modified by a software write operation.
 

docs/udps/read_buffering.rst

@@ -31,7 +31,8 @@ These UDP definitions, along with others supported by PeakRDL-regblock can be
 enabled by compiling the following file along with your design:
 :download:`regblock_udps.rdl <../../hdl-src/regblock_udps.rdl>`.
 
-``buffer_reads``
+.. describe:: buffer_reads
+
     *   Assigned value is a boolean.
     *   If true, enables double-buffering of software reads of this register.
     *   The read buffer will load the register's field values when its trigger
@@ -41,7 +42,8 @@ enabled by compiling the following file along with your design:
     *   When read by software the data returned is from the buffer contents, not
         directly from the register's fields.
 
-``rbuffer_trigger``
+.. describe:: rbuffer_trigger
+
     *   Assigned value is a reference to a register, single-bit field, signal, or
         single-bit property.
     *   Controls when the double-buffer loads the register's field vaues into the

docs/udps/write_buffering.rst

@@ -37,7 +37,8 @@ These UDP definitions, along with others supported by PeakRDL-regblock can be
 enabled by compiling the following file along with your design:
 :download:`regblock_udps.rdl <../../hdl-src/regblock_udps.rdl>`.
 
-``buffer_writes``
+.. describe:: buffer_writes
+
     *   Assigned value is a boolean.
     *   If true, enables double-buffering of writes to this register.
     *   Any software write operation to a buffered register is held back in a
@@ -47,7 +48,8 @@ enabled by compiling the following file along with your design:
     *   Unless specified otherwise, the buffer trigger occurs when the highest
         address of the buffered register is written.
 
-``wbuffer_trigger``
+.. describe:: wbuffer_trigger
+
     *   Assigned value is a reference to a register, single-bit field, signal,
         or single-bit property.
     *   Controls when the double-buffer commits the software write operation to