1VERILATOR(1) User Contributed Perl Documentation VERILATOR(1)
2
6 Verilator - Translate and simulate SystemVerilog code using 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 traditional 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 --make <make-system> Generate scripts for specified make system
61 --compiler <compiler-name> Tune for specified C++ compiler
62 --converge-limit <loops> Tune convergence settle time
63 --coverage Enable all coverage
64 --coverage-line Enable line coverage
65 --coverage-toggle Enable toggle coverage
66 --coverage-user Enable SVL user coverage
67 --coverage-underscore Enable coverage of _signals
68 -D<var>[=<value>] Set preprocessor define
69 --debug Enable debugging
70 --debug-check Enable debugging assertions
71 --no-debug-leak Disable leaking memory in --debug mode
72 --debugi <level> Enable debugging at a specified level
73 --debugi-<srcfile> <level> Enable debugging a source file at a level
74 --default-language <lang> Default language to parse
75 +define+<var>=<value> Set preprocessor define
76 --dpi-hdr-only Only produce the DPI header file
77 --dump-defines Show preprocessor defines with -E
78 --dump-tree Enable dumping .tree files
79 --dump-treei <level> Enable dumping .tree files at a level
80 --dump-treei-<srcfile> <level> Enable dumping .tree file at a source file at a level
81 -E Preprocess, but do not compile
82 --error-limit <value> Abort after this number of errors
83 --exe Link to create executable
84 -F <file> Parse options from a file, relatively
85 -f <file> Parse options from a file
86 -FI <file> Force include of a file
87 -G<name>=<value> Overwrite toplevel parameter
88 --gdb Run Verilator under GDB interactively
89 --gdbbt Run Verilator under GDB for backtrace
90 --generate-key Create random key for --protect-key
91 --getenv <var> Get environment variable with defaults
92 --help Display this help
93 -I<dir> Directory to search for includes
94 --gate-stmts <value> Tune gate optimizer depth
95 --if-depth <value> Tune IFDEPTH warning
96 +incdir+<dir> Directory to search for includes
97 --inhibit-sim Create function to turn off sim
98 --inline-mult <value> Tune module inlining
99 -LDFLAGS <flags> Linker pre-object flags for makefile
100 --l2-name <value> Verilog scope name of the top module
101 --language <lang> Default language standard to parse
102 +libext+<ext>+[ext]... Extensions for finding modules
103 --lint-only Lint, but do not make output
104 --max-num-width <value> Maximum number width (default: 64K)
105 --MMD Create .d dependency files
106 --MP Create phony dependency targets
107 --Mdir <directory> Name of output object directory
108 --mod-prefix <topname> Name to prepend to lower classes
109 --no-clk <signal-name> Prevent marking specified signal as clock
110 --no-decoration Disable comments and symbol decorations
111 --no-pins64 Don't use vluint64_t's for 33-64 bit sigs
112 --no-skip-identical Disable skipping identical output
113 +notimingchecks Ignored
114 -O0 Disable optimizations
115 -O3 High performance optimizations
116 -O<optimization-letter> Selectable optimizations
117 -o <executable> Name of final executable
118 --no-order-clock-delay Disable ordering clock enable assignments
119 --output-split <statements> Split .cpp files into pieces
120 --output-split-cfuncs <statements> Split .cpp functions
121 --output-split-ctrace <statements> Split tracing functions
122 -P Disable line numbers and blanks with -E
123 --pins-bv <bits> Specify types for top level ports
124 --pins-sc-uint Specify types for top level ports
125 --pins-sc-biguint Specify types for top level ports
126 --pins-uint8 Specify types for top level ports
127 --pipe-filter <command> Filter all input through a script
128 --pp-comments Show preprocessor comments with -E
129 --prefix <topname> Name of top level class
130 --prof-cfuncs Name functions for profiling
131 --prof-threads Enable generating gantt chart data for threads
132 --protect-key <key> Key for symbol protection
133 --protect-ids Hash identifier names for obscurity
134 --protect-lib <name> Create a DPI protected library
135 --private Debugging; see docs
136 --public Debugging; see docs
137 --public-flat-rw Mark all variables, etc as public_flat_rw
138 -pvalue+<name>=<value> Overwrite toplevel parameter
139 --quiet-exit Don't print the command on failure
140 --relative-includes Resolve includes relative to current file
141 --no-relative-cfuncs Disallow 'this->' in generated functions
142 --report-unoptflat Extra diagnostics for UNOPTFLAT
143 --rr Run Verilator and record with rr
144 --savable Enable model save-restore
145 --sc Create SystemC output
146 --stats Create statistics file
147 --stats-vars Provide statistics on variables
148 -sv Enable SystemVerilog parsing
149 +systemverilogext+<ext> Synonym for +1800-2017ext+<ext>
150 --threads <threads> Enable multithreading
151 --threads-dpi <mode> Enable multithreaded DPI
152 --threads-max-mtasks <mtasks> Tune maximum mtask partitioning
153 --top-module <topname> Name of top level input module
154 --trace Enable waveform creation
155 --trace-depth <levels> Depth of tracing
156 --trace-coverage Enable tracing of coverage
157 --trace-fst Enable FST waveform creation
158 --trace-fst-thread Enable FST threaded waveform creation
159 --trace-max-array <depth> Maximum bit width for tracing
160 --trace-max-width <width> Maximum array depth for tracing
161 --trace-params Enable tracing of parameters
162 --trace-structs Enable tracing structure names
163 --trace-underscore Enable tracing of _signals
164 -U<var> Undefine preprocessor define
165 --unroll-count <loops> Tune maximum loop iterations
166 --unroll-stmts <stmts> Tune maximum loop body size
167 --unused-regexp <regexp> Tune UNUSED lint signals
168 -V Verbose version and config
169 -v <filename> Verilog library
170 +verilog1995ext+<ext> Synonym for +1364-1995ext+<ext>
171 +verilog2001ext+<ext> Synonym for +1364-2001ext+<ext>
172 --version Displays program version and exits
173 --vpi Enable VPI compiles
174 -Wall Enable all style warnings
175 -Werror-<message> Convert warnings to errors
176 -Wfuture-<message> Disable unknown message warnings
177 -Wno-<message> Disable warning
178 -Wno-context Disable source context on warnings
179 -Wno-fatal Disable fatal exit on warnings
180 -Wno-lint Disable all lint warnings
181 -Wno-style Disable all style warnings
182 -Wpedantic Warn on compliance-test issues
183 --x-assign <mode> Assign non-initial Xs to this value
184 --x-initial <mode> Assign initial Xs to this value
185 --x-initial-edge Enable initial X->0 and X->1 edge triggers
186 --xml-only Create XML parser output
187 --xml-output XML output filename
188 -y <dir> Directory to search for modules
189 This is a short summary of the arguments to simulation runtime
191 Verilated arguments. detailed descriptions in "SIMULATION RUNTIME
192 ARGUMENTS" for more information.
193 +verilator+debug Enable debugging
195 +verilator+debugi+<value> Enable debugging at a level
196 +verilator+help Display help
197 +verilator+prof+threads+file+I<filename> Set profile filename
198 +verilator+prof+threads+start+I<value> Set profile starting point
199 +verilator+prof+threads+window+I<value> Set profile duration
200 +verilator+rand+reset+I<value> Set random reset technique
201 +verilator+seed+I<value> Set random seed
202 +verilator+noassert Disable assert checking
203 +verilator+V Verbose version and config
204 +verilator+version Show version and exit
205
207 The following are the arguments that may be passed to Verilator itself.
208 {file.v}
210 Specifies the Verilog file containing the top module to be
211 Verilated.
212 {file.c/.cc/.cpp/.cxx}
214 Specifies optional C++ files to be linked in with the Verilog code.
215 The file path should either be absolute, or relative to where the
216 make will be executed from, or add to your makefile's VPATH the
217 appropriate directory to find the file.
218 If any C++ files are specified in this way, Verilator will include
220 a make rule that generates a module executable. Without any C++
221 files, Verilator will stop at the module__ALL.a library, and
222 presume you'll continue linking with make rules you write yourself.
223 See also the -CFLAGS option.
224 {file.a/.o/.so}
226 Specifies optional object or library files to be linked in with the
227 Verilog code, as a shorthand for -LDFLAGS "<file>". The file path
228 should either be absolute, or relative to where the make will be
229 executed from, or add to your makefile's VPATH the appropriate
230 directory to find the file.
231 If any files are specified in this way, Verilator will include a
233 make rule that uses these files when linking the module executable.
234 This generally is only useful when used with the --exe option.
235 +1364-1995ext+ext
237 +1364-2001ext+ext
238 +1364-2005ext+ext
239 +1800-2005ext+ext
240 +1800-2009ext+ext
241 +1800-2012ext+ext
242 +1800-2017ext+ext
243 Specifies the language standard to be used with a specific filename
244 extension, ext.
245 For compatibility with other simulators, see also the synonyms
247 "+verilog1995ext+"ext, "+verilog2001ext+"ext, and
248 "+systemverilogext+"ext.
249 For any source file, the language specified by these options takes
251 precedence over any language specified by the "--default-language"
252 or "--language" options.
253 These options take effect in the order they are encountered. Thus
255 the following would use Verilog 1995 for "a.v" and Verilog 2001 for
256 "b.v".
257 verilator ... +1364-1995ext+v a.v +1364-2001ext+v b.v
259 These flags are only recommended for legacy mixed language designs,
261 as the preferable option is to edit the code to repair new
262 keywords, or add appropriate "`begin_keywords".
263 Note "`begin_keywords" is a SystemVerilog construct, which
265 specifies only which the set of keywords is to be recognized.
266 Whatever set is chosen, the semantics will be those of
267 SystemVerilog. By contrast "+1364-1995ext+" etc. specify both the
268 syntax and semantics to be used.
269 --assert
271 Enable all assertions.
272 --autoflush
274 After every $display or $fdisplay, flush the output stream. This
275 ensures that messages will appear immediately but may reduce
276 performance; for best performance call "fflush(stdout)"
277 occasionally in the main C loop. Defaults off, which will buffer
278 output as provided by the normal C stdio calls.
279 --bbox-sys
281 Black box any unknown $system task or function calls. System tasks
282 will be simply become no-operations, and system functions will be
283 replaced by unsized zero. Arguments to such functions will be
284 parsed, but not otherwise checked. This prevents errors when
285 linting in the presence of company specific PLI calls.
286 --bbox-unsup
288 Black box some unsupported language features, currently UDP tables,
289 the cmos and tran gate primitives, deassign statements, and mixed
290 edge errors. This may enable linting the rest of the design even
291 when unsupported constructs are present.
292 --bin filename
294 Rarely needed. Override the default filename for Verilator itself.
295 When a dependency (.d) file is created, this filename will become a
296 source dependency, such that a change in this binary will have make
297 rebuild the output files.
298 -CFLAGS flags
300 Add specified C compiler flag to the generated makefiles. For
301 multiple flags either pass them as a single argument with space
302 separators quoted in the shell ("-CFLAGS "-a -b""), or use multiple
303 -CFLAGS arguments ("-CFLAGS -a -CFLAGS -b").
304 When make is run on the generated makefile these will be passed to
306 the C++ compiler (gcc/g++/msvc++).
307 --cc
309 Specifies C++ without SystemC output mode; see also --sc.
310 --cdc
312 Experimental. Perform some clock domain crossing checks and issue
313 related warnings (CDCRSTLOGIC) and then exit; if warnings other
314 than CDC warnings are needed make a second run with --lint-only.
315 Additional warning information is also written to the file
316 {prefix}__cdc.txt.
317 Currently only checks some items that other CDC tools missed; if
319 you have interest in adding more traditional CDC checks, please
320 contact the authors.
321 --clk signal-name
323 Sometimes it is quite difficult for Verilator to distinguish clock
324 signals from other data signals. Occasionally the clock signals can
325 end up in the checking list of signals which determines if further
326 evaluation is needed. This will heavily degrade the performance of
327 a Verilated model.
328 With --clk <signal-name>, user can specified root clock into the
330 model, then Verilator will mark the signal as clocker and propagate
331 the clocker attribute automatically to other signals derived from
332 that. In this way, Verilator will try to avoid taking the clocker
333 signal into checking list.
334 Note signal-name is specified by the RTL hierarchy path. For
336 example, v.foo.bar. If the signal is the input to top-module, the
337 directly the signal name. If you find it difficult to find the
338 exact name, try to use "/*verilator clocker*/" in RTL file to mark
339 the signal directly.
340 If clock signals are assigned to vectors and then later used
342 individually, Verilator will attempt to decompose the vector and
343 connect the single-bit clock signals directly. This should be
344 transparent to the user.
345 --make make-system
347 Generates a script for the specified make system.
348 Supported make systems are gmake and cmake. Both can be specified.
350 If no make system is specified, gmake is assumed.
351 --compiler compiler-name
353 Enables tunings and workarounds for the specified C++ compiler.
354 clang
356 Tune for clang. This may reduce execution speed as it enables
357 several workarounds to avoid silly hardcoded limits in clang.
358 This includes breaking deep structures as for msvc as described
359 below.
360 gcc Tune for GNU C++, although generated code should work on almost
362 any compliant C++ compiler. Currently the default.
363 msvc
365 Tune for Microsoft Visual C++. This may reduce execution speed
366 as it enables several workarounds to avoid silly hardcoded
367 limits in MSVC++. This includes breaking deeply nested
368 parenthesized expressions into sub-expressions to avoid error
369 C1009, and breaking deep blocks into functions to avoid error
370 C1061.
371 --converge-limit loops
373 Rarely needed. Specifies the maximum number of runtime iterations
374 before creating a model failed to converge error. Defaults to 100.
375 --coverage
377 Enables all forms of coverage, alias for "--coverage-line
378 --coverage-toggle --coverage-user".
379 --coverage-line
381 Specifies basic block line coverage analysis code should be
382 inserted.
383 Coverage analysis adds statements at each code flow change point,
385 which are the branches of IF and CASE statements, a super-set of
386 normal Verilog Line Coverage. At each such branch a unique counter
387 is incremented. At the end of a test, the counters along with the
388 filename and line number corresponding to each counter are written
389 into logs/coverage.dat.
390 Verilator automatically disables coverage of branches that have a
392 $stop in them, as it is assumed $stop branches contain an error
393 check that should not occur. A /*verilator coverage_block_off*/
394 comment will perform a similar function on any code in that block
395 or below, or /*verilator coverage_on/coverage_off*/ will disable
396 coverage around lines of code.
397 Note Verilator may over-count combinatorial (non-clocked) blocks
399 when those blocks receive signals which have had the UNOPTFLAT
400 warning disabled; for most accurate results do not disable this
401 warning when using coverage.
402 --coverage-toggle
404 Specifies signal toggle coverage analysis code should be inserted.
405 Every bit of every signal in a module has a counter inserted. The
407 counter will increment on every edge change of the corresponding
408 bit.
409 Signals that are part of tasks or begin/end blocks are considered
411 local variables and are not covered. Signals that begin with
412 underscores, are integers, or are very wide (>256 bits total
413 storage across all dimensions) are also not covered.
414 Hierarchy is compressed, such that if a module is instantiated
416 multiple times, coverage will be summed for that bit across ALL
417 instantiations of that module with the same parameter set. A
418 module instantiated with different parameter values is considered a
419 different module, and will get counted separately.
420 Verilator makes a minimally-intelligent decision about what clock
422 domain the signal goes to, and only looks for edges in that clock
423 domain. This means that edges may be ignored if it is known that
424 the edge could never be seen by the receiving logic. This
425 algorithm may improve in the future. The net result is coverage
426 may be lower than what would be seen by looking at traces, but the
427 coverage is a more accurate representation of the quality of
428 stimulus into the design.
429 There may be edges counted near time zero while the model
431 stabilizes. It's a good practice to zero all coverage just before
432 releasing reset to prevent counting such behavior.
433 A /*verilator coverage_off/on */ comment pair can be used around
435 signals that do not need toggle analysis, such as RAMs and register
436 files.
437 --coverage-underscore
439 Enable coverage of signals that start with an underscore. Normally,
440 these signals are not covered. See also --trace-underscore.
441 --coverage-user
443 Enables user inserted functional coverage. Currently, all
444 functional coverage points are specified using SVA which must be
445 separately enabled with --assert.
446 For example, the following statement will add a coverage point,
448 with the comment "DefaultClock":
449 DefaultClock: cover property (@(posedge clk) cyc==3);
451 -Dvar=value
453 Defines the given preprocessor symbol, without allowing. Similar
454 to +define; +define is fairly standard across Verilog tools while
455 -D is an alias for GCC compatibility.
456 --debug
458 Select the debug built image of Verilator (if available), and
459 enable more internal assertions (equivalent to "--debug-check"),
460 debugging messages (equivalent to "--debugi 4"), and intermediate
461 form dump files (equivalent to "--dump-treei 3").
462 --debug-check
464 Rarely needed. Enable internal debugging assertion checks, without
465 changing debug verbosity. Enabled automatically when --debug
466 specified.
467 --no-debug-leak
469 In --debug mode, by default Verilator intentionally leaks AstNode's
470 instead of freeing them, so that each node pointer is unique in the
471 resulting tree files and dot files.
472 This option disables the leak. This may avoid out-of-memory errors
474 when Verilating large models in --debug mode.
475 Outside of --debug mode, AstNode's should never be leaked and this
477 option has no effect.
478 --debugi level
480 --debugi-srcfile level
481 Rarely needed - for developer use. Set internal debugging level
482 globally to the specified debug level (1-10) or set the specified
483 Verilator source file to the specified level (e.g.
484 "--debugi-V3Width 9"). Higher levels produce more detailed
485 messages.
486 --default-language value
488 Select the language to be used by default when first processing
489 each Verilog file. The language value must be "1364-1995",
490 "1364-2001", "1364-2005", "1800-2005", "1800-2009", "1800-2012" or
491 "1800-2017".
492 Any language associated with a particular file extension (see the
494 various +langext+ options) will be used in preference to the
495 language specified by --default-language.
496 The --default-language flag is only recommended for legacy code
498 using the same language in all source files, as the preferable
499 option is to edit the code to repair new keywords, or add
500 appropriate "`begin_keywords". For legacy mixed language designs,
501 the various +langext+ options should be used.
502 If no language is specified, either by this flag or +langext+
504 options, then the latest SystemVerilog language (IEEE 1800-2017) is
505 used.
506 +define+var=value
508 +define+var=value+var2=value2...
509 Defines the given preprocessor symbol, or multiple symbols if
510 separated by plusses. Similar to -D; +define is fairly standard
511 across Verilog tools while -D is an alias for GCC compatibility.
512 --dpi-hdr-only
514 Only generate the DPI header file. This option has no effect on
515 the name or location of the file.
516 --dump-defines
518 With -E, suppress normal output, and instead print a list of all
519 defines existing at the end of pre-processing the input files.
520 Similar to GCC "-dM" option. This also gives you a way of finding
521 out what is predefined in Verilator using the command:
522 touch foo.v ; verilator -E --dump-defines foo.v
524 --dump-tree
526 Rarely needed. Enable writing .tree debug files with dumping level
527 3, which dumps the standard critical stages. For details on the
528 format see the Verilator Internals manual. --dump-tree is enabled
529 automatically with --debug, so "--debug --no-dump-tree" may be
530 useful if the dump files are large and not desired.
531 --dump-treei level
533 --dump-treei-srcfile level
534 Rarely needed - for developer use. Set internal tree dumping level
535 globally to a specific dumping level or set the specified Verilator
536 source file to the specified tree dumping level (e.g.
537 "--dump-treei-V3Order 9"). Level 0 disbles dumps and is equivalent
538 to "--no-dump-tree". Level 9 enables dumping of every stage.
539 -E Preprocess the source code, but do not compile, as with 'gcc -E'.
541 Output is written to standard out. Beware of enabling debugging
542 messages, as they will also go to standard out.
543 --error-limit value
545 After this number of errors are encountered during Verilator run,
546 exit. Warnings are not counted in this limit. Defaults to 50.
547 Does not affect simulation runtime errors, for those see
549 +verilator+error+limit.
550 --exe
552 Generate an executable. You will also need to pass additional .cpp
553 files on the command line that implement the main loop for your
554 simulation.
555 -F file
557 Read the specified file, and act as if all text inside it was
558 specified as command line parameters. Any relative paths are
559 relative to the directory containing the specified file. See also
560 -f. Note -F is fairly standard across Verilog tools.
561 -f file
563 Read the specified file, and act as if all text inside it was
564 specified as command line parameters. Any relative paths are
565 relative to the current directory. See also -F. Note -f is fairly
566 standard across Verilog tools.
567 The file may contain // comments which are ignored to the end of
569 the line. Any $VAR, $(VAR), or ${VAR} will be replaced with the
570 specified environment variable.
571 -FI file
573 Force include of the specified C++ header file. All generated C++
574 files will insert a #include of the specified file before any other
575 includes. The specified file might be used to contain define
576 prototypes of custom VL_VPRINTF functions, and may need to include
577 verilatedos.h as this file is included before any other standard
578 includes.
579 -Gname=value
581 Overwrites the given parameter of the toplevel module. The value is
582 limited to basic data literals:
583 Verilog integer literals
585 The standard verilog integer literals are supported, so values
586 like 32'h8, 2'b00, 4 etc. are allowed. Care must be taken that
587 the single quote (I') is properly escaped in an interactive
588 shell, e.g., as -GWIDTH=8\'hx.
589 C integer literals
591 It is also possible to use C integer notation, including
592 hexadecimal (0x..), octal (0..) or binary (0b..) notation.
593 Double literals
595 Double literals must contain a dot (.) and/or an exponent (e).
596 Strings
598 String must in double quotes (""). On the command line it is
599 required to escape them properly, e.g. as -GSTR="\"My String\""
600 or -GSTR='"My String"'.
601 --gate-stmts value
603 Rarely needed. Set the maximum number of statements that may be
604 present in an equation for the gate substitution optimization to
605 inline that equation.
606 --gdb
608 Run Verilator underneath an interactive GDB (or VERILATOR_GDB
609 environment variable value) session. See also --gdbbt.
610 --gdbbt
612 If --debug is specified, run Verilator underneath a GDB process and
613 print a backtrace on exit, then exit GDB immediately. Without
614 --debug or if GDB doesn't seem to work, this flag is ignored.
615 Intended for easy creation of backtraces by users; otherwise see
616 the --gdb flag.
617 --generate-key
619 Generate a true-random key suitable for use with --protect-key,
620 print it, and exit immediately.
621 --getenv variable
623 If the variable is declared in the environment, print it and exit
624 immediately. Otherwise, if it's built into Verilator (e.g.
625 VERILATOR_ROOT), print that and exit immediately. Otherwise, print
626 a newline and exit immediately. This can be useful in makefiles.
627 See also -V, and the various *.mk files.
628 --help
630 Displays this message and program version and exits.
631 -Idir
633 See -y.
634 --if-depth value
636 Rarely needed. Set the depth at which the IFDEPTH warning will
637 fire, defaults to 0 which disables this warning.
638 +incdir+dir
640 See -y.
641 --inhibit-sim
643 Rarely needed. Create a "inhibitSim(bool)" function to enable and
644 disable evaluation. This allows an upper level testbench to
645 disable modules that are not important in a given simulation,
646 without needing to recompile or change the SystemC modules
647 instantiated.
648 --inline-mult value
650 Tune the inlining of modules. The default value of 2000 specifies
651 that up to 2000 new operations may be added to the model by
652 inlining, if more than this number of operations would result, the
653 module is not inlined. Larger values, or a value < 1 will inline
654 everything, will lead to longer compile times, but potentially
655 faster simulation runtimes. This setting is ignored for very small
656 modules; they will always be inlined, if allowed.
657 -LDFLAGS flags
659 Add specified C linker flags to the generated makefiles. For
660 multiple flags either pass them as a single argument with space
661 separators quoted in the shell ("-LDFLAGS "-a -b""), or use
662 multiple -LDFLAGS arguments ("-LDFLAGS -a -LDFLAGS -b").
663 When make is run on the generated makefile these will be passed to
665 the C++ linker (ld) *after* the primary file being linked. This
666 flag is called -LDFLAGS as that's the traditional name in
667 simulators; it's would have been better called LDLIBS as that's the
668 Makefile variable it controls. (In Make, LDFLAGS is before the
669 first object, LDLIBS after. -L libraries need to be in the Make
670 variable LDLIBS, not LDFLAGS.)
671 --l2-name value
673 Instead of using the module name when showing Verilog scope, use
674 the name provided. This allows simplifying some Verilator-embedded
675 modeling methodologies. Default is an l2-name matching the top
676 module. The default before 3.884 was "--l2-name v"
677 For example, the program "module t; initial $display("%m");
679 endmodule" will show by default "t". With "--l2-name v" it will
680 print "v".
681 --language value
683 A synonym for "--default-language", for compatibility with other
684 tools and earlier versions of Verilator.
685 +libext+ext+ext...
687 Specify the extensions that should be used for finding modules. If
688 for example module x is referenced, look in x.ext. Note +libext+
689 is fairly standard across Verilog tools. Defaults to .v and .sv.
690 --lint-only
692 Check the files for lint violations only, do not create any other
693 output.
694 You may also want the -Wall option to enable messages that are
696 considered stylistic and not enabled by default.
697 If the design is not to be completely Verilated see also the
699 --bbox-sys and --bbox-unsup options.
700 --max-num-width value
702 Set the maximum number literal width (e.g. in 1024'd22 this it the
703 1024). Defaults to 64K.
704 --MMD =item --no-MMD
706 Enable/disable creation of .d dependency files, used for make
707 dependency detection, similar to gcc -MMD option. By default this
708 option is enabled for --cc or --sp modes.
709 --MP
711 When creating .d dependency files with --MMD, make phony targets.
712 Similar to gcc -MP option.
713 --Mdir directory
715 Specifies the name of the Make object directory. All generated
716 files will be placed in this directory. If not specified,
717 "obj_dir" is used. The directory is created if it does not exist
718 and the parent directories exist; otherwise manually create the
719 Mdir before calling Verilator.
720 --mod-prefix topname
722 Specifies the name to prepend to all lower level classes. Defaults
723 to the same as --prefix.
724 --no-clk signal-name
726 Prevent the specified signal from being marked as clock. See
727 "--clk".
728 --no-decoration
730 When creating output Verilated code, minimize comments, whitespace,
731 symbol names and other decorative items, at the cost of greatly
732 reduced readability. This may assist C++ compile times. This will
733 not typically change the ultimate model's performance, but may in
734 some cases.
735 --no-pins64
737 Backward compatible alias for "--pins-bv 33".
738 --no-relative-cfuncs
740 Disable 'this->' references in generated functions, and instead
741 Verilator will generate absolute references starting from
742 'vlTOPp->'. This prevents V3Combine from merging functions from
743 multiple instances of the same module, so it can grow the
744 instruction stream.
745 This is a work around for old compilers. Don't set this if your C++
747 compiler supports __restrict__ properly, as GCC 4.5.x and newer do.
748 For older compilers, test if this switch gives you better
749 performance or not.
750 Compilers which don't honor __restrict__ will suspect that 'this->'
752 references and 'vlTOPp->' references may alias, and may write slow
753 code with extra loads and stores to handle the (imaginary)
754 aliasing. Using only 'vlTOPp->' references allows these old
755 compilers to produce tight code.
756 --no-skip-identical =item --skip-identical
758 Rarely needed. Disables or enables skipping execution of Verilator
759 if all source files are identical, and all output files exist with
760 newer dates. By default this option is enabled for --cc or --sp
761 modes only.
762 +notimingchecks
764 Ignored for compatibility with other simulators.
765 -O0 Disables optimization of the model.
767 -O3 Enables slow optimizations for the code Verilator itself generates
769 (as opposed to "-CFLAGS -O3" which effects the C compiler's
770 optimization. -O3 may reduce simulation runtimes at the cost of
771 compile time. This currently sets --inline-mult -1.
772 -Ooptimization-letter
774 Rarely needed. Enables or disables a specific optimizations, with
775 the optimization selected based on the letter passed. A lowercase
776 letter disables an optimization, an upper case letter enables it.
777 This is intended for debugging use only; see the source code for
778 version-dependent mappings of optimizations to -O letters.
779 -o executable
781 Specify the name for the final executable built if using --exe.
782 Defaults to the --prefix if not specified.
783 --no-order-clock-delay
785 Rarely needed. Disables a bug fix for ordering of clock enables
786 with delayed assignments. This flag should only be used when
787 suggested by the developers.
788 --output-split statements
790 Enables splitting the output .cpp files into multiple outputs.
791 When a C++ file exceeds the specified number of operations, a new
792 file will be created at the next function boundary. In addition,
793 any infrequently executed "cold" routines will be placed into
794 __Slow files. This accelerates compilation by as optimization can
795 be disabled on the routines in __Slow, and the remaining files can
796 be compiled on parallel machines. Using --output-split should have
797 only a trivial impact on performance. On one design --output-split
798 20000 resulted in splitting into approximately one-minute-compile
799 chunks.
800 Typically when using this, make with VM_PARALLEL_BUILDS=1 (set for
802 you if using the default makefiles), and use ccache.
803 --output-split-cfuncs statements
805 Enables splitting functions in the output .cpp files into multiple
806 functions. When a generated function exceeds the specified number
807 of operations, a new function will be created. With
808 --output-split, this will enable GCC to compile faster, at a small
809 loss in performance that gets worse with decreasing split values.
810 Note that this option is stronger than --output-split in the sense
811 that --output-split will not split inside a function.
812 --output-split-ctrace statements
814 Enables splitting trace functions in the output .cpp files into
815 multiple functions. Defaults to same setting as
816 --output-split-cfuncs.
817 -P With -E, disable generation of `line markers and blank lines,
819 similar to GCC -P flag.
820 --pins64
822 Backward compatible alias for "--pins-bv 65". Note that's a 65,
823 not a 64.
824 --pins-bv width
826 Specifies SystemC inputs/outputs of greater than or equal to width
827 bits wide should use sc_bv's instead of uint32/vluint64_t's. The
828 default is "--pins-bv 65", and the value must be less than or equal
829 to 65. Versions before Verilator 3.671 defaulted to "--pins-bv
830 33". The more sc_bv is used, the worse for performance. Use the
831 "/*verilator sc_bv*/" attribute to select specific ports to be
832 sc_bv.
833 --pins-sc-uint
835 Specifies SystemC inputs/outputs of greater than 2 bits wide should
836 use sc_uint between 2 and 64. When combined with the
837 "--pins-sc-biguint" combination, it results in sc_uint being used
838 between 2 and 64 and sc_biguint being used between 65 and 512.
839 --pins-sc-biguint
841 Specifies SystemC inputs/outputs of greater than 65 bits wide
842 should use sc_biguint between 65 and 512, and sc_bv from 513
843 upwards. When combined with the "--pins-sc-uint" combination, it
844 results in sc_uint being used between 2 and 64 and sc_biguint being
845 used between 65 and 512.
846 --pins-uint8
848 Specifies SystemC inputs/outputs that are smaller than the
849 --pins-bv setting and 8 bits or less should use uint8_t instead of
850 uint32_t. Likewise pins of width 9-16 will use uint16_t instead of
851 uint32_t.
852 --pipe-filter command
854 Rarely needed and experimental. Verilator will spawn the specified
855 command as a subprocess pipe, to allow the command to perform
856 custom edits on the Verilog code before it reaches Verilator.
857 Before reading each Verilog file, Verilator will pass the file name
859 to the subprocess' stdin with 'read_verilog "<filename>"'. The
860 filter may then read the file and perform any filtering it desires,
861 and feeds the new file contents back to Verilator on stdout with
862 'Content-Length'. Output to stderr from the filter feeds through
863 to Verilator's stdout and if the filter exits with non-zero status
864 Verilator terminates. See the t/t_pipe_filter test for an example.
865 To debug the output of the filter, try using the -E option to see
867 preprocessed output.
868 --pp-comments
870 With -E, show comments in preprocessor output.
871 --prefix topname
873 Specifies the name of the top level class and makefile. Defaults
874 to V prepended to the name of the --top-module switch, or V
875 prepended to the first Verilog filename passed on the command line.
876 --prof-cfuncs
878 Modify the created C++ functions to support profiling. The
879 functions will be minimized to contain one "basic" statement,
880 generally a single always block or wire statement. (Note this will
881 slow down the executable by ~5%.) Furthermore, the function name
882 will be suffixed with the basename of the Verilog module and line
883 number the statement came from. This allows gprof or oprofile
884 reports to be correlated with the original Verilog source
885 statements. See also verilator_profcfunc.
886 --prof-threads
888 Enable gantt chart data collection for threaded builds.
889 Verilator will record the start and end time of each macro-task
891 across a number of calls to eval. (What is a macro-task? See the
892 Verilator internals document.)
893 When profiling is enabled, the simulation runtime will emit a blurb
895 of profiling data in non-human-friendly form. The "verilator_gantt"
896 script will transform this into a nicer visual format and produce
897 some related statistics.
898 --protect-key key
900 Specifies the private key for --protect-ids. For best security this
901 key should be 16 or more random bytes, a reasonable secure choice
902 is the output of "verilator --generate-key". Typically, a key would
903 be created by the user once for a given protected design library,
904 then every Verilator run for subsequent versions of that library
905 would be passed the same --protect-key. Thus, if the input Verilog
906 is similar between library versions (Verilator runs), the Verilated
907 code will likewise be mostly similar.
908 If --protect-key is not specified and a key is needed, Verilator
910 will generate a new key for every Verilator run. As the key is not
911 saved, this is best for security, but means every Verilator run
912 will give vastly different output even for identical input, perhaps
913 harming compile times (and certainly thrashing any ccache).
914 --protect-ids
916 Hash any private identifiers (variable, module, and assertion block
917 names that are not on the top level) into hashed random-looking
918 identifiers, resulting after compilation in protected library
919 binaries that expose less design information. This hashing uses
920 the provided or default --protect-key, see important details there.
921 Verilator will also create a {prefix}__idmap.xml file which
923 contains the mapping from the hashed identifiers back to the
924 original identifiers. This idmap file is to be kept private, and is
925 to assist mapping any simulation runtime design assertions,
926 coverage, or trace information, which will report the hashed
927 identifiers, back to the original design's identifier names.
928 Using DPI imports/exports is allowed and generally relatively safe
930 in terms of information disclosed, which is limited to the DPI
931 function prototyptes. Use of the VPI is not recommended as many
932 design details may be exposed, and an INSECURE warning will be
933 issued.
934 --protect-lib name
936 Produces C++, Verilog wrappers and a Makefile which can in turn
937 produce a DPI library which can be used by Verilator or other
938 simulators along with the corresponding Verilog wrapper. The
939 Makefile will build both a static and dynamic version of the
940 library named libname.a and libname.so respectively. This is done
941 because some simulators require a dynamic library, but the static
942 library is arguably easier to use if possible. --protect-lib
943 implies --protect-ids.
944 This allows for the secure delivery of sensitive IP without the
946 need for encrypted RTL (i.e. IEEE P1735). See
947 examples/make_protect_lib in the distribution for a demonstration
948 of how to build and use the DPI library.
949 --private
951 Opposite of --public. Is the default; this option exists for
952 backwards compatibility.
953 --public
955 This is only for historical debug use. Using it may result in mis-
956 simulation of generated clocks.
957 Declares all signals and modules public. This will turn off signal
959 optimizations as if all signals had a /*verilator public*/ comments
960 and inlining. This will also turn off inlining as if all modules
961 had a /*verilator public_module*/, unless the module specifically
962 enabled it with /*verilator inline_module*/.
963 --public-flat-rw
965 Declares all variables, ports and wires public as if they had
966 /*verilator public_flat_rw*/ comments. This will make them VPI
967 accessible by their flat name, but not turn off module inlining.
968 This is particularly useful in combination with --vpi. This may
969 also in some rare cases result in mis-simulation of generated
970 clocks. Instead of this global switch, marking only those signals
971 that need public_flat_rw is typically significantly better
972 performing.
973 -pvalue+name=value
975 Overwrites the given parameter(s) of the toplevel module. See -G
976 for a detailed description.
977 --quiet-exit
979 When exiting due to an error, do not display the "Exiting due to
980 Errors" nor "Command Failed" messages.
981 --relative-includes
983 When a file references an include file, resolve the filename
984 relative to the path of the referencing file, instead of relative
985 to the current directory.
986 --report-unoptflat
988 Extra diagnostics for UNOPTFLAT warnings. This includes for each
989 loop, the 10 widest variables in the loop, and the 10 most fanned
990 out variables in the loop. These are candidates for splitting into
991 multiple variables to break the loop.
992 In addition produces a GraphViz DOT file of the entire strongly
994 connected components within the source associated with each loop.
995 This is produced irrespective of whether --dump-tree is set. Such
996 graphs may help in analyzing the problem, but can be very large
997 indeed.
998 Various commands exist for viewing and manipulating DOT files. For
1000 example the dot command can be used to convert a DOT file to a PDF
1001 for printing. For example:
1002 dot -Tpdf -O Vt_unoptflat_simple_2_35_unoptflat.dot
1004 will generate a PDF Vt_unoptflat_simple_2_35_unoptflat.dot.pdf from
1006 the DOT file.
1007 --rr
1009 Run Verilator and record with rr. See: rr-project.org.
1010 --savable
1012 Enable including save and restore functions in the generated model.
1013 The user code must create a VerilatedSerialize or
1015 VerilatedDeserialze object then calling the << or >> operators on
1016 the generated model and any other data the process needs
1017 saved/restored. These functions are not thread safe, and are
1018 typically called only by a main thread.
1019 For example:
1021 void save_model(const char* filenamep) {
1023 VerilatedSave os;
1024 os.open(filenamep);
1025 os << main_time; // user code must save the timestamp, etc
1026 os << *topp;
1027 }
1028 void restore_model(const char* filenamep) {
1029 VerilatedRestore os;
1030 os.open(filenamep);
1031 os >> main_time;
1032 os >> *topp;
1033 }
1034 --sc
1036 Specifies SystemC output mode; see also --cc.
1037 --stats
1039 Creates a dump file with statistics on the design in
1040 {prefix}__stats.txt.
1041 --stats-vars
1043 Creates more detailed statistics, including a list of all the
1044 variables by size (plain --stats just gives a count). See --stats,
1045 which is implied by this.
1046 --structs-packed
1048 Converts all unpacked structures to packed structures and issues a
1049 UNPACKED warning. Currently this is the default and
1050 --no-structs-packed will not work. Specifying this option allows
1051 for forward compatibility when a future version of Verilator no
1052 longer always packs unpacked structures.
1053 -sv Specifies SystemVerilog language features should be enabled;
1055 equivalent to "--language 1800-2005". This option is selected by
1056 default, it exists for compatibility with other simulators.
1057 +systemverilogext+ext
1059 A synonym for "+1800-2017ext+"ext.
1060 --threads threads
1062 --no-threads
1063 With --threads 0 or --no-threads, the default, the generated model
1064 is not thread safe. With --threads 1, the generated model is single
1065 threaded but may run in a multithreaded environment. With --threads
1066 N, where N >= 2, the model is generated to run multithreaded on up
1067 to N threads. See "MULTITHREADING".
1068 --threads-dpi all
1070 --threads-dpi none
1071 --threads-dpi pure
1072 When using --dpi with --threads, control what DPI tasks are thread
1073 safe.
1074 With --threads-dpi all, enable Verilator to assume all DPI imports
1076 are threadsafe, and to use thread-local storage for communication
1077 with DPI, potentially improving performance. Any DPI libraries need
1078 appropriate mutexes to avoid undefined behavior.
1079 With --threads-dpi none, Verilator assume DPI imports are not
1081 thread safe, and Verilator will serialize calls to DPI imports by
1082 default, potentially harming performance.
1083 With --threads-dpi pure, the default, Verilator assumes DPI pure
1085 imports are threadsafe, but non-pure DPI imports are not.
1086 --threads-max-mtasks value
1088 Rarely needed. When using --threads, specify the number of mtasks
1089 the model is to be partitioned into. If unspecified, Verilator
1090 approximates a good value.
1091 --top-module topname
1093 When the input Verilog contains more than one top level module,
1094 specifies the name of the top level Verilog module to become the
1095 top, and sets the default for if --prefix is not used. This is not
1096 needed with standard designs with only one top. See also the
1097 MULTITOP warning section.
1098 --trace
1100 Adds waveform tracing code to the model using VCD format. This
1101 overrides "--trace-fst".
1102 Verilator will generate additional {prefix}__Trace*.cpp files that
1104 will need to be compiled. In addition verilated_vcd_sc.cpp (for
1105 SystemC traces) or verilated_vcd_c.cpp (for both) must be compiled
1106 and linked in. If using the Verilator generated Makefiles, these
1107 files will be added as source targets for you. If you're not using
1108 the Verilator makefiles, you will need to add these to your
1109 Makefile manually.
1110 Having tracing compiled in may result in some small performance
1112 losses, even when waveforms are not turned on during model
1113 execution.
1114 --trace-coverage
1116 With --trace and --coverage-*, enable tracing to include a traced
1117 signal for every --coverage-line or --coverage-user inserted
1118 coverage point, to assist in debugging coverage items. Note
1119 --coverage-toggle does not get additional signals added, as the
1120 original signals being toggle-analyzed are already visible.
1121 The added signal will be a 32-bit value which will increment on
1123 each coverage occurrence. Due to this, this option may greatly
1124 increase trace file sizes and simulation runtime.
1125 --trace-depth levels
1127 Specify the number of levels deep to enable tracing, for example
1128 --trace-level 1 to only see the top level's signals. Defaults to
1129 the entire model. Using a small number will decrease visibility,
1130 but greatly improve simulation runtime and trace file size.
1131 --trace-fst
1133 Enable FST waveform tracing in the model. This overrides "--trace"
1134 and "--trace-fst-thread". See also "--trace-fst-thread".
1135 --trace-fst-thread
1137 Enable FST waveform tracing in the model, using a separate thread.
1138 This is typically faster in simulation runtime but slower in total
1139 computes than "--trace-fst". This overrides "--trace" and
1140 "--trace-fst".
1141 --trace-max-array depth
1143 Rarely needed. Specify the maximum array depth of a signal that
1144 may be traced. Defaults to 32, as tracing large arrays may greatly
1145 slow traced simulations.
1146 --trace-max-width width
1148 Rarely needed. Specify the maximum bit width of a signal that may
1149 be traced. Defaults to 256, as tracing large vectors may greatly
1150 slow traced simulations.
1151 --no-trace-params
1153 Disable tracing of parameters.
1154 --trace-structs
1156 Enable tracing to show the name of packed structure, union, and
1157 packed array fields, rather than a single combined packed bus. Due
1158 to VCD file format constraints this may result in significantly
1159 slower trace times and larger trace files.
1160 --trace-underscore
1162 Enable tracing of signals that start with an underscore. Normally,
1163 these signals are not output during tracing. See also
1164 --coverage-underscore.
1165 -Uvar
1167 Undefines the given preprocessor symbol.
1168 --unroll-count loops
1170 Rarely needed. Specifies the maximum number of loop iterations
1171 that may be unrolled. See also BLKLOOPINIT warning.
1172 --unroll-stmts statements
1174 Rarely needed. Specifies the maximum number of statements in a
1175 loop for that loop to be unrolled. See also BLKLOOPINIT warning.
1176 --unused-regexp regexp
1178 Rarely needed. Specifies a simple regexp with * and ? that if a
1179 signal name matches will suppress the UNUSED warning. Defaults to
1180 "*unused*". Setting it to "" disables matching.
1181 -V Shows the verbose version, including configuration information
1183 compiled into Verilator. (Similar to perl -V.) See also --getenv.
1184 -v filename
1186 Read the filename as a Verilog library. Any modules in the file
1187 may be used to resolve cell instantiations in the top level module,
1188 else ignored. Note -v is fairly standard across Verilog tools.
1189 +verilog1995ext+ext
1191 +verilog2001ext+ext
1192 Synonyms for "+1364-1995ext+"ext and "+1364-2001ext+"ext
1193 respectively
1194 --version
1196 Displays program version and exits.
1197 --vpi
1199 Enable use of VPI and linking against the verilated_vpi.cpp files.
1200 -Wall
1202 Enable all code style warnings, including code style warnings that
1203 are normally disabled by default. Equivelent to "-Wwarn-lint
1204 -Wwarn-style". Excludes some specialty warnings, i.e.
1205 IMPERFECTSCH.
1206 -Werror-message
1208 Convert the specified warning message into an error message. This
1209 is generally to discourage users from violating important site-wide
1210 rules, for example "-Werror-NOUNOPTFLAT".
1211 -Wfuture-message
1213 Rarely needed. Suppress unknown Verilator comments or warning
1214 messages with the given message code. This is used to allow code
1215 written with pragmas for a later version of Verilator to run under
1216 a older version; add -Wfuture- arguments for each message code or
1217 comment that the new version supports which the older version does
1218 not support.
1219 -Wno-message
1221 Disable the specified warning message, or in some cases where noted
1222 here disable an error. This will override any lint_on directives
1223 in the source, i.e. the warning will still not be printed.
1224 -Wno-context
1226 Disable showing the suspected context of the warning message by
1227 quoting the source text at the suspected location. This is used to
1228 appease tools which process the error messages may get confused by
1229 lines from the original source.
1230 -Wno-fatal
1232 When warnings are detected, print them, but do not exit the
1233 simulator.
1234 Having warning messages in builds is sloppy. It is strongly
1236 recommended you cleanup your code, use inline lint_off, or use
1237 -Wno-... flags rather than using this option.
1238 -Wno-lint
1240 Disable all lint related warning messages, and all style warnings.
1241 This is equivalent to "-Wno-ALWCOMBORDER -Wno-BSSPACE
1242 -Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASEWITHX
1243 -Wno-CMPCONST -Wno-COLONPLUS -Wno-ENDLABEL -Wno-IMPLICIT
1244 -Wno-LITENDIAN -Wno-PINCONNECTEMPTY -Wno-PINMISSING
1245 -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED
1246 -Wno-WIDTH" plus the list shown for Wno-style.
1247 It is strongly recommended you cleanup your code rather than using
1249 this option, it is only intended to be use when running test-cases
1250 of code received from third parties.
1251 -Wno-style
1253 Disable all code style related warning messages (note by default
1254 they are already disabled). This is equivalent to
1255 "-Wno-DECLFILENAME -Wno-DEFPARAM -Wno-IMPORTSTAR -Wno-INCABSPATH
1256 -Wno-PINCONNECTEMPTY -Wno-PINNOCONNECT -Wno-SYNCASYNCNET
1257 -Wno-UNDRIVEN -Wno-UNUSED -Wno-VARHIDDEN".
1258 -Wpedantic
1260 Warn on any construct demanded by IEEE, and disable all Verilator
1261 extensions that may interfere with IEEE compliance to the standard
1262 defined with --language (etc). Similar to GCC's -Wpedantic.
1263 Rarely used, and intended only for strict compliance tests.
1264 -Wwarn-message
1266 Enables the specified warning message.
1267 -Wwarn-lint
1269 Enable all lint related warning messages (note by default they are
1270 already enabled), but do not affect style messages. This is
1271 equivalent to "-Wwarn-ALWCOMBORDER -Wwarn-BSSPACE
1272 -Wwarn-CASEINCOMPLETE -Wwarn-CASEOVERLAP -Wwarn-CASEX
1273 -Wwarn-CASEWITHX -Wwarn-CMPCONST -Wwarn-COLONPLUS -Wwarn-ENDLABEL
1274 -Wwarn-IMPLICIT -Wwarn-LITENDIAN -Wwarn-PINMISSING -Wwarn-REALCVT
1275 -Wwarn-UNSIGNED -Wwarn-WIDTH".
1276 -Wwarn-style
1278 Enable all code style related warning messages. This is equivalent
1279 to "-Wwarn ASSIGNDLY -Wwarn-DECLFILENAME -Wwarn-DEFPARAM
1280 -Wwarn-INCABSPATH -Wwarn-PINNOCONNECT -Wwarn-SYNCASYNCNET
1281 -Wwarn-UNDRIVEN -Wwarn-UNUSED -Wwarn-VARHIDDEN".
1282 --x-assign 0
1284 --x-assign 1
1285 --x-assign fast (default)
1286 --x-assign unique
1287 Controls the two-state value that is replaced when an assignment to
1288 X is encountered. "--x-assign fast", the default, converts all Xs
1289 to whatever is best for performance. "--x-assign 0" converts all
1290 Xs to 0s, and is also fast. "--x-assign 1" converts all Xs to 1s,
1291 this is nearly as fast as 0, but more likely to find reset bugs as
1292 active high logic will fire. "--x-assign unique" will call a
1293 function to determine the value, this allows randomization of all
1294 Xs to find reset bugs and is the slowest, but safest for finding
1295 reset bugs in code.
1296 If using --x-assign unique, you may want to seed your random number
1298 generator such that each regression run gets a different
1299 randomization sequence. Use the system's srand48() or for Windows
1300 srand() function to do this. You'll probably also want to print
1301 any seeds selected, and code to enable rerunning with that same
1302 seed so you can reproduce bugs.
1303 Note. This option applies only to variables which are explicitly
1305 assigned to X in the Verilog source code. Initial values of clocks
1306 are set to 0 unless --x-initial-edge is specified. Initial values
1307 of all other state holding variables are controlled with
1308 --x-initial.
1309 --x-initial 0
1311 --x-initial fast
1312 --x-initial unique (default)
1313 Controls the two-state value that is used to initialize variables
1314 that are not otherwise initialized.
1315 "--x-initial 0", initializes all otherwise uninitialized variables
1317 to zero.
1318 "--x-initial unique", the default, initializes variables using a
1320 function, which determines the value to use each initialization.
1321 This gives greatest flexibility and allows finding reset bugs. See
1322 "Unknown states".
1323 "--x-initial fast", is best for performance, and initializes all
1325 variables to a state Verilator determines is optimal. This may
1326 allow further code optimizations, but will likely hide any code
1327 bugs relating to missing resets.
1328 Note. This option applies only to initial values of variables.
1330 Initial values of clocks are set to 0 unless --x-initial-edge is
1331 specified.
1332 --x-initial-edge
1334 Enables emulation of event driven simulators which generally
1335 trigger an edge on a transition from X to 1 ("posedge") or X to 0
1336 ("negedge"). Thus the following code, where "rst_n" is
1337 uninitialized would set "res_n" to "1'b1" when "rst_n" is first set
1338 to zero:
1339 reg res_n = 1'b0;
1341 always @(negedge rst_n) begin
1343 if (rst_n == 1'b0) begin
1344 res_n <= 1'b1;
1345 end
1346 end
1347 In Verilator, by default, uninitialized clocks are given a value of
1349 zero, so the above "always" block would not trigger.
1350 While it is not good practice, there are some designs that rely on
1352 X X 0 triggering a "negedge", particularly in reset sequences.
1353 Using --x-initial-edge with Verilator will replicate this behavior.
1354 It will also ensure that X X 1 triggers a "posedge".
1355 Note. Some users have reported that using this option can affect
1357 convergence, and that it may be necessary to use --converge-limit
1358 to increase the number of convergence iterations. This may be
1359 another indication of problems with the modeled design that should
1360 be addressed.
1361 --xml-only
1363 Create XML output only, do not create any other output.
1364 The XML format is intended to be used to leverage Verilator's
1366 parser and elaboration to feed to other downstream tools. Be aware
1367 that the XML format is still evolving; there will be some changes
1368 in future versions.
1369 --xml-output filename
1371 Filename for XML output file. Using this option automatically sets
1372 --xml-only.
1373 -y dir
1375 Add the directory to the list of directories that should be
1376 searched for include files or libraries. The three flags -y,
1377 +incdir and -I have similar effect; +incdir and +y are fairly
1378 standard across Verilog tools while -I is an alias for GCC
1379 compatibility.
1380 Verilator defaults to the current directory ("-y .") and any
1382 specified --Mdir, though these default paths are used after any
1383 user specified directories. This allows '-y "$(pwd)"' to be used
1384 if absolute filenames are desired for error messages instead of
1385 relative filenames.
1386
1388 The following are the arguments that may be passed to a Verilated
1389 executable, provided that executable calls Verilated::commandArgs().
1390 All simulation runtime arguments begin with +verilator, so that the
1392 user's executable may skip over all +verilator arguments when parsing
1393 its command line.
1394 +verilator+debug
1396 Enable simulation runtime debugging. Equivalent to
1397 +verilator+debugi+4.
1398 +verilator+debugi+value
1400 Enable simulation runtime debugging at the provided level.
1401 +verilator+error+limit+value
1403 Set number of non-fatal errors (e.g. assertion failures) before
1404 exiting simulation runtime. Also affects number of $stop calls
1405 needed before exit. Defaults to 1.
1406 +verilator+help
1408 Display help and exit.
1409 +verilator+prof+threads+file+filename
1411 When using --prof-threads at simulation runtime, the filename to
1412 dump to. Defaults to "profile_threads.dat".
1413 +verilator+prof+threads+start+value
1415 When using --prof-threads at simulation runtime, Verilator will
1416 wait until $time is at this value, then start the profiling warmup,
1417 then capturing. Generally this should be set to some time that is
1418 well within the normal operation of the simulation, i.e. outside of
1419 reset. If 0, the dump is disabled. Defaults to 1.
1420 +verilator+prof+threads+window+value
1422 When using --prof-threads at simulation runtime, after $time
1423 reaches +verilator+prof+threads+start, Verilator will warm up the
1424 profiling for this number of eval() calls, then will capture the
1425 profiling of this number of eval() calls. Defaults to 2, which
1426 makes sense for a single-clock-domain module where it's typical to
1427 want to capture one posedge eval() and one negedge eval().
1428 +verilator+rand+reset+value
1430 When a model was Verilated using "-x-initial unique", sets the
1431 simulation runtime initialization technique. 0 = Reset to zeros. 1
1432 = Reset to all-ones. 2 = Randomize. See "Unknown states".
1433 +verilator+seed+value
1435 For $random and "-x-initial unique", set the simulation runtime
1436 random seed value. If zero or not specified picks a value from the
1437 system random number generator.
1438 +verilator+noassert
1440 Disable assert checking per runtime argument. This is the same as
1441 calling "Verilated::assertOn(false)" in the model.
1442 +verilator+V
1444 Shows the verbose version, including configuration information.
1445 +verilator+version
1447 Displays program version and exits.
1448
1450 We'll compile this example into C++.
1451 mkdir test_our
1453 cd test_our
1454 cat >our.v <<'EOF'
1456 module our;
1457 initial begin $display("Hello World"); $finish; end
1458 endmodule
1459 EOF
1460 cat >sim_main.cpp <<'EOF'
1462 #include "Vour.h"
1463 #include "verilated.h"
1464 int main(int argc, char** argv, char** env) {
1465 Verilated::commandArgs(argc, argv);
1466 Vour* top = new Vour;
1467 while (!Verilated::gotFinish()) { top->eval(); }
1468 delete top;
1469 exit(0);
1470 }
1471 EOF
1472 See the README in the source kit for various ways to install or point
1474 to Verilator binaries. In brief, if you are running Verilator that
1475 came from your operating system (as an RPM), or did a "make install" to
1476 place Verilator into your default path, you do not need anything
1477 special in your environment, and should not have VERILATOR_ROOT set.
1478 However, if you installed Verilator from sources and want to run
1479 Verilator out of where you compiled Verilator, you need to point to the
1480 kit:
1481 # See above; don't do this if using an OS-distributed Verilator
1483 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1484 export PATH=$VERILATOR_ROOT/bin:$PATH
1485 Now we run Verilator on our little example.
1487 verilator -Wall --cc our.v --exe sim_main.cpp
1489 We can see the source code under the "obj_dir" directory. See the
1491 FILES section below for descriptions of some of the files that were
1492 created.
1493 ls -l obj_dir
1495 We then can compile it
1497 make -j -C obj_dir -f Vour.mk Vour
1499 (Verilator included a default compile rule and link rule, since we used
1501 --exe and passed a .cpp file on the Verilator command line. You can
1502 also write your own compile rules, as we'll show in the SYSTEMC
1503 section.)
1504 And now we run it
1506 obj_dir/Vour
1508 And we get as output
1510 Hello World
1512 - our.v:2: Verilog $finish
1513 Really, you're better off writing a Makefile to do all this for you.
1515 Then, when your source changes it will automatically run all of these
1516 steps; to aid this Verilator can create a makefile dependency file.
1517 See the examples directory in the distribution.
1518
1520 This is an example similar to the above, but using SystemC.
1521 mkdir test_our_sc
1523 cd test_our_sc
1524 cat >our.v <<'EOF'
1526 module our (clk);
1527 input clk; // Clock is required to get initial activation
1528 always @ (posedge clk)
1529 begin $display("Hello World"); $finish; end
1530 endmodule
1531 EOF
1532 cat >sc_main.cpp <<'EOF'
1534 #include "Vour.h"
1535 int sc_main(int argc, char** argv) {
1536 Verilated::commandArgs(argc, argv);
1537 sc_clock clk ("clk", 10, 0.5, 3, true);
1538 Vour* top;
1539 top = new Vour("top");
1540 top->clk(clk);
1541 while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
1542 delete top;
1543 exit(0);
1544 }
1545 EOF
1546 See the README in the source kit for various ways to install or point
1548 to Verilator binaries. In brief, if you are running Verilator that
1549 came from your operating system (as an RPM), or did a "make install" to
1550 place Verilator into your default path, you do not need anything
1551 special in your environment, and should not have VERILATOR_ROOT set.
1552 However, if you installed Verilator from sources and want to run
1553 Verilator out of where you compiled Verilator, you need to point to the
1554 kit:
1555 # See above; don't do this if using an OS-distributed Verilator
1557 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1558 export PATH=$VERILATOR_ROOT/bin:$PATH
1559 Now we run Verilator on our little example.
1561 verilator -Wall --sc our.v
1563 We then can compile it
1565 make -j -C obj_dir -f Vour.mk Vour__ALL.a
1567 make -j -C obj_dir -f Vour.mk ../sc_main.o verilated.o
1568 And link with SystemC. Note your path to the libraries may vary,
1570 depending on the operating system.
1571 cd obj_dir
1573 export SYSTEMC_LIBDIR=/path/to/where/libsystemc.a/exists
1574 export LD_LIBRARY_PATH=$SYSTEMC_LIBDIR:$LD_LIBRARY_PATH
1575 # Might be needed if SystemC 2.3.0
1576 export SYSTEMC_CXX_FLAGS=-pthread
1577 g++ -L$SYSTEMC_LIBDIR ../sc_main.o Vour__ALL*.o verilated.o \
1579 -o Vour -lsystemc
1580 And now we run it
1582 cd ..
1584 obj_dir/Vour
1585 And we get the same output as the C++ example:
1587 Hello World
1589 - our.v:2: Verilog $finish
1590 Really, you're better off using a Makefile to do all this for you.
1592 Then, when your source changes it will automatically run all of these
1593 steps. See the examples directory in the distribution.
1594
1596 When using SystemC, when Verilator is evaluated is managed by the
1597 SystemC kernel, and for the most part can be ignored. When using C++,
1598 the user must call eval(), or eval_step() and eval_end_step().
1599 1. When there is a single design instantiated at the C++ level that
1601 need to evaluate, just call designp->eval().
1602 2. When there are multiple designs instantiated each at the C++ level
1604 that need to evaluate, call first_designp->eval_step() then
1605 ->eval_step() on all other designs. Then call ->eval_end_step() on the
1606 first design then all other designs. If there is only a single design,
1607 you would call eval_step() then eval_end_step(); in fact eval()
1608 described above is just a wrapper which calls these two functions.
1609 When eval() is called Verilator looks for changes in clock signals and
1611 evaluates related sequential always blocks, such as computing always_ff
1612 @ (posedge...) outputs. Then Verilator evaluates combinatorial logic.
1613 Note combinatorial logic is not computed before sequential always
1615 blocks are computed (for speed reasons). Therefore it is best to set
1616 any non-clock inputs up with a separate eval() call before changing
1617 clocks().
1618 Alternatively, if all always_ff statements use only the posedge of
1620 clocks, or all inputs go directly to always_ff statements, as is
1621 typical, then you can change non-clock inputs on the negative edge of
1622 the input clock, which will be faster as there will be fewer eval()
1623 calls.
1624 For more information on evaluation, see docs/internals.adoc in the
1626 distribution.
1627
1629 For best performance, run Verilator with the "-O3 --x-assign fast
1630 --x-initial fast --noassert" flags. The -O3 flag will require longer
1631 compile times, and "--x-assign fast --x-initial fast" may increase the
1632 risk of reset bugs in trade for performance; see the above
1633 documentation for these flags.
1634 If using Verilated multithreaded, use "numactl" to ensure you are using
1636 non-conflicting hardware resources. See "MULTITHREADING".
1637 Minor Verilog code changes can also give big wins. You should not have
1639 any UNOPTFLAT warnings from Verilator. Fixing these warnings can
1640 result in huge improvements; one user fixed their one UNOPTFLAT warning
1641 by making a simple change to a clock latch used to gate clocks and
1642 gained a 60% performance improvement.
1643 Beyond that, the performance of a Verilated model depends mostly on
1645 your C++ compiler and size of your CPU's caches.
1646 By default, the lib/verilated.mk file has optimization turned off.
1648 This is for the benefit of new users, as it improves compile times at
1649 the cost of simulation runtimes. To add optimization as the default,
1650 set one of three variables, OPT, OPT_FAST, or OPT_SLOW
1651 lib/verilated.mk. Or, use the -CFLAGS and/or -LDFLAGS option on the
1652 verilator command line to pass the flags directly to the compiler or
1653 linker. Or, just for one run, pass them on the command line to make:
1654 make OPT_FAST="-Os -fno-stack-protector" -f Vour.mk Vour__ALL.a
1656 OPT_FAST specifies optimizations for those programs that are part of
1658 the fast path, mostly code that is executed every cycle. OPT_SLOW
1659 specifies optimizations for slow-path files (plus tracing), which
1660 execute only rarely, yet take a long time to compile with optimization
1661 on. OPT specifies overall optimization and affects all compiles,
1662 including those OPT_FAST and OPT_SLOW control. For best results, use
1663 OPT="-Os", and link with "-static". Nearly the same results can be had
1664 with much better compile times with OPT_FAST="-O1 -fstrict-aliasing".
1665 Higher optimization such as "-O2" or "-O3" may help, but gcc compile
1666 times may be excessive under O3 on even medium sized designs.
1667 Unfortunately, using the optimizer with SystemC files can result in
1669 compiles taking several minutes. (The SystemC libraries have many
1670 little inlined functions that drive the compiler nuts.)
1671 For best results, use the latest clang compiler (about 10% faster than
1673 GCC). Note the now fairly old GCC 3.2 and earlier have optimization
1674 bugs around pointer aliasing detection, which can result in 2x
1675 performance losses.
1676 If you will be running many simulations on a single compile,
1678 investigate feedback driven compilation. With GCC, using
1679 -fprofile-arcs, then -fbranch-probabilities will yield another 15% or
1680 so.
1681 Modern compilers also support link-time optimization (LTO), which can
1683 help especially if you link in DPI code. To enable LTO on GCC, pass
1684 "-flto" in both compilation and link. Note LTO may cause excessive
1685 compile times on large designs.
1686 Using profile driven compiler optimization, with feedback from a real
1688 design, can yield up to30% improvements.
1689 If you are using your own makefiles, you may want to compile the
1691 Verilated code with -DVL_INLINE_OPT=inline. This will inline functions,
1692 however this requires that all cpp files be compiled in a single
1693 compiler run.
1694 You may uncover further tuning possibilities by profiling the Verilog
1696 code. Use Verilator's --prof-cfuncs, then GCC's -g -pg. You can then
1697 run either oprofile or gprof to see where in the C++ code the time is
1698 spent. Run the gprof output through verilator_profcfunc and it will
1699 tell you what Verilog line numbers on which most of the time is being
1700 spent.
1701 When done, please let the author know the results. We like to keep
1703 tabs on how Verilator compares, and may be able to suggest additional
1704 improvements.
1705
1707 All output files are placed in the output directory name specified with
1708 the -Mdir option, or "obj_dir" if not specified.
1709 Verilator creates the following files in the output directory:
1711 For --make gmake, it creates:
1713 {prefix}.mk // Make include file for compiling
1715 {prefix}_classes.mk // Make include file with class names
1716 For --make cmake, it creates:
1718 {prefix}.cmake // CMake include script for compiling
1720 For -cc and -sc mode, it also creates:
1722 {prefix}.cpp // Top level C++ file
1724 {prefix}.h // Top level header
1725 {prefix}__Slow{__n}.cpp // Constructors and infrequent cold routines
1726 {prefix}{__n}.cpp // Additional top C++ files (--output-split)
1727 {prefix}{each_verilog_module}.cpp // Lower level internal C++ files
1728 {prefix}{each_verilog_module}.h // Lower level internal header files
1729 {prefix}{each_verilog_module}{__n}.cpp // Additional lower C++ files (--output-split)
1730 In certain debug and other modes, it also creates:
1732 {prefix}.xml // XML tree information (--xml)
1734 {prefix}__Dpi.cpp // DPI import and export wrappers
1735 {prefix}__Dpi.h // DPI import and export declarations
1736 {prefix}__Inlines.h // Inline support functions
1737 {prefix}__Syms.cpp // Global symbol table C++
1738 {prefix}__Syms.h // Global symbol table header
1739 {prefix}__Trace__Slow{__n}.cpp // Wave file generation code (--trace)
1740 {prefix}__Trace{__n}.cpp // Wave file generation code (--trace)
1741 {prefix}__cdc.txt // Clock Domain Crossing checks (--cdc)
1742 {prefix}__stats.txt // Statistics (--stats)
1743 {prefix}__idmap.txt // Symbol demangling (--protect-ids)
1744 It also creates internal files that can be mostly ignored:
1746 {mod_prefix}_{each_verilog_module}{__n}.vpp // Post-processed verilog
1748 {prefix}__ver.d // Make dependencies (-MMD)
1749 {prefix}__verFiles.dat // Timestamps for skip-identical
1750 {prefix}{misc}.dot // Debugging graph files (--debug)
1751 {prefix}{misc}.tree // Debugging files (--debug)
1752 After running Make, the C++ compiler may produce the following:
1754 verilated{misc}.d // Intermediate dependencies
1756 verilated{misc}.o // Intermediate objects
1757 {mod_prefix}{misc}.d // Intermediate dependencies
1758 {mod_prefix}{misc}.o // Intermediate objects
1759 {prefix} // Final executable (w/--exe argument)
1760 {prefix}__ALL.a // Library of all Verilated objects
1761 {prefix}__ALLboth.cpp // Include of classes for single compile
1762 {prefix}__ALLcls.cpp // Include of user classes for single compile
1763 {prefix}__ALLsup.cpp // Include of support files for single compile
1764 {prefix}{misc}.d // Intermediate dependencies
1765 {prefix}{misc}.o // Intermediate objects
1766
1768 LD_LIBRARY_PATH
1769 A generic Linux/OS variable specifying what directories have shared
1770 object (.so) files. This path should include SystemC and any other
1771 shared objects needed at simulation runtime.
1772 OBJCACHE
1774 Optionally specifies a caching or distribution program to place in
1775 front of all runs of the C++ Compiler. For example, "objcache
1776 --read --write", or "ccache". If using distcc or icecc/icecream,
1777 they would generally be run under either objcache or ccache; see
1778 the documentation for those programs.
1779 SYSTEMC
1781 Deprecated. Used only if SYSTEMC_INCLUDE or SYSTEMC_LIBDIR is not
1782 set. If set, specifies the directory containing the SystemC
1783 distribution. If not specified, it will come from a default
1784 optionally specified at configure time (before Verilator was
1785 compiled).
1786 SYSTEMC_ARCH
1788 Deprecated. Used only if SYSTEMC_LIBDIR is not set. Specifies the
1789 architecture name used by the SystemC kit. This is the part after
1790 the dash in the lib-{...} directory name created by a 'make' in the
1791 SystemC distribution. If not set, Verilator will try to intuit the
1792 proper setting, or use the default optionally specified at
1793 configure time (before Verilator was compiled).
1794 SYSTEMC_CXX_FLAGS
1796 Specifies additional flags that are required to be passed to GCC
1797 when building the SystemC model. System 2.3.0 may need this set to
1798 "-pthread".
1799 SYSTEMC_INCLUDE
1801 If set, specifies the directory containing the systemc.h header
1802 file. If not specified, it will come from a default optionally
1803 specified at configure time (before Verilator was compiled), or
1804 computed from SYSTEMC/include.
1805 SYSTEMC_LIBDIR
1807 If set, specifies the directory containing the libsystemc.a
1808 library. If not specified, it will come from a default optionally
1809 specified at configure time (before Verilator was compiled), or
1810 computed from SYSTEMC/lib-SYSTEMC_ARCH.
1811 VERILATOR_BIN
1813 If set, specifies an alternative name of the "verilator" binary.
1814 May be used for debugging and selecting between multiple operating
1815 system builds.
1816 VERILATOR_COVERAGE_BIN
1818 If set, specifies an alternative name of the "verilator_coverage
1819 binary". May be used for debugging and selecting between multiple
1820 operating system builds.
1821 VERILATOR_GDB
1823 If set, the command to run when using the --gdb option, such as
1824 "ddd". If not specified, it will use "gdb".
1825 VERILATOR_ROOT
1827 Specifies the directory containing the distribution kit. This is
1828 used to find the executable, Perl library, and include files. If
1829 not specified, it will come from a default optionally specified at
1830 configure time (before Verilator was compiled). It should not be
1831 specified if using a pre-compiled Verilator RPM as the hardcoded
1832 value should be correct.
1833
1835 Verilator creates a .h and .cpp file for the top level module and all
1836 modules under it. See the examples directory in the kit for examples.
1837 After the modules are completed, there will be a module.mk file that
1839 may be used with Make to produce a module__ALL.a file with all required
1840 objects in it. This is then linked with the user's top level to create
1841 the simulation executable.
1842 The user must write the top level of the simulation. Here's a simple
1844 example:
1845 #include <verilated.h> // Defines common routines
1847 #include <iostream> // Need std::cout
1848 #include "Vtop.h" // From Verilating "top.v"
1849 Vtop *top; // Instantiation of module
1851 vluint64_t main_time = 0; // Current simulation time
1853 // This is a 64-bit integer to reduce wrap over issues and
1854 // allow modulus. You can also use a double, if you wish.
1855 double sc_time_stamp () { // Called by $time in Verilog
1857 return main_time; // converts to double, to match
1858 // what SystemC does
1859 }
1860 int main(int argc, char** argv) {
1862 Verilated::commandArgs(argc, argv); // Remember args
1863 top = new Vtop; // Create instance
1865 top->reset_l = 0; // Set some inputs
1867 while (!Verilated::gotFinish()) {
1869 if (main_time > 10) {
1870 top->reset_l = 1; // Deassert reset
1871 }
1872 if ((main_time % 10) == 1) {
1873 top->clk = 1; // Toggle clock
1874 }
1875 if ((main_time % 10) == 6) {
1876 top->clk = 0;
1877 }
1878 top->eval(); // Evaluate model
1879 cout << top->out << endl; // Read a output
1880 main_time++; // Time passes...
1881 }
1882 top->final(); // Done simulating
1884 // // (Though this example doesn't get here)
1885 delete top;
1886 }
1887 Note signals are read and written as member variables of the lower
1889 module. You call the eval() method to evaluate the model. When the
1890 simulation is complete call the final() method to wrap up any
1891 SystemVerilog final blocks, and complete any assertions. See
1892 "EVALUATION LOOP".
1893
1895 Verilator will convert the top level module to a SC_MODULE. This
1896 module will plug directly into a SystemC netlist.
1897 The SC_MODULE gets the same pinout as the Verilog module, with the
1899 following type conversions: Pins of a single bit become bool. Pins
1900 2-32 bits wide become uint32_t's. Pins 33-64 bits wide become sc_bv's
1901 or vluint64_t's depending on the --no-pins64 switch. Wider pins become
1902 sc_bv's. (Uints simulate the fastest so are used where possible.)
1903 Lower modules are not pure SystemC code. This is a feature, as using
1905 the SystemC pin interconnect scheme everywhere would reduce performance
1906 by an order of magnitude.
1907
1909 Verilator supports SystemVerilog Direct Programming Interface import
1910 and export statements. Only the SystemVerilog form ("DPI-C") is
1911 supported, not the original Synopsys-only DPI.
1912 DPI Example
1914 In the SYSTEMC example above, if you wanted to import C++ functions
1915 into Verilog, put in our.v:
1916 import "DPI-C" function integer add (input integer a, input integer b);
1918 initial begin
1920 $display("%x + %x = %x", 1, 2, add(1,2));
1921 endtask
1922 Then after Verilating, Verilator will create a file Vour__Dpi.h with
1924 the prototype to call this function:
1925 extern int add (int a, int b);
1927 From the sc_main.cpp file (or another .cpp file passed to the Verilator
1929 command line, or the link), you'd then:
1930 #include "svdpi.h"
1932 #include "Vour__Dpi.h"
1933 int add(int a, int b) { return a+b; }
1934 DPI System Task/Functions
1936 Verilator extends the DPI format to allow using the same scheme to
1937 efficiently add system functions. Simply use a dollar-sign prefixed
1938 system function name for the import, but note it must be escaped.
1939 export "DPI-C" function integer \$myRand;
1941 initial $display("myRand=%d", $myRand());
1943 Going the other direction, you can export Verilog tasks so they can be
1945 called from C++:
1946 export "DPI-C" task publicSetBool;
1948 task publicSetBool;
1950 input bit in_bool;
1951 var_bool = in_bool;
1952 endtask
1953 Then after Verilating, Verilator will create a file Vour__Dpi.h with
1955 the prototype to call this function:
1956 extern bool publicSetBool(bool in_bool);
1958 From the sc_main.cpp file, you'd then:
1960 #include "Vour__Dpi.h"
1962 publicSetBool(value);
1963 Or, alternatively, call the function under the design class. This
1965 isn't DPI compatible but is easier to read and better supports multiple
1966 designs.
1967 #include "Vour__Dpi.h"
1969 Vour::publicSetBool(value);
1970 // or top->publicSetBool(value);
1971 Note that if the DPI task or function accesses any register or net
1973 within the RTL, it will require a scope to be set. This can be done
1974 using the standard functions within svdpi.h, after the module is
1975 instantiated, but before the task(s) and/or function(s) are called.
1976 For example, if the top level module is instantiated with the name
1978 "dut" and the name references within tasks are all hierarchical
1979 (dotted) names with respect to that top level module, then the scope
1980 could be set with
1981 #include "svdpi.h"
1983 ...
1984 svSetScope(svGetScopeFromName("dut"));
1985 (Remember that Verilator adds a "V" to the top of the module
1987 hierarchy.)
1988 Scope can also be set from within a DPI imported C function that has
1990 been called from Verilog by querying the scope of that function. See
1991 the sections on DPI Context Functions and DPI Header Isolation below
1992 and the comments within the svdpi.h header for more information.
1993 DPI Display Functions
1995 Verilator allows writing $display like functions using this syntax:
1996 import "DPI-C" function void
1998 \$my_display(input string formatted /*verilator sformat*/ );
1999 The /*verilator sformat*/ indicates that this function accepts a
2001 $display like format specifier followed by any number of arguments to
2002 satisfy the format.
2003 DPI Context Functions
2005 Verilator supports IEEE DPI Context Functions. Context imports pass
2006 the simulator context, including calling scope name, and filename and
2007 line number to the C code. For example, in Verilog:
2008 import "DPI-C" context function int dpic_line();
2010 initial $display("This is line %d, again, line %d\n", `line, dpic_line());
2011 This will call C++ code which may then use the svGet* functions to read
2013 information, in this case the line number of the Verilog statement that
2014 invoked the dpic_line function:
2015 int dpic_line() {
2017 // Get a scope: svScope scope = svGetScope();
2018 const char* scopenamep = svGetNameFromScope(scope);
2020 assert(scopenamep);
2021 const char* filenamep = "";
2023 int lineno = 0;
2024 if (svGetCallerInfo(&filenamep, &lineno)) {
2025 printf("dpic_line called from scope %s on line %d\n",
2026 scopenamep, lineno);
2027 return lineno;
2028 } else {
2029 return 0;
2030 }
2031 }
2032 See the IEEE Standard for more information.
2034 DPI Header Isolation
2036 Verilator places the IEEE standard header files such as svdpi.h into a
2037 separate include directory, vltstd (VeriLaTor STandarD). When
2038 compiling most applications $VERILATOR_ROOT/include/vltstd would be in
2039 the include path along with the normal $VERILATOR_ROOT/include.
2040 However, when compiling Verilated models into other simulators which
2041 have their own svdpi.h and similar standard files with different
2042 contents, the vltstd directory should not be included to prevent
2043 picking up incompatible definitions.
2044 Public Functions
2046 Instead of DPI exporting, there's also Verilator public functions,
2047 which are slightly faster, but less compatible.
2048
2050 Verilator supports a very limited subset of the VPI. This subset
2051 allows inspection, examination, value change callbacks, and depositing
2052 of values to public signals only.
2053 VPI is enabled with the verilator --vpi switch.
2055 To access signals via the VPI, Verilator must be told exactly which
2057 signals are to be accessed. This is done using the Verilator public
2058 pragmas documented below.
2059 Verilator has an important difference from an event based simulator;
2061 signal values that are changed by the VPI will not immediately
2062 propagate their values, instead the top level header file's eval()
2063 method must be called. Normally this would be part of the normal
2064 evaluation (i.e. the next clock edge), not as part of the value change.
2065 This makes the performance of VPI routines extremely fast compared to
2066 event based simulators, but can confuse some test-benches that expect
2067 immediate propagation.
2068 Note the VPI by its specified implementation will always be much slower
2070 than accessing the Verilator values by direct reference
2071 (structure->module->signame), as the VPI accessors perform lookup in
2072 functions at simulation runtime requiring at best hundreds of
2073 instructions, while the direct references are evaluated by the compiler
2074 and result in only a couple of instructions.
2075 For signal callbacks to work the main loop of the program must call
2077 VerilatedVpi::callValueCbs().
2078 VPI Example
2080 In the below example, we have readme marked read-only, and writeme
2081 which if written from outside the model will have the same semantics as
2082 if it changed on the specified clock edge.
2083 cat >our.v <<'EOF'
2085 module our (input clk);
2086 reg readme /*verilator public_flat_rd*/;
2087 reg writeme /*verilator public_flat_rw @(posedge clk) */;
2088 initial $finish;
2089 endmodule
2090 EOF
2091 There are many online tutorials and books on the VPI, but an example
2093 that accesses the above signal "readme" would be:
2094 cat >sim_main.cpp <<'<<EOF'
2096 #include "Vour.h"
2097 #include "verilated.h"
2098 #include "verilated_vpi.h" // Required to get definitions
2099 vluint64_t main_time = 0; // See comments in first example
2101 double sc_time_stamp() { return main_time; }
2102 void read_and_check() {
2104 vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
2105 if (!vh1) { vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found"); }
2106 const char* name = vpi_get_str(vpiName, vh1);
2107 printf("Module name: %s\n", name); // Prints "readme"
2108 s_vpi_value v;
2110 v.format = vpiIntVal;
2111 vpi_get_value(vh1, &v);
2112 printf("Value of v: %d\n", v.value.integer); // Prints "readme"
2113 }
2114 int main(int argc, char** argv, char** env) {
2116 Verilated::commandArgs(argc, argv);
2117 Vour* top = new Vour;
2118 Verilated::internalsDump(); // See scopes to help debug
2119 while (!Verilated::gotFinish()) {
2120 top->eval();
2121 VerilatedVpi::callValueCbs(); // For signal callbacks
2122 read_and_check();
2123 }
2124 delete top;
2125 exit(0);
2126 }
2127 EOF
2128
2130 Verilator supports cross-compiling Verilated code. This is generally
2131 used to run Verilator on a Linux system and produce C++ code that is
2132 then compiled on Windows.
2133 Cross compilation involves up to three different OSes. The build
2135 system is where you configured and compiled Verilator, the host system
2136 where you run Verilator, and the target system where you compile the
2137 Verilated code and run the simulation.
2138 Currently, Verilator requires the build and host system type to be the
2140 same, though the target system type may be different. To support this,
2141 ./configure and make Verilator on the build system. Then, run
2142 Verilator on the host system. Finally, the output of Verilator may be
2143 compiled on the different target system.
2144 To support this, none of the files that Verilator produces will
2146 reference any configure generated build-system specific files, such as
2147 config.h (which is renamed in Verilator to config_build.h to reduce
2148 confusion.) The disadvantage of this approach is that
2149 include/verilatedos.h must self-detect the requirements of the target
2150 system, rather than using configure.
2151 The target system may also require edits to the Makefiles, the simple
2153 Makefiles produced by Verilator presume the target system is the same
2154 type as the build system.
2155 CMake
2157 Verilator can be run using CMake, which takes care of both running
2158 Verilator and compiling the output. There is a CMake example in the
2159 examples/ directory. The following is a minimal CMakeLists.txt that
2160 would build the code listed in "EXAMPLE C++ EXECUTION":
2161 project(cmake_example)
2163 find_package(verilator HINTS $ENV{VERILATOR_ROOT})
2164 add_executable(Vour sim_main.cpp)
2165 verilate(Vour SOURCES our.v)
2166 find_package will automatically find an installed copy of Verilator, or
2168 use a local build if VERILATOR_ROOT is set.
2169 It is recommended to use CMake >= 3.12 and the Ninja generator, though
2171 other combinations should work. To build with CMake, change to the
2172 folder containing CMakeLists.txt and run:
2173 mkdir build
2175 cd build
2176 cmake -GNinja ..
2177 ninja
2178 Or to build with your system default generator:
2180 mkdir build
2182 cd build
2183 cmake ..
2184 cmake --build .
2185 If you're building the example you should have an executable to run:
2187 ./Vour
2189 The package sets the CMake variables verilator_FOUND, VERILATOR_ROOT
2191 and VERILATOR_BIN to the appropriate values, and also creates a
2192 verilate() function. verilate() will automatically create custom
2193 commands to run Verilator and add the generated C++ sources to the
2194 target specified.
2195 verilate(target SOURCES source ... [TOP_MODULE top] [PREFIX name]
2197 [TRACE] [TRACE_FST] [SYSTEMC] [COVERAGE]
2198 [INCLUDE_DIRS dir ...] [OPT_SLOW ...] [OPT_FAST ...]
2199 [DIRECTORY dir] [VERILATOR_ARGS ...])
2200 Lowercase and ... should be replaced with arguments, the uppercase
2202 parts delimit the arguments and can be passed in any order, or left out
2203 entirely if optional.
2204 verilate(target ...) can be called multiple times to add other verilog
2206 modules to an executable or library target.
2207 When generating Verilated SystemC sources, you should also include the
2209 SystemC include directories and link to the SystemC libraries.
2210 Verilator's CMake support provides a convenience function to
2212 automatically find and link to the SystemC library. It can be used as:
2213 verilator_link_systemc(target)
2215 where target is the name of your target.
2217 The search paths can be configured by setting some variables:
2219 - The variables SYSTEMC_INCLUDE and SYSTEMC_LIBDIR to give a direct
2221 path to the SystemC include an library path.
2222 - SYSTEMC_ROOT to set the installation prefix of an installed SystemC
2224 library.
2225 - SYSTEMC to set the installation prefix of an installed SystemC
2227 library
2228 (same as above).
2229 - When using Accellera's SystemC with CMake support, a CMake target is
2231 available that will easen above steps. This will only work if the
2232 SystemC installation can be found by CMake. This can be configured by
2233 setting the CMAKE_PREFIX_PATH variable during CMake configuration.
2234 Don't forget to set the same C++ standard for the Verilated sources as
2236 the SystemC library. This can be specified using the SYSTEMC_CXX_FLAGS
2237 environment variable.
2238 target
2240 Name of a target created by add_executable or add_library.
2241 SOURCES
2243 List of verilog files to Verilate. Must have at least one file.
2244 PREFIX
2246 Optional. Sets the Verilator output prefix. Defaults to the name of
2247 the first hdl source with a "V" prepended. Must be unique in each
2248 call to verilate(), so this is necessary if you build a module
2249 multiple times with different parameters. Must be a valid C++
2250 identifier, i.e. contains no whitespace and only characters A-Z,
2251 a-z, 0-9 or _.
2252 TOP_MODULE
2254 Optional. Sets the name of the top module. Defaults to the name of
2255 the first file in the SOURCES array.
2256 TRACE
2258 Optional. Enables VCD tracing if present, equivalent to
2259 "VERILATOR_ARGS --trace".
2260 TRACE_FST
2262 Optional. Enables FST tracing if present, equivalent to
2263 "VERILATOR_ARGS --trace-fst".
2264 SYSTEMC
2266 Optional. Enables SystemC mode, defaults to C++ if not specified.
2267 COVERAGE
2269 Optional. Enables coverage if present, equivalent to
2270 "VERILATOR_ARGS --coverage"
2271 INCLUDE_DIRS
2273 Optional. Sets directories that Verilator searches (same as -y).
2274 OPT_SLOW
2276 Optional. Set compiler flags for the slow path. You may want to
2277 reduce the optimization level to improve compile times with large
2278 designs.
2279 OPT_FAST
2281 Optional. Set compiler flags for the fast path.
2282 DIRECTORY
2284 Optional. Set the verilator output directory. It is preferable to
2285 use the default, which will avoid collisions with other files.
2286 VERILATOR_ARGS
2288 Optional. Extra arguments to Verilator. Do not specify --Mdir or
2289 --prefix here, use DIRECTORY or PREFIX.
2290 Cadence NC-SystemC Models
2292 Similar to compiling Verilated designs with gcc, Verilated designs may
2293 be compiled inside other simulators that support C++ or SystemC models.
2294 One such simulator is Cadence's NC-SystemC, part of their Incisive
2295 Verification Suite. (Highly recommended.)
2296 Using the example files above, the following command will build the
2298 model underneath NC:
2299 cd obj_dir
2301 ncsc_run \
2302 sc_main.cpp \
2303 Vour__ALLcls.cpp \
2304 Vour__ALLsup.cpp \
2305 verilated.cpp
2306 For larger designs you'll want to automate this using makefiles, which
2308 pull the names of the .cpp files to compile in from the make variables
2309 generated in obj_dir/Vour_classes.mk.
2310
2312 Verilator experimentally supports multithreading.
2313 With --no-threads, the default, the model is not thread safe, and any
2315 use of more than one thread calling into one or even different
2316 Verilated models may result in unpredictable behavior. This gives the
2317 highest single thread performance.
2318 With --threads 1, the generated model is single threaded, however the
2320 support libraries are multithread safe. This allows different
2321 instantiations of model(s) to potentially each be run under a different
2322 thread. All threading is the responsibility of the user's C++
2323 testbench.
2324 With --threads N, where N is at least 2, the generated model will be
2326 designed to run in parallel on N threads. The thread calling eval()
2327 provides one of those threads, and the generated model will create and
2328 manage the other N-1 threads. It's the client's responsibility not to
2329 oversubscribe the available CPU cores. Under CPU oversubscription, the
2330 Verilated model should not livelock nor deadlock, however, you can
2331 expect performance to be far worse than it would be with proper ratio
2332 of threads and CPU cores.
2333 With --trace-fst-thread, tracing occurs in a separate thread from the
2335 main simulation thread(s). This option is orthogonal to --threads.
2336 The remainder of this section describe behavior with --threads 1 or
2338 --threads N (not --no-threads).
2339 VL_THREADED is defined when compiling a threaded Verilated module,
2341 causing the Verilated support classes become threadsafe.
2342 The thread used for constructing a model must be the same thread that
2344 calls eval() into the model, this is called the "eval thread". The
2345 thread used to perform certain global operations such as saving and
2346 tracing must be done by a "main thread". In most cases the eval thread
2347 and main thread are the same thread (i.e. the user's top C++ testbench
2348 runs on a single thread), but this is not required.
2349 When running a multithreaded model, the default Linux task scheduler
2351 often works against the model, by assuming threads are short lived, and
2352 thus often schedules threads using multiple hyperthreads within the
2353 same physical core. For best performance use the "numactl" program to
2354 (when the threading count fits) select unique physical cores on the
2355 same socket. For example, if a model was Verilated with "--threads 4",
2356 we consult
2357 egrep 'processor|physical id|core id' /proc/cpuinfo
2359 To select cores 0, 1, 2, and 3 that are all located on the same socket
2361 (0) but different physical cores. (Also useful is "numactl
2362 --hardware", or "lscpu" but those doesn't show Hyperthreading cores.)
2363 Then we execute
2364 numactl -m 0 -C 0,1,2,3 -- verilated_executable_name
2366 This will limit memory to socket 0, and threads to cores 0, 1, 2, 3,
2368 (presumably on socket 0) optimizing performance. Of course this must
2369 be adjusted if you want another simulator using e.g. socket 1, or if
2370 you Verilated with a different number of threads. To see what CPUs are
2371 actually used, use --prof-threads.
2372 Multithreaded Verilog and Library Support
2374 $display/$stop/$finish are delayed until the end of an eval() call in
2375 order to maintain ordering between threads. This may result in
2376 additional tasks completing after the $stop or $finish.
2377 If using --coverage, the coverage routines are fully thread safe.
2379 If using --dpi, Verilator assumes pure DPI imports are thread safe,
2381 balancing performance versus safety. See --threads-dpi.
2382 If using --savable, the save/restore classes are not multithreaded
2384 and are must be called only by the eval thread.
2385 If using --sc, the SystemC kernel is not thread safe, therefore the
2387 eval thread and main thread must be the same.
2388 If using --trace, the tracing classes must be constructed and
2390 called from the main thread.
2391 If using --vpi, since SystemVerilog VPI was not architected by IEEE
2393 to be multithreaded, Verilator requires all VPI calls are only made
2394 from the main thread.
2395
2397 In addition to the command line, warnings and other features may be
2398 controlled by configuration files, typically named with the .vlt
2399 extension. An example:
2400 `verilator_config
2402 lint_off -rule WIDTH
2403 lint_off -rule CASEX -file "silly_vendor_code.v"
2404 This disables WIDTH warnings globally, and CASEX for a specific file.
2406 Configuration files are parsed after the normal Verilog preprocessing,
2408 so `ifdefs, `defines, and comments may be used as if it were normal
2409 Verilog code.
2410 Note that file or line-specific configuration only applies to files
2412 read after the configuration file. It is therefore recommended to pass
2413 the configuration file to Verilator as first file.
2414 The grammar of configuration commands is as follows:
2416 `verilator_config
2418 Take remaining text and treat it as Verilator configuration
2419 commands.
2420 coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2422 coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2423 Enable/disable coverage for the specified filename (or wildcard
2424 with '*' or '?', or all files if omitted) and range of line numbers
2425 (or all lines if omitted). Often used to ignore an entire module
2426 for coverage analysis purposes.
2427 lint_on [-rule <message>] [-file "<filename>" [-lines <line> [ -
2429 <line>]]]
2430 lint_off [-rule <message>] [-file "<filename>" [-lines <line> [ -
2431 <line>]]]
2432 lint_off [-rule <message>] [-file "<filename>"] [-match "<string>"]
2433 Enable/disables the specified lint warning, in the specified
2434 filename (or wildcard with '*' or '?', or all files if omitted) and
2435 range of line numbers (or all lines if omitted).
2436 With lint_off using '*' will override any lint_on directives in the
2438 source, i.e. the warning will still not be printed.
2439 If the -rule is omitted, all lint warnings (see list in -Wno-lint)
2441 are enabled/disabled. This will override all later lint warning
2442 enables for the specified region.
2443 If -match is set the linter warnings are matched against this
2445 (wildcard) string and are waived in case they match iff rule and
2446 file (with wildcard) also match.
2447 In previous versions -rule was named -msg. The latter is
2449 deprecated, but still works with a deprecation info, it may be
2450 removed in future versions.
2451 tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2453 tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2454 Enable/disable waveform tracing for all future signals declared in
2455 the specified filename (or wildcard with '*' or '?', or all files
2456 if omitted) and range of line numbers (or all lines if omitted).
2457 For tracing_off, cells below any module in the files/ranges
2459 specified will also not be traced.
2460 clock_enable -module "<modulename>" -var "<signame>"
2462 Indicate the signal is used to gate a clock, and the user takes
2463 responsibility for insuring there are no races related to it.
2464 Same as /*verilator clock_enable*/, see "LANGUAGE EXTENSIONS" for
2466 more information and an example.
2467 clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
2469 clocker -module "<modulename>" [-function "<funcname>"] -var
2470 "<signame>"
2471 no_clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
2472 no_clocker -module "<modulename>" [-function "<funcname>"] -var
2473 "<signame>"
2474 Indicate the signal is used as clock or not. This information is
2475 used by Verilator to mark the signal as clocker and propagate the
2476 clocker attribute automatically to derived signals. See "--clk" for
2477 more information.
2478 Same as /*verilator clocker*/, see "LANGUAGE EXTENSIONS" for more
2480 information.
2481 coverage_block_off -module "<modulename>" -block "<blockname>"
2483 coverage_block_off -file "<filename>" -line <lineno>
2484 Specifies the entire begin/end block should be ignored for coverage
2485 analysis purposes. Can either be specified as a named block or as
2486 a filename and line number.
2487 Same as /*verilator coverage_block_off*/, see "LANGUAGE EXTENSIONS"
2489 for more information.
2490 full_case -file "<filename>" -lines <lineno>
2492 parallel_case -file "<filename>" -lines <lineno>
2493 Same as "//synopsys full_case" and "//synopsys parallel_case". When
2494 these synthesis directives are discovered, Verilator will either
2495 formally prove the directive to be true, or failing that, will
2496 insert the appropriate code to detect failing cases at simulation
2497 runtime and print an "Assertion failed" error message.
2498 inline -module "<modulename>"
2500 Specifies the module may be inlined into any modules that use this
2501 module. This is useful to speed up simulation runtime with some
2502 small loss of trace visibility and modularity. Note signals under
2503 inlined submodules will be named submodule__DOT__subsignal as C++
2504 does not allow "." in signal names. When tracing such signals the
2505 tracing routines will replace the __DOT__ with the period.
2506 Same as /*verilator inline_module*/, see "LANGUAGE EXTENSIONS" for
2508 more information.
2509 isolate_assignments -module "<modulename>" [-task "<taskname>"] -var
2511 "<signame>"
2512 isolate_assignments -module "<modulename>" [-function "<funcname>"]
2513 -var "<signame>"
2514 isolate_assignments -module "<modulename>" -function "<fname>"
2515 Used to indicate the assignments to this signal in any blocks
2516 should be isolated into new blocks. When there is a large
2517 combinatorial block that is resulting in a UNOPTFLAT warning,
2518 attaching this to the signal causing a false loop may clear up the
2519 problem.
2520 Same as /* verilator isolate_assignments */, see "LANGUAGE
2522 EXTENSIONS" for more information.
2523 no_inline -module "<modulename>"
2525 Specifies the module should not be inlined into any modules that
2526 use this module. This is useful especially at the top level module
2527 to reduce the size of the interface class, to aid compile time at a
2528 small performance loss.
2529 Same as /*verilator no_inline_module*/, see "LANGUAGE EXTENSIONS"
2531 for more information.
2532 no_inline [-module "<modulename>"] -task "<taskname>"
2534 no_inline [-module "<modulename>"] -function "<funcname>"
2535 Specify the function or task should not be inlined into where it is
2536 used. This may reduce the size of the final executable when a task
2537 is used a very large number of times. For this flag to work, the
2538 task and tasks below it must be pure; they cannot reference any
2539 variables outside the task itself.
2540 Same as /*verilator no_inline_task*/, see "LANGUAGE EXTENSIONS" for
2542 more information.
2543 sc_bv -module "<modulename>" [-task "<taskname>"] -var "<signame>"
2545 sc_bv -module "<modulename>" [-function "<funcname>"] -var "<signame>"
2546 Sets the port to be of sc_bv<width> type, instead of bool,
2547 vluint32_t or vluint64_t. This may be useful if the port width is
2548 parameterized and different of such modules interface a templated
2549 module (such as a transactor) or for other reasons. In general you
2550 should avoid using this attribute when not necessary as with
2551 increasing usage of sc_bv the performance decreases significantly.
2552 Same as /*verilator sc_bv*/, see "LANGUAGE EXTENSIONS" for more
2554 information.
2555 sformat [-module "<modulename>"] [-task "<taskname>"] -var "<signame>"
2557 sformat [-module "<modulename>"] [-function "<funcname>"] -var
2558 "<signame>"
2559 Final input of a function or task "input string" to indicate the
2560 function or task should pass all remaining arguments through
2561 $sformatf. This allows creation of DPI functions with $display
2562 like behavior. See the test_regress/t/t_dpi_display.v file for an
2563 example.
2564 Same as /*verilator sformat*/, see "LANGUAGE EXTENSIONS" for more
2566 information.
2567 split_var [-module "<modulename>"] [-task "<taskname>"] -var
2569 "<varname>"
2570 split_var [-module "<modulename>"] [-function "<funcname>"] -var
2571 "<varname>"
2572 Break the variable into multiple pieces typically to resolve
2573 UNOPTFLAT performance issues. Typically the variables to attach
2574 this to are recommeded by Verilator itself, see UNOPTFLAT.
2575 Same as /*verilator split_var*/, see "LANGUAGE EXTENSIONS" for more
2577 information.
2578
2580 Verilog 2001 (IEEE 1364-2001) Support
2581 Verilator supports most Verilog 2001 language features. This includes
2582 signed numbers, "always @*", generate statements, multidimensional
2583 arrays, localparam, and C-style declarations inside port lists.
2584 Verilog 2005 (IEEE 1364-2005) Support
2586 Verilator supports most Verilog 2005 language features. This includes
2587 the `begin_keywords and `end_keywords compiler directives, $clog2, and
2588 the uwire keyword.
2589 SystemVerilog 2005 (IEEE 1800-2005) Support
2591 Verilator supports ==? and !=? operators, ++ and -- in some contexts,
2592 $bits, $countones, $error, $fatal, $info, $isunknown, $onehot,
2593 $onehot0, $unit, $warning, always_comb, always_ff, always_latch, bit,
2594 byte, chandle, const, do-while, enum, export, final, import, int,
2595 interface, logic, longint, modport, package, program, shortint, struct,
2596 time, typedef, union, var, void, priority case/if, and unique case/if.
2597 It also supports .name and .* interconnection.
2599 Verilator partially supports concurrent assert and cover statements;
2601 see the enclosed coverage tests for the syntax which is allowed.
2602 SystemVerilog 2012 (IEEE 1800-2012) Support
2604 Verilator implements a full SystemVerilog 2012 preprocessor, including
2605 function call-like preprocessor defines, default define arguments,
2606 `__FILE__, `__LINE__ and `undefineall.
2607 Verilator currently has some support for SystemVerilog synthesis
2609 constructs. As SystemVerilog features enter common usage they are
2610 added; please file a bug if a feature you need is missing.
2611 SystemVerilog 2017 (IEEE 1800-2017) Support
2613 Verilator supports the 2017 "for" loop constructs, and several minor
2614 cleanups made in 1800-2017.
2615 Verilog AMS Support
2617 Verilator implements a very small subset of Verilog AMS (Verilog Analog
2618 and Mixed-Signal Extensions) with the subset corresponding to those VMS
2619 keywords with near equivalents in the Verilog 2005 or SystemVerilog
2620 2009 languages.
2621 AMS parsing is enabled with "--language VAMS" or "--language
2623 1800+VAMS".
2624 At present Verilator implements ceil, exp, floor, ln, log, pow, sqrt,
2626 string, and wreal.
2627 Synthesis Directive Assertion Support
2629 With the --assert switch, Verilator reads any "//synopsys full_case" or
2630 "//synopsys parallel_case" directives. The same applies to any
2631 "//ambit synthesis", "//cadence" or "//pragma" directives of the same
2632 form.
2633 When these synthesis directives are discovered, Verilator will either
2635 formally prove the directive to be true, or failing that, will insert
2636 the appropriate code to detect failing cases at simulation runtime and
2637 print an "Assertion failed" error message.
2638 Verilator likewise also asserts any "unique" or "priority"
2640 SystemVerilog keywords on case statement, as well as "unique" on if
2641 statements. However, "priority if" is currently simply ignored.
2642
2644 The following additional constructs are the extensions Verilator
2645 supports on top of standard Verilog code. Using these features outside
2646 of comments or `ifdef's may break other tools.
2647 `__FILE__
2649 The __FILE__ define expands to the current filename as a string,
2650 like C++'s __FILE__. This was incorporated into to the 1800-2009
2651 standard (but supported by Verilator since 2006!)
2652 `__LINE__
2654 The __LINE__ define expands to the current filename as a string,
2655 like C++'s __LINE__. This was incorporated into to the 1800-2009
2656 standard (but supported by Verilator since 2006!)
2657 `error string
2659 This will report an error when encountered, like C++'s #error.
2660 $c(string, ...);
2662 The string will be embedded directly in the output C++ code at the
2663 point where the surrounding Verilog code is compiled. It may
2664 either be a standalone statement (with a trailing ; in the string),
2665 or a function that returns up to a 32-bit number (without a
2666 trailing ;). This can be used to call C++ functions from your
2667 Verilog code.
2668 String arguments will be put directly into the output C++ code.
2670 Expression arguments will have the code to evaluate the expression
2671 inserted. Thus to call a C++ function, $c("func(",a,")") will
2672 result in 'func(a)' in the output C++ code. For input arguments,
2673 rather than hard-coding variable names in the string $c("func(a)"),
2674 instead pass the variable as an expression $c("func(",a,")"). This
2675 will allow the call to work inside Verilog functions where the
2676 variable is flattened out, and also enable other optimizations.
2677 If you will be reading or writing any Verilog variables inside the
2679 C++ functions, the Verilog signals must be declared with
2680 /*verilator public*/.
2681 You may also append an arbitrary number to $c, generally the width
2683 of the output. [signal_32_bits = $c32("...");] This allows for
2684 compatibility with other simulators which require a differently
2685 named PLI function name for each different output width.
2686 $display, $write, $fdisplay, $fwrite, $sformat, $swrite
2688 Format arguments may use C fprintf sizes after the % escape. Per
2689 the Verilog standard, %x prints a number with the natural width,
2690 and %0x prints a number with minimum width. Verilator extends this
2691 so %5x prints 5 digits per the C standard (it's unspecified in
2692 Verilog).
2693 `coverage_block_off
2695 Specifies the entire begin/end block should be ignored for coverage
2696 analysis. Must be inside a basic block, e.g. within a begin/end
2697 pair. Same as /* verilator coverage_block_off */ and
2698 "coverage_block_off" in "CONFIGURATION FILES".
2699 `systemc_header
2701 Take remaining text up to the next `verilog or `systemc_... mode
2702 switch and place it verbatim into the output .h file's header.
2703 Must be placed as a module item, e.g. directly inside a
2704 module/endmodule pair. Despite the name of this macro, this also
2705 works in pure C++ code.
2706 `systemc_ctor
2708 Take remaining text up to the next `verilog or `systemc_... mode
2709 switch and place it verbatim into the C++ class constructor. Must
2710 be placed as a module item, e.g. directly inside a module/endmodule
2711 pair. Despite the name of this macro, this also works in pure C++
2712 code.
2713 `systemc_dtor
2715 Take remaining text up to the next `verilog or `systemc_... mode
2716 switch and place it verbatim into the C++ class destructor. Must
2717 be placed as a module item, e.g. directly inside a module/endmodule
2718 pair. Despite the name of this macro, this also works in pure C++
2719 code.
2720 `systemc_interface
2722 Take remaining text up to the next `verilog or `systemc_... mode
2723 switch and place it verbatim into the C++ class interface. Must be
2724 placed as a module item, e.g. directly inside a module/endmodule
2725 pair. Despite the name of this macro, this also works in pure C++
2726 code.
2727 `systemc_imp_header
2729 Take remaining text up to the next `verilog or `systemc_... mode
2730 switch and place it verbatim into the header of all files for this
2731 C++ class implementation. Must be placed as a module item, e.g.
2732 directly inside a module/endmodule pair. Despite the name of this
2733 macro, this also works in pure C++ code.
2734 `systemc_implementation
2736 Take remaining text up to the next `verilog or `systemc_... mode
2737 switch and place it verbatim into a single file of the C++ class
2738 implementation. Must be placed as a module item, e.g. directly
2739 inside a module/endmodule pair. Despite the name of this macro,
2740 this also works in pure C++ code.
2741 If you will be reading or writing any Verilog variables in the C++
2743 functions, the Verilog signals must be declared with /*verilator
2744 public*/. See also the public task feature; writing an accessor
2745 may result in cleaner code.
2746 `SYSTEMVERILOG
2748 The SYSTEMVERILOG, SV_COV_START and related standard defines are
2749 set by default when --language is 1800-*.
2750 `VERILATOR
2752 `verilator
2753 `verilator3
2754 The VERILATOR, verilator and verilator3 defines are set by default
2755 so you may `ifdef around compiler specific constructs.
2756 `verilator_config
2758 Take remaining text up to the next `verilog mode switch and treat
2759 it as Verilator configuration commands.
2760 `verilog
2762 Switch back to processing Verilog code after a `systemc_... mode
2763 switch. The Verilog code returns to the last language mode
2764 specified with `begin_keywords, or SystemVerilog if none was
2765 specified.
2766 /*verilator clock_enable*/
2768 Used after a signal declaration to indicate the signal is used to
2769 gate a clock, and the user takes responsibility for insuring there
2770 are no races related to it. (Typically by adding a latch, and
2771 running static timing analysis.) For example:
2772 reg enable_r /*verilator clock_enable*/;
2774 wire gated_clk = clk & enable_r;
2775 always_ff @ (posedge clk)
2776 enable_r <= enable_early;
2777 The clock_enable attribute will cause the clock gate to be ignored
2779 in the scheduling algorithm, sometimes required for correct clock
2780 behavior, and always improving performance. It's also a good idea
2781 to enable the IMPERFECTSCH warning, to ensure all clock enables are
2782 properly recognized.
2783 Same as "clock_enable" in configuration files, see "CONFIGURATION
2785 FILES" for more information.
2786 /*verilator clocker*/
2788 /*verilator no_clocker*/
2789 Used after a signal declaration to indicate the signal is used as
2790 clock or not. This information is used by Verilator to mark the
2791 signal as clocker and propagate the clocker attribute automatically
2792 to derived signals. See "--clk" for more information.
2793 Same as "clocker" and "no_clocker" in configuration files, see
2795 "CONFIGURATION FILES" for more information.
2796 /*verilator coverage_block_off*/
2798 Specifies the entire begin/end block should be ignored for coverage
2799 analysis purposes.
2800 Same as "coverage_block_off" in configuration files, see
2802 "CONFIGURATION FILES" for more information.
2803 /*verilator coverage_off*/
2805 Specifies that following lines of code should have coverage
2806 disabled. Often used to ignore an entire module for coverage
2807 analysis purposes.
2808 /*verilator coverage_on*/
2810 Specifies that following lines of code should have coverage re-
2811 enabled (if appropriate --coverage flags are passed) after being
2812 disabled earlier with /*verilator coverage_off*/.
2813 /*verilator inline_module*/
2815 Specifies the module the comment appears in may be inlined into any
2816 modules that use this module. This is useful to speed up
2817 simulation runtime with some small loss of trace visibility and
2818 modularity. Note signals under inlined submodules will be named
2819 submodule__DOT__subsignal as C++ does not allow "." in signal
2820 names. When tracing such signals the tracing routines will replace
2821 the __DOT__ with the period.
2822 Same as "inline" in configuration files, see "CONFIGURATION FILES"
2824 for more information.
2825 /*verilator isolate_assignments*/
2827 Used after a signal declaration to indicate the assignments to this
2828 signal in any blocks should be isolated into new blocks. When
2829 there is a large combinatorial block that is resulting in a
2830 UNOPTFLAT warning, attaching this to the signal causing a false
2831 loop may clear up the problem.
2832 IE, with the following
2834 reg splitme /* verilator isolate_assignments*/;
2836 // Note the placement of the semicolon above
2837 always @* begin
2838 if (....) begin
2839 splitme = ....;
2840 other assignments
2841 end
2842 end
2843 Verilator will internally split the block that assigns to "splitme"
2845 into two blocks:
2846 It would then internally break it into (sort of):
2848 // All assignments excluding those to splitme
2850 always @* begin
2851 if (....) begin
2852 other assignments
2853 end
2854 end
2855 // All assignments to splitme
2856 always @* begin
2857 if (....) begin
2858 splitme = ....;
2859 end
2860 end
2861 Same as "isolate_assignments" in configuration files, see
2863 "CONFIGURATION FILES" for more information.
2864 /*verilator lint_off msg*/
2866 Disable the specified warning message for any warnings following
2867 the comment.
2868 /*verilator lint_on msg*/
2870 Re-enable the specified warning message for any warnings following
2871 the comment.
2872 /*verilator lint_restore*/
2874 After a /*verilator lint_save*/, pop the stack containing lint
2875 message state. Often this is useful at the bottom of include
2876 files.
2877 /*verilator lint_save*/
2879 Push the current state of what lint messages are turned on or
2880 turned off to a stack. Later meta-comments may then lint_on or
2881 lint_off specific messages, then return to the earlier message
2882 state by using /*verilator lint_restore*/. For example:
2883 // verilator lint_save
2885 // verilator lint_off SOME_WARNING
2886 ... // code needing SOME_WARNING turned off
2887 // verilator lint_restore
2888 If SOME_WARNING was on before the lint_off, it will now be restored
2890 to on, and if it was off before the lint_off it will remain off.
2891 /*verilator no_inline_module*/
2893 Specifies the module the comment appears in should not be inlined
2894 into any modules that use this module. This is useful especially
2895 at the top level module to reduce the size of the interface class,
2896 to aid compile time at a small performance loss.
2897 Same as "no_inline" in configuration files, see "CONFIGURATION
2899 FILES" for more information.
2900 /*verilator no_inline_task*/
2902 Used in a function or task variable definition section to specify
2903 the function or task should not be inlined into where it is used.
2904 This may reduce the size of the final executable when a task is
2905 used a very large number of times. For this flag to work, the task
2906 and tasks below it must be pure; they cannot reference any
2907 variables outside the task itself.
2908 Same as "no_inline" in configuration files, see "CONFIGURATION
2910 FILES" for more information.
2911 /*verilator public*/ (parameter)
2913 Used after a parameter declaration to indicate the emitted C code
2914 should have the parameter values visible. Due to C++ language
2915 restrictions, this may only be used on 64-bit or narrower integral
2916 enumerations.
2917 parameter [2:0] PARAM /*verilator public*/ = 2'b0;
2919 /*verilator public*/ (typedef enum)
2921 Used after an enum typedef declaration to indicate the emitted C
2922 code should have the enum values visible. Due to C++ language
2923 restrictions, this may only be used on 64-bit or narrower integral
2924 enumerations.
2925 typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
2927 /*verilator public*/ (variable)
2929 Used after an input, output, register, or wire declaration to
2930 indicate the signal should be declared so that C code may read or
2931 write the value of the signal. This will also declare this module
2932 public, otherwise use /*verilator public_flat*/.
2933 Instead of using public variables, consider instead making a DPI or
2935 public function that accesses the variable. This is nicer as it
2936 provides an obvious entry point that is also compatible across
2937 simulators.
2938 Same as "public" in configuration files, see "CONFIGURATION FILES"
2940 for more information.
2941 /*verilator public*/ (task/function)
2943 Used inside the declaration section of a function or task
2944 declaration to indicate the function or task should be made into a
2945 C++ function, public to outside callers. Public tasks will be
2946 declared as a void C++ function, public functions will get the
2947 appropriate non-void (bool, uint32_t, etc) return type. Any input
2948 arguments will become C++ arguments to the function. Any output
2949 arguments will become C++ reference arguments. Any local
2950 registers/integers will become function automatic variables on the
2951 stack.
2952 Wide variables over 64 bits cannot be function returns, to avoid
2954 exposing complexities. However, wide variables can be
2955 input/outputs; they will be passed as references to an array of
2956 32-bit numbers.
2957 Generally, only the values of stored state (flops) should be
2959 written, as the model will NOT notice changes made to variables in
2960 these functions. (Same as when a signal is declared public.)
2961 You may want to use DPI exports instead, as it's compatible with
2963 other simulators.
2964 Same as "public" in configuration files, see "CONFIGURATION FILES"
2966 for more information.
2967 /*verilator public_flat*/ (variable)
2969 Used after an input, output, register, or wire declaration to
2970 indicate the signal should be declared so that C code may read or
2971 write the value of the signal. This will not declare this module
2972 public, which means the name of the signal or path to it may change
2973 based upon the module inlining which takes place.
2974 Same as "public_flat" in configuration files, see "CONFIGURATION
2976 FILES" for more information.
2977 /*verilator public_flat_rd*/ (variable)
2979 Used after an input, output, register, or wire declaration to
2980 indicate the signal should be declared public_flat (see above), but
2981 read-only.
2982 Same as "public_flat_rd" in configuration files, see "CONFIGURATION
2984 FILES" for more information.
2985 /*verilator public_flat_rw @(<edge_list>) */ (variable)
2987 Used after an input, output, register, or wire declaration to
2988 indicate the signal should be declared public_flat_rd (see above),
2989 and also writable, where writes should be considered to have the
2990 timing specified by the given sensitivity edge list. Set for all
2991 variables, ports and wires using the --public-flat-rw switch.
2992 Same as "public_flat_rw" in configuration files, see "CONFIGURATION
2994 FILES" for more information.
2995 /*verilator public_module*/
2997 Used after a module statement to indicate the module should not be
2998 inlined (unless specifically requested) so that C code may access
2999 the module. Verilator automatically sets this attribute when the
3000 module contains any public signals or `systemc_ directives. Also
3001 set for all modules when using the --public switch.
3002 Same as "public" in configuration files, see "CONFIGURATION FILES"
3004 for more information.
3005 /*verilator sc_clock*/
3007 Deprecated. Used after an input declaration to indicate the signal
3008 should be declared in SystemC as a sc_clock instead of a bool.
3009 This was needed in SystemC 1.1 and 1.2 only; versions 2.0 and later
3010 do not require clock pins to be sc_clocks and this is no longer
3011 needed.
3012 /*verilator sc_bv*/
3014 Used after a port declaration. It sets the port to be of
3015 sc_bv<width> type, instead of bool, vluint32_t or vluint64_t. This
3016 may be useful if the port width is parameterized and different of
3017 such modules interface a templated module (such as a transactor) or
3018 for other reasons. In general you should avoid using this
3019 attribute when not necessary as with increasing usage of sc_bv the
3020 performance decreases significantly.
3021 Same as "sc_bv" in configuration files, see "CONFIGURATION FILES"
3023 for more information.
3024 /*verilator sformat*/
3026 Attached to the final input of a function or task "input string" to
3027 indicate the function or task should pass all remaining arguments
3028 through $sformatf. This allows creation of DPI functions with
3029 $display like behavior. See the test_regress/t/t_dpi_display.v
3030 file for an example.
3031 Same as "sformat" in configuration files, see "CONFIGURATION FILES"
3033 for more information.
3034 /*verilator split_var*/
3036 Attached to a variable or a net declaration to break the variable
3037 into multiple pieces typically to resolve UNOPTFLAT performance
3038 issues. Typically the variables to attach this to are recommeded
3039 by Verilator itself, see UNOPTFLAT below.
3040 For example, Verilator will internally convert a variable with the
3042 metacomment such as:
3043 logic [7:0] x [0:1] /*verilator split_var*/;
3045 To:
3047 logic [7:0] x__BRA__0__KET__ /*verilator split_var*/;
3049 logic [7:0] x__BRA__1__KET__ /*verilator split_var*/;
3050 Note that the generated packed variables retain the split_var
3052 metacomment because they may be split into further smaller pieces
3053 accorting to the access patterns.
3054 This only supports unpacked arrays, packed arrays, and packed
3056 structs of integer types (reg, logic, bit, byte, int...); otherwise
3057 if a split was requested but cannot occur a SPLITVAR warning is
3058 issued. Splitting large arrays may slow donw the Verilation speed,
3059 so use this only on variables that require it.
3060 Same as "split_var" in configuration files, see "CONFIGURATION
3062 FILES" for more information.
3063 /*verilator tag <text...>*/
3065 Attached after a variable or structure member to indicate opaque
3066 (to Verilator) text that should be passed through to the XML output
3067 as a tag, for use by downstream applications.
3068 /*verilator tracing_off*/
3070 Disable waveform tracing for all future signals that are declared
3071 in this module, or cells below this module. Often this is placed
3072 just after a primitive's module statement, so that the entire
3073 module and cells below it are not traced.
3074 /*verilator tracing_on*/
3076 Re-enable waveform tracing for all future signals or cells that are
3077 declared.
3078
3080 There are some limitations and lack of features relative to a
3081 commercial simulator, by intent. User beware.
3082 It is strongly recommended you use a lint tool before running this
3084 program. Verilator isn't designed to easily uncover common mistakes
3085 that a lint program will find for you.
3086 Synthesis Subset
3088 Verilator supports only the Synthesis subset with a few minor additions
3089 such as $stop, $finish and $display. That is, you cannot use
3090 hierarchical references, events or similar features of the Verilog
3091 language. It also simulates as Synopsys's Design Compiler would;
3092 namely a block of the form:
3093 always @ (x) y = x & z;
3095 This will recompute y when there is even a potential for change in x or
3097 a change in z, that is when the flops computing x or z evaluate (which
3098 is what Design Compiler will synthesize.) A compliant simulator would
3099 only calculate y if x changes. Use Verilog-Mode's /*AS*/ or Verilog
3100 2001's always @* to reduce missing activity items. Avoid putting
3101 $displays in combo blocks, as they may print multiple times when not
3102 desired, even on compliant simulators as event ordering is not
3103 specified.
3104 Signal Naming
3106 To avoid conflicts with C symbol naming, any character in a signal name
3107 that is not alphanumeric nor a single underscore will be replaced by
3108 __0hh where hh is the hex code of the character. To avoid conflicts
3109 with Verilator's internal symbols, any double underscore are replaced
3110 with ___05F (5F is the hex code of an underscore.)
3111 Bind
3113 Verilator only supports "bind" to a target module name, not an instance
3114 path.
3115 Dotted cross-hierarchy references
3117 Verilator supports dotted references to variables, functions and tasks
3118 in different modules. However, references into named blocks and
3119 function-local variables are not supported. The portion before the dot
3120 must have a constant value; for example a[2].b is acceptable, while
3121 a[x].b is not.
3122 References into generated and arrayed instances use the instance names
3124 specified in the Verilog standard; arrayed instances are named
3125 {cellName}[{instanceNumber}] in Verilog, which becomes
3126 {cellname}__BRA__{instanceNumber}__KET__ inside the generated C++ code.
3127 Verilator creates numbered "genblk" when a begin: name is not specified
3129 around a block inside a generate statement. These numbers may differ
3130 between other simulators, but the Verilog specification does not allow
3131 users to use these names, so it should not matter.
3132 If you are having trouble determining where a dotted path goes wrong,
3134 note that Verilator will print a list of known scopes to help your
3135 debugging.
3136 Floating Point
3138 Short floating point (shortreal) numbers are converted to real.
3139 Latches
3141 Verilator is optimized for edge sensitive (flop based) designs. It
3142 will attempt to do the correct thing for latches, but most performance
3143 optimizations will be disabled around the latch.
3144 Structures and Unions
3146 Verilator only presently supports packed structs and packed unions.
3147 Rand and randc tags on members are simply ignored. All structures and
3148 unions are represented as a single vector, which means that generating
3149 one member of a structure from blocking, and another from non-blocking
3150 assignments is unsupported.
3151 Time
3153 All delays (#) are ignored, as they are in synthesis.
3154 Unknown states
3156 Verilator is mostly a two state simulator, not a four state simulator.
3157 However, it has two features which uncover most initialization bugs
3158 (including many that a four state simulator will miss.)
3159 Identity comparisons (=== or !==) are converted to standard ==/!== when
3161 neither side is a constant. This may make the expression result differ
3162 from a four state simulator. An === comparison to X will always be
3163 false, so that Verilog code which checks for uninitialized logic will
3164 not fire.
3165 Assigning a variable to a X will actually assign the variable to a
3167 random value (see the --x-assign switch and +verilator+rand+reset
3168 simulation runtime switch.) Thus if the value is actually used, the
3169 random value should cause downstream errors. Integers also randomize,
3170 even though the Verilog 2001 specification says they initialize to
3171 zero.
3172 All variables, depending on --x-initial setting, are typically randomly
3174 initialized using a function. By running several random simulation
3175 runs you can determine that reset is working correctly. On the first
3176 run, the function initializes variables to zero. On the second, have
3177 it initialize variables to one. On the third and following runs have
3178 it initialize them randomly. If the results match, reset works. (Note
3179 this is what the hardware will really do.) In practice, just setting
3180 all variables to one at startup finds most problems (since typically
3181 control signals are active-high).
3182 --x-assign applies to variables explicitly initialized or assigned to
3184 X. Uninitialized clocks are initialized to zero, while all other state
3185 holding variables are initialized to a random value. Event driven
3186 simulators will generally trigger an edge on a transition from X to 1
3187 ("posedge") or X to 0 ("negedge"). However, by default, since clocks
3188 are initialized to zero, Verilator will not trigger an initial negedge.
3189 Some code (particularly for reset) may rely on X->0 triggering an edge.
3190 The --x-initial-edge switch enables this behavior. Comparing runs with
3191 and without this switch will find such problems.
3192 Tri/Inout
3194 Verilator converts some simple tristate structures into two state.
3195 Pullup, pulldown, bufif0, bufif1, notif0, notif1, pmos, nmos, tri0 and
3196 tri1 are also supported. Simple comparisons with === 1'bz are also
3197 supported.
3198 An assignment of the form:
3200 inout driver;
3202 wire driver = (enable) ? output_value : 1'bz;
3203 Will be converted to
3205 input driver; // Value being driven in from "external" drivers
3207 output driver__en; // True if driven from this module
3208 output driver__out; // Value being driven from this module
3209 External logic will be needed to combine these signals with any
3211 external drivers.
3212 Tristate drivers are not supported inside functions and tasks; an inout
3214 there will be considered a two state variable that is read and written
3215 instead of a four state variable.
3216 Functions & Tasks
3218 All functions and tasks will be inlined (will not become functions in
3219 C.) The only support provided is for simple statements in tasks (which
3220 may affect global variables).
3221 Recursive functions and tasks are not supported. All inputs and
3223 outputs are automatic, as if they had the Verilog 2001 "automatic"
3224 keyword prepended. (If you don't know what this means, Verilator will
3225 do what you probably expect -- what C does. The default behavior of
3226 Verilog is different.)
3227 Generated Clocks
3229 Verilator attempts to deal with generated and enabled clocks correctly,
3230 however some cases cause problems in the scheduling algorithm which is
3231 optimized for performance. The safest option is to have all clocks as
3232 primary inputs to the model, or wires directly attached to primary
3233 inputs. For proper behavior clock enables may also need the
3234 /*verilator clock_enable*/ attribute.
3235 Ranges must be big-bit-endian
3237 Bit ranges must be numbered with the MSB being numbered greater or the
3238 same as the LSB. Little-bit-endian buses [0:15] are not supported as
3239 they aren't easily made compatible with C++.
3240 Gate Primitives
3242 The 2-state gate primitives (and, buf, nand, nor, not, or, xnor, xor)
3243 are directly converted to behavioral equivalents. The 3-state and MOS
3244 gate primitives are not supported. Tables are not supported.
3245 Specify blocks
3247 All specify blocks and timing checks are ignored.
3248 Array Initialization
3250 When initializing a large array, you need to use non-delayed
3251 assignments. Verilator will tell you when this needs to be fixed; see
3252 the BLKLOOPINIT error for more information.
3253 Array Out of Bounds
3255 Writing a memory element that is outside the bounds specified for the
3256 array may cause a different memory element inside the array to be
3257 written instead. For power-of-2 sized arrays, Verilator will give a
3258 width warning and the address. For non-power-of-2-sizes arrays, index
3259 0 will be written.
3260 Reading a memory element that is outside the bounds specified for the
3262 array will give a width warning and wrap around the power-of-2 size.
3263 For non-power-of-2 sizes, it will return a unspecified constant of the
3264 appropriate width.
3265 Assertions
3267 Verilator is beginning to add support for assertions. Verilator
3268 currently only converts assertions to simple "if (...) error"
3269 statements, and coverage statements to increment the line counters
3270 described in the coverage section.
3271 Verilator does not support SEREs yet. All assertion and coverage
3273 statements must be simple expressions that complete in one cycle.
3274 (Arguably SEREs are much of the point, but one must start somewhere.)
3275 Encrypted Verilog
3277 Open source simulators like Verilator are unable to use encrypted RTL
3278 (i.e. IEEE P1735). Talk to your IP vendor about delivering IP blocks
3279 via Verilator's --protect-lib feature.
3280 Language Keyword Limitations
3282 This section describes specific limitations for each language keyword.
3283 `__FILE__, `__LINE__, `begin_keywords, `begin_keywords,
3285 `begin_keywords, `begin_keywords, `begin_keywords, `define, `else,
3286 `elsif, `end_keywords, `endif, `error, `ifdef, `ifndef, `include,
3287 `line, `systemc_ctor, `systemc_dtor, `systemc_header,
3288 `systemc_imp_header, `systemc_implementation, `systemc_interface,
3289 `timescale, `undef, `verilog
3290 Fully supported.
3291 always, always_comb, always_ff, always_latch, and, assign, begin, buf,
3293 byte, case, casex, casez, default, defparam, do-while, else, end,
3294 endcase, endfunction, endgenerate, endmodule, endspecify, endtask,
3295 final, for, function, generate, genvar, if, initial, inout, input, int,
3296 integer, localparam, logic, longint, macromodule, module, nand,
3297 negedge, nor, not, or, output, parameter, posedge, reg, scalared,
3298 shortint, signed, supply0, supply1, task, time, tri, typedef, var,
3299 vectored, while, wire, xnor, xor
3300 Generally supported.
3301 ++, -- operators
3303 Increment/decrement can only be used as standalone statements or in
3304 for loops. They cannot be used as side effect operators inside
3305 more complicate expressions ("a = b++;").
3306 '{} operator
3308 Assignment patterns with order based, default, constant integer
3309 (array) or member identifier (struct/union) keys are supported.
3310 Data type keys and keys which are computed from a constant
3311 expression are not supported.
3312 `uselib
3314 Uselib, a vendor specific library specification method, is ignored
3315 along with anything following it until the end of that line.
3316 cast operator
3318 Casting is supported only between simple scalar types, signed and
3319 unsigned, not arrays nor structs.
3320 chandle
3322 Treated as a "longint"; does not yet warn about operations that are
3323 specified as illegal on chandles.
3324 disable
3326 Disable statements may be used only if the block being disabled is
3327 a block the disable statement itself is inside. This was commonly
3328 used to provide loop break and continue functionality before
3329 SystemVerilog added the break and continue keywords.
3330 inside
3332 Inside expressions may not include unpacked array traversal or $ as
3333 an upper bound. Case inside and case matches are also unsupported.
3334 interface
3336 Interfaces and modports, including with generated data types are
3337 supported. Generate blocks around modports are not supported, nor
3338 are virtual interfaces nor unnamed interfaces.
3339 priority if, unique if
3341 Priority and unique if's are treated as normal ifs and not asserted
3342 to be full nor unique.
3343 specify specparam
3345 All specify blocks and timing checks are ignored.
3346 string
3348 String is supported only to the point that they can be assigned,
3349 concatenated, compared, and passed to DPI imports. Standard method
3350 calls on strings are not supported.
3351 timeunit, timeprecision
3353 All timing control statements are ignored.
3354 uwire
3356 Verilator does not perform warning checking on uwires, it treats
3357 the uwire keyword as if it were the normal wire keyword.
3358 $bits, $countones, $error, $fatal, $finish, $info, $isunknown, $onehot,
3360 $onehot0, $readmemb, $readmemh, $signed, $stime, $stop, $time,
3361 $unsigned, $warning.
3362 Generally supported.
3363 $displayb, $displayh, $displayo, $writeb, $writeh, $writeo, etc
3365 The sized display functions are rarely used and so not supported.
3366 Replace them with a $write with the appropriate format specifier.
3367 $dump/$dumpports and related
3369 $dumpfile or $dumpports will create a VCD or FST file (which is
3370 based on the --trace argument given when the model was Verilated).
3371 This will take effect starting at the next eval() call. If you
3372 have multiple Verilated designs under the same C model, then this
3373 will dump signals only from the design containing the $dumpvar.
3374 $dumpvars and $dumpports module identifier is ignored; the traced
3376 instances will always start at the top of the design. The levels
3377 argument is also ignored, use tracing_on/tracing_off pragmas
3378 instead.
3379 $dumpportson/$dumpportsoff/$dumpportsall/$dumpportslimit filename
3381 argument is ignored, only a single trace file may be active at
3382 once.
3383 $dumpall/$dumpportsall, $dumpon/$dumpportson,
3385 $dumpoff/$dumpportsoff, and $dumplimit/$dumpportlimit are currently
3386 ignored.
3387 $finish, $stop
3389 The rarely used optional parameter to $finish and $stop is ignored.
3390 $fopen, $fclose, $fdisplay, $feof, $fflush, $fgetc, $fgets, $fscanf,
3392 $fwrite
3393 File descriptors passed to the file PLI calls must be file
3394 descriptors, not MCDs, which includes the mode parameter to $fopen
3395 being mandatory.
3396 $fscanf, $sscanf
3398 The formats %r, %v, and %z are not supported.
3399 $fullskew, $hold, $nochange, $period, $recovery, $recrem, $removal,
3401 $setup, $setuphold, $skew, $timeskew, $width
3402 All specify blocks and timing checks are ignored.
3403 $random
3405 $random does not support the optional argument to set the seed.
3406 Use the srand function in C to accomplish this, and note there is
3407 only one random number generator (not one per module).
3408 $readmemb, $readmemh
3410 Read memory commands should work properly. Note Verilator and the
3411 Verilog specification does not include support for readmem to
3412 multi-dimensional arrays.
3413 $test$plusargs, $value$plusargs
3415 Supported, but the instantiating C++/SystemC testbench must call
3416 Verilated::commandArgs(argc, argv);
3418 to register the command line before calling $test$plusargs or
3420 $value$plusargs.
3421 $timeformat
3423 Not supported as Verilator needs to determine all formatting at
3424 compile time. Generally you can just ifdef them out for no ill
3425 effect. Note also VL_TIME_MULTIPLIER can be defined at compile
3426 time to move the decimal point when displaying all times, model
3427 wide.
3428
3430 Warnings may be disabled in three ways. First, when the warning is
3431 printed it will include a warning code. Simply surround the offending
3432 line with a warn_off/warn_on pair:
3433 // verilator lint_off UNSIGNED
3435 if (`DEF_THAT_IS_EQ_ZERO <= 3) $stop;
3436 // verilator lint_on UNSIGNED
3437 Second, warnings may be disabled using a configuration file with a
3439 lint_off command. This is useful when a script is suppressing warnings
3440 and the Verilog source should not be changed.
3441 Warnings may also be globally disabled by invoking Verilator with the
3443 "-Wno-warning" switch. This should be avoided, as it removes all
3444 checking across the designs, and prevents other users from compiling
3445 your code without knowing the magic set of disables needed to
3446 successfully compile your design.
3447 Error and Warning Format
3449 Warnings and errors printed by Verilator always match this regular
3450 expression:
3451 %(Error|Warning)(-[A-Z0-9_]+)?: ((\S+):(\d+):((\d+):)? )?.*
3453 Errors and warning start with a percent sign (historical heritage from
3455 Digital Equipment Corporation). Some errors or warning have a code
3456 attached, with meanings described below. Some errors also have a
3457 filename, line number and optional column number (starting at column 1
3458 to match GCC).
3459 Following an the error message, Verilator will typically show the
3461 user's source code corresponding to the error, prefixed by the line
3462 number and a " | ". Following this is typically an arrow and ~
3463 pointing at the error on the source line directly above.
3464 List of all warnings
3466 ALWCOMBORDER
3467 Warns that an always_comb block has a variable which is set after
3468 it is used. This may cause simulation-synthesis mismatches, as not
3469 all commercial simulators allow this ordering.
3470 always_comb begin
3472 a = b;
3473 b = 1;
3474 end
3475 Ignoring this warning will only suppress the lint check, it will
3477 simulate correctly.
3478 ASSIGNIN
3480 Error that an assignment is being made to an input signal. This is
3481 almost certainly a mistake, though technically legal.
3482 input a;
3484 assign a = 1'b1;
3485 Ignoring this warning will only suppress the lint check, it will
3487 simulate correctly.
3488 ASSIGNDLY
3490 Warns that you have an assignment statement with a delayed time in
3491 front of it, for example:
3492 a <= #100 b;
3494 assign #100 a = b;
3495 Ignoring this warning may make Verilator simulations differ from
3497 other simulators, however at one point this was a common style so
3498 disabled by default as a code style warning.
3499 BLKANDNBLK
3501 BLKANDNBLK is an error that a variable comes from a mix of blocked
3502 and non-blocking assignments. Generally, this is caused by a
3503 register driven by both combo logic and a flop:
3504 always @ (posedge clk) foo[0] <= ...
3506 always @* foo[1] = ...
3507 Simply use a different register for the flop:
3509 always @ (posedge clk) foo_flopped[0] <= ...
3511 always @* foo[0] = foo_flopped[0];
3512 always @* foo[1] = ...
3513 This is not illegal in SystemVerilog, but a violation of good
3515 coding practice. Verilator reports this as an error, because
3516 ignoring this warning may make Verilator simulations differ from
3517 other simulators.
3518 It is generally safe to disable this error (with a "// verilator
3520 lint_off BLKANDNBLK" metacomment or the -Wno-BLKANDNBLK option)
3521 when one of the assignments is inside a public task, or when the
3522 blocked and non-blocking assignments have non-overlapping bits and
3523 structure members.
3524 BLKSEQ
3526 This indicates that a blocking assignment (=) is used in a
3527 sequential block. Generally non-blocking/delayed assignments (<=)
3528 are used in sequential blocks, to avoid the possibility of
3529 simulator races. It can be reasonable to do this if the generated
3530 signal is used ONLY later in the same block, however this style is
3531 generally discouraged as it is error prone.
3532 always @ (posedge clk) foo = ...
3534 Disabled by default as this is a code style warning; it will
3536 simulate correctly.
3537 BLKLOOPINIT
3539 This indicates that the initialization of an array needs to use
3540 non-delayed assignments. This is done in the interest of speed; if
3541 delayed assignments were used, the simulator would have to copy
3542 large arrays every cycle. (In smaller loops, loop unrolling allows
3543 the delayed assignment to work, though it's a bit slower than a
3544 non-delayed assignment.) Here's an example
3545 always @ (posedge clk)
3547 if (~reset_l) begin
3548 for (i=0; i<`ARRAY_SIZE; i++) begin
3549 array[i] = 0; // Non-delayed for verilator
3550 end
3551 This message is only seen on large or complicated loops because
3553 Verilator generally unrolls small loops. You may want to try
3554 increasing --unroll-count (and occasionally --unroll-stmts) which
3555 will raise the small loop bar to avoid this error.
3556 BOUNDED
3558 This indicates that bounded queues (e.g. "var name[$ : 3]") are
3559 unsupported.
3560 Ignoring this warning may make Verilator simulations differ from
3562 other simulators.
3563 BSSPACE
3565 Warns that a backslash is followed by a space then a newline.
3566 Likely the intent was to have a backslash directly followed by a
3567 newline (e.g. when making a `define) and there's accidentally
3568 whitespace at the end of the line. If the space is not accidental,
3569 suggest removing the backslash in the code as it serves no
3570 function.
3571 Ignoring this warning will only suppress the lint check, it will
3573 simulate correctly.
3574 CASEINCOMPLETE
3576 Warns that inside a case statement there is a stimulus pattern for
3577 which there is no case item specified. This is bad style, if a
3578 case is impossible, it's better to have a "default: $stop;" or just
3579 "default: ;" so that any design assumption violations will be
3580 discovered in simulation.
3581 Ignoring this warning will only suppress the lint check, it will
3583 simulate correctly.
3584 CASEOVERLAP
3586 Warns that inside a case statement you have case values which are
3587 detected to be overlapping. This is bad style, as moving the order
3588 of case values will cause different behavior. Generally the values
3589 can be respecified to not overlap.
3590 Ignoring this warning will only suppress the lint check, it will
3592 simulate correctly.
3593 CASEX
3595 Warns that it is simply better style to use casez, and "?" in place
3596 of "x"'s. See
3597 <http://www.sunburst-design.com/papers/CummingsSNUG1999Boston_FullParallelCase_rev1_1.pdf>
3598 Ignoring this warning will only suppress the lint check, it will
3600 simulate correctly.
3601 CASEWITHX
3603 Warns that a case statement contains a constant with a "x".
3604 Verilator is two-state so interpret such items as always false.
3605 Note a common error is to use a "X" in a case or casez statement
3606 item; often what the user instead intended is to use a casez with
3607 "?".
3608 Ignoring this warning will only suppress the lint check, it will
3610 simulate correctly.
3611 CDCRSTLOGIC
3613 With --cdc only, warns that asynchronous flop reset terms come from
3614 other than primary inputs or flopped outputs, creating the
3615 potential for reset glitches.
3616 CLKDATA
3618 Warns that clock signal is mixed used with/as data signal. The
3619 checking for this warning is enabled only if user has explicitly
3620 marked some signal as clocker using command line option or in-
3621 source meta comment (see "--clk").
3622 The warning can be disabled without affecting the simulation
3624 result. But it is recommended to check the warning as this may
3625 degrade the performance of the Verilated model.
3626 CMPCONST
3628 Warns that you are comparing a value in a way that will always be
3629 constant. For example "X > 1" will always be true when X is a
3630 single bit wide.
3631 Ignoring this warning will only suppress the lint check, it will
3633 simulate correctly.
3634 COLONPLUS
3636 Warns that a :+ is seen. Likely the intent was to use +: to select
3637 a range of bits. If the intent was a range that is explicitly
3638 positive, suggest adding a space, e.g. use ": +".
3639 Ignoring this warning will only suppress the lint check, it will
3641 simulate correctly.
3642 COMBDLY
3644 Warns that you have a delayed assignment inside of a combinatorial
3645 block. Using delayed assignments in this way is considered bad
3646 form, and may lead to the simulator not matching synthesis. If
3647 this message is suppressed, Verilator, like synthesis, will convert
3648 this to a non-delayed assignment, which may result in logic races
3649 or other nasties. See
3650 <http://www.sunburst-design.com/papers/CummingsSNUG2000SJ_NBA_rev1_2.pdf>
3651 Ignoring this warning may make Verilator simulations differ from
3653 other simulators.
3654 CONTASSREG
3656 Error that a continuous assignment is setting a reg. According to
3657 IEEE Verilog, but not SystemVerilog, a wire must be used as the
3658 target of continuous assignments.
3659 This error is only reported when "--language 1364-1995",
3661 "--language 1364-2001", or "--language 1364-2005" is used.
3662 Ignoring this error will only suppress the lint check, it will
3664 simulate correctly.
3665 DECLFILENAME
3667 Warns that a module or other declaration's name doesn't match the
3668 filename with path and extension stripped that it is declared in.
3669 The filename a modules/interfaces/programs is declared in should
3670 match the name of the module etc. so that -y directory searching
3671 will work. This warning is printed for only the first mismatching
3672 module in any given file, and -v library files are ignored.
3673 Disabled by default as this is a code style warning; it will
3675 simulate correctly.
3676 DEFPARAM
3678 Warns that the "defparam" statement was deprecated in Verilog 2001
3679 and all designs should now be using the #(...) format to specify
3680 parameters.
3681 Disabled by default as this is a code style warning; it will
3683 simulate correctly.
3684 DETECTARRAY
3686 Error when Verilator tries to deal with a combinatorial loop that
3687 could not be flattened, and which involves a datatype which
3688 Verilator cannot handle, such as an unpacked struct or a large
3689 unpacked array. This typically occurs when -Wno-UNOPTFLAT has been
3690 used to override an UNOPTFLAT warning (see below).
3691 The solution is to break the loop, as described for UNOPTFLAT.
3693 DIDNOTCONVERGE
3695 Error at simulation runtime when model did not properly settle.
3696 Verilator sometimes has to evaluate combinatorial logic multiple
3698 times, usually around code where a UNOPTFLAT warning was issued,
3699 but disabled. For example:
3700 always_comb b = ~a;
3702 always_comb a = b
3703 This code will toggle forever, and thus to prevent an infinite
3705 loop, the executable will give the didn't converge error.
3706 To debug this, first is to review any UNOPTFLAT warnings that were
3708 ignored. Though typically it is safe to ignore UNOPTFLAT (at a
3709 performance cost), at the time of issuing a UNOPTFLAT Verilator
3710 didn't know if they would eventually converge and assumed the
3711 would.
3712 Next, run Verilator with --prof-cfuncs. Run make on the generated
3714 files with "CPP_FLAGS=-DVL_DEBUG", to allow enabling simulation
3715 runtime debug messages. Rerun the test. Now just before the
3716 convergence error you should see additional output similar to this:
3717 CHANGE: filename.v:1: b
3719 CHANGE: filename.v:2: a
3720 This means that signal b and signal a keep changing, inspect the
3722 code that modifies these signals. Note if many signals are getting
3723 printed then most likely all of them are oscillating. It may also
3724 be that e.g. "a" may be oscillating, then "a" feeds signal "c"
3725 which then is also reported as oscillating.
3726 Finally, rare, more difficult cases can be debugged like a "C"
3728 program; either enter GDB and use its tracing facilities, or edit
3729 the generated C++ code to add appropriate prints to see what is
3730 going on.
3731 ENDLABEL
3733 Warns that a label attached to a "end"-something statement does not
3734 match the label attached to the block start.
3735 Ignoring this warning will only suppress the lint check, it will
3737 simulate correctly.
3738 GENCLK
3740 Warns that the specified signal is generated, but is also being
3741 used as a clock. Verilator needs to evaluate sequential logic
3742 multiple times in this situation. In somewhat contrived cases
3743 having any generated clock can reduce performance by almost a
3744 factor of two. For fastest results, generate ALL clocks outside in
3745 C++/SystemC and make them primary inputs to your Verilog model.
3746 (However once need to you have even one, don't sweat additional
3747 ones.)
3748 Ignoring this warning may make Verilator simulations differ from
3750 other simulators.
3751 IFDEPTH
3753 Warns that if/if else statements have exceeded the depth specified
3754 with --if-depth, as they are likely to result in slow priority
3755 encoders. Unique and priority if statements are ignored.
3756 Solutions include changing the code to a case statement, or a
3757 SystemVerilog 'unique if' or 'priority if'.
3758 Disabled by default as this is a code style warning; it will
3760 simulate correctly.
3761 IGNOREDRETURN
3763 Warns that a non-void function is being called as a task, and hence
3764 the return value is being ignored.
3765 This warning is required by IEEE. The portable way to suppress this
3767 warning (in SystemVerilog) is to use a void cast, e.g.
3768 void'(function_being_called_as_task());
3770 Ignoring this warning will only suppress the lint check, it will
3772 simulate correctly.
3773 IMPERFECTSCH
3775 Warns that the scheduling of the model is not absolutely perfect,
3776 and some manual code edits may result in faster performance. This
3777 warning defaults to off, is not part of -Wall, and must be turned
3778 on explicitly before the top module statement is processed.
3779 IMPLICIT
3781 Warns that a wire is being implicitly declared (it is a single bit
3782 wide output from a sub-module.) While legal in Verilog, implicit
3783 declarations only work for single bit wide signals (not buses), do
3784 not allow using a signal before it is implicitly declared by a
3785 cell, and can lead to dangling nets. A better option is the
3786 /*AUTOWIRE*/ feature of Verilog-Mode for Emacs, available from
3787 <https://www.veripool.org/verilog-mode>
3788 Ignoring this warning will only suppress the lint check, it will
3790 simulate correctly.
3791 IMPORTSTAR
3793 Warns that an "import package::*" statement is in $unit scope. This
3794 causes the imported symbols to pollute the global namespace,
3795 defeating much of the purpose of having a package. Generally
3796 "import ::*" should only be used inside a lower scope such as a
3797 package or module.
3798 Disabled by default as this is a code style warning; it will
3800 simulate correctly.
3801 IMPURE
3803 Warns that a task or function that has been marked with /*verilator
3804 no_inline_task*/ references variables that are not local to the
3805 task. Verilator cannot schedule these variables correctly.
3806 Ignoring this warning may make Verilator simulations differ from
3808 other simulators.
3809 INCABSPATH
3811 Warns that an `include filename specifies an absolute path. This
3812 means the code will not work on any other system with a different
3813 file system layout. Instead of using absolute paths, relative
3814 paths (preferably without any directory specified whatever) should
3815 be used, and +incdir used on the command line to specify the top
3816 include source directories.
3817 Disabled by default as this is a code style warning; it will
3819 simulate correctly.
3820 INFINITELOOP
3822 Warns that a while or for statement has a condition that is always
3823 true. and thus result in an infinite loop if the statement ever
3824 executes.
3825 This might be unintended behavior if the loop body contains
3827 statements that in other statements that would make time pass,
3828 which Verilator is ignoring due to e.g. STMTDLY warnings being
3829 disabled.
3830 Ignoring this warning will only suppress the lint check, it will
3832 simulate correctly (i.e. hang due to the infinite loop).
3833 INITIALDLY
3835 Warns that you have a delayed assignment inside of an initial or
3836 final block. If this message is suppressed, Verilator will convert
3837 this to a non-delayed assignment. See also the COMBDLY warning.
3838 Ignoring this warning may make Verilator simulations differ from
3840 other simulators.
3841 INSECURE
3843 Warns that the combination of options selected may be defeating the
3844 attempt to protect/obscure identifiers or hide information in the
3845 model. Correct the options provided, or inspect the output code to
3846 see if the information exposed is acceptable.
3847 Ignoring this warning will only suppress the lint check, it will
3849 simulate correctly.
3850 LITENDIAN
3852 Warns that a packed vector is declared with little endian bit
3853 numbering (i.e. [0:7]). Big endian bit numbering is now the
3854 overwhelming standard, and little numbering is now thus often due
3855 to simple oversight instead of intent.
3856 Also warns that a cell is declared with little endian range (i.e.
3858 [0:7] or [7]) and is connected to a N-wide signal. Based on IEEE
3859 the bits will likely be backwards from what you expect (i.e. cell
3860 [0] will connect to signal bit [N-1] not bit [0]).
3861 Ignoring this warning will only suppress the lint check, it will
3863 simulate correctly.
3864 MODDUP
3866 Warns that a module has multiple definitions. Generally this
3867 indicates a coding error, or a mistake in a library file and it's
3868 good practice to have one module per file (and only put each file
3869 once on the command line) to avoid these issues. For some gate
3870 level netlists duplicates are sometimes unavoidable, and MODDUP
3871 should be disabled.
3872 Ignoring this warning will cause the more recent module definition
3874 to be discarded.
3875 MULTIDRIVEN
3877 Warns that the specified signal comes from multiple always blocks.
3878 This is often unsupported by synthesis tools, and is considered bad
3879 style. It will also cause longer simulation runtimes due to
3880 reduced optimizations.
3881 Ignoring this warning will only slow simulations, it will simulate
3883 correctly.
3884 MULTITOP
3886 Warns that there are multiple top level modules, that is modules
3887 not instantiated by any other module, and both modules were put on
3888 the command line (not in a library). Three likely cases:
3889 1. A single module is intended to be the top. This warning then
3891 occurs because some low level cell is being read in, but is not
3892 really needed as part of the design. The best solution for this
3893 situation is to ensure that only the top module is put on the
3894 command line without any flags, and all remaining library files are
3895 read in as libraries with -v, or are automatically resolved by
3896 having filenames that match the module names.
3897 2. A single module is intended to be the top, the name of it is
3899 known, and all other modules should be ignored if not part of the
3900 design. The best solution is to use the --top-module option to
3901 specify the top module's name. All other modules that are not part
3902 of the design will be for the most part ignored (they must be clean
3903 in syntax and their contents will be removed as part of the Verilog
3904 module elaboration process.)
3905 3. Multiple modules are intended to be design tops, e.g. when
3907 linting a library file. As multiple modules are desired, disable
3908 the MULTITOP warning. All input/outputs will go uniquely to each
3909 module, with any conflicting and identical signal names being
3910 uniquified by adding a prefix based on the top module name followed
3911 by __02E (a Verilator-encoded ASCII ".'). This renaming is done
3912 even if the two modules' signals seem identical, e.g. multiple
3913 modules with a "clk" input.
3914 PINCONNECTEMPTY
3916 Warns that a cell instantiation has a pin which is connected to
3917 .pin_name(), e.g. not another signal, but with an explicit mention
3918 of the pin. It may be desirable to disable PINCONNECTEMPTY, as
3919 this indicates intention to have a no-connect.
3920 Disabled by default as this is a code style warning; it will
3922 simulate correctly.
3923 PINMISSING
3925 Warns that a module has a pin which is not mentioned in a cell
3926 instantiation. If a pin is not missing it should still be
3927 specified on the cell declaration with a empty connection, using
3928 "(.pin_name())".
3929 Ignoring this warning will only suppress the lint check, it will
3931 simulate correctly.
3932 PINNOCONNECT
3934 Warns that a cell instantiation has a pin which is not connected to
3935 another signal.
3936 Disabled by default as this is a code style warning; it will
3938 simulate correctly.
3939 PROCASSWIRE
3941 Error that a procedural assignment is setting a wire. According to
3942 IEEE, a var/reg must be used as the target of procedural
3943 assignments.
3944 REALCVT
3946 Warns that a real number is being implicitly rounded to an integer,
3947 with possible loss of precision.
3948 REDEFMACRO
3950 Warns that you have redefined the same macro with a different
3951 value, for example:
3952 `define MACRO def1
3954 //...
3955 `define MACRO otherdef
3956 The best solution is to use a different name for the second macro.
3958 If this is not possible, add a undef to indicate the code is
3959 overriding the value:
3960 `define MACRO def1
3962 //...
3963 `undef MACRO
3964 `define MACRO otherdef
3965 SELRANGE
3967 Warns that a selection index will go out of bounds:
3968 wire vec[6:0];
3970 initial out = vec[7]; // There is no 7
3971 Verilator will assume zero for this value, instead of X. Note that
3973 in some cases this warning may be false, when a condition upstream
3974 or downstream of the access means the access out of bounds will
3975 never execute or be used.
3976 wire vec[6:0];
3978 initial begin
3979 seven = 7;
3980 ...
3981 if (seven != 7) out = vec[seven]; // Never will use vec[7]
3982 SHORTREAL
3984 Warns that Verilator does not support "shortreal" and they will be
3985 automatically promoted to "real". The recommendation is to replace
3986 any "shortreal" in the code with "real", as "shortreal" is not
3987 widely supported across industry tools.
3988 Ignoring this warning may make Verilator simulations differ from
3990 other simulators, if the increased precision of real affects your
3991 model or DPI calls.
3992 SPLITVAR
3994 Warns that a variable with a "split_var" metacomment was not split.
3995 Some possible reasons for this are:
3996 * The datatype of the variable is not supported for splitting.
3998 (e.g. is a real).
3999 * The access pattern of the variable can not be determined
4001 statically. (e.g. is accessed as a memory).
4002 * The index of the array exceeds the array size.
4004 * The variable is accessed from outside using dotted reference.
4006 (e.g. top.instance0.variable0 = 1).
4007 * The variable is not declared in a module, but in a package or an
4009 interface.
4010 * The variable is a parameter, localparam, genvar, or queue.
4012 * The variable is tirstate or bidirectional. (e.g. inout or ref).
4014 STMTDLY
4016 Warns that you have a statement with a delayed time in front of it,
4017 for example:
4018 #100 $finish;
4020 Ignoring this warning may make Verilator simulations differ from
4022 other simulators.
4023 SYMRSVDWORD
4025 Warning that a symbol matches a C++ reserved word and using this as
4026 a symbol name would result in odd C compiler errors. You may
4027 disable this warning, but the symbol will be renamed by Verilator
4028 to avoid the conflict.
4029 SYNCASYNCNET
4031 Warns that the specified net is used in at least two different
4032 always statements with posedge/negedges (i.e. a flop). One usage
4033 has the signal in the sensitivity list and body, probably as an
4034 async reset, and the other usage has the signal only in the body,
4035 probably as a sync reset. Mixing sync and async resets is usually
4036 a mistake. The warning may be disabled with a lint_off pragma
4037 around the net, or either flopped block.
4038 Disabled by default as this is a code style warning; it will
4040 simulate correctly.
4041 TASKNSVAR
4043 Error when a call to a task or function has a output from that task
4044 tied to a non-simple signal. Instead connect the task output to a
4045 temporary signal of the appropriate width, and use that signal to
4046 set the appropriate expression as the next statement. For example:
4047 task foo; output sig; ... endtask
4049 always @* begin
4050 foo(bus_we_select_from[2]); // Will get TASKNSVAR error
4051 end
4052 Change this to:
4054 reg foo_temp_out;
4056 always @* begin
4057 foo(foo_temp_out);
4058 bus_we_select_from[2] = foo_temp_out;
4059 end
4060 Verilator doesn't do this conversion for you, as some more
4062 complicated cases would result in simulator mismatches.
4063 TICKCOUNT
4065 Warns that the number of ticks to delay a $past variable is greater
4066 than 10. At present Verilator effectively creates a flop for each
4067 delayed signals, and as such any large counts may lead to large
4068 design size increases.
4069 Ignoring this warning will only slow simulations, it will simulate
4071 correctly.
4072 UNDRIVEN
4074 Warns that the specified signal is never sourced. Verilator is
4075 fairly liberal in the usage calculations; making a signal public,
4076 or loading only a single array element marks the entire signal as
4077 driven.
4078 Disabled by default as this is a code style warning; it will
4080 simulate correctly.
4081 UNOPT
4083 Warns that due to some construct, optimization of the specified
4084 signal or block is disabled. The construct should be cleaned up to
4085 improve simulation runtime.
4086 A less obvious case of this is when a module instantiates two
4088 submodules. Inside submodule A, signal I is input and signal O is
4089 output. Likewise in submodule B, signal O is an input and I is an
4090 output. A loop exists and a UNOPT warning will result if AI & AO
4091 both come from and go to combinatorial blocks in both submodules,
4092 even if they are unrelated always blocks. This affects performance
4093 because Verilator would have to evaluate each submodule multiple
4094 times to stabilize the signals crossing between the modules.
4095 Ignoring this warning will only slow simulations, it will simulate
4097 correctly.
4098 UNOPTFLAT
4100 Warns that due to some construct, optimization of the specified
4101 signal is disabled. The signal specified includes a complete scope
4102 to the signal; it may be only one particular usage of a multiply
4103 instantiated block. The construct should be cleaned up to improve
4104 simulation runtime; two times better performance may be possible by
4105 fixing these warnings.
4106 Unlike the UNOPT warning, this occurs after netlist flattening, and
4108 indicates a more basic problem, as the less obvious case described
4109 under UNOPT does not apply.
4110 Often UNOPTFLAT is caused by logic that isn't truly circular as
4112 viewed by synthesis which analyzes interconnection per-bit, but is
4113 circular to simulation which analyzes per-bus:
4114 wire [2:0] x = {x[1:0], shift_in};
4116 This statement needs to be evaluated multiple times, as a change in
4118 "shift_in" requires "x" to be computed 3 times before it becomes
4119 stable. This is because a change in "x" requires "x" itself to
4120 change value, which causes the warning.
4121 For significantly better performance, split this into 2 separate
4123 signals:
4124 wire [2:0] xout = {x[1:0], shift_in};
4126 and change all receiving logic to instead receive "xout".
4128 Alternatively, change it to
4129 wire [2:0] x = {xin[1:0], shift_in};
4131 and change all driving logic to instead drive "xin".
4133 With this change this assignment needs to be evaluated only once.
4135 These sort of changes may also speed up your traditional event
4136 driven simulator, as it will result in fewer events per cycle.
4137 The most complicated UNOPTFLAT path we've seen was due to low bits
4139 of a bus being generated from an always statement that consumed
4140 high bits of the same bus processed by another series of always
4141 blocks. The fix is the same; split it into two separate signals
4142 generated from each block.
4143 Another way to resolve this warning is to add a "split_var"
4145 metacomment described above. This will cause the variable to be
4146 split internally, potentially resolving the conflict. If you run
4147 with --report-unoptflat Verilator will suggest possible candidates
4148 for "split_var".
4149 The UNOPTFLAT warning may also be due to clock enables, identified
4151 from the reported path going through a clock gating cell. To fix
4152 these, use the clock_enable meta comment described above.
4153 The UNOPTFLAT warning may also occur where outputs from a block of
4155 logic are independent, but occur in the same always block. To fix
4156 this, use the isolate_assignments meta comment described above.
4157 To assist in resolving UNOPTFLAT, the option "--report-unoptflat"
4159 can be used, which will provide suggestions for variables that can
4160 be split up, and a graph of all the nodes connected in the loop.
4161 See the Arguments section for more details.
4162 Ignoring this warning will only slow simulations, it will simulate
4164 correctly.
4165 UNOPTTHREADS
4167 Warns that the thread scheduler was unable to partition the design
4168 to fill the requested number of threads.
4169 One workaround is to request fewer threads with "--threads".
4171 Another possible workaround is to allow more MTasks in the
4173 simulation runtime, by increasing the value of
4174 --threads-max-mtasks. More MTasks will result in more communication
4175 and synchronization overhead at simulation runtime; the scheduler
4176 attempts to minimize the number of MTasks for this reason.
4177 Ignoring this warning will only slow simulations, it will simulate
4179 correctly.
4180 UNPACKED
4182 Warns that unpacked structs and unions are not supported.
4183 Ignoring this warning will make Verilator treat the structure as
4185 packed, which may make Verilator simulations differ from other
4186 simulators.
4187 UNSIGNED
4189 Warns that you are comparing a unsigned value in a way that implies
4190 it is signed, for example "X < 0" will always be true when X is
4191 unsigned.
4192 Ignoring this warning will only suppress the lint check, it will
4194 simulate correctly.
4195 UNUSED
4197 Warns that the specified signal is never used/consumed. Verilator
4198 is fairly liberal in the usage calculations; making a signal
4199 public, a signal matching --unused-regexp ("*unused*") or accessing
4200 only a single array element marks the entire signal as used.
4201 Disabled by default as this is a code style warning; it will
4203 simulate correctly.
4204 A recommended style for unused nets is to put at the bottom of a
4206 file code similar to the following:
4207 wire _unused_ok = &{1'b0,
4209 sig_not_used_a,
4210 sig_not_used_yet_b, // To be fixed
4211 1'b0};
4212 The reduction AND and constant zeros mean the net will always be
4214 zero, so won't use simulation runtime. The redundant leading and
4215 trailing zeros avoid syntax errors if there are no signals between
4216 them. The magic name "unused" (-unused-regexp) is recognized by
4217 Verilator and suppresses warnings; if using other lint tools,
4218 either teach to tool to ignore signals with "unused" in the name,
4219 or put the appropriate lint_off around the wire. Having unused
4220 signals in one place makes it easy to find what is unused, and
4221 reduces the number of lint_off pragmas, reducing bugs.
4222 USERINFO, USERWARN, USERERROR, USERFATAL
4224 A SystemVerilog elaboration-time assertion print was executed.
4225 VARHIDDEN
4227 Warns that a task, function, or begin/end block is declaring a
4228 variable by the same name as a variable in the upper level module
4229 or begin/end block (thus hiding the upper variable from being able
4230 to be used.) Rename the variable to avoid confusion when reading
4231 the code.
4232 Disabled by default as this is a code style warning; it will
4234 simulate correctly.
4235 WIDTH
4237 Warns that based on width rules of Verilog, two operands have
4238 different widths. Verilator generally can intuit the common usages
4239 of widths, and you shouldn't need to disable this message like you
4240 do with most lint programs. Generally other than simple mistakes,
4241 you have two solutions:
4242 If it's a constant 0 that's 32 bits or less, simply leave it
4244 unwidthed. Verilator considers zero to be any width needed.
4245 Concatenate leading zeros when doing arithmetic. In the statement
4247 wire [5:0] plus_one = from[5:0] + 6'd1 + carry[0];
4249 The best fix, which clarifies intent and will also make all tools
4251 happy is:
4252 wire [5:0] plus_one = from[5:0] + 6'd1 + {5'd0, carry[0]};
4254 Ignoring this warning will only suppress the lint check, it will
4256 simulate correctly.
4257 WIDTHCONCAT
4259 Warns that based on width rules of Verilog, a concatenate or
4260 replication has an indeterminate width. In most cases this
4261 violates the Verilog rule that widths inside concatenates and
4262 replicates must be sized, and should be fixed in the code.
4263 wire [63:0] concat = {1, 2};
4265 An example where this is technically legal (though still bad form)
4267 is:
4268 parameter PAR = 1;
4270 wire [63:0] concat = {PAR, PAR};
4271 The correct fix is to either size the 1 ("32'h1"), or add the width
4273 to the parameter definition ("parameter [31:0]"), or add the width
4274 to the parameter usage ("{PAR[31:0],PAR[31:0]}".
4275 The following describes the less obvious errors:
4277 Internal Error
4279 This error should never occur first, though may occur if earlier
4280 warnings or error messages have corrupted the program. If there
4281 are no other warnings or errors, submit a bug report.
4282 Unsupported: ....
4284 This error indicates that you are using a Verilog language
4285 construct that is not yet supported in Verilator. See the
4286 Limitations chapter.
4287
4289 The following deprecated items are scheduled for future removal:
4290 Pre-C++11 compiler support
4292 Verilator supports pre-C++11 compilers for non-threaded models when
4293 configured with --enable-prec11. This flag will be removed and
4294 C++11 compilers will be required for both compiling Verilator and
4295 compiling Verilated models no sooner than September 2020.
4296 SystemC 2.1 and earlier support
4298 Support for SystemC versions 2.1 and earlier and the related
4299 sc_clock variable attribute will be removed no sooner than July
4300 2020.
4301 Configuration File -msg
4303 The -msg argument to lint_off has been replaced with -rule. -msg
4304 is planned for removal no sooner than January 2021.
4305 XML locations
4307 The XML "fl" attribute has been replaced with "loc". "fl" is
4308 planned for removal no sooner than January 2021.
4309
4311 Can I contribute?
4312 Please contribute! Just file an issue asking for a merge, or ask
4313 on the forums if looking for something to help on. For more
4314 information see our contributor agreement.
4315 How commonly is Verilator used?
4317 Verilator is used by many of the largest silicon design companies,
4318 and all the way down to college projects. Verilator is a "big 4"
4319 simulator, meaning one of the 4 main SystemVerilog simulators
4320 available, namely the commercial products Synopsys' VCS (tm),
4321 Mentor's ModelSim (tm), Cadence Incisive/NC-Verilog/NC-Sim, and the
4322 open-source Verilator. The three commercial choices are commonly
4323 collectively called the "big 3" simulators.
4324 Does Verilator run under Windows?
4326 Yes, using Cygwin. Verilated output also compiles under Microsoft
4327 Visual C++, but this is not tested every release.
4328 Can you provide binaries?
4330 Verilator is available as a RPM for Debian/Ubuntu, SuSE, Fedora,
4331 and other distributions; this is done by porters and may slightly
4332 lag the primary distribution. If there isn't a binary build for
4333 your distribution, how about you set one up? Please contact the
4334 authors for assistance.
4335 Note people sometimes request binaries when they are having
4337 problems with their C++ compiler. Alas, binaries won't help this,
4338 as in the end a fully working C++ compiler is required to compile
4339 the output of Verilator.
4340 How can it be faster than (name-the-commercial-simulator)?
4342 Generally, the implied part is of the question is "... with all of
4343 the manpower they can put into developing it."
4344 Most commercial simulators have to be Verilog compliant, meaning
4346 event driven. This prevents them from being able to reorder blocks
4347 and make netlist-style optimizations, which are where most of the
4348 gains come from.
4349 Non-compliance shouldn't be scary. Your synthesis program isn't
4351 compliant, so your simulator shouldn't have to be -- and Verilator
4352 is closer to the synthesis interpretation, so this is a good thing
4353 for getting working silicon.
4354 Will Verilator output remain under my own license?
4356 Yes, it's just like using GCC on your programs; this is why
4357 Verilator uses the "GNU *Lesser* Public License Version 3" instead
4358 of the more typical "GNU Public License". See the licenses for
4359 details, but in brief, if you change Verilator itself or the header
4360 files Verilator includes, you must make the source code available
4361 under the GNU Lesser Public License. However, Verilator output
4362 (the Verilated code) only "include"s the licensed files, and so you
4363 are NOT required to release any output from Verilator.
4364 You also have the option of using the Perl Artistic License, which
4366 again does not require you release your Verilog or generated code,
4367 and also allows you to modify Verilator for internal use without
4368 distributing the modified version. But please contribute back to
4369 the community!
4370 One limit is that you cannot under either license release a
4372 commercial Verilog simulation product incorporating Verilator
4373 without making the source code available.
4374 As is standard with Open Source, contributions back to Verilator
4376 will be placed under the Verilator copyright and LGPL/Artistic
4377 license. Small test cases will be released into the public domain
4378 so they can be used anywhere, and large tests under the
4379 LGPL/Artistic, unless requested otherwise.
4380 Why is running Verilator (to create a model) so slow?
4382 Verilator needs more memory than the resulting simulator will
4383 require, as Verilator creates internally all of the state of the
4384 resulting generated simulator in order to optimize it. If it takes
4385 more than a minute or so (and you're not using --debug since debug
4386 is disk bound), see if your machine is paging; most likely you need
4387 to run it on a machine with more memory. Verilator is a full
4388 64-bit application and may use more than 4GB, but about 1GB is the
4389 maximum typically needed, and very large commercial designs have
4390 topped 16GB.
4391 How do I generate waveforms (traces) in C++?
4393 See the next question for tracing in SystemC mode.
4394 A. Add the --trace switch to Verilator, and in your top level C
4396 code, call Verilated::traceEverOn(true). Then you may use
4397 $dumpfile and $dumpvars to enable traces, same as with any Verilog
4398 simulator. See "examples/make_tracing_c".
4399 B. Or, for finer-grained control, or C++ files with multiple
4401 Verilated modules you may also create the trace purely from C++.
4402 Create a VerilatedVcdC object, and in your main loop call
4403 "trace_object->dump(time)" every time step, and finally call
4404 "trace_object->close()". You also need to compile
4405 verilated_vcd_c.cpp and add it to your link, preferably by adding
4406 the dependencies in $(VK_GLOBAL_OBJS) to your Makefile's link rule.
4407 This is done for you if using the Verilator --exe flag. Note you
4408 can also call ->trace on multiple Verilated objects with the same
4409 trace file if you want all data to land in the same output file.
4410 #include "verilated_vcd_c.h"
4412 ...
4413 int main(int argc, char** argv, char** env) {
4414 ...
4415 Verilated::traceEverOn(true);
4416 VerilatedVcdC* tfp = new VerilatedVcdC;
4417 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
4418 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
4419 ...
4420 while (sc_time_stamp() < sim_time && !Verilated::gotFinish()) {
4421 main_time += #;
4422 tfp->dump(main_time);
4423 }
4424 tfp->close();
4425 }
4426 How do I generate waveforms (traces) in SystemC?
4428 A. Add the --trace switch to Verilator, and in your top level
4429 sc_main, call Verilated::traceEverOn(true). Then you may use
4430 $dumpfile and $dumpvars to enable traces, same as with any Verilog
4431 simulator, see the non-SystemC example in
4432 "examples/make_tracing_c". This will trace only the module
4433 containing the $dumpvar.
4434 B. Or, you may create a trace purely from SystemC, which may trace
4436 all Verilated designs in the SystemC model. Create a VerilatedVcdSc
4437 object as you would create a normal SystemC trace file. For an
4438 example, see the call to VerilatedVcdSc in the
4439 examples/make_tracing_sc/sc_main.cpp file of the distribution, and
4440 below.
4441 Alternatively you may use the C++ trace mechanism described in the
4443 previous question, however the timescale and timeprecision will not
4444 inherited from your SystemC settings.
4445 You also need to compile verilated_vcd_sc.cpp and
4447 verilated_vcd_c.cpp and add them to your link, preferably by adding
4448 the dependencies in $(VK_GLOBAL_OBJS) to your Makefile's link rule.
4449 This is done for you if using the Verilator --exe flag.
4450 Note you can also call ->trace on multiple Verilated objects with
4452 the same trace file if you want all data to land in the same output
4453 file.
4454 #include "verilated_vcd_sc.h"
4456 ...
4457 int main(int argc, char** argv, char** env) {
4458 ...
4459 Verilated::traceEverOn(true);
4460 VerilatedVcdSc* tfp = new VerilatedVcdSc;
4461 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
4462 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
4463 ...
4464 sc_start(1);
4465 ...
4466 tfp->close();
4467 }
4468 How do I generate FST waveforms (traces) in C++?
4470 FST a format by GTKWave. This version provides a basic FST
4471 support. To dump FST format, add the --trace-fst switch to
4472 Verilator and either A. use $dumpfile/$dumpvars in Verilog as
4473 described in the VCD example above, or B. in C++ change the include
4474 described in the VCD example above:
4475 #include "verilated_fst_c.h"
4477 VerilatedFstC* tfp = new VerilatedFstC;
4478 Note that currently supporting both FST and VCD in a single
4480 simulation is impossible, but such requirement should be rare.
4481 How do I generate FST waveforms (aka dumps or traces) in SystemC?
4483 The FST library from GTKWave does not currently support SystemC;
4484 use VCD format instead.
4485 How do I view waveforms (aka dumps or traces)?
4487 Verilator makes standard VCD (Value Change Dump) and FST files.
4488 VCD files are viewable with the public domain GTKWave (recommended)
4489 or Dinotrace (legacy) programs, or any of the many commercial
4490 offerings; FST is supported by GTKWave only.
4491 How do I reduce the size of large waveform (trace) files?
4493 First, instead of calling VerilatedVcdC->open at the beginning of
4494 time, delay calling it until the time stamp where you want to
4495 tracing to begin. Likewise you can also call VerilatedVcdC->open
4496 before the end of time (perhaps a short period after you detect a
4497 verification error.)
4498 Next, add /*verilator tracing_off*/ to any very low level modules
4500 you never want to trace (such as perhaps library cells). Finally,
4501 use the --trace-depth option to limit the depth of tracing, for
4502 example --trace-depth 1 to see only the top level signals.
4503 Also be sure you write your trace files to a local solid-state
4505 disk, instead of to a network disk. Network disks are generally
4506 far slower.
4507 How do I do coverage analysis?
4509 Verilator supports both block (line) coverage and user inserted
4510 functional coverage.
4511 First, run verilator with the --coverage option. If you're using
4513 your own makefile, compile the model with the GCC flag
4514 -DVM_COVERAGE (if using Verilator's, it will do this for you.)
4515 At the end of your test, call VerilatedCov::write passing the name
4517 of the coverage data file (typically "logs/coverage.dat").
4518 Run each of your tests in different directories. Each test will
4520 create a logs/coverage.dat file.
4521 After running all of your tests, verilator_coverage is executed.
4523 Verilator_coverage reads the logs/coverage.dat file(s), and creates
4524 an annotated source code listing showing code coverage details.
4525 For an example, after running 'make test' in the Verilator
4527 distribution, see the examples/make_tracing_c/logs directory. Grep
4528 for lines starting with '%' to see what lines Verilator believes
4529 need more coverage.
4530 Where is the translate_off command? (How do I ignore a construct?)
4532 Translate on/off pragmas are generally a bad idea, as it's easy to
4533 have mismatched pairs, and you can't see what another tool sees by
4534 just preprocessing the code. Instead, use the preprocessor;
4535 Verilator defines the "VERILATOR" define for you, so just wrap the
4536 code in an ifndef region:
4537 `ifndef VERILATOR
4539 Something_Verilator_Dislikes;
4540 `endif
4541 Most synthesis tools similarly define SYNTHESIS for you.
4543 Why do I get "unexpected `do'" or "unexpected `bit'" errors?
4545 Do, bit, ref, return, and other words are now SystemVerilog
4546 keywords. You should change your code to not use them to ensure it
4547 works with newer tools. Alternatively, surround them by the
4548 Verilog 2005/SystemVerilog begin_keywords pragma to indicate
4549 Verilog 2001 code.
4550 `begin_keywords "1364-2001"
4552 integer bit; initial bit = 1;
4553 `end_keywords
4554 If you want the whole file to be parsed as Verilog 2001, just
4556 create a file with
4557 `begin_keywords "1364-2001"
4559 and add it before other Verilog files on the command line. (Note
4561 this will also change the default for --prefix, so if you're not
4562 using --prefix, you will now need to.)
4563 How do I prevent my assertions from firing during reset?
4565 Call Verilated::assertOn(false) before you first call the model,
4566 then turn it back on after reset. It defaults to true. When
4567 false, all assertions controlled by --assert are disabled.
4568 Why do I get "undefined reference to `sc_time_stamp()'"?
4570 In C++ (non SystemC) code you need to define this function so that
4571 the simulator knows the current time. See the "CONNECTING TO C++"
4572 examples.
4573 Why do I get "undefined reference to `VL_RAND_RESET_I' or
4575 `Verilated::...'"?
4576 You need to link your compiled Verilated code against the
4577 verilated.cpp file found in the include directory of the Verilator
4578 kit. This is one target in the $(VK_GLOBAL_OBJS) make variable,
4579 which should be part of your Makefile's link rule. If you use
4580 --exe, this is done for you.
4581 Is the PLI supported?
4583 Only somewhat. More specifically, the common PLI-ish calls
4584 $display, $finish, $stop, $time, $write are converted to C++
4585 equivalents. You can also use the "import DPI" SystemVerilog
4586 feature to call C code (see the chapter above). There is also
4587 limited VPI access to public signals.
4588 If you want something more complex, since Verilator emits standard
4590 C++ code, you can simply write your own C++ routines that can
4591 access and modify signal values without needing any PLI interface
4592 code, and call it with $c("{any_c++_statement}").
4593 How do I make a Verilog module that contain a C++ object?
4595 You need to add the object to the structure that Verilator creates,
4596 then use $c to call a method inside your object. The
4597 test_regress/t/t_extend_class files show an example of how to do
4598 this.
4599 How do I get faster build times?
4601 When running make pass the make variable VM_PARALLEL_BUILDS=1 so
4602 that builds occur in parallel.
4603 Use a recent compiler. Newer compilers tend do be faster, with the
4605 now relatively old GCC 3.0 to 3.3 being horrible.
4606 Compile in parallel on many machines and use caching; see the web
4608 for the ccache, distcc and icecream packages. ccache will skip GCC
4609 runs between identical source builds, even across different users.
4610 You can use the OBJCACHE environment variable to use these CC
4611 wrappers. Also see the --output-split option.
4612 To reduce the compile time of classes that use a Verilated module
4614 (e.g. a top CPP file) you may wish to add /*verilator
4615 no_inline_module*/ to your top level module. This will decrease the
4616 amount of code in the model's Verilated class, improving compile
4617 times of any instantiating top level C++ code, at a relatively
4618 small cost of execution performance.
4619 Why do so many files need to recompile when I add a signal?
4621 Adding a new signal requires the symbol table to be recompiled.
4622 Verilator uses one large symbol table, as that results in 2-3 less
4623 assembly instructions for each signal access. This makes the
4624 execution time 10-15% faster, but can result in more compilations
4625 when something changes.
4626 How do I access functions/tasks in C?
4628 Use the SystemVerilog Direct Programming Interface. You write a
4629 Verilog function or task with input/outputs that match what you
4630 want to call in with C. Then mark that function as an external
4631 function. See the DPI chapter in the manual.
4632 How do I access signals in C?
4634 The best thing is to make a SystemVerilog "export DPI task" or
4635 function that accesses that signal, as described in the DPI chapter
4636 in the manual and DPI tutorials on the web. This will allow
4637 Verilator to better optimize the model and should be portable
4638 across simulators.
4639 If you really want raw access to the signals, declare the signals
4641 you will be accessing with a /*verilator public*/ comment before
4642 the closing semicolon. Then scope into the C++ class to read the
4643 value of the signal, as you would any other member variable.
4644 Signals are the smallest of 8-bit chars, 16-bit shorts, 32-bit
4646 longs, or 64-bit long longs that fits the width of the signal.
4647 Generally, you can use just uint32_t's for 1 to 32 bits, or
4648 vluint64_t for 1 to 64 bits, and the compiler will properly up-
4649 convert smaller entities.
4650 Signals wider than 64 bits are stored as an array of 32-bit
4652 uint32_t's. Thus to read bits 31:0, access signal[0], and for bits
4653 63:32, access signal[1]. Unused bits (for example bit numbers
4654 65-96 of a 65-bit vector) will always be zero. if you change the
4655 value you must make sure to pack zeros in the unused bits or core-
4656 dumps may result. (Because Verilator strips array bound checks
4657 where it believes them to be unnecessary.)
4658 In the SYSTEMC example above, if you had in our.v:
4660 input clk /*verilator public*/;
4662 // Note the placement of the semicolon above
4663 From the sc_main.cpp file, you'd then:
4665 #include "Vour.h"
4667 #include "Vour_our.h"
4668 cout << "clock is " << top->our->clk << endl;
4669 In this example, clk is a bool you can read or set as any other
4671 variable. The value of normal signals may be set, though clocks
4672 shouldn't be changed by your code or you'll get strange results.
4673 Should a module be in Verilog or SystemC?
4675 Sometimes there is a block that just interconnects cells, and have
4676 a choice as to if you write it in Verilog or SystemC. Everything
4677 else being equal, best performance is when Verilator sees all of
4678 the design. So, look at the hierarchy of your design, labeling
4679 cells as to if they are SystemC or Verilog. Then:
4680 A module with only SystemC cells below must be SystemC.
4682 A module with a mix of Verilog and SystemC cells below must be
4684 SystemC. (As Verilator cannot connect to lower-level SystemC
4685 cells.)
4686 A module with only Verilog cells below can be either, but for best
4688 performance should be Verilog. (The exception is if you have a
4689 design that is instantiated many times; in this case Verilating one
4690 of the lower modules and instantiating that Verilated cells
4691 multiple times into a SystemC module *may* be faster.)
4692
4694 First, check the coding limitations section.
4695 Next, try the --debug switch. This will enable additional internal
4697 assertions, and may help identify the problem.
4698 Finally, reduce your code to the smallest possible routine that
4700 exhibits the bug. Even better, create a test in the test_regress/t
4701 directory, as follows:
4702 cd test_regress
4704 cp -p t/t_EXAMPLE.pl t/t_BUG.pl
4705 cp -p t/t_EXAMPLE.v t/t_BUG.v
4706 There are many hits on how to write a good test in the driver.pl
4708 documentation which can be seen by running:
4709 cd $VERILATOR_ROOT # Need the original distribution kit
4711 test_regress/driver.pl --help
4712 Edit t/t_BUG.pl to suit your example; you can do anything you want in
4714 the Verilog code there; just make sure it retains the single clk input
4715 and no outputs. Now, the following should fail:
4716 cd $VERILATOR_ROOT # Need the original distribution kit
4718 cd test_regress
4719 t/t_BUG.pl # Run on Verilator
4720 t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
4721 t/t_BUG.pl --vcs # Run on a commercial simulator
4722 t/t_BUG.pl --nc|--iv|--ghdl # Likewise on other simulators
4723 The test driver accepts a number of options, many of which mirror the
4725 main Verilator option. For example the previous test could have been
4726 run with debugging enabled. The full set of test options can be seen
4727 by running driver.pl --help as shown above.
4728 Finally, report the bug using the bug tracker at
4730 <https://verilator.org/issues>. The bug will become publicly visible;
4731 if this is unacceptable, mail the bug report to "wsnyder@wsnyder.org".
4732
4734 Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group
4735 at Digital Equipment Corporation. The Verilog code that was converted
4736 to C was then merged with a C based CPU model of the Alpha processor
4737 and simulated in a C based environment called CCLI.
4738 In 1995 Verilator started being used also for Multimedia and Network
4740 Processor development inside Digital. Duane Galbi took over active
4741 development of Verilator, and added several performance enhancements.
4742 CCLI was still being used as the shell.
4743 In 1998, through the efforts of existing DECies, mainly Duane Galbi,
4745 Digital graciously agreed to release the source code. (Subject to the
4746 code not being resold, which is compatible with the GNU Public
4747 License.)
4748 In 2001, Wilson Snyder took the kit, and added a SystemC mode, and
4750 called it Verilator2. This was the first packaged public release.
4751 In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator
4753 from scratch in C++. This added many optimizations, yielding about a
4754 2-5x performance gain.
4755 In 2009, major SystemVerilog and DPI language support was added.
4757 In 2018, Verilator 4.000 was released with multithreaded support.
4759 Currently, various language features and performance enhancements are
4761 added as the need arises. Verilator is now about 3x faster than in
4762 2002, and is faster than many popular commercial simulators.
4763
4765 When possible, please instead report bugs to
4766 <https://verilator.org/issues>.
4767 Wilson Snyder <wsnyder@wsnyder.org>
4769 Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
4771
4773 Many people have provided ideas and other assistance with Verilator.
4774 The major corporate sponsors of Verilator, by providing significant
4776 contributions of time or funds include include Atmel Corporation,
4777 Cavium Inc., Compaq Corporation, Digital Equipment Corporation,
4778 Embecosm Ltd., Hicamp Systems, Intel Corporation, Mindspeed
4779 Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun
4780 Microsystems Inc., Nauticus Networks Inc., and SiCortex Inc.
4781 The people who have contributed major functionality are Byron Bradley,
4783 Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Todd Strader,
4784 Paul Wasson, Jie Xu, and Wilson Snyder. Major testers included Jeff
4785 Dutton, Jonathon Donaldson, Ralf Karge, David Hewson, Iztok Jeras, Wim
4786 Michiels, Alex Solomatnikov, Sebastien Van Cauwenberghe, Gene Weber,
4787 and Clifford Wolf.
4788 Some of the people who have provided ideas and feedback for Verilator
4790 include: David Addison, Tariq B. Ahmad, Nikana Anastasiadis, Hans Van
4791 Antwerpen, Vasu Arasanipalai, Jens Arm, Sharad Bagri, Matthew Ballance,
4792 Andrew Bardsley, Matthew Barr, Geoff Barrett, Julius Baxter, Jeremy
4793 Bennett, Michael Berman, Victor Besyakov, David Binderman, Piotr
4794 Binkowski, Johan Bjork, David Black, Tymoteusz Blazejczyk, Daniel Bone,
4795 Gregg Bouchard, Christopher Boumenot, Nick Bowler, Byron Bradley, Bryan
4796 Brady, Maarten De Braekeleer, Charlie Brej, J Briquet, Lane Brooks,
4797 John Brownlee, Jeff Bush, Lawrence Butcher, Tony Bybell, Ted Campbell,
4798 Chris Candler, Lauren Carlson, Donal Casey, Sebastien Van Cauwenberghe,
4799 Alex Chadwick, Terry Chen, Yi-Chung Chen, Enzo Chi, Robert A. Clark,
4800 Allan Cochrane, John Coiner, Gianfranco Costamagna, George Cuan, Joe
4801 DErrico, Lukasz Dalek, Laurens van Dam, Gunter Dannoritzer, Ashutosh
4802 Das, Bernard Deadman, John Demme, Mike Denio, John Deroo, Philip
4803 Derrick, John Dickol, Ruben Diez, Danny Ding, Jacko Dirks, Ivan
4804 Djordjevic, Jonathon Donaldson, Leendert van Doorn, Sebastian Dressler,
4805 Alex Duller, Jeff Dutton, Tomas Dzetkulic, Usuario Eda, Charles
4806 Eddleston, Chandan Egbert, Joe Eiler, Ahmed El-Mahmoudy, Trevor
4807 Elbourne, Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Udi
4808 Finkelstein, Brian Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi,
4809 Benjamin Gartner, Christian Gelinek, Peter Gerst, Glen Gibb, Shankar
4810 Giri, Dan Gisselquist, Sam Gladstone, Amir Gonnen, Chitlesh Goorah,
4811 Sergi Granell, Al Grant, Xuan Guo, Driss Hafdi, Neil Hamilton, Oyvind
4812 Harboe, Jannis Harder, Junji Hashimoto, Thomas Hawkins, Mitch Hayenga,
4813 Robert Henry, David Hewson, Jamey Hicks, Joel Holdsworth, Andrew Holme,
4814 Hiroki Honda, Alex Hornung, David Horton, Jae Hossell, Alan Hunter,
4815 James Hutchinson, Jamie Iles, Ben Jackson, Shareef Jalloq, Krzysztof
4816 Jankowski, HyungKi Jeong, Iztok Jeras, James Johnson, Christophe Joly,
4817 Franck Jullien, James Jung, Mike Kagen, Arthur Kahlich, Kaalia Kahn,
4818 Guy-Armand Kamendje, Vasu Kandadi, Kanad Kanhere, Patricio Kaplan,
4819 Pieter Kapsenberg, Ralf Karge, Dan Katz, Sol Katzman, Jonathan Kimmitt,
4820 Olof Kindgren, Kevin Kiningham, Dan Kirkham, Sobhan Klnv, Gernot Koch,
4821 Soon Koh, Steve Kolecki, Brett Koonce, Will Korteland, Wojciech Koszek,
4822 Varun Koyyalagunta, David Kravitz, Roland Kruse, Sergey Kvachonok, Ed
4823 Lander, Steve Lang, Stephane Laurent, Walter Lavino, Christian Leber,
4824 Larry Lee, Igor Lesik, John Li, Eivind Liland, Yu Sheng Lin, Charlie
4825 Lind, Andrew Ling, Paul Liu, Derek Lockhart, Jake Longo, Arthur Low,
4826 Stefan Ludwig, Dan Lussier, Fred Ma, Duraid Madina, Affe Mao, Julien
4827 Margetts, Mark Marshall, Alfonso Martinez, Yves Mathieu, Patrick
4828 Maupin, Jason McMullan, Elliot Mednick, Wim Michiels, Miodrag
4829 Milanovic, Wai Sum Mong, Peter Monsson, Sean Moore, Dennis Muhlestein,
4830 John Murphy, Matt Myers, Richard Myers, Dimitris Nalbantis, Peter
4831 Nelson, Bob Newgard, Cong Van Nguyen, Paul Nitza, Yossi Nivin, Pete
4832 Nixon, Lisa Noack, Mark Nodine, Andreas Olofsson, Aleksander Osman,
4833 James Pallister, Brad Parker, Dan Petrisko, Maciej Piechotka, David
4834 Pierce, Dominic Plunkett, David Poole, Mike Popoloski, Roman Popov,
4835 Rich Porter, Niranjan Prabhu, Usha Priyadharshini, Mark Jackson Pulver,
4836 Prateek Puri, Marshal Qiao, Danilo Ramos, Chris Randall, Anton Rapp,
4837 Josh Redford, Odd Magne Reitan, Frederic Requin, Frederick Requin,
4838 Alberto Del Rio, Eric Rippey, Oleg Rodionov, Paul Rolfe, Arjen
4839 Roodselaar, Tobias Rosenkranz, Jan Egil Ruud, Denis Rystsov, John
4840 Sanguinetti, Galen Seitz, Salman Sheikh, Hao Shi, Mike Shinkarovsky,
4841 Rafael Shirakawa, Jeffrey Short, Anderson Ignacio Da Silva, Rodney
4842 Sinclair, Steven Slatter, Brian Small, Garrett Smith, Wilson Snyder,
4843 Stan Sokorac, Alex Solomatnikov, Wei Song, Art Stamness, John
4844 Stevenson, Patrick Stewart, Rob Stoddard, Todd Strader, John Stroebel,
4845 Sven Stucki, Howard Su, Emerson Suguimoto, Gene Sullivan, Renga
4846 Sundararajan, Rupert Swarbrick, Yutetsu Takatsukasa, Peter Tengstrand,
4847 Wesley Terpstra, Rui Terra, Stefan Thiede, Gary Thomas, Ian Thompson,
4848 Kevin Thompson, Mike Thyer, Hans Tichelaar, Viktor Tomov, Steve Tong,
4849 Michael Tresidder, Neil Turton, Bogdan Vukobratovic, Holger Waechtler,
4850 Philipp Wagner, Stefan Wallentowitz, Shawn Wang, Paul Wasson, Greg
4851 Waters, Thomas Watts, Eugene Weber, David Welch, Thomas J Whatson, Leon
4852 Wildman, Gerald Williams, Trevor Williams, Jeff Winston, Joshua Wise,
4853 Clifford Wolf, Johan Wouters, Junyi Xi, Ding Xiaoliang, Jie Xu, Mandy
4854 Xu, Luke Yang, and Amir Yazdanbakhsh.
4855 Thanks to them, and all those we've missed including above, or wished
4857 to remain anonymous.
4858
4860 The latest version is available from <https://verilator.org>.
4861 Copyright 2003-2020 by Wilson Snyder. This program is free software;
4863 you can redistribute it and/or modify the Verilator internals under the
4864 terms of either the GNU Lesser General Public License Version 3 or the
4865 Perl Artistic License Version 2.0.
4866 All Verilog and C++/SystemC code quoted within this documentation file
4868 are released as Creative Commons Public Domain (CC0). Many example
4869 files and test files are likewise released under CC0 into effectively
4870 the Public Domain as described in the files themselves.
4871
4873 verilator_coverage, verilator_gantt, verilator_profcfunc, make,
4874 "verilator --help" which is the source for this document,
4876 and docs/internals.adoc in the distribution.
4878perl v5.32.0 2020-07-29 VERILATOR(1)