{"id":8406,"library":"peakrdl-cheader","title":"PeakRDL C-Header Generator","description":"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.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/SystemRDL/PeakRDL-cheader","tags":["SystemRDL","PeakRDL","CSR","compiler","tool","registers","generator","C","header","software","EDA"],"install":[{"cmd":"pip install peakrdl-cheader","lang":"bash","label":"Install only PeakRDL C-Header"},{"cmd":"pip install peakrdl","lang":"bash","label":"Install PeakRDL CLI (includes c-header)"}],"dependencies":[{"reason":"Required for parsing SystemRDL files into an elaboratable model that peakrdl-cheader consumes.","package":"systemrdl-compiler","optional":false}],"imports":[{"note":"This is the primary class for generating C headers via the Python API.","symbol":"CHeaderExporter","correct":"from peakrdl_cheader.exporter import CHeaderExporter"},{"note":"Required to compile SystemRDL files before exporting. Not part of peakrdl-cheader itself, but a core dependency.","symbol":"RDLCompiler","correct":"from systemrdl import RDLCompiler"}],"quickstart":{"code":"import os\nfrom systemrdl import RDLCompiler\nfrom peakrdl_cheader.exporter import CHeaderExporter\n\n# Create a dummy RDL file for demonstration\nrdl_content = '''\n  addrmap my_device {\n    reg { field {} my_reg[31:0] = 0; } control_reg;\n    regfile my_block[8] {\n      reg { field {} status_field[7:0]; } status_reg;\n    }\n  };\n'''\nwith open('example.rdl', 'w') as f:\n    f.write(rdl_content)\n\n# 1. Compile the SystemRDL file\nrdlc = RDLCompiler()\nrdlc.compile_file('example.rdl')\ntop_node = rdlc.elaborate()\n\n# 2. Configure and generate the C header\nexporter = CHeaderExporter(\n    std=\"gnu11\", # Specify C standard, e.g., gnu11, c99\n    generate_bitfields=True, # Enable bitfield structs\n    bitfield_order_ltoh=True # Specify bitfield packing order\n)\noutput_path = 'example.h'\nexporter.export(node=top_node, path=output_path)\n\nprint(f\"C header generated successfully at {output_path}\")\n\n# Clean up dummy RDL file\nos.remove('example.rdl')\n\n# Example of how to use from CLI:\n# peakrdl c-header example.rdl -o example.h --std gnu11 --bitfields ltoh","lang":"python","description":"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."},"warnings":[{"fix":"Review the LGPLv3 license terms to ensure compatibility with your project's licensing and compliance requirements.","message":"The 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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"SystemRDL 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"C'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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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)`.","cause":"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.","error":"Generated C header has incorrect bitfield packing order, leading to wrong register accesses."},{"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.","cause":"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.","error":"Generated C struct names or typedefs collide, or do not reflect the desired hierarchy."},{"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).","cause":"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.","error":"My SystemRDL file compiles, but the generated C header for wide registers (>64 bits) is malformed or inaccessible."}]}