NOTES.md

Verilator DPI notes (measured, Verilator 5.052, macOS)

Append-only. One ## NN_name section per step.

01_first_call

• .c files on the verilator command line are compiled with $(CXX) (clang warns "treating 'c' input as 'c++'" on a cache miss). Every imported function needs C linkage: extern "C" or #include "V<top>__Dpi.h" before the definitions.
• V<top>__Dpi.h (in the -Mdir) holds one extern "C" prototype per import. Including it turns a return-type mismatch into "functions that differ only in their return type cannot be overloaded". A parameter mismatch defined outside extern "C" silently becomes a C++ overload → link error Undefined symbols "_negate".
• Missing / mangled / static symbol → macOS ld: Undefined symbols for architecture x86_64: "_factorial", referenced from: ...Vdpiimwrap_top__DOT__factorial_TOP....
• Each import gets a generated wrapper Vtop___024root____Vdpiimwrap_<scope>__DOT__<name>_TOP that converts types and passes a temporary for each output (copied back after the call).
• import "DPI" (1800-2005 spelling): %Error-UNSUPPORTED: Unsupported DPI type 'DPI': Use 'DPI-C'.
• import "DPI-C" \expect = function int fexpect(); works (c_name must be escaped when it is an SV keyword).
• pure: no call elimination observed (unused result, f(2)+f(2), loop) — every call executes.
• Importing libc strlen directly fails: Verilator emits unsigned long long strlen(const char*) for longint unsigned, which clashes with size_t strlen from <string.h> (included by the generated code). No SV type maps to unsigned long; use a wrapper. libm sin/pow/fabs/log10 and libc access import fine.
• Same C name imported with two different signatures in two packages: Duplicate declaration of DPI function with different signature (followed by an internal error).
• SV gotcha seen while writing labs: $display(c ? "PASS" : "FAIL") prints a number (the ternary yields an integral, not a string).

03_state_and_handles

