Verdi Interoperability Apps (VIA)Verdi Interoperability Apps (VIA) 1 About This Book Purpose This...

VerdiInteroperability

Apps (VIA)Novas Programming Interface (NPI)

Synopsys, Inc.

VersionThis manual supports the Verdi3TM Automated Debug Platform 2013.07 and higher versions. You should use the documentation from the version of the installed software you are currently using. This manual was printed on July 3, 2013.

Copyright and Proprietary Information Notice(c) 2013 Synopsys, Inc. All rights reserved. This software and documentation contain confidential and proprietary information that is the property of Synopsys, Inc. The software and documentation are furnished under a license agreement and may be used or copied only in accordance with the terms of the license agreement. No part of the software and documentation may be reproduced, transmitted, or translated, in any form or by any means, electronic, mechanical, manual, optical, or otherwise, without prior written permission of Synopsys, Inc., or as expressly provided by the license agreement.

Third-Party Software NoticesVerdi3TM Automated Debug Platform includes or is bundled with software licensed to Synopsys under free or open-source licenses. For additional information regarding Synopsys’s use of free and open-source software, refer to the third_party_notices.txt file included within the /doc directory of the installed Verdi software.

Destination Control StatementAll technical data contained in this publication is subject to the export control laws of the United States of America. Disclosure to nationals of other countries contrary to United States law is prohibited. It is the reader’s responsibility to determine the applicable regulations and to comply with them.

DisclaimerSYNOPSYS, INC., AND ITS LICENSORS MAKE NO WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, WITH REGARD TO THIS MATERIAL, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

TrademarksSynopsys and certain Synopsys product names are trademarks of Synopsys, as set forth at http://www.synopsys.com/Company/Pages/Trademarks.aspx.All other product or company names may be trademarks of their respective owners.Synopsys, Inc.700 E. Middlefield RoadMountain View, CA 94043www.synopsys.com

http://www.synopsys.com/Company/Pages/Trademarks.aspxhttp://www.synopsys.com

Contents

ContentsAbout This Book 1

Purpose ...............................................................................................................1Audience .............................................................................................................1Book Organization..............................................................................................2Related Publications ...........................................................................................2

NPI Usage 3

Use NPI Models in C/C++..................................................................................3Use NPI Model in Tcl.......................................................................................11Use NPI Libraries in C/C++ .............................................................................13Use NPI Libraries in Tcl...................................................................................19

NPI Language - SystemVerilog Model 23

Overview...........................................................................................................23API Reference...................................................................................................24Object Diagram.................................................................................................25Quick Start ........................................................................................................32Header File........................................................................................................39

NPI Netlist Model 41

Overview...........................................................................................................41Introduction to Netlist Object Model................................................................41API Reference...................................................................................................51Object Diagram.................................................................................................52Special Topics...................................................................................................62Header Files ......................................................................................................62

NPI Text Model 63

Overview...........................................................................................................63API Reference...................................................................................................63Object Diagram.................................................................................................64Using NPI Text Model in C/C++ Programming ..............................................65Using NPI Text Model in Tcl Programming ....................................................67Text Word Attribute (TWA) Types..................................................................69

Verdi Interoperability Apps (VIA) i

Contents

Header File........................................................................................................69Support and Limitations ...................................................................................69

NPI Design Manipulation (DM) Model 71

Overview...........................................................................................................71API Reference...................................................................................................71Object Diagram.................................................................................................74Data Types ........................................................................................................81Examples...........................................................................................................95Header File......................................................................................................100

NPI FSDB Model 101

Overview.........................................................................................................101API Reference.................................................................................................101Traverse Model...............................................................................................104Data Types ......................................................................................................109General Flow in FSDB Model........................................................................114Support and Limitations .................................................................................120

NPI Model APIs 121

Required Models.............................................................................................121Language Model .............................................................................................126Netlist Model ..................................................................................................183Text Model......................................................................................................235Design Manipulation (DM) Model .................................................................300FSDB Model ...................................................................................................477

Object Diagrams 581

Language Model .............................................................................................581Netlist Model ..................................................................................................671Text Model......................................................................................................688Design Manipulation (DM) Model .................................................................693

NPI Libraries 755

Overview.........................................................................................................755API Reference.................................................................................................755Use NPI Libraries ...........................................................................................786Header Files ....................................................................................................786

NPI Library APIs 787

ii Verdi Interoperability Apps (VIA)

Contents

Connection......................................................................................................787Find .................................................................................................................874FSDB Library .................................................................................................904Hierarchy Tree ................................................................................................960List ................................................................................................................1015Miscellaneous ...............................................................................................1026Module..........................................................................................................1059Netlist Library...............................................................................................1127Signal ............................................................................................................1170Utilities .........................................................................................................1271

Appendix A: Support Summary 1311

Language Model ...........................................................................................1311Netlist Model ................................................................................................1349

Appendix B: Text Word Attribute (TWA) Types 1359

Introduction...................................................................................................1359

Appendix C: Header Files for C/C++ APIs 1363

npi.h ..............................................................................................................1363npi_type.h .....................................................................................................1363npi_hdl.h .......................................................................................................1364npi_nl.h .........................................................................................................1373npi_text.h ......................................................................................................1377npi_dm.h .......................................................................................................1379npi_fsdb.h .....................................................................................................1413npi_L1_type.h...............................................................................................1415npi_L1.h........................................................................................................1417npi_ic.h .........................................................................................................1431

Appendix D: Netlist Model 1433

Special Topics...............................................................................................1433Special Topic APIs .......................................................................................1443

Appendix E: Language Model 1451

Example 1 .....................................................................................................1451Example 2 .....................................................................................................1453

Appendix F: KP&L 1457

Verdi Interoperability Apps (VIA) iii

Contents

Text Model Limitations ................................................................................1457FSDB Model Limitations .............................................................................1459

iv Verdi Interoperability Apps (VIA)

About This Book: Purpose:

About This Book

PurposeThis book explains how to use the Novas Programming Interface (NPI). The NPI provides an interface layer to let users access the knowledge database contained in the Verdi3TM Automated Debug Platform. Users can use the interface to create their own customized utilities. Both Tcl commands and C APIs are available in NPI.

NPI consists of two levels - NPI Models and NPI Libraries.

AudienceThe audience for this manual includes engineers who are familiar with languages and tools used in design and verification such as Verilog, VHDL, and SystemVerilog.

This document assumes that you have a basic knowledge of the platform on which your version of the Verdi platform runs: UNIX or Linux and that you are knowledgeable in C/C++ and Tcl.

Verdi Interoperability Apps (VIA) 1

About This Book: Book Organization:

Book OrganizationThis Verdi Interoperability Apps (VIA) document is organized as follows:

• About This Book provides an introduction to this book and explains how to use it.• Usage provides details on how to use the NPI with C/C++ and Tcl.• NPI Language - SystemVerilog Model provides details on using the SystemVerilog

language model for NPI.• NPI Netlist Model provides details on using the Netlist model for NPI.• NPI Text Model provides details on using the Text model for NPI.• NPI Design Manipulation Model provides details on using the Design Manipulation

model for NPI.• NPI FSDB Model provides details on using the FSDB model for NPI.• NPI Model APIs provides details on using the APIs for each of the NPI models.• Object Diagrams provides details on the Object Diagrams for each of the NPI models.• NPI Libraries provides details on using the NPI libraries.• NPI Library APIs provides details on using the APIs for the NPI library.• Appendix A provides details on types, methods and properties for the different NPI

models.• Appendix B provides details on text word attribute types.• Appendix C lists the header files for C/C++ APIs.• Appendix D provides details on special topics for the Netlist model.• Appendix E provides examples for the Language model.• Appendix F provides a list of known problems and limitations for different NPI

models.

Related Publications• Verdi3 and Siloti Tcl Reference Manual - gives detailed information on the Verdi and

Siloti Tcl commands.

2 Verdi Interoperability Apps (VIA)

NPI Usage: Use NPI Models in C/C++: Concept: Shared Library - libNPI.so

NPI UsageCurrently, users can work with the NPI models through two kinds of interfaces, one is the Tcl command interface and the other is the C interface. Compared to the C interface, Tcl commands provided by the NPI model can be played in both batch mode (through a command file) and interactive mode (through the Tcl console) when the novas executable is invoked. There is no need to compile an executable. In addition, users can hook their existing application programs through the Tcl interface with the novas executable. However, since Tcl is an interpreted language, the Tcl command interface will have worse performance due to the Tcl interpreter effort. It is recommended that you use the C interface if the application has stringent performance requirements.

Use NPI Models in C/C++

Concept: Shared Library - libNPI.soA shared library - libNPI.so - is provided for NPI programming in C/C++. The library will be loaded by the C/C++ programs when they start.

NPI C-API File StructureThe NPI C-API library is located under the Novas release package: $(NOVAS_INST_DIR)/share/NPI. The NPI directory structure follows:NPI/

L1/inc/lib/

LINUX64_GNU_322/LINUX64_GNU_346/LINUX64_GNU_422/LINUX64_GNU_452/LINUX_GNU_322/LINUX_GNU_346/LINUX_GNU_422/LINUX_GNU_452/

The directory L1/ contains the source code for the NPI Libraries. Refer to the NPI Libraries section for details.


