verilator - Online in the Cloud

PROGRAM:

NAME

Verilator - Convert Verilog code to C++/SystemC

SYNOPSIS

verilator --help
verilator --version
verilator --cc [options] [top_level.v]... [opt_c_files.cpp/c/cc/a/o/so]
verilator --sc [options] [top_level.v]... [opt_c_files.cpp/c/cc/a/o/so]
verilator --lint-only [top_level.v]...

DESCRIPTION

Verilator converts synthesizable (not behavioral) Verilog code, plus some Synthesis,
SystemVerilog and a small subset of Verilog AMS assertions, into C++ or SystemC code. It
is not a complete simulator, but a compiler.

Verilator is invoked with parameters similar to GCC, Cadence Verilog-XL/NC-Verilog, or
Synopsys's VCS. It reads the specified Verilog code, lints it, and optionally adds
coverage and waveform tracing code. For C++ and SystemC formats, it outputs .cpp and .h
files.

The files created by Verilator are then compiled with C++. The user writes a little C++
wrapper file, which instantiates the top level module, and passes this filename on the
command line. These C files are compiled in C++, and linked with the Verilated files.

The resulting executable will perform the actual simulation.

To get started, jump down to "EXAMPLE C++ EXECUTION".

ARGUMENT SUMMARY

This is a short summary of the arguments to Verilator. See the detailed descriptions in
the next sections for more information.

{file.v} Verilog top level filenames
{file.c/cc/cpp} Optional C++ files to compile in
{file.a/o/so} Optional C++ files to link in

+1364-1995ext+<ext> Use Verilog 1995 with file extension <ext>
+1364-2001ext+<ext> Use Verilog 2001 with file extension <ext>
+1364-2005ext+<ext> Use Verilog 2005 with file extension <ext>
+1800-2005ext+<ext> Use SystemVerilog 2005 with file extension <ext>
+1800-2009ext+<ext> Use SystemVerilog 2009 with file extension <ext>
+1800-2012ext+<ext> Use SystemVerilog 2012 with file extension <ext>
--assert Enable all assertions
--autoflush Flush streams after all $displays
--bbox-sys Blackbox unknown $system calls
--bbox-unsup Blackbox unsupported language features
--bin <filename> Override Verilator binary
-CFLAGS <flags> C++ Compiler flags for makefile
--cc Create C++ output
--cdc Clock domain crossing analysis
--clk <signal-name> Mark specified signal as clock
--compiler <compiler-name> Tune for specified C++ compiler
--converge-limit <loops> Tune convergence settle time
--coverage Enable all coverage
--coverage-line Enable line coverage
--coverage-toggle Enable toggle coverage
--coverage-user Enable SVL user coverage
--coverage-underscore Enable coverage of _signals
-D<var>[=<value>] Set preprocessor define
--debug Enable debugging
--debug-check Enable debugging assertions
--debugi <level> Enable debugging at a specified level
--debugi-<srcfile> <level> Enable debugging a source file at a level
--default-language <lang> Default language to parse
+define+<var>=<value> Set preprocessor define
--dump-tree Enable dumping .tree files
--dump-treei <level> Enable dumping .tree files at a level
--dump-treei-<srcfile> <level> Enable dumping .tree file at a source file at a level
-E Preprocess, but do not compile
--error-limit <value> Abort after this number of errors
--exe Link to create executable
-F <file> Parse options from a file, relatively
-f <file> Parse options from a file
--gdb Run Verilator under GDB interactively
--gdbbt Run Verilator under GDB for backtrace
--help Display this help
-I<dir> Directory to search for includes
--if-depth <value> Tune IFDEPTH warning
+incdir+<dir> Directory to search for includes
--inhibit-sim Create function to turn off sim
--inline-mult <value> Tune module inlining
-LDFLAGS <flags> Linker pre-object flags for makefile
-LDLIBS <flags> Linker library flags for makefile
--language <lang> Default language standard to parse
+libext+<ext>+[ext]... Extensions for finding modules
--lint-only Lint, but do not make output
--MMD Create .d dependency files
--MP Create phony dependency targets
--Mdir <directory> Name of output object directory
--mod-prefix <topname> Name to prepend to lower classes
--no-clk <signal-name> Prevent marking specified signal as clock
--no-pins64 Don't use vluint64_t's for 33-64 bit sigs
--no-skip-identical Disable skipping identical output
+notimingchecks Ignored
-O0 Disable optimizations
-O3 High performance optimizations
-O<optimization-letter> Selectable optimizations
-o <executable> Name of final executable
--no-order-clock-delay Disable ordering clock enable assignments
--output-split <bytes> Split .cpp files into pieces
--output-split-cfuncs <statements> Split .cpp functions
--output-split-ctrace <statements> Split tracing functions
-P Disable line numbers and blanks with -E
--pins-bv <bits> Specify types for top level ports
--pins-sc-uint Specify types for top level ports
--pins-sc-biguint Specify types for top level ports
--pins-uint8 Specify types for top level ports
--pipe-filter <command> Filter all input through a script
--prefix <topname> Name of top level class
--profile-cfuncs Name functions for profiling
--private Debugging; see docs
--public Debugging; see docs
--report-unoptflat Extra diagnostics for UNOPTFLAT
--savable Enable model save-restore
--sc Create SystemC output
--stats Create statistics file
--stats-vars Provide statistics on variables
-sv Enable SystemVerilog parsing
+systemverilogext+<ext> Synonym for +1800-2012ext+<ext>
--top-module <topname> Name of top level input module
--trace Enable waveform creation
--trace-depth <levels> Depth of tracing
--trace-max-array <depth> Maximum bit width for tracing
--trace-max-width <width> Maximum array depth for tracing
--trace-params Enable tracing parameters
--trace-structs Enable tracing structure names
--trace-underscore Enable tracing of _signals
-U<var> Undefine preprocessor define
--unroll-count <loops> Tune maximum loop iterations
--unroll-stmts <stmts> Tune maximum loop body size
--unused-regexp <regexp> Tune UNUSED lint signals
-V Verbose version and config
-v <filename> Verilog library
+verilog1995ext+<ext> Synonym for +1364-1995ext+<ext>
+verilog2001ext+<ext> Synonym for +1364-2001ext+<ext>
-Werror-<message> Convert warning to error
-Wfuture-<message> Disable unknown message warnings
-Wno-<message> Disable warning
-Wno-lint Disable all lint warnings
-Wno-style Disable all style warnings
-Wno-fatal Disable fatal exit on warnings
--x-assign <mode> Initially assign Xs to this value
--x-initial-edge Enable initial X->0 and X->1 edge triggers
-y <dir> Directory to search for modules

