Module 4 - Testbench

1. Understanding Testbench in VHDL

A VHDL testbench is a non-synthesizable VHDL entity used to simulate and verify the functionality of another VHDL entity, often referred to as the Unit Under Test (UUT). Think of it as a virtual lab environment where you can apply a sequence of inputs (stimulus) to your design and observe its behavior and outputs over time. Since the testbench itself is not meant to be turned into a physical chip, it can use more abstract and powerful VHDL constructs that are not available for synthesizable hardware descriptions.

A testbench has many uses, including:

2. Components of a Testbench

2.1 Entity Declaration

The testbench entity is declared without any ports. It's a self-contained module because it doesn't connect to any higher-level design; it is the top-level entity for the simulation.

entity project_tb is
    -- Empty because testbench doesn't have any port
end project_tb

2.2 Architecture Declaration

2.2.1 UUT Component Declaration

Inside the architecture, we first declare the entity we want to test (the UUT) as a component. The component declaration must match the entity declaration of the UUT.

For example, if we have a UUT with these entity declaration:

entity earth_destroyer is
    Port (
        clk, rst    : IN STD_LOGIC;
        input       : IN STD_LOGIC VECTOR(7 downto 0);
        mode        : IN STD_LOGIC_VECTOR(3 downto 0);
        output      : OUT STD_LOGIC_VECTOR(7 downto 0)
    );
end earth_destroyer;

The UUT component declaration for that entity will be:

component earth_destroyer is
    Port (
        clk, rst    : IN STD_LOGIC;
        input       : IN STD_LOGIC VECTOR(7 downto 0);
        mode        : IN STD_LOGIC_VECTOR(3 downto 0);
        output      : OUT STD_LOGIC_VECTOR(7 downto 0)
    );
end component;

As you can see, component declaration is almost the exact same as entity declaration. Just make sure you change entity to component and use end component instead of end <entity name>, and you're good to go.

2.2.2 Signals Declaration

We must declare internal signals within the testbench architecture. You should at least declare all the signals that corresponds to the entity input/output ports. These signals will be connected to the ports of the UUT to drive its inputs and monitor its outputs.

For example, if we have earth_destroyer entity as in Part 2.2.1, we should declare these signals:

signal clk_tb    : STD_LOGIC := '0';
signal rst_tb    : STD_LOGIC;
signal input_tb  : STD_LOGIC VECTOR(7 downto 0);
signal mode_tb   : STD_LOGIC_VECTOR(3 downto 0);
signal output_tb : STD_LOGIC_VECTOR(7 downto 0);

The name of the signal doesn't really matter, as long as its data type match the port it corresponds to.

2.3 Port Map

In VHDL, a port map is part of the component instantiation within an architecture that maps the input and output ports of an entity to local signals. By using port map, we can connect a testbench to the entity being tested, allowing inputs to be driven and outputs to be observed through the testbench.

The general syntax of port map in a testbench is:

UUT : entity_name port map (entity_port_name => local_signal_name);

For example, if we want to instantiate the component as in Part 2.2, we can write it like this:

UUT : earth_destroyer port map (
    clk    => clk_tb,
    rst    => rst_tb,
    input  => input_tb,
    mode   => mode_tb,
    output => output_tb
);

3. Testbench Architecture Models

3.1 Testbench for Combinational Circuit

There are three architectural models for changing the value of inputs in a testbench. For example, if we want to make a testbench for a half adder entity below, we could use three methods:

library IEEE;
use IEEE.STD_LOGIC_1164.all;

entity half_adder is
    Port (
        a, b       : in STD_LOGIC;
        sum, carry : out STD_LOGIC
    );
end half_adder;
    
architecture arch of half_adder is
begin
    
    sum <= a xor b;
    carry <= a and b;
    
end arch;

3.1.1 Simple Testbench

