VHDL code generator

A large ecosystem of VHDL artifacts can be generated that support both implementation and simulation in your project. See the Example below for a real-world use case of all these artifacts.

• VhdlRegisterPackageGenerator generates the base VHDL package with register indexes and modes, field indexes, field types, and field conversion functions.

• VhdlRecordPackageGenerator generates a VHDL package with register records that use native VHDL types for all fields, along with conversion functions for these.

• VhdlAxiLiteWrapperGenerator generates a VHDL entity that wraps an AXI-Lite general register file, and exposes register values to application using the natively typed records.

• VhdlSimulationReadWritePackageGenerator generates a VHDL simulation support package with procedures for reading/writing register or field values.

• VhdlSimulationCheckPackageGenerator generates a VHDL simulation support package with procedures for checking current register and field values against a given expected value.

• VhdlSimulationWaitUntilPackageGenerator generates a VHDL simulation support package with procedures for waiting until a readable register or field assumes a given value.

The recommended workflow is to generate the register file wrapper from VhdlAxiLiteWrapperGenerator and instantiate it in your VHDL design. With this, registers and their field values are available as native VHDL typed values, requiring no conversion. See the example below for an example of this.

Example

To illustrate the code generators and how to use the code from them in an effective way, there is a complete VHDL entity and testbench below. While the application (a counter that periodically sends out a pulse) is silly, the goal of the example is to showcase as many of the features as possible and how to efficiently use them.

Register definition TOML file

The registers are generated from the TOML file below. Note that there are three registers of different modes: “Read, Write”, “Write-pulse” and “Read”. In the registers there are a few different fields, of type bit, integer and enumeration.

Click to expand/collapse code.

TOML file for example.

################################################################################
[config]

mode = "r_w"

condition.type = "enumeration"
condition.description = "Set mode for how the counter operates."
condition.element.clock_cycles = "Increment counter each clock cycle."
condition.element.clock_cycles_with_enable = """
Increment counter each clock cycle when **clock_enable** is asserted.
"""
condition.element.enable_edges = """
Increment counter each time **clock_enable** changes state.
"""

increment.type = "integer"
increment.description = "How much to increment counter."
increment.max_value = 15


################################################################################
[command]

mode = "wpulse"

start.type = "bit"
start.description = "Write '1' to start operation."

stop.type = "bit"
stop.description = "Write '1' to stop operation."


################################################################################
[status]

mode = "r"

enabled.type = "bit"
enabled.description = "Reads as '1' if operation is enabled."

pulse_count.type = "integer"
pulse_count.max_value = 255
pulse_count.description = """
Number of pulses that have been sent.
Will wrap around.
Value will be cleared to zero when **config** register is written.
"""

Python file to generate register artifacts

The Python code below is used to parse the above TOML file and generate all the VHDL code we need for our VHDL implementation and testbench.

Click to expand/collapse code.

Python code that parses the example TOML file and generates the VHDL code we need.

# Standard libraries
import sys
from pathlib import Path

# First party libraries
from hdl_registers.generator.vhdl.axi_lite.wrapper import VhdlAxiLiteWrapperGenerator
from hdl_registers.generator.vhdl.record_package import VhdlRecordPackageGenerator
from hdl_registers.generator.vhdl.register_package import VhdlRegisterPackageGenerator
from hdl_registers.generator.vhdl.simulation.check_package import (
    VhdlSimulationCheckPackageGenerator,
)
from hdl_registers.generator.vhdl.simulation.read_write_package import (
    VhdlSimulationReadWritePackageGenerator,
)
from hdl_registers.generator.vhdl.simulation.wait_until_package import (
    VhdlSimulationWaitUntilPackageGenerator,
)
from hdl_registers.parser.toml import from_toml

THIS_DIR = Path(__file__).parent


def main(output_folder: Path):
    """
    Create register VHDL artifacts from the "counter" example module.
    """
    register_list = from_toml(
        name="counter", toml_file=THIS_DIR.parent / "sim" / "regs_counter.toml"
    )

    VhdlRegisterPackageGenerator(
        register_list=register_list, output_folder=output_folder
    ).create_if_needed()

    VhdlRecordPackageGenerator(
        register_list=register_list, output_folder=output_folder
    ).create_if_needed()

    VhdlAxiLiteWrapperGenerator(
        register_list=register_list, output_folder=output_folder
    ).create_if_needed()

    VhdlSimulationReadWritePackageGenerator(
        register_list=register_list, output_folder=output_folder
    ).create_if_needed()

    VhdlSimulationCheckPackageGenerator(
        register_list=register_list, output_folder=output_folder
    ).create_if_needed()

    VhdlSimulationWaitUntilPackageGenerator(
        register_list=register_list, output_folder=output_folder
    ).create_if_needed()


if __name__ == "__main__":
    main(output_folder=Path(sys.argv[1]))

VHDL example implementation

The VHDL below is the implementation of our example counter. Once again, the application is a bit silly, but it does showcase a lot of interesting features.

1. The entity uses an AXI-Lite register bus and instantiates the register file produced by VhdlAxiLiteWrapperGenerator, which can be seen below.

2. Register values up and down are record types from the package produced by VhdlRecordPackageGenerator, which can be seen below.

3. The set_status process shows

   1. How to access bit fields in a “Write-pulse” register and how to set bit fields in a “Read” register.

   2. How to set and update an integer field in a “Read” register.

   3. How to perform an action when a specific register is written on the register bus.

   Note how all the operations are performed using native VHDL types (std_ulogic, integer).

4. The count process shows

1. How to take different action depending on an enumeration field in a “Read, Write” register. Note that the field type is a VHDL enum with its elements (e.g. condition_clock_cycles) exposed.

2. How to use a numeric value from a “Read, Write” register. Since the field is of integer type, it can simply be added to another integer.

Click to expand/collapse code.

Implementation of counter example.

-- -------------------------------------------------------------------------------------------------
-- Regularly send out a 'pulse', with a frequency that is configurable over the register bus.
-- -------------------------------------------------------------------------------------------------

library ieee;
use ieee.std_logic_1164.all;

library axi_lite;
use axi_lite.axi_lite_pkg.all;

library common;
use common.types_pkg.all;

use work.counter_regs_pkg.all;
use work.counter_register_record_pkg.all;


entity counter is
  port (
    clk : in std_ulogic;
    --
    regs_m2s : in axi_lite_m2s_t;
    regs_s2m : out axi_lite_s2m_t := axi_lite_s2m_init;
    --
    clock_enable : in std_ulogic;
    pulse : out std_ulogic := '0'
  );
end entity;

architecture a of counter is

  signal regs_up : counter_regs_up_t := counter_regs_up_init;
  signal regs_down : counter_regs_down_t := counter_regs_down_init;

  signal reg_was_written : counter_reg_was_written_t := counter_reg_was_written_init;