NPI Usage: Use NPI Models in C/C++: NPI C-API File Structure

The directory lib/ contains the shared library - libNPI.so - for each platform and gcc compiler. The directory names “LINUX64_GNU_322, LINUX64_GNU_346, LINUX64_GNU_422, LINUX64_GNU_452, LINUX_GNU_322, LINUX_GNU_346, LINUX_GNU_422, LINUX_GNU_452” identify the platform (LINUX 32 or 64) and the version of the gcc compiler.

The directory inc/ contains the header files (*.h) for the NPI C-API. The file structure of inc/ is as follows:inc/

npi.h (initialization and design import)npi_type.h (basic type definition)npi_hdl.h (C-API for NPI Language model)npi_nl.h (C-API for NPI Netlist model)npi_dm.h (C-API for NPI DM model)npi_text.h (C-API for NPI Text model)npi_fsdb.h (C-API for NPI FSDB model)npi_util.h (C-API for NPI utility - used in NPI Libraries)

The files npi_hdl.h, npi_nl.h, npi_dm.h, npi_text.h, npi_fsdb.h correspond to the NPI models. Refer to the descriptions of those models.

Following is the content of the npi.h and npi_type.h files.

npi.h #ifndef NPI_INC#define NPI_INC/* initialization */int npi_init (int &argc, char** &argv);int npi_end ();int npi_load_design (int argc, char **argv);#endif /* ----- #ifndef NPI_INC ----- */npi_type.h /* ========================================================================== * Filename: npi_type.h * Description: Novas Programming Interface Type Definition * Version: 1.0 * Created: 06/15/11 15:06:32 CST * Revision: none * Company: Synopsys * ========================================================================== */#ifndef NPI_TYPE_H#define NPI_TYPE_Htypedef unsigned long long NPI_UINT64;typedef int NPI_INT32;typedef unsigned int NPI_UINT32;typedef short NPI_INT16; typedef unsigned short NPI_UINT16; typedef char NPI_BYTE8;typedef unsigned char NPI_UBYTE8;typedef enum { NPI_FALSE = 0, NPI_TRUE = 1 } NPI_BOOL;


NPI Usage: Use NPI Models in C/C++: Example

#endif /* ----- #ifndef NPI_TYPE_H ----- */

ExampleFollowing is an example that demonstrates the NPI C/C++ program.

my_program.cpp#include #include “npi.h” // must have for NPI programs#include “npi_hdl.h” // use when you’d like to use NPI Language-SystemVerilog modelusing namespace std;int main(int argc, char** argv) { // initialize NPI L0 models if( !npi_init(argc, argv) ) return 0; // the argc and argv may be different from those in npi_init() if( !npi_load_design(argc, argv) ) return 0; printf(“\n### BEGIN my_program.exe ###\n”); // iterate top instances by NPI Language model // npiHandle, npi_iterate, npi_scan, and npi_get_str are defined in npi_hdl.h npiHandle ref_hdl = NULL; npiHandle itr = npi_iterate(npiInstance, ref_hdl); // npiInstance is a defined symbol in npi_hdl.h npiHandle top_hdl; while(top_hdl = npi_scan(itr)) { const char* topName = npi_get_str(npiName, top_hdl); // npiName is a defined symbol in npi_hdl.h printf(“Top instance: %s\n”, topName); } // end of NPI models npi_end(); printf(“### END my_program.exe ###\n”); return 0;}

The details of the above example are not going to be described. The example just shows how to compile, make, and run the program.

Compile and MakeThe following command shows how to compile my_program.cpp with NPI. Specify the path to the NPI header files (npi.h and npi_hdl.h in this example) after -I.

%> g++ -o my_program.cpp -I$NOVAS_INST_DIR/share/NPI/inc


NPI Usage: Use NPI Models in C/C++: Compile and Make

The following command shows how to make the executable “my_program.exe”. Specify the path of the NPI shared library libNPI.so after -L. Assume the LINUX_GNU_422 platform is used.

%> g++ -o my_program.exe my_program.o -L$NOVAS_INST_DIR/share/NPI/lib/LINUX_GNU_422 -lNPI -ldl -lpthread -lrt

For a well organized compile and make process, it is better to have a Makefile, like the example shown below:

Makefile ## gcc compiler setup#CC = g++CFLAGS= -Wall -gLD = $(CC)LDFLAGS =RM = rm## directory setup for NPI include files and shared library (libNPI.so)#NOVAS_INST_DIR = /qa/mfg/prod/novas2012/novasv201204_0309NPI_PLATFORM = LINUX64_GNU_322NPI_INC = $(NOVAS_INST_DIR)/share/NPI/incNPI_LIB = $(NOVAS_INST_DIR)/share/NPI/lib/$(NPI_PLATFORM)NPI_SO = $(NPI_LIB)/libNPI.so## program setup#EXE = demo_L0.exeSRCS = main.cpp OBJS = ${SRCS:.cpp=.o}## compiling and linking#.SUFFIXES: .o .cpp.cpp.o :

$(CC) $(CFLAGS) -c $< -I$(NPI_INC)all: $(EXE)$(EXE): $(NPI_SO) $(OBJS)

$(LD) -o $@ $(OBJS) -ldl -lpthread -lrt -L$(NPI_LIB) -lNPI @echo “make $(EXE) successful...”

clean:-$(RM) -f $(EXE) $(OBJS)

With the Makefile, it is easy to compile and make my_program.cpp by just typing the “make” command.

%> makeg++ -Wall -g -c my_program.cpp -I/demo/Novas_Pack/novas201204/share/NPI/incg++ -o my_program.exe my_program.o -ldl -lpthread –lrt -L/demo/Novas_Pack/novas201204/share/NPI/lib/LINUX_GNU_422 -lNPI


NPI Usage: Use NPI Models in C/C++: Running the NPI Program

make my_program.exe successful...%>

Running the NPI ProgramSince the NPI program must load the shared library, libNPI.so, when it starts, it is necessary to set the environment variable LD_LIBRARY_PATH to the path of libNPI.so. For example:

%> setenv LD_LIBRARY_PATH /demo/Novas_Pack/novas201204/share/NPI/lib/LINUX64_GNU_422

Then it is acceptable to run the NPI program as follows. %> ./my_program.exe -sv example.v [NPI Init] LD_LIBRARY_PATH = /demo/Novas_Pack/novas201204/share/NPI/lib/LINUX64_GNU_422 [NPI Init] Novas resource directory = /demo/Novas_Pack/novas201204/share/NPI/lib/LINUX64_GNU_422/etc logDir = /my_program.exeLog NPI - Novas Programming Interface, Release 2012.04 (Linux x86_64/64bit) 03/09/2012 Copyright (C) 2009 - 2012 by Synopsys, Inc. Design Path = . Analyzing... source file "example3.v" Linking... 0 error(s), 0 warning(s) Total 0 error(s), 0 warning(s) ### BEGIN my_program.exe ###Top instance: $rootTop instance: BIT2### END my_program.exe ###%>

Basic NPI Program ArchitectureThe following example shows the basic construct of an NPI program:... (include other header files)// 1. include header files for NPI#include “npi.h” // a must-have for NPI programs#include “npi_hdl.h” // use when you’d like to use NPI Language-SystemVerilog model#include “npi_nl.h” // use when you’d like to use NPI Netlist model#include “npi_dm.h” // use when you’d like to use NPI DM model#include “npi_text.h” // use when you’d like to use NPI Text model#include “npi_fsdb.h” // use when you’d like to use NPI FSDB model...int main(int argc, char** argv)


NPI Usage: Use NPI Models in C/C++: Include Files

