updated top-level docs for VHDL

Author: darsor

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/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/faq.rst

@@ -1,102 +1,33 @@
 Frequently Asked Questions
 ==========================
 
-Why isn't there an option for a flat non-struct hardware interface?
+Why isn't there an option for a flat non-record hardware interface?
 -------------------------------------------------------------------
 SystemRDL is inherently a very hierarchical language.
 For small register blocks, flattening the hardware interface may be acceptable,
 but this ends up scaling very poorly as the design becomes larger and has more
 complex hierarchy.
-Using struct compositions for the hardware interface has the benefit of
+Using record compositions for the hardware interface has the benefit of
 preserving conceptual hierarchy and arrays exactly as defined in the original
 SystemRDL.
 
-How do I know I connected everything? Structs are harder to review
+How do I know I connected everything? Records are harder to review
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Initially this can be daunting, but fortunately the tool has an option to generate a
 flattened hardware interface report upon export. Try using the ``--hwif-report``
 command line option when exporting. This is the easiest way to quickly
 understand the structure of the hardware interface.
 
-
-
-Why does the tool generate un-packed structs? I prefer packed structs.
-----------------------------------------------------------------------
-Packed structs are great when describing vectors that have bit-level structure.
-In this tool, the use of un-packed structs is intentional since the hardware
-interface is not something that is meant to be bit-accessible. In the case of
-the hardware interface structs, using a packed struct is semantically inappropriate.
-
-... Then how can I initialize the struct?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-We get this request most often because designers want to initialize the ``hwif_in``
-struct with a simple assignment:
-
-.. code:: systemverilog
-
-    always_comb begin
-        hwif_in = '0;
-    end
-
-Of course since the struct actually is **unpacked**, this will result in a
-compile error which usually leads to the inappropriate assumption that it ought
-to be packed. (See this amusing blog post about `X/Y problems <https://xyproblem.info>`_)
-
-If your goal is to initialize the packed struct, fortunately SystemVerilog already
-has syntax to do this:
-
-.. code:: systemverilog
-
-    always_comb begin
-        hwif_in = '{default: '0};
-    end
-
-This is lesser-known syntax, but still very well supported by synthesis
-tools, and is the recommended way to handle this.
-
-... Why are unpacked structs preferred?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-In the case of the hardware interface ports, unpacked structs help prevent
-mistakes that are very easy to make.
-Consider the following situation - a designer has a field that sets the following
-properties: ``sw=rw; hw=rw; we;``, and wants to assign the hardware input value,
-so they erroneously do the following assignment in Verilog:
-
-.. code:: systemverilog
-
-    assign hwif_in.my_register.my_field = <some value>;
-
-This is actually a bug since the ``my_field`` member is actually a struct that
-has two members: ``we`` and ``next``. If this were a packed struct, this would
-silently compile and you would potentially have a bug that may not be noticed
-(depending on how thorough the test campaign is).
-With an unpacked struct, this gets flagged immediately as a compile error since
-the assignment is invalid.
-
-The designer may have simply forgotten that the field is an aggregate of multiple
-members and intended to do the following:
-
-.. code:: systemverilog
-
-    assign hwif.my_register.my_field.next = <some value>;
-    assign hwif.my_register.my_field.we = <some control signal>;
-
-
 The generated output does not match our organization's coding style
 -------------------------------------------------------------------
-SystemVerilog coding styles vary wildly, and unfortunately there is little
+VHDL coding styles vary wildly, and unfortunately there is little
 consensus on this topic within the digital design community.
 
-The output generated by PeakRDL-regblock strives to be as human-readable as possible,
+The output generated by PeakRDL-regblock-vhdl strives to be as human-readable as possible,
 and follow consistent indentation and styling. We do our best to use the most
 widely accepted coding style, but since this is a very opinionated space, it is
 impossible to satisfy everyone.
 
-In general, we strive to follow the
-`SystemVerilog style guide by lowRISC <https://github.com/lowRISC/style-guides/blob/master/VerilogCodingStyle.md>`_,
-but may deviate in some areas if not practical or would impose excessive complexity on the code generator.
-
-
 The lint tool I am using is flagging violations in generated code
 -----------------------------------------------------------------
 Code linting tools are a great way to check for user-error, flag inconsistencies,
@@ -113,5 +44,5 @@ complexity to the tool.
 
 If you encounter a lint violation, please carefully review and consider waiving
 it if it does not pose an actual danger. If you still believe it is a problem,
-please let us know by `submitting an issue <https://github.com/SystemRDL/PeakRDL-regblock/issues>`_
+please let us know by `submitting an issue <https://github.com/SystemRDL/PeakRDL-regblock-vhdl/issues>`_
 that describes the problem.

docs/hwif.rst

@@ -2,25 +2,25 @@ Hardware Interface
 ------------------
 
 The generated register block will present the entire hardware interface to the user
-using two struct ports:
+using two record ports:
 
 * ``hwif_in``
 * ``hwif_out``
 
 All field inputs and outputs as well as signals are consolidated into these
