Metadata-Version: 2.4
Name: peakrdl-cpp
Version: 0.1.0
Summary: PeakRDL exporter that generates C++ register maps
Author: PeakRDL-cpp contributors
License-Expression: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/Topi-ab/PeakRDL-cpp
Project-URL: Repository, https://github.com/Topi-ab/PeakRDL-cpp
Project-URL: Issues, https://github.com/Topi-ab/PeakRDL-cpp/issues
Project-URL: Changelog, https://github.com/Topi-ab/PeakRDL-cpp/releases
Keywords: systemrdl,peakrdl,registers,codegen,c++
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: PERMISSION.generated-output-exception
Requires-Dist: peakrdl>=1.5.0
Requires-Dist: systemrdl-compiler>=1.32.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# peakrdl-cpp

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

## Setup

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

Install from PyPI (after first release):

```bash
pip install peakrdl-cpp
```

## Usage

Generate a C++ header from an RDL file:

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

Use the Python API directly:

```python
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()`
  - `write()`/`wr_shadow.write()` accept both signed and unsigned integral input types regardless of field signedness.
- Access width:
  - `data_t` is deduced from SystemRDL `accesswidth`.
  - If more than one numeric `accesswidth` is present in the design, generation fails.
  - `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/README.md)
- [examples/basic/design.rdl](examples/basic/design.rdl)
- [examples/basic/main.cpp](examples/basic/main.cpp)

## Development

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

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

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

Optional deterministic seed override:

```bash
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

Release instructions are documented in
[RELEASE.md](https://github.com/Topi-ab/PeakRDL-cpp/blob/main/RELEASE.md).

## License

LGPL-3.0 (GNU Lesser General Public License v3.0). See [LICENSE](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](PERMISSION.generated-output-exception).