{// 2. parse the user-specific arguments for the programint npi_argc;char** npi_argv;parse_arguments(argc, argv, npi_argc /*Output*/, npi_argv /*Output*/);// 3. initialize NPI modelsif( !npi_init(npi_argc, npi_argv) ) return 0;// 4. if you’d like to use NPI Language/Netlist/DM/Text model, npi_load_design is a mustif( using_npi_language_or_netlist_or_dm_or_text_model() ) npi_load_design(npi_argc, npi_argv); ... (your NPI procedures)// 5. end of NPI modelsnpi_end();return 0;}

A typical NPI program contains the following 5 sections:

1. Include the NPI header files2. Separate the arguments for NPI from those for your program3. Initialize NPI4. Load the design if necessary5. End NPI

Include FilesThe header file: npi.h should always be included for an NPI program. The other NPI header files should be included based on the models to be used. See the following for the mapping between the header files and the NPI models.

• npi_hdl.h : NPI Language-SystemVerilog model• npi_nl.h : NPI Netlist model• npi_dm.h : NPI Design Manipulation (DM) model• npi_text.h : NPI Text model• npi_fsdb.h : NPI FSDB modelRefer to Appendix C: Header Files for C/C++ APIs for the header file code.

Parsing Arguments in the NPI ProgramTypically, the usage of an NPI program is similar to the following:

%> my_NPI_program.exe


NPI Usage: Use NPI Models in C/C++: Parsing Arguments in the NPI Program

where may include the following common options. Other can be listed by “novas –h”.

are for NPI models. Refer to the following section for details.

Then the user needs to separate user-defined arguments from and . For example, pick up “-input_signal system.i_cpu.i_ALUB.carry_mode” in the following command line.

%> my_program_arg.exe -f run.f -path ./Design -input_signal “system.i_cpu.i_ALUB.carry_mode”

The following code snippet demonstrates how this can be achieved....int main(int argc, char** argv) {// 2. parse the user-specific arguments for the programstring input_signal; // use STL stringint npi_argc = 0;char** npi_argv = (char**) malloc(sizeof(char*)*argc);for(int i=0; i

NPI Usage: Use NPI Models in C/C++: npi_init() and npi_end() : Initialize and Close NPI

...}

As a result, and will be saved in npi_argv and the user-defined option will be saved in the “input_signal” variable.

npi_init() and npi_end() : Initialize and Close NPInpi_init() and npi_end()are used to initialize and end an NPI program. They are required for all NPI models. The arguments (npi_argc and npi_argv) passed to npi_init() are call-by-reference, npi_init() will take the NPI options and only leave the Novas import design options.

npi_load_design() : Loading Designs in the NPI Program

If you want to use the NPI Language-SystemVerilog model, the NPI Netlist model, the NPI DM model, or the NPI Text model, you must call npi_load_design() before using the APIs of those models.

NPI OptionsThe following table lists the current NPI options. They are related to the NPI Netlist model. If not specified, NPI will use the default setting. Refer to the NPI Netlist Model chapter for details.

NPI Options

-npi_nl_rtl_opt ::= opt[+opt]opt ::= DetailRTL | DetailMux | RegocFSM | GenBlock

Specify the RTL configurations in the Netlist model.Default is: “DetailRTL+DetailMux+GenBlock”

-npi_nl_rtl_level Specify the RTL inference level. Default is 100.-npi_nl_symlib

Specify the symbol library name and path. Default is NULL.


NPI Usage: Use NPI Model in Tcl: Concept

Use NPI Model in Tcl

ConceptThe Novas executable itself can act as a Tcl interpreter. The Novas executable can be used to play any Tcl programs. The usage is similar to the following:

%> novas –play my_program.tcl

In addition, the Novas executable includes hundreds of Novas Tcl commands and the NPI commands. Therefore, applications can be created by using these commands in your algorithm. Following is an example of my_program.tcl:puts “Program Name : my_program.tcl”# npi_iterate, npi_scan, npi_get_str, and npi_release_handle are NPI commandsset top_module_iter [npi_iterate -type npiModule -refHandle “”]set top_module_hdl [npi_scan -iterator $top_module_iter]while {$top_module_hdl != “”} { # using “” (null string) for NULL handle set top_module_name [npi_get_str -property “npiName” -object $top_module_hdl] puts $top_module_name npi_release_handle -object $top_module_hdl set top_module_hdl [npi_scan -iterator $top_module_iter]}# following is the Novas Tcl command that will stop the Novas executabledebExit

The program assumes the Novas executable imports the design first. So playing my_program.tcl can be executed as follows:

%> novas –play my_program.tcl -f run.f -path ../Design

where “-f run.f -path ../Design” represents the Novas options for importing the design. Use “novas -h” for details. The program will list all the top module names in the design.

Passing Arguments in your NPI ProgramAlthough the executable can act as a Tcl interpreter, it cannot pass any arguments from the command line. That is, you cannot use the Tcl command $argv in your program for the Novas executable. For example, if you issue the following command to run the program “my_program2.tcl”, Novas will not parse the argument: “-input system.i_cpu.i_ALUB.carry_mode” and thus a run-time error will be given.

%> novas –play my_program2.tcl -f run.f -path ../Design -input “system.i_cpu.i_ALUB.carry_mode”

Novas cannot parse the argument: “-input system.i_cpu.i_ALUB.carry_mode”. Therefore, if the code was written as follows in “my_program2.tcl”:...


NPI Usage: Use NPI Model in Tcl: Passing Arguments in your NPI Program

# the following code cannot be accepted by the Novas executableset my_arg [lindex $argv 7]...The solution is to use a wrapper Tcl to take in the arguments and then pass them to the NPI program using environment variables. This is illustrated with the following example. The tclsh supports the usage of “$argv”.

wrap.tcl #!/usr/local/bin/tclshset my_arg [lindex $argv 1]set env(INPUT_SIG) $my_argexec novas -play my_program2.tcl -f run.f -path ../../demo_gate_design/Design/ &

my_program2.tcl puts “”puts “===============================”puts “Program Name : my_program2.tcl”# get input argument from the environment variable “INPUT_SIG”set input_arg $env(INPUT_SIG)puts “Input : $input_arg”# get the handle of INPUT_SIG, npi_handle_by_name is the NPI commandset hdl [npi_handle_by_name -name $input_arg -scope “”]set file_name [npi_get_str -property “npiFile” -object $hdl]set line_no [npi_get -property “npiLineNo” -object $hdl]puts “ File name : $file_name”puts “ Line no. : $line_no”puts “==============================”# following is the Novas Tcl command that will stop the Novas executabledebExit

The program can be run with the following command. This program will output the file and line number information for the specified object in the design.

%> tclsh wrap.tcl -input "system.i_cpu.i_ALUB.carry_mode"The results will be similar to the following:===============================Program Name : my_program2.tclInput : system.i_cpu.i_ALUB.carry_modeFile name : /demo_gate_design/Design/cpu.vgLine no. : 604==============================


NPI Usage: Use NPI Libraries in C/C++: Overview

Use NPI Libraries in C/C++

OverviewThe NPI Libraries package can be found in two places: the VIA Exchange website and the Novas package ($NOVAS_INST_DIR/share/NPI/L1/C/). The following introduces how to install the NPI Libraries package from both sources.

Install NPI Libraries from the Novas PackageThe NPI Libraries package is located at the directory $NOVAS_INST_DIR/share/NPI/L1/C/ in the Novas package. It is fine to copy the entire directory to a suitable location.

Install NPI Libraries from the VIA Exchange websiteAfter downloading the NPI Libraries package from http://www.via-exchange.com/download/, decompress the file and place the “C” directory in a suitable location. For example:

%> tar zxvf ......%> mv C /C_app/%> ls /C_app/Cinc/ Makefile Makefile.include obj/ src/%>

As the example shows, the npiL1 library is now under the directory /C_app/C.

Using the NPI LibrariesThe “Makefile” file under npiL1/ will go into the src/ directory and make the object file for each NPI Libraries category. The inc/ directory contains the header file: “npi_L1.h”, which defines the NPI Libraries APIs for use.

The file “Makefile.include” specifies the variables for compiling npiL1. The following shows the content of “Makefile.include”:

## define NOVAS_INST_DIR && NPI_PLATFORM#NOVAS_INST_DIR = USER_DEFINED_NOVAS_INST_DIRNPI_L0_INC = $(NOVAS_INST_DIR)/share/NPI/inc## General variables setting#


http://www.via-exchange.com/download/http://www.via-exchange.com/download/


CXX = g++# CXXFLAGS =NPI_CXXFLAGS = -Wall -gNPI_RM = rm -rfNPI_CP = cp -f

Modify the Variables “NOVAS_INST_DIR”, “CXX”, and “NPI_CXXFLAGS” for your make Environment

The following shows the basic steps for using NPI Libraries:

1. In your C/C++ program, include the file “npi_L1.h”.#include “npi_L1.h”...// then your applications can use the APIs in NPI Libraries...

The following shows an example that uses the NPI Libraries API, npi_mod_define_dump_fileName_lineNo, to dump the file name and line number of a specific module definition:#include #include “npi.h” // header for NPI Models: npi_init, npi_load_design, npi_end#include “npi_L1.h” // header for NPI Librariesint main(int argc, char** argv){// initialize NPI and load design// Novas loading design options are contained in argc, argvnpi_init(argc, argv);npi_load_design(argc, argv);// dump file name and line number for the module definition “MOD”// into the file “output.log”FILE* pFile = fopen(“output.log”, “w”);npi_mod_define_dump_fileName_lineNo(“MOD”, pFile);fclose(pFile);// leaving NPInpi_end();return 0;}

2. Compile and make. Since NPI Libraries is written using NPI Models, the compile and make steps for NPI Models are necessary. Refer to Use NPI Models in C/C++ to learn more about how to compile and make NPI programs.

The following shows the Makefile for the above example “demo.cpp”:## gcc compiler setup#



CC = g++CFLAGS = -Wall -gLD = $(CC)LDFLAGS =RM = rm## directory setup for NPI include files and shared library (libNPI.so)#NOVAS_INST_DIR = /demo/Novas_Pack/novas201110NPI_PLATFORM = LINUX_GNU_422NPI_INC = $(NOVAS_INST_DIR)/share/NPI/incNPI_LIB = $(NOVAS_INST_DIR)/share/NPI/lib/$(NPI_PLATFORM)NPI_SO = $(NPI_LIB)/libNPI.soNPI_L1_DIR = /C_app/CNPI_L1_INC = $(NPI_L1_DIR)/inc## program setup#EXE = demo.exeSRCS = demo.cpp OBJS = ${SRCS:.cpp=.o}## compiling and linking#.SUFFIXES: .o .cpp.cpp.o :$(CC) $(CFLAGS) -c $< -I$(NPI_INC) –I$(NPI_L1_INC)all: $(EXE)$(EXE): $(NPI_SO) $(OBJS) install_npiL1$(LD) -o $@ $(OBJS) $(NPI_L1_DIR)/obj/*.o -ldl -lpthread -lrt -L$(NPI_LIB) -lNPI@echo “make $(EXE) successful...”install_npiL1: $(NPI_SO)cd $(NPI_L1_DIR); makeclean:-$(RM) -f $(EXE) $(OBJS)

In the Makefile, the variable “NPI_L1_DIR” describes the location of NPI Libraries. The symbol “install_npiL1” will go to $NPI_L1_DIR and make all the object files of the NPI Libraries library. The variable “NPI_L1_INC” is used to specify the path of the include file “npi_L1.h”. Finally, link the object files in “$NPI_L1_DIR/obj/” with users’ ones to make the executable. Modify the Makefile to match your environment requirement.

Assume the design example.v is as below:module MOD(a, b);input a;output b;endmodulemodule TOP;wire w1, w2;


NPI Usage: Use NPI Libraries in C/C++: Example

MOD inst(w1, w2);endmodule

The following shows the results of running demo.exe on the design example.v.%> ./demo.exe -sv example.vlogDir = ./demo.exeLogNPI - Novas Programming Interface, Release 2011.10_RD (Linux x86_64/64bit) 08/11/2011Copyright (C) 2009 - 2012 by Synopsys, Inc.Path = .Analyzing...source file "example.v"Linking... 0 error(s), 0 warning(s)Total 0 error(s), 0 warning(s)%> cat output.logMOD, {example.v : 1}%>

ExampleThe following is an example that uses the NPI Libraries Module library. Assuming a hierarchical scope is specified by the option “-mod_scope”, the program will list all the nets in the scope and check whether a net is used in a continuous assignment. If so, the corresponding file name and line number will be printed.

demo_module_L1.cpp#include #include #include #include "npi.h" // header for NPI Models: npi_init, npi_load_design, npi_end#include “npi_util.h”#include "npi_L1.h" // header for NPI Libraries//// Usage: demo_module_L1.exe -mod_scope "scope_hier_name"

//int main(int argc, char** argv){//// 1. parse the input argument, get mod_scope//string mod_scope;npiArg arg = npi_arg_construct(argc, argv);if( npi_arg_has_attr(arg, "-mod_scope") ) {mod_scope = npi_arg_attr_get_value(arg, "-mod_scope", 1/*position*/);npi_arg_remove_attr(arg, "-mod_scope");}else {printf("Usage: demo_module_L1.exe -mod_scope \"scope_hier_name\" \n");return 1;}//// 2. initialize NPI and load design



// the argument is obtained from npiArg after removing the attribute "-mod_scope"//int new_argc = npi_arg_get_argc(arg);char** new_argv = npi_arg_get_argv(arg);npi_init(new_argc, new_argv);npi_load_design(new_argc, new_argv);printf("Input module instance = %s\n", mod_scope.c_str());//// 3. get module instance net handle by NPI Libraries Module Library//vector net_hdl_vec;npi_mod_inst_get_net((char*)mod_scope.c_str(), net_hdl_vec);//// 4. iterate all net handle//printf("\nNet and used continuous assignment:\n");for(int i=0; i


After “demo_module_L1.cpp” is compiled into “demo_module_L1.exe”, the results of running it look like the following:

%> ./demo_module_L1.exe -mod_scope "TOP.inst" -sv example3.vlogDir = ./demo_module_L1.exeLogNPI - Novas Programming Interface, Release 2011.10_RD (Linux x86_64/64bit) 08/23/2011Copyright (C) 2009 - 2012 by Synopsys, Inc.Design Path = .Analyzing...source file "example3.v"Linking... 0 error(s), 0 warning(s)Total 0 error(s), 0 warning(s)Input module instance = TOP.instNet and used continuous assignment:0) w1Continuous assign: example2.v (7)1) w2Continuous assign: example2.v (8)2) w3Continuous assign: example2.v (8)Continuous assign: example2.v (9)3) w4Continuous assign: example2.v (9)%>


