VeniVidiVici
/
verilator
mirror of https://github.com/verilator/verilator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Cleanup documentated option sort order, and enforce with test

This commit is contained in:
Wilson Snyder 2025-04-26 17:14:49 -04:00
parent c3d1c3b952
commit c9be36911f
10 changed files with 607 additions and 525 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
bin/verilator
View File

@ -341,11 +341,12 @@ detailed descriptions of these arguments.
--no-debug-leak Disable leaking memory in --debug mode
--debugi <level> Enable debugging at a specified level
--debugi-<srcfile> <level> Enable debugging a source file at a level
--decorations <level> Set output comment and spacing level
--no-decoration Disable comments and lower spacing level
--decorations <level> Set output comment and spacing level
--default-language <lang> Default language to parse
+define+<var>=<value> Set preprocessor define
--dpi-hdr-only Only produce the DPI header file
--dump-<srcfile> Enable dumping everything in source file
--dump-defines Show preprocessor defines with -E
--dump-dfg Enable dumping DfgGraphs to .dot files
--dump-graph Enable dumping V3Graphs to .dot files
@ -353,12 +354,11 @@ detailed descriptions of these arguments.
--dump-tree-addrids Use short identifiers instead of addresses
--dump-tree-dot Enable dumping Ast .tree.dot debug files
--dump-tree-json Enable dumping Ast .tree.json files and .tree.meta.json file
--dump-<srcfile> Enable dumping everything in source file
--dumpi-<srcfile> <level> Enable dumping everything in source file at level
--dumpi-dfg <level> Enable dumping DfgGraphs to .dot files at level
--dumpi-graph <level> Enable dumping V3Graphs to .dot files at level
--dumpi-tree <level> Enable dumping Ast .tree files at level
--dumpi-tree-json <level> Enable dumping Ast .tree.json files at level
--dumpi-<srcfile> <level> Enable dumping everything in source file at level
-E Preprocess, but do not compile
--emit-accessors Emit getter and setter methods for model top class
--error-limit <value> Abort after this number of errors
@ -390,8 +390,8 @@ detailed descriptions of these arguments.
--no-json-edit-nums Don't dump editNum in .tree.json files
--no-json-ids Don't use short identifiers instead of adresses/paths in .tree.json
--json-only Create JSON parser output (.tree.json and .meta.json)
--json-only-output .tree.json output filename
--json-only-meta-output .tree.meta.json output filename
--json-only-output .tree.json output filename
--l2-name <value> Verilog scope name of the top module
--language <lang> Default language standard to parse
-LDFLAGS <flags> Linker pre-object arguments for makefile
@ -399,20 +399,20 @@ detailed descriptions of these arguments.
+libext+<ext>+[ext]... Extensions for finding modules
--lint-only Lint, but do not make output
--localize-max-size <value> Tune localize optimization variable size
--make <build-tool> Generate scripts for specified build tool
-MAKEFLAGS <flags> Arguments to pass to make during --build
--main Generate C++ main() file
--main-top-name Specify top name passed to Verilated model in generated C++ main
--make <build-tool> Generate scripts for specified build tool
-MAKEFLAGS <flags> Arguments to pass to make during --build
--max-num-width <value> Maximum number width (default: 64K)
--Mdir <directory> Name of output object directory
--MMD Create .d dependency files
--mod-prefix <topname> Name to prepend to lower classes
--MP Create phony dependency targets
+notimingchecks Ignored
-o <executable> Name of final executable
-O0 Disable optimizations
-O3 High-performance optimizations
-O<optimization-letter> Selectable optimizations
-o <executable> Name of final executable
--output-groups <numfiles> Group .cpp files into larger ones
--output-split <statements> Split .cpp files into pieces
--output-split-cfuncs <statements> Split model functions
@ -467,10 +467,10 @@ detailed descriptions of these arguments.
--threads <threads> Enable multithreading
--threads-dpi <mode> Enable multithreaded DPI
--threads-max-mtasks <mtasks> Tune maximum mtask partitioning
--timing Enable timing support
--no-timing Disable timing support
--timescale <timescale> Sets default timescale
--timescale-override <timescale> Overrides all timescales
--timing Enable timing support
--no-timing Disable timing support
--top <topname> Alias of --top-module
--top-module <topname> Name of top-level input module
--trace Enable VCD waveform creation
@ -483,9 +483,9 @@ detailed descriptions of these arguments.
--trace-saif Enable SAIF file creation
--trace-structs Enable tracing structure names
--trace-threads <threads> Enable FST waveform creation on separate threads
--trace-vcd Enable VCD waveform creation
--no-trace-top Do not emit traces for signals in the top module generated by verilator
--trace-underscore Enable tracing of _signals
--trace-vcd Enable VCD waveform creation
-U<var> Undefine preprocessor define
--no-unlimited-stack Don't disable stack size limit
--unroll-count <loops> Tune maximum loop iterations
@ -494,8 +494,8 @@ detailed descriptions of these arguments.
-V Verbose version and config
-v <filename> Verilog library
--valgrind Run Verilator under valgrind
--verilate-jobs Job threads for Verilation stage
--no-verilate Skip Verilation and just compile previously Verilated code
--verilate-jobs Job threads for Verilation stage
+verilog1995ext+<ext> Synonym for +1364-1995ext+<ext>
+verilog2001ext+<ext> Synonym for +1364-2001ext+<ext>
--version Show program version and exits
@ -528,9 +528,9 @@ description of these arguments.
=for VL_SPHINX_EXTRACT "_build/gen/args_verilated.rst"
+verilator+coverage+file+<filename> Set coverage output filename
+verilator+debug Enable debugging
+verilator+debugi+<value> Enable debugging at a level
+verilator+coverage+file+<filename> Set coverage output filename
+verilator+error+limit+<value> Set error limit
+verilator+help Show help
+verilator+noassert Disable assert checking

10
docs/guide/exe_sim.rst
View File

@ -47,6 +47,11 @@ Summary:
Display help and exit.
.. option:: +verilator+noassert
Disable assert checking per runtime argument. This is the same as
calling :code:`VerilatedContext*->assertOn(false)` in the model.
.. option:: +verilator+prof+exec+file+<filename>
When a model was Verilated using :vlopt:`--prof-exec`, sets the
@ -110,11 +115,6 @@ Summary:
simulation runtime random seed value. If zero or not specified picks a
value from the system random number generator.
.. option:: +verilator+noassert
Disable assert checking per runtime argument. This is the same as
calling :code:`VerilatedContext*->assertOn(false)` in the model.
.. option:: +verilator+V
Shows the verbose version, including configuration information.

407
docs/guide/exe_verilator.rst
View File

