VHDL updates for readthedocs documentation (#19)

* update README
* updated readthedocs for VHDL
* updated many missed references to systemverilog exporter
* added note in quick start about hdl-src/ files

Author: darsor

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to the PeakRDL-regblock code generator
+# Contributing to the PeakRDL-regblock-vhdl code generator
 We love your input! We want to make contributing to this project as easy and
 transparent as possible, whether it's:
 
@@ -9,13 +9,14 @@ transparent as possible, whether it's:
 - Becoming a maintainer
 
 
-## Open an issue using the [Issue Tracker](https://github.com/SystemRDL/PeakRDL-regblock/issues)
+## Open an issue using the [Issue Tracker](https://github.com/SystemRDL/PeakRDL-regblock-vhdl/issues)
 Talking to us is the easiest way to contribute! Report a bug or feature request by
-[opening a new issue](https://github.com/SystemRDL/PeakRDL-regblock/issues).
+[opening a new issue](https://github.com/SystemRDL/PeakRDL-regblock-vhdl/issues).
 
 Issue submission expectations:
 * Please keep each issue submission limited to one topic. This helps us stay organized.
 * Before opening an issue, check if one already exists for your topic. It may have already been discussed.
+    * Check the upstream SystemVerilog regblock exporter [issue tracker](https://github.com/SystemRDL/PeakRDL-regblock/issues) as well.
 * If submitting a bug, provide enough details so we can reproduce it on our end. (version number, example SystemRDL, etc...)
 * If submitting a feature request, please make sure ...
     * ... it does not violate the semantics of the SystemRDL standard.

README.md

@@ -1,32 +1,35 @@
-[![Documentation Status](https://readthedocs.org/projects/peakrdl-regblock/badge/?version=latest)](http://peakrdl-regblock.readthedocs.io)
+[![Documentation Status](https://readthedocs.org/projects/peakrdl-regblock-vhdl/badge/?version=latest)](http://peakrdl-regblock-vhdl.readthedocs.io)
 [![build](https://github.com/SystemRDL/PeakRDL-regblock-vhdl/workflows/build/badge.svg)](https://github.com/SystemRDL/PeakRDL-regblock-vhdl/actions?query=workflow%3Abuild+branch%3Amain)
 [![Coverage Status](https://coveralls.io/repos/github/SystemRDL/PeakRDL-regblock-vhdl/badge.svg?branch=main)](https://coveralls.io/github/SystemRDL/PeakRDL-regblock-vhdl?branch=main)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/peakrdl-regblock-vhdl.svg)](https://pypi.org/project/peakrdl-regblock-vhdl)
 
 # PeakRDL-regblock-vhdl
-Compile SystemRDL into a VHDL control/status register (CSR) block. This is a VHDL port of the [SystemVerliog PeakRDL-regblock exporter](https://github.com/SystemRDL/PeakRDL-regblock).
+Compile SystemRDL into a VHDL control/status register (CSR) block.
 
 For the command line tool, see the [PeakRDL project](https://peakrdl.readthedocs.io).
 
 ## Documentation
-See the [PeakRDL-regblock Documentation](http://peakrdl-regblock.readthedocs.io) for more details
+See the [PeakRDL-regblock-vhdl Documentation](http://peakrdl-regblock-vhdl.readthedocs.io) for more details
 
 ## Relationship with PeakRDL-regblock
-This is a direct port of the SystemVerilog regblock generator PeakRDL-regblock. Updates from the upstream regblock implementation are converted to VHDL and merged into this repository.
+This is a direct VHDL translation of the SystemVerilog regblock generator [PeakRDL-regblock](https://github.com/SystemRDL/PeakRDL-regblock). Updates from the upstream regblock implementation are converted to VHDL and merged into this repository.
+
+### Goals
+
+- Maintain feature parity with the upstream SystemVerilog implementation.
+- Keep the code structure as close as possible to upstream to allow merging future updates.
+- Keep the unit tests as close as possible to upstream. In most cases they are unchanged.
+   - Tests are written in SystemVerilog and an auto-generated test adapter is used to instantiate the VHDL regblock under test.
 
 ### Versioning
 
-Version numbers track those in the upstream repository, with an added segment. For example, the VHDL version 0.23.0.0 would indicate the first release matching the functionality of the upstream version 0.23.0. Version 0.23.0.1 would indicate a patch update unique to the VHDL port.
+Version numbers track those in the upstream repository with an added segment. For example, the VHDL version 1.0.0.0 would indicate the first release matching the functionality of the upstream version 1.0.0. Version 1.0.0.1 would indicate a patch update unique to the VHDL port.
 
 In some cases (such as git tags), a `+vhdl` metadata specifier is suffixed to help differentiate from the upstream versions.
 
 ### Issue Reporting
 
-If you encounter an issue,
+If you encounter an issue or want to suggest a feature,
 1. Check if it is already reported in the upstream repository's [issue tracker](https://github.com/SystemRDL/PeakRDL-regblock/issues).
 2. Report it in the upstream repository unless you are sure it's unique to the VHDL port. If you are unsure, report it here and it may be moved upstream if deemed appropriate.
 3. The upstream fix will be merged into this VHDL port.
-
-### Unit Tests
-
-Unit tests are kept as close as possible to upstream. In most cases they are unchanged. They are written in SystemVerilog. An auto-generated test adapter is used to instantiate the VHDL regblock for test.

docs/api.rst

@@ -4,21 +4,21 @@ Exporter API
 If you are not using the `PeakRDL command-line tool <https://peakrdl.readthedocs.io>`_,
 you can still generate regblocks programmatically using the exporter API:
 
-.. autoclass:: peakrdl_regblock.RegblockExporter
+.. autoclass:: peakrdl_regblock_vhdl.RegblockExporter
     :members:
 
 Example
 -------
-Below is a simple example that demonstrates how to generate a SystemVerilog
+Below is a simple example that demonstrates how to generate a VHDL
 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
+    from peakrdl_regblock_vhdl import RegblockExporter
+    from peakrdl_regblock_vhdl.cpuif.axi4lite import AXI4Lite_Cpuif
+    from peakrdl_regblock_vhdl.udps import ALL_UDPS
 
     input_files = [
         "PATH/TO/my_register_block.rdl"
@@ -42,7 +42,7 @@ implementation from SystemRDL source.
         # A compilation error occurred. Exit with error code
         sys.exit(1)
 
-    # Export a SystemVerilog implementation
+    # Export a VHDL implementation
     exporter = RegblockExporter()
     exporter.export(
         root, "path/to/output_dir",

docs/architecture.rst

@@ -3,7 +3,7 @@ Register Block Architecture
 
 The generated register block RTL is organized into several sections.
 Each section is automatically generated based on the source register model and
-is rendered into the output register block SystemVerilog RTL.
+is rendered into the output register block VHDL RTL.
 
 .. figure:: diagrams/arch.png
 

docs/conf.py

@@ -18,7 +18,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'PeakRDL-regblock'
+project = 'PeakRDL-regblock-vhdl'
 copyright = '%d, Alex Mykyta' % datetime.datetime.now().year
 author = 'Alex Mykyta'
 

docs/configuring.rst

@@ -1,13 +1,13 @@
 .. _peakrdl_cfg:
 
-Configuring PeakRDL-regblock
-============================
+Configuring PeakRDL-regblock-vhdl
+=================================
 
 If using the `PeakRDL command line tool <https://peakrdl.readthedocs.io/>`_,
 some aspects of the ``regblock`` command have additional configuration options
 available via the PeakRDL TOML file.
 
-All regblock-specific options are defined under the ``[regblock]`` TOML heading.
+All VHDL regblock-specific options are defined under the ``[regblock-vhdl]`` TOML heading.
 
 .. data:: cpuifs
 
@@ -20,7 +20,7 @@ All regblock-specific options are defined under the ``[regblock]`` TOML heading.
 
     .. code-block:: toml
 
-        [regblock]
+        [regblock-vhdl]
         cpuifs.my-cpuif-name = "my_cpuif_module:MyCPUInterfaceClass"
 
 
@@ -41,5 +41,5 @@ All regblock-specific options are defined under the ``[regblock]`` TOML heading.
 
     .. code-block:: toml
 
-        [regblock]
+        [regblock-vhdl]
         default_reset = "arst"

docs/cpuif/apb.rst

@@ -26,16 +26,16 @@ CPU interface.
 
 The APB3 CPU interface comes in two i/o port flavors:
 
-SystemVerilog Interface
+VHDL Record Interface
     * Command line: ``--cpuif apb3``
-    * Interface Definition: :download:`apb3_intf.sv <../../hdl-src/apb3_intf.sv>`
-    * Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif`
+    * Interface Definition: :download:`apb3_intf_pkg.vhd <../../hdl-src/apb3_intf_pkg.vhd>`
+    * Class: :class:`peakrdl_regblock_vhdl.cpuif.apb3.APB3_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
     * Command line: ``--cpuif apb3-flat``
-    * Class: :class:`peakrdl_regblock.cpuif.apb3.APB3_Cpuif_flattened`
+    * Class: :class:`peakrdl_regblock_vhdl.cpuif.apb3.APB3_Cpuif_flattened`
 
 
 APB4
@@ -47,13 +47,13 @@ CPU interface.
 
 The APB4 CPU interface comes in two i/o port flavors:
 
-SystemVerilog Interface
+VHDL Record Interface
     * Command line: ``--cpuif apb4``
-    * Interface Definition: :download:`apb4_intf.sv <../../hdl-src/apb4_intf.sv>`
-    * Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif`
+    * Interface Definition: :download:`apb4_intf_pkg.vhd <../../hdl-src/apb4_intf_pkg.vhd>`
+    * Class: :class:`peakrdl_regblock_vhdl.cpuif.apb4.APB4_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
     * Command line: ``--cpuif apb4-flat``
-    * Class: :class:`peakrdl_regblock.cpuif.apb4.APB4_Cpuif_flattened`
+    * Class: :class:`peakrdl_regblock_vhdl.cpuif.apb4.APB4_Cpuif_flattened`

docs/cpuif/avalon.rst

@@ -7,16 +7,16 @@ CPU interface.
 
 The Avalon interface comes in two i/o port flavors:
 
-SystemVerilog Interface
+VHDL Record Interface
     * 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`
+    * Interface Definition: :download:`avalon_mm_intf_pkg.vhd <../../hdl-src/avalon_mm_intf_pkg.vhd>`
+    * Class: :class:`peakrdl_regblock_vhdl.cpuif.avalon.Avalon_Cpuif`
 
 Flattened inputs/outputs
     Flattens the interface into discrete input and output ports.
 
     * Command line: ``--cpuif avalon-mm-flat``
-    * Class: :class:`peakrdl_regblock.cpuif.avalon.Avalon_Cpuif_flattened`
+    * Class: :class:`peakrdl_regblock_vhdl.cpuif.avalon.Avalon_Cpuif_flattened`
 
 
 Implementation Details

docs/cpuif/axi4lite.rst

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

docs/cpuif/customizing.rst

@@ -1,45 +1,57 @@
 Customizing the CPU interface
 =============================
 
-Use your own existing SystemVerilog interface definition
+Use your own existing VHDL record definition
 --------------------------------------------------------
 
-This exporter comes pre-bundled with its own SystemVerilog interface declarations.
-What if you already have your own SystemVerilog interface declaration that you prefer?
+This exporter comes pre-bundled with its own VHDL record interface declarations.
+What if you already have your own VHDL record declaration that you prefer?
 
 Not a problem! As long as your interface definition is similar enough, it is easy
-to customize and existing CPUIF definition.
+to customize an existing CPUIF definition.
 
 
-As an example, let's use the SystemVerilog interface definition for
+As an example, let's use the VHDL record definition for
 :ref:`cpuif_axi4lite` that is bundled with this project. This interface uses
 the following style and naming conventions:
 
-* SystemVerilog interface type name is ``axi4lite_intf``
-* Defines modports named ``master`` and ``slave``
-* Interface signals are all upper-case: ``AWREADY``, ``AWVALID``, etc...
+* VHDL input record type name is ``axi4lite_slave_in_intf``
+* VHDL output record type name is ``axi4lite_slave_out_intf``
+* Record signals are all upper-case: ``AWREADY``, ``AWVALID``, etc...
 
-Lets assume your preferred SV interface definition uses a slightly different naming convention:
+Lets assume your preferred VHDL record definition uses a slightly different naming convention:
 
-* SystemVerilog interface type name is ``axi4_lite_interface``
-* Modports are capitalized and use suffixes ``Master_mp`` and ``Slave_mp``
+* VHDL input record type name is ``axi4_lite_interface_in``
+* VHDL output record type name is ``axi4_lite_interface_out``
 * Interface signals are all lower-case: ``awready``, ``awvalid``, etc...
 
 Rather than rewriting a new CPU interface definition, you can extend and adjust the existing one:
 
 .. code-block:: python
 
-    from peakrdl_regblock.cpuif.axi4lite import AXI4Lite_Cpuif
+    from peakrdl_regblock_vhdl.cpuif.axi4lite import AXI4Lite_Cpuif
 
     class My_AXI4Lite(AXI4Lite_Cpuif):
+
         @property
         def port_declaration(self) -> str:
-            # Override the port declaration text to use the alternate interface name and modport style
-            return "axi4_lite_interface.Slave_mp s_axil"
+            # Override the port declaration text to use the alternate record name and case
+            return "\n".join([
+                "s_axil_i : in axi4_lite_interface_in(",
+               f"    awaddr({self.addr_width-1} downto 0),",
+               f"    wdata({self.data_width-1} downto 0),",
+               f"    wstrb({self.data_width_bytes-1} downto 0),",
+               f"    araddr({self.addr_width-1} downto 0)",
+                ");",
+                "s_axil_o : out axi4_lite_interface_out(",
+               f"    rdata({self.data_width-1} downto 0)",
+                ")",
+            ])
+
 
         def signal(self, name:str) -> str:
             # Override the signal names to be lowercase instead
-            return "s_axil." + name.lower()
+            return super().signal(name).lower()
 
 Then use your custom CPUIF during export:
 
@@ -59,9 +71,9 @@ Custom CPU Interface Protocol
 If you require a CPU interface protocol that is not included in this project,
 you can define your own.
 
-1. Create a SystemVerilog CPUIF implementation template file.
+1. Create a VHDL CPUIF implementation template file.
 
-    This contains the SystemVerilog implementation of the bus protocol. The logic
+    This contains the VHDL implementation of the bus protocol. The logic
     in this shall implement a translation between your custom protocol and the
     :ref:`cpuif_protocol`.
 
@@ -72,7 +84,7 @@ you can define your own.
 
 2. Create a Python class that defines your CPUIF
 
-    Extend your class from :class:`peakrdl_regblock.cpuif.CpuifBase`.
+    Extend your class from :class:`peakrdl_regblock_vhdl.cpuif.CpuifBase`.
     Define the port declaration string, and provide a reference to your template file.
 
 3. Use your new CPUIF definition when exporting.
@@ -94,17 +106,17 @@ Via a package's entry point definition
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 If you are publishing a collection 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
+This advertises your custom CPUIF class to the PeakRDL-regblock-vhdl tool as a plugin
 that should be loaded, and made available as a command-line option in PeakRDL.
 
 .. code-block:: toml
 
-    [project.entry-points."peakrdl_regblock.cpuif"]
+    [project.entry-points."peakrdl_regblock_vhdl.cpuif"]
     my-cpuif = "my_package.my_module:MyCPUIF"
 
 
 *   ``my_package``: The name of your installable Python module
-*   ``peakrdl-regblock.cpuif``: This is the namespace that PeakRDL-regblock will
+*   ``peakrdl-regblock-vhdl.cpuif``: This is the namespace that PeakRDL-regblock-vhdl will
     search. Any cpuif plugins you create must be enclosed in this namespace in
     order to be discovered.
 *   ``my_package.my_module:MyCPUIF``: This is the import path that