This method is very similar to the dataflow style of VHDL programming. Values are directly assigned to input signals using the <= symbol. The difference is that each value assignment is separated by the after keyword, which indicates that the value will change after the testbench has run for the specified amount of time. For example, '1' after 60 ns means the value of the signal will change from '0' to '1' after the simulation has run for 60 ns from the very beginning.

library IEEE;
use IEEE.STD_LOGIC_1164.all;

entity half_adder_tb is
end half_adder_tb;
    
architecture tb of half_adder_tb is
    
    -- component declaration for half_adder
    component half_adder is
        Port (
            a, b       : in STD_LOGIC;
            sum, carry : out STD_LOGIC
        );
    end component;
    
    -- signal declaration for input/output stimulus
    signal a, b       : STD_LOGIC;    -- Input
    signal sum, carry : STD_LOGIC;    -- Output

begin
    -- component instantiation to connect tb to entity
    UUT: half_adder port map (
        a => a,
        b => b,
        sum => sum,
        carry => carry
    );
    
    -- input assignment (simple testbench)
    a <= '0', '1' after 20 ns, '0' after 40 ns, '1' after 60 ns;
    b <= '0', '1' after 40 ns;

end tb;

3.1.2 Testbench Using a process Statement

This method is similar to the behavioral style of VHDL programming, which uses a process statement. In this approach, every line of code inside the process is executed sequentially, one by one, much like in a typical programming language.

-- input assignment (process testbench)
tb1: process
    constant period    : time := 20 ns;
    begin
        a <= '0';
        b <= '0';
        wait for period;
            
        a <= '0';
        b <= '1';
        wait for period;
            
        a <= '1';
        b <= '0';
        wait for period;
            
        a <= '1';
        b <= '1';
        wait for period;
        
        wait; -- wait until the end of time
    end process;

3.1.3 Testbench Using a Look-up Table

This method is an extension of the process-based testbench. Instead of assigning each combination of values one by one, this method works by storing the combinations in a separate variable, called a look-up table (which can be a signal or a constant).

-- input assignment (look-up table testbench)
tb1: process
    constant period    : time := 20 ns;
    constant stream_a  : STD_LOGIC_VECTOR(0 to 3) := ('0', '1', '0', '1');
    constant stream_b  : STD_LOGIC_VECTOR(0 to 3) := ('0', '0', '1', '1');

    begin
        a <= stream_a(0);
        b <= stream_b(0);
        wait for period;
            
        a <= stream_a(1);
        b <= stream_b(1);
        wait for period;
            
        a <= stream_a(2);
        b <= stream_b(2);
        wait for period;
            
        a <= stream_a(3);
        b <= stream_b(3);
        wait for period;
        
        wait; -- wait until the end of time
    end process;

You can also use for loop for a more efficient implementation, but more of it will be covered in Module 6 and it's not recommended for this module.

3.2 Testbench for Sequential Circuit

A testbench for a sequential circuit is not much different from a testbench for a combinational circuit. The main difference is the need for several additional inputs, including a Clock and a Reset.

3.2.1 Clock Process

The clock is the heartbeat of a sequential circuit. In a testbench, the clock signal must be generated continuously throughout the simulation to drive the Unit Under Test (UUT). This is almost always done using a dedicated, independent process.

-- Inside of testbench architecture
    constant period    : time := 20 ns;    -- clock period
    signal clk         : STD_LOGIC;        -- clock signal

begin
    clk_generator : process
    begin
        clk <= '0';
        wait for period/2;
        clk <= '1';
        wait for period/2;
    end process;

3.2.2 Example of Testbench for Sequential Circuit

For example, we want to make a testbench for this updown counter entity:

library IEEE;
use IEEE.std_logic_1164.all;
use IEEE.numeric_std.all;

entity counter_updown is
    Port (
        RESET, CLK, LD, UP : in std_logic;
        DIN                : in std_logic_vector (3 downto 0);
        COUNT              : out std_logic_vector (3 downto 0)
    );
end counter_updown;

architecture my_count of counter_updown is
    signal t_cnt : unsigned(3 downto 0); -- internal counter signal
