PLI, DPI, DirectC,TLI

本文说的PLI，特指PLI 2, VPI。DPI是SV标准中组成，而DirectC和TLI是VCS中的功能组件。

关于PLI的文献只有Verilog PLI Handbook这本书。并且Verilog PLI是一本相对成熟的技术。PLI有三个libraries, TF(task/function) interface, ACC(access) interface, 以及VPI(Verilog Procedural Interface)，连同DPI，四者的时间先后顺序是1985-1989-1995-2003。而前面两个已经在IEEE 1364-2005(IEEE 1364就是verilog std)中被删除。所以重要的就是VPI和DPI。

part 1 VPI

Handbook一书中part 1的7章介绍了VPI的构建及应用。

1. 创建VPI应用。共分为四步（$hello system task为例）。

 先是在Verilog module中引用，即调用$hello()或者$hello;

》》然后是编写一个calltf routine for $hello，这个routine 是VPI和C mixed，其中需要include "vpi_user.h"包含VPI的数据结构，也可以调用C std libraries 来使用C语言的相应函数。

》》注册编写的VPI 函数，因为是calltf routine，调用s_vpi_systf_data（s_vpi_systf_data，以s_开头的为struct结构体，以t_开头的表示数据类型，以p_开头的表示指针指向struct结构体）结构，并做好相应的注册。

》》Compiling and linking $hello system task。

2a. VPI的分类 

calltf routines, ---The calltf routine is executed when simulation is running

compiletf routines, --- The compiletf routine should only be used for syntax checking， routine called before simulation time 0

sizetf routines ---  A sizetf routine is called one time, before simulation time 0.

sizetf的作用：The intent of the sizetf routine is to notify the simulator compiler or elaborator of the return size for system functions 

注： even if a system function used multiple times in verilog code, sizetf routine is only called once.

simulation callback routines 

typedef struct t_cb_data

{

 PLI_INT32    reason;                        /* callback reason */

 PLI_INT32    (*cb_rtn)(struct t_cb_data *); /* call routine */

 vpiHandle    obj;                           /* trigger object */

 p_vpi_time   time;                          /* callback time */

 p_vpi_value  value;                         /* trigger object value */

 PLI_INT32    index;                         /* index of the memory word or

var select that changed */

 PLI_BYTE8   *user_data;

} s_cb_data, *p_cb_data; 

t_cb_data中包含了PLI_INT32 reason来提供PLI 回调的原因。

关于reason共分为五个部分，simulation related, time related, action related, added in 2001以及added in 2005。

在2005版的vpi_user.h中共有32种原因。 

2b Special data types  

 PLI_INT32, PLI_UINT32, PLI_INT16, PLI_UINT16, PLI_BYTE8, PLI_UBYTE8

typedef int             PLI_INT32;

typedef unsigned int    PLI_UINT32;

typedef short           PLI_INT16;

typedef unsigned short  PLI_UINT16;

typedef char            PLI_BYTE8;
typedef unsigned char   PLI_UBYTE8; 
--from vpi_user.h

2c. 例子  $pow

A sizetf routine to establish the return size of $pow.

A VPI compiletf routine to verify that the $pow arguments are valid values.

A calltf routine to calculate the base to the power of the exponent each time $pow is executed by the simulator.

A VPI simulation callback routine to print a message when simulation firsts starts running (immediately prior to simulation time 0).

其中，simulation callback routine只是演示作用。 

由于sizetf, compiletf, 和calltf三者之间的相互关系，它们也是一起被声明在同一结构（s_vpi_systf_data tf_data;）之中。 

tf_data.type = vpiSysFunc; //PLI_INT32 type;                       /* vpiSysTask, vpiSysFunc */

tf_data.sysfunctype = vpiSysFuncSized;

// PLI_INT32 sysfunctype;  /* vpiSysTask, vpi[Int,Real,Time,Sized,  SizedSigned]Func */

/** alias 1364-1995 system function subtypes to 1364-2001 function subtypes ***/

#define vpiSysFuncType             vpiFuncType

#define vpiSysFuncInt              vpiIntFunc

#define vpiSysFuncReal             vpiRealFunc

#define vpiSysFuncTime             vpiTimeFunc

#define vpiSysFuncSized            vpiSizedFunc 

tf_data.tfname = "$pow"; //veirlog中调用的函数，开头必须是"$"

tf_data.calltf = PLIbook_PowCalltf; 对应的是后面的calltf routine

tf_data.compiletf = PLIbook_PowCompiletf; 对应的是后面的compiletf routine

tf_data.sizetf = PLIbook_PowSizetf; 对应的是后面的sizetf routine

tf_data.user_data = NULL;  //user_data 表示可以自行声明数据结构

vpi_register_systf(&tf_data); 

而callback 则是单开一边。

s_cb_data cb_data_s;

vpiHandle callback_handle; 

cb_data_s.reason = cbStartOfSimulation;

cb_data_s.cb_rtn = PLIbook_PowStartOfSim;

cb_data_s.obj = NULL;

cb_data_s.time = NULL;

cb_data_s.value = NULL;

cb_data_s.user_data = NULL;

callback_handle = vpi_register_cb(&cb_data_s);

vpi_free_object(callback_handle); /* don’t need callback handle */ 

3a. VPI library  

The VPI library can be divided into five basic groups of routines 

A handle routine obtains a handle for one specific Verilog HDL object.

An iterate routine and a scan routine obtain handles for all of a specific type of Verilog object.

get routines access information about an object.

set routines modify information about an object.

A few miscellaneous routines perform a variety of operations. 

3b. three relationships, one-to-one, one-to-many, many-to-one 

The VPI routines used to traverse from one type of object to another are:

vpi_handle(), --- one-to-one  

vpi_iterate(), vpi_scan(), --- for one-to-many

and vpi_handle_multi (). --- for many-to-one

In the Verilog language, the output port of one module can be connected to one or more input ports of other modules, using a net data type. The connection from an output to an input is referred to as an intermodule path. 

the VPI library refers to intermodule paths as a many-to-one relationship. 

这里的intermodule path既可以像hardware那样考虑delay，也可以不用。但都是many-to-one relationship 

4. VPI object diagram 

 更为详细介绍了VPI可以操作的变量类型。

尽管VPI操作复杂，但是可以对Verilog 嵌入更多的操作，如果是引入sv_vpi_user.h，也可以对更多的sv objects进行操作。 

reference: 

PLI vs DPI

http://www.sutherland-hdl.com/papers/2004-SNUG-presentation_Verilog_PLI_versus_SystemVerilog_DPI.pdf 

http://1sutherland.com/papers/2004-SNUG-paper_Verilog_PLI_versus_SystemVerilog_DPI.pdf 

由于是04年的文章，其中提及了plan中的05年Verilog HDL std已经将PLI 1.0 deprecate，而后来的标准也确实如此。

所以，paper的结尾也是改为“the PLI 1.0 is dead...long live PLI VPI and the SystemVerilog DPI!”

注： 

$stop and $finish区别

stop会halt simulator，进入interactive mode。而finish，表示仿真结束，直接退出。