Unit-testing a fork()-based VPI plug-in on Icarus Verilog 12 in a container: two header shims, a fake $save, and keep the TB timescale explicit

Situation: a C VPI library written for a commercial simulator (it forks the simulation process from a system-task calltf and has the child call the simulator's $save one time unit later) needed red/green tests on a laptop with no vendor tools. Icarus Verilog 12 (debian:stable-slim, apt install iverilog gcc) runs it well enough: vvp is single-threaded, so fork() of the whole simulator works, and cbAfterDelay, cbEndOfSimulation, vpi_handle_by_name and vpi_put_value all behave.

What was needed: 1. Header gaps. Icarus's vpi_user.h has no vpi_release_handle (the IEEE 1364-2005 name), only the older vpi_free_object. Its sv_vpi_user.h lacks vpiStructVar and vpiUnionVar. Put test-only shim headers first on the include path: a vpi_user.h that does #include_next <vpi_user.h> then #define vpi_release_handle vpi_free_object, and an sv_vpi_user.h that #include_next's and defines vpiStructVar 618 and vpiUnionVar 619 if missing. The library itself stays unchanged. 2. Loading. Icarus loads plug-ins via vvp -M<dir> -m<name> (name.vpi with vlog_startup_routines[]). Link your stub/loader object into that .vpi and call its registration routine from a startup routine, so the same stub/dlopen path as production is tested. 3. A missing built-in. Icarus has no $save, so register a test-only $save systf in the same .vpi. It writes a small image file (the sim time plus a design counter read via vpi_handle_by_name). Optional env switches let it fork a slow "compressor" child, print an error line, or start a second pthread, so timeout, error and multi-thread-refusal paths get exercised. 4. A reg vector ([8*N-1:0]) passed to a VPI task reads fine as vpiStringVal: leading zero bytes are dropped. In one case an SV string variable, assigned via if/else from $sformatf, read back as an empty string through vpiStringVal. The same string printed fine with $display. Passing a reg vector filled with $sformat avoided it. That is also the most portable choice across simulators. 5. Give the test TB an explicit timescale. Without one, Icarus defaults the module to 1 s units, so a always #1 cnt++ clock in a module with no timescale, mixed with a 1ns/1ns module, barely ticks. The sim finished in ~10 ms of wall time, and fork children never got to finish before $finish ended them. 6. To make red runs meaningful, build the library from the old tree (git archive <old> vpi stub | tar -x into a mounted dir, SRC=...). Then check that the new checks fail there. Also strengthen equality checks (e.g. require the off run to have N lines), so that empty == empty doesn't pass vacuously.