begin

  ------------------------------------------------------------------------------
  counter_reg_file_inst : entity work.counter_reg_file
    port map (
      clk => clk,
      --
      axi_lite_m2s => regs_m2s,
      axi_lite_s2m => regs_s2m,
      --
      regs_up => regs_up,
      regs_down => regs_down,
      --
      reg_was_read => open,
      reg_was_written => reg_was_written
    );


  ------------------------------------------------------------------------------
  set_status : process
  begin
    wait until rising_edge(clk);

    if regs_down.command.start then
      regs_up.status.enabled <= '1';
    end if;

    if regs_down.command.stop then
      regs_up.status.enabled <= '0';
    end if;

    if reg_was_written.config then
      -- Clear value when configuration is changed.
      regs_up.status.pulse_count <= 0;
    else
      regs_up.status.pulse_count <= regs_up.status.pulse_count + to_int(pulse);
    end if;
  end process;


  ------------------------------------------------------------------------------
  count_block : block
    constant counter_width : positive := 10;
    constant counter_activate_value : positive := 2 ** counter_width - 1;
    -- One bit extra to avoid overflow.
    constant counter_max_value : positive := 2 ** (counter_width + 1) - 1;

    signal count : natural range 0 to counter_max_value := 0;

    signal clock_enable_p1 : std_ulogic := '0';
  begin

    ------------------------------------------------------------------------------
    count_events : process
    begin
      wait until rising_edge(clk);

      pulse <= '0';

      case regs_down.config.condition is
        when condition_clock_cycles =>
          count <= count + regs_down.config.increment;

        when condition_clock_cycles_with_enable =>
          if clock_enable then
            count <= count + regs_down.config.increment;
          end if;

        when condition_enable_edges =>
          if clock_enable /= clock_enable_p1 then
            count <= count + regs_down.config.increment;
          end if;
      end case;

      if count >= counter_activate_value then
        count <= 0;
        pulse <= regs_up.status.enabled;
      end if;

      clock_enable_p1 <= clock_enable;
    end process;

  end block;

end architecture;

VHDL example testbench

The VHDL below is the testbench for our example counter implementation above.

1. The testbench uses register read/write procedures from the package produced by VhdlSimulationReadWritePackageGenerator, which can be seen below. For example write_counter_config.

2. The testbench uses register wait until procedures from the package produced by VhdlSimulationWaitUntilPackageGenerator, which can be seen below.

   1. For example wait_until_counter_status_pulse_count_equals, which will continuously read the status register until the pulse_count field is exactly equal to the supplied value.

3. The type of the value for each procedure is the native record type for that register.

   1. For example, read_counter_status returns a value of type counter_status_t which is a record that contains a bit enabled and an integer pulse_count.

4. The testbench uses register field check procedures from the package produced by VhdlSimulationCheckPackageGenerator, which can be seen below. For example check_counter_status_enabled_equal.

5. The testbench instantiates axi_lite_master.vhd which creates AXI-Lite transactions based on the VUnit bus master verification component interface commands created by the Generated VHDL simulation read/write package.

Click to expand/collapse code.

Testbench for counter example.

library ieee;
use ieee.std_logic_1164.all;

library vunit_lib;
use vunit_lib.com_pkg.net;
use vunit_lib.run_pkg.all;

library axi_lite;
use axi_lite.axi_lite_pkg.all;

library bfm;

library reg_file;

use work.counter_register_record_pkg.all;
use work.counter_register_check_pkg.all;
use work.counter_register_read_write_pkg.all;
use work.counter_register_wait_until_pkg.all;
use work.counter_regs_pkg.all;


entity tb_counter is
  generic (
    runner_cfg : string
  );
end entity;

architecture tb of tb_counter is

  signal clk : std_ulogic := '0';

  signal regs_m2s : axi_lite_m2s_t := axi_lite_m2s_init;
  signal regs_s2m : axi_lite_s2m_t := axi_lite_s2m_init;

  signal pulse, clock_enable : std_ulogic := '0';

begin

  clk <= not clk after 5 ns;
  test_runner_watchdog(runner, 1 ms);


  ------------------------------------------------------------------------------
  main : process
    variable config : counter_config_t := counter_config_init;
  begin
    test_runner_setup(runner, runner_cfg);

    -- Check initial state.
    check_counter_status_enabled_equal(net=>net, expected=>'0');
    check_counter_status_pulse_count_equal(net=>net, expected=>0);

    if run("test_count_clock_cycles") then
      config.condition := condition_clock_cycles;
      config.increment := 13;

    elsif run("test_count_clock_cycles_with_enable") then
      config.condition := condition_clock_cycles_with_enable;
      config.increment := 8;

      clock_enable <= '1';
    end if;

    -- Set configuration, which depends on test case.
    write_counter_config(net=>net, value=>config);

    -- Enable the operation.
    write_counter_command_start(net=>net, value=>'1');

    -- Check updated status.
    check_counter_status_enabled_equal(net=>net, expected=>'1');
    check_counter_status_pulse_count_equal(net=>net, expected=>0);

    -- Wait until a number of pulses have passed.
    wait_until_counter_status_pulse_count_equals(net=>net, value=>10);

    -- Stop the operation.
    write_counter_command_stop(net=>net, value=>'1');

    -- Make sure that status is updated.
    check_counter_status_enabled_equal(net=>net, expected=>'0');

    test_runner_cleanup(runner);
  end process;


  ------------------------------------------------------------------------------
  axi_lite_master_inst : entity bfm.axi_lite_master
    port map (
      clk => clk,
      --
      axi_lite_m2s => regs_m2s,
      axi_lite_s2m => regs_s2m
    );


  ------------------------------------------------------------------------------
  counter_inst : entity work.counter
    port map (
      clk => clk,
      --
      regs_m2s => regs_m2s,
      regs_s2m => regs_s2m,
      --
      clock_enable => clock_enable,
      pulse => pulse
    );

end architecture;

Generated VHDL register package

Below is the generated register package, created from the TOML file above via the VhdlRegisterPackageGenerator class. This is used by the Generated VHDL record package and the Generated VHDL AXI-Lite register file wrapper.

Click to expand/collapse code.

Example register package.

-- This file is automatically generated by hdl-registers version 6.0.2-dev.
-- Code generator VhdlRegisterPackageGenerator version 1.0.0.
-- Generated 2024-09-19 20:51 from file regs_counter.toml at commit 25b9eb172eb22827.
-- Register hash 49f02a8daa9dd4bc3dadeb2a1cfd61dcc38c3864.

library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;
use ieee.fixed_pkg.all;

library reg_file;
use reg_file.reg_file_pkg.all;


