1VERILATOR(1) User Contributed Perl Documentation VERILATOR(1)
2
6 Verilator - Convert Verilog code to C++/SystemC
7
9 verilator --help
10 verilator --version
11 verilator --cc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
12 verilator --sc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
13 verilator --lint-only -Wall [source_files.v]...
14
16 Verilator converts synthesizable (generally not behavioral) Verilog
17 code, plus some Synthesis, SystemVerilog and a small subset of Verilog
18 AMS into C++ or SystemC code. It is not a complete simulator, but a
19 compiler.
20 Verilator is invoked with parameters similar to GCC, Cadence
22 Verilog-XL/NC-Verilog, or Synopsys's VCS. It reads the specified
23 Verilog code, lints it, and optionally adds coverage and waveform
24 tracing code. For C++ and SystemC formats, it outputs .cpp and .h
25 files.
26 The files created by Verilator are then compiled with C++. The user
28 writes a little C++ wrapper file, which instantiates the top level
29 module, and passes this filename on the command line. These C files
30 are compiled in C++, and linked with the Verilated files.
31 The resulting executable will perform the actual simulation.
33 To get started, jump down to "EXAMPLE C++ EXECUTION".
35
37 This is a short summary of the arguments to Verilator itself. See the
38 detailed descriptions in "VERILATION ARGUMENTS" for more information.
39 {file.v} Verilog package, module and top module filenames
41 {file.c/cc/cpp} Optional C++ files to compile in
42 {file.a/o/so} Optional C++ files to link in
43 +1364-1995ext+<ext> Use Verilog 1995 with file extension <ext>
45 +1364-2001ext+<ext> Use Verilog 2001 with file extension <ext>
46 +1364-2005ext+<ext> Use Verilog 2005 with file extension <ext>
47 +1800-2005ext+<ext> Use SystemVerilog 2005 with file extension <ext>
48 +1800-2009ext+<ext> Use SystemVerilog 2009 with file extension <ext>
49 +1800-2012ext+<ext> Use SystemVerilog 2012 with file extension <ext>
50 +1800-2017ext+<ext> Use SystemVerilog 2017 with file extension <ext>
51 --assert Enable all assertions
52 --autoflush Flush streams after all $displays
53 --bbox-sys Blackbox unknown $system calls
54 --bbox-unsup Blackbox unsupported language features
55 --bin <filename> Override Verilator binary
56 -CFLAGS <flags> C++ Compiler flags for makefile
57 --cc Create C++ output
58 --cdc Clock domain crossing analysis
59 --clk <signal-name> Mark specified signal as clock
60 --compiler <compiler-name> Tune for specified C++ compiler
61 --converge-limit <loops> Tune convergence settle time
62 --coverage Enable all coverage
63 --coverage-line Enable line coverage
64 --coverage-toggle Enable toggle coverage
65 --coverage-user Enable SVL user coverage
66 --coverage-underscore Enable coverage of _signals
67 -D<var>[=<value>] Set preprocessor define
68 --debug Enable debugging
69 --debug-check Enable debugging assertions
70 --no-debug-leak Disable leaking memory in --debug mode
71 --debugi <level> Enable debugging at a specified level
72 --debugi-<srcfile> <level> Enable debugging a source file at a level
73 --default-language <lang> Default language to parse
74 +define+<var>=<value> Set preprocessor define
75 --dump-defines Show preprocessor defines with -E
76 --dump-tree Enable dumping .tree files
77 --dump-treei <level> Enable dumping .tree files at a level
78 --dump-treei-<srcfile> <level> Enable dumping .tree file at a source file at a level
79 -E Preprocess, but do not compile
80 --error-limit <value> Abort after this number of errors
81 --exe Link to create executable
82 -F <file> Parse options from a file, relatively
83 -f <file> Parse options from a file
84 -FI <file> Force include of a file
85 -G<name>=<value> Overwrite toplevel parameter
86 --gdb Run Verilator under GDB interactively
87 --gdbbt Run Verilator under GDB for backtrace
88 --getenv <var> Get environment variable with defaults
89 --help Display this help
90 -I<dir> Directory to search for includes
91 --gate-stmts <value> Tune gate optimizer depth
92 --if-depth <value> Tune IFDEPTH warning
93 +incdir+<dir> Directory to search for includes
94 --inhibit-sim Create function to turn off sim
95 --inline-mult <value> Tune module inlining
96 -LDFLAGS <flags> Linker pre-object flags for makefile
97 -LDLIBS <flags> Linker library flags for makefile
98 --l2-name <value> Verilog scope name of the top module
99 --language <lang> Default language standard to parse
100 +libext+<ext>+[ext]... Extensions for finding modules
101 --lint-only Lint, but do not make output
102 --MMD Create .d dependency files
103 --MP Create phony dependency targets
104 --Mdir <directory> Name of output object directory
105 --mod-prefix <topname> Name to prepend to lower classes
106 --no-clk <signal-name> Prevent marking specified signal as clock
107 --no-decoration Disable comments and symbol decorations
108 --no-pins64 Don't use vluint64_t's for 33-64 bit sigs
109 --no-skip-identical Disable skipping identical output
110 +notimingchecks Ignored
111 -O0 Disable optimizations
112 -O3 High performance optimizations
113 -O<optimization-letter> Selectable optimizations
114 -o <executable> Name of final executable
115 --no-order-clock-delay Disable ordering clock enable assignments
116 --output-split <bytes> Split .cpp files into pieces
117 --output-split-cfuncs <statements> Split .cpp functions
118 --output-split-ctrace <statements> Split tracing functions
119 -P Disable line numbers and blanks with -E
120 --pins-bv <bits> Specify types for top level ports
121 --pins-sc-uint Specify types for top level ports
122 --pins-sc-biguint Specify types for top level ports
123 --pins-uint8 Specify types for top level ports
124 --pipe-filter <command> Filter all input through a script
125 --pp-comments Show preprocessor comments with -E
126 --prefix <topname> Name of top level class
127 --prof-cfuncs Name functions for profiling
128 --prof-threads Enable generating gantt chart data for threads
129 --private Debugging; see docs
130 --public Debugging; see docs
131 -pvalue+<name>=<value> Overwrite toplevel parameter
132 --quiet-exit Don't print the command on failure
133 --relative-includes Resolve includes relative to current file
134 --no-relative-cfuncs Disallow 'this->' in generated functions
135 --report-unoptflat Extra diagnostics for UNOPTFLAT
136 --savable Enable model save-restore
137 --sc Create SystemC output
138 --stats Create statistics file
139 --stats-vars Provide statistics on variables
140 -sv Enable SystemVerilog parsing
141 +systemverilogext+<ext> Synonym for +1800-2017ext+<ext>
142 --threads <threads> Enable multithreading
143 --threads-dpi <mode> Enable multithreaded DPI
144 --threads-max-mtasks <mtasks> Tune maximum mtask partitioning
145 --top-module <topname> Name of top level input module
146 --trace Enable waveform creation
147 --trace-fst Enable FST waveform creation
148 --trace-fst-thread Enable FST threaded waveform creation
149 --trace-depth <levels> Depth of tracing
150 --trace-max-array <depth> Maximum bit width for tracing
151 --trace-max-width <width> Maximum array depth for tracing
152 --trace-params Enable tracing parameters
153 --trace-structs Enable tracing structure names
154 --trace-underscore Enable tracing of _signals
155 -U<var> Undefine preprocessor define
156 --unroll-count <loops> Tune maximum loop iterations
157 --unroll-stmts <stmts> Tune maximum loop body size
158 --unused-regexp <regexp> Tune UNUSED lint signals
159 -V Verbose version and config
160 -v <filename> Verilog library
161 +verilog1995ext+<ext> Synonym for +1364-1995ext+<ext>
162 +verilog2001ext+<ext> Synonym for +1364-2001ext+<ext>
163 --version Displays program version and exits
164 --vpi Enable VPI compiles
165 -Wall Enable all style warnings
166 -Werror-<message> Convert warnings to errors
167 -Wfuture-<message> Disable unknown message warnings
168 -Wno-<message> Disable warning
169 -Wno-lint Disable all lint warnings
170 -Wno-style Disable all style warnings
171 -Wno-fatal Disable fatal exit on warnings
172 --x-assign <mode> Assign non-initial Xs to this value
173 --x-initial <mode> Assign initial Xs to this value
174 --x-initial-edge Enable initial X->0 and X->1 edge triggers
175 --xml-only Create XML parser output
176 -y <dir> Directory to search for modules
177 This is a short summary of the arguments to run-time Verilated
179 arguments. detailed descriptions in "RUNTIME ARGUMENTS" for more
180 information.
181 +verilator+debug Enable debugging
183 +verilator+debugi+<value> Enable debugging at a level
184 +verilator+help Display help
185 +verilator+prof+threads+file+I<filename> Set profile filename
186 +verilator+prof+threads+start+I<value> Set profile starting point
187 +verilator+prof+threads+window+I<value> Set profile duration
188 +verilator+rand+reset+I<value> Set random reset technique
189 +verilator+seed+I<value> Set random seed
190 +verilator+V Verbose version and config
191 +verilator+version Show version and exit
192
194 The following are the arguments that may be passed to Verilator itself.
195 {file.v}
197 Specifies the Verilog file containing the top module to be
198 Verilated.
199 {file.c/.cc/.cpp/.cxx}
201 Specifies optional C++ files to be linked in with the Verilog code.
202 The file path should either be absolute, or relative to where the
203 make will be executed from, or add to your makefile's VPATH the
204 appropriate directory to find the file.
205 If any C++ files are specified in this way, Verilator will include
207 a make rule that generates a module executable. Without any C++
208 files, Verilator will stop at the module__ALL.a library, and
209 presume you'll continue linking with make rules you write yourself.
210 See also the -CFLAGS option.
211 {file.a/.o/.so}
213 Specifies optional object or library files to be linked in with the
214 Verilog code, as a shorthand for -LDFLAGS "<file>". The file path
215 should either be absolute, or relative to where the make will be
216 executed from, or add to your makefile's VPATH the appropriate
217 directory to find the file.
218 If any files are specified in this way, Verilator will include a
220 make rule that uses these files when linking the module executable.
221 This generally is only useful when used with the --exe option.
222 +1364-1995ext+ext
224 +1364-2001ext+ext
225 +1364-2005ext+ext
226 +1800-2005ext+ext
227 +1800-2009ext+ext
228 +1800-2012ext+ext
229 +1800-2017ext+ext
230 Specifies the language standard to be used with a specific filename
231 extension, ext.
232 For compatibility with other simulators, see also the synonyms
234 "+verilog1995ext+"ext, "+verilog2001ext+"ext, and
235 "+systemverilogext+"ext.
236 For any source file, the language specified by these options takes
238 precedence over any language specified by the "--default-language"
239 or "--language" options.
240 These options take effect in the order they are encountered. Thus
242 the following would use Verilog 1995 for "a.v" and Verilog 2001 for
243 "b.v".
244 verilator ... +1364-1995ext+v a.v +1364-2001ext+v b.v
246 These flags are only recommended for legacy mixed language designs,
248 as the preferable option is to edit the code to repair new
249 keywords, or add appropriate "`begin_keywords".
250 Note "`begin_keywords" is a SystemVerilog construct, which
252 specifies only which the set of keywords is to be recognized.
253 Whatever set is chosen, the semantics will be those of
254 SystemVerilog. By contrast "+1364-1995ext+" etc. specify both the
255 syntax and semantics to be used.
256 --assert
258 Enable all assertions.
259 --autoflush
261 After every $display or $fdisplay, flush the output stream. This
262 ensures that messages will appear immediately but may reduce
263 performance; for best performance call "fflush(stdout)"
264 occasionally in the main C loop. Defaults off, which will buffer
265 output as provided by the normal C stdio calls.
266 --bbox-sys
268 Black box any unknown $system task or function calls. System tasks
269 will be simply NOPed, and system functions will be replaced by
270 unsized zero. Arguments to such functions will be parsed, but not
271 otherwise checked. This prevents errors when linting in the
272 presence of company specific PLI calls.
273 --bbox-unsup
275 Black box some unsupported language features, currently UDP tables,
276 the cmos and tran gate primitives, deassign statements, and mixed
277 edge errors. This may enable linting the rest of the design even
278 when unsupported constructs are present.
279 --bin filename
281 Rarely needed. Override the default filename for Verilator itself.
282 When a dependency (.d) file is created, this filename will become a
283 source dependency, such that a change in this binary will have make
284 rebuild the output files.
285 -CFLAGS flags
287 Add specified C compiler flag to the generated makefiles. For
288 multiple flags either pass them as a single argument with space
289 separators quoted in the shell ("-CFLAGS "-a -b""), or use multiple
290 -CFLAGS arguments ("-CFLAGS -a -CFLAGS -b").
291 When make is run on the generated makefile these will be passed to
293 the C++ compiler (gcc/g++/msvc++).
294 --cc
296 Specifies C++ without SystemC output mode; see also --sc.
297 --cdc
299 Experimental. Perform some clock domain crossing checks and issue
300 related warnings (CDCRSTLOGIC) and then exit; if warnings other
301 than CDC warnings are needed make a second run with --lint-only.
302 Additional warning information is also written to the file
303 {prefix}__cdc.txt.
304 Currently only checks some items that other CDC tools missed; if
306 you have interest in adding more traditional CDC checks, please
307 contact the authors.
308 --clk signal-name
310 Sometimes it is quite difficult for Verilator to distinguish clock
311 signals from other data signals. Occasionally the clock signals can
312 end up in the checking list of signals which determines if further
313 evaluation is needed. This will heavily degrade the performance of
314 a Verilated model.
315 With --clk <signal-name>, user can specified root clock into the
317 model, then Verilator will mark the signal as clocker and propagate
318 the clocker attribute automatically to other signals derived from
319 that. In this way, Verilator will try to avoid taking the clocker
320 signal into checking list.
321 Note signal-name is specified by the RTL hierarchy path. For
323 example, v.foo.bar. If the signal is the input to top-module, the
324 directly the signal name. If you find it difficult to find the
325 exact name, try to use "/*verilator clocker*/" in RTL file to mark
326 the signal directly.
327 If clock signals are assigned to vectors and then later used
329 individually, Verilator will attempt to decompose the vector and
330 connect the single-bit clock signals directly. This should be
331 transparent to the user.
332 --compiler compiler-name
334 Enables tunings and workarounds for the specified C++ compiler.
335 clang
337 Tune for clang. This may reduce execution speed as it enables
338 several workarounds to avoid silly hardcoded limits in clang.
339 This includes breaking deep structures as for msvc as described
340 below.
341 gcc Tune for GNU C++, although generated code should work on almost
343 any compliant C++ compiler. Currently the default.
344 msvc
346 Tune for Microsoft Visual C++. This may reduce execution speed
347 as it enables several workarounds to avoid silly hardcoded
348 limits in MSVC++. This includes breaking deeply nested
349 parenthesized expressions into sub-expressions to avoid error
350 C1009, and breaking deep blocks into functions to avoid error
351 C1061.
352 --converge-limit loops
354 Rarely needed. Specifies the maximum number of runtime iterations
355 before creating a model failed to converge error. Defaults to 100.
356 --coverage
358 Enables all forms of coverage, alias for "--coverage-line
359 --coverage-toggle --coverage-user".
360 --coverage-line
362 Specifies basic block line coverage analysis code should be
363 inserted.
364 Coverage analysis adds statements at each code flow change point,
366 which are the branches of IF and CASE statements, a super-set of
367 normal Verilog Line Coverage. At each such branch a unique counter
368 is incremented. At the end of a test, the counters along with the
369 filename and line number corresponding to each counter are written
370 into logs/coverage.dat.
371 Verilator automatically disables coverage of branches that have a
373 $stop in them, as it is assumed $stop branches contain an error
374 check that should not occur. A /*verilator coverage_block_off*/
375 comment will perform a similar function on any code in that block
376 or below, or /*verilator coverage_on/coverage_off*/ will disable
377 coverage around lines of code.
378 Note Verilator may over-count combinatorial (non-clocked) blocks
380 when those blocks receive signals which have had the UNOPTFLAT
381 warning disabled; for most accurate results do not disable this
382 warning when using coverage.
383 --coverage-toggle
385 Specifies signal toggle coverage analysis code should be inserted.
386 Every bit of every signal in a module has a counter inserted. The
388 counter will increment on every edge change of the corresponding
389 bit.
390 Signals that are part of tasks or begin/end blocks are considered
392 local variables and are not covered. Signals that begin with
393 underscores, are integers, or are very wide (>256 bits total
394 storage across all dimensions) are also not covered.
395 Hierarchy is compressed, such that if a module is instantiated
397 multiple times, coverage will be summed for that bit across ALL
398 instantiations of that module with the same parameter set. A
399 module instantiated with different parameter values is considered a
400 different module, and will get counted separately.
401 Verilator makes a minimally-intelligent decision about what clock
403 domain the signal goes to, and only looks for edges in that clock
404 domain. This means that edges may be ignored if it is known that
405 the edge could never be seen by the receiving logic. This
406 algorithm may improve in the future. The net result is coverage
407 may be lower than what would be seen by looking at traces, but the
408 coverage is a more accurate representation of the quality of
409 stimulus into the design.
410 There may be edges counted near time zero while the model
412 stabilizes. It's a good practice to zero all coverage just before
413 releasing reset to prevent counting such behavior.
414 A /*verilator coverage_off/on */ comment pair can be used around
416 signals that do not need toggle analysis, such as RAMs and register
417 files.
418 --coverage-underscore
420 Enable coverage of signals that start with an underscore. Normally,
421 these signals are not covered. See also --trace-underscore.
422 --coverage-user
424 Enables user inserted functional coverage. Currently, all
425 functional coverage points are specified using SVA which must be
426 separately enabled with --assert.
427 For example, the following statement will add a coverage point,
429 with the comment "DefaultClock":
430 DefaultClock: cover property (@(posedge clk) cyc==3);
432 -Dvar=value
434 Defines the given preprocessor symbol, without allowing. Similar
435 to +define; +define is fairly standard across Verilog tools while
436 -D is an alias for GCC compatibility.
437 --debug
439 Select the debug built image of Verilator (if available), and
440 enable more internal assertions (equivalent to "--debug-check"),
441 debugging messages (equivalent to "--debugi 4"), and intermediate
442 form dump files (equivalent to "--dump-treei 3").
443 --debug-check
445 Rarely needed. Enable internal debugging assertion checks, without
446 changing debug verbosity. Enabled automatically when --debug
447 specified.
448 --no-debug-leak
450 In --debug mode, by default Verilator intentionally leaks AstNode's
451 instead of freeing them, so that each node pointer is unique in the
452 resulting tree files and dot files.
453 This option disables the leak. This may avoid out-of-memory errors
455 when Verilating large models in --debug mode.
456 Outside of --debug mode, AstNode's should never be leaked and this
458 option has no effect.
459 --debugi level
461 --debugi-srcfile level
462 Rarely needed - for developer use. Set internal debugging level
463 globally to the specified debug level (1-10) or set the specified
464 Verilator source file to the specified level (e.g.
465 "--debugi-V3Width 9"). Higher levels produce more detailed
466 messages.
467 --default-language value
469 Select the language to be used by default when first processing
470 each Verilog file. The language value must be "1364-1995",
471 "1364-2001", "1364-2005", "1800-2005", "1800-2009", "1800-2012" or
472 "1800-2017".
473 Any language associated with a particular file extension (see the
475 various +langext+ options) will be used in preference to the
476 language specified by --default-language.
477 The --default-language flag is only recommended for legacy code
479 using the same language in all source files, as the preferable
480 option is to edit the code to repair new keywords, or add
481 appropriate "`begin_keywords". For legacy mixed language designs,
482 the various +langext+ options should be used.
483 If no language is specified, either by this flag or +langext+
485 options, then the latest SystemVerilog language (IEEE 1800-2017) is
486 used.
487 +define+var=value
489 +define+var=value+var2=value2...
490 Defines the given preprocessor symbol, or multiple symbols if
491 separated by plusses. Similar to -D; +define is fairly standard
492 across Verilog tools while -D is an alias for GCC compatibility.
493 --dump-defines
495 With -E, suppress normal output, and instead print a list of all
496 defines existing at the end of pre-processing the input files.
497 Similar to GCC "-dM" option. This also gives you a way of finding
498 out what is predefined in Verilator using the command:
499 touch foo.v ; verilator -E --dump-defines foo.v
501 --dump-tree
503 Rarely needed. Enable writing .tree debug files with dumping level
504 3, which dumps the standard critical stages. For details on the
505 format see the Verilator Internals manual. --dump-tree is enabled
506 automatically with --debug, so "--debug --no-dump-tree" may be
507 useful if the dump files are large and not desired.
508 --dump-treei level
510 --dump-treei-srcfile level
511 Rarely needed - for developer use. Set internal tree dumping level
512 globally to a specific dumping level or set the specified Verilator
513 source file to the specified tree dumping level (e.g.
514 "--dump-treei-V3Order 9"). Level 0 disbles dumps and is equivalent
515 to "--no-dump-tree". Level 9 enables dumping of every stage.
516 -E Preprocess the source code, but do not compile, as with 'gcc -E'.
518 Output is written to standard out. Beware of enabling debugging
519 messages, as they will also go to standard out.
520 --error-limit value
522 After this number of errors or warnings are encountered, exit.
523 Defaults to 50.
524 --exe
526 Generate an executable. You will also need to pass additional .cpp
527 files on the command line that implement the main loop for your
528 simulation.
529 -F file
531 Read the specified file, and act as if all text inside it was
532 specified as command line parameters. Any relative paths are
533 relative to the directory containing the specified file. See also
534 -f. Note -F is fairly standard across Verilog tools.
535 -f file
537 Read the specified file, and act as if all text inside it was
538 specified as command line parameters. Any relative paths are
539 relative to the current directory. See also -F. Note -f is fairly
540 standard across Verilog tools.
541 The file may contain // comments which are ignored to the end of
543 the line. Any $VAR, $(VAR), or ${VAR} will be replaced with the
544 specified environment variable.
545 -FI file
547 Force include of the specified C++ header file. All generated C++
548 files will insert a #include of the specified file before any other
549 includes. The specified file might be used to contain define
550 prototypes of custom VL_VPRINTF functions, and may need to include
551 verilatedos.h as this file is included before any other standard
552 includes.
553 -Gname=value
555 Overwrites the given parameter of the toplevel module. The value is
556 limited to basic data literals:
557 Verilog integer literals
559 The standard verilog integer literals are supported, so values
560 like 32'h8, 2'b00, 4 etc. are allowed. Care must be taken that
561 the single quote (I') is properly escaped in an interactive
562 shell, e.g., as -GWIDTH=8\'hx.
563 C integer literals
565 It is also possible to use C integer notation, including
566 hexadecimal (0x..), octal (0..) or binary (0b..) notation.
567 Double literals
569 Double literals must contain a dot (.) and/or an exponent (e).
570 Strings
572 String must in double quotes (""). On the command line it is
573 required to escape them properly, e.g. as -GSTR="\"My String\""
574 or -GSTR='"My String"'.
575 --gate-stmts value
577 Rarely needed. Set the maximum number of statements that may be
578 present in an equation for the gate substitution optimization to
579 inline that equation.
580 --gdb
582 Run Verilator underneath an interactive GDB (or VERILATOR_GDB
583 environment variable value) session. See also --gdbbt.
584 --gdbbt
586 If --debug is specified, run Verilator underneath a GDB process and
587 print a backtrace on exit, then exit GDB immediately. Without
588 --debug or if GDB doesn't seem to work, this flag is ignored.
589 Intended for easy creation of backtraces by users; otherwise see
590 the --gdb flag.
591 --getenv variable
593 If the variable is declared in the environment, print it and exit
594 immediately. Otherwise, if it's built into Verilator (e.g.
595 VERILATOR_ROOT), print that and exit immediately. Otherwise, print
596 a newline and exit immediately. This can be useful in makefiles.
597 See also -V, and the various *.mk files.
598 --help
600 Displays this message and program version and exits.
601 -Idir
603 See -y.
604 --if-depth value
606 Rarely needed. Set the depth at which the IFDEPTH warning will
607 fire, defaults to 0 which disables this warning.
608 +incdir+dir
610 See -y.
611 --inhibit-sim
613 Rarely needed. Create a "inhibitSim(bool)" function to enable and
614 disable evaluation. This allows an upper level testbench to
615 disable modules that are not important in a given simulation,
616 without needing to recompile or change the SystemC modules
617 instantiated.
618 --inline-mult value
620 Tune the inlining of modules. The default value of 2000 specifies
621 that up to 2000 new operations may be added to the model by
622 inlining, if more than this number of operations would result, the
623 module is not inlined. Larger values, or a value < 1 will inline
624 everything, will lead to longer compile times, but potentially
625 faster runtimes. This setting is ignored for very small modules;
626 they will always be inlined, if allowed.
627 -LDFLAGS flags
629 Add specified C linker flags to the generated makefiles. For
630 multiple flags either pass them as a single argument with space
631 separators quoted in the shell ("-LDFLAGS "-a -b""), or use
632 multiple -LDFLAGS arguments ("-LDFLAGS -a -LDFLAGS -b").
633 When make is run on the generated makefile these will be passed to
635 the C++ linker (ld) *after* the primary file being linked. This
636 flag is called -LDFLAGS as that's the traditional name in
637 simulators; it's would have been better called LDLIBS as that's the
638 Makefile variable it controls. (In Make, LDFLAGS is before the
639 first object, LDLIBS after. -L libraries need to be in the Make
640 variable LDLIBS, not LDFLAGS.)
641 --l2-name value
643 Instead of using the module name when showing Verilog scope, use
644 the name provided. This allows simplifying some Verilator-embedded
645 modeling methodologies. Default is an l2-name matching the top
646 module. The default before 3.884 was "--l2-name v"
647 For example, the program "module t; initial $display("%m");
649 endmodule" will show by default "t". With "--l2-name v" it will
650 print "v".
651 --language value
653 A synonym for "--default-language", for compatibility with other
654 tools and earlier versions of Verilator.
655 +libext+ext+ext...
657 Specify the extensions that should be used for finding modules. If
658 for example module x is referenced, look in x.ext. Note +libext+
659 is fairly standard across Verilog tools. Defaults to .v and .sv.
660 --lint-only
662 Check the files for lint violations only, do not create any other
663 output.
664 You may also want the -Wall option to enable messages that are
666 considered stylistic and not enabled by default.
667 If the design is not to be completely Verilated see also the
669 --bbox-sys and --bbox-unsup options.
670 --MMD
672 Enable creation of .d dependency files, used for make dependency
673 detection, similar to gcc -MMD option. On by default, use --no-MMD
674 to disable.
675 --MP
677 When creating .d dependency files with --MMD, make phony targets.
678 Similar to gcc -MP option.
679 --Mdir directory
681 Specifies the name of the Make object directory. All generated
682 files will be placed in this directory. If not specified,
683 "obj_dir" is used. The directory is created if it does not exist
684 and the parent directories exist; otherwise manually create the
685 Mdir before calling Verilator.
686 --mod-prefix topname
688 Specifies the name to prepend to all lower level classes. Defaults
689 to the same as --prefix.
690 --no-clk signal-name
692 Prevent the specified signal from being marked as clock. See
693 "--clk".
694 --no-decoration
696 When creating output Verilated code, minimize comments, whitespace,
697 symbol names and other decorative items, at the cost of greatly
698 reduced readability. This may assist C++ compile times. This will
699 not typically change the ultimate model's performance, but may in
700 some cases.
701 --no-pins64
703 Backward compatible alias for "--pins-bv 33".
704 --no-relative-cfuncs
706 Disable 'this->' references in generated functions, and instead
707 Verilator will generate absolute references starting from
708 'vlTOPp->'. This prevents V3Combine from merging functions from
709 multiple instances of the same module, so it can grow the
710 instruction stream.
711 This is a work around for old compilers. Don't set this if your C++
713 compiler supports __restrict__ properly, as GCC 4.5.x and newer do.
714 For older compilers, test if this switch gives you better
715 performance or not.
716 Compilers which don't honor __restrict__ will suspect that 'this->'
718 references and 'vlTOPp->' references may alias, and may write slow
719 code with extra loads and stores to handle the (imaginary)
720 aliasing. Using only 'vlTOPp->' references allows these old
721 compilers to produce tight code.
722 --no-skip-identical
724 Rarely needed. Disables skipping execution of Verilator if all
725 source files are identical, and all output files exist with newer
726 dates.
727 +notimingchecks
729 Ignored for compatibility with other simulators.
730 -O0 Disables optimization of the model.
732 -O3 Enables slow optimizations for the code Verilator itself generates
734 (as opposed to "-CFLAGS -O3" which effects the C compiler's
735 optimization. -O3 may reduce simulation runtimes at the cost of
736 compile time. This currently sets --inline-mult -1.
737 -Ooptimization-letter
739 Rarely needed. Enables or disables a specific optimizations, with
740 the optimization selected based on the letter passed. A lowercase
741 letter disables an optimization, an upper case letter enables it.
742 This is intended for debugging use only; see the source code for
743 version-dependent mappings of optimizations to -O letters.
744 -o executable
746 Specify the name for the final executable built if using --exe.
747 Defaults to the --prefix if not specified.
748 --no-order-clock-delay
750 Rarely needed. Disables a bug fix for ordering of clock enables
751 with delayed assignments. This flag should only be used when
752 suggested by the developers.
753 --output-split bytes
755 Enables splitting the output .cpp files into multiple outputs.
756 When a C++ file exceeds the specified number of operations, a new
757 file will be created at the next function boundary. In addition,
758 any infrequently executed "cold" routines will be placed into
759 __Slow files. This accelerates compilation by as optimization can
760 be disabled on the routines in __Slow, and the remaining files can
761 be compiled on parallel machines. Using --output-split should have
762 only a trivial impact on performance. With GCC 3.3 on a 2GHz
763 Opteron, --output-split 20000 will result in splitting into
764 approximately one-minute-compile chunks.
765 --output-split-cfuncs statements
767 Enables splitting functions in the output .cpp files into multiple
768 functions. When a generated function exceeds the specified number
769 of operations, a new function will be created. With
770 --output-split, this will enable GCC to compile faster, at a small
771 loss in performance that gets worse with decreasing split values.
772 Note that this option is stronger than --output-split in the sense
773 that --output-split will not split inside a function.
774 --output-split-ctrace statements
776 Enables splitting trace functions in the output .cpp files into
777 multiple functions. Defaults to same setting as
778 --output-split-cfuncs.
779 -P With -E, disable generation of `line markers and blank lines,
781 similar to GCC -P flag.
782 --pins64
784 Backward compatible alias for "--pins-bv 65". Note that's a 65,
785 not a 64.
786 --pins-bv width
788 Specifies SystemC inputs/outputs of greater than or equal to width
789 bits wide should use sc_bv's instead of uint32/vluint64_t's. The
790 default is "--pins-bv 65", and the value must be less than or equal
791 to 65. Versions before Verilator 3.671 defaulted to "--pins-bv
792 33". The more sc_bv is used, the worse for performance. Use the
793 "/*verilator sc_bv*/" attribute to select specific ports to be
794 sc_bv.
795 --pins-sc-uint
797 Specifies SystemC inputs/outputs of greater than 2 bits wide should
798 use sc_uint between 2 and 64. When combined with the
799 "--pins-sc-biguint" combination, it results in sc_uint being used
800 between 2 and 64 and sc_biguint being used between 65 and 512.
801 --pins-sc-biguint
803 Specifies SystemC inputs/outputs of greater than 65 bits wide
804 should use sc_biguint between 65 and 512, and sc_bv from 513
805 upwards. When combined with the "--pins-sc-uint" combination, it
806 results in sc_uint being used between 2 and 64 and sc_biguint being
807 used between 65 and 512.
808 --pins-uint8
810 Specifies SystemC inputs/outputs that are smaller than the
811 --pins-bv setting and 8 bits or less should use uint8_t instead of
812 uint32_t. Likewise pins of width 9-16 will use uint16_t instead of
813 uint32_t.
814 --pipe-filter command
816 Rarely needed and experimental. Verilator will spawn the specified
817 command as a subprocess pipe, to allow the command to perform
818 custom edits on the Verilog code before it reaches Verilator.
819 Before reading each Verilog file, Verilator will pass the file name
821 to the subprocess' stdin with 'read_verilog "<filename>"'. The
822 filter may then read the file and perform any filtering it desires,
823 and feeds the new file contents back to Verilator on stdout with
824 'Content-Length'. Output to stderr from the filter feeds through
825 to Verilator's stdout and if the filter exits with non-zero status
826 Verilator terminates. See the t/t_pipe_filter test for an example.
827 To debug the output of the filter, try using the -E option to see
829 preprocessed output.
830 --pp-comments
832 With -E, show comments in preprocessor output.
833 --prefix topname
835 Specifies the name of the top level class and makefile. Defaults
836 to V prepended to the name of the --top-module switch, or V
837 prepended to the first Verilog filename passed on the command line.
838 --prof-cfuncs
840 Modify the created C++ functions to support profiling. The
841 functions will be minimized to contain one "basic" statement,
842 generally a single always block or wire statement. (Note this will
843 slow down the executable by ~5%.) Furthermore, the function name
844 will be suffixed with the basename of the Verilog module and line
845 number the statement came from. This allows gprof or oprofile
846 reports to be correlated with the original Verilog source
847 statements. See also verilator_profcfunc.
848 --prof-threads
850 Enable gantt chart data collection for threaded builds.
851 Verilator will record the start and end time of each macro-task
853 across a number of calls to eval. (What is a macro-task? See the
854 Verilator internals document.)
855 When profiling is enabled, the runtime will emit a blurb of
857 profiling data in non-human-friendly form. The "verilator_gantt"
858 script will transform this into a nicer visual format and produce
859 some related statistics.
860 --private
862 Opposite of --public. Is the default; this option exists for
863 backwards compatibility.
864 --public
866 This is only for historical debug use. Using it may result in mis-
867 simulation of generated clocks.
868 Declares all signals and modules public. This will turn off signal
870 optimizations as if all signals had a /*verilator public*/ comments
871 and inlining. This will also turn off inlining as if all modules
872 had a /*verilator public_module*/, unless the module specifically
873 enabled it with /*verilator inline_module*/.
874 -pvalue+name=value
876 Overwrites the given parameter(s) of the toplevel module. See -G
877 for a detailed description.
878 --quiet-exit
880 When exiting due to an error, do not display the "Command Failed"
881 message.
882 --relative-includes
884 When a file references an include file, resolve the filename
885 relative to the path of the referencing file, instead of relative
886 to the current directory.
887 --report-unoptflat
889 Extra diagnostics for UNOPTFLAT warnings. This includes for each
890 loop, the 10 widest variables in the loop, and the 10 most fanned
891 out variables in the loop. These are candidates for splitting into
892 multiple variables to break the loop.
893 In addition produces a GraphViz DOT file of the entire strongly
895 connected components within the source associated with each loop.
896 This is produced irrespective of whether --dump-tree is set. Such
897 graphs may help in analyzing the problem, but can be very large
898 indeed.
899 Various commands exist for viewing and manipulating DOT files. For
901 example the dot command can be used to convert a DOT file to a PDF
902 for printing. For example:
903 dot -Tpdf -O Vt_unoptflat_simple_2_35_unoptflat.dot
905 will generate a PDF Vt_unoptflat_simple_2_35_unoptflat.dot.pdf from
907 the DOT file.
908 --savable
910 Enable including save and restore functions in the generated model.
911 The user code must create a VerilatedSerialize or
913 VerilatedDeserialze object then calling the << or >> operators on
914 the generated model and any other data the process needs
915 saved/restored. These functions are not thread safe, and are
916 typically called only by a main thread.
917 For example:
919 void save_model(const char* filenamep) {
921 VerilatedSave os;
922 os.open(filenamep);
923 os << main_time; // user code must save the timestamp, etc
924 os << *topp;
925 }
926 void restore_model(const char* filenamep) {
927 VerilatedRestore os;
928 os.open(filenamep);
929 os >> main_time;
930 os >> *topp;
931 }
932 --sc
934 Specifies SystemC output mode; see also --cc.
935 --stats
937 Creates a dump file with statistics on the design in
938 {prefix}__stats.txt.
939 --stats-vars
941 Creates more detailed statistics, including a list of all the
942 variables by size (plain --stats just gives a count). See --stats,
943 which is implied by this.
944 -sv Specifies SystemVerilog language features should be enabled;
946 equivalent to "--language 1800-2005". This option is selected by
947 default, it exists for compatibility with other simulators.
948 +systemverilogext+ext
950 A synonym for "+1800-2017ext+"ext.
951 --threads threads
953 --no-threads
954 With --threads 0 or --no-threads, the default, the generated model
955 is not thread safe. With --threads 1, the generated model is single
956 threaded but may run in a multithreaded environment. With --threads
957 N, where N >= 2, the model is generated to run multithreaded on up
958 to N threads. See "MULTITHREADING".
959 --threads-dpi all
961 --threads-dpi none
962 --threads-dpi pure
963 When using --dpi with --threads, control what DPI tasks are thread
964 safe.
965 With --threads-dpi all, enable Verilator to assume all DPI imports
967 are threadsafe, and to use thread-local storage for communication
968 with DPI, potentially improving performance. Any DPI libraries need
969 appropriate mutexes to avoid undefined behavior.
970 With --threads-dpi none, Verilator assume DPI imports are not
972 thread safe, and Verilator will serialize calls to DPI imports by
973 default, potentially harming performance.
974 With --threads-dpi pure, the default, Verilator assumes DPI pure
976 imports are threadsafe, but non-pure DPI imports are not.
977 --threads-max-mtasks value
979 Rarely needed. When using --threads, specify the number of mtasks
980 the model is to be partitioned into. If unspecified, Verilator
981 approximates a good value.
982 --top-module topname
984 When the input Verilog contains more than one top level module,
985 specifies the name of the top level Verilog module to become the
986 top, and sets the default for if --prefix is not used. This is not
987 needed with standard designs with only one top.
988 --trace
990 Adds waveform tracing code to the model using VCD format. This
991 overrides "--trace-fst".
992 Verilator will generate additional {prefix}__Trace*.cpp files that
994 will need to be compiled. In addition verilated_vcd_sc.cpp (for
995 SystemC traces) or verilated_vcd_c.cpp (for both) must be compiled
996 and linked in. If using the Verilator generated Makefiles, these
997 files will be added as source targets for you. If you're not using
998 the Verilator makefiles, you will need to add these to your
999 Makefile manually.
1000 Having tracing compiled in may result in some small performance
1002 losses, even when waveforms are not turned on during model
1003 execution.
1004 --trace-fst
1006 Enable FST waveform tracing in the model. This overrides "--trace"
1007 and "--trace-fst-thread". See also "--trace-fst-thread".
1008 --trace-fst-thread
1010 Enable FST waveform tracing in the model, using a separate thread.
1011 This is typically faster in runtime but slower in total computes
1012 than "--trace-fst". This overrides "--trace" and "--trace-fst".
1013 --trace-depth levels
1015 Specify the number of levels deep to enable tracing, for example
1016 --trace-level 1 to only see the top level's signals. Defaults to
1017 the entire model. Using a small number will decrease visibility,
1018 but greatly improve runtime and trace file size.
1019 --trace-max-array depth
1021 Rarely needed. Specify the maximum array depth of a signal that
1022 may be traced. Defaults to 32, as tracing large arrays may greatly
1023 slow traced simulations.
1024 --trace-max-width width
1026 Rarely needed. Specify the maximum bit width of a signal that may
1027 be traced. Defaults to 256, as tracing large vectors may greatly
1028 slow traced simulations.
1029 --no-trace-params
1031 Disable tracing of parameters.
1032 --trace-structs
1034 Enable tracing to show the name of packed structure, union, and
1035 packed array fields, rather than a simgle combined packed bus. Due
1036 to VCD file format constraints this may result in significantly
1037 slower trace times and larger trace files.
1038 --trace-underscore
1040 Enable tracing of signals that start with an underscore. Normally,
1041 these signals are not output during tracing. See also
1042 --coverage-underscore.
1043 -Uvar
1045 Undefines the given preprocessor symbol.
1046 --unroll-count loops
1048 Rarely needed. Specifies the maximum number of loop iterations
1049 that may be unrolled. See also BLKLOOPINIT warning.
1050 --unroll-stmts statements
1052 Rarely needed. Specifies the maximum number of statements in a
1053 loop for that loop to be unrolled. See also BLKLOOPINIT warning.
1054 --unused-regexp regexp
1056 Rarely needed. Specifies a simple regexp with * and ? that if a
1057 signal name matches will suppress the UNUSED warning. Defaults to
1058 "*unused*". Setting it to "" disables matching.
1059 -V Shows the verbose version, including configuration information
1061 compiled into Verilator. (Similar to perl -V.) See also --getenv.
1062 -v filename
1064 Read the filename as a Verilog library. Any modules in the file
1065 may be used to resolve cell instantiations in the top level module,
1066 else ignored. Note -v is fairly standard across Verilog tools.
1067 +verilog1995ext+ext
1069 +verilog2001ext+ext
1070 Synonyms for "+1364-1995ext+"ext and "+1364-2001ext+"ext
1071 respectively
1072 --version
1074 Displays program version and exits.
1075 --vpi
1077 Enable use of VPI and linking against the verilated_vpi.cpp files.
1078 -Wall
1080 Enable all code style warnings, including code style warnings that
1081 are normally disabled by default. Equivelent to "-Wwarn-lint
1082 -Wwarn-style". Excludes some specialty warnings, i.e.
1083 IMPERFECTSCH.
1084 -Werror-message
1086 Convert the specified warning message into an error message. This
1087 is generally to discourage users from violating important site-wide
1088 rules, for example "-Werror-NOUNOPTFLAT".
1089 -Wfuture-message
1091 Rarely needed. Suppress unknown Verilator comments or warning
1092 messages with the given message code. This is used to allow code
1093 written with pragmas for a later version of Verilator to run under
1094 a older version; add -Wfuture- arguments for each message code or
1095 comment that the new version supports which the older version does
1096 not support.
1097 -Wno-message
1099 Disable the specified warning message, or in some cases where noted
1100 here disable an error. This will override any lint_on directives
1101 in the source, i.e. the warning will still not be printed.
1102 -Wno-lint
1104 Disable all lint related warning messages, and all style warnings.
1105 This is equivalent to "-Wno-ALWCOMBORDER -Wno-BSSPACE
1106 -Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASEWITHX
1107 -Wno-CMPCONST -Wno-COLONPLUS -Wno-ENDLABEL -Wno-IMPLICIT
1108 -Wno-LITENDIAN -Wno-PINCONNECTEMPTY -Wno-PINMISSING
1109 -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED
1110 -Wno-WIDTH" plus the list shown for Wno-style.
1111 It is strongly recommended you cleanup your code rather than using
1113 this option, it is only intended to be use when running test-cases
1114 of code received from third parties.
1115 -Wno-style
1117 Disable all code style related warning messages (note by default
1118 they are already disabled). This is equivalent to
1119 "-Wno-DECLFILENAME -Wno-DEFPARAM -Wno-IMPORTSTAR -Wno-INCABSPATH
1120 -Wno-PINCONNECTEMPTY -Wno-PINNOCONNECT -Wno-SYNCASYNCNET
1121 -Wno-UNDRIVEN -Wno-UNUSED -Wno-VARHIDDEN".
1122 -Wno-fatal
1124 When warnings are detected, print them, but do not exit the
1125 simulator.
1126 Having warning messages in builds is sloppy. It is strongly
1128 recommended you cleanup your code, use inline lint_off, or use
1129 -Wno-... flags rather than using this option.
1130 -Wwarn-message
1132 Enables the specified warning message.
1133 -Wwarn-lint
1135 Enable all lint related warning messages (note by default they are
1136 already enabled), but do not affect style messages. This is
1137 equivalent to "-Wwarn-ALWCOMBORDER -Wwarn-BSSPACE
1138 -Wwarn-CASEINCOMPLETE -Wwarn-CASEOVERLAP -Wwarn-CASEX
1139 -Wwarn-CASEWITHX -Wwarn-CMPCONST -Wwarn-COLONPLUS -Wwarn-ENDLABEL
1140 -Wwarn-IMPLICIT -Wwarn-LITENDIAN -Wwarn-PINMISSING -Wwarn-REALCVT
1141 -Wwarn-UNSIGNED -Wwarn-WIDTH".
1142 -Wwarn-style
1144 Enable all code style related warning messages. This is equivalent
1145 to "-Wwarn ASSIGNDLY -Wwarn-DECLFILENAME -Wwarn-DEFPARAM
1146 -Wwarn-INCABSPATH -Wwarn-PINNOCONNECT -Wwarn-SYNCASYNCNET
1147 -Wwarn-UNDRIVEN -Wwarn-UNUSED -Wwarn-VARHIDDEN".
1148 --x-assign 0
1150 --x-assign 1
1151 --x-assign fast (default)
1152 --x-assign unique
1153 Controls the two-state value that is replaced when an assignment to
1154 X is encountered. "--x-assign fast", the default, converts all Xs
1155 to whatever is best for performance. "--x-assign 0" converts all
1156 Xs to 0s, and is also fast. "--x-assign 1" converts all Xs to 1s,
1157 this is nearly as fast as 0, but more likely to find reset bugs as
1158 active high logic will fire. "--x-assign unique" will call a
1159 function to determine the value, this allows randomization of all
1160 Xs to find reset bugs and is the slowest, but safest for finding
1161 reset bugs in code.
1162 If using --x-assign unique, you may want to seed your random number
1164 generator such that each regression run gets a different
1165 randomization sequence. Use the system's srand48() or for Windows
1166 srand() function to do this. You'll probably also want to print
1167 any seeds selected, and code to enable rerunning with that same
1168 seed so you can reproduce bugs.
1169 Note. This option applies only to variables which are explicitly
1171 assigned to X in the Verilog source code. Initial values of clocks
1172 are set to 0 unless --x-initial-edge is specified. Initial values
1173 of all other state holding variables are controlled with
1174 --x-initial.
1175 --x-initial 0
1177 --x-initial fast
1178 --x-initial unique (default)
1179 Controls the two-state value that is used to initialize variables
1180 that are not otherwise initialized.
1181 "--x-initial 0", initializes all otherwise uninitialized variables
1183 to zero.
1184 "--x-initial unique", the default, initializes variables using a
1186 function, which determines the value to use each initialization.
1187 This gives greatest flexibility and allows finding reset bugs. See
1188 "Unknown states".
1189 "--x-initial fast", is best for performance, and initializes all
1191 variables to a state Verilator determines is optimal. This may
1192 allow further code optimizations, but will likely hide any code
1193 bugs relating to missing resets.
1194 Note. This option applies only to initial values of variables.
1196 Initial values of clocks are set to 0 unless --x-initial-edge is
1197 specified.
1198 --x-initial-edge
1200 Enables emulation of event driven simulators which generally
1201 trigger an edge on a transition from X to 1 ("posedge") or X to 0
1202 ("negedge"). Thus the following code, where "rst_n" is
1203 uninitialized would set "res_n" to "1'b1" when "rst_n" is first set
1204 to zero:
1205 reg res_n = 1'b0;
1207 always @(negedge rst_n) begin
1209 if (rst_n == 1'b0) begin
1210 res_n <= 1'b1;
1211 end
1212 end
1213 In Verilator, by default, uninitialized clocks are given a value of
1215 zero, so the above "always" block would not trigger.
1216 While it is not good practice, there are some designs that rely on
1218 X X 0 triggering a "negedge", particularly in reset sequences.
1219 Using --x-initial-edge with Verilator will replicate this behavior.
1220 It will also ensure that X X 1 triggers a "posedge".
1221 Note. Some users have reported that using this option can affect
1223 convergence, and that it may be necessary to use --converge-limit
1224 to increase the number of convergence iterations. This may be
1225 another indication of problems with the modeled design that should
1226 be addressed.
1227 --xml-only
1229 Create XML output only, do not create any other output.
1230 The XML format is intended to be used to leverage Verilator's
1232 parser and elaboration to feed to other downstream tools. Be aware
1233 that the XML format is still evolving; there will be some changes
1234 in future versions.
1235 -y dir
1237 Add the directory to the list of directories that should be
1238 searched for include files or libraries. The three flags -y,
1239 +incdir and -I have similar effect; +incdir and +y are fairly
1240 standard across Verilog tools while -I is an alias for GCC
1241 compatibility.
1242 Verilator defaults to the current directory ("-y .") and any
1244 specified --Mdir, though these default paths are used after any
1245 user specified directories. This allows '-y "$(pwd)"' to be used
1246 if absolute filenames are desired for error messages instead of
1247 relative filenames.
1248
1250 The following are the arguments that may be passed to a Verilated
1251 executable, provided that executable calls Verilated::commandArgs().
1252 All runtime arguments begin with +verilator, so that the user's
1254 executable may skip over all +verilator arguments when parsing its
1255 command line.
1256 +verilator+debug
1258 Enable debugging. Equivalent to +verilator+debugi+4.
1259 +verilator+debugi+value
1261 Enable debugging at the provided level.
1262 +verilator+help
1264 Display help and exit.
1265 +verilator+prof+threads+file+filename
1267 When using --prof-threads, the filename to dump to. Defaults to
1268 "profile_threads.dat".
1269 +verilator+prof+threads+start+value
1271 When using --prof-threads, Verilator will wait until $time is at
1272 this value, then start the profiling warmup, then capturing.
1273 Generally this should be set to some time that is well within the
1274 normal operation of the simulation, i.e. outside of reset. If 0,
1275 the dump is disabled. Defaults to 1.
1276 +verilator+prof+threads+window+value
1278 When using --prof-threads, after $time reaches
1279 +verilator+prof+threads+start, Verilator will warm up the profiling
1280 for this number of eval() calls, then will capture the profiling of
1281 this number of eval() calls. Defaults to 2, which makes sense for
1282 a single-clock-domain module where it's typical to want to capture
1283 one posedge eval() and one negedge eval().
1284 +verilator+rand+reset+value
1286 When a model was Verilated using "-x-initial unique", sets the
1287 initialization technique. 0 = Reset to zeros. 1 = Reset to all-
1288 ones. 2 = Randomize. See "Unknown states".
1289 +verilator+seed+value
1291 For $random and "-x-initial unique", set the random seed value. If
1292 zero or not specified picks a value from the system random number
1293 generator.
1294 +verilator+V
1296 Shows the verbose version, including configuration information.
1297 +verilator+version
1299 Displays program version and exits.
1300
1302 We'll compile this example into C++.
1303 mkdir test_our
1305 cd test_our
1306 cat <<EOF >our.v
1308 module our;
1309 initial begin $display("Hello World"); $finish; end
1310 endmodule
1311 EOF
1312 cat <<EOF >sim_main.cpp
1314 #include "Vour.h"
1315 #include "verilated.h"
1316 int main(int argc, char** argv, char** env) {
1317 Verilated::commandArgs(argc, argv);
1318 Vour* top = new Vour;
1319 while (!Verilated::gotFinish()) { top->eval(); }
1320 delete top;
1321 exit(0);
1322 }
1323 EOF
1324 See the README in the source kit for various ways to install or point
1326 to Verilator binaries. In brief, if you are running Verilator that
1327 came from your operating system (as an RPM), or did a "make install" to
1328 place Verilator into your default path, you do not need anything
1329 special in your environment, and should not have VERILATOR_ROOT set.
1330 However, if you installed Verilator from sources and want to run
1331 Verilator out of where you compiled Verilator, you need to point to the
1332 kit:
1333 # See above; don't do this if using an OS-distributed Verilator
1335 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1336 export PATH=$VERILATOR_ROOT/bin:$PATH
1337 Now we run Verilator on our little example.
1339 verilator -Wall --cc our.v --exe sim_main.cpp
1341 We can see the source code under the "obj_dir" directory. See the
1343 FILES section below for descriptions of some of the files that were
1344 created.
1345 ls -l obj_dir
1347 We then can compile it
1349 make -j -C obj_dir -f Vour.mk Vour
1351 (Verilator included a default compile rule and link rule, since we used
1353 --exe and passed a .cpp file on the Verilator command line. You can
1354 also write your own compile rules, as we'll show in the SYSTEMC
1355 section.)
1356 And now we run it
1358 obj_dir/Vour
1360 And we get as output
1362 Hello World
1364 - our.v:2: Verilog $finish
1365 Really, you're better off writing a Makefile to do all this for you.
1367 Then, when your source changes it will automatically run all of these
1368 steps; to aid this Verilator can create a makefile dependency file.
1369 See the examples directory in the distribution.
1370
1372 This is an example similar to the above, but using SystemC.
1373 mkdir test_our_sc
1375 cd test_our_sc
1376 cat <<EOF >our.v
1378 module our (clk);
1379 input clk; // Clock is required to get initial activation
1380 always @ (posedge clk)
1381 begin $display("Hello World"); $finish; end
1382 endmodule
1383 EOF
1384 cat <<EOF >sc_main.cpp
1386 #include "Vour.h"
1387 int sc_main(int argc, char **argv) {
1388 Verilated::commandArgs(argc, argv);
1389 sc_clock clk ("clk", 10, 0.5, 3, true);
1390 Vour* top;
1391 top = new Vour("top");
1392 top->clk(clk);
1393 while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
1394 delete top;
1395 exit(0);
1396 }
1397 EOF
1398 See the README in the source kit for various ways to install or point
1400 to Verilator binaries. In brief, if you are running Verilator that
1401 came from your operating system (as an RPM), or did a "make install" to
1402 place Verilator into your default path, you do not need anything
1403 special in your environment, and should not have VERILATOR_ROOT set.
1404 However, if you installed Verilator from sources and want to run
1405 Verilator out of where you compiled Verilator, you need to point to the
1406 kit:
1407 # See above; don't do this if using an OS-distributed Verilator
1409 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1410 export PATH=$VERILATOR_ROOT/bin:$PATH
1411 Now we run Verilator on our little example.
1413 verilator -Wall --sc our.v
1415 We then can compile it
1417 cd obj_dir
1419 make -j -f Vour.mk Vour__ALL.a
1420 make -j -f Vour.mk ../sc_main.o verilated.o
1421 And link with SystemC. Note your path to the libraries may vary,
1423 depending on the operating system.
1424 export SYSTEMC_LIBDIR=/path/to/where/libsystemc.a/exists
1426 export LD_LIBRARY_PATH=$SYSTEMC_LIBDIR:$LD_LIBRARY_PATH
1427 # Might be needed if SystemC 2.3.0
1428 export SYSTEMC_CXX_FLAGS=-pthread
1429 g++ -L$SYSTEMC_LIBDIR ../sc_main.o Vour__ALL*.o verilated.o \
1431 -o Vour -lsystemc
1432 And now we run it
1434 cd ..
1436 obj_dir/Vour
1437 And we get the same output as the C++ example:
1439 Hello World
1441 - our.v:2: Verilog $finish
1442 Really, you're better off using a Makefile to do all this for you.
1444 Then, when your source changes it will automatically run all of these
1445 steps. See the examples directory in the distribution.
1446
1448 For best performance, run Verilator with the "-O3 --x-assign=fast
1449 --x-initial fast --noassert" flags. The -O3 flag will require longer
1450 compile times, and "--x-assign fast --x-initial fast" may increase the
1451 risk of reset bugs in trade for performance; see the above
1452 documentation for these flags.
1453 If using Verilated multithreaded, use "numactl" to ensure you are using
1455 non-conflicting hardware resources. See "MULTITHREADING".
1456 Minor Verilog code changes can also give big wins. You should not have
1458 any UNOPTFLAT warnings from Verilator. Fixing these warnings can
1459 result in huge improvements; one user fixed their one UNOPTFLAT warning
1460 by making a simple change to a clock latch used to gate clocks and
1461 gained a 60% performance improvement.
1462 Beyond that, the performance of a Verilated model depends mostly on
1464 your C++ compiler and size of your CPU's caches.
1465 By default, the lib/verilated.mk file has optimization turned off.
1467 This is for the benefit of new users, as it improves compile times at
1468 the cost of runtimes. To add optimization as the default, set one of
1469 three variables, OPT, OPT_FAST, or OPT_SLOW lib/verilated.mk. Or, use
1470 the -CFLAGS and/or -LDFLAGS option on the verilator command line to
1471 pass the flags directly to the compiler or linker. Or, just for one
1472 run, pass them on the command line to make:
1473 make OPT_FAST="-O2 -fno-stack-protector" -f Vour.mk Vour__ALL.a
1475 OPT_FAST specifies optimizations for those programs that are part of
1477 the fast path, mostly code that is executed every cycle. OPT_SLOW
1478 specifies optimizations for slow-path files (plus tracing), which
1479 execute only rarely, yet take a long time to compile with optimization
1480 on. OPT specifies overall optimization and affects all compiles,
1481 including those OPT_FAST and OPT_SLOW control. For best results, use
1482 OPT="-O2", and link with "-static". Nearly the same results can be had
1483 with much better compile times with OPT_FAST="-O1 -fstrict-aliasing".
1484 Higher optimization such as "-O3" may help, but gcc compile times may
1485 be excessive under O3 on even medium sized designs. Alternatively,
1486 some larger designs report better performance using "-Os".
1487 Unfortunately, using the optimizer with SystemC files can result in
1489 compiles taking several minutes. (The SystemC libraries have many
1490 little inlined functions that drive the compiler nuts.)
1491 For best results, use GCC 3.3 or newer. GCC 3.2 and earlier have
1493 optimization bugs around pointer aliasing detection, which can result
1494 in 2x performance losses.
1495 If you will be running many simulations on a single compile,
1497 investigate feedback driven compilation. With GCC, using
1498 -fprofile-arcs, then -fbranch-probabilities will yield another 15% or
1499 so.
1500 Modern compilers also support link-time optimization (LTO), which can
1502 help especially if you link in DPI code. To enable LTO on GCC, pass
1503 "-flto" in both compilation and link. Note LTO may cause excessive
1504 compile times on large designs.
1505 If you are using your own makefiles, you may want to compile the
1507 Verilated code with -DVL_INLINE_OPT=inline. This will inline functions,
1508 however this requires that all cpp files be compiled in a single
1509 compiler run.
1510 You may uncover further tuning possibilities by profiling the Verilog
1512 code. Use Verilator's --prof-cfuncs, then GCC's -g -pg. You can then
1513 run either oprofile or gprof to see where in the C++ code the time is
1514 spent. Run the gprof output through verilator_profcfunc and it will
1515 tell you what Verilog line numbers on which most of the time is being
1516 spent.
1517 When done, please let the author know the results. I like to keep tabs
1519 on how Verilator compares, and may be able to suggest additional
1520 improvements.
1521
1523 All output files are placed in the output directory name specified with
1524 the -Mdir option, or "obj_dir" if not specified.
1525 Verilator creates the following files in the output directory:
1527 {prefix}.mk // Make include file for compiling
1529 {prefix}_classes.mk // Make include file with class names
1530 For -cc and -sc mode, it also creates:
1532 {prefix}.cpp // Top level C++ file
1534 {prefix}.h // Top level header
1535 {prefix}__Slow{__n}.cpp // Constructors and infrequent cold routines
1536 {prefix}{__n}.cpp // Additional top C++ files (--output-split)
1537 {prefix}{each_verilog_module}.cpp // Lower level internal C++ files
1538 {prefix}{each_verilog_module}.h // Lower level internal header files
1539 {prefix}{each_verilog_module}{__n}.cpp // Additional lower C++ files (--output-split)
1540 In certain debug and other modes, it also creates:
1542 {prefix}.xml // XML tree information (--xml)
1544 {prefix}__Dpi.cpp // DPI import and export wrappers
1545 {prefix}__Dpi.h // DPI import and export declarations
1546 {prefix}__Inlines.h // Inline support functions
1547 {prefix}__Syms.cpp // Global symbol table C++
1548 {prefix}__Syms.h // Global symbol table header
1549 {prefix}__Trace__Slow{__n}.cpp // Wave file generation code (--trace)
1550 {prefix}__Trace{__n}.cpp // Wave file generation code (--trace)
1551 {prefix}__cdc.txt // Clock Domain Crossing checks (--cdc)
1552 {prefix}__stats.txt // Statistics (--stats)
1553 It also creates internal files that can be mostly ignored:
1555 {mod_prefix}_{each_verilog_module}{__n}.vpp // Post-processed verilog
1557 {prefix}__ver.d // Make dependencies (-MMD)
1558 {prefix}__verFiles.dat // Timestamps for skip-identical
1559 {prefix}{misc}.dot // Debugging graph files (--debug)
1560 {prefix}{misc}.tree // Debugging files (--debug)
1561 After running Make, the C++ compiler may produce the following:
1563 verilated{misc}.d // Intermediate dependencies
1565 verilated{misc}.o // Intermediate objects
1566 {mod_prefix}{misc}.d // Intermediate dependencies
1567 {mod_prefix}{misc}.o // Intermediate objects
1568 {prefix} // Final executable (w/--exe argument)
1569 {prefix}__ALL.a // Library of all Verilated objects
1570 {prefix}__ALLboth.cpp // Include of classes for single compile
1571 {prefix}__ALLcls.cpp // Include of user classes for single compile
1572 {prefix}__ALLsup.cpp // Include of support files for single compile
1573 {prefix}{misc}.d // Intermediate dependencies
1574 {prefix}{misc}.o // Intermediate objects
1575
1577 LD_LIBRARY_PATH
1578 A generic Linux/OS variable specifying what directories have shared
1579 object (.so) files. This path should include SystemC and any other
1580 shared objects needed at runtime.
1581 OBJCACHE
1583 Optionally specifies a caching or distribution program to place in
1584 front of all runs of the C++ Compiler. For example, "objcache
1585 --read --write", or "ccache". If using distcc or icecc/icecream,
1586 they would generally be run under either objcache or ccache; see
1587 the documentation for those programs.
1588 SYSTEMC
1590 Deprecated. Used only if SYSTEMC_INCLUDE or SYSTEMC_LIBDIR is not
1591 set. If set, specifies the directory containing the SystemC
1592 distribution. If not specified, it will come from a default
1593 optionally specified at configure time (before Verilator was
1594 compiled).
1595 SYSTEMC_ARCH
1597 Deprecated. Used only if SYSTEMC_LIBDIR is not set. Specifies the
1598 architecture name used by the SystemC kit. This is the part after
1599 the dash in the lib-{...} directory name created by a 'make' in the
1600 SystemC distribution. If not set, Verilator will try to intuit the
1601 proper setting, or use the default optionally specified at
1602 configure time (before Verilator was compiled).
1603 SYSTEMC_CXX_FLAGS
1605 Specifies additional flags that are required to be passed to GCC
1606 when building the SystemC model. System 2.3.0 may need this set to
1607 "-pthread".
1608 SYSTEMC_INCLUDE
1610 If set, specifies the directory containing the systemc.h header
1611 file. If not specified, it will come from a default optionally
1612 specified at configure time (before Verilator was compiled), or
1613 computed from SYSTEMC/include.
1614 SYSTEMC_LIBDIR
1616 If set, specifies the directory containing the libsystemc.a
1617 library. If not specified, it will come from a default optionally
1618 specified at configure time (before Verilator was compiled), or
1619 computed from SYSTEMC/lib-SYSTEMC_ARCH.
1620 VCS_HOME
1622 If set, specifies the directory containing the Synopsys VCS
1623 distribution. When set, a 'make test' in the Verilator
1624 distribution will also run VCS baseline regression tests.
1625 VERILATOR_BIN
1627 If set, specifies an alternative name of the Verilator binary. May
1628 be used for debugging and selecting between multiple operating
1629 system builds.
1630 VERILATOR_GDB
1632 If set, the command to run when using the --gdb option, such as
1633 "ddd". If not specified, it will use "gdb".
1634 VERILATOR_ROOT
1636 Specifies the directory containing the distribution kit. This is
1637 used to find the executable, Perl library, and include files. If
1638 not specified, it will come from a default optionally specified at
1639 configure time (before Verilator was compiled). It should not be
1640 specified if using a pre-compiled Verilator RPM as the hardcoded
1641 value should be correct.
1642
1644 Verilator creates a .h and .cpp file for the top level module and all
1645 modules under it. See the examples directory in the kit for examples.
1646 After the modules are completed, there will be a module.mk file that
1648 may be used with Make to produce a module__ALL.a file with all required
1649 objects in it. This is then linked with the user's top level to create
1650 the simulation executable.
1651 The user must write the top level of the simulation. Here's a simple
1653 example:
1654 #include <verilated.h> // Defines common routines
1656 #include <iostream> // Need std::cout
1657 #include "Vtop.h" // From Verilating "top.v"
1658 Vtop *top; // Instantiation of module
1660 vluint64_t main_time = 0; // Current simulation time
1662 // This is a 64-bit integer to reduce wrap over issues and
1663 // allow modulus. You can also use a double, if you wish.
1664 double sc_time_stamp () { // Called by $time in Verilog
1666 return main_time; // converts to double, to match
1667 // what SystemC does
1668 }
1669 int main(int argc, char** argv) {
1671 Verilated::commandArgs(argc, argv); // Remember args
1672 top = new Vtop; // Create instance
1674 top->reset_l = 0; // Set some inputs
1676 while (!Verilated::gotFinish()) {
1678 if (main_time > 10) {
1679 top->reset_l = 1; // Deassert reset
1680 }
1681 if ((main_time % 10) == 1) {
1682 top->clk = 1; // Toggle clock
1683 }
1684 if ((main_time % 10) == 6) {
1685 top->clk = 0;
1686 }
1687 top->eval(); // Evaluate model
1688 cout << top->out << endl; // Read a output
1689 main_time++; // Time passes...
1690 }
1691 top->final(); // Done simulating
1693 // // (Though this example doesn't get here)
1694 delete top;
1695 }
1696 Note signals are read and written as member variables of the lower
1698 module. You call the eval() method to evaluate the model. When the
1699 simulation is complete call the final() method to wrap up any
1700 SystemVerilog final blocks, and complete any assertions.
1701
1703 Verilator will convert the top level module to a SC_MODULE. This
1704 module will plug directly into a SystemC netlist.
1705 The SC_MODULE gets the same pinout as the Verilog module, with the
1707 following type conversions: Pins of a single bit become bool. Pins
1708 2-32 bits wide become uint32_t's. Pins 33-64 bits wide become sc_bv's
1709 or vluint64_t's depending on the --no-pins64 switch. Wider pins become
1710 sc_bv's. (Uints simulate the fastest so are used where possible.)
1711 Lower modules are not pure SystemC code. This is a feature, as using
1713 the SystemC pin interconnect scheme everywhere would reduce performance
1714 by an order of magnitude.
1715
1717 Verilator supports SystemVerilog Direct Programming Interface import
1718 and export statements. Only the SystemVerilog form ("DPI-C") is
1719 supported, not the original Synopsys-only DPI.
1720 DPI Example
1722 In the SYSTEMC example above, if you wanted to import C++ functions
1723 into Verilog, put in our.v:
1724 import "DPI-C" function integer add (input integer a, input integer b);
1726 initial begin
1728 $display("%x + %x = %x", 1, 2, add(1,2));
1729 endtask
1730 Then after Verilating, Verilator will create a file Vour__Dpi.h with
1732 the prototype to call this function:
1733 extern int add (int a, int b);
1735 From the sc_main.cpp file (or another .cpp file passed to the Verilator
1737 command line, or the link), you'd then:
1738 #include "svdpi.h"
1740 #include "Vour__Dpi.h"
1741 int add(int a, int b) { return a+b; }
1742 DPI System Task/Functions
1744 Verilator extends the DPI format to allow using the same scheme to
1745 efficiently add system functions. Simply use a dollar-sign prefixed
1746 system function name for the import, but note it must be escaped.
1747 export "DPI-C" function integer \$myRand;
1749 initial $display("myRand=%d", $myRand());
1751 Going the other direction, you can export Verilog tasks so they can be
1753 called from C++:
1754 export "DPI-C" task publicSetBool;
1756 task publicSetBool;
1758 input bit in_bool;
1759 var_bool = in_bool;
1760 endtask
1761 Then after Verilating, Verilator will create a file Vour__Dpi.h with
1763 the prototype to call this function:
1764 extern bool publicSetBool(bool in_bool);
1766 From the sc_main.cpp file, you'd then:
1768 #include "Vour__Dpi.h"
1770 publicSetBool(value);
1771 Or, alternatively, call the function under the design class. This
1773 isn't DPI compatible but is easier to read and better supports multiple
1774 designs.
1775 #include "Vour__Dpi.h"
1777 Vour::publicSetBool(value);
1778 // or top->publicSetBool(value);
1779 Note that if the DPI task or function accesses any register or net
1781 within the RTL, it will require a scope to be set. This can be done
1782 using the standard functions within svdpi.h, after the module is
1783 instantiated, but before the task(s) and/or function(s) are called.
1784 For example, if the top level module is instantiated with the name
1786 "dut" and the name references within tasks are all hierarchical
1787 (dotted) names with respect to that top level module, then the scope
1788 could be set with
1789 #include "svdpi.h"
1791 ...
1792 svSetScope(svGetScopeFromName("dut"));
1793 (Remember that Verilator adds a "V" to the top of the module
1795 hierarchy.)
1796 Scope can also be set from within a DPI imported C function that has
1798 been called from Verilog by querying the scope of that function. See
1799 the sections on DPI Context Functions and DPI Header Isolation below
1800 and the comments within the svdpi.h header for more information.
1801 DPI Display Functions
1803 Verilator allows writing $display like functions using this syntax:
1804 import "DPI-C" function void
1806 \$my_display(input string formatted /*verilator sformat*/ );
1807 The /*verilator sformat*/ indicates that this function accepts a
1809 $display like format specifier followed by any number of arguments to
1810 satisfy the format.
1811 DPI Context Functions
1813 Verilator supports IEEE DPI Context Functions. Context imports pass
1814 the simulator context, including calling scope name, and filename and
1815 line number to the C code. For example, in Verilog:
1816 import "DPI-C" context function int dpic_line();
1818 initial $display("This is line %d, again, line %d\n", `line, dpic_line());
1819 This will call C++ code which may then use the svGet* functions to read
1821 information, in this case the line number of the Verilog statement that
1822 invoked the dpic_line function:
1823 int dpic_line() {
1825 // Get a scope: svScope scope = svGetScope();
1826 const char* scopenamep = svGetNameFromScope(scope);
1828 assert(scopenamep);
1829 const char* filenamep = "";
1831 int lineno = 0;
1832 if (svGetCallerInfo(&filenamep, &lineno)) {
1833 printf("dpic_line called from scope %s on line %d\n",
1834 scopenamep, lineno);
1835 return lineno;
1836 } else {
1837 return 0;
1838 }
1839 }
1840 See the IEEE Standard for more information.
1842 DPI Header Isolation
1844 Verilator places the IEEE standard header files such as svdpi.h into a
1845 separate include directory, vltstd (VeriLaTor STandarD). When
1846 compiling most applications $VERILATOR_ROOT/include/vltstd would be in
1847 the include path along with the normal $VERILATOR_ROOT/include.
1848 However, when compiling Verilated models into other simulators which
1849 have their own svdpi.h and similar standard files with different
1850 contents, the vltstd directory should not be included to prevent
1851 picking up incompatible definitions.
1852 Public Functions
1854 Instead of DPI exporting, there's also Verilator public functions,
1855 which are slightly faster, but less compatible.
1856
1858 Verilator supports a very limited subset of the VPI. This subset
1859 allows inspection, examination, value change callbacks, and depositing
1860 of values to public signals only.
1861 VPI is enabled with the verilator --vpi switch.
1863 To access signals via the VPI, Verilator must be told exactly which
1865 signals are to be accessed. This is done using the Verilator public
1866 pragmas documented below.
1867 Verilator has an important difference from an event based simulator;
1869 signal values that are changed by the VPI will not immediately
1870 propagate their values, instead the top level header file's eval()
1871 method must be called. Normally this would be part of the normal
1872 evaluation (i.e. the next clock edge), not as part of the value change.
1873 This makes the performance of VPI routines extremely fast compared to
1874 event based simulators, but can confuse some test-benches that expect
1875 immediate propagation.
1876 Note the VPI by its specified implementation will always be much slower
1878 than accessing the Verilator values by direct reference
1879 (structure->module->signame), as the VPI accessors perform lookup in
1880 functions at runtime requiring at best hundreds of instructions, while
1881 the direct references are evaluated by the compiler and result in only
1882 a couple of instructions.
1883 For signal callbacks to work the main loop of the program must call
1885 VerilatedVpi::callValueCbs().
1886 VPI Example
1888 In the below example, we have readme marked read-only, and writeme
1889 which if written from outside the model will have the same semantics as
1890 if it changed on the specified clock edge.
1891 cat <<EOF >our.v
1893 module our (input clk);
1894 reg readme /*verilator public_flat_rd*/;
1895 reg writeme /*verilator public_flat_rw @(posedge clk) */;
1896 initial $finish;
1897 endmodule
1898 EOF
1899 There are many online tutorials and books on the VPI, but an example
1901 that accesses the above signal "readme" would be:
1902 cat <<EOF >sim_main.cpp
1904 #include "Vour.h"
1905 #include "verilated.h"
1906 #include "verilated_vpi.h" // Required to get definitions
1907 vluint64_t main_time = 0; // See comments in first example
1909 double sc_time_stamp() { return main_time; }
1910 void read_and_check() {
1912 vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
1913 if (!vh1) { vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found"); }
1914 const char* name = vpi_get_str(vpiName, vh1);
1915 printf("Module name: %s\n", name); // Prints "readme"
1916 s_vpi_value v;
1918 v.format = vpiIntVal;
1919 vpi_get_value(vh1, &v);
1920 printf("Value of v: %d\n", v.value.integer); // Prints "readme"
1921 }
1922 int main(int argc, char** argv, char** env) {
1924 Verilated::commandArgs(argc, argv);
1925 Vour* top = new Vour;
1926 Verilated::internalsDump(); // See scopes to help debug
1927 while (!Verilated::gotFinish()) {
1928 top->eval();
1929 VerilatedVpi::callValueCbs(); // For signal callbacks
1930 read_and_check();
1931 }
1932 delete top;
1933 exit(0);
1934 }
1935 EOF
1936
1938 Verilator supports cross-compiling Verilated code. This is generally
1939 used to run Verilator on a Linux system and produce C++ code that is
1940 then compiled on Windows.
1941 Cross compilation involves up to three different OSes. The build
1943 system is where you configured and compiled Verilator, the host system
1944 where you run Verilator, and the target system where you compile the
1945 Verilated code and run the simulation.
1946 Currently, Verilator requires the build and host system type to be the
1948 same, though the target system type may be different. To support this,
1949 ./configure and make Verilator on the build system. Then, run
1950 Verilator on the host system. Finally, the output of Verilator may be
1951 compiled on the different target system.
1952 To support this, none of the files that Verilator produces will
1954 reference any configure generated build-system specific files, such as
1955 config.h (which is renamed in Verilator to config_build.h to reduce
1956 confusion.) The disadvantage of this approach is that
1957 include/verilatedos.h must self-detect the requirements of the target
1958 system, rather than using configure.
1959 The target system may also require edits to the Makefiles, the simple
1961 Makefiles produced by Verilator presume the target system is the same
1962 type as the build system.
1963 Cadence NC-SystemC Models
1965 Similar to compiling Verilated designs with gcc, Verilated designs may
1966 be compiled inside other simulators that support C++ or SystemC models.
1967 One such simulator is Cadence's NC-SystemC, part of their Incisive
1968 Verification Suite. (Highly recommended.)
1969 Using the example files above, the following command will build the
1971 model underneath NC:
1972 cd obj_dir
1974 ncsc_run \
1975 sc_main.cpp \
1976 Vour__ALLcls.cpp \
1977 Vour__ALLsup.cpp \
1978 verilated.cpp
1979 For larger designs you'll want to automate this using makefiles, which
1981 pull the names of the .cpp files to compile in from the make variables
1982 generated in obj_dir/Vour_classes.mk.
1983
1985 Verilator experimentally supports multithreading.
1986 With --no-threads, the default, the model is not thread safe, and any
1988 use of more than one thread calling into one or even different
1989 Verilated models may result in unpredictable behavior. This gives the
1990 highest single thread performance.
1991 With --threads 1, the generated model is single threaded, however the
1993 support libraries are multithread safe. This allows different
1994 instantiations of model(s) to potentially each be run under a different
1995 thread. All threading is the responsibility of the user's C++
1996 testbench.
1997 With --threads N, where N is at least 2, the generated model will be
1999 designed to run in parallel on N threads. The thread calling eval()
2000 provides one of those threads, and the generated model will create and
2001 manage the other N-1 threads. It's the client's responsibility not to
2002 oversubscribe the available CPU cores. Under CPU oversubscription, the
2003 Verilated model should not livelock nor deadlock, however, you can
2004 expect performance to be far worse than it would be with proper ratio
2005 of threads and CPU cores.
2006 With --trace-fst-thread, tracing occurs in a separate thread from the
2008 main simulation thread(s). This option is orthogonal to --threads.
2009 The remainder of this section describe behavior with --threads 1 or
2011 --threads N (not --no-threads).
2012 VL_THREADED is defined when compiling a threaded Verilated module,
2014 causing the Verilated support classes become threadsafe.
2015 The thread used for constructing a model must the the same thread that
2017 calls eval() into the model, this is called the "eval thread". The
2018 thread used to perform certain global operations such as saving and
2019 tracing must be done by a "main thread". In most cases the eval thread
2020 and main thread are the same thread (i.e. the user's top C++ testbench
2021 runs on a single thread), but this is not required.
2022 When running a multithreaded model, the default Linux task scheduler
2024 often works against the model, by assuming threads are short lived, and
2025 thus often schedules threads using multiple hyperthreads within the
2026 same physical core. For best performance use the "numactl" program to
2027 (when the threading count fits) select unique physical cores on the
2028 same socket. For example, if a model was Verilated with "--threads 4",
2029 we consult
2030 egrep 'processor|physical id|core id' /proc/cpuinfo
2032 To select cores 0, 1, 2, and 3 that are all located on the same socket
2034 (0) but different physical cores. (Also useful is "numactl
2035 --hardware", or "lscpu" but those doesn't show Hyperthreading cores.)
2036 Then we execute
2037 numactl -m 0 -C 0,1,2,3 -- verilated_executable_name
2039 This will limit memory to socket 0, and threads to cores 0, 1, 2, 3,
2041 (presumably on socket 0) optimizing performance. Of course this must
2042 be adjusted if you want another simulator using e.g. socket 1, or if
2043 you Verilated with a different number of threads. To see what CPUs are
2044 actually used, use --prof-threads.
2045 Multithreaded Verilog and Library Support
2047 $display/$stop/$finish are delayed until the end of an eval() call in
2048 order to maintain ordering between threads. This may result in
2049 additional tasks completing after the $stop or $finish.
2050 If using --coverage, the coverage routines are fully thread safe.
2052 If using --dpi, Verilator assumes pure DPI imports are thread safe,
2054 balancing performance versus safety. See --threads-dpi.
2055 If using --savable, the save/restore classes are not multithreaded
2057 and are must be called only by the eval thread.
2058 If using --sc, the SystemC kernel is not thread safe, therefore the
2060 eval thread and main thread must be the same.
2061 If using --trace, the tracing classes must be constructed and
2063 called from the main thread.
2064 If using --vpi, since SystemVerilog VPI was not architected by IEEE
2066 to be multithreaded, Verilator requires all VPI calls are only made
2067 from the main thread.
2068
2070 In addition to the command line, warnings and other features may be
2071 controlled by configuration files, typically named with the .vlt
2072 extension. An example:
2073 `verilator_config
2075 lint_off -msg WIDTH
2076 lint_off -msg CASEX -file "silly_vendor_code.v"
2077 This disables WIDTH warnings globally, and CASEX for a specific file.
2079 Configuration files are parsed after the normal Verilog preprocessing,
2081 so `ifdefs, `defines, and comments may be used as if it were normal
2082 Verilog code.
2083 The grammar of configuration commands is as follows:
2085 `verilator_config
2087 Take remaining text up the the next `verilog mode switch and treat
2088 it as Verilator configuration commands.
2089 coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2091 coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2092 Enable/disable coverage for the specified filename (or wildcard
2093 with '*' or '?', or all files if omitted) and range of line numbers
2094 (or all lines if omitted). Often used to ignore an entire module
2095 for coverage analysis purposes.
2096 lint_on [-msg <message>] [-file "<filename>" [-lines <line> [ -
2098 <line>]]]
2099 lint_off [-msg <message>] [-file "<filename>" [-lines <line> [ -
2100 <line>]]]
2101 Enable/disables the specified lint warning, in the specified
2102 filename (or wildcard with '*' or '?', or all files if omitted) and
2103 range of line numbers (or all lines if omitted).
2104 With lint_off using '*' will override any lint_on directives in the
2106 source, i.e. the warning will still not be printed.
2107 If the -msg is omitted, all lint warnings (see list in -Wno-lint)
2109 are enabled/disabled. This will override all later lint warning
2110 enables for the specified region.
2111 tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2113 tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2114 Enable/disable waveform tracing for all future signals declared in
2115 the specified filename (or wildcard with '*' or '?', or all files
2116 if omitted) and range of line numbers (or all lines if omitted).
2117 For tracing_off, cells below any module in the files/ranges
2119 specified will also not be traced.
2120
2122 Verilog 2001 (IEEE 1364-2001) Support
2123 Verilator supports most Verilog 2001 language features. This includes
2124 signed numbers, "always @*", generate statements, multidimensional
2125 arrays, localparam, and C-style declarations inside port lists.
2126 Verilog 2005 (IEEE 1364-2005) Support
2128 Verilator supports most Verilog 2005 language features. This includes
2129 the `begin_keywords and `end_keywords compiler directives, $clog2, and
2130 the uwire keyword.
2131 SystemVerilog 2005 (IEEE 1800-2005) Support
2133 Verilator supports ==? and !=? operators, ++ and -- in some contexts,
2134 $bits, $countones, $error, $fatal, $info, $isunknown, $onehot,
2135 $onehot0, $unit, $warning, always_comb, always_ff, always_latch, bit,
2136 byte, chandle, const, do-while, enum, export, final, import, int,
2137 interface, logic, longint, modport, package, program, shortint, struct,
2138 time, typedef, union, var, void, priority case/if, and unique case/if.
2139 It also supports .name and .* interconnection.
2141 Verilator partially supports concurrent assert and cover statements;
2143 see the enclosed coverage tests for the syntax which is allowed.
2144 SystemVerilog 2012 (IEEE 1800-2012) Support
2146 Verilator implements a full SystemVerilog 2012 preprocessor, including
2147 function call-like preprocessor defines, default define arguments,
2148 `__FILE__, `__LINE__ and `undefineall.
2149 Verilator currently has some support for SystemVerilog synthesis
2151 constructs. As SystemVerilog features enter common usage they are
2152 added; please file a bug if a feature you need is missing.
2153 SystemVerilog 2017 (IEEE 1800-2017) Support
2155 Verilator supports the 2017 "for" loop constructs, and several minor
2156 cleanups made in 1800-2017.
2157 Verilog AMS Support
2159 Verilator implements a very small subset of Verilog AMS (Verilog Analog
2160 and Mixed-Signal Extensions) with the subset corresponding to those VMS
2161 keywords with near equivalents in the Verilog 2005 or SystemVerilog
2162 2009 languages.
2163 AMS parsing is enabled with "--language VAMS" or "--language
2165 1800+VAMS".
2166 At present Verilator implements ceil, exp, floor, ln, log, pow, sqrt,
2168 string, and wreal.
2169 Synthesis Directive Assertion Support
2171 With the --assert switch, Verilator reads any "//synopsys full_case" or
2172 "//synopsys parallel_case" directives. The same applies to any
2173 "//ambit synthesis", "//cadence" or "//pragma" directives of the same
2174 form.
2175 When these synthesis directives are discovered, Verilator will either
2177 formally prove the directive to be true, or failing that, will insert
2178 the appropriate code to detect failing cases at runtime and print an
2179 "Assertion failed" error message.
2180 Verilator likewise also asserts any "unique" or "priority"
2182 SystemVerilog keywords on case statement, as well as "unique" on if
2183 statements. However, "priority if" is currently simply ignored.
2184
2186 The following additional constructs are the extensions Verilator
2187 supports on top of standard Verilog code. Using these features outside
2188 of comments or `ifdef's may break other tools.
2189 `__FILE__
2191 The __FILE__ define expands to the current filename as a string,
2192 like C++'s __FILE__. This was incorporated into to the 1800-2009
2193 standard (but supported by Verilator since 2006!)
2194 `__LINE__
2196 The __LINE__ define expands to the current filename as a string,
2197 like C++'s __LINE__. This was incorporated into to the 1800-2009
2198 standard (but supported by Verilator since 2006!)
2199 `error string
2201 This will report an error when encountered, like C++'s #error.
2202 $c(string, ...);
2204 The string will be embedded directly in the output C++ code at the
2205 point where the surrounding Verilog code is compiled. It may
2206 either be a standalone statement (with a trailing ; in the string),
2207 or a function that returns up to a 32-bit number (without a
2208 trailing ;). This can be used to call C++ functions from your
2209 Verilog code.
2210 String arguments will be put directly into the output C++ code.
2212 Expression arguments will have the code to evaluate the expression
2213 inserted. Thus to call a C++ function, $c("func(",a,")") will
2214 result in 'func(a)' in the output C++ code. For input arguments,
2215 rather than hard-coding variable names in the string $c("func(a)"),
2216 instead pass the variable as an expression $c("func(",a,")"). This
2217 will allow the call to work inside Verilog functions where the
2218 variable is flattened out, and also enable other optimizations.
2219 If you will be reading or writing any Verilog variables inside the
2221 C++ functions, the Verilog signals must be declared with
2222 /*verilator public*/.
2223 You may also append an arbitrary number to $c, generally the width
2225 of the output. [signal_32_bits = $c32("...");] This allows for
2226 compatibility with other simulators which require a differently
2227 named PLI function name for each different output width.
2228 $display, $write, $fdisplay, $fwrite, $sformat, $swrite
2230 Format arguments may use C fprintf sizes after the % escape. Per
2231 the Verilog standard, %x prints a number with the natural width,
2232 and %0x prints a number with minimum width. Verilator extends this
2233 so %5x prints 5 digits per the C standard (it's unspecified in
2234 Verilog).
2235 `coverage_block_off
2237 Specifies the entire begin/end block should be ignored for coverage
2238 analysis. Must be inside a basic block, e.g. within a begin/end
2239 pair. Same as /* verilator coverage_block_off */.
2240 `systemc_header
2242 Take remaining text up to the next `verilog or `systemc_... mode
2243 switch and place it verbatim into the output .h file's header.
2244 Must be placed as a module item, e.g. directly inside a
2245 module/endmodule pair. Despite the name of this macro, this also
2246 works in pure C++ code.
2247 `systemc_ctor
2249 Take remaining text up to the next `verilog or `systemc_... mode
2250 switch and place it verbatim into the C++ class constructor. Must
2251 be placed as a module item, e.g. directly inside a module/endmodule
2252 pair. Despite the name of this macro, this also works in pure C++
2253 code.
2254 `systemc_dtor
2256 Take remaining text up to the next `verilog or `systemc_... mode
2257 switch and place it verbatim into the C++ class destructor. Must
2258 be placed as a module item, e.g. directly inside a module/endmodule
2259 pair. Despite the name of this macro, this also works in pure C++
2260 code.
2261 `systemc_interface
2263 Take remaining text up to the next `verilog or `systemc_... mode
2264 switch and place it verbatim into the C++ class interface. Must be
2265 placed as a module item, e.g. directly inside a module/endmodule
2266 pair. Despite the name of this macro, this also works in pure C++
2267 code.
2268 `systemc_imp_header
2270 Take remaining text up to the next `verilog or `systemc_... mode
2271 switch and place it verbatim into the header of all files for this
2272 C++ class implementation. Must be placed as a module item, e.g.
2273 directly inside a module/endmodule pair. Despite the name of this
2274 macro, this also works in pure C++ code.
2275 `systemc_implementation
2277 Take remaining text up to the next `verilog or `systemc_... mode
2278 switch and place it verbatim into a single file of the C++ class
2279 implementation. Must be placed as a module item, e.g. directly
2280 inside a module/endmodule pair. Despite the name of this macro,
2281 this also works in pure C++ code.
2282 If you will be reading or writing any Verilog variables in the C++
2284 functions, the Verilog signals must be declared with /*verilator
2285 public*/. See also the public task feature; writing an accessor
2286 may result in cleaner code.
2287 `SYSTEMVERILOG
2289 The SYSTEMVERILOG, SV_COV_START and related standard defines are
2290 set by default when --language is 1800-*.
2291 `VERILATOR
2293 `verilator
2294 `verilator3
2295 The VERILATOR, verilator and verilator3 defines are set by default
2296 so you may `ifdef around compiler specific constructs.
2297 `verilator_config
2299 Take remaining text up the the next `verilog mode switch and treat
2300 it as Verilator configuration commands.
2301 `verilog
2303 Switch back to processing Verilog code after a `systemc_... mode
2304 switch. The Verilog code returns to the last language mode
2305 specified with `begin_keywords, or SystemVerilog if none was
2306 specified.
2307 /*verilator clock_enable*/
2309 Used after a signal declaration to indicate the signal is used to
2310 gate a clock, and the user takes responsibility for insuring there
2311 are no races related to it. (Typically by adding a latch, and
2312 running static timing analysis.) For example:
2313 reg enable_r /*verilator clock_enable*/;
2315 wire gated_clk = clk & enable_r;
2316 always_ff @ (posedge clk)
2317 enable_r <= enable_early;
2318 The clock_enable attribute will cause the clock gate to be ignored
2320 in the scheduling algorithm, sometimes required for correct clock
2321 behavior, and always improving performance. It's also a good idea
2322 to enable the IMPERFECTSCH warning, to insure all clock enables are
2323 properly recognized.
2324 /*verilator clocker*/
2326 /*verilator no_clocker*/
2327 Used after a signal declaration to indicate the signal is used as
2328 clock or not. This information is used by Verilator to mark the
2329 signal as clocker and propagate the clocker attribute automatically
2330 to derived signals. See "--clk" for more information.
2331 /*verilator coverage_block_off*/
2333 Specifies the entire begin/end block should be ignored for coverage
2334 analysis purposes.
2335 /*verilator coverage_off*/
2337 Specifies that following lines of code should have coverage
2338 disabled. Often used to ignore an entire module for coverage
2339 analysis purposes.
2340 /*verilator coverage_on*/
2342 Specifies that following lines of code should have coverage re-
2343 enabled (if appropriate --coverage flags are passed) after being
2344 disabled earlier with /*verilator coverage_off*/.
2345 /*verilator inline_module*/
2347 Specifies the module the comment appears in may be inlined into any
2348 modules that use this module. This is useful to speed up
2349 simulation time with some small loss of trace visibility and
2350 modularity. Note signals under inlined submodules will be named
2351 submodule__DOT__subsignal as C++ does not allow "." in signal
2352 names. When tracing such signals the tracing routines will replace
2353 the __DOT__ with the period.
2354 /*verilator isolate_assignments*/
2356 Used after a signal declaration to indicate the assignments to this
2357 signal in any blocks should be isolated into new blocks. When
2358 there is a large combinatorial block that is resulting in a
2359 UNOPTFLAT warning, attaching this to the signal causing a false
2360 loop may clear up the problem.
2361 IE, with the following
2363 reg splitme /* verilator isolate_assignments*/;
2365 // Note the placement of the semicolon above
2366 always @* begin
2367 if (....) begin
2368 splitme = ....;
2369 other assignments
2370 end
2371 end
2372 Verilator will internally split the block that assigns to "splitme"
2374 into two blocks:
2375 It would then internally break it into (sort of):
2377 // All assignments excluding those to splitme
2379 always @* begin
2380 if (....) begin
2381 other assignments
2382 end
2383 end
2384 // All assignments to splitme
2385 always @* begin
2386 if (....) begin
2387 splitme = ....;
2388 end
2389 end
2390 /*verilator lint_off msg*/
2392 Disable the specified warning message for any warnings following
2393 the comment.
2394 /*verilator lint_on msg*/
2396 Re-enable the specified warning message for any warnings following
2397 the comment.
2398 /*verilator lint_restore*/
2400 After a /*verilator lint_save*/, pop the stack containing lint
2401 message state. Often this is useful at the bottom of include
2402 files.
2403 /*verilator lint_save*/
2405 Push the current state of what lint messages are turned on or
2406 turned off to a stack. Later meta-comments may then lint_on or
2407 lint_off specific messages, then return to the earlier message
2408 state by using /*verilator lint_restore*/. For example:
2409 // verilator lint_save
2411 // verilator lint_off SOME_WARNING
2412 ... // code needing SOME_WARNING turned off
2413 // verilator lint_restore
2414 If SOME_WARNING was on before the lint_off, it will now be restored
2416 to on, and if it was off before the lint_off it will remain off.
2417 /*verilator no_inline_module*/
2419 Specifies the module the comment appears in should not be inlined
2420 into any modules that use this module. This is useful especially
2421 at the top level module to reduce the size of the interface class,
2422 to aid compile time at a small performance loss.
2423 /*verilator no_inline_task*/
2425 Used in a function or task variable definition section to specify
2426 the function or task should not be inlined into where it is used.
2427 This may reduce the size of the final executable when a task is
2428 used a very large number of times. For this flag to work, the task
2429 and tasks below it must be pure; they cannot reference any
2430 variables outside the task itself.
2431 /*verilator public*/ (parameter)
2433 Used after a parameter declaration to indicate the emitted C code
2434 should have the parameter values visible. Due to C++ language
2435 restrictions, this may only be used on 64-bit or narrower integral
2436 enumerations.
2437 parameter [2:0] PARAM /*verilator public*/ = 2'b0;
2439 /*verilator public*/ (typedef enum)
2441 Used after an enum typedef declaration to indicate the emitted C
2442 code should have the enum values visible. Due to C++ language
2443 restrictions, this may only be used on 64-bit or narrower integral
2444 enumerations.
2445 typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
2447 /*verilator public*/ (variable)
2449 Used after an input, output, register, or wire declaration to
2450 indicate the signal should be declared so that C code may read or
2451 write the value of the signal. This will also declare this module
2452 public, otherwise use /*verilator public_flat*/.
2453 Instead of using public variables, consider instead making a DPI or
2455 public function that accesses the variable. This is nicer as it
2456 provides an obvious entry point that is also compatible across
2457 simulators.
2458 /*verilator public*/ (task/function)
2460 Used inside the declaration section of a function or task
2461 declaration to indicate the function or task should be made into a
2462 C++ function, public to outside callers. Public tasks will be
2463 declared as a void C++ function, public functions will get the
2464 appropriate non-void (bool, uint32_t, etc) return type. Any input
2465 arguments will become C++ arguments to the function. Any output
2466 arguments will become C++ reference arguments. Any local
2467 registers/integers will become function automatic variables on the
2468 stack.
2469 Wide variables over 64 bits cannot be function returns, to avoid
2471 exposing complexities. However, wide variables can be
2472 input/outputs; they will be passed as references to an array of
2473 32-bit numbers.
2474 Generally, only the values of stored state (flops) should be
2476 written, as the model will NOT notice changes made to variables in
2477 these functions. (Same as when a signal is declared public.)
2478 You may want to use DPI exports instead, as it's compatible with
2480 other simulators.
2481 /*verilator public_flat*/ (variable)
2483 Used after an input, output, register, or wire declaration to
2484 indicate the signal should be declared so that C code may read or
2485 write the value of the signal. This will not declare this module
2486 public, which means the name of the signal or path to it may change
2487 based upon the module inlining which takes place.
2488 /*verilator public_flat_rd*/ (variable)
2490 Used after an input, output, register, or wire declaration to
2491 indicate the signal should be declared public_flat (see above), but
2492 read-only.
2493 /*verilator public_flat_rw @(<edge_list>) */ (variable)
2495 Used after an input, output, register, or wire declaration to
2496 indicate the signal should be declared public_flat_rd (see above),
2497 and also writable, where writes should be considered to have the
2498 timing specified by the given sensitivity edge list.
2499 /*verilator public_module*/
2501 Used after a module statement to indicate the module should not be
2502 inlined (unless specifically requested) so that C code may access
2503 the module. Verilator automatically sets this attribute when the
2504 module contains any public signals or `systemc_ directives. Also
2505 set for all modules when using the --public switch.
2506 /*verilator sc_clock*/
2508 Rarely needed. Used after an input declaration to indicate the
2509 signal should be declared in SystemC as a sc_clock instead of a
2510 bool. This was needed in SystemC 1.1 and 1.2 only; versions 2.0
2511 and later do not require clock pins to be sc_clocks and this is no
2512 longer needed.
2513 /*verilator sc_bv*/
2515 Used after a port declaration. It sets the port to be of
2516 sc_bv<width> type, instead of bool, vluint32_t or vluint64_t. This
2517 may be useful if the port width is parameterized and different of
2518 such modules interface a templated module (such as a transactor) or
2519 for other reasons. In general you should avoid using this
2520 attribute when not necessary as with increasing usage of sc_bv the
2521 performance increases significantly.
2522 /*verilator sformat*/
2524 Attached to the final input of a function or task "input string" to
2525 indicate the function or task should pass all remaining arguments
2526 through $sformatf. This allows creation of DPI functions with
2527 $display like behavior. See the test_regress/t/t_dpi_display.v
2528 file for an example.
2529 /*verilator tag <text...>*/
2531 Attached after a variable or structure member to indicate opaque
2532 (to Verilator) text that should be passed through to the XML output
2533 as a tag, for use by downstream applications.
2534 /*verilator tracing_off*/
2536 Disable waveform tracing for all future signals that are declared
2537 in this module, or cells below this module. Often this is placed
2538 just after a primitive's module statement, so that the entire
2539 module and cells below it are not traced.
2540 /*verilator tracing_on*/
2542 Re-enable waveform tracing for all future signals or cells that are
2543 declared.
2544
2546 There are some limitations and lack of features relative to a
2547 commercial simulator, by intent. User beware.
2548 It is strongly recommended you use a lint tool before running this
2550 program. Verilator isn't designed to easily uncover common mistakes
2551 that a lint program will find for you.
2552 Synthesis Subset
2554 Verilator supports only the Synthesis subset with a few minor additions
2555 such as $stop, $finish and $display. That is, you cannot use
2556 hierarchical references, events or similar features of the Verilog
2557 language. It also simulates as Synopsys's Design Compiler would;
2558 namely a block of the form:
2559 always @ (x) y = x & z;
2561 This will recompute y when there is even a potential for change in x or
2563 a change in z, that is when the flops computing x or z evaluate (which
2564 is what Design Compiler will synthesize.) A compliant simulator would
2565 only calculate y if x changes. Use Verilog-Mode's /*AS*/ or Verilog
2566 2001's always @* to reduce missing activity items. Avoid putting
2567 $displays in combo blocks, as they may print multiple times when not
2568 desired, even on compliant simulators as event ordering is not
2569 specified.
2570 Signal Naming
2572 To avoid conflicts with C symbol naming, any character in a signal name
2573 that is not alphanumeric nor a single underscore will be replaced by
2574 __0hh where hh is the hex code of the character. To avoid conflicts
2575 with Verilator's internal symbols, any double underscore are replaced
2576 with ___05F (5F is the hex code of an underscore.)
2577 Bind
2579 Verilator only supports "bind" to a target module name, not an instance
2580 path.
2581 Dotted cross-hierarchy references
2583 Verilator supports dotted references to variables, functions and tasks
2584 in different modules. However, references into named blocks and
2585 function-local variables are not supported. The portion before the dot
2586 must have a constant value; for example a[2].b is acceptable, while
2587 a[x].b is not.
2588 References into generated and arrayed instances use the instance names
2590 specified in the Verilog standard; arrayed instances are named
2591 {cellName}[{instanceNumber}] in Verilog, which becomes
2592 {cellname}__BRA__{instanceNumber}__KET__ inside the generated C++ code.
2593 Verilator creates numbered "genblk" when a begin: name is not specified
2595 around a block inside a generate statement. These numbers may differ
2596 between other simulators, but the Verilog specification does not allow
2597 users to use these names, so it should not matter.
2598 If you are having trouble determining where a dotted path goes wrong,
2600 note that Verilator will print a list of known scopes to help your
2601 debugging.
2602 Floating Point
2604 Floating Point (real) numbers are supported.
2605 Latches
2607 Verilator is optimized for edge sensitive (flop based) designs. It
2608 will attempt to do the correct thing for latches, but most performance
2609 optimizations will be disabled around the latch.
2610 Structures and Unions
2612 Verilator only presently supports packed structs and packed unions.
2613 Rand and randc tags on members are simply ignored. All structures and
2614 unions are represented as a single vector, which means that generating
2615 one member of a structure from blocking, and another from non-blocking
2616 assignments is unsupported.
2617 Time
2619 All delays (#) are ignored, as they are in synthesis.
2620 Unknown states
2622 Verilator is mostly a two state simulator, not a four state simulator.
2623 However, it has two features which uncover most initialization bugs
2624 (including many that a four state simulator will miss.)
2625 Identity comparisons (=== or !==) are converted to standard ==/!== when
2627 neither side is a constant. This may make the expression result differ
2628 from a four state simulator. An === comparison to X will always be
2629 false, so that Verilog code which checks for uninitialized logic will
2630 not fire.
2631 Assigning a variable to a X will actually assign the variable to a
2633 random value (see the --x-assign switch and +verilator+rand+reset
2634 runtime switch.) Thus if the value is actually used, the random value
2635 should cause downstream errors. Integers also randomize, even though
2636 the Verilog 2001 specification says they initialize to zero.
2637 All variables, depending on --x-initial setting, are typically randomly
2639 initialized using a function. By running several random simulation
2640 runs you can determine that reset is working correctly. On the first
2641 run, the function initializes variables to zero. On the second, have
2642 it initialize variables to one. On the third and following runs have
2643 it initialize them randomly. If the results match, reset works. (Note
2644 this is what the hardware will really do.) In practice, just setting
2645 all variables to one at startup finds most problems (since typically
2646 control signals are active-high).
2647 --x-assign applies to variables explicitly initialized or assigned to
2649 X. Uninitialized clocks are initialized to zero, while all other state
2650 holding variables are initialized to a random value. Event driven
2651 simulators will generally trigger an edge on a transition from X to 1
2652 ("posedge") or X to 0 ("negedge"). However, by default, since clocks
2653 are initialized to zero, Verilator will not trigger an initial negedge.
2654 Some code (particularly for reset) may rely on X->0 triggering an edge.
2655 The --x-initial-edge switch enables this behavior. Comparing runs with
2656 and without this switch will find such problems.
2657 Tri/Inout
2659 Verilator converts some simple tristate structures into two state.
2660 Pullup, pulldown, bufif0, bufif1, notif0, notif1, pmos, nmos, tri0 and
2661 tri1 are also supported. Simple comparisons with === 1'bz are also
2662 supported.
2663 An assignment of the form:
2665 inout driver;
2667 wire driver = (enable) ? output_value : 1'bz;
2668 Will be converted to
2670 input driver; // Value being driven in from "external" drivers
2672 output driver__en; // True if driven from this module
2673 output driver__out; // Value being driven from this module
2674 External logic will be needed to combine these signals with any
2676 external drivers.
2677 Tristate drivers are not supported inside functions and tasks; an inout
2679 there will be considered a two state variable that is read and written
2680 instead of a four state variable.
2681 Functions & Tasks
2683 All functions and tasks will be inlined (will not become functions in
2684 C.) The only support provided is for simple statements in tasks (which
2685 may affect global variables).
2686 Recursive functions and tasks are not supported. All inputs and
2688 outputs are automatic, as if they had the Verilog 2001 "automatic"
2689 keyword prepended. (If you don't know what this means, Verilator will
2690 do what you probably expect -- what C does. The default behavior of
2691 Verilog is different.)
2692 Generated Clocks
2694 Verilator attempts to deal with generated and enabled clocks correctly,
2695 however some cases cause problems in the scheduling algorithm which is
2696 optimized for performance. The safest option is to have all clocks as
2697 primary inputs to the model, or wires directly attached to primary
2698 inputs. For proper behavior clock enables may also need the
2699 /*verilator clock_enable*/ attribute.
2700 Ranges must be big-bit-endian
2702 Bit ranges must be numbered with the MSB being numbered greater or the
2703 same as the LSB. Little-bit-endian buses [0:15] are not supported as
2704 they aren't easily made compatible with C++.
2705 Gate Primitives
2707 The 2-state gate primitives (and, buf, nand, nor, not, or, xnor, xor)
2708 are directly converted to behavioral equivalents. The 3-state and MOS
2709 gate primitives are not supported. Tables are not supported.
2710 Specify blocks
2712 All specify blocks and timing checks are ignored.
2713 Array Initialization
2715 When initializing a large array, you need to use non-delayed
2716 assignments. Verilator will tell you when this needs to be fixed; see
2717 the BLKLOOPINIT error for more information.
2718 Array Out of Bounds
2720 Writing a memory element that is outside the bounds specified for the
2721 array may cause a different memory element inside the array to be
2722 written instead. For power-of-2 sized arrays, Verilator will give a
2723 width warning and the address. For non-power-of-2-sizes arrays, index
2724 0 will be written.
2725 Reading a memory element that is outside the bounds specified for the
2727 array will give a width warning and wrap around the power-of-2 size.
2728 For non-power-of-2 sizes, it will return a unspecified constant of the
2729 appropriate width.
2730 Assertions
2732 Verilator is beginning to add support for assertions. Verilator
2733 currently only converts assertions to simple "if (...) error"
2734 statements, and coverage statements to increment the line counters
2735 described in the coverage section.
2736 Verilator does not support SEREs yet. All assertion and coverage
2738 statements must be simple expressions that complete in one cycle.
2739 (Arguably SEREs are much of the point, but one must start somewhere.)
2740 Language Keyword Limitations
2742 This section describes specific limitations for each language keyword.
2743 `__FILE__, `__LINE__, `begin_keywords, `begin_keywords,
2745 `begin_keywords, `begin_keywords, `begin_keywords, `define, `else,
2746 `elsif, `end_keywords, `endif, `error, `ifdef, `ifndef, `include,
2747 `line, `systemc_ctor, `systemc_dtor, `systemc_header,
2748 `systemc_imp_header, `systemc_implementation, `systemc_interface,
2749 `timescale, `undef, `verilog
2750 Fully supported.
2751 always, always_comb, always_ff, always_latch, and, assign, begin, buf,
2753 byte, case, casex, casez, default, defparam, do-while, else, end,
2754 endcase, endfunction, endgenerate, endmodule, endspecify, endtask,
2755 final, for, function, generate, genvar, if, initial, inout, input, int,
2756 integer, localparam, logic, longint, macromodule, module, nand,
2757 negedge, nor, not, or, output, parameter, posedge, reg, scalared,
2758 shortint, signed, supply0, supply1, task, time, tri, typedef, var,
2759 vectored, while, wire, xnor, xor
2760 Generally supported.
2761 ++, -- operators
2763 Increment/decrement can only be used as standalone statements or in
2764 for loops. They cannot be used as side effect operators inside
2765 more complicate expressions ("a = b++;").
2766 '{} operator
2768 Assignment patterns with order based, default, constant integer
2769 (array) or member identifier (struct/union) keys are supported.
2770 Data type keys and keys which are computed from a constant
2771 expression are not supported.
2772 cast operator
2774 Casting is supported only between simple scalar types, signed and
2775 unsigned, not arrays nor structs.
2776 chandle
2778 Treated as a "longint"; does not yet warn about operations that are
2779 specified as illegal on chandles.
2780 disable
2782 Disable statements may be used only if the block being disabled is
2783 a block the disable statement itself is inside. This was commonly
2784 used to provide loop break and continue functionality before
2785 SystemVerilog added the break and continue keywords.
2786 inside
2788 Inside expressions may not include unpacked array traversal or $ as
2789 an upper bound. Case inside and case matches are also unsupported.
2790 interface
2792 Interfaces and modports, including with generated data types are
2793 supported. Generate blocks around modports are not supported, nor
2794 are virtual interfaces nor unnamed interfaces.
2795 priority if, unique if
2797 Priority and unique if's are treated as normal ifs and not asserted
2798 to be full nor unique.
2799 specify specparam
2801 All specify blocks and timing checks are ignored.
2802 string
2804 String is supported only to the point that they can be assigned,
2805 concatenated, compared, and passed to DPI imports. Standard method
2806 calls on strings are not supported.
2807 timeunit, timeprecision
2809 All timing control statements are ignored.
2810 uwire
2812 Verilator does not perform warning checking on uwires, it treats
2813 the uwire keyword as if it were the normal wire keyword.
2814 $bits, $countones, $error, $fatal, $finish, $info, $isunknown, $onehot,
2816 $onehot0, $readmemb, $readmemh, $signed, $stime, $stop, $time,
2817 $unsigned, $warning.
2818 Generally supported.
2819 $display, $write, $fdisplay, $fwrite, $swrite
2821 $display and friends must have a constant format string as the
2822 first argument (as with C's printf). The rare usage which lists
2823 variables standalone without a format is not supported.
2824 $displayb, $displayh, $displayo, $writeb, $writeh, $writeo, etc
2826 The sized display functions are rarely used and so not supported.
2827 Replace them with a $write with the appropriate format specifier.
2828 $finish, $stop
2830 The rarely used optional parameter to $finish and $stop is ignored.
2831 $fopen, $fclose, $fdisplay, $feof, $fflush, $fgetc, $fgets, $fscanf,
2833 $fwrite
2834 File descriptors passed to the file PLI calls must be file
2835 descriptors, not MCDs, which includes the mode parameter to $fopen
2836 being mandatory.
2837 $fscanf, $sscanf
2839 Only integer formats are supported; %e, %f, %m, %r, %v, and %z are
2840 not supported.
2841 $fullskew, $hold, $nochange, $period, $recovery, $recrem, $removal,
2843 $setup, $setuphold, $skew, $timeskew, $width
2844 All specify blocks and timing checks are ignored.
2845 $random
2847 $random does not support the optional argument to set the seed.
2848 Use the srand function in C to accomplish this, and note there is
2849 only one random number generator (not one per module).
2850 $readmemb, $readmemh
2852 Read memory commands should work properly. Note Verilator and the
2853 Verilog specification does not include support for readmem to
2854 multi-dimensional arrays.
2855 $test$plusargs, $value$plusargs
2857 Supported, but the instantiating C++/SystemC testbench must call
2858 Verilated::commandArgs(argc, argv);
2860 to register the command line before calling $test$plusargs or
2862 $value$plusargs.
2863 $timeformat
2865 Not supported as Verilator needs to determine all formatting at
2866 compile time. Generally you can just ifdef them out for no ill
2867 effect. Note also VL_TIME_MULTIPLIER can be defined at compile
2868 time to move the decimal point when displaying all times, model
2869 wide.
2870
2872 Warnings may be disabled in three ways. First, when the warning is
2873 printed it will include a warning code. Simply surround the offending
2874 line with a warn_off/warn_on pair:
2875 // verilator lint_off UNSIGNED
2877 if (`DEF_THAT_IS_EQ_ZERO <= 3) $stop;
2878 // verilator lint_on UNSIGNED
2879 Second, warnings may be disabled using a configuration file with a
2881 lint_off command. This is useful when a script is suppressing warnings
2882 and the Verilog source should not be changed.
2883 Warnings may also be globally disabled by invoking Verilator with the
2885 "-Wno-warning" switch. This should be avoided, as it removes all
2886 checking across the designs, and prevents other users from compiling
2887 your code without knowing the magic set of disables needed to
2888 successfully compile your design.
2889 List of all warnings:
2891 ALWCOMBORDER
2893 Warns that an always_comb block has a variable which is set after
2894 it is used. This may cause simulation-synthesis mismatches, as not
2895 all commercial simulators allow this ordering.
2896 always_comb begin
2898 a = b;
2899 b = 1;
2900 end
2901 Ignoring this warning will only suppress the lint check, it will
2903 simulate correctly.
2904 ASSIGNIN
2906 Error that an assignment is being made to an input signal. This is
2907 almost certainly a mistake, though technically legal.
2908 input a;
2910 assign a = 1'b1;
2911 Ignoring this warning will only suppress the lint check, it will
2913 simulate correctly.
2914 ASSIGNDLY
2916 Warns that you have an assignment statement with a delayed time in
2917 front of it, for example:
2918 a <= #100 b;
2920 assign #100 a = b;
2921 Ignoring this warning may make Verilator simulations differ from
2923 other simulators, however at one point this was a common style so
2924 disabled by default as a code style warning.
2925 BLKANDNBLK
2927 BLKANDNBLK is an error that a variable comes from a mix of blocked
2928 and non-blocking assignments. Generally, this is caused by a
2929 register driven by both combo logic and a flop:
2930 always @ (posedge clk) foo[0] <= ...
2932 always @* foo[1] = ...
2933 Simply use a different register for the flop:
2935 always @ (posedge clk) foo_flopped[0] <= ...
2937 always @* foo[0] = foo_flopped[0];
2938 always @* foo[1] = ...
2939 This is not illegal in SystemVerilog, but a violation of good
2941 coding practice. Verilator reports this as an error, because
2942 ignoring this warning may make Verilator simulations differ from
2943 other simulators.
2944 It is generally safe to disable this error (with a "// verilator
2946 lint_off BLKANDNBLK" metacomment or the -Wno-BLKANDNBLK option)
2947 when one of the assignments is inside a public task, or when the
2948 blocked and non-blocking assignments have non-overlapping bits and
2949 structure members.
2950 BLKSEQ
2952 This indicates that a blocking assignment (=) is used in a
2953 sequential block. Generally non-blocking/delayed assignments (<=)
2954 are used in sequential blocks, to avoid the possibility of
2955 simulator races. It can be reasonable to do this if the generated
2956 signal is used ONLY later in the same block, however this style is
2957 generally discouraged as it is error prone.
2958 always @ (posedge clk) foo = ...
2960 Disabled by default as this is a code style warning; it will
2962 simulate correctly.
2963 BLKLOOPINIT
2965 This indicates that the initialization of an array needs to use
2966 non-delayed assignments. This is done in the interest of speed; if
2967 delayed assignments were used, the simulator would have to copy
2968 large arrays every cycle. (In smaller loops, loop unrolling allows
2969 the delayed assignment to work, though it's a bit slower than a
2970 non-delayed assignment.) Here's an example
2971 always @ (posedge clk)
2973 if (~reset_l) begin
2974 for (i=0; i<`ARRAY_SIZE; i++) begin
2975 array[i] = 0; // Non-delayed for verilator
2976 end
2977 This message is only seen on large or complicated loops because
2979 Verilator generally unrolls small loops. You may want to try
2980 increasing --unroll-count (and occasionally --unroll-stmts) which
2981 will raise the small loop bar to avoid this error.
2982 BSSPACE
2984 Warns that a backslash is followed by a space then a newline.
2985 Likely the intent was to have a backslash directly followed by a
2986 newline (e.g. when making a `define) and there's accidentally
2987 whitespace at the end of the line. If the space is not accidental,
2988 suggest removing the backslash in the code as it serves no
2989 function.
2990 Ignoring this warning will only suppress the lint check, it will
2992 simulate correctly.
2993 CASEINCOMPLETE
2995 Warns that inside a case statement there is a stimulus pattern for
2996 which there is no case item specified. This is bad style, if a
2997 case is impossible, it's better to have a "default: $stop;" or just
2998 "default: ;" so that any design assumption violations will be
2999 discovered in simulation.
3000 Ignoring this warning will only suppress the lint check, it will
3002 simulate correctly.
3003 CASEOVERLAP
3005 Warns that inside a case statement you have case values which are
3006 detected to be overlapping. This is bad style, as moving the order
3007 of case values will cause different behavior. Generally the values
3008 can be respecified to not overlap.
3009 Ignoring this warning will only suppress the lint check, it will
3011 simulate correctly.
3012 CASEX
3014 Warns that it is simply better style to use casez, and "?" in place
3015 of "x"'s. See
3016 <http://www.sunburst-design.com/papers/CummingsSNUG1999Boston_FullParallelCase_rev1_1.pdf>
3017 Ignoring this warning will only suppress the lint check, it will
3019 simulate correctly.
3020 CASEWITHX
3022 Warns that a case statement contains a constant with a "x".
3023 Verilator is two-state so interpret such items as always false.
3024 Note a common error is to use a "X" in a case or casez statement
3025 item; often what the user instead intended is to use a casez with
3026 "?".
3027 Ignoring this warning will only suppress the lint check, it will
3029 simulate correctly.
3030 CDCRSTLOGIC
3032 With --cdc only, warns that asynchronous flop reset terms come from
3033 other than primary inputs or flopped outputs, creating the
3034 potential for reset glitches.
3035 CLKDATA
3037 Warns that clock signal is mixed used with/as data signal. The
3038 checking for this warning is enabled only if user has explicitly
3039 marked some signal as clocker using command line option or in-
3040 source meta comment (see "--clk").
3041 The warning can be disabled without affecting the simulation
3043 result. But it is recommended to check the warning as this may
3044 degrade the performance of the Verilated model.
3045 CMPCONST
3047 Warns that you are comparing a value in a way that will always be
3048 constant. For example "X > 1" will always be true when X is a
3049 single bit wide.
3050 Ignoring this warning will only suppress the lint check, it will
3052 simulate correctly.
3053 COLONPLUS
3055 Warns that a :+ is seen. Likely the intent was to use +: to select
3056 a range of bits. If the intent was a range that is explicitly
3057 positive, suggest adding a space, e.g. use ": +".
3058 Ignoring this warning will only suppress the lint check, it will
3060 simulate correctly.
3061 COMBDLY
3063 Warns that you have a delayed assignment inside of a combinatorial
3064 block. Using delayed assignments in this way is considered bad
3065 form, and may lead to the simulator not matching synthesis. If
3066 this message is suppressed, Verilator, like synthesis, will convert
3067 this to a non-delayed assignment, which may result in logic races
3068 or other nasties. See
3069 <http://www.sunburst-design.com/papers/CummingsSNUG2000SJ_NBA_rev1_2.pdf>
3070 Ignoring this warning may make Verilator simulations differ from
3072 other simulators.
3073 CONTASSREG
3075 Error that a continuous assignment is setting a reg. According to
3076 IEEE Verilog, but not SystemVerilog, a wire must be used as the
3077 target of continuous assignments.
3078 This error is only reported when "--language 1364-1995",
3080 "--language 1364-2001", or "--language 1364-2005" is used.
3081 Ignoring this error will only suppress the lint check, it will
3083 simulate correctly.
3084 DECLFILENAME
3086 Warns that a module or other declaration's name doesn't match the
3087 filename with path and extension stripped that it is declared in.
3088 The filename a modules/interfaces/programs is declared in should
3089 match the name of the module etc. so that -y directory searching
3090 will work. This warning is printed for only the first mismatching
3091 module in any given file, and -v library files are ignored.
3092 Disabled by default as this is a code style warning; it will
3094 simulate correctly.
3095 DEFPARAM
3097 Warns that the "defparam" statement was deprecated in Verilog 2001
3098 and all designs should now be using the #(...) format to specify
3099 parameters.
3100 Disabled by default as this is a code style warning; it will
3102 simulate correctly.
3103 DETECTARRAY
3105 Error when Verilator tries to deal with a combinatorial loop that
3106 could not be flattened, and which involves a datatype which
3107 Verilator cannot handle, such as an unpacked struct or a large
3108 unpacked array. This typically ocurrs when -Wno-UNOPTFLAT has been
3109 used to override an UNOPTFLAT warning (see below).
3110 The solution is to break the loop, as described for UNOPTFLAT.
3112 ENDLABEL
3114 Warns that a label attached to a "end"-something statement does not
3115 match the label attached to the block start.
3116 Ignoring this warning will only suppress the lint check, it will
3118 simulate correctly.
3119 GENCLK
3121 Warns that the specified signal is generated, but is also being
3122 used as a clock. Verilator needs to evaluate sequential logic
3123 multiple times in this situation. In somewhat contrived cases
3124 having any generated clock can reduce performance by almost a
3125 factor of two. For fastest results, generate ALL clocks outside in
3126 C++/SystemC and make them primary inputs to your Verilog model.
3127 (However once need to you have even one, don't sweat additional
3128 ones.)
3129 Ignoring this warning may make Verilator simulations differ from
3131 other simulators.
3132 IFDEPTH
3134 Warns that if/if else statements have exceeded the depth specified
3135 with --if-depth, as they are likely to result in slow priority
3136 encoders. Unique and priority if statements are ignored.
3137 Solutions include changing the code to a case statement, or a
3138 SystemVerilog 'unique if' or 'priority if'.
3139 Disabled by default as this is a code style warning; it will
3141 simulate correctly.
3142 IGNOREDRETURN
3144 Warns that a non-void function is being called as a task, and hence
3145 the return value is being ignored.
3146 This warning is required by IEEE. The portable way to suppress this
3148 warning (in SystemVerilog) is to use a void cast, e.g.
3149 void'(function_being_called_as_task());
3151 Ignoring this warning will only suppress the lint check, it will
3153 simulate correctly.
3154 IMPERFECTSCH
3156 Warns that the scheduling of the model is not absolutely perfect,
3157 and some manual code edits may result in faster performance. This
3158 warning defaults to off, is not part of -Wall, and must be turned
3159 on explicitly before the top module statement is processed.
3160 IMPLICIT
3162 Warns that a wire is being implicitly declared (it is a single bit
3163 wide output from a sub-module.) While legal in Verilog, implicit
3164 declarations only work for single bit wide signals (not buses), do
3165 not allow using a signal before it is implicitly declared by a
3166 cell, and can lead to dangling nets. A better option is the
3167 /*AUTOWIRE*/ feature of Verilog-Mode for Emacs, available from
3168 <http://www.veripool.org/>
3169 Ignoring this warning will only suppress the lint check, it will
3171 simulate correctly.
3172 IMPORTSTAR
3174 Warns that an "import package::*" statement is in $unit scope. This
3175 causes the imported symbols to polute the global namespace,
3176 defeating much of the purpose of having a package. Generally
3177 "import ::*" should only be used inside a lower scope such as a
3178 package or module.
3179 Disabled by default as this is a code style warning; it will
3181 simulate correctly.
3182 IMPURE
3184 Warns that a task or function that has been marked with /*verilator
3185 no_inline_task*/ references variables that are not local to the
3186 task. Verilator cannot schedule these variables correctly.
3187 Ignoring this warning may make Verilator simulations differ from
3189 other simulators.
3190 INCABSPATH
3192 Warns that an `include filename specifies an absolute path. This
3193 means the code will not work on any other system with a different
3194 file system layout. Instead of using absolute paths, relative
3195 paths (preferably without any directory specified whatever) should
3196 be used, and +incdir used on the command line to specify the top
3197 include source directories.
3198 Disabled by default as this is a code style warning; it will
3200 simulate correctly.
3201 INFINITELOOP
3203 Warns that a while or for statement has a condition that is always
3204 true. and thus result in an infinite loop if the statement ever
3205 executes.
3206 This might be unintended behavior if the loop body contains
3208 statements that in other statements that would make time pass,
3209 which Verilator is ignoring due to e.g. STMTDLY warnings being
3210 disabled.
3211 Ignoring this warning will only suppress the lint check, it will
3213 simulate correctly (i.e. hang due to the infinite loop).
3214 INITIALDLY
3216 Warns that you have a delayed assignment inside of an initial or
3217 final block. If this message is suppressed, Verilator will convert
3218 this to a non-delayed assignment. See also the COMBDLY warning.
3219 Ignoring this warning may make Verilator simulations differ from
3221 other simulators.
3222 LITENDIAN
3224 Warns that a packed vector is declared with little endian bit
3225 numbering (i.e. [0:7]). Big endian bit numbering is now the
3226 overwhelming standard, and little numbering is now thus often due
3227 to simple oversight instead of intent.
3228 Also warns that a cell is declared with little endian range (i.e.
3230 [0:7] or [7]) and is connected to a N-wide signal. Based on IEEE
3231 the bits will likely be backwards from what you expect (i.e. cell
3232 [0] will connect to signal bit [N-1] not bit [0]).
3233 Ignoring this warning will only suppress the lint check, it will
3235 simulate correctly.
3236 MODDUP
3238 Warns that a module has multiple definitions. Generally this
3239 indicates a coding error, or a mistake in a library file and it's
3240 good practice to have one module per file (and only put each file
3241 once on the command line) to avoid these issues. For some gate
3242 level netlists duplicates are sometimes unavoidable, and MODDUP
3243 should be disabled.
3244 Ignoring this warning will cause the more recent module definition
3246 to be discarded.
3247 MULTIDRIVEN
3249 Warns that the specified signal comes from multiple always blocks.
3250 This is often unsupported by synthesis tools, and is considered bad
3251 style. It will also cause longer runtimes due to reduced
3252 optimizations.
3253 Ignoring this warning will only slow simulations, it will simulate
3255 correctly.
3256 MULTITOP
3258 Error that there are multiple top level modules, that is modules
3259 not instantiated by any other module. Verilator only supports a
3260 single top level, if you need more, create a module that wraps all
3261 of the top modules.
3262 Often this error is because some low level cell is being read in,
3264 but is not really needed. The best solution is to insure that each
3265 module is in a unique file by the same name. Otherwise, make sure
3266 all library files are read in as libraries with -v, instead of
3267 automatically with -y.
3268 PINCONNECTEMPTY
3270 Warns that a cell instantiation has a pin which is connected to
3271 .pin_name(), e.g. not another signal, but with an explicit mention
3272 of the pin. It may be desirable to disable PINCONNECTEMPTY, as
3273 this indicates intention to have a no-connect.
3274 Disabled by default as this is a code style warning; it will
3276 simulate correctly.
3277 PINMISSING
3279 Warns that a module has a pin which is not mentioned in a cell
3280 instantiation. If a pin is not missing it should still be
3281 specified on the cell declaration with a empty connection, using
3282 "(.pin_name())".
3283 Ignoring this warning will only suppress the lint check, it will
3285 simulate correctly.
3286 PINNOCONNECT
3288 Warns that a cell instantiation has a pin which is not connected to
3289 another signal.
3290 Disabled by default as this is a code style warning; it will
3292 simulate correctly.
3293 PROCASSWIRE
3295 Error that a procedural assignment is setting a wire. According to
3296 IEEE, a var/reg must be used as the target of procedural
3297 assignments.
3298 REALCVT
3300 Warns that a real number is being implicitly rounded to an integer,
3301 with possible loss of precision.
3302 REDEFMACRO
3304 Warns that you have redefined the same macro with a different
3305 value, for example:
3306 `define MACRO def1
3308 //...
3309 `define MACRO otherdef
3310 The best solution is to use a different name for the second macro.
3312 If this is not possible, add a undef to indicate the code is
3313 overriding the value:
3314 `define MACRO def1
3316 //...
3317 `undef MACRO
3318 `define MACRO otherdef
3319 SELRANGE
3321 Warns that a selection index will go out of bounds:
3322 wire vec[6:0];
3324 initial out = vec[7]; // There is no 7
3325 Verilator will assume zero for this value, instead of X. Note that
3327 in some cases this warning may be false, when a condition upstream
3328 or downstream of the access means the access out of bounds will
3329 never execute or be used.
3330 wire vec[6:0];
3332 initial begin
3333 seven = 7;
3334 ...
3335 if (seven != 7) out = vec[seven]; // Never will use vec[7]
3336 STMTDLY
3338 Warns that you have a statement with a delayed time in front of it,
3339 for example:
3340 #100 $finish;
3342 Ignoring this warning may make Verilator simulations differ from
3344 other simulators.
3345 SYMRSVDWORD
3347 Warning that a symbol matches a C++ reserved word and using this as
3348 a symbol name would result in odd C compiler errors. You may
3349 disable this warning, but the symbol will be renamed by Verilator
3350 to avoid the conflict.
3351 SYNCASYNCNET
3353 Warns that the specified net is used in at least two different
3354 always statements with posedge/negedges (i.e. a flop). One usage
3355 has the signal in the sensitivity list and body, probably as an
3356 async reset, and the other usage has the signal only in the body,
3357 probably as a sync reset. Mixing sync and async resets is usually
3358 a mistake. The warning may be disabled with a lint_off pragma
3359 around the net, or either flopped block.
3360 Disabled by default as this is a code style warning; it will
3362 simulate correctly.
3363 TASKNSVAR
3365 Error when a call to a task or function has a output from that task
3366 tied to a non-simple signal. Instead connect the task output to a
3367 temporary signal of the appropriate width, and use that signal to
3368 set the appropriate expression as the next statement. For example:
3369 task foo; output sig; ... endtask
3371 always @* begin
3372 foo(bus_we_select_from[2]); // Will get TASKNSVAR error
3373 end
3374 Change this to:
3376 reg foo_temp_out;
3378 always @* begin
3379 foo(foo_temp_out);
3380 bus_we_select_from[2] = foo_temp_out;
3381 end
3382 Verilator doesn't do this conversion for you, as some more
3384 complicated cases would result in simulator mismatches.
3385 TICKCOUNT
3387 Warns that the number of ticks to delay a $past variable is greater
3388 than 10. At present Verilator effectively creates a flop for each
3389 delayed signals, and as such any large counts may lead to large
3390 design size increases.
3391 Ignoring this warning will only slow simulations, it will simulate
3393 correctly.
3394 UNDRIVEN
3396 Warns that the specified signal is never sourced. Verilator is
3397 fairly liberal in the usage calculations; making a signal public,
3398 or loading only a single array element marks the entire signal as
3399 driven.
3400 Disabled by default as this is a code style warning; it will
3402 simulate correctly.
3403 UNOPT
3405 Warns that due to some construct, optimization of the specified
3406 signal or block is disabled. The construct should be cleaned up to
3407 improve runtime.
3408 A less obvious case of this is when a module instantiates two
3410 submodules. Inside submodule A, signal I is input and signal O is
3411 output. Likewise in submodule B, signal O is an input and I is an
3412 output. A loop exists and a UNOPT warning will result if AI & AO
3413 both come from and go to combinatorial blocks in both submodules,
3414 even if they are unrelated always blocks. This affects performance
3415 because Verilator would have to evaluate each submodule multiple
3416 times to stabilize the signals crossing between the modules.
3417 Ignoring this warning will only slow simulations, it will simulate
3419 correctly.
3420 UNOPTFLAT
3422 Warns that due to some construct, optimization of the specified
3423 signal is disabled. The signal specified includes a complete scope
3424 to the signal; it may be only one particular usage of a multiply
3425 instantiated block. The construct should be cleaned up to improve
3426 runtime; two times better performance may be possible by fixing
3427 these warnings.
3428 Unlike the UNOPT warning, this occurs after netlist flattening, and
3430 indicates a more basic problem, as the less obvious case described
3431 under UNOPT does not apply.
3432 Often UNOPTFLAT is caused by logic that isn't truly circular as
3434 viewed by synthesis which analyzes interconnection per-bit, but is
3435 circular to simulation which analyzes per-bus:
3436 wire [2:0] x = {x[1:0], shift_in};
3438 This statement needs to be evaluated multiple times, as a change in
3440 "shift_in" requires "x" to be computed 3 times before it becomes
3441 stable. This is because a change in "x" requires "x" itself to
3442 change value, which causes the warning.
3443 For significantly better performance, split this into 2 separate
3445 signals:
3446 wire [2:0] xout = {x[1:0], shift_in};
3448 and change all receiving logic to instead receive "xout".
3450 Alternatively, change it to
3451 wire [2:0] x = {xin[1:0], shift_in};
3453 and change all driving logic to instead drive "xin".
3455 With this change this assignment needs to be evaluated only once.
3457 These sort of changes may also speed up your traditional event
3458 driven simulator, as it will result in fewer events per cycle.
3459 The most complicated UNOPTFLAT path we've seen was due to low bits
3461 of a bus being generated from an always statement that consumed
3462 high bits of the same bus processed by another series of always
3463 blocks. The fix is the same; split it into two separate signals
3464 generated from each block.
3465 The UNOPTFLAT warning may also be due to clock enables, identified
3467 from the reported path going through a clock gating cell. To fix
3468 these, use the clock_enable meta comment described above.
3469 The UNOPTFLAT warning may also occur where outputs from a block of
3471 logic are independent, but occur in the same always block. To fix
3472 this, use the isolate_assignments meta comment described above.
3473 To assist in resolving UNOPTFLAT, the option "--report-unoptflat"
3475 can be used, which will provide suggestions for variables that can
3476 be split up, and a graph of all the nodes connected in the loop.
3477 See the Arguments section for more details.
3478 Ignoring this warning will only slow simulations, it will simulate
3480 correctly.
3481 UNOPTTHREADS
3483 Warns that the thread scheduler was unable to partition the design
3484 to fill the requested number of threads.
3485 One workaround is to request fewer threads with "--threads".
3487 Another possible workaround is to allow more MTasks in the runtime,
3489 by increasing the value of --threads-max-mtasks. More MTasks will
3490 result in more communication and synchronization overhead at
3491 runtime; the scheduler attempts to minimize the number of MTasks
3492 for this reason.
3493 Ignoring this warning will only slow simulations, it will simulate
3495 correctly.
3496 UNPACKED
3498 Warns that unpacked structs and unions are not supported.
3499 Ignoring this warning will make Verilator treat the structure as
3501 packed, which may make Verilator simulations differ from other
3502 simulators.
3503 UNSIGNED
3505 Warns that you are comparing a unsigned value in a way that implies
3506 it is signed, for example "X < 0" will always be true when X is
3507 unsigned.
3508 Ignoring this warning will only suppress the lint check, it will
3510 simulate correctly.
3511 UNUSED
3513 Warns that the specified signal is never sinked. Verilator is
3514 fairly liberal in the usage calculations; making a signal public, a
3515 signal matching --unused-regexp ("*unused*") or accessing only a
3516 single array element marks the entire signal as used.
3517 Disabled by default as this is a code style warning; it will
3519 simulate correctly.
3520 A recommended style for unused nets is to put at the bottom of a
3522 file code similar to the following:
3523 wire _unused_ok = &{1'b0,
3525 sig_not_used_a,
3526 sig_not_used_yet_b, // To be fixed
3527 1'b0};
3528 The reduction AND and constant zeros mean the net will always be
3530 zero, so won't use simulation time. The redundant leading and
3531 trailing zeros avoid syntax errors if there are no signals between
3532 them. The magic name "unused" (-unused-regexp) is recognized by
3533 Verilator and suppresses warnings; if using other lint tools,
3534 either teach to tool to ignore signals with "unused" in the name,
3535 or put the appropriate lint_off around the wire. Having unused
3536 signals in one place makes it easy to find what is unused, and
3537 reduces the number of lint_off pragmas, reducing bugs.
3538 USERINFO, USERWARN, USERERROR, USERFATAL
3540 A SystemVerilog elaboration-time assertion print was executed.
3541 VARHIDDEN
3543 Warns that a task, function, or begin/end block is declaring a
3544 variable by the same name as a variable in the upper level module
3545 or begin/end block (thus hiding the upper variable from being able
3546 to be used.) Rename the variable to avoid confusion when reading
3547 the code.
3548 Disabled by default as this is a code style warning; it will
3550 simulate correctly.
3551 WIDTH
3553 Warns that based on width rules of Verilog, two operands have
3554 different widths. Verilator generally can intuit the common usages
3555 of widths, and you shouldn't need to disable this message like you
3556 do with most lint programs. Generally other than simple mistakes,
3557 you have two solutions:
3558 If it's a constant 0 that's 32 bits or less, simply leave it
3560 unwidthed. Verilator considers zero to be any width needed.
3561 Concatenate leading zeros when doing arithmetic. In the statement
3563 wire [5:0] plus_one = from[5:0] + 6'd1 + carry[0];
3565 The best fix, which clarifies intent and will also make all tools
3567 happy is:
3568 wire [5:0] plus_one = from[5:0] + 6'd1 + {5'd0, carry[0]};
3570 Ignoring this warning will only suppress the lint check, it will
3572 simulate correctly.
3573 WIDTHCONCAT
3575 Warns that based on width rules of Verilog, a concatenate or
3576 replication has an indeterminate width. In most cases this
3577 violates the Verilog rule that widths inside concatenates and
3578 replicates must be sized, and should be fixed in the code.
3579 wire [63:0] concat = {1, 2};
3581 An example where this is technically legal (though still bad form)
3583 is:
3584 parameter PAR = 1;
3586 wire [63:0] concat = {PAR, PAR};
3587 The correct fix is to either size the 1 ("32'h1"), or add the width
3589 to the parameter definition ("parameter [31:0]"), or add the width
3590 to the parameter usage ("{PAR[31:0],PAR[31:0]}".
3591 The following describes the less obvious errors:
3593 Internal Error
3595 This error should never occur first, though may occur if earlier
3596 warnings or error messages have corrupted the program. If there
3597 are no other warnings or errors, submit a bug report.
3598 Unsupported: ....
3600 This error indicates that you are using a Verilog language
3601 construct that is not yet supported in Verilator. See the
3602 Limitations chapter.
3603 Verilated model didn't converge
3605 Verilator sometimes has to evaluate combinatorial logic multiple
3606 times, usually around code where a UNOPTFLAT warning was issued,
3607 but disabled. For example:
3608 always @ (a) b=~a;
3610 always @ (b) a=b
3611 will toggle forever and thus the executable will give the didn't
3613 converge error to prevent an infinite loop.
3614 To debug this, first is to review any UNOPTFLAT warnings that were
3616 ignored, though typically these can be ignored (at a performance
3617 cost), convergence issues can also be flagged with this warning as
3618 Verilator didn't know if they would eventually converge.
3619 Next, run Verilator with --prof-cfuncs. Run make on the generated
3621 files with "OPT=-DVL_DEBUG". Then call Verilated::debug(1) in your
3622 main.cpp.
3623 This will cause each change in a variable to print a message. Near
3625 the bottom you'll see the variables that causes the problem. For
3626 the program above:
3627 CHANGE: filename.v:1: b
3629 CHANGE: filename.v:2: a
3630 If many signals are getting printed then most likely each are
3632 oscillating (or there is a bug). It may also be that e.g. "a" may
3633 be oscillating, then "a" feeds signal "c" which then is also
3634 reported as oscillating.
3635 Finally, rare more difficult cases can be debugged like a "C"
3637 program; either enter GDB and use its tracing facilities, or edit
3638 the generated C++ code to add appropriate prints to see what is
3639 going on.
3640
3642 Does it run under Windows?
3643 Yes, using Cygwin. Verilated output also compiles under Microsoft
3644 Visual C++ Version 7 or newer, but this is not tested every
3645 release.
3646 Can you provide binaries?
3648 Verilator is available as a RPM for Debian/Ubuntu, SuSE, Fedora,
3649 and perhaps other systems; this is done by porters and may slightly
3650 lag the primary distribution. If there isn't a binary build for
3651 your distribution, how about you set one up? Please contact the
3652 authors for assistance.
3653 Note people sometimes request binaries when they are having
3655 problems with their C++ compiler. Alas, binaries won't help this,
3656 as in the end a fully working C++ compiler is required to compile
3657 the output of Verilator.
3658 How can it be faster than (name-the-commercial-simulator)?
3660 Generally, the implied part is of the question is "... with all of
3661 the manpower they can put into developing it."
3662 Most commercial simulators have to be Verilog compliant, meaning
3664 event driven. This prevents them from being able to reorder blocks
3665 and make netlist-style optimizations, which are where most of the
3666 gains come from.
3667 Non-compliance shouldn't be scary. Your synthesis program isn't
3669 compliant, so your simulator shouldn't have to be -- and Verilator
3670 is closer to the synthesis interpretation, so this is a good thing
3671 for getting working silicon.
3672 Will Verilator output remain under my own license?
3674 Yes, it's just like using GCC on your programs; this is why
3675 Verilator uses the "GNU *Lesser* Public License Version 3" instead
3676 of the more typical "GNU Public License". See the licenses for
3677 details, but in brief, if you change Verilator itself or the header
3678 files Verilator includes, you must make the source code available
3679 under the GNU Lesser Public License. However, Verilator output
3680 (the Verilated code) only "include"s the licensed files, and so you
3681 are NOT required to release any output from Verilator.
3682 You also have the option of using the Perl Artistic License, which
3684 again does not require you release your Verilog or generated code,
3685 and also allows you to modify Verilator for internal use without
3686 distributing the modified version. But please contribute back to
3687 the community!
3688 One limit is that you cannot under either license release a
3690 commercial Verilog simulation product incorporating Verilator
3691 without making the source code available.
3692 As is standard with Open Source, contributions back to Verilator
3694 will be placed under the Verilator copyright and LGPL/Artistic
3695 license. Small test cases will be released into the public domain
3696 so they can be used anywhere, and large tests under the
3697 LGPL/Artistic, unless requested otherwise.
3698 Why is Verilation so slow?
3700 Verilator needs more memory than the resulting simulator will
3701 require, as Verilator creates internally all of the state of the
3702 resulting generated simulator in order to optimize it. If it takes
3703 more than a minute or so (and you're not using --debug since debug
3704 is disk bound), see if your machine is paging; most likely you need
3705 to run it on a machine with more memory. Verilator is a full
3706 64-bit application and may use more than 4GB, but about 1GB is the
3707 maximum typically needed, and very large commercial designs have
3708 topped 16GB.
3709 How do I generate waveforms (traces) in C++?
3711 See the next question for tracing in SystemC mode.
3712 Add the --trace switch to Verilator, and in your top level C code,
3714 call Verilated::traceEverOn(true). Then create a VerilatedVcdC
3715 object, and in your main loop call "trace_object->dump(time)" every
3716 time step, and finally call "trace_object->close()". For an
3717 example, see below and the examples/tracing_c/sim_main.cpp file of
3718 the distribution.
3719 You also need to compile verilated_vcd_c.cpp and add it to your
3721 link, preferably by adding the dependencies in $(VK_GLOBAL_OBJS) to
3722 your Makefile's link rule. This is done for you if using the
3723 Verilator --exe flag.
3724 Note you can also call ->trace on multiple Verilated objects with
3726 the same trace file if you want all data to land in the same output
3727 file.
3728 #include "verilated_vcd_c.h"
3730 ...
3731 int main(int argc, char** argv, char** env) {
3732 ...
3733 Verilated::traceEverOn(true);
3734 VerilatedVcdC* tfp = new VerilatedVcdC;
3735 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
3736 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
3737 ...
3738 while (sc_time_stamp() < sim_time && !Verilated::gotFinish()) {
3739 main_time += #;
3740 tfp->dump(main_time);
3741 }
3742 tfp->close();
3743 }
3744 How do I generate waveforms (traces) in SystemC?
3746 Add the --trace switch to Verilator, and in your top level C
3747 sc_main code, include verilated_vcd_sc.h. Then call
3748 Verilated::traceEverOn(true). Then create a VerilatedVcdSc object
3749 as you would create a normal SystemC trace file. For an example,
3750 see the call to VerilatedVcdSc in the
3751 examples/tracing_sc/sc_main.cpp file of the distribution, and
3752 below.
3753 Alternatively you may use the C++ trace mechanism described in the
3755 previous question, however the timescale and timeprecision will not
3756 inherited from your SystemC settings.
3757 You also need to compile verilated_vcd_sc.cpp and
3759 verilated_vcd_c.cpp and add them to your link, preferably by adding
3760 the dependencies in $(VK_GLOBAL_OBJS) to your Makefile's link rule.
3761 This is done for you if using the Verilator --exe flag.
3762 Note you can also call ->trace on multiple Verilated objects with
3764 the same trace file if you want all data to land in the same output
3765 file.
3766 #include "verilated_vcd_sc.h"
3768 ...
3769 int main(int argc, char** argv, char** env) {
3770 ...
3771 Verilated::traceEverOn(true);
3772 VerilatedVcdSc* tfp = new VerilatedVcdSc;
3773 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
3774 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
3775 ...
3776 sc_start(1);
3777 ...
3778 tfp->close();
3779 }
3780 How do I generate FST waveforms (traces) in C++?
3782 FST a format by GTKWave. This version provides a basic FST
3783 support. To dump FST format, add the --trace-fst switch to
3784 Verilator and change the include path in the testbench to:
3785 #include "verilated_fst_c.h"
3787 VerilatedFstC* tfp = new VerilatedFstC;
3788 Note that currently supporting both FST and VCD in a single
3790 simulation is impossible, but such requirement could be rare.
3791 How do I generate FST waveforms (traces) in SystemC?
3793 The FST library from GTKWave does not currently support SystemC;
3794 use VCD format instead.
3795 How do I view waveforms (traces)?
3797 Verilator makes standard VCD (Value Change Dump) and FST files.
3798 VCD files are viewable with the public domain GTKWave (recommended)
3799 or Dinotrace (legacy) programs, or any of the many commercial
3800 offerings; FST is supported by GTKWave only.
3801 How do I reduce the size of large waveform (trace) files?
3803 First, instead of calling VerilatedVcdC->open at the beginning of
3804 time, delay calling it until the time stamp where you want to
3805 tracing to begin. Likewise you can also call VerilatedVcdC->open
3806 before the end of time (perhaps a short period after you detect a
3807 verification error.)
3808 Next, add /*verilator tracing_off*/ to any very low level modules
3810 you never want to trace (such as perhaps library cells). Finally,
3811 use the --trace-depth option to limit the depth of tracing, for
3812 example --trace-depth 1 to see only the top level signals.
3813 Also be sure you write your trace files to a local solid-state
3815 disk, instead of to a network disk. Network disks are generally
3816 far slower.
3817 How do I do coverage analysis?
3819 Verilator supports both block (line) coverage and user inserted
3820 functional coverage.
3821 First, run verilator with the --coverage option. If you're using
3823 your own makefile, compile the model with the GCC flag
3824 -DVM_COVERAGE (if using Verilator's, it will do this for you.)
3825 At the end of your test, call VerilatedCov::write passing the name
3827 of the coverage data file (typically "logs/coverage.dat").
3828 Run each of your tests in different directories. Each test will
3830 create a logs/coverage.dat file.
3831 After running all of your tests, verilator_coverage is executed.
3833 Verilator_coverage reads the logs/coverage.dat file(s), and creates
3834 an annotated source code listing showing code coverage details.
3835 For an example, after running 'make test' in the Verilator
3837 distribution, see the examples/tracing_c/logs directory. Grep for
3838 lines starting with '%' to see what lines Verilator believes need
3839 more coverage.
3840 Where is the translate_off command? (How do I ignore a construct?)
3842 Translate on/off pragmas are generally a bad idea, as it's easy to
3843 have mismatched pairs, and you can't see what another tool sees by
3844 just preprocessing the code. Instead, use the preprocessor;
3845 Verilator defines the "VERILATOR" define for you, so just wrap the
3846 code in an ifndef region:
3847 `ifndef VERILATOR
3849 Something_Verilator_Dislikes;
3850 `endif
3851 Most synthesis tools similarly define SYNTHESIS for you.
3853 Why do I get "unexpected `do'" or "unexpected `bit'" errors?
3855 Do, bit, ref, return, and other words are now SystemVerilog
3856 keywords. You should change your code to not use them to insure it
3857 works with newer tools. Alternatively, surround them by the
3858 Verilog 2005/SystemVerilog begin_keywords pragma to indicate
3859 Verilog 2001 code.
3860 `begin_keywords "1364-2001"
3862 integer bit; initial bit = 1;
3863 `end_keywords
3864 If you want the whole file to be parsed as Verilog 2001, just
3866 create a file with
3867 `begin_keywords "1364-2001"
3869 and add it before other Verilog files on the command line. (Note
3871 this will also change the default for --prefix, so if you're not
3872 using --prefix, you will now need to.)
3873 How do I prevent my assertions from firing during reset?
3875 Call Verilated::assertOn(false) before you first call the model,
3876 then turn it back on after reset. It defaults to true. When
3877 false, all assertions controlled by --assert are disabled.
3878 Why do I get "undefined reference to `sc_time_stamp()'"?
3880 In C++ (non SystemC) code you need to define this function so that
3881 the simulator knows the current time. See the "CONNECTING TO C++"
3882 examples.
3883 Why do I get "undefined reference to `VL_RAND_RESET_I' or
3885 `Verilated::...'"?
3886 You need to link your compiled Verilated code against the
3887 verilated.cpp file found in the include directory of the Verilator
3888 kit. This is one target in the $(VK_GLOBAL_OBJS) make variable,
3889 which should be part of your Makefile's link rule. If you use
3890 --exe, this is done for you.
3891 Is the PLI supported?
3893 Only somewhat. More specifically, the common PLI-ish calls
3894 $display, $finish, $stop, $time, $write are converted to C++
3895 equivalents. You can also use the "import DPI" SystemVerilog
3896 feature to call C code (see the chapter above). There is also
3897 limited VPI access to public signals.
3898 If you want something more complex, since Verilator emits standard
3900 C++ code, you can simply write your own C++ routines that can
3901 access and modify signal values without needing any PLI interface
3902 code, and call it with $c("{any_c++_statement}").
3903 How do I make a Verilog module that contain a C++ object?
3905 You need to add the object to the structure that Verilator creates,
3906 then use $c to call a method inside your object. The
3907 test_regress/t/t_extend_class files show an example of how to do
3908 this.
3909 How do I get faster build times?
3911 Use a recent compiler. Newer compilers tend do be faster, with the
3912 now relatively old GCC 3.0 to 3.3 being horrible.
3913 Compile in parallel on many machines and use caching; see the web
3915 for the ccache, distcc and icecream packages. ccache will skip GCC
3916 runs between identical source builds, even across different users.
3917 You can use the OBJCACHE environment variable to use these CC
3918 wrappers. Also see the --output-split option.
3919 To reduce the compile time of classes that use a Verilated module
3921 (e.g. a top CPP file) you may wish to add /*verilator
3922 no_inline_module*/ to your top level module. This will decrease the
3923 amount of code in the model's Verilated class, improving compile
3924 times of any instantiating top level C++ code, at a relatively
3925 small cost of execution performance.
3926 Why do so many files need to recompile when I add a signal?
3928 Adding a new signal requires the symbol table to be recompiled.
3929 Verilator uses one large symbol table, as that results in 2-3 less
3930 assembly instructions for each signal access. This makes the
3931 execution time 10-15% faster, but can result in more compilations
3932 when something changes.
3933 How do I access functions/tasks in C?
3935 Use the SystemVerilog Direct Programming Interface. You write a
3936 Verilog function or task with input/outputs that match what you
3937 want to call in with C. Then mark that function as an external
3938 function. See the DPI chapter in the manual.
3939 How do I access signals in C?
3941 The best thing is to make a SystemVerilog "export DPI task" or
3942 function that accesses that signal, as described in the DPI chapter
3943 in the manual and DPI tutorials on the web. This will allow
3944 Verilator to better optimize the model and should be portable
3945 across simulators.
3946 If you really want raw access to the signals, declare the signals
3948 you will be accessing with a /*verilator public*/ comment before
3949 the closing semicolon. Then scope into the C++ class to read the
3950 value of the signal, as you would any other member variable.
3951 Signals are the smallest of 8-bit chars, 16-bit shorts, 32-bit
3953 longs, or 64-bit long longs that fits the width of the signal.
3954 Generally, you can use just uint32_t's for 1 to 32 bits, or
3955 vluint64_t for 1 to 64 bits, and the compiler will properly up-
3956 convert smaller entities.
3957 Signals wider than 64 bits are stored as an array of 32-bit
3959 uint32_t's. Thus to read bits 31:0, access signal[0], and for bits
3960 63:32, access signal[1]. Unused bits (for example bit numbers
3961 65-96 of a 65-bit vector) will always be zero. if you change the
3962 value you must make sure to pack zeros in the unused bits or core-
3963 dumps may result. (Because Verilator strips array bound checks
3964 where it believes them to be unnecessary.)
3965 In the SYSTEMC example above, if you had in our.v:
3967 input clk /*verilator public*/;
3969 // Note the placement of the semicolon above
3970 From the sc_main.cpp file, you'd then:
3972 #include "Vour.h"
3974 #include "Vour_our.h"
3975 cout << "clock is " << top->our->clk << endl;
3976 In this example, clk is a bool you can read or set as any other
3978 variable. The value of normal signals may be set, though clocks
3979 shouldn't be changed by your code or you'll get strange results.
3980 Should a module be in Verilog or SystemC?
3982 Sometimes there is a block that just interconnects cells, and have
3983 a choice as to if you write it in Verilog or SystemC. Everything
3984 else being equal, best performance is when Verilator sees all of
3985 the design. So, look at the hierarchy of your design, labeling
3986 cells as to if they are SystemC or Verilog. Then:
3987 A module with only SystemC cells below must be SystemC.
3989 A module with a mix of Verilog and SystemC cells below must be
3991 SystemC. (As Verilator cannot connect to lower-level SystemC
3992 cells.)
3993 A module with only Verilog cells below can be either, but for best
3995 performance should be Verilog. (The exception is if you have a
3996 design that is instantiated many times; in this case Verilating one
3997 of the lower modules and instantiating that Verilated cells
3998 multiple times into a SystemC module *may* be faster.)
3999
4001 First, check the the coding limitations section.
4002 Next, try the --debug switch. This will enable additional internal
4004 assertions, and may help identify the problem.
4005 Finally, reduce your code to the smallest possible routine that
4007 exhibits the bug. Even better, create a test in the test_regress/t
4008 directory, as follows:
4009 cd test_regress
4011 cp -p t/t_EXAMPLE.pl t/t_BUG.pl
4012 cp -p t/t_EXAMPLE.v t/t_BUG.v
4013 There are many hits on how to write a good test in the driver.pl
4015 documentation which can be seen by running:
4016 cd $VERILATOR_ROOT # Need the original distribution kit
4018 test_regress/driver.pl --help
4019 Edit t/t_BUG.pl to suit your example; you can do anything you want in
4021 the Verilog code there; just make sure it retains the single clk input
4022 and no outputs. Now, the following should fail:
4023 cd $VERILATOR_ROOT # Need the original distribution kit
4025 cd test_regress
4026 t/t_BUG.pl # Run on Verilator
4027 t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
4028 t/t_BUG.pl --vcs # Run on a commercial simulator
4029 t/t_BUG.pl --nc|--iv|--ghdl # Likewise on other simulators
4030 The test driver accepts a number of options, many of which mirror the
4032 main Verilator option. For example the previous test could have been
4033 run with debugging enabled. The full set of test options can be seen
4034 by running driver.pl --help as shown above.
4035 Finally, report the bug using the bug tracker at
4037 <http://www.veripool.org/verilator>. The bug will become publicly
4038 visible; if this is unacceptable, mail the bug report to
4039 "wsnyder@wsnyder.org".
4040
4042 Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group
4043 at Digital Equipment Corporation. The Verilog code that was converted
4044 to C was then merged with a C based CPU model of the Alpha processor
4045 and simulated in a C based environment called CCLI.
4046 In 1995 Verilator started being used also for Multimedia and Network
4048 Processor development inside Digital. Duane Galbi took over active
4049 development of Verilator, and added several performance enhancements.
4050 CCLI was still being used as the shell.
4051 In 1998, through the efforts of existing DECies, mainly Duane Galbi,
4053 Digital graciously agreed to release the source code. (Subject to the
4054 code not being resold, which is compatible with the GNU Public
4055 License.)
4056 In 2001, Wilson Snyder took the kit, and added a SystemC mode, and
4058 called it Verilator2. This was the first packaged public release.
4059 In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator
4061 from scratch in C++. This added many optimizations, yielding about a
4062 2-5x performance gain.
4063 In 2009, major SystemVerilog and DPI language support was added.
4065 In 2018, Verilator 4.000 was released with multithreaded support.
4067 Currently, various language features and performance enhancements are
4069 added as the need arises. Verilator is now about 3x faster than in
4070 2002, and is faster than many popular commercial simulators.
4071
4073 When possible, please instead report bugs to
4074 <http://www.veripool.org/>.
4075 Wilson Snyder <wsnyder@wsnyder.org>
4077 Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
4079
4081 Many people have provided ideas and other assistance with Verilator.
4082 The major corporate sponsors of Verilator, by providing significant
4084 contributions of time or funds include include Atmel Corporation,
4085 Cavium Inc., Compaq Corporation, Digital Equipment Corporation,
4086 Embecosm Ltd., Hicamp Systems, Intel Corporation, Mindspeed
4087 Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun
4088 Microsystems Inc., Nauticus Networks Inc., and SiCortex Inc.
4089 The people who have contributed major functionality are Byron Bradley,
4091 Jeremy Bennett, Jie Xu, Lane Brooks, John Coiner, Duane Galbi, Paul
4092 Wasson, and Wilson Snyder. Major testers included Jeff Dutton,
4093 Jonathon Donaldson, Ralf Karge, David Hewson, Iztok Jeras, Wim
4094 Michiels, Alex Solomatnikov, Sebastien Van Cauwenberghe, Gene Weber,
4095 and Clifford Wolf.
4096 Some of the people who have provided ideas and feedback for Verilator
4098 include: Ahmed El-Mahmoudy, David Addison, Tariq B. Ahmad, Nikana
4099 Anastasiadis, Hans Van Antwerpen, Vasu Arasanipalai, Jens Arm, Sharad
4100 Bagri, Andrew Bardsley, Matthew Barr, Geoff Barrett, Julius Baxter,
4101 Jeremy Bennett, Michael Berman, Victor Besyakov, David Binderman, Johan
4102 Bjork, David Black, Tymoteusz Blazejczyk, Daniel Bone, Gregg Bouchard,
4103 Christopher Boumenot, Nick Bowler, Byron Bradley, Bryan Brady, Charlie
4104 Brej, J Briquet, Lane Brooks, John Brownlee, Jeff Bush, Lawrence
4105 Butcher, Ted Campbell, Chris Candler, Lauren Carlson, Donal Casey,
4106 Sebastien Van Cauwenberghe, Terry Chen, Enzo Chi, Robert A. Clark,
4107 Allan Cochrane, John Coiner, Laurens van Dam, Gunter Dannoritzer,
4108 Ashutosh Das, Bernard Deadman, John Demme, Mike Denio, John Deroo,
4109 Philip Derrick, Joe DErrico, John Dickol, Ruben Diez, Danny Ding, Ivan
4110 Djordjevic, Jonathon Donaldson, Sebastian Dressler, Alex Duller, Jeff
4111 Dutton, Usuario Eda, Chandan Egbert, Joe Eiler, Ahmed El-Mahmoudy,
4112 Trevor Elbourne, Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Brian
4113 Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi, Christian Gelinek,
4114 Glen Gibb, Shankar Giri, Dan Gisselquist, Sam Gladstone, Amir Gonnen,
4115 Chitlesh Goorah, Xuan Guo, Neil Hamilton, Jannis Harder, Junji
4116 Hashimoto, Thomas Hawkins, Robert Henry, David Hewson, Jamey Hicks,
4117 Joel Holdsworth, Hiroki Honda, Alex Hornung, David Horton, Jae Hossell,
4118 Alan Hunter, James Hutchinson, Jamie Iles, Ben Jackson, Shareef Jalloq,
4119 Krzysztof Jankowski, HyungKi Jeong, Iztok Jeras, James Johnson,
4120 Christophe Joly, Franck Jullien, James Jung, Mike Kagen, Arthur
4121 Kahlich, Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi, Patricio
4122 Kaplan, Ralf Karge, Dan Katz, Sol Katzman, Jonathan Kimmitt, Olof
4123 Kindgren, Dan Kirkham, Sobhan Klnv, Gernot Koch, Soon Koh, Steve
4124 Kolecki, Brett Koonce, Wojciech Koszek, Varun Koyyalagunta, David
4125 Kravitz, Roland Kruse, Sergey Kvachonok, Ed Lander, Steve Lang,
4126 Stephane Laurent, Walter Lavino, Christian Leber, Igor Lesik, John Li,
4127 Eivind Liland, Yu Sheng Lin, Charlie Lind, Andrew Ling, Paul Liu, Derek
4128 Lockhart, Arthur Low, Stefan Ludwig, Dan Lussier, Fred Ma, Duraid
4129 Madina, Julien Margetts, Mark Marshall, Alfonso Martinez, Yves Mathieu,
4130 Patrick Maupin, Jason McMullan, Elliot Mednick, Wim Michiels, Miodrag
4131 Milanovic, Wai Sum Mong, Sean Moore, Dennis Muhlestein, John Murphy,
4132 Richard Myers, Dimitris Nalbantis, Bob Newgard, Cong Van Nguyen, Paul
4133 Nitza, Pete Nixon, Lisa Noack, Mark Nodine, Andreas Olofsson, James
4134 Pallister, Brad Parker, Maciej Piechotka, David Pierce, Dominic
4135 Plunkett, David Poole, Mike Popoloski, Rich Porter, Niranjan Prabhu,
4136 Usha Priyadharshini, Mark Jackson Pulver, Prateek Puri, Marshal Qiao,
4137 Chris Randall, Anton Rapp, Josh Redford, Odd Magne Reitan, Frederic
4138 Requin, Alberto Del Rio, Oleg Rodionov, Paul Rolfe, Arjen Roodselaar,
4139 Jan Egil Ruud, John Sanguinetti, Galen Seitz, Salman Sheikh, Mike
4140 Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Rodney Sinclair, Steven
4141 Slatter, Brian Small, Wilson Snyder, Alex Solomatnikov, Wei Song, Art
4142 Stamness, John Stevenson, Patrick Stewart, Rob Stoddard, Todd Strader,
4143 John Stroebel, Sven Stucki, Emerson Suguimoto, Gene Sullivan, Renga
4144 Sundararajan, Yutetsu Takatsukasa, Peter Tengstrand, Wesley Terpstra,
4145 Rui Terra, Stefan Thiede, Gary Thomas, Kevin Thompson, Ian Thompson,
4146 Mike Thyer, Hans Tichelaar, Steve Tong, Michael Tresidder, Holger
4147 Waechtler, Stefan Wallentowitz, Shawn Wang, Paul Wasson, Greg Waters,
4148 Thomas Watts, Eugene Weber, David Welch, Thomas J Whatson, Leon
4149 Wildman, Gerald Williams, Trevor Williams, Jeff Winston, Joshua Wise,
4150 Clifford Wolf, Johan Wouters, Junyi Xi, Ding Xiaoliang, Jie Xu, Mandy
4151 Xu, Luke Yang, and Amir Yazdanbakhsh.
4152 Thanks to them, and all those we've missed including above, or wished
4154 to remain anonymous.
4155
4157 The latest version is available from <http://www.veripool.org/>.
4158 Copyright 2003-2019 by Wilson Snyder. Verilator is free software; you
4160 can redistribute it and/or modify the Verilator internals under the
4161 terms of either the GNU Lesser General Public License Version 3 or the
4162 Perl Artistic License Version 2.0.
4163
4165 verilator_coverage, verilator_gantt, verilator_profcfunc, make,
4166 "verilator --help" which is the source for this document,
4168 and internals.txt in the distribution.
4170perl v5.30.0 2019-08-22 VERILATOR(1)