PeakRDL-regblock

1.3.1 · active · verified Thu Apr 16

PeakRDL-regblock is a free and open-source control & status register (CSR) compiler. It translates SystemRDL register descriptions into synthesizable SystemVerilog RTL modules for hardware designs. The library is actively maintained, with a recent major release (1.0.0) in April 2025, and subsequent minor releases, currently at version 1.3.1, indicating a rapid release cadence.

Common errors

```
peakrdl: command not found
```
cause The `peakrdl` command-line tool, which orchestrates the `regblock` subcommand, was not installed or is not in the system's PATH.

fix Install `peakrdl-regblock` with the `[cli]` extra: `pip install peakrdl-regblock[cli]`. If `peakrdl` is desired as a standalone, ensure it is also installed (`pip install peakrdl`).
```
RDLCompileError: ...
```
cause The SystemRDL input file (or string) contains syntax errors, semantic violations, or is not compliant with the SystemRDL specification.

fix Carefully review the SystemRDL code against the SystemRDL 2.0 specification for correctness. Use a linter or an RDL editor if available.
```
AttributeError: 'RootNode' object has no attribute 'cpuif' or TypeError: export() missing 1 required positional argument: 'cpuif_cls'
```
cause When using the `RegblockExporter` API, the `cpuif_cls` parameter (specifying the CPU interface type like AXI4Lite, APB, etc.) was either not provided or was incorrect, or the `node` provided to `export` does not represent a valid SystemRDL root for a register block.

fix Ensure you are passing an appropriate CPU interface class (e.g., `cpuif_cls=AXI4Lite` from `peakrdl_regblock.cpuif`) to the `exporter.export()` method. The `node` argument should be the compiled `RootNode` or `AddrmapNode` of your register block.

Warnings

breaking Version 1.0.0 dropped support for Python 3.6. Users on older Python versions must upgrade to Python 3.7 or newer to use this library version and above.
Fix: Upgrade Python environment to 3.7+.
gotcha The generated SystemVerilog hardware interface (`hwif` structs) makes no guarantees on field order. Relying on positional access or the SystemVerilog streaming operator for bit-level ordering of fields within these structs can lead to incorrect behavior or compilation issues.
Fix: Always access `hwif` struct members directly by name (e.g., `hwif_out.my_reg.my_field.value`) to ensure correct behavior and avoid assumptions about bit-positions.
gotcha This library generates SystemVerilog RTL. If your project requires VHDL, you should use the sister project `PeakRDL-regblock-VHDL` instead, which is a feature-equivalent fork designed for VHDL output.
Fix: For VHDL, install `peakrdl-regblock-vhdl` (e.g., `pip install peakrdl-regblock-vhdl[cli]`) and use its corresponding tools/APIs.
gotcha The `alias` keyword for registers is currently not supported. Attempting to use it in SystemRDL input will result in compilation or export errors.
Fix: Avoid using the `alias` keyword in your SystemRDL descriptions. Restructure your register definitions to avoid this feature.

Install

pip install peakrdl-regblock Basic install
pip install peakrdl-regblock[cli] Install with command-line tool support

Imports

RegblockExporter
```
from peakrdl_regblock import RegblockExporter
```
Primary class for programmatic generation of register blocks.
RDLCompiler
```
from systemrdl import RDLCompiler
```
Used to compile SystemRDL source files, which is a prerequisite for using RegblockExporter.

Quickstart

This quickstart demonstrates how to programmatically compile a simple SystemRDL description and then export it into a SystemVerilog register block using the `RegblockExporter`. It specifies an AXI4-Lite CPU interface and outputs the generated files to a directory named 'generated_regblock'. Alternatively, the primary method for most users is via the `peakrdl regblock` command-line tool.

import os
from systemrdl import RDLCompiler, RDLCompileError
from peakrdl_regblock import RegblockExporter
from peakrdl_regblock.cpuif import AXI4Lite

rdl_content = """
addrmap my_registers {
    reg { field { sw=rw; } my_field; } my_reg[2];
};
"""

output_dir = './generated_regblock'

if not os.path.exists(output_dir):
    os.makedirs(output_dir)

try:
    compiler = RDLCompiler()
    compiler.compile_string(rdl_content)
    root = compiler.top.get_child_by_name('my_registers')

    exporter = RegblockExporter()
    exporter.export(
        node=root,
        output_dir=output_dir,
        cpuif_cls=AXI4Lite,
        module_name='my_register_block'
    )
    print(f"Successfully generated SystemVerilog to {output_dir}")
except RDLCompileError as e:
    print(f"SystemRDL compilation failed: {e}")
except Exception as e:
    print(f"Regblock export failed: {e}")

view raw JSON →