Verification · Lesson 9 of 14

Self-checking testbenches in SystemVerilog

Write self-checking SystemVerilog testbenches: clock and reset, tasks, reference models, random stimulus, waveforms and assertions, run in Icarus and Verilator.

beginner50 minUpdated Free

What you will learn

  • Build a testbench with clock generation, reset, stimulus and an automatic checker
  • Compare a design against a reference model every cycle and report PASS or FAIL
  • Use tasks, a fixed random seed and plusargs to make tests short and repeatable
  • Dump waveforms and open them in GTKWave or Surfer
  • Write immediate and simple concurrent assertions and know which simulators support them

Before you start

  • Verilog and SystemVerilog for synthesis (lesson 4)
  • Sequential logic (lesson 7)

After this lesson you can write a testbench that drives a design, compares every output against a reference model, and ends with a clear PASS or FAIL. You will run it in Icarus Verilog and Verilator, look at the waveforms, and add assertions.

Why simulate before you build

A bug found in simulation costs a few seconds per iteration. You change the code, rerun, and see every signal at every time step. The same bug found on the board costs a full synthesis and implementation run per attempt, and you can only see the signals you routed to pins or to an on-chip logic analyser (lesson 14 on implementation and debug covers those tools).

Simulation also lets you test cases that are hard to create on hardware: a carry out of the top bit, a reset in the middle of an operation, a framing error on a serial line. When a design that passes a good testbench fails on the board, look first at what the testbench does not cover: constraints, pin assignments and clocks.

The goal is a self-checking testbench. Looking at waveforms by eye is fine while you write the design, but it does not scale and it cannot be rerun after every change. A self-checking testbench decides on its own whether the design is correct, so you can run it in seconds, as often as you like.

Anatomy of a testbench

A testbench is a SystemVerilog module with no ports. It contains the design under test (DUT) and everything needed to exercise it.

Block diagram inside a dashed box labelled module tb_accum8. A clock and reset block feeds clk and rst to the DUT, accum8. A stimulus block, labelled directed cases then random with a fixed seed, sends clr, en and din to the DUT and the same inputs to a reference model. The DUT outputs acc and carry and the reference model's expected values both go to a checker that compares each cycle and counts mismatches. The checker feeds a PASS or FAIL block that ends the simulation with finish or fatal.
Structure of a self-checking testbench. Stimulus drives the design and a reference model with the same inputs, and a checker compares their outputs every cycle.

The parts are:

  • Clock and reset generation.
  • Stimulus: directed cases you choose by hand, then random cases.
  • Reference model: an independent description of what the DUT should do, written for clarity rather than for synthesis.
  • Checker: compares DUT outputs with the model and counts mismatches.
  • Report: prints PASS or FAIL and ends the simulation with a status a script can test.

The worked example in this lesson is a small 8-bit accumulator. The same structure scales to much larger designs; only the model and the stimulus grow.

The design under test

module accum8 (
    input  logic       clk,
    input  logic       rst,     // synchronous, active high
    input  logic       clr,     // synchronous clear
    input  logic       en,      // add din this cycle
    input  logic [7:0] din,
    output logic [7:0] acc,
    output logic       carry    // carry-out of the most recent addition
);

    always_ff @(posedge clk) begin
        if (rst || clr) begin
            acc   <= 8'd0;
            carry <= 1'b0;
        end else if (en) begin
            {carry, acc} <= {1'b0, acc} + {1'b0, din};
        end
    end

endmodule

On each rising edge the accumulator clears if rst or clr is high, adds din if en is high, and otherwise holds. clr has priority over en. That priority rule is exactly the sort of detail a testbench should check explicitly.

Download accum8.sv

Time units, clock and reset

Timescale

`timescale 1ns / 1ps

The first number is the time unit for delays in this file, so #5 means 5 ns. The second is the precision: the smallest step the simulator resolves. Put the same `timescale line at the top of every file, including the RTL. If some files have one and others do not, Icarus Verilog with -Wall warns that the timescale is inherited from another file, and the delay units then depend on the order of the files on the command line.

Clock

initial begin
    clk = 1'b0;
    forever #5 clk = ~clk;     // 10 ns period, 100 MHz
end

The clock toggles every half period. Initialise it in the same initial block. A clock that starts as x produces no clean edge until it has toggled once.

Reset

Put reset in a task, so the test sequence reads like a list of steps:

task automatic do_reset();
    rst = 1'b1;
    clr = 1'b0;
    en  = 1'b0;
    din = 8'h00;
    repeat (2) @(negedge clk);
    rst = 1'b0;
    model_acc   = 8'h00;
    model_carry = 1'b0;
    if (acc !== 8'h00 || carry !== 1'b0)
        $fatal(1, "reset failed: acc=%h carry=%b", acc, carry);
