README
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