Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

CI linting: pylint Checked with mypy PyPI - Python Version Documentation Status Downloads

Introduction

PeakRDL Python is used to generate a python based Register Access Layer (RAL) from SystemRDL.

Documentation

See the peakrdl-python Documentation for more details

Getting Started

Installation

  1. Install a recent version of Python 3
  2. Install peakrdl-python
    python3 -m pip install peakrdl-python
    
  3. (Optional) Install peakrdl, this is needed if you want to use peakrdl python from the command line
    python3 -m pip install peakrdl
    

Demo

This demonstration relies on downloading the systemRDL example from Accelera, available here: accelera-generic_example.rdl. This demonstration also assumes that peakrdl has been installed.

  1. Build the Register Access Layer (RAL) from the systemRDL code
    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:
    """
    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
    python3 -m some_register_map_demo
    
    This will generate the following output on the console:
    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

Some important changes

0.9.0

In order to address a major limitation of peakrdl-python that prevented it from implementing the full systemRDL specification, a breaking API change was needed for handling blocks:

  • registers (in register array)
  • memory entries in a memory

Users are encouraged to upgrade in order to avoid this limitation. However, there is a legacy mode to support users with existing designs, see: Legacy Block Callback and Block Access in the documentation

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 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 enumeration types (based on IntEnum) can be used, see Legacy Enumeration Types in the documentation

2.0.0

Version 2.0.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.

Version 2.1.0 has improved this to ensure field encoding enumerations were correctly deduplicated.

The implementation requires a hash to be generated of each node in order to determine whether it is unique or not. This hash was incorperated within the class names which resulted in the code changing each time it was regenerated, version 2.1.0 introduces a option to either:

  • 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

3.0.0

Version 3.0.0 has included a significant refactoring of the generated test cases, moving functions out of the templates (generated code) in favour of an enhanced test library. On some cases, this reduced the size of the test case generated code by 90%, significantly improved the time to generate the code and also improved the time to run the tests by a 30% reduction.

In preparation for the removal of some legacy features from the early versions 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. Until version 3.0.0 the new type was not the default, it now is. The old enumeration types can still be used by setting legacy_enum_type.
  • The first versions of PeakRDL Python used the built-in Array type for accessing blocks of data efficiently. 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

Metadata

Release files for peakrdl-python 4.0.0rc1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for peakrdl-python 4.0.0rc1
File Size Uploaded Provenance Actions
peakrdl_python-4.0.0rc1.tar.gz 188.9 kB Without provenance Details for peakrdl_python-4.0.0rc1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for peakrdl-python 4.0.0rc1
File Interpreter ABI Platform Actions
peakrdl_python-4.0.0rc1-py3-none-any.whl Python 3 none any Details for peakrdl_python-4.0.0rc1-py3-none-any.whl

Total release size: 356.4 kB

Release files / peakrdl_python-4.0.0rc1.tar.gz

Download URL peakrdl_python-4.0.0rc1.tar.gz
Size 188.9 kB
Tags Source
SHA-256 checksum
How to use checksums
9bc4d2615417d4dfc87502d11fbb0bc658239eded0e055391c3bac006b685c3c
BLAKE2b-256 checksum
How to use checksums
77cd5ab84f1f55bd9633fb62937fc99f1576a112ddcf5d719b299d638398ce8b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / peakrdl_python-4.0.0rc1-py3-none-any.whl

Download URL peakrdl_python-4.0.0rc1-py3-none-any.whl
Size 167.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9bcbfe456bff902d7c0d10d32aa8145a26000ef326e7328c88045f765359e3d1
BLAKE2b-256 checksum
How to use checksums
9ef6fa05b9a689fcb31ad82ed301ceec88cd59e5704ac20a8779357d0b4b5b53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for peakrdl-python 4.0.0rc1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page