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 The "Verilator" package converts all synthesizable, and many
17 behavioral, Verilog and SystemVerilog designs into a C++ or SystemC
18 model that after compiling can be executed. Verilator is not a
19 traditional simulator, but a compiler.
20 Verilator is typically used as follows:
22 1. The "verilator" executable is invoked with parameters similar to
24 GCC, Cadence Verilog-XL/NC-Verilog, or Synopsys VCS. "verilator" reads
25 the specified user's SystemVerilog code, lints it, optionally adds
26 coverage and waveform tracing support, and compiles the design into a
27 source level C++ or SystemC "model". The resulting model's C++ or
28 SystemC code is output as .cpp and .h files. This is referred to as
29 "verilating" and the process is "to verilate"; the output is a
30 "verilated" model.
31 2. For simulation, a small user written C++ wrapper file is required,
33 the "wrapper". This wrapper defines the C++ function `main()` which
34 instantiates the Verilated model as a C++/SystemC object.
35 3. The user main wrapper, the files created by Verilator, a "runtime
37 library" provided by Verilator, and if applicable the SystemC libraries
38 are then compiled using a C++ compiler to create a simulation
39 executable.
40 4. The resulting executable will perform the actual simulation, during
42 "simulation runtime".
43 To get started, jump down to the "EXAMPLE C++ EXECUTION" section.
45
47 This is a short summary of the arguments to the "verilator" executable.
48 See "VERILATION ARGUMENTS" for the detailed descriptions of these
49 arguments.
50 {file.v} Verilog package, module and top module filenames
52 {file.c/cc/cpp} Optional C++ files to compile in
53 {file.a/o/so} Optional C++ files to link in
54 +1364-1995ext+<ext> Use Verilog 1995 with file extension <ext>
56 +1364-2001ext+<ext> Use Verilog 2001 with file extension <ext>
57 +1364-2005ext+<ext> Use Verilog 2005 with file extension <ext>
58 +1800-2005ext+<ext> Use SystemVerilog 2005 with file extension <ext>
59 +1800-2009ext+<ext> Use SystemVerilog 2009 with file extension <ext>
60 +1800-2012ext+<ext> Use SystemVerilog 2012 with file extension <ext>
61 +1800-2017ext+<ext> Use SystemVerilog 2017 with file extension <ext>
62 --assert Enable all assertions
63 --autoflush Flush streams after all $displays
64 --bbox-sys Blackbox unknown $system calls
65 --bbox-unsup Blackbox unsupported language features
66 --bin <filename> Override Verilator binary
67 --build Build model executable/library after Verilation
68 -CFLAGS <flags> C++ compiler flags for makefile
69 --cc Create C++ output
70 --cdc Clock domain crossing analysis
71 --clk <signal-name> Mark specified signal as clock
72 --make <build-tool> Generate scripts for specified build tool
73 --compiler <compiler-name> Tune for specified C++ compiler
74 --converge-limit <loops> Tune convergence settle time
75 --coverage Enable all coverage
76 --coverage-line Enable line coverage
77 --coverage-toggle Enable toggle coverage
78 --coverage-user Enable SVL user coverage
79 --coverage-underscore Enable coverage of _signals
80 -D<var>[=<value>] Set preprocessor define
81 --debug Enable debugging
82 --debug-check Enable debugging assertions
83 --no-debug-leak Disable leaking memory in --debug mode
84 --debugi <level> Enable debugging at a specified level
85 --debugi-<srcfile> <level> Enable debugging a source file at a level
86 --default-language <lang> Default language to parse
87 +define+<var>=<value> Set preprocessor define
88 --dpi-hdr-only Only produce the DPI header file
89 --dump-defines Show preprocessor defines with -E
90 --dump-tree Enable dumping .tree files
91 --dump-treei <level> Enable dumping .tree files at a level
92 --dump-treei-<srcfile> <level> Enable dumping .tree file at a source file at a level
93 --dump-tree-addrids Use short identifiers instead of addresses
94 -E Preprocess, but do not compile
95 --error-limit <value> Abort after this number of errors
96 --exe Link to create executable
97 -F <file> Parse options from a file, relatively
98 -f <file> Parse options from a file
99 -FI <file> Force include of a file
100 --flatten Force inlining of all modules, tasks and functions
101 -G<name>=<value> Overwrite top-level parameter
102 --gdb Run Verilator under GDB interactively
103 --gdbbt Run Verilator under GDB for backtrace
104 --generate-key Create random key for --protect-key
105 --getenv <var> Get environment variable with defaults
106 --help Display this help
107 --hierarchical Enable hierarchical Verilation
108 -I<dir> Directory to search for includes
109 -j <jobs> Parallelism for --build
110 --gate-stmts <value> Tune gate optimizer depth
111 --if-depth <value> Tune IFDEPTH warning
112 +incdir+<dir> Directory to search for includes
113 --inhibit-sim Create function to turn off sim
114 --inline-mult <value> Tune module inlining
115 -LDFLAGS <flags> Linker pre-object flags for makefile
116 --l2-name <value> Verilog scope name of the top module
117 --language <lang> Default language standard to parse
118 +libext+<ext>+[ext]... Extensions for finding modules
119 --lint-only Lint, but do not make output
120 -MAKEFLAGS <flags> Options to make during --build
121 --max-num-width <value> Maximum number width (default: 64K)
122 --MMD Create .d dependency files
123 --MP Create phony dependency targets
124 --Mdir <directory> Name of output object directory
125 --mod-prefix <topname> Name to prepend to lower classes
126 --no-clk <signal-name> Prevent marking specified signal as clock
127 --no-decoration Disable comments and symbol decorations
128 --no-pins64 Don't use vluint64_t's for 33-64 bit sigs
129 --no-skip-identical Disable skipping identical output
130 +notimingchecks Ignored
131 -O0 Disable optimizations
132 -O3 High performance optimizations
133 -O<optimization-letter> Selectable optimizations
134 -o <executable> Name of final executable
135 --no-order-clock-delay Disable ordering clock enable assignments
136 --no-verilate Skip verilation and just compile previously Verilated code.
137 --output-split <statements> Split .cpp files into pieces
138 --output-split-cfuncs <statements> Split model functions
139 --output-split-ctrace <statements> Split tracing functions
140 -P Disable line numbers and blanks with -E
141 --pins-bv <bits> Specify types for top level ports
142 --pins-sc-uint Specify types for top level ports
143 --pins-sc-biguint Specify types for top level ports
144 --pins-uint8 Specify types for top level ports
145 --pipe-filter <command> Filter all input through a script
146 --pp-comments Show preprocessor comments with -E
147 --prefix <topname> Name of top level class
148 --prof-cfuncs Name functions for profiling
149 --prof-threads Enable generating gantt chart data for threads
150 --protect-key <key> Key for symbol protection
151 --protect-ids Hash identifier names for obscurity
152 --protect-lib <name> Create a DPI protected library
153 --private Debugging; see docs
154 --public Debugging; see docs
155 --public-flat-rw Mark all variables, etc as public_flat_rw
156 -pvalue+<name>=<value> Overwrite toplevel parameter
157 --quiet-exit Don't print the command on failure
158 --relative-includes Resolve includes relative to current file
159 --no-relative-cfuncs Disallow 'this->' in generated functions
160 --report-unoptflat Extra diagnostics for UNOPTFLAT
161 --rr Run Verilator and record with rr
162 --savable Enable model save-restore
163 --sc Create SystemC output
164 --stats Create statistics file
165 --stats-vars Provide statistics on variables
166 -sv Enable SystemVerilog parsing
167 +systemverilogext+<ext> Synonym for +1800-2017ext+<ext>
168 --threads <threads> Enable multithreading
169 --threads-dpi <mode> Enable multithreaded DPI
170 --threads-max-mtasks <mtasks> Tune maximum mtask partitioning
171 --timescale <timescale> Sets default timescale
172 --timescale-override <timescale> Overrides all timescales
173 --top <topname> Alias of --top-module
174 --top-module <topname> Name of top level input module
175 --trace Enable waveform creation
176 --trace-coverage Enable tracing of coverage
177 --trace-depth <levels> Depth of tracing
178 --trace-fst Enable FST waveform creation
179 --trace-max-array <depth> Maximum bit width for tracing
180 --trace-max-width <width> Maximum array depth for tracing
181 --trace-params Enable tracing of parameters
182 --trace-structs Enable tracing structure names
183 --trace-threads <threads> Enable waveform creation on separate threads
184 --trace-underscore Enable tracing of _signals
185 -U<var> Undefine preprocessor define
186 --unroll-count <loops> Tune maximum loop iterations
187 --unroll-stmts <stmts> Tune maximum loop body size
188 --unused-regexp <regexp> Tune UNUSED lint signals
189 -V Verbose version and config
190 -v <filename> Verilog library
191 +verilog1995ext+<ext> Synonym for +1364-1995ext+<ext>
192 +verilog2001ext+<ext> Synonym for +1364-2001ext+<ext>
193 --version Displays program version and exits
194 --vpi Enable VPI compiles
195 --waiver-output <filename> Create a waiver file based on the linter warnings
196 -Wall Enable all style warnings
197 -Werror-<message> Convert warnings to errors
198 -Wfuture-<message> Disable unknown message warnings
199 -Wno-<message> Disable warning
200 -Wno-context Disable source context on warnings
201 -Wno-fatal Disable fatal exit on warnings
202 -Wno-lint Disable all lint warnings
203 -Wno-style Disable all style warnings
204 -Wpedantic Warn on compliance-test issues
205 --x-assign <mode> Assign non-initial Xs to this value
206 --x-initial <mode> Assign initial Xs to this value
207 --x-initial-edge Enable initial X->0 and X->1 edge triggers
208 --xml-only Create XML parser output
209 --xml-output XML output filename
210 -y <dir> Directory to search for modules
211 This is a short summary of the simulation runtime arguments, i.e. for
213 the final Verilated simulation runtime models. See "SIMULATION RUNTIME
214 ARGUMENTS" for the detailed description of these arguments.
215 +verilator+debug Enable debugging
217 +verilator+debugi+<value> Enable debugging at a level
218 +verilator+help Display help
219 +verilator+prof+threads+file+I<filename> Set profile filename
220 +verilator+prof+threads+start+I<value> Set profile starting point
221 +verilator+prof+threads+window+I<value> Set profile duration
222 +verilator+rand+reset+I<value> Set random reset technique
223 +verilator+seed+I<value> Set random seed
224 +verilator+noassert Disable assert checking
225 +verilator+V Verbose version and config
226 +verilator+version Show version and exit
227
229 The following are the arguments that may be passed to the "verilator"
230 executable.
231 {file.v}
233 Specifies the Verilog file containing the top module to be
234 Verilated.
235 {file.c/.cc/.cpp/.cxx}
237 Used with --exe to specify optional C++ files to be linked in with
238 the Verilog code. The file path should either be absolute, or
239 relative to where the make will be executed from, or add to your
240 makefile's VPATH the appropriate directory to find the file.
241 See also the -CFLAGS and -LDFLAGS options, which are useful when
243 the C++ files need special compiler flags.
244 {file.a/.o/.so}
246 Specifies optional object or library files to be linked in with the
247 Verilog code, as a shorthand for -LDFLAGS "<file>". The file path
248 should either be absolute, or relative to where the make will be
249 executed from, or add to your makefile's VPATH the appropriate
250 directory to find the file.
251 If any files are specified in this way, Verilator will include a
253 make rule that uses these files when linking the module executable.
254 This generally is only useful when used with the --exe option.
255 +1364-1995ext+ext
257 +1364-2001ext+ext
258 +1364-2005ext+ext
259 +1800-2005ext+ext
260 +1800-2009ext+ext
261 +1800-2012ext+ext
262 +1800-2017ext+ext
263 Specifies the language standard to be used with a specific filename
264 extension, ext.
265 For compatibility with other simulators, see also the synonyms
267 "+verilog1995ext+"ext, "+verilog2001ext+"ext, and
268 "+systemverilogext+"ext.
269 For any source file, the language specified by these options takes
271 precedence over any language specified by the "--default-language"
272 or "--language" options.
273 These options take effect in the order they are encountered. Thus
275 the following would use Verilog 1995 for "a.v" and Verilog 2001 for
276 "b.v".
277 verilator ... +1364-1995ext+v a.v +1364-2001ext+v b.v
279 These flags are only recommended for legacy mixed language designs,
281 as the preferable option is to edit the code to repair new
282 keywords, or add appropriate "`begin_keywords".
283 Note "`begin_keywords" is a SystemVerilog construct, which
285 specifies only the set of keywords to be recognized. This also
286 controls some error messages that vary between language standards.
287 Note at present Verilator tends to be overly permissive, e.g. it
288 will accept many grammar and other semantic extensions which might
289 not be legal when set to an older standard.
290 --assert
292 Enable all assertions.
293 --autoflush
295 After every $display or $fdisplay, flush the output stream. This
296 ensures that messages will appear immediately but may reduce
297 performance. For best performance call "fflush(stdout)"
298 occasionally in the C++ main loop. Defaults to off, which will
299 buffer output as provided by the normal C/C++ standard library IO.
300 --bbox-sys
302 Black box any unknown $system task or function calls. System tasks
303 will simply become no-operations, and system functions will be
304 replaced with unsized zero. Arguments to such functions will be
305 parsed, but not otherwise checked. This prevents errors when
306 linting in the presence of company specific PLI calls.
307 Using this argument will likely cause incorrect simulation.
309 --bbox-unsup
311 Black box some unsupported language features, currently UDP tables,
312 the cmos and tran gate primitives, deassign statements, and mixed
313 edge errors. This may enable linting the rest of the design even
314 when unsupported constructs are present.
315 Using this argument will likely cause incorrect simulation.
317 --bin filename
319 Rarely needed. Override the default filename for Verilator itself.
320 When a dependency (.d) file is created, this filename will become a
321 source dependency, such that a change in this binary will have make
322 rebuild the output files.
323 --build
325 After generating the SystemC/C++ code, Verilator will invoke the
326 toolchain to build the model library (and executable when "--exe"
327 is also used). Verilator manages the build itself, and for this
328 --build requires GNU Make to be available on the platform.
329 -CFLAGS flags
331 Add specified C compiler flag to the generated makefiles. For
332 multiple flags either pass them as a single argument with space
333 separators quoted in the shell ("-CFLAGS "-a -b""), or use multiple
334 -CFLAGS arguments ("-CFLAGS -a -CFLAGS -b").
335 When make is run on the generated makefile these will be passed to
337 the C++ compiler (g++/clang++/msvc++).
338 --cc
340 Specifies C++ without SystemC output mode; see also --sc.
341 --cdc
343 Permanently experimental. Perform some clock domain crossing
344 checks and issue related warnings (CDCRSTLOGIC) and then exit; if
345 warnings other than CDC warnings are needed make a second run with
346 --lint-only. Additional warning information is also written to the
347 file {prefix}__cdc.txt.
348 Currently only checks some items that other CDC tools missed; if
350 you have interest in adding more traditional CDC checks, please
351 contact the authors.
352 --clk signal-name
354 Sometimes it is quite difficult for Verilator to distinguish clock
355 signals from other data signals. Occasionally the clock signals can
356 end up in the checking list of signals which determines if further
357 evaluation is needed. This will heavily degrade the performance of
358 a Verilated model.
359 With --clk <signal-name>, user can specified root clock into the
361 model, then Verilator will mark the signal as clocker and propagate
362 the clocker attribute automatically to other signals derived from
363 that. In this way, Verilator will try to avoid taking the clocker
364 signal into checking list.
365 Note signal-name is specified by the RTL hierarchy path. For
367 example, v.foo.bar. If the signal is the input to top-module, the
368 directly the signal name. If you find it difficult to find the
369 exact name, try to use "/*verilator clocker*/" in RTL file to mark
370 the signal directly.
371 If clock signals are assigned to vectors and then later used
373 individually, Verilator will attempt to decompose the vector and
374 connect the single-bit clock signals directly. This should be
375 transparent to the user.
376 --make build-tool
378 Generates a script for the specified build tool.
379 Supported values are "gmake" for GNU Make and "cmake" for CMake.
381 Both can be specified together. If no build tool is specified,
382 gmake is assumed. The executable of gmake can be configured via
383 environment variable "MAKE".
384 When using --build Verilator takes over the responsibility of
386 building the model library/executable. For this reason --make
387 cannot be specified when using --build.
388 --compiler compiler-name
390 Enables workarounds for the specified C++ compiler, either "clang",
391 "gcc", or "msvc". Currently this does not change any performance
392 tuning flags, but it may in the future.
393 clang
395 Tune for clang. This may reduce execution speed as it enables
396 several workarounds to avoid silly hard-coded limits in clang.
397 This includes breaking deep structures as for msvc as described
398 below.
399 gcc Tune for GNU C++, although generated code should work on almost
401 any compliant C++ compiler. Currently the default.
402 msvc
404 Tune for Microsoft Visual C++. This may reduce execution speed
405 as it enables several workarounds to avoid silly hard-coded
406 limits in MSVC++. This includes breaking deeply nested
407 parenthesized expressions into sub-expressions to avoid error
408 C1009, and breaking deep blocks into functions to avoid error
409 C1061.
410 --converge-limit loops
412 Rarely needed. Specifies the maximum number of runtime iterations
413 before creating a model failed to converge error. Defaults to 100.
414 --coverage
416 Enables all forms of coverage, alias for "--coverage-line
417 --coverage-toggle --coverage-user".
418 --coverage-line
420 Specifies basic block line coverage analysis code should be
421 inserted.
422 Coverage analysis adds statements at each code flow change point
424 (e.g. at branches). At each such branch a unique counter is
425 incremented. At the end of a test, the counters along with the
426 filename and line number corresponding to each counter are written
427 into logs/coverage.dat.
428 Verilator automatically disables coverage of branches that have a
430 $stop in them, as it is assumed $stop branches contain an error
431 check that should not occur. A /*verilator coverage_block_off*/
432 comment will perform a similar function on any code in that block
433 or below, or /*verilator coverage_on/coverage_off*/ will disable
434 coverage around lines of code.
435 Note Verilator may over-count combinatorial (non-clocked) blocks
437 when those blocks receive signals which have had the UNOPTFLAT
438 warning disabled; for most accurate results do not disable this
439 warning when using coverage.
440 --coverage-toggle
442 Specifies signal toggle coverage analysis code should be inserted.
443 Every bit of every signal in a module has a counter inserted. The
445 counter will increment on every edge change of the corresponding
446 bit.
447 Signals that are part of tasks or begin/end blocks are considered
449 local variables and are not covered. Signals that begin with
450 underscores, are integers, or are very wide (>256 bits total
451 storage across all dimensions) are also not covered.
452 Hierarchy is compressed, such that if a module is instantiated
454 multiple times, coverage will be summed for that bit across ALL
455 instantiations of that module with the same parameter set. A
456 module instantiated with different parameter values is considered a
457 different module, and will get counted separately.
458 Verilator makes a minimally-intelligent decision about what clock
460 domain the signal goes to, and only looks for edges in that clock
461 domain. This means that edges may be ignored if it is known that
462 the edge could never be seen by the receiving logic. This
463 algorithm may improve in the future. The net result is coverage
464 may be lower than what would be seen by looking at traces, but the
465 coverage is a more accurate representation of the quality of
466 stimulus into the design.
467 There may be edges counted near time zero while the model
469 stabilizes. It's a good practice to zero all coverage just before
470 releasing reset to prevent counting such behavior.
471 A /*verilator coverage_off/on */ comment pair can be used around
473 signals that do not need toggle analysis, such as RAMs and register
474 files.
475 --coverage-underscore
477 Enable coverage of signals that start with an underscore. Normally,
478 these signals are not covered. See also --trace-underscore.
479 --coverage-user
481 Enables user inserted functional coverage. Currently, all
482 functional coverage points are specified using SVA which must be
483 separately enabled with --assert.
484 For example, the following statement will add a coverage point,
486 with the comment "DefaultClock":
487 DefaultClock: cover property (@(posedge clk) cyc==3);
489 -Dvar=value
491 Defines the given preprocessor symbol. Similar to +define, but
492 does not allow multiple definitions with a single option using plus
493 signs. +define is fairly standard across Verilog tools while -D is
494 similar to GCC.
495 --debug
497 Select the debug executable of Verilator (if available), and enable
498 more internal assertions (equivalent to "--debug-check"), debugging
499 messages (equivalent to "--debugi 4"), and intermediate form dump
500 files (equivalent to "--dump-treei 3").
501 --debug-check
503 Rarely needed. Enable internal debugging assertion checks, without
504 changing debug verbosity. Enabled automatically when --debug
505 specified.
506 --no-debug-leak
508 In --debug mode, by default Verilator intentionally leaks AstNode
509 instances instead of freeing them, so that each node pointer is
510 unique in the resulting tree files and dot files.
511 This option disables the leak. This may avoid out-of-memory errors
513 when Verilating large models in --debug mode.
514 Outside of --debug mode, AstNode instances should never be leaked
516 and this option has no effect.
517 --debugi level
519 --debugi-srcfile level
520 Rarely needed - for developer use. Set internal debugging level
521 globally to the specified debug level (1-10) or set the specified
522 Verilator source file to the specified level (e.g.
523 "--debugi-V3Width 9"). Higher levels produce more detailed
524 messages.
525 --default-language value
527 Select the language to be used by default when first processing
528 each Verilog file. The language value must be "1364-1995",
529 "1364-2001", "1364-2005", "1800-2005", "1800-2009", "1800-2012" or
530 "1800-2017".
531 Any language associated with a particular file extension (see the
533 various +langext+ options) will be used in preference to the
534 language specified by --default-language.
535 The --default-language flag is only recommended for legacy code
537 using the same language in all source files, as the preferable
538 option is to edit the code to repair new keywords, or add
539 appropriate "`begin_keywords". For legacy mixed language designs,
540 the various +langext+ options should be used.
541 If no language is specified, either by this flag or +langext+
543 options, then the latest SystemVerilog language (IEEE 1800-2017) is
544 used.
545 +define+var=value
547 +define+var=value+var2=value2...
548 Defines the given preprocessor symbol, or multiple symbols if
549 separated by plus signs. Similar to -D; +define is fairly standard
550 across Verilog tools while -D is similar to GCC.
551 --dpi-hdr-only
553 Only generate the DPI header file. This option has no effect on
554 the name or location of the emitted DPI header file, it is output
555 in "--Mdir" as it would be without this option.
556 --dump-defines
558 With -E, suppress normal output, and instead print a list of all
559 defines existing at the end of pre-processing the input files.
560 Similar to GCC "-dM" option. This also gives you a way of finding
561 out what is predefined in Verilator using the command:
562 touch foo.v ; verilator -E --dump-defines foo.v
564 --dump-tree
566 Rarely needed. Enable writing .tree debug files with dumping level
567 3, which dumps the standard critical stages. For details on the
568 format see the Verilator Internals manual. --dump-tree is enabled
569 automatically with --debug, so "--debug --no-dump-tree" may be
570 useful if the dump files are large and not desired.
571 --dump-treei level
573 --dump-treei-srcfile level
574 Rarely needed - for developer use. Set internal tree dumping level
575 globally to a specific dumping level or set the specified Verilator
576 source file to the specified tree dumping level (e.g.
577 "--dump-treei-V3Order 9"). Level 0 disables dumps and is
578 equivalent to "--no-dump-tree". Level 9 enables dumping of every
579 stage.
580 --dump-tree-addrids
582 Rarely needed - for developer use. Replace AST node addresses with
583 short identifiers in tree dumps to enhance readability. Each
584 unique pointer value is mapped to a unique identifier, but note
585 that this is not necessarily unique per node instance as an address
586 might get reused by a newly allocated node after a node with the
587 same address has been dumped then freed.
588 -E Preprocess the source code, but do not compile, as with 'gcc -E'.
590 Output is written to standard out. Beware of enabling debugging
591 messages, as they will also go to standard out.
592 --error-limit value
594 After this number of errors are encountered during Verilator run,
595 exit. Warnings are not counted in this limit. Defaults to 50.
596 Does not affect simulation runtime errors, for those see
598 +verilator+error+limit.
599 --exe
601 Generate an executable. You will also need to pass additional .cpp
602 files on the command line that implement the main loop for your
603 simulation.
604 -F file
606 Read the specified file, and act as if all text inside it was
607 specified as command line parameters. Any relative paths are
608 relative to the directory containing the specified file. See also
609 -f. Note -F is fairly standard across Verilog tools.
610 -f file
612 Read the specified file, and act as if all text inside it was
613 specified as command line parameters. Any relative paths are
614 relative to the current directory. See also -F. Note -f is fairly
615 standard across Verilog tools.
616 The file may contain // comments which are ignored to the end of
618 the line. Any $VAR, $(VAR), or ${VAR} will be replaced with the
619 specified environment variable.
620 -FI file
622 Force include of the specified C++ header file. All generated C++
623 files will insert a #include of the specified file before any other
624 includes. The specified file might be used to contain define
625 prototypes of custom VL_VPRINTF functions, and may need to include
626 verilatedos.h as this file is included before any other standard
627 includes.
628 --flatten
630 Force flattening of the design's hierarchy, with all modules, tasks
631 and functions inlined. Typically used with "--xml-only". Note
632 flattening large designs may require significant CPU time, memory
633 and storage.
634 -Gname=value
636 Overwrites the given parameter of the toplevel module. The value is
637 limited to basic data literals:
638 Verilog integer literals
640 The standard Verilog integer literals are supported, so values
641 like 32'h8, 2'b00, 4 etc. are allowed. Care must be taken that
642 the single quote (I') is properly escaped in an interactive
643 shell, e.g., as -GWIDTH=8\'hx.
644 C integer literals
646 It is also possible to use C integer notation, including
647 hexadecimal (0x..), octal (0..) or binary (0b..) notation.
648 Double literals
650 Double literals must be one of the following styles:
651 - contains a dot (.) (e.g. 1.23)
652 - contains an exponent (e/E) (e.g. 12e3)
653 - contains p/P for hexadecimal floating point in C99 (e.g.
654 0x123.ABCp1)
655 Strings
657 Strings must be in double quotes (""). They must be escaped
658 properly on the command line, e.g. as -GSTR="\"My String\"" or
659 -GSTR='"My String"'.
660 --gate-stmts value
662 Rarely needed. Set the maximum number of statements that may be
663 present in an equation for the gate substitution optimization to
664 inline that equation.
665 --gdb
667 Run Verilator underneath an interactive GDB (or VERILATOR_GDB
668 environment variable value) session. See also --gdbbt.
669 --gdbbt
671 If --debug is specified, run Verilator underneath a GDB process and
672 print a backtrace on exit, then exit GDB immediately. Without
673 --debug or if GDB doesn't seem to work, this flag is ignored.
674 Intended for easy creation of backtraces by users; otherwise see
675 the --gdb flag.
676 --generate-key
678 Generate a true-random key suitable for use with --protect-key,
679 print it, and exit immediately.
680 --getenv variable
682 If the variable is declared in the environment, print it and exit
683 immediately. Otherwise, if it's built into Verilator (e.g.
684 VERILATOR_ROOT), print that and exit immediately. Otherwise, print
685 a newline and exit immediately. This can be useful in makefiles.
686 See also -V, and the various *.mk files.
687 --help
689 Displays this message and program version and exits.
690 --hierarchical
692 Enable hierarchical Verilation otherwise /*verilator hier_block*/
693 metacomment is ignored. See "HIERARCHICAL VERILATION".
694 -Idir
696 See -y.
697 --if-depth value
699 Rarely needed. Set the depth at which the IFDEPTH warning will
700 fire, defaults to 0 which disables this warning.
701 +incdir+dir
703 See -y.
704 --inhibit-sim
706 Rarely needed. Create a "inhibitSim(bool)" function to enable and
707 disable evaluation. This allows an upper level testbench to
708 disable modules that are not important in a given simulation,
709 without needing to recompile or change the SystemC modules
710 instantiated.
711 --inline-mult value
713 Tune the inlining of modules. The default value of 2000 specifies
714 that up to 2000 new operations may be added to the model by
715 inlining, if more than this number of operations would result, the
716 module is not inlined. Larger values, or a value < 1 will inline
717 everything, will lead to longer compile times, but potentially
718 faster simulation speed. This setting is ignored for very small
719 modules; they will always be inlined, if allowed.
720 -j <value>
722 Specify the level of parallelism for --build. <value> must be a
723 positive integer specifying the maximum number of parallel build
724 jobs, or can be omitted. When <value> is omitted, the build will
725 not try to limit the number of parallel build jobs but attempt to
726 execute all independent build steps in parallel.
727 -LDFLAGS flags
729 Add specified C linker flags to the generated makefiles. For
730 multiple flags either pass them as a single argument with space
731 separators quoted in the shell ("-LDFLAGS "-a -b""), or use
732 multiple -LDFLAGS arguments ("-LDFLAGS -a -LDFLAGS -b").
733 When make is run on the generated makefile these will be passed to
735 the C++ linker (ld) *after* the primary file being linked. This
736 flag is called -LDFLAGS as that's the traditional name in
737 simulators; it's would have been better called LDLIBS as that's the
738 Makefile variable it controls. (In Make, LDFLAGS is before the
739 first object, LDLIBS after. -L libraries need to be in the Make
740 variable LDLIBS, not LDFLAGS.)
741 --l2-name value
743 Instead of using the module name when showing Verilog scope, use
744 the name provided. This allows simplifying some Verilator-embedded
745 modeling methodologies. Default is an l2-name matching the top
746 module. The default before 3.884 was "--l2-name v"
747 For example, the program "module t; initial $display("%m");
749 endmodule" will show by default "t". With "--l2-name v" it will
750 print "v".
751 --language value
753 A synonym for "--default-language", for compatibility with other
754 tools and earlier versions of Verilator.
755 +libext+ext+ext...
757 Specify the extensions that should be used for finding modules. If
758 for example module x is referenced, look in x.ext. Note +libext+
759 is fairly standard across Verilog tools. Defaults to .v and .sv.
760 --lint-only
762 Check the files for lint violations only, do not create any other
763 output.
764 You may also want the -Wall option to enable messages that are
766 considered stylistic and not enabled by default.
767 If the design is not to be completely Verilated see also the
769 --bbox-sys and --bbox-unsup options.
770 -MAKEFLAGS <string>
772 When using --build, add the specified flag to the invoked make
773 command line. For multiple flags either pass them as a single
774 argument with space separators quoted in the shell (e.g.
775 "-MAKEFLAGS "-a -b""), or use multiple -MAKEFLAGS arguments (e.g.
776 "-MAKEFLAGS -l -MAKEFLAGS -k"). Use of this option should not be
777 required for simple builds using the host toolchain.
778 --max-num-width value
780 Set the maximum number literal width (e.g. in 1024'd22 this it the
781 1024). Defaults to 64K.
782 --MMD =item --no-MMD
784 Enable/disable creation of .d dependency files, used for make
785 dependency detection, similar to gcc -MMD option. By default this
786 option is enabled for --cc or --sc modes.
787 --MP
789 When creating .d dependency files with --MMD, make phony targets.
790 Similar to gcc -MP option.
791 --Mdir directory
793 Specifies the name of the Make object directory. All generated
794 files will be placed in this directory. If not specified,
795 "obj_dir" is used. The directory is created if it does not exist
796 and the parent directories exist; otherwise manually create the
797 Mdir before calling Verilator.
798 --mod-prefix topname
800 Specifies the name to prepend to all lower level classes. Defaults
801 to the same as --prefix.
802 --no-clk signal-name
804 Prevent the specified signal from being marked as clock. See
805 "--clk".
806 --no-decoration
808 When creating output Verilated code, minimize comments, white
809 space, symbol names and other decorative items, at the cost of
810 greatly reduced readability. This may assist C++ compile times.
811 This will not typically change the ultimate model's performance,
812 but may in some cases.
813 --no-pins64
815 Backward compatible alias for "--pins-bv 33".
816 --no-relative-cfuncs
818 Disable 'this->' references in generated functions, and instead
819 Verilator will generate absolute references starting from
820 'vlTOPp->'. This prevents V3Combine from merging functions from
821 multiple instances of the same module, so it can grow the
822 instruction stream.
823 This is a work around for old compilers. Don't set this if your C++
825 compiler supports __restrict__ properly, as GCC 4.5.x and newer do.
826 For older compilers, test if this switch gives you better
827 performance or not.
828 Compilers which don't honor __restrict__ will suspect that 'this->'
830 references and 'vlTOPp->' references may alias, and may write slow
831 code with extra loads and stores to handle the (imaginary)
832 aliasing. Using only 'vlTOPp->' references allows these old
833 compilers to produce tight code.
834 --no-skip-identical =item --skip-identical
836 Rarely needed. Disables or enables skipping execution of Verilator
837 if all source files are identical, and all output files exist with
838 newer dates. By default this option is enabled for --cc or --sc
839 modes only.
840 +notimingchecks
842 Ignored for compatibility with other simulators.
843 -O0 Disables optimization of the model.
845 -O3 Enables slow optimizations for the code Verilator itself generates
847 (as opposed to "-CFLAGS -O3" which effects the C compiler's
848 optimization. -O3 may improve simulation performance at the cost
849 of compile time. This currently sets --inline-mult -1.
850 -Ooptimization-letter
852 Rarely needed. Enables or disables a specific optimizations, with
853 the optimization selected based on the letter passed. A lowercase
854 letter disables an optimization, an upper case letter enables it.
855 This is intended for debugging use only; see the source code for
856 version-dependent mappings of optimizations to -O letters.
857 -o executable
859 Specify the name for the final executable built if using --exe.
860 Defaults to the --prefix if not specified.
861 --no-order-clock-delay
863 Rarely needed. Disables a bug fix for ordering of clock enables
864 with delayed assignments. This flag should only be used when
865 suggested by the developers.
866 --output-split statements
868 Enables splitting the output .cpp files into multiple outputs.
869 When a C++ file exceeds the specified number of operations, a new
870 file will be created at the next function boundary. In addition,
871 if the total output code size exceeds the specified value,
872 VM_PARALLEL_BUILDS will be set to 1 by default in the generated
873 make files, making parallel compilation possible. Using
874 --output-split should have only a trivial impact on model
875 performance. But can greatly improve C++ compilation speed. The use
876 of ccache (set for you if present at configure time) is also more
877 effective with this option.
878 This option is on by default with a value of 20000. To disable,
880 pass with a value of 0.
881 --output-split-cfuncs statements
883 Enables splitting functions in the output .cpp files into multiple
884 functions. When a generated function exceeds the specified number
885 of operations, a new function will be created. With
886 --output-split, this will enable the C++ compiler to compile
887 faster, at a small loss in performance that gets worse with
888 decreasing split values. Note that this option is stronger than
889 --output-split in the sense that --output-split will not split
890 inside a function.
891 Defaults to the value of --output-split, unless explicitly
893 specified.
894 --output-split-ctrace statements
896 Similar to --output-split-cfuncs, enables splitting trace functions
897 in the output .cpp files into multiple functions.
898 Defaults to the value of --output-split, unless explicitly
900 specified.
901 -P With -E, disable generation of `line markers and blank lines,
903 similar to GCC -P flag.
904 --pins64
906 Backward compatible alias for "--pins-bv 65". Note that's a 65,
907 not a 64.
908 --pins-bv width
910 Specifies SystemC inputs/outputs of greater than or equal to width
911 bits wide should use sc_bv's instead of uint32/vluint64_t's. The
912 default is "--pins-bv 65", and the value must be less than or equal
913 to 65. Versions before Verilator 3.671 defaulted to "--pins-bv
914 33". The more sc_bv is used, the worse for performance. Use the
915 "/*verilator sc_bv*/" attribute to select specific ports to be
916 sc_bv.
917 --pins-sc-uint
919 Specifies SystemC inputs/outputs of greater than 2 bits wide should
920 use sc_uint between 2 and 64. When combined with the
921 "--pins-sc-biguint" combination, it results in sc_uint being used
922 between 2 and 64 and sc_biguint being used between 65 and 512.
923 --pins-sc-biguint
925 Specifies SystemC inputs/outputs of greater than 65 bits wide
926 should use sc_biguint between 65 and 512, and sc_bv from 513
927 upwards. When combined with the "--pins-sc-uint" combination, it
928 results in sc_uint being used between 2 and 64 and sc_biguint being
929 used between 65 and 512.
930 --pins-uint8
932 Specifies SystemC inputs/outputs that are smaller than the
933 --pins-bv setting and 8 bits or less should use uint8_t instead of
934 uint32_t. Likewise pins of width 9-16 will use uint16_t instead of
935 uint32_t.
936 --pipe-filter command
938 Rarely needed. Verilator will spawn the specified command as a
939 subprocess pipe, to allow the command to perform custom edits on
940 the Verilog code before it reaches Verilator.
941 Before reading each Verilog file, Verilator will pass the file name
943 to the subprocess' stdin with 'read "<filename>"'. The filter may
944 then read the file and perform any filtering it desires, and feeds
945 the new file contents back to Verilator on stdout by first emitting
946 a line defining the length in bytes of the filtered output
947 'Content-Length: <bytes>', followed by the new filtered contents.
948 Output to stderr from the filter feeds through to Verilator's
949 stdout and if the filter exits with non-zero status Verilator
950 terminates. See the t/t_pipe_filter test for an example.
951 To debug the output of the filter, try using the -E option to see
953 preprocessed output.
954 --pp-comments
956 With -E, show comments in preprocessor output.
957 --prefix topname
959 Specifies the name of the top level class and makefile. Defaults
960 to V prepended to the name of the --top switch, or V prepended to
961 the first Verilog filename passed on the command line.
962 --prof-cfuncs
964 Modify the created C++ functions to support profiling. The
965 functions will be minimized to contain one "basic" statement,
966 generally a single always block or wire statement. (Note this will
967 slow down the executable by ~5%.) Furthermore, the function name
968 will be suffixed with the basename of the Verilog module and line
969 number the statement came from. This allows gprof or oprofile
970 reports to be correlated with the original Verilog source
971 statements. See also verilator_profcfunc.
972 --prof-threads
974 Enable gantt chart data collection for threaded builds.
975 Verilator will record the start and end time of each macro-task
977 across a number of calls to eval. (What is a macro-task? See the
978 Verilator internals document.)
979 When profiling is enabled, the simulation runtime will emit a blurb
981 of profiling data in non-human-friendly form. The "verilator_gantt"
982 script will transform this into a nicer visual format and produce
983 some related statistics.
984 --protect-key key
986 Specifies the private key for --protect-ids. For best security this
987 key should be 16 or more random bytes, a reasonable secure choice
988 is the output of "verilator --generate-key". Typically, a key would
989 be created by the user once for a given protected design library,
990 then every Verilator run for subsequent versions of that library
991 would be passed the same --protect-key. Thus, if the input Verilog
992 is similar between library versions (Verilator runs), the Verilated
993 code will likewise be mostly similar.
994 If --protect-key is not specified and a key is needed, Verilator
996 will generate a new key for every Verilator run. As the key is not
997 saved, this is best for security, but means every Verilator run
998 will give vastly different output even for identical input, perhaps
999 harming compile times (and certainly thrashing any ccache).
1000 --protect-ids
1002 Hash any private identifiers (variable, module, and assertion block
1003 names that are not on the top level) into hashed random-looking
1004 identifiers, resulting after compilation in protected library
1005 binaries that expose less design information. This hashing uses
1006 the provided or default --protect-key, see important details there.
1007 Verilator will also create a {prefix}__idmap.xml file which
1009 contains the mapping from the hashed identifiers back to the
1010 original identifiers. This idmap file is to be kept private, and is
1011 to assist mapping any simulation runtime design assertions,
1012 coverage, or trace information, which will report the hashed
1013 identifiers, back to the original design's identifier names.
1014 Using DPI imports/exports is allowed and generally relatively safe
1016 in terms of information disclosed, which is limited to the DPI
1017 function prototyptes. Use of the VPI is not recommended as many
1018 design details may be exposed, and an INSECURE warning will be
1019 issued.
1020 --protect-lib name
1022 Produces C++, Verilog wrappers and a Makefile which can in turn
1023 produce a DPI library which can be used by Verilator or other
1024 simulators along with the corresponding Verilog wrapper. The
1025 Makefile will build both a static and dynamic version of the
1026 library named libname.a and libname.so respectively. This is done
1027 because some simulators require a dynamic library, but the static
1028 library is arguably easier to use if possible. --protect-lib
1029 implies --protect-ids.
1030 This allows for the secure delivery of sensitive IP without the
1032 need for encrypted RTL (i.e. IEEE P1735). See
1033 examples/make_protect_lib in the distribution for a demonstration
1034 of how to build and use the DPI library.
1035 When using --protect-lib it is advised to also use
1037 "--timescale-override /1fs" to ensure the model has a time
1038 resolution that is always compatible with the time precision of the
1039 upper instantiating module.
1040 --private
1042 Opposite of --public. Is the default; this option exists for
1043 backwards compatibility.
1044 --public
1046 This is only for historical debug use. Using it may result in mis-
1047 simulation of generated clocks.
1048 Declares all signals and modules public. This will turn off signal
1050 optimizations as if all signals had a /*verilator public*/ comments
1051 and inlining. This will also turn off inlining as if all modules
1052 had a /*verilator public_module*/, unless the module specifically
1053 enabled it with /*verilator inline_module*/.
1054 --public-flat-rw
1056 Declares all variables, ports and wires public as if they had
1057 /*verilator public_flat_rw @ (<variable's_source_process_edge>)*/
1058 comments. This will make them VPI accessible by their flat name,
1059 but not turn off module inlining. This is particularly useful in
1060 combination with --vpi. This may also in some rare cases result in
1061 mis-simulation of generated clocks. Instead of this global switch,
1062 marking only those signals that need public_flat_rw is typically
1063 significantly better performing.
1064 -pvalue+name=value
1066 Overwrites the given parameter(s) of the toplevel module. See -G
1067 for a detailed description.
1068 --quiet-exit
1070 When exiting due to an error, do not display the "Exiting due to
1071 Errors" nor "Command Failed" messages.
1072 --relative-includes
1074 When a file references an include file, resolve the filename
1075 relative to the path of the referencing file, instead of relative
1076 to the current directory.
1077 --report-unoptflat
1079 Extra diagnostics for UNOPTFLAT warnings. This includes for each
1080 loop, the 10 widest variables in the loop, and the 10 most fanned
1081 out variables in the loop. These are candidates for splitting into
1082 multiple variables to break the loop.
1083 In addition produces a GraphViz DOT file of the entire strongly
1085 connected components within the source associated with each loop.
1086 This is produced irrespective of whether --dump-tree is set. Such
1087 graphs may help in analyzing the problem, but can be very large
1088 indeed.
1089 Various commands exist for viewing and manipulating DOT files. For
1091 example the dot command can be used to convert a DOT file to a PDF
1092 for printing. For example:
1093 dot -Tpdf -O Vt_unoptflat_simple_2_35_unoptflat.dot
1095 will generate a PDF Vt_unoptflat_simple_2_35_unoptflat.dot.pdf from
1097 the DOT file.
1098 As an alternative, the xdot command can be used to view DOT files
1100 interactively:
1101 xdot Vt_unoptflat_simple_2_35_unoptflat.dot
1103 --rr
1105 Run Verilator and record with rr. See: rr-project.org.
1106 --savable
1108 Enable including save and restore functions in the generated model.
1109 The user code must create a VerilatedSerialize or
1111 VerilatedDeserialze object then calling the << or >> operators on
1112 the generated model and any other data the process needs
1113 saved/restored. These functions are not thread safe, and are
1114 typically called only by a main thread.
1115 For example:
1117 void save_model(const char* filenamep) {
1119 VerilatedSave os;
1120 os.open(filenamep);
1121 os << main_time; // user code must save the timestamp, etc
1122 os << *topp;
1123 }
1124 void restore_model(const char* filenamep) {
1125 VerilatedRestore os;
1126 os.open(filenamep);
1127 os >> main_time;
1128 os >> *topp;
1129 }
1130 --sc
1132 Specifies SystemC output mode; see also --cc.
1133 --stats
1135 Creates a dump file with statistics on the design in
1136 {prefix}__stats.txt.
1137 --stats-vars
1139 Creates more detailed statistics, including a list of all the
1140 variables by size (plain --stats just gives a count). See --stats,
1141 which is implied by this.
1142 --structs-packed
1144 Converts all unpacked structures to packed structures and issues a
1145 UNPACKED warning. Currently this is the default and
1146 --no-structs-packed will not work. Specifying this option allows
1147 for forward compatibility when a future version of Verilator no
1148 longer always packs unpacked structures.
1149 -sv Specifies SystemVerilog language features should be enabled;
1151 equivalent to "--language 1800-2017". This option is selected by
1152 default, it exists for compatibility with other simulators.
1153 +systemverilogext+ext
1155 A synonym for "+1800-2017ext+"ext.
1156 --threads threads
1158 --no-threads
1159 With --threads 0 or --no-threads, the default, the generated model
1160 is not thread safe. With --threads 1, the generated model is single
1161 threaded but may run in a multithreaded environment. With --threads
1162 N, where N >= 2, the model is generated to run multithreaded on up
1163 to N threads. See "MULTITHREADING".
1164 --threads-dpi all
1166 --threads-dpi none
1167 --threads-dpi pure
1168 When using --threads, controls which DPI imported tasks and
1169 functions are considered thread safe.
1170 With --threads-dpi all, enable Verilator to assume all DPI imports
1172 are threadsafe, and to use thread-local storage for communication
1173 with DPI, potentially improving performance. Any DPI libraries need
1174 appropriate mutexes to avoid undefined behavior.
1175 With --threads-dpi none, Verilator assume DPI imports are not
1177 thread safe, and Verilator will serialize calls to DPI imports by
1178 default, potentially harming performance.
1179 With --threads-dpi pure, the default, Verilator assumes DPI pure
1181 imports are threadsafe, but non-pure DPI imports are not.
1182 --threads-max-mtasks value
1184 Rarely needed. When using --threads, specify the number of mtasks
1185 the model is to be partitioned into. If unspecified, Verilator
1186 approximates a good value.
1187 --timescale timeunit/timeprecision
1189 Sets default timescale, timeunit and timeprecision for when
1190 `timescale does not occur in sources. Default is "1ps/1ps" (to
1191 match SystemC). This is overridden by "--timescale-override".
1192 --timescale-override timeunit/timeprecision
1194 --timescale-override /timeprecision
1195 Overrides all `timescales in sources. The timeunit may be left
1196 empty to specify only to override the timeprecision, e.g. "/1fs".
1197 The time precision must be consistent with SystemC's
1199 sc_set_time_resolution, or the C++ code instantiating the Verilated
1200 module. As 1fs is the finest time precision it may be desirable to
1201 always use a precision of 1fs.
1202 --top topname
1204 --top-module topname
1205 When the input Verilog contains more than one top level module,
1206 specifies the name of the Verilog module to become the top level
1207 module, and sets the default for --prefix if not explicitly
1208 specified. This is not needed with standard designs with only one
1209 top. See also the MULTITOP warning section.
1210 --trace
1212 Adds waveform tracing code to the model using VCD format. This
1213 overrides "--trace-fst".
1214 Verilator will generate additional {prefix}__Trace*.cpp files that
1216 will need to be compiled. In addition verilated_vcd_sc.cpp (for
1217 SystemC traces) or verilated_vcd_c.cpp (for both) must be compiled
1218 and linked in. If using the Verilator generated Makefiles, these
1219 files will be added to the source file lists for you. If you are
1220 not using the Verilator Makefiles, you will need to add these to
1221 your Makefile manually.
1222 Having tracing compiled in may result in some small performance
1224 losses, even when tracing is not turned on during model execution.
1225 See also "--trace-threads".
1227 --trace-coverage
1229 With --trace and --coverage-*, enable tracing to include a traced
1230 signal for every --coverage-line or --coverage-user inserted
1231 coverage point, to assist in debugging coverage items. Note
1232 --coverage-toggle does not get additional signals added, as the
1233 original signals being toggle-analyzed are already visible.
1234 The added signal will be a 32-bit value which will increment on
1236 each coverage occurrence. Due to this, this option may greatly
1237 increase trace file sizes and reduce simulation speed.
1238 --trace-depth levels
1240 Specify the number of levels deep to enable tracing, for example
1241 --trace-level 1 to only see the top level's signals. Defaults to
1242 the entire model. Using a small number will decrease visibility,
1243 but greatly improve simulation performance and trace file size.
1244 --trace-fst
1246 Enable FST waveform tracing in the model. This overrides "--trace".
1247 See also "--trace-threads".
1248 --trace-max-array depth
1250 Rarely needed. Specify the maximum array depth of a signal that
1251 may be traced. Defaults to 32, as tracing large arrays may greatly
1252 slow traced simulations.
1253 --trace-max-width width
1255 Rarely needed. Specify the maximum bit width of a signal that may
1256 be traced. Defaults to 256, as tracing large vectors may greatly
1257 slow traced simulations.
1258 --no-trace-params
1260 Disable tracing of parameters.
1261 --trace-structs
1263 Enable tracing to show the name of packed structure, union, and
1264 packed array fields, rather than a single combined packed bus. Due
1265 to VCD file format constraints this may result in significantly
1266 slower trace times and larger trace files.
1267 --trace-threads threads
1269 Enable waveform tracing using separate threads. This is typically
1270 faster in simulation runtime but uses more total compute. This
1271 option is independent of, and works with, both "--trace" and
1272 "--trace-fst". Different trace formats can take advantage of more
1273 trace threads to varying degrees. Currently VCD tracing can utilize
1274 at most --trace-threads 1, and FST tracing can utilize at most
1275 --trace-threads 2. This overrides "--no-threads".
1276 --trace-underscore
1278 Enable tracing of signals that start with an underscore. Normally,
1279 these signals are not output during tracing. See also
1280 --coverage-underscore.
1281 -Uvar
1283 Undefines the given preprocessor symbol.
1284 --unroll-count loops
1286 Rarely needed. Specifies the maximum number of loop iterations
1287 that may be unrolled. See also BLKLOOPINIT warning.
1288 --unroll-stmts statements
1290 Rarely needed. Specifies the maximum number of statements in a
1291 loop for that loop to be unrolled. See also BLKLOOPINIT warning.
1292 --unused-regexp regexp
1294 Rarely needed. Specifies a simple regexp with * and ? that if a
1295 signal name matches will suppress the UNUSED warning. Defaults to
1296 "*unused*". Setting it to "" disables matching.
1297 -V Shows the verbose version, including configuration information
1299 compiled into Verilator. (Similar to perl -V.) See also --getenv.
1300 -v filename
1302 Read the filename as a Verilog library. Any modules in the file
1303 may be used to resolve instances in the top level module, else
1304 ignored. Note -v is fairly standard across Verilog tools.
1305 --no-verilate
1307 When using --build, disable generation of C++/SystemC code, and
1308 execute only the build. This can be useful for rebuilding Verilated
1309 code produced by a previous invocation of Verilator.
1310 +verilog1995ext+ext
1312 +verilog2001ext+ext
1313 Synonyms for "+1364-1995ext+"ext and "+1364-2001ext+"ext
1314 respectively
1315 --version
1317 Displays program version and exits.
1318 --vpi
1320 Enable use of VPI and linking against the verilated_vpi.cpp files.
1321 --waiver-output <filename>
1323 Generate a waiver file which contains all waiver statements to
1324 suppress the warnings emitted during this Verilator run. This in
1325 particular is useful as a starting point for solving linter
1326 warnings or suppressing them systematically.
1327 The generated file is in the Verilator Configuration format, see
1329 "CONFIGURATION FILES", and can directly be consumed by Verilator.
1330 The standard file extension is .vlt.
1331 -Wall
1333 Enable all code style warnings, including code style warnings that
1334 are normally disabled by default. Equivalent to "-Wwarn-lint
1335 -Wwarn-style". Excludes some specialty warnings, i.e.
1336 IMPERFECTSCH.
1337 -Werror-message
1339 Promote the specified warning message into an error message. This
1340 is generally to discourage users from violating important site-wide
1341 rules, for example "-Werror-NOUNOPTFLAT".
1342 -Wfuture-message
1344 Rarely needed. Suppress unknown Verilator comments or warning
1345 messages with the given message code. This is used to allow code
1346 written with pragmas for a later version of Verilator to run under
1347 a older version; add -Wfuture- arguments for each message code or
1348 comment that the new version supports which the older version does
1349 not support.
1350 -Wno-message
1352 Disable the specified warning/error message. This will override
1353 any lint_on directives in the source, i.e. the warning will still
1354 not be printed.
1355 -Wno-context
1357 Disable showing the suspected context of the warning message by
1358 quoting the source text at the suspected location. This can be
1359 used to appease tools which process the warning messages but may
1360 get confused by lines from the original source.
1361 -Wno-fatal
1363 When warnings are detected, print them, but do not terminate
1364 Verilator.
1365 Having warning messages in builds is sloppy. It is strongly
1367 recommended you cleanup your code, use inline lint_off, or use
1368 -Wno-... flags rather than using this option.
1369 -Wno-lint
1371 Disable all lint related warning messages, and all style warnings.
1372 This is equivalent to "-Wno-ALWCOMBORDER -Wno-BSSPACE
1373 -Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASTCONST
1374 -Wno-CASEWITHX -Wno-CMPCONST -Wno-COLONPLUS -Wno-ENDLABEL
1375 -Wno-IMPLICIT -Wno-LITENDIAN -Wno-PINCONNECTEMPTY -Wno-PINMISSING
1376 -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED
1377 -Wno-WIDTH" plus the list shown for Wno-style.
1378 It is strongly recommended you cleanup your code rather than using
1380 this option, it is only intended to be use when running test-cases
1381 of code received from third parties.
1382 -Wno-style
1384 Disable all code style related warning messages (note by default
1385 they are already disabled). This is equivalent to
1386 "-Wno-DECLFILENAME -Wno-DEFPARAM -Wno-IMPORTSTAR -Wno-INCABSPATH
1387 -Wno-PINCONNECTEMPTY -Wno-PINNOCONNECT -Wno-SYNCASYNCNET
1388 -Wno-UNDRIVEN -Wno-UNUSED -Wno-VARHIDDEN".
1389 -Wpedantic
1391 Warn on any construct demanded by IEEE, and disable all Verilator
1392 extensions that may interfere with IEEE compliance to the standard
1393 defined with --default-language (etc). Similar to GCC's
1394 -Wpedantic. Rarely used, and intended only for strict compliance
1395 tests.
1396 -Wwarn-message
1398 Enables the specified warning message.
1399 -Wwarn-lint
1401 Enable all lint related warning messages (note by default they are
1402 already enabled), but do not affect style messages. This is
1403 equivalent to "-Wwarn-ALWCOMBORDER -Wwarn-BSSPACE
1404 -Wwarn-CASEINCOMPLETE -Wwarn-CASEOVERLAP -Wwarn-CASEX
1405 -Wwarn-CASTCONST -Wwarn-CASEWITHX -Wwarn-CMPCONST -Wwarn-COLONPLUS
1406 -Wwarn-ENDLABEL -Wwarn-IMPLICIT -Wwarn-LITENDIAN -Wwarn-PINMISSING
1407 -Wwarn-REALCVT -Wwarn-UNSIGNED -Wwarn-WIDTH".
1408 -Wwarn-style
1410 Enable all code style related warning messages. This is equivalent
1411 to "-Wwarn ASSIGNDLY -Wwarn-DECLFILENAME -Wwarn-DEFPARAM
1412 -Wwarn-INCABSPATH -Wwarn-PINNOCONNECT -Wwarn-SYNCASYNCNET
1413 -Wwarn-UNDRIVEN -Wwarn-UNUSED -Wwarn-VARHIDDEN".
1414 --x-assign 0
1416 --x-assign 1
1417 --x-assign fast (default)
1418 --x-assign unique
1419 Controls the two-state value that is substituted when an explicit X
1420 value is encountered in the source. "--x-assign fast", the default,
1421 converts all Xs to whatever is best for performance. "--x-assign
1422 0" converts all Xs to 0s, and is also fast. "--x-assign 1"
1423 converts all Xs to 1s, this is nearly as fast as 0, but more likely
1424 to find reset bugs as active high logic will fire. Using
1425 "--x-assign unique" will result in all explicit Xs being replaced
1426 by a constant value determined at runtime. The value is determined
1427 by calling a function at initialization time. This enables
1428 randomization of Xs with different seeds on different executions.
1429 This method is the slowest, but safest for finding reset bugs.
1430 If using --x-assign unique, you may want to seed your random number
1432 generator such that each regression run gets a different
1433 randomization sequence. The simplest is to use the +verilator+seed
1434 runtime option. Alternatively use the system's srand48() or for
1435 Windows srand() function to do this. You'll probably also want to
1436 print any seeds selected, and code to enable rerunning with that
1437 same seed so you can reproduce bugs.
1438 Note. This option applies only to values which are explicitly
1440 written as X in the Verilog source code. Initial values of clocks
1441 are set to 0 unless --x-initial-edge is specified. Initial values
1442 of all other state holding variables are controlled with
1443 --x-initial.
1444 --x-initial 0
1446 --x-initial fast
1447 --x-initial unique (default)
1448 Controls the two-state value that is used to initialize variables
1449 that are not otherwise initialized.
1450 "--x-initial 0", initializes all otherwise uninitialized variables
1452 to zero.
1453 "--x-initial unique", the default, initializes variables using a
1455 function, which determines the value to use each initialization.
1456 This gives greatest flexibility and allows finding reset bugs. See
1457 "Unknown states".
1458 "--x-initial fast", is best for performance, and initializes all
1460 variables to a state Verilator determines is optimal. This may
1461 allow further code optimizations, but will likely hide any code
1462 bugs relating to missing resets.
1463 Note. This option applies only to initial values of variables.
1465 Initial values of clocks are set to 0 unless --x-initial-edge is
1466 specified.
1467 --x-initial-edge
1469 Enables emulation of event driven simulators which generally
1470 trigger an edge on a transition from X to 1 ("posedge") or X to 0
1471 ("negedge"). Thus the following code, where "rst_n" is
1472 uninitialized would set "res_n" to "1'b1" when "rst_n" is first set
1473 to zero:
1474 reg res_n = 1'b0;
1476 always @(negedge rst_n) begin
1478 if (rst_n == 1'b0) begin
1479 res_n <= 1'b1;
1480 end
1481 end
1482 In Verilator, by default, uninitialized clocks are given a value of
1484 zero, so the above "always" block would not trigger.
1485 While it is not good practice, there are some designs that rely on
1487 X X 0 triggering a "negedge", particularly in reset sequences.
1488 Using --x-initial-edge with Verilator will replicate this behavior.
1489 It will also ensure that X X 1 triggers a "posedge".
1490 Note. Some users have reported that using this option can affect
1492 convergence, and that it may be necessary to use --converge-limit
1493 to increase the number of convergence iterations. This may be
1494 another indication of problems with the modeled design that should
1495 be addressed.
1496 --xml-only
1498 Create XML output only, do not create any other output.
1499 The XML format is intended to be used to leverage Verilator's
1501 parser and elaboration to feed to other downstream tools. Be aware
1502 that the XML format is still evolving; there will be some changes
1503 in future versions.
1504 --xml-output filename
1506 Filename for XML output file. Using this option automatically sets
1507 --xml-only.
1508 -y dir
1510 Add the directory to the list of directories that should be
1511 searched for include files or libraries. The three flags -y,
1512 +incdir and -I have similar effect; +incdir and +y are fairly
1513 standard across Verilog tools while -I is used by many C++
1514 compilers.
1515 Verilator defaults to the current directory ("-y .") and any
1517 specified --Mdir, though these default paths are used after any
1518 user specified directories. This allows '-y "$(pwd)"' to be used
1519 if absolute filenames are desired for error messages instead of
1520 relative filenames.
1521
1523 The following are the arguments that may be passed to a Verilated
1524 executable, provided that executable calls Verilated::commandArgs().
1525 All simulation runtime arguments begin with +verilator, so that the
1527 user's executable may skip over all +verilator arguments when parsing
1528 its command line.
1529 +verilator+debug
1531 Enable simulation runtime debugging. Equivalent to
1532 +verilator+debugi+4.
1533 +verilator+debugi+value
1535 Enable simulation runtime debugging at the provided level.
1536 +verilator+error+limit+value
1538 Set number of non-fatal errors (e.g. assertion failures) before
1539 exiting simulation runtime. Also affects number of $stop calls
1540 needed before exit. Defaults to 1.
1541 +verilator+help
1543 Display help and exit.
1544 +verilator+prof+threads+file+filename
1546 When a model was Verilated using --prof-threads, sets the
1547 simulation runtime filename to dump to. Defaults to
1548 "profile_threads.dat".
1549 +verilator+prof+threads+start+value
1551 When a model was Verilated using --prof-threads, the simulation
1552 runtime will wait until $time is at this value (expressed in units
1553 of the time precision), then start the profiling warmup, then
1554 capturing. Generally this should be set to some time that is well
1555 within the normal operation of the simulation, i.e. outside of
1556 reset. If 0, the dump is disabled. Defaults to 1.
1557 +verilator+prof+threads+window+value
1559 When a model was Verilated using --prof-threads, after $time
1560 reaches +verilator+prof+threads+start, Verilator will warm up the
1561 profiling for this number of eval() calls, then will capture the
1562 profiling of this number of eval() calls. Defaults to 2, which
1563 makes sense for a single-clock-domain module where it's typical to
1564 want to capture one posedge eval() and one negedge eval().
1565 +verilator+rand+reset+value
1567 When a model was Verilated using "-x-initial unique", sets the
1568 simulation runtime initialization technique. 0 = Reset to zeros. 1
1569 = Reset to all-ones. 2 = Randomize. See "Unknown states".
1570 +verilator+seed+value
1572 For $random and "-x-initial unique", set the simulation runtime
1573 random seed value. If zero or not specified picks a value from the
1574 system random number generator.
1575 +verilator+noassert
1577 Disable assert checking per runtime argument. This is the same as
1578 calling "Verilated::assertOn(false)" in the model.
1579 +verilator+V
1581 Shows the verbose version, including configuration information.
1582 +verilator+version
1584 Displays program version and exits.
1585
1587 We'll compile this example into C++.
1588 mkdir test_our
1590 cd test_our
1591 cat >our.v <<'EOF'
1593 module our;
1594 initial begin $display("Hello World"); $finish; end
1595 endmodule
1596 EOF
1597 cat >sim_main.cpp <<'EOF'
1599 #include "Vour.h"
1600 #include "verilated.h"
1601 int main(int argc, char** argv, char** env) {
1602 Verilated::commandArgs(argc, argv);
1603 Vour* top = new Vour;
1604 while (!Verilated::gotFinish()) { top->eval(); }
1605 delete top;
1606 exit(0);
1607 }
1608 EOF
1609 See the README in the source kit for various ways to install or point
1611 to Verilator binaries. In brief, if you installed Verilator using the
1612 package manager of your operating system, or did a "make install" to
1613 place Verilator into your default path, you do not need anything
1614 special in your environment, and should not have VERILATOR_ROOT set.
1615 However, if you installed Verilator from sources and want to run
1616 Verilator out of where you compiled Verilator, you need to point to the
1617 kit:
1618 # See above; don't do this if using an OS-distributed Verilator
1620 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1621 export PATH=$VERILATOR_ROOT/bin:$PATH
1622 Now we run Verilator on our little example.
1624 verilator -Wall --cc our.v --exe --build sim_main.cpp
1626 We can see the source code under the "obj_dir" directory. See the
1628 FILES section below for descriptions of some of the files that were
1629 created.
1630 ls -l obj_dir
1632 (Verilator included a default compile rule and link rule, since we used
1634 --exe and passed a .cpp file on the Verilator command line. Verilator
1635 also then used "make" to build a final executable, since we used
1636 --build. You can also write your own compile rules, and run make
1637 yourself as we'll show in the SYSTEMC section.
1638 And now we run it:
1640 obj_dir/Vour
1642 And we get as output:
1644 Hello World
1646 - our.v:2: Verilog $finish
1647 Really, you're better off writing a Makefile to do all this for you.
1649 Then, when your source changes it will automatically run all of these
1650 steps; to aid this Verilator can create a makefile dependency file.
1651 See the examples directory in the distribution.
1652
1654 This is an example similar to the above, but using SystemC.
1655 mkdir test_our_sc
1657 cd test_our_sc
1658 cat >our.v <<'EOF'
1660 module our (clk);
1661 input clk; // Clock is required to get initial activation
1662 always @ (posedge clk)
1663 begin $display("Hello World"); $finish; end
1664 endmodule
1665 EOF
1666 cat >sc_main.cpp <<'EOF'
1668 #include "Vour.h"
1669 int sc_main(int argc, char** argv) {
1670 Verilated::commandArgs(argc, argv);
1671 sc_clock clk("clk", 10, SC_NS, 0.5, 3, SC_NS, true);
1672 Vour* top;
1673 top = new Vour("top");
1674 top->clk(clk);
1675 while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
1676 delete top;
1677 exit(0);
1678 }
1679 EOF
1680 See the README in the source kit for various ways to install or point
1682 to Verilator binaries. In brief, if you installed Verilator using the
1683 package manager of your operating system, or did a "make install" to
1684 place Verilator into your default path, you do not need anything
1685 special in your environment, and should not have VERILATOR_ROOT set.
1686 However, if you installed Verilator from sources and want to run
1687 Verilator out of where you compiled Verilator, you need to point to the
1688 kit:
1689 # See above; don't do this if using an OS-distributed Verilator
1691 export VERILATOR_ROOT=/path/to/where/verilator/was/installed
1692 export PATH=$VERILATOR_ROOT/bin:$PATH
1693 Now we run Verilator on our little example.
1695 verilator -Wall --sc our.v
1697 We then can compile it
1699 make -j -C obj_dir -f Vour.mk Vour__ALL.a
1701 make -j -C obj_dir -f Vour.mk ../sc_main.o verilated.o
1702 And link with SystemC. Note your path to the libraries may vary,
1704 depending on the operating system.
1705 cd obj_dir
1707 export SYSTEMC_LIBDIR=/path/to/where/libsystemc.a/exists
1708 export LD_LIBRARY_PATH=$SYSTEMC_LIBDIR:$LD_LIBRARY_PATH
1709 # Might be needed if SystemC 2.3.0
1710 export SYSTEMC_CXX_FLAGS=-pthread
1711 g++ -L$SYSTEMC_LIBDIR ../sc_main.o Vour__ALL.a verilated.o \
1713 -o Vour -lsystemc
1714 And now we run it
1716 cd ..
1718 obj_dir/Vour
1719 And we get the same output as the C++ example:
1721 Hello World
1723 - our.v:2: Verilog $finish
1724 Really, you're better off using a Makefile to do all this for you.
1726 Then, when your source changes it will automatically run all of these
1727 steps. See the examples directory in the distribution.
1728
1730 When using SystemC, evaluation of the Verilated model is managed by the
1731 SystemC kernel, and for the most part can be ignored. When using C++,
1732 the user must call eval(), or eval_step() and eval_end_step().
1733 1. When there is a single design instantiated at the C++ level that
1735 needs to evaluate, just call designp->eval().
1736 2. When there are multiple designs instantiated at the C++ level that
1738 need to evaluate, call first_designp->eval_step() then ->eval_step() on
1739 all other designs. Then call ->eval_end_step() on the first design
1740 then all other designs. If there is only a single design, you would
1741 call eval_step() then eval_end_step(); in fact eval() described above
1742 is just a wrapper which calls these two functions.
1743 When eval() is called Verilator looks for changes in clock signals and
1745 evaluates related sequential always blocks, such as computing always_ff
1746 @ (posedge...) outputs. Then Verilator evaluates combinatorial logic.
1747 Note combinatorial logic is not computed before sequential always
1749 blocks are computed (for speed reasons). Therefore it is best to set
1750 any non-clock inputs up with a separate eval() call before changing
1751 clocks.
1752 Alternatively, if all always_ff statements use only the posedge of
1754 clocks, or all inputs go directly to always_ff statements, as is
1755 typical, then you can change non-clock inputs on the negative edge of
1756 the input clock, which will be faster as there will be fewer eval()
1757 calls.
1758 For more information on evaluation, see docs/internals.adoc in the
1760 distribution.
1761
1763 For best performance, run Verilator with the "-O3 --x-assign fast
1764 --x-initial fast --noassert" flags. The -O3 flag will require longer
1765 time to run Verilator, and "--x-assign fast --x-initial fast" may
1766 increase the risk of reset bugs in trade for performance; see the above
1767 documentation for these flags.
1768 If using Verilated multithreaded, use "numactl" to ensure you are using
1770 non-conflicting hardware resources. See "MULTITHREADING".
1771 Minor Verilog code changes can also give big wins. You should not have
1773 any UNOPTFLAT warnings from Verilator. Fixing these warnings can
1774 result in huge improvements; one user fixed their one UNOPTFLAT warning
1775 by making a simple change to a clock latch used to gate clocks and
1776 gained a 60% performance improvement.
1777 Beyond that, the performance of a Verilated model depends mostly on
1779 your C++ compiler and size of your CPU's caches. Experience shows that
1780 large models are often limited by the size of the instruction cache,
1781 and as such reducing code size if possible can be beneficial.
1782 The supplied $VERILATOR_ROOT/include/verilated.mk file uses the OPT,
1784 OPT_FAST, OPT_SLOW and OPT_GLOBAL variables to control optimization.
1785 You can set these when compiling the output of Verilator with Make, for
1786 example:
1787 make OPT_FAST="-Os -march=native" -f Vour.mk Vour__ALL.a
1789 OPT_FAST specifies optimization flags for those parts of the model that
1791 are on the fast path. This is mostly code that is executed every cycle.
1792 OPT_SLOW applies to slow-path code, which executes rarely, often only
1793 once at the beginning or end of simulation. Note that OPT_SLOW is
1794 ignored if VM_PARALLEL_BUILDS is not 1, in which case all generated
1795 code will be compiled in a single compilation unit using OPT_FAST. See
1796 also the "--output-split" option. The OPT_GLOBAL variable applies to
1797 common code in the runtime library used by Verilated models (shipped in
1798 $VERILATOR_ROOT/include). Additional C++ files passed on the verilator
1799 command line use OPT_FAST. The OPT variable applies to all compilation
1800 units in addition to the specific OPT_* variables described above.
1801 You can also use the -CFLAGS and/or -LDFLAGS options on the verilator
1803 command line to pass flags directly to the compiler or linker.
1804 The default values of the OPT_* variables are chosen to yield good
1806 simulation speed with reasonable C++ compilation times. To this end,
1807 OPT_FAST is set to "-Os" by default. Higher optimization such as "-O2"
1808 or "-O3" may help (though often they provide only a very small
1809 performance benefit), but compile times may be excessively large even
1810 with medium sized designs. Compilation times can be improved at the
1811 expense of simulation speed by reducing optimization, for example with
1812 OPT_FAST="-O0". Often good simulation speed can be achieved with
1813 OPT_FAST="-O1 -fstrict-aliasing" but with improved compilation times.
1814 Files controlled by OPT_SLOW have little effect on performance and
1815 therefore OPT_SLOW is empty by default (equivalent to "-O0") for
1816 improved compilation speed. In common use-cases there should be little
1817 benefit in changing OPT_SLOW. OPT_GLOBAL is set to "-Os" by default
1818 and there should rarely be a need to change it. As the runtime library
1819 is small in comparison to a lot of Verilated models, disabling
1820 optimization on the runtime library should not have a serious effect on
1821 overall compilation time, but may have detrimental effect on simulation
1822 speed, especially with tracing. In addition to the above, for best
1823 results use OPT="-march=native", the latest Clang compiler (about 10%
1824 faster than GCC), and link statically.
1825 Generally the answer to which optimization level gives the best user
1827 experience depends on the use case and some experimentation can pay
1828 dividends. For a speedy debug cycle during development, especially on
1829 large designs where C++ compilation speed can dominate, consider using
1830 lower optimization to get to an executable faster. For throughput
1831 oriented use cases, for example regressions, it is usually worth
1832 spending extra compilation time to reduce total CPU time.
1833 If you will be running many simulations on a single model, you can
1835 investigate profile guided optimization. With GCC, using
1836 -fprofile-arcs, then -fbranch-probabilities will yield another 15% or
1837 so.
1838 Modern compilers also support link-time optimization (LTO), which can
1840 help especially if you link in DPI code. To enable LTO on GCC, pass
1841 "-flto" in both compilation and link. Note LTO may cause excessive
1842 compile times on large designs.
1843 Unfortunately, using the optimizer with SystemC files can result in
1845 compilation taking several minutes. (The SystemC libraries have many
1846 little inlined functions that drive the compiler nuts.)
1847 If you are using your own makefiles, you may want to compile the
1849 Verilated code with -DVL_INLINE_OPT=inline. This will inline functions,
1850 however this requires that all cpp files be compiled in a single
1851 compiler run.
1852 You may uncover further tuning possibilities by profiling the Verilog
1854 code. Use Verilator's --prof-cfuncs, then GCC's -g -pg. You can then
1855 run either oprofile or gprof to see where in the C++ code the time is
1856 spent. Run the gprof output through verilator_profcfunc and it will
1857 tell you what Verilog line numbers on which most of the time is being
1858 spent.
1859 When done, please let the author know the results. We like to keep
1861 tabs on how Verilator compares, and may be able to suggest additional
1862 improvements.
1863
1865 All output files are placed in the output directory specified with the
1866 "--Mdir" option, or "obj_dir" if not specified.
1867 Verilator creates the following files in the output directory:
1869 For --make gmake, it creates:
1871 {prefix}.mk // Make include file for compiling
1873 {prefix}_classes.mk // Make include file with class names
1874 {prefix}_hier.mk // Make file for hierarchy blocks
1875 {prefix}_hierMkArgs.f // Arguments for hierarchical Verilation.
1876 For --make cmake, it creates:
1878 {prefix}.cmake // CMake include script for compiling
1880 {prefix}_hierCMakeArgs.f // Arguments for hierarchical Verilation.
1881 For -cc and -sc mode, it also creates:
1883 {prefix}.cpp // Top level C++ file
1885 {prefix}.h // Top level header
1886 {prefix}__Slow{__n}.cpp // Constructors and infrequent cold routines
1887 {prefix}{__n}.cpp // Additional top C++ files (--output-split)
1888 {prefix}{each_verilog_module}.cpp // Lower level internal C++ files
1889 {prefix}{each_verilog_module}.h // Lower level internal header files
1890 {prefix}{each_verilog_module}{__n}.cpp // Additional lower C++ files (--output-split)
1891 For --hierarchy mode, it creates:
1893 {prefix}__hierVer.d // Make dependencies of the top
1894 module in the
1895 hierarchical Verilation
1896 {prefix}__hier.dir/ // Directory to store .dot,
1897 .vpp, .tree of the
1898 top module in the
1899 hierarchical Verilation
1900 V{hier_block}/ // Directory to Verilate each
1901 hierarchy block
1902 In certain debug and other modes, it also creates:
1904 {prefix}.xml // XML tree information (--xml)
1906 {prefix}__Dpi.cpp // DPI import and export wrappers
1907 {prefix}__Dpi.h // DPI import and export declarations
1908 {prefix}__Inlines.h // Inline support functions
1909 {prefix}__Syms.cpp // Global symbol table C++
1910 {prefix}__Syms.h // Global symbol table header
1911 {prefix}__Trace__Slow{__n}.cpp // Wave file generation code (--trace)
1912 {prefix}__Trace{__n}.cpp // Wave file generation code (--trace)
1913 {prefix}__cdc.txt // Clock Domain Crossing checks (--cdc)
1914 {prefix}__stats.txt // Statistics (--stats)
1915 {prefix}__idmap.txt // Symbol demangling (--protect-ids)
1916 It also creates internal files that can be mostly ignored:
1918 {mod_prefix}_{each_verilog_module}{__n}.vpp // Pre-processed verilog
1920 {prefix}__ver.d // Make dependencies (-MMD)
1921 {prefix}__verFiles.dat // Timestamps for skip-identical
1922 {prefix}{misc}.dot // Debugging graph files (--debug)
1923 {prefix}{misc}.tree // Debugging files (--debug)
1924 After running Make, the C++ compiler may produce the following:
1926 verilated{misc}.d // Intermediate dependencies
1928 verilated{misc}.o // Intermediate objects
1929 {mod_prefix}{misc}.d // Intermediate dependencies
1930 {mod_prefix}{misc}.o // Intermediate objects
1931 {prefix} // Final executable (w/--exe argument)
1932 {prefix}__ALL.a // Library of all Verilated objects
1933 {prefix}__ALL.cpp // Include of all code for single compile
1934 {prefix}{misc}.d // Intermediate dependencies
1935 {prefix}{misc}.o // Intermediate objects
1936
1938 LD_LIBRARY_PATH
1939 A generic Linux/OS variable specifying what directories have shared
1940 object (.so) files. This path should include SystemC and any other
1941 shared objects needed at simulation runtime.
1942 MAKE
1944 Names the executable of the make command invoked when using the
1945 --build option. Some operating systems may require "gmake" to this
1946 variable to launch GNU make. If this variable is not specified,
1947 "make" is used.
1948 OBJCACHE
1950 Optionally specifies a caching or distribution program to place in
1951 front of all runs of the C++ compiler. For example, "ccache". If
1952 using distcc or icecc/icecream, they would generally be run under
1953 cache; see the documentation for those programs. If OBJCACHE is
1954 not set, and at configure time ccache was present, ccache will be
1955 used as a default.
1956 SYSTEMC
1958 Deprecated. Used only if SYSTEMC_INCLUDE or SYSTEMC_LIBDIR is not
1959 set. If set, specifies the directory containing the SystemC
1960 distribution. If not specified, it will come from a default
1961 optionally specified at configure time (before Verilator was
1962 compiled).
1963 SYSTEMC_ARCH
1965 Deprecated. Used only if SYSTEMC_LIBDIR is not set. Specifies the
1966 architecture name used by the SystemC kit. This is the part after
1967 the dash in the lib-{...} directory name created by a 'make' in the
1968 SystemC distribution. If not set, Verilator will try to intuit the
1969 proper setting, or use the default optionally specified at
1970 configure time (before Verilator was compiled).
1971 SYSTEMC_CXX_FLAGS
1973 Specifies additional flags that are required to be passed to GCC
1974 when building the SystemC model. System 2.3.0 may need this set to
1975 "-pthread".
1976 SYSTEMC_INCLUDE
1978 If set, specifies the directory containing the systemc.h header
1979 file. If not specified, it will come from a default optionally
1980 specified at configure time (before Verilator was compiled), or
1981 computed from SYSTEMC/include.
1982 SYSTEMC_LIBDIR
1984 If set, specifies the directory containing the libsystemc.a
1985 library. If not specified, it will come from a default optionally
1986 specified at configure time (before Verilator was compiled), or
1987 computed from SYSTEMC/lib-SYSTEMC_ARCH.
1988 VERILATOR_BIN
1990 If set, specifies an alternative name of the "verilator" binary.
1991 May be used for debugging and selecting between multiple operating
1992 system builds.
1993 VERILATOR_COVERAGE_BIN
1995 If set, specifies an alternative name of the "verilator_coverage
1996 binary". May be used for debugging and selecting between multiple
1997 operating system builds.
1998 VERILATOR_GDB
2000 If set, the command to run when using the --gdb option, such as
2001 "ddd". If not specified, it will use "gdb".
2002 VERILATOR_ROOT
2004 Specifies the directory containing the distribution kit. This is
2005 used to find the executable, Perl library, and include files. If
2006 not specified, it will come from a default optionally specified at
2007 configure time (before Verilator was compiled). It should not be
2008 specified if using a pre-compiled Verilator package as the hard-
2009 coded value should be correct.
2010
2012 Verilator creates a prefix.h and prefix.cpp file for the top level
2013 module, together with additional .h and .cpp files for internals. See
2014 the examples directory in the kit for examples.
2015 After the model is created, there will be a prefix.mk file that may be
2017 used with Make to produce a prefix__ALL.a file with all required
2018 objects in it. This is then linked with the user's C++ main loop to
2019 create the simulation executable.
2020 The user must write the C++ main loop of the simulation. Here is a
2022 simple example:
2023 #include <verilated.h> // Defines common routines
2025 #include <iostream> // Need std::cout
2026 #include "Vtop.h" // From Verilating "top.v"
2027 Vtop *top; // Instantiation of module
2029 vluint64_t main_time = 0; // Current simulation time
2031 // This is a 64-bit integer to reduce wrap over issues and
2032 // allow modulus. This is in units of the timeprecision
2033 // used in Verilog (or from --timescale-override)
2034 double sc_time_stamp () { // Called by $time in Verilog
2036 return main_time; // converts to double, to match
2037 // what SystemC does
2038 }
2039 int main(int argc, char** argv) {
2041 Verilated::commandArgs(argc, argv); // Remember args
2042 top = new Vtop; // Create instance
2044 top->reset_l = 0; // Set some inputs
2046 while (!Verilated::gotFinish()) {
2048 if (main_time > 10) {
2049 top->reset_l = 1; // Deassert reset
2050 }
2051 if ((main_time % 10) == 1) {
2052 top->clk = 1; // Toggle clock
2053 }
2054 if ((main_time % 10) == 6) {
2055 top->clk = 0;
2056 }
2057 top->eval(); // Evaluate model
2058 cout << top->out << endl; // Read a output
2059 main_time++; // Time passes...
2060 }
2061 top->final(); // Done simulating
2063 // // (Though this example doesn't get here)
2064 delete top;
2065 }
2066 Note signals are read and written as member variables of the model.
2068 You call the eval() method to evaluate the model. When the simulation
2069 is complete call the final() method to execute any SystemVerilog final
2070 blocks, and complete any assertions. See "EVALUATION LOOP".
2071
2073 Verilator will convert the top level module to a SC_MODULE. This
2074 module will plug directly into a SystemC netlist.
2075 The SC_MODULE gets the same pinout as the Verilog module, with the
2077 following type conversions: Pins of a single bit become bool. Pins
2078 2-32 bits wide become uint32_t's. Pins 33-64 bits wide become sc_bv's
2079 or vluint64_t's depending on the --no-pins64 switch. Wider pins become
2080 sc_bv's. (Uints simulate the fastest so are used where possible.)
2081 Lower modules are not pure SystemC code. This is a feature, as using
2083 the SystemC pin interconnect scheme everywhere would reduce performance
2084 by an order of magnitude.
2085
2087 Verilator supports SystemVerilog Direct Programming Interface import
2088 and export statements. Only the SystemVerilog form ("DPI-C") is
2089 supported, not the original Synopsys-only DPI.
2090 DPI Example
2092 In the SYSTEMC example above, if you wanted to import C++ functions
2093 into Verilog, put in our.v:
2094 import "DPI-C" function int add (input int a, input int b);
2096 initial begin
2098 $display("%x + %x = %x", 1, 2, add(1,2));
2099 endtask
2100 Then after Verilating, Verilator will create a file Vour__Dpi.h with
2102 the prototype to call this function:
2103 extern int add (int a, int b);
2105 From the sc_main.cpp file (or another .cpp file passed to the Verilator
2107 command line, or the link), you'd then:
2108 #include "svdpi.h"
2110 #include "Vour__Dpi.h"
2111 int add(int a, int b) { return a+b; }
2112 DPI System Task/Functions
2114 Verilator extends the DPI format to allow using the same scheme to
2115 efficiently add system functions. Simply use a dollar-sign prefixed
2116 system function name for the import, but note it must be escaped.
2117 export "DPI-C" function integer \$myRand;
2119 initial $display("myRand=%d", $myRand());
2121 Going the other direction, you can export Verilog tasks so they can be
2123 called from C++:
2124 export "DPI-C" task publicSetBool;
2126 task publicSetBool;
2128 input bit in_bool;
2129 var_bool = in_bool;
2130 endtask
2131 Then after Verilating, Verilator will create a file Vour__Dpi.h with
2133 the prototype to call this function:
2134 extern void publicSetBool(svBit in_bool);
2136 From the sc_main.cpp file, you'd then:
2138 #include "Vour__Dpi.h"
2140 publicSetBool(value);
2141 Or, alternatively, call the function under the design class. This
2143 isn't DPI compatible but is easier to read and better supports multiple
2144 designs.
2145 #include "Vour__Dpi.h"
2147 Vour::publicSetBool(value);
2148 // or top->publicSetBool(value);
2149 Note that if the DPI task or function accesses any register or net
2151 within the RTL, it will require a scope to be set. This can be done
2152 using the standard functions within svdpi.h, after the module is
2153 instantiated, but before the task(s) and/or function(s) are called.
2154 For example, if the top level module is instantiated with the name
2156 "dut" and the name references within tasks are all hierarchical
2157 (dotted) names with respect to that top level module, then the scope
2158 could be set with
2159 #include "svdpi.h"
2161 ...
2162 svSetScope(svGetScopeFromName("TOP.dut"));
2163 (Remember that Verilator adds a "TOP" to the top of the module
2165 hierarchy.)
2166 Scope can also be set from within a DPI imported C function that has
2168 been called from Verilog by querying the scope of that function. See
2169 the sections on DPI Context Functions and DPI Header Isolation below
2170 and the comments within the svdpi.h header for more information.
2171 DPI Display Functions
2173 Verilator allows writing $display like functions using this syntax:
2174 import "DPI-C" function void
2176 \$my_display(input string formatted /*verilator sformat*/ );
2177 The /*verilator sformat*/ indicates that this function accepts a
2179 $display like format specifier followed by any number of arguments to
2180 satisfy the format.
2181 DPI Context Functions
2183 Verilator supports IEEE DPI Context Functions. Context imports pass
2184 the simulator context, including calling scope name, and filename and
2185 line number to the C code. For example, in Verilog:
2186 import "DPI-C" context function int dpic_line();
2188 initial $display("This is line %d, again, line %d\n", `line, dpic_line());
2189 This will call C++ code which may then use the svGet* functions to read
2191 information, in this case the line number of the Verilog statement that
2192 invoked the dpic_line function:
2193 int dpic_line() {
2195 // Get a scope: svScope scope = svGetScope();
2196 const char* scopenamep = svGetNameFromScope(scope);
2198 assert(scopenamep);
2199 const char* filenamep = "";
2201 int lineno = 0;
2202 if (svGetCallerInfo(&filenamep, &lineno)) {
2203 printf("dpic_line called from scope %s on line %d\n",
2204 scopenamep, lineno);
2205 return lineno;
2206 } else {
2207 return 0;
2208 }
2209 }
2210 See the IEEE Standard for more information.
2212 DPI Header Isolation
2214 Verilator places the IEEE standard header files such as svdpi.h into a
2215 separate include directory, vltstd (VeriLaTor STandarD). When
2216 compiling most applications $VERILATOR_ROOT/include/vltstd would be in
2217 the include path along with the normal $VERILATOR_ROOT/include.
2218 However, when compiling Verilated models into other simulators which
2219 have their own svdpi.h and similar standard files with different
2220 contents, the vltstd directory should not be included to prevent
2221 picking up incompatible definitions.
2222 Public Functions
2224 Instead of DPI exporting, there's also Verilator public functions,
2225 which are slightly faster, but less compatible.
2226
2228 Verilator supports a very limited subset of the VPI. This subset
2229 allows inspection, examination, value change callbacks, and depositing
2230 of values to public signals only.
2231 VPI is enabled with the verilator --vpi switch.
2233 To access signals via the VPI, Verilator must be told exactly which
2235 signals are to be accessed. This is done using the Verilator public
2236 pragmas documented below.
2237 Verilator has an important difference from an event based simulator;
2239 signal values that are changed by the VPI will not immediately
2240 propagate their values, instead the top level header file's eval()
2241 method must be called. Normally this would be part of the normal
2242 evaluation (i.e. the next clock edge), not as part of the value change.
2243 This makes the performance of VPI routines extremely fast compared to
2244 event based simulators, but can confuse some test-benches that expect
2245 immediate propagation.
2246 Note the VPI by its specified implementation will always be much slower
2248 than accessing the Verilator values by direct reference
2249 (structure->module->signame), as the VPI accessors perform lookup in
2250 functions at simulation runtime requiring at best hundreds of
2251 instructions, while the direct references are evaluated by the compiler
2252 and result in only a couple of instructions.
2253 For signal callbacks to work the main loop of the program must call
2255 VerilatedVpi::callValueCbs().
2256 VPI Example
2258 In the below example, we have readme marked read-only, and writeme
2259 which if written from outside the model will have the same semantics as
2260 if it changed on the specified clock edge.
2261 cat >our.v <<'EOF'
2263 module our (input clk);
2264 reg readme /*verilator public_flat_rd*/;
2265 reg writeme /*verilator public_flat_rw @(posedge clk) */;
2266 initial $finish;
2267 endmodule
2268 EOF
2269 There are many online tutorials and books on the VPI, but an example
2271 that accesses the above signal "readme" would be:
2272 cat >sim_main.cpp <<'<<EOF'
2274 #include "Vour.h"
2275 #include "verilated.h"
2276 #include "verilated_vpi.h" // Required to get definitions
2277 vluint64_t main_time = 0; // See comments in first example
2279 double sc_time_stamp() { return main_time; }
2280 void read_and_check() {
2282 vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
2283 if (!vh1) { vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found"); }
2284 const char* name = vpi_get_str(vpiName, vh1);
2285 printf("Module name: %s\n", name); // Prints "readme"
2286 s_vpi_value v;
2288 v.format = vpiIntVal;
2289 vpi_get_value(vh1, &v);
2290 printf("Value of v: %d\n", v.value.integer); // Prints "readme"
2291 }
2292 int main(int argc, char** argv, char** env) {
2294 Verilated::commandArgs(argc, argv);
2295 Vour* top = new Vour;
2296 Verilated::internalsDump(); // See scopes to help debug
2297 while (!Verilated::gotFinish()) {
2298 top->eval();
2299 VerilatedVpi::callValueCbs(); // For signal callbacks
2300 read_and_check();
2301 }
2302 delete top;
2303 exit(0);
2304 }
2305 EOF
2306
2308 Verilator supports cross-compiling Verilated code. This is generally
2309 used to run Verilator on a Linux system and produce C++ code that is
2310 then compiled on Windows.
2311 Cross compilation involves up to three different OSes. The build
2313 system is where you configured and compiled Verilator, the host system
2314 where you run Verilator, and the target system where you compile the
2315 Verilated code and run the simulation.
2316 Currently, Verilator requires the build and host system type to be the
2318 same, though the target system type may be different. To support this,
2319 ./configure and make Verilator on the build system. Then, run
2320 Verilator on the host system. Finally, the output of Verilator may be
2321 compiled on the different target system.
2322 To support this, none of the files that Verilator produces will
2324 reference any configure generated build-system specific files, such as
2325 config.h (which is renamed in Verilator to config_build.h to reduce
2326 confusion.) The disadvantage of this approach is that
2327 include/verilatedos.h must self-detect the requirements of the target
2328 system, rather than using configure.
2329 The target system may also require edits to the Makefiles, the simple
2331 Makefiles produced by Verilator presume the target system is the same
2332 type as the build system.
2333 CMake
2335 Verilator can be run using CMake, which takes care of both running
2336 Verilator and compiling the output. There is a CMake example in the
2337 examples/ directory. The following is a minimal CMakeLists.txt that
2338 would build the code listed in "EXAMPLE C++ EXECUTION":
2339 project(cmake_example)
2341 find_package(verilator HINTS $ENV{VERILATOR_ROOT})
2342 add_executable(Vour sim_main.cpp)
2343 verilate(Vour SOURCES our.v)
2344 find_package will automatically find an installed copy of Verilator, or
2346 use a local build if VERILATOR_ROOT is set.
2347 It is recommended to use CMake >= 3.12 and the Ninja generator, though
2349 other combinations should work. To build with CMake, change to the
2350 folder containing CMakeLists.txt and run:
2351 mkdir build
2353 cd build
2354 cmake -GNinja ..
2355 ninja
2356 Or to build with your system default generator:
2358 mkdir build
2360 cd build
2361 cmake ..
2362 cmake --build .
2363 If you're building the example you should have an executable to run:
2365 ./Vour
2367 The package sets the CMake variables verilator_FOUND, VERILATOR_ROOT
2369 and VERILATOR_BIN to the appropriate values, and also creates a
2370 verilate() function. verilate() will automatically create custom
2371 commands to run Verilator and add the generated C++ sources to the
2372 target specified.
2373 verilate(target SOURCES source ... [TOP_MODULE top] [PREFIX name]
2375 [TRACE] [TRACE_FST] [SYSTEMC] [COVERAGE]
2376 [INCLUDE_DIRS dir ...] [OPT_SLOW ...] [OPT_FAST ...]
2377 [OPT_GLOBAL ..] [DIRECTORY dir] [VERILATOR_ARGS ...])
2378 Lowercase and ... should be replaced with arguments, the uppercase
2380 parts delimit the arguments and can be passed in any order, or left out
2381 entirely if optional.
2382 verilate(target ...) can be called multiple times to add other verilog
2384 modules to an executable or library target.
2385 When generating Verilated SystemC sources, you should also include the
2387 SystemC include directories and link to the SystemC libraries.
2388 Verilator's CMake support provides a convenience function to
2390 automatically find and link to the SystemC library. It can be used as:
2391 verilator_link_systemc(target)
2393 where target is the name of your target.
2395 The search paths can be configured by setting some variables:
2397 - The variables SYSTEMC_INCLUDE and SYSTEMC_LIBDIR to give a direct
2399 path to the SystemC include an library path.
2400 - SYSTEMC_ROOT to set the installation prefix of an installed SystemC
2402 library.
2403 - SYSTEMC to set the installation prefix of an installed SystemC
2405 library
2406 (same as above).
2407 - When using Accellera's SystemC with CMake support, a CMake target is
2409 available that simplifies the above steps. This will only work if the
2410 SystemC installation can be found by CMake. This can be configured by
2411 setting the CMAKE_PREFIX_PATH variable during CMake configuration.
2412 Don't forget to set the same C++ standard for the Verilated sources as
2414 the SystemC library. This can be specified using the SYSTEMC_CXX_FLAGS
2415 environment variable.
2416 target
2418 Name of a target created by add_executable or add_library.
2419 SOURCES
2421 List of Verilog files to Verilate. Must have at least one file.
2422 PREFIX
2424 Optional. Sets the Verilator output prefix. Defaults to the name of
2425 the first source file with a "V" prepended. Must be unique in each
2426 call to verilate(), so this is necessary if you build a module
2427 multiple times with different parameters. Must be a valid C++
2428 identifier, i.e. contains no white space and only characters A-Z,
2429 a-z, 0-9 or _.
2430 TOP_MODULE
2432 Optional. Sets the name of the top module. Defaults to the name of
2433 the first file in the SOURCES array.
2434 TRACE
2436 Optional. Enables VCD tracing if present, equivalent to
2437 "VERILATOR_ARGS --trace".
2438 TRACE_FST
2440 Optional. Enables FST tracing if present, equivalent to
2441 "VERILATOR_ARGS --trace-fst".
2442 SYSTEMC
2444 Optional. Enables SystemC mode, defaults to C++ if not specified.
2445 COVERAGE
2447 Optional. Enables coverage if present, equivalent to
2448 "VERILATOR_ARGS --coverage"
2449 INCLUDE_DIRS
2451 Optional. Sets directories that Verilator searches (same as -y).
2452 OPT_SLOW
2454 Optional. Set compiler flags for the slow path. You may want to
2455 reduce the optimization level to improve compile times with large
2456 designs.
2457 OPT_FAST
2459 Optional. Set compiler flags for the fast path.
2460 OPT_GLOBAL
2462 Optional. Set compiler flags for the common runtime library used by
2463 Verilated models.
2464 DIRECTORY
2466 Optional. Set the verilator output directory. It is preferable to
2467 use the default, which will avoid collisions with other files.
2468 VERILATOR_ARGS
2470 Optional. Extra arguments to Verilator. Do not specify --Mdir or
2471 --prefix here, use DIRECTORY or PREFIX.
2472
2474 Large designs may take long (e.g. 10+ minutes) and huge memory (e.g.
2475 100+GB) to Verilate. One workaround is hierarchical Verilation, it is
2476 to Verilate each moderate size of building blocks and finally combine
2477 the building blocks. The building block will be called "hierarchy
2478 block" later.
2479 The current hierarchical Verilation is based on protect-lib. Each
2481 hierarchy block is Verilated to protect-lib. User modules of the
2482 hierarchy blocks will see a tiny wrapper generated by protect-lib
2483 instead of the actual design.
2484 Usage
2486 All user need to do is mark moderate size of module as hierarchy block
2487 and pass --hierarchical option to verilator command. There are two
2488 ways to mark a module:
2489 a) Write /* verilator hier_block */ metacomment in HDL code
2491 See L</"LANGUAGE EXTENSIONS"> for more detail.
2492 b) add hier_block line in the configuration file.
2493 See C<hier_block> in L</"CONFIGURATION FILES"> for example.
2494 You don't have to take care of hierarchical blocks when compiling
2496 Verilated C++ code. You can compile as usual.
2497 make -C obj_dir -f Vtop_module_name.mk
2498 See also "Overlapping Verilation and compilation" to get executable
2500 quickly.
2501 Limitations
2503 Because hierarchy blocks are Verilated to protect-lib, they have some
2504 limitations such as:
2505 The block cannot be accessed using dot (.) from upper module.
2507 Signals in the block cannot be traced.
2508 Modport cannot be used at the hirarchical block boundary.
2509 On the other hand, the following usage is supported.
2511 - Nested hierarchy block. A hierarchy block may instantiate other
2513 hierarchy blocks.
2514 - Parameterized hierarchy block. Parameters of a hierarchy block can be
2515 overridden using #(.param_name(value)) construct.
2516 The simulation speed may not be as fast as flat Verilation, in which
2518 all modules are globally scheduled.
2519 Overlapping Verilation and compilation
2521 Verilator needs to run N + 2 times in hierarchical Verilation, where N
2522 is the number of hierarchy blocks. 1 of 2 is for the top module which
2523 refers wrappers of all other hierarchy blocks. The other 1 of 2 is the
2524 initial run that searches modules marked with /*verilator hier_block*/
2525 metacomment and creates a plan and write in (prefix)_hier.mk. This
2526 initial run internally invokes other N + 1 runs, so you don't have to
2527 care about these N + 1 times of run.
2528 If -j <jobs> option is specified, Verilation for hierarchy blocks runs
2530 in parallel.
2531 If --build option is also specified, C++ compilation also runs as soon
2533 as a hierarchy block is Verilated. C++ compilation and Verilation for
2534 other hierarchy blocks run simultaneously.
2535
2537 Verilator supports multithreaded simulation models.
2538 With --no-threads, the default, the model is not thread safe, and any
2540 use of more than one thread calling into one or even different
2541 Verilated models may result in unpredictable behavior. This gives the
2542 highest single thread performance.
2543 With --threads 1, the generated model is single threaded, however the
2545 support libraries are multithread safe. This allows different
2546 instantiations of model(s) to potentially each be run under a different
2547 thread. All threading is the responsibility of the user's C++
2548 testbench.
2549 With --threads N, where N is at least 2, the generated model will be
2551 designed to run in parallel on N threads. The thread calling eval()
2552 provides one of those threads, and the generated model will create and
2553 manage the other N-1 threads. It's the client's responsibility not to
2554 oversubscribe the available CPU cores. Under CPU oversubscription, the
2555 Verilated model should not livelock nor deadlock, however, you can
2556 expect performance to be far worse than it would be with proper ratio
2557 of threads and CPU cores.
2558 The remainder of this section describe behavior with --threads 1 or
2560 --threads N (not --no-threads).
2561 VL_THREADED is defined when compiling a threaded Verilated module,
2563 causing the Verilated support classes become threadsafe.
2564 The thread used for constructing a model must be the same thread that
2566 calls eval() into the model, this is called the "eval thread". The
2567 thread used to perform certain global operations such as saving and
2568 tracing must be done by a "main thread". In most cases the eval thread
2569 and main thread are the same thread (i.e. the user's top C++ testbench
2570 runs on a single thread), but this is not required.
2571 The --trace-threads options can be used to produce trace dumps using
2573 multiple threads. If --trace-threads is set without --threads, then
2574 --trace-threads will imply --threads 1, i.e.: the support libraries
2575 will be thread safe.
2576 With --trace-threads 0, trace dumps are produced on the main thread.
2578 This again gives the highest single thread performance.
2579 With --trace-threads N, where N is at least 1, N additional threads
2581 will be created and managed by the trace files (e.g.: VerilatedVcdC or
2582 VerilatedFstC), to generate the trace dump. The main thread will be
2583 released to proceed with execution as soon as possible, though some
2584 blocking of the main thread is still necessary while capturing the
2585 trace. Different trace formats can utilize a various number of threads.
2586 See the --trace-threads option.
2587 When running a multithreaded model, the default Linux task scheduler
2589 often works against the model, by assuming threads are short lived, and
2590 thus often schedules threads using multiple hyperthreads within the
2591 same physical core. For best performance use the "numactl" program to
2592 (when the threading count fits) select unique physical cores on the
2593 same socket. The same applies for --trace-threads as well.
2594 As an example, if a model was Verilated with "--threads 4", we consult
2596 egrep 'processor|physical id|core id' /proc/cpuinfo
2598 To select cores 0, 1, 2, and 3 that are all located on the same socket
2600 (0) but different physical cores. (Also useful is "numactl
2601 --hardware", or "lscpu" but those doesn't show Hyperthreading cores.)
2602 Then we execute
2603 numactl -m 0 -C 0,1,2,3 -- verilated_executable_name
2605 This will limit memory to socket 0, and threads to cores 0, 1, 2, 3,
2607 (presumably on socket 0) optimizing performance. Of course this must
2608 be adjusted if you want another simulator using e.g. socket 1, or if
2609 you Verilated with a different number of threads. To see what CPUs are
2610 actually used, use --prof-threads.
2611 Multithreaded Verilog and Library Support
2613 $display/$stop/$finish are delayed until the end of an eval() call in
2614 order to maintain ordering between threads. This may result in
2615 additional tasks completing after the $stop or $finish.
2616 If using --coverage, the coverage routines are fully thread safe.
2618 If using --dpi, Verilator assumes pure DPI imports are thread safe,
2620 balancing performance versus safety. See --threads-dpi.
2621 If using --savable, the save/restore classes are not multithreaded
2623 and must be called only by the eval thread.
2624 If using --sc, the SystemC kernel is not thread safe, therefore the
2626 eval thread and main thread must be the same.
2627 If using --trace, the tracing classes must be constructed and
2629 called from the main thread.
2630 If using --vpi, since SystemVerilog VPI was not architected by IEEE
2632 to be multithreaded, Verilator requires all VPI calls are only made
2633 from the main thread.
2634
2636 In addition to the command line, warnings and other features may be
2637 controlled by configuration files, typically named with the .vlt
2638 extension. An example:
2639 `verilator_config
2641 lint_off -rule WIDTH
2642 lint_off -rule CASEX -file "silly_vendor_code.v"
2643 This disables WIDTH warnings globally, and CASEX for a specific file.
2645 Configuration files are fed through the normal Verilog preprocessor
2647 prior to parsing, so `ifdefs, `defines, and comments may be used as if
2648 it were normal Verilog code.
2649 Note that file or line-specific configuration only applies to files
2651 read after the configuration file. It is therefore recommended to pass
2652 the configuration file to Verilator as the first file.
2653 The grammar of configuration commands is as follows:
2655 `verilator_config
2657 Take remaining text and treat it as Verilator configuration
2658 commands.
2659 coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2661 coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2662 Enable/disable coverage for the specified filename (or wildcard
2663 with '*' or '?', or all files if omitted) and range of line numbers
2664 (or all lines if omitted). Often used to ignore an entire module
2665 for coverage analysis purposes.
2666 lint_on [-rule <message>] [-file "<filename>" [-lines <line> [ -
2668 <line>]]]
2669 lint_off [-rule <message>] [-file "<filename>" [-lines <line> [ -
2670 <line>]]]
2671 lint_off [-rule <message>] [-file "<filename>"] [-match "<string>"]
2672 Enable/disables the specified lint warning, in the specified
2673 filename (or wildcard with '*' or '?', or all files if omitted) and
2674 range of line numbers (or all lines if omitted).
2675 With lint_off using '*' will override any lint_on directives in the
2677 source, i.e. the warning will still not be printed.
2678 If the -rule is omitted, all lint warnings (see list in -Wno-lint)
2680 are enabled/disabled. This will override all later lint warning
2681 enables for the specified region.
2682 If -match is set the linter warnings are matched against this
2684 (wildcard) string and are waived in case they match and iff rule
2685 and file (with wildcard) also match.
2686 In previous versions -rule was named -msg. The latter is
2688 deprecated, but still works with a deprecation info, it may be
2689 removed in future versions.
2690 tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]
2692 tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
2693 Enable/disable waveform tracing for all future signals declared in
2694 the specified filename (or wildcard with '*' or '?', or all files
2695 if omitted) and range of line numbers (or all lines if omitted).
2696 For tracing_off, instances below any module in the files/ranges
2698 specified will also not be traced.
2699 clock_enable -module "<modulename>" -var "<signame>"
2701 Indicate the signal is used to gate a clock, and the user takes
2702 responsibility for insuring there are no races related to it.
2703 Same as /*verilator clock_enable*/, see "LANGUAGE EXTENSIONS" for
2705 more information and an example.
2706 clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
2708 clocker -module "<modulename>" [-function "<funcname>"] -var
2709 "<signame>"
2710 no_clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
2711 no_clocker -module "<modulename>" [-function "<funcname>"] -var
2712 "<signame>"
2713 Indicate the signal is used as clock or not. This information is
2714 used by Verilator to mark the signal as clocker and propagate the
2715 clocker attribute automatically to derived signals. See "--clk" for
2716 more information.
2717 Same as /*verilator clocker*/, see "LANGUAGE EXTENSIONS" for more
2719 information.
2720 coverage_block_off -module "<modulename>" -block "<blockname>"
2722 coverage_block_off -file "<filename>" -line <lineno>
2723 Specifies the entire begin/end block should be ignored for coverage
2724 analysis purposes. Can either be specified as a named block or as
2725 a filename and line number.
2726 Same as /*verilator coverage_block_off*/, see "LANGUAGE EXTENSIONS"
2728 for more information.
2729 full_case -file "<filename>" -lines <lineno>
2731 parallel_case -file "<filename>" -lines <lineno>
2732 Same as "//synopsys full_case" and "//synopsys parallel_case". When
2733 these synthesis directives are discovered, Verilator will either
2734 formally prove the directive to be true, or failing that, will
2735 insert the appropriate code to detect failing cases at simulation
2736 runtime and print an "Assertion failed" error message.
2737 hier_block -module "<modulename>"
2739 Specifies that the module is a unit of hierarchical Verilation.
2740 Note that the setting is ignored unless --hierachical option is
2741 specified. See "HIERARCHICAL VERILATION" for more information.
2742 inline -module "<modulename>"
2744 Specifies the module may be inlined into any modules that use this
2745 module. Same as /*verilator inline_module*/, and see that under
2746 "LANGUAGE EXTENSIONS" for more information.
2747 isolate_assignments -module "<modulename>" [-task "<taskname>"] -var
2749 "<signame>"
2750 isolate_assignments -module "<modulename>" [-function "<funcname>"]
2751 -var "<signame>"
2752 isolate_assignments -module "<modulename>" -function "<fname>"
2753 Used to indicate the assignments to this signal in any blocks
2754 should be isolated into new blocks. When there is a large
2755 combinatorial block that is resulting in a UNOPTFLAT warning,
2756 attaching this to the signal causing a false loop may clear up the
2757 problem.
2758 Same as /* verilator isolate_assignments */, see "LANGUAGE
2760 EXTENSIONS" for more information.
2761 no_inline -module "<modulename>"
2763 Specifies the module should not be inlined into any modules that
2764 use this module. Same as /*verilator no_inline_module*/, and see
2765 that under "LANGUAGE EXTENSIONS" for more information.
2766 no_inline [-module "<modulename>"] -task "<taskname>"
2768 no_inline [-module "<modulename>"] -function "<funcname>"
2769 Specify the function or task should not be inlined into where it is
2770 used. This may reduce the size of the final executable when a task
2771 is used a very large number of times. For this flag to work, the
2772 task and tasks below it must be pure; they cannot reference any
2773 variables outside the task itself.
2774 Same as /*verilator no_inline_task*/, see "LANGUAGE EXTENSIONS" for
2776 more information.
2777 public [-module "<modulename>"] [-task/-function "<taskname>"] -var
2779 "<signame>"
2780 public_flat [-module "<modulename>"] [-task/-function "<taskname>"]
2781 -var "<signame>"
2782 public_flat_rd [-module "<modulename>"] [-task/-function "<taskname>"]
2783 -var "<signame>"
2784 public_flat_rw [-module "<modulename>"] [-task/-function "<taskname>"]
2785 -var "<signame>" "@(edge)"
2786 Sets the variable to be public. Same as /*verilator public*/ or
2787 /*verilator public_flat*/ etc, see those under "LANGUAGE
2788 EXTENSIONS" for more information.
2789 sc_bv -module "<modulename>" [-task "<taskname>"] -var "<signame>"
2791 sc_bv -module "<modulename>" [-function "<funcname>"] -var "<signame>"
2792 Sets the port to be of sc_bv<width> type, instead of bool,
2793 vluint32_t or vluint64_t. Same as /*verilator sc_bv*/, see that
2794 under "LANGUAGE EXTENSIONS" for more information.
2795 sformat [-module "<modulename>"] [-task "<taskname>"] -var "<signame>"
2797 sformat [-module "<modulename>"] [-function "<funcname>"] -var
2798 "<signame>"
2799 Must be applied to the final argument of type "input string" of a
2800 function or task to indicate the function or task should pass all
2801 remaining arguments through $sformatf. This allows creation of DPI
2802 functions with $display like behavior. See the
2803 test_regress/t/t_dpi_display.v file for an example.
2804 Same as /*verilator sformat*/, see "LANGUAGE EXTENSIONS" for more
2806 information.
2807 split_var [-module "<modulename>"] [-task "<taskname>"] -var
2809 "<varname>"
2810 split_var [-module "<modulename>"] [-function "<funcname>"] -var
2811 "<varname>"
2812 Break the variable into multiple pieces typically to resolve
2813 UNOPTFLAT performance issues. Typically the variables to attach
2814 this to are recommended by Verilator itself, see UNOPTFLAT.
2815 Same as /*verilator split_var*/, see "LANGUAGE EXTENSIONS" for more
2817 information.
2818
2820 Verilog 2001 (IEEE 1364-2001) Support
2821 Verilator supports most Verilog 2001 language features. This includes
2822 signed numbers, "always @*", generate statements, multidimensional
2823 arrays, localparam, and C-style declarations inside port lists.
2824 Verilog 2005 (IEEE 1364-2005) Support
2826 Verilator supports most Verilog 2005 language features. This includes
2827 the `begin_keywords and `end_keywords compiler directives, $clog2, and
2828 the uwire keyword.
2829 SystemVerilog 2005 (IEEE 1800-2005) Support
2831 Verilator supports ==? and !=? operators, ++ and -- in some contexts,
2832 $bits, $countbits, $countones, $error, $fatal, $info, $isunknown,
2833 $onehot, $onehot0, $unit, $warning, always_comb, always_ff,
2834 always_latch, bit, byte, chandle, const, do-while, enum, export, final,
2835 import, int, interface, logic, longint, modport, package, program,
2836 shortint, struct, time, typedef, union, var, void, priority case/if,
2837 and unique case/if.
2838 It also supports .name and .* interconnection.
2840 Verilator partially supports concurrent assert and cover statements;
2842 see the enclosed coverage tests for the syntax which is allowed.
2843 SystemVerilog 2012 (IEEE 1800-2012) Support
2845 Verilator implements a full SystemVerilog 2012 preprocessor, including
2846 function call-like preprocessor defines, default define arguments,
2847 `__FILE__, `__LINE__ and `undefineall.
2848 Verilator currently has some support for SystemVerilog synthesis
2850 constructs. As SystemVerilog features enter common usage they are
2851 added; please file a bug if a feature you need is missing.
2852 SystemVerilog 2017 (IEEE 1800-2017) Support
2854 Verilator supports the 2017 "for" loop constructs, and several minor
2855 cleanups made in 1800-2017.
2856 Verilog AMS Support
2858 Verilator implements a very small subset of Verilog AMS (Verilog Analog
2859 and Mixed-Signal Extensions) with the subset corresponding to those VMS
2860 keywords with near equivalents in the Verilog 2005 or SystemVerilog
2861 2009 languages.
2862 AMS parsing is enabled with "--language VAMS" or "--language
2864 1800+VAMS".
2865 At present Verilator implements ceil, exp, floor, ln, log, pow, sqrt,
2867 string, and wreal.
2868 Synthesis Directive Assertion Support
2870 With the --assert switch, Verilator reads any "//synopsys full_case" or
2871 "//synopsys parallel_case" directives. The same applies to any
2872 "//ambit synthesis", "//cadence" or "//pragma" directives of the same
2873 form.
2874 When these synthesis directives are discovered, Verilator will either
2876 formally prove the directive to be true, or failing that, will insert
2877 the appropriate code to detect failing cases at simulation runtime and
2878 print an "Assertion failed" error message.
2879 Verilator likewise also asserts any "unique" or "priority"
2881 SystemVerilog keywords on case statement, as well as "unique" on if
2882 statements. However, "priority if" is currently simply ignored.
2883
2885 The following additional constructs are the extensions Verilator
2886 supports on top of standard Verilog code. Using these features outside
2887 of comments or `ifdef's may break other tools.
2888 `__FILE__
2890 The __FILE__ define expands to the current filename as a string,
2891 like C++'s __FILE__. This was incorporated into to the 1800-2009
2892 standard (but supported by Verilator since 2006!)
2893 `__LINE__
2895 The __LINE__ define expands to the current filename as a string,
2896 like C++'s __LINE__. This was incorporated into to the 1800-2009
2897 standard (but supported by Verilator since 2006!)
2898 `error string
2900 This will report an error when encountered, like C++'s #error.
2901 $c(string, ...);
2903 The string will be embedded directly in the output C++ code at the
2904 point where the surrounding Verilog code is compiled. It may
2905 either be a standalone statement (with a trailing ; in the string),
2906 or a function that returns up to a 32-bit number (without a
2907 trailing ;). This can be used to call C++ functions from your
2908 Verilog code.
2909 String arguments will be put directly into the output C++ code.
2911 Expression arguments will have the code to evaluate the expression
2912 inserted. Thus to call a C++ function, $c("func(",a,")") will
2913 result in 'func(a)' in the output C++ code. For input arguments,
2914 rather than hard-coding variable names in the string $c("func(a)"),
2915 instead pass the variable as an expression $c("func(",a,")"). This
2916 will allow the call to work inside Verilog functions where the
2917 variable is flattened out, and also enable other optimizations.
2918 If you will be reading or writing any Verilog variables inside the
2920 C++ functions, the Verilog signals must be declared with
2921 /*verilator public*/.
2922 You may also append an arbitrary number to $c, generally the width
2924 of the output. [signal_32_bits = $c32("...");] This allows for
2925 compatibility with other simulators which require a differently
2926 named PLI function name for each different output width.
2927 $display, $write, $fdisplay, $fwrite, $sformat, $swrite
2929 Format arguments may use C fprintf sizes after the % escape. Per
2930 the Verilog standard, %x prints a number with the natural width,
2931 and %0x prints a number with minimum width. Verilator extends this
2932 so %5x prints 5 digits per the C standard (this is unspecified in
2933 Verilog, but was incorporated into the 1800-2009).
2934 `coverage_block_off
2936 Specifies the entire begin/end block should be ignored for coverage
2937 analysis. Must be inside a code block, e.g. within a begin/end
2938 pair. Same as /* verilator coverage_block_off */ and
2939 "coverage_block_off" in "CONFIGURATION FILES".
2940 `systemc_header
2942 Take remaining text up to the next `verilog or `systemc_... mode
2943 switch and place it verbatim into the output .h file's header.
2944 Must be placed as a module item, e.g. directly inside a
2945 module/endmodule pair. Despite the name of this macro, this also
2946 works in pure C++ code.
2947 `systemc_ctor
2949 Take remaining text up to the next `verilog or `systemc_... mode
2950 switch and place it verbatim into the C++ class constructor. Must
2951 be placed as a module item, e.g. directly inside a module/endmodule
2952 pair. Despite the name of this macro, this also works in pure C++
2953 code.
2954 `systemc_dtor
2956 Take remaining text up to the next `verilog or `systemc_... mode
2957 switch and place it verbatim into the C++ class destructor. Must
2958 be placed as a module item, e.g. directly inside a module/endmodule
2959 pair. Despite the name of this macro, this also works in pure C++
2960 code.
2961 `systemc_interface
2963 Take remaining text up to the next `verilog or `systemc_... mode
2964 switch and place it verbatim into the C++ class interface. Must be
2965 placed as a module item, e.g. directly inside a module/endmodule
2966 pair. Despite the name of this macro, this also works in pure C++
2967 code.
2968 `systemc_imp_header
2970 Take remaining text up to the next `verilog or `systemc_... mode
2971 switch and place it verbatim into the header of all files for this
2972 C++ class implementation. Must be placed as a module item, e.g.
2973 directly inside a module/endmodule pair. Despite the name of this
2974 macro, this also works in pure C++ code.
2975 `systemc_implementation
2977 Take remaining text up to the next `verilog or `systemc_... mode
2978 switch and place it verbatim into a single file of the C++ class
2979 implementation. Must be placed as a module item, e.g. directly
2980 inside a module/endmodule pair. Despite the name of this macro,
2981 this also works in pure C++ code.
2982 If you will be reading or writing any Verilog variables in the C++
2984 functions, the Verilog signals must be declared with /*verilator
2985 public*/. See also the public task feature; writing an accessor
2986 may result in cleaner code.
2987 `SYSTEMVERILOG
2989 The SYSTEMVERILOG, SV_COV_START and related standard defines are
2990 set by default when --language is 1800-*.
2991 `VERILATOR
2993 `verilator
2994 `verilator3
2995 The VERILATOR, verilator and verilator3 defines are set by default
2996 so you may `ifdef around tool specific constructs.
2997 `verilator_config
2999 Take remaining text up to the next `verilog mode switch and treat
3000 it as Verilator configuration commands.
3001 `verilog
3003 Switch back to processing Verilog code after a `systemc_... mode
3004 switch. The Verilog code returns to the last language mode
3005 specified with `begin_keywords, or SystemVerilog if none was
3006 specified.
3007 /*verilator clock_enable*/
3009 Used after a signal declaration to indicate the signal is used to
3010 gate a clock, and the user takes responsibility for insuring there
3011 are no races related to it. (Typically by adding a latch, and
3012 running static timing analysis.) For example:
3013 reg enable_r /*verilator clock_enable*/;
3015 wire gated_clk = clk & enable_r;
3016 always_ff @ (posedge clk)
3017 enable_r <= enable_early;
3018 The clock_enable attribute will cause the clock gate to be ignored
3020 in the scheduling algorithm, sometimes required for correct clock
3021 behavior, and always improving performance. It's also a good idea
3022 to enable the IMPERFECTSCH warning, to ensure all clock enables are
3023 properly recognized.
3024 Same as "clock_enable" in configuration files, see "CONFIGURATION
3026 FILES" for more information.
3027 /*verilator clocker*/
3029 /*verilator no_clocker*/
3030 Used after a signal declaration to indicate the signal is used as
3031 clock or not. This information is used by Verilator to mark the
3032 signal as clocker and propagate the clocker attribute automatically
3033 to derived signals. See "--clk" for more information.
3034 Same as "clocker" and "no_clocker" in configuration files, see
3036 "CONFIGURATION FILES" for more information.
3037 /*verilator coverage_block_off*/
3039 Specifies the entire begin/end block should be ignored for coverage
3040 analysis purposes.
3041 Same as "coverage_block_off" in configuration files, see
3043 "CONFIGURATION FILES" for more information.
3044 /*verilator coverage_off*/
3046 Specifies that following lines of code should have coverage
3047 disabled. Often used to ignore an entire module for coverage
3048 analysis purposes.
3049 /*verilator coverage_on*/
3051 Specifies that following lines of code should have coverage re-
3052 enabled (if appropriate --coverage flags are passed) after being
3053 disabled earlier with /*verilator coverage_off*/.
3054 /*verilator hier_block*/
3056 Specifies that the module is a unit of hierarchical Verilation.
3057 This metacomment must be between
3058 "module module_name(...);" and "endmodule". The module will not
3059 be inlined nor uniquified for each instance in hierarchical
3060 Verilation. Note that the metacomment is ignored unless
3061 --hierachical option is specified.
3062 See "HIERARCHICAL VERILATION" for more information.
3064 /*verilator inline_module*/
3066 Specifies the module the comment appears in may be inlined into any
3067 modules that use this module. This is useful to speed up
3068 simulation runtime. Note if using "--public" that signals under
3069 inlined submodules will be named submodule__DOT__subsignal as C++
3070 does not allow "." in signal names.
3071 Same as "inline" in configuration files, see "CONFIGURATION FILES"
3073 for more information.
3074 /*verilator isolate_assignments*/
3076 Used after a signal declaration to indicate the assignments to this
3077 signal in any blocks should be isolated into new blocks. When
3078 there is a large combinatorial block that is resulting in a
3079 UNOPTFLAT warning, attaching this to the signal causing a false
3080 loop may clear up the problem.
3081 IE, with the following
3083 reg splitme /* verilator isolate_assignments*/;
3085 // Note the placement of the semicolon above
3086 always @* begin
3087 if (....) begin
3088 splitme = ....;
3089 other assignments
3090 end
3091 end
3092 Verilator will internally split the block that assigns to "splitme"
3094 into two blocks:
3095 It would then internally break it into (sort of):
3097 // All assignments excluding those to splitme
3099 always @* begin
3100 if (....) begin
3101 other assignments
3102 end
3103 end
3104 // All assignments to splitme
3105 always @* begin
3106 if (....) begin
3107 splitme = ....;
3108 end
3109 end
3110 Same as "isolate_assignments" in configuration files, see
3112 "CONFIGURATION FILES" for more information.
3113 /*verilator lint_off msg*/
3115 Disable the specified warning message for any warnings following
3116 the comment.
3117 /*verilator lint_on msg*/
3119 Re-enable the specified warning message for any warnings following
3120 the comment.
3121 /*verilator lint_restore*/
3123 After a /*verilator lint_save*/, pop the stack containing lint
3124 message state. Often this is useful at the bottom of include
3125 files.
3126 /*verilator lint_save*/
3128 Push the current state of what lint messages are turned on or
3129 turned off to a stack. Later meta-comments may then lint_on or
3130 lint_off specific messages, then return to the earlier message
3131 state by using /*verilator lint_restore*/. For example:
3132 // verilator lint_save
3134 // verilator lint_off SOME_WARNING
3135 ... // code needing SOME_WARNING turned off
3136 // verilator lint_restore
3137 If SOME_WARNING was on before the lint_off, it will now be restored
3139 to on, and if it was off before the lint_off it will remain off.
3140 /*verilator no_inline_module*/
3142 Specifies the module the comment appears in should not be inlined
3143 into any modules that use this module.
3144 Same as "no_inline" in configuration files, see "CONFIGURATION
3146 FILES" for more information.
3147 /*verilator no_inline_task*/
3149 Used in a function or task variable definition section to specify
3150 the function or task should not be inlined into where it is used.
3151 This may reduce the size of the final executable when a task is
3152 used a very large number of times. For this flag to work, the task
3153 and tasks below it must be pure; they cannot reference any
3154 variables outside the task itself.
3155 Same as "no_inline" in configuration files, see "CONFIGURATION
3157 FILES" for more information.
3158 /*verilator public*/ (parameter)
3160 Used after a parameter declaration to indicate the emitted C code
3161 should have the parameter values visible. Due to C++ language
3162 restrictions, this may only be used on 64-bit or narrower integral
3163 enumerations.
3164 parameter [2:0] PARAM /*verilator public*/ = 2'b0;
3166 /*verilator public*/ (typedef enum)
3168 Used after an enum typedef declaration to indicate the emitted C
3169 code should have the enum values visible. Due to C++ language
3170 restrictions, this may only be used on 64-bit or narrower integral
3171 enumerations.
3172 typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
3174 /*verilator public*/ (variable)
3176 Used after an input, output, register, or wire declaration to
3177 indicate the signal should be declared so that C code may read or
3178 write the value of the signal. This will also declare this module
3179 public, otherwise use /*verilator public_flat*/.
3180 Instead of using public variables, consider instead making a DPI or
3182 public function that accesses the variable. This is nicer as it
3183 provides an obvious entry point that is also compatible across
3184 simulators.
3185 Same as "public" in configuration files, see "CONFIGURATION FILES"
3187 for more information.
3188 /*verilator public*/ (task/function)
3190 Used inside the declaration section of a function or task
3191 declaration to indicate the function or task should be made into a
3192 C++ function, public to outside callers. Public tasks will be
3193 declared as a void C++ function, public functions will get the
3194 appropriate non-void (bool, uint32_t, etc) return type. Any input
3195 arguments will become C++ arguments to the function. Any output
3196 arguments will become C++ reference arguments. Any local
3197 registers/integers will become function automatic variables on the
3198 stack.
3199 Wide variables over 64 bits cannot be function returns, to avoid
3201 exposing complexities. However, wide variables can be
3202 input/outputs; they will be passed as references to an array of
3203 32-bit numbers.
3204 Generally, only the values of stored state (flops) should be
3206 written, as the model will NOT notice changes made to variables in
3207 these functions. (Same as when a signal is declared public.)
3208 You may want to use DPI exports instead, as it's compatible with
3210 other simulators.
3211 Same as "public" in configuration files, see "CONFIGURATION FILES"
3213 for more information.
3214 /*verilator public_flat*/ (variable)
3216 Used after an input, output, register, or wire declaration to
3217 indicate the signal should be declared so that C code may read or
3218 write the value of the signal. This will not declare this module
3219 public, which means the name of the signal or path to it may change
3220 based upon the module inlining which takes place.
3221 Same as "public_flat" in configuration files, see "CONFIGURATION
3223 FILES" for more information.
3224 /*verilator public_flat_rd*/ (variable)
3226 Used after an input, output, register, or wire declaration to
3227 indicate the signal should be declared public_flat (see above), but
3228 read-only.
3229 Same as "public_flat_rd" in configuration files, see "CONFIGURATION
3231 FILES" for more information.
3232 /*verilator public_flat_rw @(<edge_list>) */ (variable)
3234 Used after an input, output, register, or wire declaration to
3235 indicate the signal should be declared public_flat_rd (see above),
3236 and also writable, where writes should be considered to have the
3237 timing specified by the given sensitivity edge list. Set for all
3238 variables, ports and wires using the --public-flat-rw switch.
3239 Same as "public_flat_rw" in configuration files, see "CONFIGURATION
3241 FILES" for more information.
3242 /*verilator public_module*/
3244 Used after a module statement to indicate the module should not be
3245 inlined (unless specifically requested) so that C code may access
3246 the module. Verilator automatically sets this attribute when the
3247 module contains any public signals or `systemc_ directives. Also
3248 set for all modules when using the --public switch.
3249 Same as "public" in configuration files, see "CONFIGURATION FILES"
3251 for more information.
3252 /*verilator sc_clock*/
3254 Deprecated and ignored. Previously used after an input declaration
3255 to indicate the signal should be declared in SystemC as a sc_clock
3256 instead of a bool. This was needed in SystemC 1.1 and 1.2 only;
3257 versions 2.0 and later do not require clock pins to be sc_clocks
3258 and this is no longer needed and is ignored.
3259 /*verilator sc_bv*/
3261 Used after a port declaration. It sets the port to be of
3262 sc_bv<width> type, instead of bool, vluint32_t or vluint64_t. This
3263 may be useful if the port width is parameterized and the
3264 instantiating C++ code wants to always have a sc_bv so it can
3265 accept any width. In general you should avoid using this attribute
3266 when not necessary as with increasing usage of sc_bv the
3267 performance decreases significantly.
3268 Same as "sc_bv" in configuration files, see "CONFIGURATION FILES"
3270 for more information.
3271 /*verilator sformat*/
3273 Attached to the final argument of type "input string" of a function
3274 or task to indicate the function or task should pass all remaining
3275 arguments through $sformatf. This allows creation of DPI functions
3276 with $display like behavior. See the
3277 test_regress/t/t_dpi_display.v file for an example.
3278 Same as "sformat" in configuration files, see "CONFIGURATION FILES"
3280 for more information.
3281 /*verilator split_var*/
3283 Attached to a variable or a net declaration to break the variable
3284 into multiple pieces typically to resolve UNOPTFLAT performance
3285 issues. Typically the variables to attach this to are recommended
3286 by Verilator itself, see UNOPTFLAT below.
3287 For example, Verilator will internally convert a variable with the
3289 metacomment such as:
3290 logic [7:0] x [0:1] /*verilator split_var*/;
3292 To:
3294 logic [7:0] x__BRA__0__KET__ /*verilator split_var*/;
3296 logic [7:0] x__BRA__1__KET__ /*verilator split_var*/;
3297 Note that the generated packed variables retain the split_var
3299 metacomment because they may be split into further smaller pieces
3300 according to the access patterns.
3301 This only supports unpacked arrays, packed arrays, and packed
3303 structs of integer types (reg, logic, bit, byte, int...); otherwise
3304 if a split was requested but cannot occur a SPLITVAR warning is
3305 issued. Splitting large arrays may slow down the Verilation speed,
3306 so use this only on variables that require it.
3307 Same as "split_var" in configuration files, see "CONFIGURATION
3309 FILES" for more information.
3310 /*verilator tag <text...>*/
3312 Attached after a variable or structure member to indicate opaque
3313 (to Verilator) text that should be passed through to the XML output
3314 as a tag, for use by downstream applications.
3315 /*verilator tracing_off*/
3317 Disable waveform tracing for all future signals that are declared
3318 in this module, or instances below this module. Often this is
3319 placed just after a primitive's module statement, so that the
3320 entire module and instances below it are not traced.
3321 /*verilator tracing_on*/
3323 Re-enable waveform tracing for all future signals or instances that
3324 are declared.
3325
3327 There are some limitations and lack of features relative to the major
3328 closed-source simulators, by intent.
3329 Synthesis Subset
3331 Verilator supports the Synthesis subset with other verification
3332 constructs being added over time. Verilator also simulates events as
3333 Synopsys's Design Compiler would; namely given a block of the form:
3334 always @ (x) y = x & z;
3336 This will recompute y when there is even a potential for change in x or
3338 a change in z, that is when the flops computing x or z evaluate (which
3339 is what Design Compiler will synthesize.) A compliant simulator would
3340 only calculate y if x changes. We recommend using always_comb to make
3341 the code run the same everywhere. Also avoid putting $displays in
3342 combo blocks, as they may print multiple times when not desired, even
3343 on compliant simulators as event ordering is not specified.
3344 Signal Naming
3346 To avoid conflicts with C symbol naming, any character in a signal name
3347 that is not alphanumeric nor a single underscore will be replaced by
3348 __0hh where hh is the hex code of the character. To avoid conflicts
3349 with Verilator's internal symbols, any double underscore are replaced
3350 with ___05F (5F is the hex code of an underscore.)
3351 Bind
3353 Verilator only supports "bind" to a target module name, not an instance
3354 path.
3355 Class
3357 Verilator class support is limited but in active development.
3358 Verilator supports members, and methods. Verilator does not support
3359 class static members, class extend, or class parameters.
3360 Dotted cross-hierarchy references
3362 Verilator supports dotted references to variables, functions and tasks
3363 in different modules. The portion before the dot must have a constant
3364 value; for example a[2].b is acceptable, while a[x].b is generally not.
3365 References into generated and arrayed instances use the instance names
3367 specified in the Verilog standard; arrayed instances are named
3368 {instanceName}[{instanceNumber}] in Verilog, which becomes
3369 {instanceName}__BRA__{instanceNumber}__KET__ inside the generated C++
3370 code.
3371 Latches
3373 Verilator is optimized for edge sensitive (flop based) designs. It
3374 will attempt to do the correct thing for latches, but most performance
3375 optimizations will be disabled around the latch.
3376 Structures and Unions
3378 Presently Verilator only supports packed structs and packed unions.
3379 Rand and randc tags on members are simply ignored. All structures and
3380 unions are represented as a single vector, which means that generating
3381 one member of a structure from blocking, and another from non-blocking
3382 assignments is unsupported.
3383 Time
3385 All delays (#) are ignored, as they are in synthesis.
3386 Unknown states
3388 Verilator is mostly a two state simulator, not a four state simulator.
3389 However, it has two features which uncover most initialization bugs
3390 (including many that a four state simulator will miss.)
3391 Identity comparisons (=== or !==) are converted to standard ==/!= when
3393 neither side is a constant. This may make the expression yield a
3394 different result compared to a four state simulator. An === comparison
3395 to X will always be false, so that Verilog code which checks for
3396 uninitialized logic will not fire.
3397 Assigning X to a variable will actually assign a constant value as
3399 determined by the --x-assign switch. This allows runtime
3400 randomization, thus if the value is actually used, the random value
3401 should cause downstream errors. Integers also get randomized, even
3402 though the Verilog 2001 specification says they initialize to zero.
3403 Note however that randomization happens at initialization time and
3404 hence during a single simulation run, the same constant (but random)
3405 value will be used every time the assignment is executed.
3406 All variables, depending on --x-initial setting, are typically randomly
3408 initialized using a function. By running several random simulation
3409 runs you can determine that reset is working correctly. On the first
3410 run, have the function initialize variables to zero. On the second,
3411 have it initialize variables to one. On the third and following runs
3412 have it initialize them randomly. If the results match, reset works.
3413 (Note this is what the hardware will really do.) In practice, just
3414 setting all variables to one at startup finds most problems (since
3415 typically control signals are active-high).
3416 --x-assign applies to variables explicitly initialized or assigned an
3418 X. Uninitialized clocks are initialized to zero, while all other state
3419 holding variables are initialized to a random value. Event driven
3420 simulators will generally trigger an edge on a transition from X to 1
3421 ("posedge") or X to 0 ("negedge"). However, by default, since clocks
3422 are initialized to zero, Verilator will not trigger an initial negedge.
3423 Some code (particularly for reset) may rely on X->0 triggering an edge.
3424 The --x-initial-edge switch enables this behavior. Comparing runs with
3425 and without this switch will find such problems.
3426 Tri/Inout
3428 Verilator converts some simple tristate structures into two state.
3429 Pullup, pulldown, bufif0, bufif1, notif0, notif1, pmos, nmos, tri0 and
3430 tri1 are also supported. Simple comparisons with === 1'bz are also
3431 supported.
3432 An assignment of the form:
3434 inout driver;
3436 wire driver = (enable) ? output_value : 1'bz;
3437 Will be converted to
3439 input driver; // Value being driven in from "external" drivers
3441 output driver__en; // True if driven from this module
3442 output driver__out; // Value being driven from this module
3443 External logic will be needed to combine these signals with any
3445 external drivers.
3446 Tristate drivers are not supported inside functions and tasks; an inout
3448 there will be considered a two state variable that is read and written
3449 instead of a four state variable.
3450 Functions & Tasks
3452 All functions and tasks will be inlined (will not become functions in
3453 C.) The only support provided is for simple statements in tasks (which
3454 may affect global variables).
3455 Recursive functions and tasks are not supported. All inputs and
3457 outputs are automatic, as if they had the Verilog 2001 "automatic"
3458 keyword prepended. (If you don't know what this means, Verilator will
3459 do what you probably expect -- what C does. The default behavior of
3460 Verilog is different.)
3461 Generated Clocks
3463 Verilator attempts to deal with generated and gated clocks correctly,
3464 however some cases cause problems in the scheduling algorithm which is
3465 optimized for performance. The safest option is to have all clocks as
3466 primary inputs to the model, or wires directly attached to primary
3467 inputs. For proper behavior clock enables may also need the
3468 /*verilator clock_enable*/ attribute.
3469 Gate Primitives
3471 The 2-state gate primitives (and, buf, nand, nor, not, or, xnor, xor)
3472 are directly converted to behavioral equivalents. The 3-state and MOS
3473 gate primitives are not supported. Tables are not supported.
3474 Specify blocks
3476 All specify blocks and timing checks are ignored. All min:typ:max
3477 delays use the typical value.
3478 Array Initialization
3480 When initializing a large array, you need to use non-delayed
3481 assignments. Verilator will tell you when this needs to be fixed; see
3482 the BLKLOOPINIT error for more information.
3483 Array Out of Bounds
3485 Writing a memory element that is outside the bounds specified for the
3486 array may cause a different memory element inside the array to be
3487 written instead. For power-of-2 sized arrays, Verilator will give a
3488 width warning and the address. For non-power-of-2-sizes arrays, index
3489 0 will be written.
3490 Reading a memory element that is outside the bounds specified for the
3492 array will give a width warning and wrap around the power-of-2 size.
3493 For non-power-of-2 sizes, it will return a unspecified constant of the
3494 appropriate width.
3495 Assertions
3497 Verilator is beginning to add support for assertions. Verilator
3498 currently only converts assertions to simple "if (...) error"
3499 statements, and coverage statements to increment the line counters
3500 described in the coverage section.
3501 Verilator does not support SEREs yet. All assertion and coverage
3503 statements must be simple expressions that complete in one cycle.
3504 Encrypted Verilog
3506 Open source simulators like Verilator are unable to use encrypted RTL
3507 (i.e. IEEE P1735). Talk to your IP vendor about delivering IP blocks
3508 via Verilator's --protect-lib feature.
3509 Language Keyword Limitations
3511 This section describes specific limitations for each language keyword.
3512 `__FILE__, `__LINE__, `begin_keywords, `begin_keywords,
3514 `begin_keywords, `begin_keywords, `begin_keywords, `define, `else,
3515 `elsif, `end_keywords, `endif, `error, `ifdef, `ifndef, `include,
3516 `line, `systemc_ctor, `systemc_dtor, `systemc_header,
3517 `systemc_imp_header, `systemc_implementation, `systemc_interface,
3518 `undef, `verilog
3519 Fully supported.
3520 always, always_comb, always_ff, always_latch, and, assign, begin, buf,
3522 byte, case, casex, casez, default, defparam, do-while, else, end,
3523 endcase, endfunction, endgenerate, endmodule, endspecify, endtask,
3524 final, for, function, generate, genvar, if, initial, inout, input, int,
3525 integer, localparam, logic, longint, macromodule, module, nand,
3526 negedge, nor, not, or, output, parameter, posedge, reg, scalared,
3527 shortint, signed, supply0, supply1, task, time, tri, typedef, var,
3528 vectored, while, wire, xnor, xor
3529 Generally supported.
3530 ++, -- operators
3532 Increment/decrement can only be used as standalone statements or in
3533 certain limited cases.
3534 '{} operator
3536 Assignment patterns with order based, default, constant integer
3537 (array) or member identifier (struct/union) keys are supported.
3538 Data type keys and keys which are computed from a constant
3539 expression are not supported.
3540 `uselib
3542 Uselib, a vendor specific library specification method, is ignored
3543 along with anything following it until the end of that line.
3544 cast operator
3546 Casting is supported only between simple scalar types, signed and
3547 unsigned, not arrays nor structs.
3548 chandle
3550 Treated as a "longint"; does not yet warn about operations that are
3551 specified as illegal on chandles.
3552 disable
3554 Disable statements may be used only if the block being disabled is
3555 a block the disable statement itself is inside. This was commonly
3556 used to provide loop break and continue functionality before
3557 SystemVerilog added the break and continue keywords.
3558 inside
3560 Inside expressions may not include unpacked array traversal or $ as
3561 an upper bound. Case inside and case matches are also unsupported.
3562 interface
3564 Interfaces and modports, including with generated data types are
3565 supported. Generate blocks around modports are not supported, nor
3566 are virtual interfaces nor unnamed interfaces.
3567 shortreal
3569 Short floating point (shortreal) numbers are converted to real.
3570 Most other simulators either do not support float, or convert
3571 likewise.
3572 specify specparam
3574 All specify blocks and timing checks are ignored.
3575 uwire
3577 Verilator does not perform warning checking on uwires, it treats
3578 the uwire keyword as if it were the normal wire keyword.
3579 $bits, $countbits, $countones, $error, $fatal, $finish, $info,
3581 $isunknown, $onehot, $onehot0, $readmemb, $readmemh, $signed, $stime,
3582 $stop, $time, $unsigned, $warning.
3583 Generally supported.
3584 $dump/$dumpports and related
3586 $dumpfile or $dumpports will create a VCD or FST file (which is
3587 based on the --trace argument given when the model was Verilated).
3588 This will take effect starting at the next eval() call. If you
3589 have multiple Verilated designs under the same C model, then this
3590 will dump signals only from the design containing the $dumpvars.
3591 $dumpvars and $dumpports module identifier is ignored; the traced
3593 instances will always start at the top of the design. The levels
3594 argument is also ignored, use tracing_on/tracing_off pragmas
3595 instead.
3596 $dumpportson/$dumpportsoff/$dumpportsall/$dumpportslimit filename
3598 argument is ignored, only a single trace file may be active at
3599 once.
3600 $dumpall/$dumpportsall, $dumpon/$dumpportson,
3602 $dumpoff/$dumpportsoff, and $dumplimit/$dumpportlimit are currently
3603 ignored.
3604 $exit, $finish, $stop
3606 The rarely used optional parameter to $finish and $stop is ignored.
3607 $exit is aliased to $finish.
3608 $fopen, $fclose, $fdisplay, $ferror, $feof, $fflush, $fgetc, $fgets,
3610 $fscanf, $fwrite, $fscanf, $sscanf
3611 Generally supported.
3612 $fullskew, $hold, $nochange, $period, $recovery, $recrem, $removal,
3614 $setup, $setuphold, $skew, $timeskew, $width
3615 All specify blocks and timing checks are ignored.
3616 $random, $urandom, $urandom_range
3618 Use +verilator+seed argument to set the seed if there is no $random
3619 or $urandom optional argument to set the seed. There is one random
3620 seed per C thread, not per module for $random, nor per object for
3621 random stability of $urandom/$urandom_range.
3622 $readmemb, $readmemh
3624 Read memory commands should work properly. Note Verilator and the
3625 Verilog specification does not include support for readmem to
3626 multi-dimensional arrays.
3627 $test$plusargs, $value$plusargs
3629 Supported, but the instantiating C++/SystemC testbench must call
3630 Verilated::commandArgs(argc, argv);
3632 to register the command line before calling $test$plusargs or
3634 $value$plusargs.
3635
3637 Warnings may be disabled in three ways. First, when the warning is
3638 printed it will include a warning code. Simply surround the offending
3639 line with a lint_off/lint_on pair:
3640 // verilator lint_off UNSIGNED
3642 if (`DEF_THAT_IS_EQ_ZERO <= 3) $stop;
3643 // verilator lint_on UNSIGNED
3644 Second, warnings may be disabled using a configuration file with a
3646 lint_off command. This is useful when a script is suppressing warnings
3647 and the Verilog source should not be changed.
3648 Warnings may also be globally disabled by invoking Verilator with the
3650 "-Wno-warning" switch. This should be avoided, as it removes all
3651 checking across the designs, and prevents other users from compiling
3652 your code without knowing the magic set of disables needed to
3653 successfully compile your design.
3654 Error and Warning Format
3656 Warnings and errors printed by Verilator always match this regular
3657 expression:
3658 %(Error|Warning)(-[A-Z0-9_]+)?: ((\S+):(\d+):((\d+):)? )?.*
3660 Errors and warning start with a percent sign (historical heritage from
3662 Digital Equipment Corporation). Some errors or warning have a code
3663 attached, with meanings described below. Some errors also have a
3664 filename, line number and optional column number (starting at column 1
3665 to match GCC).
3666 Following the error message, Verilator will typically show the user's
3668 source code corresponding to the error, prefixed by the line number and
3669 a " | ". Following this is typically an arrow and ~ pointing at the
3670 error on the source line directly above.
3671 List of all warnings
3673 ALWCOMBORDER
3674 Warns that an always_comb block has a variable which is set after
3675 it is used. This may cause simulation-synthesis mismatches, as not
3676 all simulators allow this ordering.
3677 always_comb begin
3679 a = b;
3680 b = 1;
3681 end
3682 Ignoring this warning will only suppress the lint check, it will
3684 simulate correctly.
3685 ASSIGNIN
3687 Error that an assignment is being made to an input signal. This is
3688 almost certainly a mistake, though technically legal.
3689 input a;
3691 assign a = 1'b1;
3692 Ignoring this warning will only suppress the lint check, it will
3694 simulate correctly.
3695 ASSIGNDLY
3697 Warns that you have an assignment statement with a delayed time in
3698 front of it, for example:
3699 a <= #100 b;
3701 assign #100 a = b;
3702 Ignoring this warning may make Verilator simulations differ from
3704 other simulators, however at one point this was a common style so
3705 disabled by default as a code style warning.
3706 BLKANDNBLK
3708 BLKANDNBLK is an error that a variable comes from a mix of blocking
3709 and non-blocking assignments.
3710 This is not illegal in SystemVerilog, but a violation of good
3712 coding practice. Verilator reports this as an error, because
3713 ignoring this warning may make Verilator simulations differ from
3714 other simulators.
3715 It is generally safe to disable this error (with a "// verilator
3717 lint_off BLKANDNBLK" metacomment or the -Wno-BLKANDNBLK option)
3718 when one of the assignments is inside a public task, or when the
3719 blocking and non-blocking assignments have non-overlapping bits and
3720 structure members.
3721 Generally, this is caused by a register driven by both combo logic
3723 and a flop:
3724 logic [1:0] foo;
3726 always @ (posedge clk) foo[0] <= ...
3727 always @* foo[1] = ...
3728 Simply use a different register for the flop:
3730 logic [1:0] foo;
3732 always @ (posedge clk) foo_flopped[0] <= ...
3733 always @* foo[0] = foo_flopped[0];
3734 always @* foo[1] = ...
3735 Or, this may also avoid the error:
3737 logic [1:0] foo /*verilator split_var*/;
3739 BLKSEQ
3741 This indicates that a blocking assignment (=) is used in a
3742 sequential block. Generally non-blocking/delayed assignments (<=)
3743 are used in sequential blocks, to avoid the possibility of
3744 simulator races. It can be reasonable to do this if the generated
3745 signal is used ONLY later in the same block, however this style is
3746 generally discouraged as it is error prone.
3747 always @ (posedge clk) foo = ...
3749 Disabled by default as this is a code style warning; it will
3751 simulate correctly.
3752 BLKLOOPINIT
3754 This indicates that the initialization of an array needs to use
3755 non-delayed assignments. This is done in the interest of speed; if
3756 delayed assignments were used, the simulator would have to copy
3757 large arrays every cycle. (In smaller loops, loop unrolling allows
3758 the delayed assignment to work, though it's a bit slower than a
3759 non-delayed assignment.) Here's an example
3760 always @ (posedge clk)
3762 if (~reset_l) begin
3763 for (i=0; i<`ARRAY_SIZE; i++) begin
3764 array[i] = 0; // Non-delayed for verilator
3765 end
3766 This message is only seen on large or complicated loops because
3768 Verilator generally unrolls small loops. You may want to try
3769 increasing --unroll-count (and occasionally --unroll-stmts) which
3770 will raise the small loop bar to avoid this error.
3771 BOUNDED
3773 This indicates that bounded queues (e.g. "var name[$ : 3]") are
3774 unsupported.
3775 Ignoring this warning may make Verilator simulations differ from
3777 other simulators.
3778 BSSPACE
3780 Warns that a backslash is followed by a space then a newline.
3781 Likely the intent was to have a backslash directly followed by a
3782 newline (e.g. when making a `define) and there's accidentally white
3783 space at the end of the line. If the space is not accidental,
3784 suggest removing the backslash in the code as it serves no
3785 function.
3786 Ignoring this warning will only suppress the lint check, it will
3788 simulate correctly.
3789 CASEINCOMPLETE
3791 Warns that inside a case statement there is a stimulus pattern for
3792 which there is no case item specified. This is bad style, if a
3793 case is impossible, it's better to have a "default: $stop;" or just
3794 "default: ;" so that any design assumption violations will be
3795 discovered in simulation.
3796 Ignoring this warning will only suppress the lint check, it will
3798 simulate correctly.
3799 CASEOVERLAP
3801 Warns that inside a case statement you have case values which are
3802 detected to be overlapping. This is bad style, as moving the order
3803 of case values will cause different behavior. Generally the values
3804 can be respecified to not overlap.
3805 Ignoring this warning will only suppress the lint check, it will
3807 simulate correctly.
3808 CASEWITHX
3810 Warns that a case statement contains a constant with a "x".
3811 Verilator is two-state so interpret such items as always false.
3812 Note a common error is to use a "X" in a case or casez statement
3813 item; often what the user instead intended is to use a casez with
3814 "?".
3815 Ignoring this warning will only suppress the lint check, it will
3817 simulate correctly.
3818 CASEX
3820 Warns that it is simply better style to use casez, and "?" in place
3821 of "x"'s. See
3822 <http://www.sunburst-design.com/papers/CummingsSNUG1999Boston_FullParallelCase_rev1_1.pdf>
3823 Ignoring this warning will only suppress the lint check, it will
3825 simulate correctly.
3826 CASTCONST
3828 Warns that a dynamic cast ($cast) is unnecessary as the $cast will
3829 always succeed or fail. If it will always fail, the $cast is
3830 useless. If it will always succeed a static cast may be preferred.
3831 Ignoring this warning will only suppress the lint check, it will
3833 simulate correctly. On other simulators, not fixing CASTCONST may
3834 result in decreased performance.
3835 CDCRSTLOGIC
3837 With --cdc only, warns that asynchronous flop reset terms come from
3838 other than primary inputs or flopped outputs, creating the
3839 potential for reset glitches.
3840 CLKDATA
3842 Warns that clock signal is mixed used with/as data signal. The
3843 checking for this warning is enabled only if user has explicitly
3844 marked some signal as clocker using command line option or in-
3845 source meta comment (see "--clk").
3846 The warning can be disabled without affecting the simulation
3848 result. But it is recommended to check the warning as this may
3849 degrade the performance of the Verilated model.
3850 CMPCONST
3852 Warns that you are comparing a value in a way that will always be
3853 constant. For example "X > 1" will always be true when X is a
3854 single bit wide.
3855 Ignoring this warning will only suppress the lint check, it will
3857 simulate correctly.
3858 COLONPLUS
3860 Warns that a :+ is seen. Likely the intent was to use +: to select
3861 a range of bits. If the intent was a range that is explicitly
3862 positive, suggest adding a space, e.g. use ": +".
3863 Ignoring this warning will only suppress the lint check, it will
3865 simulate correctly.
3866 COMBDLY
3868 Warns that you have a delayed assignment inside of a combinatorial
3869 block. Using delayed assignments in this way is considered bad
3870 form, and may lead to the simulator not matching synthesis. If
3871 this message is suppressed, Verilator, like synthesis, will convert
3872 this to a non-delayed assignment, which may result in logic races
3873 or other nasties. See
3874 <http://www.sunburst-design.com/papers/CummingsSNUG2000SJ_NBA_rev1_2.pdf>
3875 Ignoring this warning may make Verilator simulations differ from
3877 other simulators.
3878 CONTASSREG
3880 Error that a continuous assignment is setting a reg. According to
3881 IEEE Verilog, but not SystemVerilog, a wire must be used as the
3882 target of continuous assignments.
3883 This error is only reported when "--language 1364-1995",
3885 "--language 1364-2001", or "--language 1364-2005" is used.
3886 Ignoring this error will only suppress the lint check, it will
3888 simulate correctly.
3889 DECLFILENAME
3891 Warns that a module or other declaration's name doesn't match the
3892 filename with path and extension stripped that it is declared in.
3893 The filename a modules/interfaces/programs is declared in should
3894 match the name of the module etc. so that -y directory searching
3895 will work. This warning is printed for only the first mismatching
3896 module in any given file, and -v library files are ignored.
3897 Disabled by default as this is a code style warning; it will
3899 simulate correctly.
3900 DEFPARAM
3902 Warns that the "defparam" statement was deprecated in Verilog 2001
3903 and all designs should now be using the #(...) format to specify
3904 parameters.
3905 Disabled by default as this is a code style warning; it will
3907 simulate correctly.
3908 DETECTARRAY
3910 Error when Verilator tries to deal with a combinatorial loop that
3911 could not be flattened, and which involves a datatype which
3912 Verilator cannot handle, such as an unpacked struct or a large
3913 unpacked array. This typically occurs when -Wno-UNOPTFLAT has been
3914 used to override an UNOPTFLAT warning (see below).
3915 The solution is to break the loop, as described for UNOPTFLAT.
3917 DIDNOTCONVERGE
3919 Error at simulation runtime when model did not properly settle.
3920 Verilator sometimes has to evaluate combinatorial logic multiple
3922 times, usually around code where a UNOPTFLAT warning was issued,
3923 but disabled. For example:
3924 always_comb b = ~a;
3926 always_comb a = b
3927 This code will toggle forever, and thus to prevent an infinite
3929 loop, the executable will give the didn't converge error.
3930 To debug this, first review any UNOPTFLAT warnings that were
3932 ignored. Though typically it is safe to ignore UNOPTFLAT (at a
3933 performance cost), at the time of issuing a UNOPTFLAT Verilator did
3934 not know if the logic would eventually converge and assumed it
3935 would.
3936 Next, run Verilator with --prof-cfuncs. Run make on the generated
3938 files with "CPP_FLAGS=-DVL_DEBUG", to allow enabling simulation
3939 runtime debug messages. Rerun the test. Now just before the
3940 convergence error you should see additional output similar to this:
3941 CHANGE: filename.v:1: b
3943 CHANGE: filename.v:2: a
3944 This means that signal b and signal a keep changing, inspect the
3946 code that modifies these signals. Note if many signals are getting
3947 printed then most likely all of them are oscillating. It may also
3948 be that e.g. "a" may be oscillating, then "a" feeds signal "c"
3949 which then is also reported as oscillating.
3950 Finally, rare, more difficult cases can be debugged like a "C"
3952 program; either enter GDB and use its tracing facilities, or edit
3953 the generated C++ code to add appropriate prints to see what is
3954 going on.
3955 ENDLABEL
3957 Warns that a label attached to a "end"-something statement does not
3958 match the label attached to the block start.
3959 Ignoring this warning will only suppress the lint check, it will
3961 simulate correctly.
3962 GENCLK
3964 Deprecated and no longer used as a warning. Used to indicate that
3965 the specified signal was is generated inside the model, and also
3966 being used as a clock.
3967 HIERBLOCK
3969 Warns that the top module is marked as a hierarchy block by
3970 hier_block metacomment, which is not legal. This setting on the
3971 top module will be ignored. =item IFDEPTH
3972 Warns that if/if else statements have exceeded the depth specified
3974 with --if-depth, as they are likely to result in slow priority
3975 encoders. Statements below unique and priority if statements are
3976 ignored. Solutions include changing the code to a case statement,
3977 or a SystemVerilog 'unique if' or 'priority if'.
3978 Disabled by default as this is a code style warning; it will
3980 simulate correctly.
3981 IGNOREDRETURN
3983 Warns that a non-void function is being called as a task, and hence
3984 the return value is being ignored.
3985 This warning is required by IEEE. The portable way to suppress this
3987 warning (in SystemVerilog) is to use a void cast, e.g.
3988 void'(function_being_called_as_task());
3990 Ignoring this warning will only suppress the lint check, it will
3992 simulate correctly.
3993 IMPERFECTSCH
3995 Warns that the scheduling of the model is not absolutely perfect,
3996 and some manual code edits may result in faster performance. This
3997 warning defaults to off, is not part of -Wall, and must be turned
3998 on explicitly before the top module statement is processed.
3999 IMPLICIT
4001 Warns that a wire is being implicitly declared (it is a single bit
4002 wide output from a sub-module.) While legal in Verilog, implicit
4003 declarations only work for single bit wide signals (not buses), do
4004 not allow using a signal before it is implicitly declared by an
4005 instance, and can lead to dangling nets. A better option is the
4006 /*AUTOWIRE*/ feature of Verilog-Mode for Emacs, available from
4007 <https://www.veripool.org/verilog-mode>
4008 Ignoring this warning will only suppress the lint check, it will
4010 simulate correctly.
4011 IMPORTSTAR
4013 Warns that an "import package::*" statement is in $unit scope. This
4014 causes the imported symbols to pollute the global namespace,
4015 defeating much of the purpose of having a package. Generally
4016 "import ::*" should only be used inside a lower scope such as a
4017 package or module.
4018 Disabled by default as this is a code style warning; it will
4020 simulate correctly.
4021 IMPURE
4023 Warns that a task or function that has been marked with /*verilator
4024 no_inline_task*/ references variables that are not local to the
4025 task. Verilator cannot schedule these variables correctly.
4026 Ignoring this warning may make Verilator simulations differ from
4028 other simulators.
4029 INCABSPATH
4031 Warns that an `include filename specifies an absolute path. This
4032 means the code will not work on any other system with a different
4033 file system layout. Instead of using absolute paths, relative
4034 paths (preferably without any directory specified whatsoever)
4035 should be used, and +incdir used on the command line to specify the
4036 top include source directories.
4037 Disabled by default as this is a code style warning; it will
4039 simulate correctly.
4040 INFINITELOOP
4042 Warns that a while or for statement has a condition that is always
4043 true. and thus results in an infinite loop if the statement ever
4044 executes.
4045 This might be unintended behavior if the loop body contains
4047 statements that in other simulators would make time pass, which
4048 Verilator is ignoring due to e.g. STMTDLY warnings being disabled.
4049 Ignoring this warning will only suppress the lint check, it will
4051 simulate correctly (i.e. hang due to the infinite loop).
4052 INITIALDLY
4054 Warns that you have a delayed assignment inside of an initial or
4055 final block. If this message is suppressed, Verilator will convert
4056 this to a non-delayed assignment. See also the COMBDLY warning.
4057 Ignoring this warning may make Verilator simulations differ from
4059 other simulators.
4060 INSECURE
4062 Warns that the combination of options selected may be defeating the
4063 attempt to protect/obscure identifiers or hide information in the
4064 model. Correct the options provided, or inspect the output code to
4065 see if the information exposed is acceptable.
4066 Ignoring this warning will only suppress the lint check, it will
4068 simulate correctly.
4069 LATCH
4071 Warns that a signal is not assigned in all control paths of a
4072 combinational always block, resulting in the inference of a latch.
4073 For intentional latches, consider using the always_latch
4074 (SystemVerilog) keyword instead. The warning may be disabled with
4075 a lint_off pragma around the always block.
4076 Ignoring this warning will only suppress the lint check, it will
4078 simulate correctly.
4079 LITENDIAN
4081 Warns that a packed vector is declared with little endian bit
4082 numbering (i.e. [0:7]). Big endian bit numbering is now the
4083 overwhelming standard, and little numbering is now thus often due
4084 to simple oversight instead of intent.
4085 Also warns that an instance is declared with little endian range
4087 (i.e. [0:7] or [7]) and is connected to a N-wide signal. Based on
4088 IEEE the bits will likely be backwards from what you expect (i.e.
4089 instance [0] will connect to signal bit [N-1] not bit [0]).
4090 Ignoring this warning will only suppress the lint check, it will
4092 simulate correctly.
4093 MODDUP
4095 Warns that a module has multiple definitions. Generally this
4096 indicates a coding error, or a mistake in a library file and it's
4097 good practice to have one module per file (and only put each file
4098 once on the command line) to avoid these issues. For some gate
4099 level netlists duplicates are sometimes unavoidable, and MODDUP
4100 should be disabled.
4101 Ignoring this warning will cause the more recent module definition
4103 to be discarded.
4104 MULTIDRIVEN
4106 Warns that the specified signal comes from multiple always blocks.
4107 This is often unsupported by synthesis tools, and is considered bad
4108 style. It will also cause longer simulation runtimes due to
4109 reduced optimizations.
4110 Ignoring this warning will only slow simulations, it will simulate
4112 correctly.
4113 MULTITOP
4115 Warns that there are multiple top level modules, that is modules
4116 not instantiated by any other module, and both modules were put on
4117 the command line (not in a library). Three likely cases:
4118 1. A single module is intended to be the top. This warning then
4120 occurs because some low level instance is being read in, but is not
4121 really needed as part of the design. The best solution for this
4122 situation is to ensure that only the top module is put on the
4123 command line without any flags, and all remaining library files are
4124 read in as libraries with -v, or are automatically resolved by
4125 having filenames that match the module names.
4126 2. A single module is intended to be the top, the name of it is
4128 known, and all other modules should be ignored if not part of the
4129 design. The best solution is to use the --top option to specify
4130 the top module's name. All other modules that are not part of the
4131 design will be for the most part ignored (they must be clean in
4132 syntax and their contents will be removed as part of the Verilog
4133 module elaboration process.)
4134 3. Multiple modules are intended to be design tops, e.g. when
4136 linting a library file. As multiple modules are desired, disable
4137 the MULTITOP warning. All input/outputs will go uniquely to each
4138 module, with any conflicting and identical signal names being made
4139 unique by adding a prefix based on the top module name followed by
4140 __02E (a Verilator-encoded ASCII ".'). This renaming is done even
4141 if the two modules' signals seem identical, e.g. multiple modules
4142 with a "clk" input.
4143 NOLATCH
4145 Warns that no latch was detected in an always_latch block. The
4146 warning may be disabled with a lint_off pragma around the always
4147 block, but recoding using a regular always may be more appropriate.
4148 Ignoring this warning will only suppress the lint check, it will
4150 simulate correctly.
4151 PINCONNECTEMPTY
4153 Warns that an instance has a pin which is connected to .pin_name(),
4154 e.g. not another signal, but with an explicit mention of the pin.
4155 It may be desirable to disable PINCONNECTEMPTY, as this indicates
4156 intention to have a no-connect.
4157 Disabled by default as this is a code style warning; it will
4159 simulate correctly.
4160 PINMISSING
4162 Warns that a module has a pin which is not mentioned in an
4163 instance. If a pin is not missing it should still be specified on
4164 the instance declaration with a empty connection, using
4165 "(.pin_name())".
4166 Ignoring this warning will only suppress the lint check, it will
4168 simulate correctly.
4169 PINNOCONNECT
4171 Warns that an instance has a pin which is not connected to another
4172 signal.
4173 Disabled by default as this is a code style warning; it will
4175 simulate correctly.
4176 PKGNODECL
4178 Error that a package/class appears to have been referenced that has
4179 not yet been declared. According to IEEE 1800-2017 26.3 all
4180 packages must be declared before being used.
4181 PROCASSWIRE
4183 Error that a procedural assignment is setting a wire. According to
4184 IEEE, a var/reg must be used as the target of procedural
4185 assignments.
4186 RANDC
4188 Warns that the 'randc' keyword is currently unsupported, and that
4189 it is being converted to 'rand'.
4190 REALCVT
4192 Warns that a real number is being implicitly rounded to an integer,
4193 with possible loss of precision.
4194 REDEFMACRO
4196 Warns that you have redefined the same macro with a different
4197 value, for example:
4198 `define MACRO def1
4200 //...
4201 `define MACRO otherdef
4202 The best solution is to use a different name for the second macro.
4204 If this is not possible, add a undef to indicate the code is
4205 overriding the value:
4206 `define MACRO def1
4208 //...
4209 `undef MACRO
4210 `define MACRO otherdef
4211 SELRANGE
4213 Warns that a selection index will go out of bounds:
4214 wire vec[6:0];
4216 initial out = vec[7]; // There is no 7
4217 Verilator will assume zero for this value, instead of X. Note that
4219 in some cases this warning may be false, when a condition upstream
4220 or downstream of the access means the access out of bounds will
4221 never execute or be used.
4222 wire vec[6:0];
4224 initial begin
4225 seven = 7;
4226 ...
4227 if (seven != 7) out = vec[seven]; // Never will use vec[7]
4228 SHORTREAL
4230 Warns that Verilator does not support "shortreal" and they will be
4231 automatically promoted to "real". The recommendation is to replace
4232 any "shortreal" in the code with "real", as "shortreal" is not
4233 widely supported across industry tools.
4234 Ignoring this warning may make Verilator simulations differ from
4236 other simulators, if the increased precision of real affects your
4237 model or DPI calls.
4238 SPLITVAR
4240 Warns that a variable with a "split_var" metacomment was not split.
4241 Some possible reasons for this are:
4242 * The datatype of the variable is not supported for splitting.
4244 (e.g. is a real).
4245 * The access pattern of the variable can not be determined
4247 statically. (e.g. is accessed as a memory).
4248 * The index of the array exceeds the array size.
4250 * The variable is accessed from outside using dotted reference.
4252 (e.g. top.instance0.variable0 = 1).
4253 * The variable is not declared in a module, but in a package or an
4255 interface.
4256 * The variable is a parameter, localparam, genvar, or queue.
4258 * The variable is tristate or bidirectional. (e.g. inout or ref).
4260 STMTDLY
4262 Warns that you have a statement with a delayed time in front of it,
4263 for example:
4264 #100 $finish;
4266 Ignoring this warning may make Verilator simulations differ from
4268 other simulators.
4269 SYMRSVDWORD
4271 Warning that a symbol matches a C++ reserved word and using this as
4272 a symbol name would result in odd C++ compiler errors. You may
4273 disable this warning, but the symbol will be renamed by Verilator
4274 to avoid the conflict.
4275 SYNCASYNCNET
4277 Warns that the specified net is used in at least two different
4278 always statements with posedge/negedges (i.e. a flop). One usage
4279 has the signal in the sensitivity list and body, probably as an
4280 async reset, and the other usage has the signal only in the body,
4281 probably as a sync reset. Mixing sync and async resets is usually
4282 a mistake. The warning may be disabled with a lint_off pragma
4283 around the net, or either flopped block.
4284 Disabled by default as this is a code style warning; it will
4286 simulate correctly.
4287 TASKNSVAR
4289 Error when a call to a task or function has an inout from that task
4290 tied to a non-simple signal. Instead connect the task output to a
4291 temporary signal of the appropriate width, and use that signal to
4292 set the appropriate expression as the next statement. For example:
4293 task foo(inout sig); ... endtask
4295 always @* begin
4296 foo(bus_we_select_from[2]); // Will get TASKNSVAR error
4297 end
4298 Change this to:
4300 reg foo_temp_out;
4302 always @* begin
4303 foo(foo_temp_out);
4304 bus_we_select_from[2] = foo_temp_out;
4305 end
4306 Verilator doesn't do this conversion for you, as some more
4308 complicated cases would result in simulator mismatches.
4309 TICKCOUNT
4311 Warns that the number of ticks to delay a $past variable is greater
4312 than 10. At present Verilator effectively creates a flop for each
4313 delayed signals, and as such any large counts may lead to large
4314 design size increases.
4315 Ignoring this warning will only slow simulations, it will simulate
4317 correctly.
4318 TIMESCALEMOD
4320 Error that `timescale is used in some but not all modules.
4321 Recommend using --timescale argument, or in front of all modules
4322 use:
4323 `include "timescale.vh"
4325 Then in that file set the timescale.
4327 This is an error due to IEEE specifications, but it may be disabled
4329 similar to warnings. Ignoring this error may result in a module
4330 having an unexpected timescale.
4331 UNDRIVEN
4333 Warns that the specified signal has no source. Verilator is fairly
4334 liberal in the usage calculations; making a signal public, or
4335 setting only a single array element marks the entire signal as
4336 driven.
4337 Disabled by default as this is a code style warning; it will
4339 simulate correctly.
4340 UNOPT
4342 Warns that due to some construct, optimization of the specified
4343 signal or block is disabled. The construct should be cleaned up to
4344 improve simulation performance.
4345 A less obvious case of this is when a module instantiates two
4347 submodules. Inside submodule A, signal I is input and signal O is
4348 output. Likewise in submodule B, signal O is an input and I is an
4349 output. A loop exists and a UNOPT warning will result if AI & AO
4350 both come from and go to combinatorial blocks in both submodules,
4351 even if they are unrelated always blocks. This affects performance
4352 because Verilator would have to evaluate each submodule multiple
4353 times to stabilize the signals crossing between the modules.
4354 Ignoring this warning will only slow simulations, it will simulate
4356 correctly.
4357 UNOPTFLAT
4359 Warns that due to some construct, optimization of the specified
4360 signal is disabled. The signal reported includes a complete scope
4361 to the signal; it may be only one particular usage of a multiply
4362 instantiated block. The construct should be cleaned up to improve
4363 simulation performance; two times better performance may be
4364 possible by fixing these warnings.
4365 Unlike the UNOPT warning, this occurs after flattening the netlist,
4367 and indicates a more basic problem, as the less obvious case
4368 described under UNOPT does not apply.
4369 Often UNOPTFLAT is caused by logic that isn't truly circular as
4371 viewed by synthesis which analyzes interconnection per-bit, but is
4372 circular to simulation which analyzes per-bus:
4373 wire [2:0] x = {x[1:0], shift_in};
4375 This statement needs to be evaluated multiple times, as a change in
4377 "shift_in" requires "x" to be computed 3 times before it becomes
4378 stable. This is because a change in "x" requires "x" itself to
4379 change value, which causes the warning.
4380 For significantly better performance, split this into 2 separate
4382 signals:
4383 wire [2:0] xout = {x[1:0], shift_in};
4385 and change all receiving logic to instead receive "xout".
4387 Alternatively, change it to
4388 wire [2:0] x = {xin[1:0], shift_in};
4390 and change all driving logic to instead drive "xin".
4392 With this change this assignment needs to be evaluated only once.
4394 These sort of changes may also speed up your traditional event
4395 driven simulator, as it will result in fewer events per cycle.
4396 The most complicated UNOPTFLAT path we've seen was due to low bits
4398 of a bus being generated from an always statement that consumed
4399 high bits of the same bus processed by another series of always
4400 blocks. The fix is the same; split it into two separate signals
4401 generated from each block.
4402 Another way to resolve this warning is to add a "split_var"
4404 metacomment described above. This will cause the variable to be
4405 split internally, potentially resolving the conflict. If you run
4406 with --report-unoptflat Verilator will suggest possible candidates
4407 for "split_var".
4408 The UNOPTFLAT warning may also be due to clock enables, identified
4410 from the reported path going through a clock gating instance. To
4411 fix these, use the clock_enable meta comment described above.
4412 The UNOPTFLAT warning may also occur where outputs from a block of
4414 logic are independent, but occur in the same always block. To fix
4415 this, use the isolate_assignments meta comment described above.
4416 To assist in resolving UNOPTFLAT, the option "--report-unoptflat"
4418 can be used, which will provide suggestions for variables that can
4419 be split up, and a graph of all the nodes connected in the loop.
4420 See the Arguments section for more details.
4421 Ignoring this warning will only slow simulations, it will simulate
4423 correctly.
4424 UNOPTTHREADS
4426 Warns that the thread scheduler was unable to partition the design
4427 to fill the requested number of threads.
4428 One workaround is to request fewer threads with "--threads".
4430 Another possible workaround is to allow more MTasks in the
4432 simulation runtime, by increasing the value of
4433 --threads-max-mtasks. More MTasks will result in more communication
4434 and synchronization overhead at simulation runtime; the scheduler
4435 attempts to minimize the number of MTasks for this reason.
4436 Ignoring this warning will only slow simulations, it will simulate
4438 correctly.
4439 UNPACKED
4441 Warns that unpacked structs and unions are not supported.
4442 Ignoring this warning will make Verilator treat the structure as
4444 packed, which may make Verilator simulations differ from other
4445 simulators. This downgrading may also result what would normally be
4446 a legal unpacked struct/array inside an unpacked struct/array
4447 becoming an illegal unpacked struct/array inside a packed
4448 struct/array.
4449 UNSIGNED
4451 Warns that you are comparing a unsigned value in a way that implies
4452 it is signed, for example "X < 0" will always be false when X is
4453 unsigned.
4454 Ignoring this warning will only suppress the lint check, it will
4456 simulate correctly.
4457 UNSUPPORTED
4459 UNSUPPORTED is an error that the construct might be legal according
4460 to IEEE but is not currently supported.
4461 This error may be ignored with --bbox-unsup, however this will make
4463 the design simulate incorrectly; see the details under
4464 --bbox-unsup.
4465 UNUSED
4467 Warns that the specified signal or parameter is never
4468 used/consumed. Verilator is fairly liberal in the usage
4469 calculations; making a signal public, a signal matching
4470 --unused-regexp ("*unused*") or accessing only a single array
4471 element marks the entire signal as used.
4472 Disabled by default as this is a code style warning; it will
4474 simulate correctly.
4475 A recommended style for unused nets is to put at the bottom of a
4477 file code similar to the following:
4478 wire _unused_ok = &{1'b0,
4480 sig_not_used_a,
4481 sig_not_used_yet_b, // To be fixed
4482 1'b0};
4483 The reduction AND and constant zeros mean the net will always be
4485 zero, so won't use simulation runtime. The redundant leading and
4486 trailing zeros avoid syntax errors if there are no signals between
4487 them. The magic name "unused" (-unused-regexp) is recognized by
4488 Verilator and suppresses warnings; if using other lint tools,
4489 either teach it to the tool to ignore signals with "unused" in the
4490 name, or put the appropriate lint_off around the wire. Having
4491 unused signals in one place makes it easy to find what is unused,
4492 and reduces the number of lint_off pragmas, reducing bugs.
4493 USERINFO, USERWARN, USERERROR, USERFATAL
4495 A SystemVerilog elaboration-time assertion print was executed.
4496 VARHIDDEN
4498 Warns that a task, function, or begin/end block is declaring a
4499 variable by the same name as a variable in the upper level module
4500 or begin/end block (thus hiding the upper variable from being able
4501 to be used.) Rename the variable to avoid confusion when reading
4502 the code.
4503 Disabled by default as this is a code style warning; it will
4505 simulate correctly.
4506 WIDTH
4508 Warns that based on width rules of Verilog, two operands have
4509 different widths. Verilator generally can intuit the common usages
4510 of widths, and you shouldn't need to disable this message like you
4511 do with most lint programs. Generally other than simple mistakes,
4512 you have two solutions:
4513 If it's a constant 0 that's 32 bits or less, simply leave it
4515 unwidthed. Verilator considers zero to be any width needed.
4516 Concatenate leading zeros when doing arithmetic. In the statement
4518 wire [5:0] plus_one = from[5:0] + 6'd1 + carry[0];
4520 The best fix, which clarifies intent and will also make all tools
4522 happy is:
4523 wire [5:0] plus_one = from[5:0] + 6'd1 + {5'd0, carry[0]};
4525 Ignoring this warning will only suppress the lint check, it will
4527 simulate correctly.
4528 WIDTHCONCAT
4530 Warns that based on width rules of Verilog, a concatenate or
4531 replication has an indeterminate width. In most cases this
4532 violates the Verilog rule that widths inside concatenates and
4533 replicates must be sized, and should be fixed in the code.
4534 wire [63:0] concat = {1, 2};
4536 An example where this is technically legal (though still bad form)
4538 is:
4539 parameter PAR = 1;
4541 wire [63:0] concat = {PAR, PAR};
4542 The correct fix is to either size the 1 ("32'h1"), or add the width
4544 to the parameter definition ("parameter [31:0]"), or add the width
4545 to the parameter usage ("{PAR[31:0],PAR[31:0]}".
4546 The following describes the less obvious errors:
4548 Internal Error
4550 This error should never occur first, though may occur if earlier
4551 warnings or error messages have corrupted the program. If there
4552 are no other warnings or errors, submit a bug report.
4553 Unsupported: ....
4555 This error indicates that you are using a Verilog language
4556 construct that is not yet supported in Verilator. See the
4557 Limitations chapter.
4558
4560 The following deprecated items are scheduled for future removal:
4561 C++11 compiler support
4563 Verilator currently requires C++11 or newer compilers. Verilator
4564 will require C++14 or newer compilers for both compiling Verilator
4565 and compiling Verilated models no sooner than January 2022.
4566 Configuration File -msg
4568 The -msg argument to lint_off has been replaced with -rule. -msg
4569 is planned for removal no sooner than January 2021.
4570 XML locations
4572 The XML "fl" attribute has been replaced with "loc". "fl" is
4573 planned for removal no sooner than January 2021.
4574
4576 Can I contribute?
4577 Please contribute! Just submit a pull request, or raise an issue
4578 to discuss if looking for something to help on. For more
4579 information see our contributor agreement.
4580 How widely is Verilator used?
4582 Verilator is used by many of the largest silicon design companies,
4583 and all the way down to college projects. Verilator is one of the
4584 "big 4" simulators, meaning one of the 4 main SystemVerilog
4585 simulators available, namely the commercial products Synopsys VCS
4586 (tm), Mentor Questa/ModelSim (tm), Cadence
4587 Xcelium/Incisive/NC-Verilog/NC-Sim (tm), and the open-source
4588 Verilator. The three commercial offerings are often collectively
4589 called the "big 3" simulators.
4590 Does Verilator run under Windows?
4592 Yes, using Cygwin. Verilated output also compiles under Microsoft
4593 Visual C++, but this is not tested every release.
4594 Can you provide binaries?
4596 You can install Verilator via the system package manager (apt, yum,
4597 etc.) on many Linux distributions, including Debian, Ubuntu, SuSE,
4598 Fedora, and others. These packages are provided by the Linux
4599 distributions and generally will lag the version of the mainline
4600 Verilator repository. If no binary package is available for your
4601 distribution, how about you set one up? Please contact the authors
4602 for assistance.
4603 How can it be faster than (name-a-big-3-closed-source-simulator)?
4605 Generally, the implied part of the question is "... with all of the
4606 manpower they can put into developing it."
4607 Most simulators have to be compliant with the complete IEEE 1364
4609 (Verilog) and IEEE 1800 (SystemVerilog) standards, meaning they
4610 have to be event driven. This prevents them from being able to
4611 reorder blocks and make netlist-style optimizations, which are
4612 where most of the gains come from.
4613 You should not be scared by non-compliance. Your synthesis tool
4615 isn't compliant with the whole standard to start with, so your
4616 simulator need not be either. Verilator is closer to the synthesis
4617 interpretation, so this is a good thing for getting working
4618 silicon.
4619 Will Verilator output remain under my own license?
4621 Yes, it's just like using GCC on your programs; this is why
4622 Verilator uses the "GNU *Lesser* Public License Version 3" instead
4623 of the more typical "GNU Public License". See the licenses for
4624 details, but in brief, if you change Verilator itself or the header
4625 files Verilator includes, you must make the source code available
4626 under the GNU Lesser Public License. However, Verilator output
4627 (the Verilated code) only "include"s the licensed files, and so you
4628 are NOT required to release any output from Verilator.
4629 You also have the option of using the Perl Artistic License, which
4631 again does not require you to release your Verilog or generated
4632 code, and also allows you to modify Verilator for internal use
4633 without distributing the modified version. But please contribute
4634 back to the community!
4635 One limit is that you cannot under either license release a
4637 commercial Verilog simulation product incorporating Verilator
4638 without making the source code available.
4639 As is standard with Open Source, contributions back to Verilator
4641 will be placed under the Verilator copyright and LGPL/Artistic
4642 license. Small test cases will be released into the public domain
4643 so they can be used anywhere, and large tests under the
4644 LGPL/Artistic, unless requested otherwise.
4645 Why is running Verilator (to create a model) so slow?
4647 Verilator needs more memory than the resulting simulator will
4648 require, as Verilator internally creates all of the state of the
4649 resulting generated simulator in order to optimize it. If it takes
4650 more than a few minutes or so (and you're not using --debug since
4651 debug mode is disk bound), see if your machine is paging; most
4652 likely you need to run it on a machine with more memory. Very large
4653 designs are known to have topped 16GB resident set size.
4654 How do I generate waveforms (traces) in C++?
4656 See the next question for tracing in SystemC mode.
4657 A. Add the --trace switch to Verilator, and in your top level C
4659 code, call Verilated::traceEverOn(true). Then you may use
4660 $dumpfile and $dumpvars to enable traces, same as with any Verilog
4661 simulator. See "examples/make_tracing_c".
4662 B. Or, for finer-grained control, or C++ files with multiple
4664 Verilated modules you may also create the trace purely from C++.
4665 Create a VerilatedVcdC object, and in your main loop call
4666 "trace_object->dump(time)" every time step, and finally call
4667 "trace_object->close()". You also need to compile
4668 verilated_vcd_c.cpp and add it to your link, preferably by adding
4669 the dependencies in $(VK_GLOBAL_OBJS) to your Makefile's link rule.
4670 This is done for you if using the Verilator --exe flag. Note you
4671 can also call ->trace on multiple Verilated objects with the same
4672 trace file if you want all data to land in the same output file.
4673 #include "verilated_vcd_c.h"
4675 ...
4676 int main(int argc, char** argv, char** env) {
4677 ...
4678 Verilated::traceEverOn(true);
4679 VerilatedVcdC* tfp = new VerilatedVcdC;
4680 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
4681 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
4682 ...
4683 while (sc_time_stamp() < sim_time && !Verilated::gotFinish()) {
4684 main_time += #;
4685 tfp->dump(main_time);
4686 }
4687 tfp->close();
4688 }
4689 How do I generate waveforms (traces) in SystemC?
4691 A. Add the --trace switch to Verilator, and in your top level
4692 sc_main, call Verilated::traceEverOn(true). Then you may use
4693 $dumpfile and $dumpvars to enable traces, same as with any Verilog
4694 simulator, see the non-SystemC example in
4695 "examples/make_tracing_c". This will trace only the module
4696 containing the $dumpvar.
4697 B. Or, you may create a trace purely from SystemC, which may trace
4699 all Verilated designs in the SystemC model. Create a VerilatedVcdSc
4700 object as you would create a normal SystemC trace file. For an
4701 example, see the call to VerilatedVcdSc in the
4702 examples/make_tracing_sc/sc_main.cpp file of the distribution, and
4703 below.
4704 Alternatively you may use the C++ trace mechanism described in the
4706 previous question, note the timescale and timeprecision will be
4707 inherited from your SystemC settings.
4708 You also need to compile verilated_vcd_sc.cpp and
4710 verilated_vcd_c.cpp and add them to your link, preferably by adding
4711 the dependencies in $(VK_GLOBAL_OBJS) to your Makefile's link rule.
4712 This is done for you if using the Verilator --exe flag.
4713 Note you can also call ->trace on multiple Verilated objects with
4715 the same trace file if you want all data to land in the same output
4716 file.
4717 When using SystemC 2.3, the SystemC library must have been built
4719 with the experimental simulation phase callback based tracing
4720 disabled. This is disabled by default when building SystemC with
4721 its configure based build system, but when building SystemC with
4722 CMake, you must pass -DENABLE_PHASE_CALLBACKS_TRACING=OFF to
4723 disable this feature.
4724 #include "verilated_vcd_sc.h"
4726 ...
4727 int main(int argc, char** argv, char** env) {
4728 ...
4729 Verilated::traceEverOn(true);
4730 VerilatedVcdSc* tfp = new VerilatedVcdSc;
4731 topp->trace(tfp, 99); // Trace 99 levels of hierarchy
4732 tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
4733 ...
4734 sc_start(1);
4735 ...
4736 tfp->close();
4737 }
4738 How do I generate FST waveforms (traces) in C++?
4740 FST is a trace file format developed by GTKWave. Verilator
4741 provides basic FST support. To dump traces in FST format, add the
4742 --trace-fst switch to Verilator and either A. use
4743 $dumpfile/$dumpvars in Verilog as described in the VCD example
4744 above, or B. in C++ change the include described in the VCD example
4745 above:
4746 #include "verilated_fst_c.h"
4748 VerilatedFstC* tfp = new VerilatedFstC;
4749 Note that currently supporting both FST and VCD in a single
4751 simulation is impossible, but such requirement should be rare. You
4752 can however ifdef around the trace format in your C++ main loop,
4753 and select VCD or FST at build time, should you require.
4754 How do I generate FST waveforms (aka dumps or traces) in SystemC?
4756 The FST library from GTKWave does not currently support SystemC;
4757 use VCD format instead.
4758 How do I view waveforms (aka dumps or traces)?
4760 Verilator creates standard VCD (Value Change Dump) and FST files.
4761 VCD files are viewable with the open source GTKWave (recommended)
4762 or Dinotrace (legacy) programs, or any of the many closed-source
4763 offerings; FST is supported only by GTKWave.
4764 How do I reduce the size of large waveform (trace) files?
4766 First, instead of calling VerilatedVcdC->open at the beginning of
4767 time, delay calling it until the time stamp where you want tracing
4768 to begin. Likewise you can also call VerilatedVcdC->open before
4769 the end of time (perhaps a short period after you detect a
4770 verification error).
4771 Next, add /*verilator tracing_off*/ to any very low level modules
4773 you never want to trace (such as perhaps library cells). Finally,
4774 use the --trace-depth option to limit the depth of tracing, for
4775 example --trace-depth 1 to see only the top level signals.
4776 Also be sure you write your trace files to a local solid-state
4778 drive, instead of to a network drive. Network drives are generally
4779 far slower.
4780 You can also consider using FST tracing instead of VCD. FST dumps
4782 are a fraction of the size of the equivalent VCD. FST tracing can
4783 be slower than VCD tracing, but it might be the only option if the
4784 VCD file size is prohibitively large.
4785 How do I do coverage analysis?
4787 Verilator supports both block (line) coverage and user inserted
4788 functional coverage.
4789 First, run verilator with the --coverage option. If you are using
4791 your own makefile, compile the model with the GCC flag
4792 -DVM_COVERAGE (if using the makefile provided by Verilator, it will
4793 do this for you).
4794 At the end of your test, call VerilatedCov::write passing the name
4796 of the coverage data file (typically "logs/coverage.dat").
4797 Run each of your tests in different directories. Each test will
4799 create a logs/coverage.dat file.
4800 After running all of your tests, execute the verilator_coverage
4802 tool. The verilator_coverage tool reads the logs/coverage.dat
4803 file(s), and creates an annotated source code listing showing code
4804 coverage details.
4805 For an example, after running 'make test' in the Verilator
4807 distribution, see the examples/make_tracing_c/logs directory. Grep
4808 for lines starting with '%' to see what lines Verilator believes
4809 need more coverage.
4810 Info files can be written by verilator_coverage for import to
4812 "lcov". This enables use of "genhtml" for HTML reports and
4813 importing reports to sites such as <https://codecov.io>.
4814 Where is the translate_off command? (How do I ignore a construct?)
4816 Translate on/off pragmas are generally a bad idea, as it's easy to
4817 have mismatched pairs, and you can't see what another tool sees by
4818 just preprocessing the code. Instead, use the preprocessor;
4819 Verilator defines the "VERILATOR" define for you, so just wrap the
4820 code in an ifndef region:
4821 `ifndef VERILATOR
4823 Something_Verilator_Dislikes;
4824 `endif
4825 Most synthesis tools similarly define SYNTHESIS for you.
4827 Why do I get "unexpected "do"" or "unexpected "bit"" errors?
4829 The words "do", "bit", "ref", "return", and others are reserved
4830 keywords in SystemVerilog. Older Verilog code might use these as
4831 identifiers. You should change your code to not use them to ensure
4832 it works with newer tools. Alternatively, surround them by the
4833 Verilog 2005/SystemVerilog begin_keywords pragma to indicate
4834 Verilog 2001 code.
4835 `begin_keywords "1364-2001"
4837 integer bit; initial bit = 1;
4838 `end_keywords
4839 If you want the whole design to be parsed as Verilog 2001, please
4841 see the "--default-language" option.
4842 How do I prevent my assertions from firing during reset?
4844 Call Verilated::assertOn(false) before you first call the model,
4845 then turn it back on after reset. It defaults to true. When
4846 false, all assertions controlled by --assert are disabled.
4847 Why do I get "undefined reference to `sc_time_stamp()'"?
4849 In C++ (non SystemC) code you need to define this function so that
4850 the simulator knows the current time. See the "CONNECTING TO C++"
4851 examples.
4852 Why do I get "undefined reference to `VL_RAND_RESET_I' or
4854 `Verilated::...'"?
4855 You need to link your compiled Verilated code against the
4856 verilated.cpp file found in the include directory of the Verilator
4857 kit. This is one target in the $(VK_GLOBAL_OBJS) make variable,
4858 which should be part of your Makefile's link rule. If you use
4859 --exe, this is done for you.
4860 Is the PLI supported?
4862 Only somewhat. More specifically, the common PLI-ish calls
4863 $display, $finish, $stop, $time, $write are converted to C++
4864 equivalents. You can also use the "import DPI" SystemVerilog
4865 feature to call C code (see the chapter above). There is also
4866 limited VPI access to public signals.
4867 If you want something more complex, since Verilator emits standard
4869 C++ code, you can simply write your own C++ routines that can
4870 access and modify signal values without needing any PLI interface
4871 code, and call it with $c("{any_c++_statement}").
4872 How do I make a Verilog module that contain a C++ object?
4874 You need to add the object to the structure that Verilator creates,
4875 then use $c to call a method inside your object. The
4876 test_regress/t/t_extend_class files show an example of how to do
4877 this.
4878 How do I get faster build times?
4880 When running make pass the make variable VM_PARALLEL_BUILDS=1 so
4881 that builds occur in parallel. Note this is now set by default if
4882 an output file was large enough to be split due to the
4883 --output-split option.
4884 Verilator emits any infrequently executed "cold" routines into
4886 separate __Slow.cpp files. This can accelerate compilation as
4887 optimization can be disabled on these routines. See the OPT_FAST
4888 and OPT_SLOW make variables and the BENCHMARKING & OPTIMIZATION
4889 section of the manual.
4890 Use a recent compiler. Newer compilers tend to be faster.
4892 Compile in parallel on many machines and use caching; see the web
4894 for the ccache, distcc and icecream packages. ccache will skip GCC
4895 runs between identical source builds, even across different users.
4896 If ccache was installed when Verilator was built it is used, or see
4897 OBJCACHE environment variable to override this. Also see the
4898 --output-split option.
4899 To reduce the compile time of classes that use a Verilated module
4901 (e.g. a top CPP file) you may wish to add /*verilator
4902 no_inline_module*/ to your top level module. This will decrease the
4903 amount of code in the model's Verilated class, improving compile
4904 times of any instantiating top level C++ code, at a relatively
4905 small cost of execution performance.
4906 Why do so many files need to recompile when I add a signal?
4908 Adding a new signal requires the symbol table to be recompiled.
4909 Verilator uses one large symbol table, as that results in 2-3 less
4910 assembly instructions for each signal access. This makes the
4911 execution time 10-15% faster, but can result in more compilations
4912 when something changes.
4913 How do I access Verilog functions/tasks in C?
4915 Use the SystemVerilog Direct Programming Interface. You write a
4916 Verilog function or task with input/outputs that match what you
4917 want to call in with C. Then mark that function as a DPI export
4918 function. See the DPI chapter in the IEEE Standard.
4919 How do I access C++ functions/tasks in Verilog?
4921 Use the SystemVerilog Direct Programming Interface. You write a
4922 Verilog function or task with input/outputs that match what you
4923 want to call in with C. Then mark that function as a DPI import
4924 function. See the DPI chapter in the IEEE Standard.
4925 How do I access signals in C?
4927 The best thing to do is to make a SystemVerilog "export DPI" task
4928 or function that accesses that signal, as described in the DPI
4929 chapter in the manual and DPI tutorials on the web. This will
4930 allow Verilator to better optimize the model and should be portable
4931 across simulators.
4932 If you really want raw access to the signals, declare the signals
4934 you will be accessing with a /*verilator public*/ comment before
4935 the closing semicolon. Then scope into the C++ class to read the
4936 value of the signal, as you would any other member variable.
4937 Signals are the smallest of 8-bit unsigned chars (equivalent to
4939 uint8_t), 16-bit unsigned shorts (uint16_t), 32-bit unsigned longs
4940 (uint32_t), or 64-bit unsigned long longs (uint64_t) that fits the
4941 width of the signal. Generally, you can use just uint32_t's for 1
4942 to 32 bits, or vluint64_t for 1 to 64 bits, and the compiler will
4943 properly up-convert smaller entities. Note even signed ports are
4944 declared as unsigned; you must sign extend yourself to the
4945 appropriate signal width.
4946 Signals wider than 64 bits are stored as an array of 32-bit
4948 uint32_t's. Thus to read bits 31:0, access signal[0], and for bits
4949 63:32, access signal[1]. Unused bits (for example bit numbers
4950 65-96 of a 65-bit vector) will always be zero. If you change the
4951 value you must make sure to pack zeros in the unused bits or core-
4952 dumps may result, because Verilator strips array bound checks where
4953 it believes them to be unnecessary to improve performance.
4954 In the SYSTEMC example above, if you had in our.v:
4956 input clk /*verilator public*/;
4958 // Note the placement of the semicolon above
4959 From the sc_main.cpp file, you'd then:
4961 #include "Vour.h"
4963 #include "Vour_our.h"
4964 cout << "clock is " << top->our->clk << endl;
4965 In this example, clk is a bool you can read or set as any other
4967 variable. The value of normal signals may be set, though clocks
4968 shouldn't be changed by your code or you'll get strange results.
4969 Should a module be in Verilog or SystemC?
4971 Sometimes there is a block that just interconnects instances, and
4972 have a choice as to if you write it in Verilog or SystemC.
4973 Everything else being equal, best performance is when Verilator
4974 sees all of the design. So, look at the hierarchy of your design,
4975 labeling instances as to if they are SystemC or Verilog. Then:
4976 A module with only SystemC instances below must be SystemC.
4978 A module with a mix of Verilog and SystemC instances below must be
4980 SystemC. (As Verilator cannot connect to lower-level SystemC
4981 instances.)
4982 A module with only Verilog instances below can be either, but for
4984 best performance should be Verilog. (The exception is if you have
4985 a design that is instantiated many times; in this case Verilating
4986 one of the lower modules and instantiating that Verilated instances
4987 multiple times into a SystemC module *may* be faster.)
4988
4990 First, check the "LANGUAGE LIMITATIONS" section.
4991 Next, try the --debug switch. This will enable additional internal
4993 assertions, and may help identify the problem.
4994 Finally, reduce your code to the smallest possible routine that
4996 exhibits the bug. Even better, create a test in the test_regress/t
4997 directory, as follows:
4998 cd test_regress
5000 cp -p t/t_EXAMPLE.pl t/t_BUG.pl
5001 cp -p t/t_EXAMPLE.v t/t_BUG.v
5002 There are many hints on how to write a good test in the driver.pl
5004 documentation which can be seen by running:
5005 cd $VERILATOR_ROOT # Need the original distribution kit
5007 test_regress/driver.pl --help
5008 Edit t/t_BUG.pl to suit your example; you can do anything you want in
5010 the Verilog code there; just make sure it retains the single clk input
5011 and no outputs. Now, the following should fail:
5012 cd $VERILATOR_ROOT # Need the original distribution kit
5014 cd test_regress
5015 t/t_BUG.pl # Run on Verilator
5016 t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
5017 t/t_BUG.pl --vcs # Run on VCS simulator
5018 t/t_BUG.pl --nc|--iv|--ghdl # Likewise on other simulators
5019 The test driver accepts a number of options, many of which mirror the
5021 main Verilator option. For example the previous test could have been
5022 run with debugging enabled. The full set of test options can be seen
5023 by running driver.pl --help as shown above.
5024 Finally, report the bug using the bug tracker at
5026 <https://verilator.org/issues>. The bug will become publicly visible;
5027 if this is unacceptable, mail the bug report to "wsnyder@wsnyder.org".
5028
5030 Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group
5031 at Digital Equipment Corporation. The Verilog code that was converted
5032 to C was then merged with a C based CPU model of the Alpha processor
5033 and simulated in a C based environment called CCLI.
5034 In 1995 Verilator started being used also for Multimedia and Network
5036 Processor development inside Digital. Duane Galbi took over active
5037 development of Verilator, and added several performance enhancements.
5038 CCLI was still being used as the shell.
5039 In 1998, through the efforts of existing DECies, mainly Duane Galbi,
5041 Digital graciously agreed to release the source code. (Subject to the
5042 code not being resold, which is compatible with the GNU Public
5043 License.)
5044 In 2001, Wilson Snyder took the kit, and added a SystemC mode, and
5046 called it Verilator2. This was the first packaged public release.
5047 In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator
5049 from scratch in C++. This added many optimizations, yielding about a
5050 2-5x performance gain.
5051 In 2009, major SystemVerilog and DPI language support was added.
5053 In 2018, Verilator 4.000 was released with multithreaded support.
5055 Currently, various language features and performance enhancements are
5057 added as the need arises. Verilator is now about 3x faster than in
5058 2002, and is faster than most (if not every) other simulator.
5059
5061 When possible, please instead report bugs to
5062 <https://verilator.org/issues>.
5063 Wilson Snyder <wsnyder@wsnyder.org>
5065 Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
5067
5069 Many people have provided ideas and other assistance with Verilator.
5070 Verilator is receiving major development support from the CHIPS
5072 Alliance.
5073 Previous major corporate sponsors of Verilator, by providing
5075 significant contributions of time or funds included include Atmel
5076 Corporation, Cavium Inc., Compaq Corporation, Digital Equipment
5077 Corporation, Embecosm Ltd., Hicamp Systems, Intel Corporation,
5078 Mindspeed Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun
5079 Microsystems Inc., Nauticus Networks Inc., and SiCortex Inc.
5080 The people who have contributed major functionality are Byron Bradley,
5082 Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Geza Lore, Todd
5083 Strader, Stefan Wallentowitz, Paul Wasson, Jie Xu, and Wilson Snyder.
5084 Major testers included Jeff Dutton, Jonathon Donaldson, Ralf Karge,
5085 David Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov, Sebastien
5086 Van Cauwenberghe, Gene Weber, and Clifford Wolf.
5087 Some of the people who have provided ideas, and feedback for Verilator
5089 include: David Addison, Tariq B. Ahmad, Nikana Anastasiadis, Hans Van
5090 Antwerpen, Vasu Arasanipalai, Jens Arm, Sharad Bagri, Matthew Ballance,
5091 Andrew Bardsley, Matthew Barr, Geoff Barrett, Julius Baxter, Jeremy
5092 Bennett, Michael Berman, Victor Besyakov, Moinak Bhattacharyya, David
5093 Binderman, Piotr Binkowski, Johan Bjork, David Black, Tymoteusz
5094 Blazejczyk, Daniel Bone, Gregg Bouchard, Christopher Boumenot, Nick
5095 Bowler, Byron Bradley, Bryan Brady, Maarten De Braekeleer, Charlie
5096 Brej, J Briquet, Lane Brooks, John Brownlee, Jeff Bush, Lawrence
5097 Butcher, Tony Bybell, Ted Campbell, Chris Candler, Lauren Carlson,
5098 Donal Casey, Sebastien Van Cauwenberghe, Alex Chadwick, Terry Chen, Yi-
5099 Chung Chen, Enzo Chi, Robert A. Clark, Allan Cochrane, John Coiner,
5100 Gianfranco Costamagna, Sean Cross, George Cuan, Joe DErrico, Lukasz
5101 Dalek, Laurens van Dam, Gunter Dannoritzer, Ashutosh Das, Bernard
5102 Deadman, John Demme, Mike Denio, John Deroo, Philip Derrick, John
5103 Dickol, Ruben Diez, Danny Ding, Jacko Dirks, Ivan Djordjevic, Jonathon
5104 Donaldson, Leendert van Doorn, Sebastian Dressler, Alex Duller, Jeff
5105 Dutton, Tomas Dzetkulic, Usuario Eda, Charles Eddleston, Chandan
5106 Egbert, Joe Eiler, Ahmed El-Mahmoudy, Trevor Elbourne, Mats Engstrom,
5107 Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Udi Finkelstein, Brian
5108 Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi, Benjamin Gartner,
5109 Christian Gelinek, Peter Gerst, Glen Gibb, Michael Gielda, Shankar
5110 Giri, Dan Gisselquist, Petr Gladkikh, Sam Gladstone, Amir Gonnen,
5111 Chitlesh Goorah, Kai Gossner, Sergi Granell, Al Grant, Alexander
5112 Grobman, Xuan Guo, Driss Hafdi, Neil Hamilton, James Hanlon, Oyvind
5113 Harboe, Jannis Harder, Junji Hashimoto, Thomas Hawkins, Mitch Hayenga,
5114 Robert Henry, Stephen Henry, David Hewson, Jamey Hicks, Joel
5115 Holdsworth, Andrew Holme, Hiroki Honda, Alex Hornung, David Horton,
5116 Peter Horvath, Jae Hossell, Alan Hunter, James Hutchinson, Jamie Iles,
5117 Ben Jackson, Shareef Jalloq, Krzysztof Jankowski, HyungKi Jeong, Iztok
5118 Jeras, James Johnson, Christophe Joly, Franck Jullien, James Jung, Mike
5119 Kagen, Arthur Kahlich, Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi,
5120 Kanad Kanhere, Patricio Kaplan, Pieter Kapsenberg, Ralf Karge, Dan
5121 Katz, Sol Katzman, Ian Kennedy, Jonathan Kimmitt, Olof Kindgren, Kevin
5122 Kiningham, Dan Kirkham, Sobhan Klnv, Gernot Koch, Soon Koh, Nathan
5123 Kohagen, Steve Kolecki, Brett Koonce, Will Korteland, Wojciech Koszek,
5124 Varun Koyyalagunta, David Kravitz, Roland Kruse, Sergey Kvachonok,
5125 Charles Eric LaForest, Ed Lander, Steve Lang, Stephane Laurent, Walter
5126 Lavino, Christian Leber, Larry Lee, Igor Lesik, John Li, Eivind Liland,
5127 Yu Sheng Lin, Charlie Lind, Andrew Ling, Jiuyang Liu, Paul Liu, Derek
5128 Lockhart, Jake Longo, Geza Lore, Arthur Low, Stefan Ludwig, Dan
5129 Lussier, Fred Ma, Duraid Madina, Affe Mao, Julien Margetts, Mark
5130 Marshall, Alfonso Martinez, Yves Mathieu, Patrick Maupin, Jason
5131 McMullan, Elliot Mednick, Wim Michiels, Miodrag Milanovic, Wai Sum
5132 Mong, Peter Monsson, Sean Moore, Dennis Muhlestein, John Murphy, Matt
5133 Myers, Nathan Myers, Richard Myers, Dimitris Nalbantis, Peter Nelson,
5134 Bob Newgard, Cong Van Nguyen, Paul Nitza, Yossi Nivin, Pete Nixon, Lisa
5135 Noack, Mark Nodine, Kuba Ober, Andreas Olofsson, Aleksander Osman,
5136 James Pallister, Vassilis Papaefstathiou, Brad Parker, Dan Petrisko,
5137 Maciej Piechotka, David Pierce, Dominic Plunkett, David Poole, Mike
5138 Popoloski, Roman Popov, Rich Porter, Niranjan Prabhu, Usha
5139 Priyadharshini, Mark Jackson Pulver, Prateek Puri, Marshal Qiao, Danilo
5140 Ramos, Chris Randall, Anton Rapp, Josh Redford, Odd Magne Reitan,
5141 Frederic Requin, Frederick Requin, Dustin Richmond, Alberto Del Rio,
5142 Eric Rippey, Oleg Rodionov, Ludwig Rogiers, Paul Rolfe, Arjen
5143 Roodselaar, Tobias Rosenkranz, Huang Rui, Jan Egil Ruud, Denis Rystsov,
5144 John Sanguinetti, Galen Seitz, Salman Sheikh, Hao Shi, Mike
5145 Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Anderson Ignacio Da
5146 Silva, Rodney Sinclair, Steven Slatter, Brian Small, Garrett Smith, Tim
5147 Snyder, Maciej Sobkowski, Stan Sokorac, Alex Solomatnikov, Wei Song,
5148 Art Stamness, David Stanford, John Stevenson, Pete Stevenson, Patrick
5149 Stewart, Rob Stoddard, Todd Strader, John Stroebel, Sven Stucki, Howard
5150 Su, Emerson Suguimoto, Gene Sullivan, Qingyao Sun, Renga Sundararajan,
5151 Rupert Swarbrick, Yutetsu Takatsukasa, Peter Tengstrand, Wesley
5152 Terpstra, Rui Terra, Stefan Thiede, Gary Thomas, Ian Thompson, Kevin
5153 Thompson, Mike Thyer, Hans Tichelaar, Viktor Tomov, Steve Tong, Michael
5154 Tresidder, Neil Turton, Srini Vemuri, Yuri Victorovich, Bogdan
5155 Vukobratovic, Holger Waechtler, Philipp Wagner, Stefan Wallentowitz,
5156 Shawn Wang, Paul Wasson, Greg Waters, Thomas Watts, Eugene Weber, David
5157 Welch, Thomas J Whatson, Marco Widmer, Leon Wildman, Daniel Wilkerson,
5158 Gerald Williams, Trevor Williams, Jan Van Winkel, Jeff Winston, Joshua
5159 Wise, Clifford Wolf, Tobias Wolfel, Johan Wouters, Junyi Xi, Ding
5160 Xiaoliang, Jie Xu, Mandy Xu, Takatsukasa Y, Luke Yang, and Amir
5161 Yazdanbakhsh.
5162 Thanks to them, and all those we've missed including above, or wished
5164 to remain anonymous.
5165
5167 The latest version is available from <https://verilator.org>.
5168 Copyright 2003-2021 by Wilson Snyder. This program is free software;
5170 you can redistribute it and/or modify the Verilator internals under the
5171 terms of either the GNU Lesser General Public License Version 3 or the
5172 Perl Artistic License Version 2.0.
5173 All Verilog and C++/SystemC code quoted within this documentation file
5175 are released as Creative Commons Public Domain (CC0). Many example
5176 files and test files are likewise released under CC0 into effectively
5177 the Public Domain as described in the files themselves.
5178
5180 verilator_coverage, verilator_gantt, verilator_profcfunc, make,
5181 "verilator --help" which is the source for this document,
5183 and docs/internals.adoc in the distribution.
5185perl v5.34.0 2021-07-23 VERILATOR(1)