NPI Usage: Use NPI Libraries in Tcl: Overview

Use NPI Libraries in Tcl

OverviewThe NPI Libraries package can be found in two places: the VIA Exchange website and the Novas package ($NOVAS_INST_DIR/share/NPI/L1/TCL/). The following introduces how to install the NPI Libraries package from both sources.

Install NPI Libraries from the Novas PackageThe NPI Libraries package is located at the directory $NOVAS_INST_DIR/share/NPI/L1/TCL/ in the Novas package. It is fine to copy the entire directory to a suitable location.

Install NPI Libraries from the VIA Exchange websiteAfter downloading the NPI Libraries package from http://www.via-exchange.com/download/, decompress the file and place the “TCL” directory in a suitable location. For example:

%> tar zxvf ......%> lsTCL/%> move TCL /my_app/%> ls /my_app/TCLnpi_L1.tcl src/%>

As the above example shows, the npiL1 library is now under the directory /my_app/TCL.

Using the NPI LibrariesTo use NPI Libraries, you just need to source the file “npi_L1.tcl” at the beginning of your Tcl program. For example:

source /my_app/TCL/npi_L1.tcl...# then your applications can use the API in NPI Libraries...

Setting an environment variable for the path of NPI Libraries is also recommended, for example:

%> setenv NPIL1_PATH /my_app/TCL Then in any of your applications, you just need to source npi_L1.tcl as follows:


http://www.via-exchange.com/download/http://www.via-exchange.com/download/

NPI Usage: Use NPI Libraries in Tcl: Example

source $env(NPIL1_PATH)/npi_L1.tcl...# then your applications can use the API in NPI Libraries...

The following shows an example that uses the NPI Libraries API, npi_mod_define_dump_fileName_lineNo, to dump the file name and line number of a specific module definition:

# invoke NPI Librariessource $env(NPIL1_PATH)/npi_L1.tcl# dump file name and line number of the module definition “MOD”# into the file “output.log”set file_handle [open “output.log” “w”]::npi_L1::npi_mod_define_dump_fileName_lineNo MOD $file_handleclose $file_handle# leaving NovasdebExit

Assume the design example.v is as follows:module MOD(a, b);input a;output b;endmodulemodule TOP;wire w1, w2;MOD inst(w1, w2);endmodule

Then you can use Novas executable to run the script demo.tcl. (If you are not familiar with NPI usage, refer to Use NPI Model in Tcl to learn more.)

%> novas -sv example.v -play demo.tcl

“output.log” will look like:%> cat output.logMOD, {example.v : 1}%>

ExampleThe following is an example that uses the NPI Libraries Module library. Assuming a hierarchical cope is specified by the environment variable “$MOD_SCOPE “, the script will list all the nets in the scope and check whether a net is used in a continuous assignment. If so, the corresponding file name and line number will be printed.

demo_module_L1.tcl# use NPI Librariessource $env(NPIL1_PATH)/npi_L1.tcl



# input : module instance hierarchical name in $env(MOD_SCOPE)if { [info exists ::env(MOD_SCOPE)] == 0 } {puts "Please specify the environment variable: \"MOD_SCOPE\""puts " for the input name of module instance hierarchical"debExit}puts "Input module instance = $env(MOD_SCOPE)"set mod_scope $env(MOD_SCOPE)# get module instance net handle in NPI Libraries Module libraryset net_hdl_list {}set net_num [::npi_L1::npi_mod_inst_get_net $mod_scope net_hdl_list]# iterate all net handleputs ""puts "Net and used continuous assignment:"for { set i 0 } { [expr $i < $net_num ] } { incr i } {set net_hdl [lindex $net_hdl_list $i]puts "$i) [npi_get_str -property npiName -object $net_hdl]"# get the continuous assignment from the net handleset iter_hdl [npi_iterate -type npiUse -refHandle $net_hdl]while { [set cont_assign_hdl [npi_scan -iterator $iter_hdl]] != "" } {if { [npi_get_str -property npiType -object $cont_assign_hdl] == "npiContAssign" } {set fileName [npi_get_str -property npiFile -object $cont_assign_hdl]set lineNo [npi_get -property npiLineNo -object $cont_assign_hdl]puts " Continuous assign: $fileName ($lineNo)"}}}# leave NovasdebExit

Following is a design example:module MOD;wire w1;wire #10 w2;wire #12 w3;wire w4;assign #(2+2) w1 = 1;assign {w2, w3} = 2'b01;assign w4 = w3;endmodulemodule TOP;MOD inst();endmodule

Assume the input is “TOP.inst”; then running demo_module_L1.tcl looks like:%> setenv MOD_SCOPE “TOP.inst”%> novas -sv example_design.v -play demo_module_L1.tcllogDir = ./novasLogNovas Release 2011.10_RD (Linux x86_64/64bit) 08/23/2011Copyright (C) 2009 - 2012 by Synopsys, Inc.All Rights Reserved.www.synopsys.comThis computer program constitutes or contains trade secrets and confidential information of Synopsys, Inc. or its licensors. This computer program is protected by copyright law and international treaties.



rcfile = ./novas.rcInput module instance = TOP.instNet and used continuous assignment:0) w1Continuous assign: example_design.v (7)1) w2Continuous assign: example_design.v (8)2) w3Continuous assign: example_design.v (8)Continuous assign: example_design.v (9)3) w4Continuous assign: example_design.v (9)%>


NPI Language - SystemVerilog Model: Overview:

NPI Language - SystemVerilog Model

