1
2       PLI 2.0 VPI ROUTINE EXAMPLES AND INSTALLATION TEST
3
4This directory contains PLI 2.0 API vpi_ routine examples to illustrate use
5of PLI 2.0.  To test for correct installation run the inst_pli.sh script that
6compiles vpi_ programs into .so libraries which are dynamically loaded
7using new +loadvpi= Cver command line option and run.
8
9To see an example asynchronously driven PLI 2.0 vpi_ model, look
10at async.c (and async.v) test below.  The other tests show various
11PLI 2.0 vpi_ routine capabilities but are not complete models.
12
13To learn more about PLI 2.0 capabilities, read the various examples.  To
14learn how to use a particular vpi_ routine, access method, or to get
15properties from a particular object, run "grep [object or routine name] *.c".
16
17This script assumes you are using new +loadvpi= dynamic library PLI
18execution.  If you need to statically link your PLI libraries contact
19Pragmatic C to obtain the libraries and test scripts.
20
21HOW TO RUN THE TEST SCRIPT FOR ALL SYSTEMS EXCEPT MAC OSX AND CYGWIN (below)
22
231) Run the shell script inst_pli.sh [OS name].  Various compiler and Verilog
24   output messages will be printed but there should be no diff command
25   differences printed.  You must pass the name of your system as the one
26   argument to the script.  Depending on your platform, names are:
27   for X86 linux (suffix lnx), Sparc (suffix sparc-gcc),
28   X86 64-bit (suffix lnx64).
29
30   Run the shell script opt_inst_pli.sh [OS name] to test PLI using
31   optimizer (-O) incremental compiler.
32
33   By convention makefile.[OS name] assumes this test is run in release
34   directory tree with include files in pli_incs 2 directory levels up
35   and Cver binary also 2 levels up.
36
37   The commands to run Cver with dynamically loaded user PLI library
38   explicitly access the user .so library in this directory.  For your
39   PLI libraries, it is better to set the LD_LIBRARY_PATH environment
40   variables so explicit "./" is not needed
41
422) After completing the test, run clean.sh to remove work files.
43   The inst_pli.sh script removes each PLI library .so dynamic library after
44   running the test that uses it so unless something went wrong, you
45   do not need to run clean.sh.
46
473) Use makefile.[your OS] as a template for your vpi_ PLI 2.0 models.
48   Notice to use the PLI1 user defined PLI system/task function interface,
49   you must use +loadpli1= option.  To use newer PLI2 vpi_ user defined PLI
50   system/task function interface you must use +loadvpi=.  You should
51   use the +loadvpi= option for all new PLI code because of the additional
52   capabilities.  +loadpli1= system tasks can't be used with new vpi_
53   system task and function access methods because +loadpli1 system tasks
54   and functions must support old behavior.
55
56HOW TO RUN THE TEST SCRIPT FOR MAC OSX
57
581) Run the shell script inst_pli.osx.sh.  Notice you do not need the
59   OS shell argument here.  Various compiler and Verilog
60   output messages will be printed but there should be no diff command
61   differences printed.  You must run this different script for MAC OSX
62   because OSX uses .dylib suffix for dynamic libraries and uses the
63   mach dynamic library mechanism instead of normal .so and dlopen.
64
65   By convention, makefile.osx assumes this test is run in release
66   directory tree with include files in pli_incs 2 directory levels up
67   and Cver binary is in bin directory also 2 levels up.
68
69   The commands to run Cver with dynamically loaded user PLI library
70   explicitly access the user .dylib library in this directory.  For your
71   PLI libraries, it is better to set the LD_LIBRARY_PATH environment
72   variables so explicit "./" is not needed
73
74   Mac OSX linker (from mach OS) requires that a leading '_' be added to
75   each symbol name.  Cver does this automatically but you must make
76   sure that your bootstrap routine name does not start with underscore ('_').
77
782) After completing the test, run clean.sh to remove work files.
79   The inst_pli.osx.sh script removes each PLI library .so dynamic library
80   after running the test that uses it so unless something went wrong, you
81   do not need to run clean.sh.
82
833) Use makefile.osx as a template for your PLI models.  You must use
84   exactly the LFLAGS options and set and export LD_LIBRARY_PATH
85   environment variable, or your .dylib user PLI code will not load
86   properly.
87
88HOW TO RUN PLI ON CYGWIN
89   ****IMPORTANT - as of 02/02/04 the latest version of Cygwin contains a
90       bug which doesn't run the PLI correctly.  To run the PLI you will need
91       Cygwin version 1.5.5 or earlier.
92
931) First, you must make a cver dll and executable.  Go to the objs directory
94   (gplcver-*/objs/), and type the following commands:
95
96       make -f makefile.dll dll                 #makes the dll library
97       make -f makefile.dll exe                 #make the new cver.exe
98
992) Next copy the libcver.dll library to the lib directory:
100
101       cp libcver.dll /lib/
102
1033) In the vpi examples directory (this one), type the following commands:
104
105       make -f makefile.cygwin dll                #compiles libvfopen1.c
106       make -f makefile.cygwin run                #runs the PLI example
107
1084) All of these should compile correctly, and 'make -f makefile.vpi run',
109   runs the PLI example vfopen1.v after making the libvopen1 library.
110
111---------------------------------------------------------------------------
112
113Tests are:
114
115  1. async.c is asynchronously switching not gate implemented using vpi_.
116
117  2. vhello1.c and vhello2.c are "hello world" tests that also show use
118     of environment determing vpi_ routines.
119
120  3. vhelbad.c is a "hello world" test with some vpi_ errors to illustrate
121     vpi_ error checking.
122
123  4. findcaus.c is test that traverses Verilog design hierarchy.
124
125  5. vcabtsts.c is a test that registers every call back and prints a message
126     when it occurs.
127
128  6. vprtchg.c adds cbValueChange callbacks to every .v file varaibles and
129     prints a message on every change.
130
131  7. vprtchg2.c test also prints every variable change in a design
132     except it uses vpi_get_value and vpi_get_time instead of the built in
133     value change callback values.
134
135  8. vprtchg3.c prints new and old variable values using an on change call
136     back.
137
138  9. vprtdels.c accesses and prints every delay in a design.
139
140  10. vprtdel2.c illustrates vpi_ timscale handling.
141
142  11. vsetdels.c use vpi_ to set delays.
143
144  12. vsetval1.c tests various vpi_put_value uses.
145
146  13. vtimcbs.c illustrates use of various delay callbacks.
147
148  14. vfopen1.c implements $fopen built in system function using PLI 2.0.
149
150  15. vfopen2.c is  variant of the vfopen1.c test using vpi_ system task
151      instead of vpi_ system function.
152
153  16. vconta1.c tests continous assignments and non lvalue expression
154      decomposition.
155
156  17. vchkprt1.c tests most port and vpiHighConn/vpiLowConn one to one
157      and one to many iterators.  It is possible that either the .c model
158      or Cver's interpretation of the LRM are not right because Cver
159      assumes all bit iterators are LSB to MSB in terms of vpi_scan order.
160
161  18. vdrvld1.c tests vpiDriver and vpiLoad iterators for nets.
162
163  19. vdrvld2.c tests vpiDriver and vpiLoad iterators for bits of nets.
164
165  20. dfpsetd.c tests vpi_put_value to defparam and specparam during
166      cbEndOfCompile call back for delay annotation (allows delay annotation
167      to procedural delay controls and continuous assignments).  Test
168      sets same delays and produces same results using vpi_ as dfpsetd.vc
169      in install.tst directory that uses 2 SDF delay annotation files.
170