luke
/
verilator
mirror of https://github.com/verilator/verilator.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Commentary: Use standard multiline rst comments, other cleanups

This commit is contained in:
Wilson Snyder 2026-06-18 21:58:01 -04:00
parent 50c15f3705
commit 749b93e405
38 changed files with 148 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
README.rst
View File

@ -1,7 +1,8 @@
.. Github doesn't render images unless absolute URL
.. Do not know of a conditional tag, "only: github" nor "github display" works
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
Github doesn't render images unless absolute URL
Do not know of a conditional tag, "only: github" nor "github display" works
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
|badge1| |badge2| |badge3| |badge4| |badge5| |badge7| |badge8|

5
ci/docker/buildenv/README.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _verilator build docker container:

5
ci/docker/run/README.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Verilator Executable Docker Container
=====================================

5
docs/CONTRIBUTING.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Contributing to Verilator
=========================

5
docs/README.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Verilator Documentation
=======================

5
docs/guide/changes.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
****************
Revision History

5
docs/guide/connecting.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _connecting:

5
docs/guide/contributing.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*******************************
Contributing and Reporting Bugs

5
docs/guide/contributors.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
************************
Contributors and Origins

5
docs/guide/control.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _verilator control files:

5
docs/guide/copyright.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*********
Copyright

5
docs/guide/deprecations.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
Deprecations
============

5
docs/guide/environment.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _environment:

5
docs/guide/example_binary.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _example create-binary execution:

5
docs/guide/example_cc.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _example c++ execution:

5
docs/guide/example_common_install.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
First you need Verilator installed, see :ref:`Installation`. In brief, if
you installed Verilator using the package manager of your operating system,

5
docs/guide/example_dist.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _examples in the distribution:

5
docs/guide/example_sc.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _example systemc execution:

5
docs/guide/examples.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _examples:

9
docs/guide/exe_sim.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _simulation runtime arguments:
@ -50,8 +51,8 @@ Options:
.. option:: +verilator+log+file+<filename>
Log all stdout and stderr to the specified output filename. If not specified
the normal stdout/stderr streams are used.
Log all stdout and stderr to the specified output filename. If not specified
the normal stdout/stderr streams are used.
.. option:: +verilator+noassert

7
docs/guide/exe_verilator.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
===================
verilator Arguments
@ -669,7 +670,7 @@ Summary:
.. option:: -fno-case-tree
Rarely needed. Disable converting case statements into bitwise branch trees.
Rarely needed. Disable converting case statements into bit-wise branch trees.
.. option:: -fno-combine

5
docs/guide/exe_verilator_coverage.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator_coverage
==================

5
docs/guide/exe_verilator_gantt.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator_gantt
===============

5
docs/guide/exe_verilator_profcfunc.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
verilator_profcfunc
===================

5
docs/guide/executables.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*********************************
Executable and Argument Reference

5
docs/guide/extensions.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
===================
Language Extensions

5
docs/guide/faq.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
******************************
FAQ/Frequently Asked Questions

11
docs/guide/files.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
*****
Files
@ -163,9 +164,11 @@ The Verilated executable may produce the following:
.. list-table::
* - coverage.dat
- Code coverage output, and default input filename for :command:`verilator_coverage`
- Code coverage output, and default input filename for
:command:`verilator_coverage`
* - gmon.out
- GCC/clang code profiler output, often fed into :command:`verilator_profcfunc`
- GCC/clang code profiler output, often fed into
:command:`verilator_profcfunc`
* - profile.vlt
- --prof-pgo data file for :ref:`Thread PGO`
* - profile_exec.dat

5
docs/guide/index.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
######################
Verilator User's Guide

5
docs/guide/install-cmake.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _cmakeinstallation:

5
docs/guide/install.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _installation:

5
docs/guide/languages.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
***************
Input Languages

5
docs/guide/overview.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
********
Overview