• .c files passed to verilator --binary are compiled with the C++ compiler (clang: treating 'c' input as 'c++' when in C++ mode, this behavior is deprecated). DPI functions therefore need extern "C", and C idioms invalid in C++ (implicit void* casts from malloc) fail.
• The generated V<top>__Dpi.h is in the Mdir and the C files compile with -I. from there, so #include "Vtop__Dpi.h" works with no extra flag. It declares chandle as void* and names parameters after the SV formals. Including it turns the book's counter7(c7* inst, ...) (Sample 12.9) into error: conflicting types for 'counter7'; without it the mismatch links silently (C linkage has no parameter types).
• Missing extern "C" on C++ wrappers: link fails with "_counter7_new", referenced from: ... ld: symbol(s) not found (macOS adds the leading _).
• Internally Verilator passes chandle as a 64-bit QData (unsigned long long) in its Vdpiimwrap_* wrappers.
• Two always blocks that call the same import in the same time step: Verilator 5.052 called the second-declared instance first (u2 before u1). final blocks: top's ran before the instances' (u2, then u1). Both orders are unspecified by the LRM.
• A pure import with hidden state (a call counter): Verilator 5.052 still executed all 13 calls (a merged duplicate, a discarded void'() result, and a loop whose results are overwritten). The LRM allows eliminating them; do not rely on either behavior.
• --threads 2: with the default --threads-dpi pure, pure imports were called from 2 OS threads and non-pure imports from 1. --threads-dpi none serializes them to 1 thread. --threads-dpi all gave the same counts as pure in this design (non-pure calls stayed on 1 thread). Results were identical in every mode.
• chandle rules (IEEE 1800-2023 6.14) under verilator --lint-only -Wall: int x = h only warns (WIDTHTRUNC, 64→32 bits); h + 1, assign g = h and @(h) are accepted silently; only chandle inside a packed struct is an error. Verilator models chandle as a 64-bit integer, so code that relies on this will not port to commercial simulators.
• import "DPI-C" function void bump(ref int x); is accepted silently (no warning even with -Wall) and mapped to void bump(int* x). IEEE 1800 forbids ref in imports; commercial tools reject it.
• Imports in always_comb/assign: exactly one call per input change per call site (2 sites, 10 changes → 2 + 20 calls). Event-driven simulators may evaluate more often; keep stateful models out of combinational code.
• Including Vtop__Dpi.h rescues C++ wrappers written without extern "C": the header's earlier extern "C" declarations give the later definitions C linkage (lab nocxxh build links and runs correctly).

02_data_types

• shortreal in a DPI signature: Verilator warns SHORTREAL and generates double in Vtop__Dpi.h (LRM: float). A C definition with float links silently and reads garbage (0.1 → -1.59e-23). Including Vtop__Dpi.h turns it into a compile error.
• ref in an import is accepted silently (generates int*); the LRM forbids it.
• A 1'bz literal as a DPI argument: %Error-UNSUPPORTED: Unsupported tristate construct: ARG. X/Z held in variables arrive as 0 (2-state); C-written bval bits are dropped on output.
• Output arguments are uninitialized stack locals in the generated wrapper (svBitVecVal v__Vcvt[2];) and are copied back unconditionally: an output C never writes overwrites the SV variable with stale stack data (measured: the previous call's 40-bit temp).
• Copy-back masks to the declared width (VL_SET_Q_SVBV(40, ...), scalars 1U & x); input chunks arrive with zero unused bits and no sign extension. The LRM guarantees neither.
• SV_GET_SIGNED_BITS(v, N) in vltstd/svdpi.h (Annex I text) tests bit N instead of N-1: SV_GET_SIGNED_BITS(0x80, 8) = 128.
• Result types: bit [31:0] → svBitVecVal; bit [32:0] and any 4-state vector (logic [6:0], integer, time) are errors citing IEEE 1800-2023 35.5.5.
• Verilator skips verilation (and its warnings) when the -Mdir is up to date: a check that greps warnings needs a clean build.
• SV gotcha seen in testbenches: $display(c ? "PASS" : "FAIL") prints a number (the string literal is integral in an expression).

08_python_golden_model

• Open-array actuals must be fixed-size unpacked arrays: a dynamic array (or queue) is rejected (Unsupported: DPI argument of type DYNARRAYDTYPE, or an internal error Passing dynamic array or queue as actual argument to DPI open array is not yet supported depending on where it is declared).
• An assignment pattern '{...} as an open-array actual: Unsupported: Assignment pattern applies against non-struct/union data type: 'UNSIZEDARRAYDTYPE'. Assign it to a fixed array variable first.
• svGetArrayPtr() of an input fixed array points at the SV variable itself (writes in SV after the call are visible through a pointer kept by C/Python). An output open array is a temporary on the C stack (different address on every call), copied back after the call returns.
• Unpacked-array argument shape must match exactly: logic signed [15:0] c[8] -> input shortint x[8] is %Error-UNSUPPORTED: Shape of the argument does not match the shape of the parameter. Same family: a shortint array on a logic signed [15:0] array port is Array element types are not equivalent.
• $error stops the simulation (Verilog $stop, exit code 1) unless +verilator+error+limit+N.
• $display(cond ? "PASS" : "FAIL") prints a number, not the string (the argument is not a format literal).
• A comment that starts with // Verilator: is parsed as a pragma (Unknown verilator comment).
• Variable with initializer declared inside a loop body of an initial block is static: the initializer runs once at time 0 (int len = $urandom_range(...) was always 0). Use automatic. No warning.
• Verilator compiles .c files as C++ (clang warns treating 'c' input as 'c++'); #include "Vtop__Dpi.h" works because --top-module top makes the prefix Vtop.

06_golden_model_c

• Open arrays only take fixed-size actuals. Passing a dynamic array (or queue) to an input T a[] DPI formal fails at elaboration: %Error-UNSUPPORTED: Unsupported: DPI argument of type DYNARRAYDTYPE (pointing at the import), followed by Internal Error: ../V3Task.cpp:759. Fixed-size unpacked arrays work (svSize, svLow, svGetArrayPtr, svGetArrElemPtr1 all fine, also for output). Workaround: copy into a fixed buffer and pass the length as a separate int (see golden_pkg.sv).
• randomize() runs an external SMT solver (z3): ~5-10 ms per call on this machine, CPU mostly idle (sim cpu 0.68 s vs walltime 12.9 s for 2500 calls). Parallel sims contend for it. It dwarfs DPI cost (a DPI call into C is ~2-10 ns); use $urandom stimulus when measuring anything else.
• Sized negative literal in dist: x dist {-16'sh8000 := 5} on a shortint is unsatisfiable (%Warning-UNSATCONSTR, randomize() returns 0). Plain -32768 works.
• User .c files are compiled with the C++ compiler (clang: warning: treating 'c' input as 'c++') from inside the -Mdir, so #include "Vtop__Dpi.h" works and gives C linkage + prototype checking for free.

04_arrays_structs_strings

• Open-array actuals: only fixed-size arrays. Dynamic array → %Error-UNSUPPORTED: Unsupported: DPI argument of type DYNARRAYDTYPE; queue → ... QUEUEDTYPE; slice a[1:2] → %Error: Internal: Unexpected Call. Workaround: copy through a fixed buffer + explicit count.
• Unpacked struct as DPI argument → Unsupported: DPI argument of type REFDTYPE '<name>'. Use packed structs (svBitVecVal) or separate members.
• Packed open-array elements are stored natively: bit[7:0] = 1 byte, bit[12:0] = 2, bit[63:0] = 8, bit[99:0] = 16 (32-bit words). A svBitVecVal* cast on a svGetArrElemPtr1 result is wrong for widths ≤ 32 (reads neighbors); use svGetBitArrElem1VecVal.
• Flat storage of unpacked arrays: low index first, row-major (int v[10:1] has v[1] at offset 0).
• output arrays: open-array temporary arrives zero-filled and is copied back whole (unwritten elements become 0); fixed-size output arrays return garbage in unwritten elements. inout keeps them.
• svGetArrElemPtr* out of range or with the wrong number of indices: run-time %Warning: DPI svOpenArrayHandle function ... and NULL.
• Returned strings are copied into std::string immediately (one static buffer survives two calls in one $display).
• 4-state: bval written by C is ignored; svGetLogicArrElem*VecVal writes bval = 0.
• C compiler warnings (e.g. -Wreturn-stack-address) only appear in the Verilator build log; with ccache they are replayed on cache hits.
• buf is a Verilog keyword (gate primitive): int buf[256]; is a syntax error.

05_export_and_context

• Timing controls anywhere below an exported task (#, @, or nested in a called task) are a compile error: %Error-UNSUPPORTED: ... Unsupported: Timing controls inside DPI-exported tasks. Book Sample 12.40 does not build. Portable alternative: pull model (SV loops and waits, C is a zero-time iterator), see 05_export_and_context/lab/mem_pull.*.
• Generated header declares exported tasks as void (LRM Annex H: int disable flag); imported tasks as int. svIsDisabledState() links and returns 0.
• Imported function calling an exported zero-time task: accepted (LRM: illegal).
• Non-context import calling an export: fatal only if no scope was ever set (Testbench C called 'X' but scope wasn't set ... See IEEE 1800-2023 35.5.3., preceded by a %Warning: DPI C Function called by Verilog DPI import with missing 'context' keyword.); if an earlier context call left a scope, the export of THAT instance runs silently.
• svGetScopeFromName takes the %m name (top.b2, top.gen[0].u); TOP.top.b2 and relative names return NULL.
• svPutUserData/svGetUserData, svGetCallerInfo (path as on the command line) work.
• pure is not exploited: discarded/duplicated/loop-invariant pure calls all execute (also with -O3). A DPI function in a continuous assign ran 11 times for 5 input changes.
• Cost per call (5 M calls, idle machine): generic ≈ pure ≈ 1.3–1.8 ns, context ≈ 10 ns, context + 1 export ≈ 18–21 ns.
• Unwritten output args come back as garbage: the import wrapper passes an uninitialized temp (o__Vcvt).
• $error defaults to $stop (abort) at the first error; +verilator+error+limit+N keeps going.

07_embedding_python

• .c files passed to verilator --binary are compiled with the C++ compiler (__cplusplus=201703; clang warns "treating 'c' input as 'c++'"). Include Vtop__Dpi.h so definitions get extern "C" from the prototypes.
• Open-array formal (input byte unsigned d[]) with a dynamic array actual: %Error-UNSUPPORTED: Unsupported: DPI argument of type DYNARRAYDTYPE (+ an internal error in V3Task). A fixed-size actual works.
• A // comment whose first word is Verilator: (any case) is parsed as a pragma: %Error-BADVLTPRAGMA: Unknown verilator comment. Don't start comments with the tool's name.
• $finish does not stop the calling process: statements after it in the same initial still execute, then final blocks run.
• $error with the default error limit becomes $stop: "Aborting...", exit status 1, final blocks do not run. +verilator+error+limit+N keeps going ("$stop, ignored due to +verilator+error+limit").
• --threads 4 with the default --threads-dpi pure: non-pure DPI calls are serialized onto ONE thread that is NOT the thread that ran initial (3200/3200 calls off the init thread). pure imports or --threads-dpi all spread calls over 4 threads. Any thread-affine C library (CPython) needs per-call thread attach (PyGILState_Ensure).
• Embedded CPython 3.14: python3-config --ldflags lacks -lpython3.14 (use --embed); numpy imports fine in the Verilator binary (~0.1 s) but only once per process (re-init + import → "cannot load module more than once per process").
• macOS: WEXITSTATUS(system(cmd)) does not compile as C++ ("cannot take the address of an rvalue"); <wait.h> (Spear Sample 12.52) is Linux-only, use <sys/wait.h>.
• Unpacked array port connections with non-equivalent element types are checked inconsistently: a whole shortint c[8] on a logic signed [15:0] coef [8] port fails (Array element types are not equivalent), but a sub-array shortint c[2][8] -> .coef(c[u]) builds and simulates. Both are illegal per the LRM.
• Calling any CPython API (e.g. PyLong_FromNativeBytes) before the interpreter is initialized segfaults the simulator on the first DPI call: make every bridge entry point go through the function that initializes.

08_python_golden_model (contract unification)

• Step 08 now links step 06's golden_pkg.sv by relative path; Python-only extras live in py_extra_pkg.sv. One build line per backend, no SV change.
• 06's golden.c and wall.c rely on #include "Vtop__Dpi.h" for C linkage (no extern "C" of their own). A testbench that links wall.c without importing wall_s still builds: the definition just gets C++ linkage and is unused.
• A contract with no shutdown call: the bridge registers atexit(Py_FinalizeEx wrapper) on first init. Verilator's main() returns after final blocks, so Python's buffered stdout is flushed and Fir8.__del__ runs.
• Bug selection without SV or rebuild: GOLDEN_BUG=fir_trunc vlr ... (bash passes a prefix assignment to a function's child processes); the C twin is -CFLAGS -DMUTANT=1 (rebuild).

LRM review corrections

Checked against IEEE 1800-2023 clause 35 and Annexes H, I, J (2026-10-15). Older lines above stay as written; these supersede them.

• Return types: bit [6:0]/bit [31:0] results are NOT legal per §35.5.5 and H.8.9 (only byte…string and scalar bit/logic). Verilator accepting packed bit results ≤ 32 bits is an extension, so Spear §12.1.4 is not an erratum. The LRM's own §35.5.4 example function bit [15:0] getStimulus() contradicts its normative list.
• import "DPI" (02 notes above: "1800-2005 spelling"): it selects the deprecated SV3.1a packed-argument passing (opaque handles, H.14). §35.5.4 requires a warning or an error, so Verilator's error is compliant.
• Unpacked array element order is fixed by H.7.3 and H.7.6(c): the lower index goes first. Verilator follows it; it is not implementation-defined.
• Packed open-array elements: H.7.3 requires canonical form; H.12.4 requires svGetArrElemPtr* to return NULL if the storage differs. Verilator's native storage with non-NULL pointers is an LRM deviation.
• Exported tasks declared void in Vtop__Dpi.h: deviation from §35.8 / H.8.2 (same header as an import task, int).
• Export from a non-context import: an error per §35.5.3, behavior undefined per H.9.3 (user error, not implementation-defined).
• svDimensions: H.12.2 defers to §20.7 ($dimensions counts packed + unpacked). Verilator returns unpacked dims only; the LRM is ambiguous.
• pure misuse (new, 01 pure_rules.sv): pure function void, pure task, and pure with an output all build and run with no diagnostic (illegal per §35.5.1.3/§35.5.2).
• Shared C names (new, 01 cid.sv, 05 xshared.sv): one C name in two scopes with an identical signature works. Changing only the context qualifier gives Duplicate declaration of DPI function with different signature (then an internal error). Two modules exporting hello + svSetScope works.
• C++ exception through an import (new, 03 exc.cpp): libc++ terminating due to uncaught exception, exit 134, no final blocks (§35.5.1.6: undefined). try/catch in the wrapper fixes it.
• Time API (new, 05 svtime.c): svGetTime ignores type and scope: always sim time in precision units (25 ns → 25000 at 1 ps), real never written. svGetTimeUnit reports −9 for a module with timeunit 1us (the scope table stores the global unit). svGetTimePrecision ignores the scope.
• svDpiVersion() returns "1800-2005" (02 ver.c).
• Dynamic-array formal on an export (new, 05 xdyn.sv): %Error: Verilator internal fault, sorry. instead of a diagnostic (erroneous per §35.5.6).