Metadata-Version: 2.4
Name: bust
Version: 1.0.0b1
Summary: Generate VHDL register files, UVVM testbenches, headers and documentation from a JSON register map.
Author-email: Ola Groettvik <olagrottvik@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/logvik-org/bust
Project-URL: Documentation, https://bust.readthedocs.io
Project-URL: Repository, https://github.com/logvik-org/bust
Project-URL: Issues, https://github.com/logvik-org/bust/issues
Project-URL: Changelog, https://github.com/logvik-org/bust/blob/master/CHANGELOG.md
Keywords: vhdl,fpga,asic,register-map,generator,uvvm,axi,ipbus,avalon,wishbone,apb
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: docopt>=0.6.2
Requires-Dist: pylatexenc>=2.1
Requires-Dist: Jinja2<4.0,>=3.1.5
Requires-Dist: json5>=0.9
Requires-Dist: textual>=3.1
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Requires-Dist: jsonschema>=4.18; extra == "test"
Requires-Dist: mypy==1.18.2; extra == "test"
Requires-Dist: vsg==3.35.0; extra == "test"
Requires-Dist: black==25.11.0; extra == "test"
Provides-Extra: dev
Requires-Dist: bust[test]; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: furo>=2024.8; extra == "docs"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="docs/images/logo-light.png">
    <img alt="bust: single source of truth" src="https://raw.githubusercontent.com/logvik-org/bust/master/docs/images/logo-light.png" width="480">
  </picture>
</p>

[![Tests](https://github.com/logvik-org/bust/actions/workflows/python_tests.yml/badge.svg)](https://github.com/logvik-org/bust/actions/workflows/python_tests.yml)
[![VHDL simulation](https://github.com/logvik-org/bust/actions/workflows/vhdl_sim.yml/badge.svg)](https://github.com/logvik-org/bust/actions/workflows/vhdl_sim.yml)
[![Docs](https://readthedocs.org/projects/bust/badge/?version=latest)](https://bust.readthedocs.io)
[![PyPI](https://img.shields.io/pypi/v/bust.svg)](https://pypi.org/project/bust/)
[![Python](https://img.shields.io/pypi/pyversions/bust.svg)](https://pypi.org/project/bust/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/logvik-org/bust/blob/master/LICENSE)

**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](https://developer.arm.com/documentation/ihi0022/latest/),
  [IPBus](https://ipbus.web.cern.ch/), SBI (the UVVM simple bus interface),
  [Avalon-MM](https://www.intel.com/content/www/us/en/docs/programmable/683091/current/introduction-to-the-interface-specifications.html),
  [Wishbone](https://wishbone-interconnect.readthedocs.io/) and
  [APB](https://developer.arm.com/documentation/ihi0024/latest/). 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.

```bash
pip install bust
```

## Usage

```bash
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:

```json
{
  "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." }
        ]
      }
    ]
  }
}
```

```bash
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](https://bust.readthedocs.io):

- [Getting started](https://bust.readthedocs.io/en/latest/getting-started.html)
- [Register map format](https://bust.readthedocs.io/en/latest/register-map-format.html)
- [Access modes](https://bust.readthedocs.io/en/latest/access-modes.html)
- [Buses](https://bust.readthedocs.io/en/latest/buses.html)
- [Upgrading from 0.14](https://bust.readthedocs.io/en/latest/upgrading.html)
- [Development](https://bust.readthedocs.io/en/latest/development.html)

Release notes are in the [changelog](https://github.com/logvik-org/bust/blob/master/CHANGELOG.md).
Report bugs and ideas as [GitHub issues](https://github.com/logvik-org/bust/issues).

## License

Licensed under the **Apache License 2.0**. See [LICENSE](https://github.com/logvik-org/bust/blob/master/LICENSE) and
[NOTICE](https://github.com/logvik-org/bust/blob/master/NOTICE).

## Author

**Ola Groettvik** - [GitHub](https://github.com/olagrottvik)

### 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.
