Skip to content

Commit eef8f7c

Browse files
amykyta3amykyta3
committed
Doc updates
1 parent 5c3dd6e commit eef8f7c

File tree

13 files changed

+121
-95
lines changed

13 files changed

+121
-95
lines changed

‎docs/api.rst

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,50 @@
11
Exporter API
22
============
33

4+
If you are not using the `PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_,
5+
you can still generate regblocks programmaticaly using the exporter API:
6+
47
.. autoclass:: peakrdl_regblock.RegblockExporter
58
:members:
9+
10+
Example
11+
-------
12+
Below is a simple example that demonstrates how to generate a SystemVerilog
13+
implementation from SystemRDL source.
14+
15+
.. code-block:: python
16+
:emphasize-lines: 2-4, 29-33
17+
18+
from systemrdl import RDLCompiler, RDLCompileError
19+
from peakrdl_regblock import RegblockExporter
20+
from peakrdl_regblock.cpuif.axi4lite import AXI4Lite_Cpuif
21+
from peakrdl_regblock.udps import ALL_UDPS
22+
23+
input_files = [
24+
"PATH/TO/my_register_block.rdl"
25+
]
26+
27+
# Create an instance of the compiler
28+
rdlc = RDLCompiler()
29+
30+
# Register all UDPs that 'regblock' requires
31+
for udp in ALL_UDPS:
32+
rdlc.register_udp(udp)
33+
34+
try:
35+
# Compile your RDL files
36+
for input_file in input_files:
37+
rdlc.compile_file(input_file)
38+
39+
# Elaborate the design
40+
root = rdlc.elaborate()
41+
except RDLCompileError:
42+
# A compilation error occurred. Exit with error code
43+
sys.exit(1)
44+
45+
# Export a SystemVerilog implementation
46+
exporter = RegblockExporter()
47+
exporter.export(
48+
root, "path/to/output_dir",
49+
cpuif_cls=AXI4Lite_Cpuif
50+
)

‎docs/configuring.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _peakrdl_cfg:
2+
13
Configuring PeakRDL-regblock
24
============================
35

@@ -34,3 +36,10 @@ All regblock-specific options are defined under the ``[regblock]`` TOML heading.
3436
* ``rst_n``
3537
* ``arst``
3638
* ``arst_n``
39+
40+
For example:
41+
42+
.. code-block:: toml
43+
44+
[regblock]
45+
default_reset = "arst"

‎docs/cpuif/apb.rst

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,15 @@ CPU interface.
2727
The APB3 CPU interface comes in two i/o port flavors:
2828

2929
SystemVerilog Interface
30-
Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif`
31-
32-
Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
30+
* Command line: ``--cpuif apb3``
31+
* Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
32+
* Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif`
3333

3434
Flattened inputs/outputs
3535
Flattens the interface into discrete input and output ports.
3636

37-
Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif_flattened`
37+
* Command line: ``--cpuif apb3-flat``
38+
* Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif_flattened`
3839

3940

4041
APB4
@@ -47,11 +48,12 @@ CPU interface.
4748
The APB4 CPU interface comes in two i/o port flavors:
4849

4950
SystemVerilog Interface
50-
Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif`
51-
52-
Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
51+
* Command line: ``--cpuif apb4``
52+
* Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
53+
* Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif`
5354

5455
Flattened inputs/outputs
5556
Flattens the interface into discrete input and output ports.
5657

57-
Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif_flattened`
58+
* Command line: ``--cpuif apb4-flat``
59+
* Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif_flattened`

‎docs/cpuif/avalon.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,15 @@ CPU interface.
88
The Avalon interface comes in two i/o port flavors:
99

1010
SystemVerilog Interface
11-
Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif`
12-
13-
Interface Definition: :download:`avalon_mm_intf.sv <../../hdl-src/avalon_mm_intf.sv>`
11+
* Command line: ``--cpuif avalon-mm``
12+
* Interface Definition: :download:`avalon_mm_intf.sv <../../hdl-src/avalon_mm_intf.sv>`
13+
* Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif`
1414

1515
Flattened inputs/outputs
1616
Flattens the interface into discrete input and output ports.
1717

18-
Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif_flattened`
18+
* Command line: ``--cpuif avalon-mm-flat``
19+
* Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif_flattened`
1920

2021

2122
Implementation Details

‎docs/cpuif/axi4lite.rst

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,15 @@ CPU interface.
1010
The AXI4-Lite CPU interface comes in two i/o port flavors:
1111

1212
SystemVerilog Interface
13-
Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif`
14-
15-
Interface Definition: :download:`axi4lite_intf.sv <../../hdl-src/axi4lite_intf.sv>`
13+
* Command line: ``--cpuif axi4-lite``
14+
* Interface Definition: :download:`axi4lite_intf.sv <../../hdl-src/axi4lite_intf.sv>`
15+
* Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif`
1616

1717
Flattened inputs/outputs
1818
Flattens the interface into discrete input and output ports.
1919

20-
Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif_flattened`
20+
* Command line: ``--cpuif axi4-lite-flat``
21+
* Class: :class:`peakrdl_regblock.cpuif.axi4lite.AXI4Lite_Cpuif_flattened`
2122

