python-dpic · tutorial

DPI-C from scratch, then Python as a golden model

An incremental tutorial on the SystemVerilog Direct Programming Interface, measured on Verilator 5.052, ending with Python functions called as bit-exact reference models from a SystemVerilog testbench.

Start with step 01 →Run the labsSource on GitHub
8steps, ≈ 2 h each
458lab checks, all passing
52measured Verilator gaps
15book errata fixed

Get started

Each step is a guide plus a lab. The guide reads in the browser (this site, or tutorial/index.html from a clone, offline). The lab is a folder of small SystemVerilog + C/Python testbenches that Verilator builds and runs; check.py asserts every number the guide quotes.

You needForMeasured with
Verilator 5.xevery lab (--binary --timing)5.052
A C/C++ compilerevery labApple clang, macOS x86_64
Python 3 with python3-configcheck.py; embedding in steps 07–083.14
numpystep 08 (FIR golden model)2.x
z3step 06 (randomize() calls it as an external solver)
ccache (optional)faster rebuilds
git clone https://github.com/leandrotozzi/python-dpic.git
cd python-dpic/tutorial/01_first_call/lab
python3 check.py        # builds every testbench in build/, runs them, asserts the results

Every guide has the same layout: text → worked examples → exercises with hidden solutions → self-graded quiz → lab walkthrough → cheat sheet. Try an exercise before opening its solution; the files it refers to are in the step's lab/ (lab/ex/ for exercises). The index on the left of each guide ticks off sections as you read; the cards below show that progress.

Everything was measured on macOS. Linux runs the same commands; the few macOS-only details are flagged on the Verilator gaps page. Commercial simulators (Questa, VCS, Xcelium) follow the same IEEE 1800 Annex H rules; where they differ from Verilator the guides say so.

Part A · DPI-C

Spear & Tumbush ch. 12
01

First call

import "DPI-C", pure, renaming, libm, how Verilator compiles and links C, the generated prototype header, extern "C".
02

Data types

The SV↔C type map, svBitVecVal/svLogicVecVal, wide vectors, directions, 2-state vs 4-state.
03

State and handles

Static vs per-instance state, chandle, C++ models behind a C ABI, lifetime and leaks, threads.
04

Arrays, structs, strings

Fixed and open arrays, svOpenArrayHandle, packed arrays, struct layout, string ownership.
05

Export and context

Calling SV from C, context vs pure, scopes, why exported tasks can't wait in Verilator.
06

Golden model in C

DUT + C reference + scoreboard, random stimulus, mutants, cost per call, stream vs batch.

Part B · Python

the same SV imports, backed by Python
07

Embedding Python

The CPython C API from a DPI library: lifecycle, imports, refcounts, errors, the GIL, venvs.
08

Python golden model

zlib and numpy as reference models, wide ints, batching, measured C vs Python, pysv / PyHDL-IF / cocotb.
!

What doesn't work in Verilator

52 measured gaps in one place, silent wrong results first, each with its workaround and the lab that proves it.

Steps 06 and 08 share two DUTs: crc32_stream.sv (CRC-32/IEEE, bit-exact with zlib.crc32) and fir8.sv (8-tap Q1.15 FIR, round half-up, saturating). Raw measurements behind every guide: NOTES.md.

References