package counter_regs_pkg is

  -- ---------------------------------------------------------------------------
  -- The valid range of register indexes.
  subtype counter_reg_range is natural range 0 to 2;

  -- Register indexes, within the list of registers.
  constant counter_config : natural := 0;
  constant counter_command : natural := 1;
  constant counter_status : natural := 2;

  -- Declare 'reg_map' and 'regs_init' constants here but define them in body (deferred constants).
  -- So that functions have been elaborated when they are called.
  -- Needed for ModelSim compilation to pass.

  -- To be used as the 'regs' generic of 'axi_lite_reg_file.vhd'.
  constant counter_reg_map : reg_definition_vec_t(counter_reg_range);

  -- To be used for the 'regs_up' and 'regs_down' ports of 'axi_lite_reg_file.vhd'.
  subtype counter_regs_t is reg_vec_t(counter_reg_range);
  -- To be used as the 'default_values' generic of 'axi_lite_reg_file.vhd'.
  constant counter_regs_init : counter_regs_t;

  -- To be used for the 'reg_was_read' and 'reg_was_written' ports of 'axi_lite_reg_file.vhd'.
  subtype counter_reg_was_accessed_t is std_ulogic_vector(counter_reg_range);

  -- -----------------------------------------------------------------------------
  -- Fields in the 'config' register.
  -- Range of the 'condition' field.
  subtype counter_config_condition is natural range 1 downto 0;
  -- Width of the 'condition' field.
  constant counter_config_condition_width : positive := 2;
  -- Type for the 'condition' field.
  type counter_config_condition_t is (
    condition_clock_cycles,
    condition_clock_cycles_with_enable,
    condition_enable_edges
  );
  -- Default value of the 'condition' field.
  constant counter_config_condition_init : counter_config_condition_t := condition_clock_cycles;
  -- Type for the 'condition' field as an SLV.
  subtype counter_config_condition_slv_t is std_ulogic_vector(1 downto 0);
  -- Cast a 'condition' field value to SLV.
  function to_slv(data : counter_config_condition_t) return counter_config_condition_slv_t;
  -- Get a 'condition' field value from a register value.
  function to_counter_config_condition(data : reg_t) return counter_config_condition_t;

  -- Range of the 'increment' field.
  subtype counter_config_increment is natural range 5 downto 2;
  -- Width of the 'increment' field.
  constant counter_config_increment_width : positive := 4;
  -- Type for the 'increment' field.
  subtype counter_config_increment_t is integer range 0 to 15;
  -- Default value of the 'increment' field.
  constant counter_config_increment_init : counter_config_increment_t := 0;
  -- Type for the 'increment' field as an SLV.
  subtype counter_config_increment_slv_t is std_ulogic_vector(3 downto 0);
  -- Cast a 'increment' field value to SLV.
  function to_counter_config_increment_slv(data : counter_config_increment_t) return counter_config_increment_slv_t;
  -- Get a 'increment' field value from a register value.
  function to_counter_config_increment(data : reg_t) return counter_config_increment_t;

  -- -----------------------------------------------------------------------------
  -- Fields in the 'command' register.
  -- Range of the 'start' field.
  constant counter_command_start : natural := 0;
  -- Default value of the 'start' field.
  constant counter_command_start_init : std_ulogic := '0';

  -- Range of the 'stop' field.
  constant counter_command_stop : natural := 1;
  -- Default value of the 'stop' field.
  constant counter_command_stop_init : std_ulogic := '0';

  -- -----------------------------------------------------------------------------
  -- Fields in the 'status' register.
  -- Range of the 'enabled' field.
  constant counter_status_enabled : natural := 0;
  -- Default value of the 'enabled' field.
  constant counter_status_enabled_init : std_ulogic := '0';

  -- Range of the 'pulse_count' field.
  subtype counter_status_pulse_count is natural range 8 downto 1;
  -- Width of the 'pulse_count' field.
  constant counter_status_pulse_count_width : positive := 8;
  -- Type for the 'pulse_count' field.
  subtype counter_status_pulse_count_t is integer range 0 to 255;
  -- Default value of the 'pulse_count' field.
  constant counter_status_pulse_count_init : counter_status_pulse_count_t := 0;
  -- Type for the 'pulse_count' field as an SLV.
  subtype counter_status_pulse_count_slv_t is std_ulogic_vector(7 downto 0);
  -- Cast a 'pulse_count' field value to SLV.
  function to_counter_status_pulse_count_slv(data : counter_status_pulse_count_t) return counter_status_pulse_count_slv_t;
  -- Get a 'pulse_count' field value from a register value.
  function to_counter_status_pulse_count(data : reg_t) return counter_status_pulse_count_t;

end package;

package body counter_regs_pkg is

  constant counter_reg_map : reg_definition_vec_t(counter_reg_range) := (
    0 => (idx => counter_config, reg_type => r_w),
    1 => (idx => counter_command, reg_type => wpulse),
    2 => (idx => counter_status, reg_type => r)
  );

  constant counter_regs_init : counter_regs_t := (
    0 => "00000000000000000000000000000000",
    1 => "00000000000000000000000000000000",
    2 => "00000000000000000000000000000000"
  );

  -- Cast a 'condition' field value to SLV.
  function to_slv(data : counter_config_condition_t) return counter_config_condition_slv_t is
    constant data_int : natural := counter_config_condition_t'pos(data);
    constant result : counter_config_condition_slv_t := std_ulogic_vector(
      to_unsigned(data_int, counter_config_condition_width)
    );
  begin
    return result;
  end function;

  -- Get a 'condition' field value from a register value.
  function to_counter_config_condition(data : reg_t) return counter_config_condition_t is
    constant field_slv : counter_config_condition_slv_t := data(counter_config_condition);
    constant field_int : natural := to_integer(unsigned(field_slv));
    constant result : counter_config_condition_t := counter_config_condition_t'val(field_int);
  begin
    return result;
  end function;

  -- Cast a 'increment' field value to SLV.
  function to_counter_config_increment_slv(data : counter_config_increment_t) return counter_config_increment_slv_t is
    constant result : counter_config_increment_slv_t := std_ulogic_vector(to_unsigned(data, counter_config_increment_width));
  begin
    return result;
  end function;

  -- Get a 'increment' field value from a register value.
  function to_counter_config_increment(data : reg_t) return counter_config_increment_t is
    constant result : integer := to_integer(unsigned(data(counter_config_increment)));
  begin
    return result;
  end function;

  -- Cast a 'pulse_count' field value to SLV.
  function to_counter_status_pulse_count_slv(data : counter_status_pulse_count_t) return counter_status_pulse_count_slv_t is
    constant result : counter_status_pulse_count_slv_t := std_ulogic_vector(to_unsigned(data, counter_status_pulse_count_width));
  begin
    return result;
  end function;

  -- Get a 'pulse_count' field value from a register value.
  function to_counter_status_pulse_count(data : reg_t) return counter_status_pulse_count_t is
    constant result : integer := to_integer(unsigned(data(counter_status_pulse_count)));
  begin
    return result;
  end function;

end package body;

Generated VHDL record package

Below is the generated record package, created from the TOML file above via the VhdlRecordPackageGenerator class. This is used by the Generated VHDL AXI-Lite register file wrapper as well as the VHDL example implementation and the VHDL example testbench.

Click to expand/collapse code.

Example register record package.

-- This file is automatically generated by hdl-registers version 6.0.2-dev.
-- Code generator VhdlRecordPackageGenerator version 1.0.0.
-- Generated 2024-09-19 20:51 from file regs_counter.toml at commit 25b9eb172eb22827.
-- Register hash 49f02a8daa9dd4bc3dadeb2a1cfd61dcc38c3864.

