Verilog programming-language-interface primer

Verilog programming-language-interface primer
by Swapnajit Mittra, SGI -- EDN
Wednesday 21 August 2002
Swapnajit Mittra, SGI -- from EDN, 2/9/1999
Designers have employed HDLs for more than a decade, using them to replace a schematic-based design methodology and to convey design ideas. Verilog and VHDL are the two most widely used HDLs for electronics design. Verilog has approximately 35,000 active designers who have completed more than 50,000 designs using the Cadence Verilog software suite. Even with Verilog's success, many seasoned Verilog users still perceive its programming-language interface (PLI) as a "software task" (Reference 1). A step-by-step approach helps you "break the ice" when writing PLI functions. By learning the essentials of PLI design without getting bogged down by too many details, you will acquire a basic knowledge of PLI that you can immediately use.Why should you use a PLI?A PLI gives you an application-program interface (API) to Verilog. Essentially, a PLI is a mechanism that invokes a C function from Verilog code. People usually call the construct that invokes a PLI routine in Verilog a "system task" or "system function" if it is part of a simulator and a "user-defined task" or "user-defined function" if the user writes it. Because the essential mechanism for a PLI remains the same in both cases, this article uses the term "system call" to indicate both constructs. Examples of common system calls that most Verilog simulators include are $display, $monitor, and $finish.You use a PLI primarily for doing tasks that would otherwise be impossible to do using Verilog syntax. For example, IEEE Standard1364-1995 Verilog has a predefined construct for doing a file write, ($fwrite, which is another built-in system call written using a PLI), but it does not have one for reading a register value directly from a file (Reference 2). More common tasks for which PLI is the only way to achieve the desired results include writing functional models, calculating delays, and getting design information. (For example, no Verilog construct gives the instance name of the parent of the current module in the design hierarchy.)To illustrate the basic steps for creating a PLI routine, consider the problem in Listing 1. This problem is much simpler than a real-life problem you solve using PLI, however it shows many of the basic steps you use to build a PLI routine. When you run the Verilog in the listing, it should print the value of the register as 10 at time 100 and 3 at time 300. You can think of creating a PLI routine as a two-step process: First, you write the PLI routine in C; then, you compile and link this routine to the simulator's binary code.Writing a PLI routine The way a PLI routine interfaces with the simulator varies from simulator to simulator, although the main functions remain the same. This article discusses the interfacing mechanisms of the two most popular commercial simulators, Cadence's Verilog-XL (Reference 3) and Synopsys' VCS (Reference 4). Although other commercial simulators support PLI, their interfacing mechanisms do not differ significantly from these two. Over the years, Verilog PLI has evolved into PLI 1.0 and Verilog Procedural Interfaces (VPI). This article covers only PLI 1.0. Despite the differences in interfacing parts and versions, you can break down the creation of a PLI routine into four main steps.Step 1: Include the header filesBy convention, a C program implements a PLI routine in a file veriuser.c. Although you can change this name, the vconfig tool assumes this default name while generating the compilation script in a Verilog-XL environment. For now, assume that you keep the PLI routine in the file veriuser.c.In a Verilog-XL environment, the file veriuser.c must start with the following lines:#include #include In a VCS environment, the file must start with:#include These header files contain the most basic data structures of the Verilog PLI that the program will use.Step 2: Declare the function prototypes and variables A PLI routine consists of several functions. Just as you would for a normal C program, you should place the prototype declarations for the functions before the function definitions. For this case, the function appears as:int my_calltf(), my_checktf();In the above function, the int prototype declaration implies that these functions return an integer at the end of their execution. If there is no error, the normal return value is 0. However, if the functions are in separate files, you should declare them as external functions with:extern int my_calltf(), my_checktf();A typical PLI routine, like any other C program, may need a few other housekeeping variables. Step 3: Set up the essential data structuresYou must define a number of data structures in a PLI program. A Verilog simulator communicates with the C code through these variables. Open Verilog International (OVI), an organization for standardizing Verilog, recommends only one mandatory data structure, veriusertfs. However, the exact number and syntax of these data structures vary from simulator to simulator. For example, Verilog-XL requires four such data structures and their functions for any PLI routine to work; VCS needs none of them and instead uses a separate input file. The main interfacing data structure for Verilog-XL is an array of structures or a table called veriusertfs. Verilog-XL uses this table to determine the properties associated with the system calls that correspond to this PLI routine. The simulator does not recognize any names other than veriusertfs. Each element of veriusertfs has a distinct function, and you need all these functions to achieve the overall objective of correctly writing the PLI routine. The number of rows in veriusertfs is the same as the number of user-defined system calls plus one for the last entry, which is a mandatory 0. In this case, the veriusertfs array should look like: s_tfcell veriusertfs[] = {{usertask, 0, my_checktf, 0, my_calltf, 0, "$print_reg"},{0} /* Final entry must be zero */}The first entry, usertask, indicates that the system call does not return anything. It is equivalent to procedure in Pascal or function returning void in C. In the previous data-structure, my_ checktf and my_calltf are the names of the two functions that you use to implement the system call $print_reg. These names are arbitrary, and you can replace them with other names. The function my_checktf is generally known as a checktf routine. It checks the validity of the passed parameters. Similarly, my_calltf, which you usually call calltf routine, performs the main task of the system call. The positions of these names in veriusertfs are very important. For example, if you want to use my_checkt for any other name as a checking function, it must be the third element. The function veriusertfs provides options for a few other user-defined functions that you will not use in this routine. A zero replaces any function that you do not use. Therefore, the second, fourth, and sixth elements in the entry are zeroes. Table 1 summarises the objectives of each entry in a row of veriusertfs. If there are additional system calls, you need to define a separate entry in veriusertfs for each one. Verilog-XL also needs the following variables or functions:char *veriuser_version_str;int (*endofcompile_routines[])();bool err_intercept();The first variable, veriuser_version_str, is a string indicating the application's user-defined-version information. A bool (Boolean) variable is an integer subtype with permitted values 0 and 1. In most cases, you can use Cadence-supplied default values for these variables or functions.In VCS, instead of a table, you use the equivalent information in a separate file, which you usually call pli.tab. This name is also user-defined. In the current example using $print_reg, the contents of this file are:$print_reg check=my_checktf call=my_calltfStep 4: The constituent functionsWith the prototype declarations in place, you are ready to write the two functions, my_checktf() and my_calltf(), which constitute the main body of the PLI application.As previously discussed, a checktf routine checks the validity of passed parameters. It is a good practice to check whether the total number of parameters is the same as you expect, and whether each parameter is required. For example, in this case, you expect the program to pass only one parameter of type register. You do this task in the function my_checktf() (Listing 2).The functions starting with tf_ are the library functions and are commonly known as utility routines. The library functions in the previous function and their usage are tf_nump(), which determines how many parameters you are passing, and tf_typep(), which determines the parameter type by its position in the system call in the Verilog code. In this case, the system call is $print_reg. Thus, tf_typep(1) gives the type of the first parameter, tf_typep(2) gives the type of the second parameter, and so on. If the parameter does not exist, tf_typep() returns an error. (In this case, tf_typep(2) does not exist.) In the current example, you expect the program to pass a register value as a parameter. Therefore, the type should be tf_readwrite. If a wire is the expected parameter, the type should be tf_readonly. To facilitate error-condition checking, it is a good idea to first check the number of parameters and then to check their types. The tf_error() function prints an error message and signals the simulator to increment its error count. These library functions and constants are parts of the header files that you have included at the top of the file in Step 1.A calltf function is the heart of the PLI routine. It usually contains the main body of the PLI routine. In this case, it should read the value of the register and then print this value. The following code shows how you can accomplish this job:int my_calltf(){ io_printf("$print_reg: Value of the reg=%x at time=%d\n", tf_getp(1), tf_gettime());}In the above code, io_printf() does the same job as printf() in C, printing the value in standard output. Additionally, the function prints the same information in the Verilog log file. The function tf_getp() gets the register's integer value. The function tf_gettime() returns the current simulation time and needs no input parameter. Calltf is the most complicated function in a PLI routine. It often runs for several hundred lines.Now that you have created the two main functions, you need to put them into one place. Listing 3 shows how to implement $print_reg in a Verilog-XL environment.The next task is making the Verilog simulator understand the existence of your new system call. To accomplish this task, you must compile the PLI routine and then link it to the simulator's binary. Although you can manually integrate the PLI code with the Verilog binary by running a C compiler and merging the object files, it is more convenient to use a script. In Verilog-XL, a program called vconfig generates this script. The default name for this script is cr_vlog. While generating this script, the program vconfig asks for the name of the compiled Verilog that you prefer. It also asks whether to include model libraries, which are PLI code, from standard vendors. For most of these questions, the default answer, which you input if you press return without entering anything, is good enough unless you have a customized environment. At the end, vconfig asks for the path for your veriuser.c files. Once you generate the script cr_vlog, you need only to run the script to generate a customized Verilog simulator that can execute the new system call.A sample run of the compiled Verilog using this PLI routine produces the output with a Verilog-XL simulator (Listing 4).Modifying the value of a registerYou use a PLI is to read design information and to modify this information in the design database. The following example shows how you can do this modification. Create a system call, $invert, to print the value of a register (as in the previous example), bitwise invert the content, and print this updated value. Many ways exist to invert a value of a binary number. By using a straightforward algorithm to do the inversion, as the following list shows, helps you gain more insight into the PLI mechanism and library functions: 1. read the content of the register as a string;2. convert all ones in the string to twos, convert all zeros to ones, convert all twos to zeros, convert all Z's to X's, and leave X's intact; and3. put the modified string back into the register.The second step converts all ones to zeros and zeros to ones. Note that the checktf function in this case does not differ from the earlier one, because in both cases the number and type of input parameter are the same.Creating the PLI routineListing 5 shows the implementation of $invert routine in a VCS environment. This program uses the following library functions:tf_strgetp() returns the content of the register as a string. Just liketf_getp(), it reads the register's content as a decimal. In Listing 5, tf_strgetp(1, b) reads the content of the first parameter in binary format. (An h or o, in place of a b, read it in hexadecimal or octal format, respectively). The routine then copies the content to a string val_string.tf_strdelputp() writes a value to a parameter from a string-value specification. This function takes a number of arguments, including the parameter index number (the relative position of the parameters in the system call, starting with 1 for the parameter on the far left); the size of the string whose value the parameter contains (in this case, it should be same size as the register); the encoding radix; the actual string; and two other delay-related arguments, which you ignore by passing zeros for them. Although not shown in the current example, a simpler decimal counterpart of tf_strdelputp() is tf_putp().It is important to remember that a program can change or overwrite only the value of certain objects from a PLI routine. Any attempt to change a variable that you cannot put on the left of a procedural assignment in Verilog, such as a wire, results in an error. In general, you can modify the contents of a variable of type tf_readwrite. The checktf function my_checktf() checks this feature.One additional user-defined function that Listing 5 uses is move(), which has three parameters. In the third parameter, a string, the second parameter replaces every occurrence of the first parameter. In the current case, a series of calls to move() changes the zeros to ones and ones to zeros. However, once a program converts zeros to ones, you must distinguish the converted ones in the string from the original ones. To make this distinction, the program first changes all initial ones to twos. A two is an invalid value for binary logic, but you can use it in an intermediate step for this example. At the end, the program converts all twos back to zeros. The program completes its task by putting the inverted value back into the register using the tf_strdelputp() function.Listing 6 shows a sample Verilog program containing the call $invert. In a VCS environment, a file lists the functions associated with a PLI routine. Although this file can have any name, you usually call it pli.tab. This file is equivalent to the veriusertfs[] structure in Verilog-XL. The content of this file in the current example is:$invert call=invert_calltf check=my_checktfBy saving this program in the file test.v, you generate an executable binary pli_invert with the command:$ vcs -o pli_invert -P pli.tab test.v veriuser.cExecuting pli_invert, you get:
= 0 navigator.userAgent.indexOf("MSIE") >= 0) {
document.write('');}
// -->