OverviewNPI Language - SystemVerilog Model lets users traverse designs from the HDL language (SystemVerilog) perspective. Every construct in the language will be regarded as an object. The IEEE Std 1800 -2009 SystemVerilog Language Reference Manual (LRM) is applied as the foundation of this model. Most of the object model diagrams are similar to VPI Object Model Diagram in LRM Chapter 37.

Refer to the API Reference section to see all the APIs that are used in the Language Model. Refer to the Object Diagram section to understand the HDL language structure and to learn how to traverse designs via the Language Model.

Refer to the Language Model section of Appendix A for the List of All Types, Methods, and Properties and the Complete Supported List.


NPI Language - SystemVerilog Model: API Reference:

API ReferenceThe following are the APIs available in the NPI Language Model.

The header file (used in C/C++).

typedef void* npiHandle The data type of the object (used in C/C++).

npi_handle_by_name Get a handle to an object with a specific name.

npi_handle Obtain a handle to an object with a one-to-one relationship.

npi_iterate Obtain an iterator handle to objects with a one-to-many relationship.

npi_scan Scan the SystemVerilog hierarchy for objects with a one-to-many relationship.

npi_release_handle Release a handle and its associated resources allocated by NPI Language routines.

npi_get Get the value of an integer or Boolean property of an object.

npi_get_str Get the value of a string property of an object.

npi_get_value Retrieve the value of the parameter object and literal.

npi_compare_objects Compare two handles to determine whether they refer to the same object.

npi_handle_by_index Get a member handle to an object by its parent handle and a specified index number.

npi_handle_by_range Get a part-select handle to an object by the handle that covers it and a specified range.

npi_objects_overlap Check if two handles overlap physically.

npi_set_permanent_handle Set the handle as “permanent” which can not be released until npi_release_all_handles is called.

npi_release_all_handles Release all the handles and their associated resources allocated by NPI Language routines.


NPI Language - SystemVerilog Model: Object Diagram: Abstract

Object Diagram

AbstractAll possible relationships and properties that an object might have are documented in the form of object diagrams, which use enclosures to represent objects and arrows to represent the type of relationship. The properties of the object are listed below the diagrams. The following lists all the supported types of the object diagram.

Object Category Names in Object Diagram Object Types or Tags

Module module npiModuleInterface interface npiInterfaceModport modport npiModportInstance instance (class)Instance Arrays instance array (class)Scope scope (class)IO Declaration io decl npiIODeclPorts port npiPortReference Objects ref obj npiRefObjNets nets (class)Net Select net select npiNetSelectVariable variables (class)Variable Select var select npiVarSelectObject Range range npiRangeTypespec typespec (class)Named Events named event npiNamedEventParameter and param assign parameter, param assign npiParameter, npiParamAssignPrimitive primitive (class)UDP and UDP Definition udp npiUdpTask and Function Declaration task func (class)

Task and Function Calls tf call (class)Continuous Assignment cont assign npiContAssignBit Select bit select npiBitSelectSimple Expression simple expr (class)


NPI Language - SystemVerilog Model: Object Diagram: Keys to the Symbols Used in Object Dia-

Keys to the Symbols Used in Object DiagramsThe following describes the keys to the symbols used in the object diagrams. Keys are provided for objects and classes, traversing relationships, and accessing properties.

Diagram Key for Objects and Classes1. Object definition: Bold letters in a solid enclosure indicate an object definition. The

properties of the object are defined in this location.

Use use (class)Expression expr (class)Atomic Statement and Statement atomic stmt (class)

Event Statement event stmt npiEventStmtProcess process (class)Assignment assignment npiAssignmentEvent Control event control ‘@’ npiEventControlWhile, Repeat while, repeat npiWhile, npiRepeatWait wait npiWaitDelay Control delay control ‘#’ npiDelayControlRepeat Control repeat control npiRepeatControlForever forever npiForeverIf, If-else if, if else npiIf, npiIfElseCase case npiCaseFor for npiForDo-while do while npiDoWhileDisable disable npiDisableReturn Statement return stmt npiReturnStmtAssign Statement, Deassign, Force, Release

assign stmt, deassign, force, release (class)

Generate gen scope npiGenScopeIterator iterator (container)Pattern Item pattern item (class)



2. Object reference: Normal letters in a solid enclosure indicate an object reference.

3. Class definition: Bold italic letters in a dotted enclosure indicate a class definition, where the class groups other objects and classes. Properties of the class are defined in this location. The class definition can contain an object definition.

4. Class reference: Italic letters in a dotted enclosure indicate a class reference.

5. Unnamed class: A dotted enclosure with no name is an unnamed class. It is sometimes convenient to group objects although they shall not be referenced as a group elsewhere; therefore, a name is not indicated.

Diagram Key for Accessing Properties1. Integer and Boolean properties are accessed with the routine npi_get(). These

properties are of type NPI_INT32 in C/C++.



C-API example: Given handle obj_h to an object of type npiObj, get the type of the object.NPI_INT32 type = npi_get(npiType, obj_h);

Tcl example: Given handle $obj_h to an object of type npiObj, get the type of the object.set type [ npi_get –property npiType –object $obj_h ]

2. String properties are accessed with routine npi_get_str(). String properties are of type const NPI_BYTE8* in C/C++.

C-API example: Given handle obj_h to an object of type npiObj, get the type of the object.const NPI BYTE8 *type_str = npi_get_str(npiType, obj_h);

Tcl example: Given handle $obj_h to an object of type npiObj, get the type of the object.set type_str [ npi_get –property npiType –object $obj_h ]

3. Complex properties for net value are accessed with the indicated routines. See the descriptions of the routines for usage.



Diagram Key for Traversing RelationshipsFor relationships that do not have a tag, the type used for access is determined by adding “npi” to the beginning of the word within the enclosure with each word’s first letter being a capital.

1. A single arrow indicates a one-to-one relationship accessed with the routine npi_handle().

C-API example: Given npiHandle variable ref_h of type ref, access obj_h of type Obj:obj_h = npi_handle(Obj, ref_h);

Tcl example: Given npiHandle variable $ref_h of type ref, access obj_h of type Obj:set obj_h [ npi_handle –type Obj –refHandle $ref_h ]

2. A tagged one-to-one relationship is traversed similarly, using Tag instead of Obj.

C-API example: Given npiHandle variable ref_h of type ref, access obj_h of type Obj:obj_h = npi_handle(Tag, ref_h);

Tcl example: Given npiHandle variable $ref_h of type ref, access obj_h of type Obj:set obj_h [ npi_handle –type Tag –refHandle $ref_h ]



3. A one-to-one relationship which originates from a circle is traversed using NULL for the ref_h.

C-API example: Access obj_h of type Obj with NULL reference:obj_h = npi_handle(Obj, NULL);

Tcl example: Access obj_h of type Obj with NULL reference:set obj_h [ npi_handle –type Obj –refHandle “” ]

4. A double arrow indicates a one-to-many relationship accessed with the routine npi_scan().

C-API example: Given npiHandle variable ref_h of type ref, scan objects of type Obj:itr = npi_iterate(Obj, ref_h);while ( obj_h = npi_scan(itr) ) {/* process ’obj_h’ */}

Tcl example: Given npiHandle variable $ref_h of type ref, scan objects of type Obj:set itr [ npi_iterate –type Obj –refHandle $ref_h ]while { [ set obj_h [ npi_scan –iterator $itr ] ] != “” } {/* process ’$obj_h’ */}

5. A tagged one-to-many relationship is traversed similarly, using Tag instead of Obj.



C-API example: Given npiHandle variable ref_h of type ref, scan objects of type Obj:itr = npi_iterate(Tag, ref_h);while ( obj_h = npi_scan(itr) ) {/* process ’obj_h’ */}

Tcl example: Given npiHandle variable $ref_h of type ref, scan objects of type Obj:set itr [ npi_iterate –type Tag –refHandle $ref_h ]while { [ set obj_h [ npi_scan –iterator $itr ] ] != “” } {/* process ’$obj_h’ */}

6. A one-to-many relationship that originates from a circle is traversed using NULL for the ref_h.

C-API example: Scan objects of type Obj with NULL reference:itr = npi_iterate(Obj, NULL);while ( obj_h = npi_scan(itr) ) {/* process ’obj_h’ */}

Tcl example: Scan objects of type Obj with NULL reference:set itr [ npi_iterate –type Obj –refHandle “” ]while { [ set obj_h [ npi_scan –iterator $itr ] ] != “” } {/* process ’$obj_h’ */}


NPI Language - SystemVerilog Model: Quick Start: SystemVerilog HDL Object

Quick Start

SystemVerilog HDL ObjectThe NPI Language Model treats SystemVerilog HDL constructs as objects, and the NPI Language Model routines provide ways to locate any specific object or type of object within the design loaded from the Verdi system.

Considering the following SystemVerilog example as follows:

example.v:module Counter (input wire clock, resetN, output logic [15:0] count); always @(posedge clock, negedge resetN) begin : B1 if( !resetN ) count

NPI Language - SystemVerilog Model: Quick Start: npiHandle Data Type

• Within the module instance object “TEST.dut”,• 3 port objects, with the name “clock”, “resetN”, and “count”. Each port has a