ARGUMENTS

{file.v}
Specifies the Verilog file containing the top module to be Verilated.

{file.c/.cc/.cpp/.cxx}
Specifies optional C++ files to be linked in with the Verilog code. If any C++ files
are specified in this way, Verilator will include a make rule that generates a module
executable. Without any C++ files, Verilator will stop at the module__ALL.a library,
and presume you'll continue linking with make rules you write yourself. See also the
-CFLAGS option.

{file.a/.o/.so}
Specifies optional object or library files to be linked in with the Verilog code, as a
shorthand for -LDFLAGS "<file>". If any files are specified in this way, Verilator
will include a make rule that uses these files when linking the module executable.
This generally is only useful when used with the --exe option.

+1364-1995ext+ext
+1364-2001ext+ext
+1364-2005ext+ext
+1800-2005ext+ext
+1800-2009ext+ext
+1800-2012ext+ext
Specifies the language standard to be used with a specific filename extension, ext.

For compatibility with other simulators, see also the synonyms "+verilog1995ext+"ext,
"+verilog2001ext+"ext, and "+systemverilogext+"ext.

For any source file, the language specified by these options takes precedence over any
language specified by the "--default-language" or "--language" options.

These options take effect in the order they are encountered. Thus the following would
use Verilog 1995 for "a.v" and Verilog 2001 for "b.v".

verilator ... +1364-1995ext+v a.v +1364-2001ext+v b.v

These flags are only recommended for legacy mixed language designs, as the preferable
option is to edit the code to repair new keywords, or add appropriate
"`begin_keywords".

Note "`begin_keywords" is a SystemVerilog construct, which specifies only which the
set of keywords is to be recognized. Whatever set is chosen, the semantics will be
those of SystemVerilog. By contrast "+1364-1995ext+" etc. specify both the syntax and
semantics to be used.

--assert
Enable all assertions.

See also --x-assign and --x-initial-edge; setting "--x-assign unique" and/or
"--x-initial-edge" may be desirable.

--autoflush
After every $display or $fdisplay, flush the output stream. This insures that
messages will appear immediately but may reduce performance; for best performance call
"fflush(stdout)" occasionally in the main C loop. Defaults off, which will buffer
output as provided by the normal C stdio calls.

--bbox-sys
Black box any unknown $system task or function calls. System tasks will be simply
NOPed, and system functions will be replaced by unsized zero. Arguments to such
functions will be parsed, but not otherwise checked. This prevents errors when
linting in the presence of company specific PLI calls.

--bbox-unsup
Black box some unsupported language features, currently UDP tables and the cmos and
tran gate primitives. This may enable linting the rest of the design even when
unsupported constructs are present.

--bin filename
Rarely needed. Override the default filename for Verilator itself. When a dependency
(.d) file is created, this filename will become a source dependency, such that a
change in this binary will have make rebuild the output files.

-CFLAGS flags
Add specified C compiler flags to the generated makefiles. When make is run on the
generated makefile these will be passed to the C++ compiler (gcc/g++/msvc++).

--cc
Specifies C++ without SystemC output mode; see also --sc.

--cdc
Experimental. Perform some clock domain crossing checks and issue related warnings
(CDCRSTLOGIC) and then exit; if warnings other than CDC warnings are needed make a
second run with --lint-only. Additional warning information is also written to the
file {prefix}__cdc.txt.

Currently only checks some items that other CDC tools missed; if you have interest in
adding more traditional CDC checks, please contact the authors.

--clk signal-name
Sometimes it is quite difficult for Verilator to distinguish clock signals from other
data signals. Occasionally the clock signals can end up in the checking list of
signals which determines if further evaluation is needed. This will heavily degrade
the performance of verilated model.

