DPI-C tutorial · Step 06 · End of Part A

The golden-model pattern: a C reference model behind a self-checking testbench

Steps 01–05 taught the mechanics of DPI: types, handles, arrays, exports. This step puts them to work on the job DPI exists for in verification: an independent C model of the DUT's spec, called from a scoreboard, compared bit-exactly, and proven to fire. The SV half of the contract is built so step 08 can replace the C with Python without touching a line of SystemVerilog.

Prereqs: 01–05Book: Spear & Tumbush ch. 12 (§12.2–12.4), ch. 1 (layered TB)Lab: lab/check.py, Verilator 5.052

§0 · TutorialThe step in one idea

A testbench without a reference model can only tell you that the DUT did something. A scoreboard with a reference model tells you whether it did the right thing, on every transaction, for stimulus nobody wrote by hand. The reference model is usually written in a software language: the spec is already there (a standard, a MATLAB or Python model from the algorithm team), software is faster to write than RTL, and an independent implementation does not share the RTL's bugs. DPI-C is the standard way to call that model from SystemVerilog.

This step builds the whole pattern on two small DUTs from common/rtl: a byte-streaming CRC-32 and an 8-tap fixed-point FIR. Along the way it answers the questions you hit on a real block. How should the DPI functions be shaped? Should the model be called per transaction or per block? When should the comparison happen? How do you know the checker can fail at all? What does a DPI call cost, and what dominates the run time instead? Every number on this page comes from the lab and is asserted by check.py.

0.1What a golden model is (and what it is not)

A golden model (also called a reference model or predictor) is an implementation of the DUT's specification that runs next to the simulation and predicts what the DUT should output for the inputs it actually received. Spear's chapter 1 places it inside the layered testbench. The generator creates transactions, the driver turns them into pin activity, the monitor turns pin activity back into transactions, and the scoreboard compares observed results against the model's predictions (§1.10). Chapter 12 supplies the mechanism: the model lives in C and the scoreboard calls it through import "DPI-C".

Three properties separate a useful golden model from a second copy of the RTL:

• Independent. It implements the spec, ideally with a different algorithm and by a different person. The CRC model in this step uses a 256-entry lookup table, while the RTL does eight bitwise shift/XOR steps per byte. If both were written from the same misreading of the polynomial, they would agree with each other and both be wrong. That is why the model is also anchored to an external fact: the catalogue check value CRC-32("123456789") = 0xCBF43926, which the TB prints at time 0.
• Bit-exact where the spec is exact. A DSP model in floating point can only check "close enough". The FIR spec here fixes the arithmetic (35-bit accumulator, round half-up, saturate to int16), so the C model reproduces it exactly and the scoreboard compares with !==, with no tolerance window.
• Untimed. The model does not know about clocks, latency or valid gaps. It sees a sequence of inputs and returns a sequence of outputs. Pairing outputs with inputs is the scoreboard's job, and keeping that out of the model is what makes it reusable (and swappable for Python in step 08).

0.2The two DUTs and their specs

Both DUTs live in tutorial/common/rtl and are shared with steps 07–08. What matters here is the spec each one implements, because that is what the model encodes.

Ambiguity in the spec is the most common source of "model bugs" that are really spec bugs. Before writing a line of C, settle every one of these: rounding mode (half-up, half-even, truncate), what an arithmetic shift does to negatives (floor), saturation versus wrap, reset state, what happens when two controls are active at once (clear with in_valid), and the bit order of a CRC. The lab drives clear together with a stray byte on purpose (clear_with_valid) so that the priority rule is exercised, not assumed.

0.3Designing the DPI contract

The contract is the set of import "DPI-C" declarations. Put them in a package of their own, lab/golden_pkg.sv. Everything on the SV side depends on that file and nothing else, so anything that defines these C symbols can serve as the model. It can be golden.c, a C++ class (exercise 9), or the embedded-Python bridge of step 08.

package golden_pkg;
  // CRC-32: incremental, state behind a chandle (one call per byte)
  import "DPI-C" function chandle      crc32_new();
  import "DPI-C" function void         crc32_free  (input chandle h);
  import "DPI-C" function void         crc32_clear (input chandle h);
  import "DPI-C" function int unsigned crc32_update(input chandle h, input byte unsigned b);
  // CRC-32: whole message, stateless. msg must be a FIXED-size array (Verilator)
  import "DPI-C" pure function int unsigned crc32_msg(input byte unsigned msg[], input int len);
  // FIR: stateful, per sample or per block
  import "DPI-C" function chandle  fir8_new  (input shortint coef[8]);
  import "DPI-C" function void     fir8_free (input chandle h);
  import "DPI-C" function shortint fir8_step (input chandle h, input shortint x);
  import "DPI-C" function void     fir8_block(input chandle h, input shortint x[],
                                              output shortint y[], input int n);
endpackage

Each choice in that file is a decision you will make again on a real block:

• State lives behind a chandle (step 03). A FIR and an incremental CRC have memory. With a static C variable, two DUT instances (or two scoreboards for two channels) would share one model. With new/free pairs, each scoreboard owns its own model.
• Two granularities for the same function. crc32_update/fir8_step are called once per transaction as the monitor sees it. crc32_msg/fir8_block take a whole array. The per-item form is what you need to check every cycle. The block form amortizes call overhead, which hardly matters for C (0.9) and matters a lot for Python (step 08).
• pure only where it is true. crc32_msg's result depends only on its arguments, so it is pure (the simulator may skip or reorder calls). fir8_step mutates hidden state; marking it pure would let the simulator eliminate "redundant" calls and silently desynchronize the model (step 05).
• Plain C types. shortint ↔ short, byte unsigned ↔ unsigned char, int unsigned ↔ unsigned int: no svBitVecVal packing (step 02). Fixed-size shortint coef[8] arrives as const short*. The [] formals arrive as svOpenArrayHandle (step 04).
• Fixed buffers plus an explicit length. The natural signature for a variable-length message is crc32_msg(input byte unsigned msg[]), called with a dynamic array. Verilator 5.052 rejects that at elaboration (below), so the TB copies into a fixed-size buffer and passes the length. Commercial simulators accept dynamic-array actuals for open-array formals (IEEE 1800-2023 §35.5.6.1), but the length argument costs nothing and keeps the contract portable.

%Error-UNSUPPORTED: golden_pkg.sv:10:75: Unsupported: DPI argument of type DYNARRAYDTYPE
%Error: Internal Error: ... ../V3Task.cpp:759: No non-inline task associated with this task call?

0.4The C models

lab/golden.c has two parts. The first is the CRC. A bitwise byte update builds the 256-entry table once, and the model itself uses the table. The code is short, and its structure is the point:

#include "svdpi.h"
#include "Vtop__Dpi.h"   /* generated prototypes: a signature mismatch is a compile error */

static uint32_t crc_tab[256];
static inline uint32_t crc_step(uint32_t s, uint8_t b) { return (s >> 8) ^ crc_tab[(s ^ b) & 0xFF]; }

typedef struct { uint32_t state; } crc_t;    /* register value, before the final inversion */

void* crc32_new(void) { crc_tab_init(); crc_t* c = malloc(sizeof *c); c->state = 0xFFFFFFFFu; return c; }
void  crc32_clear(void* h) { ((crc_t*)h)->state = 0xFFFFFFFFu; }
unsigned int crc32_update(void* h, unsigned char b) {
  crc_t* c = (crc_t*)h;
  c->state = crc_step(c->state, b);
  return ~c->state;                            /* = the DUT's crc output after this byte */
}

Three details carry over to every model you write:

• Include the generated header. Verilator writes V<top>__Dpi.h with the C prototype of every import (step 01). Including it in the model turns a mismatched signature into a compile error instead of stack garbage at run time. It also supplies extern "C", which matters because Verilator compiles .c files with the C++ compiler (clang: warning: treating 'c' input as 'c++'). Commercial flows generate the same header with a switch (Questa -dpiheader, VCS -dpi_header, Xcelium -dpiheader).
• Mirror the observable, not the implementation. crc32_update returns ~state because the DUT's port is ~state_q. The model is free to store its state however it likes, but what it returns must match what the monitor can see on pins.
• Contract violations abort; mismatches do not. A len larger than the buffer is a testbench bug, so crc32_msg prints the reason and calls abort(). A DUT that disagrees with the model is a result, so the model returns its prediction and the scoreboard decides. Exercise 12 shows the abort: crc32_msg: len=300 outside buffer of 256 and exit code 134 (SIGABRT).

The FIR model is just as small. The accumulator is 64-bit, so the 35-bit sum can never overflow, and C's >> on a negative signed value is an arithmetic shift on every compiler you will meet. That shift is implementation-defined in C++17 and only guaranteed in C++20, but it matches SV's >>>, which is floor division by a power of two.

typedef struct { int16_t coef[8]; int16_t dly[8]; } fir_t;   /* dly[0] = x[n-1] */

static int16_t fir_q15(const fir_t* f, int16_t x) {
  int64_t acc = (int64_t)f->coef[0] * x;
  for (int k = 1; k < 8; k++) acc += (int64_t)f->coef[k] * f->dly[k - 1];
  int64_t r = (acc + (1 << 14)) >> 15;                    /* round half-up, floor */
  return (int16_t)(r > 32767 ? 32767 : r < -32768 ? -32768 : r);
}
short fir8_step(void* h, short x) {                     /* predict, then shift */
  fir_t* f = (fir_t*)h;  int16_t y = fir_q15(f, x);  fir_push(f, x);  return y;
}
void fir8_block(void* h, const svOpenArrayHandle x, const svOpenArrayHandle y, int n) {
  const short* xp = svGetArrayPtr(x);  short* yp = svGetArrayPtr(y);  /* NULL if not contiguous */
  for (int i = 0; i < n; i++) yp[i] = fir8_step(h, xp[i]);
}

0.5The layered testbench

Each DUT gets a small layered TB in one file (lab/fir_tb.sv, lab/crc_tb.sv): an interface with a clocking block, and a package with a transaction class, a driver, a monitor and a scoreboard. The structure is Spear's chapter 1 minus the generator/agent ceremony; UVM would split each class into a uvm_sequence_item, uvm_driver, uvm_monitor and uvm_scoreboard connected by analysis ports, but the DPI part is identical.

The clocking block is what makes the monitor/scoreboard pairing trivial. Its inputs are sampled just before the clock edge (#1step), so at edge $k$ the monitor sees the input the DUT is about to capture and the output the DUT registered at edge $k-1$:

clocking cb @(posedge clk);                  // sample just before the edge, drive just after it
  output in_valid, in_x;
  input  in_valid_s = in_valid, in_x_s = in_x, out_valid, out_y;
endclocking

task run();                                     // fir_monitor
  forever begin
    @(vif.cb);
    if (vif.rst_n !== 1'b1) continue;
    if (vif.cb.out_valid)  sb.write_out(vif.cb.out_y);   // result of the input of edge k-1
    if (vif.cb.in_valid_s) sb.write_in(vif.cb.in_x_s);   // input captured at edge k
  end
endtask

The scoreboard keeps a FIFO of predictions. write_in calls the model immediately and pushes the expected output; write_out pops the oldest prediction and compares. Because the model is untimed, the scoreboard never needs to know that the latency is one cycle; it only needs outputs to come out in input order, which is the spec.

function void write_in(shortint x);
  xs.push_back(x);
  if (!batch) exp_q.push_back(fir8_step(h, x));    // DPI call: one per accepted input
endfunction
function void write_out(shortint y);
  ys.push_back(y);
  if (!batch) begin
    if (exp_q.size() == 0) begin error(ys.size() - 1, 0, y, "output with no input"); return; end
    compare(ys.size() - 1, exp_q.pop_front(), y);
  end
endfunction

The CRC needs a different scoreboard because its output is a state, valid on every cycle, not a stream of results. Its monitor calls one method per edge, edge_seen(cyc, clear, valid, byte, crc). In stream mode the scoreboard first checks the sampled crc against its current prediction (the CRC of everything accepted so far) and then applies the edge's action to the model: crc32_clear on clear (which wins over valid, as in the RTL), otherwise crc32_update. The model replays the DUT's control decisions, which is exactly why those decisions have to be in the spec.

0.6Where to compare: per transaction or per block

Both scoreboards take +MODE=stream (default) or +MODE=batch. In stream mode the model is called as the monitor reports, and each output is checked when it appears. In batch mode the scoreboard only records. For the FIR it calls fir8_block once per 256 samples at the end of the test. For the CRC it calls crc32_msg once per frame, when clear closes the frame, and compares the final CRC only.

+FLIP=k is a fake DUT bug injected in the monitor. For the FIR it flips the LSB of output #k; for the CRC it flips bit 31 of the sampled crc on checked cycle #k, a one-cycle glitch that the next edge "repairs". For a stream-of-results DUT like the FIR, both modes find the bug and name the same index; the difference is when you hear about it (at simulated time of the failure, with waveforms around it, versus after the run). For a state-output DUT like the CRC, the per-frame check is strictly weaker: the glitch on cycle 500 lands mid-frame (frame 2, byte 151) and batch mode never looks at that cycle.

Two smaller decisions also show up in the code. The error report prints the first five mismatches in full (model, kind, index or cycle, input, expected, got) and then only counts, because after the first error a stateful DUT usually diverges for the rest of the transaction. In the CRC mutant run below, one bad table entry produces 73 mismatches, all consequences of the first. The second decision: after every comparison the final report also checks that the number of outputs equals the number of inputs, because a DUT that drops or duplicates an output can otherwise pass every comparison it was given.

0.7Stimulus, corners and seeds

A golden model makes random stimulus worth running: no one has to write the expected values. It does not make random stimulus good. Uniform 16-bit samples almost never hit the cases a fixed-point DUT gets wrong: full-scale inputs, the most negative code, long runs that drive the accumulator to its extremes. So the transaction class weights the corners explicitly:

class fir_txn;
  rand bit      valid;
  rand shortint x;
  constraint c_valid { valid dist {1 := 8, 0 := 2}; }                 // random bubbles
  constraint c_x { x dist {32767 := 5, -32768 := 5, 0 := 5,               // saturation corners
                           [-100:100] :/ 15, [-32767:32766] :/ 70}; }
endclass

The coefficients are random too, with a 1-in-4 chance per tap of being exactly 32767 or -32768. The result is that 142 of the 500 outputs of seed 1 saturate (248 of 500 for seed 2). Without that, the saturation logic, which is half of the spec, would be checked by luck. The CRC frames get the same treatment: length 0 (an empty frame), 1–8, up to 256; bytes weighted toward 0x00 and 0xFF; random gaps; and a clear that sometimes arrives together with a stray byte.

Reproducibility is one plusarg. The TB reads +SEED=n and calls process::self().srandom(seed) before creating any object, so every random value derives from it, including those of the class instances, which inherit the seed of the thread that constructs them (IEEE 1800-2023 §18.14). It prints a digest of the coefficients and every input sample. Seed 1 gives 99b218a1 in both stream and batch mode, and seed 2 gives 949caf20. The equality across modes is not an accident. The scoreboard never draws a random number, so changing how you check cannot change what you drive. Keep it that way: a checker that consumes randomness makes a failing seed stop failing when you add a debug print.

0.8Proving the checker fires

A scoreboard that never fails is either checking a perfect DUT or checking nothing. You find out which by breaking something on purpose and watching it fail. The lab does this in two places:

• DUT side: +FLIP=k corrupts one observed value in the monitor (previous section). It proves the comparison path, the error message and the index bookkeeping.
• Model side: golden.c compiled with -CFLAGS -DMUTANT=n gets one realistic bug. These are the bugs a hurried model writer actually makes. Each failure pattern tells you something about your stimulus.

0.9What a DPI call costs

lab/bench.sv times $10^7$ calls of each kind with a wall-clock DPI helper (wall_s(), clock_gettime) and prints nanoseconds per item. Numbers from the run used for this page; on a busy machine they move by up to 2×, so check.py asserts orders of magnitude and orderings, not exact values.

What the numbers say, in order of importance:

1. In Verilator a DPI import is an ordinary C function call. The generated wrapper converts arguments (here, none of the types need conversion) and calls your function: about 2 ns of overhead. The 200,000-sample run calls fir8_step 200,000 times, about 1.2 ms of a 1.6 s run, under 0.1 %. check.py asserts that the DPI share is below 5 %.
2. Batching buys nothing for a C model. fir8_block256 is within noise of fir8_step: the arithmetic dominates the call. The full FIR TB in batch mode was 1.31 s versus 1.64 s in stream mode for 200,000 samples, a difference made by SV queue handling and machine noise, not DPI. With C, choose stream or batch for debuggability (0.6), not speed.
3. The model in C beats the model in SV. The same FIR as an SV class costs about 3× more per sample in Verilator. This is not an argument against SV models, but it dispels the idea that crossing into C is expensive.
4. This changes with Python. A call into an embedded CPython interpreter costs on the order of a microsecond or more: the arguments become Python objects and the interpreter runs bytecode. Then 200,000 calls cost a noticeable fraction of the run, and the block API (one call, one array) becomes the tool. Step 08 measures exactly that, through these same imports, on both backends (its tb_perf.sv; step 08).

0.10Swapping the implementation

The contract in 0.3 pays off here. lab/ex/golden_cpp.cpp implements the same nine symbols with two C++ classes, Crc32 and Fir8. Each chandle is a new'd object; each import is a one-line wrapper that casts the handle and calls a method. This is Spear's §12.3 static-wrapper pattern (Samples 12.14 and 12.16), minus the hand-written extern "C" block: including Vtop__Dpi.h gives every definition C linkage, because a function first declared extern "C" keeps that linkage.

void* fir8_new(const short* coef) { return new Fir8(coef); }
void  fir8_free(void* h) { delete static_cast<Fir8*>(h); }
short fir8_step(void* h, short x) { return static_cast<Fir8*>(h)->step(x); }

The run script builds the FIR testbench twice from the same SV, once with golden.c and once with ex/golden_cpp.cpp, and runs both with +SEED=3 +FAST +N=20000. Both print digest ca87667f and PASS fir8. Nothing on the SV side knew which one it got.

Step 08 replaces the object again, this time with a thin C layer that forwards each call into an embedded Python interpreter running zlib.crc32 and a numpy FIR. Three things in this step's contract were chosen for that:

• The handle maps to a Python object (a model instance), so per-instance state works the same way.
• The block entry points (crc32_msg, fir8_block) give Python whole arrays. That is where it is fast: one call, one bytes or numpy buffer, the loop inside C-implemented library code.
• The types are plain integers and arrays of them, which convert directly to Python int and buffer objects. No 4-state values or packed structs cross the boundary.

0.11Recipe: a C golden model for your block

1. Pin down the spec to the bit: rounding, saturation, signedness, reset state, control priorities, bit/byte order. Find an external check value (a standard's test vector, the algorithm team's output).
2. Write the contract as a package of imports: new/free plus a per-item call for stateful models, a block call for throughput, pure only for stateless functions, plain C types, fixed-size buffers plus length.
3. Write the model against the spec, with a different algorithm from the RTL where possible. Include the generated __Dpi.h. Abort on contract violations, never on mismatches.
4. Feed it from the monitor, never from the driver. Pair outputs with predictions through a FIFO (streams) or by replaying the control decisions every cycle (state outputs).
5. Compare at monitor time, bit-exactly, with a report that names the model, the index or cycle, the input, the expected and the observed value. Print the first few mismatches, count the rest, and check the transaction counts at the end.
6. Weight the corners in the stimulus, take the seed from a plusarg, and keep the checker free of random calls.
7. Break it on purpose: one DUT-side injection, two or three model mutants, all expected to fail, all in the regression.
8. Measure before optimizing. With a C model the DPI call is noise; the solver and the TB dominate.

§1 · ObjectivesWhat you should be able to do

• Explain what makes a reference model independent, bit-exact and untimed, and why a cycle-accurate "model" is a different tool.
• Design a DPI contract for a stateful model: chandle lifecycle, per-item and block entry points, pure only where true, portable argument types.
• Wire a model into a layered SV testbench so that predictions come from sampled inputs and are paired with outputs by order, independent of latency and gaps.
• Choose between per-transaction and end-of-test comparison, and know what each one can miss.
• Write stimulus that reaches the spec's corners, make it reproducible from one seed, and keep the checker from disturbing it.
• Prove that a checker fires with DUT-side injection and model mutants, and read what a surviving mutant says about the stimulus.
• Measure DPI call cost against the rest of the run, and predict when batching matters (Python, step 08) and when it does not (C).
• Swap the implementation behind the contract without touching the SV side.

Prerequisites: import declarations and the generated header (01), type mapping (02), chandle state (03), open arrays (04), pure/context (05).

§2 · Exercises12 graded exercises, with solutions

★ basic · ★★ intermediate · ★★★ real design. Every solution that contains code or a number was run in the lab and is checked by check.py; code lives in lab/ex/. "Ex. 12.N" = exercise from Spear & Tumbush ch. 12 (the book gives no solutions).

/* ex/shift.c (excerpt). C makes x << 32 undefined behavior; SV defines it as 0. */
static uint32_t sh(uint32_t i, int n) {
  if (n >= 32 || n <= -32) return 0;
  return n > 0 ? i << n : n < 0 ? i >> -n : i;
}
unsigned int shift_c(unsigned int i, int n) { return sh(i, n); }
static uint32_t reg;                                  /* one register for every caller */
unsigned int shift_reg(unsigned int i, int n, unsigned char ld) {
  reg = ld ? sh(i, n) : sh(reg, n);
  return reg;
}

import "DPI-C" pure function int unsigned shift_c(input int unsigned i, input int n);
import "DPI-C" function int unsigned shift_reg(input int unsigned i, input int n, input bit ld);

static unsigned long calls;                           /* Ex. 12.4: across instances */
void* shift_new(unsigned int init) {                  /* Ex. 12.5: initial value */
  uint32_t* r = malloc(sizeof *r);  *r = init;  return r;
}
unsigned int shift_inst(void* h, unsigned int i, int n, unsigned char ld) {
  uint32_t* r = h;
  *r = ld ? sh(i, n) : sh(*r, n);
  printf("LOG shift_inst inst=%p ... reg=%08x calls=%lu\n", h, *r, ++calls);
  return *r;
}

LOG shift_inst inst=0x600003508030 i=00000000 n=1 ld=0 reg=00000002 calls=1
LOG shift_inst inst=0x600003508040 i=00000000 n=-4 ld=0 reg=00000010 calls=2
LOG shift_inst inst=0x600003508030 i=00000000 n=1 ld=0 reg=00000004 calls=3
LOG shift_inst inst=0x600003508040 i=00000000 n=-4 ld=0 reg=00000001 calls=4

task run(int n);
  fir_txn t = new();
  for (int sent = 0; sent < n; ) begin
    void'(t.randomize());
    @(vif.cb);
    vif.cb.in_valid <= t.valid;
    vif.cb.in_x     <= t.x;
    sb.write_in(t.x);                    // "the monitor is redundant for inputs"
    sent += t.valid;
  end
endtask

// ex/residue_tb.sv
module top;
  import golden_pkg::*;
  initial begin
    byte unsigned b[64];
    int bad = 0;
    for (int t = 0; t < 1000; t++) begin
      int len = $urandom_range(60);
      int unsigned c;
      for (int i = 0; i < len; i++) b[i] = $urandom;
      c = crc32_msg(b, len);
      for (int k = 0; k < 4; k++) b[len + k] = c[8*k +: 8];      // little-endian
      if (crc32_msg(b, len + 4) != 32'h2144DF1C) bad++;
    end
    $display("LOG residue trials=1000 bad=%0d", bad);
    $finish;
  end
endmodule

#include "Vtop__Dpi.h"   // declares the imports extern "C"; the definitions below inherit it
void* crc32_new() { return new Crc32; }
void  crc32_free(void* h) { delete static_cast<Crc32*>(h); }
unsigned int crc32_update(void* h, unsigned char b) { return static_cast<Crc32*>(h)->push(b); }
void* fir8_new(const short* coef) { return new Fir8(coef); }
short fir8_step(void* h, short x) { return static_cast<Fir8*>(h)->step(x); }
// ... crc32_clear, crc32_msg, fir8_free, fir8_block likewise

duplicate symbol '_crc32_clear' in:
    .../build/vl_dup/golden_cpp.o
    .../build/vl_dup/golden.o
duplicate symbol '_fir8_step' in:
...

§3 · QuizCheck your reasoning

Pick an answer, press Check. Each explanation covers the right answer and the tempting wrong one.

§4 · LabRun it, read it, break it

Files in 06_golden_model_c/lab/:

Before running, predict: (1) Will stream and batch FIR runs with the same seed print the same digest? (2) Which mutant produces exactly as many errors as there are saturated outputs? (3) Will batch-mode CRC catch +FLIP=500? (4) Is fir8_block256 much faster per sample than fir8_step?

cd tutorial/06_golden_model_c/lab
python3 check.py              # runs run.sh, then asserts; prints the bench numbers
python3 check.py --no-run     # re-check existing logs
./build/vl_fir/Vtop +SEED=7 +FAST +N=100000 +MODE=batch   # try your own

What to look at: build/*.log, one per run, with LOG lines (fir_run, fir_sb, crc_sb, mismatch, bench) and PASS/FAIL. build/results.txt counts PASS/FAIL per TB: 12 PASS and 8 FAIL, and the 8 FAILs are the intended ones (flips and mutants).

Things to try: in crc_scoreboard::edge_seen, apply the byte when clear and valid arrive together (the opposite of the RTL's priority) and watch which cycle fails first; change BLK in the FIR scoreboard to 1 and re-time batch mode; add a fifth mutant (round half-even) and predict its kill rate before running (hint: it only differs on exact ties).

§5 · Cheat sheetFor the next block you verify

Rules

1. The model implements the spec, not the RTL; anchor it to an external value.
2. Untimed model, timed testbench: latency and gaps live in the monitor/scoreboard.
3. Feed the model from the monitor's sampled values.
4. Compare at monitor time, bit-exactly; report first mismatch in full, count the rest, check the counts.
5. Per-frame checks of a state output are blind between frames.
6. pure only for stateless functions.
7. Abort on contract violations; report mismatches.
8. Weight the corners; one seed plusarg; no randomness in the checker.
9. Keep mutants in the regression as must-fail tests.
10. In Verilator, DPI into C costs nanoseconds: measure the solver and the TB first. Batch for Python, not for C.

Spear & Tumbush, SystemVerilog for Verification, 3rd ed. (Springer, 2012), ch. 1 (§1.9–1.11) and ch. 12 (§12.2–12.4, Ex. 12.1–12.5); IEEE Std 1800-2023 §35.5.6.1, §35.6.1, H.12. DUTs: tutorial/common/rtl. Every number on this page comes from 06_golden_model_c/lab/check.py (Verilator 5.052, macOS x86_64); timings vary with machine load.