diff --git a/docs/api.rst b/docs/api.rst index c92fd68..b949c0f 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,5 +1,50 @@ Exporter API ============ +If you are not using the `PeakRDL command-line tool `_, +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 + ) diff --git a/docs/configuring.rst b/docs/configuring.rst index 4f1dd39..425ecee 100644 --- a/docs/configuring.rst +++ b/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" diff --git a/docs/cpuif/apb.rst b/docs/cpuif/apb.rst index 7cc149e..efec7d8 100644 --- a/docs/cpuif/apb.rst +++ b/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` - - 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` diff --git a/docs/cpuif/avalon.rst b/docs/cpuif/avalon.rst index 547c508..2ae8a04 100644 --- a/docs/cpuif/avalon.rst +++ b/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` - - 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 diff --git a/docs/cpuif/axi4lite.rst b/docs/cpuif/axi4lite.rst index 7d0860d..255be14 100644 --- a/docs/cpuif/axi4lite.rst +++ b/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` - - 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 diff --git a/docs/cpuif/customizing.rst b/docs/cpuif/customizing.rst index b9a2c6e..4f888f5 100644 --- a/docs/cpuif/customizing.rst +++ b/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 `_, 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 `_, -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 `_. +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 diff --git a/docs/cpuif/passthrough.rst b/docs/cpuif/passthrough.rst index 89dbd6b..0bfb2d7 100644 --- a/docs/cpuif/passthrough.rst +++ b/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`. diff --git a/docs/index.rst b/docs/index.rst index 7e7ed7b..3cca0ce 100644 --- a/docs/index.rst +++ b/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 `_: .. 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: diff --git a/docs/props/rhs_props.rst b/docs/props/rhs_props.rst index f7f3cb1..6234bd5 100644 --- a/docs/props/rhs_props.rst +++ b/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. diff --git a/docs/rdl_features/external.rst b/docs/rdl_features/external.rst index b2d62d9..2032b5b 100644 --- a/docs/rdl_features/external.rst +++ b/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 diff --git a/docs/udps/extended_swacc.rst b/docs/udps/extended_swacc.rst index 7280a77..f760275 100644 --- a/docs/udps/extended_swacc.rst +++ b/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. diff --git a/docs/udps/read_buffering.rst b/docs/udps/read_buffering.rst index e905fc7..3f61b89 100644 --- a/docs/udps/read_buffering.rst +++ b/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 diff --git a/docs/udps/write_buffering.rst b/docs/udps/write_buffering.rst index 42d92c8..1d5d2ba 100644 --- a/docs/udps/write_buffering.rst +++ b/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