@ -1,8 +1,9 @@
.. Copyright 2003-2025 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator Arguments
===================
=====================
verilator Arguments
=====================
The following arguments may be passed to the "verilator" executable.
@ -11,20 +12,6 @@ Summary:
.. include:: ../_build/gen/args_verilator.rst
.. option:: <file.v>
Specifies the Verilog file containing the top module to be Verilated.
.. option:: <file.c/.cc/.cpp/.cxx>
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:: <file.a/.o/.so>
Specifies optional object or library files to be linked with the
@ -37,6 +24,20 @@ Summary:
rule that uses these files when linking the module's executable. This
generally is only useful when used with the :vlopt:`--exe` option.
.. option:: <file.c/.cc/.cpp/.cxx>
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:: <file.v>
Specifies the Verilog file containing the top module to be Verilated.
.. option:: +1364-1995ext+<ext>
.. option:: +1364-2001ext+<ext>
@ -331,11 +332,11 @@ Summary:
detailed messages. See :vlopt:`--debug` for other implications of
enabling debug.
.. option:: --decorations none
.. option:: --no-decoration
.. option:: --decorations medium
Alias for ``--decorations none``.
.. option:: --decorations node
.. option:: --decorations <level>
When creating output Verilated code, set level of comment and whitespace
decoration.
@ -362,10 +363,6 @@ Summary:
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 <value>
Select the language used by default when first processing each
@ -402,6 +399,11 @@ Summary:
name or location of the emitted DPI header file, it is output in
:vlopt:`--Mdir` as it would be without this option.
.. option:: --dump-<srcfile>
Rarely needed - for developer use. Enable all dumping in the given
source file at level 3.
.. option:: --dump-defines
With :vlopt:`-E`, suppress normal output, and instead print a list of
@ -433,18 +435,6 @@ Summary:
: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
@ -454,10 +444,24 @@ Summary:
by a newly allocated node after a node with the same address has been
dumped and then freed.
.. option:: --dump-<srcfile>
.. option:: --dump-tree-dot
Rarely needed - for developer use. Enable all dumping in the given
source file at level 3.
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-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:: --dumpi-<srcfile> <level>
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-<srcfile>`. Level 9 enables the dumping of everything.
.. option:: --dumpi-dfg <level>
@ -479,13 +483,6 @@ Summary:
Rarely needed - for developer use. Set internal Ast JSON dumping level
globally to the specified value.
.. option:: --dumpi-<srcfile> <level>
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-<srcfile>`. Level 9 enables the dumping of everything.
.. option:: -E
Preprocess the source code, but do not compile, similar to C++
@ -569,7 +566,7 @@ Summary:
.. option:: -fno-const
.. options: -fno-const-before-dfg
.. option:: -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
@ -592,14 +589,14 @@ Summary:
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-dfg-pre-inline
Do not apply the DFG optimizer before inlining.
.. option:: -fno-expand
.. option:: -fno-func-opt
@ -724,14 +721,6 @@ Summary:
Generate a true-random key suitable for use with :vlopt:`--protect-key`,
print it, and exit immediately.
.. option:: --getenv <variable>
If the variable is declared in the environment, print it and exit
immediately. Otherwise, if it's built into Verilator
(e.g., VERILATOR_ROOT), print that and exit immediately. Otherwise, print
a newline and exit immediately. This can be useful in makefiles. See
also :vlopt:`-V`, and the various :file:`*.mk` files.
.. option:: --get-supported <feature>
If the given feature is supported, print "1" and exit
@ -741,6 +730,14 @@ Summary:
Feature may be one of the following: COROUTINES, SYSTEMC.
.. option:: --getenv <variable>
If the variable is declared in the environment, print it and exit
immediately. Otherwise, if it's built into Verilator
(e.g., VERILATOR_ROOT), print that and exit immediately. Otherwise, print
a newline and exit immediately. This can be useful in makefiles. See
also :vlopt:`-V`, and the various :file:`*.mk` files.
.. option:: --help
Displays this message and program version and exits.
@ -803,6 +800,15 @@ Summary:
must be a positive integer specifying the maximum number of parallel
build jobs.
.. option:: --no-json-edit-nums
Don't dump edit number in .tree.json files. This may make the file more
run-to-run stable for easier comparison.
.. option:: --no-json-ids
Don't use short identifiers instead of addresses/paths in .tree.json.
.. option:: --json-only
Create JSON output only, do not create any other output.
@ -826,15 +832,6 @@ Summary:
Specifies the filename for the main output file (`.tree.json`) of --json-only.
Using this option automatically sets :vlopt:`--json-only`.
.. option:: --no-json-edit-nums
Don't dump edit number in .tree.json files. This may make the file more
run-to-run stable for easier comparison.
.. option:: --no-json-ids
Don't use short identifiers instead of addresses/paths in .tree.json.
.. option:: --l2-name <value>
Instead of using the module name when showing Verilog scope, use the
@ -908,30 +905,6 @@ Summary:
Rarely needed. Set the maximum variable size in bytes for it to be
subject to localizing-to-stack optimization. Defaults to 1024.
.. option:: --make <build-tool>
Generates a script for the specified build tool.
Supported values are ``gmake`` for GNU Make, or ``cmake`` for CMake, or
``json`` to create a JSON file to feed other build tools.
Multiple options can be specified together. If no build tool is
specified, gmake is assumed. The executable of gmake can be configured
via the environment variable :option:`MAKE`.
When using :vlopt:`--build`, Verilator takes over the responsibility of
building the model library/executable. For this reason :option:`--make`
cannot be specified when using :vlopt:`--build`.
.. option:: -MAKEFLAGS <string>
When using :vlopt:`--build`, add the specified argument to the invoked
make command line. For multiple flags, either pass them as a single
argument with space separators quoted in the shell (e.g. ``-MAKEFLAGS
"-a -b"``), or use multiple -MAKEFLAGS arguments
(e.g. ``-MAKEFLAGS -l -MAKEFLAGS -k``). Use of this option should not be
required for simple builds using the host toolchain.
.. option:: --main
Generates a top-level C++ main() file that supports parsing arguments,
@ -957,6 +930,30 @@ Summary:
If the string ``"-"`` is used, no top level scope is added.
.. option:: --make <build-tool>
Generates a script for the specified build tool.
Supported values are ``gmake`` for GNU Make, or ``cmake`` for CMake, or
``json`` to create a JSON file to feed other build tools.
Multiple options can be specified together. If no build tool is
specified, gmake is assumed. The executable of gmake can be configured
via the environment variable :option:`MAKE`.
When using :vlopt:`--build`, Verilator takes over the responsibility of
building the model library/executable. For this reason :option:`--make`
cannot be specified when using :vlopt:`--build`.
.. option:: -MAKEFLAGS <string>
When using :vlopt:`--build`, add the specified argument to the invoked
make command line. For multiple flags, either pass them as a single
argument with space separators quoted in the shell (e.g. ``-MAKEFLAGS
"-a -b"``), or use multiple -MAKEFLAGS arguments
(e.g. ``-MAKEFLAGS -l -MAKEFLAGS -k``). Use of this option should not be
required for simple builds using the host toolchain.
.. option:: --max-num-width <value>
Set the maximum number literal width (e.g., in 1024'd22 this
@ -991,6 +988,11 @@ Summary:
Ignored for compatibility with other simulators.
.. option:: -o <executable>
Specify the name for the final executable built if using :vlopt:`--exe`.
Defaults to the :vlopt:`--prefix` if not specified.
.. option:: -O0
Disables optimization of the model.
@ -1011,11 +1013,6 @@ Summary:
is deprecated and the various `-f<optimization>` arguments should be
used instead.
.. option:: -o <executable>
Specify the name for the final executable built if using :vlopt:`--exe`.
Defaults to the :vlopt:`--prefix` if not specified.
.. option:: --no-order-clock-delay
Deprecated and has no effect (ignored).
@ -1107,6 +1104,14 @@ Summary:
position to indicate the corresponding bit of the __out variable has
a value being driven from within the Verilated model.
.. option:: --pins-sc-biguint
Specifies SystemC inputs/outputs greater than 65 bits wide should use
sc_biguint between 65 and 512, and sc_bv from 513 upwards. When
combined with the :vlopt:`--pins-sc-uint` combination, it results in
sc_uint being used between 2 and 64 and sc_biguint being used between 65
and 512.
.. option:: --pins-sc-uint
Specifies SystemC inputs/outputs greater than 2 bits wide should use
@ -1118,14 +1123,6 @@ Summary:
Specifies SystemC inputs/outputs one bit wide should use sc_uint<1>.
.. option:: --pins-sc-biguint
Specifies SystemC inputs/outputs greater than 65 bits wide should use
sc_biguint between 65 and 512, and sc_bv from 513 upwards. When
combined with the :vlopt:`--pins-sc-uint` combination, it results in
sc_uint being used between 2 and 64 and sc_biguint being used between 65
and 512.
.. option:: --pins-uint8
Specifies SystemC inputs/outputs smaller than the
@ -1487,6 +1484,12 @@ Summary:
A synonym for :vlopt:`+1800-2023ext+\<ext\>`.
.. option:: --no-threads
Deprecated and has no effect (ignored).
In versions before 5.004, created a model which was not thread-safe.
.. option:: --threads <threads>
With "--threads 1", the default, the generated model is single-threaded
@ -1495,17 +1498,7 @@ Summary:
threads. See :ref:`Multithreading`. This option also applies to
:vlopt:`--trace-vcd` (but not :vlopt:`--trace-fst`).
.. option:: --no-threads
Deprecated and has no effect (ignored).
In versions before 5.004, created a model which was not thread-safe.
.. option:: --threads-dpi all
.. option:: --threads-dpi none
.. option:: --threads-dpi pure
.. option:: --threads-dpi <mode>
When using :vlopt:`--threads`, controls which DPI imported tasks and
functions are considered thread-safe.
@ -1539,10 +1532,10 @@ Summary:
does not occur before a given module. Default is "1ps/1ps" (to match
SystemC). This is overridden by :vlopt:`--timescale-override`.
.. option:: --timescale-override <timeunit>/<timeprecision>
.. option:: --timescale-override /<timeprecision>
.. option:: --timescale-override <timeunit>/<timeprecision>
Overrides all "\`timescale"s in sources. The timeunit may be left empty
to specify only to override the timeprecision, e.g. "/1fs".
@ -1891,33 +1884,36 @@ Summary:
``-Wwarn-UNUSEDGENVAR`` ``-Wwarn-UNUSEDLOOP`` ``-Wwarn-UNUSEDPARAM``
``-Wwarn-UNUSEDSIGNAL`` ``-Wwarn-VARHIDDEN``.
.. option:: --x-assign 0
.. option:: --x-assign 1
.. option:: --x-assign fast (default)
.. option:: --x-assign unique
.. option:: --x-assign <mode>
Controls the two-state value that is substituted when an explicit X
value is encountered in the source. "--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. Using "--x-assign unique" will result in
all explicit Xs being replaced by a constant value determined at
runtime. The value is determined by calling a function at initialization
time. This enables the randomization of Xs with different seeds on different
executions. This method is the slowest, but safest for finding reset
bugs.
value is encountered in the source.
If using "--x-assign unique", you may want to seed your random number
generator such that each regression run gets a different randomization
sequence. The simplest is to use the :vlopt:`+verilator+seed+\<value\>`
runtime option. Alternatively, use the system's :code:`srand48()` or for
Windows :code:`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.
With "--x-assign 0",
converts all Xs to 0s, and is also fast.
With "--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.
With "--x-assign fast", the default,
converts all Xs to whatever is best for performance.
With "--x-assign unique",
all explicit Xs being replaced by a constant value determined at
runtime. The value is determined by calling a function at
initialization time. This enables the randomization of Xs with
different seeds on different executions. This method is the slowest,
but safest for finding reset bugs.
If using `--x-assign unique`, you may want to seed your random number
generator such that each regression run gets a different randomization
sequence. The simplest is to use the
:vlopt:`+verilator+seed+\<value\>` runtime option. Alternatively, use
the system's :code:`srand48()` or for Windows :code:`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::
@ -1927,24 +1923,20 @@ Summary:
specified. Initial values of all other state holding variables are
controlled with `--x-initial`.
.. option:: --x-initial 0
.. option:: --x-initial fast
.. option:: --x-initial unique (default)
.. option:: --x-initial <mode>
Controls the two-state value used to initialize variables that
are not otherwise initialized.
"--x-initial 0",
With "--x-initial 0",
initializes all otherwise uninitialized variables to zero.
"--x-initial unique", the default,
With "--x-initial unique", the default,
initializes variables using a function, which determines the value to
use for each initialization. This gives the greatest flexibility and
allows for finding reset bugs. See :ref:`Unknown states`.
"--x-initial fast",
With "--x-initial fast",
is best for performance, and initializes all variables to a state
Verilator determines is optimal. This may allow further code
optimizations, but will likely hide any code bugs relating to missing
@ -2025,8 +2017,9 @@ Summary:
.. _Configuration Files:
Configuration Files
===================
=====================
Configuration Files
=====================
In addition to the command line, warnings and other features for the
:command:`verilator` command may be controlled with configuration files,
@ -2059,15 +2052,6 @@ The grammar of configuration commands is as follows:
Take the remaining text and treat it as Verilator configuration commands.
.. option:: coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]
.. option:: coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
Enable/disable coverage for the specified filename (or wildcard with
'\*' or '?', or all files if omitted) and range of line numbers (or all
lines if omitted). Often used to ignore an entire module for coverage
analysis purposes.
.. option:: clock_enable -module "<modulename>" -var "<signame>"
Deprecated and has no effect (ignored).
@ -2079,30 +2063,42 @@ The grammar of configuration commands is as follows:
Same as :option:`/*verilator&32;clock_enable*/` metacomment.
.. option:: clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
.. t_dist_docs_style ignore no_clocker
.. option:: clocker -module "<modulename>" [-function "<funcname>"] -var "<signame>"
.. option:: no_clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
.. option:: clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
.. option:: no_clocker -module "<modulename>" [-function "<funcname>"] -var "<signame>"
.. option:: no_clocker -module "<modulename>" [-task "<taskname>"] -var "<signame>"
Indicates whether the signal is used as clock or not. Verilator uses
this information to mark the signal and any derived signals as clocker.
See :vlopt:`--clk`.
Same as :option:`/*verilator&32;clocker*/` metacomment.
.. option:: coverage_block_off -module "<modulename>" -block "<blockname>"
.. option:: coverage_block_off -file "<filename>" -line <lineno>
.. option:: coverage_block_off -module "<modulename>" -block "<blockname>"
Specifies the entire begin/end block should be ignored for coverage
analysis purposes. It can either be specified as a named block or as a
filename and line number.
Same as :option:`/*verilator&32;coverage_block_off*/` metacomment.
.. option:: coverage_off [-file "<filename>" [-lines <line> [ - <line> ]]]
.. option:: coverage_on [-file "<filename>" [-lines <line> [ - <line> ]]]
Enable/disable coverage for the specified filename (or wildcard with
'\*' or '?', or all files if omitted) and range of line numbers (or all
lines if omitted). Often used to ignore an entire module for coverage
analysis purposes.
.. option:: forceable -module "<modulename>" -var "<signame>"
Generate public `<signame>__VforceEn` and `<signame>__VforceVal` signals
@ -2113,11 +2109,8 @@ The grammar of configuration commands is as follows:
.. option:: full_case -file "<filename>" -lines <lineno>
.. option:: parallel_case -file "<filename>" -lines <lineno>
Same as :code:`//synopsys full_case` and
:code:`//synopsys parallel_case`. When these synthesis directives are
discovered, Verilator will either formally prove the directive to be
Same as :code:`//synthesis full_case`. When these synthesis directives
are discovered, Verilator will either formally prove the directive to be
true, or, failing that, will insert the appropriate code to detect
failing cases at simulation runtime and print an "Assertion failed"
error message.
@ -2154,15 +2147,8 @@ The grammar of configuration commands is as follows:
Specifies the module may be inlined into any modules that use this
module. Same as :option:`/*verilator&32;inline_module*/` metacomment.
.. option:: isolate_assignments -module "<modulename>" [-task "<taskname>"] -var "<signame>"
.. option:: isolate_assignments -module "<modulename>" [-function "<funcname>"] -var "<signame>"
.. option:: isolate_assignments -module "<modulename>" -function "<fname>"
Used to indicate that the assignments to this signal in any blocks
should be isolated into new blocks. Same as
:option:`/*verilator&32;isolate_assignments*/` metacomment.
.. t_dist_docs_style ignore no_inline
.. option:: no_inline -module "<modulename>"
@ -2170,10 +2156,10 @@ The grammar of configuration commands is as follows:
this module. Same as :option:`/*verilator&32;no_inline_module*/`
metacomment.
.. option:: no_inline [-module "<modulename>"] -task "<taskname>"
.. option:: no_inline [-module "<modulename>"] -function "<funcname>"
.. option:: no_inline [-module "<modulename>"] -task "<taskname>"
Specify the function or task should not be inlined into where it is
used. This may reduce the size of the final executable when a task is
used a very large number of times. For this flag to work, the task and
@ -2182,12 +2168,22 @@ The grammar of configuration commands is as follows:
Same as :option:`/*verilator&32;no_inline_task*/` metacomment.
.. option:: lint_on [-rule <message>] [-file "<filename>" [-lines <line> [ - <line>]]]
.. option:: isolate_assignments -module "<modulename>" -function "<fname>"
.. option:: isolate_assignments -module "<modulename>" [-function "<funcname>"] -var "<signame>"
.. option:: isolate_assignments -module "<modulename>" [-task "<taskname>"] -var "<signame>"
Used to indicate that the assignments to this signal in any blocks
should be isolated into new blocks. Same as
:option:`/*verilator&32;isolate_assignments*/` metacomment.
.. option:: lint_off [-rule <message>] [-file "<filename>" [-lines <line> [ - <line>]]]
.. option:: lint_off [-rule <message>] [-file "<filename>"] [-contents "<wildcard>"] [-match "<wildcard>"]
.. option:: lint_on [-rule <message>] [-file "<filename>" [-lines <line> [ - <line>]]]
Enable/disables the specified lint warning, in the specified filename
(or wildcard with '\*' or '?', or all files if omitted) and range of
line numbers (or all lines if omitted).
@ -2218,18 +2214,13 @@ The grammar of configuration commands is as follows:
Before version 4.026, :code:`-rule` was named :code:`-msg`, and
:code:`-msg` remained a deprecated alias until Version 5.000.
.. option:: public [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>"
.. option:: parallel_case -file "<filename>" -lines <lineno>
.. option:: public_flat [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>"
.. option:: public_flat_rd [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>"
.. option:: public_flat_rw [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>" "@(edge)"
Sets the variable to be public. Same as
:option:`/*verilator&32;public*/` or
:option:`/*verilator&32;public_flat*/`, etc., metacomments. See
also :ref:`VPI Example`.
Same as :code:`//synthesis parallel_case`. When these synthesis
directives are discovered, Verilator will either formally prove the
directive to be true, or, failing that, will insert the appropriate code
to detect failing cases at simulation runtime and print an "Assertion
failed" error message.
.. option:: profile_data -hier-dpi "<function_name>" -cost <cost_value>
@ -2244,18 +2235,31 @@ The grammar of configuration commands is as follows:
order to improve model runtime performance. This option is not expected
to be used by users directly. See :ref:`Thread PGO`.
.. option:: sc_bv -module "<modulename>" [-task "<taskname>"] -var "<signame>"
.. option:: public [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>"
.. option:: public_flat [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>"
.. option:: public_flat_rd [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>"
.. option:: public_flat_rw [-module "<modulename>"] [-task/-function "<taskname>"] -var "<signame>" "@(edge)"
Sets the variable to be public. Same as
:option:`/*verilator&32;public*/` or
:option:`/*verilator&32;public_flat*/`, etc., metacomments. See
also :ref:`VPI Example`.
.. option:: sc_bv -module "<modulename>" [-function "<funcname>"] -var "<signame>"
.. option:: sc_bv -module "<modulename>" [-task "<taskname>"] -var "<signame>"
Sets the port to be of :code:`sc_bv<{width}>` type, instead of bool,
uint32_t, or uint64_t. Same as :option:`/*verilator&32;sc_bv*/`
metacomment.
.. option:: sformat [-module "<modulename>"] [-task "<taskname>"] -var "<signame>"
.. option:: sformat [-module "<modulename>"] [-function "<funcname>"] -var "<signame>"
.. option:: sformat [-module "<modulename>"] [-task "<taskname>"] -var "<signame>"
Must be applied to the final argument of type :code:`input string` of a
function or task to indicate that the function or task should pass all
remaining arguments through $sformatf. This allows the creation of DPI
@ -2264,20 +2268,20 @@ The grammar of configuration commands is as follows:
Same as :option:`/*verilator&32;sformat*/` metacomment.
.. option:: split_var [-module "<modulename>"] [-task "<taskname>"] -var "<varname>"
.. option:: split_var [-module "<modulename>"] [-function "<funcname>"] -var "<varname>"
.. option:: split_var [-module "<modulename>"] [-task "<taskname>"] -var "<varname>"
Break the variable into multiple pieces typically to resolve UNOPTFLAT
performance issues. Typically the variables to attach this to are
recommended by Verilator itself; see :option:`UNOPTFLAT`.
Same as :option:`/*verilator&32;split_var*/` metacomment.
.. option:: timing_on [-file "<filename>" [-lines <line> [ - <line>]]]
.. option:: timing_off [-file "<filename>" [-lines <line> [ - <line>]]]
.. option:: timing_on [-file "<filename>" [-lines <line> [ - <line>]]]
Enables/disables timing constructs for the specified file and lines.
When disabled, all timing control constructs in the specified source
code locations are ignored the same way as with the
@ -2287,14 +2291,17 @@ The grammar of configuration commands is as follows:
Same as :option:`/*verilator&32;timing_on*/`,
:option:`/*verilator&32;timing_off*/` metacomments.
.. option:: tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]
.. t_dist_docs_style ignore tracing_on
.. option:: tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
.. option:: tracing_on [-scope "<scopename>" [-levels <levels> ]]
.. option:: tracing_on [-file "<filename>" [-lines <line> [ - <line> ]]]
.. option:: tracing_off [-scope "<scopename>" [-levels <levels> ]]
.. option:: tracing_on [-scope "<scopename>" [-levels <levels> ]]
Enable/disable waveform tracing for all future signals declared in
all files.

143
docs/guide/exe_verilator_coverage.rst
View File

@ -49,116 +49,119 @@ verilator_coverage Arguments
.. option:: <filename>
Specifies the input coverage data file. Multiple filenames may be provided
to read multiple inputs. If no data file is specified, by default,
"coverage.dat" will be read.
Specifies the input coverage data file. Multiple filenames may be
provided to read multiple inputs. If no data file is specified, by
default, "coverage.dat" will be read.
.. option:: --annotate <output_directory>
Specifies the directory name to which source files with annotated coverage
data should be written.
Specifies the directory name to which source files with annotated
coverage data should be written.
Points are children of each line coverage- branches, expressions or toggle points.
When point counts are aggregated into a line, the minimum and maximum counts
are used to determine the status of the line (complete, partial, failing)
The count is equal to the maximum of the points.
Points are children of each line coverage- branches, expressions or
toggle points. When point counts are aggregated into a line, the
minimum and maximum counts are used to determine the status of the line
(complete, partial, failing) The count is equal to the maximum of the
points.
Coverage data is annotated at the beginning of the line and is formatted
as a special character followed by the number of coverage hits. The special
characters " ,%,~,+,-" indicate summary of the coverage, and allow use of grep
to filter the report.
Coverage data is annotated at the beginning of the line and is formatted
as a special character followed by the number of coverage hits. The
special characters " ,%,~,+,-" indicate summary of the coverage, and
allow use of grep to filter the report.
* " " (whitespace) indicates that all points on the line are above the coverage min.
* "%" indicates that all points on the line are below the coverage min.
* "~" indicates that some points on the line are above the coverage min and some are below.
* "+" coverage point was at or above the min. Only used with :option:`--annotate-points`.
* "-" coverage point was below the min. Only used with :option:`--annotate-points`.
* " " (whitespace) indicates that all points on the line are above the coverage min.
* "%" indicates that all points on the line are below the coverage min.
* "~" indicates that some points on the line are above the coverage min and some are below.
* "+" coverage point was at or above the min. Only used with :option:`--annotate-points`.
* "-" coverage point was below the min. Only used with :option:`--annotate-points`.
.. code-block::
.. code-block::
100000 input logic a; // Begins with whitespace, because
// number of hits (100000) is above the min.
+100000 point: comment=a // Begins with +, because
// number of hits (100000) is above the min.
%000000 input logic b; // Begins with %, because
// number of hits (0) is below the min.
-000000 point: comment=b // Begins with -, because
// number of hits (0) is below the min.
~000010 if (cyc!=0) begin // Begins with ~, because
// branches are below and above the min.
+000010 point: comment=if // The if branch is above the min.
-000000 point: comment=else // The else branch is below the min.
100000 input logic a; // Begins with whitespace, because
// number of hits (100000) is above the min.
+100000 point: comment=a // Begins with +, because
// number of hits (100000) is above the min.
%000000 input logic b; // Begins with %, because
// number of hits (0) is below the min.
-000000 point: comment=b // Begins with -, because
// number of hits (0) is below the min.
~000010 if (cyc!=0) begin // Begins with ~, because
// branches are below and above the min.
+000010 point: comment=if // The if branch is above the min.
-000000 point: comment=else // The else branch is below the min.
.. option:: --annotate-all
Specifies all files should be shown. By default, only those source files
with low coverage are written to the output directory.
Specifies all files should be shown. By default, only those source
files with low coverage are written to the output directory.
This option should be used together with :option:`--annotate`.
This option should be used together with :option:`--annotate`.
.. option:: --annotate-min <count>
Specifies the threshold (<count>) below which coverage point is considered
sufficient. If the threshold is not exceeded, then the annotation will begin
with a "%" symbol to indicate the coverage is insufficient.
Specifies the threshold (<count>) below which coverage point is
considered sufficient. If the threshold is not exceeded, then the
annotation will begin with a "%" symbol to indicate the coverage is
insufficient.
The <count> threshold defaults to 10.
The <count> threshold defaults to 10.
This option should be used together with :option:`--annotate`.
This option should be used together with :option:`--annotate`.
.. option:: --annotate-points
Specifies all coverage points should be shown after each line of text. By
default, only source lines are shown.
Specifies all coverage points should be shown after each line of text. By
default, only source lines are shown.
.. code-block::
.. code-block::
100000 input logic a, b, c;
+100000 point: comment=a // These lines are only shown
+200000 point: comment=b // with option --annotate-points
+300000 point: comment=c // enabled.
100000 input logic a, b, c;
+100000 point: comment=a // These lines are only shown
+200000 point: comment=b // with option --annotate-points
+300000 point: comment=c // enabled.
This option should be used together with :option:`--annotate`.
This option should be used together with :option:`--annotate`.
.. option:: --help
Displays a help summary, the program version, and exits.
Displays a help summary, the program version, and exits.
.. option:: --rank
Prints an experimental report listing the relative importance of each test
in covering all of the coverage points. The report shows "Covered" which
indicates the number of points the test covers; a test is considered to
cover a point if it has a bucket count of at least 1. The "rank" column has
a higher number t indicate the test is more critical, and rank 0 means the
test does not need to be run to cover the points. "RankPts" indicates the
number of coverage points this test will contribute to overall coverage if
all tests are run in the order of highest to the lowest rank.
Prints an experimental report listing the relative importance of each
test in covering all of the coverage points. The report shows "Covered"
which indicates the number of points the test covers; a test is
considered to cover a point if it has a bucket count of at least 1. The
"rank" column has a higher number t indicate the test is more critical,
and rank 0 means the test does not need to be run to cover the points.
"RankPts" indicates the number of coverage points this test will
contribute to overall coverage if all tests are run in the order of
highest to the lowest rank.
.. option:: --unlink
With :option:`--write`, unlink all input files after the output
has been successfully created.
With :option:`--write`, unlink all input files after the output has been
successfully created.
.. option:: --version
Displays program version and exits.
Displays program version and exits.
.. option:: --write <filename>
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in verilator_coverage data format.
This is useful in scripts to combine many coverage data files (likely
generated from random test runs) into one master coverage file.
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in verilator_coverage data
format. This is useful in scripts to combine many coverage data files
(likely generated from random test runs) into one master coverage file.
.. option:: --write-info <filename.info>
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in :command:`lcov` .info format.
This may be used to feed into :command:`lcov` to aggregate or generate
reports. This format lacks the comments for cover points that the
verilator_coverage format has. It can be used with :command:`genhtml`
to generate an HTML report. :command:`genhtml --branch-coverage` will
also display the branch coverage, analogous to :option:`--annotate-points`
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in :command:`lcov` .info format.
This may be used to feed into :command:`lcov` to aggregate or generate
reports. This format lacks the comments for cover points that the
verilator_coverage format has. It can be used with :command:`genhtml` to
generate an HTML report. :command:`genhtml --branch-coverage` will also
display the branch coverage, analogous to :option:`--annotate-points`.

8
docs/guide/exe_verilator_gantt.rst
View File

@ -84,16 +84,16 @@ verilator_gantt Arguments
.. option:: <filename>
The filename to read data from; the default is "profile_exec.dat".
The filename to read data from; the default is "profile_exec.dat".
.. option:: --help
Displays a help summary, the program version, and exits.
Displays a help summary, the program version, and exits.
.. option:: --no-vcd
Disables creating a .vcd file.
Disables creating a .vcd file.
.. option:: --vcd <filename>
Sets the output filename for vcd dump; the default is "verilator_gantt.vcd".
Sets the output filename for vcd dump; the default is "verilator_gantt.vcd".

4
docs/guide/exe_verilator_profcfunc.rst
View File

@ -33,8 +33,8 @@ verilator_profcfunc Arguments
.. option:: <filename>
The :command:`gprof`-generated filename to read data from. Typically "gprof.out".
The :command:`gprof`-generated filename to read data from. Typically "gprof.out".
.. option:: --help
Displays a help summary, the program version, and exits.
Displays a help summary, the program version, and exits.

378
docs/guide/extensions.rst
View File

@ -1,14 +1,19 @@
.. Copyright 2003-2025 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*******************
Language Extensions
*******************
=====================
Language Extensions
=====================
The following additional constructs are the extensions Verilator supports
on top of standard Verilog code. Using these features outside of comments
or "`ifdef`"'s may break other tools.
.. option:: """ [string] """
A triple-quoted block specifies a string that may include newlines and
single quotes. This extension was standardized in IEEE 1800-2023.
.. option:: `__FILE__
The :option:`\`__FILE__` define expands to the current filename as a
@ -21,6 +26,12 @@ or "`ifdef`"'s may break other tools.
C++'s __LINE__. This Verilator feature added in 2006 was incorporated
into IEEE 1800-2009.
.. option:: `coverage_block_off
Specifies the entire begin/end block should be ignored for coverage
analysis. Must be inside a code block, e.g., within a begin/end pair.
Same as :option:`coverage_block_off` in :ref:`Configuration Files`.
.. option:: `error [string]
This will report an error when the preprocessor emits it, similar to
@ -33,10 +44,116 @@ or "`ifdef`"'s may break other tools.
internal tests, so that debugging can leave the line numbers correctly
referring to the test file's line numbers.
.. option:: """ [string] """
.. option:: `systemc_class_name
A triple-quoted block specifies a string that may include newlines and
single quotes. This extension was standardized in IEEE 1800-2023.
Inside one of the :option:`\`systemc_... <\`systemc_header>` text
blocks, replaced with the C++ class name generated for the given
containing SystemVerilog class or module. Currently this is replaced
blindly, ignoring quoting or other escapes; this behavior may change in
the future. This attribute is indented only to be used internally in
`verilated_std.sv`.
.. option:: `systemc_ctor
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class constructor. Must be placed as a module or
class item, e.g., directly inside a module/endmodule or class/endclass
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `systemc_dtor
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class destructor. Must be placed as a module or
class item, e.g., directly inside a module/endmodule or class/endclass
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `systemc_header
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the output .h file's header. Must be placed as a module
or class item, e.g., directly inside a module/endmodule or
class/endclass pair. Despite the name of this macro, this also works in
pure C++ code.
.. option:: `systemc_header_post
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the output .h file's header after the class definition.
Must be placed as a module or class item, e.g., directly inside a
module/endmodule or class/endclass pair. Despite the name of this macro,
this also works in pure C++ code.
.. option:: `systemc_imp_header
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the header of all files for this C++ class implementation.
Must be placed as a module or class item, e.g., directly inside a
module/endmodule or class/endclass pair. Despite the name of this macro,
this also works in pure C++ code.
.. option:: `systemc_implementation
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into a single file of the C++ class implementation. Must be
placed as a module or class item, e.g., directly inside a
module/endmodule or class/endclass pair. Despite the name of this macro,
this also works in pure C++ code.
If you will be reading or writing any Verilog variables in the C++
functions, the Verilog signals must be declared with a
:option:`/*verilator&32;public*/` metacomment. See also the public task
feature; writing an accessor may result in cleaner code.
.. option:: `systemc_interface
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class interface. Must be placed as a module or
class item, e.g., directly inside a module/endmodule or class/endclass
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `SYSTEMVERILOG
The SYSTEMVERILOG, SV_COV_START, and related standard predefined macros
are defined by default when :vlopt:`--language <--language>` is
"1800-\*".
.. option:: `VERILATOR
.. option:: `verilator
.. option:: `verilator3
The VERILATOR, verilator and verilator3 predefined macros are defined by
default so you may "\`ifdef" around tool specific constructs.
.. option:: `verilator_config
Take the remaining text up to the next :option:`\`verilog` mode switch and
treat it as Verilator configuration commands. See :ref:`Configuration Files`.
.. option:: `VERILATOR_TIMING
The VERILATOR_TIMING define is set when :vlopt:`--timing` is used to
allow an "\`ifdef" of code dependent on this feature. Note that this define
is not affected by the :option:`timing_off` configuration file option
nor timing metacomments.
.. option:: `verilog
Switch back to processing Verilog code after a
:option:`\`systemc_... <\`systemc_header>` mode switch. The Verilog
code returns to the last language mode specified with
"\`begin_keywords", or SystemVerilog if none was specified.
.. t_dist_docs_style restart_sort
.. option:: $c([string], ...);
@ -86,6 +203,16 @@ or "`ifdef`"'s may break other tools.
prints 5 digits per the C standard. This extension was standardized into
1800-2009.
.. option:: $stacktrace
Called as a task, print a stack trace. Called as a function, return a
string with a stack trace. This relies on the C++ system trace, which
may give less meaningful results if the model is not compiled with debug
symbols. Also, the data represents the C++ stack; the SystemVerilog
functions/tasks involved may be renamed and/or inlined before becoming
the C++ functions that may be visible in the stack trace. This
extension was standardized in IEEE 1800-2023.
.. option:: $timeprecision
Returns the timeprecision of the model as an integer. This extension is
@ -96,120 +223,6 @@ or "`ifdef`"'s may break other tools.
Returns the timeunit of the current module as an integer. This
extension is experimental and may be removed without deprecation.
.. option:: `coverage_block_off
Specifies the entire begin/end block should be ignored for coverage
analysis. Must be inside a code block, e.g., within a begin/end pair.
Same as :option:`coverage_block_off` in :ref:`Configuration Files`.
.. option:: `systemc_header
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the output .h file's header. Must be placed as a module
or class item, e.g., directly inside a module/endmodule or
class/endclass pair. Despite the name of this macro, this also works in
pure C++ code.
.. option:: `systemc_header_post
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the output .h file's header after the class definition.
Must be placed as a module or class item, e.g., directly inside a
module/endmodule or class/endclass pair. Despite the name of this macro,
this also works in pure C++ code.
.. option:: `systemc_class_name
Inside one of the :option:`\`systemc_... <\`systemc_header>` text
blocks, replaced with the C++ class name generated for the given
containing SystemVerilog class or module. Currently this is replaced
blindly, ignoring quoting or other escapes; this behavior may change in
the future. This attribute is indented only to be used internally in
`verilated_std.sv`.
.. option:: `systemc_ctor
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class constructor. Must be placed as a module or
class item, e.g., directly inside a module/endmodule or class/endclass
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `systemc_dtor
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class destructor. Must be placed as a module or
class item, e.g., directly inside a module/endmodule or class/endclass
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `systemc_interface
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the C++ class interface. Must be placed as a module or
class item, e.g., directly inside a module/endmodule or class/endclass
pair. Despite the name of this macro, this also works in pure C++ code.
.. option:: `systemc_imp_header
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into the header of all files for this C++ class implementation.
Must be placed as a module or class item, e.g., directly inside a
module/endmodule or class/endclass pair. Despite the name of this macro,
this also works in pure C++ code.
.. option:: `systemc_implementation
Take the remaining text up to the next :option:`\`verilog` or
:option:`\`systemc_... <\`systemc_header>` mode switch and place it
verbatim into a single file of the C++ class implementation. Must be
placed as a module or class item, e.g., directly inside a
module/endmodule or class/endclass pair. Despite the name of this macro,
this also works in pure C++ code.
If you will be reading or writing any Verilog variables in the C++
functions, the Verilog signals must be declared with a
:option:`/*verilator&32;public*/` metacomment. See also the public task
feature; writing an accessor may result in cleaner code.
.. option:: `SYSTEMVERILOG
The SYSTEMVERILOG, SV_COV_START, and related standard predefined macros
are defined by default when :vlopt:`--language <--language>` is
"1800-\*".
.. option:: `VERILATOR
.. option:: `verilator
.. option:: `verilator3
The VERILATOR, verilator and verilator3 predefined macros are defined by
default so you may "\`ifdef" around tool specific constructs.
.. option:: `verilator_config
Take the remaining text up to the next :option:`\`verilog` mode switch and
treat it as Verilator configuration commands. See :ref:`Configuration Files`.
.. option:: `VERILATOR_TIMING
The VERILATOR_TIMING define is set when :vlopt:`--timing` is used to
allow an "\`ifdef" of code dependent on this feature. Note that this define
is not affected by the :option:`timing_off` configuration file option
nor timing metacomments.
.. option:: `verilog
Switch back to processing Verilog code after a
:option:`\`systemc_... <\`systemc_header>` mode switch. The Verilog
code returns to the last language mode specified with
"\`begin_keywords", or SystemVerilog if none was specified.
.. option:: /*verilator&32;clock_enable*/
Deprecated and has no effect (ignored).
@ -234,6 +247,9 @@ or "`ifdef`"'s may break other tools.
Same as :option:`clock_enable` configuration file option.
.. t_dist_docs_style ignore /*verilator&32;no_clocker*/
.. option:: /*verilator&32;clocker*/
.. option:: /*verilator&32;no_clocker*/
@ -401,29 +417,6 @@ or "`ifdef`"'s may break other tools.
parameter [2:0] PARAM /*verilator public*/ = 2'b0;
.. option:: /*verilator&32;public*/ (on typedef enum)
Used after an enum typedef declaration to indicate the emitted C code
should have the enum values visible. Due to C++ language restrictions,
this may only be used on 64-bit or narrower integral enumerations.
.. code-block:: sv
typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
.. option:: /*verilator&32;public*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
the signal should be declared so that C code may read or write the value
of the signal. This will also declare this module public; otherwise, use
:code:`/*verilator&32;public_flat*/`.
Instead of using public variables, consider making a DPI or public
function that accesses the variable. This is nicer as it provides an
obvious entry point compatible across simulators.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;public*/ (on task/function)
Used inside the declaration section of a function or task declaration to
@ -448,6 +441,52 @@ or "`ifdef`"'s may break other tools.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;public*/ (on typedef enum)
Used after an enum typedef declaration to indicate the emitted C code
should have the enum values visible. Due to C++ language restrictions,
this may only be used on 64-bit or narrower integral enumerations.
.. code-block:: sv
typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
.. option:: /*verilator&32;public*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
the signal should be declared so that C code may read or write the value
of the signal. This will also declare this module public; otherwise, use
:code:`/*verilator&32;public_flat*/`.
Instead of using public variables, consider making a DPI or public
function that accesses the variable. This is nicer as it provides an
obvious entry point compatible across simulators.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;public_[|flat|flat_rd|flat_rw]_on [@(<edge_list>)]*/ (as scope)
Used to wrap multiple signals and parameters with the respective public attribute.
See attribute above for their respective behavior. Cannot be nested. e.g:
.. code-block:: sv
/*verilator public_flat_rw_on*/
logic clk;
logic rst;
parameter width = 8;
/* verilator public_off*/
logic data;
Is equivalent to:
.. code-block:: sv
logic clk /*verilator public_flat_rw*/;
logic rst /*verilator public_flat_rw*/;
parameter width /*verilator public_flat_rw*/ = 8;
logic data;
.. option:: /*verilator&32;public_flat*/ (on variable)
Used after an input, output, register, or wire declaration to indicate
@ -475,33 +514,6 @@ or "`ifdef`"'s may break other tools.
Same as :option:`public_flat_rw` configuration file option.
.. option:: /*verilator&32;public_[|flat|flat_rd|flat_rw]_on [@(<edge_list>)]*/ (as scope)
Used to wrap multiple signals and parameters with the respective public attribute.
See attribute above for their respective behavior. Cannot be nested. e.g:
.. code-block:: sv
/*verilator public_flat_rw_on*/
logic clk;
logic rst;
parameter width = 8;
/* verilator public_off*/
logic data;
Is equivalent to:
.. code-block:: sv
logic clk /*verilator public_flat_rw*/;
logic rst /*verilator public_flat_rw*/;
parameter width /*verilator public_flat_rw*/ = 8;
logic data;
.. option:: /*verilator&32;public_off*/
Terminates the previous `/*verilator public*_on*/` directive; see above.
.. option:: /*verilator&32;public_module*/
Used after a module statement to indicate the module should not be
@ -512,13 +524,9 @@ or "`ifdef`"'s may break other tools.
Same as :option:`public` configuration file option.
.. option:: /*verilator&32;sc_clock*/
.. option:: /*verilator&32;public_off*/
Deprecated and ignored. Previously used after an input declaration to
indicate the signal should be declared in SystemC as a sc_clock instead
of a bool. This was needed in SystemC 1.1 and 1.2 only; versions 2.0
and later do not require clock pins to be sc_clocks, and this is no
longer needed and is ignored.
Terminates the previous `/*verilator public*_on*/` directive; see above.
.. option:: /*verilator&32;sc_bv*/
@ -531,6 +539,14 @@ or "`ifdef`"'s may break other tools.
Same as :option:`sc_bv` configuration file option.
.. option:: /*verilator&32;sc_clock*/
Deprecated and ignored. Previously used after an input declaration to
indicate the signal should be declared in SystemC as a sc_clock instead
of a bool. This was needed in SystemC 1.1 and 1.2 only; versions 2.0
and later do not require clock pins to be sc_clocks, and this is no
longer needed and is ignored.
.. option:: /*verilator&32;sformat*/
Attached to the final argument of type "input string" of a function or
@ -649,13 +665,3 @@ or "`ifdef`"'s may break other tools.
following loop at the same statement level should always be fully
unrolled by Verilator, ignoring :vlopt:`--unroll-count`. This is
similar to clang's ``#pragma clang loop unroll(full)``.
.. option:: $stacktrace
Called as a task, print a stack trace. Called as a function, return a
string with a stack trace. This relies on the C++ system trace, which
may give less meaningful results if the model is not compiled with debug
symbols. Also, the data represents the C++ stack; the SystemVerilog
functions/tasks involved may be renamed and/or inlined before becoming
the C++ functions that may be visible in the stack trace. This
extension was standardized in IEEE 1800-2023.

92
docs/guide/warnings.rst
View File

@ -1,9 +1,9 @@
.. Copyright 2003-2025 by Wilson Snyder.
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*******************
Errors and Warnings
*******************
=====================
Errors and Warnings
=====================
.. _Disabling Warnings:
@ -86,6 +86,8 @@ List Of Warnings
Limitations`.
.. t_dist_docs_style restart_sort
.. option:: ALWCOMBORDER
.. TODO better example
@ -1247,13 +1249,6 @@ List Of Warnings
simulate correctly.
.. option:: NOTIMING
Error when a timing-related construct that requires :vlopt:`--timing` has
been encountered. Issued only if Verilator is run with the
:vlopt:`--no-timing` option.
.. option:: NONSTD
Warns when a non-standard language feature is used that has a standard
@ -1262,6 +1257,13 @@ List Of Warnings
:code:`$sformatf`.
.. option:: NOTIMING
Error when a timing-related construct that requires :vlopt:`--timing` has
been encountered. Issued only if Verilator is run with the
:vlopt:`--no-timing` option.
.. option:: NULLPORT
Warns that a null port was detected in the module definition port
@ -1375,6 +1377,26 @@ List Of Warnings
This error may be disabled with a lint_off PINNOTFOUND metacomment.
.. option:: PKGNODECL
An error that a package/class appears to have been referenced that has
not yet been declared. According to IEEE 1800-2023 26.3, all packages
must be declared before being used.
Faulty example:
.. include:: ../../docs/gen/ex_PKGNODECL_faulty.rst
Results in:
.. include:: ../../docs/gen/ex_PKGNODECL_msg.rst
Often the package is declared in its own header file. In this case add
an include of that package header file to the referencing file. (And
make sure you have header guards in the package's header file to prevent
multiple declarations of the package.)
.. option:: PORTSHORT
Warns that an output port is connected to a constant.
@ -1398,26 +1420,6 @@ List Of Warnings
This error may be disabled with a lint_off PORTSHORT metacomment.
.. option:: PKGNODECL
An error that a package/class appears to have been referenced that has
not yet been declared. According to IEEE 1800-2023 26.3, all packages
must be declared before being used.
Faulty example:
.. include:: ../../docs/gen/ex_PKGNODECL_faulty.rst
Results in:
.. include:: ../../docs/gen/ex_PKGNODECL_msg.rst
Often the package is declared in its own header file. In this case add
an include of that package header file to the referencing file. (And
make sure you have header guards in the package's header file to prevent
multiple declarations of the package.)
.. option:: PREPROCZERO
Warns that a preprocessor \`ifdef/\`ifndef expression (added in IEEE
@ -2207,21 +2209,6 @@ List Of Warnings
.. include:: ../../docs/gen/ex_WIDTHEXPAND_1_fixed.rst
.. option:: WIDTHTRUNC
A more granular :option:`WIDTH` warning, for when a value is
truncated. See :option:`WIDTH`.
.. option:: WIDTHEXPAND
A more granular :option:`WIDTH` warning, for when a value is zero
expanded. See :option:`WIDTH`.
.. option:: WIDTHXZEXPAND
A more granular :option:`WIDTH` warning, for when a value is X/Z
expanded. See :option:`WIDTH`.
.. option:: WIDTHCONCAT
Warns that based on the width rules of Verilog, a concatenate, or
@ -2247,6 +2234,21 @@ List Of Warnings
width to the parameter usage (:code:`{PAR[31:0], PAR[31:0]}`).
.. option:: WIDTHEXPAND
A more granular :option:`WIDTH` warning, for when a value is zero
expanded. See :option:`WIDTH`.
.. option:: WIDTHTRUNC
A more granular :option:`WIDTH` warning, for when a value is
truncated. See :option:`WIDTH`.
.. option:: WIDTHXZEXPAND
A more granular :option:`WIDTH` warning, for when a value is X/Z
expanded. See :option:`WIDTH`.
.. option:: ZERODLY
Warns that `#0` delays do not schedule the process to be resumed in the

1
docs/spelling.txt
View File

@ -1101,6 +1101,7 @@ verilogmod
verimake
veriuser
vl
vlSelf
vlopt
vlt
vltstd

65
test_regress/t/t_dist_docs_style.py
View File

@ -35,9 +35,71 @@ def check_pattern(filename, contents, pattern, message):
break
lineno += m.group(1).count("\n")
buf = m.group(3)
test.error(filename + ":" + str(lineno) + ": " + message)
test.error_keep_going(filename + ":" + str(lineno) + ": " + message)
def check_sorted(filename, contents):
re_option = re.compile(r'^\.\. option:: (.*)')
re_other = re.compile(r'^[^ ]')
# .. t_dist_docs_style ignore string
# Ignore the given string, as a prefix match
re_ignore = re.compile(r' *\.\. t_dist_docs_style ignore (.*)')
# .. t_dist_docs_style restart_sort
# Restart the sort as if it's a new list, for forcing specific ordering
re_restart = re.compile(r' *\.\. t_dist_docs_style restart_sort')
contents += "__EOF__\n"
lineno = 0
options = []
ignores = []
for line in contents.split("\n"):
lineno += 1
if re.match(r'^($|\.\. _)', line):
continue
match_option = re_option.match(line)
match_ignore = re_ignore.match(line)
if match_option:
arg = match_option.group(1)
# print("-option %s" % line)
hit = False
for ignore in ignores:
if arg[:len(ignore)] == ignore:
hit = True
if not hit:
options.append([lineno, arg])
elif match_ignore:
arg = match_ignore.group(1)
ignores.append(arg)
elif (options and re_other.match(line)) or re_restart.match(line):
# print("-end-list %d %s" % (len(options), line))
check_sorted_options(filename, options)
ignores = []
options = []
def check_sorted_options(filename, options):
last_opt = None
for opt_data in options:
(lineno, opt) = opt_data
if last_opt and _option_sort_key(last_opt) > _option_sort_key(opt):
test.error_keep_going(filename + ":" + str(lineno) +
": Option '%s' should be in sorted order before '%s'" %
(opt, last_opt))
last_opt = opt
def _option_sort_key(opt):
opt = re.sub(r'^<', ' <', opt) # <file> before -option
opt = re.sub(r'^\+', '-', opt) # +options sort with -options
opt = re.sub(r'^--', '-', opt) # -- sorts with -
opt = re.sub(r'^-no-', '-', opt) # -no- sorts with non-no
opt = opt.lower()
return opt
#####
if not os.path.exists(root + "/.git"):
test.skip("Not in a git repository")
@ -57,5 +119,6 @@ for filename in sorted(files.keys()):
"tag:`...` should not be split between lines")
check_pattern(filename, contents, r'.*[a-z](?<!:ref):\'',
"tag:`...' should use backticks instead")
check_sorted(filename, contents)
test.passes()