Generated HDL¶
For each register map, bust writes a small set of VHDL files. Your design
instantiates one entity, named after the module, connects the bus to it, and
reads and drives the registers through two records, to_hw and from_hw.
The examples on this page use a timer module on AXI4-Lite. Every VHDL snippet is bust’s output for this register map, trimmed:
{
"bus": {
"type": "axi",
"addr_width": 32,
"data_width": 32
},
"module": {
"name": "timer",
"register": [
{
"name": "ctrl", "address": "0x0", "sw": "rw", "hw": "r", "type": "fields",
"fields": [
{"name": "enable", "type": "bit"},
{"name": "mode", "type": "vector", "width": 2,
"enums": [{"name": "ONESHOT", "value": 0}, {"name": "PERIODIC", "value": 1}]},
{"name": "start", "type": "bit", "singlepulse": true}
]
},
{
"name": "load", "address": "0x4", "sw": "rw", "hw": "r",
"type": "default", "swmod": true
},
{
"name": "status", "address": "0x8", "sw": "ro", "hw": "w", "type": "fields",
"fields": [
{"name": "count", "type": "vector", "width": 16, "we": true},
{"name": "running", "type": "bit"}
]
},
{
"name": "irq", "address": "0xc", "sw": "rw", "hw": "r", "type": "fields",
"fields": [
{"name": "expired", "type": "bit", "hwset": true, "onwrite": "woclr"}
]
}
]
}
}
The register map format page describes the JSON, and
Access modes describes what sw, hw and the modifiers do.
Files¶
For a module named <module>, bust writes these files:
File |
Contents |
|---|---|
|
The top level of the module, the entity your design instantiates. This file is yours, see Your top level. |
|
The bus endpoint. It translates the bus protocol to the local bus and instantiates the register file. |
|
The register file: storage, access-mode behaviour, hardware updates, the read mux and the bus response. |
|
Register offsets, enumeration types, and the |
|
The local-bus records |
|
A self-checking UVVM testbench for the bus endpoint. See Testbenches. |
<bus> is axi, ipb, sbi, avalon, wishbone or apb. A file with a
suffix after the module name is bust’s: bust writes it again on every run.
<module>.vhd is yours. The Buses page lists the ports of each
endpoint.
Each generated file starts with a line such as
-- Generated by bust v1.0.0 2026-10-23 14:05. To keep the files the same
from run to run, set the environment variable SOURCE_DATE_EPOCH to a fixed
time in seconds since 1970.
The generated VHDL follows the default style of
vsg, the VHDL Style
Guide, with constants and generics in upper case, use clauses not indented
and conditions without parentheses. The rules are in
vsg.yaml, and the
tests of bust check the generated examples against them with vsg 3.35.0. If
your project checks its VHDL with other vsg rules, leave the generated files
out of that check, or run vsg on them with your rules.
your design
└── <module> <module>.vhd: yours
└── <module>_<bus>_endpoint generated: the bus side
└── <module>_regfile generated: the registers and the address decoding
Where the files go¶
The VHDL lands in hdl/ and the testbench in tb/, next to the header/ and
doc/ directories of the software headers and the documentation. For
the timer:
timer/
├── doc/
├── hdl/
│ ├── timer.vhd
│ ├── timer_axi_endpoint.vhd
│ ├── timer_localbus_pkg.vhd
│ ├── timer_regfile.vhd
│ └── timer_regfile_pkg.vhd
├── header/
└── tb/
└── timer_tb.vhd
bust puts the four directories in a directory named after the module, here
timer/, inside the output directory. You choose the output directory with
-o. Command line describes the default.
Compile order¶
Compile the files in this order, all into the same library:
<module>_localbus_pkg.vhd<module>_regfile_pkg.vhd<module>_regfile.vhd<module>_<bus>_endpoint.vhd<module>.vhd<module>_tb.vhd, for simulation only
The files refer to each other through work, so the library name is up to
you. The files use VHDL-2008 syntax, so compile with VHDL-2008 enabled. With
GHDL, into a library called periph:
for f in timer_localbus_pkg timer_regfile_pkg timer_regfile timer_axi_endpoint timer; do
ghdl -a --std=08 --work=periph timer/hdl/$f.vhd
done
An IPBus module also needs the IPBus package compiled into a library called
ipbus first, see IPBus.
The local bus¶
bust keeps all register-map logic in one register file per module and connects it to your bus through a thin endpoint. Between the two is the local bus, a minimal single-beat interface. The register file is the same VHDL whichever bus you choose, so every bus gets the same access-mode behaviour. Changing the bus replaces the endpoint, and the register file stays the same.
The local bus is two records in <module>_localbus_pkg:
package timer_localbus_pkg is
constant C_LB_ADDR_WIDTH : natural := 32;
constant C_LB_DATA_WIDTH : natural := 32;
type t_lb_m2s is record
address : std_logic_vector(C_LB_ADDR_WIDTH - 1 downto 0);
wdata : std_logic_vector(C_LB_DATA_WIDTH - 1 downto 0);
wen : std_logic;
ren : std_logic;
end record t_lb_m2s;
type t_lb_s2m is record
rdata : std_logic_vector(C_LB_DATA_WIDTH - 1 downto 0);
ack : std_logic;
err : std_logic;
end record t_lb_s2m;
The widths are the addr_width and data_width of the register map.
Member |
Direction |
Meaning |
|---|---|---|
|
endpoint to register file |
The address the bus master drove: the base address plus the register offset. |
|
endpoint to register file |
Write data. |
|
endpoint to register file |
Write request. |
|
endpoint to register file |
Read request. |
|
register file to endpoint |
Read data, valid with |
|
register file to endpoint |
The access completed. |
|
register file to endpoint |
The address did not decode, see errors. |
A transfer works like this:
The endpoint raises one of
wenorren, withaddressandwdata, and holds them until it seesackorerr.The register file answers with a one-cycle pulse on
ackorerrin the clock cycle after the request. There is one transfer at a time and no bursts.A request that is still held in the cycle of the answer is not serviced again, so every transfer takes at least two clock cycles.
There is no separate wait or stall signal. A target that needs more time answers later, and the endpoint waits. The generated register file always answers in one cycle.
The register file entity takes the local bus, the clock and a reset whose polarity the endpoint sets to match its bus:
entity timer_regfile is
generic (
G_BASE_ADDRESS : unsigned(31 downto 0) := 32x"0";
G_CHECK_BASE_ADDRESS : boolean := true;
G_MODULE_ADDR_WIDTH : natural := C_TIMER_MODULE_ADDR_WIDTH;
G_UNMAPPED_READ_DATA : std_logic_vector(31 downto 0) := (others => '0');
G_ERR_ON_BAD_ACCESS : boolean := false;
G_RESET_ACTIVE_LOW : boolean := false
);
port (
clk : in std_logic;
reset : in std_logic;
lb_m2s : in t_lb_m2s;
lb_s2m : out t_lb_s2m;
to_hw : out t_timer_to_hw;
from_hw : in t_timer_from_hw
);
end entity timer_regfile;
The register file resets synchronously, on a rising edge of clk while the
reset is asserted.
The register-file package¶
<module>_regfile_pkg holds everything your design needs to talk to the
registers. Use it in any file that connects to the module:
use work.timer_regfile_pkg.all;
Name |
What it is |
|---|---|
|
The register offset of each register, |
|
The number of low address bits that select a register, and the default of |
|
The |
|
The enumeration type of an enumerated field. |
|
Conversions between an enumeration type and its bits. |
|
Everything the hardware reads, one member per register. |
|
The fields of one register that the hardware reads. A register without fields has none. |
|
One field’s value together with its |
|
Everything the hardware drives, one member per register. |
|
A |
|
A |
|
The fields of one register that the hardware drives. A register without fields has none. |
|
One field’s value together with its |
|
The register file’s internal storage, its reset value and its address decoding. Your design does not need them. |
Module, register and field names keep the case you gave them in the JSON. The constants are in upper case.
The timer’s register offsets, its version and hash, and its enumeration type:
constant C_TIMER_CTRL_OFFSET : std_logic_vector(31 downto 0) := 32x"00";
constant C_TIMER_LOAD_OFFSET : std_logic_vector(31 downto 0) := 32x"04";
constant C_TIMER_STATUS_OFFSET : std_logic_vector(31 downto 0) := 32x"08";
constant C_TIMER_IRQ_OFFSET : std_logic_vector(31 downto 0) := 32x"0C";
constant C_TIMER_MODULE_ADDR_WIDTH : natural := 4;
-- The version of the register map and the hash of its content.
constant C_TIMER_REGMAP_VERSION : string := "";
constant C_TIMER_REGMAP_HASH : std_logic_vector(31 downto 0) := x"9FACFD14";
type t_timer_ctrl_mode is (ONESHOT, PERIODIC);
-- Convert t_timer_ctrl_mode to and from its encoded bits.
function to_slv (
v : t_timer_ctrl_mode
) return std_logic_vector;
function to_timer_ctrl_mode (
s : std_logic_vector(1 downto 0)
) return t_timer_ctrl_mode;
Hardware reads: to_hw¶
to_hw has one member per register that has at least one field with hw: r
or hw: rw. For a register with fields, that member is a record with one member
per such field. A register without fields has no record of its own, and its
member is its value:
type t_timer_ctrl_to_hw is record
enable : std_logic;
mode : t_timer_ctrl_mode;
start : std_logic;
end record t_timer_ctrl_to_hw;
type t_timer_load_load_out is record
value : std_logic_vector(31 downto 0);
swmod : std_logic;
end record t_timer_load_load_out;
type t_timer_irq_to_hw is record
expired : std_logic;
end record t_timer_irq_to_hw;
type t_timer_to_hw is record
ctrl : t_timer_ctrl_to_hw;
load : t_timer_load_load_out;
irq : t_timer_irq_to_hw;
end record t_timer_to_hw;
Field |
Member in |
|---|---|
A bit field |
|
A vector field |
|
An enumerated field |
Its enumeration type, such as |
A field with |
A record with |
A register without fields, such as load of type default, is read as
to_hw.load, with the same types as a field. Here it is a record with value
and swmod, because load has swmod, so the hardware reads
to_hw.load.value and to_hw.load.swmod. Without swmod it would be the
std_logic_vector itself. status is missing because hardware cannot read
it.
Hardware drives: from_hw¶
from_hw has one member per register that has at least one field the hardware
writes (hw: w or hw: rw) or sets or clears (hwset, hwclr). As in
to_hw, a register without fields is driven directly, as from_hw.<reg>:
type t_timer_status_count_in is record
value : std_logic_vector(15 downto 0);
we : std_logic;
end record t_timer_status_count_in;
type t_timer_status_from_hw is record
count : t_timer_status_count_in;
running : std_logic;
end record t_timer_status_from_hw;
type t_timer_irq_expired_in is record
set : std_logic;
end record t_timer_irq_expired_in;
type t_timer_irq_from_hw is record
expired : t_timer_irq_expired_in;
end record t_timer_irq_from_hw;
type t_timer_from_hw is record
status : t_timer_status_from_hw;
irq : t_timer_irq_from_hw;
end record t_timer_from_hw;
Field |
Member in |
|---|---|
|
The value itself. The register file stores it every clock cycle, except for a status field ( |
With |
A record with |
With |
A record with |
A module whose fields the hardware never reads has no to_hw port, and one
whose fields the hardware never drives has no from_hw port.
Instantiate the module¶
The starter <module>.vhd has the generics and ports of the endpoint, to_hw
and from_hw included, so you can instantiate it as it is and keep your logic
next to it. Connect the bus ports and declare one signal of each record type.
The timer’s AXI4-Lite ports connect one to one:
use work.timer_regfile_pkg.all;
architecture rtl of my_design is
signal timer_to_hw : t_timer_to_hw;
signal timer_from_hw : t_timer_from_hw;
signal count : unsigned(15 downto 0) := (others => '0');
begin
i_timer : entity work.timer
generic map (
G_BASE_ADDRESS => x"4000_1000",
G_CHECK_BASE_ADDRESS => true,
G_MODULE_ADDR_WIDTH => 12)
port map (
clk => clk,
areset_n => areset_n,
awaddr => awaddr,
awvalid => awvalid,
awready => awready,
wdata => wdata,
wvalid => wvalid,
wready => wready,
bresp => bresp,
bvalid => bvalid,
bready => bready,
araddr => araddr,
arvalid => arvalid,
arready => arready,
rdata => rdata,
rresp => rresp,
rvalid => rvalid,
rready => rready,
to_hw => timer_to_hw,
from_hw => timer_from_hw);
Your logic then reads timer_to_hw and drives timer_from_hw, field by field
and by name:
p_count : process (clk) is
begin
if rising_edge(clk) then
if timer_to_hw.ctrl.start = '1' or timer_to_hw.load.swmod = '1' then
count <= unsigned(timer_to_hw.load.value(15 downto 0));
elsif timer_to_hw.ctrl.enable = '1' then
if count /= 0 then
count <= count - 1;
elsif timer_to_hw.ctrl.mode = PERIODIC then
count <= unsigned(timer_to_hw.load.value(15 downto 0));
end if;
end if;
end if;
end process p_count;
timer_from_hw.status.count.value <= std_logic_vector(count);
timer_from_hw.status.count.we <= timer_to_hw.ctrl.enable;
timer_from_hw.status.running <= '1' when count /= 0 else '0';
timer_from_hw.irq.expired.set <= '1' when count = 1 else '0';
irq <= timer_to_hw.irq.expired;
Drive every member of from_hw. A we, wel, set or clr input you leave
undriven stays 'U' in simulation.
Base address¶
The starter top level, the endpoint and the register file have the same three generics:
entity timer is
generic (
G_BASE_ADDRESS : unsigned(31 downto 0) := 32x"0";
G_CHECK_BASE_ADDRESS : boolean := true;
G_MODULE_ADDR_WIDTH : natural := C_TIMER_MODULE_ADDR_WIDTH;
G_UNMAPPED_READ_DATA : std_logic_vector(31 downto 0) := (others => '0');
G_ERR_ON_BAD_ACCESS : boolean := false
);
G_BASE_ADDRESS sets where the module sits on the bus. G_CHECK_BASE_ADDRESS
sets whether the module checks the base address of each access, and
G_MODULE_ADDR_WIDTH sets how many low address bits the module decodes, so
the module answers for 2**G_MODULE_ADDR_WIDTH addresses from its base
address. Base address and address range
shows how the register file decodes an address with each setting.
G_UNMAPPED_READ_DATA is the data a read gets from an address where no
register sits, such as x"DEADBEEF" to make it stand out in a register dump.
G_ERR_ON_BAD_ACCESS adds an error response for a write to a register software
cannot write and a read of one it cannot read, see
Access modes.
Several modules in one design¶
Every generated design unit is named after its module, including the local-bus
package. Each module’s <module>_localbus_pkg is sized from that module’s own
addr_width and data_width, so modules with different widths can share one
library. A timer with 32-bit addresses and data and a GPIO module with 16-bit
addresses and data can both be compiled into periph. Compile each module’s
files in the order above. The order between the modules does not matter.
The names your design uses from <module>_regfile_pkg carry the module name,
such as t_timer_ctrl_to_hw and C_TIMER_CTRL_OFFSET, so one file can use the
packages of several modules with .all. The internal names of the register
file, such as t_ctrl_regs and reg_addr_match, are the same in every
package. VHDL hides a name that two such packages declare, so refer to one of
them with a selected name, such as work.gpio_regfile_pkg.reg_addr_match.
Your top level¶
<module>.vhd is yours. bust writes it once, as a starter, when the file does
not exist, and then leaves it alone. Running bust again does not change it,
and neither does -f. The starter contains only the endpoint. You can use it
as it is, as in Instantiate the module, or make it
your module: add your own generics, ports and logic, and turn to_hw and
from_hw into signals inside it.
Run bust again after you change the register map. It regenerates every other
file, and asks before it overwrites one unless you add -f. <module>.vhd
needs no change for new registers or fields, because it connects to_hw and
from_hw as whole records. It needs one when you change the bus type, which
changes the bus ports, or when the module gets its first to_hw or from_hw
port.
To start over from a fresh starter, run bust with --replace-top. It keeps
your old file as <module>.vhd.bak, and asks first unless you add -f.