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

Install a recent version of Python 3
Install peakrdl-python
```
python3 -m pip install peakrdl-python
```
(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.

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

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

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.2

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.2
File	Size	Uploaded
peakrdl_python-3.1.2.tar.gz	187.6 kB	May 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for peakrdl-python 3.1.2
File	Interpreter	ABI	Platform	Reset
peakrdl_python-3.1.2-py3-none-any.whl 168.7 kB May 24, 2026	Python 3	none	any	Details

Total release size: 356.3 kB

Release files / peakrdl_python-3.1.2.tar.gz

Download URL	peakrdl_python-3.1.2.tar.gz
Size	187.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`f77bbae8d71c132aa64844832aadfc582b216184f6b083de233ba3d4f0415036`
BLAKE2b-256 checksum How to use checksums	`68414cce75f525abcefdc9c1d9e507789258e7fcb3a382b401854bea8a05b407`
Upload date	May 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

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

Download URL	peakrdl_python-3.1.2-py3-none-any.whl
Size	168.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5df90a08936a12d442e70e9773802b16f02198ac553df58eb535a69006d14a33`
BLAKE2b-256 checksum How to use checksums	`06f977632f86e24574f27a43bbe0e7a8b74589ac58872bb903dd70b0d9a75bc5`
Upload date	May 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`