DPI-C tutorial · Part B · Step 07

Embedding Python in a SystemVerilog simulation

DPI gives you C. CPython is a C library. Link it into the simulator, start the interpreter once, and every Python function becomes callable from SystemVerilog at a cost of tens of nanoseconds. What makes or breaks it is the boring part: lifecycle, reference counts, errors, buffers and threads.

Prereqs: steps 01–05 (import/export, types, chandle, open arrays, context)Measured on Verilator 5.052 + Python 3.14.7, macOS x86_64Answers are hidden: think first

§0 · TutorialThe step, explained

Part A ended with a golden model written in C. C is fast and DPI speaks it natively, but C is a poor language for reference models: no big integers, no complex numbers, no numpy, no zlib, no quick prototyping. The model you trust most is often a Python script that the algorithm team already wrote. This step shows how to call it in-process from SystemVerilog: the simulator links libpython, your DPI C code owns an interpreter, and an SV function call becomes a Python function call.

Nothing here is specific to Python: it is ordinary DPI-C (steps 01–05) plus the CPython C API, the same API every embedder uses (Blender, GDB, LibreOffice). The C API is large, but an embedder needs about twenty functions. The hard parts are elsewhere. One is the interpreter's lifecycle, which has to fit inside the simulator's lifecycle. Another is ownership: every PyObject* has a reference count, and a C bug there is a leak or a crash, never a compile error. The rest is errors that must reach the SV log, two output buffers fighting over the same file descriptor, and the GIL as soon as Verilator runs multithreaded. Every claim below is measured in the lab and asserted by check.py.

0.1Three ways to reach Python from a testbench

Spear §12.9 ("Connecting Other Languages") shows the oldest way: a DPI wrapper around system() that runs a Perl script and returns its exit status (Samples 12.51–12.53). It works for anything with a command line, and it costs a fork+exec+interpreter start per call. The second way is a socket: a Python server process and a DPI client, as in this repo's legacy/sockets_dpi/ and the AMIQ example. The third is to embed the interpreter in the simulator process.

Embedding wins on cost and on data types: arguments cross as C values and become Python objects without serialization. It loses on isolation: a crash in Python's C code is a crash of your simulator, and one process means one interpreter state shared by the whole testbench. For a golden model called millions of times per test, embedding is the default; the rest of this step makes it robust.

0.2Building and linking

The simulator executable must contain (or load) libpython3.14, and your DPI C file must see Python.h. Python ships the flags in python3-config, with one trap: since Python 3.8, python3-config --ldflags omits -lpython3.X, because extension modules must not link libpython (they get its symbols from the host process). An embedder must link it, and asks for it with --embed:

$ python3-config --ldflags
-L/usr/local/opt/python@3.14/.../config-3.14-darwin -ldl -framework CoreFoundation
$ python3-config --embed --ldflags
-L/usr/local/opt/python@3.14/.../config-3.14-darwin -lpython3.14 -ldl -framework CoreFoundation

Without --embed the link fails with Undefined symbols for architecture x86_64: "_Py_Initialize" (lab build noembed). The shared helper common/lab.sh wraps the right flags in py_flags, which turns each word into a Verilator -CFLAGS or -LDFLAGS argument:

# run.sh: build in the background, then run
vlb basic basic.sv basic.c $(py_flags)
# expands to: verilator --binary ... basic.sv basic.c \
#   -CFLAGS -I.../include/python3.14 -LDFLAGS -L.../config-3.14-darwin -LDFLAGS -lpython3.14 ...

0.3Lifecycle: start once, call many times, finalize once

The interpreter has three phases: Py_Initialize* (tens of milliseconds: the sys module, the import system, the encodings, site), any number of calls, and Py_FinalizeEx (flush sys.stdout, run atexit handlers, tear down modules). Map them onto the simulation:

• Init: either explicitly, from an initial block through an imported py_init(dir) (the lab's basic), or lazily, inside the first DPI call (exercise E7). Explicit init makes failures visible at time 0 and lets SV pass configuration (a plusarg with the module directory); lazy init means no init call to forget.
• Calls: import the module once, fetch the callables once with PyObject_GetAttrString and cache the pointers in static variables. Each DPI call is then one PyObject_Call*.
• Finalize: from an SV final block. Verilator runs final blocks on $finish, after the last time step.

// basic.sv (excerpt): the whole lifecycle in SV
import "DPI-C" function int  py_init(input string moddir);
import "DPI-C" function void py_fin();
initial begin
  void'($value$plusargs("pydir=%s", dir));
  if (py_init(dir) != 0) $fatal(1, "python init failed");
  ...
end
final py_fin();

/* basic.c (excerpt) */
int py_init(const char *moddir) {
  if (Py_IsInitialized()) return 0;
  Py_Initialize();
  PyObject *path = PySys_GetObject("path");      /* borrowed: do NOT decref */
  PyObject *dir = PyUnicode_FromString(moddir);  /* new */
  PyList_Insert(path, 0, dir);
  Py_DECREF(dir);
  PyObject *mod = PyImport_ImportModule("toys"); /* new */
  if (!mod) { PyErr_Print(); return -1; }
  f_add = PyObject_GetAttrString(mod, "add");    /* new, cached until py_fin */
  ...
  Py_DECREF(mod);                                /* sys.modules keeps it alive */
  return 0;
}
void py_fin(void) {
  Py_CLEAR(f_add); ...                            /* drop cached refs first */
  Py_FinalizeEx();
}

The lab's lifecycle experiment calls a Python function that does print("PY hello from python") and registers an atexit handler, with stdout redirected to a file as in any regression. Four runs:

Read the nofin row twice: the Python output is gone, and the atexit handler never ran. Python's sys.stdout is its own buffer (0.8); only finalize flushes it, and the process exits through C exit(), which knows nothing about Python's buffers. Any Python-side cleanup (closing a results file, dumping coverage, writing a waveform of model internals) is lost the same way.

The raw row is the other classic: a pointer cached before finalize points into freed interpreter memory. Use Py_CLEAR on every cached pointer in the finalize function, and guard every entry point with a flag (or Py_IsInitialized()) if anything can call after final.

0.4Configuring the interpreter: PyConfig, PyInitConfig, venvs

Py_Initialize() configures Python like the python3 command with no arguments, reading PYTHONPATH, PYTHONHOME and friends from the environment. To control it from C there are two APIs. PyConfig (PEP 587, Python 3.8+) is a struct you fill and pass to Py_InitializeFromConfig. PyInitConfig (PEP 741, new in 3.14) sets options by name, so your code does not depend on the struct layout:

/* config.c: PyConfig (3.8+) */
PyConfig cfg;
PyConfig_InitPythonConfig(&cfg);                    /* like `python3`; Isolated = like `python3 -I` */
PyStatus st = PyConfig_SetBytesString(&cfg, &cfg.program_name, "dpi-sim");
if (*venv) st = PyConfig_SetBytesString(&cfg, &cfg.executable, venv);
cfg.buffered_stdio = 0;                              /* like `python3 -u` */
st = Py_InitializeFromConfig(&cfg);
PyConfig_Clear(&cfg);
if (PyStatus_Exception(st)) ... st.err_msg ...

/* config.c: PyInitConfig (3.14) — same result, options by name */
PyInitConfig *c = PyInitConfig_Create();
int bad = PyInitConfig_SetStr(c, "program_name", "dpi-sim")
       || PyInitConfig_SetInt(c, "buffered_stdio", 0)
       || (*venv && PyInitConfig_SetStr(c, "executable", venv))
       || Py_InitializeFromInitConfig(c);
PyInitConfig_Free(c);

What the lab measured, printing sys.executable, whether a venv is active (sys.prefix != sys.base_prefix) and whether numpy imports:

Three lessons. First, an embedded interpreter believes it is the simulator binary; that is harmless, but it means Python finds its standard library from the build-time prefix, not from a venv. To use a project venv, set executable to the venv's bin/python: CPython's path calculation finds pyvenv.cfg next to it. Use an absolute path, since a relative one prints RuntimeWarning: Unexpected value in sys.prefix. A plain venv sees only its own packages, so numpy disappears; that is the isolation you want for reproducible regressions, once the venv has its requirements installed. Second, PyConfig and PyInitConfig give identical results. Prefer PyInitConfig on 3.14+, and PyConfig if you must support 3.8–3.13. Third, the pitfall in cfg_replace: setting module_search_paths_set = 1 to add your model directory replaces the computed sys.path, the stdlib disappears, and init dies before anything runs. Add model directories after init (PyList_Insert on sys.path, as basic.c does), or through PYTHONPATH.

0.5Calling Python and converting values

Every call has the same five beats: build argument objects, call, check for NULL, convert the result to C, release the result. The C API has shortcuts for the first two. PyObject_CallFunction(f, fmt, ...) builds a tuple from a Py_BuildValue format string. PyObject_CallOneArg and PyObject_CallNoArgs skip the tuple (vectorcall, 3.9+). PyObject_CallMethod(obj, "name", fmt, ...) calls a method. The format letters that matter for DPI types:

The integer row deserves its demo. Python integers are unbounded, so add(0x7fffffff, 1) returns 2147483648. PyLong_AsLong converts it happily into a 64-bit long, and the (int) cast at the DPI boundary wraps it to -2147483648 (lab: LOG wrap r=-2147483648). No error, no warning: the SV side sees a plausible negative number. A golden model that silently wraps is worse than none. The checked version asks for overflow explicitly and returns a status:

/* returns 0 ok, 1 result does not fit in int, -1 Python error */
int py_add_checked(int a, int b, int *sum) {       /* SV: output int sum */
  PyObject *r = PyObject_CallFunction(f_add, "ii", a, b);
  if (!r) { PyErr_Print(); return -1; }
  int overflow;
  long long v = PyLong_AsLongLongAndOverflow(r, &overflow);
  Py_DECREF(r);
  if (overflow || v < INT32_MIN || v > INT32_MAX) return 1;
  *sum = (int)v;
  return 0;
}

Measured: py_add_checked(0x7fffffff, 1) returns 1; py_add_checked(-5, 3) returns 0 with sum=-2. With longint the boundary moves: py_pow2(62) returns 4611686018427387904, while 2⁶³ and 2⁶⁴ make PyLong_AsLongLong return -1 and raise OverflowError. A C caller cannot tell that -1 from a real -1 without asking PyErr_Occurred().

Strings run into C's ownership problem in reverse. A DPI function that returns string returns a const char*, and the simulator copies it when the call returns (H.8.10: the pointer must stay valid until then). PyUnicode_AsUTF8(obj) returns a pointer into the str object's own buffer, which is valid exactly as long as the object lives. So you cannot Py_DECREF the result before returning its UTF-8 pointer. The lab keeps the last result alive in a static and replaces it on the next call:

static PyObject *last_str;                         /* owns the buffer returned to SV */
const char *py_reverse(const char *s) {
  PyObject *r = PyObject_CallFunction(f_reverse, "s", s);
  if (!r) { PyErr_Print(); return ""; }
  Py_XSETREF(last_str, r);                          /* DECREFs the previous result */
  return PyUnicode_AsUTF8(last_str);
}

0.6Reference counting: new, borrowed, stolen

Every PyObject has a reference count; when it drops to zero the object is freed. Each C API function documents what it hands you, and you need exactly three words:

• New reference: you own it and must Py_DECREF it (or hand it to someone who takes it). Most constructors and calls: PyObject_Call*, PyObject_GetAttrString, PyImport_ImportModule, PyUnicode_FromString, PyLong_FromLong.
• Borrowed reference: someone else owns it; use it, do not decref it, do not keep it past the owner's lifetime. PySys_GetObject, PyList_GetItem, PyTuple_GetItem, PyDict_GetItemString, PyEval_GetBuiltins.
• Stolen reference: the callee takes over your reference. Rare and explicit: PyList_SetItem, PyTuple_SetItem. (PyList_Insert, PyList_Append and PyDict_SetItemString do not steal: they add their own reference, which is why basic.c decrefs dir after inserting it into sys.path.)

A missing DECREF is a leak; an extra one is a use-after-free that crashes later, somewhere else. The lab measures the leak with sys.getallocatedblocks() around 1000 calls of a Python function that returns a fresh 1000-element list: 0 blocks per call with the DECREF, 2 blocks per call without it (the list object and its item array). In a regression with 10⁷ transactions that is 20 million blocks and several GB, so the run dies of memory exhaustion instead of failing a check.

The chandle from step 03 composes naturally with this: a Python object created for an SV-side instance is a new reference owned by the SV side. The handle is the PyObject* itself, and the matching "destroy" import decrefs it. Exercise E10 builds the book's shift-register exercises (Ex. 12.3–12.6) this way.

0.7Errors: from a Python exception to $error

The C API reports failure in-band: functions that return objects return NULL; functions that return numbers return -1 (or -1.0); in both cases a thread-local error indicator holds the exception. You must check every call and then either handle and clear the indicator or propagate it by returning failure yourself. The bridge is the last C frame before SV, so it must handle it: SV cannot see a Python exception.

PyErr_Print() is the quick way: it prints the traceback to Python's sys.stderr and clears the indicator. For a testbench you want the traceback in the SV log, at the SV time, counted as an error. Since 3.12, PyErr_GetRaisedException() returns the exception as one object and clears the indicator, replacing the three-pointer PyErr_Fetch. Format it with the traceback module and hand the text to an exported SV function. That makes the import context (step 05):

// errors.sv
import "DPI-C" context function int err_divide(input int a, input int b, output int q);
export "DPI-C" function sv_py_error;
function void sv_py_error(string where, string text);
  n_py_errors++;
  $display("LOG sv_py_error n=%0d where=%s", n_py_errors, where);
  $display("%s", text);
endfunction

/* errors.c */
static void report(const char *where) {
  PyObject *exc = PyErr_GetRaisedException();               /* new ref; indicator cleared */
  PyObject *lines = PyObject_CallOneArg(f_format, exc);     /* traceback.format_exception */
  PyObject *sep = PyUnicode_FromString("");
  PyObject *text = lines ? PyUnicode_Join(sep, lines) : NULL;
  sv_py_error(where, text ? PyUnicode_AsUTF8(text) : "<unformattable exception>");
  Py_XDECREF(text); Py_DECREF(sep); Py_XDECREF(lines); Py_DECREF(exc);
}
int err_divide(int a, int b, int *q) {
  PyObject *r = PyObject_CallFunction(f_divide, "ii", a, b);
  if (!r) { report("divide"); return -1; }
  *q = (int)PyLong_AsLong(r);
  Py_DECREF(r);
  return 0;
}

Measured output for err_divide(7, 0, q), a full traceback with 3.11+ column markers, inside the simulation log:

LOG sv_py_error n=1 where=divide
Traceback (most recent call last):
  File ".../lab/py/errs.py", line 6, in divide
    return _inner(a, b)
  File ".../lab/py/errs.py", line 10, in _inner
    return a // b                      # ZeroDivisionError when b == 0
           ~~^^~~
ZeroDivisionError: division by zero

LOG divide zero rc=-1

0.8Two stdout buffers, one file descriptor

$display in Verilator goes through C stdio (printf on stdout). Python's print goes through sys.stdout, an io.TextIOWrapper with its own buffer that ends in a write() on file descriptor 1. On a terminal both are line-buffered and everything looks fine. When the log is redirected to a file, as in every regression, both are block-buffered and the two streams no longer interleave. The buffering experiment alternates $display("SV i") and Python print("PY i") three times:

Flushing only one side makes it worse, not better: in buf_py Python's text jumps ahead of SV text that was printed earlier. Both buffers must be drained at every hand-over. The robust setup is buffered_stdio = 0 in the config (Python writes through, like python -u) plus fflush(stdout) at the top of every bridge function that may print. The alternative is to never print from the model and return text to SV for $display, which also puts it at the right simulation time.

0.9The GIL, and what --threads does to your bridge

CPython (the default, GIL-enabled build) lets only the thread holding the Global Interpreter Lock run Python code, and each OS thread that calls into Python needs a thread state. Py_Initialize creates one for the calling thread and leaves that thread holding the GIL. In a single-threaded simulation that is all you need: every DPI call arrives on the same thread that initialized Python, and the bridge never mentions the GIL. All of 0.2–0.8 relies on this.

Verilator's --threads N partitions the evaluated design into tasks run by N threads. The lab's threads experiment has eight independent lanes, each calling a Python function from its own always_ff, 400 clocks, and records which OS threads call the DPI function:

The surprising row is th_np_safe. With the default --threads-dpi pure, Verilator serializes non-pure DPI calls onto one thread, but that thread is not the one that ran the initial block and Py_Initialize. So even a non-pure import, which you might believe is "single-threaded", crashes without GIL handling (th_np). Marking imports pure (or --threads-dpi all) spreads them over all four threads, which is legal only because of the GIL calls below. Python still runs one call at a time, so you gain no speed in the model, only correctness.

/* threads.c with -DGIL_SAFE: the pattern for any multithreaded host */
void th_init(void) {
  Py_Initialize();
  ...                                         /* import, cache callables */
  main_ts = PyEval_SaveThread();              /* release the GIL held since init */
}
int th_call(int x) {
  PyGILState_STATE g = PyGILState_Ensure();   /* any thread: get a thread state + GIL */
  PyObject *r = PyObject_CallFunction(f_add, "ii", x, 1);
  int v = r ? (int)PyLong_AsLong(r) : -1;
  Py_XDECREF(r);
  PyGILState_Release(g);
  return v & 0xffff;
}
void th_fin(void) {
  PyEval_RestoreThread(main_ts);              /* take the GIL back on the init thread */
  Py_FinalizeEx();
}

Skipping PyEval_SaveThread after init is the deadlock variant: the init thread keeps the GIL while waiting for the worker threads, and the workers wait in PyGILState_Ensure forever. Calls are not free either: PyGILState_Ensure/Release add a mutex hand-off per call, which step 08 measures.

0.10Extension modules: does numpy work inside the simulator?

Yes, on this setup. cfg_sys imports numpy in 80–130 ms and computes np.arange(4) @ np.arange(4) = 14 inside the Verilator process. numpy's C extension needs libpython's symbols (PyExc_TypeError, PyLong_FromLong, …) at load time. Here the simulator executable links libpython3.14 (a framework dylib on macOS), so the dynamic loader resolves them from the process. Two things to remember:

• numpy can be imported once per process. After a finalize, a re-initialized interpreter cannot import it again (0.3). Finalize once, at the end.
• The import cost (~0.1 s) is paid at the first import. Import heavy modules in py_init so the cost lands at time 0 and not in the middle of the first transaction.

With a commercial simulator that dlopens your DPI library, revisit the RTLD_GLOBAL note in 0.2.

0.11What changed since the Python 2 examples in this repo

The repo's legacy/python-embedded-C/ (Python 2.6, irun, CentOS 6) and legacy/bridge_irun/ follow the classic recipe from the 2000s: Py_Initialize, PyRun_SimpleString, PyObject_CallObject, PYTHONPATH exported in the shell. The ideas are unchanged. These are the details that now differ:

0.12Recipe: a robust Python bridge

1. Build with python3-config --embed; include V<top>__Dpi.h in the bridge.
2. One py_init(dir) from initial: PyConfig/PyInitConfig with buffered_stdio=0 and an absolute venv executable; then insert the model directory (plusarg) into sys.path; import every module (including numpy) and cache the callables. Return a status; $fatal on failure.
3. Each bridge function: fflush(stdout); build args; call; on NULL report the exception through an exported SV function and return a status; convert with overflow checks; DECREF everything you own; keep returned strings alive in a static.
4. If the simulator may call from other threads (--threads, commercial MT engines): PyEval_SaveThread after init, PyGILState_Ensure/Release around every call, PyEval_RestoreThread before finalize.
5. final: Py_CLEAR every cached pointer, Py_FinalizeEx once; guard entry points against calls after it.
6. Test the bridge with large values and fresh objects (immortals hide bugs), and run with the log redirected to a file.

Step 08 applies this recipe to real golden models (zlib.crc32 and a numpy FIR for the DUTs in common/rtl), adds arbitrary-width integers and arrays, and measures the cost per call against the C model of step 06.

§1 · ObjectivesWhat you should be able to do

• Build a Verilator simulation that embeds CPython, and explain why --embed is needed and what a missing -lpython looks like.
• Place init, calls and finalize correctly in the simulation, and predict what is lost when finalize is skipped or $error aborts the run.
• Configure the interpreter (program name, unbuffered stdio, venv, sys.path) with PyConfig or PyInitConfig, and avoid the module_search_paths trap.
• Convert every scalar DPI type to and from Python objects without silent truncation, and return strings with a correct lifetime.
• Classify every C API result as new, borrowed or stolen, and measure a leak.
• Turn a Python exception into a traceback in the SV log and a status code, and never leave the error indicator set.
• Make Python output interleave correctly with $display in a redirected log.
• Make a bridge safe under verilator --threads with the GIL state API.

Prerequisites: 02 (C types of DPI arguments), 03 (chandle), 04 (open arrays, string lifetime), 05 (export, context).

§2 · Exercises12 graded exercises, with solutions

★ basic · ★★ intermediate · ★★★ real design. Code solutions live in lab/ex/ and every output quoted below is asserted by check.py. "Ex. 12.N" is an exercise from Spear & Tumbush ch. 12 (the book has no solutions), redone with Python as the model.

verilator --binary tb.sv bridge.c -CFLAGS "$(python3-config --cflags)" -LDFLAGS "$(python3-config --ldflags)"

PyObject *path = PySys_GetObject("path");
PyObject *dir = PyUnicode_FromString("py");
PyList_Insert(path, 0, dir);
Py_DECREF(dir);
Py_DECREF(path);            /* tidy up */

# ex/py/exmods.py
MASK = 0xFFFF_FFFF
def shift(i, n):
    i &= MASK
    return (i << n) & MASK if n >= 0 else i >> -n

/* ex/shift.c: "I" passes the unsigned value, so Python sees 0x800000F1, not a negative int */
unsigned int shift_py(unsigned int i, int n, int naive) {
  PyObject *r = PyObject_CallFunction(naive ? f_naive : f_shift, "Ii", i, n);
  if (!r) { ... print type and message ...; return 0xDEADBEEF; }
  unsigned int v = (unsigned int)PyLong_AsUnsignedLong(r);
  Py_DECREF(r);
  return v;
}

const char *py_name(int id) {
  PyObject *r = PyObject_CallFunction(f_name, "i", id);
  const char *s = PyUnicode_AsUTF8(r);
  Py_DECREF(r);
  return s;
}

/* ex/lazy.c */
static PyObject *f_add;
static int inits;
static int ensure(void) {
  if (f_add) return 0;
  inits++;
  Py_Initialize();
  const char *dirs = getenv("PY_DPI_PATH");
  PyObject *path = PySys_GetObject("path"), *dir = PyUnicode_FromString(dirs ? dirs : ".");
  PyList_Insert(path, 0, dir);
  Py_DECREF(dir);
  PyObject *m = PyImport_ImportModule("toys");
  if (!m) { PyErr_Print(); return -1; }
  f_add = PyObject_GetAttrString(m, "add");
  Py_DECREF(m);
  return f_add ? 0 : -1;
}
int lazy_add(int a, int b) { if (ensure()) return 0; ... }
void lazy_fin(void) { if (f_add) { Py_CLEAR(f_add); Py_FinalizeEx(); } }

/* ex/eval.c (core) */
static PyObject *globals;                  /* {'__builtins__': ..., 'math': ...} built at init */
static int fail(void) {
  PyObject *exc = PyErr_GetRaisedException();
  PyObject *msg = PyUnicode_FromFormat("%s: %S", Py_TYPE(exc)->tp_name, exc);
  sv_py_error(PyUnicode_AsUTF8(msg));        /* exported; import must be context */
  Py_DECREF(msg); Py_DECREF(exc);
  return -1;
}
int py_eval(const char *expr, double *r) {
  PyObject *v = PyRun_String(expr, Py_eval_input, globals, globals);
  if (!v) return fail();
  double d = PyFloat_AsDouble(v);
  Py_DECREF(v);
  if (d == -1.0 && PyErr_Occurred()) return fail();
  *r = d;
  return 0;
}

# ex/py/exmods.py
class Shifter:
    calls = 0                           # class attribute: shared (Ex. 12.4)
    def __init__(self, init=0):         # Ex. 12.5
        self.reg = init & MASK
    def step(self, i, n, ld):
        Shifter.calls += 1
        self.reg = shift(i if ld else self.reg, n)
        return self.reg

/* ex/shifter.c: the chandle IS the PyObject*, a new reference owned by SV */
void *sh_new(unsigned int init) {
  PyObject *obj = PyObject_CallFunction(cls, "I", init);
  if (!obj) { PyErr_Print(); return NULL; }
  live++;
  return obj;
}
unsigned int sh_step(void *h, unsigned int i, int n, svBit ld) {
  PyObject *r = PyObject_CallMethod((PyObject *)h, "step", "IiO", i, n, ld ? Py_True : Py_False);
  ...
}
void sh_free(void *h) { Py_XDECREF((PyObject *)h); live--; }

/* ex/spawn.c */
#include <sys/wait.h>          /* the book's <wait.h> is Linux-only */
int call_cmd(const char *cmd) {
  int status = system(cmd);      /* macOS WEXITSTATUS needs an lvalue */
  return WEXITSTATUS(status);
}

§3 · Quiz14 self-grading questions

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

§4 · LabRun it, predict it, check it

Everything lives in tutorial/07_embedding_python/lab/. One command builds 17 Verilator binaries in parallel, runs 29 experiments and asserts 71 facts:

cd tutorial/07_embedding_python/lab
python3 check.py            # builds + runs + asserts (about 1–3 min from scratch, seconds when cached)
python3 check.py --no-run   # only re-checks the logs in build/

Results measured on this machine (Verilator 5.052, Python 3.14.7, macOS x86_64, log redirected to a file):

Timings vary with machine load; check.py asserts orders of magnitude, not exact values. The behaviors (orders, crashes, error texts) are asserted exactly.

§5 · Cheat sheetThe bridge on one page

Rules

1. One interpreter per process: initialize once, finalize once, at the end.
2. Every PyObject* you get is new, borrowed or stolen; look it up and comment it.
3. Every call can fail: check NULL / -1 && PyErr_Occurred(), and leave the indicator clear when you return to SV.
4. Python exceptions become text in the SV log plus a status code, never a silent default value.
5. Narrowing happens at the DPI boundary: range-check before casting.
6. Two buffers share fd 1: flush C before calling Python, run Python unbuffered.
7. Any thread other than the init thread needs PyGILState_Ensure, and with --threads that is every DPI thread.
8. Heavy imports (numpy) go in py_init, so their cost lands at time 0.
9. Test with big numbers and fresh objects: immortals hide refcount bugs.
10. Pin the environment from the command line (plusargs, venv), never from the shell.

Sources: IEEE Std 1800-2023 clause 35, H.8.10 and H.9.3; Spear & Tumbush, SystemVerilog for Verification 3rd ed., §12.9 and Ex. 12.1–12.6; Python 3.14 documentation, Embedding Python in Another Application, Python Initialization Configuration (PEP 587, PEP 741), Initialization, Finalization, and Threads, PEP 683 (immortal objects); Verilator 5.052 manual (--threads, --threads-dpi). All measurements: lab/check.py.