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

regbank utils