Release/2.0.0

.github/workflows/action.yaml

@@ -10,6 +10,7 @@ on:
   pull_request:
     branches:
     - main
+    - 'release/**'
   schedule:
     - cron: '00 6 1 * *'
   release:
@@ -136,12 +137,15 @@ jobs:
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --legacy_block_access
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --legacy_enum_type
+          python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --copy_libraries
 
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include int_property_to_include
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include int_property_to_include str_property_to_include
           python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp bool_property_to_include enum_property_to_include int_property_to_include str_property_to_include struct_property_to_include double_layer_struct_property_to_include
+
+          python -m generate_and_test --RDL_source_file tests/testcases/user_defined_properties.rdl --root_node user_defined_properties --udp_regex "bool_property_to_include|enum_property_to_include|int_property_to_include|str_property_to_include|struct_property_to_include|double_layer_struct_property_to_include"
 
           python -m generate_and_test --RDL_source_file tests/testcases/reserved_elements.rdl --root_node reserved_elements --hide_regex "(?:[\w_\[\]]+\.)+RSVD"
 
@@ -179,7 +183,8 @@ jobs:
           peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw/show_hidden/ --show_hidden
           peakrdl python tests/testcases/simple.xml tests/testcases/multifile.rdl -o peakrdl_out/raw
           peakrdl python tests/testcases/extended_memories.rdl -o peakrdl_out/raw/
-          peakrdl python tests/testcases/user_defined_properties.rdl -o peakrdl_out/raw/ --udp bool_property_to_include
+          peakrdl python tests/testcases/user_defined_properties.rdl -o peakrdl_out/raw/list/ --udp bool_property_to_include enum_property_to_include struct_property_to_include str_property_to_include
+          peakrdl python tests/testcases/user_defined_properties.rdl -o peakrdl_out/raw/regex/ --udp_regex "bool_property_to_include|enum_property_to_include|struct_property_to_include|str_property_to_include"
           peakrdl python tests/testcases/reserved_elements.rdl -o peakrdl_out/raw/ --hide_regex "(?:[\w_\[\]]+\.)+RSVD"
           peakrdl python tests/testcases/parametrised_top.rdl -o peakrdl_out/raw/ -P MY_PARAM=3
           python -m unittest discover -s peakrdl_out/raw
@@ -257,17 +262,25 @@ jobs:
           python -m with_hal
 
           cd ../..
+
+          cd example/user_defined_properties/
+          peakrdl python user_defined_properties.rdl -o . --udp_regex "^(?!python_hide$)(?!python_name$).+"
+          python -m demo_user_defined_properties
+
+          cd ../..
+
+
 
   integration_tests:
     needs:
-      - mypy
-      - lint
-      - unit_tests
+      - peakrdl_integration
+      - dev_runner
 
     runs-on: ubuntu-latest
     strategy:
       matrix:
         python-version: [3.9, "3.10", "3.11", "3.12", "3.13", "3.14"]
+        lib_copy: [true, false]
 
     steps:
     - uses: actions/checkout@v4
@@ -284,32 +297,46 @@ jobs:
 
         # retrieve the example code from the systemRDL compiler
         wget -L https://raw.githubusercontent.com/SystemRDL/systemrdl-compiler/main/examples/accelera-generic_example.rdl -O tests/testcases/accelera-generic_example.rdl
-
-    - name: Generate testcases
-      run: |
-
+
         # one of the test cases uses IPxact so we need the importer
         python -m pip install peakrdl-ipxact
         # the generated code is type checked with mypy so this is needed
         python -m pip install mypy
 
-        python generate_testcases.py
+    - name: Generate testcases (lib_copy true)
+      if: matrix.lib_copy == true
+      run: |
+        python generate_testcases.py --copy_libraries --output lib_included_testcase_output
+
+    - name: Generate testcases (lib_copy false)
+      if: matrix.lib_copy == false
+      run: |
+        python generate_testcases.py --output lib_excluded_testcase_output
+
+    - name: Static checks (lib_copy true)
+      if: matrix.lib_copy == true
+      run: |
+        mypy lib_included_testcase_output
 
-    - name: Static checks
+    - name: Static checks (lib_copy false)
+      if: matrix.lib_copy == false
       run: |
+        mypy lib_excluded_testcase_output
 
-        mypy testcase_output
-        # pylint testcase_output/autopep8 --disable=duplicate-code,line-too-long,too-many-statements,invalid-name,unused-import,too-many-instance-attributes,too-many-arguments,too-many-lines
+    - name: Run the generated tests (lib_copy true)
+      if: matrix.lib_copy == true
+      run: |
+        python -m unittest discover -s lib_included_testcase_output
 
-    - name: Run the generated tests
+    - name: Run the generated tests (lib_copy false)
+      if: matrix.lib_copy == false
       run: |
-        python -m unittest discover -s testcase_output
+        python -m unittest discover -s lib_excluded_testcase_output
 
   autoformating:
     needs:
       - integration_tests
