Registry / devops / peakrdl-cheader

peakrdl-cheader

library1.1.0pypypi✓ verified 84d ago

PeakRDL C-Header is a Python package used to generate a C Header file, typically representing a register abstraction layer, from a SystemRDL register model. It enables direct C-language access to hardware registers by generating C struct definitions that mirror the hardware address space. The library is currently active, with its latest version being 1.1.0, and maintains a regular release cadence, with updates addressing features and fixes.

devops

pip install peakrdl-cheader

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · PEAKRDL-CHEADER

peakrdl-cheader

devopspythonv1.1.0

Install

3.2s avg

Import

343ms

Disk

69MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.940 runs

installs and imports cleanly · install 0.0s · import 0.350s · 68MB

glibc

py 3.10–3.940 runs

installs and imports cleanly · install 3.2s · import 0.336s · 72MB

69MB installed

● package 69MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CHeaderExporter

✓ from peakrdl_cheader.exporter import CHeaderExporter

This is the primary class for generating C headers via the Python API.

RDLCompiler

✓ from systemrdl import RDLCompiler

Required to compile SystemRDL files before exporting. Not part of peakrdl-cheader itself, but a core dependency.

This quickstart demonstrates how to use `peakrdl-cheader` via its Python API. It involves compiling a SystemRDL file using `systemrdl.RDLCompiler` to obtain an elaborated register model, then passing this model to `CHeaderExporter.export()` with desired configuration options to generate a C header file. This approach is useful for integrating the generator into custom build pipelines. Alternatively, for command-line usage, the `peakrdl` CLI tool provides a `c-header` subcommand.

import os from systemrdl import RDLCompiler from peakrdl_cheader.exporter import CHeaderExporter # Create a dummy RDL file for demonstration rdl_content = ''' addrmap my_device { reg { field {} my_reg[31:0] = 0; } control_reg; regfile my_block[8] { reg { field {} status_field[7:0]; } status_reg; } }; ''' with open('example.rdl', 'w') as f: f.write(rdl_content) # 1. Compile the SystemRDL file rdlc = RDLCompiler() rdlc.compile_file('example.rdl') top_node = rdlc.elaborate() # 2. Configure and generate the C header exporter = CHeaderExporter( std="gnu11", # Specify C standard, e.g., gnu11, c99 generate_bitfields=True, # Enable bitfield structs bitfield_order_ltoh=True # Specify bitfield packing order ) output_path = 'example.h' exporter.export(node=top_node, path=output_path) print(f"C header generated successfully at {output_path}") # Clean up dummy RDL file os.remove('example.rdl') # Example of how to use from CLI: # peakrdl c-header example.rdl -o example.h --std gnu11 --bitfields ltoh

peakrdl-cheader --version

Debug

Known issues

breakingThe project license was changed from Apache-2.0 to LGPLv3 in version 1.1.0. While not a code-breaking change, this is a significant alteration in licensing terms that affects how the software can be incorporated into other projects.

fix

Review the LGPLv3 license terms to ensure compatibility with your project's licensing and compliance requirements.

affects: >=1.1.0

gotchaThe packing order of C struct bitfields is implementation-defined (compiler and architecture dependent). If `generate_bitfields` is enabled, you *must* explicitly specify `bitfield_order_ltoh` (Low-to-High) or `bitfield_order_htol` (High-to-Low) to match your target environment, or the generated header may lead to incorrect hardware access.

fix

When enabling bitfield generation, set `bitfield_order_ltoh=True` or `bitfield_order_ltoh=False` (for HTOL) in the `CHeaderExporter` constructor, or use the `--bitfields ltoh` or `--bitfields htol` CLI options. Run generated test cases on your target to verify correctness.

affects: All versions

gotchaSystemRDL allows identifiers to be repeated in different lexical scopes. If your exporter flattens hierarchy or relies on simple type names, this can lead to C identifier collisions in the generated header.

fix

Utilize the `type_style` parameter (e.g., 'lexical' or 'hierarchical') to control how C `typedef` names are generated. 'hierarchical' style uses the component's full hierarchy to ensure unique names.

affects: All versions

gotchaC's `<stdint.h>` types typically only extend up to 64 bits. For SystemRDL registers wider than 64 bits, `peakrdl-cheader` will represent them as an array of smaller sub-words in the C header. Failure to configure the `wide_reg_subword_size` parameter will result in default behavior which might not align with expectations.

fix

For designs with registers > 64 bits, explicitly set `wide_reg_subword_size` (e.g., 8, 16, 32, or 64) in the `CHeaderExporter` to define the desired sub-word array size.

affects: All versions

Errors

Common errors & fixes

Generated C header has incorrect bitfield packing order, leading to wrong register accesses.

C struct bitfield packing order (Low-to-High vs High-to-Low) is implementation-defined by the C compiler and target architecture. The `peakrdl-cheader` tool requires explicit direction for this.

fix

When using `generate_bitfields=True`, ensure `bitfield_order_ltoh` is set correctly to `True` or `False` based on your C compiler's behavior. Example: `exporter = CHeaderExporter(generate_bitfields=True, bitfield_order_ltoh=True)`.

Generated C struct names or typedefs collide, or do not reflect the desired hierarchy.

SystemRDL allows names to be reused in different scopes, and the C exporter's default naming style (`type_style`) might not prevent collisions or match your preferred naming convention.

fix

Adjust the `type_style` parameter in `CHeaderExporter`. Use `type_style="hierarchical"` to derive names from the full SystemRDL component hierarchy for uniqueness, or `type_style="lexical"` to use RDL lexical scope names.

My SystemRDL file compiles, but the generated C header for wide registers (>64 bits) is malformed or inaccessible.

Standard C integer types are limited to 64 bits. For wider registers, `peakrdl-cheader` generates an array of smaller types, and this behavior needs to be explicitly configured.

fix

Set the `wide_reg_subword_size` parameter in `CHeaderExporter` to specify how larger registers should be broken down (e.g., `wide_reg_subword_size=32` for an array of 32-bit words).

Upgrade

Version history

1.1.0latest on PyPI · released Mar 28, 2026

Audit

Dependencies

systemrdl-compilerrequiredRequired for parsing SystemRDL files into an elaboratable model that peakrdl-cheader consumes.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/SystemRDL/PeakRDL-cheader ↗

packagehttps://pypi.org/project/peakrdl-cheader/ ↗

docshttps://peakrdl-cheader.readthedocs.io/ ↗

changeloghttps://github.com/SystemRDL/PeakRDL-cheader/releases ↗