VUnit on Elaborated Designs

Using Queues in VHDL with VUnit

Thu, 13 Mar 2025 00:00:00 +0000

Learning Outcome

By the end of this post we’ll understand how to use queues to store and share data across processes in our test testbenches, and we’ll have several examples of working code to help us get started in our next project.

What is a Queue?

A queue is a data structure into which data are written on one side (push) and read on the other side (pop). Queues operate on a first-in first-out basis, and like a hardware FIFO, we usually cannot access the elements inside the queue.

At a minimum, a queue must support pushing data to it and popping data from it. In a ‘push’ operation the data is added to the back of the queue. Any existing elements inside the queue are shifted to make room for the new data.

A ‘pop’ operation works in the opposite direction: data is removed from the from the front of the queue. Any remaining elements stay in their position as the queue shrinks, until eventually it is empty again.

Queues are very useful for storing and sharing data between processes in a test bench. A typical use case is to save the inputs to a design under test (DUT) in an input queue and the outputs of the DUT in an output queue. The test bench can then run a reference model that reads the data from the input queue, calculates a set of expected outputs, and compares them with the actual output values stored in the output queue.

Using Queues in VUnit

Unlike SystemVerilog, VHDL does not support queues natively. Luckily, the VUnit verification framework includes a queue data type and API to interact with it, so we don’t have to implement our own.

The function calls that we’ll use most frequently when working with queues in VUnit are: new, push, pop, is_empty, length, and flush. Let’s discuss each one with a code example.

We start by setting up a minimal VUnit testbench.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


-- File: vunit_queues.vhd

library vunit_lib;
context vunit_lib.vunit_context;

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

architecture tb of tb_example is
begin
  main : process
  begin
    test_runner_setup(runner, runner_cfg);
    test_runner_cleanup(runner);
  end process;
end architecture;

Then we can add our ’test_queue’ signal, of type ‘queue_t’.

1
2
3
4
5


-- File: vunit_queues.vhd

architecture tb of tb_example is
  signal test_queue : queue_t;
begin

We’ll also declare several variables in our ‘main’ process to exchange data with the queue API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


-- File: vunit_queues.vhd

main : process
  variable bit_push_v       : std_logic := '1';
  variable vector_16_push_v : std_logic_vector(15 downto 0) := x"0123";
  variable vector_32_push_v : std_logic_vector(31 downto 0) := x"456789AB";
  variable integer_push_v   : integer := 2147483647;
  variable bit_pop_v        : std_logic
  variable vector_16_pop_v  : std_logic_vector(15 downto 0);
  variable vector_32_pop_v  : std_logic_vector(31 downto 0);
  variable integer_pop_v    : integer;
begin

Now we are ready to describe the logic in our ‘main’ process.

New

The ’new’ function creates the underlying queue object that we will use. It must be called before performing any other operations on the queue.

1
2
3
4
5


-- File: vunit_queues.vhd

info("***** Creating the queue *****");
test_queue <= new_queue;
wait for 0 ns;  -- Removing this will cause an error

One important thing to note is that the queue operations do not consume any simulation time, so in some cases we’ll need to add a delay to make sure that a function call is executed. In this example, if we remove the ‘wait for 0 ns’ statement, the next operation (push) would produce an error, because we’d be trying to manipulate a null queue.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# Surrounding code from 'see' command
#   86 :     value : character
#   87 :   ) is
#   88 :     variable tail : integer;
#   89 :     variable head : integer;
#   90 :   begin
# ->91 :     assert queue /= null_queue report "Push to null queue";
#   92 :     tail := get(queue.p_meta, tail_idx);
#   93 :     head := get(queue.p_meta, head_idx);
#   94 :     if length(queue.data) < tail + 1 then
#   95 :       -- Allocate more new data, double data to avoid
# 
fail (P=0 S=0 F=1 T=1) lib.vubit_queue_tb.all (1.6 seconds)

Push

The ‘push’ function stores a new element into the queue. Unlike SystemVerilog queues, a single VUnit queue can hold elements of different data types at the same time.

1
2
3
4
5
6
7


-- File: vunit_queues.vhd

info("Pushing elements of different types to the queue");
push(test_queue, bit_v);
push(test_queue, vector_16_v);
push(test_queue, vector_32_v);
push(test_queue, integer_v);

Pop

The ‘pop’ function removes the oldest element in the queue and returns it so that we can use or store it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


-- File: vunit_queues.vhd