library ieee;
use ieee.fixed_pkg.all;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

library reg_file;
use reg_file.reg_file_pkg.reg_t;

use work.counter_regs_pkg.all;


package counter_register_record_pkg is

  -- -----------------------------------------------------------------------------
  -- Record with correctly-typed members for each field in each register.
  -- Fields in the 'config' register as a record.
  type counter_config_t is record
    condition : counter_config_condition_t;
    increment : counter_config_increment_t;
  end record;
  -- Default value for the 'config' register as a record.
  constant counter_config_init : counter_config_t := (
    condition => counter_config_condition_init,
    increment => counter_config_increment_init
  );
  -- Convert a record of the 'config' register to SLV.
  function to_slv(data : counter_config_t) return reg_t;
  -- Convert an SLV register value to the record for the 'config' register.
  function to_counter_config(data : reg_t) return counter_config_t;

  -- Fields in the 'command' register as a record.
  type counter_command_t is record
    start : std_ulogic;
    stop : std_ulogic;
  end record;
  -- Default value for the 'command' register as a record.
  constant counter_command_init : counter_command_t := (
    start => counter_command_start_init,
    stop => counter_command_stop_init
  );
  -- Convert a record of the 'command' register to SLV.
  function to_slv(data : counter_command_t) return reg_t;
  -- Convert an SLV register value to the record for the 'command' register.
  function to_counter_command(data : reg_t) return counter_command_t;

  -- Fields in the 'status' register as a record.
  type counter_status_t is record
    enabled : std_ulogic;
    pulse_count : counter_status_pulse_count_t;
  end record;
  -- Default value for the 'status' register as a record.
  constant counter_status_init : counter_status_t := (
    enabled => counter_status_enabled_init,
    pulse_count => counter_status_pulse_count_init
  );
  -- Convert a record of the 'status' register to SLV.
  function to_slv(data : counter_status_t) return reg_t;
  -- Convert an SLV register value to the record for the 'status' register.
  function to_counter_status(data : reg_t) return counter_status_t;

  -- -----------------------------------------------------------------------------
  -- Below is a record with correctly typed and ranged members for all registers, register arrays
  -- and fields that are in the 'up' direction.
  -- Record with everything in the 'up' direction.
  type counter_regs_up_t is record
    status : counter_status_t;
  end record;
  -- Default value of the above record.
  constant counter_regs_up_init : counter_regs_up_t := (
    status => counter_status_init
  );
  -- Convert record with everything in the 'up' direction to SLV register list.
  function to_slv(data : counter_regs_up_t) return counter_regs_t;

  -- -----------------------------------------------------------------------------
  -- Below is a record with correctly typed and ranged members for all registers, register arrays
  -- and fields that are in the 'down' direction.
  -- Record with everything in the 'down' direction.
  type counter_regs_down_t is record
    config : counter_config_t;
    command : counter_command_t;
  end record;
  -- Default value of the above record.
  constant counter_regs_down_init : counter_regs_down_t := (
    config => counter_config_init,
    command => counter_command_init
  );
  -- Convert SLV register list to record with everything in the 'down' direction.
  function to_counter_regs_down(data : counter_regs_t) return counter_regs_down_t;

  -- ---------------------------------------------------------------------------
  -- Below is a record with a status bit for each readable register in the register map.
  -- It can be used for the 'reg_was_read' port of a register file wrapper.
  -- Combined status mask record for all readable register.
  type counter_reg_was_read_t is record
    config : std_ulogic;
    status : std_ulogic;
  end record;
  -- Default value for the above record.
  constant counter_reg_was_read_init : counter_reg_was_read_t := (
    others => '0'
  );
  -- Convert an SLV 'reg_was_read' from generic register file to the record above.
  function to_counter_reg_was_read(
    data : counter_reg_was_accessed_t
  ) return counter_reg_was_read_t;

  -- ---------------------------------------------------------------------------
  -- Below is a record with a status bit for each writeable register in the register map.
  -- It can be used for the 'reg_was_written' port of a register file wrapper.
  -- Combined status mask record for all writeable register.
  type counter_reg_was_written_t is record
    config : std_ulogic;
    command : std_ulogic;
  end record;
  -- Default value for the above record.
  constant counter_reg_was_written_init : counter_reg_was_written_t := (
    others => '0'
  );
  -- Convert an SLV 'reg_was_written' from generic register file to the record above.
  function to_counter_reg_was_written(
    data : counter_reg_was_accessed_t
  ) return counter_reg_was_written_t;

end package;

package body counter_register_record_pkg is

  function to_slv(data : counter_config_t) return reg_t is
    variable result : reg_t := (others => '-');
  begin
    result(counter_config_condition) := to_slv(data.condition);
    result(counter_config_increment) := to_counter_config_increment_slv(data.increment);

    return result;
  end function;

  function to_counter_config(data : reg_t) return counter_config_t is
    variable result : counter_config_t := counter_config_init;
  begin
    result.condition := to_counter_config_condition(data);
    result.increment := to_counter_config_increment(data);

    return result;
  end function;

  function to_slv(data : counter_command_t) return reg_t is
    variable result : reg_t := (others => '-');
  begin
    result(counter_command_start) := data.start;
    result(counter_command_stop) := data.stop;

    return result;
  end function;

  function to_counter_command(data : reg_t) return counter_command_t is
    variable result : counter_command_t := counter_command_init;
  begin
    result.start := data(counter_command_start);
    result.stop := data(counter_command_stop);

    return result;
  end function;

  function to_slv(data : counter_status_t) return reg_t is
    variable result : reg_t := (others => '-');
  begin
    result(counter_status_enabled) := data.enabled;
    result(counter_status_pulse_count) := to_counter_status_pulse_count_slv(data.pulse_count);

    return result;
  end function;

  function to_counter_status(data : reg_t) return counter_status_t is
    variable result : counter_status_t := counter_status_init;
  begin
    result.enabled := data(counter_status_enabled);
    result.pulse_count := to_counter_status_pulse_count(data);

    return result;
  end function;

  function to_slv(data : counter_regs_up_t) return counter_regs_t is
    variable result : counter_regs_t := counter_regs_init;
  begin
    result(counter_status) := to_slv(data.status);

    return result;
  end function;

  function to_counter_regs_down(data : counter_regs_t) return counter_regs_down_t is
    variable result : counter_regs_down_t := counter_regs_down_init;
  begin
    result.config := to_counter_config(data(counter_config));
    result.command := to_counter_command(data(counter_command));

    return result;
  end function;

  function to_counter_reg_was_read(
    data : counter_reg_was_accessed_t
  ) return counter_reg_was_read_t is
    variable result : counter_reg_was_read_t := counter_reg_was_read_init;
  begin
    result.config := data(counter_config);
    result.status := data(counter_status);

    return result;
  end function;

  function to_counter_reg_was_written(
    data : counter_reg_was_accessed_t
  ) return counter_reg_was_written_t is
    variable result : counter_reg_was_written_t := counter_reg_was_written_init;
  begin
    result.config := data(counter_config);
    result.command := data(counter_command);

    return result;
  end function;