$invert: Modifying the content from 00001111 to 11110000 at time 100$finish at simulation time 200You now know the basic structure of a PLI routine and the mechanism of linking it to build a custom version of Verilog. You can also read, convert, and modify the values of the elementary components of a design database in Verilog through a PLI routine and read the simulation time for the routine. These tasks are the basic and often most necessary ones for a PLI routine to carry out. Considering all that PLI offers, this information is just the tip of the iceberg. You can also use a PLI to access design information other than register contents. (For more information about Verilog and C modeling, see References 5 and 6.) A short history of Verilog PLI Verilog started as a proprietary product from Gateway Design Automation, a company that Cadence subsequently bought. According to people close to the project at the time, the requirements for a programming-language interface (PLI) in Verilog came up early during designs. One of the problems facing them was that a single workstation could not cope with the simulation load of an entire design. The need for load balancing among multiple workstations soon became a necessity. Designers used a PLI as a tool to solve this problem.People designed the first generation of PLI routines, called TF or tf_ routines, to work only with the parameters passed to them. It was soon apparent that you could not pass all design parameters as software parameters. For example, you could not pass a delay path between two modules as software parameter. As a result, more sophisticated versions of PLI-library functions emerged. These functions, known as access or ACC/acc_ routines, focused PLI attention to cover a variety of design objects while keeping the user interface as simple as possible. Access routines did a good job, but, for keeping the user interface simple, the interface was inconsistent. In 1995, Cadence came up with the third generation of PLI for Verilog, the Verilog Procedural Interface (VPI). All three generations of PLI are part of IEEE Standard 1364-1995.

