Registering PLI applications

Each PLI application must register its system tasks and functions with the simulator, providing the name of each system task and function and the associated callback routines. Since many PLI applications already interface to Verilog-XL, ModelSim Verilog PLI applications make use of the same mechanism to register information about each system task and function in an array of s_tfcell structures. This structure is declared in the veriuser.h include file as follows:

typedef int (*p_tffn)(); 
typedef struct t_tfcell {
	short type;		/* USERTASK, USERFUNCTION, or USERREALFUNCTION */
	short data;		/* passed as data argument of callback function */
		p_tffn checktf;  /* argument checking callback function */
		p_tffn sizetf;   /* function return size callback function */
		p_tffn calltf;   /* task or function call callback function */
		p_tffn misctf;   /* miscellaneous reason callback function */
	char *tfname;		/* name of system task or function */ 
		/* The following fields are ignored by ModelSim Verilog */
	int forwref;
	char *tfveritool;
	char *tferrmessage;
	int hash;
	struct t_tfcell *left_p;
	struct t_tfcell *right_p;
	char *namecell_p;
	int warning_printed;
} s_tfcell, *p_tfcell; 

The various callback functions (checktf, sizetf, calltf, and misctf) are described in detail in the IEEE Std 1364. The simulator calls these functions for various reasons. All callback functions are optional, but most applications contain at least the calltf function, which is called when the system task or function is executed in the Verilog code. The first argument to the callback functions is the value supplied in the data field (many PLI applications don't use this field). The type field defines the entry as either a system task (USERTASK) or a system function that returns either a register (USERFUNCTION) or a real (USERREALFUNCTION). The tfname field is the system task or function name (it must begin with $). The remaining fields are not used by ModelSim Verilog.

On loading of a PLI application, the simulator first looks for an init_usertfs function, and then a veriusertfs array. If init_usertfs is found, the simulator calls that function so that it can call mti_RegisterUserTF() for each system task or function defined. The mti_RegisterUserTF() function is declared in veriuser.h as follows:

void mti_RegisterUserTF(p_tfcell usertf); 

The storage for each usertf entry passed to the simulator must persist throughout the simulation because the simulator de-references the usertf pointer to call the callback functions. It is recommended that you define your entries in an array, with the last entry set to 0. If the array is named veriusertfs (as is the case for linking to Verilog-XL), then you don't have to provide an init_usertfs function, and the simulator will automatically register the entries directly from the array (the last entry must be 0). For example,

s_tfcell veriusertfs[] = {
	{usertask, 0, 0, 0, abc_calltf, 0, "$abc"},
	{usertask, 0, 0, 0, xyz_calltf, 0, "$xyz"},
	{0}  /* last entry must be 0 */
}; 

Alternatively, you can add an init_usertfs function to explicitly register each entry from the array:

void init_usertfs()
{
	p_tfcell usertf = veriusertfs;
	while (usertf->type)
		mti_RegisterUserTF(usertf++);
} 

It is an error if a PLI shared library does not contain a veriusertfs array or an init_usertfs function.

Since PLI applications are dynamically loaded by the simulator, you must specify which applications to load (each application must be a dynamically loadable library, see "Compiling and linking PLI/VPI applications" ). The PLI applications are specified as follows:

• As a list in the Veriuser entry in the modelsim.ini file:

Veriuser = pliapp1.so pliapp2.so pliappn.so 

• As a list in the PLIOBJS environment variable:

% setenv PLIOBJS "pliapp1.so pliapp2.so pliappn.so" 

• As a -pli option to the simulator (multiple options are allowed):

-pli pliapp1.so -pli pliapp2.so -pli pliappn.so 

The various methods of specifying PLI applications can be used simultaneously. The libraries are loaded in the order listed above. Environment variable references can be used in the paths to the libraries in all cases.

Model Technology Incorporated Voice: (503) 641-1340 Fax: (503)526-5410 www.model.com sales@model.com