end package body;

Generated VHDL AXI-Lite register file wrapper

Below is the generated AXI-Lite register file wrapper, created from the TOML file above via the VhdlAxiLiteWrapperGenerator class. This is instantiated in the VHDL example implementation to get register values of native type without any manual casting.

Click to expand/collapse code.

Example AXI-Lite register file wrapper.

-- -----------------------------------------------------------------------------
-- AXI-Lite register file for the 'counter' module registers.
--
-- Is a wrapper around the generic AXI-Lite register file from hdl-modules:
-- * https://hdl-modules.com/modules/reg_file/reg_file.html#axi-lite-reg-file-vhd
-- * https://github.com/hdl-modules/hdl-modules/blob/main/modules/reg_file/src/axi_lite_reg_file.vhd
--
-- Sets correct generics, and performs conversion to the easy-to-use register record types.
-- -----------------------------------------------------------------------------
-- This file is automatically generated by hdl-registers version 6.0.2-dev.
-- Code generator VhdlAxiLiteWrapperGenerator version 1.0.0.
-- Generated 2024-09-19 20:51 from file regs_counter.toml at commit 25b9eb172eb22827.
-- Register hash 49f02a8daa9dd4bc3dadeb2a1cfd61dcc38c3864.
-- -----------------------------------------------------------------------------

library ieee;
use ieee.std_logic_1164.all;

library axi_lite;
use axi_lite.axi_lite_pkg.all;

library reg_file;
use reg_file.reg_file_pkg.all;

use work.counter_regs_pkg.all;
use work.counter_register_record_pkg.all;


entity counter_reg_file is
  port (
    clk : in std_ulogic;
    --# {}
    --# Register control bus.
    axi_lite_m2s : in axi_lite_m2s_t;
    axi_lite_s2m : out axi_lite_s2m_t := axi_lite_s2m_init;
    --# {}
    -- Register values.
    regs_up : in counter_regs_up_t := counter_regs_up_init;
    regs_down : out counter_regs_down_t := counter_regs_down_init;
    --# {}
    -- Each bit is pulsed for one cycle when the corresponding register is read/written.
    reg_was_read : out counter_reg_was_read_t := counter_reg_was_read_init;
    reg_was_written : out counter_reg_was_written_t := counter_reg_was_written_init
  );
end entity;

architecture a of counter_reg_file is

  signal regs_up_slv, regs_down_slv : counter_regs_t := counter_regs_init;

  signal reg_was_read_slv, reg_was_written_slv : counter_reg_was_accessed_t := (
    others => '0'
  );

begin

  ------------------------------------------------------------------------------
  -- Instantiate the generic AXI-Lite register file from
  -- * https://hdl-modules.com/modules/reg_file/reg_file.html#axi-lite-reg-file-vhd
  -- * https://github.com/hdl-modules/hdl-modules/blob/main/modules/reg_file/src/axi_lite_reg_file.vhd
  axi_lite_reg_file_inst : entity reg_file.axi_lite_reg_file
    generic map (
      regs => counter_reg_map,
      default_values => counter_regs_init
    )
    port map(
      clk => clk,
      --
      axi_lite_m2s => axi_lite_m2s,
      axi_lite_s2m => axi_lite_s2m,
      --
      regs_up => regs_up_slv,
      regs_down => regs_down_slv,
      --
      reg_was_read => reg_was_read_slv,
      reg_was_written => reg_was_written_slv
    );


  ------------------------------------------------------------------------------
  -- Combinatorially convert the register record to a list of SLV values that can be handled
  -- by the generic register file implementation.
  assign_regs_up : process(regs_up)
  begin
    regs_up_slv <= to_slv(regs_up);
  end process;


  ------------------------------------------------------------------------------
  -- Combinatorially convert the list of SLV values from the generic register file into the record
  -- we want to use in our application.
  assign_regs_down : process(regs_down_slv)
  begin
    regs_down <= to_counter_regs_down(regs_down_slv);
  end process;


  ------------------------------------------------------------------------------
  -- Combinatorially convert status mask to a record where only the applicable registers are present.
  assign_reg_was_read : process(reg_was_read_slv)
  begin
    reg_was_read <= to_counter_reg_was_read(reg_was_read_slv);
  end process;


  ------------------------------------------------------------------------------
  -- Combinatorially convert status mask to a record where only the applicable registers are present.
  assign_reg_was_written : process(reg_was_written_slv)
  begin
    reg_was_written <= to_counter_reg_was_written(reg_was_written_slv);
  end process;

end architecture;

Generated VHDL simulation read/write package

Below is the generated register simulation read/write package, created from the TOML file above via the VhdlSimulationReadWritePackageGenerator class. It is used by the VHDL example testbench to read/write registers in a compact way.

Click to expand/collapse code.

Example register simulation read/write package.

-- This file is automatically generated by hdl-registers version 6.0.2-dev.
-- Code generator VhdlSimulationReadWritePackageGenerator version 1.0.0.
-- Generated 2024-09-19 20:51 from file regs_counter.toml at commit 25b9eb172eb22827.
-- Register hash 49f02a8daa9dd4bc3dadeb2a1cfd61dcc38c3864.

library ieee;
use ieee.numeric_std.all;
use ieee.std_logic_1164.all;

library vunit_lib;
use vunit_lib.bus_master_pkg.bus_master_t;
use vunit_lib.bus_master_pkg.read_bus;
use vunit_lib.bus_master_pkg.write_bus;
use vunit_lib.com_types_pkg.network_t;

library common;
use common.addr_pkg.addr_t;
use common.addr_pkg.addr_width;

library reg_file;
use reg_file.reg_file_pkg.reg_t;
use reg_file.reg_file_pkg.reg_width;
use reg_file.reg_operations_pkg.regs_bus_master;

use work.counter_regs_pkg.all;
use work.counter_register_record_pkg.all;


