{"id":8410,"library":"peakrdl","title":"PeakRDL","description":"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.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/SystemRDL/PeakRDL","tags":["SystemRDL","register-generation","hardware-description","HDL","UVM","IP-XACT","code-generation","CLI","embedded-systems"],"install":[{"cmd":"pip install peakrdl","lang":"bash","label":"Install core PeakRDL CLI"},{"cmd":"pip install peakrdl-python","lang":"bash","label":"Install Python RAL generator (if needed for API)"},{"cmd":"pip install peakrdl-cheader","lang":"bash","label":"Install C Header generator (if needed for API)"}],"dependencies":[{"reason":"Internal dependency for parsing SystemRDL files, often directly imported when using the Python API of PeakRDL extensions.","package":"systemrdl-compiler","optional":false}],"imports":[{"note":"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.","symbol":"RDLCompiler","correct":"from systemrdl import RDLCompiler"},{"note":"For generating Python Register Access Layers (RALs) via Python API. This requires the 'peakrdl-python' package.","symbol":"PythonExporter","correct":"from peakrdl_python.exporter import PythonExporter"},{"note":"For generating C Header files via Python API. This requires the 'peakrdl-cheader' package.","symbol":"CHeaderExporter","correct":"from peakrdl_cheader.exporter import CHeaderExporter"}],"quickstart":{"code":"# example.rdl\naddrmap my_device {\n    reg { \n        field { sw = rw; hw = r; } control_field[7:0] = 0; \n        field { sw = r; hw = w; } status_field[15:8] = 0; \n    } my_register;\n    regfile my_block [2] {\n        reg { field { sw = rw; } data[31:0] = 0; } data_reg;\n    };\n};\n\n# Terminal commands\n# Generate a C header file\npeakrdl c-header example.rdl -o example.h\n\n# Generate HTML documentation\npeakrdl html example.rdl -o html_docs/","lang":"bash","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.7 or higher.","message":"PeakRDL v1.3.0 dropped support for Python 3.6. Ensure your environment uses Python 3.7 or newer to avoid compatibility issues.","severity":"breaking","affected_versions":">=1.3.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.9.0 of peakrdl-python"},{"fix":"Consult the GNU LGPLv3 license to understand the implications for your project, especially regarding linking and distribution of derived works.","message":"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.","severity":"gotcha","affected_versions":">=1.4.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0 of peakrdl-python"},{"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.","message":"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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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>`.","cause":"The `peakrdl` executable is not in your system's PATH, or the package was not installed correctly.","error":"peakrdl: command not found"},{"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).","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.","error":"Command '['python', '-m', 'peakrdl_something']' returned non-zero exit status 1."},{"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.","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.","error":"Error: peakrdl.plugins.PluginError: Plugin 'my_custom_plugin' could not be loaded"},{"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.","cause":"This import path or symbol might be incorrect, deprecated, or specific to an older/newer version of `peakrdl-python`.","error":"from peakrdl_python import compiler_with_udp_registers\nImportError: cannot import name 'compiler_with_udp_registers' from 'peakrdl_python'"}]}