System Register Bank Utilities

This toolkit manages your self-describing FPGA register bank using a YAML source file as the single source of truth. It auto-generates:

• Encoded binary + hex files for FPGA BRAM
• Python constants for software tests
• VHDL constants for ROM depth
• (Optional) Deserializer for runtime SW inspection

📁 Folder Layout

regbank-utils/
├── add_register.py             # Add a register via CLI prompts
├── remove_register.py          # Remove register by name or address
├── validate_schema.py          # Validate schema structure and sanity
├── generate_regbank_pkg.py     # Generate VHDL system_regbank_pkg.vhd
├── gen_info_pkg.py             # Generate VHDL rom_info_pkg.vhd
├── check_regbank_version.py    # Skip regeneration if versions match
├── payload_encoder.py          # YAML → MsgPack/hex for BRAM
├── payload_decoder.py          # Binary → Structured/Text decoding
├── markdown_encoder.py         # Generate Markdown docs from YAML
├── yml_to_csv.py               # Export YAML to CSV
├── bin_to_hex.py               # Convert raw binary to hex file
├── regbank_schema.yml          # 📜 Main register schema example
└── tests/                      # 🧪 Automated tests
    └── test_regbank_utils.py

📦 Requirements

pip install -r requirements.txt

⚙️ Usage

🔄 Encode Register Map

python payload_encoder.py register_map.yaml

Output:

• regbank_manifest.hex (for FPGA)
• regbank_manifest.bin (for software tools)

Flags:

• --format=raw Encodes as raw 32-bit words (default)
• --format=structured Encodes as msgpack dictionary with metadata
• --bin=<bin_file_name> Defines the output binary file name

🧠 Generate Python Constants

python generate_constants.py register_map.yaml regbank_constants.py

🧮 Generate VHDL Info Package

python gen_info_pkg.py $(ROOT_DIR) $(MANIFEST_FILE) $(CONFIG_FILE)

Generates src/pkg/rom_info_pkg.vhd containing build info and register bank version constants.

📖 Generate VHDL Register Package

python generate_regbank_pkg.py register_map.yaml system_regbank_pkg.vhd

Generates system_regbank_pkg.vhd containing register index constants and types.

📖 Decode from Binary (optional)

python payload_decoder.py regbank_manifest.bin
python payload_decoder.py regbank_manifest.bin --out decoded.txt

Flags:

• --format=raw Decodes a raw-encoded binary file (default)
• --format=structured Decodes a structured-packed binary file
• --out=<out_file_name> Defines the output file (text or binary depending on mode)

📝 Generate Documentation

python markdown_encoder.py register_map.yaml -o register_bank.md

📊 Export to CSV

python yml_to_csv.py register_map.yaml register_map.csv

🔍 Register Bank Schema Validators

• Duplicate address detection
• Bitfield overlap validation
• 4-byte alignment check (with --address-mode support)
• Register name format check (UPPER_SNAKE_CASE)
• Warnings with --strict support

🛠 Example CLI Usage

Add a register interactively

python add_register.py regbank_schema.yml

Remove one by name or address

python remove_register.py regbank_schema.yml INJ_CONTROL
python remove_register.py regbank_schema.yml 0x84

Validate schema before generation

python validate_schema.py regbank_schema.yml --strict

Only regenerate if version changed

python check_regbank_version.py regbank_schema.yml rom_info_pkg.vhd || \
  python generate_regbank_pkg.py regbank_schema.yml system_regbank_pkg.vhd

🛠 Integrate into Makefile

regbank_gen: regbank_manifest.hex system_regbank_pkg.vhd regbank_constants.py

regbank_manifest.hex regbank_manifest.bin: register_map.yaml
 python tools/regbank-utils/payload_encoder.py $<

system_regbank_pkg.vhd: register_map.yaml
 python tools/regbank-utils/generate_regbank_pkg.py $< $@

regbank_constants.py: register_map.yaml
 python tools/regbank-utils/generate_constants.py $< $@

synthesis: regbank_gen
 $(VIVADO_XLNX) $(ROOT_DIR)/tcl/gen_synthesis.tcl -tclargs $(ROOT_DIR)

🤖 Future Ideas

• Auto-generate C headers / Rust bindings
• Simulator-aware register dumping
• Register ABI diff tool

Welcome to spec-driven FPGA development. Maintain once. Generate everywhere. ⚡

• No redundant copies of constants
• No manual doc editing
• Fully traceable, testable, and git-friendly