Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Testbenches

Procedures, Test Vectors and Debugging

Structure big VHDL testbenches with procedures, read test vectors from files with textio, debug simulation with waveforms and fix the usual X and U problems.

Once a testbench grows beyond a few dozen lines, repeating the same three statements for every test case becomes painful and error-prone. This lesson shows how to keep a bench readable with procedures, how to read test data from a file, and how to debug a failing simulation. VHDL code is read-only on this site; C programs model the ideas and run.

Procedures in a testbench

A procedure bundles a sequence of actions, and in a testbench it may contain wait statements. A typical helper performs one bus write:

VHDL
procedure write_reg (
  constant addr : in  natural;
  constant data : in  std_logic_vector(7 downto 0);
  signal   clk  : in  std_logic;
  signal   we   : out std_logic;
  signal   a    : out natural range 0 to 15;
  signal   d    : out std_logic_vector(7 downto 0)) is
begin
  wait until rising_edge(clk);
  a <= addr; d <= data; we <= '1';
  wait until rising_edge(clk);
  we <= '0';
end procedure;

Calling it is one line: write_reg(3, x"5A", clk, we, a, d);. Notes:

  • Signals passed to a procedure must be declared signal in the parameter list so the procedure drives the real signal.
  • Declare the procedure in the process declarative part, in the architecture or in a package, so several tests can share it.
  • A function cannot contain wait and cannot drive signals, so use procedures for bus actions and functions for pure calculations (for example computing an expected CRC).

Reading test vectors from a file

Hard-coded tables become unwieldy with thousands of cases. The std.textio package lets a testbench read a text file line by line. Suppose vectors.txt contains a b expected_sum, one test per line, in hexadecimal.

VHDL
use std.textio.all;
use ieee.std_logic_textio.all;   -- for hread on std_logic_vector (VHDL-93/2002)

file_proc : process
  file f : text open read_mode is "vectors.txt";
  variable l : line;
  variable a, b, s : std_logic_vector(7 downto 0);
  variable ok : boolean;
begin
  while not endfile(f) loop
    readline(f, l);
    hread(l, a); hread(l, b); hread(l, s);
    a_in <= a; b_in <= b;
    wait for 10 ns;
    assert sum_out = s
      report "mismatch for " & to_hstring(a) & "+" & to_hstring(b)
      severity error;
  end loop;
  wait;
end process;

In VHDL-2008 hread is built into std.textio; to_hstring is also standard there. Real simulators run in a folder that holds the data file, and the path is relative to the working directory, a common reason for a "file not found" failure.

A file-based flow is powerful: a script (Python, for instance) can generate the vectors and expected results from a golden model, and the same file can test the VHDL design and a software implementation.

A C model of a vector-driven bench

The program below embeds the vector text as a string, parses it line by line (as readline/hread do), checks an 8-bit adder with carry-out, and reports the failing line numbers.

C C stand-in: reading vectors from text like textio

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Debugging a failing simulation

1. Look at the waveform

Start from the first signal that is wrong in time, not the last. Trace it backward through the design: why is this register wrong at this edge? Which of its inputs was wrong one cycle earlier?

2. Understand the nine-value logic

std_logic has more values than '0' and '1'. The ones you see in debugging:

Value Meaning Typical cause
'U' uninitialized no reset, no initial value
'X' forcing unknown two drivers conflict, or an X propagated
'Z' high impedance tri-state output not driven
'W', 'L', 'H' weak values pull-ups and pull-downs
'-' don't care used in synthesis tables

A 'U' that spreads through logic usually traces to a missing reset or a missing initial value. An 'X' often means two processes drive the same signal.

3. Print what you need

VHDL
report "state=" & state_t'image(state) & " cnt=" & integer'image(to_integer(cnt));

'image works on enumeration, integer and std_logic types.

4. Common bugs and their symptoms

Symptom Likely cause
Output stays 'U' forever Reset never applied or reset asserted too short
Output stuck at a value Process sensitivity list missing a signal
Output one cycle late/early Check made at the edge instead of after it
'X' in the waveform Multiple drivers on one signal
Simulation never stops Free-running clock without done, or no final wait;
Works in simulation, fails on the FPGA Latch, unsynchronized input or timing violation (see chapter 7)

A C model of X-propagation

Unknown values are one of the main reasons to simulate before you program hardware. This small program models three-valued logic (0, 1, X) and shows an AND gate that resolves an unknown input to a known result when the other input is 0.

C C stand-in: three-valued logic and X propagation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Notice 0 AND X = 0: a known value can absorb an unknown. That is why an X may disappear in simulation on one path and then persist on another.

Good habits that save hours

  • One test, one purpose: name each test case and print its name before it runs.
  • Keep stimulus and checking separate (separate processes).
  • Make the bench self-contained: it ends with PASS/FAIL, with no manual waveform inspection.
  • Use a regression script that compiles, runs all benches and greps for "FAILED".
  • Dump waveforms only when debugging: they are big and slow.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can a procedure contain wait statements while a function cannot?

    A function computes and returns a value in zero time; a procedure may consume time with wait.
  2. 2. A signal is 'U' in the waveform for the whole run. What is the most likely reason?

    U means uninitialized: nothing has driven the signal yet.
  3. 3. Which VHDL package reads text lines from a file?

    std.textio provides text files, line variables, readline and read/write routines.
  4. 4. What typically produces an 'X' in a std_logic waveform?

    The resolution function of std_logic gives 'X' when drivers conflict.

Summary

  • Use procedures (with signal parameters) for repeated bus actions; functions for pure calculations.
  • Drive large test sets from files with std.textio; generate the vectors from a golden model.
  • Debug backward from the first wrong signal; learn the meaning of U, X and Z.
  • Keep benches self-checking, short and named, and run them from a script.
  • C stand-ins can validate vectors and logic ideas before you touch a simulator.

Next: What Synthesis Does