2
2
######################################################################
4
# Copyright 2003-2010 by Wilson Snyder. This program is free software; you
4
# Copyright 2003-2011 by Wilson Snyder. This program is free software; you
5
5
# can redistribute it and/or modify it under the terms of either the GNU
6
6
# Lesser General Public License Version 3 or the Perl Artistic License
78
78
# Determine runtime flags and run
79
if ($opt_gdbbt && !gdb_works()) {
80
warn "-Info: --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
79
83
if ($opt_gdbbt && !$opt_gdb && $Debug) {
80
84
# Run under GDB to get gdbbt
81
85
run ("gdb ".verilator_bin()
86
." --batch --quiet --return-child-result"
83
87
." -ex 'run ".join(' ',@Opt_Verilator_Sw)."'"
84
88
." -ex 'set width 0'"
87
die "%Error: --gdbbt looses the exit status; so must assume run went badly...";
90
92
run (($opt_gdb?"$opt_gdb ":"")
111
113
sub verilator_bin {
113
115
# Use VERILATOR_ROOT if defined, else assume verilator_bin is in the search path
114
$bin .= $ENV{VERILATOR_ROOT}."/" if defined($ENV{VERILATOR_ROOT});
115
$bin .= ($ENV{VERILATOR_BIN}
116
|| ($Debug ? "verilator_bin_dbg" : "verilator_bin"));
116
my $basename = ($ENV{VERILATOR_BIN}
117
|| ($Debug ? "verilator_bin_dbg" : "verilator_bin"));
118
if (defined($ENV{VERILATOR_ROOT})) {
119
my $dir = $ENV{VERILATOR_ROOT};
120
if (-x "$dir/bin/$basename") { # From a "make install" into VERILATOR_ROOT
121
$bin = "$dir/bin/$basename";
123
$bin = "$dir/$basename"; # From pointing to kit directory
121
132
#######################################################################
136
$! = undef; # Cleanup -x
137
system("gdb /bin/echo"
138
." --batch-silent --quiet --return-child-result"
139
." -ex 'run -n'" # `echo -n`
140
." -ex 'set width 0'"
125
147
# Run command, check errors
126
148
my $command = shift;
149
$! = undef; # Cleanup -x
127
150
print "\t$command\n" if $Debug>=3;
128
151
system($command);
206
229
--bbox-sys Blackbox unknown $system calls
207
230
--bbox-unsup Blackbox unsupported language features
208
231
--bin <filename> Override Verilator binary
209
-CFLAGS <flags> C++ Compiler flags for makefile
232
-CFLAGS <flags> C++ Compiler flags for makefile
210
233
--cc Create C++ output
211
234
--cdc Clock domain crossing analysis
212
235
--compiler <compiler-name> Tune for specified C++ compiler
222
245
--debugi-<srcfile> <level> Enable debugging a source file at a level
223
246
+define+<var>+<value> Set preprocessor define
224
247
--dump-tree Enable dumping .tree files
225
-E Preprocess, but do not compile
248
-E Preprocess, but do not compile
226
249
--error-limit <value> Abort after this number of errors
227
250
--exe Link to create executable
251
-F <file> Parse options from a file, relatively
228
252
-f <file> Parse options from a file
229
--help Display this help.
253
--gdbbt Run Verilator under GDB for backtrace
254
--help Display this help
230
255
-I<dir> Directory to search for includes
256
--if-depth <value> Tune IFDEPTH warning
231
257
+incdir+<dir> Directory to search for includes
232
258
--inhibit-sim Create function to turn off sim
233
259
--inline-mult <value> Tune module inlining
234
-LDFLAGS <flags> Linker pre-object flags for makefile
235
-LDLIBS <flags> Linker library flags for makefile
260
-LDFLAGS <flags> Linker pre-object flags for makefile
261
-LDLIBS <flags> Linker library flags for makefile
236
262
--language <lang> Language standard to parse
237
263
+libext+<ext>+[ext]... Extensions for finding modules
238
264
--lint-only Lint, but do not make output
246
272
-O0 Disable optimizations
247
273
-O3 High performance optimizations
248
274
-O<optimization-letter> Selectable optimizations
249
-o <executable> Name of final executable
275
-o <executable> Name of final executable
250
276
--output-split <bytes> Split .cpp files into pieces
251
277
--output-split-cfuncs <statements> Split .ccp functions
252
278
--pins-bv <bits> Specify types for top level ports
253
279
--pins-uint8 Specify types for top level ports
254
--pipe-filter <command> Filter all input through a script
280
--pipe-filter <command> Filter all input through a script
255
281
--prefix <topname> Name of top level class
256
282
--profile-cfuncs Name functions for profiling
257
283
--private Debugging; see docs
268
294
-U<var> Undefine preprocessor define
269
295
--unroll-count <loops> Tune maximum loop iterations
270
296
--unroll-stmts <stmts> Tune maximum loop body size
297
--unused-regexp <regexp> Tune UNUSED lint signals
271
298
-V Verbose version and config
272
299
-v <filename> Verilog library
273
300
-Werror-<message> Convert warning to error
274
301
-Wfuture-<message> Disable unknown message warnings
275
302
-Wno-<message> Disable warning
276
303
-Wno-lint Disable all lint warnings
304
-Wno-style Disable all style warnings
277
305
-x-assign <mode> Initially assign Xs to this value
278
306
-y <dir> Directory to search for modules
500
528
Generate a executable. You will also need to pass additional .cpp files on
501
529
the command line that implement the main loop for your simulation.
533
Read the specified file, and act as if all text inside it was specified as
534
command line parameters. Any relative paths are relative to the directory
535
containing the specified file. Note -F is fairly standard across Verilog
505
540
Read the specified file, and act as if all text inside it was specified as
506
command line parameters. Note -f is fairly standard across Verilog tools.
541
command line parameters. Any relative paths are relative to the current
542
directory. Note -f is fairly standard across Verilog tools.
546
If --debug is specified, run Verilator underneath a GDB process and print
547
a backtrace on exit. Without --debug or if GDB doesn't seem to work, this
516
558
are fairly standard across Verilog tools while -I is an alias for GCC
561
=item --if-depth I<value>
563
Rarely needed. Set the depth at which the IFDEPTH warning will fire,
564
defaults to 0 which disables this warning.
519
566
=item +incdir+I<dir>
521
568
Add the directory to the list of directories that should be searched for
568
615
Check the files for lint violations only, do not create any other output.
617
You may also want the -Wall option to enable messages that are considered
618
stylistic and not enabled by default.
570
620
If the design is not to be completely Verilated see also the --bbox-sys and
571
621
--bbox-unsup options.
783
833
Rarely needed. Specifies the maximum number of statements in a loop for
784
834
that loop to be unrolled. See also BLKLOOPINIT warning.
836
=item --unused-regexp I<regexp>
838
Rarely needed. Specifies a simple regexp with * and ? that if a signal
839
name matches will suppress the UNUSED warning. Defaults to "*unused*".
840
Setting it to "" disables matching.
788
844
Shows the verbose version, including configuration information compiled
794
850
used to resolve cell instantiations in the top level module, else ignored.
795
851
Note -v is fairly standard across Verilog tools.
855
Enable all warnings, including code style warnings that are normally
797
858
=item -Werror-I<message>
799
860
Convert the specified warning message into a error message. This is
817
Disable all lint related warning messages. This is equivalent to
818
"-Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASEWITHX
819
-Wno-CMPCONST -Wno-IMPLICIT -Wno-LITENDIAN -Wno-UNDRIVEN -Wno-UNSIGNED
820
-Wno-UNUSED -Wno-VARHIDDEN -Wno-WIDTH".
878
Disable all lint related warning messages, and all style warnings. This is
879
equivalent to "-Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX
880
-Wno-CASEWITHX -Wno-CMPCONST -Wno-IMPLICIT -Wno-LITENDIAN -Wno-SYNCASYNCNET
881
-Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED -Wno-WIDTH" plus the list shown for
822
884
It is strongly recommended you cleanup your code rather than using this
823
885
option, it is only intended to be use when running test-cases of code
824
886
received from third parties.
890
Disable all code style related warning messages (note by default they are
891
already disabled). This is equivalent to "-Wno-DECLFILENAME -Wno-DEFPARAM
892
-Wno-INCABSPATH -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNUSED
826
895
=item -Wwarn-I<message>
828
897
Enables the specified warning message.
901
Enable all lint related warning messages (note by default they are already
902
enabled), but do not affect style messages. This is equivalent to
903
"-Wwarn-CASEINCOMPLETE -Wwarn-CASEOVERLAP -Wwarn-CASEX -Wwarn-CASEWITHX
904
-Wwarn-CMPCONST -Wwarn-IMPLICIT -Wwarn-LITENDIAN -Wwarn-UNSIGNED
909
Enable all code style related warning messages. This is equivalent to
910
"-Wwarn-DECLFILENAME -Wwarn-DEFPARAM -Wwarn-INCABSPATH -Wwarn-SYNCASYNCNET
911
-Wwarn-UNDRIVEN -Wwarn-UNUSED -Wwarn-VARHIDDEN".
830
913
=item -x-assign 0
832
915
=item -x-assign 1
970
If you installed Verilator from sources, or a tarball, but not as part of
971
your operating system (as an RPM), first you need to point to the kit:
973
export VERILATOR_ROOT=/path/to/where/verilator/was/installed
974
export PATH=$VERILATOR_ROOT/bin:$PATH
887
976
Now we run Verilator on our little example.
889
export VERILATOR_ROOT=/path/to/where/verilator/was/installed
890
$VERILATOR_ROOT/bin/verilator --cc our.v --exe sim_main.cpp
978
verilator -Wall --cc our.v --exe sim_main.cpp
892
980
We can see the source code under the "obj_dir" directory. See the FILES
893
981
section below for descriptions of some of the files that were created.
1037
If you installed Verilator from sources, or a tarball, but not as part of
1038
your operating system (as an RPM), first you need to point to the kit:
1040
export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1041
export PATH=$VERILATOR_ROOT/bin:$PATH
949
1043
Now we run Verilator on our little example.
951
export VERILATOR_ROOT=/path/to/where/verilator/was/installed
952
$VERILATOR_ROOT/bin/verilator --sp our.v
1045
verilator -Wall --sp our.v
954
1047
Then we convert the SystemPerl output to SystemC.
1160
1253
Specifies the directory containing the distribution kit. This is used to
1161
1254
find the executable, Perl library, and include files. If not specified, it
1162
1255
will come from a default optionally specified at configure time (before
1163
Verilator was compiled).
1256
Verilator was compiled). It should not be specified if using a pre-compiled
1257
Verilator RPM as the hardcoded value should be correct.
1331
1425
are slightly faster, but less compatible.
1428
=head1 VERIFICATION PROCEDURAL INTERFACE (VPI)
1430
Verilator supports a very limited subset of the VPI. This subset allows
1431
inspection, examination, value change callbacks, and depositing of values
1432
to public signals only.
1434
To access signals via the VPI, Verilator must be told exactly which signals
1435
are to be accessed. This is done using the Verilator public pragmas
1438
Verilator has an important difference from an event based simulator; signal
1439
values that are changed by the VPI will not immediately propagate their
1440
values, instead the top level header file's eval() method must be called.
1441
Normally this would be part of the normal evaluation (IE the next clock
1442
edge), not as part of the value change. This makes the performance of VPI
1443
routines extremely fast compared to event based simulators, but can confuse
1444
some test-benches that expect immediate propagation.
1446
Note the VPI by it's specified implementation will always be much slower
1447
than accessing the Verilator values by direct reference
1448
(structure->module->signame), as the VPI accessors perform lookup in
1449
functions at runtime requiring at best hundreds of instructions, while the
1450
direct references are evaluated by the compiler and result in only a couple
1455
In the below example, we have readme marked read-only, and writeme which if
1456
written from outside the model will have the same semantics as if it
1457
changed on the specified clock edge.
1460
reg readme /*verilator public_flat_rd*/;
1461
reg writeme /*verilator public_flat_rw @(posedge clk) */;
1464
There are many online tutorials and books on the VPI, but an example that
1465
accesses the above would be:
1467
void read_and_check() {
1468
vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"t.readme", NULL);
1469
if (!vh1) { error... }
1470
const char* name = vpi_get_str(vpiName, vh1);
1471
printf("Module name: %s\n"); // Prints "readme"
1474
v.format = vpiIntVal;
1475
vpi_get_value(vh1, &v);
1476
printf("Value of v: %d\n", v.value.integer); // Prints "readme"
1334
1480
=head1 CROSS COMPILATION
1336
1482
Verilator supports cross-compiling Verilated code. This is generally used
1409
1555
=item coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
1411
Disable coverage for the specified filename (or all files if omitted) and
1412
range of line numbers (or all lines if omitted). Often used to ignore an
1413
entire module for coverage analysis purposes.
1415
=item lint_off -msg <message> [-file "<filename>" [-lines <line> [ - <line>]]]
1417
Disables the specified lint warning in the specified filename (or all files
1418
if omitted) and range of line numbers (or all lines if omitted).
1557
Disable coverage for the specified filename (or wildcard with '*' or '?',
1558
or all files if omitted) and range of line numbers (or all lines if
1559
omitted). Often used to ignore an entire module for coverage analysis
1562
=item lint_off [-msg <message>] [-file "<filename>" [-lines <line> [ - <line>]]]
1564
Disables the specified lint warning, in the specified filename (or wildcard
1565
with '*' or '?', or all files if omitted) and range of line numbers (or all
1568
If the -msg is omitted, all lint warnings are disabled. This will override
1569
all later lint warning enables for the specified region.
1420
1571
=item tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
1422
1573
Disable waveform tracing for all future signals declared in the specified
1423
filename (or all files if omitted) and range of line numbers (or all lines
1574
filename (or wildcard with '*' or '?', or all files if omitted) and range
1575
of line numbers (or all lines if omitted).
2177
2334
Ignoring this warning may make Verilator simulations differ from other
2339
This indicates that a blocking assignment (=) is used in a sequential
2340
block. Generally non-blocking/delayed assignments (<=) are used in
2341
sequential blocks, to avoid the possibility of simulator races. It can be
2342
reasonable to do this if the generated signal is used ONLY later in the
2343
same block, however this style is generally discouraged as it is error
2346
always @ (posedge clk) foo = ...
2348
Disabled by default as this is a code style warning; it will simulate
2180
2351
=item BLKLOOPINIT
2182
2353
This indicates that the initialization of an array needs to use non-delayed
2261
2432
Ignoring this warning may make Verilator simulations differ from other
2437
Warns that a module or other declaration's name doesn't match the filename
2438
with path and extension stripped that it is declared in. The filename a
2439
modules/interfaces/programs is declared in should match the name of the
2440
module etc. so that -y directory searching will work. This warning is
2441
printed for only the first mismatching module in any given file, and -v
2442
library files are ignored.
2444
Disabled by default as this is a code style warning; it will simulate
2449
Warns that the "defparam" statement was deprecated in Verilog 2001 and all
2450
designs should now be using the #(...) format to specify parameters.
2452
Disabled by default as this is a code style warning; it will simulate
2266
2457
Warns that the specified signal is generated, but is also being used as a
2274
2465
Ignoring this warning may make Verilator simulations differ from other
2470
Warns that if/if else statements have exceeded the depth specified with
2471
--if-depth, as they are likely to result in slow priority encoders. Unique
2472
and priority if statements are ignored. Solutions include changing the
2473
code to a case statement, or a SystemVerilog 'unique if' or 'priority if'.
2475
Disabled by default as this is a code style warning; it will simulate
2277
2478
=item IMPERFECTSCH
2279
2480
Warns that the scheduling of the model is not absolutely perfect, and some
2302
2503
Ignoring this warning may make Verilator simulations differ from other
2508
Warns that an `include filename specifies an absolute path. This means the
2509
code will not work on any other system with a different file system layout.
2510
Instead of using absolute paths, relative paths (preferably without any
2511
directory specified whatever) should be used, and +include used on the
2512
command line to specify the top include source directory.
2514
Disabled by default as this is a code style warning; it will simulate
2305
2517
=item LITENDIAN
2307
2519
Warns that a vector is declared with little endian bit numbering
2373
2585
message as you would disable warnings, but the symbol will be renamed by
2374
2586
Verilator to avoid the conflict.
2590
Warns that the specified net is used in at least two different always
2591
statements with posedge/negedges (i.e. a flop). One usage has the signal
2592
in the sensitivity list and body, probably as a async reset, and the other
2593
usage has the signal only in the body, probably as a sync reset. Mixing
2594
sync and async resets is usually a mistake. The warning may be disabled
2595
with a lint_off pragma around the net, or either flopped block.
2597
Disabled by default as this is a code style warning; it will simulate
2376
2600
=item TASKNSVAR
2378
2602
Error when a call to a task or function has a output from that task tied to
2401
Warns that the specified signal is never sourced.
2625
Warns that the specified signal is never sourced. Verilator is fairly
2626
liberal in the usage calculations; making a signal public, or loading only
2627
a single array element marks the entire signal as driven.
2403
Ignoring this warning will only suppress the lint check, it will simulate
2629
Disabled by default as this is a code style warning; it will simulate
2486
Warns that the specified signal is never sinked. This is a future message,
2487
currently Verilator will not produce this warning.
2712
Warns that the specified signal is never sinked. Verilator is fairly
2713
liberal in the usage calculations; making a signal public, a signal
2714
matching --unused-regexp ("*unused*") or accessing only a single array
2715
element marks the entire signal as used.
2489
Ignoring this warning will only suppress the lint check, it will simulate
2717
Disabled by default as this is a code style warning; it will simulate
2720
A recommended style for unused nets is to put at the bottom of a file code
2721
similar to the following:
2723
wire _unused_ok = &{1'b0,
2725
sig_not_used_yet_b, // To be fixed
2728
The reduction AND and constant zeros mean the net will always be zero, so
2729
won't use simulation time. The redundant leading and trailing zeros avoid
2730
syntax errors if there are no signals between them. The magic name
2731
"unused" (-unused-regexp) is recognized by Verilator and suppresses
2732
warnings; if using other lint tools, either teach to tool to ignore signals
2733
with "unused" in the name, or put the appropriate lint_off around the wire.
2734
Having unused signals in one place makes it easy to find what is unused,
2735
and reduces the number of lint_off pragmas, reducing bugs.
2492
2737
=item VARHIDDEN
2494
2739
Warns that a task, function, or begin/end block is declaring a variable by
2496
2741
(thus hiding the upper variable from being able to be used.) Rename the
2497
2742
variable to avoid confusion when reading the code.
2499
Ignoring this warning will only suppress the lint check, it will simulate
2744
Disabled by default as this is a code style warning; it will simulate
2810
3055
=item Is the PLI supported?
3057
Only somewhat. More specifically, the common PLI-ish calls $display,
3058
$finish, $stop, $time, $write are converted to C++ equivalents. You can
3059
also use the "import DPI" SystemVerilog feature to call C code (see the
3060
chapter above). There is also limited VPI access to public signals.
2814
More specifically, the common PLI-ish calls $display, $finish, $stop,
2815
$time, $write are converted to C++ equivalents. You can also use the
2816
"import DPI" SystemVerilog feature to call C code (see the chapter above).
2817
3062
If you want something more complex, since Verilator emits standard C++
2818
3063
code, you can simply write your own C++ routines that can access and modify
2819
3064
signal values without needing any PLI interface code, and call it with
3013
3258
The latest version is available from L<http://www.veripool.org/>.
3015
Copyright 2003-2010 by Wilson Snyder. Verilator is free software; you can
3260
Copyright 2003-2011 by Wilson Snyder. Verilator is free software; you can
3016
3261
redistribute it and/or modify the Verilator internals under the terms of
3017
3262
either the GNU Lesser General Public License Version 3 or the Perl Artistic
3018
3263
License Version 2.0.
added
removed
bin/verilator
