Using PLI 2.0 (VPI) with VCS
(Yes, it really works!)
Stuart Sutherland
Sutherland HDL, Inc., Portland, Oregon
stuart@sutherland-hdl.com
ABSTRACT
The Verilog PLI VPI library, often referred to as “PLI 2.0”, is the latest generation of the Verilog
PLI standard. The VPI library has a number of advantages over the older TF and ACC libraries
(often collectively referred to as “PLI 1.0”). The VPI library has been part of the IEEE 1364 Ver-
ilog standard since 1995, but the VCS simulator has only just begun to support the VPI library
with version 6.1, which is projected to be released early in 2002. This paper presents why it is
desirable to use the VPI library, and how well the library is supported in VCS. The goal of the
paper is to answer the question: “Are there compelling reasons to use PLI 2.0 in your future PLI
applications?”
SNUG San Jose 2002 2 Using PLI 2.0 (VPI) with VCS / Stuart Sutherland
1.0 What are “PLI 1.0” and “PLI 2.0”
The PLI has been an integral part of the Verilog language since 1985, and has been a major con-
tributor to the success of Verilog. There have been a number of versions of the PLI in its 17-year
history.
1985: The TF library. The original Verilog PLI was designed to read and write the arguments of
a system task. For the most part, this first generation of the PLI could not see the internals of a
simulation data structure; it could only see the information passed in as system task arguments.
This first generation of the PLI is a library of C functions which mostly begin with the letters
“tf_” (for “task/function”). Hence, the library is often referred to as the “TF” library. In most Ver-
ilog simulators, the TF library is defined in a file called veriuser.c. Until version 6.1, however,
VCS placed the library in a file called vcs_user.c. VCS 6.1 now uses the standard veriuser.c file.
1988: The ACC library. A second generation of the PLI was created to supplement and extend
the capability of the TF library. This second library is defined in a different C file, called
acc_user.h. All the routines in this library begin with the letters “acc_”, which stands for
“access”. The ACC library was developed specifically at the request of ASIC vendors to do delay
calculation, power analysis and other types of analysis involving the cells that make up an ASIC
netlist. The ACC library provides access into the simulation for structural designs (netlists). The
ability to access the structural level of a design has made the ACC library very valuable for a wide
variety of other types of applications as well. Waveform displays such as VirSim and other graph-
ical design debug utilities often use the ACC library.
A primary limitation of the ACC library, however, is that it can only access the structural level of
Verilog models. The ACC library cannot access RTL models, memory arrays and many other
types of objects that make up a large part of many Verilog HDL models. Another drawback of the
ACC library is its ad-hoc evolution. Much of the library of C functions were added after the orig-
inal release in 1988. These additional routines were added a little here and a little there, with no
guiding specification to ensure consistency in syntax and semantics. As a result, the ACC library
is full of inconsistencies, redundancies and poorly defined behavior. It is awkward to learn and
difficult for simulation vendors to implement. The ACC library behaves differently in every Ver-
ilog simulator.
1990: The OVI “PLI 1.0” standard. When Gateway Design Automation/Cadence released the
Verilog language and PLI to the public domain, the users forum Open Verilog International (OVI)
labeled the combined TF/ACC libraries as “PLI 1.0”. This term was strictly a label—PLI 1.0 did
not add any new features or capabilities to the Verilog PLI.
1993: The OVI “PLI 2.0” standard. OVI decided to completely replace the TF and ACC librar-
ies with a new library, that eliminated the redundancies and limitations of the old libraries. OVI
called the new library “PLI 2.0”. This new library combined all the functionality of the 200+ rou-
tines in the TF and ACC libraries into a single library of about 25 routines. The syntax of these
routines were simple and well defined. PLI 2.0 overcame many, if not all, of the weaknesses and
drawbacks of the ACC library.
OVI intended to totally eliminate the old TF and ACC libraries, and therefore deliberately made
PLI 2.0 so that it was not backward compatible. Indeed, OVI’s PLI 2.0 called its library ACC, and
used many of the same function names and constant names as the older ACC library, but with dif-
SNUG San Jose 2002 3 Using PLI 2.0 (VPI) with VCS / Stuart Sutherland
ferent functionality and values. Because PLI 2.0 was not backward compatible, the hundreds of
existing PLI applications could not be used together with a PLI 2.0 application. Therefore, no
simulators ever completed implementing the OVI version of the PLI 2.0 standard. The original
OVI “PLI 2.0” never saw the light of day.
1995: The IEEE 1364-1995 standard
1
and the VPI library. In 1995, the IEEE standardized
both the Verilog HDL and PLI the way it stood in 1993. No enhancements were considered for
1364-1995. For the PLI, the IEEE chose to standardize both PLI 1.0 and 2.0. The former, to pre-
serve backward compatibility. The latter, because it really was a much better procedural interface.
To allow both the old PLI 1.0 and the incompatible PLI 2.0 standards to be used at the same time,
the IEEE rewrote the PLI 2.0 so that it was backward compatible. As part of that process, the PLI
2.0 routines were renamed to “VPI” (for “Verilog Procedural Interface”).
Note: In the IEEE standard, the terms “PLI 1.0” and “PLI 2.0” do not exist. There is one PLI,
with three libraries, TF, ACC and VPI.
2001: The IEEE 1364-2001 standard
2
. The IEEE spent three years defining a major set of
enhancements to the Verilog standard. These enhancements were ratified early in 2001. The new
Verilog-2001 standard adds a number of powerful enhancements to the Verilog HDL, including:
multi-dimensional arrays, re-entrant tasks, recursive functions, configurations, attributes (which
can replace those annoying synthesis pragmas hidden in comments), and several dozen other use-
ful and important features. For more details on these features, refer to the SNUG San Jose 2001
Conference paper, “Getting the Most out of IEEE 1364-2000 Verilog Standard”
3
.
2.0 Why use the VPI library?
To understand the advantages gained by using the VPI library, we must first look at the strengths
and weaknesses of the older TF and ACC libraries.
2.1 Strengths and weaknesses of the TF library
The TF library can only access the arguments of a system task or function. Due to this limited
access, simulators can predict at compile time exactly what information a PLI application will
access. This allows simulators to highly optimize the simulation data structure. VCS takes full
advantage of this, and achieves its best simulation performance when only the TF library is used.
However, the TF library cannot traverse design hierarchy, analyze design structure, modify
delays, or access RTL code. This greatly limits the types of PLI applications that can be written
with the TF library. Originally, the TF library contained just a few C functions. Over a number of
years, however, the library evolved until it grew to have more than 110 C functions. This growth
occurred with no specification to guide the evolution. As a result, the library is full of inconsisten-
cies and redundancies. The TF library also has a great number of problems with portability to dif-
ferent simulators and different operating systems. Hence PLI applications do not work the same
way on all simulators. In part, this portability problem stems from the fact that the TF library was
originally designed to work with just the Cadence Verilog-XL simulator, in the days of DEC PDP-
11 computers. The TF library does not support many of the new constructs added in the IEEE
1364-2001 standard.
SNUG San Jose 2002 4 Using PLI 2.0 (VPI) with VCS / Stuart Sutherland
2.2 Strengths and weaknesses of the ACC library
The ACC library is an extension to the TF library. It provides access to structural objects within a
simulation data structure. Structural objects include module instances, primitive instances, delays,
net declarations, and variable declarations. The access to structural objects is achieved using rou-
tines which can search for objects. This overcomes the primary limitation of the TF library, which
requires objects to be listed as system task/function arguments. However, the ACC library suffers
from many of the same problems as the TF library. There are well over 100 C functions, with
inconsistent syntax and semantics. The specification and documentation of the ACC library rou-
tines were grossly lacking when the library was first placed in the public domain. This has led to
differences in the way the ACC routines work on different simulators.
The ACC library can arbitrarily access any structural object anywhere within the simulation data
structure. This provides the capabilities needed for SDF back annotation, power analysis, gate-
level logic flow tracing, waveform displays, and a wide variety of commercial and in-house PLI
applications. But, the ACC library is limited to only accessing structural (netlist) based designs.
The ACC library cannot access all types of objects that make up the typical Verilog design. Ver-
ilog procedures, continuous assignments and memory arrays and other components of an RTL
level model are not
accessible by the ACC library, and it cannot access much of what is in a typi-
cal test bench.
Performance is another limitation of the ACC library. The arbitrary access to structural objects
within the simulation data structure means that a simulation compiler cannot predict what will be
accessed, and therefore cannot optimize the data structure as effectively. The run-time perfor-
mance of VCS slows down dramatically if the ACC library is granted full access to the entire sim-
ulation data structure.
The ACC library cannot access many of the new constructs in the IEEE 1364-2001 standard.
2.3 Strengths and weaknesses of the VPI library
The VPI library is a complete superset of the older TF and ACC libraries. It provides the advan-
tages of both libraries, yet strives to eliminate the many disadvantages. The primary advantages
are:
• The VPI library replaces over 220 C functions that are complex, inconsistent and have portabil-
ity problems, with 37 C functions that have a simple, consistent syntax.
• The VPI library provides full access to the RTL and behavioral code within a simulation data
structure.
• The access methods used by the VPI library to find information in the simulation data structure
are architected in such a way that they can be implemented more efficiently in simulators,
(though there is nothing in the standard to compel a simulator to be more efficient).
• The VPI library encourages a more disciplined structured programming style. The way the VPI
library locates objects within the simulation data structure also encourages writing code that is
efficient for simulation performance and memory usage. This is very different than the TF and
ACC libraries, which encourage a very unstructured and highly inefficient programming style.
SNUG San Jose 2002 5 Using PLI 2.0 (VPI) with VCS / Stuart Sutherland
• Verilog-2001 adds over 45 major enhancements to the Verilog HDL. The VPI library was
updated to provide full access to all these new capabilities.
• The VPI library was designed to be able to grow with the Verilog language. When the next gen-
eration of the IEEE Verilog standard comes out, the VPI library will be able support whatever
new capabilities are added to the language.
The last two advantages are critical advantages of the VPI library. The size of designs that engi-
neers are modeling is increasing rapidly. The software tools engineers use must evolve, in order to
be useful on future designs. Verilog has evolved, and will continue to evolve. The IEEE 1364
standards group that oversees the Verilog language long ago determined that it was not logical—
and even impossible—to keep adding to the bloated TF and ACC libraries, with their inconsisten-
cies and compatibility problems. The IEEE standards group is only evolving the VPI library. A
PLI application will only work with the new Verilog-2001 features and whatever comes after Ver-
ilog-2001, if the PLI application is written with the VPI library.
3.0 The nuts and bolts of the VPI
The following subsections explain the basics of how the VPI library works. The purpose of this
explanation is to provide the background necessary to answer the question as to whether the VPI
offers advantages that are compelling enough to use it with VCS.
3.1 The VPI Library
The Verilog-2001 VPI library comprises 37 C functions, with accompanying C structures and
constant definitions. In general, the functions are divided into three categories: those that locate
objects, those that read and modify information about objects, and utility routines for tasks such
as controlling simulation and file I/O.
3.2 Object Handles
The VPI works by obtaining a “handle” to an object. A handle is a pointer to a structure contain-
ing information about the object. In this regard, the VPI works similarly to the ACC routines.
However, the VPI considers virtually every thing that exists in a Verilog model, or within a Ver-
ilog simulation, as an object. The ACC library only considers the structural items of a design as
models, such as nets, primitive instances and module instances.
3.3 Object Diagrams
The IEEE VPI standard provides detailed diagrams showing the relation of each object to other
objects. For example, the diagram for a net object shows all the types of Verilog constructs a net
could be connected to. Using the diagrams, a PLI application developer can easily determine how
to obtain a handle to any specific object. The diagrams also document what information is avail-
able about each object, such as its name, data type or logic value. The figure below illustrates a
sample diagram.
