Command line¶
bust reads one JSON register map and writes the VHDL, the testbench, the headers and the documentation for it. This page lists the options, where the files go, and what bust does when they already exist.
Usage¶
bust --help starts with the usage lines:
Usage:
bust FILE [-o DIR] [[[-f] [-d | -p] [-i] [--replace-top]] | [-a [-f]] | [--migrate [-f]] | [-c | -e]]
bust --version
bust -h | --help
FILE is the JSON register map, described in
Register map format. The usage line also says which
options go together:
-ocombines with everything else, but only a run that generates files uses it.-f, one of-dand-p, and-icombine with each other. They control a normal run that generates files.-asaves the JSON file instead of generating files. It takes-fto save without asking.--migrateconverts the files instead of generating them. It takes-fto convert without asking.-cand-eopen the editor, so they stand alone.
Any other combination, such as -d -p or -c -f, makes bust print the usage
and exit with status 1.
Options¶
Option |
Effect |
|---|---|
|
Write the output under |
|
Overwrite existing files without asking, except |
|
Do not write the documentation: no |
|
Write the |
|
Do not write the headers: the |
|
Replace |
|
Give every register a new address and save the JSON file. Generates nothing. With |
|
Convert a bust 0.14 JSON file and its |
|
Create |
|
Open |
|
Print |
|
Print the usage and a short description of each option, then exit. |
Every run that generates files writes the VHDL files and the testbench. No option turns them off. Software headers describes the headers and the address table, and Documentation the documentation.
Output directory¶
bust writes into -o DIR, or else into the directory that holds the JSON
file. There it adds a directory named after the module (the name in the
module section).
Inside that directory, bust writes four directories. This is the output of
bust example_ipbus.json -o out for the IPBus example from the repository,
with pdflatex installed:
out/
└── example_ipbus/
├── doc/
│ ├── example_ipbus.aux
│ ├── example_ipbus.html
│ ├── example_ipbus.log
│ ├── example_ipbus.md
│ ├── example_ipbus.pdf
│ └── example_ipbus.tex
├── hdl/
│ ├── example_ipbus.vhd
│ ├── example_ipbus_ipb_endpoint.vhd
│ ├── example_ipbus_localbus_pkg.vhd
│ ├── example_ipbus_regfile.vhd
│ └── example_ipbus_regfile_pkg.vhd
├── header/
│ ├── example_ipbus.h
│ ├── example_ipbus.hpp
│ ├── example_ipbus.py
│ └── example_ipbus.xml
└── tb/
└── example_ipbus_tb.vhd
Directory |
Files |
Described in |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
The endpoint file is named after the bus:
Bus type |
Endpoint file |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
bust creates all four directories whenever it generates files, so -d leaves
an empty doc/ and -i an empty header/.
Existing files¶
This section is about the files bust generates. <module>.vhd is yours, see
Your top level.
Without -f¶
For each file that already exists, bust asks before it replaces it:
Do you want to overwrite out/example_ipbus/hdl/example_ipbus_localbus_pkg.vhd? (y/N):
Answer y to replace the file. Any other answer keeps it, and bust prints
Did not write and the path, then goes on with the next file. The generated
files refer to each other, so keep them from the same run.
bust asks only when standard input is a terminal. In a script or a CI job, it stops at the first existing file instead and exits with status 1:
ERROR: Could not generate local-bus VHDL files
An error occurred during output generation...
FileExistsError: out/example_ipbus/hdl/example_ipbus_localbus_pkg.vhd already exists and there is no terminal to ask whether to overwrite it. Run bust with -f to overwrite it.
Use -f in scripts.
With -f¶
bust replaces every file it generates without asking. It does not replace
<module>.vhd, which is yours, and says how to:
out/example_axi/hdl/example_axi.vhd is yours, so -f did not replace it. To replace it with a fresh starter, run bust with --replace-top.
Your top level¶
<module>.vhd is the top level of your module, and the file is yours. When it
does not exist, bust writes a starter and says so:
Wrote out/example_axi/hdl/example_axi.vhd, a starting point that is yours to edit. bust will not change it again.
After that, bust leaves the file alone, with or without -f.
Generated HDL describes the starter.
--replace-top replaces the file with a fresh starter and keeps your old file
next to it as <module>.vhd.bak. bust asks first, and with -f it replaces
the file without asking:
bust example_axi.json -o out --replace-top -f
Replaced out/example_axi/hdl/example_axi.vhd with a fresh starter. The old file is out/example_axi/hdl/example_axi.vhd.bak.
Renumber addresses¶
-a reads FILE, gives every register a new address, and writes the
addresses into FILE. It generates no other output. It asks before it replaces
FILE, or, without a terminal, stops as described in
Existing files. Add -f to save without asking:
bust timer.json -a -f
bust numbers the registers in the order they appear, starting at 0. They are
data_width / 8 apart, and 1 apart on IPBus or with "byte_addressable": false
in the module. See
Byte and word addresses.
Addresses you wrote yourself are replaced.
Only the addresses change in the file. A register without an address gets
one, and an address that is already right keeps the form it has, such as 16
or "0x10". Comments, keys bust does not know and the layout of the file stay
as they are, in JSON and JSON5 files. These registers:
"register": [
{ "name": "ctrl", "sw": "rw", "hw": "r", "type": "vector", "width": 8, "address": "0x10" },
{ "name": "status", "sw": "ro", "hw": "w" },
{ "name": "irq", "sw": "rw", "hw": "r", "address": "0x8" }
]
become:
"register": [
{ "name": "ctrl", "sw": "rw", "hw": "r", "type": "vector", "width": 8, "address": "0x0" },
{ "name": "status", "sw": "ro", "hw": "w", "address": "0x4" },
{ "name": "irq", "sw": "rw", "hw": "r", "address": "0x8" }
]
When every address is right already, bust says
The addresses in FILE are in order already. and does not write FILE.
Migrate a bust 0.14 file¶
bust reads only the bust 1.0 register map format. A file written for bust 0.14 stops bust with an error for each 0.14 key or value, such as:
timer.json:14: module.register[0].mode: a bust 0.14 key, which bust no longer reads. Run bust with --migrate to convert the file.
bust FILE --migrate converts such a file to the bust 1.0 format. It replaces
each mode with the access keys it stands for, removes the settings section
and the keys bust 1.0 has no use for, and changes the old type names and
values. It changes only those values in the file, so comments and the layout
stay. It also connects a bust 0.14 <module>.vhd to the bust 1.0 endpoint.
It lists the changes and asks first, unless you add -f, and keeps each old
file with the suffix .0_14. Give it the same -o as your other runs, then
generate the files:
bust timer.json -o out --migrate
bust timer.json -o out
bust lists any line of <module>.vhd it could not change. Change those by
hand. A register with a pulse_cycles other than 1 or a stall_cycles other
than 0 stops the migration, because bust 1.0 cannot generate that timing.
Interactive editor¶
-c and -e open a full-screen editor in the terminal, built on
Textual. It runs in any terminal Textual
supports, on Linux, macOS and Windows. It needs an interactive terminal.
Without one, bust stops with
The editor (-c, -e) needs an interactive terminal. and exits with status 1.
The main screen¶
The main screen shows the register map in three panes:
Registers lists every register with its name, address, type, width,
sw,hw, reset and description.Fields of … lists the fields of the register under the cursor, if it is a
fieldsregister.The right pane lists each key of the register or field in focus with its value, and under it what the key does. A key the file does not set shows the value bust uses, dimmed, with
(not set).
The panes are numbered 1, 2 and 3, and the one with focus has a highlighted
border. Tab and Shift+Tab move between them, the keys 1, 2 and 3 jump to
one, and the mouse works too. The arrow keys move within a pane. Enter on a
register or a field moves to its keys, and Enter on a key opens a dialog to
change it. The line under the title repeats this, and ? lists every key.
These keys work on the main screen, and the footer lists most of them:
Key |
What it does |
|---|---|
|
Add a register. |
|
Add a field to the register under the cursor, which must be a |
|
Remove the register or field in focus, after asking. |
|
Change the module’s |
|
Write the address bust gives each register without an |
|
Show the overview of the register map. |
|
Switch between the light and the dark theme, which use the colours of this documentation. |
|
List every key. |
|
Save |
|
Quit. With unsaved changes, the editor asks whether to save first. |
In a dialog, Enter or OK takes the answers and Escape cancels. A key with a
fixed set of values, such as sw or onread, is a list to choose from. Choose
not set, or press Remove from the file for a key typed as text, to remove
the key from the file. Changing the type of a register asks for what the new
type needs, such as the first field of a fields register, and removes what it
no longer uses, such as the width of a former vector. The enums row of a
field lists its enumerated values, where a adds one, Enter changes one and
Delete removes one.
The overview¶
o shows the whole register map the way the
documentation does. It has the module’s name, version,
register map hash and bus, then the register list with the number, name,
software and hardware access, address, type, width and reset of each register.
Then each register follows with its address, its description and a bit
diagram. The diagram draws each field as a box over its bits, with the
numbers of its highest and lowest bit above and its reset value below. Bits no
field uses show as reserved, see Reserved fields. A box is wider than its bits where its name would
not fit. Under the diagram, each field is listed with its description and its
access.
Enter on a register in the list moves to its diagram. Escape goes back to the editor. The overview shows the register map as it is in the editor, including changes that are not saved yet.
Create a register map¶
bust FILE -c opens a dialog for the bus type, the address width, the data
width (not for IPBus, which has 32-bit data), the module name, the version, a
description, and whether addresses count bytes (byte_addressable). The module
name defaults to the file name, and byte_addressable to what the bus does.
Then it asks for the first register. FILE must not exist. If it does, bust
stops with FILE exists. Edit it with bust FILE -e.
The editor writes every key the register map format recommends, even where bust has a default:
The module gets
name,version,descriptionandbyte_addressable.Each register gets
name,address,type,sw,hw,widthfor avector,resetunless it has fields, anddescription. The editor offers the next free address.Each field gets
name,type,position,widthfor avector,resetanddescription. A field getsswandhwonly where they differ from its register, so it keeps inheriting the rest.
This applies to every register and field the editor adds, with -c or -e.
A hash or version register gets only name, address, type and
description, since bust sets its access and its value. Set the other keys, such as onwrite, in the right pane once the register or
field is added.
Edit a register map¶
bust FILE -e reads FILE, in JSON or JSON5, and opens the main screen.
Checks¶
The editor checks every change the way bust FILE checks the register map. A
dialog shows bust’s message under the answers and stays open for an answer
bust rejects, such as an address that another register uses:
Could not parse register count: Invalid field format: onwrite requires a software-writable field (sw rw or wo) (field count in reg count)
Fix the answer or press Escape to keep the old value. A change made without a
dialog, such as removing a field, shows Not changed: and bust’s message
instead. So the editor cannot save a register map that bust rejects. It shows
each warning, such as an unknown key, once.
Saving¶
The editor writes FILE only when the register map changed. Opening a file
and quitting leaves it untouched, and changing a value and changing it back is
no change.
Saving changes only the text of the values that changed. Comments, the order
of the keys, number forms such as 0x1c, keys bust does not know and the
layout of the file stay as they are. New values are written as plain JSON,
which a JSON5 file accepts too. If FILE changed on disk after the editor read
it, saving stops with FILE changed after the editor read it, so it was not saved.
For a JSON5 file that bust cannot edit in place, such as one with escaped characters in a key, the editor says so when it opens the file. Saving then rewrites the file as plain JSON without comments, and asks first.
Messages and debug.log¶
bust prints its progress and its errors on standard error. A run that writes every file prints:
Parsing file: example_axi.json...
Project path: /path/to/out
Generating local-bus VHDL files...
Generating Module Include Files...
Generating Module Documentation...
Generating Documentation PDF...
When pdflatex is not on your PATH, the last line is instead:
pdflatex is not on PATH, so bust skipped the PDF. The documentation is in /path/to/out/example_axi/doc/example_axi.html.
When pdflatex runs but reports errors, bust prints
pdflatex reported errors. See <doc dir>/<module>.log. In both cases bust
still exits with status 0, since every other file was written.
Documentation describes the PDF step.
An error in the register map is printed as a message that names the problem, and bust exits with status 1. A value of the wrong form gives the file, the line and the path to the value, and bust lists every such problem in one run:
timer.json:3: bus.type: "pci" is not one of "axi", "ipbus", "sbi", "avalon", "wishbone", "apb"
timer.json:12: module.register[1].address: "1c" has hexadecimal digits but no 0x. Write "0x1c" for a hexadecimal number.
2 problems in timer.json
A rule that ties keys together stops bust at the first problem:
When specifying address for register reg1, address 0x0 is already assigned to other register
How bust checks the file
describes the steps. A file that is missing or not JSON gives
Cannot read timer.json: No such file or directory or the line and column of
the error, as in timer.json:3:5: Expecting ',' delimiter.
A run that stops with an error also adds to debug.log in the directory you
run bust from. Each run starts with a line that gives the time and the command
line, followed by the same messages with a timestamp, a line for each file
written, and the full Python traceback of the error. Look there when a message
is not enough, and attach it when you report a problem. A run that succeeds
adds nothing, and neither do --version, --help and a usage error. Delete
the file when you no longer need it.
Exit codes¶
Code |
Meaning |
|---|---|
0 |
Success. Also when you answered no to an overwrite question, when the PDF could not be made, and for |
1 |
Any error: invalid command-line arguments, a JSON file that is missing or not valid JSON, a register map that fails validation, a file that could not be written (including an existing file with no terminal to ask), or the editor without a terminal. |
From Python¶
bust.generate_files returns every file the command line writes, without writing anything or running pdflatex. It takes the text of a register map or the parsed JSON, and gives the content of each file by its path under the output directory:
import bust
with open("timer.json", encoding="utf-8") as fp:
files = bust.generate_files(fp.read())
print(files["timer/hdl/timer_regfile.vhd"])
The paths are the ones bust timer.json -o DIR -p writes under DIR, with / on every platform. The result always holds a starter timer/hdl/timer.vhd. The command line writes that file only when it is missing, since it is yours to edit, so a program that keeps files should do the same. A register map with problems raises bust.exceptions.FormatError, with every problem in the message.