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+V Verbose version and config
203 +verilator+version Show version and exit
204
206 The following are the arguments that may be passed to Verilator itself.
207 {file.v}
209 Specifies the Verilog file containing the top module to be
210 Verilated.
211 {file.c/.cc/.cpp/.cxx}
213 Specifies optional C++ files to be linked in with the Verilog code.
214 The file path should either be absolute, or relative to where the
215 make will be executed from, or add to your makefile's VPATH the
216 appropriate directory to find the file.
217 If any C++ files are specified in this way, Verilator will include
219 a make rule that generates a module executable. Without any C++
220 files, Verilator will stop at the module__ALL.a library, and
221 presume you'll continue linking with make rules you write yourself.
222 See also the -CFLAGS option.
223 {file.a/.o/.so}
225 Specifies optional object or library files to be linked in with the
226 Verilog code, as a shorthand for -LDFLAGS "<file>". The file path
227 should either be absolute, or relative to where the make will be
228 executed from, or add to your makefile's VPATH the appropriate
229 directory to find the file.
230 If any files are specified in this way, Verilator will include a
232 make rule that uses these files when linking the module executable.
233 This generally is only useful when used with the --exe option.
234 +1364-1995ext+ext
236 +1364-2001ext+ext
237 +1364-2005ext+ext
238 +1800-2005ext+ext
239 +1800-2009ext+ext
240 +1800-2012ext+ext
241 +1800-2017ext+ext
242 Specifies the language standard to be used with a specific filename
243 extension, ext.
244 For compatibility with other simulators, see also the synonyms
246 "+verilog1995ext+"ext, "+verilog2001ext+"ext, and
247 "+systemverilogext+"ext.
248 For any source file, the language specified by these options takes
250 precedence over any language specified by the "--default-language"
251 or "--language" options.
252 These options take effect in the order they are encountered. Thus
254 the following would use Verilog 1995 for "a.v" and Verilog 2001 for
255 "b.v".
256 verilator ... +1364-1995ext+v a.v +1364-2001ext+v b.v
258 These flags are only recommended for legacy mixed language designs,
260 as the preferable option is to edit the code to repair new
261 keywords, or add appropriate "`begin_keywords".
262 Note "`begin_keywords" is a SystemVerilog construct, which
264 specifies only which the set of keywords is to be recognized.
265 Whatever set is chosen, the semantics will be those of
266 SystemVerilog. By contrast "+1364-1995ext+" etc. specify both the
267 syntax and semantics to be used.
268 --assert
270 Enable all assertions.
271 --autoflush
273 After every $display or $fdisplay, flush the output stream. This
274 ensures that messages will appear immediately but may reduce
275 performance; for best performance call "fflush(stdout)"
276 occasionally in the main C loop. Defaults off, which will buffer
277 output as provided by the normal C stdio calls.
278 --bbox-sys
280 Black box any unknown $system task or function calls. System tasks
281 will be simply become no-operations, and system functions will be
282 replaced by unsized zero. Arguments to such functions will be
283 parsed, but not otherwise checked. This prevents errors when
284 linting in the presence of company specific PLI calls.
285 --bbox-unsup
287 Black box some unsupported language features, currently UDP tables,
288 the cmos and tran gate primitives, deassign statements, and mixed
289 edge errors. This may enable linting the rest of the design even
290 when unsupported constructs are present.
291 --bin filename
293 Rarely needed. Override the default filename for Verilator itself.
294 When a dependency (.d) file is created, this filename will become a
295 source dependency, such that a change in this binary will have make
296 rebuild the output files.
297 -CFLAGS flags
299 Add specified C compiler flag to the generated makefiles. For
300 multiple flags either pass them as a single argument with space
301 separators quoted in the shell ("-CFLAGS "-a -b""), or use multiple
302 -CFLAGS arguments ("-CFLAGS -a -CFLAGS -b").
303 When make is run on the generated makefile these will be passed to
305 the C++ compiler (gcc/g++/msvc++).
306 --cc
308 Specifies C++ without SystemC output mode; see also --sc.
309 --cdc
311 Experimental. Perform some clock domain crossing checks and issue
312 related warnings (CDCRSTLOGIC) and then exit; if warnings other
313 than CDC warnings are needed make a second run with --lint-only.
314 Additional warning information is also written to the file
315 {prefix}__cdc.txt.
316 Currently only checks some items that other CDC tools missed; if
318 you have interest in adding more traditional CDC checks, please
319 contact the authors.
320 --clk signal-name
322 Sometimes it is quite difficult for Verilator to distinguish clock
323 signals from other data signals. Occasionally the clock signals can
324 end up in the checking list of signals which determines if further
325 evaluation is needed. This will heavily degrade the performance of
326 a Verilated model.
327 With --clk <signal-name>, user can specified root clock into the
329 model, then Verilator will mark the signal as clocker and propagate
330 the clocker attribute automatically to other signals derived from
331 that. In this way, Verilator will try to avoid taking the clocker
332 signal into checking list.
333 Note signal-name is specified by the RTL hierarchy path. For
335 example, v.foo.bar. If the signal is the input to top-module, the
336 directly the signal name. If you find it difficult to find the
337 exact name, try to use "/*verilator clocker*/" in RTL file to mark
338 the signal directly.
339 If clock signals are assigned to vectors and then later used
341 individually, Verilator will attempt to decompose the vector and
342 connect the single-bit clock signals directly. This should be
343 transparent to the user.
344 --make make-system
346 Generates a script for the specified make system.
347 Supported make systems are gmake and cmake. Both can be specified.
349 If no make system is specified, gmake is assumed.
350 --compiler compiler-name
352 Enables tunings and workarounds for the specified C++ compiler.
353 clang
355 Tune for clang. This may reduce execution speed as it enables
356 several workarounds to avoid silly hardcoded limits in clang.
357 This includes breaking deep structures as for msvc as described
358 below.
359 gcc Tune for GNU C++, although generated code should work on almost
361 any compliant C++ compiler. Currently the default.
362 msvc
364 Tune for Microsoft Visual C++. This may reduce execution speed
365 as it enables several workarounds to avoid silly hardcoded
366 limits in MSVC++. This includes breaking deeply nested
367 parenthesized expressions into sub-expressions to avoid error
368 C1009, and breaking deep blocks into functions to avoid error
369 C1061.
370 --converge-limit loops
372 Rarely needed. Specifies the maximum number of runtime iterations
373 before creating a model failed to converge error. Defaults to 100.
374 --coverage
376 Enables all forms of coverage, alias for "--coverage-line
377 --coverage-toggle --coverage-user".
378 --coverage-line
380 Specifies basic block line coverage analysis code should be
381 inserted.
382 Coverage analysis adds statements at each code flow change point,
384 which are the branches of IF and CASE statements, a super-set of
385 normal Verilog Line Coverage. At each such branch a unique counter
386 is incremented. At the end of a test, the counters along with the
387 filename and line number corresponding to each counter are written
388 into logs/coverage.dat.
389 Verilator automatically disables coverage of branches that have a
391 $stop in them, as it is assumed $stop branches contain an error
392 check that should not occur. A /*verilator coverage_block_off*/
393 comment will perform a similar function on any code in that block
394 or below, or /*verilator coverage_on/coverage_off*/ will disable
395 coverage around lines of code.
396 Note Verilator may over-count combinatorial (non-clocked) blocks
398 when those blocks receive signals which have had the UNOPTFLAT
399 warning disabled; for most accurate results do not disable this
400 warning when using coverage.
401 --coverage-toggle
403 Specifies signal toggle coverage analysis code should be inserted.
404 Every bit of every signal in a module has a counter inserted. The
406 counter will increment on every edge change of the corresponding
407 bit.
408 Signals that are part of tasks or begin/end blocks are considered
410 local variables and are not covered. Signals that begin with
411 underscores, are integers, or are very wide (>256 bits total
412 storage across all dimensions) are also not covered.
413 Hierarchy is compressed, such that if a module is instantiated
415 multiple times, coverage will be summed for that bit across ALL
416 instantiations of that module with the same parameter set. A
417 module instantiated with different parameter values is considered a
418 different module, and will get counted separately.
419 Verilator makes a minimally-intelligent decision about what clock
421 domain the signal goes to, and only looks for edges in that clock
422 domain. This means that edges may be ignored if it is known that
423 the edge could never be seen by the receiving logic. This
424 algorithm may improve in the future. The net result is coverage
425 may be lower than what would be seen by looking at traces, but the
426 coverage is a more accurate representation of the quality of
427 stimulus into the design.
428 There may be edges counted near time zero while the model
430 stabilizes. It's a good practice to zero all coverage just before
431 releasing reset to prevent counting such behavior.
432 A /*verilator coverage_off/on */ comment pair can be used around
434 signals that do not need toggle analysis, such as RAMs and register
435 files.
436 --coverage-underscore
438 Enable coverage of signals that start with an underscore. Normally,
439 these signals are not covered. See also --trace-underscore.
440 --coverage-user
442 Enables user inserted functional coverage. Currently, all
443 functional coverage points are specified using SVA which must be
444 separately enabled with --assert.
445 For example, the following statement will add a coverage point,
447 with the comment "DefaultClock":
448 DefaultClock: cover property (@(posedge clk) cyc==3);
450 -Dvar=value
452 Defines the given preprocessor symbol, without allowing. Similar
453 to +define; +define is fairly standard across Verilog tools while
454 -D is an alias for GCC compatibility.
455 --debug
457 Select the debug built image of Verilator (if available), and
458 enable more internal assertions (equivalent to "--debug-check"),
459 debugging messages (equivalent to "--debugi 4"), and intermediate
460 form dump files (equivalent to "--dump-treei 3").
461 --debug-check
463 Rarely needed. Enable internal debugging assertion checks, without
464 changing debug verbosity. Enabled automatically when --debug
465 specified.
466 --no-debug-leak
468 In --debug mode, by default Verilator intentionally leaks AstNode's
469 instead of freeing them, so that each node pointer is unique in the
470 resulting tree files and dot files.
471 This option disables the leak. This may avoid out-of-memory errors
473 when Verilating large models in --debug mode.
474 Outside of --debug mode, AstNode's should never be leaked and this
476 option has no effect.
477 --debugi level
479 --debugi-srcfile level
480 Rarely needed - for developer use. Set internal debugging level
481 globally to the specified debug level (1-10) or set the specified
482 Verilator source file to the specified level (e.g.
483 "--debugi-V3Width 9"). Higher levels produce more detailed
484 messages.
485 --default-language value
487 Select the language to be used by default when first processing
488 each Verilog file. The language value must be "1364-1995",
489 "1364-2001", "1364-2005", "1800-2005", "1800-2009", "1800-2012" or
490 "1800-2017".
491 Any language associated with a particular file extension (see the
493 various +langext+ options) will be used in preference to the
494 language specified by --default-language.
495 The --default-language flag is only recommended for legacy code
497 using the same language in all source files, as the preferable
498 option is to edit the code to repair new keywords, or add
499 appropriate "`begin_keywords". For legacy mixed language designs,
500 the various +langext+ options should be used.
501 If no language is specified, either by this flag or +langext+
503 options, then the latest SystemVerilog language (IEEE 1800-2017) is
504 used.
505 +define+var=value
507 +define+var=value+var2=value2...
508 Defines the given preprocessor symbol, or multiple symbols if
509 separated by plusses. Similar to -D; +define is fairly standard
510 across Verilog tools while -D is an alias for GCC compatibility.
511 --dpi-hdr-only
513 Only generate the DPI header file. This option has no effect on
514 the name or location of the file.
515 --dump-defines
517 With -E, suppress normal output, and instead print a list of all
518 defines existing at the end of pre-processing the input files.
519 Similar to GCC "-dM" option. This also gives you a way of finding
520 out what is predefined in Verilator using the command:
521 touch foo.v ; verilator -E --dump-defines foo.v
523 --dump-tree
525 Rarely needed. Enable writing .tree debug files with dumping level
526 3, which dumps the standard critical stages. For details on the
527 format see the Verilator Internals manual. --dump-tree is enabled
528 automatically with --debug, so "--debug --no-dump-tree" may be
529 useful if the dump files are large and not desired.
530 --dump-treei level
532 --dump-treei-srcfile level
533 Rarely needed - for developer use. Set internal tree dumping level
534 globally to a specific dumping level or set the specified Verilator
535 source file to the specified tree dumping level (e.g.
536 "--dump-treei-V3Order 9"). Level 0 disbles dumps and is equivalent
537 to "--no-dump-tree". Level 9 enables dumping of every stage.
538 -E Preprocess the source code, but do not compile, as with 'gcc -E'.
540 Output is written to standard out. Beware of enabling debugging
541 messages, as they will also go to standard out.
542 --error-limit value
544 After this number of errors are encountered during Verilator run,
545 exit. Warnings are not counted in this limit. Defaults to 50.
546 Does not affect simulation runtime errors, for those see
548 +verilator+error+limit.
549 --exe
551 Generate an executable. You will also need to pass additional .cpp
552 files on the command line that implement the main loop for your
553 simulation.
554 -F file
556 Read the specified file, and act as if all text inside it was
557 specified as command line parameters. Any relative paths are
558 relative to the directory containing the specified file. See also
559 -f. Note -F is fairly standard across Verilog tools.
560 -f file
562 Read the specified file, and act as if all text inside it was
563 specified as command line parameters. Any relative paths are
564 relative to the current directory. See also -F. Note -f is fairly
565 standard across Verilog tools.
566 The file may contain // comments which are ignored to the end of
568 the line. Any $VAR, $(VAR), or ${VAR} will be replaced with the
569 specified environment variable.
570 -FI file
572 Force include of the specified C++ header file. All generated C++
573 files will insert a #include of the specified file before any other
574 includes. The specified file might be used to contain define
575 prototypes of custom VL_VPRINTF functions, and may need to include
576 verilatedos.h as this file is included before any other standard
577 includes.
578 -Gname=value
580 Overwrites the given parameter of the toplevel module. The value is
581 limited to basic data literals:
582 Verilog integer literals
584 The standard verilog integer literals are supported, so values
585 like 32'h8, 2'b00, 4 etc. are allowed. Care must be taken that
586 the single quote (I') is properly escaped in an interactive
587 shell, e.g., as -GWIDTH=8\'hx.
588 C integer literals
590 It is also possible to use C integer notation, including
591 hexadecimal (0x..), octal (0..) or binary (0b..) notation.
592 Double literals
594 Double literals must contain a dot (.) and/or an exponent (e).
595 Strings
597 String must in double quotes (""). On the command line it is
598 required to escape them properly, e.g. as -GSTR="\"My String\""
599 or -GSTR='"My String"'.
600 --gate-stmts value
602 Rarely needed. Set the maximum number of statements that may be
603 present in an equation for the gate substitution optimization to
604 inline that equation.
605 --gdb
607 Run Verilator underneath an interactive GDB (or VERILATOR_GDB
608 environment variable value) session. See also --gdbbt.
609 --gdbbt
611 If --debug is specified, run Verilator underneath a GDB process and
612 print a backtrace on exit, then exit GDB immediately. Without
613 --debug or if GDB doesn't seem to work, this flag is ignored.
614 Intended for easy creation of backtraces by users; otherwise see
615 the --gdb flag.
616 --generate-key
618 Generate a true-random key suitable for use with --protect-key,
619 print it, and exit immediately.
620 --getenv variable
622 If the variable is declared in the environment, print it and exit
623 immediately. Otherwise, if it's built into Verilator (e.g.
624 VERILATOR_ROOT), print that and exit immediately. Otherwise, print
625 a newline and exit immediately. This can be useful in makefiles.
626 See also -V, and the various *.mk files.
627 --help
629 Displays this message and program version and exits.
630 -Idir
632 See -y.
633 --if-depth value
635 Rarely needed. Set the depth at which the IFDEPTH warning will
636 fire, defaults to 0 which disables this warning.
637 +incdir+dir
639 See -y.
640 --inhibit-sim
642 Rarely needed. Create a "inhibitSim(bool)" function to enable and
643 disable evaluation. This allows an upper level testbench to
644 disable modules that are not important in a given simulation,
645 without needing to recompile or change the SystemC modules
646 instantiated.
647 --inline-mult value
649 Tune the inlining of modules. The default value of 2000 specifies
650 that up to 2000 new operations may be added to the model by
651 inlining, if more than this number of operations would result, the
652 module is not inlined. Larger values, or a value < 1 will inline
653 everything, will lead to longer compile times, but potentially
654 faster simulation runtimes. This setting is ignored for very small
655 modules; they will always be inlined, if allowed.
656 -LDFLAGS flags
658 Add specified C linker flags to the generated makefiles. For
659 multiple flags either pass them as a single argument with space
660 separators quoted in the shell ("-LDFLAGS "-a -b""), or use
661 multiple -LDFLAGS arguments ("-LDFLAGS -a -LDFLAGS -b").
662 When make is run on the generated makefile these will be passed to
664 the C++ linker (ld) *after* the primary file being linked. This
665 flag is called -LDFLAGS as that's the traditional name in
666 simulators; it's would have been better called LDLIBS as that's the
667 Makefile variable it controls. (In Make, LDFLAGS is before the
668 first object, LDLIBS after. -L libraries need to be in the Make
669 variable LDLIBS, not LDFLAGS.)
670 --l2-name value
672 Instead of using the module name when showing Verilog scope, use
673 the name provided. This allows simplifying some Verilator-embedded
674 modeling methodologies. Default is an l2-name matching the top
675 module. The default before 3.884 was "--l2-name v"
676 For example, the program "module t; initial $display("%m");
678 endmodule" will show by default "t". With "--l2-name v" it will
679 print "v".
680 --language value
682 A synonym for "--default-language", for compatibility with other
683 tools and earlier versions of Verilator.
684 +libext+ext+ext...
686 Specify the extensions that should be used for finding modules. If
687 for example module x is referenced, look in x.ext. Note +libext+
688 is fairly standard across Verilog tools. Defaults to .v and .sv.
689 --lint-only
691 Check the files for lint violations only, do not create any other
692 output.
693 You may also want the -Wall option to enable messages that are
695 considered stylistic and not enabled by default.
696 If the design is not to be completely Verilated see also the
698 --bbox-sys and --bbox-unsup options.
699 --max-num-width value
701 Set the maximum number literal width (e.g. in 1024'd22 this it the
702 1024). Defaults to 64K.
703 --MMD =item --no-MMD
705 Enable/disable creation of .d dependency files, used for make
706 dependency detection, similar to gcc -MMD option. By default this
707 option is enabled for --cc or --sp modes.
708 --MP
710 When creating .d dependency files with --MMD, make phony targets.
711 Similar to gcc -MP option.
712 --Mdir directory
714 Specifies the name of the Make object directory. All generated
715 files will be placed in this directory. If not specified,
716 "obj_dir" is used. The directory is created if it does not exist
717 and the parent directories exist; otherwise manually create the
718 Mdir before calling Verilator.
719 --mod-prefix topname
721 Specifies the name to prepend to all lower level classes. Defaults
722 to the same as --prefix.
723 --no-clk signal-name
725 Prevent the specified signal from being marked as clock. See
726 "--clk".
727 --no-decoration
729 When creating output Verilated code, minimize comments, whitespace,
730 symbol names and other decorative items, at the cost of greatly
731 reduced readability. This may assist C++ compile times. This will
732 not typically change the ultimate model's performance, but may in
733 some cases.
734 --no-pins64
736 Backward compatible alias for "--pins-bv 33".
737 --no-relative-cfuncs
739 Disable 'this->' references in generated functions, and instead
740 Verilator will generate absolute references starting from
741 'vlTOPp->'. This prevents V3Combine from merging functions from
742 multiple instances of the same module, so it can grow the
743 instruction stream.
744 This is a work around for old compilers. Don't set this if your C++
746 compiler supports __restrict__ properly, as GCC 4.5.x and newer do.
747 For older compilers, test if this switch gives you better
748 performance or not.
749 Compilers which don't honor __restrict__ will suspect that 'this->'
751 references and 'vlTOPp->' references may alias, and may write slow
752 code with extra loads and stores to handle the (imaginary)
753 aliasing. Using only 'vlTOPp->' references allows these old
754 compilers to produce tight code.
755 --no-skip-identical =item --skip-identical
757 Rarely needed. Disables or enables skipping execution of Verilator
758 if all source files are identical, and all output files exist with
759 newer dates. By default this option is enabled for --cc or --sp
760 modes only.
761 +notimingchecks
763 Ignored for compatibility with other simulators.
764 -O0 Disables optimization of the model.
766 -O3 Enables slow optimizations for the code Verilator itself generates
768 (as opposed to "-CFLAGS -O3" which effects the C compiler's
769 optimization. -O3 may reduce simulation runtimes at the cost of
770 compile time. This currently sets --inline-mult -1.
771 -Ooptimization-letter
773 Rarely needed. Enables or disables a specific optimizations, with
774 the optimization selected based on the letter passed. A lowercase
775 letter disables an optimization, an upper case letter enables it.
776 This is intended for debugging use only; see the source code for
777 version-dependent mappings of optimizations to -O letters.
778 -o executable
780 Specify the name for the final executable built if using --exe.
781 Defaults to the --prefix if not specified.
782 --no-order-clock-delay
784 Rarely needed. Disables a bug fix for ordering of clock enables
785 with delayed assignments. This flag should only be used when
786 suggested by the developers.
787 --output-split statements
789 Enables splitting the output .cpp files into multiple outputs.
790 When a C++ file exceeds the specified number of operations, a new
791 file will be created at the next function boundary. In addition,
792 any infrequently executed "cold" routines will be placed into
793 __Slow files. This accelerates compilation by as optimization can
794 be disabled on the routines in __Slow, and the remaining files can
795 be compiled on parallel machines. Using --output-split should have
796 only a trivial impact on performance. On one design --output-split
797 20000 resulted in splitting into approximately one-minute-compile
798 chunks.
799 Typically when using this, make with VM_PARALLEL_BUILDS=1, and use
801 ccache.
802 --output-split-cfuncs statements
804 Enables splitting functions in the output .cpp files into multiple
805 functions. When a generated function exceeds the specified number
806 of operations, a new function will be created. With
807 --output-split, this will enable GCC to compile faster, at a small
808 loss in performance that gets worse with decreasing split values.
809 Note that this option is stronger than --output-split in the sense
810 that --output-split will not split inside a function.
811 --output-split-ctrace statements
813 Enables splitting trace functions in the output .cpp files into
814 multiple functions. Defaults to same setting as
815 --output-split-cfuncs.
816 -P With -E, disable generation of `line markers and blank lines,
818 similar to GCC -P flag.
819 --pins64
821 Backward compatible alias for "--pins-bv 65". Note that's a 65,
822 not a 64.
823 --pins-bv width
825 Specifies SystemC inputs/outputs of greater than or equal to width
826 bits wide should use sc_bv's instead of uint32/vluint64_t's. The
827 default is "--pins-bv 65", and the value must be less than or equal
828 to 65. Versions before Verilator 3.671 defaulted to "--pins-bv
829 33". The more sc_bv is used, the worse for performance. Use the
830 "/*verilator sc_bv*/" attribute to select specific ports to be
831 sc_bv.
832 --pins-sc-uint
834 Specifies SystemC inputs/outputs of greater than 2 bits wide should
835 use sc_uint between 2 and 64. When combined with the
836 "--pins-sc-biguint" combination, it results in sc_uint being used
837 between 2 and 64 and sc_biguint being used between 65 and 512.
838 --pins-sc-biguint
840 Specifies SystemC inputs/outputs of greater than 65 bits wide
841 should use sc_biguint between 65 and 512, and sc_bv from 513
842 upwards. When combined with the "--pins-sc-uint" combination, it
843 results in sc_uint being used between 2 and 64 and sc_biguint being
844 used between 65 and 512.
845 --pins-uint8
847 Specifies SystemC inputs/outputs that are smaller than the
848 --pins-bv setting and 8 bits or less should use uint8_t instead of
849 uint32_t. Likewise pins of width 9-16 will use uint16_t instead of
850 uint32_t.
851 --pipe-filter command
853 Rarely needed and experimental. Verilator will spawn the specified
854 command as a subprocess pipe, to allow the command to perform
855 custom edits on the Verilog code before it reaches Verilator.
856 Before reading each Verilog file, Verilator will pass the file name
858 to the subprocess' stdin with 'read_verilog "<filename>"'. The
859 filter may then read the file and perform any filtering it desires,
860 and feeds the new file contents back to Verilator on stdout with
861 'Content-Length'. Output to stderr from the filter feeds through
862 to Verilator's stdout and if the filter exits with non-zero status
863 Verilator terminates. See the t/t_pipe_filter test for an example.
864 To debug the output of the filter, try using the -E option to see
866 preprocessed output.
867 --pp-comments
869 With -E, show comments in preprocessor output.
870 --prefix topname
872 Specifies the name of the top level class and makefile. Defaults
873 to V prepended to the name of the --top-module switch, or V
874 prepended to the first Verilog filename passed on the command line.
875 --prof-cfuncs
877 Modify the created C++ functions to support profiling. The
878 functions will be minimized to contain one "basic" statement,
879 generally a single always block or wire statement. (Note this will
880 slow down the executable by ~5%.) Furthermore, the function name
881 will be suffixed with the basename of the Verilog module and line
882 number the statement came from. This allows gprof or oprofile
883 reports to be correlated with the original Verilog source
884 statements. See also verilator_profcfunc.
885 --prof-threads
887 Enable gantt chart data collection for threaded builds.
888 Verilator will record the start and end time of each macro-task
890 across a number of calls to eval. (What is a macro-task? See the
891 Verilator internals document.)
892 When profiling is enabled, the simulation runtime will emit a blurb
894 of profiling data in non-human-friendly form. The "verilator_gantt"
895 script will transform this into a nicer visual format and produce
896 some related statistics.
897 --protect-key key
899 Specifies the private key for --protect-ids. For best security this
900 key should be 16 or more random bytes, a reasonable secure choice
901 is the output of "verilator --generate-key". Typically, a key would
902 be created by the user once for a given protected design library,
903 then every Verilator run for subsequent versions of that library
904 would be passed the same --protect-key. Thus, if the input Verilog
905 is similar between library versions (Verilator runs), the Verilated
906 code will likewise be mostly similar.
907 If --protect-key is not specified and a key is needed, Verilator
909 will generate a new key for every Verilator run. As the key is not
910 saved, this is best for security, but means every Verilator run
911 will give vastly different output even for identical input, perhaps
912 harming compile times (and certainly thrashing any ccache).
913 --protect-ids
915 Hash any private identifiers (variable, module, and assertion block
916 names that are not on the top level) into hashed random-looking
917 identifiers, resulting after compilation in protected library
918 binaries that expose less design information. This hashing uses
919 the provided or default --protect-key, see important details there.
920 Verilator will also create a {prefix}__idmap.xml file which
922 contains the mapping from the hashed identifiers back to the
923 original identifiers. This idmap file is to be kept private, and is
924 to assist mapping any simulation runtime design assertions,
925 coverage, or trace information, which will report the hashed
926 identifiers, back to the original design's identifier names.
927 Using DPI imports/exports is allowed and generally relatively safe
929 in terms of information disclosed, which is limited to the DPI
930 function prototyptes. Use of the VPI is not recommended as many
931 design details may be exposed, and an INSECURE warning will be
932 issued.
933 --protect-lib name
935 Produces C++, Verilog wrappers and a Makefile which can in turn
936 produce a DPI library which can be used by Verilator or other
937 simulators along with the corresponding Verilog wrapper. The
938 Makefile will build both a static and dynamic version of the
939 library named libname.a and libname.so respectively. This is done
940 because some simulators require a dynamic library, but the static
941 library is arguably easier to use if possible. --protect-lib
942 implies --protect-ids.
943 This allows for the secure delivery of sensitive IP without the
945 need for encrypted RTL (i.e. IEEE P1735). See
946 examples/make_protect_lib in the distribution for a demonstration
947 of how to build and use the DPI library.
948 --private
950 Opposite of --public. Is the default; this option exists for
951 backwards compatibility.
952 --public
954 This is only for historical debug use. Using it may result in mis-
955 simulation of generated clocks.
956 Declares all signals and modules public. This will turn off signal
958 optimizations as if all signals had a /*verilator public*/ comments
959 and inlining. This will also turn off inlining as if all modules
960 had a /*verilator public_module*/, unless the module specifically
961 enabled it with /*verilator inline_module*/.
962 --public-flat-rw
964 Declares all variables, ports and wires public as if they had
965 /*verilator public_flat_rw*/ comments. This will make them VPI
966 accessible by their flat name, but not turn off module inlining.
967 This is particularly useful in combination with --vpi. This may
968 also in some rare cases result in mis-simulation of generated
969 clocks. Instead of this global switch, marking only those signals
970 that need public_flat_rw is typically significantly better
971 performing.
972 -pvalue+name=value
974 Overwrites the given parameter(s) of the toplevel module. See -G
975 for a detailed description.
976 --quiet-exit
978 When exiting due to an error, do not display the "Command Failed"
979 message.
980 --relative-includes
982 When a file references an include file, resolve the filename
983 relative to the path of the referencing file, instead of relative
984 to the current directory.
985 --report-unoptflat
987 Extra diagnostics for UNOPTFLAT warnings. This includes for each
988 loop, the 10 widest variables in the loop, and the 10 most fanned
989 out variables in the loop. These are candidates for splitting into
990 multiple variables to break the loop.
991 In addition produces a GraphViz DOT file of the entire strongly
993 connected components within the source associated with each loop.
994 This is produced irrespective of whether --dump-tree is set. Such
995 graphs may help in analyzing the problem, but can be very large
996 indeed.
997 Various commands exist for viewing and manipulating DOT files. For
999 example the dot command can be used to convert a DOT file to a PDF
1000 for printing. For example:
1001 dot -Tpdf -O Vt_unoptflat_simple_2_35_unoptflat.dot
1003 will generate a PDF Vt_unoptflat_simple_2_35_unoptflat.dot.pdf from
1005 the DOT file.
1006 --rr
1008 Run Verilator and record with rr. See: rr-project.org.
1009 --savable
1011 Enable including save and restore functions in the generated model.
1012 The user code must create a VerilatedSerialize or
1014 VerilatedDeserialze object then calling the << or >> operators on
1015 the generated model and any other data the process needs
1016 saved/restored. These functions are not thread safe, and are
1017 typically called only by a main thread.
1018 For example:
1020 void save_model(const char* filenamep) {
1022 VerilatedSave os;
1023 os.open(filenamep);
1024 os << main_time; // user code must save the timestamp, etc
1025 os << *topp;
1026 }
1027 void restore_model(const char* filenamep) {
1028 VerilatedRestore os;
1029 os.open(filenamep);
1030 os >> main_time;
1031 os >> *topp;
1032 }
1033 --sc
1035 Specifies SystemC output mode; see also --cc.
1036 --stats
1038 Creates a dump file with statistics on the design in
1039 {prefix}__stats.txt.
1040 --stats-vars
1042 Creates more detailed statistics, including a list of all the
1043 variables by size (plain --stats just gives a count). See --stats,
1044 which is implied by this.
1045 -sv Specifies SystemVerilog language features should be enabled;
1047 equivalent to "--language 1800-2005". This option is selected by
1048 default, it exists for compatibility with other simulators.
1049 +systemverilogext+ext
1051 A synonym for "+1800-2017ext+"ext.
1052 --threads threads
1054 --no-threads
1055 With --threads 0 or --no-threads, the default, the generated model
1056 is not thread safe. With --threads 1, the generated model is single
1057 threaded but may run in a multithreaded environment. With --threads
1058 N, where N >= 2, the model is generated to run multithreaded on up
1059 to N threads. See "MULTITHREADING".
1060 --threads-dpi all
1062 --threads-dpi none
1063 --threads-dpi pure
1064 When using --dpi with --threads, control what DPI tasks are thread
1065 safe.
1066 With --threads-dpi all, enable Verilator to assume all DPI imports
1068 are threadsafe, and to use thread-local storage for communication
1069 with DPI, potentially improving performance. Any DPI libraries need
1070 appropriate mutexes to avoid undefined behavior.
1071 With --threads-dpi none, Verilator assume DPI imports are not
1073 thread safe, and Verilator will serialize calls to DPI imports by
1074 default, potentially harming performance.
1075 With --threads-dpi pure, the default, Verilator assumes DPI pure
1077 imports are threadsafe, but non-pure DPI imports are not.
1078 --threads-max-mtasks value
1080 Rarely needed. When using --threads, specify the number of mtasks
1081 the model is to be partitioned into. If unspecified, Verilator
1082 approximates a good value.
1083 --top-module topname
1085 When the input Verilog contains more than one top level module,
1086 specifies the name of the top level Verilog module to become the
1087 top, and sets the default for if --prefix is not used. This is not
1088 needed with standard designs with only one top. See also the
1089 MULTITOP warning section.
1090 --trace
1092 Adds waveform tracing code to the model using VCD format. This
1093 overrides "--trace-fst".
1094 Verilator will generate additional {prefix}__Trace*.cpp files that
1096 will need to be compiled. In addition verilated_vcd_sc.cpp (for
1097 SystemC traces) or verilated_vcd_c.cpp (for both) must be compiled
1098 and linked in. If using the Verilator generated Makefiles, these
1099 files will be added as source targets for you. If you're not using
1100 the Verilator makefiles, you will need to add these to your
1101 Makefile manually.
1102 Having tracing compiled in may result in some small performance
1104 losses, even when waveforms are not turned on during model
1105 execution.
1106 --trace-coverage
1108 With --trace and --coverage-*, enable tracing to include a traced
1109 signal for every --coverage-line or --coverage-user inserted
1110 coverage point, to assist in debugging coverage items. Note
1111 --coverage-toggle does not get additional signals added, as the
1112 original signals being toggle-analyzed are already visible.
1113 The added signal will be a 32-bit value which will increment on
1115 each coverage occurrence. Due to this, this option may greatly
1116 increase trace file sizes and simulation runtime.
1117 --trace-depth levels
1119 Specify the number of levels deep to enable tracing, for example
1120 --trace-level 1 to only see the top level's signals. Defaults to
1121 the entire model. Using a small number will decrease visibility,
1122 but greatly improve simulation runtime and trace file size.
1123 --trace-fst
1125 Enable FST waveform tracing in the model. This overrides "--trace"
1126 and "--trace-fst-thread". See also "--trace-fst-thread".
1127 --trace-fst-thread
1129 Enable FST waveform tracing in the model, using a separate thread.
1130 This is typically faster in simulation runtime but slower in total
1131 computes than "--trace-fst". This overrides "--trace" and
1132 "--trace-fst".
1133 --trace-max-array depth
1135 Rarely needed. Specify the maximum array depth of a signal that
1136 may be traced. Defaults to 32, as tracing large arrays may greatly
1137 slow traced simulations.
1138 --trace-max-width width
1140 Rarely needed. Specify the maximum bit width of a signal that may
1141 be traced. Defaults to 256, as tracing large vectors may greatly
1142 slow traced simulations.
1143 --no-trace-params
1145 Disable tracing of parameters.
1146 --trace-structs
1148 Enable tracing to show the name of packed structure, union, and
1149 packed array fields, rather than a single combined packed bus. Due
1150 to VCD file format constraints this may result in significantly
1151 slower trace times and larger trace files.
1152 --trace-underscore
1154 Enable tracing of signals that start with an underscore. Normally,
1155 these signals are not output during tracing. See also
1156 --coverage-underscore.
1157 -Uvar
1159 Undefines the given preprocessor symbol.
1160 --unroll-count loops
1162 Rarely needed. Specifies the maximum number of loop iterations
1163 that may be unrolled. See also BLKLOOPINIT warning.
1164 --unroll-stmts statements
1166 Rarely needed. Specifies the maximum number of statements in a
1167 loop for that loop to be unrolled. See also BLKLOOPINIT warning.
1168 --unused-regexp regexp
1170 Rarely needed. Specifies a simple regexp with * and ? that if a
1171 signal name matches will suppress the UNUSED warning. Defaults to
1172 "*unused*". Setting it to "" disables matching.
1173 -V Shows the verbose version, including configuration information
1175 compiled into Verilator. (Similar to perl -V.) See also --getenv.
1176 -v filename
1178 Read the filename as a Verilog library. Any modules in the file
1179 may be used to resolve cell instantiations in the top level module,
1180 else ignored. Note -v is fairly standard across Verilog tools.
1181 +verilog1995ext+ext
1183 +verilog2001ext+ext
1184 Synonyms for "+1364-1995ext+"ext and "+1364-2001ext+"ext
1185 respectively
1186 --version
1188 Displays program version and exits.
1189 --vpi
1191 Enable use of VPI and linking against the verilated_vpi.cpp files.
1192 -Wall
1194 Enable all code style warnings, including code style warnings that
1195 are normally disabled by default. Equivelent to "-Wwarn-lint
1196 -Wwarn-style". Excludes some specialty warnings, i.e.
1197 IMPERFECTSCH.
1198 -Werror-message
1200 Convert the specified warning message into an error message. This
1201 is generally to discourage users from violating important site-wide
1202 rules, for example "-Werror-NOUNOPTFLAT".
1203 -Wfuture-message
1205 Rarely needed. Suppress unknown Verilator comments or warning
1206 messages with the given message code. This is used to allow code
1207 written with pragmas for a later version of Verilator to run under
1208 a older version; add -Wfuture- arguments for each message code or
1209 comment that the new version supports which the older version does
1210 not support.
1211 -Wno-message
1213 Disable the specified warning message, or in some cases where noted
1214 here disable an error. This will override any lint_on directives
1215 in the source, i.e. the warning will still not be printed.
1216 -Wno-context
1218 Disable showing the suspected context of the warning message by
1219 quoting the source text at the suspected location. This is used to
1220 appease tools which process the error messages may get confused by
1221 lines from the original source.
1222 -Wno-fatal
1224 When warnings are detected, print them, but do not exit the
1225 simulator.
1226 Having warning messages in builds is sloppy. It is strongly
1228 recommended you cleanup your code, use inline lint_off, or use
1229 -Wno-... flags rather than using this option.
1230 -Wno-lint
1232 Disable all lint related warning messages, and all style warnings.
1233 This is equivalent to "-Wno-ALWCOMBORDER -Wno-BSSPACE
1234 -Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASEWITHX
1235 -Wno-CMPCONST -Wno-COLONPLUS -Wno-ENDLABEL -Wno-IMPLICIT
1236 -Wno-LITENDIAN -Wno-PINCONNECTEMPTY -Wno-PINMISSING
1237 -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED
1238 -Wno-WIDTH" plus the list shown for Wno-style.
1239 It is strongly recommended you cleanup your code rather than using
1241 this option, it is only intended to be use when running test-cases
1242 of code received from third parties.
1243 -Wno-style
1245 Disable all code style related warning messages (note by default
1246 they are already disabled). This is equivalent to
1247 "-Wno-DECLFILENAME -Wno-DEFPARAM -Wno-IMPORTSTAR -Wno-INCABSPATH
1248 -Wno-PINCONNECTEMPTY -Wno-PINNOCONNECT -Wno-SYNCASYNCNET
1249 -Wno-UNDRIVEN -Wno-UNUSED -Wno-VARHIDDEN".
1250 -Wpedantic
1252 Warn on any construct demanded by IEEE, and disable all Verilator
1253 extensions that may interfere with IEEE compliance to the standard
1254 defined with --language (etc). Similar to GCC's -Wpedantic.
1255 Rarely used, and intended only for strict compliance tests.
1256 -Wwarn-message
1258 Enables the specified warning message.
1259 -Wwarn-lint
1261 Enable all lint related warning messages (note by default they are
1262 already enabled), but do not affect style messages. This is
1263 equivalent to "-Wwarn-ALWCOMBORDER -Wwarn-BSSPACE
1264 -Wwarn-CASEINCOMPLETE -Wwarn-CASEOVERLAP -Wwarn-CASEX
1265 -Wwarn-CASEWITHX -Wwarn-CMPCONST -Wwarn-COLONPLUS -Wwarn-ENDLABEL
1266 -Wwarn-IMPLICIT -Wwarn-LITENDIAN -Wwarn-PINMISSING -Wwarn-REALCVT
1267 -Wwarn-UNSIGNED -Wwarn-WIDTH".
1268 -Wwarn-style
1270 Enable all code style related warning messages. This is equivalent
1271 to "-Wwarn ASSIGNDLY -Wwarn-DECLFILENAME -Wwarn-DEFPARAM
1272 -Wwarn-INCABSPATH -Wwarn-PINNOCONNECT -Wwarn-SYNCASYNCNET
1273 -Wwarn-UNDRIVEN -Wwarn-UNUSED -Wwarn-VARHIDDEN".
1274 --x-assign 0
1276 --x-assign 1
1277 --x-assign fast (default)
1278 --x-assign unique
1279 Controls the two-state value that is replaced when an assignment to
1280 X is encountered. "--x-assign fast", the default, converts all Xs
1281 to whatever is best for performance. "--x-assign 0" converts all
1282 Xs to 0s, and is also fast. "--x-assign 1" converts all Xs to 1s,
1283 this is nearly as fast as 0, but more likely to find reset bugs as
1284 active high logic will fire. "--x-assign unique" will call a
1285 function to determine the value, this allows randomization of all
1286 Xs to find reset bugs and is the slowest, but safest for finding
1287 reset bugs in code.
1288 If using --x-assign unique, you may want to seed your random number
1290 generator such that each regression run gets a different
1291 randomization sequence. Use the system's srand48() or for Windows
1292 srand() function to do this. You'll probably also want to print
1293 any seeds selected, and code to enable rerunning with that same
1294 seed so you can reproduce bugs.
1295 Note. This option applies only to variables which are explicitly
1297 assigned to X in the Verilog source code. Initial values of clocks
1298 are set to 0 unless --x-initial-edge is specified. Initial values
1299 of all other state holding variables are controlled with
1300 --x-initial.
1301 --x-initial 0
1303 --x-initial fast
1304 --x-initial unique (default)
1305 Controls the two-state value that is used to initialize variables
1306 that are not otherwise initialized.
1307 "--x-initial 0", initializes all otherwise uninitialized variables
1309 to zero.
1310 "--x-initial unique", the default, initializes variables using a
1312 function, which determines the value to use each initialization.
1313 This gives greatest flexibility and allows finding reset bugs. See
1314 "Unknown states".
1315 "--x-initial fast", is best for performance, and initializes all
1317 variables to a state Verilator determines is optimal. This may
1318 allow further code optimizations, but will likely hide any code
1319 bugs relating to missing resets.
1320 Note. This option applies only to initial values of variables.
1322 Initial values of clocks are set to 0 unless --x-initial-edge is
1323 specified.
1324 --x-initial-edge
1326 Enables emulation of event driven simulators which generally
1327 trigger an edge on a transition from X to 1 ("posedge") or X to 0
1328 ("negedge"). Thus the following code, where "rst_n" is
1329 uninitialized would set "res_n" to "1'b1" when "rst_n" is first set
1330 to zero:
1331 reg res_n = 1'b0;
1333 always @(negedge rst_n) begin
1335 if (rst_n == 1'b0) begin
1336 res_n <= 1'b1;
1337 end
1338 end
1339 In Verilator, by default, uninitialized clocks are given a value of
1341 zero, so the above "always" block would not trigger.
1342 While it is not good practice, there are some designs that rely on
1344 X X 0 triggering a "negedge", particularly in reset sequences.
1345 Using --x-initial-edge with Verilator will replicate this behavior.
1346 It will also ensure that X X 1 triggers a "posedge".
1347 Note. Some users have reported that using this option can affect
1349 convergence, and that it may be necessary to use --converge-limit
1350 to increase the number of convergence iterations. This may be
1351 another indication of problems with the modeled design that should
1352 be addressed.
1353 --xml-only
1355 Create XML output only, do not create any other output.
1356 The XML format is intended to be used to leverage Verilator's
1358 parser and elaboration to feed to other downstream tools. Be aware
1359 that the XML format is still evolving; there will be some changes
1360 in future versions.
1361 --xml-output filename
1363 Filename for XML output file. Using this option automatically sets
1364 --xml-only.
1365 -y dir
1367 Add the directory to the list of directories that should be
1368 searched for include files or libraries. The three flags -y,
1369 +incdir and -I have similar effect; +incdir and +y are fairly
1370 standard across Verilog tools while -I is an alias for GCC
1371 compatibility.
1372 Verilator defaults to the current directory ("-y .") and any
1374 specified --Mdir, though these default paths are used after any
1375 user specified directories. This allows '-y "$(pwd)"' to be used
1376 if absolute filenames are desired for error messages instead of
1377 relative filenames.
1378
1380 The following are the arguments that may be passed to a Verilated
1381 executable, provided that executable calls Verilated::commandArgs().
1382 All simulation runtime arguments begin with +verilator, so that the
1384 user's executable may skip over all +verilator arguments when parsing
1385 its command line.
1386 +verilator+debug
1388 Enable simulation runtime debugging. Equivalent to
1389 +verilator+debugi+4.
1390 +verilator+debugi+value
1392 Enable simulation runtime debugging at the provided level.
1393 +verilator+error+limit+value
1395 Set number of non-fatal errors (e.g. assertion failures) before
1396 exiting simulation runtime. Also affects number of $stop calls
1397 needed before exit. Defaults to 1.
1398 +verilator+help
1400 Display help and exit.
1401 +verilator+prof+threads+file+filename
1403 When using --prof-threads at simulation runtime, the filename to
1404 dump to. Defaults to "profile_threads.dat".
1405 +verilator+prof+threads+start+value
1407 When using --prof-threads at simulation runtime, Verilator will
1408 wait until $time is at this value, then start the profiling warmup,
1409 then capturing. Generally this should be set to some time that is
1410 well within the normal operation of the simulation, i.e. outside of
1411 reset. If 0, the dump is disabled. Defaults to 1.
1412 +verilator+prof+threads+window+value
1414 When using --prof-threads at simulation runtime, after $time
1415 reaches +verilator+prof+threads+start, Verilator will warm up the
1416 profiling for this number of eval() calls, then will capture the
1417 profiling of this number of eval() calls. Defaults to 2, which
1418 makes sense for a single-clock-domain module where it's typical to
1419 want to capture one posedge eval() and one negedge eval().
1420 +verilator+rand+reset+value
1422 When a model was Verilated using "-x-initial unique", sets the
1423 simulation runtime initialization technique. 0 = Reset to zeros. 1
1424 = Reset to all-ones. 2 = Randomize. See "Unknown states".
1425 +verilator+seed+value
1427 For $random and "-x-initial unique", set the simulation runtime
1428 random seed value. If zero or not specified picks a value from the
1429 system random number generator.
1430 +verilator+V
1432 Shows the verbose version, including configuration information.
1433 +verilator+version
1435 Displays program version and exits.
1436
1438 We'll compile this example into C++.
1439 mkdir test_our
1441 cd test_our
1442 cat >our.v <<'EOF'
1444 module our;
1445 initial begin $display("Hello World"); $finish; end
1446 endmodule
1447 EOF
1448 cat >sim_main.cpp <<'EOF'
1450 #include "Vour.h"
1451 #include "verilated.h"
1452 int main(int argc, char** argv, char** env) {
1453 Verilated::commandArgs(argc, argv);
1454 Vour* top = new Vour;
1455 while (!Verilated::gotFinish()) { top->eval(); }
1456 delete top;
1457 exit(0);
1458 }
1459 EOF
1460 See the README in the source kit for various ways to install or point
1462 to Verilator binaries. In brief, if you are running Verilator that
1463 came from your operating system (as an RPM), or did a "make install" to
1464 place Verilator into your default path, you do not need anything
1465 special in your environment, and should not have VERILATOR_ROOT set.
1466 However, if you installed Verilator from sources and want to run
1467 Verilator out of where you compiled Verilator, you need to point to the
1468 kit:
1469 # See above; don't do this if using an OS-distributed Verilator
1471 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1472 export PATH=$VERILATOR_ROOT/bin:$PATH
1473 Now we run Verilator on our little example.
1475 verilator -Wall --cc our.v --exe sim_main.cpp
1477 We can see the source code under the "obj_dir" directory. See the
1479 FILES section below for descriptions of some of the files that were
1480 created.
1481 ls -l obj_dir
1483 We then can compile it
1485 make -j -C obj_dir -f Vour.mk Vour
1487 (Verilator included a default compile rule and link rule, since we used
1489 --exe and passed a .cpp file on the Verilator command line. You can
1490 also write your own compile rules, as we'll show in the SYSTEMC
1491 section.)
1492 And now we run it
1494 obj_dir/Vour
1496 And we get as output
1498 Hello World
1500 - our.v:2: Verilog $finish
1501 Really, you're better off writing a Makefile to do all this for you.
1503 Then, when your source changes it will automatically run all of these
1504 steps; to aid this Verilator can create a makefile dependency file.
1505 See the examples directory in the distribution.
1506
1508 This is an example similar to the above, but using SystemC.
1509 mkdir test_our_sc
1511 cd test_our_sc
1512 cat >our.v <<'EOF'
1514 module our (clk);
1515 input clk; // Clock is required to get initial activation
1516 always @ (posedge clk)
1517 begin $display("Hello World"); $finish; end
1518 endmodule
1519 EOF
1520 cat >sc_main.cpp <<'EOF'
1522 #include "Vour.h"
1523 int sc_main(int argc, char** argv) {
1524 Verilated::commandArgs(argc, argv);
1525 sc_clock clk ("clk", 10, 0.5, 3, true);
1526 Vour* top;
1527 top = new Vour("top");
1528 top->clk(clk);
1529 while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
1530 delete top;
1531 exit(0);
1532 }
1533 EOF
1534 See the README in the source kit for various ways to install or point
1536 to Verilator binaries. In brief, if you are running Verilator that
1537 came from your operating system (as an RPM), or did a "make install" to
1538 place Verilator into your default path, you do not need anything
1539 special in your environment, and should not have VERILATOR_ROOT set.
1540 However, if you installed Verilator from sources and want to run
1541 Verilator out of where you compiled Verilator, you need to point to the
1542 kit:
1543 # See above; don't do this if using an OS-distributed Verilator
1545 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1546 export PATH=$VERILATOR_ROOT/bin:$PATH
1547 Now we run Verilator on our little example.
1549 verilator -Wall --sc our.v
1551 We then can compile it
1553 cd obj_dir
1555 make -j -f Vour.mk Vour__ALL.a
1556 make -j -f Vour.mk ../sc_main.o verilated.o
1557 And link with SystemC. Note your path to the libraries may vary,
1559 depending on the operating system.
1560 export SYSTEMC_LIBDIR=/path/to/where/libsystemc.a/exists
1562 export LD_LIBRARY_PATH=$SYSTEMC_LIBDIR:$LD_LIBRARY_PATH
1563 # Might be needed if SystemC 2.3.0
1564 export SYSTEMC_CXX_FLAGS=-pthread
1565 g++ -L$SYSTEMC_LIBDIR ../sc_main.o Vour__ALL*.o verilated.o \
1567 -o Vour -lsystemc
1568 And now we run it
1570 cd ..
1572 obj_dir/Vour
1573 And we get the same output as the C++ example:
1575 Hello World
1577 - our.v:2: Verilog $finish
1578 Really, you're better off using a Makefile to do all this for you.
1580 Then, when your source changes it will automatically run all of these
1581 steps. See the examples directory in the distribution.
1582
1584 For best performance, run Verilator with the "-O3 --x-assign fast
1585 --x-initial fast --noassert" flags. The -O3 flag will require longer
1586 compile times, and "--x-assign fast --x-initial fast" may increase the
1587 risk of reset bugs in trade for performance; see the above
1588 documentation for these flags.
1589 If using Verilated multithreaded, use "numactl" to ensure you are using
1591 non-conflicting hardware resources. See "MULTITHREADING".
1592 Minor Verilog code changes can also give big wins. You should not have
1594 any UNOPTFLAT warnings from Verilator. Fixing these warnings can
1595 result in huge improvements; one user fixed their one UNOPTFLAT warning
1596 by making a simple change to a clock latch used to gate clocks and
1597 gained a 60% performance improvement.
1598 Beyond that, the performance of a Verilated model depends mostly on
1600 your C++ compiler and size of your CPU's caches.
1601 By default, the lib/verilated.mk file has optimization turned off.
1603 This is for the benefit of new users, as it improves compile times at
1604 the cost of simulation runtimes. To add optimization as the default,
1605 set one of three variables, OPT, OPT_FAST, or OPT_SLOW
1606 lib/verilated.mk. Or, use the -CFLAGS and/or -LDFLAGS option on the
1607 verilator command line to pass the flags directly to the compiler or
1608 linker. Or, just for one run, pass them on the command line to make:
1609 make OPT_FAST="-O2 -fno-stack-protector" -f Vour.mk Vour__ALL.a
1611 OPT_FAST specifies optimizations for those programs that are part of
1613 the fast path, mostly code that is executed every cycle. OPT_SLOW
1614 specifies optimizations for slow-path files (plus tracing), which
1615 execute only rarely, yet take a long time to compile with optimization
1616 on. OPT specifies overall optimization and affects all compiles,
1617 including those OPT_FAST and OPT_SLOW control. For best results, use
1618 OPT="-O2", and link with "-static". Nearly the same results can be had
1619 with much better compile times with OPT_FAST="-O1 -fstrict-aliasing".
1620 Higher optimization such as "-O3" may help, but gcc compile times may
1621 be excessive under O3 on even medium sized designs. Alternatively,
1622 some larger designs report better performance using "-Os".
1623 Unfortunately, using the optimizer with SystemC files can result in
1625 compiles taking several minutes. (The SystemC libraries have many
1626 little inlined functions that drive the compiler nuts.)
1627 For best results, use GCC 3.3 or newer. GCC 3.2 and earlier have
1629 optimization bugs around pointer aliasing detection, which can result
1630 in 2x performance losses.
1631 If you will be running many simulations on a single compile,
1633 investigate feedback driven compilation. With GCC, using
1634 -fprofile-arcs, then -fbranch-probabilities will yield another 15% or
1635 so.
1636 Modern compilers also support link-time optimization (LTO), which can
1638 help especially if you link in DPI code. To enable LTO on GCC, pass
1639 "-flto" in both compilation and link. Note LTO may cause excessive
1640 compile times on large designs.
1641 If you are using your own makefiles, you may want to compile the
1643 Verilated code with -DVL_INLINE_OPT=inline. This will inline functions,
1644 however this requires that all cpp files be compiled in a single
1645 compiler run.
1646 You may uncover further tuning possibilities by profiling the Verilog
1648 code. Use Verilator's --prof-cfuncs, then GCC's -g -pg. You can then
1649 run either oprofile or gprof to see where in the C++ code the time is
1650 spent. Run the gprof output through verilator_profcfunc and it will
1651 tell you what Verilog line numbers on which most of the time is being
1652 spent.
1653 When done, please let the author know the results. I like to keep tabs
1655 on how Verilator compares, and may be able to suggest additional
1656 improvements.
1657
1659 All output files are placed in the output directory name specified with
1660 the -Mdir option, or "obj_dir" if not specified.
1661 Verilator creates the following files in the output directory:
1663 For --make gmake, it creates:
1665 {prefix}.mk // Make include file for compiling
1667 {prefix}_classes.mk // Make include file with class names
1668 For --make cmake, it creates:
1670 {prefix}.cmake // CMake include script for compiling
1672 For -cc and -sc mode, it also creates:
1674 {prefix}.cpp // Top level C++ file
1676 {prefix}.h // Top level header
1677 {prefix}__Slow{__n}.cpp // Constructors and infrequent cold routines
1678 {prefix}{__n}.cpp // Additional top C++ files (--output-split)
1679 {prefix}{each_verilog_module}.cpp // Lower level internal C++ files
1680 {prefix}{each_verilog_module}.h // Lower level internal header files
1681 {prefix}{each_verilog_module}{__n}.cpp // Additional lower C++ files (--output-split)
1682 In certain debug and other modes, it also creates:
1684 {prefix}.xml // XML tree information (--xml)
1686 {prefix}__Dpi.cpp // DPI import and export wrappers
1687 {prefix}__Dpi.h // DPI import and export declarations
1688 {prefix}__Inlines.h // Inline support functions
1689 {prefix}__Syms.cpp // Global symbol table C++
1690 {prefix}__Syms.h // Global symbol table header
1691 {prefix}__Trace__Slow{__n}.cpp // Wave file generation code (--trace)
1692 {prefix}__Trace{__n}.cpp // Wave file generation code (--trace)
1693 {prefix}__cdc.txt // Clock Domain Crossing checks (--cdc)
1694 {prefix}__stats.txt // Statistics (--stats)
1695 {prefix}__idmap.txt // Symbol demangling (--protect-ids)
1696 It also creates internal files that can be mostly ignored:
1698 {mod_prefix}_{each_verilog_module}{__n}.vpp // Post-processed verilog
1700 {prefix}__ver.d // Make dependencies (-MMD)
1701 {prefix}__verFiles.dat // Timestamps for skip-identical
1702 {prefix}{misc}.dot // Debugging graph files (--debug)
1703 {prefix}{misc}.tree // Debugging files (--debug)
1704 After running Make, the C++ compiler may produce the following:
1706 verilated{misc}.d // Intermediate dependencies
1708 verilated{misc}.o // Intermediate objects
1709 {mod_prefix}{misc}.d // Intermediate dependencies
1710 {mod_prefix}{misc}.o // Intermediate objects
1711 {prefix} // Final executable (w/--exe argument)
1712 {prefix}__ALL.a // Library of all Verilated objects
1713 {prefix}__ALLboth.cpp // Include of classes for single compile
1714 {prefix}__ALLcls.cpp // Include of user classes for single compile
1715 {prefix}__ALLsup.cpp // Include of support files for single compile
1716 {prefix}{misc}.d // Intermediate dependencies
1717 {prefix}{misc}.o // Intermediate objects
1718
1720 LD_LIBRARY_PATH
1721 A generic Linux/OS variable specifying what directories have shared
1722 object (.so) files. This path should include SystemC and any other
1723 shared objects needed at simultion runtime.
1724 OBJCACHE
1726 Optionally specifies a caching or distribution program to place in
1727 front of all runs of the C++ Compiler. For example, "objcache
1728 --read --write", or "ccache". If using distcc or icecc/icecream,
1729 they would generally be run under either objcache or ccache; see
1730 the documentation for those programs.
1731 SYSTEMC
1733 Deprecated. Used only if SYSTEMC_INCLUDE or SYSTEMC_LIBDIR is not
1734 set. If set, specifies the directory containing the SystemC
1735 distribution. If not specified, it will come from a default
1736 optionally specified at configure time (before Verilator was
1737 compiled).
1738 SYSTEMC_ARCH
1740 Deprecated. Used only if SYSTEMC_LIBDIR is not set. Specifies the
1741 architecture name used by the SystemC kit. This is the part after
1742 the dash in the lib-{...} directory name created by a 'make' in the
1743 SystemC distribution. If not set, Verilator will try to intuit the
1744 proper setting, or use the default optionally specified at
1745 configure time (before Verilator was compiled).
1746 SYSTEMC_CXX_FLAGS
1748 Specifies additional flags that are required to be passed to GCC
1749 when building the SystemC model. System 2.3.0 may need this set to
1750 "-pthread".
1751 SYSTEMC_INCLUDE
1753 If set, specifies the directory containing the systemc.h header
1754 file. If not specified, it will come from a default optionally
1755 specified at configure time (before Verilator was compiled), or
1756 computed from SYSTEMC/include.
1757 SYSTEMC_LIBDIR
1759 If set, specifies the directory containing the libsystemc.a
1760 library. If not specified, it will come from a default optionally
1761 specified at configure time (before Verilator was compiled), or
1762 computed from SYSTEMC/lib-SYSTEMC_ARCH.
1763 VERILATOR_BIN
1765 If set, specifies an alternative name of the "verilator" binary.
1766 May be used for debugging and selecting between multiple operating
1767 system builds.
1768 VERILATOR_COVERAGE_BIN
1770 If set, specifies an alternative name of the "verilator_coverage
1771 binary". May be used for debugging and selecting between multiple
1772 operating system builds.
1773 VERILATOR_GDB
1775 If set, the command to run when using the --gdb option, such as
1776 "ddd". If not specified, it will use "gdb".
1777 VERILATOR_ROOT
1779 Specifies the directory containing the distribution kit. This is
1780 used to find the executable, Perl library, and include files. If
1781 not specified, it will come from a default optionally specified at
1782 configure time (before Verilator was compiled). It should not be
1783 specified if using a pre-compiled Verilator RPM as the hardcoded
1784 value should be correct.
1785
1787 Verilator creates a .h and .cpp file for the top level module and all
1788 modules under it. See the examples directory in the kit for examples.
1789 After the modules are completed, there will be a module.mk file that
1791 may be used with Make to produce a module__ALL.a file with all required
1792 objects in it. This is then linked with the user's top level to create
1793 the simulation executable.
1794 The user must write the top level of the simulation. Here's a simple
1796 example:
1797 #include <verilated.h> // Defines common routines
1799 #include <iostream> // Need std::cout
1800 #include "Vtop.h" // From Verilating "top.v"
1801 Vtop *top; // Instantiation of module
1803 vluint64_t main_time = 0; // Current simulation time
1805 // This is a 64-bit integer to reduce wrap over issues and
1806 // allow modulus. You can also use a double, if you wish.
1807 double sc_time_stamp () { // Called by $time in Verilog
1809 return main_time; // converts to double, to match
1810 // what SystemC does
1811 }
1812 int main(int argc, char** argv) {
1814 Verilated::commandArgs(argc, argv); // Remember args
1815 top = new Vtop; // Create instance
1817 top->reset_l = 0; // Set some inputs
1819 while (!Verilated::gotFinish()) {
1821 if (main_time > 10) {
1822 top->reset_l = 1; // Deassert reset
1823 }
1824 if ((main_time % 10) == 1) {
1825 top->clk = 1; // Toggle clock
1826 }
1827 if ((main_time % 10) == 6) {
1828 top->clk = 0;
1829 }
1830 top->eval(); // Evaluate model
1831 cout << top->out << endl; // Read a output
1832 main_time++; // Time passes...
1833 }
1834 top->final(); // Done simulating
1836 // // (Though this example doesn't get here)
1837 delete top;
1838 }
1839 Note signals are read and written as member variables of the lower
1841 module. You call the eval() method to evaluate the model. When the
1842 simulation is complete call the final() method to wrap up any
1843 SystemVerilog final blocks, and complete any assertions.
1844
1846 Verilator will convert the top level module to a SC_MODULE. This
1847 module will plug directly into a SystemC netlist.
1848 The SC_MODULE gets the same pinout as the Verilog module, with the
1850 following type conversions: Pins of a single bit become bool. Pins
1851 2-32 bits wide become uint32_t's. Pins 33-64 bits wide become sc_bv's
1852 or vluint64_t's depending on the --no-pins64 switch. Wider pins become
1853 sc_bv's. (Uints simulate the fastest so are used where possible.)
1854 Lower modules are not pure SystemC code. This is a feature, as using
1856 the SystemC pin interconnect scheme everywhere would reduce performance
1857 by an order of magnitude.
1858
1860 Verilator supports SystemVerilog Direct Programming Interface import
1861 and export statements. Only the SystemVerilog form ("DPI-C") is
1862 supported, not the original Synopsys-only DPI.
1863 DPI Example
1865 In the SYSTEMC example above, if you wanted to import C++ functions
1866 into Verilog, put in our.v:
1867 import "DPI-C" function integer add (input integer a, input integer b);
1869 initial begin
1871 $display("%x + %x = %x", 1, 2, add(1,2));
1872 endtask
1873 Then after Verilating, Verilator will create a file Vour__Dpi.h with
1875 the prototype to call this function:
1876 extern int add (int a, int b);
1878 From the sc_main.cpp file (or another .cpp file passed to the Verilator
1880 command line, or the link), you'd then:
1881 #include "svdpi.h"
1883 #include "Vour__Dpi.h"
1884 int add(int a, int b) { return a+b; }
1885 DPI System Task/Functions
1887 Verilator extends the DPI format to allow using the same scheme to
1888 efficiently add system functions. Simply use a dollar-sign prefixed
1889 system function name for the import, but note it must be escaped.
1890 export "DPI-C" function integer \$myRand;
1892 initial $display("myRand=%d", $myRand());
1894 Going the other direction, you can export Verilog tasks so they can be
1896 called from C++:
1897 export "DPI-C" task publicSetBool;
1899 task publicSetBool;
1901 input bit in_bool;
1902 var_bool = in_bool;
1903 endtask
1904 Then after Verilating, Verilator will create a file Vour__Dpi.h with
1906 the prototype to call this function:
1907 extern bool publicSetBool(bool in_bool);
1909 From the sc_main.cpp file, you'd then:
1911 #include "Vour__Dpi.h"
1913 publicSetBool(value);
1914 Or, alternatively, call the function under the design class. This
1916 isn't DPI compatible but is easier to read and better supports multiple
1917 designs.
1918 #include "Vour__Dpi.h"
1920 Vour::publicSetBool(value);
1921 // or top->publicSetBool(value);
1922 Note that if the DPI task or function accesses any register or net
1924 within the RTL, it will require a scope to be set. This can be done
1925 using the standard functions within svdpi.h, after the module is
1926 instantiated, but before the task(s) and/or function(s) are called.
1927 For example, if the top level module is instantiated with the name
1929 "dut" and the name references within tasks are all hierarchical
1930 (dotted) names with respect to that top level module, then the scope
1931 could be set with
1932 #include "svdpi.h"
1934 ...
1935 svSetScope(svGetScopeFromName("dut"));
1936 (Remember that Verilator adds a "V" to the top of the module
1938 hierarchy.)
1939 Scope can also be set from within a DPI imported C function that has
1941 been called from Verilog by querying the scope of that function. See
1942 the sections on DPI Context Functions and DPI Header Isolation below
1943 and the comments within the svdpi.h header for more information.
1944 DPI Display Functions
1946 Verilator allows writing $display like functions using this syntax:
1947 import "DPI-C" function void
1949 \$my_display(input string formatted /*verilator sformat*/ );
1950 The /*verilator sformat*/ indicates that this function accepts a
1952 $display like format specifier followed by any number of arguments to
1953 satisfy the format.
1954 DPI Context Functions
1956 Verilator supports IEEE DPI Context Functions. Context imports pass
1957 the simulator context, including calling scope name, and filename and
1958 line number to the C code. For example, in Verilog:
1959 import "DPI-C" context function int dpic_line();
1961 initial $display("This is line %d, again, line %d\n", `line, dpic_line());
1962 This will call C++ code which may then use the svGet* functions to read
1964 information, in this case the line number of the Verilog statement that
1965 invoked the dpic_line function:
1966 int dpic_line() {
1968 // Get a scope: svScope scope = svGetScope();
1969 const char* scopenamep = svGetNameFromScope(scope);
1971 assert(scopenamep);
1972 const char* filenamep = "";
1974 int lineno = 0;
1975 if (svGetCallerInfo(&filenamep, &lineno)) {
1976 printf("dpic_line called from scope %s on line %d\n",
1977 scopenamep, lineno);
1978 return lineno;
1979 } else {
1980 return 0;
1981 }
1982 }
1983 See the IEEE Standard for more information.
1985 DPI Header Isolation
1987 Verilator places the IEEE standard header files such as svdpi.h into a
1988 separate include directory, vltstd (VeriLaTor STandarD). When
1989 compiling most applications $VERILATOR_ROOT/include/vltstd would be in
1990 the include path along with the normal $VERILATOR_ROOT/include.
1991 However, when compiling Verilated models into other simulators which
1992 have their own svdpi.h and similar standard files with different
1993 contents, the vltstd directory should not be included to prevent
1994 picking up incompatible definitions.
1995 Public Functions
1997 Instead of DPI exporting, there's also Verilator public functions,
1998 which are slightly faster, but less compatible.
1999
2001 Verilator supports a very limited subset of the VPI. This subset
2002 allows inspection, examination, value change callbacks, and depositing
2003 of values to public signals only.
2004 VPI is enabled with the verilator --vpi switch.
2006 To access signals via the VPI, Verilator must be told exactly which
2008 signals are to be accessed. This is done using the Verilator public
2009 pragmas documented below.
2010 Verilator has an important difference from an event based simulator;
2012 signal values that are changed by the VPI will not immediately
2013 propagate their values, instead the top level header file's eval()
2014 method must be called. Normally this would be part of the normal
2015 evaluation (i.e. the next clock edge), not as part of the value change.
2016 This makes the performance of VPI routines extremely fast compared to
2017 event based simulators, but can confuse some test-benches that expect
2018 immediate propagation.
2019 Note the VPI by its specified implementation will always be much slower
2021 than accessing the Verilator values by direct reference
2022 (structure->module->signame), as the VPI accessors perform lookup in
2023 functions at simulation runtime requiring at best hundreds of
2024 instructions, while the direct references are evaluated by the compiler
2025 and result in only a couple of instructions.
2026 For signal callbacks to work the main loop of the program must call
2028 VerilatedVpi::callValueCbs().
2029 VPI Example
2031 In the below example, we have readme marked read-only, and writeme
2032 which if written from outside the model will have the same semantics as
2033 if it changed on the specified clock edge.
2034 cat >our.v <<'EOF'
2036 module our (input clk);
2037 reg readme /*verilator public_flat_rd*/;
2038 reg writeme /*verilator public_flat_rw @(posedge clk) */;
2039 initial $finish;
2040 endmodule
2041 EOF
2042 There are many online tutorials and books on the VPI, but an example
2044 that accesses the above signal "readme" would be:
2045 cat >sim_main.cpp <<'<<EOF'
2047 #include "Vour.h"
2048 #include "verilated.h"
2049 #include "verilated_vpi.h" // Required to get definitions
2050 vluint64_t main_time = 0; // See comments in first example
2052 double sc_time_stamp() { return main_time; }
2053 void read_and_check() {
2055 vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
2056 if (!vh1) { vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found"); }
2057 const char* name = vpi_get_str(vpiName, vh1);
2058 printf("Module name: %s\n", name); // Prints "readme"
2059 s_vpi_value v;
2061 v.format = vpiIntVal;
2062 vpi_get_value(vh1, &v);
2063 printf("Value of v: %d\n", v.value.integer); // Prints "readme"
2064 }
2065 int main(int argc, char** argv, char** env) {
2067 Verilated::commandArgs(argc, argv);
2068 Vour* top = new Vour;
2069 Verilated::internalsDump(); // See scopes to help debug
2070 while (!Verilated::gotFinish()) {
2071 top->eval();
2072 VerilatedVpi::callValueCbs(); // For signal callbacks
2073 read_and_check();
2074 }
2075 delete top;
2076 exit(0);
2077 }
2078 EOF
2079
2081 Verilator supports cross-compiling Verilated code. This is generally
2082 used to run Verilator on a Linux system and produce C++ code that is
2083 then compiled on Windows.
2084 Cross compilation involves up to three different OSes. The build
2086 system is where you configured and compiled Verilator, the host system
2087 where you run Verilator, and the target system where you compile the
2088 Verilated code and run the simulation.
2089 Currently, Verilator requires the build and host system type to be the
2091 same, though the target system type may be different. To support this,
2092 ./configure and make Verilator on the build system. Then, run
2093 Verilator on the host system. Finally, the output of Verilator may be
2094 compiled on the different target system.
2095 To support this, none of the files that Verilator produces will
2097 reference any configure generated build-system specific files, such as
2098 config.h (which is renamed in Verilator to config_build.h to reduce
2099 confusion.) The disadvantage of this approach is that
2100 include/verilatedos.h must self-detect the requirements of the target
2101 system, rather than using configure.
2102 The target system may also require edits to the Makefiles, the simple
2104 Makefiles produced by Verilator presume the target system is the same
2105 type as the build system.
2106 CMake
2108 Verilator can be run using CMake, which takes care of both running
2109 Verilator and compiling the output. There is a CMake example in the
2110 examples/ directory. The following is a minimal CMakeLists.txt that
2111 would build the code listed in "EXAMPLE C++ EXECUTION":
2112 project(cmake_example)
2114 find_package(verilator HINTS $ENV{VERILATOR_ROOT})
2115 add_executable(Vour sim_main.cpp)
2116 verilate(Vour SOURCES our.v)
2117 find_package will automatically find an installed copy of Verilator, or
2119 use a local build if VERILATOR_ROOT is set.
2120 It is recommended to use CMake >= 3.12 and the Ninja generator, though
2122 other combinations should work. To build with CMake, change to the
2123 folder containing CMakeLists.txt and run:
2124 mkdir build
2126 cd build
2127 cmake -GNinja ..
2128 ninja
2129 Or to build with your system default generator:
2131 mkdir build
2133 cd build
2134 cmake ..
2135 cmake --build .
2136 If you're building the example you should have an executable to run:
2138 ./Vour
2140 The package sets the CMake variables verilator_FOUND, VERILATOR_ROOT
2142 and VERILATOR_BIN to the appropriate values, and also creates a
2143 verilate() function. verilate() will automatically create custom
2144 commands to run Verilator and add the generated C++ sources to the
2145 target specified.
2146 verilate(target SOURCES source ... [TOP_MODULE top] [PREFIX name]
2148 [TRACE] [TRACE_FST] [SYSTEMC] [COVERAGE]
2149 [INCLUDE_DIRS dir ...] [OPT_SLOW ...] [OPT_FAST ...]
2150 [DIRECTORY dir] [VERILATOR_ARGS ...])
2151 Lowercase and ... should be replaced with arguments, the uppercase
2153 parts delimit the arguments and can be passed in any order, or left out
2154 entirely if optional.
2155 verilate(target ...) can be called multiple times to add other verilog
2157 modules to an executable or library target.
2158 When generating Verilated SystemC sources, you should also include the
2160 SystemC include directories and link to the SystemC libraries.
2161 Verilator's CMake support provides a convenience function to
2163 automatically find and link to the SystemC library. It can be used as:
2164 verilator_link_systemc(target)
2166 where target is the name of your target.
2168 The search paths can be configured by setting some variables:
2170 - The variables SYSTEMC_INCLUDE and SYSTEMC_LIBDIR to give a direct
2172 path to the SystemC include an library path.
2173 - SYSTEMC_ROOT to set the installation prefix of an installed SystemC
2175 library.
2176 - SYSTEMC to set the installation prefix of an installed SystemC
2178 library
2179 (same as above).
2180 - When using Accellera's SystemC with CMake support, a CMake target is
2182 available that will easen above steps. This will only work if the
2183 SystemC installation can be found by CMake. This can be configured by
2184 setting the CMAKE_PREFIX_PATH variable during CMake configuration.
2185 Don't forget to set the same C++ standard for the Verilated sources as
2187 the SystemC library. This can be specified using the SYSTEMC_CXX_FLAGS
2188 environment variable.
2189 target
2191 Name of a target created by add_executable or add_library.
2192 SOURCES
2194 List of verilog files to Verilate. Must have at least one file.
2195 PREFIX
2197 Optional. Sets the Verilator output prefix. Defaults to the name of
2198 the first hdl source with a "V" prepended. Must be unique in each
2199 call to verilate(), so this is necessary if you build a module
2200 multiple times with different parameters. Must be a valid C++
2201 identifier, i.e. contains no whitespace and only characters A-Z,
2202 a-z, 0-9 or _.
2203 TOP_MODULE
2205 Optional. Sets the name of the top module. Defaults to the name of
2206 the first file in the SOURCES array.
2207 TRACE
2209 Optional. Enables VCD tracing if present, equivalent to
2210 "VERILATOR_ARGS --trace".
2211 TRACE_FST
2213 Optional. Enables FST tracing if present, equivalent to
2214 "VERILATOR_ARGS --trace-fst".
2215 SYSTEMC
2217 Optional. Enables SystemC mode, defaults to C++ if not specified.
2218 COVERAGE
2220 Optional. Enables coverage if present, equivalent to
2221 "VERILATOR_ARGS --coverage"
2222 INCLUDE_DIRS
2224 Optional. Sets directories that Verilator searches (same as -y).
2225 OPT_SLOW
2227 Optional. Set compiler flags for the slow path. You may want to
2228 reduce the optimization level to improve compile times with large
2229 designs.
2230 OPT_FAST
2232 Optional. Set compiler flags for the fast path.
2233 DIRECTORY
2235 Optional. Set the verilator output directory. It is preferable to
2236 use the default, which will avoid collisions with other files.
2237 VERILATOR_ARGS
2239 Optional. Extra arguments to Verilator. Do not specify --Mdir or
2240 --prefix here, use DIRECTORY or PREFIX.
2241 Cadence NC-SystemC Models
2243 Similar to compiling Verilated designs with gcc, Verilated designs may
2244 be compiled inside other simulators that support C++ or SystemC models.
2245 One such simulator is Cadence's NC-SystemC, part of their Incisive
2246 Verification Suite. (Highly recommended.)
2247 Using the example files above, the following command will build the
2249 model underneath NC:
2250 cd obj_dir
2252 ncsc_run \
2253 sc_main.cpp \
2254 Vour__ALLcls.cpp \
2255 Vour__ALLsup.cpp \
2256 verilated.cpp
2257 For larger designs you'll want to automate this using makefiles, which
2259 pull the names of the .cpp files to compile in from the make variables
2260 generated in obj_dir/Vour_classes.mk.
2261
2263 Verilator experimentally supports multithreading.
2264 With --no-threads, the default, the model is not thread safe, and any
2266 use of more than one thread calling into one or even different
2267 Verilated models may result in unpredictable behavior. This gives the
2268 highest single thread performance.
2269 With --threads 1, the generated model is single threaded, however the
2271 support libraries are multithread safe. This allows different
2272 instantiations of model(s) to potentially each be run under a different
2273 thread. All threading is the responsibility of the user's C++
2274 testbench.
2275 With --threads N, where N is at least 2, the generated model will be
2277 designed to run in parallel on N threads. The thread calling eval()
2278 provides one of those threads, and the generated model will create and
2279 manage the other N-1 threads. It's the client's responsibility not to
2280 oversubscribe the available CPU cores. Under CPU oversubscription, the
2281 Verilated model should not livelock nor deadlock, however, you can
2282 expect performance to be far worse than it would be with proper ratio
2283 of threads and CPU cores.
2284 With --trace-fst-thread, tracing occurs in a separate thread from the
2286 main simulation thread(s). This option is orthogonal to --threads.
2287 The remainder of this section describe behavior with --threads 1 or
2289 --threads N (not --no-threads).
2290 VL_THREADED is defined when compiling a threaded Verilated module,
2292 causing the Verilated support classes become threadsafe.
2293 The thread used for constructing a model must be the same thread that
2295 calls eval() into the model, this is called the "eval thread". The
2296 thread used to perform certain global operations such as saving and
2297 tracing must be done by a "main thread". In most cases the eval thread
2298 and main thread are the same thread (i.e. the user's top C++ testbench
2299 runs on a single thread), but this is not required.
2300 When running a multithreaded model, the default Linux task scheduler
2302 often works against the model, by assuming threads are short lived, and
2303 thus often schedules threads using multiple hyperthreads within the
2304 same physical core. For best performance use the "numactl" program to
2305 (when the threading count fits) select unique physical cores on the
2306 same socket. For example, if a model was Verilated with "--threads 4",
2307 we consult
2308 egrep 'processor|physical id|core id' /proc/cpuinfo
2310 To select cores 0, 1, 2, and 3 that are all located on the same socket
2312 (0) but different physical cores. (Also useful is "numactl
2313 --hardware", or "lscpu" but those doesn't show Hyperthreading cores.)
2314 Then we execute
2315 numactl -m 0 -C 0,1,2,3 -- verilated_executable_name
2317 This will limit memory to socket 0, and threads to cores 0, 1, 2, 3,
2319 (presumably on socket 0) optimizing performance. Of course this must
2320 be adjusted if you want another simulator using e.g. socket 1, or if
2321 you Verilated with a different number of threads. To see what CPUs are
2322 actually used, use --prof-threads.
2323 Multithreaded Verilog and Library Support
2325 $display/$stop/$finish are delayed until the end of an eval() call in
2326 order to maintain ordering between threads. This may result in
2327 additional tasks completing after the $stop or $finish.
2328 If using --coverage, the coverage routines are fully thread safe.
2330 If using --dpi, Verilator assumes pure DPI imports are thread safe,
2332 balancing performance versus safety. See --threads-dpi.
2333 If using --savable, the save/restore classes are not multithreaded
2335 and are must be called only by the eval thread.
2336 If using --sc, the SystemC kernel is not thread safe, therefore the
2338 eval thread and main thread must be the same.
2339 If using --trace, the tracing classes must be constructed and
2341 called from the main thread.
2342 If using --vpi, since SystemVerilog VPI was not architected by IEEE
2344 to be multithreaded, Verilator requires all VPI calls are only made
2345 from the main thread.
2346
2348 In addition to the command line, warnings and other features may be
2349 controlled by configuration files, typically named with the .vlt
2350 extension. An example:
2351 `verilator_config
2353 lint_off -rule WIDTH
2354 lint_off -rule CASEX -file "silly_vendor_code.v"
2355 This disables WIDTH warnings globally, and CASEX for a specific file.
2357 Configuration files are parsed after the normal Verilog preprocessing,
2359 so `ifdefs, `defines, and comments may be used as if it were normal
2360 Verilog code.
2361 Note that file or line-specific configuration only applies to files
2363 read after the configuration file. It is therefore recommended to pass
2364 the configuration file to Verilator as first file.
2365 The grammar of configuration commands is as follows:
2367 `verilator_config
2369 Take remaining text and treat it as Verilator configuration
2370 commands.
2371 coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2373 coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2374 Enable/disable coverage for the specified filename (or wildcard
2375 with '*' or '?', or all files if omitted) and range of line numbers
2376 (or all lines if omitted). Often used to ignore an entire module
2377 for coverage analysis purposes.
2378 lint_on [-rule <message>] [-file "<filename>" [-lines <line> [ -
2380 <line>]]]
2381 lint_off [-rule <message>] [-file "<filename>" [-lines <line> [ -
2382 <line>]]]
2383 lint_off [-rule <message>] [-file "<filename>"] [-match "<string>"]
2384 Enable/disables the specified lint warning, in the specified
2385 filename (or wildcard with '*' or '?', or all files if omitted) and
2386 range of line numbers (or all lines if omitted).
2387 With lint_off using '*' will override any lint_on directives in the
2389 source, i.e. the warning will still not be printed.
2390 If the -rule is omitted, all lint warnings (see list in -Wno-lint)
2392 are enabled/disabled. This will override all later lint warning
2393 enables for the specified region.
2394 If -match is set the linter warnings are matched against this
2396 (wildcard) string and are waived in case they match iff rule and
2397 file (with wildcard) also match.
2398 In previous versions -rule was named -msg. The latter is
2400 deprecated, but still works with a deprecation info, it may be
2401 removed in future versions.
2402 tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2404 tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2405 Enable/disable waveform tracing for all future signals declared in
2406 the specified filename (or wildcard with '*' or '?', or all files
2407 if omitted) and range of line numbers (or all lines if omitted).
2408 For tracing_off, cells below any module in the files/ranges
2410 specified will also not be traced.
2411 clock_enable -module "<modulename>" -signal "<signame>"
2413 Indicate the signal is used to gate a clock, and the user takes
2414 responsibility for insuring there are no races related to it.
2415 Same as /*verilator clock_enable*/, see "LANGUAGE EXTENSIONS" for
2417 more information and an example.
2418 clocker -module "<modulename>" [-task "<taskname>"] -signal "<signame>"
2420 clocker -module "<modulename>" [-function "<funcname>"] -signal
2421 "<signame>"
2422 no_clocker -module "<modulename>" [-task "<taskname>"] -signal
2423 "<signame>"
2424 no_clocker -module "<modulename>" [-function "<funcname>"] -signal
2425 "<signame>"
2426 Indicate the signal is used as clock or not. This information is
2427 used by Verilator to mark the signal as clocker and propagate the
2428 clocker attribute automatically to derived signals. See "--clk" for
2429 more information.
2430 Same as /*verilator clocker*/, see "LANGUAGE EXTENSIONS" for more
2432 information.
2433 coverage_block_off -module "<modulename>" -block "<blockname>"
2435 coverage_block_off -file "<filename>" -line <lineno>
2436 Specifies the entire begin/end block should be ignored for coverage
2437 analysis purposes. Can either be specified as a named block or as
2438 a filename and line number.
2439 Same as /*verilator coverage_block_off*/, see "LANGUAGE EXTENSIONS"
2441 for more information.
2442 full_case -file "<filename>" -lines <lineno>
2444 parallel_case -file "<filename>" -lines <lineno>
2445 Same as "//synopsys full_case" and "//synopsys parallel_case". When
2446 these synthesis directives are discovered, Verilator will either
2447 formally prove the directive to be true, or failing that, will
2448 insert the appropriate code to detect failing cases at simulation
2449 runtime and print an "Assertion failed" error message.
2450 inline -module "<modulename>"
2452 Specifies the module may be inlined into any modules that use this
2453 module. This is useful to speed up simulation runtime with some
2454 small loss of trace visibility and modularity. Note signals under
2455 inlined submodules will be named submodule__DOT__subsignal as C++
2456 does not allow "." in signal names. When tracing such signals the
2457 tracing routines will replace the __DOT__ with the period.
2458 Same as /*verilator inline_module*/, see "LANGUAGE EXTENSIONS" for
2460 more information.
2461 isolate_assignments -module "<modulename>" [-task "<taskname>"] -signal
2463 "<signame>"
2464 isolate_assignments -module "<modulename>" [-function "<funcname>"]
2465 -signal "<signame>"
2466 isolate_assignments -module "<modulename>" -function "<fname>"
2467 Used to indicate the assignments to this signal in any blocks
2468 should be isolated into new blocks. When there is a large
2469 combinatorial block that is resulting in a UNOPTFLAT warning,
2470 attaching this to the signal causing a false loop may clear up the
2471 problem.
2472 Same as /* verilator isolate_assignments */, see "LANGUAGE
2474 EXTENSIONS" for more information.
2475 no_inline -module "<modulename>"
2477 Specifies the module should not be inlined into any modules that
2478 use this module. This is useful especially at the top level module
2479 to reduce the size of the interface class, to aid compile time at a
2480 small performance loss.
2481 Same as /*verilator no_inline_module*/, see "LANGUAGE EXTENSIONS"
2483 for more information.
2484 no_inline [-module "<modulename>"] -task "<taskname>"
2486 no_inline [-module "<modulename>"] -function "<funcname>"
2487 Specify the function or task should not be inlined into where it is
2488 used. This may reduce the size of the final executable when a task
2489 is used a very large number of times. For this flag to work, the
2490 task and tasks below it must be pure; they cannot reference any
2491 variables outside the task itself.
2492 Same as /*verilator no_inline_task*/, see "LANGUAGE EXTENSIONS" for
2494 more information.
2495 sc_bv -module "<modulename>" [-task "<taskname>"] -signal "<signame>"
2497 sc_bv -module "<modulename>" [-function "<funcname>"] -signal
2498 "<signame>"
2499 Sets the port to be of sc_bv<width> type, instead of bool,
2500 vluint32_t or vluint64_t. This may be useful if the port width is
2501 parameterized and different of such modules interface a templated
2502 module (such as a transactor) or for other reasons. In general you
2503 should avoid using this attribute when not necessary as with
2504 increasing usage of sc_bv the performance decreases significantly.
2505 Same as /*verilator sc_bv*/, see "LANGUAGE EXTENSIONS" for more
2507 information.
2508 sformat [-module "<modulename>"] [-task "<taskname>"] -signal
2510 "<signame>"
2511 sformat [-module "<modulename>"] [-function "<funcname>"] -signal
2512 "<signame>"
2513 Final input of a function or task "input string" to indicate the
2514 function or task should pass all remaining arguments through
2515 $sformatf. This allows creation of DPI functions with $display
2516 like behavior. See the test_regress/t/t_dpi_display.v file for an
2517 example.
2518 Same as /*verilator sformat*/, see "LANGUAGE EXTENSIONS" for more
2520 information.
2521
2523 Verilog 2001 (IEEE 1364-2001) Support
2524 Verilator supports most Verilog 2001 language features. This includes
2525 signed numbers, "always @*", generate statements, multidimensional
2526 arrays, localparam, and C-style declarations inside port lists.
2527 Verilog 2005 (IEEE 1364-2005) Support
2529 Verilator supports most Verilog 2005 language features. This includes
2530 the `begin_keywords and `end_keywords compiler directives, $clog2, and
2531 the uwire keyword.
2532 SystemVerilog 2005 (IEEE 1800-2005) Support
2534 Verilator supports ==? and !=? operators, ++ and -- in some contexts,
2535 $bits, $countones, $error, $fatal, $info, $isunknown, $onehot,
2536 $onehot0, $unit, $warning, always_comb, always_ff, always_latch, bit,
2537 byte, chandle, const, do-while, enum, export, final, import, int,
2538 interface, logic, longint, modport, package, program, shortint, struct,
2539 time, typedef, union, var, void, priority case/if, and unique case/if.
2540 It also supports .name and .* interconnection.
2542 Verilator partially supports concurrent assert and cover statements;
2544 see the enclosed coverage tests for the syntax which is allowed.
2545 SystemVerilog 2012 (IEEE 1800-2012) Support
2547 Verilator implements a full SystemVerilog 2012 preprocessor, including
2548 function call-like preprocessor defines, default define arguments,
2549 `__FILE__, `__LINE__ and `undefineall.
2550 Verilator currently has some support for SystemVerilog synthesis
2552 constructs. As SystemVerilog features enter common usage they are
2553 added; please file a bug if a feature you need is missing.
2554 SystemVerilog 2017 (IEEE 1800-2017) Support
2556 Verilator supports the 2017 "for" loop constructs, and several minor
2557 cleanups made in 1800-2017.
2558 Verilog AMS Support
2560 Verilator implements a very small subset of Verilog AMS (Verilog Analog
2561 and Mixed-Signal Extensions) with the subset corresponding to those VMS
2562 keywords with near equivalents in the Verilog 2005 or SystemVerilog
2563 2009 languages.
2564 AMS parsing is enabled with "--language VAMS" or "--language
2566 1800+VAMS".
2567 At present Verilator implements ceil, exp, floor, ln, log, pow, sqrt,
2569 string, and wreal.
2570 Synthesis Directive Assertion Support
2572 With the --assert switch, Verilator reads any "//synopsys full_case" or
2573 "//synopsys parallel_case" directives. The same applies to any
2574 "//ambit synthesis", "//cadence" or "//pragma" directives of the same
2575 form.
2576 When these synthesis directives are discovered, Verilator will either
2578 formally prove the directive to be true, or failing that, will insert
2579 the appropriate code to detect failing cases at simulation runtime and
2580 print an "Assertion failed" error message.
2581 Verilator likewise also asserts any "unique" or "priority"
2583 SystemVerilog keywords on case statement, as well as "unique" on if
2584 statements. However, "priority if" is currently simply ignored.
2585
2587 The following additional constructs are the extensions Verilator
2588 supports on top of standard Verilog code. Using these features outside
2589 of comments or `ifdef's may break other tools.
2590 `__FILE__
2592 The __FILE__ define expands to the current filename as a string,
2593 like C++'s __FILE__. This was incorporated into to the 1800-2009
2594 standard (but supported by Verilator since 2006!)
2595 `__LINE__
2597 The __LINE__ define expands to the current filename as a string,
2598 like C++'s __LINE__. This was incorporated into to the 1800-2009
2599 standard (but supported by Verilator since 2006!)
2600 `error string
2602 This will report an error when encountered, like C++'s #error.
2603 $c(string, ...);
2605 The string will be embedded directly in the output C++ code at the
2606 point where the surrounding Verilog code is compiled. It may
2607 either be a standalone statement (with a trailing ; in the string),
2608 or a function that returns up to a 32-bit number (without a
2609 trailing ;). This can be used to call C++ functions from your
2610 Verilog code.
2611 String arguments will be put directly into the output C++ code.
2613 Expression arguments will have the code to evaluate the expression
2614 inserted. Thus to call a C++ function, $c("func(",a,")") will
2615 result in 'func(a)' in the output C++ code. For input arguments,
2616 rather than hard-coding variable names in the string $c("func(a)"),
2617 instead pass the variable as an expression $c("func(",a,")"). This
2618 will allow the call to work inside Verilog functions where the
2619 variable is flattened out, and also enable other optimizations.
2620 If you will be reading or writing any Verilog variables inside the
2622 C++ functions, the Verilog signals must be declared with
2623 /*verilator public*/.
2624 You may also append an arbitrary number to $c, generally the width
2626 of the output. [signal_32_bits = $c32("...");] This allows for
2627 compatibility with other simulators which require a differently
2628 named PLI function name for each different output width.
2629 $display, $write, $fdisplay, $fwrite, $sformat, $swrite
2631 Format arguments may use C fprintf sizes after the % escape. Per
2632 the Verilog standard, %x prints a number with the natural width,
2633 and %0x prints a number with minimum width. Verilator extends this
2634 so %5x prints 5 digits per the C standard (it's unspecified in
2635 Verilog).
2636 `coverage_block_off
2638 Specifies the entire begin/end block should be ignored for coverage
2639 analysis. Must be inside a basic block, e.g. within a begin/end
2640 pair. Same as /* verilator coverage_block_off */ and
2641 "coverage_block_off" in "CONFIGURATION FILES".
2642 `systemc_header
2644 Take remaining text up to the next `verilog or `systemc_... mode
2645 switch and place it verbatim into the output .h file's header.
2646 Must be placed as a module item, e.g. directly inside a
2647 module/endmodule pair. Despite the name of this macro, this also
2648 works in pure C++ code.
2649 `systemc_ctor
2651 Take remaining text up to the next `verilog or `systemc_... mode
2652 switch and place it verbatim into the C++ class constructor. Must
2653 be placed as a module item, e.g. directly inside a module/endmodule
2654 pair. Despite the name of this macro, this also works in pure C++
2655 code.
2656 `systemc_dtor
2658 Take remaining text up to the next `verilog or `systemc_... mode
2659 switch and place it verbatim into the C++ class destructor. Must
2660 be placed as a module item, e.g. directly inside a module/endmodule
2661 pair. Despite the name of this macro, this also works in pure C++
2662 code.
2663 `systemc_interface
2665 Take remaining text up to the next `verilog or `systemc_... mode
2666 switch and place it verbatim into the C++ class interface. Must be
2667 placed as a module item, e.g. directly inside a module/endmodule
2668 pair. Despite the name of this macro, this also works in pure C++
2669 code.
2670 `systemc_imp_header
2672 Take remaining text up to the next `verilog or `systemc_... mode
2673 switch and place it verbatim into the header of all files for this
2674 C++ class implementation. Must be placed as a module item, e.g.
2675 directly inside a module/endmodule pair. Despite the name of this
2676 macro, this also works in pure C++ code.
2677 `systemc_implementation
2679 Take remaining text up to the next `verilog or `systemc_... mode
2680 switch and place it verbatim into a single file of the C++ class
2681 implementation. Must be placed as a module item, e.g. directly
2682 inside a module/endmodule pair. Despite the name of this macro,
2683 this also works in pure C++ code.
2684 If you will be reading or writing any Verilog variables in the C++
2686 functions, the Verilog signals must be declared with /*verilator
2687 public*/. See also the public task feature; writing an accessor
2688 may result in cleaner code.
2689 `SYSTEMVERILOG
2691 The SYSTEMVERILOG, SV_COV_START and related standard defines are
2692 set by default when --language is 1800-*.
2693 `VERILATOR
2695 `verilator
2696 `verilator3
2697 The VERILATOR, verilator and verilator3 defines are set by default
2698 so you may `ifdef around compiler specific constructs.
2699 `verilator_config
2701 Take remaining text up to the next `verilog mode switch and treat
2702 it as Verilator configuration commands.
2703 `verilog
2705 Switch back to processing Verilog code after a `systemc_... mode
2706 switch. The Verilog code returns to the last language mode
2707 specified with `begin_keywords, or SystemVerilog if none was
2708 specified.
2709 /*verilator clock_enable*/
2711 Used after a signal declaration to indicate the signal is used to
2712 gate a clock, and the user takes responsibility for insuring there
2713 are no races related to it. (Typically by adding a latch, and
2714 running static timing analysis.) For example:
2715 reg enable_r /*verilator clock_enable*/;
2717 wire gated_clk = clk & enable_r;
2718 always_ff @ (posedge clk)
2719 enable_r <= enable_early;
2720 The clock_enable attribute will cause the clock gate to be ignored
2722 in the scheduling algorithm, sometimes required for correct clock
2723 behavior, and always improving performance. It's also a good idea
2724 to enable the IMPERFECTSCH warning, to ensure all clock enables are
2725 properly recognized.
2726 Same as "clock_enable" in configuration files, see "CONFIGURATION
2728 FILES" for more information.
2729 /*verilator clocker*/
2731 /*verilator no_clocker*/
2732 Used after a signal declaration to indicate the signal is used as
2733 clock or not. This information is used by Verilator to mark the
2734 signal as clocker and propagate the clocker attribute automatically
2735 to derived signals. See "--clk" for more information.
2736 Same as "clocker" and "no_clocker" in configuration files, see
2738 "CONFIGURATION FILES" for more information.
2739 /*verilator coverage_block_off*/
2741 Specifies the entire begin/end block should be ignored for coverage
2742 analysis purposes.
2743 Same as "coverage_block_off" in configuration files, see
2745 "CONFIGURATION FILES" for more information.
2746 /*verilator coverage_off*/
2748 Specifies that following lines of code should have coverage
2749 disabled. Often used to ignore an entire module for coverage
2750 analysis purposes.
2751 /*verilator coverage_on*/
2753 Specifies that following lines of code should have coverage re-
2754 enabled (if appropriate --coverage flags are passed) after being
2755 disabled earlier with /*verilator coverage_off*/.
2756 /*verilator inline_module*/
2758 Specifies the module the comment appears in may be inlined into any
2759 modules that use this module. This is useful to speed up
2760 simulation runtime with some small loss of trace visibility and
2761 modularity. Note signals under inlined submodules will be named
2762 submodule__DOT__subsignal as C++ does not allow "." in signal
2763 names. When tracing such signals the tracing routines will replace
2764 the __DOT__ with the period.
2765 Same as "inline" in configuration files, see "CONFIGURATION FILES"
2767 for more information.
2768 /*verilator isolate_assignments*/
2770 Used after a signal declaration to indicate the assignments to this
2771 signal in any blocks should be isolated into new blocks. When
2772 there is a large combinatorial block that is resulting in a
2773 UNOPTFLAT warning, attaching this to the signal causing a false
2774 loop may clear up the problem.
2775 IE, with the following
2777 reg splitme /* verilator isolate_assignments*/;
2779 // Note the placement of the semicolon above
2780 always @* begin
2781 if (....) begin
2782 splitme = ....;
2783 other assignments
2784 end
2785 end
2786 Verilator will internally split the block that assigns to "splitme"
2788 into two blocks:
2789 It would then internally break it into (sort of):
2791 // All assignments excluding those to splitme
2793 always @* begin
2794 if (....) begin
2795 other assignments
2796 end
2797 end
2798 // All assignments to splitme
2799 always @* begin
2800 if (....) begin
2801 splitme = ....;
2802 end
2803 end
2804 Same as "isolate_assignments" in configuration files, see
2806 "CONFIGURATION FILES" for more information.
2807 /*verilator lint_off msg*/
2809 Disable the specified warning message for any warnings following
2810 the comment.
2811 /*verilator lint_on msg*/
2813 Re-enable the specified warning message for any warnings following
2814 the comment.
2815 /*verilator lint_restore*/
2817 After a /*verilator lint_save*/, pop the stack containing lint
2818 message state. Often this is useful at the bottom of include
2819 files.
2820 /*verilator lint_save*/
2822 Push the current state of what lint messages are turned on or
2823 turned off to a stack. Later meta-comments may then lint_on or
2824 lint_off specific messages, then return to the earlier message
2825 state by using /*verilator lint_restore*/. For example:
2826 // verilator lint_save
2828 // verilator lint_off SOME_WARNING
2829 ... // code needing SOME_WARNING turned off
2830 // verilator lint_restore
2831 If SOME_WARNING was on before the lint_off, it will now be restored
2833 to on, and if it was off before the lint_off it will remain off.
2834 /*verilator no_inline_module*/
2836 Specifies the module the comment appears in should not be inlined
2837 into any modules that use this module. This is useful especially
2838 at the top level module to reduce the size of the interface class,
2839 to aid compile time at a small performance loss.
2840 Same as "no_inline" in configuration files, see "CONFIGURATION
2842 FILES" for more information.
2843 /*verilator no_inline_task*/
2845 Used in a function or task variable definition section to specify
2846 the function or task should not be inlined into where it is used.
2847 This may reduce the size of the final executable when a task is
2848 used a very large number of times. For this flag to work, the task
2849 and tasks below it must be pure; they cannot reference any
2850 variables outside the task itself.
2851 Same as "no_inline" in configuration files, see "CONFIGURATION
2853 FILES" for more information.
2854 /*verilator public*/ (parameter)
2856 Used after a parameter declaration to indicate the emitted C code
2857 should have the parameter values visible. Due to C++ language
2858 restrictions, this may only be used on 64-bit or narrower integral
2859 enumerations.
2860 parameter [2:0] PARAM /*verilator public*/ = 2'b0;
2862 /*verilator public*/ (typedef enum)
2864 Used after an enum typedef declaration to indicate the emitted C
2865 code should have the enum values visible. Due to C++ language
2866 restrictions, this may only be used on 64-bit or narrower integral
2867 enumerations.
2868 typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
2870 /*verilator public*/ (variable)
2872 Used after an input, output, register, or wire declaration to
2873 indicate the signal should be declared so that C code may read or
2874 write the value of the signal. This will also declare this module
2875 public, otherwise use /*verilator public_flat*/.
2876 Instead of using public variables, consider instead making a DPI or
2878 public function that accesses the variable. This is nicer as it
2879 provides an obvious entry point that is also compatible across
2880 simulators.
2881 Same as "public" in configuration files, see "CONFIGURATION FILES"
2883 for more information.
2884 /*verilator public*/ (task/function)
2886 Used inside the declaration section of a function or task
2887 declaration to indicate the function or task should be made into a
2888 C++ function, public to outside callers. Public tasks will be
2889 declared as a void C++ function, public functions will get the
2890 appropriate non-void (bool, uint32_t, etc) return type. Any input
2891 arguments will become C++ arguments to the function. Any output
2892 arguments will become C++ reference arguments. Any local
2893 registers/integers will become function automatic variables on the
2894 stack.
2895 Wide variables over 64 bits cannot be function returns, to avoid
2897 exposing complexities. However, wide variables can be
2898 input/outputs; they will be passed as references to an array of
2899 32-bit numbers.
2900 Generally, only the values of stored state (flops) should be
2902 written, as the model will NOT notice changes made to variables in
2903 these functions. (Same as when a signal is declared public.)
2904 You may want to use DPI exports instead, as it's compatible with
2906 other simulators.
2907 Same as "public" in configuration files, see "CONFIGURATION FILES"
2909 for more information.
2910 /*verilator public_flat*/ (variable)
2912 Used after an input, output, register, or wire declaration to
2913 indicate the signal should be declared so that C code may read or
2914 write the value of the signal. This will not declare this module
2915 public, which means the name of the signal or path to it may change
2916 based upon the module inlining which takes place.
2917 Same as "public_flat" in configuration files, see "CONFIGURATION
2919 FILES" for more information.
2920 /*verilator public_flat_rd*/ (variable)
2922 Used after an input, output, register, or wire declaration to
2923 indicate the signal should be declared public_flat (see above), but
2924 read-only.
2925 Same as "public_flat_rd" in configuration files, see "CONFIGURATION
2927 FILES" for more information.
2928 /*verilator public_flat_rw @(<edge_list>) */ (variable)
2930 Used after an input, output, register, or wire declaration to
2931 indicate the signal should be declared public_flat_rd (see above),
2932 and also writable, where writes should be considered to have the
2933 timing specified by the given sensitivity edge list. Set for all
2934 variables, ports and wires using the --public-flat-rw switch.
2935 Same as "public_flat_rw" in configuration files, see "CONFIGURATION
2937 FILES" for more information.
2938 /*verilator public_module*/
2940 Used after a module statement to indicate the module should not be
2941 inlined (unless specifically requested) so that C code may access
2942 the module. Verilator automatically sets this attribute when the
2943 module contains any public signals or `systemc_ directives. Also
2944 set for all modules when using the --public switch.
2945 Same as "public" in configuration files, see "CONFIGURATION FILES"
2947 for more information.
2948 /*verilator sc_clock*/
2950 Deprecated. Used after an input declaration to indicate the signal
2951 should be declared in SystemC as a sc_clock instead of a bool.
2952 This was needed in SystemC 1.1 and 1.2 only; versions 2.0 and later
2953 do not require clock pins to be sc_clocks and this is no longer
2954 needed.
2955 /*verilator sc_bv*/
2957 Used after a port declaration. It sets the port to be of
2958 sc_bv<width> type, instead of bool, vluint32_t or vluint64_t. This
2959 may be useful if the port width is parameterized and different of
2960 such modules interface a templated module (such as a transactor) or
2961 for other reasons. In general you should avoid using this
2962 attribute when not necessary as with increasing usage of sc_bv the
2963 performance decreases significantly.
2964 Same as "sc_bv" in configuration files, see "CONFIGURATION FILES"
2966 for more information.
2967 /*verilator sformat*/
2969 Attached to the final input of a function or task "input string" to
2970 indicate the function or task should pass all remaining arguments
2971 through $sformatf. This allows creation of DPI functions with
2972 $display like behavior. See the test_regress/t/t_dpi_display.v
2973 file for an example.
2974 Same as "sformat" in configuration files, see "CONFIGURATION FILES"
2976 for more information.
2977 /*verilator tag <text...>*/
2979 Attached after a variable or structure member to indicate opaque
2980 (to Verilator) text that should be passed through to the XML output
2981 as a tag, for use by downstream applications.
2982 /*verilator tracing_off*/
2984 Disable waveform tracing for all future signals that are declared
2985 in this module, or cells below this module. Often this is placed
2986 just after a primitive's module statement, so that the entire
2987 module and cells below it are not traced.
2988 /*verilator tracing_on*/
2990 Re-enable waveform tracing for all future signals or cells that are
2991 declared.
2992
2994 There are some limitations and lack of features relative to a
2995 commercial simulator, by intent. User beware.
2996 It is strongly recommended you use a lint tool before running this
2998 program. Verilator isn't designed to easily uncover common mistakes
2999 that a lint program will find for you.
3000 Synthesis Subset
3002 Verilator supports only the Synthesis subset with a few minor additions
3003 such as $stop, $finish and $display. That is, you cannot use
3004 hierarchical references, events or similar features of the Verilog
3005 language. It also simulates as Synopsys's Design Compiler would;
3006 namely a block of the form:
3007 always @ (x) y = x & z;
3009 This will recompute y when there is even a potential for change in x or
3011 a change in z, that is when the flops computing x or z evaluate (which
3012 is what Design Compiler will synthesize.) A compliant simulator would
3013 only calculate y if x changes. Use Verilog-Mode's /*AS*/ or Verilog
3014 2001's always @* to reduce missing activity items. Avoid putting
3015 $displays in combo blocks, as they may print multiple times when not
3016 desired, even on compliant simulators as event ordering is not
3017 specified.
3018 Signal Naming
3020 To avoid conflicts with C symbol naming, any character in a signal name
3021 that is not alphanumeric nor a single underscore will be replaced by
3022 __0hh where hh is the hex code of the character. To avoid conflicts
3023 with Verilator's internal symbols, any double underscore are replaced
3024 with ___05F (5F is the hex code of an underscore.)
3025 Bind
3027 Verilator only supports "bind" to a target module name, not an instance
3028 path.
3029 Dotted cross-hierarchy references
3031 Verilator supports dotted references to variables, functions and tasks
3032 in different modules. However, references into named blocks and
3033 function-local variables are not supported. The portion before the dot
3034 must have a constant value; for example a[2].b is acceptable, while
3035 a[x].b is not.
3036 References into generated and arrayed instances use the instance names
3038 specified in the Verilog standard; arrayed instances are named
3039 {cellName}[{instanceNumber}] in Verilog, which becomes
3040 {cellname}__BRA__{instanceNumber}__KET__ inside the generated C++ code.
3041 Verilator creates numbered "genblk" when a begin: name is not specified
3043 around a block inside a generate statement. These numbers may differ
3044 between other simulators, but the Verilog specification does not allow
3045 users to use these names, so it should not matter.
3046 If you are having trouble determining where a dotted path goes wrong,
3048 note that Verilator will print a list of known scopes to help your
3049 debugging.
3050 Floating Point
3052 Short floating point (shortreal) numbers are converted to real.
3053 Latches
3055 Verilator is optimized for edge sensitive (flop based) designs. It
3056 will attempt to do the correct thing for latches, but most performance
3057 optimizations will be disabled around the latch.
3058 Structures and Unions
3060 Verilator only presently supports packed structs and packed unions.
3061 Rand and randc tags on members are simply ignored. All structures and
3062 unions are represented as a single vector, which means that generating
3063 one member of a structure from blocking, and another from non-blocking
3064 assignments is unsupported.
3065 Time
3067 All delays (#) are ignored, as they are in synthesis.
3068 Unknown states
3070 Verilator is mostly a two state simulator, not a four state simulator.
3071 However, it has two features which uncover most initialization bugs
3072 (including many that a four state simulator will miss.)
3073 Identity comparisons (=== or !==) are converted to standard ==/!== when
3075 neither side is a constant. This may make the expression result differ
3076 from a four state simulator. An === comparison to X will always be
3077 false, so that Verilog code which checks for uninitialized logic will
3078 not fire.
3079 Assigning a variable to a X will actually assign the variable to a
3081 random value (see the --x-assign switch and +verilator+rand+reset
3082 simulation runtime switch.) Thus if the value is actually used, the
3083 random value should cause downstream errors. Integers also randomize,
3084 even though the Verilog 2001 specification says they initialize to
3085 zero.
3086 All variables, depending on --x-initial setting, are typically randomly
3088 initialized using a function. By running several random simulation
3089 runs you can determine that reset is working correctly. On the first
3090 run, the function initializes variables to zero. On the second, have
3091 it initialize variables to one. On the third and following runs have
3092 it initialize them randomly. If the results match, reset works. (Note
3093 this is what the hardware will really do.) In practice, just setting
3094 all variables to one at startup finds most problems (since typically
3095 control signals are active-high).
3096 --x-assign applies to variables explicitly initialized or assigned to
3098 X. Uninitialized clocks are initialized to zero, while all other state
3099 holding variables are initialized to a random value. Event driven
3100 simulators will generally trigger an edge on a transition from X to 1
3101 ("posedge") or X to 0 ("negedge"). However, by default, since clocks
3102 are initialized to zero, Verilator will not trigger an initial negedge.
3103 Some code (particularly for reset) may rely on X->0 triggering an edge.
3104 The --x-initial-edge switch enables this behavior. Comparing runs with
3105 and without this switch will find such problems.
3106 Tri/Inout
3108 Verilator converts some simple tristate structures into two state.
3109 Pullup, pulldown, bufif0, bufif1, notif0, notif1, pmos, nmos, tri0 and
3110 tri1 are also supported. Simple comparisons with === 1'bz are also
3111 supported.
3112 An assignment of the form:
3114 inout driver;
3116 wire driver = (enable) ? output_value : 1'bz;
3117 Will be converted to
3119 input driver; // Value being driven in from "external" drivers
3121 output driver__en; // True if driven from this module
3122 output driver__out; // Value being driven from this module
3123 External logic will be needed to combine these signals with any
3125 external drivers.
3126 Tristate drivers are not supported inside functions and tasks; an inout
3128 there will be considered a two state variable that is read and written
3129 instead of a four state variable.
3130 Functions & Tasks
3132 All functions and tasks will be inlined (will not become functions in
3133 C.) The only support provided is for simple statements in tasks (which
3134 may affect global variables).
3135 Recursive functions and tasks are not supported. All inputs and
3137 outputs are automatic, as if they had the Verilog 2001 "automatic"
3138 keyword prepended. (If you don't know what this means, Verilator will
3139 do what you probably expect -- what C does. The default behavior of
3140 Verilog is different.)
3141 Generated Clocks
3143 Verilator attempts to deal with generated and enabled clocks correctly,
3144 however some cases cause problems in the scheduling algorithm which is
3145 optimized for performance. The safest option is to have all clocks as
3146 primary inputs to the model, or wires directly attached to primary
3147 inputs. For proper behavior clock enables may also need the
3148 /*verilator clock_enable*/ attribute.
3149 Ranges must be big-bit-endian
3151 Bit ranges must be numbered with the MSB being numbered greater or the
3152 same as the LSB. Little-bit-endian buses [0:15] are not supported as
3153 they aren't easily made compatible with C++.
3154 Gate Primitives
3156 The 2-state gate primitives (and, buf, nand, nor, not, or, xnor, xor)
3157 are directly converted to behavioral equivalents. The 3-state and MOS
3158 gate primitives are not supported. Tables are not supported.
3159 Specify blocks
3161 All specify blocks and timing checks are ignored.
3162 Array Initialization
3164 When initializing a large array, you need to use non-delayed
3165 assignments. Verilator will tell you when this needs to be fixed; see
3166 the BLKLOOPINIT error for more information.
3167 Array Out of Bounds
3169 Writing a memory element that is outside the bounds specified for the
3170 array may cause a different memory element inside the array to be
3171 written instead. For power-of-2 sized arrays, Verilator will give a
3172 width warning and the address. For non-power-of-2-sizes arrays, index
3173 0 will be written.
3174 Reading a memory element that is outside the bounds specified for the
3176 array will give a width warning and wrap around the power-of-2 size.
3177 For non-power-of-2 sizes, it will return a unspecified constant of the
3178 appropriate width.
3179 Assertions
3181 Verilator is beginning to add support for assertions. Verilator
3182 currently only converts assertions to simple "if (...) error"
3183 statements, and coverage statements to increment the line counters
3184 described in the coverage section.
3185 Verilator does not support SEREs yet. All assertion and coverage
3187 statements must be simple expressions that complete in one cycle.
3188 (Arguably SEREs are much of the point, but one must start somewhere.)
3189 Encrypted Verilog
3191 Open source simulators like Verilator are unable to use encrypted RTL
3192 (i.e. IEEE P1735). Talk to your IP vendor about delivering IP blocks
3193 via Verilator's --protect-lib feature.
3194 Language Keyword Limitations
3196 This section describes specific limitations for each language keyword.
3197 `__FILE__, `__LINE__, `begin_keywords, `begin_keywords,
3199 `begin_keywords, `begin_keywords, `begin_keywords, `define, `else,
3200 `elsif, `end_keywords, `endif, `error, `ifdef, `ifndef, `include,
3201 `line, `systemc_ctor, `systemc_dtor, `systemc_header,
3202 `systemc_imp_header, `systemc_implementation, `systemc_interface,
3203 `timescale, `undef, `verilog
3204 Fully supported.
3205 always, always_comb, always_ff, always_latch, and, assign, begin, buf,
3207 byte, case, casex, casez, default, defparam, do-while, else, end,
3208 endcase, endfunction, endgenerate, endmodule, endspecify, endtask,
3209 final, for, function, generate, genvar, if, initial, inout, input, int,
3210 integer, localparam, logic, longint, macromodule, module, nand,
3211 negedge, nor, not, or, output, parameter, posedge, reg, scalared,
3212 shortint, signed, supply0, supply1, task, time, tri, typedef, var,
3213 vectored, while, wire, xnor, xor
3214 Generally supported.
3215 ++, -- operators
3217 Increment/decrement can only be used as standalone statements or in
3218 for loops. They cannot be used as side effect operators inside
3219 more complicate expressions ("a = b++;").
3220 '{} operator
3222 Assignment patterns with order based, default, constant integer
3223 (array) or member identifier (struct/union) keys are supported.
3224 Data type keys and keys which are computed from a constant
3225 expression are not supported.
3226 `uselib
3228 Uselib, a vendor specific library specification method, is ignored
3229 along with anything following it until the end of that line.
3230 cast operator
3232 Casting is supported only between simple scalar types, signed and
3233 unsigned, not arrays nor structs.
3234 chandle
3236 Treated as a "longint"; does not yet warn about operations that are
3237 specified as illegal on chandles.
3238 disable
3240 Disable statements may be used only if the block being disabled is
3241 a block the disable statement itself is inside. This was commonly
3242 used to provide loop break and continue functionality before
3243 SystemVerilog added the break and continue keywords.
3244 inside
3246 Inside expressions may not include unpacked array traversal or $ as
3247 an upper bound. Case inside and case matches are also unsupported.
3248 interface
3250 Interfaces and modports, including with generated data types are
3251 supported. Generate blocks around modports are not supported, nor
3252 are virtual interfaces nor unnamed interfaces.
3253 priority if, unique if
3255 Priority and unique if's are treated as normal ifs and not asserted
3256 to be full nor unique.
3257 specify specparam
3259 All specify blocks and timing checks are ignored.
3260 string
3262 String is supported only to the point that they can be assigned,
3263 concatenated, compared, and passed to DPI imports. Standard method
3264 calls on strings are not supported.
3265 timeunit, timeprecision
3267 All timing control statements are ignored.
3268 uwire
3270 Verilator does not perform warning checking on uwires, it treats
3271 the uwire keyword as if it were the normal wire keyword.
3272 $bits, $countones, $error, $fatal, $finish, $info, $isunknown, $onehot,
3274 $onehot0, $readmemb, $readmemh, $signed, $stime, $stop, $time,
3275 $unsigned, $warning.
3276 Generally supported.
3277 $display, $write, $fdisplay, $fwrite, $swrite
3279 $display and friends must have a constant format string as the
3280 first argument (as with C's printf). The rare usage which lists
3281 variables standalone without a format is not supported.
3282 $displayb, $displayh, $displayo, $writeb, $writeh, $writeo, etc
3284 The sized display functions are rarely used and so not supported.
3285 Replace them with a $write with the appropriate format specifier.
3286 $finish, $stop
3288 The rarely used optional parameter to $finish and $stop is ignored.
3289 $fopen, $fclose, $fdisplay, $feof, $fflush, $fgetc, $fgets, $fscanf,
3291 $fwrite
3292 File descriptors passed to the file PLI calls must be file
3293 descriptors, not MCDs, which includes the mode parameter to $fopen
3294 being mandatory.
3295 $fscanf, $sscanf
3297 The formats %r, %v, and %z are not supported.
3298 $fullskew, $hold, $nochange, $period, $recovery, $recrem, $removal,
3300 $setup, $setuphold, $skew, $timeskew, $width
3301 All specify blocks and timing checks are ignored.
3302 $random
3304 $random does not support the optional argument to set the seed.
3305 Use the srand function in C to accomplish this, and note there is
3306 only one random number generator (not one per module).
3307 $readmemb, $readmemh
3309 Read memory commands should work properly. Note Verilator and the
3310 Verilog specification does not include support for readmem to
3311 multi-dimensional arrays.
3312 $test$plusargs, $value$plusargs
3314 Supported, but the instantiating C++/SystemC testbench must call
3315 Verilated::commandArgs(argc, argv);
3317 to register the command line before calling $test$plusargs or
3319 $value$plusargs.
3320 $timeformat
3322 Not supported as Verilator needs to determine all formatting at
3323 compile time. Generally you can just ifdef them out for no ill
3324 effect. Note also VL_TIME_MULTIPLIER can be defined at compile
3325 time to move the decimal point when displaying all times, model
3326 wide.
3327
3329 Warnings may be disabled in three ways. First, when the warning is
3330 printed it will include a warning code. Simply surround the offending
3331 line with a warn_off/warn_on pair:
3332 // verilator lint_off UNSIGNED
3334 if (`DEF_THAT_IS_EQ_ZERO <= 3) $stop;
3335 // verilator lint_on UNSIGNED
3336 Second, warnings may be disabled using a configuration file with a
3338 lint_off command. This is useful when a script is suppressing warnings
3339 and the Verilog source should not be changed.
3340 Warnings may also be globally disabled by invoking Verilator with the
3342 "-Wno-warning" switch. This should be avoided, as it removes all
3343 checking across the designs, and prevents other users from compiling
3344 your code without knowing the magic set of disables needed to
3345 successfully compile your design.
3346 List of all warnings:
3348 ALWCOMBORDER
3350 Warns that an always_comb block has a variable which is set after
3351 it is used. This may cause simulation-synthesis mismatches, as not
3352 all commercial simulators allow this ordering.
3353 always_comb begin
3355 a = b;
3356 b = 1;
3357 end
3358 Ignoring this warning will only suppress the lint check, it will
3360 simulate correctly.
3361 ASSIGNIN
3363 Error that an assignment is being made to an input signal. This is
3364 almost certainly a mistake, though technically legal.
3365 input a;
3367 assign a = 1'b1;
3368 Ignoring this warning will only suppress the lint check, it will
3370 simulate correctly.
3371 ASSIGNDLY
3373 Warns that you have an assignment statement with a delayed time in
3374 front of it, for example:
3375 a <= #100 b;
3377 assign #100 a = b;
3378 Ignoring this warning may make Verilator simulations differ from
3380 other simulators, however at one point this was a common style so
3381 disabled by default as a code style warning.
3382 BLKANDNBLK
3384 BLKANDNBLK is an error that a variable comes from a mix of blocked
3385 and non-blocking assignments. Generally, this is caused by a
3386 register driven by both combo logic and a flop:
3387 always @ (posedge clk) foo[0] <= ...
3389 always @* foo[1] = ...
3390 Simply use a different register for the flop:
3392 always @ (posedge clk) foo_flopped[0] <= ...
3394 always @* foo[0] = foo_flopped[0];
3395 always @* foo[1] = ...
3396 This is not illegal in SystemVerilog, but a violation of good
3398 coding practice. Verilator reports this as an error, because
3399 ignoring this warning may make Verilator simulations differ from
3400 other simulators.
3401 It is generally safe to disable this error (with a "// verilator
3403 lint_off BLKANDNBLK" metacomment or the -Wno-BLKANDNBLK option)
3404 when one of the assignments is inside a public task, or when the
3405 blocked and non-blocking assignments have non-overlapping bits and
3406 structure members.
3407 BLKSEQ
3409 This indicates that a blocking assignment (=) is used in a
3410 sequential block. Generally non-blocking/delayed assignments (<=)
3411 are used in sequential blocks, to avoid the possibility of
3412 simulator races. It can be reasonable to do this if the generated
3413 signal is used ONLY later in the same block, however this style is
3414 generally discouraged as it is error prone.
3415 always @ (posedge clk) foo = ...
3417 Disabled by default as this is a code style warning; it will
3419 simulate correctly.
3420 BLKLOOPINIT
3422 This indicates that the initialization of an array needs to use
3423 non-delayed assignments. This is done in the interest of speed; if
3424 delayed assignments were used, the simulator would have to copy
3425 large arrays every cycle. (In smaller loops, loop unrolling allows
3426 the delayed assignment to work, though it's a bit slower than a
3427 non-delayed assignment.) Here's an example
3428 always @ (posedge clk)
3430 if (~reset_l) begin
3431 for (i=0; i<`ARRAY_SIZE; i++) begin
3432 array[i] = 0; // Non-delayed for verilator
3433 end
3434 This message is only seen on large or complicated loops because
3436 Verilator generally unrolls small loops. You may want to try
3437 increasing --unroll-count (and occasionally --unroll-stmts) which
3438 will raise the small loop bar to avoid this error.
3439 BOUNDED
3441 This indicates that bounded queues (e.g. "var name[$ : 3]") are
3442 unsupported.
3443 Ignoring this warning may make Verilator simulations differ from
3445 other simulators.
3446 BSSPACE
3448 Warns that a backslash is followed by a space then a newline.
3449 Likely the intent was to have a backslash directly followed by a
3450 newline (e.g. when making a `define) and there's accidentally
3451 whitespace at the end of the line. If the space is not accidental,
3452 suggest removing the backslash in the code as it serves no
3453 function.
3454 Ignoring this warning will only suppress the lint check, it will
3456 simulate correctly.
3457 CASEINCOMPLETE
3459 Warns that inside a case statement there is a stimulus pattern for
3460 which there is no case item specified. This is bad style, if a
3461 case is impossible, it's better to have a "default: $stop;" or just
3462 "default: ;" so that any design assumption violations will be
3463 discovered in simulation.
3464 Ignoring this warning will only suppress the lint check, it will
3466 simulate correctly.
3467 CASEOVERLAP
3469 Warns that inside a case statement you have case values which are
3470 detected to be overlapping. This is bad style, as moving the order
3471 of case values will cause different behavior. Generally the values
3472 can be respecified to not overlap.
3473 Ignoring this warning will only suppress the lint check, it will
3475 simulate correctly.
3476 CASEX
3478 Warns that it is simply better style to use casez, and "?" in place
3479 of "x"'s. See
3480 <http://www.sunburst-design.com/papers/CummingsSNUG1999Boston_FullParallelCase_rev1_1.pdf>
3481 Ignoring this warning will only suppress the lint check, it will
3483 simulate correctly.
3484 CASEWITHX
3486 Warns that a case statement contains a constant with a "x".
3487 Verilator is two-state so interpret such items as always false.
3488 Note a common error is to use a "X" in a case or casez statement
3489 item; often what the user instead intended is to use a casez with
3490 "?".
3491 Ignoring this warning will only suppress the lint check, it will
3493 simulate correctly.
3494 CDCRSTLOGIC
3496 With --cdc only, warns that asynchronous flop reset terms come from
3497 other than primary inputs or flopped outputs, creating the
3498 potential for reset glitches.
3499 CLKDATA
3501 Warns that clock signal is mixed used with/as data signal. The
3502 checking for this warning is enabled only if user has explicitly
3503 marked some signal as clocker using command line option or in-
3504 source meta comment (see "--clk").
3505 The warning can be disabled without affecting the simulation
3507 result. But it is recommended to check the warning as this may
3508 degrade the performance of the Verilated model.
3509 CMPCONST
3511 Warns that you are comparing a value in a way that will always be
3512 constant. For example "X > 1" will always be true when X is a
3513 single bit wide.
3514 Ignoring this warning will only suppress the lint check, it will
3516 simulate correctly.
3517 COLONPLUS
3519 Warns that a :+ is seen. Likely the intent was to use +: to select
3520 a range of bits. If the intent was a range that is explicitly
3521 positive, suggest adding a space, e.g. use ": +".
3522 Ignoring this warning will only suppress the lint check, it will
3524 simulate correctly.
3525 COMBDLY
3527 Warns that you have a delayed assignment inside of a combinatorial
3528 block. Using delayed assignments in this way is considered bad
3529 form, and may lead to the simulator not matching synthesis. If
3530 this message is suppressed, Verilator, like synthesis, will convert
3531 this to a non-delayed assignment, which may result in logic races
3532 or other nasties. See
3533 <http://www.sunburst-design.com/papers/CummingsSNUG2000SJ_NBA_rev1_2.pdf>
3534 Ignoring this warning may make Verilator simulations differ from
3536 other simulators.
3537 CONTASSREG
3539 Error that a continuous assignment is setting a reg. According to
3540 IEEE Verilog, but not SystemVerilog, a wire must be used as the
3541 target of continuous assignments.
3542 This error is only reported when "--language 1364-1995",
3544 "--language 1364-2001", or "--language 1364-2005" is used.
3545 Ignoring this error will only suppress the lint check, it will
3547 simulate correctly.
3548 DECLFILENAME
3550 Warns that a module or other declaration's name doesn't match the
3551 filename with path and extension stripped that it is declared in.
3552 The filename a modules/interfaces/programs is declared in should
3553 match the name of the module etc. so that -y directory searching
3554 will work. This warning is printed for only the first mismatching
3555 module in any given file, and -v library files are ignored.
3556 Disabled by default as this is a code style warning; it will
3558 simulate correctly.
3559 DEFPARAM
3561 Warns that the "defparam" statement was deprecated in Verilog 2001
3562 and all designs should now be using the #(...) format to specify
3563 parameters.
3564 Disabled by default as this is a code style warning; it will
3566 simulate correctly.
3567 DETECTARRAY
3569 Error when Verilator tries to deal with a combinatorial loop that
3570 could not be flattened, and which involves a datatype which
3571 Verilator cannot handle, such as an unpacked struct or a large
3572 unpacked array. This typically occurs when -Wno-UNOPTFLAT has been
3573 used to override an UNOPTFLAT warning (see below).
3574 The solution is to break the loop, as described for UNOPTFLAT.
3576 DIDNOTCONVERGE
3578 Error at simulation runtime when model did not properly settle.
3579 Verilator sometimes has to evaluate combinatorial logic multiple
3581 times, usually around code where a UNOPTFLAT warning was issued,
3582 but disabled. For example:
3583 always_comb b = ~a;
3585 always_comb a = b
3586 This code will toggle forever, and thus to prevent an infinite
3588 loop, the executable will give the didn't converge error.
3589 To debug this, first is to review any UNOPTFLAT warnings that were
3591 ignored. Though typically it is safe to ignore UNOPTFLAT (at a
3592 performance cost), at the time of issuing a UNOPTFLAT Verilator
3593 didn't know if they would eventually converge and assumed the
3594 would.
3595 Next, run Verilator with --prof-cfuncs. Run make on the generated
3597 files with "CPP_FLAGS=-DVL_DEBUG", to allow enabling simulation
3598 runtime debug messages. Rerun the test. Now just before the
3599 convergence error you should see additional output similar to this:
3600 CHANGE: filename.v:1: b
3602 CHANGE: filename.v:2: a
3603 This means that signal b and signal a keep changing, inspect the
3605 code that modifies these signals. Note if many signals are getting
3606 printed then most likely all of them are oscillating. It may also
3607 be that e.g. "a" may be oscillating, then "a" feeds signal "c"
3608 which then is also reported as oscillating.
3609 Finally, rare, more difficult cases can be debugged like a "C"
3611 program; either enter GDB and use its tracing facilities, or edit
3612 the generated C++ code to add appropriate prints to see what is
3613 going on.
3614 ENDLABEL
3616 Warns that a label attached to a "end"-something statement does not
3617 match the label attached to the block start.
3618 Ignoring this warning will only suppress the lint check, it will
3620 simulate correctly.
3621 GENCLK
3623 Warns that the specified signal is generated, but is also being
3624 used as a clock. Verilator needs to evaluate sequential logic
3625 multiple times in this situation. In somewhat contrived cases
3626 having any generated clock can reduce performance by almost a
3627 factor of two. For fastest results, generate ALL clocks outside in
3628 C++/SystemC and make them primary inputs to your Verilog model.
3629 (However once need to you have even one, don't sweat additional
3630 ones.)
3631 Ignoring this warning may make Verilator simulations differ from
3633 other simulators.
3634 IFDEPTH
3636 Warns that if/if else statements have exceeded the depth specified
3637 with --if-depth, as they are likely to result in slow priority
3638 encoders. Unique and priority if statements are ignored.
3639 Solutions include changing the code to a case statement, or a
3640 SystemVerilog 'unique if' or 'priority if'.
3641 Disabled by default as this is a code style warning; it will
3643 simulate correctly.
3644 IGNOREDRETURN
3646 Warns that a non-void function is being called as a task, and hence
3647 the return value is being ignored.
3648 This warning is required by IEEE. The portable way to suppress this
3650 warning (in SystemVerilog) is to use a void cast, e.g.
3651 void'(function_being_called_as_task());
3653 Ignoring this warning will only suppress the lint check, it will
3655 simulate correctly.
3656 IMPERFECTSCH
3658 Warns that the scheduling of the model is not absolutely perfect,
3659 and some manual code edits may result in faster performance. This
3660 warning defaults to off, is not part of -Wall, and must be turned
3661 on explicitly before the top module statement is processed.
3662 IMPLICIT
3664 Warns that a wire is being implicitly declared (it is a single bit
3665 wide output from a sub-module.) While legal in Verilog, implicit
3666 declarations only work for single bit wide signals (not buses), do
3667 not allow using a signal before it is implicitly declared by a
3668 cell, and can lead to dangling nets. A better option is the
3669 /*AUTOWIRE*/ feature of Verilog-Mode for Emacs, available from
3670 <https://www.veripool.org/verilog-mode>
3671 Ignoring this warning will only suppress the lint check, it will
3673 simulate correctly.
3674 IMPORTSTAR
3676 Warns that an "import package::*" statement is in $unit scope. This
3677 causes the imported symbols to pollute the global namespace,
3678 defeating much of the purpose of having a package. Generally
3679 "import ::*" should only be used inside a lower scope such as a
3680 package or module.
3681 Disabled by default as this is a code style warning; it will
3683 simulate correctly.
3684 IMPURE
3686 Warns that a task or function that has been marked with /*verilator
3687 no_inline_task*/ references variables that are not local to the
3688 task. Verilator cannot schedule these variables correctly.
3689 Ignoring this warning may make Verilator simulations differ from
3691 other simulators.
3692 INCABSPATH
3694 Warns that an `include filename specifies an absolute path. This
3695 means the code will not work on any other system with a different
3696 file system layout. Instead of using absolute paths, relative
3697 paths (preferably without any directory specified whatever) should
3698 be used, and +incdir used on the command line to specify the top
3699 include source directories.
3700 Disabled by default as this is a code style warning; it will
3702 simulate correctly.
3703 INFINITELOOP
3705 Warns that a while or for statement has a condition that is always
3706 true. and thus result in an infinite loop if the statement ever
3707 executes.
3708 This might be unintended behavior if the loop body contains
3710 statements that in other statements that would make time pass,
3711 which Verilator is ignoring due to e.g. STMTDLY warnings being
3712 disabled.
3713 Ignoring this warning will only suppress the lint check, it will
3715 simulate correctly (i.e. hang due to the infinite loop).
3716 INITIALDLY
3718 Warns that you have a delayed assignment inside of an initial or
3719 final block. If this message is suppressed, Verilator will convert
3720 this to a non-delayed assignment. See also the COMBDLY warning.
3721 Ignoring this warning may make Verilator simulations differ from
3723 other simulators.
3724 INSECURE
3726 Warns that the combination of options selected may be defeating the
3727 attempt to protect/obscure identifiers or hide information in the
3728 model. Correct the options provided, or inspect the output code to
3729 see if the information exposed is acceptable.
3730 Ignoring this warning will only suppress the lint check, it will
3732 simulate correctly.
3733 LITENDIAN
3735 Warns that a packed vector is declared with little endian bit
3736 numbering (i.e. [0:7]). Big endian bit numbering is now the
3737 overwhelming standard, and little numbering is now thus often due
3738 to simple oversight instead of intent.
3739 Also warns that a cell is declared with little endian range (i.e.
3741 [0:7] or [7]) and is connected to a N-wide signal. Based on IEEE
3742 the bits will likely be backwards from what you expect (i.e. cell
3743 [0] will connect to signal bit [N-1] not bit [0]).
3744 Ignoring this warning will only suppress the lint check, it will
3746 simulate correctly.
3747 MODDUP
3749 Warns that a module has multiple definitions. Generally this
3750 indicates a coding error, or a mistake in a library file and it's
3751 good practice to have one module per file (and only put each file
3752 once on the command line) to avoid these issues. For some gate
3753 level netlists duplicates are sometimes unavoidable, and MODDUP
3754 should be disabled.
3755 Ignoring this warning will cause the more recent module definition
3757 to be discarded.
3758 MULTIDRIVEN
3760 Warns that the specified signal comes from multiple always blocks.
3761 This is often unsupported by synthesis tools, and is considered bad
3762 style. It will also cause longer simulation runtimes due to
3763 reduced optimizations.
3764 Ignoring this warning will only slow simulations, it will simulate
3766 correctly.
3767 MULTITOP
3769 Warns that there are multiple top level modules, that is modules
3770 not instantiated by any other module, and both modules were put on
3771 the command line (not in a library). Three likely cases:
3772 1. A single module is intended to be the top. This warning then
3774 occurs because some low level cell is being read in, but is not
3775 really needed as part of the design. The best solution for this
3776 situation is to ensure that only the top module is put on the
3777 command line without any flags, and all remaining library files are
3778 read in as libraries with -v, or are automatically resolved by
3779 having filenames that match the module names.
3780 2. A single module is intended to be the top, the name of it is
3782 known, and all other modules should be ignored if not part of the
3783 design. The best solution is to use the --top-module option to
3784 specify the top module's name. All other modules that are not part
3785 of the design will be for the most part ignored (they must be clean
3786 in syntax and their contents will be removed as part of the Verilog
3787 module elaboration process.)
3788 3. Multiple modules are intended to be design tops, e.g. when
3790 linting a library file. As multiple modules are desired, disable
3791 the MULTITOP warning. All input/outputs will go uniquely to each
3792 module, with any conflicting and identical signal names being
3793 uniquified by adding a prefix based on the top module name followed
3794 by __02E (a Verilator-encoded ASCII ".'). This renaming is done
3795 even if the two modules' signals seem identical, e.g. multiple
3796 modules with a "clk" input.
3797 PINCONNECTEMPTY
3799 Warns that a cell instantiation has a pin which is connected to
3800 .pin_name(), e.g. not another signal, but with an explicit mention
3801 of the pin. It may be desirable to disable PINCONNECTEMPTY, as
3802 this indicates intention to have a no-connect.
3803 Disabled by default as this is a code style warning; it will
3805 simulate correctly.
3806 PINMISSING
3808 Warns that a module has a pin which is not mentioned in a cell
3809 instantiation. If a pin is not missing it should still be
3810 specified on the cell declaration with a empty connection, using
3811 "(.pin_name())".
3812 Ignoring this warning will only suppress the lint check, it will
3814 simulate correctly.
3815 PINNOCONNECT
3817 Warns that a cell instantiation has a pin which is not connected to
3818 another signal.
3819 Disabled by default as this is a code style warning; it will
3821 simulate correctly.
3822 PROCASSWIRE
3824 Error that a procedural assignment is setting a wire. According to
3825 IEEE, a var/reg must be used as the target of procedural
3826 assignments.
3827 REALCVT
3829 Warns that a real number is being implicitly rounded to an integer,
3830 with possible loss of precision.
3831 REDEFMACRO
3833 Warns that you have redefined the same macro with a different
3834 value, for example:
3835 `define MACRO def1
3837 //...
3838 `define MACRO otherdef
3839 The best solution is to use a different name for the second macro.
3841 If this is not possible, add a undef to indicate the code is
3842 overriding the value:
3843 `define MACRO def1
3845 //...
3846 `undef MACRO
3847 `define MACRO otherdef
3848 SELRANGE
3850 Warns that a selection index will go out of bounds:
3851 wire vec[6:0];
3853 initial out = vec[7]; // There is no 7
3854 Verilator will assume zero for this value, instead of X. Note that
3856 in some cases this warning may be false, when a condition upstream
3857 or downstream of the access means the access out of bounds will
3858 never execute or be used.
3859 wire vec[6:0];
3861 initial begin
3862 seven = 7;
3863 ...
3864 if (seven != 7) out = vec[seven]; // Never will use vec[7]
3865 SHORTREAL
3867 Warns that Verilator does not support "shortreal" and they will be
3868 automatically promoted to "real". The recommendation is to replace
3869 any "shortreal" in the code with "real", as "shortreal" is not
3870 widely supported across industry tools.
3871 Ignoring this warning may make Verilator simulations differ from
3873 other simulators, if the increased precision of real affects your
3874 model or DPI calls.
3875 STMTDLY
3877 Warns that you have a statement with a delayed time in front of it,
3878 for example:
3879 #100 $finish;
3881 Ignoring this warning may make Verilator simulations differ from
3883 other simulators.
3884 SYMRSVDWORD
3886 Warning that a symbol matches a C++ reserved word and using this as
3887 a symbol name would result in odd C compiler errors. You may
3888 disable this warning, but the symbol will be renamed by Verilator
3889 to avoid the conflict.
3890 SYNCASYNCNET
3892 Warns that the specified net is used in at least two different
3893 always statements with posedge/negedges (i.e. a flop). One usage
3894 has the signal in the sensitivity list and body, probably as an
3895 async reset, and the other usage has the signal only in the body,
3896 probably as a sync reset. Mixing sync and async resets is usually
3897 a mistake. The warning may be disabled with a lint_off pragma
3898 around the net, or either flopped block.
3899 Disabled by default as this is a code style warning; it will
3901 simulate correctly.
3902 TASKNSVAR
3904 Error when a call to a task or function has a output from that task
3905 tied to a non-simple signal. Instead connect the task output to a
3906 temporary signal of the appropriate width, and use that signal to
3907 set the appropriate expression as the next statement. For example:
3908 task foo; output sig; ... endtask
3910 always @* begin
3911 foo(bus_we_select_from[2]); // Will get TASKNSVAR error
3912 end
3913 Change this to:
3915 reg foo_temp_out;
3917 always @* begin
3918 foo(foo_temp_out);
3919 bus_we_select_from[2] = foo_temp_out;
3920 end
3921 Verilator doesn't do this conversion for you, as some more
3923 complicated cases would result in simulator mismatches.
3924 TICKCOUNT
3926 Warns that the number of ticks to delay a $past variable is greater
3927 than 10. At present Verilator effectively creates a flop for each
3928 delayed signals, and as such any large counts may lead to large
3929 design size increases.
3930 Ignoring this warning will only slow simulations, it will simulate
3932 correctly.
3933 UNDRIVEN
3935 Warns that the specified signal is never sourced. Verilator is
3936 fairly liberal in the usage calculations; making a signal public,
3937 or loading only a single array element marks the entire signal as
3938 driven.
3939 Disabled by default as this is a code style warning; it will
3941 simulate correctly.
3942 UNOPT
3944 Warns that due to some construct, optimization of the specified
3945 signal or block is disabled. The construct should be cleaned up to
3946 improve simulation runtime.
3947 A less obvious case of this is when a module instantiates two
3949 submodules. Inside submodule A, signal I is input and signal O is
3950 output. Likewise in submodule B, signal O is an input and I is an
3951 output. A loop exists and a UNOPT warning will result if AI & AO
3952 both come from and go to combinatorial blocks in both submodules,
3953 even if they are unrelated always blocks. This affects performance
3954 because Verilator would have to evaluate each submodule multiple
3955 times to stabilize the signals crossing between the modules.
3956 Ignoring this warning will only slow simulations, it will simulate
3958 correctly.
3959 UNOPTFLAT
3961 Warns that due to some construct, optimization of the specified
3962 signal is disabled. The signal specified includes a complete scope
3963 to the signal; it may be only one particular usage of a multiply
3964 instantiated block. The construct should be cleaned up to improve
3965 simulation runtime; two times better performance may be possible by
3966 fixing these warnings.
3967 Unlike the UNOPT warning, this occurs after netlist flattening, and
3969 indicates a more basic problem, as the less obvious case described
3970 under UNOPT does not apply.
3971 Often UNOPTFLAT is caused by logic that isn't truly circular as
3973 viewed by synthesis which analyzes interconnection per-bit, but is
3974 circular to simulation which analyzes per-bus:
3975 wire [2:0] x = {x[1:0], shift_in};
3977 This statement needs to be evaluated multiple times, as a change in
3979 "shift_in" requires "x" to be computed 3 times before it becomes
3980 stable. This is because a change in "x" requires "x" itself to
3981 change value, which causes the warning.
3982 For significantly better performance, split this into 2 separate
3984 signals:
3985 wire [2:0] xout = {x[1:0], shift_in};
3987 and change all receiving logic to instead receive "xout".
3989 Alternatively, change it to
3990 wire [2:0] x = {xin[1:0], shift_in};
3992 and change all driving logic to instead drive "xin".
3994 With this change this assignment needs to be evaluated only once.
3996 These sort of changes may also speed up your traditional event
3997 driven simulator, as it will result in fewer events per cycle.
3998 The most complicated UNOPTFLAT path we've seen was due to low bits
4000 of a bus being generated from an always statement that consumed
4001 high bits of the same bus processed by another series of always
4002 blocks. The fix is the same; split it into two separate signals
4003 generated from each block.
4004 The UNOPTFLAT warning may also be due to clock enables, identified
4006 from the reported path going through a clock gating cell. To fix
4007 these, use the clock_enable meta comment described above.
4008 The UNOPTFLAT warning may also occur where outputs from a block of
4010 logic are independent, but occur in the same always block. To fix
4011 this, use the isolate_assignments meta comment described above.
4012 To assist in resolving UNOPTFLAT, the option "--report-unoptflat"
4014 can be used, which will provide suggestions for variables that can
4015 be split up, and a graph of all the nodes connected in the loop.
4016 See the Arguments section for more details.
4017 Ignoring this warning will only slow simulations, it will simulate
4019 correctly.
4020 UNOPTTHREADS
4022 Warns that the thread scheduler was unable to partition the design
4023 to fill the requested number of threads.
4024 One workaround is to request fewer threads with "--threads".
4026 Another possible workaround is to allow more MTasks in the
4028 simulation runtime, by increasing the value of
4029 --threads-max-mtasks. More MTasks will result in more communication
4030 and synchronization overhead at simulation runtime; the scheduler
4031 attempts to minimize the number of MTasks for this reason.
4032 Ignoring this warning will only slow simulations, it will simulate
4034 correctly.
4035 UNPACKED
4037 Warns that unpacked structs and unions are not supported.
4038 Ignoring this warning will make Verilator treat the structure as
4040 packed, which may make Verilator simulations differ from other
4041 simulators.
4042 UNSIGNED
4044 Warns that you are comparing a unsigned value in a way that implies
4045 it is signed, for example "X < 0" will always be true when X is
4046 unsigned.
4047 Ignoring this warning will only suppress the lint check, it will
4049 simulate correctly.
4050 UNUSED
4052 Warns that the specified signal is never used/consumed. Verilator
4053 is fairly liberal in the usage calculations; making a signal
4054 public, a signal matching --unused-regexp ("*unused*") or accessing
4055 only a single array element marks the entire signal as used.
4056 Disabled by default as this is a code style warning; it will
4058 simulate correctly.
4059 A recommended style for unused nets is to put at the bottom of a
4061 file code similar to the following:
4062 wire _unused_ok = &{1'b0,
4064 sig_not_used_a,
4065 sig_not_used_yet_b, // To be fixed
4066 1'b0};
4067 The reduction AND and constant zeros mean the net will always be
4069 zero, so won't use simulation runtime. The redundant leading and
4070 trailing zeros avoid syntax errors if there are no signals between
4071 them. The magic name "unused" (-unused-regexp) is recognized by
4072 Verilator and suppresses warnings; if using other lint tools,
4073 either teach to tool to ignore signals with "unused" in the name,
4074 or put the appropriate lint_off around the wire. Having unused
4075 signals in one place makes it easy to find what is unused, and
4076 reduces the number of lint_off pragmas, reducing bugs.
4077 USERINFO, USERWARN, USERERROR, USERFATAL
4079 A SystemVerilog elaboration-time assertion print was executed.
4080 VARHIDDEN
4082 Warns that a task, function, or begin/end block is declaring a
4083 variable by the same name as a variable in the upper level module
4084 or begin/end block (thus hiding the upper variable from being able
4085 to be used.) Rename the variable to avoid confusion when reading
4086 the code.
4087 Disabled by default as this is a code style warning; it will
4089 simulate correctly.
4090 WIDTH
4092 Warns that based on width rules of Verilog, two operands have
4093 different widths. Verilator generally can intuit the common usages
4094 of widths, and you shouldn't need to disable this message like you
4095 do with most lint programs. Generally other than simple mistakes,
4096 you have two solutions:
4097 If it's a constant 0 that's 32 bits or less, simply leave it
4099 unwidthed. Verilator considers zero to be any width needed.
4100 Concatenate leading zeros when doing arithmetic. In the statement
4102 wire [5:0] plus_one = from[5:0] + 6'd1 + carry[0];
4104 The best fix, which clarifies intent and will also make all tools
4106 happy is:
4107 wire [5:0] plus_one = from[5:0] + 6'd1 + {5'd0, carry[0]};
4109 Ignoring this warning will only suppress the lint check, it will
4111 simulate correctly.
4112 WIDTHCONCAT
4114 Warns that based on width rules of Verilog, a concatenate or
4115 replication has an indeterminate width. In most cases this
4116 violates the Verilog rule that widths inside concatenates and
4117 replicates must be sized, and should be fixed in the code.
4118 wire [63:0] concat = {1, 2};
4120 An example where this is technically legal (though still bad form)
4122 is:
4123 parameter PAR = 1;
4125 wire [63:0] concat = {PAR, PAR};
4126 The correct fix is to either size the 1 ("32'h1"), or add the width
4128 to the parameter definition ("parameter [31:0]"), or add the width
4129 to the parameter usage ("{PAR[31:0],PAR[31:0]}".
4130 The following describes the less obvious errors:
4132 Internal Error
4134 This error should never occur first, though may occur if earlier
4135 warnings or error messages have corrupted the program. If there
4136 are no other warnings or errors, submit a bug report.
4137 Unsupported: ....
4139 This error indicates that you are using a Verilog language
4140 construct that is not yet supported in Verilator. See the
4141 Limitations chapter.
4142
4144 The following deprecated items are scheduled for future removal:
4145 Pre-C++11 compiler support
4147 Verilator supports pre-C++11 compilers for non-threaded models when
4148 configured with --enable-prec11. This flag will be removed and
4149 C++11 compilers will be required for both compiling Verilator and
4150 compiling Verilated models no sooner than September 2020.
4151 SystemC 2.1 and earlier support
4153 Support for SystemC versions 2.1 and earlier and the related
4154 sc_clock variable attribute will be removed no sooner than July
4155 2020.
4156 Configuration File -msg
4158 The -msg argument to lint_off has been replaced with -rule. -msg
4159 is planned for removal no sooner than January 2021.
4160 XML locations
4162 The XML "fl" attribute has been replaced with "loc". "fl" is
4163 planned for removal no sooner than January 2021.
4164
4166 Can I contribute?
4167 Please contribute! Just file an issue asking for a merge, or ask
4168 on the forums if looking for something to help on. For more
4169 information see our contributor agreement.
4170 How commonly is Verilator used?
4172 Verilator is used by many of the largest silicon design companies,
4173 and all the way down to college projects. Verilator is a "big 4"
4174 simulator, meaning one of the 4 main SystemVerilog simulators
4175 available, namely the commercial products Synopsys' VCS (tm),
4176 Mentor's ModelSim (tm), Cadence Incisive/NC-Verilog/NC-Sim, and the
4177 open-source Verilator. The three commercial choices are commonly
4178 collectively called the "big 3" simulators.
4179 Does Verilator run under Windows?
4181 Yes, using Cygwin. Verilated output also compiles under Microsoft
4182 Visual C++, but this is not tested every release.
4183 Can you provide binaries?
4185 Verilator is available as a RPM for Debian/Ubuntu, SuSE, Fedora,
4186 and other distributions; this is done by porters and may slightly
4187 lag the primary distribution. If there isn't a binary build for
4188 your distribution, how about you set one up? Please contact the
4189 authors for assistance.
4190 Note people sometimes request binaries when they are having
4192 problems with their C++ compiler. Alas, binaries won't help this,
4193 as in the end a fully working C++ compiler is required to compile
4194 the output of Verilator.
4195 How can it be faster than (name-the-commercial-simulator)?
4197 Generally, the implied part is of the question is "... with all of
4198 the manpower they can put into developing it."
4199 Most commercial simulators have to be Verilog compliant, meaning
4201 event driven. This prevents them from being able to reorder blocks
4202 and make netlist-style optimizations, which are where most of the
4203 gains come from.
4204 Non-compliance shouldn't be scary. Your synthesis program isn't
4206 compliant, so your simulator shouldn't have to be -- and Verilator
4207 is closer to the synthesis interpretation, so this is a good thing
4208 for getting working silicon.
4209 Will Verilator output remain under my own license?
4211 Yes, it's just like using GCC on your programs; this is why
4212 Verilator uses the "GNU *Lesser* Public License Version 3" instead
4213 of the more typical "GNU Public License". See the licenses for
4214 details, but in brief, if you change Verilator itself or the header
4215 files Verilator includes, you must make the source code available
4216 under the GNU Lesser Public License. However, Verilator output
4217 (the Verilated code) only "include"s the licensed files, and so you
4218 are NOT required to release any output from Verilator.
4219 You also have the option of using the Perl Artistic License, which
4221 again does not require you release your Verilog or generated code,
4222 and also allows you to modify Verilator for internal use without
4223 distributing the modified version. But please contribute back to
4224 the community!
4225 One limit is that you cannot under either license release a
4227 commercial Verilog simulation product incorporating Verilator
4228 without making the source code available.
4229 As is standard with Open Source, contributions back to Verilator
4231 will be placed under the Verilator copyright and LGPL/Artistic
4232 license. Small test cases will be released into the public domain
4233 so they can be used anywhere, and large tests under the
4234 LGPL/Artistic, unless requested otherwise.
4235 Why is running Verilator (to create a model) so slow?
4237 Verilator needs more memory than the resulting simulator will
4238 require, as Verilator creates internally all of the state of the
4239 resulting generated simulator in order to optimize it. If it takes
4240 more than a minute or so (and you're not using --debug since debug
4241 is disk bound), see if your machine is paging; most likely you need
4242 to run it on a machine with more memory. Verilator is a full
4243 64-bit application and may use more than 4GB, but about 1GB is the
4244 maximum typically needed, and very large commercial designs have
4245 topped 16GB.
4246 How do I generate waveforms (traces) in C++?
4248 See the next question for tracing in SystemC mode.
4249 Add the --trace switch to Verilator, and in your top level C code,
4251 call Verilated::traceEverOn(true). Then create a VerilatedVcdC
4252 object, and in your main loop call "trace_object->dump(time)" every
4253 time step, and finally call "trace_object->close()". For an
4254 example, see below and the examples/make_tracing_c/sim_main.cpp
4255 file of the distribution.
4256 You also need to compile verilated_vcd_c.cpp and add it to your
4258 link, preferably by adding the dependencies in $(VK_GLOBAL_OBJS) to
4259 your Makefile's link rule. This is done for you if using the
4260 Verilator --exe flag.
4261 Note you can also call ->trace on multiple Verilated objects with
4263 the same trace file if you want all data to land in the same output
4264 file.
4265 #include "verilated_vcd_c.h"
4267 ...
4268 int main(int argc, char** argv, char** env) {
4269 ...
4270 Verilated::traceEverOn(true);
4271 VerilatedVcdC* tfp = new VerilatedVcdC;
4272 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
4273 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
4274 ...
4275 while (sc_time_stamp() < sim_time && !Verilated::gotFinish()) {
4276 main_time += #;
4277 tfp->dump(main_time);
4278 }
4279 tfp->close();
4280 }
4281 How do I generate waveforms (traces) in SystemC?
4283 Add the --trace switch to Verilator, and in your top level C
4284 sc_main code, include verilated_vcd_sc.h. Then call
4285 Verilated::traceEverOn(true). Then create a VerilatedVcdSc object
4286 as you would create a normal SystemC trace file. For an example,
4287 see the call to VerilatedVcdSc in the
4288 examples/make_tracing_sc/sc_main.cpp file of the distribution, and
4289 below.
4290 Alternatively you may use the C++ trace mechanism described in the
4292 previous question, however the timescale and timeprecision will not
4293 inherited from your SystemC settings.
4294 You also need to compile verilated_vcd_sc.cpp and
4296 verilated_vcd_c.cpp and add them to your link, preferably by adding
4297 the dependencies in $(VK_GLOBAL_OBJS) to your Makefile's link rule.
4298 This is done for you if using the Verilator --exe flag.
4299 Note you can also call ->trace on multiple Verilated objects with
4301 the same trace file if you want all data to land in the same output
4302 file.
4303 #include "verilated_vcd_sc.h"
4305 ...
4306 int main(int argc, char** argv, char** env) {
4307 ...
4308 Verilated::traceEverOn(true);
4309 VerilatedVcdSc* tfp = new VerilatedVcdSc;
4310 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
4311 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
4312 ...
4313 sc_start(1);
4314 ...
4315 tfp->close();
4316 }
4317 How do I generate FST waveforms (traces) in C++?
4319 FST a format by GTKWave. This version provides a basic FST
4320 support. To dump FST format, add the --trace-fst switch to
4321 Verilator and change the include path in the testbench to:
4322 #include "verilated_fst_c.h"
4324 VerilatedFstC* tfp = new VerilatedFstC;
4325 Note that currently supporting both FST and VCD in a single
4327 simulation is impossible, but such requirement could be rare.
4328 How do I generate FST waveforms (traces) in SystemC?
4330 The FST library from GTKWave does not currently support SystemC;
4331 use VCD format instead.
4332 How do I view waveforms (traces)?
4334 Verilator makes standard VCD (Value Change Dump) and FST files.
4335 VCD files are viewable with the public domain GTKWave (recommended)
4336 or Dinotrace (legacy) programs, or any of the many commercial
4337 offerings; FST is supported by GTKWave only.
4338 How do I reduce the size of large waveform (trace) files?
4340 First, instead of calling VerilatedVcdC->open at the beginning of
4341 time, delay calling it until the time stamp where you want to
4342 tracing to begin. Likewise you can also call VerilatedVcdC->open
4343 before the end of time (perhaps a short period after you detect a
4344 verification error.)
4345 Next, add /*verilator tracing_off*/ to any very low level modules
4347 you never want to trace (such as perhaps library cells). Finally,
4348 use the --trace-depth option to limit the depth of tracing, for
4349 example --trace-depth 1 to see only the top level signals.
4350 Also be sure you write your trace files to a local solid-state
4352 disk, instead of to a network disk. Network disks are generally
4353 far slower.
4354 How do I do coverage analysis?
4356 Verilator supports both block (line) coverage and user inserted
4357 functional coverage.
4358 First, run verilator with the --coverage option. If you're using
4360 your own makefile, compile the model with the GCC flag
4361 -DVM_COVERAGE (if using Verilator's, it will do this for you.)
4362 At the end of your test, call VerilatedCov::write passing the name
4364 of the coverage data file (typically "logs/coverage.dat").
4365 Run each of your tests in different directories. Each test will
4367 create a logs/coverage.dat file.
4368 After running all of your tests, verilator_coverage is executed.
4370 Verilator_coverage reads the logs/coverage.dat file(s), and creates
4371 an annotated source code listing showing code coverage details.
4372 For an example, after running 'make test' in the Verilator
4374 distribution, see the examples/make_tracing_c/logs directory. Grep
4375 for lines starting with '%' to see what lines Verilator believes
4376 need more coverage.
4377 Where is the translate_off command? (How do I ignore a construct?)
4379 Translate on/off pragmas are generally a bad idea, as it's easy to
4380 have mismatched pairs, and you can't see what another tool sees by
4381 just preprocessing the code. Instead, use the preprocessor;
4382 Verilator defines the "VERILATOR" define for you, so just wrap the
4383 code in an ifndef region:
4384 `ifndef VERILATOR
4386 Something_Verilator_Dislikes;
4387 `endif
4388 Most synthesis tools similarly define SYNTHESIS for you.
4390 Why do I get "unexpected `do'" or "unexpected `bit'" errors?
4392 Do, bit, ref, return, and other words are now SystemVerilog
4393 keywords. You should change your code to not use them to ensure it
4394 works with newer tools. Alternatively, surround them by the
4395 Verilog 2005/SystemVerilog begin_keywords pragma to indicate
4396 Verilog 2001 code.
4397 `begin_keywords "1364-2001"
4399 integer bit; initial bit = 1;
4400 `end_keywords
4401 If you want the whole file to be parsed as Verilog 2001, just
4403 create a file with
4404 `begin_keywords "1364-2001"
4406 and add it before other Verilog files on the command line. (Note
4408 this will also change the default for --prefix, so if you're not
4409 using --prefix, you will now need to.)
4410 How do I prevent my assertions from firing during reset?
4412 Call Verilated::assertOn(false) before you first call the model,
4413 then turn it back on after reset. It defaults to true. When
4414 false, all assertions controlled by --assert are disabled.
4415 Why do I get "undefined reference to `sc_time_stamp()'"?
4417 In C++ (non SystemC) code you need to define this function so that
4418 the simulator knows the current time. See the "CONNECTING TO C++"
4419 examples.
4420 Why do I get "undefined reference to `VL_RAND_RESET_I' or
4422 `Verilated::...'"?
4423 You need to link your compiled Verilated code against the
4424 verilated.cpp file found in the include directory of the Verilator
4425 kit. This is one target in the $(VK_GLOBAL_OBJS) make variable,
4426 which should be part of your Makefile's link rule. If you use
4427 --exe, this is done for you.
4428 Is the PLI supported?
4430 Only somewhat. More specifically, the common PLI-ish calls
4431 $display, $finish, $stop, $time, $write are converted to C++
4432 equivalents. You can also use the "import DPI" SystemVerilog
4433 feature to call C code (see the chapter above). There is also
4434 limited VPI access to public signals.
4435 If you want something more complex, since Verilator emits standard
4437 C++ code, you can simply write your own C++ routines that can
4438 access and modify signal values without needing any PLI interface
4439 code, and call it with $c("{any_c++_statement}").
4440 How do I make a Verilog module that contain a C++ object?
4442 You need to add the object to the structure that Verilator creates,
4443 then use $c to call a method inside your object. The
4444 test_regress/t/t_extend_class files show an example of how to do
4445 this.
4446 How do I get faster build times?
4448 When running make pass the make variable VM_PARALLEL_BUILDS=1 so
4449 that builds occur in parallel.
4450 Use a recent compiler. Newer compilers tend do be faster, with the
4452 now relatively old GCC 3.0 to 3.3 being horrible.
4453 Compile in parallel on many machines and use caching; see the web
4455 for the ccache, distcc and icecream packages. ccache will skip GCC
4456 runs between identical source builds, even across different users.
4457 You can use the OBJCACHE environment variable to use these CC
4458 wrappers. Also see the --output-split option.
4459 To reduce the compile time of classes that use a Verilated module
4461 (e.g. a top CPP file) you may wish to add /*verilator
4462 no_inline_module*/ to your top level module. This will decrease the
4463 amount of code in the model's Verilated class, improving compile
4464 times of any instantiating top level C++ code, at a relatively
4465 small cost of execution performance.
4466 Why do so many files need to recompile when I add a signal?
4468 Adding a new signal requires the symbol table to be recompiled.
4469 Verilator uses one large symbol table, as that results in 2-3 less
4470 assembly instructions for each signal access. This makes the
4471 execution time 10-15% faster, but can result in more compilations
4472 when something changes.
4473 How do I access functions/tasks in C?
4475 Use the SystemVerilog Direct Programming Interface. You write a
4476 Verilog function or task with input/outputs that match what you
4477 want to call in with C. Then mark that function as an external
4478 function. See the DPI chapter in the manual.
4479 How do I access signals in C?
4481 The best thing is to make a SystemVerilog "export DPI task" or
4482 function that accesses that signal, as described in the DPI chapter
4483 in the manual and DPI tutorials on the web. This will allow
4484 Verilator to better optimize the model and should be portable
4485 across simulators.
4486 If you really want raw access to the signals, declare the signals
4488 you will be accessing with a /*verilator public*/ comment before
4489 the closing semicolon. Then scope into the C++ class to read the
4490 value of the signal, as you would any other member variable.
4491 Signals are the smallest of 8-bit chars, 16-bit shorts, 32-bit
4493 longs, or 64-bit long longs that fits the width of the signal.
4494 Generally, you can use just uint32_t's for 1 to 32 bits, or
4495 vluint64_t for 1 to 64 bits, and the compiler will properly up-
4496 convert smaller entities.
4497 Signals wider than 64 bits are stored as an array of 32-bit
4499 uint32_t's. Thus to read bits 31:0, access signal[0], and for bits
4500 63:32, access signal[1]. Unused bits (for example bit numbers
4501 65-96 of a 65-bit vector) will always be zero. if you change the
4502 value you must make sure to pack zeros in the unused bits or core-
4503 dumps may result. (Because Verilator strips array bound checks
4504 where it believes them to be unnecessary.)
4505 In the SYSTEMC example above, if you had in our.v:
4507 input clk /*verilator public*/;
4509 // Note the placement of the semicolon above
4510 From the sc_main.cpp file, you'd then:
4512 #include "Vour.h"
4514 #include "Vour_our.h"
4515 cout << "clock is " << top->our->clk << endl;
4516 In this example, clk is a bool you can read or set as any other
4518 variable. The value of normal signals may be set, though clocks
4519 shouldn't be changed by your code or you'll get strange results.
4520 Should a module be in Verilog or SystemC?
4522 Sometimes there is a block that just interconnects cells, and have
4523 a choice as to if you write it in Verilog or SystemC. Everything
4524 else being equal, best performance is when Verilator sees all of
4525 the design. So, look at the hierarchy of your design, labeling
4526 cells as to if they are SystemC or Verilog. Then:
4527 A module with only SystemC cells below must be SystemC.
4529 A module with a mix of Verilog and SystemC cells below must be
4531 SystemC. (As Verilator cannot connect to lower-level SystemC
4532 cells.)
4533 A module with only Verilog cells below can be either, but for best
4535 performance should be Verilog. (The exception is if you have a
4536 design that is instantiated many times; in this case Verilating one
4537 of the lower modules and instantiating that Verilated cells
4538 multiple times into a SystemC module *may* be faster.)
4539
4541 First, check the coding limitations section.
4542 Next, try the --debug switch. This will enable additional internal
4544 assertions, and may help identify the problem.
4545 Finally, reduce your code to the smallest possible routine that
4547 exhibits the bug. Even better, create a test in the test_regress/t
4548 directory, as follows:
4549 cd test_regress
4551 cp -p t/t_EXAMPLE.pl t/t_BUG.pl
4552 cp -p t/t_EXAMPLE.v t/t_BUG.v
4553 There are many hits on how to write a good test in the driver.pl
4555 documentation which can be seen by running:
4556 cd $VERILATOR_ROOT # Need the original distribution kit
4558 test_regress/driver.pl --help
4559 Edit t/t_BUG.pl to suit your example; you can do anything you want in
4561 the Verilog code there; just make sure it retains the single clk input
4562 and no outputs. Now, the following should fail:
4563 cd $VERILATOR_ROOT # Need the original distribution kit
4565 cd test_regress
4566 t/t_BUG.pl # Run on Verilator
4567 t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
4568 t/t_BUG.pl --vcs # Run on a commercial simulator
4569 t/t_BUG.pl --nc|--iv|--ghdl # Likewise on other simulators
4570 The test driver accepts a number of options, many of which mirror the
4572 main Verilator option. For example the previous test could have been
4573 run with debugging enabled. The full set of test options can be seen
4574 by running driver.pl --help as shown above.
4575 Finally, report the bug using the bug tracker at
4577 <https://verilator.org/issues>. The bug will become publicly visible;
4578 if this is unacceptable, mail the bug report to "wsnyder@wsnyder.org".
4579
4581 Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group
4582 at Digital Equipment Corporation. The Verilog code that was converted
4583 to C was then merged with a C based CPU model of the Alpha processor
4584 and simulated in a C based environment called CCLI.
4585 In 1995 Verilator started being used also for Multimedia and Network
4587 Processor development inside Digital. Duane Galbi took over active
4588 development of Verilator, and added several performance enhancements.
4589 CCLI was still being used as the shell.
4590 In 1998, through the efforts of existing DECies, mainly Duane Galbi,
4592 Digital graciously agreed to release the source code. (Subject to the
4593 code not being resold, which is compatible with the GNU Public
4594 License.)
4595 In 2001, Wilson Snyder took the kit, and added a SystemC mode, and
4597 called it Verilator2. This was the first packaged public release.
4598 In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator
4600 from scratch in C++. This added many optimizations, yielding about a
4601 2-5x performance gain.
4602 In 2009, major SystemVerilog and DPI language support was added.
4604 In 2018, Verilator 4.000 was released with multithreaded support.
4606 Currently, various language features and performance enhancements are
4608 added as the need arises. Verilator is now about 3x faster than in
4609 2002, and is faster than many popular commercial simulators.
4610
4612 When possible, please instead report bugs to
4613 <https://verilator.org/issues>.
4614 Wilson Snyder <wsnyder@wsnyder.org>
4616 Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
4618
4620 Many people have provided ideas and other assistance with Verilator.
4621 The major corporate sponsors of Verilator, by providing significant
4623 contributions of time or funds include include Atmel Corporation,
4624 Cavium Inc., Compaq Corporation, Digital Equipment Corporation,
4625 Embecosm Ltd., Hicamp Systems, Intel Corporation, Mindspeed
4626 Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun
4627 Microsystems Inc., Nauticus Networks Inc., and SiCortex Inc.
4628 The people who have contributed major functionality are Byron Bradley,
4630 Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Todd Strader,
4631 Paul Wasson, Jie Xu, and Wilson Snyder. Major testers included Jeff
4632 Dutton, Jonathon Donaldson, Ralf Karge, David Hewson, Iztok Jeras, Wim
4633 Michiels, Alex Solomatnikov, Sebastien Van Cauwenberghe, Gene Weber,
4634 and Clifford Wolf.
4635 Some of the people who have provided ideas and feedback for Verilator
4637 include: David Addison, Tariq B. Ahmad, Nikana Anastasiadis, Hans Van
4638 Antwerpen, Vasu Arasanipalai, Jens Arm, Sharad Bagri, Matthew Ballance,
4639 Andrew Bardsley, Matthew Barr, Geoff Barrett, Julius Baxter, Jeremy
4640 Bennett, Michael Berman, Victor Besyakov, David Binderman, Piotr
4641 Binkowski, Johan Bjork, David Black, Tymoteusz Blazejczyk, Daniel Bone,
4642 Gregg Bouchard, Christopher Boumenot, Nick Bowler, Byron Bradley, Bryan
4643 Brady, Maarten De Braekeleer, Charlie Brej, J Briquet, Lane Brooks,
4644 John Brownlee, Jeff Bush, Lawrence Butcher, Tony Bybell, Ted Campbell,
4645 Chris Candler, Lauren Carlson, Donal Casey, Sebastien Van Cauwenberghe,
4646 Alex Chadwick, Terry Chen, Yi-Chung Chen, Enzo Chi, Robert A. Clark,
4647 Allan Cochrane, John Coiner, Gianfranco Costamagna, George Cuan, Joe
4648 DErrico, Lukasz Dalek, Laurens van Dam, Gunter Dannoritzer, Ashutosh
4649 Das, Bernard Deadman, John Demme, Mike Denio, John Deroo, Philip
4650 Derrick, John Dickol, Ruben Diez, Danny Ding, Jacko Dirks, Ivan
4651 Djordjevic, Jonathon Donaldson, Leendert van Doorn, Sebastian Dressler,
4652 Alex Duller, Jeff Dutton, Tomas Dzetkulic, Usuario Eda, Charles
4653 Eddleston, Chandan Egbert, Joe Eiler, Ahmed El-Mahmoudy, Trevor
4654 Elbourne, Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Udi
4655 Finkelstein, Brian Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi,
4656 Benjamin Gartner, Christian Gelinek, Peter Gerst, Glen Gibb, Shankar
4657 Giri, Dan Gisselquist, Sam Gladstone, Amir Gonnen, Chitlesh Goorah,
4658 Sergi Granell, Al Grant, Xuan Guo, Driss Hafdi, Neil Hamilton, Oyvind
4659 Harboe, Jannis Harder, Junji Hashimoto, Thomas Hawkins, Mitch Hayenga,
4660 Robert Henry, David Hewson, Jamey Hicks, Joel Holdsworth, Andrew Holme,
4661 Hiroki Honda, Alex Hornung, David Horton, Jae Hossell, Alan Hunter,
4662 James Hutchinson, Jamie Iles, Ben Jackson, Shareef Jalloq, Krzysztof
4663 Jankowski, HyungKi Jeong, Iztok Jeras, James Johnson, Christophe Joly,
4664 Franck Jullien, James Jung, Mike Kagen, Arthur Kahlich, Kaalia Kahn,
4665 Guy-Armand Kamendje, Vasu Kandadi, Kanad Kanhere, Patricio Kaplan,
4666 Pieter Kapsenberg, Ralf Karge, Dan Katz, Sol Katzman, Jonathan Kimmitt,
4667 Olof Kindgren, Kevin Kiningham, Dan Kirkham, Sobhan Klnv, Gernot Koch,
4668 Soon Koh, Steve Kolecki, Brett Koonce, Will Korteland, Wojciech Koszek,
4669 Varun Koyyalagunta, David Kravitz, Roland Kruse, Sergey Kvachonok, Ed
4670 Lander, Steve Lang, Stephane Laurent, Walter Lavino, Christian Leber,
4671 Larry Lee, Igor Lesik, John Li, Eivind Liland, Yu Sheng Lin, Charlie
4672 Lind, Andrew Ling, Paul Liu, Derek Lockhart, Jake Longo, Arthur Low,
4673 Stefan Ludwig, Dan Lussier, Fred Ma, Duraid Madina, Affe Mao, Julien
4674 Margetts, Mark Marshall, Alfonso Martinez, Yves Mathieu, Patrick
4675 Maupin, Jason McMullan, Elliot Mednick, Wim Michiels, Miodrag
4676 Milanovic, Wai Sum Mong, Peter Monsson, Sean Moore, Dennis Muhlestein,
4677 John Murphy, Matt Myers, Richard Myers, Dimitris Nalbantis, Peter
4678 Nelson, Bob Newgard, Cong Van Nguyen, Paul Nitza, Yossi Nivin, Pete
4679 Nixon, Lisa Noack, Mark Nodine, Andreas Olofsson, Aleksander Osman,
4680 James Pallister, Brad Parker, Dan Petrisko, Maciej Piechotka, David
4681 Pierce, Dominic Plunkett, David Poole, Mike Popoloski, Roman Popov,
4682 Rich Porter, Niranjan Prabhu, Usha Priyadharshini, Mark Jackson Pulver,
4683 Prateek Puri, Marshal Qiao, Danilo Ramos, Chris Randall, Anton Rapp,
4684 Josh Redford, Odd Magne Reitan, Frederic Requin, Frederick Requin,
4685 Alberto Del Rio, Eric Rippey, Oleg Rodionov, Paul Rolfe, Arjen
4686 Roodselaar, Tobias Rosenkranz, Jan Egil Ruud, Denis Rystsov, John
4687 Sanguinetti, Galen Seitz, Salman Sheikh, Hao Shi, Mike Shinkarovsky,
4688 Rafael Shirakawa, Jeffrey Short, Anderson Ignacio Da Silva, Rodney
4689 Sinclair, Steven Slatter, Brian Small, Garrett Smith, Wilson Snyder,
4690 Stan Sokorac, Alex Solomatnikov, Wei Song, Art Stamness, John
4691 Stevenson, Patrick Stewart, Rob Stoddard, Todd Strader, John Stroebel,
4692 Sven Stucki, Howard Su, Emerson Suguimoto, Gene Sullivan, Renga
4693 Sundararajan, Rupert Swarbrick, Yutetsu Takatsukasa, Peter Tengstrand,
4694 Wesley Terpstra, Rui Terra, Stefan Thiede, Gary Thomas, Ian Thompson,
4695 Kevin Thompson, Mike Thyer, Hans Tichelaar, Viktor Tomov, Steve Tong,
4696 Michael Tresidder, Neil Turton, Bogdan Vukobratovic, Holger Waechtler,
4697 Philipp Wagner, Stefan Wallentowitz, Shawn Wang, Paul Wasson, Greg
4698 Waters, Thomas Watts, Eugene Weber, David Welch, Thomas J Whatson, Leon
4699 Wildman, Gerald Williams, Trevor Williams, Jeff Winston, Joshua Wise,
4700 Clifford Wolf, Johan Wouters, Junyi Xi, Ding Xiaoliang, Jie Xu, Mandy
4701 Xu, Luke Yang, and Amir Yazdanbakhsh.
4702 Thanks to them, and all those we've missed including above, or wished
4704 to remain anonymous.
4705
4707 The latest version is available from <https://verilator.org>.
4708 Copyright 2003-2020 by Wilson Snyder. Verilator is free software; you
4710 can redistribute it and/or modify the Verilator internals under the
4711 terms of either the GNU Lesser General Public License Version 3 or the
4712 Perl Artistic License Version 2.0.
4713
4715 verilator_coverage, verilator_gantt, verilator_profcfunc, make,
4716 "verilator --help" which is the source for this document,
4718 and internals.txt in the distribution.
4720perl v5.30.1 2020-02-16 VERILATOR(1)