With --clk <signal-name>, user can specified root clock into the model, then Verilator
will mark the signal as clocker and propagate the clocker attribute automatically to
other signals derived from that. In this way, Verilator will try to avoid taking the
clocker signal into checking list.

Note signal-name is specified by the RTL hiearchy path. For example, v.foo.bar. If
the signal is the input to top-module, the directly the signal name. If you find it
difficult to find the exact name, try to use "/*verilator clocker*/" in RTL file to
mark the signal directly.

--compiler compiler-name
Enables tunings and work-arounds for the specified C++ compiler.

clang
Tune for clang. This may reduce execution speed as it enables several workarounds
to avoid silly hardcoded limits in clang. This includes breaking deep structures
as for msvc as described below.

gcc Tune for Gnu C++, although generated code should work on almost any compliant C++
compiler. Currently the default.

msvc
Tune for Microsoft Visual C++. This may reduce execution speed as it enables
several workarounds to avoid silly hardcoded limits in MSVC++. This includes
breaking deeply nested parenthesized expressions into sub-expressions to avoid
error C1009, and breaking deep blocks into functions to avoid error C1061.

--converge-limit <loops>
Rarely needed. Specifies the maximum number of runtime iterations before creating a
model failed to converge error. Defaults to 100.

--coverage
Enables all forms of coverage, alias for "--coverage-line --coverage-toggle
--coverage-user".

--coverage-line
Specifies basic block line coverage analysis code should be inserted.

Coverage analysis adds statements at each code flow change point, which are the
branches of IF and CASE statements, a super-set of normal Verilog Line Coverage. At
each such branch a unique counter is incremented. At the end of a test, the counters
along with the filename and line number corresponding to each counter are written into
logs/coverage.pl.

Verilator automatically disables coverage of branches that have a $stop in them, as it
is assumed $stop branches contain an error check that should not occur. A /*verilator
coverage_block_off*/ comment will perform a similar function on any code in that block
or below, or /*verilator coverage_on/coverage_off*/ will disable coverage around lines
of code.

Note Verilator may over-count combinatorial (non-clocked) blocks when those blocks
receive signals which have had the UNOPTFLAT warning disabled; for most accurate
results do not disable this warning when using coverage.

--coverage-toggle
Specifies signal toggle coverage analysis code should be inserted.

Every bit of every signal in a module has a counter inserted. The counter will
increment on every edge change of the corresponding bit.

Signals that are part of tasks or begin/end blocks are considered local variables and
are not covered. Signals that begin with underscores, are integers, or are very wide
(>256 bits total storage across all dimensions) are also not covered.

Hierarchy is compressed, such that if a module is instantiated multiple times,
coverage will be summed for that bit across ALL instantiations of that module with the
same parameter set. A module instantiated with different parameter values is
considered a different module, and will get counted separately.

Verilator makes a minimally-intelligent decision about what clock domain the signal
goes to, and only looks for edges in that clock domain. This means that edges may be
ignored if it is known that the edge could never be seen by the receiving logic. This
algorithm may improve in the future. The net result is coverage may be lower than
what would be seen by looking at traces, but the coverage is a more accurate
representation of the quality of stimulus into the design.

There may be edges counted near time zero while the model stabilizes. It's a good
practice to zero all coverage just before releasing reset to prevent counting such
behavior.

A /*verilator coverage_off/on */ comment pair can be used around signals that do not
need toggle analysis, such as RAMs and register files.

--coverage-underscore
Enable coverage of signals that start with an underscore. Normally, these signals are
not covered. See also --trace-underscore.

--coverage-user
Enables user inserted functional coverage. Currently, all functional coverage points
are specified using SVA which must be separately enabled with --assert.

For example, the following statement will add a coverage point, with the comment
"DefaultClock":

DefaultClock: cover property (@(posedge clk) cyc==3);

-Dvar=value
Defines the given preprocessor symbol, without allowing. Similar to +define; +define
is fairly standard across Verilog tools while -D is an alias for GCC compatibility.

--debug
Select the debug built image of Verilator (if available), and enable more internal
assertions (equivelent to "--debug-check"), debugging messages (equivelent to
"--debugi 4"), and intermediate form dump files (equivilent to "--dump-treei 3").

--debug-check
Rarely needed. Enable internal debugging assertion checks, without changing debug
verbosity. Enabled automatically when --debug specified.

--debugi <level>
--debugi-<srcfile> <level>
Rarely needed - for developer use. Set internal debugging level globally to the
specified debug level (1-10) or set the specified Verilator source file to the
specified level (e.g. "--debugi-V3Width 9"). Higher levels produce more detailed
messages.

--default-language value
Select the language to be used by default when first processing each Verilog file.
The language value must be "1364-1995", "1364-2001", "1364-2005", "1800-2005",
"1800-2009" or "1800-2012".

Any language associated with a particular file extension (see the various +langext+
options) will be used in preference to the language specified by --default-language.

The --default-language flag is only recommended for legacy code using the same
language in all source files, as the preferable option is to edit the code to repair
new keywords, or add appropriate "`begin_keywords". For legacy mixed language designs,
the various +langext+ options should be used.

If no language is specified, either by this flag or +langext+ options, then the latest
SystemVerilog language (IEEE 1800-2012) is used.

