Writing Testbenches

So far (Chapters 7–9) you have written HDL that describes hardware. To know whether the description is right, you run it in a simulator: a program that computes, instant by instant, the value every signal would have in the real circuit. The simulator needs something to drive the inputs and watch the outputs. That something is the testbench — an HDL module that is never turned into hardware. It exists only in simulation, so it may use every language feature: delays, loops over time, files, printing.

The circuit being tested is called the DUT (device under test). A good testbench does four jobs: it generates a clock, applies a reset, feeds stimulus (input values), and checks the outputs automatically, ending with a clear PASS or FAIL. This chapter builds those four jobs one at a time, in both languages, and finishes with a reference model written in Python that the HDL testbench reads from a file.

We use two open-source simulators, one per language, plus a waveform viewer (Chapter 11):

Linux (Debian, Ubuntu, and WSL on Windows). All three are in the standard repositories:

sudo apt update
sudo apt install iverilog ghdl gtkwave
iverilog -V | head -1      # Icarus Verilog version 12.0 (stable)
ghdl --version | head -1   # GHDL 4.1.0 ...

macOS. Install Homebrew, then brew install icarus-verilog. GHDL publishes ready-made macOS archives (for Apple silicon and Intel) on its GitHub releases page; unpack one and add its bin directory to your PATH. The Homebrew packages for GHDL and GTKWave have at times been unavailable or blocked by Apple's Gatekeeper, so for viewing waveforms on a Mac the simplest choice is Surfer, a modern viewer with native builds (surfer-project.org) that reads the same VCD files.

Windows. The least painful route is WSL (Windows Subsystem for Linux): run wsl --install in an administrator terminal, reboot, open the Ubuntu app and use the apt line above. Native alternatives exist — an Icarus Verilog installer that bundles GTKWave, and Windows builds of GHDL on its GitHub releases page — but every command in this course is written for a Unix-style shell. The YosysHQ OSS CAD Suite is another option on all three systems: one download containing Icarus, GTKWave and many other open-source FPGA tools.

Our first DUT is a 4-bit counter with a synchronous reset rst and an enable en(Chapter 9). The extra output wrap is high during the cycle in which the counter is about to roll over from 15 to 0 — useful for chaining counters.

