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.
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.
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.
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 13 | Verilator 5.054 | |
|---|---|---|
$error | Prints, keeps running | Prints, then stops the simulation with exit status 1 |
$fatal(1, ...) | Prints, exit status 1 | Prints, exit status 1 |
$finish | Exit status 0 | Exit 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:
Downloadtb_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.
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();
endtaskCall 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)));
endThe 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.
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
endShow 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) beginA 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
`timescalein every file, drive inputs away from the active clock edge, and wrap repeated sequences inautomatictasks. - 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.
Further reading
- Book
- Standard
- Standard
- Tool
- Tool
- Tool
- Tool
- Tool
Found a mistake or something unclear?Report a correction.
Follow this course
Get an email when new lessons and projects are added to this course.