+define+var=value
+define+var=value+var2=value2...
Defines the given preprocessor symbol, or multiple symbols if separated by plusses.
Similar to -D; +define is fairly standard across Verilog tools while -D is an alias
for GCC compatibility.

--dump-tree
Rarely needed. Enable writing .tree debug files with dumping level 3, which dumps the
standard critical stages. For details on the format see the Verilator Internals
manual. --dump-tree is enabled automatically with --debug, so "--debug
--no-dump-tree" may be useful if the dump files are large and not desired.

--dump-treei <level>
--dump-treei-<srcfile> <level>
Rarely needed - for developer use. Set internal tree dumping level globally to a
specific dumping level or set the specified Verilator source file to the specified
tree dumping level (e.g. "--dump-treei-V3Order 9"). Level 0 disbles dumps and is
equivalent to "--no-dump-tree". Level 9 enables dumping of every stage.

-E Preprocess the source code, but do not compile, as with 'gcc -E'. Output is written
to standard out. Beware of enabling debugging messages, as they will also go to
standard out.

--error-limit <value>
After this number of errors or warnings are encountered, exit. Defaults to 50.

--exe
Generate an executable. You will also need to pass additional .cpp files on the
command line that implement the main loop for your simulation.

-F file
Read the specified file, and act as if all text inside it was specified as command
line parameters. Any relative paths are relative to the directory containing the
specified file. See also -f. Note -F is fairly standard across Verilog tools.

-f file
Read the specified file, and act as if all text inside it was specified as command
line parameters. Any relative paths are relative to the current directory. See also
-F. Note -f is fairly standard across Verilog tools.

The file may contain // comments which are ignored to the end of the line. Any $VAR,
$(VAR), or ${VAR} will be replaced with the specified environment variable.

--gdb
Run Verilator underneath an interactive GDB (or VERILATOR_GDB environment variable
value) session. See also --gdbbt.

--gdbbt
If --debug is specified, run Verilator underneath a GDB process and print a backtrace
on exit, then exit GDB immediately. Without --debug or if GDB doesn't seem to work,
this flag is ignored. Intended for easy creation of backtraces by users; otherwise
see the --gdb flag.

--help
Displays this message and program version and exits.

-Idir
See -y.

--if-depth value
Rarely needed. Set the depth at which the IFDEPTH warning will fire, defaults to 0
which disables this warning.

+incdir+dir
See -y.

--inhibit-sim
Rarely needed. Create a "inhibitSim(bool)" function to enable and disable evaluation.
This allows an upper level testbench to disable modules that are not important in a
given simulation, without needing to recompile or change the SystemC modules
instantiated.

--inline-mult value
Tune the inlining of modules. The default value of 2000 specifies that up to 2000 new
operations may be added to the model by inlining, if more than this number of
operations would result, the module is not inlined. Larger values, or a value <= 1
will inline everything, will lead to longer compile times, but potentially faster
runtimes. This setting is ignored for very small modules; they will always be
inlined, if allowed.

-LDFLAGS flags
Add specified C linker flags to the generated makefiles. When make is run on the
generated makefile these will be passed to the C++ linker (ld) *after* the primary
file being linked. This flag is called -LDFLAGS as that's the traditional name in
simulators; it's would have been better called LDLIBS as that's the Makefile variable
it controls. (In Make, LDFLAGS is before the first object, LDLIBS after. -L
libraries need to be in the Make variable LDLIBS, not LDFLAGS.)

--language value
A synonym for "--default-langauge", for compatibility with other tools and earlier
versions of Verilator.

+libext+ext+ext...
Specify the extensions that should be used for finding modules. If for example module
x is referenced, look in x.ext. Note +libext+ is fairly standard across Verilog
tools. Defaults to .v and .sv.

--lint-only
Check the files for lint violations only, do not create any other output.

You may also want the -Wall option to enable messages that are considered stylistic
and not enabled by default.

If the design is not to be completely Verilated see also the --bbox-sys and
--bbox-unsup options.

--MMD
Enable creation of .d dependency files, used for make dependency detection, similar to
gcc -MMD option. On by default, use --no-MMD to disable.

--MP
When creating .d dependency files with --MMD, make phony targets. Similar to gcc -MP
option.

--Mdir directory
Specifies the name of the Make object directory. All generated files will be placed
in this directory. If not specified, "obj_dir" is used. The directory is created if
it does not exist and the parent directories exist; otherwise manually create the Mdir
before calling Verilator.

--mod-prefix topname
Specifies the name to prepend to all lower level classes. Defaults to the same as
--prefix.

--no-clk <signal-name>
Prevent the specified signal from being marked as clock. See "--clk".

--no-pins64
Backward compatible alias for "--pins-bv 33".

--no-skip-identical
Rarely needed. Disables skipping execution of Verilator if all source files are
identical, and all output files exist with newer dates.

+notimingchecks
Ignored for compatibility with other simulators.

-O0 Disables optimization of the model.