// Counter with synchronous reset and enable; wrap pulses on the last count
module counter #(
    parameter WIDTH = 4
) (
    input  wire             clk,
    input  wire             rst,
    input  wire             en,
    output reg  [WIDTH-1:0] count = 0,
    output wire             wrap
);
    assign wrap = en && (count == {WIDTH{1'b1}});

    always @(posedge clk) begin
        if (rst)
            count <= 0;
        else if (en)
            count <= count + 1'b1;
    end
endmodule

-- Counter with synchronous reset and enable; wrap pulses on the last count
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity counter is
    generic (WIDTH : positive := 4);
    port (
        clk   : in  std_logic;
        rst   : in  std_logic;
        en    : in  std_logic;
        count : out std_logic_vector(WIDTH-1 downto 0);
        wrap  : out std_logic
    );
end entity;

architecture rtl of counter is
    signal cnt : unsigned(WIDTH-1 downto 0) := (others => '0');
begin
    count <= std_logic_vector(cnt);
    wrap  <= '1' when en = '1' and cnt = 2**WIDTH - 1 else '0';

    process (clk)
    begin
        if rising_edge(clk) then
            if rst = '1' then
                cnt <= (others => '0');
            elsif en = '1' then
                cnt <= cnt + 1;
            end if;
        end if;
    end process;
end architecture;

The testbench below is the template you will reuse for every clocked design in this course. Read it with the numbered comments:

1. No ports. A testbench is the top of the simulation; nothing is outside it. In VHDL the entity is empty; in Verilog the module has no port list.
2. The DUT instance, with parameters/generics overridden if needed. Signals that the testbench drives are reg in Verilog (they are assigned inside initial/always); signals the DUT drives are wire.
3. The clock generator: a process that inverts clk every half period. With `timescale 1ns/1ps, #4 means 4 ns, so the period is 8 ns = 125 MHz like the PYNQ-Z2. In VHDL, clk <= not clk after 4 ns when not done; does the same, and stops when done becomes true so the simulation can end by itself (GHDL stops when no events are left).
4. A task / procedure that packages one step of the test (Section 5).
5. Reset: rst starts at 1 and is released after two clock edges.
6. Stimulus and checking, then a final verdict and $finish.

`timescale 1ns/1ps
module counter_tb;                       // 1. no ports: the testbench is the whole world
    reg        clk = 0, rst = 1, en = 0;
    wire [3:0] count;
    wire       wrap;
    integer    expected = 0, errors = 0, wraps = 0, i;

    counter #(.WIDTH(4)) dut (.clk(clk), .rst(rst), .en(en),   // 2. the DUT
                              .count(count), .wrap(wrap));

    always #4 clk = ~clk;                // 3. clock: 8 ns period (125 MHz)

    // 4. a task: wait one cycle, update the expected value, compare
    task step(input e);
        begin
            en = e;
            @(posedge clk);
            if (e) begin
                if (expected == 15) wraps = wraps + 1;
                expected = (expected + 1) % 16;
            end
            @(negedge clk);              // look half a period after the edge
            if (count !== expected) begin
                $display("ERROR at %0d ns: count=%0d expected=%0d", $time, count, expected);
                errors = errors + 1;
            end
        end
    endtask

    initial begin
        repeat (2) @(negedge clk);       // 5. reset for two cycles
        rst = 0;
        for (i = 0; i < 40; i = i + 1)   // 6. stimulus: enable 3 cycles out of 4
            step(i % 4 != 3);
        if (errors == 0) $display("PASS: 40 cycles checked, %0d wrap(s), %0d ns", wraps, $time);
        else             $display("FAIL: %0d error(s)", errors);
        $finish;
    end
endmodule

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

entity counter_tb is                     -- 1. no ports: the testbench is the whole world
end entity;

architecture sim of counter_tb is
    signal clk   : std_logic := '0';
    signal rst   : std_logic := '1';
    signal en    : std_logic := '0';
    signal count : std_logic_vector(3 downto 0);
    signal wrap  : std_logic;
    signal done  : boolean := false;
begin
    dut : entity work.counter            -- 2. the DUT
        generic map (WIDTH => 4)
        port map (clk => clk, rst => rst, en => en, count => count, wrap => wrap);

    clk <= not clk after 4 ns when not done;   -- 3. clock: 8 ns period (125 MHz)

    stimulus : process
        variable expected : natural := 0;
        variable errors   : natural := 0;
        variable wraps    : natural := 0;

        -- 4. a procedure: wait one cycle, update the expected value, compare
        procedure step(e : std_logic) is
        begin
            en <= e;
            wait until rising_edge(clk);
            if e = '1' then
                if expected = 15 then wraps := wraps + 1; end if;
                expected := (expected + 1) mod 16;
            end if;
            wait until falling_edge(clk);      -- look half a period after the edge
            if to_integer(unsigned(count)) /= expected then
                report "ERROR at " & to_string(now, ns) & ": count=" &
                       integer'image(to_integer(unsigned(count))) &
                       " expected=" & integer'image(expected) severity error;
                errors := errors + 1;
            end if;
        end procedure;
    begin
        for i in 1 to 2 loop                   -- 5. reset for two cycles
            wait until falling_edge(clk);
        end loop;
        rst <= '0';
        for i in 0 to 39 loop                  -- 6. stimulus: enable 3 cycles out of 4
            if i mod 4 /= 3 then step('1'); else step('0'); end if;
        end loop;
        if errors = 0 then
            report "PASS: 40 cycles checked, " & integer'image(wraps) & " wrap(s), " & to_string(now, ns);
        else
            report "FAIL: " & integer'image(errors) & " error(s)" severity failure;
        end if;
        done <= true;
        wait;
    end process;
end architecture;

$ iverilog -g2012 -o tb counter.v counter_tb.v && vvp -n tb
PASS: 40 cycles checked, 1 wrap(s), 336 ns
counter_tb.v:37: $finish called at 336000 (1ps)

$ ghdl -a --std=08 counter.vhd counter_tb.vhd
$ ghdl -e --std=08 counter_tb && ghdl -r --std=08 counter_tb
counter_tb.vhd:53:13:@336ns:(report note): PASS: 40 cycles checked, 1 wrap(s), 336 ns

The steps differ slightly: iverilog compiles all files into one executable that vvpruns (-n makes $stop behave like $finish, so it never waits for keyboard input). GHDL analyses each file into a library called work (-a),elaborates the top unit — builds the full hierarchy (-e) — then runs it (-r). Analyse files in dependency order: the DUT before the testbench that instantiates it.

A simulator keeps a current time and a queue of future events. #4 or wait for 4 nsmeans “suspend this process and resume 4 ns later”. Nothing else happens between events, which is why simulating a millisecond of a quiet circuit is quick.

In Verilog the unit of # is set by `timescale unit/precision. With `timescale 1ns/1ps, #4 is 4 ns and #0.25 is rounded to the nearest picosecond. The directive applies to every module compiled after it, so put it at the top of each testbench file. $time returns the time in the module's own unit (here ns), which is why counter_tb prints it with %0d; %t would print it in the global precision (ps). VHDL has a physical type time with real units: 4 ns, 2.5 us, and now is the current time.

Inside a single time step, the simulator can run many delta cycles: one signal update wakes another process, which updates another signal, and so on, all at the same simulated instant. This is how a chain of combinational logic settles in zero time. It is also the source of the most common testbench bug: a race between the testbench and the DUT at the clock edge.

Writing the same “set inputs, wait, compare” lines forty times is error-prone. A Verilog task or VHDL procedure is a named block of statements that may contain waits. In counter_tb, step(e) drives the enable, waits for a clock edge, updates the expected value exactly as the hardware should, and compares at the falling edge. The main sequence then reads like a description of the test.

Two language details matter. In Verilog, a task declared inside the testbench module can read and write the module's variables directly (expected, errors). In VHDL, a procedure declared inside a process can assign that process's variables and drive the signals the process drives (en) — which is why step lives in the declarative part of stimulus and not in the architecture.

A testbench that only prints values forces you to read them, every time, forever. A self-checking testbench computes the expected value itself, compares, counts mismatches, and prints one verdict line. It turns a test into something you can rerun after every edit in a second.

The expected value must come from an independent description of the behaviour. In counter_tb that is the integer expression (expected + 1) % 16 — written differently from the DUT's count + 1'b1 on a 4-bit register, so a misunderstanding in one is unlikely to be repeated in the other. To see that the check has teeth, change the DUT to add 2 instead of 1:

ERROR at 24 ns: count=2 expected=1
...
ERROR at 336 ns: count=12 expected=14
FAIL: 39 error(s)

Two comparison rules keep checks honest. Verilog signals have four values (0, 1, X unknown, Z high-impedance; Chapter 11). The ordinary == and != return X if either side contains X or Z, and if (X) silently takes the else branch. The case equalityoperators === and !== compare the four values literally and always return 0 or 1, so an unknown output is reported as an error instead of passing. In VHDL, = on std_logic_vector already compares element by element, so "XXXX" /= "0011" is true.

For scripts and continuous integration it also helps if a failing test returns a non-zero exit status. In Verilog, $fatal(1, "msg") stops the simulation and makes vvp exit with code 1. In VHDL, report ... severity failure stops GHDL with a non-zero exit code; severity error prints but continues, which is what you want while counting mismatches.

A combinational block has no memory: its outputs depend only on its present inputs. If it has\(n\) input bits, there are exactly

possible input patterns, and trying all of them proves the block correct — there is nothing left to go wrong. A 4-bit adder with carry in has \(n = 4 + 4 + 1 = 9\), so 512 tests, which simulate in a few milliseconds. The trick is to run one counter i from 0 to 511 and split its bits across the inputs: {cin, a, b} = i.

// 4-bit adder with carry in and carry out (purely combinational)
module adder4 (
    input  wire [3:0] a,
    input  wire [3:0] b,
    input  wire       cin,
    output wire [3:0] sum,
    output wire       cout
);
    assign {cout, sum} = a + b + cin;
endmodule

-- 4-bit adder with carry in and carry out (purely combinational)
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity adder4 is
    port (
        a    : in  std_logic_vector(3 downto 0);
        b    : in  std_logic_vector(3 downto 0);
        cin  : in  std_logic;
        sum  : out std_logic_vector(3 downto 0);
        cout : out std_logic
    );
end entity;

architecture rtl of adder4 is
    signal s5 : unsigned(4 downto 0);
begin
    s5   <= resize(unsigned(a), 5) + resize(unsigned(b), 5) + ("0000" & cin);
    sum  <= std_logic_vector(s5(3 downto 0));
    cout <= s5(4);
end architecture;

`timescale 1ns/1ps
module adder4_tb;
    reg  [3:0] a, b;
    reg        cin;
    wire [3:0] sum;
    wire       cout;
    integer    i, expected, errors = 0;

    adder4 dut (.a(a), .b(b), .cin(cin), .sum(sum), .cout(cout));

    initial begin
        // 9 input bits -> 512 combinations: try every one of them
        for (i = 0; i < 512; i = i + 1) begin
            {cin, a, b} = i;
            #1;                                   // let the combinational logic settle
            expected = a + b + cin;               // reference: integer arithmetic
            if ({cout, sum} !== expected) begin
                $display("ERROR: %0d + %0d + %0d gave %0d", a, b, cin, {cout, sum});
                errors = errors + 1;
            end
        end
        if (errors == 0) $display("PASS: all 512 input combinations correct");
        else             $display("FAIL: %0d of 512 wrong", errors);
        $finish;
    end
endmodule

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

entity adder4_tb is
end entity;

architecture sim of adder4_tb is
    signal a, b, sum : std_logic_vector(3 downto 0);
    signal cin, cout : std_logic;
begin
    dut : entity work.adder4
        port map (a => a, b => b, cin => cin, sum => sum, cout => cout);

    process
        variable v        : unsigned(8 downto 0);
        variable expected : natural;
        variable errors   : natural := 0;
    begin
        -- 9 input bits -> 512 combinations: try every one of them
        for i in 0 to 511 loop
            v   := to_unsigned(i, 9);
            cin <= v(8);
            a   <= std_logic_vector(v(7 downto 4));
            b   <= std_logic_vector(v(3 downto 0));
            wait for 1 ns;                        -- let the combinational logic settle
            expected := to_integer(unsigned(a)) + to_integer(unsigned(b))
                      + to_integer(v(8 downto 8));
            if to_integer(unsigned(cout & sum)) /= expected then
                report "ERROR: " & to_string(i) & " gave " &
                       to_string(to_integer(unsigned(cout & sum))) severity error;
                errors := errors + 1;
            end if;
        end loop;
        if errors = 0 then
            report "PASS: all 512 input combinations correct";
        else
            report "FAIL: " & to_string(errors) & " of 512 wrong" severity failure;
        end if;
        wait;
    end process;
end architecture;

PASS: all 512 input combinations correct            (Icarus, at 512 ns)
adder4_tb.vhd:36:13:@512ns:(report note): PASS: all 512 input combinations correct

Notice the #1 / wait for 1 ns after applying each input. Combinational logic in a simulator settles in delta cycles at the same time step, but the testbench process must suspend for the simulator to propagate the new values; reading sum without waiting would see the result for the previous inputs.

Exhaustive testing stops being practical around 30 input bits (\(2^{30} \approx 10^9\)). Two 32-bit operands give \(2^{64}\) combinations — thousands of years. Larger blocks are tested with chosen corner cases (zero, one, maximum, minimum, sign boundaries) plus many random vectors, checked against a reference model. That is the next section.

For anything with real arithmetic, the cleanest expected values come from a reference model: a short program in a high-level language that says what the block computes, without any hardware detail. Python is ideal. The model writes test vectors and expected results into a text file; the HDL testbench reads the file, drives the DUT and compares. The two sides share nothing but the file format.

Our DUT is a saturating adder: it adds two signed 8-bit numbers (range −128 to 127), but instead of wrapping around on overflow — 100 + 100 would give −56 in plain 8-bit arithmetic — it clamps the result to the nearest representable value and raises ovf. Audio and image processing use this constantly, because a loud sample that clips sounds far better than one that flips sign.

// Signed 8-bit adder that saturates instead of wrapping around
module sat_add8 (
    input  wire signed [7:0] a,
    input  wire signed [7:0] b,
    output wire signed [7:0] y,
    output wire              ovf     // 1 when the true sum did not fit
);
    wire signed [8:0] s = a + b;     // one extra bit: never overflows

    assign ovf = (s > 9'sd127) || (s < -9'sd128);
    assign y   = (s > 9'sd127)  ? 8'sd127 :
                 (s < -9'sd128) ? -8'sd128 : s[7:0];
endmodule

-- Signed 8-bit adder that saturates instead of wrapping around
library ieee;
use ieee.std_logic_1164.all;
use ieee.numeric_std.all;

entity sat_add8 is
    port (
        a   : in  std_logic_vector(7 downto 0);
        b   : in  std_logic_vector(7 downto 0);
        y   : out std_logic_vector(7 downto 0);
        ovf : out std_logic                 -- 1 when the true sum did not fit
    );
end entity;

architecture rtl of sat_add8 is
    signal s : signed(8 downto 0);          -- one extra bit: never overflows
begin
    s   <= resize(signed(a), 9) + resize(signed(b), 9);

    ovf <= '1' when s > 127 or s < -128 else '0';
    y   <= std_logic_vector(to_signed(127, 8))  when s > 127  else
           std_logic_vector(to_signed(-128, 8)) when s < -128 else
           std_logic_vector(s(7 downto 0));
end architecture;

The Python side generates 81 corner-case pairs (every combination of nine dangerous values) and 175 random pairs, computes the expected outputs with ordinary Python integers, and writes one line per test: four bytes in hex — a, b, expected y, expected ovf. Run it to see the vectors and the picture of what the DUT must do:

80808001      a = -128, b = -128 -> y = -128 (0x80), ovf = 1
80818001      a = -128, b = -127 -> y = -128, ovf = 1
80c08001      a = -128, b =  -64 -> y = -128, ovf = 1
80ff8001      a = -128, b =   -1 -> y = -128, ovf = 1
...

On the HDL side, Verilog's $readmemh loads a whole hex file into a memory array in one call; each line becomes one 32-bit word, and a concatenation on the left of = splits it into fields. VHDL reads text files with the std.textio package: readline gets one line, hread parses hex digits into a std_logic_vector (in VHDL-2008 it lives in std_logic_1164 itself).

`timescale 1ns/1ps
module sat_add8_tb;
    localparam N = 256;
    reg  [31:0] vec [0:N-1];          // memory filled from the file
    reg  signed [7:0] a, b;
    wire signed [7:0] y;
    wire        ovf;
    reg  signed [7:0] y_exp;
    reg         ovf_exp;
    integer     i, errors = 0;

    sat_add8 dut (.a(a), .b(b), .y(y), .ovf(ovf));

    initial begin
        $readmemh("vectors.hex", vec);   // one 32-bit hex word per line
        for (i = 0; i < N; i = i + 1) begin
            {a, b, y_exp} = vec[i][31:8];
            ovf_exp       = vec[i][0];
            #1;
            if (y !== y_exp || ovf !== ovf_exp) begin
                $display("ERROR vector %0d: %0d + %0d -> y=%0d ovf=%b, expected %0d %b",
                         i, a, b, y, ovf, y_exp, ovf_exp);
                errors = errors + 1;
            end
        end
        if (errors == 0) $display("PASS: %0d vectors from vectors.hex match the Python model", N);
        else             $display("FAIL: %0d mismatches", errors);
        $finish;
    end
endmodule

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

entity sat_add8_tb is
end entity;

architecture sim of sat_add8_tb is
    signal a, b    : std_logic_vector(7 downto 0) := (others => '0');
    signal y       : std_logic_vector(7 downto 0);
    signal ovf     : std_logic;
begin
    dut : entity work.sat_add8 port map (a => a, b => b, y => y, ovf => ovf);

    process
        file     f       : text open read_mode is "vectors.hex";
        variable l       : line;
        variable word    : std_logic_vector(31 downto 0);
        variable n       : natural := 0;
        variable errors  : natural := 0;
    begin
        while not endfile(f) loop
            readline(f, l);                 -- one line of text
            hread(l, word);                 -- parse 8 hex digits (VHDL-2008)
            a <= word(31 downto 24);
            b <= word(23 downto 16);
            wait for 1 ns;
            if y /= word(15 downto 8) or ovf /= word(0) then
                report "ERROR vector " & to_string(n) & ": " &
                       to_string(to_integer(signed(a))) & " + " &
                       to_string(to_integer(signed(b))) & " -> y=" &
                       to_string(to_integer(signed(y))) severity error;
                errors := errors + 1;
            end if;
            n := n + 1;
        end loop;
        if errors = 0 then
            report "PASS: " & to_string(n) & " vectors from vectors.hex match the Python model";
        else
            report "FAIL: " & to_string(errors) & " mismatches" severity failure;
        end if;
        wait;
    end process;
end architecture;

$ python3 gen_vectors.py
wrote 256 vectors to vectors.hex
$ iverilog -g2012 -o tb sat_add8.v sat_add8_tb.v && vvp -n tb
PASS: 256 vectors from vectors.hex match the Python model
$ ghdl -a --std=08 sat_add8.vhd sat_add8_tb.vhd && ghdl -e --std=08 sat_add8_tb
$ ghdl -r --std=08 sat_add8_tb --ieee-asserts=disable-at-0
sat_add8_tb.vhd:39:13:@256ns:(report note): PASS: 256 vectors from vectors.hex match the Python model

Without --ieee-asserts=disable-at-0, GHDL prints a few warnings “NUMERIC_STD.">": metavalue detected” at time 0. They are harmless: before the first delta cycle the internal sum s is still 'U' (uninitialised), and the comparison functions warn about it. The option silences such warnings at time 0 only, so real ones later are still shown.

To prove the check works, make the Verilog DUT wrap on positive overflow instead of saturating: the testbench reports FAIL: 27 mismatches — exactly the random and corner vectors whose sum exceeds 127.

A passing test tells you only that the cases you tried work. When a test fails, the next step is to look inside: Chapter 11 dumps every signal to a waveform file and walks through the bugs you will meet most often. Chapter 12 then uses these testbenches on finite state machines.