{"id":8408,"library":"peakrdl-regblock","title":"PeakRDL-regblock","description":"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.","status":"active","version":"1.3.1","language":"en","source_language":"en","source_url":"https://github.com/SystemRDL/PeakRDL-regblock","tags":["SystemRDL","SystemVerilog","RTL","FPGA","ASIC","CSR","compiler","hardware design","register automation"],"install":[{"cmd":"pip install peakrdl-regblock","lang":"bash","label":"Basic install"},{"cmd":"pip install peakrdl-regblock[cli]","lang":"bash","label":"Install with command-line tool support"}],"dependencies":[{"reason":"Requires Python 3.7 or newer to run the library.","package":"python","optional":false},{"reason":"Provides the `peakrdl` command-line orchestrator, which includes the `regblock` subcommand for this library. Automatically installed with `peakrdl-regblock[cli]`.","package":"peakrdl","optional":true},{"reason":"The underlying SystemRDL compiler front-end used by peakrdl-regblock for parsing RDL files.","package":"systemrdl-compiler","optional":false}],"imports":[{"note":"Primary class for programmatic generation of register blocks.","symbol":"RegblockExporter","correct":"from peakrdl_regblock import RegblockExporter"},{"note":"Used to compile SystemRDL source files, which is a prerequisite for using RegblockExporter.","symbol":"RDLCompiler","correct":"from systemrdl import RDLCompiler"}],"quickstart":{"code":"import os\nfrom systemrdl import RDLCompiler, RDLCompileError\nfrom peakrdl_regblock import RegblockExporter\nfrom peakrdl_regblock.cpuif import AXI4Lite\n\nrdl_content = \"\"\"\naddrmap my_registers {\n    reg { field { sw=rw; } my_field; } my_reg[2];\n};\n\"\"\"\n\noutput_dir = './generated_regblock'\n\nif not os.path.exists(output_dir):\n    os.makedirs(output_dir)\n\ntry:\n    compiler = RDLCompiler()\n    compiler.compile_string(rdl_content)\n    root = compiler.top.get_child_by_name('my_registers')\n\n    exporter = RegblockExporter()\n    exporter.export(\n        node=root,\n        output_dir=output_dir,\n        cpuif_cls=AXI4Lite,\n        module_name='my_register_block'\n    )\n    print(f\"Successfully generated SystemVerilog to {output_dir}\")\nexcept RDLCompileError as e:\n    print(f\"SystemRDL compilation failed: {e}\")\nexcept Exception as e:\n    print(f\"Regblock export failed: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python environment to 3.7+.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"For VHDL, install `peakrdl-regblock-vhdl` (e.g., `pip install peakrdl-regblock-vhdl[cli]`) and use its corresponding tools/APIs.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Avoid using the `alias` keyword in your SystemRDL descriptions. Restructure your register definitions to avoid this feature.","message":"The `alias` keyword for registers is currently not supported. Attempting to use it in SystemRDL input will result in compilation or export errors.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`).","cause":"The `peakrdl` command-line tool, which orchestrates the `regblock` subcommand, was not installed or is not in the system's PATH.","error":"peakrdl: command not found"},{"fix":"Carefully review the SystemRDL code against the SystemRDL 2.0 specification for correctness. Use a linter or an RDL editor if available.","cause":"The SystemRDL input file (or string) contains syntax errors, semantic violations, or is not compliant with the SystemRDL specification.","error":"RDLCompileError: ..."},{"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.","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.","error":"AttributeError: 'RootNode' object has no attribute 'cpuif' or TypeError: export() missing 1 required positional argument: 'cpuif_cls'"}]}