package counter_register_read_write_pkg is

  -- ---------------------------------------------------------------------------
  -- Read the 'config' register.
  procedure read_counter_config(
    signal net : inout network_t;
    value : out counter_config_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Read the 'condition' field in the 'config' register.
  procedure read_counter_config_condition(
    signal net : inout network_t;
    value : out counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Read the 'increment' field in the 'config' register.
  procedure read_counter_config_increment(
    signal net : inout network_t;
    value : out counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Write the 'config' register.
  procedure write_counter_config(
    signal net : inout network_t;
    value : in counter_config_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Write the 'condition' field in the 'config' register.
  -- Will read-modify-write the register to set the field to the supplied 'value'.
  procedure write_counter_config_condition(
    signal net : inout network_t;
    value : in counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Write the 'increment' field in the 'config' register.
  -- Will read-modify-write the register to set the field to the supplied 'value'.
  procedure write_counter_config_increment(
    signal net : inout network_t;
    value : in counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Write the 'command' register.
  procedure write_counter_command(
    signal net : inout network_t;
    value : in counter_command_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Write the 'start' field in the 'command' register.
  -- Will write the whole register, with the field set to the 
  -- supplied 'value' and everything else set to default.
  procedure write_counter_command_start(
    signal net : inout network_t;
    value : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Write the 'stop' field in the 'command' register.
  -- Will write the whole register, with the field set to the 
  -- supplied 'value' and everything else set to default.
  procedure write_counter_command_stop(
    signal net : inout network_t;
    value : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Read the 'status' register.
  procedure read_counter_status(
    signal net : inout network_t;
    value : out counter_status_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Read the 'enabled' field in the 'status' register.
  procedure read_counter_status_enabled(
    signal net : inout network_t;
    value : out std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );

  -- Read the 'pulse_count' field in the 'status' register.
  procedure read_counter_status_pulse_count(
    signal net : inout network_t;
    value : out counter_status_pulse_count_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  );
  -- ---------------------------------------------------------------------------

end package;

package body counter_register_read_write_pkg is

  -- ---------------------------------------------------------------------------
  -- Read the 'config' register.
  procedure read_counter_config(
    signal net : inout network_t;
    value : out counter_config_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    constant reg_index : counter_reg_range := counter_config;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);
    variable reg_value : reg_t := (others => '0');
  begin
    read_bus(
      net => net,
      bus_handle => bus_handle,
      address => std_logic_vector(reg_address),
      data => reg_value
    );
    value := to_counter_config(reg_value);
  end procedure;

  -- Read the 'condition' field in the 'config' register.
  procedure read_counter_config_condition(
    signal net : inout network_t;
    value : out counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_config_t := counter_config_init;
  begin
    read_counter_config(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
    value := reg_value.condition;
  end procedure;

  -- Read the 'increment' field in the 'config' register.
  procedure read_counter_config_increment(
    signal net : inout network_t;
    value : out counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_config_t := counter_config_init;
  begin
    read_counter_config(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
    value := reg_value.increment;
  end procedure;

  -- Write the 'config' register.
  procedure write_counter_config(
    signal net : inout network_t;
    value : in counter_config_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    constant reg_index : counter_reg_range := counter_config;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);
    constant reg_value : reg_t := to_slv(value);
  begin
    write_bus(
      net => net,
      bus_handle => bus_handle,
      address => std_logic_vector(reg_address),
      data => reg_value
    );
  end procedure;

  -- Write the 'condition' field in the 'config' register.
  -- Will read-modify-write the register to set the field to the supplied 'value'.
  procedure write_counter_config_condition(
    signal net : inout network_t;
    value : in counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_config_t := counter_config_init;
  begin
    read_counter_config(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
    reg_value.condition := value;

    write_counter_config(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
  end procedure;

  -- Write the 'increment' field in the 'config' register.
  -- Will read-modify-write the register to set the field to the supplied 'value'.
  procedure write_counter_config_increment(
    signal net : inout network_t;
    value : in counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_config_t := counter_config_init;
  begin
    read_counter_config(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
    reg_value.increment := value;

    write_counter_config(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
  end procedure;
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Write the 'command' register.
  procedure write_counter_command(
    signal net : inout network_t;
    value : in counter_command_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    constant reg_index : counter_reg_range := counter_command;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);
    constant reg_value : reg_t := to_slv(value);
  begin
    write_bus(
      net => net,
      bus_handle => bus_handle,
      address => std_logic_vector(reg_address),
      data => reg_value
    );
  end procedure;

  -- Write the 'start' field in the 'command' register.
  -- Will write the whole register, with the field set to the 
  -- supplied 'value' and everything else set to default.
  procedure write_counter_command_start(
    signal net : inout network_t;
    value : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_command_t := counter_command_init;
  begin
    reg_value.start := value;

    write_counter_command(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
  end procedure;

  -- Write the 'stop' field in the 'command' register.
  -- Will write the whole register, with the field set to the 
  -- supplied 'value' and everything else set to default.
  procedure write_counter_command_stop(
    signal net : inout network_t;
    value : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_command_t := counter_command_init;
  begin
    reg_value.stop := value;

    write_counter_command(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
  end procedure;
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Read the 'status' register.
  procedure read_counter_status(
    signal net : inout network_t;
    value : out counter_status_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    constant reg_index : counter_reg_range := counter_status;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);
    variable reg_value : reg_t := (others => '0');
  begin
    read_bus(
      net => net,
      bus_handle => bus_handle,
      address => std_logic_vector(reg_address),
      data => reg_value
    );
    value := to_counter_status(reg_value);
  end procedure;

  -- Read the 'enabled' field in the 'status' register.
  procedure read_counter_status_enabled(
    signal net : inout network_t;
    value : out std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_status_t := counter_status_init;
  begin
    read_counter_status(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
    value := reg_value.enabled;
  end procedure;

  -- Read the 'pulse_count' field in the 'status' register.
  procedure read_counter_status_pulse_count(
    signal net : inout network_t;
    value : out counter_status_pulse_count_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master
  ) is
    variable reg_value : counter_status_t := counter_status_init;
  begin
    read_counter_status(
      net => net,
      value => reg_value,
      base_address => base_address,
      bus_handle => bus_handle
    );
    value := reg_value.pulse_count;
  end procedure;
  -- ---------------------------------------------------------------------------

end package body;

Generated VHDL simulation check package

Below is the generated register simulation check package, created from the TOML file above via the VhdlSimulationCheckPackageGenerator class. It is used by the VHDL example testbench to check that the status register has the expected value.

Click to expand/collapse code.

Example register simulation check package.

-- This file is automatically generated by hdl-registers version 6.0.2-dev.
-- Code generator VhdlSimulationCheckPackageGenerator version 1.0.0.
-- Generated 2024-09-19 20:51 from file regs_counter.toml at commit 25b9eb172eb22827.
-- Register hash 49f02a8daa9dd4bc3dadeb2a1cfd61dcc38c3864.

library ieee;
use ieee.fixed_pkg.all;
use ieee.numeric_std.all;
use ieee.std_logic_1164.all;

library vunit_lib;
use vunit_lib.bus_master_pkg.bus_master_t;
use vunit_lib.check_pkg.all;
use vunit_lib.checker_pkg.all;
use vunit_lib.com_types_pkg.network_t;
use vunit_lib.string_ops.hex_image;

library common;
use common.addr_pkg.addr_t;

library reg_file;
use reg_file.reg_operations_pkg.regs_bus_master;

use work.counter_register_read_write_pkg.all;
use work.counter_register_record_pkg.all;
use work.counter_regs_pkg.all;


package counter_register_check_pkg is

  -- ---------------------------------------------------------------------------
  -- Check that the current value of the 'condition' field in the 'config' register
  -- equals the given 'expected' value.
  procedure check_counter_config_condition_equal(
    signal net : inout network_t;
    expected : in counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  );

  -- Check that the current value of the 'increment' field in the 'config' register
  -- equals the given 'expected' value.
  procedure check_counter_config_increment_equal(
    signal net : inout network_t;
    expected : in counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  );
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Check that the current value of the 'enabled' field in the 'status' register
  -- equals the given 'expected' value.
  procedure check_counter_status_enabled_equal(
    signal net : inout network_t;
    expected : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  );

  -- Check that the current value of the 'pulse_count' field in the 'status' register
  -- equals the given 'expected' value.
  procedure check_counter_status_pulse_count_equal(
    signal net : inout network_t;
    expected : in counter_status_pulse_count_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  );
  -- ---------------------------------------------------------------------------

end package;

package body counter_register_check_pkg is

  -- ---------------------------------------------------------------------------
  -- Check that the current value of the 'condition' field in the 'config' register
  -- equals the given 'expected' value.
  procedure check_counter_config_condition_equal(
    signal net : inout network_t;
    expected : in counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  ) is
    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Checking the 'condition' field in the 'config' register"
      & register_array_message
      & base_address_message
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;

    variable got_reg : counter_config_t := counter_config_init;
    variable got : counter_config_condition_t := counter_config_condition_init;
  begin
    read_counter_config(
      net => net,
      value => got_reg,
      base_address => base_address,
      bus_handle => bus_handle
    );
    got := got_reg.condition;

    if got /= expected then
      failing_check(
        checker => default_checker,
        msg => p_std_msg(
          check_result => "Equality check failed",
          msg => get_message,
          ctx => (
            "Got " & to_string(got) & "."
            & " Expected " & to_string(expected) & "."
          )
        )
      );
    end if;
  end procedure;

  -- Check that the current value of the 'increment' field in the 'config' register
  -- equals the given 'expected' value.
  procedure check_counter_config_increment_equal(
    signal net : inout network_t;
    expected : in counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  ) is
    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Checking the 'increment' field in the 'config' register"
      & register_array_message
      & base_address_message
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;

    variable got_reg : counter_config_t := counter_config_init;
    variable got : counter_config_increment_t := counter_config_increment_init;
  begin
    read_counter_config(
      net => net,
      value => got_reg,
      base_address => base_address,
      bus_handle => bus_handle
    );
    got := got_reg.increment;

    check_equal(got=>got, expected=>expected, msg=>get_message);
  end procedure;
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Check that the current value of the 'enabled' field in the 'status' register
  -- equals the given 'expected' value.
  procedure check_counter_status_enabled_equal(
    signal net : inout network_t;
    expected : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  ) is
    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Checking the 'enabled' field in the 'status' register"
      & register_array_message
      & base_address_message
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;

    variable got_reg : counter_status_t := counter_status_init;
    variable got : std_ulogic := counter_status_enabled_init;
  begin
    read_counter_status(
      net => net,
      value => got_reg,
      base_address => base_address,
      bus_handle => bus_handle
    );
    got := got_reg.enabled;

    check_equal(got=>got, expected=>expected, msg=>get_message);
  end procedure;

  -- Check that the current value of the 'pulse_count' field in the 'status' register
  -- equals the given 'expected' value.
  procedure check_counter_status_pulse_count_equal(
    signal net : inout network_t;
    expected : in counter_status_pulse_count_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    message : in string := ""
  ) is
    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Checking the 'pulse_count' field in the 'status' register"
      & register_array_message
      & base_address_message
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;

    variable got_reg : counter_status_t := counter_status_init;
    variable got : counter_status_pulse_count_t := counter_status_pulse_count_init;
  begin
    read_counter_status(
      net => net,
      value => got_reg,
      base_address => base_address,
      bus_handle => bus_handle
    );
    got := got_reg.pulse_count;

    check_equal(got=>got, expected=>expected, msg=>get_message);
  end procedure;
  -- ---------------------------------------------------------------------------

end package body;

Generated VHDL simulation wait until package

Below is the generated register simulation wait until package, created from the TOML file above via the VhdlSimulationWaitUntilPackageGenerator class. It is used by the VHDL example testbench to wait for registers to assume a give value.

Click to expand/collapse code.

Example register simulation wait until package.

-- This file is automatically generated by hdl-registers version 6.0.2-dev.
-- Code generator VhdlSimulationWaitUntilPackageGenerator version 1.0.0.
-- Generated 2024-09-19 20:51 from file regs_counter.toml at commit 25b9eb172eb22827.
-- Register hash 49f02a8daa9dd4bc3dadeb2a1cfd61dcc38c3864.

library ieee;
use ieee.fixed_pkg.all;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

library vunit_lib;
use vunit_lib.bus_master_pkg.bus_master_t;
use vunit_lib.bus_master_pkg.wait_until_read_equals;
use vunit_lib.com_types_pkg.max_timeout;
use vunit_lib.com_types_pkg.network_t;
use vunit_lib.string_ops.hex_image;

library common;
use common.addr_pkg.addr_t;
use common.addr_pkg.addr_width;

library reg_file;
use reg_file.reg_file_pkg.reg_t;
use reg_file.reg_operations_pkg.regs_bus_master;

use work.counter_regs_pkg.all;
use work.counter_register_record_pkg.all;


package counter_register_wait_until_pkg is

  -- ---------------------------------------------------------------------------
  -- Wait until the 'config' register equals the given 'value'.
  procedure wait_until_counter_config_equals(
    signal net : inout network_t;
    value : in counter_config_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  );

  -- Wait until the 'condition' field in the 'config' register equals the given 'value'.
  procedure wait_until_counter_config_condition_equals(
    signal net : inout network_t;
    value : in counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  );

  -- Wait until the 'increment' field in the 'config' register equals the given 'value'.
  procedure wait_until_counter_config_increment_equals(
    signal net : inout network_t;
    value : in counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  );
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Wait until the 'status' register equals the given 'value'.
  procedure wait_until_counter_status_equals(
    signal net : inout network_t;
    value : in counter_status_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  );

  -- Wait until the 'enabled' field in the 'status' register equals the given 'value'.
  procedure wait_until_counter_status_enabled_equals(
    signal net : inout network_t;
    value : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  );

  -- Wait until the 'pulse_count' field in the 'status' register equals the given 'value'.
  procedure wait_until_counter_status_pulse_count_equals(
    signal net : inout network_t;
    value : in counter_status_pulse_count_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  );
  -- ---------------------------------------------------------------------------

end package;

package body counter_register_wait_until_pkg is

  -- ---------------------------------------------------------------------------
  -- Wait until the 'config' register equals the given 'value'.
  procedure wait_until_counter_config_equals(
    signal net : inout network_t;
    value : in counter_config_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  ) is
    constant reg_value : reg_t := to_slv(value);

    constant reg_index : counter_reg_range := counter_config;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);

    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Timeout while waiting for the 'config' register"
      & register_array_message
      & base_address_message
      & " to equal the given value: "
      & to_string(reg_value)
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;
  begin
    wait_until_read_equals(
      net => net,
      bus_handle => bus_handle,
      addr => std_ulogic_vector(reg_address),
      value => reg_value,
      timeout => timeout,
      msg => get_message
    );
  end procedure;

  -- Wait until the 'condition' field in the 'config' register equals the given 'value'.
  procedure wait_until_counter_config_condition_equals(
    signal net : inout network_t;
    value : in counter_config_condition_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  ) is
    constant reg_value : reg_t := (
      counter_config_condition => to_slv(value),
      others => '-'
    );

    constant reg_index : counter_reg_range := counter_config;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);

    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Timeout while waiting for the 'condition' field in the 'config' register"
      & register_array_message
      & base_address_message
      & " to equal the given value: "
      & to_string(reg_value)
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;
  begin
    wait_until_read_equals(
      net => net,
      bus_handle => bus_handle,
      addr => std_ulogic_vector(reg_address),
      value => reg_value,
      timeout => timeout,
      msg => get_message
    );
  end procedure;

  -- Wait until the 'increment' field in the 'config' register equals the given 'value'.
  procedure wait_until_counter_config_increment_equals(
    signal net : inout network_t;
    value : in counter_config_increment_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  ) is
    constant reg_value : reg_t := (
      counter_config_increment => to_counter_config_increment_slv(value),
      others => '-'
    );

    constant reg_index : counter_reg_range := counter_config;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);

    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Timeout while waiting for the 'increment' field in the 'config' register"
      & register_array_message
      & base_address_message
      & " to equal the given value: "
      & to_string(reg_value)
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;
  begin
    wait_until_read_equals(
      net => net,
      bus_handle => bus_handle,
      addr => std_ulogic_vector(reg_address),
      value => reg_value,
      timeout => timeout,
      msg => get_message
    );
  end procedure;
  -- ---------------------------------------------------------------------------

  -- ---------------------------------------------------------------------------
  -- Wait until the 'status' register equals the given 'value'.
  procedure wait_until_counter_status_equals(
    signal net : inout network_t;
    value : in counter_status_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  ) is
    constant reg_value : reg_t := to_slv(value);

    constant reg_index : counter_reg_range := counter_status;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);

    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Timeout while waiting for the 'status' register"
      & register_array_message
      & base_address_message
      & " to equal the given value: "
      & to_string(reg_value)
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;
  begin
    wait_until_read_equals(
      net => net,
      bus_handle => bus_handle,
      addr => std_ulogic_vector(reg_address),
      value => reg_value,
      timeout => timeout,
      msg => get_message
    );
  end procedure;

  -- Wait until the 'enabled' field in the 'status' register equals the given 'value'.
  procedure wait_until_counter_status_enabled_equals(
    signal net : inout network_t;
    value : in std_ulogic;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  ) is
    constant reg_value : reg_t := (
      counter_status_enabled => value,
      others => '-'
    );

    constant reg_index : counter_reg_range := counter_status;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);

    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Timeout while waiting for the 'enabled' field in the 'status' register"
      & register_array_message
      & base_address_message
      & " to equal the given value: "
      & to_string(reg_value)
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;
  begin
    wait_until_read_equals(
      net => net,
      bus_handle => bus_handle,
      addr => std_ulogic_vector(reg_address),
      value => reg_value,
      timeout => timeout,
      msg => get_message
    );
  end procedure;

  -- Wait until the 'pulse_count' field in the 'status' register equals the given 'value'.
  procedure wait_until_counter_status_pulse_count_equals(
    signal net : inout network_t;
    value : in counter_status_pulse_count_t;
    base_address : in addr_t := (others => '0');
    bus_handle : in bus_master_t := regs_bus_master;
    timeout : delay_length := max_timeout;
    message : string := ""
  ) is
    constant reg_value : reg_t := (
      counter_status_pulse_count => to_counter_status_pulse_count_slv(value),
      others => '-'
    );

    constant reg_index : counter_reg_range := counter_status;
    constant reg_address : addr_t := base_address + to_unsigned(4 * reg_index, addr_width);

    constant register_array_message : string := "";
    function base_address_message return string is
    begin
      if base_address /= 0 then
        return " (at base address " & hex_image(std_logic_vector(base_address)) & ")";
      end if;

      return "";
    end function;
    constant base_message : string := (
      "Timeout while waiting for the 'pulse_count' field in the 'status' register"
      & register_array_message
      & base_address_message
      & " to equal the given value: "
      & to_string(reg_value)
      & "."
    );
    function get_message return string is
    begin
      if message = "" then
        return base_message;
      end if;

      return base_message & " " & message & ".";
    end function;
  begin
    wait_until_read_equals(
      net => net,
      bus_handle => bus_handle,
      addr => std_ulogic_vector(reg_address),
      value => reg_value,
      timeout => timeout,
      msg => get_message
    );
  end procedure;
  -- ---------------------------------------------------------------------------

end package body;

Performance

Since generation of VHDL packages is usually run in real time (e.g. before running a simulation) the speed of the tool is important. In order the save time, RegisterCodeGenerator.create_if_needed() maintains a hash of the register definitions, and will only generate the VHDL file when necessary. Hence it is recommended to call this function as opposed to RegisterCodeGenerator.create() which will waste time by always re-creating, even when it is not necessary.

See here for a comparison with the performance of other tools.

Dependencies

Most of the generated code depends on VHDL packages from hdl-modules version 4.0.0 or greater.

The VhdlRegisterPackageGenerator and VhdlRecordPackageGenerator packages depend on reg_file_pkg.vhd. Can be downloaded from GitHub here: https://github.com/hdl-modules/hdl-modules/blob/main/modules/reg_file/src/reg_file_pkg.vhd

The VhdlSimulationReadWritePackageGenerator and VhdlSimulationWaitUntilPackageGenerator packages furthermore depend on reg_operations_pkg.vhd and addr_pkg.vhd.

The VhdlAxiLiteWrapperGenerator package also depends on axi_lite_pkg.vhd.

Unresolved types

The generated VHDL uses unresolved types (e.g. std_ulogic_vector instead of std_logic_vector) consistently. This means that accidental multiple drivers of a signal will result in an error when simulating or synthesizing the design.

Since e.g. std_logic is a sub-type of std_ulogic in VHDL-2008, it is no problem if hdl-registers components are integrated in a code base that still uses the resolved types. I.e. a std_logic signal can be assigned to a hdl-registers signal of type std_ulogic, and vice versa, without problem.

Further tools for simplifying register handling

There is a large eco-system of register-related components in the hdl-modules project. Firstly there are wrappers in the bfm library for easier working with VUnit verification components. Furthermore there is a large number of synthesizable AXI/AXI-Lite components available that enable the register bus:

• AXI-to-AXI-Lite converter: axi_to_axi_lite.vhd,

• AXI/AXI-Lite crossbar: axi_simple_read_crossbar.vhd, axi_simple_write_crossbar.vhd, axi_lite_simple_read_crossbar.vhd, axi_lite_simple_write_crossbar.vhd,

• AXI-Lite mux (splitter): axi_lite_mux.vhd,

• AXI-Lite clock domain crossing: axi_lite_cdc.vhd,

• etc…

See the reg_file library, axi library and axi_lite library for more details.