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

<module>.vhd

The top level of the module, the entity your design instantiates. This file is yours, see Your top level.

<module>_<bus>_endpoint.vhd

The bus endpoint. It translates the bus protocol to the local bus and instantiates the register file.

<module>_regfile.vhd

The register file: storage, access-mode behaviour, hardware updates, the read mux and the bus response.

<module>_regfile_pkg.vhd

Register offsets, enumeration types, and the to_hw and from_hw record types you connect to.

<module>_localbus_pkg.vhd

The local-bus records t_lb_m2s and t_lb_s2m, sized for this module.

<module>_tb.vhd

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:

  1. <module>_localbus_pkg.vhd

  2. <module>_regfile_pkg.vhd

  3. <module>_regfile.vhd

  4. <module>_<bus>_endpoint.vhd

  5. <module>.vhd

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

address

endpoint to register file

The address the bus master drove: the base address plus the register offset.

wdata

endpoint to register file

Write data.

wen

endpoint to register file

Write request.

ren

endpoint to register file

Read request.

rdata

register file to endpoint

Read data, valid with ack.

ack

register file to endpoint

The access completed.

err

register file to endpoint

The address did not decode, see errors.

A transfer works like this:

  • The endpoint raises one of wen or ren, with address and wdata, and holds them until it sees ack or err.

  • The register file answers with a one-cycle pulse on ack or err in 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

C_<MODULE>_<REG>_OFFSET

The register offset of each register, addr_width bits wide.

C_<MODULE>_MODULE_ADDR_WIDTH

The number of low address bits that select a register, and the default of G_MODULE_ADDR_WIDTH.

C_<MODULE>_REGMAP_VERSION, C_<MODULE>_REGMAP_HASH

The version of the module as a string and the 32-bit hash of the register map. See Version and hash.

t_<module>_<reg>_<field>

The enumeration type of an enumerated field.

to_slv, to_<module>_<reg>_<field>

Conversions between an enumeration type and its bits.

t_<module>_to_hw

Everything the hardware reads, one member per register.

t_<module>_<reg>_to_hw

The fields of one register that the hardware reads. A register without fields has none.

t_<module>_<reg>_<field>_out

One field’s value together with its swmod or swacc strobe.

t_<module>_from_hw

Everything the hardware drives, one member per register.

C_<MODULE>_TO_HW_RESET

A t_<module>_to_hw with every value at its reset and every strobe inactive, for a model or testbench that drives to_hw.

C_<MODULE>_FROM_HW_RESET

A t_<module>_from_hw with every value at its reset and every strobe inactive. Use it to tie off from_hw or as its initial value.

t_<module>_<reg>_from_hw

The fields of one register that the hardware drives. A register without fields has none.

t_<module>_<reg>_<field>_in

One field’s value together with its we, wel, set or clr input.

t_<module>_regs, t_<reg>_regs, C_<MODULE>_REGS_RESET, is_in_range, reg_addr_match, is_mapped, is_sw_writable, is_sw_readable

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 to_hw.<reg>.<field>

A bit field

std_logic

A vector field

std_logic_vector(width - 1 downto 0)

An enumerated field

Its enumeration type, such as t_timer_ctrl_mode

A field with swmod or swacc

A record with value and the strobe, such as to_hw.<reg>.<field>.swmod

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 from_hw.<reg>.<field>

hw: w or rw without modifiers

The value itself. The register file stores it every clock cycle, except for a status field (sw: r, hw: w, no onread), which a read takes from from_hw directly.

With we or wel

A record with value and we or wel.

With hwset or hwclr

A record with set or clr, after value if the hardware also writes the field.

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.