peakrdl-cpp

peakrdl-cpp is a PeakRDL exporter plugin that generates C++ register access APIs from SystemRDL designs.

Setup

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Install from PyPI (after first release):

pip install peakrdl-cpp

Usage

Generate a C++ header from an RDL file:

peakrdl cpp design.rdl -o regs.hpp \
  --namespace my_block \
  --class-name MyBlock \
  --error-style exceptions

Use the Python API directly:

from systemrdl import RDLCompiler
from peakrdl_cpp import CppExporter

compiler = RDLCompiler()
compiler.compile_file("design.rdl")
root = compiler.elaborate()

CppExporter().export(
    root.top,  # RootNode also works
    "regs.hpp",
    namespace="my_block",
    class_name="MyBlock",
    error_style="exceptions",   # or "status"
    check_write_range=True,     # optional, defaults to True
)

Generated API shape:

• Hierarchical object access with array indexing:
  • my_root.regfile_1[3].sub_regfile.example_reg.field.write(13);
  • auto v = my_root.regfile_1[3].sub_regfile.example_reg.field.read();
• Field APIs respect sw access rules:
  • sw=r: no write()
  • sw=w: no read()
• Shadow API:
  • field.rd_shadow.read() (reads register read-shadow)
  • field.wr_shadow.read() / field.wr_shadow.write(...) (reads/updates register write-shadow)
  • reg.rd_shadow.read_hw(), reg.wr_shadow.flush(), reg.wr_shadow.flush_always()
  • regfile.rd_shadow.read_hw(), regfile.wr_shadow.flush(), regfile.wr_shadow.flush_always()
  • addrmap.rd_shadow.read_hw(), addrmap.wr_shadow.flush(), addrmap.wr_shadow.flush_always()
• Hard generation error on reserved symbol conflicts (for example rd_shadow or wr_shadow).
• Error handling style:
  • --error-style exceptions throws std::runtime_error
  • --error-style status records errors and exposes ok()/last_error()/clear_error()
  • In exceptions mode these status methods still exist, but are mainly useful in status mode.
• Write range validation:
  • enabled by default
  • disable with --no-write-range-check to skip generated runtime range checks on write() and wr_shadow.write()
  • non-enum scalar fields accept both signed and unsigned integral input types for write() and wr_shadow.write().
• Enum fields:
  • SystemRDL fields with encode = some_enum; emit a public C++ enum class.
  • Encoded scalar field APIs use that enum type for read(), write(...), rd_shadow.read(), wr_shadow.read(), and wr_shadow.write(...).
  • Raw integral writes are intentionally not part of the encoded field API.
• Access width:
  • data_t is deduced from SystemRDL accesswidth.
  • If more than one numeric accesswidth is present in the design, generation fails.
  • Registers may be wider than accesswidth up to 64 bits. Multiword readable registers require buffer_reads=true; multiword writable registers require buffer_writes=true.
  • Fields wider than data_t use compact std::array<data_t, N> values in generated read/write/shadow APIs.
  • addr_t is fixed to std::uint32_t.

Bus adapter requirements:

• data_t read(addr_t addr);
• void write(addr_t addr, data_t value);
• This contract is currently documented but not yet enforced via C++ concepts/static constraints.

Example

See checked-in example case:

• examples/basic/README.md
• examples/basic/design.rdl
• examples/basic/main.cpp

Development

. .venv/bin/activate
pip install -e ".[test]"
pytest

Run adaptive compile/run checks against an external RDL file:

PEAKRDL_CPP_TEST_RDL=/abs/path/to/design.rdl \
  ./.venv/bin/pytest -q tests/test_exporter_adaptive.py

Optional deterministic seed override:

PEAKRDL_CPP_TEST_RDL=/abs/path/to/design.rdl \
PEAKRDL_CPP_TEST_SEED=42 \
  ./.venv/bin/pytest -q tests/test_exporter_adaptive.py

The test suite includes end-to-end validation:

• compile RDL
• generate C++
• compile and link C++ test bench against generated headers
• execute runtime behavior checks

Maintainer Notes

Version history is documented in doc/VERSION_HISTORY.md.

Release instructions are documented in RELEASE.md.

License

LGPL-3.0 (GNU Lesser General Public License v3.0). See LICENSE.

Generated output exception:

• Output generated by this project (for example, generated C++ headers/sources) may be used, copied, modified, and distributed under terms of your choice, including proprietary terms.
• This exception does not change the license of this project's own source code.
• The exception is provided as an additional permission under GNU GPLv3 section 7 (as incorporated by LGPLv3).

See PERMISSION.generated-output-exception.