.. Copyright 2003-2024 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 verilator Arguments =================== The following arguments may be passed to the "verilator" executable. Summary: .. include:: ../_build/gen/args_verilator.rst .. option:: Specifies the Verilog file containing the top module to be Verilated. .. option:: Used with :vlopt:`--exe` to specify optional C++ files to be linked in with the Verilog code. The file path should either be absolute, or relative to where the make will be executed from, or add to your makefile's VPATH the appropriate directory to find the file. See also :vlopt:`-CFLAGS` and :vlopt:`-LDFLAGS` options, which are useful when the C++ files need special compiler flags. .. option:: Specifies optional object or library files to be linked with the Verilog code, as a shorthand for :vlopt:`-LDFLAGS \ <-LDFLAGS>`. The file path should either be absolute, or relative to where the make will be executed from, or add the appropriate directory to your makefile's VPATH to find the file. If any files are specified in this way, Verilator will include a make rule that uses these files when linking the module's executable. This generally is only useful when used with the :vlopt:`--exe` option. .. option:: +1364-1995ext+ .. option:: +1364-2001ext+ .. option:: +1364-2005ext+ .. option:: +1800-2005ext+ .. option:: +1800-2009ext+ .. option:: +1800-2012ext+ .. option:: +1800-2017ext+ .. option:: +1800-2023ext+ Specifies the language standard to be used with a specific filename extension, . For compatibility with other simulators, see also the synonyms :vlopt:`+verilog1995ext+\`, :vlopt:`+verilog2001ext+\`, and :vlopt:`+systemverilogext+\`. For any source file, the language specified by these options takes precedence over any language specified by the :vlopt:`--default-language` or :vlopt:`--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``: .. code-block:: bash verilator ... +1364-1995ext+v a.v +1364-2001ext+v b.v These options 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* the set of keywords to be recognized. This also controls some error messages that vary between language standards. At present, Verilator tends to be overly permissive, e.g., it will accept many grammar and other semantic extensions which might not be legal when set to an older standard. .. option:: --assert Enable all assertions. Implies :vlopt:`--assert-case`. .. option:: --assert-case Enable unique/unique0/priority case related checks. .. option:: --autoflush After every $display or $fdisplay, flush the output stream. This ensures that messages will appear immediately but may reduce performance. For best performance, call :code:`fflush(stdout)` occasionally in the C++ main loop. Defaults to off, which will buffer output as provided by the normal C/C++ standard library IO. .. option:: --bbox-sys Black box any unknown $system task or function calls. System tasks will become no-operations, and system functions will be replaced with 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. Using this argument will likely cause incorrect simulation. .. option:: --bbox-unsup Black box some unsupported language features, currently UDP tables, the cmos and tran gate primitives, deassign statements, and mixed edge errors. This may enable linting of the rest of the design even when unsupported constructs are present. Using this argument will likely cause incorrect simulation. .. option:: --binary Create a Verilated simulator binary. Alias for :vlopt:`--main` :vlopt:`--exe` :vlopt:`--build` :vlopt:`--timing`. See also :vlopt:`-j`. .. option:: --build After generating the SystemC/C++ code, Verilator will invoke the toolchain to build the model library (and executable when :vlopt:`--exe` is also used). Verilator manages the build itself, and for this --build requires GNU Make to be available on the platform. :vlopt:`--build` cannot be specified when using :vlopt:`-E`, :vlopt:`--dpi-hdr-only`, :vlopt:`--lint-only`, or :vlopt:`--xml-only`. .. option:: --build-dep-bin Rarely needed. 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. Defaults to the full path to the Verilator binary. This option was named `--bin` before version 4.228. .. option:: --build-jobs [] Specify the level of parallelism for :vlopt:`--build`. If zero, uses the number of threads in the current hardware. Otherwise, the must be a positive integer specifying the maximum number of parallel build jobs. This forms the :command:`make` option ``-j`` value, unless the :option:`MAKEFLAGS` environment variable contains ``-jobserver-auth``, in which case Verilator assumes that make's jobserver is being used. See also :vlopt:`-j`. .. option:: --cc Specify C++ without SystemC output mode; see also the :vlopt:`--sc` option. .. option:: -CFLAGS Add specified C compiler argument to the generated makefiles. For multiple flags, either pass them as a single argument with space separators quoted in the shell (:command:`-CFLAGS "-a -b"`), or use multiple -CFLAGS options (:command:`-CFLAGS -a -CFLAGS -b`). When make is run on the generated makefile, these will be passed to the C++ compiler (g++/clang++/msvc++). .. option:: --clk With :vlopt:`--clk`, the specified signal is marked as a clock signal. The provided signal name is specified using a RTL hierarchy path. For example, v.foo.bar. If the signal is the input to top-module, then directly provide the signal name. Alternatively, use a :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the signal directly. If clock signals are assigned to vectors and later used as individual bits, Verilator will attempt to decompose the vector and connect the single-bit clock signals. In versions before 5.000, the clocker attribute is useful in cases where Verilator does not properly distinguish clock signals from other data signals. Using clocker will cause the signal indicated to be considered a clock, and remove it from the combinatorial logic reevaluation checking code. This may greatly improve performance. .. option:: --no-clk Prevent the specified signal from being marked as a clock. See :vlopt:`--clk`. .. option:: --compiler Enables workarounds for the specified C++ compiler (list below). This does not change any performance tuning options, but it may in the future. This also does not change default compiler flags; these are determined when Verilator was configured. clang Tune for clang. This may reduce execution speed as it enables several workarounds to avoid silly hard-coded 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 hard-coded 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. .. option:: --compiler-include Specifies additional headers to be included in the final PCH header. It is required to add them to this header, due to compilers' limitation that allow only one precompiled header per compilation. Use this instead of ::vlopt:`-CFLAGS` with `-include `. .. option:: --converge-limit Rarely needed. Specifies the maximum number of runtime iterations before creating a model failed to converge error. Defaults to 100. .. option:: --coverage Enables all forms of coverage, an alias for :vlopt:`--coverage-line` :vlopt:`--coverage-toggle` :vlopt:`--coverage-user`. .. option:: --coverage-line Enables basic block line coverage analysis. See :ref:`Line Coverage`. .. option:: --coverage-max-width Rarely needed. Specify the maximum bit width of a signal subject to toggle coverage. Defaults to 256, as covering large vectors may greatly slow coverage simulations. .. option:: --coverage-toggle Enables adding signal toggle coverage. See :ref:`Toggle Coverage`. .. option:: --coverage-underscore Enable coverage of signals that start with an underscore. Normally, these signals are not covered. See also :vlopt:`--trace-underscore` option. .. option:: --coverage-user Enables adding user-inserted functional coverage. See :ref:`User Coverage`. .. option:: -D= Defines the given preprocessor symbol. Similar to :vlopt:`+define <+define+>`, but does not allow multiple definitions with a single option using plus signs. "+define" is relatively standard across Verilog tools, while "-D" is similar to :command:`gcc -D`. .. option:: --debug Run under debug. * Select the debug executable of Verilator (if available). This generally is a less-optimized binary with symbols present (so GDB can be used on it). * Enable debugging messages (equivalent to :vlopt:`--debugi 3 <--debugi>`). * Enable internal assertions (equivalent to :vlopt:`--debug-check`). * Enable intermediate form dump files (equivalent to :vlopt:`--dumpi-tree 3 <--dumpi-tree>`). * Leak to make node numbers unique (equivalent to :vlopt:`--debug-leak <--no-debug-leak>`. * Call abort() instead of exit() if there are any errors (so GDB can see the program state). .. option:: --debug-check Rarely needed. Enable internal debugging assertion checks, without changing debug verbosity. Enabled automatically with :vlopt:`--debug` option. .. option:: --no-debug-leak In :vlopt:`--debug` mode, by default, Verilator intentionally leaks AstNode instances instead of freeing them, so that each node pointer is unique in the resulting tree files and dot files. This option disables the leak. This may avoid out-of-memory errors when Verilating large models in :vlopt:`--debug` mode. Outside of :vlopt:`--debug` mode, AstNode instances should never be leaked, and this option has no effect. .. option:: --debugi Rarely needed - for developer use. Set the internal debugging level globally to the specified debug level (1-10). Higher levels produce more detailed messages. .. option:: --debugi- Rarely needed - for developer use. Set the specified Verilator source file to the specified level (e.g., :vlopt:`--debugi-V3Width 9 <--debugi>`). Higher levels produce more detailed messages. See :vlopt:`--debug` for other implications of enabling debug. .. option:: --decorations none .. option:: --decorations medium .. option:: --decorations node When creating output Verilated code, set level of comment and whitespace decoration. With "--decorations none", Minimize comments, white space, symbol names, and other decorative items, at the cost of reduced readability. This may assist C++ compile times. This will not typically change the ultimate model's performance, but may in some cases. See also :vlopt:`--no-decoration` option. With "--decorations medium", The default, put a small amount of comments and white space, for typical level of readability. With "--decorations node", Include comments indicating what caused generation of the following text, including what node pointer (corresponding to :vlopt:`--dump-tree` .tree printed data), and the source Verilog filename and line number. If subsequent following statements etc have the same filename/line number these comments are omitted. This enables easy debug when looking at the C++ code to determine what Verilog source may be related. As node pointers are not stable between different Verilator runs, this may harm compile caching and should only be used for debug. .. option:: --no-decoration Alias for ``--decorations none``. .. option:: --default-language Select the language used by default when first processing each Verilog file. The language value must be "VAMS", "1364-1995", "1364-2001", "1364-2001-noconfig", "1364-2005", "1800-2005", "1800-2009", "1800-2012", "1800-2017", "1800-2023", or "1800+VAMS". Any language associated with a particular file extension (see the various +*\ ext+ options) will be used in preference to the language specified by :vlopt:`--default-language`. The :vlopt:`--default-language` 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 :code:`\`begin_keywords`. For legacy mixed-language designs, the various ``+ext+`` options should be used. If no language is specified, either by this option or ``+ext+`` options, then the latest SystemVerilog language (IEEE 1800-2023) is used. .. option:: +define+= .. option:: +define+=[+=][...] Defines the given preprocessor symbol, or multiple symbols if separated by plus signs. Similar to :vlopt:`-D <-D>`; +define is relatively standard across Verilog tools while :vlopt:`-D <-D>` is similar to :command:`gcc -D`. .. option:: --dpi-hdr-only Only generate the DPI header file. This option does not affect on the name or location of the emitted DPI header file, it is output in :vlopt:`--Mdir` as it would be without this option. .. option:: --dump-defines With :vlopt:`-E`, suppress normal output, and instead print a list of all defines existing at the end of pre-processing the input files. Similar to GCC "-dM" option. This also gives you a way of finding out what is predefined in Verilator using the command: .. code-block:: bash touch foo.v ; verilator -E --dump-defines foo.v .. option:: --dump-dfg Rarely needed. Enable dumping DfgGraph .dot debug files with dumping level 3. .. option:: --dump-graph Rarely needed. Enable dumping V3Graph .dot debug files with dumping level 3. Before Verilator 4.228, :vlopt:`--dump-tree` used to include this option. .. option:: --dump-tree Rarely needed. Enable dumping Ast .tree debug files with dumping level 3, which dumps the standard critical stages. For details on the format, see the Verilator Internals manual. :vlopt:`--dump-tree` is enabled automatically with :vlopt:`--debug`, so :vlopt:`--debug --no-dump-tree <--dump-tree>` may be useful if the dump files are large and not desired. .. option:: --dump-tree-json Rarely needed. Enable dumping Ast .json.tree debug files with dumping level 3, which dumps the standard critical stages. For details on the format, see the Verilator Internals manual. .. option:: --dump-tree-dot Rarely needed. Enable dumping Ast .tree.dot debug files in Graphviz Dot format. This option implies :vlopt:`--dump-tree`, unless :vlopt:`--dumpi-tree` was passed explicitly. .. option:: --dump-tree-addrids Rarely needed - for developer use. Replace AST node addresses with short identifiers in tree dumps to enhance readability. Each unique pointer value is mapped to a unique identifier, but note that this is not necessarily unique per node instance as an address might get reused by a newly allocated node after a node with the same address has been dumped and then freed. .. option:: --dump- Rarely needed - for developer use. Enable all dumping in the given source file at level 3. .. option:: --dumpi-dfg Rarely needed - for developer use. Set the internal DfgGraph dumping level globally to the specified value. .. option:: --dumpi-graph Rarely needed - for developer use. Set internal V3Graph dumping level globally to the specified value. .. option:: --dumpi-tree Rarely needed - for developer use. Set internal Ast dumping level globally to the specified value. .. option:: --dumpi-tree-json Rarely needed - for developer use. Set internal Ast JSON dumping level globally to the specified value. .. option:: --dumpi- Rarely needed - for developer use. Set the dumping level in the specified Verilator source file to the specified value (e.g., `--dumpi-V3Order 9`). Level 0 disables dumps and is equivalent to `--no-dump-`. Level 9 enables the dumping of everything. .. option:: -E Preprocess the source code, but do not compile, similar to C++ preprocessing using :command:`gcc -E`. Output is written to standard out. Beware of enabling debugging messages, as they will also go to standard out. See :vlopt:`--no-std`, which is implied by this. See also :vlopt:`--dump-defines`, :vlopt:`-P`, and :vlopt:`--pp-comments` options. .. option:: --emit-accessors Emit getter and setter methods for each top-level signal in the model top class. Signals are still available as public members, but with the `__Vm_sig_` prefix. .. option:: --error-limit After this number of errors are encountered during Verilator run, exit. Warnings are not counted in this limit. Defaults to 50. It does not affect simulation runtime errors, for those, see :vlopt:`+verilator+error+limit+\`. .. option:: --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. .. option:: --expand-limit Rarely needed. Fine-tune optimizations to set the maximum size of an expression in 32-bit words to expand into separate word-based statements. .. option:: -F Read the specified file, and act as if all text inside it was specified as command line arguments. Any relative paths are relative to the directory containing the specified file. See also :vlopt:`-f` option. Note :option:`-F` is relatively standard across Verilog tools. .. option:: -f Read the specified file, and act as if all text inside it was specified as command line arguments. Any relative paths are relative to the current directory. See also :vlopt:`-F` option. Note :option:`-f` is relatively standard across Verilog tools. The file may contain :code:`//` comments which are ignored until the end of the line. It may also contain :code:`/* .. */` comments which are ignored, be cautious that wildcards are not handled in -f files, and that :code:`directory/*` is the beginning of a comment, not a wildcard. Any :code:`$VAR`, :code:`$(VAR)`, or :code:`${VAR}` will be replaced with the specified environment variable. .. option:: -FI Force include of the specified C++ header file. All generated C++ files will insert a #include of the specified file before any other includes. The specified file might be used to contain define prototypes of custom :code:`VL_VPRINTF` functions, and may need to include :file:`verilatedos.h` as this file is included before any other standard includes. .. option:: --flatten Force flattening of the design's hierarchy, with all modules, tasks, and functions inlined. Typically used with :vlopt:`--xml-only`. Flattening large designs may require significant CPU time, memory and storage. .. option:: -fno-acyc-simp .. option:: -fno-assemble .. option:: -fno-case .. option:: -fno-combine .. option:: -fno-const .. options: -fno-const-before-dfg Do not apply any global expression folding prior to the DFG pass. This option is solely for the purpose of DFG testing and should not be used otherwise. .. option:: -fno-const-bit-op-tree .. option:: -fno-dedup .. option:: -fno-dfg Disable all use of the DFG-based combinational logic optimizer. Alias for :vlopt:`-fno-dfg-pre-inline` and :vlopt:`-fno-dfg-post-inline`. .. option:: -fno-dfg-peephole Disable the DFG peephole optimizer. .. option:: -fno-dfg-peephole- Disable individual DFG peephole optimizer pattern. .. option:: -fno-dfg-pre-inline Do not apply the DFG optimizer before inlining. .. option:: -fno-dfg-post-inline Do not apply the DFG optimizer after inlining. .. option:: -fno-expand .. option:: -fno-func-opt .. option:: -fno-func-opt-balance-cat .. option:: -fno-func-opt-split-cat .. option:: -fno-gate .. option:: -fno-inline .. option:: -fno-life .. option:: -fno-life-post .. option:: -fno-localize .. option:: -fno-merge-cond .. option:: -fno-merge-cond-motion .. option:: -fno-merge-const-pool .. option:: -fno-reloop .. option:: -fno-reorder .. option:: -fno-split .. option:: -fno-subst .. option:: -fno-subst-const .. option:: -fno-table Rarely needed. Disables one of the internal optimization steps. These are typically used only when recommended by a maintainer to help debug or work around an issue. .. option:: -future0