From 7dde11b4c6ee707b7bdcee68bfc2a3a41ffb786d Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Tue, 24 Feb 2026 21:11:39 -0500 Subject: [PATCH] Docs: Split control.rst from exe_verilator.rst. --- docs/guide/control.rst | 348 +++++++++++++++++++++++++++++++++++ docs/guide/exe_verilator.rst | 347 ---------------------------------- docs/guide/index.rst | 1 + 3 files changed, 349 insertions(+), 347 deletions(-) create mode 100644 docs/guide/control.rst diff --git a/docs/guide/control.rst b/docs/guide/control.rst new file mode 100644 index 000000000..d42afceff --- /dev/null +++ b/docs/guide/control.rst @@ -0,0 +1,348 @@ +.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder +.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 + +.. _verilator control files: + +======================= +Verilator Control Files +======================= + +In addition to the command line, warnings and other features for the +:command:`verilator` command may be controlled with Verilator Control +Files, not to be confused with IEEE Configurations blocks +(`config...endconfig`). Typically named with the `.vlt` extension, what +makes it a Verilator Control File is the :option:`\`verilator_config` +directive. These files, when named `.vlt`, are read before source code +files; if this behavior is undesired, name the control file with a `.v` or +other suffix. + +An example: + +.. code-block:: sv + + `verilator_config + lint_off -rule WIDTH + lint_off -rule CASEX -file "silly_vendor_code.v" + +This disables WIDTH warnings globally, and CASEX for a specific file. + +Verilator control files are fed through the normal Verilog preprocessor +prior to parsing, so "\`ifdef", "\`define", and comments may be used as if +the control file was standard Verilog code. + +Note that file or line-specific control only applies to files read after +the control file. It is therefore recommended to pass the control file to +Verilator as the first file. + +The grammar of control commands is as follows: + +.. option:: `verilator_config + + Take the remaining text and treat it as Verilator Control File commands. + See :ref:`Verilator Control Files`. + +.. option:: clock_enable -module "" -var "" + + Deprecated and has no effect (ignored). + + In versions before 5.000: + + Indicates that the signal is used to gate a clock, and the user takes + responsibility for ensuring there are no races related to it. + + Same as :option:`/*verilator&32;clock_enable*/` metacomment. + + + .. t_dist_docs_style ignore no_clocker + +.. option:: clocker -module "" [-function ""] -var "" + +.. option:: clocker -module "" [-task ""] -var "" + +.. option:: no_clocker -module "" [-function ""] -var "" + +.. option:: no_clocker -module "" [-task ""] -var "" + + Deprecated and has no effect (ignored). + + In versions before 5.042: + + 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 -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 + that can force/release a signal from C++ code. The force control + signals are created as :option:`public_flat` signals. + + Same as :option:`/*verilator&32;forceable*/` metacomment. + +.. option:: full_case -file "" -lines + + Same as ``//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. + +.. option:: hier_block -module "" + + Specifies that the module is an unit of hierarchical Verilation. Note + that the setting is ignored unless the :vlopt:`--hierarchical` option is + specified. See :ref:`Hierarchical Verilation`. + +.. option:: hier_params -module "" + + Specifies that the module contains parameters a :vlopt:`--hierarchical` block. This option + is used internally to specify parameters for deparametrized hier block instances. + This option should not be used directly. + See :ref:`Hierarchical Verilation`. + +.. option:: hier_workers -hier-dpi "" -workers + + Specifies how many threads need to be used for scheduling hierarchical DPI + tasks. This data is inserted internally during :vlopt:`--hierarchical`, + based on value specified in `hier_workers -module`. This option + should not be used directly. See :ref:`Hierarchical Verilation`. + +.. option:: hier_workers -module "" -workers + + Specifies how many threads need to be used for scheduling given module with + :option:`/*verilator&32;hier_block*/` metacomment. This number needs to be + smaller than :vlopt:`--threads` to fit in a thread schedule. + See :ref:`Hierarchical Verilation`. + +.. option:: inline -module "" + + Specifies the module may be inlined into any modules that use this + module. Same as :option:`/*verilator&32;inline_module*/` metacomment. + + .. t_dist_docs_style ignore no_inline + +.. option:: no_inline -module "" + + Specifies the module should not be inlined into any modules that use + this module. Same as :option:`/*verilator&32;no_inline_module*/` + metacomment. + +.. 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 + tasks below it must be pure; they cannot reference any variables outside + the task itself. + + Same as :option:`/*verilator&32;no_inline_task*/` metacomment. + +.. 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). + + If the ``-rule`` is omitted, all lint warnings (see list in + :vlopt:`-Wno-lint`) are enabled/disabled. + + If ``-contents`` is provided, the input files must contain the given + wildcard (with '\*' or '?'), and are waived in case they match, provided + the ``-rule``, ``-file``, and ``-contents`` also match. The wildcard + should be designed to match a single line; it is unspecified if the + wildcard is allowed to match across multiple lines. The input contents + does not include :vlopt:`--std <--no-std>` standard files, nor control + files (with ``verilator_config``). Typical use for this is to match a + version number present in the Verilog sources, so that the waiver will + only apply to that version of the sources. + + If ``-match`` is provided, the linter warnings are matched against the + given wildcard (with '\*' or '?'), and are waived in case they match, + provided the ``-rule``, ``-file``, and ``-contents`` also match. The + wildcard is compared across the entire multi-line message; see + :vlopt:`--waiver-multiline`. + + When there are overlapping conflicting lint_on/lint_off directives, they + are resolved in the following priority order: + + * All lint_on/lint_off without a ``-file``, or with a ``-file "\*"``, + are processed in order of parsing. + * All lint_on/lint_off with ``-file "non-\*"`` are processed in order of + parsing. + * All lint_off with ``--match`` in order of parsing. + + If a warning is disabled with lint_off, it will not be printed, even if + the source contains a lint_on metacomment. The control file directives + and metacomments are interpreted separately and do not interact. A + warning is emitted only if not disabled either in a control file or via + metacomments. + + Before version 4.026, ``-rule`` was named ``-msg``, and + ``-msg`` remained a deprecated alias until Version 5.000. + +.. option:: parallel_case -file "" -lines + + Same as ``//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 + + Internal profiling data inserted during :vlopt:`--hierarchical`; specifies + execution cost of a hierarchical DPI wrappers for modules with + :option:`/*verilator&32;hier_block*/` metacomment. See + :ref:`Hierarchical Verilation`. + +.. option:: profile_data -mtask "" -cost + + Feeds profile-guided optimization data into the Verilator algorithms in + order to improve model runtime performance. This option is not expected + to be used by users directly. See :ref:`Thread PGO`. + +.. option:: public [-module ""] [-task/-function ""] [-var ""] + +.. option:: public_flat [-module ""] [-task/-function ""] [(-param | -port | -var) ""] + +.. option:: public_flat_rd [-module ""] [-task/-function ""] [(-param | -port | -var) ""] + +.. option:: public_flat_rw [-module ""] [-task/-function ""] [(-param | -port | -var) ""] ["@(edge)"] + + Sets the specified signal to be public. Same as + :option:`/*verilator&32;public*/` or + :option:`/*verilator&32;public_flat*/`, etc., metacomments. See also + :ref:`VPI Example`. + + Using ``-port`` only selects matching ports, ``-param`` matches + parameters and localparams, and ``-var`` matches any signal (including + ports, parameters, and regular variables or nets). In all three, the + following ```` can contain ``*`` and ``?`` wildcard + characters that match any substring or any single character respectively. + +.. option:: sc_biguint -module "" -var "" + + Sets the input/output signal to be of ``sc_biguint<{width}>`` type. + This metacomment works for signals of any width. + Same as :option:`/*verilator&32;sc_biguint*/` metacomment. + +.. option:: sc_bv -module "" -var "" + + Sets the port to be of ``sc_bv<{width}>`` type, instead of bool, + uint32_t, or uint64_t. Same as :option:`/*verilator&32;sc_bv*/` + metacomment. + +.. option:: sformat [-module ""] [-function ""] -var "" + +.. option:: sformat [-module ""] [-task ""] -var "" + + Must be applied to the final argument of type ``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 + functions with $display-like behavior. See the + :file:`test_regress/t/t_dpi_display.v` file for an example. + + Same as :option:`/*verilator&32;sformat*/` metacomment. + +.. 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_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 + :option:`--no-timing`, and code:`fork`/``join*`` blocks are + converted into ``begin``/``end`` blocks. + + Similar to :option:`/*verilator&32;timing_on*/`, + :option:`/*verilator&32;timing_off*/` meta-comments, but interpreted + independently. If either a control file, or meta-comments disable timing + constructs, they will be disabled. + + .. t_dist_docs_style ignore tracing_on + +.. option:: tracing_off [-file "" [-lines [ - ]]] + +.. 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. + + With ``-file``, enable/disable waveform tracing in the specified + filename (or wildcard with '\*' or '?'), and ``-line`` range of line + numbers (or all lines if omitted). + + For tracing_off with ``-file``, instances below any module in the + files/ranges specified will also not be traced. To overcome this + feature, use tracing_on on the upper module declaration and on any + cells, or use the ``-scope`` flavor of the command. + + With ``-scope`` enable/disable waveform tracing for the specified scope + (or wildcard with '\*' or '?'), and optional ``--levels`` number of + levels below. These controls only operate after other + file/line/module-based controls have indicated the signal should be + traced. Matching is performed on the shortest prefix first, such that + ``tracing_on -scope "a.b" tracing_off -scope "a"`` will turn it on for + "a.b" and off for everything else "a.*". + + With ``-levels`` (used with ``-scope``), the number of levels below that + scope which the rule is to match, where 0 means all levels below, 1 the + exact level as the provided scope, and 2 means an additional level of + children below the provided scope, etc. + +.. option:: verilator_lib -module "" + + Internal use only. Marks the specified module as being a stub for a library + created by :vlopt:`--lib-create` (including when created with + :vlopt:`--hierarchical`). Required for special internal processing. diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index a3d421fff..e3d434fa4 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -2255,350 +2255,3 @@ Summary: user-specified directories. This allows '-y "$(pwd)"' to be used if absolute filenames are desired for error messages instead of relative filenames. - - -.. _verilator control files: - -======================= -Verilator Control Files -======================= - -In addition to the command line, warnings and other features for the -:command:`verilator` command may be controlled with Verilator Control -Files, not to be confused with IEEE Configurations blocks -(`config...endconfig`). Typically named with the `.vlt` extension, what -makes it a Verilator Control File is the :option:`\`verilator_config` -directive. These files, when named `.vlt`, are read before source code -files; if this behavior is undesired, name the control file with a `.v` or -other suffix. - -An example: - -.. code-block:: sv - - `verilator_config - lint_off -rule WIDTH - lint_off -rule CASEX -file "silly_vendor_code.v" - -This disables WIDTH warnings globally, and CASEX for a specific file. - -Verilator control files are fed through the normal Verilog preprocessor -prior to parsing, so "\`ifdef", "\`define", and comments may be used as if -the control file was standard Verilog code. - -Note that file or line-specific control only applies to files read after -the control file. It is therefore recommended to pass the control file to -Verilator as the first file. - -The grammar of control commands is as follows: - -.. option:: `verilator_config - - Take the remaining text and treat it as Verilator Control File commands. - See :ref:`Verilator Control Files`. - -.. option:: clock_enable -module "" -var "" - - Deprecated and has no effect (ignored). - - In versions before 5.000: - - Indicates that the signal is used to gate a clock, and the user takes - responsibility for ensuring there are no races related to it. - - Same as :option:`/*verilator&32;clock_enable*/` metacomment. - - - .. t_dist_docs_style ignore no_clocker - -.. option:: clocker -module "" [-function ""] -var "" - -.. option:: clocker -module "" [-task ""] -var "" - -.. option:: no_clocker -module "" [-function ""] -var "" - -.. option:: no_clocker -module "" [-task ""] -var "" - - Deprecated and has no effect (ignored). - - In versions before 5.042: - - 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 -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 - that can force/release a signal from C++ code. The force control - signals are created as :option:`public_flat` signals. - - Same as :option:`/*verilator&32;forceable*/` metacomment. - -.. option:: full_case -file "" -lines - - Same as ``//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. - -.. option:: hier_block -module "" - - Specifies that the module is an unit of hierarchical Verilation. Note - that the setting is ignored unless the :vlopt:`--hierarchical` option is - specified. See :ref:`Hierarchical Verilation`. - -.. option:: hier_params -module "" - - Specifies that the module contains parameters a :vlopt:`--hierarchical` block. This option - is used internally to specify parameters for deparametrized hier block instances. - This option should not be used directly. - See :ref:`Hierarchical Verilation`. - -.. option:: hier_workers -hier-dpi "" -workers - - Specifies how many threads need to be used for scheduling hierarchical DPI - tasks. This data is inserted internally during :vlopt:`--hierarchical`, - based on value specified in `hier_workers -module`. This option - should not be used directly. See :ref:`Hierarchical Verilation`. - -.. option:: hier_workers -module "" -workers - - Specifies how many threads need to be used for scheduling given module with - :option:`/*verilator&32;hier_block*/` metacomment. This number needs to be - smaller than :vlopt:`--threads` to fit in a thread schedule. - See :ref:`Hierarchical Verilation`. - -.. option:: inline -module "" - - Specifies the module may be inlined into any modules that use this - module. Same as :option:`/*verilator&32;inline_module*/` metacomment. - - .. t_dist_docs_style ignore no_inline - -.. option:: no_inline -module "" - - Specifies the module should not be inlined into any modules that use - this module. Same as :option:`/*verilator&32;no_inline_module*/` - metacomment. - -.. 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 - tasks below it must be pure; they cannot reference any variables outside - the task itself. - - Same as :option:`/*verilator&32;no_inline_task*/` metacomment. - -.. 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). - - If the ``-rule`` is omitted, all lint warnings (see list in - :vlopt:`-Wno-lint`) are enabled/disabled. - - If ``-contents`` is provided, the input files must contain the given - wildcard (with '\*' or '?'), and are waived in case they match, provided - the ``-rule``, ``-file``, and ``-contents`` also match. The wildcard - should be designed to match a single line; it is unspecified if the - wildcard is allowed to match across multiple lines. The input contents - does not include :vlopt:`--std <--no-std>` standard files, nor control - files (with ``verilator_config``). Typical use for this is to match a - version number present in the Verilog sources, so that the waiver will - only apply to that version of the sources. - - If ``-match`` is provided, the linter warnings are matched against the - given wildcard (with '\*' or '?'), and are waived in case they match, - provided the ``-rule``, ``-file``, and ``-contents`` also match. The - wildcard is compared across the entire multi-line message; see - :vlopt:`--waiver-multiline`. - - When there are overlapping conflicting lint_on/lint_off directives, they - are resolved in the following priority order: - - * All lint_on/lint_off without a ``-file``, or with a ``-file "\*"``, - are processed in order of parsing. - * All lint_on/lint_off with ``-file "non-\*"`` are processed in order of - parsing. - * All lint_off with ``--match`` in order of parsing. - - If a warning is disabled with lint_off, it will not be printed, even if - the source contains a lint_on metacomment. The control file directives - and metacomments are interpreted separately and do not interact. A - warning is emitted only if not disabled either in a control file or via - metacomments. - - Before version 4.026, ``-rule`` was named ``-msg``, and - ``-msg`` remained a deprecated alias until Version 5.000. - -.. option:: parallel_case -file "" -lines - - Same as ``//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 - - Internal profiling data inserted during :vlopt:`--hierarchical`; specifies - execution cost of a hierarchical DPI wrappers for modules with - :option:`/*verilator&32;hier_block*/` metacomment. See - :ref:`Hierarchical Verilation`. - -.. option:: profile_data -mtask "" -cost - - Feeds profile-guided optimization data into the Verilator algorithms in - order to improve model runtime performance. This option is not expected - to be used by users directly. See :ref:`Thread PGO`. - -.. option:: public [-module ""] [-task/-function ""] [-var ""] - -.. option:: public_flat [-module ""] [-task/-function ""] [(-param | -port | -var) ""] - -.. option:: public_flat_rd [-module ""] [-task/-function ""] [(-param | -port | -var) ""] - -.. option:: public_flat_rw [-module ""] [-task/-function ""] [(-param | -port | -var) ""] ["@(edge)"] - - Sets the specified signal to be public. Same as - :option:`/*verilator&32;public*/` or - :option:`/*verilator&32;public_flat*/`, etc., metacomments. See also - :ref:`VPI Example`. - - Using ``-port`` only selects matching ports, ``-param`` matches - parameters and localparams, and ``-var`` matches any signal (including - ports, parameters, and regular variables or nets). In all three, the - following ```` can contain ``*`` and ``?`` wildcard - characters that match any substring or any single character respectively. - -.. option:: sc_biguint -module "" -var "" - - Sets the input/output signal to be of ``sc_biguint<{width}>`` type. - This metacomment works for signals of any width. - Same as :option:`/*verilator&32;sc_biguint*/` metacomment. - -.. option:: sc_bv -module "" -var "" - - Sets the port to be of ``sc_bv<{width}>`` type, instead of bool, - uint32_t, or uint64_t. Same as :option:`/*verilator&32;sc_bv*/` - metacomment. - -.. option:: sformat [-module ""] [-function ""] -var "" - -.. option:: sformat [-module ""] [-task ""] -var "" - - Must be applied to the final argument of type ``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 - functions with $display-like behavior. See the - :file:`test_regress/t/t_dpi_display.v` file for an example. - - Same as :option:`/*verilator&32;sformat*/` metacomment. - -.. 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_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 - :option:`--no-timing`, and code:`fork`/``join*`` blocks are - converted into ``begin``/``end`` blocks. - - Similar to :option:`/*verilator&32;timing_on*/`, - :option:`/*verilator&32;timing_off*/` meta-comments, but interpreted - independently. If either a control file, or meta-comments disable timing - constructs, they will be disabled. - - .. t_dist_docs_style ignore tracing_on - -.. option:: tracing_off [-file "" [-lines [ - ]]] - -.. 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. - - With ``-file``, enable/disable waveform tracing in the specified - filename (or wildcard with '\*' or '?'), and ``-line`` range of line - numbers (or all lines if omitted). - - For tracing_off with ``-file``, instances below any module in the - files/ranges specified will also not be traced. To overcome this - feature, use tracing_on on the upper module declaration and on any - cells, or use the ``-scope`` flavor of the command. - - With ``-scope`` enable/disable waveform tracing for the specified scope - (or wildcard with '\*' or '?'), and optional ``--levels`` number of - levels below. These controls only operate after other - file/line/module-based controls have indicated the signal should be - traced. Matching is performed on the shortest prefix first, such that - ``tracing_on -scope "a.b" tracing_off -scope "a"`` will turn it on for - "a.b" and off for everything else "a.*". - - With ``-levels`` (used with ``-scope``), the number of levels below that - scope which the rule is to match, where 0 means all levels below, 1 the - exact level as the provided scope, and 2 means an additional level of - children below the provided scope, etc. - -.. option:: verilator_lib -module "" - - Internal use only. Marks the specified module as being a stub for a library - created by :vlopt:`--lib-create` (including when created with - :vlopt:`--hierarchical`). Required for special internal processing. diff --git a/docs/guide/index.rst b/docs/guide/index.rst index 35a74211e..5df45c271 100644 --- a/docs/guide/index.rst +++ b/docs/guide/index.rst @@ -32,6 +32,7 @@ Verilator User's Guide languages.rst extensions.rst + control.rst executables.rst warnings.rst files.rst