HOW IT WORKS

The VPI interface for Icarus Verilog works by creating from a
collection of PLI applications a single vpi module. The vpi module
includes compiled code for the applications linked together (with any
other libraries that the applications need) into a module with a
single exported symbol, the vlog_startup_routines array.

The product that wishes to invoke the module (normally at run time)
loads the module, locates the vlog_startup_routines table, and calls
all the startup routines contained in that table. It is possible for a
product to link with many modules. In that case, all the modules are
linked in and startup routines are called in order.

The product that uses vpi modules uses the environment variable
VPI_MODULE_PATH as a ':' separated list of directories. This is the
module search path. When a module is specified by name (using whatever
means the product supports) the module search path is scanned until
the module is located.

The special module name "system.vpi" is part of the core Icarus
Verilog distribution and includes implementations of the standard
system tasks/functions.

COMPILING A VPI MODULE (LINUX)

To compile a module, first compile down to object files all the PLI
applications that you wish to include in the module. Then, create a
small "C" source file that defines only the startup table like so:

    extern void hello_register();
    void (*vlog_startup_routines[])() = {
        hello_register,
	0
    };

Compile this table source down to its object file, as well. Finally,
link the application with the command:

    cc -o foo.vpi -shared <all the .o files> -lvpi

The -lvpi flag brings in the interface library that handles the
interface between the module you are making and the simulator run-time
that is loading this module. This contains the supported vpi functions
as stubs that bind to the appropriate implementations.

The resulting foo.vpi file is the vpi module. Place it in a location
where the product to use it can locate it.


CAVEAT EMPTOR

Only the calltf function is supported in general. The sizetf function
is used by the vvp runtime if the object is a function, but only to
check that the function width really is what the compiler already
guessed.  The compiletf function may be supported by the vvp runtime
sometime in the future but not yet.