From 32dafdcc616bf4ee71250d13b887a763727196f7 Mon Sep 17 00:00:00 2001 From: Wilson Snyder Date: Sat, 20 Dec 2025 22:41:26 -0500 Subject: [PATCH] Internals: Cleanup some docstrfmt issues. --- docs/guide/connecting.rst | 8 ++++---- docs/guide/contributors.rst | 7 ++++--- docs/guide/example_binary.rst | 3 +-- docs/guide/example_cc.rst | 3 +-- docs/guide/extensions.rst | 6 +++--- docs/guide/faq.rst | 4 ++-- docs/guide/install.rst | 8 ++++---- docs/guide/languages.rst | 4 ++-- docs/guide/verilating.rst | 9 +++++---- docs/guide/warnings.rst | 10 +++++----- docs/internals.rst | 27 +++++++++++++++++---------- 11 files changed, 48 insertions(+), 41 deletions(-) diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst index dab359147..c9d7f7578 100644 --- a/docs/guide/connecting.rst +++ b/docs/guide/connecting.rst @@ -502,16 +502,16 @@ described above is just a wrapper which calls these two functions. 3. If using delays and :vlopt:`--timing`, there are two additional methods the user should call: - * ``designp->eventsPending()``, which returns ``true`` if there are - any delayed events pending, + * ``designp->eventsPending()``, which returns ``true`` if there are any + delayed events pending, * ``designp->nextTimeSlot()``, which returns the simulation time of the next delayed event. This method can only be called if ``designp->eventsPending()`` returned ``true``. Call ``eventsPending()`` to check if you should continue with the simulation, and then ``nextTimeSlot()`` to move simulation time forward. -:vlopt:`--main` can be used with :vlopt:`--timing` to generate a basic example -of a timing-enabled eval loop. +:vlopt:`--main` can be used with :vlopt:`--timing` to generate a basic +example of a timing-enabled eval loop. When ``eval()`` (or ``eval_step()``) is called Verilator looks for changes in clock signals and evaluates related sequential always blocks, such as diff --git a/docs/guide/contributors.rst b/docs/guide/contributors.rst index dd5676cce..a782eb120 100644 --- a/docs/guide/contributors.rst +++ b/docs/guide/contributors.rst @@ -29,9 +29,10 @@ Alliance `_, and `Antmicro Ltd Previous major corporate sponsors of Verilator, by providing significant contributions of time or funds include: Antmicro Ltd., Atmel Corporation, Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd., Fractile -Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed Technologies -Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus -Networks Inc., SiCortex Inc, Shunyao CAD, and Western Digital Inc. +Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed +Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems +Inc., Nauticus Networks Inc., SiCortex Inc, Shunyao CAD, and Western +Digital Inc. The contributors of major functionality are: Jeremy Bennett, Krzysztof Bieganski, Byron Bradley, Lane Brooks, John Coiner, Duane Galbi, Arkadiusz diff --git a/docs/guide/example_binary.rst b/docs/guide/example_binary.rst index c8d656b52..6633d46d1 100644 --- a/docs/guide/example_binary.rst +++ b/docs/guide/example_binary.rst @@ -39,8 +39,7 @@ Breaking this command down: #. :vlopt:`-j` `0` to Verilate using use as many CPU threads as the machine has. -#. :vlopt:`-Wall` so Verilator has stronger lint warnings - enabled. +#. :vlopt:`-Wall` so Verilator has stronger lint warnings enabled. #. An finally, :command:`our.v`, which is our SystemVerilog design file. diff --git a/docs/guide/example_cc.rst b/docs/guide/example_cc.rst index 7278d7270..c01f294d5 100644 --- a/docs/guide/example_cc.rst +++ b/docs/guide/example_cc.rst @@ -60,8 +60,7 @@ Breaking this command down: #. :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. +#. :vlopt:`-Wall` so Verilator has stronger lint warnings enabled. #. And finally, :command:`our.v` which is our SystemVerilog design file. diff --git a/docs/guide/extensions.rst b/docs/guide/extensions.rst index 79d4d50fa..e4d003c2a 100644 --- a/docs/guide/extensions.rst +++ b/docs/guide/extensions.rst @@ -1,9 +1,9 @@ .. 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 diff --git a/docs/guide/faq.rst b/docs/guide/faq.rst index dd56b20da..b806ca180 100644 --- a/docs/guide/faq.rst +++ b/docs/guide/faq.rst @@ -403,8 +403,8 @@ How do I get faster build times? environment variable to override this. Also see the :vlopt:`--output-split` option and :ref: `Profiling ccache efficiency`. -* To reduce the compile time of classes that use a Verilated module (e.g., a - top CPP file) you may wish to add a +* To reduce the compile time of classes that use a Verilated module (e.g., + a top CPP file) you may wish to add a :option:`/*verilator&32;no_inline_module*/` metacomment to your top-level module. This will decrease the amount of code in the model's Verilated class, improving compile times of any instantiating top-level C++ code, diff --git a/docs/guide/install.rst b/docs/guide/install.rst index b7a1c1297..b9ac0ad94 100644 --- a/docs/guide/install.rst +++ b/docs/guide/install.rst @@ -163,10 +163,10 @@ packages (see internals.rst), and a Python virtual environment: cpan install Pod::Perldoc The Python virtual environment is only required for running the whole test -suite, and for additional development steps like linting and formatting. It is -not required for building Verilator itself. To install the python virtual -environment and all dependencies automatically, run the following once, after -``configure``: +suite, and for additional development steps like linting and formatting. It +is not required for building Verilator itself. To install the python +virtual environment and all dependencies automatically, run the following +once, after ``configure``: .. code-block:: bash diff --git a/docs/guide/languages.rst b/docs/guide/languages.rst index a5da686f2..05dc1f8ed 100644 --- a/docs/guide/languages.rst +++ b/docs/guide/languages.rst @@ -143,8 +143,8 @@ error, except: * delay statements - they are ignored (as they are in synthesis), though they do issue a :option:`STMTDLY` warning, -* intra-assignment timing controls - they are ignored, though they do issue an - :option:`ASSIGNDLY` warning, +* intra-assignment timing controls - they are ignored, though they do issue + an :option:`ASSIGNDLY` warning, * net delays - they are ignored, * event controls at the top of the procedure, diff --git a/docs/guide/verilating.rst b/docs/guide/verilating.rst index 7e79d3641..25b5e966f 100644 --- a/docs/guide/verilating.rst +++ b/docs/guide/verilating.rst @@ -22,8 +22,8 @@ Verilator may be used in five major ways: that may be used to feed into other user-designed tools. * With the :vlopt:`-E` option, Verilator will preprocess the code according - to IEEE preprocessing rules and write the output to standard out. This - is useful to feed other tools and to debug how "\`define" statements are + to IEEE preprocessing rules and write the output to standard out. This is + useful to feed other tools and to debug how "\`define" statements are expanded. @@ -80,8 +80,9 @@ Verilator first reads all files provided on the command line and :vlopt:`-f` files, and parses all modules within. Each module is assigned to the most recent library specified with :vlopt:`-work`, thus `-work liba a.v -work libb b.v` will assign modules in `a.v` to `liba` and modules in -`b.v` to `libb`. In the absence of a `-work` mapping, each module is optionally -assigned to a library based on mappings provided by :vlopt:`-libmap`. +`b.v` to `libb`. In the absence of a `-work` mapping, each module is +optionally assigned to a library based on mappings provided by +:vlopt:`-libmap`. If a module is not defined from a file on the command-line, Verilator attempts to find a filename constructed from the module name using diff --git a/docs/guide/warnings.rst b/docs/guide/warnings.rst index f231e0894..eeec260b5 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: @@ -46,8 +46,8 @@ Warnings may be disabled in multiple ways: lint_off -rule UNSIGNED -file "*/example.v" -lines 1 Metacomments and control file directives do not interact. If a warning is -disabled by either metacomments, or a directive in a control file, it will not -be emitted. +disabled by either metacomments, or a directive in a control file, it will +not be emitted. Error And Warning Format ======================== diff --git a/docs/internals.rst b/docs/internals.rst index cf5325f4b..df592e8ac 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1,8 +1,8 @@ |Logo| -===================== - Verilator Internals -===================== +=================== +Verilator Internals +=================== .. contents:: :depth: 3 @@ -1771,8 +1771,8 @@ files that were read, filtered by preprocessing. This file can be fed back into Verilator, replacing on the command line all of the previous input files, to enable simplification of test cases. This file also contains most command line arguments Verilator was invoked as `// verilator fargs`` -metacomments, with and can be parsed by ``-f`. So to reproduce the run that -created the file, run: +metacomments, with and can be parsed by `\`-f`. So to reproduce the run +that created the file, run: :: verilator -f __inputs.vpp __inputs.vpp @@ -2095,11 +2095,18 @@ To print a node: ``src/.gdbinit`` and ``src/.gdbinit.py`` define handy utilities for working with JSON AST dumps. For example: -* ``jstash nodep`` - Perform a JSON AST dump and save it into GDB value history (e.g. ``$1``) -* ``jtree nodep`` - Perform a JSON AST dump and pretty print it using ``astsee_verilator``. -* ``jtree $1`` - Pretty print a dump that was previously saved by ``jstash``. -* ``jtree nodep -d '.file, .timeunit'`` - Perform a JSON AST dump, filter out some fields and pretty print it. -* ``jtree 0x55555613dca0`` - Pretty print using address literal (rather than actual pointer). +* ``jstash nodep`` - Perform a JSON AST dump and save it into GDB value + history (e.g. ``$1``) + +* ``jtree nodep`` - Perform a JSON AST dump and pretty print it using + ``astsee_verilator``. +* ``jtree $1`` - Pretty print a dump that was previously saved by + ``jstash``. +* ``jtree nodep -d '.file, .timeunit'`` - Perform a JSON AST dump, filter + out some fields and pretty print it. + +* ``jtree 0x55555613dca0`` - Pretty print using address literal (rather + than actual pointer). * ``jtree $1 nodep`` - Diff ``nodep`` against an older dump. A detailed description of ``jstash`` and ``jtree`` can be displayed using