Skip to main content

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

Metadata

Release files for peakrdl-python 3.1.3

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 3.1.3
File Size Uploaded Provenance Actions
peakrdl_python-3.1.3.tar.gz 187.7 kB Without provenance Details for peakrdl_python-3.1.3.tar.gz

Built distribution (wheel)

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

Total release size: 356.5 kB

Release files / peakrdl_python-3.1.3.tar.gz

Download URL peakrdl_python-3.1.3.tar.gz
Size 187.7 kB
Tags Source
SHA-256 checksum
How to use checksums
11ad68a98578b17510d8de01361fbd62dc114b177506fc3f01f0cb9a526b472d
BLAKE2b-256 checksum
How to use checksums
bc6b2dfa645461cf3197164338d0eee5ac2798dbbb6deb23f1d3576ed02e5507
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / peakrdl_python-3.1.3-py3-none-any.whl

Download URL peakrdl_python-3.1.3-py3-none-any.whl
Size 168.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7d443f525a9ca5ea7cb760601e2e12e6e6a5219c1e055d3255bb6297c41206f8
BLAKE2b-256 checksum
How to use checksums
4d202d046ba19ffc888a8af1936c6348440e53114f4193aad5b608dc6c8bfed8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for peakrdl-python 3.1.3

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

3.1.3 This release

2 release files No provenance

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