2223

2324
Pipelined Performance

‎docs/cpuif/customizing.rst

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,8 @@ you can define your own.
6565
in this shall implement a translation between your custom protocol and the
6666
:ref:`cpuif_protocol`.
6767

68-
Reminder that this template will be preprocessed using Jinja, so you can use
68+
Reminder that this template will be preprocessed using
69+
`Jinja <https://jinja.palletsprojects.com>`_, so you can use
6970
some templating tags to dynamically render content. See the implementations of
7071
existing CPU interfaces as an example.
7172

@@ -75,16 +76,26 @@ you can define your own.
7576
Define the port declaration string, and provide a reference to your template file.
7677

7778
3. Use your new CPUIF definition when exporting.
78-
4. If you think the CPUIF protocol is something others might find useful, let me know and I can add it to PeakRDL!
79-
80-
81-
Entry point for the PeakRDL command line tool
82-
---------------------------------------------
83-
To make your custom CPUIF class visible to the `PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_,
84-
provide an entry point linkage in your package's ``setup.py``. This advertises
85-
your custom CPUIF class to the PeakRDL-regblock tool as a plugin that should be
86-
loaded, and made available as a command-line option in PeakRDL.
87-
79+
4. If you think the CPUIF protocol is something others might find useful, let me
80+
know and I can add it to PeakRDL!
81+
82+
83+
Loading into the PeakRDL command line tool
84+
------------------------------------------
85+
There are two ways to make your custom CPUIF class visible to the
86+
`PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_.
87+
88+
Via the PeakRDL TOML
89+
^^^^^^^^^^^^^^^^^^^^
90+
The easiest way to add your cpuif is via the TOML config file. See the
91+
:ref:`peakrdl_cfg` section for more details.
92+
93+
Via a package's entry point definition
94+
--------------------------------------
95+
If you are publishing a collecxtion of PeakRDL plugins as an installable Python
96+
package, you can advertise them to PeakRDL using an entry point.
97+
This advertises your custom CPUIF class to the PeakRDL-regblock tool as a plugin
98+
that should be loaded, and made available as a command-line option in PeakRDL.
8899

89100
.. code-block:: python
90101
:emphasize-lines: 7-11

‎docs/cpuif/passthrough.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ CPUIF Passthrough
44
This CPUIF mode bypasses the protocol converter stage and directly exposes the
55
internal CPUIF handshake signals to the user.
66

7-
Class: :class:`peakrdl_regblock.cpuif.passthrough.PassthroughCpuif`
7+
* Command line: ``--cpuif passthrough``
8+
* Class: :class:`peakrdl_regblock.cpuif.passthrough.PassthroughCpuif`
89

910
For more details on the protocol itself, see: :ref:`cpuif_protocol`.

‎docs/index.rst

Lines changed: 7 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -31,57 +31,17 @@ Install from `PyPi`_ using pip
3131

3232

3333