-O3 Enables slow optimizations for the code Verilator itself generates (as opposed to
"-CFLAGS -O3" which effects the C compiler's optimization. -O3 may reduce simulation
runtimes at the cost of compile time. This currently sets --inline-mult -1.

-Ooptimization-letter
Rarely needed. Enables or disables a specific optimizations, with the optimization
selected based on the letter passed. A lowercase letter disables an optimization, an
upper case letter enables it. This is intended for debugging use only; see the source
code for version-dependent mappings of optimizations to -O letters.

-o <executable>
Specify the name for the final executable built if using --exe. Defaults to the
--prefix if not specified.

--no-order-clock-delay
Rarely needed. Disables a bug fix for ordering of clock enables with delayed
assignments. This flag should only be used when suggested by the developers.

--output-split bytes
Enables splitting the output .cpp/.sp files into multiple outputs. When a C++ file
exceeds the specified number of operations, a new file will be created at the next
function boundary. In addition, any slow routines will be placed into __Slow files.
This accelerates compilation by as optimization can be disabled on the slow routines,
and the remaining files can be compiled on parallel machines. Using --output-split
should have only a trivial impact on performance. With GCC 3.3 on a 2GHz Opteron,
--output-split 20000 will result in splitting into approximately one-minute-compile
chunks.

--output-split-cfuncs statements
Enables splitting functions in the output .cpp/.sp files into multiple functions.
When a generated function exceeds the specified number of operations, a new function
will be created. With --output-split, this will enable GCC to compile faster, at a
small loss in performance that gets worse with decreasing split values. Note that
this option is stronger than --output-split in the sense that --output-split will not
split inside a function.

--output-split-ctrace statements
Enables splitting trace functions in the output .cpp/.sp files into multiple
functions. Defaults to same setting as --output-split-cfuncs.

-P With -E, disable generation of `line markers and blank lines, similar to GCC -P flag.

--pins64
Backward compatible alias for "--pins-bv 65". Note that's a 65, not a 64.

--pins-bv width
Specifies SystemC inputs/outputs of greater than or equal to width bits wide should
use sc_bv's instead of uint32/vluint64_t's. The default is "--pins-bv 65". Versions
before Verilator 3.671 defaulted to "--pins-bv 33". The more sc_bv is used, the worse
for performance. Use the "/*verilator sc_bv*/" attribute to select specific ports to
be sc_bv.

--pins-sc-uint
Specifies SystemC inputs/outputs of greater than 2 bits wide should use sc_uint
between 2 and 64. When combined with the "--pins-sc-biguint" combination, it results
in sc_uint being used between 2 and 64 and sc_biguint being used between 65 and 512.

--pins-sc-biguint
Specifies SystemC inputs/outputs of greater than 65 bits wide should use sc_biguint
between 65 and 512, and sc_bv from 513 upwards. When combined with the
"--pins-sc-uint" combination, it results in sc_uint being used between 2 and 64 and
sc_biguint being used between 65 and 512.

--pins-uint8
Specifies SystemC inputs/outputs that are smaller than the --pins-bv setting and 8
bits or less should use uint8_t instead of uint32_t. Likewise pins of width 9-16 will
use uint16_t instead of uint32_t.

--pipe-filter command
Rarely needed and experimental. Verilator will spawn the specified command as a
subprocess pipe, to allow the command to perform custom edits on the Verilog code
before it reaches Verilator.

Before reading each Verilog file, Verilator will pass the file name to the subprocess'
stdin with 'read_verilog "<filename>"'. The filter may then read the file and perform
any filtering it desires, and feeds the new file contents back to Verilator on stdout
with 'Content-Length'. Output to stderr from the filter feeds through to Verilator's
stdout and if the filter exits with non-zero status Verilator terminates. See the
t/t_pipe_filter test for an example.

To debug the output of the filter, try using the -E option to see preprocessed output.

--prefix topname
Specifies the name of the top level class and makefile. Defaults to V prepended to
the name of the --top-module switch, or V prepended to the first Verilog filename
passed on the command line.

--profile-cfuncs
Modify the created C++ functions to support profiling. The functions will be
minimized to contain one "basic" statement, generally a single always block or wire
statement. (Note this will slow down the executable by ~5%.) Furthermore, the
function name will be suffixed with the basename of the Verilog module and line number
the statement came from. This allows gprof or oprofile reports to be correlated with
the original Verilog source statements.

--private
Opposite of --public. Is the default; this option exists for backwards compatibility.

--public
This is only for historical debug use. Using it may result in mis-simulation of
generated clocks.

Declares all signals and modules public. This will turn off signal optimizations as
if all signals had a /*verilator public*/ comments and inlining. This will also turn
off inlining as if all modules had a /*verilator public_module*/, unless the module
specifically enabled it with /*verilator inline_module*/.

--report-unoptflat
Extra diagnostics for UNOPTFLAT warnings. This includes for each loop, the 10 widest
variables in the loop, and the 10 most fanned out variables in the loop. These are
candidates for splitting into multiple variables to break the loop.

In addition produces a GraphViz DOT file of the entire strongly connected components
within the source associated with each loop. This is produced irrespective of whether
--dump-tree is set. Such graphs may help in analyzing the problem, but can be very
large indeed.

Various commands exist for viewing and manipulating DOT files. For example the dot
command can be used to convert a DOT file to a PDF for printing. For example:

dot -Tpdf -O Vt_unoptflat_simple_2_35_unoptflat.dot

will generate a PDF Vt_unoptflat_simple_2_35_unoptflat.dot.pdf from the DOT file.

--savable
Enable including save and restore functions in the generated model.

The user code must create a VerilatedSerialize or VerilatedDeserialze object then
calling the << or >> operators on the generated model and any other data the process
needs saved/restored. For example:

void save_model(const char* filenamep) {
VerilatedSave os;
os.open(filenamep);
os << main_time; // user code must save the timestamp, etc
os << *topp;
}
void restore_model(const char* filenamep) {
VerilatedRestore os;
os.open(filenamep);
os >> main_time;
os >> *topp;
}

--sc
Specifies SystemC output mode; see also --cc.

--stats
Creates a dump file with statistics on the design in {prefix}__stats.txt.

--stats-vars
Creates more detailed statistics including a list of all the variables by size (plain
--stats just gives a count). See --stats, which is implied by this.

-sv Specifies SystemVerilog language features should be enabled; equivalent to "--language
1800-2005". This option is selected by default, it exists for compatibility with
other simulators.

+systemverilogext+ext
A synonym for "+1800-2012ext+"ext.

--top-module topname
When the input Verilog contains more than one top level module, specifies the name of
the top level Verilog module to become the top, and sets the default for if --prefix
is not used. This is not needed with standard designs with only one top.

--trace
Adds waveform tracing code to the model. Verilator will generate additional
{prefix}__Trace*.cpp files that will need to be compiled. In addition
verilated_vcd_sc.cpp (for SystemC traces) or verilated_vcd_c.cpp (for both) must be
compiled and linked in. If using the Verilator generated Makefiles, these will be
added as source targets for you. If you're not using the Verilator makefiles, you
will need to add these to your Makefile manually.

Having tracing compiled in may result in some small performance losses, even when
waveforms are not turned on during model execution.

--trace-depth levels
Specify the number of levels deep to enable tracing, for example --trace-level 1 to
only see the top level's signals. Defaults to the entire model. Using a small number
will decrease visibility, but greatly improve runtime and trace file size.

--trace-max-array depth
Rarely needed. Specify the maximum array depth of a signal that may be traced.
Defaults to 32, as tracing large arrays may greatly slow traced simulations.

--trace-max-width width
Rarely needed. Specify the maximum bit width of a signal that may be traced.
Defaults to 256, as tracing large vectors may greatly slow traced simulations.

--no-trace-params
Disable tracing of parameters.

--trace-structs
Enable tracing to show the name of packed structure, union, and packed array fields,
rather than a simgle combined packed bus. Due to VCD file format constraints this may
result in significantly slower trace times and larger trace files.

--trace-underscore
Enable tracing of signals that start with an underscore. Normally, these signals are
not output during tracing. See also --coverage-underscore.

-Uvar
Undefines the given preprocessor symbol.

--unroll-count loops
Rarely needed. Specifies the maximum number of loop iterations that may be unrolled.
See also BLKLOOPINIT warning.

--unroll-stmts statements
Rarely needed. Specifies the maximum number of statements in a loop for that loop to
be unrolled. See also BLKLOOPINIT warning.

--unused-regexp regexp
Rarely needed. Specifies a simple regexp with * and ? that if a signal name matches
will suppress the UNUSED warning. Defaults to "*unused*". Setting it to "" disables
matching.

-V Shows the verbose version, including configuration information compiled into
Verilator. (Similar to perl -V.)

-v filename
Read the filename as a Verilog library. Any modules in the file may be used to
resolve cell instantiations in the top level module, else ignored. Note -v is fairly
standard across Verilog tools.

+verilog1995ext+ext
+verilog2001ext+ext
Synonyms for "+1364-1995ext+"ext and "+1364-2001ext+"ext respectively

-Wall
Enable all warnings, including code style warnings that are normally disabled by
default.

-Werror-message
Convert the specified warning message into an error message. This is generally to
discourage users from violating important site-wide rules, for example
"-Werror-NOUNOPTFLAT".

-Wfuture-message
Rarely needed. Suppress unknown Verilator comments or warning messages with the given
message code. This is used to allow code written with pragmas for a later version of
Verilator to run under a older version; add -Wfuture- arguments for each message code
or comment that the new version supports which the older version does not support.

-Wno-message
Disable the specified warning message. This will override any lint_on directives in
the source, i.e. the warning will still not be printed.

-Wno-lint
Disable all lint related warning messages, and all style warnings. This is equivalent
to "-Wno-ALWCOMBORDER -Wno-CASEINCOMPLETE -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASEWITHX
-Wno-CMPCONST -Wno-ENDLABEL -Wno-IMPLICIT -Wno-LITENDIAN -Wno-PINCONNECTEMPTY
-Wno-PINMISSING -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED -Wno-WIDTH"
plus the list shown for Wno-style.

It is strongly recommended you cleanup your code rather than using this option, it is
only intended to be use when running test-cases of code received from third parties.

-Wno-style
Disable all code style related warning messages (note by default they are already
disabled). This is equivalent to "-Wno-DECLFILENAME -Wno-DEFPARAM -Wno-INCABSPATH
-Wno-PINCONNECTEMPTY -Wno-PINNOCONNECT -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNUSED
-Wno-VARHIDDEN".

-Wno-fatal
When warnings are detected, print them, but do not exit the simulator.

Having warning messages in builds is sloppy. It is strongly recommended you cleanup
your code, use inline lint_off, or use -Wno-... flags rather than using this option.

-Wwarn-message
Enables the specified warning message.

-Wwarn-lint
Enable all lint related warning messages (note by default they are already enabled),
but do not affect style messages. This is equivalent to "-Wwarn-ALWCOMBORDER
-Wwarn-CASEINCOMPLETE -Wwarn-CASEOVERLAP -Wwarn-CASEX -Wwarn-CASEWITHX -Wwarn-CMPCONST
-Wwarn-ENDLABEL -Wwarn-IMPLICIT -Wwarn-LITENDIAN -Wwarn-PINMISSING -Wwarn-REALCVT
-Wwarn-UNSIGNED -Wwarn-WIDTH".

-Wwarn-style
Enable all code style related warning messages. This is equivalent to "-Wwarn
ASSIGNDLY -Wwarn-DECLFILENAME -Wwarn-DEFPARAM -Wwarn-INCABSPATH -Wwarn-PINNOCONNECT
-Wwarn-SYNCASYNCNET -Wwarn-UNDRIVEN -Wwarn-UNUSED -Wwarn-VARHIDDEN".

--x-assign 0
--x-assign 1
--x-assign fast (default)
--x-assign unique
Controls the two-state value that is replaced when an assignment to X is encountered.
--x-assign=fast, the default, converts all Xs to whatever is best for performance.
--x-assign=0 converts all Xs to 0s, and is also fast. --x-assign=1 converts all Xs to
1s, this is nearly as fast as 0, but more likely to find reset bugs as active high
logic will fire. --x-assign=unique will call a function to determine the value, this
allows randomization of all Xs to find reset bugs and is the slowest, but safest for
finding reset bugs in code.

If using --x-assign unique, you may want to seed your random number generator such
that each regression run gets a different randomization sequence. Use the system's
srand48() or for Windows srand() function to do this. You'll probably also want to
print any seeds selected, and code to enable rerunning with that same seed so you can
reproduce bugs.

Note. This option applies only to variables which are explicitly assigned to X in the
Verilog source code. Initial values of clocks are set to 0 unless --x-initial-edge is
specified. Initial values of all other state holding variables are set as though
--x-assign unique had been specified.

--x-initial-edge
Enables emulation of event driven simulators which generally trigger an edge on a
transition from X to 1 ("posedge") or X to 0 ("negedge"). Thus the following code,
where "rst_n" is uninitialized would set "res_n" to "1'b1" when "rst_n" is first set
to zero:

reg res_n = 1'b0;

always @(negedge rst_n) begin
if (rst_n == 1'b0) begin
res_n <= 1'b1;
end
end

In Verilator, by default, uninitialized clocks are given a value of zero, so the above
"always" block would not trigger.

While it is not good practice, there are some designs that rely on X X 0 triggering a
"negedge", particularly in reset sequences. Using --x-initial-edge with Verilator will
replicate this behavior. It will also ensure that X X 1 triggers a "posedge".

Note. Some users have reported that using this option can affect convergence, and that
it may be necessary to use --converge-limit to increase the number of convergence
iterations. This may be another indication of problems with the modelled design that
should be addressed.

-y dir
Add the directory to the list of directories that should be searched for include files
or libraries. The three flags -y, +incdir and -I have similar effect; +incdir and +y
are fairly standard across Verilog tools while -I is an alias for GCC compatibility.

Verilator defaults to the current directory ("-y .") and any specified --Mdir, though
these default paths are used after any user specified directories. This allows '-y
"$(pwd)"' to be used if absolute filenames are desired for error messages instead of
relative filenames.

EXAMPLE C++ EXECUTION

We'll compile this example into C++.

mkdir test_our
cd test_our

cat <<EOF >our.v
module our;
initial begin $display("Hello World"); $finish; end
endmodule
EOF

cat <<EOF >sim_main.cpp
#include "Vour.h"
#include "verilated.h"
int main(int argc, char **argv, char **env) {
Verilated::commandArgs(argc, argv);
Vour* top = new Vour;
while (!Verilated::gotFinish()) { top->eval(); }
delete top;
exit(0);
}
EOF

If you installed Verilator from sources, or a tarball, but not as part of your operating
system (as an RPM), first you need to point to the kit:

export VERILATOR_ROOT=/path/to/where/verilator/was/installed
export PATH=$VERILATOR_ROOT/bin:$PATH

Now we run Verilator on our little example.

verilator -Wall --cc our.v --exe sim_main.cpp

We can see the source code under the "obj_dir" directory. See the FILES section below for
descriptions of some of the files that were created.

ls -l obj_dir

We then can compile it

cd obj_dir
make -j -f Vour.mk Vour

(Verilator included a default compile rule and link rule, since we used --exe and passed a
.cpp file on the Verilator command line. You can also write your own compile rules, as
we'll show in the SYSTEMC section.)

And now we run it

cd ..
obj_dir/Vour

And we get as output

Hello World
- our.v:2: Verilog $finish

Really, you're better off writing a Makefile to do all this for you. Then, when your
source changes it will automatically run all of these steps. See the test_c directory in
the distribution for an example.

EXAMPLE SYSTEMC EXECUTION

This is an example similar to the above, but using SystemC.

mkdir test_our_sc
cd test_our_sc

cat <<EOF >our.v
module our (clk);
input clk; // Clock is required to get initial activation
always @ (posedge clk)
begin $display("Hello World"); $finish; end
endmodule
EOF

cat <<EOF >sc_main.cpp
#include "Vour.h"
int sc_main(int argc, char **argv) {
Verilated::commandArgs(argc, argv);
sc_clock clk ("clk",10, 0.5, 3, true);
Vour* top;
top = new Vour("top"); // SP_CELL (top, Vour);
top->clk(clk); // SP_PIN (top, clk, clk);
while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
delete top;
exit(0);
}
EOF

If you installed Verilator from sources, or a tarball, but not as part of your operating
system (as an RPM), first you need to point to the kit:

export VERILATOR_ROOT=/path/to/where/verilator/was/installed
export PATH=$VERILATOR_ROOT/bin:$PATH

Now we run Verilator on our little example.

verilator -Wall --sc our.v

We then can compile it

make -j -f Vour.mk Vour__ALL.a
make -j -f Vour.mk ../sc_main.o verilated.o

And link with SystemC. Note your path to the libraries may vary, depending on the
operating system.

export SYSTEMC_LIBDIR=/path/to/where/libsystemc.a/exists
export LD_LIBRARY_PATH=$SYSTEMC_LIBDIR:$LD_LIBRARY_PATH
# Might be needed if SystemC 2.3.0
export SYSTEMC_CXX_FLAGS=-pthread

g++ -L$SYSTEMC_LIBDIR ../sc_main.o Vour__ALL*.o verilated.o \
-o Vour -lsystemc

And now we run it

cd ..
obj_dir/Vour

And we get the same output as the C++ example:

Hello World
- our.v:2: Verilog $finish

Really, you're better off using a Makefile to do all this for you. Then, when your source
changes it will automatically run all of these steps. See the test_sc directory in the
distribution for an example.

BENCHMARKING & OPTIMIZATION

For best performance, run Verilator with the "-O3 --x-assign=fast --noassert" flags. The
-O3 flag will require longer compile times, and --x-assign=fast may increase the risk of
reset bugs in trade for performance; see the above documentation for these flags.

Minor Verilog code changes can also give big wins. You should not have any UNOPTFLAT
warnings from Verilator. Fixing these warnings can result in huge improvements; one user
fixed their one UNOPTFLAT warning by making a simple change to a clock latch used to gate
clocks and gained a 60% performance improvement.

Beyond that, the performance of a Verilated model depends mostly on your C++ compiler and
size of your CPU's caches.

By default, the lib/verilated.mk file has optimization turned off. This is for the
benefit of new users, as it improves compile times at the cost of runtimes. To add
optimization as the default, set one of three variables, OPT, OPT_FAST, or OPT_SLOW
lib/verilated.mk. Or, use the -CFLAGS and/or -LDFLAGS option on the verilator command
line to pass the flags directly to the compiler or linker. Or, just for one run, pass
them on the command line to make:

make OPT_FAST="-O2" -f Vour.mk Vour__ALL.a

OPT_FAST specifies optimizations for those programs that are part of the fast path, mostly
code that is executed every cycle. OPT_SLOW specifies optimizations for slow-path files
(plus tracing), which execute only rarely, yet take a long time to compile with
optimization on. OPT specifies overall optimization and affects all compiles, including
those OPT_FAST and OPT_SLOW affect. For best results, use OPT="-O2", and link with
"-static". Nearly the same results can be had with much better compile times with
OPT_FAST="-O1 -fstrict-aliasing". Higher optimization such as "-O3" may help, but gcc
compile times may be excessive under O3 on even medium sized designs. Alternatively, some
larger designs report better performance using "-Os".

Unfortunately, using the optimizer with SystemC files can result in compiles taking
several minutes. (The SystemC libraries have many little inlined functions that drive the
compiler nuts.)

For best results, use GCC 3.3 or newer. GCC 3.2 and earlier have optimization bugs around
pointer aliasing detection, which can result in 2x performance losses.

If you will be running many simulations on a single compile, investigate feedback driven
compilation. With GCC, using -fprofile-arcs, then -fbranch-probabilities will yield
another 15% or so.

Modern compilers also support link-time optimization (LTO), which can help especially if
you link in DPI code. To enable LTO on GCC, pass "-flto" in both compilation and link.
Note LTO may cause excessive compile times on large designs.

If you are using your own makefiles, you may want to compile the Verilated code with
-DVL_INLINE_OPT=inline. This will inline functions, however this requires that all cpp
files be compiled in a single compiler run.

You may uncover further tuning possibilities by profiling the Verilog code. Use
Verilator's --profile-cfuncs, then GCC's -g -pg. You can then run either oprofile or
gprof to see where in the C++ code the time is spent. Run the gprof output through
verilator_profcfunc and it will tell you what Verilog line numbers on which most of the
time is being spent.

When done, please let the author know the results. I like to keep tabs on how Verilator
compares, and may be able to suggest additional improvements.

Use verilator online using onworks.net services