From d61ad04f3289760c8f9ad8ecdf6459e83452ae02 Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Fri, 9 Dec 2022 21:01:33 -0500 Subject: [PATCH] docs: Fix and test for AsciiDoc breaks (#3728) --- docs/guide/connecting.rst | 4 +- docs/guide/example_cc.rst | 6 +- docs/guide/example_dist.rst | 2 +- docs/guide/exe_sim.rst | 8 +-- docs/guide/exe_verilator.rst | 98 +++++++++++++++-------------- docs/guide/extensions.rst | 10 +-- docs/guide/languages.rst | 11 ++-- docs/guide/simulating.rst | 16 ++--- docs/guide/verilating.rst | 10 +-- docs/guide/warnings.rst | 35 ++++++----- test_regress/t/t_dist_docs_style.pl | 2 +- 11 files changed, 106 insertions(+), 96 deletions(-) diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst index 16f569007..177af7520 100644 --- a/docs/guide/connecting.rst +++ b/docs/guide/connecting.rst @@ -51,8 +51,8 @@ also the instance of the top level instance in the design hierarchy (what you would refer to with :code:`$root` in SystemVerilog). This meant that all internal variables that were implemented by Verilator in the root scope were accessible as members of the model class itself. Note there were often -many such variable due to module inlining, including :code:`/* verilator -public_flat */` items. +many such variable due to module inlining, including +:code:`/* verilator public_flat */` items. This means that user code that accesses internal signals in the model (likely including :code:`/* verilator public_flat */` signals, as they are diff --git a/docs/guide/example_cc.rst b/docs/guide/example_cc.rst index 3d8662aba..41280015b 100644 --- a/docs/guide/example_cc.rst +++ b/docs/guide/example_cc.rst @@ -58,13 +58,13 @@ Breaking this command down: own compile rules, and run make yourself as we show in :ref:`Example SystemC Execution`.) -#. :vlopt:`-j` `0' to Verilate using use as many CPU threads as the machine - has. +#. :vlopt:`-j 0 <-j>` to Verilate using use as many CPU threads as the + machine has. #. :vlopt:`-Wall` so Verilator has stronger lint warnings enabled. -#. An finally, :command:`our.v` which is our SystemVerilog design file. +#. And finally, :command:`our.v` which is our SystemVerilog design file. Once Verilator completes we can see the generated C++ code under the :file:`obj_dir` directory. diff --git a/docs/guide/example_dist.rst b/docs/guide/example_dist.rst index 6e6947071..c68509e11 100644 --- a/docs/guide/example_dist.rst +++ b/docs/guide/example_dist.rst @@ -7,7 +7,7 @@ Examples in the Distribution ============================ See the ``examples/`` directory that is part of the distribution, and -is installed (in a OS-specific place, often in e.g. +is installed (in an OS-specific place, often in e.g. ``/usr/local/share/verilator/examples``). These examples include: examples/make_hello_binary diff --git a/docs/guide/exe_sim.rst b/docs/guide/exe_sim.rst index 03dd1d76e..48b85f4fe 100644 --- a/docs/guide/exe_sim.rst +++ b/docs/guide/exe_sim.rst @@ -82,10 +82,10 @@ Summary: .. option:: +verilator+rand+reset+ - When a model was Verilated using :vlopt:`--x-initial unique - <--x-initial>`, sets the simulation runtime initialization technique. 0 - = Reset to zeros. 1 = Reset to all-ones. 2 = Randomize. See - :ref:`Unknown States`. + When a model was Verilated using + :vlopt:`--x-initial unique <--x-initial>`, sets the simulation runtime + initialization technique. 0 = Reset to zeros. 1 = Reset to all-ones. 2 + = Randomize. See :ref:`Unknown States`. .. option:: +verilator+seed+ diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index d1efb3f25..25534b23c 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -29,10 +29,10 @@ Summary: .. option:: Specifies optional object or library files to be linked in with the - Verilog code, as a shorthand for :vlopt:`-LDFLAGS \`. 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. + Verilog code, as a shorthand for + :vlopt:`-LDFLAGS \ <-LDFLAGS>`. The file path should either be + absolute, or relative to where the make will be executed from, or add to + your makefile's VPATH the appropriate directory to find the file. If any files are specified in this way, Verilator will include a make rule that uses these files when linking the module's executable. This @@ -257,10 +257,11 @@ Summary: .. option:: -D= - Defines the given preprocessor symbol. Similar to :vlopt:`+define - <+define+>`, but does not allow multiple definitions with a single - option using plus signs. "+define" is fairly standard across Verilog - tools while "-D" is similar to :command:`gcc -D`. + Defines the given preprocessor symbol. Similar to + :vlopt:`+define <+define+>`, but does not allow multiple + definitions with a single option using plus signs. "+define" is fairly + standard across Verilog tools while "-D" is similar to + :command:`gcc -D`. .. option:: --debug @@ -270,10 +271,10 @@ Summary: generally is a less-optimized binary with symbols present (so GDB can be used on it). * Enable debugging messages (equivalent to :vlopt:`--debugi 3 <--debugi>`). * Enable internal assertions (equivalent to :vlopt:`--debug-check`). - * Enable intermediate form dump files (equivalent to :vlopt:`--dumpi-tree 3 - <--dumpi-tree>`). - * Leak to make node numbers unique (equivalent to :vlopt:`--debug-leak - <--no-debug-leak>`. + * Enable intermediate form dump files (equivalent to + :vlopt:`--dumpi-tree 3 <--dumpi-tree>`). + * Leak to make node numbers unique (equivalent to + :vlopt:`--debug-leak <--no-debug-leak>`. * Call abort() instead of exit() if there are any errors (so GDB can see the program state). @@ -304,9 +305,10 @@ Summary: .. option:: --debugi- Rarely needed - for developer use. Set the specified Verilator source - file to the specified level (e.g. :vlopt:`--debugi-V3Width 9 - <--debugi>`). Higher levels produce more detailed messages. See - :vlopt:`--debug` for other implications of enabling debug. + file to the specified level (e.g. + :vlopt:`--debugi-V3Width 9 <--debugi>`). Higher levels produce more + detailed messages. See :vlopt:`--debug` for other implications of + enabling debug. .. option:: --no-decoration @@ -378,9 +380,9 @@ Summary: Rarely needed. Enable dumping Ast .tree debug files with dumping level 3, which dumps the standard critical stages. For details on the format see the Verilator Internals manual. :vlopt:`--dump-tree` is enabled - automatically with :vlopt:`--debug`, so :vlopt:`--debug --no-dump-tree - <--dump-tree>` may be useful if the dump files are large and not - desired. + automatically with :vlopt:`--debug`, so + :vlopt:`--debug --no-dump-tree <--dump-tree>` may be useful if the dump + files are large and not desired. .. option:: --dump-tree-dot @@ -392,7 +394,7 @@ Summary: Rarely needed - for developer use. Replace AST node addresses with short identifiers in tree dumps to enhance readability. Each unique - pointer value is mapped to a unique identifier, but note that this is + pointer value is mapped to an unique identifier, but note that this is not necessarily unique per node instance as an address might get reused by a newly allocated node after a node with the same address has been dumped then freed. @@ -570,7 +572,7 @@ Summary: Rarely needed. Suppress an unknown Verilator option for an option that takes no additional arguments. This is used to allow scripts written - with pragmas for a later version of Verilator to run under a older + with pragmas for a later version of Verilator to run under an older version. e.g. :code:`-future0 option --option` would on older versions that do not understand :code:`--option` or :code:`+option` suppress what would otherwise be an invalid option error, and on newer versions that @@ -582,13 +584,14 @@ Summary: Rarely needed. Suppress an unknown Verilator option for an option that takes an additional argument. This is used to allow scripts written - with pragmas for a later version of Verilator to run under a older + with pragmas for a later version of Verilator to run under an older version. e.g. :code:`-future1 option --option arg` would on older - versions that do not understand :code:`--option arg` or :code:`+option - arg` suppress what would otherwise be an invalid option error, and on - newer versions that implement :code:`--option arg`, :code:`-future1 - option --option arg` would have the :code:`-future1 option` ignored and - the :code:`--option arg` would function appropriately. + versions that do not understand :code:`--option arg` or + :code:`+option arg` suppress what would otherwise be an invalid option + error, and on newer versions that implement :code:`--option arg`, + :code:`-future1 option --option arg` would have the + :code:`-future1 option` ignored and the :code:`--option arg` would function + appropriately. .. option:: -G= @@ -711,9 +714,9 @@ Summary: methodologies. Default is an l2-name matching the top module. The default before Verilator 3.884 was ``--l2-name v``. - For example, the program :code:`module t; initial $display("%m"); - endmodule` will show by default "t". With ``--l2-name v`` it will print - "v". + For example, the program + :code:`module t; initial $display("%m"); endmodule` will show by default + "t". With ``--l2-name v`` it will print "v". .. option:: --language @@ -855,8 +858,8 @@ Summary: Enables slow optimizations for the code Verilator itself generates (as opposed to :vlopt:`-CFLAGS -O3 <-CFLAGS>` which effects the C compiler's optimization. :vlopt:`-O3` may improve simulation performance at the - cost of compile time. This currently sets :vlopt:`--inline-mult -1 - <--inline-mult>`. + cost of compile time. This currently sets + :vlopt:`--inline-mult -1 <--inline-mult>`. .. option:: -O @@ -1096,18 +1099,18 @@ Summary: .. option:: --public-flat-rw Declares all variables, ports and wires public as if they had - :code:`/*verilator public_flat_rw @ - ()*/` metacomments. This will make them - VPI accessible by their flat name, but not turn off module inlining. - This is particularly useful in combination with :vlopt:`--vpi`. This may - also in some rare cases result in mis-simulation of generated clocks. - Instead of this global option, marking only those signals that need - public_flat_rw is typically significantly better performing. + :code:`/*verilator public_flat_rw @ ()*/` + metacomments. This will make them VPI accessible by their flat name, + but not turn off module inlining. This is particularly useful in + combination with :vlopt:`--vpi`. This may also in some rare cases result + in mis-simulation of generated clocks. Instead of this global option, + marking only those signals that need public_flat_rw is typically + significantly better performing. .. option:: -pvalue+= - Overwrites the given parameter(s) of the toplevel module. See :vlopt:`-G - <-G>` for a detailed description. + Overwrites the given parameter(s) of the toplevel module. See + :vlopt:`-G <-G>` for a detailed description. .. option:: --quiet-exit @@ -1465,7 +1468,7 @@ Summary: Rarely needed. Suppress unknown Verilator comments or warning messages with the given message code. This is used to allow code written with - pragmas for a later version of Verilator to run under a older version; + pragmas for a later version of Verilator to run under an older version; add "-Wfuture-" arguments for each message code or comment that the new version supports which the older version does not support. @@ -1753,15 +1756,16 @@ The grammar of configuration commands is as follows: .. 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 true, or - failing that, will insert the appropriate code to detect failing cases - at simulation runtime and print an "Assertion failed" error message. + 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 + 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 a unit of hierarchical Verilation. Note + 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`. diff --git a/docs/guide/extensions.rst b/docs/guide/extensions.rst index 5cb0cf572..c3f5c6621 100644 --- a/docs/guide/extensions.rst +++ b/docs/guide/extensions.rst @@ -57,10 +57,10 @@ or "`ifdef`"'s may break other tools. Verilator does not use any text inside the quotes for ordering/scheduling. If you need the $c to be called at a specific time, e.g. when a variable changes, then the $c must be under an - appropriate sensitivity statement, e.g. :code:`always @(posedge clk) - $c("func()")` to call it on every edge, or e.g. :code:`always @* - c("func(",a,")")` to call it when :code:`a` changes (the latter working - because :code:`a` is outside the quotes). + appropriate sensitivity statement, e.g. + :code:`always @(posedge clk) $c("func()")` to call it on every edge, or + e.g. :code:`always @* c("func(",a,")")` to call it when :code:`a` + changes (the latter working because :code:`a` is outside the quotes). If you will be reading or writing any Verilog variables inside the C++ functions, the Verilog signals must be declared with @@ -251,7 +251,7 @@ or "`ifdef`"'s may break other tools. .. option:: /*verilator&32;hier_block*/ - Specifies that the module is a unit of hierarchical Verilation. This + Specifies that the module is an unit of hierarchical Verilation. This metacomment must be between :code:`module module_name(...);` and :code:`endmodule`. The module will not be inlined nor uniquified for each instance in hierarchical Verilation. Note that the metacomment is diff --git a/docs/guide/languages.rst b/docs/guide/languages.rst index e600dc314..21acd8ff6 100644 --- a/docs/guide/languages.rst +++ b/docs/guide/languages.rst @@ -80,10 +80,11 @@ string, and wreal. Synthesis Directive Assertion Support ------------------------------------- -With the :vlopt:`--assert` option, Verilator reads any :code:`//synopsys -full_case` or :code:`//synopsys parallel_case` directives. The same -applies to any :code:`//ambit synthesis`, :code:`//cadence` or -:code:`//pragma` directives of the same form. +With the :vlopt:`--assert` option, Verilator reads any + +:code:`//synopsys full_case` or :code:`//synopsys parallel_case` +directives. The same applies to any :code:`//ambit synthesis`, +:code:`//cadence` or :code:`//pragma` directives of the same form. When these synthesis directives are discovered, Verilator will either formally prove the directive to be true, or failing that, will insert the @@ -369,7 +370,7 @@ and the address. For non-power-of-2-sizes arrays, index 0 will be written. Reading a memory element that is outside the bounds specified for the array will give a width warning and wrap around the power-of-2 size. For -non-power-of-2 sizes, it will return a unspecified constant of the +non-power-of-2 sizes, it will return an unspecified constant of the appropriate width. diff --git a/docs/guide/simulating.rst b/docs/guide/simulating.rst index 7209a0a19..271985836 100644 --- a/docs/guide/simulating.rst +++ b/docs/guide/simulating.rst @@ -18,12 +18,14 @@ Benchmarking & Optimization =========================== For best performance, run Verilator with the :vlopt:`-O3` -:vlopt:`--x-assign fast <--x-assign>` :vlopt:`--x-initial fast -<--x-initial>` :vlopt:`--noassert <--assert>` options. The :vlopt:`-O3` -option will require longer time to run Verilator, and :vlopt:`--x-assign -fast <--x-assign>` :vlopt:`--x-initial fast <--x-assign>` may increase the -risk of reset bugs in trade for performance; see the above documentation -for these options. +:vlopt:`--x-assign fast <--x-assign>` +:vlopt:`--x-initial fast <--x-initial>` +:vlopt:`--noassert <--assert>` options. The :vlopt:`-O3` +option will require longer time to run Verilator, and +:vlopt:`--x-assign fast <--x-assign>` +:vlopt:`--x-initial fast <--x-assign>` +may increase the risk of reset bugs in trade for performance; see the above +documentation for these options. If using Verilated multithreaded, use ``numactl`` to ensure you are using non-conflicting hardware resources. See :ref:`Multithreading`. Also @@ -162,7 +164,7 @@ Line Coverage With :vlopt:`--coverage` or :vlopt:`--coverage-line`, Verilator will automatically add coverage analysis at each code flow change point (e.g. at -branches). At each such branch a unique counter is incremented. At the +branches). At each such branch an unique counter is incremented. At the end of a test, the counters along with the filename and line number corresponding to each counter are written into the coverage file. diff --git a/docs/guide/verilating.rst b/docs/guide/verilating.rst index f041097d2..2f91bf7f8 100644 --- a/docs/guide/verilating.rst +++ b/docs/guide/verilating.rst @@ -239,17 +239,17 @@ physical core. For best performance use the :command:`numactl` program to (when the threading count fits) select unique physical cores on the same socket. The same applies for :vlopt:`--trace-threads` as well. -As an example, if a model was Verilated with :vlopt:`--threads 4 -<--threads>`, we consult: +As an example, if a model was Verilated with +:vlopt:`--threads 4 <--threads>`, we consult: .. code-block:: bash egrep 'processor|physical id|core id' /proc/cpuinfo To select cores 0, 1, 2, and 3 that are all located on the same socket (0) -but different physical cores. (Also useful is :command:`numactl ---hardware`, or :command:`lscpu` but those doesn't show Hyperthreading -cores.) Then we execute: +but different physical cores. (Also useful is +:command:`numactl --hardware`, or :command:`lscpu` but those doesn't show +hyperthreading cores.) Then we execute: .. code-block:: bash diff --git a/docs/guide/warnings.rst b/docs/guide/warnings.rst index 071fc01b8..db4344cd9 100644 --- a/docs/guide/warnings.rst +++ b/docs/guide/warnings.rst @@ -150,11 +150,11 @@ List Of Warnings practice. Verilator reports this as an error, because ignoring this warning may make Verilator simulations differ from other simulators. - It is generally safe to disable this error (with a :code:`// verilator - lint_off BLKANDNBLK` metacomment or the :code:`-Wno-BLKANDNBLK` option) - when one of the assignments is inside a public task, or when the - blocking and non-blocking assignments have non-overlapping bits and - structure members. + It is generally safe to disable this error (with a + :code:`// verilator lint_off BLKANDNBLK` metacomment or the + :code:`-Wno-BLKANDNBLK` option) when one of the assignments is inside a + public task, or when the blocking and non-blocking assignments have + non-overlapping bits and structure members. Generally, this is caused by a register driven by both combo logic and a flop: @@ -383,8 +383,10 @@ List Of Warnings Verilog, but not SystemVerilog, a wire must be used as the target of continuous assignments. - This error is only reported when :vlopt:`--language 1364-1995 - <--language>`, :vlopt:`--language 1364-2001 <--language>`, or + This error is only reported when + + :vlopt:`--language 1364-1995 <--language>`, + :vlopt:`--language 1364-2001 <--language>`, or :vlopt:`--language 1364-2005 <--language>` is used. Ignoring this error will only suppress the lint check, it will simulate @@ -483,7 +485,7 @@ List Of Warnings Error at simulation runtime when model did not properly settle. Verilator sometimes has to evaluate combinatorial logic multiple times, - usually around code where a UNOPTFLAT warning was issued, but disabled. + usually around code where an UNOPTFLAT warning was issued, but disabled. Faulty example: @@ -499,12 +501,13 @@ List Of Warnings To debug this, first review any UNOPTFLAT warnings that were ignored. Though typically it is safe to ignore UNOPTFLAT (at a - performance cost), at the time of issuing a UNOPTFLAT Verilator did not + performance cost), at the time of issuing an UNOPTFLAT Verilator did not know if the logic would eventually converge and assumed it would. - Next, run Verilator with :vlopt:`--prof-cfuncs -CFLAGS -DVL_DEBUG - <--prof-cfuncs>`. Rerun the test. Now just before the convergence - error you should see additional output similar to this: + Next, run Verilator with + :vlopt:`--prof-cfuncs -CFLAGS -DVL_DEBUG <--prof-cfuncs>`. Rerun the + test. Now just before the convergence error you should see additional + output similar to this: .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_msg.rst @@ -983,7 +986,7 @@ List Of Warnings Warns that a module has a pin which is not mentioned in an instance. If a pin is not missing it should still be specified on the instance - declaration with a empty connection, using :code:`(.pin_name())`. + declaration with an empty connection, using :code:`(.pin_name())`. Ignoring this warning will only suppress the lint check, it will simulate correctly. @@ -1161,7 +1164,7 @@ List Of Warnings example.v:1:20: ... Location of previous definition, with value: 'def2' The best solution is to use a different name for the second macro. If - this is not possible, add a undef to indicate the code is overriding the + this is not possible, add an undef to indicate the code is overriding the value. This will express the intent and should avoid future warnings on any linting tool: @@ -1555,7 +1558,7 @@ List Of Warnings .. TODO better example - Warns that the code is comparing a unsigned value in a way that implies + Warns that the code is comparing an unsigned value in a way that implies it is signed, for example "X < 0" will always be false when X is unsigned. @@ -1716,7 +1719,7 @@ List Of Warnings .. include:: ../../docs/gen/ex_VARHIDDEN_msg.rst - To resolve, rename the variable to a unique name. + To resolve, rename the variable to an unique name. .. option:: WAITCONST diff --git a/test_regress/t/t_dist_docs_style.pl b/test_regress/t/t_dist_docs_style.pl index 0cda99082..035c25176 100755 --- a/test_regress/t/t_dist_docs_style.pl +++ b/test_regress/t/t_dist_docs_style.pl @@ -23,7 +23,7 @@ foreach my $file (sort keys %files) { my $contents = file_contents($filename); checkPattern($filename, $contents, - qr/.*(?