HLS Register Interface Parser

The module pyrogue.utilities.hls._RegInterfParser parses HLS-generated register header macros and generates a starter Rogue application file (application.py) containing RemoteVariable, RemoteCommand, or MemoryDevice definitions.

Why this utility exists

HLS flows often generate AXI addressable register maps described in *_hw.h header files. This utility helps convert those macro-based descriptions into a Rogue tree scaffold so software can quickly mirror the hardware map.

CLI Usage

Run the parser module with one output mode:

python -m pyrogue.utilities.hls._RegInterfParser --remoteVariable
python -m pyrogue.utilities.hls._RegInterfParser --remoteCommand
python -m pyrogue.utilities.hls._RegInterfParser --memoryDevice

At runtime, the tool prompts for a zip file path. It extracts the archive, searches for a *_hw.h file, parses #define macros, groups related macro families, and writes application.py in the current directory.

Typical workflow

  1. Build/export your HLS project artifacts.

  2. Provide the generated archive to this utility.

  3. Select output type (RemoteVariable, RemoteCommand, or MemoryDevice).

  4. Review/edit the generated application.py and integrate it into your project’s Rogue tree.

Supported macro patterns

The parser groups related register macros by common name stems and key suffixes:

  • ADDR

  • BASE / HIGH

  • BITS / WIDTH

  • DEPTH

From these macros, it derives name, address offset, width/depth, and emits appropriate constructor arguments in the generated Python code.

Function Reference

run()

Top-level CLI entry point.

  • Parses command-line options to select output mode.

  • Sets parser state for the selected target object type.

  • Calls parse() then write().

parse()

Parses HLS register macros and returns normalized parameter records.

  • Prompts for zip file location.

  • Validates zip input and extracts archive contents.

  • Locates *_hw.h.

  • Collects and groups #define macros.

  • Enforces a max width constraint (currently 64 bits).

  • Returns a list of namedtuple records matching selected output mode.

write(parameters)

Generates application.py from parsed records.

  • Writes an Application(pr.Device) class skeleton.

  • Emits one definition block per parsed record: - pr.RemoteVariable(...) - pr.RemoteCommand(...) - pr.MemoryDevice(...)

  • Leaves placeholders for user customization in initialize().

Notes and limitations

  • The utility creates a starting point; manual cleanup/refinement is expected.

  • Macro naming conventions in HLS output drive parsing quality.

  • Complex register semantics (arrays, packed bitfields, side effects) may need hand-editing after generation.