Driving a VCS simulation from a VPI library over pipes: write-region, vpiStop, UCLI call and checkpoint gotchas
Field notes from building a controller for VCS W-2024.09: a VPI library parks the simulation in cbReadOnlySynch, serves commands from a pipe, and uses UCLI (-ucli -ucli2Proc) for checkpoints.
1. vpi_put_value (force, deposit or release) issued from inside a cbReadOnlySynch is silently ignored: no error, and the value doesn't change. Queue the writes, register cbAfterDelay(1), apply them there, and serve again at that step's ReadOnlySynch. Writes then land 1 time unit after the stop point.
2. UCLI 'call {$mytask}' refuses a system task registered through vpi_register_systf ('not a system/user-defined task'). You can't re-enter your library from UCLI that way.
3. vpi_control(vpiStop) from a callback doesn't stop at once: the simulator first moves to the next time step. A resume callback registered with cbAfterDelay(1) before the stop can fire before UCLI gets its prompt. If it blocks on your pipe, you deadlock. Fix: the resume callback polls without blocking for a token that the controller writes after its UCLI work, and otherwise re-arms itself.
4. Fork-style 'checkpoint -add' / 'checkpoint -join <id>' (with -ucli2Proc) took about 0.45 s and 0.65 s on a 16-core RISC-V SoC testbench. The library's own memory (callbacks, watch lists) rewinds with the join, and inherited pipe fds keep working.
5. File 'save' took about 3 s (86 MB compressed). But 'restore <file>' brings back memory, not inherited pipe fds, so the channel dies. Use reopenable named FIFOs plus cbEndOfRestart if you need file restore.
6. vpi_get_value with vpiBinStrVal on a string or real variable can leave value.str unset; set it to NULL first and check vpi_chk_error. In SV modules, logic variables come back from vpi_iterate(vpiVariables), not from vpiReg.
7. Value-change callbacks with vpiSuppressVal/vpiSuppressTime that only mark a signal dirty, plus one cbReadOnlySynch per time step that reads the dirty ones, gave streams that matched a full +all FSDB bit for bit (X/Z included) for 100 signals over about 300K cycles. That's 3.8M changes, at about 27% simulation slowdown with 100 busy signals watched.
8. Runtime -sv_lib (DPI) doesn't call vlog_startup_routines either; VPI needs the compile-time -load (see the separate note on runtime -load).
Verified on VCS W-2024.09 (-ucli -ucli2Proc). Two caveats.
(a) Process tree: the controller's child is a /bin/sh ucli wrapper, with the simv and ucli.exe under it. 'checkpoint -add' forks a child of the active simv. 'checkpoint -join' makes that child the active sim and forks a fresh copy, but the original simv stays alive, parked. So processes accumulate: 4 after one checkpoint, 5 after a join, 6 after a second checkpoint. On a clean UCLI quit or stdin EOF, everything exits. If the controller is SIGKILLed, the active sim exits on pipe EOF, but the checkpoint children are reparented to init, and the original simv, ucli.exe and the wrapper all survive indefinitely. A ppid-tree walk from the spawned pid then misses them. Spawn the sim in its own process group/session and kill by pgid; also kill the group from the library on channel EOF.
(b) Point 3's late vpiStop means the checkpoint is taken at the next event after the stop point, here half a clock period later and past an edge, not at the time you parked. Read the time at the UCLI prompt or on resume, and report that.