diff --git a/README.rst b/README.rst index 5093785cc..cd067fffa 100644 --- a/README.rst +++ b/README.rst @@ -152,9 +152,9 @@ Verilator is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License Version 3 or the Perl Artistic License Version 2.0. See the documentation for more details. -.. _CHIPS Alliance: https://chipsalliance.org -.. _Icarus Verilog: https://steveicarus.github.io/iverilog -.. _Linux Foundation: https://www.linuxfoundation.org +.. _chips alliance: https://chipsalliance.org +.. _icarus verilog: https://steveicarus.github.io/iverilog +.. _linux foundation: https://www.linuxfoundation.org .. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png .. |verilator multithreaded performance| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png .. |verilator usage| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png diff --git a/ci/docker/buildenv/README.rst b/ci/docker/buildenv/README.rst index ee4c1095a..a111e1be7 100644 --- a/ci/docker/buildenv/README.rst +++ b/ci/docker/buildenv/README.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Verilator Build Docker Container: +.. _verilator build docker container: Verilator Build Docker Container ================================ diff --git a/docs/guide/connecting.rst b/docs/guide/connecting.rst index ac6c55971..b951acd97 100644 --- a/docs/guide/connecting.rst +++ b/docs/guide/connecting.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Connecting: +.. _connecting: ****************************** Connecting to Verilated Models @@ -39,7 +39,7 @@ model: internals, including :code:`/* verilator public_flat */` items. -.. _Porting from pre 4.210: +.. _porting from pre 4.210: Model interface changes in version 4.210 ------------------------------------------ @@ -78,7 +78,7 @@ often inlined into the root scope) will need to be updated as follows: contain one additional indirection via the :code:`rootp` pointer. -.. _Connecting to C++: +.. _connecting to C++: Connecting to C++ ================= @@ -418,7 +418,7 @@ be deferred for later. These delayed values can be flushed to the model with :code:`VerilatedVpi::doInertialPuts()`. -.. _VPI Example: +.. _vpi example: VPI Example ----------- @@ -482,7 +482,7 @@ accesses the above signal "readme" would be: EOF -.. _Evaluation Loop: +.. _evaluation loop: Wrappers and Model Evaluation Loop ================================== diff --git a/docs/guide/contributing.rst b/docs/guide/contributing.rst index e25fa9bc4..b5d82f3b5 100644 --- a/docs/guide/contributing.rst +++ b/docs/guide/contributing.rst @@ -62,7 +62,7 @@ Finally, report the bug at `Verilator Issues `_. The bug will become publicly visible; if this is unacceptable, mail the bug report to ``wsnyder@wsnyder.org``. -.. _Minimizing bug-inducing code: +.. _minimizing bug-inducing code: Minimizing bug-inducing code ============================ diff --git a/docs/guide/deprecations.rst b/docs/guide/deprecations.rst index b8f573570..1d7f85f75 100644 --- a/docs/guide/deprecations.rst +++ b/docs/guide/deprecations.rst @@ -21,7 +21,7 @@ XML output Verilator currently supports XML parser output (enabled with `--xml-only`). Support for `--xml-*` options will be deprecated no sooner than January 2026. ---make cmake +`--make cmake` The `--make cmake` options is deprecated and will be removed no sooner than January 2026. Use `--make json` instead. Note that the CMake integration shipping with Verilator (verilator-config.mk) already uses `--make json` so diff --git a/docs/guide/example_binary.rst b/docs/guide/example_binary.rst index 3085d235d..1dfa4b62c 100644 --- a/docs/guide/example_binary.rst +++ b/docs/guide/example_binary.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Example Create-Binary Execution: +.. _example create-binary execution: Example Create-Binary Execution =============================== diff --git a/docs/guide/example_cc.rst b/docs/guide/example_cc.rst index 2173e64e1..1df01228c 100644 --- a/docs/guide/example_cc.rst +++ b/docs/guide/example_cc.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Example C++ Execution: +.. _example c++ execution: Example C++ Execution ===================== diff --git a/docs/guide/example_dist.rst b/docs/guide/example_dist.rst index cafb63c12..fa042ff3b 100644 --- a/docs/guide/example_dist.rst +++ b/docs/guide/example_dist.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Examples in the Distribution: +.. _examples in the distribution: Examples in the Distribution ============================ diff --git a/docs/guide/example_sc.rst b/docs/guide/example_sc.rst index c6e235785..3c448e8bc 100644 --- a/docs/guide/example_sc.rst +++ b/docs/guide/example_sc.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Example SystemC Execution: +.. _example systemc execution: Example SystemC Execution ========================= diff --git a/docs/guide/examples.rst b/docs/guide/examples.rst index 7c27c6d5f..7d32c0188 100644 --- a/docs/guide/examples.rst +++ b/docs/guide/examples.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Examples: +.. _examples: ======== Examples diff --git a/docs/guide/exe_sim.rst b/docs/guide/exe_sim.rst index abe946acd..e79bcf537 100644 --- a/docs/guide/exe_sim.rst +++ b/docs/guide/exe_sim.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Simulation Runtime Arguments: +.. _simulation runtime arguments: Simulation Runtime Arguments ============================ diff --git a/docs/guide/exe_verilator.rst b/docs/guide/exe_verilator.rst index 6ec700b0e..3e5337089 100644 --- a/docs/guide/exe_verilator.rst +++ b/docs/guide/exe_verilator.rst @@ -2196,7 +2196,7 @@ Summary: filenames. -.. _Verilator Control Files: +.. _verilator control files: ======================= Verilator Control Files diff --git a/docs/guide/files.rst b/docs/guide/files.rst index 47e82a1a8..38da5bfd1 100644 --- a/docs/guide/files.rst +++ b/docs/guide/files.rst @@ -5,7 +5,7 @@ Files ***** -.. _Files in the Distribution: +.. _files in the distribution: Files in the Git Tree ===================== @@ -28,7 +28,7 @@ Verilator: test_regress => Internal tests -.. _Files Read/Written: +.. _files read/written: Files Read/Written ================== @@ -42,33 +42,33 @@ For --cc/--sc, it creates: .. list-table:: - * - *{prefix}*\ .json + * - *{prefix}*.json - JSON build definition compiling (from --make json) - * - *{prefix}*\ .mk + * - *{prefix}*.mk - Make include file for compiling (from --make gmake) * - *{prefix}*\ _classes.mk - Make include file with class names (from --make gmake) - * - *{prefix}*\ .h + * - *{prefix}*.h - Model header - * - *{prefix}*\ .cpp + * - *{prefix}*.cpp - Model C++ file * - *{prefix}*\ ___024root.h - Top-level internal header file (from SystemVerilog $root) * - *{prefix}*\ ___024root.cpp - Top-level internal C++ file (from SystemVerilog $root) - * - *{prefix}*\ ___024root\ *{__n}*\ .cpp + * - *{prefix}*\ ___024root\ *{__n}*.cpp - Additional top-level internal C++ files - * - *{prefix}*\ ___024root__Slow\ *{__n}*\ .cpp + * - *{prefix}*\ ___024root__Slow\ *{__n}*.cpp - Infrequent cold routines - * - *{prefix}*\ ___024root__Trace\ *{__n}*\ .cpp + * - *{prefix}*\ ___024root__Trace\ *{__n}*.cpp - Wave file generation code (from --trace-\*) - * - *{prefix}*\ ___024root__Trace__Slow\ *{__n}*\ .cpp + * - *{prefix}*\ ___024root__Trace__Slow\ *{__n}*.cpp - Wave file generation code (from --trace-\*) * - *{prefix}*\ __Dpi.h - DPI import and export declarations (from --dpi) * - *{prefix}*\ __Dpi.cpp - Global DPI export wrappers (from --dpi) - * - *{prefix}*\ __Dpi_Export\ *{__n}*\ .cpp + * - *{prefix}*\ __Dpi_Export\ *{__n}*.cpp - DPI export wrappers scoped to this particular model (from --dpi) * - *{prefix}*\ __Inlines.h - Inline support functions @@ -76,11 +76,11 @@ For --cc/--sc, it creates: - Global symbol table header * - *{prefix}*\ __Syms.cpp - Global symbol table C++ - * - *{prefix}{each_verilog_module}*\ .h + * - *{prefix}{each_verilog_module}*.h - Lower level internal header files - * - *{prefix}{each_verilog_module}*\ .cpp + * - *{prefix}{each_verilog_module}*.cpp - Lower level internal C++ files - * - *{prefix}{each_verilog_module}{__n}*\ .cpp + * - *{prefix}{each_verilog_module}{__n}*.cpp - Additional lower C++ files For --hierarchical mode, it creates: @@ -106,13 +106,13 @@ In specific debug and other modes, it also creates: .. list-table:: - * - *{prefix}*\ .sarif + * - *{prefix}*.sarif - SARIF diagnostics (from --diagnostics-sarif) - * - *{prefix}*\ .tree.json + * - *{prefix}*.tree.json - JSON tree information (from --json-only) - * - *{prefix}*\ .tree.meta.json + * - *{prefix}*.tree.meta.json - JSON tree metadata (from --json-only) - * - *{prefix}*\ .xml + * - *{prefix}*.xml - XML tree information (from --xml) * - *{prefix}*\ __cdc.txt - Clock Domain Crossing checks (from --cdc) @@ -124,30 +124,30 @@ In specific debug and other modes, it also creates: - Make dependencies (from -MMD) * - *{prefix}*\ __verFiles.dat - Timestamps (from --skip-identical) - * - *{prefix}{misc}*\ .dot + * - *{prefix}{misc}*.dot - Debugging graph files (from --debug) - * - *{prefix}{misc}*\ .tree + * - *{prefix}{misc}*.tree - Debugging files (from --debug) - * - *{prefix}*\ __inputs\ .vpp + * - *{prefix}*\ __inputs.vpp - Pre-processed verilog for all files (from --debug) - * - *{prefix}*\ _ *{each_verilog_base_filename}*\ .vpp + * - *{prefix}*\ _ *{each_verilog_base_filename}*.vpp - Pre-processed verilog for each file (from --debug) After running Make, the C++ compiler may produce the following: .. list-table:: - * - verilated{misc}*\ .d + * - verilated{misc}*.d - Intermediate dependencies - * - verilated{misc}*\ .o + * - verilated{misc}*.o - Intermediate objects - * - {mod_prefix}{misc}*\ .d + * - {mod_prefix}{misc}*.d - Intermediate dependencies - * - {mod_prefix}{misc}*\ .o + * - {mod_prefix}{misc}*.o - Intermediate objects * - *{prefix}*\ - Final executable (from --exe) - * - lib\ *{prefix}*\ .a + * - lib\ *{prefix}*.a - Final archive (default lib mode) * - libverilated.a - Runtime for verilated model (default lib mode) @@ -155,9 +155,9 @@ After running Make, the C++ compiler may produce the following: - Library of all Verilated objects * - *{prefix}*\ __ALL.cpp - Include of all code for single compile - * - *{prefix}{misc}*\ .d + * - *{prefix}{misc}*.d - Intermediate dependencies - * - *{prefix}{misc}*\ .o + * - *{prefix}{misc}*.o - Intermediate objects The Verilated executable may produce the following: diff --git a/docs/guide/install-cmake.rst b/docs/guide/install-cmake.rst index f096d769b..eb55196c9 100644 --- a/docs/guide/install-cmake.rst +++ b/docs/guide/install-cmake.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _CMakeInstallation: +.. _cmakeinstallation: ****************** CMake Installation @@ -10,7 +10,7 @@ CMake Installation This section discusses how to build and install Verilator using cmake. Currently cmake is only officially supported for Windows builds (not Linux). -.. _Tools Install: +.. _tools install: Quick Install ============= @@ -50,7 +50,7 @@ To build using ninja: cmake --install . --prefix $PWD/../install -.. _CMake Usage: +.. _cmake usage: Usage ===== diff --git a/docs/guide/install.rst b/docs/guide/install.rst index 6aebca34c..4d9dcc46d 100644 --- a/docs/guide/install.rst +++ b/docs/guide/install.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Installation: +.. _installation: ************ Installation @@ -9,7 +9,7 @@ Installation This section discusses how to install Verilator. -.. _Package Manager Quick Install: +.. _package manager quick install: Package Manager Quick Install ============================= @@ -26,7 +26,7 @@ instead.) To install as a package: For other distributions, refer to `Repology Verilator Distro Packages `__. -.. _pre-commit Quick Install: +.. _pre-commit quick install: pre-commit Quick Install ============================= @@ -46,7 +46,7 @@ To use the hook, add the following entry to your :code:`.pre-commit-config.yaml` hooks: - id: verilator -.. _Git Install: +.. _git install: Git Quick Install ================= @@ -83,7 +83,7 @@ In brief, to install from git: sudo make install -.. _Detailed Build Instructions: +.. _detailed build instructions: Detailed Build Instructions =========================== @@ -206,7 +206,7 @@ faster for different scenarios, the solver to use at run-time can be specified by the environment variable :option:`VERILATOR_SOLVER`. -.. _Obtain Sources: +.. _obtain sources: Obtain Sources -------------- diff --git a/docs/guide/languages.rst b/docs/guide/languages.rst index 1f030a883..0aa428a3e 100644 --- a/docs/guide/languages.rst +++ b/docs/guide/languages.rst @@ -172,7 +172,7 @@ using the :option:`timing_off` and :option:`timing_off` options in Verilator Control Files. -.. _Language Limitations: +.. _language limitations: Language Limitations ==================== @@ -254,7 +254,7 @@ generating one member of a structure from blocking, and another from non-blocking assignments is unsupported. -.. _Unknown States: +.. _unknown states: Unknown States -------------- diff --git a/docs/guide/simulating.rst b/docs/guide/simulating.rst index 6fb2fa08a..c50d67fb0 100644 --- a/docs/guide/simulating.rst +++ b/docs/guide/simulating.rst @@ -1,7 +1,7 @@ .. Copyright 2003-2025 by Wilson Snyder. .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -.. _Simulating: +.. _simulating: ************************************ Simulating (Verilated-Model Runtime) @@ -12,7 +12,7 @@ Verilated model's executable. For the runtime arguments to a simulated model, see :ref:`Simulation Runtime Arguments`. -.. _Simulation Summary Report: +.. _simulation summary report: Simulation Summary Report ========================= @@ -68,7 +68,7 @@ The information in this report is: Total memory used during simulation in megabytes. -.. _Benchmarking & Optimization: +.. _benchmarking & optimization: Benchmarking & Optimization =========================== @@ -174,7 +174,7 @@ keep tabs on how Verilator compares and may be able to suggest additional improvements. -.. _Coverage Analysis: +.. _coverage analysis: Coverage Analysis ================= @@ -183,15 +183,15 @@ Verilator supports adding code to the Verilated model to support SystemVerilog code coverage. With :vlopt:`--coverage`, Verilator enables all forms of coverage: -* :ref:`User Coverage` -* :ref:`Line Coverage` -* :ref:`Toggle Coverage` +- :ref:`User Coverage` +- :ref:`Line Coverage` +- :ref:`Toggle Coverage` When a model with coverage is executed, it will create a coverage file for collection and later analysis, see :ref:`Coverage Collection`. -.. _User Coverage: +.. _user coverage: Functional Coverage ------------------- @@ -208,7 +208,7 @@ point under the coverage name "DefaultClock": DefaultClock: cover property (@(posedge clk) cyc==3); -.. _Line Coverage: +.. _line coverage: Line Coverage ------------- @@ -225,7 +225,7 @@ disabled; for the most accurate results, do not disable this warning when using coverage. -.. _Toggle Coverage: +.. _toggle coverage: Toggle Coverage --------------- @@ -265,7 +265,7 @@ A :option:`/*verilator&32;coverage_off*/` signals that do not need toggle analysis, such as RAMs and register files. -.. _Expression Coverage: +.. _expression coverage: Expression Coverage ------------------- @@ -301,7 +301,7 @@ are not mutually exclusive. -000003 point: comment=(t2==0 && t4==0) => 0 hier=top.t -000002 point: comment=(t3==0 && t4==1) => 1 hier=top.t -.. _Suppressing Coverage: +.. _suppressing coverage: Suppressing Coverage -------------------- @@ -317,7 +317,7 @@ that should not occur. A :option:`/*verilator&32;coverage_block_off*/` metacomment will perform a similar function on any code in that block or below. -.. _Coverage Collection: +.. _coverage collection: Coverage Collection ------------------- @@ -362,7 +362,7 @@ and importing reports to sites such as `https://codecov.io `_. -.. _Profiling: +.. _profiling: Code Profiling ============== @@ -387,7 +387,7 @@ To use profiling: on which most of the time is being spent. -.. _Execution Profiling: +.. _execution profiling: Execution Profiling =================== @@ -423,7 +423,7 @@ saved profiling file into a visual format and produce related statistics. For more information, see :command:`verilator_gantt`. -.. _Profiling ccache efficiency: +.. _profiling ccache efficiency: Profiling ccache efficiency =========================== @@ -451,7 +451,7 @@ targets are specified, `cchache-report` will build the `default` target. This feature is currently experimental and might change in subsequent releases. -.. _Save/Restore: +.. _save/restore: Save/Restore ============ @@ -506,7 +506,7 @@ toggle rate PGO, branch prediction PGO, statement execution time PGO, or others, as they prove beneficial. -.. _Thread PGO: +.. _thread pgo: Thread Profile-Guided Optimization ---------------------------------- @@ -552,7 +552,7 @@ create new profiling data, then rerun Verilator with the same input source files and that new profiling data. -.. _Compiler PGO: +.. _compiler pgo: Compiler Profile-Guided Optimization ------------------------------------ @@ -605,7 +605,7 @@ feedback-directed optimization. See the appropriate compiler documentation. -.. _Runtime Debugging: +.. _runtime debugging: Runtime Debugging ================= diff --git a/docs/guide/verilating.rst b/docs/guide/verilating.rst index 39193096f..9002a378f 100644 --- a/docs/guide/verilating.rst +++ b/docs/guide/verilating.rst @@ -27,7 +27,7 @@ Verilator may be used in five major ways: expanded. -.. _Binary, C++ and SystemC Generation: +.. _binary, c++ and systemc generation: Binary, C++ and SystemC Generation ================================== @@ -65,7 +65,7 @@ Once a model is built, the next step is typically for the user to run it, see :ref:`Simulating`. -.. _Finding and Binding Modules: +.. _finding and binding modules: Finding and Binding Modules =========================== @@ -99,7 +99,7 @@ coexist uniquely within each library name. When IEEE `config use` is supported, more complicated selections will be able to be specified. -.. _Hierarchical Verilation: +.. _hierarchical verilation: Hierarchical Verilation ======================= @@ -168,7 +168,7 @@ But, the following usage is supported: overridden using :code:`#(.param_name(value))` construct. -.. _Overlapping Verilation and Compilation: +.. _overlapping verilation and compilation: Overlapping Verilation and Compilation -------------------------------------- @@ -220,7 +220,7 @@ Makefiles produced by Verilator presume the target system is the same type as the build system. -.. _Multithreading: +.. _multithreading: Multithreading ============== @@ -335,7 +335,7 @@ IEEE to be multithreaded, Verilator requires all VPI calls are only made from the main thread. -.. _GNU Make: +.. _gnu make: GNU Make ======== @@ -347,7 +347,7 @@ If calling Verilator from a makefile, the :vlopt:`--MMD` option will create a dependency file, allowing Make to only run Verilator if input Verilog files change. -.. _CMake: +.. _cmake: CMake ===== @@ -547,7 +547,7 @@ The search paths can be configured by setting some variables: SYSTEMC_ROOT). -.. _Verilation Summary Report: +.. _verilation summary report: Verilation Summary Report ========================= diff --git a/docs/guide/warnings.rst b/docs/guide/warnings.rst index eb5d15d5d..35f6cebb2 100644 --- a/docs/guide/warnings.rst +++ b/docs/guide/warnings.rst @@ -5,7 +5,7 @@ Errors and Warnings ===================== -.. _Disabling Warnings: +.. _disabling warnings: Disabling Warnings ================== diff --git a/docs/internals.rst b/docs/internals.rst index f9f58f893..7d25ba13e 100644 --- a/docs/internals.rst +++ b/docs/internals.rst @@ -1500,7 +1500,7 @@ that type (if it is of class ``SOMETYPE``, or a derived class of as that is faster.) -.. _Testing: +.. _testing: Testing ======= @@ -1732,8 +1732,8 @@ be controlled with ``-debugi- ``. For example ``--debug debug level 5, with the V3Width.cpp file at level 9. ---debug -------- +`--debug` +--------- When you run with ``--debug``, there are three primary output file types placed into the obj_dir, .vpp, .tree and .dot files. @@ -2173,96 +2173,124 @@ arguments are passed as Verilator arguments. driver.py Non-Scenario Arguments -------------------------------- ---benchmark [] - Show execution times of each step. If an optional number is given, - specifies the number of simulation cycles (for tests that support it). +.. program:: driver.py ---debug - Same as ``verilator --debug``: Use the debug version of Verilator which - enables additional assertions, debugging messages, and structure dump - files. +.. option:: --benchmark [] ---debugi(-) - Same as ``verilator --debugi level``: Set Verilator internal debugging - level globally to the specified debug level (1-10). + Show execution times of each step. If an optional number is given, + specifies the number of simulation cycles (for tests that support it). ---driver-clean - After a test passes, remove the generated objects. Reduces storage - requirements, but may result in longer runtime if the tests are run - again. +.. option:: --debug ---dump-tree - Same as ``verilator --dump-tree``: Enable Verilator writing .tree debug - files with dumping level 3, which dumps the standard critical stages. - For details on the format see `.tree Output`. + Same as ``verilator --debug``: Use the debug version of Verilator which + enables additional assertions, debugging messages, and structure dump + files. ---fail-max - Set the number of failing tests, after which the driver will stop running - additional tests. Defaults to 20, 0 disables. +.. option:: --debugi(-) ---gdb - Same as ``verilator --gdb``: Run Verilator under the debugger. + Same as ``verilator --debugi level``: Set Verilator internal debugging + level globally to the specified debug level (1-10). ---gdbbt - Same as ``verilator --gdbbt``: Run Verilator under the debugger, only to - print backtrace information. Requires ``--debug``. +.. option:: --driver-clean ---gdbsim - Run Verilator generated executable under the debugger. + After a test passes, remove the generated objects. Reduces storage + requirements, but may result in longer runtime if the tests are run + again. ---golden - Update golden files, equivalent to ``export HARNESS_UPDATE_GOLDEN=1``. +.. option:: --dump-tree ---hashset / - Split tests based on a hash of the test names into and run only - tests in set number (0..-1). + Same as ``verilator --dump-tree``: Enable Verilator writing .tree debug + files with dumping level 3, which dumps the standard critical stages. + For details on the format see `.tree Output`. ---help - Displays help message and exits. +.. option:: --fail-max ---j # - Run number of parallel tests, or 0 to determine the count based on the - number of cores installed. + Set the number of failing tests, after which the driver will stop + running additional tests. Defaults to 20, 0 disables. ---obj-suffix - Append the argument to the name of the ``test_regress/obj_`` directories. +.. option:: --gdb ---quiet - Suppress all output except for failures and progress messages every 15 - seconds. Intended for use only in automated regressions. See also - ``--rerun``, and ``--verbose`` which is not the opposite of ``--quiet``. + Same as ``verilator --gdb``: Run Verilator under the debugger. ---rerun - Rerun all tests that failed in this run. Reruns force the flags - ``--no-quiet --j 1``. +.. option:: --gdbbt ---rr - Same as ``verilator --rr``: Run Verilator and record with ``rr``. + Same as ``verilator --gdbbt``: Run Verilator under the debugger, only to + print backtrace information. Requires ``--debug``. ---rrsim - Run Verilator generated executable and record with ``rr``. +.. option:: --gdbsim ---site - Run site-specific tests also. + Run Verilator generated executable under the debugger. ---stop - Stop on the first error. +.. option:: --golden ---top-filename - Override the default Verilog file name. + Update golden files, equivalent to ``export HARNESS_UPDATE_GOLDEN=1``. ---trace - Set the simulator-specific flags to request waveform tracing. +.. option:: --hashset / ---valgrind - Same as ``verilator --valgrind``: Run Verilator under `Valgrind `_. + Split tests based on a hash of the test names into and run + only tests in set number (0..-1). ---verbose - Compile and run the test in verbose mode. This means ``TEST_VERBOSE`` - will be defined for the test (Verilog and any C++/SystemC wrapper). +.. option:: --help ---verilated-debug - For tests using the standard C++ wrapper, enable runtime debug mode. + Displays help message and exits. + +.. option:: --j # + + Run number of parallel tests, or 0 to determine the count based on the + number of cores installed. + +.. option:: --obj-suffix + + Append the argument to the name of the ``test_regress/obj_`` + directories. + +.. option:: --quiet + + Suppress all output except for failures and progress messages every 15 + seconds. Intended for use only in automated regressions. See also + ``--rerun``, and ``--verbose`` which is not the opposite of ``--quiet``. + +.. option:: --rerun + + Rerun all tests that failed in this run. Reruns force the flags + ``--no-quiet --j 1``. + +.. option:: --rr + + Same as ``verilator --rr``: Run Verilator and record with ``rr``. + +.. option:: --rrsim + + Run Verilator generated executable and record with ``rr``. + +.. option:: --site + + Run site-specific tests also. + +.. option:: --stop + + Stop on the first error. + +.. option:: --top-filename + + Override the default Verilog file name. + +.. option:: --trace + + Set the simulator-specific flags to request waveform tracing. + +.. option:: --valgrind + + Same as ``verilator --valgrind``: Run Verilator under `Valgrind `_. + +.. option:: --verbose + + Compile and run the test in verbose mode. This means ``TEST_VERBOSE`` + will be defined for the test (Verilog and any C++/SystemC wrapper). + +.. option:: --verilated-debug + + For tests using the standard C++ wrapper, enable runtime debug mode. driver.py Scenario Arguments @@ -2272,39 +2300,50 @@ The following options control which simulator is used, and which tests are run. Multiple flags may be used to run multiple simulators/scenarios simultaneously. ---atsim - Run ATSIM simulator tests. +.. option:: --atsim ---dist - Run simulator-agnostic distribution tests. + Run ATSIM simulator tests. ---ghdl - Run GHDL simulator tests. +.. option:: --dist ---iv - Run Icarus Verilog simulator tests. + Run simulator-agnostic distribution tests. ---ms - Run ModelSim simulator tests. +.. option:: --ghdl ---nc - Run Cadence NC-Verilog simulator tests. + Run GHDL simulator tests. ---vcs - Run Synopsys VCS simulator tests. +.. option:: --iv ---vlt - Run Verilator tests in single-threaded mode. Default unless another - scenario flag is provided. + Run Icarus Verilog simulator tests. ---vltmt - Run Verilator tests in multithreaded mode. +.. option:: --ms ---xrun - Run Cadence Xcelium simulator tests. + Run ModelSim simulator tests. ---xsim - Run Xilinx XSim simulator tests. +.. option:: --nc + + Run Cadence NC-Verilog simulator tests. + +.. option:: --vcs + + Run Synopsys VCS simulator tests. + +.. option:: --vlt + + Run Verilator tests in single-threaded mode. Default unless another + scenario flag is provided. + +.. option:: --vltmt + + Run Verilator tests in multithreaded mode. + +.. option:: --xrun + + Run Cadence Xcelium simulator tests. + +.. option:: --xsim + + Run Xilinx XSim simulator tests. driver.py Environment diff --git a/docs/xml.rst b/docs/xml.rst index 61390030b..eeedbe83c 100644 --- a/docs/xml.rst +++ b/docs/xml.rst @@ -29,19 +29,19 @@ Structure The XML document consists of 4 sections within the top level ``verilator_xml`` element: -````\ ... ```` +````... ```` This section contains a list of all design files read, including the built-in constructs and the command line as their own entries. Each ```` has an attribute ``id`` which is a short ASCII string unique to that file. Other elements' ``loc`` attributes use this id to refer to a particular file. -````\ ... ```` +````... ```` All files containing Verilog module definitions are listed in this section. This element's contents is a subset of the ```` element's contents. -````\ ... ```` +````... ```` The cells section of the XML document contains the design instance hierarchy. Each instance is represented with the ```` element with the following attributes: @@ -57,10 +57,10 @@ The XML document consists of 4 sections within the top level - ``hier``: The full hierarchy path. -````\ ... ```` +````... ```` The netlist section contains a number of - ````\ ... ```` elements, each describing the - contents of that module, and a single ````\ ... + ````... ```` elements, each describing the + contents of that module, and a single ````... ```` element which lists all used types used within the modules. Each type has a numeric ``id`` attribute that is referred to by elements in the ```` elements using the ``dtype_id``