vector size and direction• 3 io declaration objects, with the name “clock”, “resetN”, and “count”• An always process object. Within the process is a named begin scope object with

the name “B1”. Within the named begin scope is the if-else statement object.

npiHandle Data TypeA handle is an opaque reference to an object in the NPI Language Model. It is represented as a value of the data type npiHandle. A handle allows an NPI program to refer to an object without assuming details of the representation of the object. NPI provides functions that operate on objects referred to by handles. The particular operations that are legal for an object referred to by a handle depend on the type of the object.

The following are ways to create or obtain the npiHandle:

1. npi_handle_by_name(): returns a handle that refers to an object identified by a specific name

2. npi_handle(): returns a handle that refers to an object in a one-to-one relationship3. npi_iterate(): returns a handle to an iterator object for scanning a one-to-many

relationship4. npi_scan(): returns a handle to objects in a one-to-many relationship using their

iterator object

Obtaining Objects from Design Names: npi_handle_by_name

One of the simplest ways to obtain an npiHandle object is to use npi_handle_by_name().This function can be applied to all objects with a full name property. The name can be hierarchical or simple. If scope is NULL (C/C++) or empty string “” (Tcl), then name will be searched for from the top level of hierarchy. If a scope object is provided, then search within that scope only.

For example, in the above design example.v, using the following routine in C/C++:npiHandle module_handle = npi_handle_by_name(“TEST.dut”, NULL);

or using the following routine in Tcl:set module_handle [ npi_handle_by_name -name “TEST.dut” -scope “” ]

will get the npiHandle of the module instance object “TEST.dut”.


NPI Language - SystemVerilog Model: Quick Start: Object Relationships

Object RelationshipsEach object in a SystemVerilog design is related to other objects. In example.v above, the module instance “TEST” contains 2 variable objects and the module instance “TEST.dut” contains 3 port objects. In the NPI Language Model, there are two types of object relationships:

1. One-to-one relationships: occur when an object is only related to another object of a certain type. In the example.v, the module instance “TEST.dut” is contained in the module “TEST”. So there is a one-to-one relationship from an instance to its scope

2. One-to-many relationships: occur when an object is related to several other objects of a certain type. In SystemVerilog HDL, the module may contain more than one net, so there is a one-to-many relationship from the module instance “TEST” to the net objects in example.v.

All of the possible relationships that an object might have are documented in the NPI object diagrams. These object diagrams provide a graphical representation of those objects within a SystemVerilog design to which NPI routines will provide access. The diagrams will not only show the relationships between objects, but also the properties of each object. Objects with sufficient commonality are placed in a class. Class relationships and properties apply to all the objects in the class.

The following is a simplified object diagram example:

In this simplified object diagram:

• The solid enclosure designates the objects of type “port”.• The dotted enclosures designate the objects of class “variable” and “scope”. The

name of the object class uses an italicized font.• The double arrow from the “scope” class to the “variable” class indicates a

one-to-many relationship. A “scope” can contain many “variables”.• The single arrow from the “variable” class to the “scope” class indicates a one-to-one

relationship. A specific variable can only occur within one scope.• There are two single arrows from the “port” object to “variable” class. Above the

arrows are the tags that represent the type of method in the relationship. • The tag “npiHighConn” indicates a one-to-one relationship from the “port” object

to the “variable” class. A specific variable of the port’s high connection is obtained.


NPI Language - SystemVerilog Model: Quick Start: Object Relationships

• The tag “npiLowConn” indicates a one-to-one relationship from the “port” object to the “variable” class. A specific variable of the port’s low connection is obtained

For object relationships (unless a special tag is shown in the diagram), the type used for access is determined by adding “npi” to the beginning of the word within the enclosure with each word’s first letter being a capital. The following introduces how to traverse the object relationship by NPI routines.

One-to-one Relationships: npi_handleThe routine “npi_handle” is used to obtain the objects in a one-to-one relationship. In the figure shown above, the object belonging to the “scope” class can be obtained by:

npiHandle scope_handle = npi_handle (npiScope, variable_handle); // in C/C++

or set scope_handle [ npi_handle -type “npiScope” -refHandle $variable_handle ] # in Tcl

Similarly, with the “npiHighConn” tag in the single arrow, the one-to-one relationship from a “port” object to an object belonging to the “variable” class can be obtained by:

npiHandle variable_handle = npi_handle (npiHighConn, port_handle); // in C/C++

or set variable_handle [ npi_handle -type “npiHighConn” -refHandle $port_handle ] # in Tcl

One-to-many Relationships: npi_iterate & npi_scanThe routines “npi_iterate” and “npi_scan” are used to obtain the objects in a one-to-many relationship. The following C/C++ code snippet shows how to use the routines to traverse the “variable” objects from the object belonging to the “scope” class:

npiHandle iterator = npi_iterate (npiVariable, scope_handle);npiHandle variable_handle;while ( (variable_handle = npi_scan(iterator)) != NULL ) {// do something for the “variable_handle”}

The following Tcl code snippet shows the routines to traverse the “variable” objects from the object belonging to the “scope” class:

set iterator [ npi_iterate -type “npiVariable” -refHandle $scope_handle ]while { [set variable_handle [npi_scan -iterator $iterator]] != "" } { // do something for the “$variable_handle”}


NPI Language - SystemVerilog Model: Quick Start: Accessing Object Properties: npi_get and

Accessing Object Properties: npi_get and npi_get_strEach object in a SystemVerilog design has some properties. For example, consider the following simplified object diagram:

In the simplified object diagram, the objects of the class “instance” contain the following properties:

• Boolean properties: “npiArrayMember”, “npiAutomatic”, “npiCellInstance”, “npiTop”. For Boolean properties, value 1 represents TRUE and value 0 represents FALSE

• Integer properties: “npiDefLineNo”, “npiLineNo”, “npiType”• String properties: “npiDefFile”, “npiDefName”, “npiFile”, “npiName”,

“npiFullName”, “npiType”The routine npi_get() is used to obtain a Boolean or integer property of an object. For example, in C/C++ the property of the instance location “npiLineNo” can be obtained by:

NPI_INT32 line_number = npi_get (npiLineNo, instance_handle);

Or in Tcl the same property can be obtained by:set line_number [ npi_get -property “npiLineNo” -object $instance_handle ]

The routine npi_get_str() is used to obtain a string property of an object. For example, in C/C++ the property of the instance name “npiName” can be obtained by:

NPI_BYTE8* instance_name = npi_get_str (npiName, instance_handle);

Or in Tcl the same property can be obtained by:set instance_name [ npi_get_str -property “npiName” -object $instance_handle ]


NPI Language - SystemVerilog Model: Quick Start: Other Topics

Other Topics

Handle Release: npi_release_handleThe routine npi_release_handle() called by an NPI program will release a handle. The routine npi_scan() releases the iterator handle when npi_scan() returns NULL. It is recommended that an NPI program releases handles when they are no longer needed.

Lifetimes of ObjectsThe lifetime of an object is the duration of existence of the object in the NPI model. A handle is said to be valid from the time of its creation until the time at which it is released, or until the object that it refers to ceases to exist, or until termination of the NPI program; at other times it is invalid. An NPI program will not refer to an object using an invalid handle, nor will an NPI program attempt to release an invalid handle.

ExamplesThe following design.v file shows an example that dumps the name and the net type of the object that belongs to the class “Nets”, in the module instance “TEST.dummy”.

design.v module Counter (input wire clock, resetN, output logic [15:0] count); always @(posedge clock, negedge resetN) begin : B1 if( !resetN ) count

NPI Language - SystemVerilog Model: Quick Start: Examples

initial begin resetN = 0; #2 resetN = 1; #1 $finish; end endmodule

C/C++ ExampleRemember to include “npi_hdl.h” in the C/C++ program when using the NPI Language Model.

main.cpp #include #include #include “npi.h”#include “npi_hdl.h” int main (int argc, char **argv){ if( !npi_init(argc , argv) ) return 1; if( !npi_load_design(argc, argv) ) return 1; npiHandle dummy_inst_hdl = npi_handle_by_name(“TEST.dummy”, NULL ); assert( dummy_inst_hdl ); printf(“Module= %s\n”, npi_get_str(npiFullName, dummy_inst_hdl)); // traverse net npiHandle net_itr = npi_iterate(npiNet, dummy_inst_hdl); npiHandle net_hdl = NULL; while((net_hdl = npi_scan(net_itr))) { printf(“ Net= \t %s \t (%s)\n”, npi_get_str(npiName, net_hdl), npi_get_str(npiNetType, net_hdl)); } // traverse array net net_itr = npi_iterate(npiArrayNet, dummy_inst_hdl); net_hdl = NULL; while((net_hdl = npi_scan(net_itr))) { printf(“ Array Net= \t %s \t (%s)\n”, npi_get_str(npiName, net_hdl), npi_get_str(npiNetType, net_hdl)); } npi_end(); return 0;}

Results:Module= TEST.dummy

Net= clock (npiWire)Net= w1 (npiWire)Net= w3 (npiWor)Net= w4 (npiWand)Net= w5 (npiTri)Array Net= w2 (npiWire)


NPI Language - SystemVerilog Model: Header File: Examples

Tcl Examplemain.tcl

# load the designdebImport -sv design.v set dummy_inst_hdl [ npi_handle_by_name -name “TEST.dummy” -scope “” ]puts “Module= [npi_get_str -property npiFullName -object $dummy_inst_hdl]” # traverse netset net_itr [ npi_iterate -type npiNet -refHandle $dummy_inst_hdl ]while { [set net_hdl [npi_scan -iterator $net_itr]] != “” } {puts “ Net= \t [npi_get_str -property npiName -object $net_hdl] \t ([npi_get_str -property npiNetType -object $net_hdl])”} # traverse array netset net_itr [ npi_iterate -type npiArrayNet -refHandle $dummy_inst_hdl ]while { [set net_hdl [npi_scan -iterator $net_itr]] != “” } {puts “ Array Net= \t [npi_get_str -property npiName -object $net_hdl] \t ([npi_get_str -property npiNetType -object $net_hdl])”} # exit novasdebExit

Results:Module= TEST.dummy

Net= clock (npiWire)Net= w1 (npiWire)Net= w3 (npiWor)Net= w4 (npiWand)Net= w5 (npiTri)Array Net= w2 (npiWire)

Header FileRefer to the section in Appendix C for the npi_hdl.h header file details.


NPI Language - SystemVerilog Model: Header File: Examples


NPI Netlist Model: Overview:

NPI Netlist Model

OverviewThis model lets users traverse designs from the netlist perspective. The netlist is obtained from the Verdi inference database, which can be regarded as the results of technology-independent non-optimized synthesis results. In the netlist model, a design only consists of four kinds of objects – net, instance, port, and instance port. The connectivity relationship is provided along with the objects.

Refer to the Introduction to Netlist Object Model and Object Diagram sections to understand the HDL language structure and learn how to traverse designs via NPI. Refer to the API Reference section to see all the APIs that are used in the Language Model.

Refer to the Netlist Model section of Appendix A for the List of All Types, Methods, and Properties and the List of All Supported Methods and Properties for Different Objects.

Introduction to Netlist Object ModelIn the NPI Netlist model, there are four types of objects that are extracted from a design, instance, port, instance port, and net, as shown in the following figure.

Figure: NPI Netlist Object Model

InstanceAn instance object in the NPI Netlist model is either a module instance or a primitive instance. A module instance denotes a module reference in the design that serves as a


NPI Netlist Model: Introduction to Netlist Object Model:

container for sub instance, port, instance port, and net objects. A primitive instance denotes the minimum design unit. It is used to represent low-level logic gates and switches with specific cell functions. For example, npiNlAndCell, npiNlFSMCell, and npiNlBufCell. The following figure is a simple example showing the concept of module instance and primitive instance objects in the NPI Netlist model. For detailed information about properties and relationships of an instance object, refer to the Instance object diagram.

Figure: Instance Objects in NPI Netlist Model

PortA port object represents a port of a module instance. It is used to connect instance port and net objects belonging to the module instance. For detailed information about properties and relationships of port objects, refer to the Ports object diagram.

Instance PortAn instance port object represents the port instance along with the instance object. In the NPI Netlist model, each instance port object has a specific property to indicate its functional type. For example, npiNlDataPort, npiNlClockPort, and npiNlLatchedPort. For detailed information about properties and relationships of instance port objects, refer to the Instance Ports object diagram.

NetA net object represents physical connections between structural entities, such as instance port and port. For detailed information about properties and relationships of net objects, refer to the Nets object diagram.

The following shows the source code of the RTL design CPUsystem.module CPUsystem (RESET, CLOCK1, CLOCK2, CLOCK3, CLOCK4);

input CLOCK1, CLOCK2, CLOCK3, CLOCK4;input RESET;wire [7:0] addr, data, wire VMA, R_W, BUSY;wire [7:0] RAM20, RAM21, RAM22, RAM23, wire [7:0] PC, IXR;wire IR_load;CPU i_CPU (CLOCK1, CLOCK2, CLOCK3, CLOCK4, RESET

VMA, R_W ,BUSY, data, addr);pram i_pram (CLOCK1, VMA, R_W, BUSY, addr, data);

endmodule

(a) module instance (b) primitive instance


NPI Netlist Model: Introduction to Netlist Object Model: Pseudo Object

In this HDL code, the top module CPUsystem contains several module instantiations and wire declarations. In the resulting NPI Netlist model (see the following figure), CPUsustem is modeled as a module instance object that contains: • Two instance objects, i_CPU and i_pram.• Five port objects, CLOCK1, CLOCK2, CLOCK3, CLOCK4, and RESET.• Ten net objects, BUSY, CLOCK1, CLOCK2, CLOCK3, CLOCK4, RESET, R

W, VMA, addr[7:0], and data[7:0].

Figure: NPI Netlist Model of the RTL Design

The NPI Netlist model depends on the Verdi inference engine and may discard useless wires or registers. For example, in the code and above figure, wires RAM20, RAM21, RAM22, RAM23, PC, IXR, IR_load are floating nets in the design and do not end up in the NPI Netlist model.

Pseudo ObjectAs mentioned before, the NPI Netlist model contains different objects. Such objects are called actual objects. For an actual object, you can perform object-level traversing through the APIs (see Object Diagram and API Reference).

To make it easier for bit-level traversing, the NPI Netlist model creates a different type of object, called pseudo object. A pseudo object is dynamically created from an actual object based on the bit range given for traversing.

In the NPI Netlist model, an actual object is regarded as the parent of the created pseudo objects. Actually, a pseudo object is equivalent to its parent object on object-level


NPI Netlist Model: Introduction to Netlist Object Model: Pseudo Object

traversing, but it only covers a specific sub-range of its parent object. The purpose of the pseudo object is mainly for easier bit-level traversing.

The Connectivity Relationships between Actual Objects figure shows an example of an actual object connection. In this case, “p_in[3:0]” is an instance port object, and “a[1:0],b[1:0]”, “a[1:0]”, “b[1:0]”, “a[0]”, and “a[1]” are net objects with different types.

The actual object connectivity relationships are listed as follows:

Figure: Connectivity Relationships between Actual Objects

The object-level connectivity relationship can also be presented as bus connections as shown in the following figure.

Figure: Object-level Connectivity Relationships between Actual Objects

In bit-level traversing, the connectivity relationship of net object “a[1]” should be the most significant bit of net object “a[1:0]” instead of the full bus of “a[1:0]”. To present such an object, the NPI Netlist creates a net object called “a[1:0]#[1]”, which is a pseudo object dynamically created from the actual object “a[1:0]”. The Bit-level Connectivity Relations between Actual Objects and Pseudo Objects figure shows the result when the pseudo objects are added to the connectivity relationships of the net objects “a[1]”, “a[0]”, and “b[1:0]”:

“p_in[3:0]” is connected to “a[1:0],b[1:0]”“a[1:0],b[1:0]” is connected to “p_in[3:0]”; “a[1:0],b[1:0]”, “a[1:0]”, and “b[1:0]”“a[1:0]” is connected to “a[1:0],b[1:0]”, “a[0]”, and “a[1]”“b[1:0]” is connected to “a[1:0],b[1:0]”“a[1]” is connected to “a[1:0]”“a[0]” is connected to “a[1:0]”

“a[1]” is connected to “a[1:0]#[1]”.“a[1:0]#[1]” is connected to “a[1]” and “a[1:0],b[1:0]#[0]”.


NPI Netlist Model: Introduction to Netlist Object Model: Schematic Configurations

where “a[1:0]#[1]”, “a[1:0]#[0]”, “a[1:0],b[1:0]#[0]”, “a[1:0],b[1:0]#[1]”, “a[1:0],b[1:0]#[2:3]” are pseudo net objects, and “p_in[3:0]#[3]”, “p_in[3:0]#[2]”, “p_in[3:0]#[1:0]” are pseudo instance port objects. Note that in the current implementation, concat net object “a[1:0], b[1:0]” has the default range of [0:3].

Figure: Bit-level Connectivity Relations between Actual Objects and Pseudo Objects

Schematic ConfigurationsThe NPI Netlist can operate with different schematic configurations. In this sub clause, these configurations together with examples are described.

RTL ConfigurationsDetailRTL: If the option is set, instances will be inferred in detailed view.

DetailLevel: Use this option to control the Netlist RTL level. The input value takes effect only when the DetailRTL option is on. The level number must be a positive number; otherwise, the default value 4 will be applied. The following figures are an example of DetailRTL with different level configurations.

Figure: Source Code

“a[1:0],b[1:0]#[0]” is connected to “a[1:0]#[1]” and “p_in[3:0]#[3]”.

“a[0]” is connected to “a[1:0]#[0]”.“a[1:0]#[0]” is connected to “a[0]” and “a[1:0],b[1:0]#[1]”.“a[1:0],b[1:0]#[1]” is connected to “a[1:0]#[0]” and “p_in[3:0]#[2]”.

“b[1:0]” is connected to “a[1:0],b[1:0]#[2:3]”.“a[1:0],b[1:0]#[2:3]” is connected to “p_in[3:0]#[1:0]”.

module top;wire a, b, c, d;assign d = (a || b) && c;

endmodule



Figure: DetailRTL= “off”

Figure: DetailRTL= “on”, DetailLevel=1

Figure: DetailRTL= “on”, DetailLevel=2

DetailMux: If this option is set, unintended latches will be extracted as MUX style in the detailed schematics. Note that the input value takes effect only when the DetailRTL option is on. The following figures are examples of a DetailMux configuration.

Figure: Source Code

module mux;wire [1:0] sel;reg q, a1, a2, a3;always @(sel) case (sel)

2’b00: q = a1;2’b01: q = a2;2’b10: q = a3;

endcaseendmodule



Figure: DetailRTL= “on”, DetailMux= “off”

Figure: DetailRTL= “on”, DetailMux= “on”

RecogFSM: If this option is set, FSM recognition will apply to the inferred objects. The following figures are examples of RecogFSM configuration.



Figure: Source Code

Figure: RecogFSM= “off”

Figure: RecogFSM= “on”

module top; reg [1:0] CurrStateFSM3, NextStateFSM3; wire Clock; parameter ST_Sum1 = 0, ST_Sum2 = 1, ST_Sum3 = 2,

ST_NoSum = 3; always @(CurrStateFSM3) begin

case (CurrStateFSM3)ST_Sum1: NextStateFSM3 = ST_Sum2;ST_Sum2: NextStateFSM3 = ST_Sum3;ST_Sum3: NextStateFSM3 = ST_Sum1;ST_NoSum: NextStateFSM3 = ST_Sum1;default: NextStateFSM3 = ST_Sum1;

endcase end always @(posedge Clock) begin

CurrStateFSM3 = NextStateFSM3; endendmodule



GenBlock: If this option is set, when the GENERATE block is at the architecture level, the block will be expanded and individual instances will be inferred. If the If the block is at the RTL level, this option will have no effect. The following figure is an example of GenBlock configuration.

Figure: Source Code

Figure: GenBlock= “off”

Figure: GenBlock= “on”

RecogLibCell: When symbol libraries do not exist, cells defined with ‘celldefine or ‘endcelledefine, or cells imported with the –v or -y options will be recognized as modules if this option is set. It should be noted that the global settings will be applied after turning

module top;wire [2:0] a, b, c;genvar i;generate for (i=0;i


on this option, and all the tracing results will be reset. The following figure is an example of RecogLibCell configuration.

Figure: Source Code

Figure: RecogLibCell = “off”

Figure: RecogLibCell = “on”

Symbol Library ConfigurationsSymbol Library Names: The option specifies the preferred symbol library name(s) in this text field. Multiple library names can be separated by either a space or a colon (:) character.

Symbol Library Paths: The option specifies the preferred symbol library path(s) in this text field. Multiple path strings can be separated by either a space or a colon (:) character.

module top;wire z, a, b;AN2 an2(z, a, b);

endmodule`celldefinemodule AN2(Z, A, B);

input A, B;output Z;and #1 ( Z, A, B);

endmodule`endcelldefine


NPI Netlist Model: API Reference: Schematic Configurations

API ReferenceThe following list of APIs are available in all NPI models:

The following list of APIs are available in all NPI Netlist models:

Name Description

npi.h The header for all NPI applications (used in C/C++)npi_init Perform the initialization activities for the NPI process (used in C/C++).npi_end Perform the ending activities for the NPI process (used in C/C++).npi_load_design Load the design from input files (used in C/C++).

Name Description

npi_nl.h The header file (used in C/C++)typedef void* npiNlHandle The data type of the netlist object (used in C/C++)npi_nl_get Get the value of an integer or Boolean property of an object.npi_nl_get_str Get the value of a string property of an object.npi_nl_handle Obtain a handle to an object with a one-to-one relationship.

npi_nl_handle_by_index Get a handle to an object using its index number within a given object.

npi_nl_handle_by_range Get a handle to an object using the specified range within a given object.npi_nl_handle_by_name Get a handle to an object with a specific name.

npi_nl_iterate Obtain an iterator handle to objects with a one-to-many relationship.

npi_nl_iterate_with_range Obtain an iterator handle to objects with a one-to-many relationship under the given range.

npi_nl_release_all_handles Release all the handles and their associated resources allocated by NPI Netlist routines.

npi_nl_release_handle Release the handle and its associated resources allocated by NPI Netlist routines.

npi_nl_scan Scan the Netlist model for objects with a one-to-many relationship.

npi_nl_set_permanent_handle Set the handle as “permanent” which can not be released until npi_nl_release_all_handles is called.

npi_nl_table_lookup Get the value of an output instport belonging to the combinational UDP cell.


NPI Netlist Model: Object Diagram: Abstract

Object Diagram

AbstractAll the possible relationships and properties that an object might have are documented in the form of object diagrams, which use enclosures to represent objects and arrows to represent the type of relationship. The properties of the object are listed below the diagrams. Following is the list of all the supported types for the object diagram.

NPI Netlist HandlesA handle is an opaque reference to an object in the NPI Netlist model. It is represented as a value of the data type npiNlHandle. However, the interpretation of the representation is implementation defined. A handle allows an NPI Netlist program to refer to an object without assuming details of the representation of the object. The NPI Netlist provides functions that operate on objects referred to by handles. The particular operations that are legal for an object referred to by a handle depend on the type of the object.

Handle CreationA handle may be created by one of the following functions in an NPI Netlist application program:

1. npi_nl_handle, returns a handle that refers to an object in a one-to-one relationship2. npi_nl_handle_by_index, returns a handle to an object based on the index number of

the object within the reference object3. npi_nl_handle_by_range, returns a handle to an object based on the specified range of

the object within the reference object 4. npi_nl_handle_by_name, returns a handle that refers to an object identified by a

specific name

Object Category Names in the Object Diagram Object Types or Tags

Instance inst npiNIInstPorts ports (class)Instance Ports instance ports (class)Nets nets (class)Drivers, Loads drivers, loads (class)Iterator iterator npiNIIterator


NPI Netlist Model: Object Diagram: NPI Netlist Object Classifications

5. npi_nl_iterate, returns a handle to an iterator object for scanning a one-to-many relationship

6. npi_nl_iterate_with_range, returns a handle to an iterator object for scanning a one-to-many relationship under the given range

7. npi_nl_scan, returns a handle to objects in a one-to-many relationship, using their iterator object

NOTE: The number of handles that an implementation can create may be constrained by the capacity of the host system.

Handle ReleaseThe function npi_nl_release_handle called by an NPI Netlist program causes a tool to release a handle. If a tool shares resources associated with handles and one NPI Netlist program releases a handle, other NPI Netlist programs will be able to continue to refer to objects using handles that they have not released. The tool may reclaim resources associated with the representation of a released handle.

NOTE: - It is recommended that an NPI Netlist program release handles when they are no longer needed. - A tool may reclaim resources associated with a handle when the handle is released by an NPI Netlist program, provided the requirements of Handle Creation are met. As a consequence, resources might not be reclaimed immediately upon release of a handle by an NPI Netlist program, as the resources may be associated with handles in use by other NPI Netlist programs.

Validity of HandlesA handle is said to be valid from the time of its creation until the time it is released, or until the object that it refers to ceases to exist, or until termination of the tool; at other times it is invalid. A NPI Netlist program will not refer to an object using an invalid handle, nor will an NPI Netlist program attempt to release an invalid handle.

NPI Netlist Object ClassificationsNPI Netlist objects are classified using object diagrams. These diagrams provide a graphical representation of those objects within a Netlist model to which the NPI Netlist routines will provide access. The diagrams show the relationships between objects and the properties of each object. Objects with sufficient commonality are placed in groups. Group relationships and properties apply to all objects in the group.

As an example, the simplified diagram in Figure 1 shows that there is a one-to-many relationship from objects of type inst to objects of type port and a one-to-one relationship


NPI Netlist Model: Object Diagram: NPI Netlist Object Classifications

from objects of type port to objects of type inst. Objects of type port have properties npiNlName, and npiNlSize with data types string and integer, respectively.

Figure: Examples of Object Relationships Diagram

For object relationships (unless a special tag is shown in the diagram), the type used for access is determined by adding “npiNl” to the beginning of the word within the enclosure and capitalizing each word’s first letter. Using the above example, if an application has a handle to a port and wants to go to the instance where the port is defined, the call would be as follows:

instH = npi_nl_handle(npiNlInst, portH);

where portH is a handle to the port. As another example, to access an “instport” object, use the type “npiNlInstPort”.

Accessing Object Relationships and PropertiesThe NPI Netlist defines the C data type of npiNlHandle. All objects are manipulated via an npiNlHandle variable. Object handles can be accessed from a relationship with another object or from a hierarchical name as the following example demonstrates:

npiNlHandle net;net = npi_nl_handle_by_name(“top.m1.w1”);

This example call retrieves a handle to wire top.m1.w1 and assigns it to the npiNlHandle variable, net.

The NPI Netlist provides generic functions, such as traversing relationships and determining property values. One-to-one relationships are traversed with the function npi_nl_handle. In the following example, the instance that contains net is derived from a handle to that net:

npiNlHandle net, inst;net = npi_nl_handle_by_name(“top.m1.w1”);inst = npi_nl_handle(npiNlInst, net);

The call to npi_nl_handle in the above example will return a handle to instance top.m1. Som

Verdi Interoperability Apps (VIA)Verdi Interoperability Apps (VIA) 1 About This Book Purpose This...

Documents

Transcript of Verdi Interoperability Apps (VIA)Verdi Interoperability Apps (VIA) 1 About This Book Purpose This...