Foreign interface

PLI and VPI connect a simulator to code outside the HDL

The interface can inspect design objects, register callbacks, exchange values, and integrate models—but it also crosses language, memory, scheduling, and tool boundaries.

What the boundary enables

The Programming Language Interface is the older umbrella for connecting Verilog simulation to compiled host-language code. VPI, the Verilog Procedural Interface, provides a standardized object-oriented view of elaborated design data and simulator activity. An extension can traverse hierarchy, read and write values under defined rules, register system tasks and functions, schedule callbacks, and cooperate with other software.

Typical uses include connecting a reference model, reading a specialized data format, implementing a custom system task, gathering coverage or trace information, and adapting an existing software model. The interface is not automatically faster or more accurate than HDL. Its value comes when functionality already exists outside the language or when simulator access is necessary for instrumentation and control.

Design for the simulator lifecycle

Integration code has several phases. Registration makes tasks, functions, or startup routines known. Elaboration determines the hierarchy and object relationships the extension may inspect. Start-of-simulation callbacks are suitable for initialization that requires an elaborated design. Value-change, time, read-only, and read-write callbacks participate during the run. End-of-simulation handling releases resources and writes final results.

Code should validate every object lookup and property query. Hierarchical names can change when parameters, generate blocks, or synthesis transformations change structure. Prefer stable handles discovered from known scopes, and keep all simulator-owned handles within their documented lifetime. Treat a missing object as a clear integration error rather than dereferencing it later.

Time and callbacks are part of correctness

A callback observes one region of the simulation schedule. Reading too early may see values before pending updates; writing in a read-only phase is invalid; writing at the wrong time can race with RTL and make results tool-dependent. Define whether data is sampled before or after nonblocking updates and which simulation time units are used. If the external model has its own notion of time, make the conversion explicit.

Four-state values require special care. Host-language integers do not naturally represent zero, one, unknown, and high impedance with arbitrary width. Use the interface representation that preserves value and control bits, and specify how the external model handles unknown input. Signedness, endianness, packed-vector ordering, and width truncation should all have boundary tests.

Engineer it like a small systems component

Isolate tool-specific compile and load options behind a narrow build layer. Pin compiler application-binary-interface expectations and test supported platforms in automation. Avoid global mutable state where multiple simulator instances or tests could interact. Check array bounds, string lengths, file input, and allocation results. A simulator process may hold valuable regression state, so an extension crash is far more disruptive than an ordinary assertion failure.

Provide a minimal HDL test that registers the extension, exercises normal and error cases, checks callback order, and exits with an unambiguous status. Run it whenever the compiler, simulator, host compiler, or operating system changes. If portability matters, keep the core model independent from VPI and place simulator access in a thin adapter.

Document the build boundary for the next maintainer. Include the host compiler requirements, include and library discovery, simulator load option, exported registration symbol, supported platforms, and a tiny invocation example. Binary integration becomes fragile when these facts exist only in one shell history or build server.

The documentation guide explains which questions belong to the language standard and which belong to a simulator manual. The simulation guide supplies the scheduler and testbench context for this interface.