peakrdl-python 3.1.3__tar.gz → 4.0.0__tar.gz

{peakrdl_python-3.1.3 → peakrdl_python-4.0.0}/.github/workflows/action.yaml

@@ -1,8 +1,6 @@
 # This is a basic workflow to help you get started with Actions
 
 name: CI
-permissions:
-  contents: read
 
 # Controls when the action will run.
 on:
@@ -22,6 +20,10 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+permissions:
+  contents: read
+  id-token: write
+
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
   lint:
@@ -74,7 +76,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15" ]
 
     steps:
       - uses: actions/checkout@v5
@@ -104,7 +106,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15" ]
 
     steps:
       - uses: actions/checkout@v5
@@ -140,10 +142,6 @@ jobs:
 
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map
           sleep 10
-          python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --legacy_block_access
-          sleep 10
-          python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --legacy_enum_type
-          sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --copy_libraries
           sleep 10
           python -m generate_and_test --RDL_source_file tests/testcases/accelera-generic_example.rdl --root_node some_register_map --hashing_mode PYTHONHASH
@@ -181,7 +179,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"  ]
 
     steps:
       - uses: actions/checkout@v5
@@ -214,16 +212,11 @@ jobs:
           peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw_async/ --async
           peakrdl python tests/testcases/hidden_property.rdl -o peakrdl_out/raw_async/show_hidden/ --show_hidden --async
           python -m unittest discover -s peakrdl_out/raw_async
-          peakrdl python tests/testcases/basic.rdl -o peakrdl_out/raw_legacy_block/ --legacy_block_access
-          python -m unittest discover -s peakrdl_out/raw_legacy_block
-
+          
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/no_test/ --skip_test_case_generation
           
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/no_lib/ --skip_library_copy
           python -m unittest discover -s peakrdl_out/no_lib
-          
-          peakrdl python tests/testcases/enum_example.rdl -o peakrdl_out/raw_legacy_enum/ --legacy_enum_type
-          python -m unittest discover -s peakrdl_out/raw_legacy_enum
 
           # test a TOMl file that passes in overridden templates
           peakrdl python tests/testcases/basic.rdl -o peakrdl_out/simple_user_template/ --peakrdl-cfg tests/alternative_templates_toml/peakrdl.toml
@@ -295,6 +288,18 @@ jobs:
           
           cd ../..
           
+          cd example/write_only_registers/
+          peakrdl python write_only_registers.rdl -o .
+          python -m demo_write_only_registers
+
+          cd ../..
+          
+          cd example/fifo_register_example/
+          peakrdl python fifo_register_example.rdl -o .
+          python -m demo_fifo_register_example
+
+          cd ../..
+          
   identical_code:
     needs:
       - mypy