40
docs/guide/simulating.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
.. _simulating:
@ -218,8 +219,8 @@ Covergroup Coverage
With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
translate covergroup coverage points the user has inserted manually in
SystemVerilog code into the Verilated model. Verilator supports
coverpoints with value and transition bins, and cross points.
SystemVerilog code into the Verilated model. Verilator supports coverpoints
with value and transition bins, and cross points.
.. _fsm coverage:
@ -244,15 +245,15 @@ encodings in these common forms:
- Single-process FSMs, whose state dispatch is written as ``case (state)``
or as a top-level ``if`` / ``else if`` chain comparing the same state
variable against known state values
- Two-process and three-block FSMs, where a clocked state register is paired
with a combinational next-state block using the same supported
- Two-process and three-block FSMs, where a clocked state register is
paired with a combinational next-state block using the same supported
``case`` or top-level ``if`` / ``else if`` dispatch forms
Scalar state encodings may be wider than 32 bits. This allows sparse
state encodings, such as high-Hamming-distance enum or localparam values,
to be preserved in the detected FSM model. Verilator uses the declared
enum item name, parameter name, or localparam name as the reported state
label where possible.
Scalar state encodings may be wider than 32 bits. This allows sparse state
encodings, such as high-Hamming-distance enum or localparam values, to be
preserved in the detected FSM model. Verilator uses the declared enum item
name, parameter name, or localparam name as the reported state label where
possible.
Simple input guards are supported when they appear inside a recognized
state branch, or as a top-level conjunction containing exactly one state
@ -275,10 +276,10 @@ the extracted coverage model:
- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch
arcs that would otherwise be skipped by the conservative extractor.
State registers may also be wrapped by a transparent instance, for
example a project flop wrapper or primitive. Such wrappers must be
described explicitly with a VLT command file action before Verilator will
use their data, state, clock, or reset connections for FSM extraction:
State registers may also be wrapped by a transparent instance, for example
a project flop wrapper or primitive. Such wrappers must be described
explicitly with a VLT command file action before Verilator will use their
data, state, clock, or reset connections for FSM extraction:
.. code-block:: sv
@ -298,11 +299,10 @@ Optional reset metadata may also be supplied:
fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i" \
-reset "rst_ni" -reset_value "ResetValue"
Reset arcs are emitted only when the configured reset port has an
inferable edge in the wrapper and the configured reset value parameter is
statically resolvable. If reset metadata is incomplete, Verilator warns
and may still emit FSM state and transition coverage, but reset arcs are
omitted.
Reset arcs are emitted only when the configured reset port has an inferable
edge in the wrapper and the configured reset value parameter is statically
resolvable. If reset metadata is incomplete, Verilator warns and may still
emit FSM state and transition coverage, but reset arcs are omitted.
Reset transitions are included in the collected data either way. By
default, :command:`verilator_coverage` summarizes reset-only arcs rather

5
docs/guide/verilating.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
**********
Verilating

5
docs/guide/warnings.rst
View File

@ -1,5 +1,6 @@
.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
..
SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
===================
Errors and Warnings

19
docs/internals.rst
View File

@ -732,8 +732,8 @@ event `a` was called first - which is necessary to know.
There are two functions for managing timing logic called by ``_eval()``:
* ``_timing_ready()``, which commits all coroutines whose triggers were
not set in the current iteration,
* ``_timing_ready()``, which commits all coroutines whose triggers were not
set in the current iteration,
* ``_timing_resume()``, which calls `resume()` on all trigger and delay
schedulers whose triggers were set in the current iteration.
@ -937,14 +937,15 @@ macro-task's dataset fits in one core's local caches.
To achieve spatial locality, we tag each variable with the set of
macro-tasks that access it. Let's call this set the "footprint" of that
variable. The variables in a given module have a set of footprints. We group
variables with identical non-empty footprints, emit those groups in deterministic
footprint-key order, then emit variables with no footprint information last.
variable. The variables in a given module have a set of footprints. We
group variables with identical non-empty footprints, emit those groups in
deterministic footprint-key order, then emit variables with no footprint
information last.
The first emitted variable in each footprint group is aligned to a cache-line
boundary. This avoids false sharing between different macro-task footprints
without building a complete pairwise-distance graph over all footprints, which
would use excessive memory on very large models.
The first emitted variable in each footprint group is aligned to a
cache-line boundary. This avoids false sharing between different macro-task
footprints without building a complete pairwise-distance graph over all
footprints, which would use excessive memory on very large models.
This is an old idea. Simulators designed at DEC in the early 1990s used
similar techniques to optimize both single-thread and multithread modes.

7
docs/security.rst
View File

@ -1,6 +1,7 @@
.. for github, vim: syntax=reStructuredText
.. SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
.. SPDX-License-Identifier: CC0-1.0
..
for github, vim: syntax=reStructuredText
SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
SPDX-License-Identifier: CC0-1.0
Security Policy
===============