diff --git a/bin/verilator b/bin/verilator index ac93e6e50..89c18ea6f 100755 --- a/bin/verilator +++ b/bin/verilator @@ -341,11 +341,12 @@ detailed descriptions of these arguments. --no-debug-leak Disable leaking memory in --debug mode --debugi Enable debugging at a specified level --debugi- Enable debugging a source file at a level - --decorations Set output comment and spacing level --no-decoration Disable comments and lower spacing level + --decorations Set output comment and spacing level --default-language Default language to parse +define+= Set preprocessor define --dpi-hdr-only Only produce the DPI header file + --dump- 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- Enable dumping everything in source file + --dumpi- Enable dumping everything in source file at level --dumpi-dfg Enable dumping DfgGraphs to .dot files at level --dumpi-graph Enable dumping V3Graphs to .dot files at level --dumpi-tree Enable dumping Ast .tree files at level --dumpi-tree-json Enable dumping Ast .tree.json files at level - --dumpi- 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 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 Verilog scope name of the top module --language Default language standard to parse -LDFLAGS Linker pre-object arguments for makefile @@ -399,20 +399,20 @@ detailed descriptions of these arguments. +libext++[ext]... Extensions for finding modules --lint-only Lint, but do not make output --localize-max-size Tune localize optimization variable size - --make Generate scripts for specified build tool - -MAKEFLAGS 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 Generate scripts for specified build tool + -MAKEFLAGS Arguments to pass to make during --build --max-num-width Maximum number width (default: 64K) --Mdir Name of output object directory --MMD Create .d dependency files --mod-prefix Name to prepend to lower classes --MP Create phony dependency targets +notimingchecks Ignored + -o Name of final executable -O0 Disable optimizations -O3 High-performance optimizations -O Selectable optimizations - -o Name of final executable --output-groups Group .cpp files into larger ones --output-split Split .cpp files into pieces --output-split-cfuncs Split model functions @@ -467,10 +467,10 @@ detailed descriptions of these arguments. --threads Enable multithreading --threads-dpi Enable multithreaded DPI --threads-max-mtasks Tune maximum mtask partitioning - --timing Enable timing support - --no-timing Disable timing support --timescale Sets default timescale --timescale-override Overrides all timescales + --timing Enable timing support + --no-timing Disable timing support --top Alias of --top-module --top-module 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 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 Undefine preprocessor define --no-unlimited-stack Don't disable stack size limit --unroll-count Tune maximum loop iterations @@ -494,8 +494,8 @@ detailed descriptions of these arguments. -V Verbose version and config -v 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+ Synonym for +1364-1995ext+ +verilog2001ext+ Synonym for +1364-2001ext+ --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+ Set coverage output filename +verilator+debug Enable debugging +verilator+debugi+ Enable debugging at a level - +verilator+coverage+file+ Set coverage output filename +verilator+error+limit+ Set error limit +verilator+help Show help +verilator+noassert Disable assert checking diff --git a/docs/guide/exe_sim.rst b/docs/guide/exe_sim.rst index 743541794..abe946acd 100644 --- a/docs/guide/exe_sim.rst +++ b/docs/guide/exe_sim.rst @@ -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+ 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. diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index 7e1af30fb..2f2b1cdfe 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -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:: - - 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 @@ -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:: + + 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 the Verilog file containing the top module to be Verilated. + .. option:: +1364-1995ext+ .. option:: +1364-2001ext+ @@ -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 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 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- + + 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- +.. 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- + + 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:: --dumpi-dfg @@ -479,13 +483,6 @@ Summary: 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++ @@ -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 - - 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 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 + + 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 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 - - 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 - - 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 + + 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 + + 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 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 + + 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` arguments should be used instead. -.. option:: -o - - 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+\`. +.. option:: --no-threads + + Deprecated and has no effect (ignored). + + In versions before 5.004, created a model which was not thread-safe. + .. option:: --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 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 / - .. option:: --timescale-override / +.. option:: --timescale-override / + 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 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+\` - 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+\` 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 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 "" [-lines [ - ]]] - -.. option:: coverage_off [-file "" [-lines [ - ]]] - - 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 "" -var "" 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 "" [-task ""] -var "" + + .. t_dist_docs_style ignore no_clocker .. option:: clocker -module "" [-function ""] -var "" -.. option:: no_clocker -module "" [-task ""] -var "" +.. option:: clocker -module "" [-task ""] -var "" .. option:: no_clocker -module "" [-function ""] -var "" +.. option:: no_clocker -module "" [-task ""] -var "" + 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 "" -block "" - .. option:: coverage_block_off -file "" -line +.. option:: coverage_block_off -module "" -block "" + 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 "" [-lines [ - ]]] + +.. option:: coverage_on [-file "" [-lines [ - ]]] + + 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 "" -var "" Generate public `__VforceEn` and `__VforceVal` signals @@ -2113,11 +2109,8 @@ The grammar of configuration commands is as follows: .. option:: full_case -file "" -lines -.. option:: parallel_case -file "" -lines - - 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 "" [-task ""] -var "" -.. option:: isolate_assignments -module "" [-function ""] -var "" - -.. option:: isolate_assignments -module "" -function "" - - 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 "" @@ -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 ""] -task "" - .. option:: no_inline [-module ""] -function "" +.. option:: no_inline [-module ""] -task "" + 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 ] [-file "" [-lines [ - ]]] +.. option:: isolate_assignments -module "" -function "" + +.. option:: isolate_assignments -module "" [-function ""] -var "" + +.. option:: isolate_assignments -module "" [-task ""] -var "" + + 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 ] [-file "" [-lines [ - ]]] .. option:: lint_off [-rule ] [-file ""] [-contents ""] [-match ""] +.. option:: lint_on [-rule ] [-file "" [-lines [ - ]]] + 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 ""] [-task/-function ""] -var "" +.. option:: parallel_case -file "" -lines -.. option:: public_flat [-module ""] [-task/-function ""] -var "" - -.. option:: public_flat_rd [-module ""] [-task/-function ""] -var "" - -.. option:: public_flat_rw [-module ""] [-task/-function ""] -var "" "@(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 "" -cost @@ -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 "" [-task ""] -var "" +.. option:: public [-module ""] [-task/-function ""] -var "" + +.. option:: public_flat [-module ""] [-task/-function ""] -var "" + +.. option:: public_flat_rd [-module ""] [-task/-function ""] -var "" + +.. option:: public_flat_rw [-module ""] [-task/-function ""] -var "" "@(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 "" [-function ""] -var "" +.. option:: sc_bv -module "" [-task ""] -var "" + 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 ""] [-task ""] -var "" - .. option:: sformat [-module ""] [-function ""] -var "" +.. option:: sformat [-module ""] [-task ""] -var "" + 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 ""] [-task ""] -var "" - .. option:: split_var [-module ""] [-function ""] -var "" +.. option:: split_var [-module ""] [-task ""] -var "" + 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 "" [-lines [ - ]]] - .. option:: timing_off [-file "" [-lines [ - ]]] +.. option:: timing_on [-file "" [-lines [ - ]]] + 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 "" [-lines [ - ]]] + + .. t_dist_docs_style ignore tracing_on .. option:: tracing_off [-file "" [-lines [ - ]]] -.. option:: tracing_on [-scope "" [-levels ]] +.. option:: tracing_on [-file "" [-lines [ - ]]] .. option:: tracing_off [-scope "" [-levels ]] +.. option:: tracing_on [-scope "" [-levels ]] + Enable/disable waveform tracing for all future signals declared in all files. diff --git a/docs/guide/exe_verilator_coverage.rst b/docs/guide/exe_verilator_coverage.rst index 23caac867..11cd6e52a 100644 --- a/docs/guide/exe_verilator_coverage.rst +++ b/docs/guide/exe_verilator_coverage.rst @@ -49,116 +49,119 @@ verilator_coverage Arguments .. option:: -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 -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 -Specifies the threshold () 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 () 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 threshold defaults to 10. + The 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 -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 -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`. diff --git a/docs/guide/exe_verilator_gantt.rst b/docs/guide/exe_verilator_gantt.rst index 135ba1a8f..bb74e53ca 100644 --- a/docs/guide/exe_verilator_gantt.rst +++ b/docs/guide/exe_verilator_gantt.rst @@ -84,16 +84,16 @@ verilator_gantt Arguments .. option:: -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 -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". diff --git a/docs/guide/exe_verilator_profcfunc.rst b/docs/guide/exe_verilator_profcfunc.rst index 8fb7fba33..4d28819ed 100644 --- a/docs/guide/exe_verilator_profcfunc.rst +++ b/docs/guide/exe_verilator_profcfunc.rst @@ -33,8 +33,8 @@ verilator_profcfunc Arguments .. option:: -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. diff --git a/docs/guide/extensions.rst b/docs/guide/extensions.rst index 31f65678a..b01c28f91 100644 --- a/docs/guide/extensions.rst +++ b/docs/guide/extensions.rst @@ -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 [@()]*/ (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 [@()]*/ (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. diff --git a/docs/guide/warnings.rst b/docs/guide/warnings.rst index 606ac1868..119957f0c 100644 --- a/docs/guide/warnings.rst +++ b/docs/guide/warnings.rst @@ -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 diff --git a/docs/spelling.txt b/docs/spelling.txt index 1c2aa0519..d2326c6eb 100644 --- a/docs/spelling.txt +++ b/docs/spelling.txt @@ -1101,6 +1101,7 @@ verilogmod verimake veriuser vl +vlSelf vlopt vlt vltstd diff --git a/test_regress/t/t_dist_docs_style.py b/test_regress/t/t_dist_docs_style.py index 6acdf983e..049bbd2f5 100755 --- a/test_regress/t/t_dist_docs_style.py +++ b/test_regress/t/t_dist_docs_style.py @@ -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) # 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](?