Verilog coding examples chapters

http://iroi.seu.edu.cn/books/asics/Book/CH11/CH11.07.htm

8 Cs of Knowledge Management

http://www.techsparks.com/The-8-Cs-of-KM-success-Learning-from-the-IT-sector.html

writing PLI

http://www.asic-world.com/verilog/pli2.html#Writing_PLI_Application

Re-Use of Verification Environment for Verification of Memory Controller

Re-Use of Verification Environment for Verification of Memory Controller
Aniruddha Baljekar, NXP Semiconductors India Pvt. Ltd.
Bangalore, INDIA

Abstract:

With the complexity of the design on the rise, coverage of functional verification is one of the increasing challenges faced by the design and the verification teams. Reducing the verification time without compromising the quality of the verification is the greatest challenge to the verification engineers. Improving the verification process is highly critical to improve upon time to market. To achieve this, re-use of the verification environment across different levels is the way forward. The re-use of the verification environment can be achieved at following levels:


Reuse with different IPs
Reuse at different levels of integration
Reuse at different levels of abstraction (SystemC (PV/PVT), RTL)
The paper covers the following:

Methodology adopted to address the re-use of the test environment/testbench at unit level across testing of highly abstract level models (modeled in SystemC) and RTL models (modeled in VHDL/Verilog)
Methodology and challenges faced towards unit level verification of complex TLM (SystemC) model (memory controllers: external static memory controller and external nand flash controller) using this re-use methodology
Methodology in creating verification IP’s to provide interfaces to enable its re-use at these different levels of abstraction
Following tools are used in this methodology:

Specman Elite as the functional verification tool which supports coverage driven verification methodology
vManager for plan driven verification
Scenario builder to create specific scenarios.
eVCs as the verification IP’s
1. Introduction

The paper describes the methodology on re-use of unit level verification framework across different levels of abstraction. It also mentions about how to create a new eVC or extend an existing eVC to provide TLM interface. Inputs to this paper are based on the experience from verification of the memory controller (re-using the RTL verification components in verification of the TLM model).

2. Motivation

Re-use of the coverage driven verification framework and environment is very important to reduce the time taken for verification. With challenges to build a TLM model in line with the time to market, it is very important to reduce the time taken to create the model and validate the model without compromising the quality. At present in NXP there are portfolio IP’s available at RTL for which the SystemC TLM models are being developed. Lots of effort has gone in the verification these RTL IP’s. If there is a possibility to reuse the testbenches developed for RTL verification in the verification of the TLM models, then the time required to verify the TLM models can be reduced. In the near future, the SystemC TLM models will be developed much before the RTL models. In this case the testbenches developed to verify SystemC TLM models can be re-used and extended for the verification of the RTL models. Re-use of the verification framework across the various abstraction levels is extremely important to reduce the total development time.

3. Technical Details

The main expectations from such a re-use approach can be categorized into:

High Level:

Reuse of the existing RTL verification environment to verify SystemC model
Minimum bring up time of verification framework
Common methodology towards creation of re-usable verification framework for all groups and environments
Technical view:

Reuse existing Specman sequences, monitors, scoreboard and other eRM compliant verification components from the RTL verification environment
Clear methodology to support RTL and SystemC models
3.1 Verification Environment Overview



3.1.1 Recommendations in creating re-usable Module eVC

The following requirements are essential for Module eVC re-use:

No interference between eVCs
Common look and feel, similar activation and similar documentation
Support for combining eVCs (control, checking, layering etc.)
Support for modular debugging
Commonality in implementation
Avoid using too many output messages
Avoid using too many parallel threads
Avoid sampling events at @sys.any
Use list resize() for large lists
Use Keyed list for better memory performance
Use str_join() instead of append() for large strings
3.1.2 Integrating Module eVCs into an SVE

All eVCs and connections between them are created during generation. Best known practice of generating and connecting eVCs is discussed to address following issues.

Decide when to use pointers and when to use ports
Resolve generation issues such as :
Generation order
Connecting cross pointers
To connect eVCs with pointers:

In the system eVC, define the pointers from the system eVC to the interface eVCs
Avoid pointers in the opposite direction. The interface eVC should be independent of the system eVCs associated with it
In the SVE instantiate the eVCs
In both the eVCs and the SVE, connect the pointers procedurally
The pointers between eVCs are connected procedurally after generation of the architecture. The connect_pointers() method is activated in a top-down fashion. The method is called automatically after all units have been generated and the pointers of the parent unit have been connected by the parent unit’s connect_pointers() method
3.1.3 Configuration Re-usability

The eVC configuration is a reusable aspect that must be encapsulated with the eVC. When an eVC becomes part of a system, some of its configuration is fixed according to the specific use in the system.

Each level in the unit hierarchy can have a configuration struct. Configuration is always projected top down, typically using constraints from the parent.

The configuration of a component depends only on the configuration of the parent environment.

If the configuration of siblings is mutually dependent, the dependency must be generated in the parent environment and propagated down to the siblings.

The key of configuration reusability is determining what elements of the configuration are reusable when the system becomes part of a bigger system. The elements that are reusable should be part of the eVC itself. The non-reusable configuration elements go into the SVE configuration file

3.1.4 Reusing sequences

Reusing sequences from the various components of the environment saves effort when building the verification environment. SoC environments typically require synchronization of the input of several agents. Virtual Sequence is the solution for providing synchronization on SoC level verification.

Multi channel sequence generation can be defined as follows:

Ensure that each of the agents has its own sequence (and sequence driver)
Define a new (virtual) sequence (and sequence driver) using the sequence statement and omitting the item parameter
Add the existing sequence drivers as fields of the new sequence driver
Pass the existing sequence drivers using constraints to the BFM sequences done by the virtual sequence.
A virtual sequence driver is always instantiated at the SVE level. Its primary role is to drive coordinated scenarios involving multiple inputs to the system. These scenarios are built from reusable sequences from the lower-level eVCs. Virtual sequence drivers from the module level can be reused (instantiated) on the system level. These sequence drivers are:

Defined in module eVCs
Instantiated in the SVE of the module eVC (as a usage example)
Reused by instantiating in a system SVE
Module-level sequences are not always reusable on the system level. In general, mixing random sequences can break a design. For example, inputs that are accessible at module level might not be accessible at system level.

3.1.5 Additional recommendations

Create a uRM compliant top-level verification framework for it to be re-usable at different levels of abstractions (RTL and TLM)
Create test sequences using virtual sequences. Virtual sequences, unlike BFM sequences, are not tightly connected to a specific sequence type or item. Virtual sequences can do sequences of other types (but not items). As a result, one can use virtual sequences to drive more than one agent and models a generic driver. These virtual sequences can be easily connected to the driver of the Module eVC
Use ports for getting the internal state of the DUT. Do not use ‘tick defines to probe into the design. In case ‘tick defines is absolutely required, provide an option to switch off this tick defines when the DUT is SystemC. ‘tick defines in the code result in error during the creation of the stub e.g. sync true ( '~/ip_xxx_tb_testbench_full/pwr_c_sys_ack'== 0)
Use backpointers to units to access any object instantiated in the verification environment. Avoid using “sys.