{"id":5509,"library":"systemrdl-compiler","title":"SystemRDL Compiler","description":"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.","status":"active","version":"1.32.2","language":"en","source_language":"en","source_url":"https://github.com/SystemRDL/systemrdl-compiler","tags":["hardware description","systemrdl","compiler","register description","EDA","CSR","automation","generator"],"install":[{"cmd":"pip install systemrdl-compiler","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires Python >=3.7 for execution.","package":"python","optional":false},{"reason":"Provides backported type hints.","package":"typing-extensions","optional":false},{"reason":"Used for colored terminal output.","package":"colorama","optional":false},{"reason":"Runtime for the ANTLR4-generated parser.","package":"antlr4-python3-runtime","optional":false},{"reason":"Used for processing Markdown within RDL 'desc' properties.","package":"markdown","optional":false},{"reason":"Required if RDL source files contain embedded Perl preprocessor tags.","package":"perl","optional":true}],"imports":[{"note":"Main class for compiling and elaborating SystemRDL designs.","symbol":"RDLCompiler","correct":"from systemrdl import RDLCompiler"},{"note":"Represents the root of the elaborated register model.","symbol":"RootNode","correct":"from systemrdl.node import RootNode"},{"note":"Base class for all elaborated components in the register model.","symbol":"Node","correct":"from systemrdl.node import Node"}],"quickstart":{"code":"from systemrdl import RDLCompiler\nfrom systemrdl.node import RootNode, Node\n\n# Create a dummy RDL file content\nrdl_content = \"\"\"\naddrmap my_block {\n    reg {\n        field { sw=rw; } my_field[31:0] = 0;\n    } my_register @0x0;\n};\n\"\"\"\n\n# 1. Instantiate the compiler\ncompiler = RDLCompiler()\n\n# 2. Compile the RDL source\ntry:\n    compiler.compile_string(rdl_content, \"dummy.rdl\")\nexcept Exception as e:\n    print(f\"Compilation failed: {e}\")\n    exit(1)\n\n# 3. Elaborate the design\ntry:\n    # 'my_block' is the top-level addrmap definition name\n    root = compiler.elaborate(top_def_name=\"my_block\")\nexcept Exception as e:\n    print(f\"Elaboration failed: {e}\")\n    exit(1)\n\n# 4. Traverse the elaborated model\nprint(\"Elaborated RDL Model:\")\nfor node in root.descendants(): # Use descendants for recursive traversal\n    indent = \"  \" * node.depth\n    print(f\"{indent}- {node.get_path()} (Type: {node.type_name})\")\n\n# Example: Access a specific register node\nreg_node = root.find_by_path(\"my_block.my_register\")\nif reg_node:\n    print(f\"Found register: {reg_node.inst_name} at address {hex(reg_node.addr_offset)}\")\n    for field in reg_node.fields():\n        print(f\"  Field: {field.inst_name}, Bits: [{field.msb}:{field.lsb}]\")","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"deprecated","affected_versions":">=1.30.1"},{"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.","message":"Version `1.30.0` was yanked from PyPI due to a regression. Users should avoid installing this specific version.","severity":"gotcha","affected_versions":"1.30.0"},{"fix":"Ensure your development environment uses Python 3.7 or newer to maintain compatibility.","message":"Support for Python 3.5 and 3.6 was officially dropped in version `1.28.0`.","severity":"breaking","affected_versions":">=1.28.0"},{"fix":"If your design uses overlapping fields and you rely on `RegNode.fields(include_gaps=True)`, verify the output against the new, correct behavior.","message":"The 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.","severity":"gotcha","affected_versions":">=1.32.0"},{"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.","message":"In `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.","severity":"breaking","affected_versions":">=1.29.3"},{"fix":"Install Perl on your system if you use RDL files with Perl preprocessor directives. Windows users need to download and install Perl separately.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If your tools or scripts relied on `FieldNode.is_volatile` for singlepulse fields, verify that the updated behavior aligns with your expectations.","message":"In `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.","severity":"gotcha","affected_versions":">=1.32.2"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}