34-
Quick Start - PeakRDL
35-
---------------------
34+
Example
35+
-------
3636
The easiest way is to use the `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_:
3737

3838
.. code-block:: bash
3939
40-
peakrdl regblock atxmega_spi.rdl -o regblock/ --cpuif axi4-lite
41-
42-
43-
Quick Start - API
44-
-----------------
45-
Otherwise if you want, there is a Python API.
46-
Below is a simple example that demonstrates how to generate a SystemVerilog
47-
implementation from SystemRDL source.
48-
49-
.. code-block:: python
50-
:emphasize-lines: 2-4, 29-33
51-
52-
from systemrdl import RDLCompiler, RDLCompileError
53-
from peakrdl_regblock import RegblockExporter
54-
from peakrdl_regblock.cpuif.axi4lite import AXI4Lite_Cpuif
55-
from peakrdl_regblock.udps import ALL_UDPS
56-
57-
input_files = [
58-
"PATH/TO/my_register_block.rdl"
59-
]
60-
61-
# Create an instance of the compiler
62-
rdlc = RDLCompiler()
40+
# Install the command line tool
41+
python3 -m pip install peakrdl
6342
64-
# Register all UDPs that 'regblock' requires
65-
for udp in ALL_UDPS:
66-
rdlc.register_udp(udp)
67-
68-
try:
69-
# Compile your RDL files
70-
for input_file in input_files:
71-
rdlc.compile_file(input_file)
72-
73-
# Elaborate the design
74-
root = rdlc.elaborate()
75-
except RDLCompileError:
76-
# A compilation error occurred. Exit with error code
77-
sys.exit(1)
78-
79-
# Export a SystemVerilog implementation
80-
exporter = RegblockExporter()
81-
exporter.export(
82-
root, "path/to/output_dir",
83-
cpuif_cls=AXI4Lite_Cpuif
84-
)
43+
# Export!
44+
peakrdl regblock atxmega_spi.rdl -o regblock/ --cpuif axi4-lite
8545
8646
8747
Links
@@ -101,9 +61,9 @@ Links
10161
architecture
10262
hwif
10363
configuring
104-
api
10564
limitations
10665
licensing
66+
api
10767

10868
.. toctree::
10969
:hidden:

‎docs/props/rhs_props.rst

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -53,8 +53,6 @@ Represents the signal that controls the field's hwenable/hwmask behavior.
5353

5454
field -> we/wel
5555
^^^^^^^^^^^^^^^
56-
|EX|
57-
5856
Represents the signal that controls the field's we/wel behavior.
5957

6058
field -> next
@@ -63,11 +61,11 @@ field -> next
6361

6462
field -> reset
6563
^^^^^^^^^^^^^^
66-
|EX|
64+
Represents the value that was assigned to this property.
6765

6866
field -> resetsignal
6967
^^^^^^^^^^^^^^^^^^^^
70-
|EX|
68+
Represents the value that was assigned to this property.
7169

7270
--------------------------------------------------------------------------------
7371

@@ -81,8 +79,6 @@ Represents the signal that controls the field's counter increment control.
8179

8280
field -> incrsaturate/saturate
8381
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
84-
|EX|
85-
8682
Represents the internal 1-bit event signal that indicates whether the counter is saturated
8783
at its saturation value.
8884

@@ -103,8 +99,6 @@ at its saturation value.
10399

104100
field -> incrthreshold/threshold
105101
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
106-
|EX|
107-
108102
Represents the 1-bit event signal that indicates whether the counter has met or
109103
exceeded its incrthreshold.
110104

@@ -122,8 +116,6 @@ Represents the signal that controls the field's counter decrement control.
122116

123117
field -> decrsaturate
124118
^^^^^^^^^^^^^^^^^^^^^
125-
|EX|
126-
127119
Represents the internal 1-bit event signal that indicates whether the counter is saturated
128120
at its saturation value.
129121

@@ -143,8 +135,6 @@ at its saturation value.
143135

144136
field -> decrthreshold
145137
^^^^^^^^^^^^^^^^^^^^^^
146-
|EX|
147-
148138
Represents the 1-bit event signal that indicates whether the counter has met or
149139
exceeded its incrthreshold.
150140

‎docs/rdl_features/external.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,10 @@ External registers are annotated as such by using the ``external`` keyword:
3232

3333
.. code-block:: systemrdl
3434
35-
# An internal register
35+
// An internal register
3636
my_reg int_reg;
3737
38-
# An external register
38+
// An external register
3939
external my_reg ext_reg;
4040
4141
Request

0 commit comments

Comments
 (0)