bust 1.0.0b1

bust generates the register file of an FPGA or ASIC module from a JSON register map. From one file it writes the VHDL register file with its bus endpoint, a self-checking UVVM testbench, C, C++ and Python headers, an IPBus address table and LaTeX documentation.

Features

• Six buses: AXI4-Lite, IPBus, SBI (the UVVM simple bus interface), Avalon-MM, Wishbone and APB. Each is a thin endpoint in front of the same register file.
• Your design reaches every field by name through the to_hw and from_hw VHDL records, and enumerated fields become VHDL enumeration types.
• Separate software and hardware access per field, with SystemRDL-style side effects: clear or set on read, set, clear or toggle on write, single-cycle pulses, hardware set and clear, write enables and access strobes.
• The base address is a VHDL generic, so one module can sit at any address.
• A self-checking UVVM testbench for every module, on every bus.
• C, C++ and Python headers, an IPBus address table for uHAL and LaTeX/PDF documentation from the same file.

Installation

bust needs Python 3.9 or newer.

pip install bust

Usage

bust FILE [-o DIR] [[[-F | -f] [-d | -p] [-i]] | [-a] | [-c | -e]]
bust --version
bust -h | --help

A minimal register map with one control register:

{
  "bus": { "type": "axi", "addr_width": 32, "data_width": 32 },
  "module": {
    "name": "blinky",
    "version": "1.0",
    "description": "LED control.",
    "register": [
      {
        "name": "ctrl", "address": "0x0", "sw": "rw", "hw": "r", "type": "fields",
        "description": "LED control.",
        "fields": [
          { "name": "enable", "type": "bit", "description": "Turn the LED on." },
          { "name": "rate", "type": "vector", "width": 4, "description": "Blink rate." }
        ]
      }
    ]
  }
}

bust blinky.json -o out -p

This writes out/blinky/ with the VHDL in hdl/, the testbench in tb/, the headers in header/ and the LaTeX documentation in doc/. hdl/blinky.vhd is a starter top level that is yours to edit: bust writes it once and leaves it alone after that. Your logic reads to_hw.ctrl.enable and to_hw.ctrl.rate from blinky_axi_endpoint, which bust regenerates on every run.

How bust is tested

• The generated files for the example register maps are kept in the repository. Every change is compared with them byte for byte, on Python 3.9 to 3.14.
• Every change to the generated VHDL is simulated with nvc and UVVM. This runs the generated testbench on all six buses, a register map with every class of access mode combination, and two modules compiled into one library.
• Hand-written reference VHDL and testbenches for all six buses run against the generated VHDL. They are the one check that does not come from the generator itself.

Documentation

The full documentation is at bust.readthedocs.io:

• Getting started
• Register map format
• Access modes
• Buses
• Upgrading from 0.14
• Development

Release notes are in the changelog. Report bugs and ideas as GitHub issues.

License

Licensed under the Apache License 2.0. See LICENSE and NOTICE.

Author

Ola Groettvik - GitHub

AI assistance

bust started as a hand-written tool. Most of the code for 1.0 was written with AI assistance. The author reviewed every change, and no change is merged before it passes the checks under How bust is tested above.