bslathi19/PeakRDL-regblock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Doc updates

Browse Source
This commit is contained in:
Alex Mykyta
2023-08-03 22:53:22 -07:00
parent 5c3dd6e6bb
commit eef8f7cdb4
13 changed files with 118 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/api.rst
View File

@@ -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
)

9
docs/configuring.rst
View File

@@ -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"

18
docs/cpuif/apb.rst
View File

@@ -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`
Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
* Command line: ``--cpuif apb3``
* 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`
Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
* Command line: ``--cpuif apb4``
* 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`

9
docs/cpuif/avalon.rst
View File

@@ -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`
Interface Definition: :download:`avalon_mm_intf.sv <../../hdl-src/avalon_mm_intf.sv>`
* Command line: ``--cpuif avalon-mm``
* 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

9
docs/cpuif/axi4lite.rst
View File

@@ -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`
Interface Definition: :download:`axi4lite_intf.sv <../../hdl-src/axi4lite_intf.sv>`
* Command line: ``--cpuif axi4-lite``
* 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

27
docs/cpuif/customizing.rst
View File

@@ -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
---------------------------------------------
To make your custom CPUIF class visible to the `PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_,
provide an entry point linkage in your package's ``setup.py``. 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.
Loading into the PeakRDL command line tool
------------------------------------------
There are two ways to make your custom CPUIF class visible to the
`PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_.
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

3
docs/cpuif/passthrough.rst
View File

@@ -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`.

54
docs/index.rst
View File

@@ -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:

14
docs/props/rhs_props.rst
View File

@@ -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.

4
docs/rdl_features/external.rst
View File

@@ -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

6
docs/udps/extended_swacc.rst
View File

@@ -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.

6
docs/udps/read_buffering.rst
View File

@@ -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

6
docs/udps/write_buffering.rst
View File

@@ -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