-struct ports. The presence of each depends on the specific contents of the design
+record ports. The presence of each depends on the specific contents of the design
 being exported.
 
 
-Using structs for the hardware interface has the following benefits:
+Using records for the hardware interface has the following benefits:
 
 * Preserves register map component grouping, arrays, and hierarchy.
 * Avoids naming collisions and cumbersome signal name flattening.
 * Allows for more natural mapping and distribution of register block signals to a design's hardware components.
-* Use of unpacked arrays/structs prevents common assignment mistakes as they are enforced by the compiler.
+* Use of arrays/records prevents common assignment mistakes as they are enforced by the compiler.
 
 
-Structs are organized as follows: ``hwif_out.<heir_path>.<feature>``
+Records are organized as follows: ``hwif_out.<heir_path>.<feature>``
 
 For example, a simple design such as:
 
@@ -36,16 +36,16 @@ For example, a simple design such as:
             } my_reg[2];
         };
 
-... results in the following struct members:
+... results in the following record members:
 
 .. code-block:: text
 
-    hwif_out.my_reg[0].my_field.value
-    hwif_in.my_reg[0].my_field.next
-    hwif_in.my_reg[0].my_field.we
-    hwif_out.my_reg[1].my_field.value
-    hwif_in.my_reg[1].my_field.next
-    hwif_in.my_reg[1].my_field.we
+    hwif_out.my_reg(0).my_field.value
+    hwif_in.my_reg(0).my_field.next_q
+    hwif_in.my_reg(0).my_field.we
+    hwif_out.my_reg(1).my_field.value
+    hwif_in.my_reg(1).my_field.next_q
+    hwif_in.my_reg(1).my_field.we
 
 For brevity in this documentation, hwif features will be described using shorthand
 notation that omits the hierarchical path: ``hwif_out..<feature>``

docs/index.rst

@@ -22,16 +22,17 @@ The easiest way to use PeakRDL-regblock-vhdl is via the  `PeakRDL command line t
     python3 -m pip install peakrdl-regblock-vhdl[cli]
 
     # Export!
-    peakrdl regblock atxmega_spi.rdl -o regblock/ --cpuif axi4-lite
+    peakrdl regblock-vhdl atxmega_spi.rdl -o regblock/ --cpuif axi4-lite
 
 
 Links
 -----
 
-- `Source repository <https://github.com/SystemRDL/PeakRDL-regblock>`_
-- `Release Notes <https://github.com/SystemRDL/PeakRDL-regblock/releases>`_
-- `Issue tracker <https://github.com/SystemRDL/PeakRDL-regblock/issues>`_
-- `PyPi <https://pypi.org/project/peakrdl-regblock>`_
+- `Source repository <https://github.com/SystemRDL/PeakRDL-regblock-vhdl>`_
+- `Release Notes <https://github.com/SystemRDL/PeakRDL-regblock-vhdl/releases>`_
+- `Issue tracker <https://github.com/SystemRDL/PeakRDL-regblock-vhdl/issues>`_
+- `PyPi <https://pypi.org/project/peakrdl-regblock-vhdl>`_
+- `SystemVerilog Exporter <https://github.com/SystemRDL/PeakRDL-regblock>`_
 - `SystemRDL Specification <http://accellera.org/downloads/standards/systemrdl>`_
 
 

docs/licensing.rst

@@ -1,9 +1,9 @@
 Licensing
 =========
 
-Re-distribution of the PeakRDL-regblock code generator tool shall adhere to the
+Re-distribution of the PeakRDL-regblock-vhdl code generator tool shall adhere to the
 terms outlined by the GNU GPL v3 license. For a copy of the license, see:
-https://github.com/SystemRDL/PeakRDL-regblock/blob/main/LICENSE
+https://github.com/SystemRDL/PeakRDL-regblock-vhdl/blob/main/LICENSE
 
 
 Why GPL?
@@ -23,19 +23,19 @@ explicitly mentioned in the exemptions below.
 
 What is exempt from the GPL v3 license?
 ---------------------------------------
-Don't worry. Not everything that the PeakRDL-regblock project touches is
+Don't worry. Not everything that the PeakRDL-regblock-vhdl project touches is
 considered GPL v3 code.
 
 The following are exempt and are free to use with no restrictions:
 
-*   Any code that is generated using PeakRDL-regblock is 100% yours. Since it
+*   Any code that is generated using PeakRDL-regblock-vhdl is 100% yours. Since it
     was derived from your regblock definition, it remains yours. You can
     distribute it freely, use it in a proprietary ASIC, sell it as part of an
     IP, whatever.
 *   Any code snippets in this documentation can be freely copy/pasted. These are
     examples that are intended for this purpose.
 *   All reference files that are downloadable from this documentation, which are
-    also available in the `hdl-src folder in the repository <https://github.com/SystemRDL/PeakRDL-regblock/tree/main/hdl-src>`_
+    also available in the `hdl-src folder in the repository <https://github.com/SystemRDL/PeakRDL-regblock-vhdl/tree/main/hdl-src>`_
 
 
 Can I use this as part of my company's internally developed tools?