Programming Language Interface (PLI) of Verilog HDL is a mechanism to interface Verilog programs with programs written in C language. It also provides mechanism to access internal databases of the simulator from the C program.

A.2 Why is it used for ?

PLI is used for implementing system calls which would have been hard to do otherwise (or impossible) using Verilog syntax. Or, in other words, you can take advantage of both the paradigms - parallel and hardware related features of Verilog and sequential flow of C - using PLI.

A.3 What are the most frequently used applications of Verilog PLI ?

Some of the most common applications of PLI are delay back annotation, writing delay calculators and developing user interface.

A.4 Wait! wait! I am a VHDL user and I am already impressed. Is there a VHDL PLI available ?

VHDL does not have a PLI (one more reason for you to switch to Verilog), although preliminary proposals are there for standardizing such an interface.

A.5 Gee! Is there anything that PLI does NOT allow ?

Verilog PLI does not permit anything goes against the rules of the language. You can not, for instance, assign a value to a wire, just as you can not do that in Verilog program either. Apart from these, there are few things that Verilog PLI does not allow; most notable among them are : you can not create an object and you do not have access to compiler directives (although, in most cases you can see their effects).

A.6 I heard PLI applications slow down the simulation and make the simulation environment clumsy ?

Alice: "Mr. Rabbit, can you tell me where does this road go ?"
Mr. Rabbit: "That depends on where you want to go."
We have been asked this question several times. Over the years, we figured out there is no definite answer to this question as there is no clear benchmark available. We will also explain why the question itself is not well-defined below. The above question usually takes two forms. First, if I write a PLI application and use it in my simulation, does that slow down the simulation ? The answer is of course yes , just as any other added code would do in any other programming language. However, if you do not use the PLI application in your Verilog model, the answer depends on a lot what the application does and which simulator you use. See for example, this answer .
The second variation is if I write a C model and then use PLI to integrate it with main Verilog source, will that be faster than the corresponding Verilog model ? Here also it depends on which simulator you are using and what your model does. This is an answer from one of the Verilog simulator vendors.
Having said that, for most of the applications that we have seen, our emperical judgement is that any simulation performance degradation due to PLI is not that big as long as the applications themselves are well-written and do not violate basic programming rules.

B. Resources

B.1 Is there any book on Verilog PLI ?

There are two textbooks on Verilog PLI.
Principles of Verilog PLI
Swapnajit Mittra
Kluwer Academic Publishers, Norwell MA
ISBN: 0-7923-8477-6
and

Using the Verilog PLI: A Tutorial and Reference
Stuart Sutherland
Kluwer Academic Publishers, Norwell MA

Other sources for Verilog PLI resources are the two standard manuals.

IEEE Std 1364-1995 : IEEE Standard Hardware Description Language based on the Verilog Hardware Description Language
Published by the IEEE, Inc., 345 East 47th Street, New York, NY 10017, USA
ISBN 1-55937-727-5
OPEN VERILOG INTERNATIONAL (OVI) PROGRAMMING LANGUAGE INTERFACE (PLI), Version 2.0
$150 per copy, plus local sales tax
Open Verilog International
Lynn Horobin
15466 Los Gatos Blvd., Suite 109-071
Los Gatos, CA 95032
Phone: (408) 353-8899 -- FAX: (408) 353-8869
e-mail: ovi@netcom.com

B.2 Is there any web sites for PLI references ?

Well, you are reading one right now.
Apart from this, here is an incomplete list:
A Brief Introduction to PLI
Alternate Verilog FAQ: Part 2

C. Preparations

C.1 I do not know C. Can I write a PLI application in any other language than C ?

The answer to this question is "Yes" and "No". If you are not accessing design database (for example, if all that your program does is "Hello! World."), you can write it in any language, compile it to object code and link it to Verilog and other PLI C programs. However, if you are accessing the database (e.g. reading/writing some register etc.) you do not have much choice than to use C. This is because libraries have language bindings.
Notice that, some simulators do support C++. The process of linking a C++ routine to these simulators varies. You need to look at the manuals of these simulators to find out how exactly the process works. See C.7 and C.8 for more details on this subject.

C.2 Why do not I see a main() in a PLI application ?

Because, your PLI routine is not an independent C program. It consists of C functions which are called by the actual main() function of the simulator (or one of its sub functions).

C.3 What are s_tfcell and veriusertfs[] ?

s_tfcell is a predefined data structure defined as a structure to hold, among things, the type of the PLI routine (task or function) and names of the component functions. veriusertfs[] is an array of these structures.

C.4 I use VCS and there is no such data structure as s_tfcell and veriusertfs[] in it. Why ?

This is because VCS uses a file with the equivalent data in it. This file is normally called a table file.

C.5 I saw veriuser.h as part of IEEE Std. 1364-1995. But my VCS distribution does not have it. What's wrong ?

VCS uses its own header file called vcsuser.h.

C.6 What is a callback ?

A callback is a mechanism to invoke a function when some other event occurs.

C.7 Can I write my PLI application in C++ ?

