Registry / serialization / systemrdl-compiler

systemrdl-compiler

JSON →
library1.32.2pypypi✓ verified 22d ago

The systemrdl-compiler project implements a generic compiler front-end for Accellera's SystemRDL 2.0 register description language. It provides an elaborated register model that is easy to traverse and query, facilitating the creation of custom register space view generators. The project is actively maintained with frequent minor releases addressing bugs and adding features.

pip install systemrdl-compiler
INSTALL
IMPORT
SIG · SYSTEMRDL-COMPILER
S
systemrdl-compiler
serializationpythonv1.32.2
Install
2.4s avg
Import
243ms
Disk
55MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.32.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.250s · 54.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 2.4s · import 0.236s · 59MB
55MB installed
● package 55MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

RDLCompiler
from systemrdl import RDLCompiler
Main class for compiling and elaborating SystemRDL designs.
RootNode
from systemrdl.node import RootNode
Represents the root of the elaborated register model.
Node
from systemrdl.node import Node
Base class for all elaborated components in the register model.

This quickstart demonstrates how to compile a simple SystemRDL string, elaborate it into a register model, and then traverse the resulting `RootNode` to inspect components like registers and fields. The `RDLCompiler` is the entry point, `compile_string` parses the RDL, and `elaborate` creates the hierarchical `RootNode` representation. The `descendants()` and `find_by_path()` methods are shown for model traversal and access.

from systemrdl import RDLCompiler from systemrdl.node import RootNode, Node # Create a dummy RDL file content rdl_content = """ addrmap my_block { reg { field { sw=rw; } my_field[31:0] = 0; } my_register @0x0; }; """ # 1. Instantiate the compiler compiler = RDLCompiler() # 2. Compile the RDL source try: compiler.compile_string(rdl_content, "dummy.rdl") except Exception as e: print(f"Compilation failed: {e}") exit(1) # 3. Elaborate the design try: # 'my_block' is the top-level addrmap definition name root = compiler.elaborate(top_def_name="my_block") except Exception as e: print(f"Elaboration failed: {e}") exit(1) # 4. Traverse the elaborated model print("Elaborated RDL Model:") for node in root.descendants(): # Use descendants for recursive traversal indent = " " * node.depth print(f"{indent}- {node.get_path()} (Type: {node.type_name})") # Example: Access a specific register node reg_node = root.find_by_path("my_block.my_register") if reg_node: print(f"Found register: {reg_node.inst_name} at address {hex(reg_node.addr_offset)}") for field in reg_node.fields(): print(f" Field: {field.inst_name}, Bits: [{field.msb}:{field.lsb}]")
systemrdl-compiler --version
Debug
Known issues
deprecatedThe `Node.inst` API layer was deprecated from the public API in v1.30.1. Directly querying `Component` objects via `Node.inst` is no longer recommended and may break in future releases.
fix
Migrate code to use equivalent properties and methods directly from the `Node` API layer instead of accessing `Node.inst` internals. Consult the documentation for alternative access patterns.
affects: >=1.30.1
gotchaVersion `1.30.0` was yanked from PyPI due to a regression. Users should avoid installing this specific version.
fix
Always install the latest stable version or a specific patched version (e.g., `1.30.1` or later) to avoid this known problematic release.
affects: 1.30.0
breakingSupport for Python 3.5 and 3.6 was officially dropped in version `1.28.0`.
fix
Ensure your development environment uses Python 3.7 or newer to maintain compatibility.
affects: >=1.28.0
gotchaThe behavior of `RegNode.fields(include_gaps=True)` with overlapping fields was fixed in `v1.32.0`. Previously, it could return 'nonsensical reserved regions'. This change might alter results for designs with overlapping fields if `include_gaps` was used.
fix
If your design uses overlapping fields and you rely on `RegNode.fields(include_gaps=True)`, verify the output against the new, correct behavior.
affects: >=1.32.0
breakingIn `v1.29.3`, methods like `Node.children()`, `Node.signals()`, `RegNode.fields()`, etc., changed their return type from generators to lists. Code expecting generator behavior (e.g., lazy evaluation or single iteration without explicit conversion) may need adjustment.
fix
While this change often has 'zero impact', if your code explicitly relied on generator properties, review usage. Explicitly casting to `list()` is no longer necessary but harmless.
affects: >=1.29.3
gotchaIf RDL source files contain embedded Perl preprocessor tags, a Perl installation visible through the system's `PATH` environment variable is required for the compiler to function correctly.
fix
Install Perl on your system if you use RDL files with Perl preprocessor directives. Windows users need to download and install Perl separately.
affects: All versions
gotchaIn `v1.32.2`, the `FieldNode.is_volatile` property was updated to correctly include 'singlepulse' fields as volatile. This change reflects a more accurate interpretation of the SystemRDL specification.
fix
If your tools or scripts relied on `FieldNode.is_volatile` for singlepulse fields, verify that the updated behavior aligns with your expectations.
affects: >=1.32.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'systemrdl'
The systemrdl-compiler package has not been installed in the active Python environment.
fix
pip install systemrdl-compiler
ImportError: cannot import name 'RDLCompiler' from 'systemrdl'
The RDLCompiler class is located within the `systemrdl.compiler` submodule, not directly in the top-level `systemrdl` package.
fix
from systemrdl.compiler import RDLCompiler
systemrdl.core.RDLCompileError
The provided SystemRDL input contains syntax or semantic errors (e.g., unexpected tokens, undefined properties, incorrect structure), preventing the compiler from successfully parsing or elaborating the design.
fix
Review the specific error message (which typically includes file, line, and column) and correct the SystemRDL source code according to the SystemRDL 2.0 specification.
RuntimeError: No design has been elaborated yet. Call compile_file() or compile_string() first.
The `get_root()` method was called on an `RDLCompiler` instance before any SystemRDL source code was successfully compiled, meaning there is no elaborated design model to retrieve.
fix
Ensure `compiler.compile_file("your_file.rdl")` or `compiler.compile_string("your_rdl_string")` is called and completes successfully before attempting to retrieve the root node of the design.
[RDL ERROR] example.rdl:5:10: Member 'foo' is not defined
The SystemRDL file contains a semantic error, referencing a component, field, or property that has not been declared or is out of scope.
fix
Review your SystemRDL file at the specified line and column to define 'foo' or correct the reference to an existing member.
Upgrade
Version history
1.32.2latest on PyPI · released Feb 27, 2026
Audit
Dependencies
pythonrequiredRequires Python >=3.7 for execution.
typing-extensionsrequiredProvides backported type hints.
coloramarequiredUsed for colored terminal output.
antlr4-python3-runtimerequiredRuntime for the ANTLR4-generated parser.
markdownrequiredUsed for processing Markdown within RDL 'desc' properties.
perloptionalRequired if RDL source files contain embedded Perl preprocessor tags.
Agent activity
11 hits · last 30 days
node
8
Resources
systemrdl-compiler — pip install systemrdl-compiler · libregistry