Register map format¶
A register map is one JSON file that describes one module: the bus it sits on, its registers and their fields. bust generates the VHDL, the testbench, the headers and the documentation from it.
{
"bus": {
"type": "axi",
"addr_width": 16,
"data_width": 32
},
"module": {
"name": "uart",
"version": "1.2",
"description": "UART control and status.",
"register": [
{
"name": "ctrl",
"address": "0x0",
"type": "fields",
"sw": "rw",
"hw": "r",
"description": "Transmitter and receiver control.",
"fields": [
{ "name": "tx_en", "type": "bit", "description": "Enable the transmitter." },
{ "name": "rx_en", "type": "bit", "description": "Enable the receiver." },
{
"name": "parity",
"type": "vector",
"width": 2,
"description": "Parity bit.",
"enums": [
{ "name": "PAR_NONE", "value": 0 },
{ "name": "PAR_EVEN", "value": 1 },
{ "name": "PAR_ODD", "value": 2 }
]
},
{
"name": "flush",
"type": "bit",
"position": 8,
"singlepulse": true,
"description": "Write 1 to empty both FIFOs."
}
]
},
{
"name": "baud_div",
"address": "0x4",
"type": "vector",
"width": 16,
"reset": "0x1b2",
"sw": "rw",
"hw": "r",
"description": "Clock cycles per bit."
},
{
"name": "status",
"address": "0x8",
"type": "fields",
"sw": "ro",
"hw": "w",
"description": "Transmitter and receiver state.",
"fields": [
{ "name": "tx_busy", "type": "bit", "description": "A byte is being sent." },
{ "name": "rx_level", "type": "vector", "width": 5, "description": "Bytes in the receive FIFO." },
{
"name": "overrun",
"type": "bit",
"position": 8,
"hw": "r",
"hwset": true,
"onread": "rclr",
"description": "A received byte was lost. Cleared when read."
}
]
}
]
}
}
The file has two sections:
bus: the bus protocol and its address and data widths.module: the module’s name and its registers.
This page describes every key. In the tables, the Default column says
required for a key that must be present. Every other key is optional, and
bust uses the default when the key is left out. The access keys (sw, hw, onread and the
others) decide what software and hardware can do with each field.
Access modes describes what each of them does in hardware.
bust reads and checks the whole file before it writes anything. See How bust checks the file.
Numbers¶
Every number in the file, such as an address, a reset or a width, can be
written as a JSON number or as a string:
Written as |
Read as |
Example |
Value |
|---|---|---|---|
a JSON number |
decimal |
|
16 |
a string |
decimal |
|
16 |
a string that starts with |
hexadecimal |
|
16 |
a string that starts with |
binary |
|
16 |
Plain JSON has no hexadecimal numbers, so a hexadecimal value is a string.
Upper and lower case both work, as in "0X1B2" and "0x1b2". A number cannot
be negative, and a fraction, a space or any other character stops bust. So does
a string with hexadecimal digits but no 0x, because it cannot be decimal:
uart.json:31: module.register[2].reset: "1B2" has hexadecimal digits but no 0x. Write "0x1B2" for a hexadecimal number.
bust also reads the file as JSON5, whatever its name. A
JSON5 file can have comments, trailing commas, keys without quotes and
hexadecimal numbers without quotes, such as "address": 0x1c. bust -a and
the editor keep the comments when they
save a JSON5 file.
Bus¶
"bus": {
"type": "axi",
"addr_width": 16,
"data_width": 32
}
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
string |
required |
The bus protocol, from the table below. |
|
required |
Width of the bus address in bits. |
|
|
required |
Width of the bus data in bits. No register can be wider. |
|
Protocol |
An address selects |
|---|---|---|
|
AXI4-Lite |
a byte |
|
IPBus |
a 32-bit word |
|
SBI |
a byte |
|
Avalon-MM |
a byte |
|
Wishbone B4 classic |
a byte |
|
AMBA APB |
a byte |
Write the type in lowercase. Any other value stops bust:
uart.json:2: bus.type: "AXI" is not one of "axi", "ipbus", "sbi", "avalon", "wishbone", "apb". Did you mean "axi"?
IPBus carries 32-bit data and 32-bit addresses, so an ipbus module needs a
data_width of 32 and an addr_width of at most 32. Other values stop bust
with an error such as:
Bus type ipbus carries 32-bit data, so data_width must be 32 (got 16)
On every bus, data_width must be a whole number of bytes, because bust
places registers data_width / 8 bytes apart on a byte-addressed bus. bust
does not limit the widths further. Buses describes the ports and
the timing of each protocol.
Module¶
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
string |
required |
Module name. It names the generated files and VHDL units, such as |
|
list |
required |
The registers, see Registers. |
|
string |
|
The version of the register map. Every generated file carries it, see Version and hash. Printable ASCII characters other than |
|
string |
|
Shown in the documentation. |
|
boolean |
from the bus |
|
Version and hash¶
bust gives software and hardware two ways to tell which register map they
are built from. version is the text you give in the JSON file, such as
"1.2". bust does not check or change it, so raise it yourself when the
register map changes. The hash is a 32-bit number that bust computes from the
register map on every run, so it changes whenever the register map changes,
with nothing for you to keep up to date.
The hash covers the module name, the data width, byte_addressable and, for
each register and field, the name, register offset, bit position, width, type,
reset, access modes and enumeration values. Descriptions, version, the bus
type and addr_width do not count. Neither does the bust version, so a newer
bust gives the same hash for the same register map. The value is the first 32
bits of the SHA-256 of these values written as JSON.
Both appear in every output:
Output |
Version |
Hash |
|---|---|---|
|
|
|
C header |
|
|
C++ and Python headers |
|
|
IPBus address table |
|
|
Documentation |
Title and page footer (HTML: running header, Markdown: line under the title) |
Title, under the version |
Hash and version registers¶
To let software check at run time which register map the hardware holds, add
a register with "type": "hash", "type": "version" or both. bust sets their
values: the hash, and the version of the module as a number. Both have sw
ro and hw na, and they are constants, so they cost no flip-flops.
Software reads them and compares them with REGMAP_HASH and REGMAP_VERSION
in its header. A different hash means the software and the hardware come from
different register maps. The version tells you which version the hardware
says it is.
"module": {
"name": "uart",
"version": "1.2.0",
"register": [
{
"name": "id_hash",
"type": "hash",
"description": "Register map hash"
},
{
"name": "id_version",
"type": "version",
"description": "Register map version"
},
{
"name": "ctrl",
"sw": "rw",
"hw": "r"
}
]
}
A version register needs a version of the form MAJOR.MINOR or
MAJOR.MINOR.PATCH, with each number from 0 to 255. It holds the version as
0x00MMmmpp: the major number in bits 23 to 16, the minor number in bits 15
to 8 and the patch number in bits 7 to 0, so "1.2" reads as 0x00010200. A
larger version reads as a larger number, so software can also check for a
minimum version.
A hash or version register takes only name, type, address and
description, since bust sets the rest. It spans data_width bits, which
must be at least 32, and a module has at most one of each. Otherwise it is a
register like any other, with a name and an address of your choice, and it
appears in the headers, the IPBus address table, the documentation and the
generated testbench. The hash covers both registers, apart from their values.
So, like the version itself, the value of the version register does not
change the hash.
Put them first, as above, or give them an address, so that they keep their
register offsets while the register map grows. Software built from an older
header then still finds them.
Registers¶
Each entry in register is one register.
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
string |
required |
Register name. See Names. |
|
string |
|
|
|
next free address |
Register offset. See Addresses. |
|
|
|
Width of a |
|
|
|
Reset value of a register without fields. See Reset values. |
|
|
string |
|
Shown in the documentation and the IPBus address table. |
|
list |
none |
The fields of a |
access keys |
Defaults for the register’s fields. See Access keys. |
Register types¶
|
The register holds |
|---|---|
|
one |
|
one |
|
one |
|
the fields listed under |
|
the register map hash, as a read-only constant of |
|
the |
A register without fields works like one field that spans the register. It
takes the register’s reset and access keys, and to_hw and from_hw hold
its value directly, with no record of its own. bust generated this member of
to_hw for baud_div in the example:
baud_div : std_logic_vector(15 downto 0);
Your logic reads it as to_hw.baud_div.
bust ignores a width on a default or bit register and prints a warning:
User-specified width of default register does not match the expected width (32). Ignoring configured width.
A register with a fields list is a fields register, so you can leave out
"type": "fields". It needs at least one field. A fields list on a register
of another type stops bust.
Addresses¶
address is the register offset, the register’s distance from the module’s
base address. See Base address and address range. It is a
number, such as "0x1c" or 28. The address must fit in
addr_width bits.
Give every register an address when you can. The register map then says where each register is, and adding, removing or reordering registers does not move the others.
address is optional, though. A register without an address gets the lowest
free address. bust goes through the list in order and places each such
register at the first address that no earlier register uses. It steps by
data_width / 8 when addresses count bytes and by 1 when they count data
words. See Byte and word addresses. With AXI4-Lite
and 32-bit data, these registers get the addresses in the table:
"register": [
{ "name": "ctrl", "address": "0x0" },
{ "name": "status" },
{ "name": "irq", "address": "0x10" },
{ "name": "debug" }
]
Register |
|
Address |
|---|---|---|
|
|
0x0 |
|
left out |
0x4 |
|
|
0x10 |
|
left out |
0x8 |
debug comes after irq in the list, but 0x8 is the lowest address that no
earlier register uses.
A register with an address that an earlier register already took stops bust.
With "address": "0x4" on irq, status would already have taken 0x4:
When specifying address for register irq, address 0x4 is already assigned to other register
So either give every register an address, or list the registers with an address before the registers without one.
bust -a gives every register a new address, in list order, and writes the
addresses into the JSON file. It replaces addresses you set by hand. See
Command line.
The generated register file compares the whole address, so software has to use the exact address of each register. An access to any other address, including a byte address inside a register, gets the bus’s error response. See Access modes.
The base address of the module is not part of the register map. You set it
with the G_BASE_ADDRESS generic when you instantiate the module. See
Generated HDL.
Byte and word addresses¶
An address counts either bytes or data words. byte_addressable in module
says which:
|
An address counts |
bust places registers |
An address you set |
|---|---|---|---|
|
bytes |
|
must be a multiple of |
|
data words |
1 apart |
can be any address |
The default follows the bus: false on IPBus, whose addresses count 32-bit
words, and true on every other bus. Set false on another bus when the
master or the interconnect drives word addresses, as many Wishbone designs and
some bridges from IPBus do. The endpoint compares the address exactly as the
master drives it, so byte_addressable must match what the master drives.
With 32-bit data, the third register of a module is at 0x8 with true and
at 0x2 with false.
With true, an address that is not a multiple of data_width / 8 stops bust:
Address 0x6 of register baud_div is not a multiple of 4, the data width in bytes
Reset values¶
reset is a number, such as "0x1b2" or 434. The value must
fit in the register’s width, otherwise bust stops:
Could not parse register baud_div: Invalid register format: Reset value does not match register: baud_div
Leave reset out of a fields register and give each field its own reset.
bust builds the register’s reset value from its fields.
Names¶
Module, register, field and enumeration names become VHDL identifiers, so they must follow the VHDL rules for basic identifiers:
start with a letter,
contain only letters, digits and underscores,
not end with an underscore or contain two underscores in a row,
not be a VHDL reserved word, such as
signal,inorregister.
A field named in, for example, stops bust. Reserved words count in any case,
so IN is rejected too:
Could not parse register ctrl: Invalid identifier: in - identifier cannot be identical to VHDL keyword.
bust warns, but goes on, when a name mixes uppercase and lowercase letters. The headers turn names into uppercase
constants, such as CTRL_PARITY_MASK.
Register names must be unique in the module, field names in their register
and enumeration names in their field. VHDL ignores case, so ctrl and CTRL
are the same name, and bust stops when two names differ only in case. A
register cannot have the same name as the module, because both would declare a
type t_<name>_regs.
Fields¶
A fields register lists its fields under fields. Each entry is one field.
Key |
Type |
Default |
Meaning |
|---|---|---|---|
|
string |
required |
Field name. See Names. |
|
string |
required |
|
|
|
Width of a |
|
|
next free bit |
Lowest bit of the field. See Bit positions. |
|
|
|
Reset value of the field. |
|
|
string |
|
Shown in the documentation and the IPBus address table. |
|
list |
none |
Named values. See Enumerations. |
access keys |
from the register |
See Access keys. |
Bit positions¶
Fields fill the register from bit 0 upwards, in the order you list them. Each
field starts at the bit after the previous one, unless it has a position. A
position can leave a gap, but it cannot go back, so list the fields from the
lowest bit to the highest. In the example, flush sits at bit 8 and bits 4 to
7 of ctrl are reserved:
Field |
Bits |
|---|---|
|
0 |
|
1 |
|
3:2 |
|
8 |
A position below the next free bit stops bust:
Could not parse register ctrl: Invalid field format: Field 'flush' in register 'ctrl': position 2 overlaps bits already in use (next free bit is 4).
A fields register is as wide as its highest field bit plus one, 9 bits for
ctrl. It cannot be wider than data_width:
Could not parse register ctrl: Register width exceeded module data width by 1 in register ctrl
Module width: 32
Register width: 33
Bits that no field covers read as 0, and writes to them have no effect.
Reserved fields¶
The LaTeX, HTML and Markdown documentation and the editor overview show each run of bits that no field covers as a reserved field, in the bit diagram and among the fields, in bit order. For ctrl in the example:
31 9 8 7 4 3 2 1 0
┌────────────────────────────────────────────────────────────────────┬───────┬───────────┬────────┬───────┬───────┐
│ reserved │ flush │ reserved │ parity │ rx_en │ tx_en │
└────────────────────────────────────────────────────────────────────┴───────┴───────────┴────────┴───────┴───────┘
- 0 - 0x0 0 0
tx_en Enable the transmitter. (sw: rw, hw: r)
rx_en Enable the receiver. (sw: rw, hw: r)
parity Parity bit. (sw: rw, hw: r; values: PAR_NONE=0, PAR_EVEN=1, PAR_ODD=2)
reserved Bits 7:4. Read as 0, writes have no effect.
flush Write 1 to empty both FIFOs. (sw: rw, hw: r, singlepulse)
reserved Bits 31:9. Read as 0, writes have no effect.
Reserved fields exist only in the documentation and the editor overview, and you do not list them in the JSON file. The VHDL, the headers and the IPBus address table do not change, and neither does the hash.
Enumerations¶
A field with an enums list has named values. bust generates a VHDL
enumeration type for it, and the headers get a constant for each value.
{
"name": "parity",
"type": "vector",
"width": 2,
"enums": [
{ "name": "PAR_NONE", "value": 0 },
{ "name": "PAR_EVEN", "value": 1 },
{ "name": "PAR_ODD", "value": 2 }
]
}
Each entry has two keys:
name: the name of the value. It becomes a VHDL enumeration literal, so it follows the name rules and must be unique in the field.value: the encoding, a number. It must fit in the field’s width and be unique in the field.
bust reads no other keys from an entry and warns about any other key, such as
a description. The values need not be in order or contiguous, and not every
encoding needs a name. parity leaves 3 unnamed.
Without a reset, an enumerated field resets to the entry with value 0. When
no entry has value 0, it resets to the first entry in the list. A reset must
be the value of one of the entries:
Could not parse register ctrl: Invalid field format: Reset value 0x3 of enumerated field parity in reg ctrl matches no declared enum value
The other checks give these errors:
Could not parse register ctrl: Invalid field format: Enum 'PAR_ODD' value 4 does not fit field parity (width 2) in reg ctrl
Could not parse register ctrl: Invalid field format: Duplicate enum value 1 in field parity in reg ctrl
Could not parse register ctrl: Invalid field format: Duplicate enum name 'PAR_EVEN' in field parity in reg ctrl
enums belongs on a field. On a register without fields, bust ignores it with
a warning, so give such a register "type": "fields" and one field.
Access modes describes the generated type,
how software writes are decoded, and which access keys an enumerated field
cannot have.
Access keys¶
Key |
Values |
Default |
|---|---|---|
|
|
|
|
|
|
|
|
none |
|
|
none |
|
|
|
|
|
|
|
|
|
|
|
|
Each key can sit on a field, or on its register as the default for all the register’s fields. A key on the field wins over the same key on the register. Access modes describes what each key does, how inheritance works, and which combinations bust rejects.
Give the boolean keys as JSON true or false. A string such as "false"
stops bust. null counts as false. A value that is not in the table stops
bust and lists the valid ones:
uart.json:14: module.register[0].sw: "rx" is not one of "rw", "ro", "wo", "na". Did you mean "rw"?
Keys bust does not know¶
bust warns about each key it does not read, and otherwise ignores it. A
misspelt key such as onwrit gives:
uart.json:21: module.register[0].fields[0].onwrit: bust does not know this key and ignores it. Did you mean 'onwrite'?
bust -a and the editor keep unknown
keys when they save the file.
How bust checks the file¶
bust checks a register map in two steps, and stops after the first step that finds a problem.
The file must be JSON or JSON5. An error in the syntax gives the line and the column, as in
uart.json:12:7: Expecting ',' delimiter.Each value must have the type and the form this page gives for its key, and each required key must be present. This is the JSON Schema of the register map. bust lists every problem it finds in one run, then the number of problems, and exits with status 1:
uart.json:14: module.register[0].sw: "rx" is not one of "rw", "ro", "wo", "na". Did you mean "rw"? uart.json:31: module.register[2].reset: "1B2" has hexadecimal digits but no 0x. Write "0x1B2" for a hexadecimal number. uart.json:40: module.register[3]: missing key 'name' 3 problems in uart.json
Each line starts with the file and the line in it, so an editor or a terminal that knows the form can jump there. Next comes the path to the value:
module.register[2]is the third register in the list, counted from 0, andfields[1]its second field. An unknown key is a warning in the same form, see Keys bust does not know.The rules that tie keys together come last: two registers at one address, a field that does not fit its register, a reset value that does not fit, a name VHDL does not accept, or an access mode bust cannot generate. bust stops at the first of these and names the register, as in:
Could not parse register ctrl: Register width exceeded module data width by 1 in register ctrl
The editor gives the same messages, without the file name and the line.
JSON Schema¶
bust.schema.register_map_schema() returns the JSON Schema (draft 2020-12) of
the register map, which step 2 checks. It lists each key with its allowed
values, its default and a short description, for editors and other tools.
bust also reads the values of sw, hw, onread, onwrite and type in
upper case, which the schema leaves out.
The schema of the latest release is at
https://bust.readthedocs.io/en/stable/register-map.schema.json. Point a
register map to it with a "$schema" key, and VS Code, JetBrains IDEs and other
editors with JSON Schema support complete keys, show each description on hover
and mark wrong values, with no extension:
{
"$schema": "https://bust.readthedocs.io/en/stable/register-map.schema.json",
"bus": {"type": "axi", "addr_width": 32, "data_width": 32},
"module": {"name": "timer", "register": []}
}
bust ignores the key, and the editor adds it to each register map it creates.