begin
    process (CLK, RESET)
    begin
        if (RESET = '1') then
            t_cnt <= (others => '0'); -- clear
        elsif (rising_edge(CLK)) then
            if (LD = '1') then t_cnt <= unsigned(DIN); -- load
            else
                if (UP = '1') then t_cnt <= t_cnt + 1; -- incr
                else t_cnt <= t_cnt - 1; -- decr
                end if;
            end if;
        end if;
    end process;
    COUNT <= std_logic_vector(t_cnt);
end my_count;

In this case, the testbench combines the three architectural models that were previously explained. The Clock signal uses a process statement, while the Reset signal uses the simple assignment method. The other inputs are assigned directly in the declaration section because their values will not change.

Additionally, it is important to note the presence of the max_clk variable, which is used to limit the number of clock cycles run by the testbench. If the clock cycles are not limited, the testbench will continue to run indefinitely unless the program is stopped manually.

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

entity counter_updown_tb is
end counter_updown_tb;

architecture arch of counter_updown_tb is
    component counter_updown is
        Port (
            RESET, CLK, LD, UP : in std_logic;
            DIN                : in std_logic_vector (3 downto 0);
            COUNT              : out std_logic_vector (3 downto 0)
        );
    end component;

    constant period    : time := 20 ns;    -- clock period
    constant max_clk   : integer := 11;    -- maximum clock cycle
    signal cnt         : integer := 0;     -- clock cycle counter

    constant LD        : std_logic := '0';              -- input
    constant UP        : std_logic := '1';              -- input
    signal DIN         : std_logic_vector(3 downto 0);  -- input
    signal RESET       : std_logic;                     -- input
    signal CLK         : std_logic;                     -- input
    signal COUNT       : std_logic_vector(3 downto 0);  -- output

begin
    UUT : counter_updown port map (RESET, CLK, LD, UP, DIN, COUNT);
        
    -- reset = '1' at the first clock cycle, then change to '0'
    reset <= '1', '0' after period/2;

    CLK_generator : process
    begin
        CLK <= '0';
        wait for period/2;
        CLK <= '1';
        wait for period/2;

        if(cnt < max_clk) then cnt <= cnt + 1;
        else wait;
        end if;
    end process;
end arch;

Here is the simulation result of the testbench above: Result

4. Assert and Report Statement

4.1 Assert Statement

The assert statement is used for creating self-checking testbenches. It acts like an automated check that constantly monitors a condition. If the condition is false, it "asserts" a message, alerting us to a problem without requiring us to manually inspect the waveforms.

The full syntax of an assert statement is:

ASSERT condition REPORT "message" SEVERITY level;

For example, if we want to implement the assert statement in our testbench from section 3.1.2, we can implement it as below:

tb1: process
    constant period    : time := 20 ns;
    begin
        a <= '0';
        b <= '0';
        wait for period;
            
        assert ((sum = '0') and (carry = '0'))
        report "tes gagal pada testcase ke-1" severity error;
            
        a <= '0';
        b <= '1';
        wait for period;
            
        assert ((sum = '1') and (carry = '0'))
        report "tes gagal pada testcase ke-2" severity error;
            
        a <= '1';
        b <= '0';
        wait for period;
            
        assert ((sum = '1') and (carry = '0'))
        report "tes gagal pada testcase ke-3" severity error;
            
        a <= '1';
        b <= '1';
        wait for period;
            
        assert ((sum = '0') and (carry = '1'))
        report "tes gagal pada testcase ke-4" severity error;
        
        wait; -- wait until the end of time
    end process;

The following is the output produced by the testbench: TB Result

4.2 Severity Level

The severity level tells the simulator how serious the failed assertion is. There are four standard levels:

Level Description Simulator Action
NOTE Informational message. Used for debugging, tracing, or indicating progress. Prints the message and continues simulation.
WARNING Non-critical issue. Something is unexpected or out of spec, but the design might still function. Prints a warning and continues simulation. Increments a warning counter.
ERROR Functional failure. The design's output is incorrect. This is the standard for a failed test. Prints an error and continues simulation. Increments an error counter.
FAILURE Catastrophic/Fatal error. Something is fundamentally broken, making further simulation pointless. Prints a failure message and immediately halts the simulation.

Note that if we don't explicitly specify which severity level used in a report statement, it automatically defaults to note.

5. File I/O in VHDL

In VHDL, we can perform file handling using the TextIO library. This feature is very useful for documenting the results of a program that has been created. To use the TextIO library, we need to add it at the beginning of our program as follows:

use std.textio.all;
use ieee.std_logic_textio.all; -- For std_logic types

5.1 Read File

When repeatedly simulating a design, changing the value of each input one by one can be time-consuming and inefficient. Therefore, we can use a feature from the TextIO library that can read inputs from a file to be used in the design simulation.

Here is how to read input from a file in VHDL. First, we can define the file to be read within a process statement and open it in read_mode:

process
    -- Define the file and its open mode
    file text_file   : text open read_mode is "filename.txt";

    -- Variable to receive data from the file
    variable fileinp : integer;

    -- Line type variable to hold a row from the text file
    variable row     : line;

    -- Variale to store file reading status
    variable ok      : boolean

Then, we can read the file using the readline and read procedures from the TextIO library as follows:

begin
    while not endfile(text_file) loop --loop until the end of the text file
        readline(text_file, row); --reads the line from the file
        
        -- Skip empty lines or comments that start with '#'
        if row.all'length = 0 or row.all(1) = '#' then
            next;
        end if;

        -- Reads a variable from the line and puts it into fileinp
        read(row, fileinp, ok); 
        
        assert ok
        report "Read 'sel' failed for line: " & row.all
        severity failure;  --report if the file read fails
         
        wait for delay; --delay for the read iteration
    end loop;
end process;

5.2 Write File

Besides reading a set of inputs to be used in a testbench, we can also use the TextIO library to save the results of our testbench to a file. This allows us to analyze the results without having to use a simulator like ModelSim or Vivado.

Here are the steps required to write the results of a testbench to a file. First, we can define the file to be created and open it in write_mode:

process
    -- Open "filename.txt" in write mode
    file text_file      : text open write_mode is "filename.txt";

    -- Line type variable to build a row for the text file
    variable row        : line;

    -- Variable holding the data to be written to the file
    variable data_write : integer;

Then, we can use the write and writeline procedures rom the TextIO library to write data to the file as follows:

begin
    -- writes data to the file, left-justified, 15 characters
    write(row, data_write, left, 15); 

    writeline(text_file, row); -- writes the line to the file
end process;

Extra: Array in VHDL

6.1 Array

In VHDL, an array is a collection of elements that share the same data type. You can think of an array as a variable that holds many elements of the same type, and these elements are indexed to be accessed. The index can be a number or another indexable type, such as integer, natural, or std_logic_vector. Arrays can have one dimension (one-dimensional array) or more (two-dimensional, three-dimensional, and so on). Two-dimensional arrays are often used to represent tables or matrices.

6.2 Type

A type is a definition used to declare a new data type in VHDL. A type can be used to define complex data types, such as arrays or records, or as a type used to declare variables, ports, or signals. Types can also be used to describe the properties and structure of data.

VHDL has predefined data types, such as std_logic, std_logic_vector, integer, and others, but we can also create our own custom data types. Types that are predefined or embedded in VHDL libraries are called "built-in types," while types that we define ourselves are called "user-defined types."

Here is an example of using type and array to create a bank of 8-bit registers:

type RegisterArray is array (0 to 7) of std_logic_vector(7 downto 0);
signal registers : RegisterArray := (others => (others => '0'));

In the example above, we are defining a structure that could be used in an entity like a RegisterBank which has eight 8-bit registers. These registers are represented by the registers array, which has 8 elements, each with a length of 8 bits.