-      - peakrdl_integration
-      - dev_runner
+
 
     runs-on: ubuntu-latest
     strategy:

README.md

@@ -1,15 +1,82 @@
 ![CI](https://github.com/krcb197/PeakRDL-python/actions/workflows/action.yaml/badge.svg)
 [![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/peakrdl-python.svg)](https://pypi.org/project/peakrdl-python)
 [![Documentation Status](https://readthedocs.org/projects/peakrdl-python/badge/?version=latest)](https://peakrdl-python.readthedocs.io/en/latest/?badge=latest)
 [![Downloads](https://static.pepy.tech/badge/peakrdl-python)](https://pepy.tech/project/peakrdl-python)
 
-# peakrdl-python
-Generate Python Register Access Layer (RAL) from SystemRDL
+# Introduction
+PeakRDL Python is used to generate a python based Register Access Layer (RAL) from SystemRDL.
 
 ## Documentation
 See the [peakrdl-python Documentation](https://peakrdl-python.readthedocs.io/) for more details
 
+## Getting Started
+
+### Installation
+
+1. Install a recent version of Python 3
+2. Install `peakrdl-python`
+   ```console
+   python3 -m pip install peakrdl-python
+   ```
+3. (Optional) Install `peakrdl`, this is needed if you want to use peakrdl python from the command
+   line
+   ```console
+   python3 -m pip install peakrdl
+   ```
+
+### Demo
+
+This demonstration relies on downloading the systemRDL example from Accelera, available here: [accelera-generic_example.rdl](https://github.com/SystemRDL/systemrdl-compiler/blob/main/examples/accelera-generic_example.rdl). This demonstration also 
+assumes that peakrdl has been installed.
+
+1. Build the Register Access Layer (RAL) from the systemRDL code
+   ```console
+   peakrdl python accelera-generic_example.rdl -o .
+   ```
+   This will create a python package called `some_register_map` containing the python RAL
+2. In addition to the RAL, peakrdl-python also generates a simulator that can be used to exercise 
+   the RAL without connecting to real hardware. Enter the following code into a file:
+   ```python
+   """
+   A demonstration of using peakrdl-python using the accelera generic example
+   """
+   # import the top level RAL class
+   from some_register_map.reg_model import RegModel
+   # import the simulator class
+   from some_register_map.sim import Simulator
+
+   from some_register_map.lib import NormalCallbackSet
+
+   if __name__ == '__main__':
+       # create an instance of the RAL with the callbacks directed at the hardware simulator
+       hw_sim = Simulator(0)
+       ral = RegModel(callbacks=NormalCallbackSet(read_callback=hw_sim.read,
+                                                  write_callback=hw_sim.write))
+
+       # read chip ID
+       chip_id_part_number = ral.chip_id_reg.part_num.read()
+       chip_id_revision_number = ral.chip_id_reg.part_num.read()
+       print(f'Chip ID:{chip_id_part_number}.{chip_id_revision_number}')
+   ```
+   save it as `some_register_map_demo.py`
+3. Run the example
+   ```commandline
+   python3 -m some_register_map_demo
+   ```
+   This will generate the following output on the console:
+   ```commandline
+   Chip ID:0.0
+   ```
+
+# Usage
+
+To make use of the RAL with real hardware or a different simulation, the callbacks will need to be 
+connected to the appropriate access function in order to perform an address space reads and writes 
+
+# Upgrading from previous versions (some important changes)
+
 ## Upgrading from pre 0.9.0
 
 In order to address a major limitation of peakrdl-python that prevented it from implementing the
@@ -24,9 +91,16 @@ documentation
 ## Upgrading from pre 1.2.0
 
 Version 1.2 introduced a new way to define the enumerations for the field encoding. This allows 
-metadata from the systemRDL to propogate through to the generated code. This may break advanced 
+metadata from the systemRDL to propagate through to the generated code. This may break advanced 
 usage of the python enumerations. User are encouraged to use the new feature, however, if there 
-are problems with the old enumeation types (based on `IntEnum`) can be used, see 
+are problems with the old enumeration types (based on `IntEnum`) can be used, see 
 _Legacy Enumeration Types_ in the documentation
 
+## Upgrading from pre 2.0.0
+
+Version 2.0 introduced a significant change to the process for building the register model python
+code. This change was intended to reduce the size of the generated code by only generating 
+python classes for systemRDL components that required unique classes. The previous versions were 
+more conservative and tended to generate a lot of duplicate classes.
+
 

docs/api_components.rst

@@ -18,22 +18,22 @@ Base Classes
 Address Maps
 ============
 
-.. autoclass:: peakrdl_python.lib.base.AddressMap
+.. autoclass:: peakrdl_python.lib.sections.AddressMap
     :members:
     :inherited-members:
 
-.. autoclass:: peakrdl_python.lib.base.AddressMapArray
+.. autoclass:: peakrdl_python.lib.sections.AddressMapArray
     :members:
     :inherited-members:
 
 Register Files
 ==============
 
-.. autoclass:: peakrdl_python.lib.base.RegFile
+.. autoclass:: peakrdl_python.lib.sections.RegFile
     :members:
     :inherited-members:
 
-.. autoclass:: peakrdl_python.lib.base.RegFileArray
+.. autoclass:: peakrdl_python.lib.sections.RegFileArray
     :members:
     :inherited-members:
 

docs/generated_package.rst

@@ -24,6 +24,22 @@ In the folder structure above:
 - ``lib`` - This is a package of base classes used by the register access layer (The copy of this can be skipped, see :ref:`skipping-lib-copy`)
 - ``sim_lib`` - This is a package of base classes used by the register access layer simulator (The copy of this can be skipped, see :ref:`skipping-lib-copy`)
 
+.. versionchanged:: 2.0.0
+
+    The ``reg_model`` was changed in version 2.0.0 to split it out into multiple modules rather
+    than building the whole register model in a single python module. This helps avoid
+    excessively large files which helps speed up the generation and loading time.
+
+Top Level Classes
+-----------------
+
+.. versionchanged:: 2.0.0
+
+    A new class aliases were added to the ``reg_model`` and ``sim`` packages to allow the register
+    model and simulator to be imported more easily. See the example below using ``RegModel`` and
+    ``Simulator``.
+
+
 Running the Unit Tests
 ======================
 
@@ -402,6 +418,11 @@ Exposing User Defined Properties
 SystemRDL allows properties to be added to any component (Field, Memory, Register, Register File,
 Address Map), so called *User Defined Properties (UDP)*.
 
+There are two methods to expose user defined properties:
+
+- A list of strings to include in the package
+- A Regular Expression which will include any UDP which matches the regular expression
+
 Consider the following systemRDL example with a user defined property: ``component_usage``
 
 .. literalinclude :: ../example/user_defined_properties/user_defined_properties.rdl
@@ -413,12 +434,28 @@ User Defined Properties are not automatically included they must be specified, a
 
    peakrdl python user_defined_properties.rdl -o . --udp component_usage
 
+Alternatively the User Defined Properties can be included with a regular expression.
+In the following case all UDPs are included, except the ones used by PeakRDL python
+
+.. code-block:: bash
+
+   peakrdl python user_defined_properties.rdl -o . --udp_regex "^(?!python_hide$)(?!python_name$).+"
+
+.. warning::
+
+   Attempting to use both the list and regular expression approach is not supported and will
+   generate an error
+
 The user defined properties are stored in a ``udp`` property of all component in the generated
 register access and can be accessed as follows:
 
 .. literalinclude :: ../example/user_defined_properties/demo_user_defined_properties.py
    :language: python
 
+.. versionadded:: 2.0.0
+
+    Regular Expression matching for User Defined Properties was added in version 2.0.0
+
 Python Safe Names
 =================
 

example/array_access/demo_array_access.py

@@ -1,17 +1,17 @@
-import json
-from typing import Union
-
-from array_access.reg_model.array_access import array_access_cls
-from array_access.sim.array_access import array_access_simulator_cls
+"""
+A demonstration of array access for peakrdl-python
+"""
+from array_access.reg_model import RegModel
+from array_access.sim import Simulator
 from array_access.lib.callbacks import NormalCallbackSet
 
 if __name__ == '__main__':
 
     # setup the simple simulator
-    sim = array_access_simulator_cls(0)
+    sim = Simulator(0)
 
     # create an instance of the class
-    regmodel = array_access_cls(callbacks=NormalCallbackSet(read_callback=sim.read))
+    regmodel = RegModel(callbacks=NormalCallbackSet(read_callback=sim.read))
 
     # access a entry in the 1D array
     print(regmodel.reg_array_1D[0].field_a.read())

example/enumerated_fields/demo_enumerated_fields.py

@@ -1,17 +1,17 @@
 """
-A demonstration of using enumeration
+A demonstration of using enumeration for peakrdl-python
 """
 from enumerated_fields.lib import NormalCallbackSet
 
-from enumerated_fields.reg_model.enumerated_fields import enumerated_fields_cls as GPIO
-from enumerated_fields.sim.enumerated_fields import enumerated_fields_simulator_cls as HardwareSimulator
+from enumerated_fields.reg_model import RegModel
+from enumerated_fields.sim import Simulator
 
 if __name__ == '__main__':
 
     # create an instance of the hardware simulator
-    hw = HardwareSimulator(0)
+    hw = Simulator(0)
     # create an instance of the RAL with the callbacks directed at the hardware simulator
-    gpio = GPIO(callbacks=NormalCallbackSet(read_callback=hw.read, write_callback=hw.write))
+    gpio = RegModel(callbacks=NormalCallbackSet(read_callback=hw.read, write_callback=hw.write))
 
     # get the field values
     for field in gpio.gpio_strength.readable_fields: