DPI-C tutorial · Part B · Step 08

Python as the golden model

The reference model you trust most is often three lines of Python: zlib.crc32, a numpy convolution, an unbounded int. This step wires such models to the two DUTs in common/rtl behind a DPI contract that a C model could implement just as well, and measures what the convenience costs.

Prereqs: steps 02 (svBitVecVal), 03 (chandle), 04 (open arrays), 06 (scoreboard), 07 (CPython C API)Measured on Verilator 5.052 + Python 3.14.7 + numpy 2.5.2, macOS x86_64Solutions are hidden: think first

§0 · TutorialThe step, explained

Step 06 built the golden-model pattern with a C reference; step 07 showed how to start an interpreter inside the simulator and call into it. This step puts the two together for real hardware: a CRC-32 stream unit whose reference is zlib.crc32, and an 8-tap Q1.15 FIR whose reference is a numpy convolution. The interesting questions are not "how do I call Python" (step 07 answered that) but: how do you shape the DPI boundary so the model is swappable, how do you move arrays and 200-bit integers across it without copies or truncation, where do errors go, how do you keep the model bit-exact, and when does the per-call cost start to dominate your regression time.

Everything below runs in lab/. Every number in this page comes from build/ logs and is asserted by lab/check.py (51 asserts), except the throughput figures in 0.11, which are machine dependent: check.py asserts their ratios, not their values.

0.1One contract, two backends

The single most useful design decision in this step was already made in step 06: the DPI imports are written as if the model were C, with plain C types, and kept in one package, 06_golden_model_c/lab/golden_pkg.sv. This step reuses that file unchanged (run.sh points at it; there is no copy). The testbench only knows the package. Two C files implement the same symbols: step 06's golden.c computes the answer itself, this step's golden_py.c forwards each call into Python (golden.py). Which one you get is decided by the link line, not by the SV source.

// 06_golden_model_c/lab/golden_pkg.sv (shared with step 06, unchanged)
package golden_pkg;
  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);
  import "DPI-C" pure function int unsigned crc32_msg(input byte unsigned msg[], input int len);
  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

# lab/run.sh: same testbench, two binaries
G6=../../06_golden_model_c/lab                       # the contract and the C backend live in step 06
PY="$G6/golden_pkg.sv py_extra_pkg.sv golden_py.c $G6/wall.c $(py_flags)"
C="$G6/golden_pkg.sv $G6/golden.c $G6/wall.c"
vlb crc_py  $PY $RTL/crc32_stream.sv tb_crc.sv
vlb crc_c   $C  $RTL/crc32_stream.sv tb_crc.sv

Things only Python can offer (a 200-bit multiply on unbounded ints, run-time bug selection, the text of a Python exception, a generic call-anything bridge) do not belong in a contract that C must also implement. They live in a second, Python-only package, lab/py_extra_pkg.sv (py_mul_wide, py_set_bug, py_last_error, py_call_i64), also implemented in golden_py.c. A testbench that must run on both backends imports only golden_pkg; tb_crc.sv, tb_fir.sv and tb_perf.sv do.

Two small conventions from step 01 matter here. Both backends #include "Vtop__Dpi.h", the prototype header Verilator generates from the imports, so a C signature that drifts from golden_pkg.sv is a compile error rather than a crash. And both are compiled as C++ by Verilator (clang prints treating 'c' input as 'c++'), so the definitions sit inside #ifdef __cplusplus extern "C" {.

0.2CRC-32: the model is one line

crc32_stream.sv implements CRC-32/IEEE 802.3: reflected, polynomial 0xEDB88320, initial value and final XOR 0xFFFFFFFF. Its output crc is the CRC of every byte accepted since the last clear, i.e. the inverted register. That is exactly the value Python's zlib.crc32 returns, and zlib.crc32(data, value) continues a running CRC: the CRC of a + b equals zlib.crc32(b, zlib.crc32(a)). So the model is:

# lab/golden.py
def crc32_update(crc, data):
    """crc: CRC of the bytes so far (0 for an empty message); data: any bytes-like chunk."""
    return zlib.crc32(data, crc)

class Crc32:                                  # behind the chandle of crc32_new/clear/update
    def __init__(self): self.crc = 0
    def clear(self):    self.crc = 0
    def update(self, b):
        self.crc = zlib.crc32(bytes((b,)), self.crc)
        return self.crc                        # = the DUT's crc output after this byte

Notice what is not there: no table, no bit loop, no reflection, no XOR-out. That is the point of a Python golden model: the reference comes from a library used by every zip file on the planet, not from a second hand-written copy of the algorithm you are trying to verify. The lab's first check is the standard check value: the CRC of the ASCII string "123456789" is 0xCBF43926, and the DUT prints LOG crc check_value=cbf43926.

For crc32_msg the C side turns the open array into a memoryview that points at the simulator's own memory (no copy), calls the cached function, converts the result back, and releases the view:

/* lab/golden_py.c */
unsigned int crc32_msg(const svOpenArrayHandle msg, int len) {
  if (len < 0 || len > svSize(msg, 1)) { /* contract violation: print */ abort(); }   /* as golden.c */
  PyObject* f = callable("golden", "crc32_update");      /* imported once, then cached */
  if (!f) return 0;
  PyObject* mv = PyMemoryView_FromMemory((char*)svGetArrayPtr(msg), len, PyBUF_READ);
  PyObject* r  = PyObject_CallFunction(f, "IO", 0u, mv);    /* "I" = unsigned int */
  unsigned int v = r ? (unsigned int)PyLong_AsUnsignedLong(r) : 0;
  if (!r || PyErr_Occurred()) { fail("crc32_update"); v = 0; }   /* As*() returns -1 on error */
  Py_XDECREF(r);
  release(mv, "crc32_update");                           /* see 0.9 */
  return v;
}

0.3Where to compare: per byte or per message

A running CRC lets the scoreboard check the DUT at two granularities with the same model. Per byte: after every accepted byte, update the expected CRC with a one-byte chunk and compare against crc. Per message: collect the bytes, call the model once at the end, compare once. Both are in tb_crc.sv, selected by +per_byte:

if (per_byte) begin                                    // after each accepted byte
  exp_crc = crc32_update(h, msg[i]); n_calls++;          // h = crc32_new(), crc32_clear(h) per message
  check($sformatf("msg %0d byte %0d", m, i));
end
...
if (!per_byte) begin                                   // once per message
  exp_crc = crc32_msg(msg, len); n_calls++;
  check($sformatf("msg %0d", m));
end

The run sends 300 messages (one empty, one "123456789", 298 random of 1–256 bytes) with random idle cycles, 39 480 bytes in total, and passes in all four combinations:

(Wall times from one run, measured from after crc32_new(), so the ~0.1 s of interpreter start-up and imports (0.11) is not in them. Most of the time is the DUT simulation itself, which is why the backends are close; the numbers move by tens of milliseconds from run to run on a loaded machine. Compare the call counts, which are exact, not these times; 0.11 measures the per-call cost properly.)

0.4A stateful model behind a chandle

A FIR has state: the last seven inputs. Step 03 kept per-instance C state behind a chandle; with Python the natural state container is an object, and the chandle simply is the PyObject*. The ownership rule is the whole design: the chandle owns exactly one strong reference. fir8_new returns the new reference that the constructor call produced (no extra Py_INCREF, no Py_DECREF), and fir8_free drops it.

void* fir8_new(const short* coef) {                 /* input shortint coef[8] -> const short* */
  PyObject* cls = callable("golden", "Fir8");
  if (!cls) return NULL;
  PyObject* c = Py_BuildValue("[hhhhhhhh]", coef[0], coef[1], coef[2], coef[3],
                                            coef[4], coef[5], coef[6], coef[7]);
  PyObject* obj = PyObject_CallOneArg(cls, c);           /* new reference ...           */
  Py_DECREF(c);
  if (!obj) fail("Fir8()");
  return obj;                                            /* ... handed to SV as the chandle */
}
void fir8_free(void* h) { Py_XDECREF((PyObject*)h); }    /* last ref: Fir8.__del__ runs here */

On the SV side nothing distinguishes this from step 03's C counter: h[u] = fir8_new(coef[u]) per DUT instance, fir8_step(h[u], x) per sample, fir8_free(h[u]) at the end. tb_fir.sv instantiates two fir8 with different coefficient sets (a sharp one that saturates often and a low-pass), so two independent Python objects carry two histories. The lab proves the reference count with a class counter Fir8.live, read through the generic bridge of 0.12: LOG live_before value=0, live_after_new value=1, live_after_free value=0.

The per-sample call uses PyObject_CallMethodOneArg with the method name interned once in a static, so no string object is built per sample:

short fir8_step(void* h, short x) {
  static PyObject* name;
  if (!h) return 0;
  if (!name) name = PyUnicode_InternFromString("step");
  PyObject* px = PyLong_FromLong(x);
  PyObject* r  = PyObject_CallMethodOneArg((PyObject*)h, name, px);
  Py_DECREF(px);
  short y = r ? (short)PyLong_AsLong(r) : 0;
  if (!r || PyErr_Occurred()) { fail("Fir8.step"); y = 0; }
  Py_XDECREF(r);
  return y;
}

0.5Bit-exact fixed point

A golden model is only useful if it is bit-exact; "close enough" turns every mismatch into a judgment call. fir8.sv defines its arithmetic in its header, and the model must reproduce each step:

Each piece has a Python twin that matches SV exactly, provided you stay in integers:

• Products and sums: Python int is unbounded; numpy int64 is wide enough (34 bits needed). Never use float: np.convolve on float64 is exact only up to 53 bits and you would be relying on luck.
• Floor shift: >> on a negative Python int or numpy int64 rounds toward −∞, like SV >>> on a signed value. C's >> on a negative signed value is implementation-defined in C (defined as arithmetic since C++20, and arithmetic on every real compiler); the C backend comments it.
• Saturation: min(32767, max(-32768, r)) or np.clip.
• History: the DUT's delay line only shifts when in_valid is high; the model only advances when it is called. Calling the model on every clock instead of every accepted sample is the most common stateful-model bug (see exercise E11 for its cousin, reset).

# lab/golden.py: Fir8.step (per sample) and Fir8.block (per array)
def step(self, x):
    c, h = self.cl, self.h                          # plain Python ints: see below
    acc = c[0]*x + c[1]*h[0] + c[2]*h[1] + c[3]*h[2] + c[4]*h[3] + c[5]*h[4] + c[6]*h[5] + c[7]*h[6]
    self.h = [x] + h[:6]
    return self._out(acc)                           # (acc + 2**14) >> 15, then saturate

def block(self, xin, yout):                       # xin/yout: buffers of int16, see 0.6
    x = np.frombuffer(xin, dtype=np.int16).astype(np.int64)
    full = np.concatenate([np.array(self.h[::-1], dtype=np.int64), x])   # oldest .. newest
    acc = np.convolve(full, self.c, mode="valid")   # len(x) outputs, exact in int64
    np.frombuffer(yout, dtype=np.int16)[:] = self._out(acc)
    self.h = full[::-1][:7].tolist()
    return len(x)

golden.py checks itself without any simulator (python3 golden.py): step, block in uneven chunks, a numpy-per-sample variant and a straight transcription of the formula above must agree on 3000 random samples. In simulation, both DUT instances match the model on all 2048 accepted samples; 631 of the 4096 outputs saturate (LOG fir samples=2048 calls=4096 errors=0 saturated=631), with either backend.

0.6Batching with zero-copy arrays

Every model call costs a DPI crossing, an interpreter entry, argument boxing and result unboxing, whatever the model does. Batching moves many samples per call. fir8_block takes an input open array and an output open array; the bridge exposes both to Python as memoryviews over the simulator's buffers, read-only for x and writable for y, so numpy reads the inputs in place and writes the outputs in place:

void fir8_block(void* h, const svOpenArrayHandle x, const svOpenArrayHandle y, int n) {
  if (n < 0 || n > svSize(x, 1) || n > svSize(y, 1)) { /* contract violation */ abort(); }
  if (!h) return;
  PyObject* mx = PyMemoryView_FromMemory((char*)svGetArrayPtr(x), 2 * n, PyBUF_READ);
  PyObject* my = PyMemoryView_FromMemory((char*)svGetArrayPtr(y), 2 * n, PyBUF_WRITE);
  PyObject* r  = PyObject_CallMethod((PyObject*)h, "block", "OO", mx, my);
  if (!r) fail("Fir8.block");
  Py_XDECREF(r);
  release(mx, "Fir8.block x");
  release(my, "Fir8.block y");
}

The scoreboard side collects the DUT's inputs and outputs in fixed arrays of 256, calls the model once per block and compares 256 pairs. Same stimulus, same result: calls=16 instead of calls=4096, zero errors, for both instances and both backends.

xs[nb] = in_x; ys[0][nb] = out_y[0]; ys[1][nb] = out_y[1];
if (++nb == BLK) begin                                // BLK = 256, N = 2048: no partial block
  for (int u = 0; u < 2; u++) begin
    fir8_block(h[u], xs, ym, nb); n_calls++;
    for (int i = 0; i < nb; i++) cmp(u, n - nb + 1 + i, ys[u][i], ym[i]);
  end
  nb = 0;
end

0.7Integers of any width

Wide arithmetic is where Python models shine and C models hurt. A bit [99:0] argument arrives in C as const svBitVecVal*: an array of 32-bit words, least significant word first (step 02). A Python int has no width. Since 3.13 the C API converts between the two in one call each: PyLong_FromUnsignedNativeBytes and PyLong_AsNativeBytes.

static PyObject* bits_to_py(const svBitVecVal* v, int nbits) {
  svBitVecVal w[16];
  int nw = (nbits + 31) / 32;
  memcpy(w, v, 4 * nw);
  if (nbits % 32) w[nw - 1] &= (1u << (nbits % 32)) - 1;  /* unused top bits */
  return PyLong_FromUnsignedNativeBytes(w, 4 * nw,
           Py_ASNATIVEBYTES_LITTLE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER);
}
static int py_to_bits(PyObject* o, svBitVecVal* v, int nbits) {
  int nw = (nbits + 31) / 32;
  Py_ssize_t need = PyLong_AsNativeBytes(o, v, 4 * nw, Py_ASNATIVEBYTES_LITTLE_ENDIAN |
                        Py_ASNATIVEBYTES_UNSIGNED_BUFFER | Py_ASNATIVEBYTES_REJECT_NEGATIVE);
  if (need < 0) return 0;                                /* not an int, or negative */
  svBitVecVal top = nbits % 32 ? ~((1u << (nbits % 32)) - 1) : 0;
  if (need > 4 * nw || (v[nw - 1] & top)) {             /* does not fit in nbits */
    PyErr_Format(PyExc_OverflowError, "result does not fit in %d bits", nbits);
    return 0;
  }
  return 1;
}

With those two helpers the 100×100→200-bit multiply model is return a * b, exposed as py_mul_wide in the Python-only py_extra_pkg.sv. A C model would need a 15-line schoolbook loop over 32-bit limbs with carries, which is exactly the kind of code you would otherwise have to verify too. The testbench checks the Python model against SV's own wide multiply, 200'(a) * 200'(b), on 1000 vectors including the corner cases (all ones, a carry into bit 100, zero): LOG wide n=1000 errors=0 and max_product=ffffffffffffffffffffffffe0000000000000000000000001, which is $(2^{100}-1)^2 = 2^{200} - 2^{101} + 1$.

0.8Errors into the scoreboard

A Python exception inside a DPI call must never escape as a crash or, worse, as a plausible-looking return value. The C API reports failures in two ways and the bridge must check both: a NULL result from a call, and an error indicator with a valid-looking result from a conversion (PyLong_AsLong and friends return -1 and set the indicator on overflow). The lab's first version returned that -1 to SV: LOG overflow value=-1. Now every wrapper zeroes the result on error.

fail() turns the pending exception into a one-line message (PyErr_GetRaisedException, Python 3.12+). Step 06's contract has no error call, because a C model has nothing to report: it cannot raise. So the bridge does two things with the message. It prints it at once on stderr (golden_py: fails: KeyError: 0), and the wrapper returns 0, which the scoreboard then sees as a mismatch: loud, never silent, and no change to a testbench that also runs on C. It also keeps it for py_last_error() in py_extra_pkg.sv, which returns the message and clears it: a pull model for Python-only testbenches that want the text in their own log. Step 07 shows the push alternative, a context import that calls an exported SV function to report; pull keeps every import non-context, push reports even when the caller forgets to ask.

// tb_err.sv: imports golden_pkg (the contract) and py_extra_pkg (Python-only)
function automatic void show(string tag, longint v);
  $display("LOG %s value=%0d err=%s", tag, v, py_last_error());
endfunction
show("raises", py_call_i64("golden", "fails", none));    // value=0 err=fails: KeyError: 0

tb_err.sv provokes each failure class and prints what reaches SV:

0.9Buffer lifetime: the contract Python cannot see

A memoryview built with PyMemoryView_FromMemory does not own its memory. It is valid only while the simulator keeps the buffer alive, which the LRM guarantees only for the duration of the call. If the model keeps a reference and uses it later, it reads whatever the simulator has there by then: for an input fixed array, live SV storage; for an output array, a dead stack frame (Fig. 5).

The bridge does what it can. After the call, a reference count above 1 on the memoryview means the model stored it (self.kept = xin), and the bridge reports it. Then it calls release(), so any later access through that memoryview raises ValueError instead of reading garbage. What it cannot see is a numpy view: np.frombuffer(xin) holds its own internal buffer reference, not the memoryview object. The lab's keep_numpy bug shows the consequence. After the call returns, SV writes xs[0] = 1234, and Python reads it back through the kept view without any DPI call involved: LOG keep_numpy value=0 err= (undetected), then LOG kept0_after_sv_write value=1234.

0.10Proving the scoreboard can fail

A scoreboard that has never failed has not been tested. Bug injection is the backend's business, not the contract's, so the SV does not change: step 06's golden.c rebuilt with -DMUTANT=1, and golden.py started with GOLDEN_BUG=fir_trunc in the environment (same binary), both make the model truncate instead of rounding, a one-LSB difference that only shows on about half the samples. The per-sample scoreboard, the per-block scoreboard and the C backend all report the same first mismatch and the same count:

LOG first_mismatch unit=0 sample=0 dut=-12612 model=-12613
LOG fir samples=2048 calls=4096 errors=1729 saturated=631
FAIL

Three things are proven at once: the comparison is sensitive to one LSB; the per-block scoreboard reports the same absolute sample index as the per-sample one (the index arithmetic n - nb + 1 + i is right); and the Python and C models make the same mistake in the same place, so they share the contract and differ only in implementation.

The other half of "can it fail" is "did it test anything". Exercise E5 shows a scoreboard that prints PASS after checking zero bytes, because of an SV initializer rule. Always log what was covered (bytes=39480) and assert on it.

0.11What it costs

tb_perf.sv measures model throughput with no DUT: the same SV calls each backend 100 000 times (or in blocks of 1024), timing with step 06's wall_s() import (clock_gettime). The C backend is step 06's golden.c, whose CRC is table-driven. One run on this machine:

What to read from it:

• The crossing is cheap, the interpreter is not free. An empty Python call through the bridge costs about 0.3 µs (3.5 M calls/s). A per-sample Python FIR call costs about 0.85 µs. The same call into C costs about 5 ns. Per-sample Python models are ~170× slower than C ones.
• Batching recovers most of it. The numpy block model runs at 30 M samples/s, 25× the per-sample Python model and within 7× of C.
• Python can beat your C. zlib.crc32 over 1 KiB blocks runs at 1.15 GB/s, 2× faster than step 06's table-driven C loop (571 MB/s), because zlib is optimized C with wider tables and SIMD. The cost of Python is per call, not per byte.
• The first call pays the start-up. Interpreter initialization plus importing numpy took 102 ms (first_call_us=102210). Pay it once, at time 0 (step 07 does it in an explicit py_init).
• Spawning a process per call (Spear §12.9, $system) runs at 25 calls/s: ~40 ms each, 140 000× slower than the embedded call.

To put it in budget terms: if the DUT simulation itself runs at 10 k cycles/s (a mid-size block in Verilator), a per-transaction Python model at ~1 µs per call adds about 1 % to the wall time. Python per sample only hurts when the DUT is tiny and fast, as in these labs, or when the model call happens on every clock of a long regression. Exercise E8 does the arithmetic.

0.12A generic bridge

The typed wrappers above need C code per model function. For quick experiments a generic entry point helps: name the module and function as strings, pass integers, get an integer back. The callable is looked up once and cached in a dict keyed "module.func".

long long py_call_i64(const char* mod, const char* func, const svOpenArrayHandle args) {
  PyObject* f = callable(mod, func);                     /* cached after the first lookup */
  if (!f) return 0;
  int n = svSize(args, 1);
  const long long* a = (const long long*)svGetArrayPtr(args);
  PyObject* t = PyTuple_New(n);
  for (int i = 0; i < n; i++) PyTuple_SET_ITEM(t, i, PyLong_FromLongLong(a[i]));   /* steals */
  PyObject* r = PyObject_Call(f, t, NULL);
  Py_DECREF(t);
  long long v = r ? PyLong_AsLongLong(r) : 0;
  if (!r || PyErr_Occurred()) { fail(func); v = 0; }
  Py_XDECREF(r);
  return v;
}

import "DPI-C" function longint py_call_i64(input string mod, input string func, input longint args[]);
longint two[2] = '{40, 2};
$display("%0d", py_call_i64("operator", "add", two));   // 42: any importable function, no glue
$display("%0d", py_call_i64("math", "gcd", two));       // 2

Two Verilator constraints shape it: an open-array actual must be a fixed array variable (no '{...} literal, no dynamic array), and SV has no zero-length fixed array. So a call with no arguments passes a one-element dummy (longint none[1]), and functions meant for the generic bridge accept *_. Forgetting that is a TypeError that the bridge reports, and if the caller does not read py_last_error(), a 0 that only the stderr line explains: it happened twice while writing the exercises.

0.13Beyond hand-written glue

Everything in this step is ~250 lines of C you now understand line by line. That understanding is what lets you judge the libraries that generate such glue for you. In M. Ballance's taxonomy (Properly Introducing Python to your UVM Testbench, DVCon US 2026), there are two ways to put Python in a verification environment:

This tutorial is the function-wrapper approach done by hand. The options, as of October 2026:

0.14Recipe: a Python golden model over DPI

1. Write the imports in a package, with C types, as if the model were C. Implement a C backend if at all possible; keep both linkable.
2. Include V<top>__Dpi.h in every bridge file. Cache callables; intern method names used per sample.
3. Arrays: fixed SV arrays plus a length; svGetArrayPtr into a memoryview; numpy frombuffer on it. Outputs written in place through a writable memoryview.
4. Wide vectors: mask the unused top bits, PyLong_FromUnsignedNativeBytes in, PyLong_AsNativeBytes out with a fit check. Signed: sign-extend first, and make the model wrap like SV.
5. Stateful models: one Python object per DUT instance behind a chandle that owns one reference; free before Py_FinalizeEx; count live objects.
6. Errors: check NULL and PyErr_Occurred(); return a neutral value; surface the message (pull or push) and never compare a failed model result.
7. Bit-exact arithmetic in integers only; document the rounding and saturation in the DUT header and transcribe it.
8. Per-sample models in plain Python, block models in numpy; compare per transaction while debugging, per block in regression.
9. Inject a model bug and see the scoreboard fail; log what was covered and assert it.

§1 · ObjectivesWhat you can do after this step

• Design a DPI model contract in C types that a C and a Python backend both implement, and select the backend at link time.
• Use a Python library function (zlib.crc32) as a bit-exact reference, including its chaining semantics.
• Hold one Python object per DUT instance behind a chandle with correct reference ownership, and prove it.
• Transcribe fixed-point rounding and saturation into integer Python/numpy that matches SV bit for bit.
• Pass arrays into and out of Python without copies, and state exactly how long those buffers are valid.
• Convert svBitVecVal vectors of any width to and from Python int, unsigned and signed, with overflow detection.
• Route every Python failure into the scoreboard, and know what $error does in Verilator.
• Estimate the per-call cost and choose between per-sample, per-block, C, or a framework (pysv, PyHDL-IF, cocotb).

Prerequisites: open arrays and svGetArrayPtr (step 04), chandle lifetimes (step 03), the scoreboard pattern (step 06), CPython init/refcounts/errors (step 07).

§2 · Exercises11 graded exercises, with solutions

★ basic · ★★ intermediate · ★★★ real-world. Code solutions live in lab/ex/ (or the lab root) and are built, run and asserted by check.py.

# lab/ex/ex_models.py
M32 = (1 << 32) - 1
def shift(i, n):
    return (i << n) & M32 if n >= 0 else (i & M32) >> -n

// lab/ex/ex_shift.sv (loop body)
i = $urandom; n = $urandom_range(0, 70) - 35;
a = '{longint'(i), longint'(n)};                         // a: longint a[2] (a variable, not a literal actual)
got = 32'(py_call_i64("ex_models", "shift", a));
exp_v = (n >= 0) ? i << n : i >> -n;                      // SV: shift by >= width gives 0

int py_square(int x) {
  return PyLong_AsLong(PyObject_CallFunction(f_square, "i", x));
}

initial begin
  ...
  for (int m = 0; m < 300; m++) begin
    int len = (m == 0) ? 0 : (m == 1) ? 9 : $urandom_range(1, 256);
    clear = 1; @(negedge clk); clear = 0;
    exp_crc = 0;
    for (int i = 0; i < len; i++) begin ... end
    exp_crc = crc32_msg(msg, len); check(...);
  end

// lab/ex/ex_crc_frames.sv (loop body)
automatic int len = $urandom_range(46, 1500);
foreach (frame[i]) frame[i] = 8'($urandom);
fcs = crc32_msg(frame, len);
for (int k = 0; k < 4; k++) frame[len + k] = fcs[8*k +: 8];   // LSB first
// clear, stream len+4 bytes into the DUT ...
model = crc32_msg(frame, len + 4);
if (crc !== 32'h2144DF1C || model !== 32'h2144DF1C) n_err++;

# lab/ex/ex_models.py
class Shift:
    calls = 0                                  # Ex. 12.4: class attribute, shared
    def __init__(self, init=0):
        self.reg = init & M32                  # Ex. 12.5
    def shift(self, i, n, ld):
        Shift.calls += 1
        self.reg = shift(i if ld else self.reg, n)
        return self.reg
    def total_calls(self, *_):                 # *_: the bridge always passes >= 1 arg
        return Shift.calls

/* lab/ex/golden_ex.c (includes ../golden_py.c for callable() and fail()) */
void* py_new(const char* mod, const char* cls, const svOpenArrayHandle args) {
  PyObject* c = callable(mod, cls);
  if (!c) return NULL;
  PyObject* t = args_tuple(args);
  PyObject* obj = PyObject_Call(c, t, NULL);           /* the chandle's one reference */
  Py_DECREF(t);
  if (!obj) fail(cls);
  return obj;
}
long long py_call_method_i64(void* obj, const char* method, const svOpenArrayHandle args);
void py_free(void* obj) { Py_XDECREF((PyObject*)obj); }

w[3] = (w[3] & 0x8) ? (w[3] | 0xFFFFFFF0u) : (w[3] & 0xF);       /* sign-extend bit 99 */
PyObject* f  = callable("ex_models", "neg100");       /* FIRST: it initializes Python */
PyObject* pa = f ? PyLong_FromNativeBytes(w, 16, Py_ASNATIVEBYTES_LITTLE_ENDIAN) : NULL;
...
Py_ssize_t need = PyLong_AsNativeBytes(r, y, 16, Py_ASNATIVEBYTES_LITTLE_ENDIAN);
if (need < 0) fail("neg100");
else if (need > 16 || ((y[3] >> 3) != 0 && (y[3] >> 3) != 0x1FFFFFFFu)) /* report overflow */;
y[3] &= 0xF;

def wrap(v, bits):                             # two's-complement wrap, like SV
    return ((v + (1 << (bits - 1))) % (1 << bits)) - (1 << (bits - 1))
def neg100(a):
    return wrap(-a, 100)

class Fir8R(golden.Fir8):
    def __init__(self, *coef):                  # 8 scalar args: what py_new can pass
        super().__init__(coef)
    def reset(self, *_):
        self.h = [0] * 7
        return 0

if (n == 300) begin
  rst_n = 0; @(negedge clk); rst_n = 1;
  void'(py_call_method_i64(h, "reset", none));
  if (py_last_error() != "") n_err++;               // never ignore it
end

§3 · Quiz14 questions, self-grading

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

§4 · LabRun it, swap the backend, break it

Predict first. Before running: how many model calls does the per-byte CRC run make? Will the per-block FIR run see the same first mismatch as the per-sample run under fir_trunc? Which is faster for 1 KiB CRC blocks, the Python or the C backend?

Run.

cd tutorial/08_python_golden_model/lab
python3 golden.py           # the models alone, no simulator
python3 check.py            # 18 builds (3 must fail) + 1 lint, 23 runs, 51 asserts (~20 s)
python3 check.py --no-run   # re-check existing logs
cat build/results.txt       # every LOG/PASS/FAIL line

run.sh exports PYTHONPATH=$PWD:$PWD/ex so the embedded interpreter finds golden.py; run a binary by hand the same way: PYTHONPATH=$PWD ./build/vl_fir_py/Vtop +block, or GOLDEN_BUG=fir_trunc PYTHONPATH=$PWD ./build/vl_fir_py/Vtop to see it fail.

Results (from build/, asserted):

Break it yourself. Comment out the mask in bits_to_py and run tb_wide (the result depends on what Verilator leaves in the top bits: it may well still pass, which is the problem with relying on it). Delete v = 0; in py_call_i64 and look at LOG overflow. Add Py_INCREF(obj) in fir8_new and watch live_after_free.

§5 · Cheat sheetStep 08 on one screen

Rules of thumb

1. Write the imports for the model, in C types; link Python or C behind them. Python-only conveniences go in a separate package.
2. Prefer a library reference (zlib, numpy, int) over a second hand-written algorithm.
3. Bit-exact means integers: floor shifts, explicit rounding, explicit saturation, explicit wrap.
4. Buffers and strings from DPI are borrowed for the call. Copy what you keep.
5. Every conversion can fail with a valid-looking value: check PyErr_Occurred().
6. A chandle owns one reference. Count live objects.
7. The cost is per call: batch, compare per block in regression, per transaction while debugging.
8. Inject a model bug and log coverage counts; a PASS that tested nothing is still a PASS.
9. Commercial simulators accept dynamic arrays, literals, and keep going after $error; Verilator does not. Write to the intersection.
10. When Python should drive the testbench, not just model it, look at PyHDL-IF (UVM) or cocotb (new TBs).

Sources: Spear & Tumbush, SystemVerilog for Verification, 3rd ed., ch. 12 (Ex. 12.1–12.6, §12.9); IEEE 1800-2023 clause 35, H.7.7, H.8.4, H.8.10; Python 3.14 C API (PyLong_AsNativeBytes, PyErr_GetRaisedException); zlib documentation (crc32); M. Ballance, Properly Introducing Python to your UVM Testbench, DVCon US 2026; pysv and PyHDL-IF documentation. Measurements: lab/check.py.