endtask

The task also resets the reference model and checks the DUT. If reset does not work, nothing after it is meaningful, so $fatal stops the run straight away.

automatic gives each call of the task its own copy of its local variables. Without it, tasks are static: all calls share one copy, which breaks as soon as two processes call the task at once. Make every testbench task automatic unless you have a reason not to.

Driving inputs without races

At a rising clock edge, the DUT’s always_ff blocks and the testbench’s processes all wake up in the same time step. If the testbench changes din with a blocking assignment at that moment, whether the DUT sees the old or the new value depends on the order in which the simulator happens to run the processes. Different simulators, or the same simulator after a small code change, can give different results.

The simplest rule is to change inputs away from the active edge. This testbench drives inputs on the falling edge, half a cycle before the next rising edge, and checks outputs on the following falling edge:

// One clock cycle: drive inputs on the falling edge, let the DUT
// and the model react to the rising edge, check on the next falling edge.
task automatic step(input logic c, input logic e, input logic [7:0] d);
    clr = c;
    en  = e;
    din = d;
    @(posedge clk);
    if (c)
        {model_carry, model_acc} = 9'h000;
    else if (e)
        {model_carry, model_acc} = {1'b0, model_acc} + {1'b0, d};
    @(negedge clk);
    check_outputs();
endtask

The other common approach is to drive inputs right after the rising edge with non-blocking assignments (din <= d;). SystemVerilog clocking blocks formalise this, but simulator support for them varies, so this lesson sticks to the falling-edge style.

The reference model and the checker

The reference model is the two if lines in step. It updates model_acc and model_carry at the same rising edge as the DUT, using the same inputs. Here the model looks a lot like the RTL, because the design is tiny. For bigger designs the model is usually written at a higher level: a queue instead of a FIFO’s pointer logic, a multiplication operator instead of a pipelined multiplier, a shift register instead of a sequence-detecting FSM.

Write the model from the specification, not by copying the RTL. If you copy the RTL, a misunderstanding of the specification ends up in both and the test passes.

The checker is another task:

task automatic check_outputs();
    checks++;
    assert (acc === model_acc && carry === model_carry)
    else begin
        errors++;
        $error("t=%0t: acc=%h carry=%b, expected acc=%h carry=%b",
               $time, acc, carry, model_acc, model_carry);
    end
endtask

Two details matter.

Use === and !==. The ordinary operators == and != return x if either side contains an x or z bit. An if with an x condition takes the else branch. So if (acc != model_acc) errors++; silently passes when acc is all x, which is exactly the state of a register someone forgot to reset. The case-equality operators compare x and z literally and always return 0 or 1.

Print enough to debug. The message includes the simulation time, the actual values and the expected values. With the time you can jump straight to the failure in the waveform viewer.

The assert ... else form is an immediate assertion: a procedural check that is evaluated when execution reaches it, like an if. It works in both Icarus Verilog and Verilator.

Reporting results

SystemVerilog has four severity tasks, all of which print the file, line and a message: $info, $warning, $error and $fatal. $display prints without a severity. $finish ends the simulation. $fatal ends it with an error.

Simulators differ in what $error does. Measured with the versions used for this course:

Icarus Verilog 13Verilator 5.054
$errorPrints, keeps runningPrints, then stops the simulation with exit status 1
$fatal(1, ...)Prints, exit status 1Prints, exit status 1
$finishExit status 0Exit status 0

Verilator’s stop-on-first-error is controlled by the runtime option +verilator+error+limit+<n>, which lets it continue up to n errors.

Because of these differences, end every test the same way: count errors yourself, print a one-line summary and call $fatal on failure. Then a script, a Makefile or a CI job can rely on the exit status in either simulator.

if (errors == 0) begin
    $display("PASS: %0d checks, seed %0d", checks, seed0);
    $finish;
end else begin
    $fatal(1, "FAIL: %0d errors in %0d checks, seed %0d", errors, checks, seed0);
end

Add a watchdog as well. A testbench that waits for a signal that never comes otherwise runs forever:

initial begin
    #1ms;
    $fatal(1, "timeout");
end

Directed and random stimulus

Directed cases test what you know is risky. For an accumulator that means a carry out of bit 7, a sum of exactly 256, holding while en is low, and clr and en asserted together:

step(1'b0, 1'b1, 8'h01);   // 0 + 1
step(1'b0, 1'b1, 8'h01);   // 1 + 1
step(1'b0, 1'b0, 8'h55);   // en low: hold, din ignored
step(1'b0, 1'b1, 8'hFE);   // 2 + FE = 100: carry out, acc = 00
step(1'b0, 1'b1, 8'h80);
step(1'b0, 1'b1, 8'h80);   // 80 + 80 = 100
step(1'b0, 1'b1, 8'hFF);   // carry clears on the next add
step(1'b1, 1'b1, 8'h12);   // clr wins over en

Random cases find what you did not think of. Shape the distribution so that interesting events happen often but not all the time. Here en is high three cycles in four and clr about one cycle in 32, so the accumulator gets long enough runs to overflow:

repeat (5000) begin
    step(($random(seed) & 31) == 0,
         ($random(seed) & 3) != 0,
         8'($random(seed)));
end

Fixed seeds

$random(seed) takes an integer variable, returns a 32-bit pseudo-random value and updates the variable. The same starting seed gives the same sequence on the same simulator, so a failing run can be repeated exactly. The testbench reads the seed from the command line with a plusarg and prints it in the summary:

if (!$value$plusargs("seed=%d", seed0)) seed0 = 1;
seed = seed0;
vvp sim +seed=42

Do not expect the same sequence across simulators. The sequence detector testbench in lesson 8 sees 138 pattern matches in Icarus Verilog and 135 in Verilator from the same seed. The fix is to record the simulator together with the seed when you log a failure.

SystemVerilog also has $urandom, $urandom_range and class-based constrained randomisation with randomize(). Icarus Verilog and Verilator support the system functions. Full constrained-random testing needs a simulator with complete class and constraint support; that is the territory of UVM, mentioned at the end of this lesson.

Waveforms

A failing check tells you that something is wrong. The waveform shows why. Ask the simulator to write a value change dump (VCD):

if ($test$plusargs("dump")) begin
    $dumpfile("tb_accum8.vcd");
    $dumpvars(0, tb_accum8);    // 0 = this module and everything below it
end

Controlling the dump with the +dump plusarg keeps normal runs fast and the disk clean. A run of this testbench with +dump writes a VCD of about 630 kB.

Two free viewers open these files:

  • GTKWave reads VCD, FST, LXT, LXT2, VZT and GHW files.
  • Surfer is a newer viewer with a native application and a web version at app.surfer-project.org.

Icarus Verilog can write FST, a compressed format, instead of VCD: run vvp sim -fst +dump (the -fst flag goes after the file name, like a plusarg). The Icarus documentation recommends FST when you use GTKWave or Surfer. For this testbench the file shrinks from about 630 kB to 54 kB. It keeps the name given to $dumpfile, so rename it to .fst if your viewer goes by the extension. In Verilator, $dumpvars is ignored unless you build with --trace (VCD) or --trace-fst (FST).

Open the file and add clk, en, din, acc, carry, model_acc and model_carry from the tb_accum8 scope. Putting the model signals next to the DUT outputs makes a mismatch obvious.

Assertions

The immediate assertion in check_outputs checks a condition at one moment. Concurrent assertions, part of SystemVerilog Assertions (SVA), check behaviour over clock cycles. They run on their own, alongside the rest of the testbench, at every clock edge.

// The cycle after clr, both outputs are zero.
a_clr: assert property (@(posedge clk) disable iff (rst)
                        clr |=> (acc == 8'h00 && !carry))
       else $error("acc not cleared after clr");

// With clr and en both low, the accumulator holds its value.
a_hold: assert property (@(posedge clk) disable iff (rst)
                         (!clr && !en) |=> $stable(acc))
        else $error("acc changed while en was low");

Read a |=> b as “if a holds at a clock edge, b must hold at the next one”. |-> checks b at the same edge. disable iff (rst) switches the check off during reset. $stable(acc) is true when acc has the same value as at the previous edge.

These properties state rules without a reference model, and they can sit in the RTL file next to the code they describe. Formal verification tools can also try to prove them for all possible input sequences, which simulation cannot do.

Tool support is the catch. Icarus Verilog 13 accepts immediate assertions but stops with a syntax error on both of the properties above. Verilator 5.054 runs them. The testbench therefore wraps them in a guard, using the macro that Icarus defines:

`ifndef __ICARUS__
    a_clr:  assert property (...);
    a_hold: assert property (...);
`endif

Verilator versions before 5.038 needed the --assert flag to enable assertions; newer versions enable them by default. Check the version you have with verilator --version.

Running the testbench

The complete testbench:

Download tb_accum8.sv

Icarus Verilog

iverilog -g2012 -Wall -o sim tb_accum8.sv accum8.sv
vvp sim

-g2012 selects IEEE 1800-2012 SystemVerilog, and -Wall enables almost all warnings. Expected output:

PASS: 5008 checks, seed 1
tb_accum8.sv:138: $finish called at 50110000 (1ps)

Verilator

Verilator compiles the design and testbench to a C++ program, then you run that program:

verilator --binary -j 0 --top tb_accum8 tb_accum8.sv accum8.sv
./obj_dir/Vtb_accum8

--binary is shorthand for --main --exe --build --timing: it generates a main(), builds the executable and enables the timing support that testbench delays such as #5 and @(negedge clk) need. -j 0 builds with all CPU cores. Expected output:

PASS: 5008 checks, seed 1
- tb_accum8.sv:138: Verilog $finish

followed by a short simulation report. Run verilator --lint-only -Wall tb_accum8.sv accum8.sv as well. Verilator’s lint is stricter than Icarus and catches width mismatches and unused signals in both RTL and testbench code.

Check that the testbench can fail

A testbench that has never failed has not been tested. Break the DUT on purpose: for example, swap the priority so that en wins over clr. Both simulators should then report FAIL. Icarus prints a mismatch for most random cycles, because the accumulator drifts away from the model. Verilator stops at the first mismatch, on the directed clr and en case. Undo the change afterwards.

Next steps: cocotb and UVM

Two widely used frameworks take these ideas further.

cocotb lets you write the testbench in Python. The DUT stays in Verilog, SystemVerilog or VHDL, and a simulator runs it while Python code drives and checks the signals. You can use Python libraries for reference models, for example a protocol decoder or NumPy for DSP. The cocotb documentation lists Icarus Verilog (11.0 and later) and Verilator (5.036 and later) among the supported simulators.

UVM, the Universal Verification Methodology, is a SystemVerilog class library standardised by IEEE. It defines reusable components (drivers, monitors, scoreboards, sequences) and is widely used for verifying large ASIC and FPGA designs. It relies on classes and constrained randomisation, so it needs a simulator with full support for both. Check your simulator’s documentation before you start.

The structure in this lesson (stimulus, DUT, reference model, checker) is the core of both.

Exercise

Test a reset in the middle of operation

The testbench only resets the accumulator at the start. Add a task mid_reset() that raises rst for one cycle while en is high and din is 8'hFF, updates the model and checks the outputs. Call it a few times during the random phase.

Show solution
// Pulse rst for one cycle while en is high, then check the outputs.
task automatic mid_reset();
    rst = 1'b1;
    clr = 1'b0;
    en  = 1'b1;
    din = 8'hFF;
    @(posedge clk);
    model_acc   = 8'h00;
    model_carry = 1'b0;
    @(negedge clk);
    rst = 1'b0;
    check_outputs();
endtask

Call it from the random loop, for example every 1000 checks:

repeat (5000) begin
    if (checks % 1000 == 500) mid_reset();
    step(($random(seed) & 31) == 0,
         ($random(seed) & 3) != 0,
         8'($random(seed)));
end

The modified testbench passes with 5013 checks in Icarus Verilog and passes Verilator lint. The task follows the same pattern as step: drive on the falling edge, update the model at the rising edge, check on the next falling edge.

Exercise

Find the bug in the checker

A colleague’s testbench for a counter uses this checker. The counter’s reset was accidentally removed from the RTL, so its output is x for the whole simulation. The testbench still prints PASS. Why, and what is the fix?

always @(negedge clk) begin
    if (count != expected) begin
        $display("mismatch");
        errors = errors + 1;
    end
end
Show solution

count is x, so count != expected evaluates to x. An if treats x as false and skips the error branch, so no error is ever counted. Use the case-inequality operator, which compares x bits literally:

if (count !== expected) begin

A good habit is to add an explicit check after reset that every output is a known value, as do_reset does in this lesson. Changing $display to $error also helps, because the message then carries a severity, file and line.

Summary

  • A self-checking testbench has clock and reset generation, stimulus, a reference model, a checker and a PASS/FAIL report. It decides on its own whether the design works, so you can rerun it after every change.
  • Use one `timescale in every file, drive inputs away from the active clock edge, and wrap repeated sequences in automatic tasks.
  • Compare with === and !==, count errors yourself and end a failing run with $fatal(1, ...) so the exit status is non-zero in every simulator.
  • Mix directed cases for known corner cases with random stimulus from a fixed, printed seed. Dump waveforms only when you need them.
  • Immediate assertions work in Icarus and Verilator; concurrent SVA properties need Verilator or another simulator with SVA support. cocotb and UVM build on the same structure.

Check your understanding

Pick an answer for each question, then check. Answers stay hidden until you submit.

1. The checker uses if (acc != expected) to report errors. The DUT output acc is 8'bx after a bug. What happens?
2. Why does the testbench drive the DUT inputs on the falling clock edge?
3. With Icarus Verilog, a testbench calls $error three times and then $finish. What is the exit status of vvp?
4. Which flag does verilator --binary not include?

Found a mistake or something unclear?Report a correction.