info("***** Popping elements of different types from the queue *****");
bit_pop_v := pop(test_queue);
vector_16_pop_v := pop(test_queue);
vector_32_pop_v := pop(test_queue);
integer_pop_v := pop(test_queue);
info("Popped a 16-bit vector: " & to_hstring(vector_16_pop_v));
info("Popped a 32-bit vector: " & to_hstring(vector_32_pop_v));
info("Popped an integer: " & integer'image(integer_pop_v));

1
2
3
4
5
6


-- Simulation output

# 0 ps - default - INFO - ***** Popping elements of different types from the queue *****
# 0 ps - default - INFO - Popped a 16-bit vector: 0123
# 0 ps - default - INFO - Popped a 32-bit vector: 456789AB
# 0 ps - default - INFO - Popped an integer: 2147483647

The VUnit API also includes verbose versions of the ‘push’ and ‘pop’ functions, which we can use to make the type of the argument or return type explicit.

1
2
3
4
5
6
7


-- File: vunit_queues.vhd

info("***** Using verbose funtion calls to resolve data types *****");
push(test_queue, vector_32_push_v);
info("Popping a logic vector: " & to_string(pop_std_ulogic_vector(test_queue)));
push(test_queue, vector_32_push_v);
-- info("Popping a logic vector: " & to_string(pop(test_queue)));    -- Error!

Uncommenting the last line of the code section above produces an error.

1
2
3
4
5


-- Simulation output

# 0 ps - default - INFO - ***** Using verbose funtion calls to resolve data types *****
# 0 ps - default - INFO - Popping a logic vector: 01000101011001111000100110101011
# ** Error: Got queue element of type std_ulogic_vector, expected string_ptr_t.

We can comment the last line again to get the testbench running. This also leaves the second 32-bit vector still in the queue.

Is Empty

The ‘is_empty’ function returns ‘true’ if the queue is empty, and ‘false’ if it has at least one element.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


-- File: vunit_queues.vhd

info("Checking if the queue is empty");
if is_empty(test_queue) then
  info("The queue is empty");
else
  info("The queue is not empty");
end if;
push(test_queue, bit_v);
if is_empty(test_queue) then
  info("The queue is empty");
else
  info("The queue is not empty");
end if;

1
2
3
4
5


-- Simulation output

# 0 ps - default - INFO - ***** Checking if the queue is empty *****
# 0 ps - default - INFO - The queue is not empty
# 0 ps - default - INFO - The queue is empty

Flush

The ‘flush’ function removes all elements from the queue, leaving it empty.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


-- File: vunit_queues.vhd

info("***** Flushing the queue *****");
push(test_queue, bit_push_v);
push(test_queue, vector_16_push_v);
push(test_queue, vector_32_push_v);
push(test_queue, integer_push_v);
info("Queue length before flushing:" & natural'image(length(test_queue)));
flush(test_queue);
info("Queue length after flushing:" & natural'image(length(test_queue)));

1
2
3
4
5


-- Simulation output

# 0 ps - default - INFO - ***** Flushing the queue *****
# 0 ps - default - INFO - Queue length before flushing: 59
# 0 ps - default - INFO - Queue length after flushing: 0

Length

The ’length’ function returns the length of the queue, in bytes. It’s important to note that this length refers to the space that the simulator allocates to each element in the queue, and not the size of the element that we use in our test bench. For example, calling the ‘length’ function on a queue with one integer returns 5 bytes, not the 4 bytes that we might expect given that an integer in VHDL is by default 32-bits wide. The same applies to logic vectors: the length of a 1-bit vector is 2 bytes, the length of a 32-bit vector is 30 bytes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


-- File: vunit_queues.vhd

info("***** Getting the queue's length *****");
push(test_queue, bit_push_v);
info("Queue length after pushing a single bit: " & natural'image(length(test_queue)));
flush(test_queue);
push(test_queue, vector_8_push_v);
info("Queue length after pushing a 8-bit vector: " & natural'image(length(test_queue)));
flush(test_queue);
push(test_queue, vector_16_push_v);
info("Queue length after pushing a 16-bit vector: " & natural'image(length(test_queue)));
flush(test_queue);
push(test_queue, vector_32_push_v);
info("Queue length after pushing a 32-bit vector: " & natural'image(length(test_queue)));
flush(test_queue);
push(test_queue, integer_push_v);
info("Queue length after pushing an integer: " & natural'image(length(test_queue)));
flush(test_queue);

1
2
3
4
5
6
7
8


-- Simulation output

# 0 ps - default - INFO - ***** Getting the queue's length *****
# 0 ps - default - INFO - Queue length after pushing a single bit:2
# 0 ps - default - INFO - Queue length after pushing a 8-bit vector:18
# 0 ps - default - INFO - Queue length after pushing a 16-bit vector:22
# 0 ps - default - INFO - Queue length after pushing a 32-bit vector:30
# 0 ps - default - INFO - Queue length after pushing an integer:5

Summary

In this post we discussed queues, a FIFO-like data structure that we can use to transfer data between processes in a testbench. Because of VHDL’s lack of native support for queues, we looked into the VUnit’s queue library, and ran code examples for the most common operations in the VUnit queue API: new, push, pop, is_empty, length, and flush.

Cheers,

Isaac

Setting up a VHDL Verification Environment with VUnit

Fri, 24 Jan 2025 00:00:00 +0000

Using a verification framework can dramatically improve the quality of our designs. However, setting up a verification framework from scratch can be quite daunting. Luckily, there are open-source libraries that handle most of the infrastructure required for creating, running and managing our tests, so that we can focus on the parts of our testbench that are unique to our design and add value to our development process.

In this post we will set up a minimal verification environment with VUnit. Our testbench will include verification components for driving an monitoring an AXI-Stream bus.

What is VUnit?

VUnit is a open-source unit-testing framework for digital systems design with VHDL and SystemVerilog. It provides the infrastructure for creating and managing verification environments so we can focus on writing meaningful tests. At its core, VUnit provides a Python-based test runner that manages our test cases, handles compilation dependencies, and produces structured test reports.

In addition to automating the simulation runs and test management, VUnit also provides several libraries to help write our testcases. These libraries include verification components, logging mechanisms, check procedures, and randomization. By leveraging these pre-built components we can make the testcase-creation process more efficient, less error-prone, and more enjoyable.

Prerequisites for Setting up a Verification Environment with VUnit

There are two prerequisites for using VUnit: we must have a supported VHDL simulator and we must have a Python installation, including a package manager and a tool for creating virtual environments.

VUnit supports several simulators, a comprehensive list can be found in the project’s documentation. For this example we will use GHDL. In Ubuntu 24.04.1 LTS we can install GHDL using the Snap packet manager.

1

sudo snap install ghdl

Once we have our simulator, we can install the VUnit Python module. The recommended way to do this is within a Python virtual environment. If we’re using venv we can do this from the terminal by moving into the folder where we’ll run our simulations and using the commands shown below.

1
2
3


python3 -m venv venv
source venv/bin/activate
pip install vunit_hdl

We are now ready to create our verification environemnt.

Setting up a minimal Verification Environment with VUnit

A VUnit verification environment includes at least two files: a testbench and a simulation script.

This is what a VUnit testbench in its simplest form looks like, as described in the VUnit User Guide.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


library vunit_lib;
context vunit_lib.vunit_context;

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

architecture tb of tb_example is
begin
  main : process
  begin
    test_runner_setup(runner, runner_cfg);
    report "Hello world!";
    test_runner_cleanup(runner); -- Simulation ends here
  end process;
end architecture;

We must pair our testbench with a simulation script, which in its minimal form looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


from vunit import VUnit

# Create VUnit instance by parsing command line arguments
vu = VUnit.from_argv()

# Add VUnit's builtin HDL utilities
vu.add_vhdl_builtins()

# Create library 'lib'
lib = vu.add_library("lib")

# Add all files ending in .vhd in current working directory to library
lib.add_source_files("*.vhd")

# Run vunit function
vu.main()

We can then run the simulation script from the command line.

1

python3 run.py

The terminal output confirms that the test was run succesfully. Line 4 shows the location of the file where all the messages in our testbench are logged.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


Compile passed

Starting lib.tb_example.all
Output file: /home/isaac/Projects/blog/004_vunit_verification_environment/vunit_out/test_output/lib.tb_example.all_7b5933c73ddb812488c059080644e9fd58c418d9/output.txt
pass (P=1 S=0 F=0 T=1) lib.tb_example.all (0.3 seconds)

==== Summary ==============================
pass lib.tb_example.all (0.3 seconds)
===========================================
pass 1 of 1
===========================================
Total time was 0.3 seconds
Elapsed time was 0.3 seconds
===========================================
All passed!

Our testcase executed a single statement - printing “Hello World!” to the output file.

1
2


/home/isaac/Projects/blog/004_vunit_verification_environment/vunit_tb.vhd:13:5:@0ms:(report note): Hello world!
simulation stopped @0ms with status 0

Using AXI-Stream Verification Components

VUnit includes Verification Components with support for several standard interfaces, including AXI-Stream.

To get started, we include the vu.add_verification_components() statement in our simulation script to add support for the Verification Components.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


from vunit import VUnit

# Create VUnit instance by parsing command line arguments
vu = VUnit.from_argv()

# Add VUnit's builtin HDL utilities
vu.add_vhdl_builtins()

# Add VUnit Verification Components
vu.add_verification_components()

# Create library 'lib'
lib = vu.add_library("lib")

# Add all files ending in .vhd in current working directory to library
lib.add_source_files("*.vhd")

# Run vunit function
vu.main()

We can now expand our existing testbench by adding one AXI-Stream Master and one AXI-Stream Slave Verification Component. First we add all the signals and constants that we’ll use to configure and connect the verification components.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


architecture tb of tb_example is

  signal    clk             : std_logic := '0';
  constant  CLK_PERIOD      : time      := 10 ns;
  constant  AXIS_DATA_WIDTH : integer   := 24;

  -- AXI-Stream Master Interface Deifnition and Configuration
  constant m_axis : axi_stream_master_t := new_axi_stream_master(
    data_length => AXIS_DATA_WIDTH,
    stall_config => new_stall_config(0.05, 1, 10)
  );

  -- AXI-Stream Slave Interface Deifnition and Configuration
  constant s_axis  : axi_stream_slave_t  := new_axi_stream_slave(
    data_length => AXIS_DATA_WIDTH,
    stall_config => new_stall_config(0.05, 1, 10)
  );

  -- AXI-Stream Signals
  signal axis_valid  : std_logic;
  signal axis_ready  : std_logic;
  signal axis_last   : std_logic; 
  signal axis_data   : std_logic_vector(AXIS_DATA_WIDTH-1 downto 0);

begin

Then we can add the Verification Components themselves.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


begin

  vunit_axism : entity vunit_lib.axi_stream_master
    generic map (
      master => m_axis
    )
    port map (
      aclk   => clk,
      tvalid => axis_valid,
      tready => axis_ready,
      tdata  => axis_data,
      tlast  => axis_last
    );

  vunit_axiss : entity vunit_lib.axi_stream_slave
    generic map (
      slave => s_axis
    )
    port map (
      aclk   => clk,
      tvalid => axis_valid,
      tready => axis_ready,
      tdata  => axis_data,
      tlast  => axis_last
    );

  main : process
  begin
    test_runner_setup(runner, runner_cfg);
    report "Hello world!";
    test_runner_cleanup(runner); -- Simulation ends here
  end process;

end architecture;

We are now ready to generate - and capture - data over the AXI-Stream bus. To do this we must expand our ‘main’ process to start the data transmission and reception in the AXI-Stream Verification Components.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


main : process
  variable axis_tdata_v : std_logic_vector(AXIS_DATA_WIDTH-1 downto 0);
  variable axis_tlast_v : std_logic;
begin
  test_runner_setup(runner, runner_cfg);
  report "Hello world!";
  for i in 0 to 99 loop
    push_axi_stream(net, m_axis, std_logic_vector(to_unsigned(i, AXIS_DATA_WIDTH)) , tlast => axis_tlast);
    pop_axi_stream(net, s_axis, tdata => axis_tdata_v, tlast => axis_tlast_v);
  end loop;
  wait for 1 us;
  test_runner_cleanup(runner); -- Simulation ends here
end process main;

At this point we can simulate our expanded testbench. Because I’m using GHDL as my simulator, I’ll include an argument that creates a VCD waveform in the simulation script.

1

python3 run.py --gtkwave-fmt vcd

Finally, we can see the results of our simulation. For this example I’m using Surfer as a waveform viewer. Surfer is a VSCode extension, which allows us to visualize our waveforms without leaving the code editor.

Zooming in at the start of the simulation, we can see that the tvalid and tready signals of the AXI-Stream bus are toggled by the Verification Components. For this they use the parameters we set when we declared the m_axis and s_axis constants for the AXI-Stream Master and Slave interfaces, respectively.

Summary

In this post we created a minimal simulation environment with VUnit that included driving a monitoring AXI-Stream interfaces.

We started with a minimal VHDL testbench and a Python simulation script, which we used to create a bare-bones ‘Hello World!’ simulation. We then expanded the simulation script to include the VUnit verification components in our environment and added the logic required for instantiating, connecting, and using the Verification Components in our testbench. Finally, we ran our simulation and confirmed that our verification environment worked by inspecting the generated waveform.

Cheers,

Isaac