One of the most favorite questions from our readers. The short answer is "Yes, in most cases". Click here for a longer one.

C.8 Can I write my PLI application in Java ?

There are two known interfaces between Verilog and Java.

Time-rover Inc. sells a Java PLI interface enabling you to access the entire Java suite of packages. Click here to reach their website.
Newisys has released Jove, an open verification environment for the Java platform. Jove is a set of Java APIs and tools to enable Verilog hardware design verification of ASICs and FPGAs using the Java programming language.

C.9 Can I write my PLI application in Perl/Python ?

There are at least 3 programs that support Perl interface to Verilog PLI. Two of them also support Python interface. Wilson Snyder has dedicated his Perl package Verilog_pli to the Verilog user community. It is available from his VeriPool webpage. A student project in Berkely named ScriptEDA has a Perl/Python interface. Lastly, NelSim Software provides an open source package that can be downloaded from their ScriptSim page. According to Nelsim, "ScriptSim does not involve linking an interpreter into the simulation. The interpreter runs outside the simulation, making it impossible for script errors to crash the simulator. It also allows the interpreter to create sophisticated GUIs without interfering with the simulation."

D. Compilation

D.1 Does it matter if I use a 16 bit, 32 bit or 64 bit C compiler for compiling my application ?

No. Internal variables of the simulators are independent of system specification. For example, integer is assumed to be 32 bit irrespective of whatever system you are using.

D.2 During compilation, I get an error message

ld: Unresolved symbol: tf_...
Probably you forgot to include veriuser.h or one of its variants.

D.3 During compilation, I get an error message

handle myHndl;
Syntax error: at or near symbol myHndl
Probably you forgot to include acc_user.h .

D.4 During compilation, I am trying to port an application which was earlier used with Verilog-XL/NC, but during compilation I get the following error message:

vpi_user.h - include file not found.
Either you have not set the path correctly or you are trying to compile the application in an environment which does not support PLI2.0.

E. Libraries/Versions

E.1 Given a choice, which of the three types of routines - TF, ACC and VPI - should I use for my application ?

It depends on a number of factors, including the nature of the application that you are writing and your own familiarity with the libraries. If the nature of the application allows you to use any of the three functions, it seems TF routines are faster.

E.2 Can I use libraries from both versions of PLI in the same application ?

Yes, as long as you are including the right header files.

E.3 Are "handle"s interchangeable between PLI versions 1.0 and 2.0?

Handles in PLI1.0 and 2.0 are of different types. The data type for PLI1.0 handle is handle, when the data type for 2.0 is vpi_handle. So, they can not be used interchangeably. However, Cadence Design Systems in its implementation of PLI2.0, provides two functions for converting handles from one type to the other.

F. How do I ...?

F.1 How do I return a value from a user defined function ?

Use tf_putp() or tf_strdelputp() with an argument index 0, i.e.
tf_putp(0, ret_val);

F.2 Which library function(s) should I use to read value of a register ?

tf_getp() or tf_strgetp().

F.3 Which library function(s) should I use to write a value to a register ?

tf_putp() or tf_strdelputp().

F.4 Which library function(s) should I use to read value of a memory element ?

tf_nodeinfo().

F.5 Is there an access routine to manipulate memory variables in Verilog PLI ?

Not in the standard Verilog. VCS is working on providing one in version5.1

F.6 How do I change delay value of an object ?

If you want to add a value to an already existing delay value, use acc_fetch_delay(). If you want to replace the current delay value with a new one, use acc_replace_delays().

F.7 How do I implement a callback ?

There are different kinds of callbacks and depending on what kind you want to implement as well as what version of PLI you are using, you need to use different library functions. For example, in PLI1.0 you need to use the function tf_setdelay() for introducing a callback event after certain simulation time, tf_asynchon() to invoke a function asynchronously whenever any parameter value changes.

F.8 Is there a PLI library function to tell me the value of a macro (defined using `define) ?

No. Macros are preprocessed and substituted before the actual compilation takes place. So it is not possible for a PLI routine to find out the value.
A trick to avoid this problem is to define the macro as an environment variable before running the simulation, then inside your PLI routine use the standard C library function getenv() to access the value of that environment variable. If you intend to change/undefine the macro, use another PLI routine which calls putenv() to set a new value of the variable.

F.9 Can a PLI C/C++ application call a Verilog task or function ?

A C/C++ function in a PLI application can not invoke a Verilog task or function directly. But, here is a work-around for that.
1. Declare a reg:
   reg flag;
   initial flag = 1'b0;
2. Pass this reg along with other arguments to the system call:
      ...
      $my_call(flag, ...);
3. Inside the PLI routine, change the value of this reg whenever you want to invoke a Verilog task/function.
   
   tf_putp(1, 1-tf_getp(1));
4. Back in Verilog domain, add this
   always @(flag)
      call_my_task(...);
This will call the Verilog task call_my_task() whenever flag changes its value.

Join Verification Management Group

Shop Amazon - Contract Cell Phones & Service Plans

Book of the Month