bust 1.0.0

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

Features

• Six buses: AXI4-Lite, IPBus, SBI (the UVVM simple bus interface), Avalon-MM, Wishbone and APB.
• 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.
• A self-checking UVVM testbench for every module, on every bus.
• The base address is a VHDL generic, so one module can sit at any or even multiple addresses.
• C, C++ and Python headers, an IPBus address table for uHAL and 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 with two fields:

{
  "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.
• 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.
• Hand-written reference VHDL and testbenches for all six buses run against the generated VHDL.

Documentation

The full documentation is at bust.readthedocs.io:

• Getting started
• Register map format
• Access modes
• Buses
• 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 is mainly a hand-written tool. Some of the code is 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.