Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Testbenches

Your First Testbench

Learn what a Verilog testbench is, how it instantiates a design under test, drives inputs with initial blocks and delays, and why it has no ports or synthesis.

A testbench is a Verilog module whose job is to exercise another module and show you whether it behaves correctly. Hardware cannot be debugged by "running it and seeing" the way software can, so before any design reaches an FPGA or a chip you simulate it: a simulator executes your Verilog on a computer, and the testbench supplies the inputs and watches the outputs.

In this lesson you will build the smallest useful testbench, see why it has no ports, learn the three pieces every testbench has (a device under test, stimulus, and observation), and meet the simulation time model that makes #10 mean something. The following lessons add system tasks, self-checking, clocks and files.

Verilog simulators (Icarus Verilog, Verilator, ModelSim, VCS, Questa, Vivado xsim) are not available on this site. The Verilog code below is read-only. The runnable C programs are stand-ins that model the same idea: a function plays the DUT and a main plays the testbench.

The shape of a testbench

A design under test (DUT) here is a 4-bit adder with a carry out:

VERILOG
module adder4 (
  input  [3:0] a, b,
  input        cin,
  output [3:0] sum,
  output       cout
);
  assign {cout, sum} = a + b + cin;
endmodule

The testbench is another module, but it has no ports: nothing outside it drives or reads it. Inside, it declares a reg for every DUT input (a testbench drives them from procedural code) and a wire for every DUT output (the DUT drives them):

VERILOG
module adder4_tb;
  reg  [3:0] a, b;
  reg        cin;
  wire [3:0] sum;
  wire       cout;

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

  initial begin
    a = 4'd3;  b = 4'd4;  cin = 1'b0;
    #10;
    a = 4'd9;  b = 4'd9;  cin = 1'b1;
    #10;
    a = 4'd15; b = 4'd1;  cin = 1'b0;
    #10;
    $finish;
  end
endmodule

Notice the connection style .a(a): named port connection. It is longer than positional connection but it cannot silently swap two ports, so use it for every instance you write. Instance names (dut) are free; calling it dut makes testbenches easy to read.

The three parts

Every testbench, from this 15-line one to a UVM environment with thousands of lines, has the same three jobs:

  1. Instantiate the design under test and wire it up.
  2. Stimulate: drive inputs over time.
  3. Observe: print, check or record outputs.
flowchart LR
  S["Stimulus<br/>(initial blocks)"] --> D["DUT<br/>(adder4)"]
  D --> O["Observation<br/>(display, checks, waves)"]
  C["Clock and reset"] --> D

The testbench surrounds the DUT: it drives its inputs and watches its outputs.

initial blocks and simulation time

An initial block starts at time 0 and runs once, top to bottom. Simulation time advances only when a statement waits, and #10 means "wait 10 time units". What a "unit" is comes from the timescale directive:

VERILOG
`timescale 1ns / 1ps

The first number is the time unit used by # delays (here 1 ns), the second is the precision to which the simulator rounds delays (1 ps). Without a timescale, tools pick their own default, which is a classic source of "it behaves differently on your machine" bugs, so put one at the top of every testbench file.

Delays like #10 are for testbenches only. Real hardware has no "wait 10 ns" statement, and synthesis tools ignore delays or reject them. Never rely on a # delay inside a design module.

Running the idea in C

A simulator is, at heart, a loop that advances time and updates values. The C program below models the testbench above: adder4 is a function that returns the same results as the Verilog, and main applies the three input patterns with a printed time stamp. This is not Verilog and not an event-driven simulator; it only shows the stimulus-and-observe flow.

C Stand-in: a function as DUT, main as testbench

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.

The three lines show 3 + 4 = 7 with no carry, 9 + 9 + 1 = 19, which is 4'b0011 with a carry out of 1, and 15 + 1 = 16, which wraps to 0 with a carry. A Verilog simulator would print the same numbers: the 4-bit width of sum is what truncates the result.

Why testbench variables are reg

In Verilog, a reg can be assigned inside initial and always blocks, a wire can only be driven by assign or by an output port. Since the testbench drives DUT inputs from an initial block, those signals must be reg. The DUT outputs are driven by the DUT, so the testbench sees them as wire. (SystemVerilog's logic removes this split, see SystemVerilog data types.)

Time zero and race conditions

At time 0 every initial and always block becomes ready at once, and the simulator picks any order. If one block reads a signal that another block writes at time 0, the result depends on that order. Two habits avoid trouble:

  • Give inputs an explicit initial value at time 0, and wait a little before the first check.
  • Change testbench inputs away from clock edges (or with the techniques in clocks, memories and files).

A second stand-in: advancing time

Event-driven simulators keep a list of future events ordered by time. The second program is a miniature of that: events carry a time and an action, and the loop always runs the earliest one. The delays in the Verilog initial block create exactly such a list.

C Stand-in: a tiny time-ordered event queue

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 the continue when the next event has the same time: both a and b change at time 10 and the sum is evaluated only after the whole time step. Real simulators do this with a precise set of regions per time step; stimulus and system tasks shows where $display and $monitor fit in.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does a testbench module usually have no ports?

    The testbench is the top of the simulation hierarchy. It creates the signals itself and connects them to the DUT.
  2. 2. In a classic Verilog testbench, what type are the signals that drive DUT inputs from an initial block?

    Procedural assignments in initial and always blocks can only target variables such as reg. DUT outputs are wires.
  3. 3. What does #10; do inside an initial block?

    # is a simulation delay. It advances time by the given number of timescale units and has no hardware meaning.
  4. 4. What does the timescale 1ns / 1ps directive mean?

    The first value is the time unit for # delays, the second is the simulator's rounding precision.

Summary

  • A testbench is a port-less top module that instantiates the DUT, drives inputs and observes outputs.
  • Testbench inputs are reg, DUT outputs are wire (until you use SystemVerilog logic).
  • initial runs once at time 0; #n advances simulation time and is testbench-only.
  • Put a timescale in every file and connect ports by name.
  • The C stand-ins model the flow (stimulus, DUT, observation, ordered events), not a real simulator.

Next: Stimulus and System Tasks