PeakRDL

1.5.0 · active · verified Thu Apr 16

PeakRDL is a free and open-source toolchain for control/status register (CSR) automation and code generation. It is centered around the SystemRDL register description language but can also work with other CSR specifications like IP-XACT. The current version is 1.5.0, and it maintains an active development and release cadence, providing a unified command-line interface for tasks such as generating Verilog CSR RTL, compiling C register abstraction layers, and producing documentation.

Common errors

```
peakrdl: command not found
```
cause The `peakrdl` executable is not in your system's PATH, or the package was not installed correctly.

fix Ensure `peakrdl` is installed (`pip install peakrdl`) and that your Python environment's script directory is included in your system's PATH. You can often run it directly via `python -m peakrdl <command>`.
```
Command '['python', '-m', 'peakrdl_something']' returned non-zero exit status 1.
```
cause A `peakrdl` subcommand (which are often separate packages like `peakrdl-python`, `peakrdl-cheader`) failed. This typically means the specific extension is not installed or has encountered an internal error.

fix Verify that the specific `peakrdl-*` extension (e.g., `peakrdl-python`) is installed (`pip install peakrdl-python`). If it is, check the error output from the failing subcommand for more details (e.g., RDL compilation errors, configuration issues).
```
Error: peakrdl.plugins.PluginError: Plugin 'my_custom_plugin' could not be loaded
```
cause PeakRDL failed to discover or load a custom plugin. This could be due to incorrect entry point configuration in `setup.py`, a typo in the plugin's module path, or issues within the plugin's code.

fix Ensure your custom plugin is correctly defined with an `importer` or `exporter` entry point in your `pyproject.toml` or `setup.py`, and that the `__peakrdl__.py` file at your package root is correct. Alternatively, verify its path if using `peakrdl.toml` for configuration.
```
from peakrdl_python import compiler_with_udp_registers
ImportError: cannot import name 'compiler_with_udp_registers' from 'peakrdl_python'
```
cause This import path or symbol might be incorrect, deprecated, or specific to an older/newer version of `peakrdl-python`.

fix Refer to the `peakrdl-python` documentation for the correct import paths. The `compiler_with_udp_registers` function is part of the `peakrdl_python` package, so ensure it is installed and that the documentation for your version shows this import as valid. Many examples now use `systemrdl.RDLCompiler` directly.

Warnings

breaking PeakRDL v1.3.0 dropped support for Python 3.6. Ensure your environment uses Python 3.7 or newer to avoid compatibility issues.
Fix: Upgrade your Python environment to version 3.7 or higher.
breaking The `peakrdl-python` package (version 0.9.0) introduced a breaking API change for handling blocks (registers in arrays, memory entries) to address limitations in implementing the full SystemRDL specification.
Fix: Review the `peakrdl-python` documentation for versions 0.9.0 and above, specifically regarding block access methods, and update your code accordingly. The `legacy_block_access` option in `PythonExporter` might be relevant for older code.
gotcha PeakRDL v1.4.0 changed its licensing from MIT to GNU LGPLv3 for the CLI and all core extensions. While LGPLv3 is permissive, review its terms if you are redistributing PeakRDL or its generated code in proprietary projects.
Fix: Consult the GNU LGPLv3 license to understand the implications for your project, especially regarding linking and distribution of derived works.
gotcha From `peakrdl-python` v3.0.0, a new custom enumeration type is used by default in generated Python Register Access Layers (RALs) to expose SystemRDL `name` and `desc` properties. Older code relying on `IntEnum` behavior might need adjustment.
Fix: If your generated code relies on the old `IntEnum` type, set the `legacy_enum_type=True` parameter in the `PythonExporter` when generating your RAL.
gotcha SystemRDL allows identifiers to be repeated in different lexical scopes. If an exporter flattens hierarchy or uses common namespaces, this can lead to name collisions in the generated output. Similarly, different enumerations can have the same `state_e` name.
Fix: Tool developers should use `Node.get_path()` or `get_scope_path()` to ensure unique identifiers in generated code, or implement strategies to disambiguate names.

Install

pip install peakrdl Install core PeakRDL CLI
pip install peakrdl-python Install Python RAL generator (if needed for API)
pip install peakrdl-cheader Install C Header generator (if needed for API)

Imports

RDLCompiler
```
from systemrdl import RDLCompiler
```
While 'peakrdl' is primarily a CLI, its Python API for extensions (like `peakrdl-python`, `peakrdl-cheader`) often requires `systemrdl.RDLCompiler` to parse RDL files programmatically. There isn't a single 'main' import from the `peakrdl` package itself for typical user-facing programmatic tasks beyond plugin development.
PythonExporter
```
from peakrdl_python.exporter import PythonExporter
```
For generating Python Register Access Layers (RALs) via Python API. This requires the 'peakrdl-python' package.
CHeaderExporter
```
from peakrdl_cheader.exporter import CHeaderExporter
```
For generating C Header files via Python API. This requires the 'peakrdl-cheader' package.

Quickstart

This quickstart demonstrates how to use the `peakrdl` command-line tool to generate a C header file and HTML documentation from a simple SystemRDL description. First, create a file named `example.rdl` with the provided content, then run the `peakrdl` commands in your terminal.

# example.rdl
addrmap my_device {
    reg { 
        field { sw = rw; hw = r; } control_field[7:0] = 0; 
        field { sw = r; hw = w; } status_field[15:8] = 0; 
    } my_register;
    regfile my_block [2] {
        reg { field { sw = rw; } data[31:0] = 0; } data_reg;
    };
};

# Terminal commands
# Generate a C header file
peakrdl c-header example.rdl -o example.h

# Generate HTML documentation
peakrdl html example.rdl -o html_docs/

view raw JSON →