@@ -304,7 +309,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14" ]
+        python-version: [ 3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15" ]
 
     steps:
       - uses: actions/checkout@v5
@@ -338,7 +343,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.9, "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
         lib_copy: [true, false]
 
     steps:
@@ -388,7 +393,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.9, "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
 
     steps:
     - uses: actions/checkout@v5
@@ -480,16 +485,16 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install -U build
+          python -m pip install --upgrade pip build
 
       - name: Build
-        run: python -m build
+        run: python -m build --sdist --wheel --outdir dist
 
       - uses: actions/upload-artifact@v4
         with:
-          path: |
-            dist/*.tar.gz
-            dist/*.whl
+          name: python-package
+          path: dist/*
+          if-no-files-found: error
 
   #-------------------------------------------------------------------------------
   deploy:
@@ -498,15 +503,19 @@ jobs:
 
     runs-on: ubuntu-latest
 
+    permissions:
+      contents: read
+      id-token: write
+
     # Only publish when a GitHub Release is created.
     if: github.event_name == 'release'
     steps:
       - uses: actions/download-artifact@v4
         with:
-          name: artifact
+          name: python-package
           path: dist
 
       - uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          user: __token__
-          password: ${{ secrets.PYPI_API_TOKEN }}
+          packages-dir: dist/
+          skip-existing: true

{peakrdl_python-3.1.3 → peakrdl_python-4.0.0}/.gitignore

@@ -58,3 +58,4 @@ __pycache__/
 /example/simulating_callbacks/mychip/
 /example/tranversing_address_map/chip_with_registers/
 /generate_and_test_output/
+/tests/testcases/accelera-generic_example.rdl

{peakrdl_python-3.1.3 → peakrdl_python-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peakrdl-python
-Version: 3.1.3
+Version: 4.0.0
 Summary: Generate Python Register Access Layer (RAL) from SystemRDL
 Author: Keith Brady
 License:              GNU LESSER GENERAL PUBLIC LICENSE
@@ -182,6 +182,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
@@ -341,4 +342,23 @@ the following options were changed:
   This had some restrictions, so the a new methodology based on the `list` type was introduced in version 0.9.
   The old array based behaviour is no longer the default but can be turned on using the `legacy_block_access`
 
+## 4.0.0
+
+some legacy features from the early versions were removed in release 4.0.0, the following options were changed:
+- Version 1.2 introduced a new custom enumeration type (rather than using `IntEnum`) in order to allow
+  the content to `name` and `desc` systemRDL properties in be accessible. Version 4.0.0 removed the option to use `IntEnum`
+- The first versions of PeakRDL Python used the built-in `Array` type for accessing blocks of data efficiently.
+  This had some restrictions, so a new methodology based on the `list` type was introduced in version 0.9.
+  The old array based behaviour was removed in this version
+
+This release also improved the features for write-only register:
+- field write operations no longer have a hard-code base value of `0` in the register, the base register value is configurable via the `write_initial_state` property
+- the `write_fields` methods also uses the `write_initial_state` property to allow other bits in the register to be set if needed, rather than a hardcoded `0`
+- A new `single_write` context manager can be used to set multiple field values in a single write with a configurable initial register state
+
+The read/write register class has similar feature:
+- A new `single_write` context manager that does not use a read before the write to set multiple field values in a single write with a configurable initial register state
+- A new `write_all_fields_without_read` method tht will write all the writable fields with the `write_initial_state` property to allow other bits in the register to be set if needed
+
+
 

{peakrdl_python-3.1.3 → peakrdl_python-4.0.0}/README.md

@@ -130,4 +130,23 @@ the following options were changed:
   This had some restrictions, so the a new methodology based on the `list` type was introduced in version 0.9.
   The old array based behaviour is no longer the default but can be turned on using the `legacy_block_access`
 
+## 4.0.0
+
+some legacy features from the early versions were removed in release 4.0.0, the following options were changed:
+- Version 1.2 introduced a new custom enumeration type (rather than using `IntEnum`) in order to allow
+  the content to `name` and `desc` systemRDL properties in be accessible. Version 4.0.0 removed the option to use `IntEnum`
+- The first versions of PeakRDL Python used the built-in `Array` type for accessing blocks of data efficiently.
+  This had some restrictions, so a new methodology based on the `list` type was introduced in version 0.9.
+  The old array based behaviour was removed in this version
+
+This release also improved the features for write-only register:
+- field write operations no longer have a hard-code base value of `0` in the register, the base register value is configurable via the `write_initial_state` property
+- the `write_fields` methods also uses the `write_initial_state` property to allow other bits in the register to be set if needed, rather than a hardcoded `0`
+- A new `single_write` context manager can be used to set multiple field values in a single write with a configurable initial register state
+
+The read/write register class has similar feature:
+- A new `single_write` context manager that does not use a read before the write to set multiple field values in a single write with a configurable initial register state
+- A new `write_all_fields_without_read` method tht will write all the writable fields with the `write_initial_state` property to allow other bits in the register to be set if needed
+
+
 

peakrdl_python-4.0.0/docs/generated_package/callbacks.rst

@@ -0,0 +1,113 @@
+Callbacks
+*********
+
+The Register Access Layer will typically interfaced to a driver that
+allows accesses the chip.
+
+.. tip:: The simulator generated with the register model can be used as an alternative to
+         a hardware connection
+
+In order to operate the register access layer typically requires the following:
+
+- A callback for a single register write, this not required if there is no writable register in
+  the register access layer
+- A callback for a single register read, this not required if there is no writable register in
+  the register access layer
+
+In addition the register access layer can make use of block operations where a block of the
+address space is read in a single transaction. Not all drivers support these
+
+The examples of these two methods are included within the generated register
+access layer package so that it can be used from the console:
+
+.. code-block:: python
+
+    def read_addr_space(addr: int, width: int, accesswidth: int) -> int:
+        """
+        Callback to simulate the operation of the package, everytime the read is called, it will
+        request the user input the value to be read back.
+
+        Args:
+            addr: Address to write to
+            width: Width of the register in bits
+            accesswidth: Minimum access width of the register in bits
+
+        Returns:
+            value inputted by the used
+        """
+        assert isinstance(addr, int)
+        assert isinstance(width, int)
+        assert isinstance(accesswidth, int)
+        return input('value to read from address:0x%X' % addr)
+
+    def write_addr_space(addr: int, width: int, accesswidth: int, data: int) -> None:
+        """
+        Callback to simulate the operation of the package, everytime the write is called, it will
+        print out the result.
+
+        Args:
+            addr: Address to write to
+            width: Width of the register in bits
+            accesswidth: Minimum access width of the register in bits
+            data: value to be written to the register
+
+        Returns:
+            None
+        """
+        assert isinstance(addr, int)
+        assert isinstance(width, int)
+        assert isinstance(accesswidth, int)
+        assert isinstance(data, int)
+        print('write data:0x%X to address:0x%X' % (data, addr))
+
+In a real system these call backs will be connected to a driver.
+
+In addition there is also an option to use ``async`` callbacks if the package is built
+``asyncoutput`` set to True.
+
+Callback Set
+============
+
+The callbacks are passed into the register access layer using either:
+
+* ``NormalCallbackSet`` for standard python function callbacks
+* ``AsyncCallbackSet`` for async python function callbacks, these are called from the library using
+  ``await``
+
+Legacy Block Callback and Block Access
+======================================
+
+.. versionchanged:: 0.9.0
+
+   Previous versions of PeakRDL Python used the python ``array.array`` for efficiently moving blocks
+   of data. This was changed in version 0.9.0 in order to accommodate memories which were larger
+   than 64 bit wide which could not be supported as the array type only support entries of up to
+   64 bit.
+
+   .. warning::
+      The developers apologise for making a breaking change, however, not being able to fully the
+      systemRDL specification was determined to be a major limitation that needed to be addressed.
+
+      It could have left this as a future compatibility mode before making a breaking change but
+      that would just delay the pain it was felt to be better to get as many users onto the new
+      API as soon as possible whilst PeakRDL Python is in beta.
+
+   If you really want to just keep on with the array based interface and make only minimal changes
+   to existing code, there are two simple steps:
+
+   1. The northbound interfaces that are provided by the generated package expect lists of integers
+      rather than array. The old interfaces can be retained by using the ``legacy_block_access``
+      build option.
+   2. The southbound interfaces into the callbacks again need to use lists for the
+      ``read_block_callback`` and ``write_block_callback`` methods. If you want to continue to use
+      the old scheme use the following callback classes which are part of the callbacks:
+      * ``NormalCallbackSetLegacy`` for standard python function callbacks
+      * ``AsyncCallbackSetLegacy`` for async python function callbacks, these are called from the library using ``await``
+
+.. versionchanged:: 3.0.0
+
+    The ``legacy_block_access`` will now default to ``False``
+
+.. versionchanged:: 4.0.0
+
+    The ``legacy_block_access`` was removed, the ``NormalCallbackSetLegacy`` and ``AsyncCallbackSetLegacy`` are no longer supported

peakrdl_python-4.0.0/docs/generated_package/output_structure.rst

@@ -0,0 +1,132 @@
+Output Structure
+****************
+
+PeakRDL Python generates a python Register Access Layer (RAL) from a System RDL design. The
+generated python code is contained in a package, structured as shown below. The ``root_name``
+will be based on the top level address map name with the package was generated
+
+| ``<root_name>``
+| ├── ``lib``
+| ├── ``lib_test``
+| ├── ``sim_lib``
+| ├── ``reg_model``
+| │ └── ``<root_name>.py``
+| ├── ``sim``
+| │ └── ``<root_name>.py``
+| └── ``tests``
+|   └── ``test_<root_name>.py``
+
+In the folder structure above:
+
+- ``<root_name>.py`` - This is the register access layer code for the design
+- ``test_<root_name>.py`` - This is a set of autogenerated unittests to verify the register access layer (The unit test generation can be skipped, see ``skip_test_case_generation``)
+- ``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`)
+- ``lib_test`` - This is a package of base classes autogenerated unit tests (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.
+
+.. versionchanged:: 3.0.0
+
+    The auto-generated unit tests were changed in version 3.0.0 to split to make use
+    of a test library, which significantly reduced the size of the generated code.
+
+Top Level Classes
+=================
+
+In order to use the generated packages, the Top Level Class needs to be imported.
+
+.. 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``.
+
+.. warning:: It is not recommended to import the child classes. If a sub-section of the register
+             model is all that is needed, it is better to only build the section needed.
+
+Class Names
+===========
+
+PeakRDL Python generates python classes to model the parts of the register model. These can not
+always map to the names in the code, especially if attributes are overridden. Therefore PeakRDL
+Python generates new names.
+
+.. versionchanged:: 2.0.0
+
+    In order to reduce duplication within the generated model a hashing algortihm is applied to the
+    nodes in the design to determine which nodes are unique. This hash is appended to the name
+    of all the python classes in the register model
+
+.. versionadded:: 2.1.0
+
+    There are two possible algorithms for the hashing, this is selectable by the user:
+
+    * The builtin python ``hash`` function, this is fast but is a salted hash so changes hashes export to
+      export
+    * Use the ``SHA256`` hash from the python ``hashlib`` standard library, this may slow down the export
+      of large register models but will be consistent, therefore is useful if the resultant code is being
+      checked into a version control system (such as GIT) and the differences are being reviewed
+
+    .. tip::
+
+        Use the default builtin ``hash`` option unless you need to use the alternative
+
+Unit Tests
+==========
+
+In addition to the Register Model a set od unit tests are made that test that the register model has been
+built correctly
+
+Running the Unit Tests
+----------------------
+
+There are many ways to run Python Unit tests. A good place to start is the ``unittest`` module
+included in the Python standard installation.
+
+
+Simulator
+=========
+
+PeakRDL Python also generates an simulator, this can be used to test and develop using the
+generated package. The simulator is used in a the examples shown earlier in this section. The
+simulator has the option to attach a callback to the read and write operations of either a
+register or field. In addition there is a ``value`` property that allows access to the register
+or field content, this allows the contents to be accessed or updated without activating the
+callbacks, this is intended to allow the simulator to be extended with behaviour that is not
+fully described by the systemRDL.
+
+.. warning:: The PeakRDL Python simulator is not intended to replace an RTL simulation of the
+             design. It does not simulate the hardware, it is intended as a simple tool for
+             development and testing of the python wrappers or code that uses them.
+
+.. _skipping-lib-copy:
+
+Skipping the Library Copy
+=========================
+
+In some cases it may be desirable to skip the copy of the library from the generated pacakge.
+This may be useful in development of PeakRDL-python. It can also be used to avoid distributing
+licensed code.
+
+.. warning:: If the libraries are not distributed with the package, it is very important to
+             ensure users download the matching version of the PeakRDL-python package to use it
+
+Autoformatting
+==============
+
+The generated code is not perfect it often has lots of spare black lines, over time this will
+improve but the quickest way to resolve these issue is to include an autoformatter
+post-generation. Previous versions of peakrdl-python included the option to run an autoformatter
+to clean up the generated code. This had two issues:
+
+* It created maintenance issues when the autoformatter changed
+* The choice of autoformatter is an individual one, rather than force an autoformatter on people
+  it is better to let people choose their own.
+
+peakrdl-python uses the Black `Black <https://pypi.org/project/black/L>`_ in the CI tests to check
+that the generated code is compatible with an autoformatter.