Version bump

Fixes #3718

.clang-format

@@ -17,7 +17,7 @@ AllowShortLoopsOnASingleLine: true
 AlwaysBreakAfterDefinitionReturnType: None
 AlwaysBreakAfterReturnType: None
 AlwaysBreakBeforeMultilineStrings: false
-AlwaysBreakTemplateDeclarations: false
+AlwaysBreakTemplateDeclarations: true
 BinPackArguments: true
 BinPackParameters: true
 BraceWrapping:
@@ -56,18 +56,29 @@ DisableFormat:   false
 ExperimentalAutoDetectBinPacking: false
 FixNamespaceComments: true
 ForEachMacros:
-  - foreach
   - Q_FOREACH
   - BOOST_FOREACH
-IncludeBlocks:   Preserve
+
+# Include grouping/sorting
+SortIncludes:    true
+IncludeBlocks:   Regroup
 IncludeCategories:
-  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
-    Priority:        2
-  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
-    Priority:        3
-  - Regex:           '.*'
-    Priority:        1
-IncludeIsMainRegex: '(Test)?$'
+  - Regex:           '"(config_build|verilated_config|verilatedos)\.h"'
+    Priority:        -1 # Sepecials before main header
+  - Regex:           '(<|")verilated.*'
+    Priority:        1 # Runtime headers
+  - Regex:           '"V3.*__gen.*\.h"'
+    Priority:        3 # Generated internal headers separately
+  - Regex:           '"V3.*"'
+    Priority:        2 # Internal header
+  - Regex:           '".*"'
+    Priority:        4 # Other non-system headers
+  - Regex:           '<[[:alnum:]_.]+>'
+    Priority:        5 # Simple system headers next
+  - Regex:           '<.*>'
+    Priority:        6 # Other system headers next
+IncludeIsMainRegex: '$'
+
 IndentCaseLabels: false
 IndentPPDirectives: None
 IndentWidth:     4
@@ -91,7 +102,6 @@ PenaltyExcessCharacter: 1000000
 PenaltyReturnTypeOnItsOwnLine: 60
 PointerAlignment: Left
 ReflowComments:  true
-SortIncludes:    false
 SortUsingDeclarations: true
 SpaceAfterCStyleCast: false
 SpaceAfterTemplateKeyword: true
@@ -108,4 +118,3 @@ Standard:        Cpp11
 TabWidth:        8
 UseTab:          Never
 ...
-

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug report
-about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
+about: Use this to report that something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
 title: ''
 labels: new
 assignees: ''
@@ -13,4 +13,6 @@ Can you attach an example that shows the issue?  (Must be openly licensed, ideal
 
 What 'verilator --version' are you using?  Did you try it with the git master version?
 
-Would you be willing to try to fix Verilator yourself with assistance?
+What OS and distribution are you using?
+
+May we assist you in trying to fix this in Verilator yourself?

.github/ISSUE_TEMPLATE/feature.md

@@ -1,6 +1,6 @@
 ---
 name: Feature Request
-about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
+about: Use this to request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
 title: ''
 labels: new
 assignees: ''
@@ -13,4 +13,4 @@ What would you like added/supported?
 
 Can you attach an example that runs on other simulators?  (Must be openly licensed, ideally in test_regress format.)
 
-May we assist you in trying to fix this yourself?
+May we assist you in trying to fix this in Verilator yourself?

.github/ISSUE_TEMPLATE/questions.md

@@ -1,6 +1,6 @@
 ---
 name: Q and A, or Other
-about: Ask a question, not related to a specific bug or feature request. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
+about: Use this to ask a question, not related to a specific bug nor feature request. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
 title: ''
 labels: new
 assignees: ''

.github/workflows/build.yml

@@ -29,7 +29,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-20.04, ubuntu-18.04, ubuntu-16.04]
+        os: [ubuntu-22.04, ubuntu-20.04, ubuntu-18.04]
         compiler:
           - { cc: clang, cxx: clang++ }
           - { cc: gcc,   cxx: g++     }
@@ -37,11 +37,16 @@ jobs:
         exclude:
           # Build pull requests only with ubuntu-20.04 and without m32
           - os:  ${{ github.event_name == 'pull_request' && 'ubuntu-18.04' || 'do-not-exclude' }}
-          - os:  ${{ github.event_name == 'pull_request' && 'ubuntu-16.04' || 'do-not-exclude' }}
+          - os:  ${{ github.event_name == 'pull_request' && 'ubuntu-22.04' || 'do-not-exclude' }}
           - m32: ${{ github.event_name == 'pull_request' && 1              || 'do-not-exclude' }}
           # Build -m32 only on ubuntu-20.04
           - {os: ubuntu-18.04, m32: 1}
-          - {os: ubuntu-16.04, m32: 1}
+          - {os: ubuntu-22.04, m32: 1}
+        include:
+          # Build GCC 10 on ubuntu-20.04
+          - os: ubuntu-20.04
+            compiler: { cc: gcc-10, cxx: g++-10 }
+            m32: 0
     runs-on: ${{ matrix.os }}
     name: Build | ${{ matrix.os }} | ${{ matrix.compiler.cc }} ${{ matrix.m32 && '| -m32' || '' }}
     env:
@@ -56,12 +61,12 @@ jobs:
     steps:
 
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         path: repo
 
     - name: Cache $CCACHE_DIR
-      uses: actions/cache@v2
+      uses: actions/cache@v3
       env:
         CACHE_KEY: ${{ env.CACHE_BASE_KEY }}-ccache
       with:
@@ -81,7 +86,7 @@ jobs:
       run: tar --posix -c -z -f ${{ env.VERILATOR_ARCHIVE }} repo
 
     - name: Upload tar archive
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v3
       with:
         path: ${{ github.workspace }}/${{ env.VERILATOR_ARCHIVE }}
         name: ${{ env.VERILATOR_ARCHIVE }}
@@ -92,7 +97,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-20.04, ubuntu-18.04, ubuntu-16.04]
+        os: [ubuntu-22.04, ubuntu-20.04, ubuntu-18.04]
         compiler:
           - { cc: clang, cxx: clang++ }
           - { cc: gcc,   cxx: g++     }
@@ -101,11 +106,18 @@ jobs:
         exclude:
           # Build pull requests only with ubuntu-20.04 and without m32
           - os:  ${{ github.event_name == 'pull_request' && 'ubuntu-18.04' || 'do-not-exclude' }}
-          - os:  ${{ github.event_name == 'pull_request' && 'ubuntu-16.04' || 'do-not-exclude' }}
+          - os:  ${{ github.event_name == 'pull_request' && 'ubuntu-22.04' || 'do-not-exclude' }}
           - m32: ${{ github.event_name == 'pull_request' && 1              || 'do-not-exclude' }}
           # Build -m32 only on ubuntu-20.04
           - {os: ubuntu-18.04, m32: 1}
-          - {os: ubuntu-16.04, m32: 1}
+          - {os: ubuntu-22.04, m32: 1}
+        include:
+          # Test with GCC 10 on ubuntu-20.04 without m32
+          - {os: ubuntu-20.04, compiler: { cc: gcc-10, cxx: g++-10 }, m32: 0, suite: dist-vlt-0}
+          - {os: ubuntu-20.04, compiler: { cc: gcc-10, cxx: g++-10 }, m32: 0, suite: dist-vlt-1}
+          - {os: ubuntu-20.04, compiler: { cc: gcc-10, cxx: g++-10 }, m32: 0, suite: dist-vlt-2}
+          - {os: ubuntu-20.04, compiler: { cc: gcc-10, cxx: g++-10 }, m32: 0, suite: vltmt-0}
+          - {os: ubuntu-20.04, compiler: { cc: gcc-10, cxx: g++-10 }, m32: 0, suite: vltmt-1}
     runs-on: ${{ matrix.os }}
     name: Test | ${{ matrix.os }} | ${{ matrix.compiler.cc }} | ${{ matrix.suite }} ${{ matrix.m32 && '| -m32' || '' }}
     env:
@@ -114,13 +126,13 @@ jobs:
       CI_M32: ${{ matrix.m32 }}
       CC: ${{ matrix.compiler.cc }}
       CXX: ${{ matrix.compiler.cxx }}
-      CACHE_BASE_KEY: test-${{ matrix.os }}-${{ matrix.compiler.cc }}-m32=${{ matrix.m32 }}-${ matrix.suite }}
+      CACHE_BASE_KEY: test-${{ matrix.os }}-${{ matrix.compiler.cc }}-m32=${{ matrix.m32 }}-${{ matrix.suite }}
       CCACHE_MAXSIZE: 64M # Per build matrix entry (2160M in total)
       VERILATOR_ARCHIVE: verilator-${{ github.sha }}-${{ matrix.os }}-${{ matrix.compiler.cc }}${{ matrix.m32 && '-m32' || '' }}.tar.gz
     steps:
 
     - name: Download tar archive
-      uses: actions/download-artifact@v2
+      uses: actions/download-artifact@v3
       with:
         name: ${{ env.VERILATOR_ARCHIVE }}
         path: ${{ github.workspace }}
@@ -130,7 +142,7 @@ jobs:
       run: tar -x -z -f ${{ env.VERILATOR_ARCHIVE }}
 
     - name: Cache $CCACHE_DIR
-      uses: actions/cache@v2
+      uses: actions/cache@v3
       env:
         CACHE_KEY: ${{ env.CACHE_BASE_KEY }}-ccache
       with:

.github/workflows/contributor.yml

@@ -11,7 +11,7 @@ on:
 jobs:
   Test:
     name: "'docs/CONTRIBUTORS' was signed"
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - run: test_regress/t/t_dist_contributors.pl

.github/workflows/coverage.yml

@@ -24,14 +24,14 @@ jobs:
 
 
   Build:
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     env:
       CI_BUILD_STAGE_NAME: build
-      CI_RUNS_ON: ubuntu-20.04
+      CI_RUNS_ON: ubuntu-22.04
     steps:
 
     - name: Checkout
-      uses: actions/checkout@v2
+      uses: actions/checkout@v3
       with:
         path: repo
 
@@ -46,7 +46,7 @@ jobs:
       run: tar --posix -c -z -f ${{ env.VERILATOR_ARCHIVE }} repo
 
     - name: Upload tar archive
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v3
       with:
         path: ${{ github.workspace }}/${{ env.VERILATOR_ARCHIVE }}
         name: ${{ env.VERILATOR_ARCHIVE }}
@@ -73,15 +73,15 @@ jobs:
         - 9
         include:
         - { test: dist, num: '' }
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-22.04
     name: test-${{ matrix.test }}${{ matrix.num }}
     env:
       CI_BUILD_STAGE_NAME: test
-      CI_RUNS_ON: ubuntu-20.04
+      CI_RUNS_ON: ubuntu-22.04
     steps:
 
     - name: Download tar archive
-      uses: actions/download-artifact@v2
+      uses: actions/download-artifact@v3
       with:
         name: ${{ env.VERILATOR_ARCHIVE }}
         path: ${{ github.workspace }}

.github/workflows/format.yml

@@ -10,16 +10,16 @@ on:
 
 jobs:
   format:
-    runs-on: ubuntu-20.04
-    name: Ubuntu 20.04 | format
+    runs-on: ubuntu-22.04
+    name: Ubuntu 22.04 | format
     env:
       CI_OS_NAME: linux
-      CI_RUNS_ON: ubuntu-20.04
+      CI_RUNS_ON: ubuntu-22.04
       CI_COMMIT: ${{ github.sha }}
       CI_M32: 0
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
       - name: Install packages for build
@@ -27,14 +27,14 @@ jobs:
           CI_BUILD_STAGE_NAME: build
         run: |
           bash ci/ci-install.bash &&
-          sudo apt-get install clang-format-11 yapf3 &&
+          sudo apt-get install clang-format-14 yapf3 &&
           git config --global user.email "[email protected]" &&
           git config --global user.name "github action"
       - name: Format code
         run: |
           autoconf &&
           ./configure &&
-          make -j 2 format CLANGFORMAT=clang-format-11 &&
+          make -j 2 format CLANGFORMAT=clang-format-14 &&
           git status
       - name: Push
         run: |

.gitignore

@@ -1,5 +1,6 @@
 \#*
 .#*
+.gdb_history
 .nfs*
 *~
 *.tidy
@@ -39,3 +40,4 @@ verilator-config-version.cmake
 **/__pycache__/*
 **/_build/*
 **/obj_dir/*
+/.vscode/

CPPLINT.cfg

@@ -0,0 +1,17 @@
+set noparent
+linelength=100
+filter=-build/c++11
+filter=-build/header_guard
+filter=-build/include_order
+filter=-build/include_subdir
+filter=-readability/inheritance
+filter=-readability/nolint
+filter=-readability/todo
+filter=-runtime/references
+filter=-whitespace/blank_line
+filter=-whitespace/empty_if_body
+filter=-whitespace/indent
+filter=-whitespace/newline
+filter=-whitespace/braces
+filter=-whitespace/parens
+filter=-whitespace/todo

Changes

@@ -8,6 +8,314 @@ The changes in each Verilator version are described below.  The
 contributors that suggested a given feature are shown in []. Thanks!
 
 
+Verilator 5.002 2022-10-29
+==========================
+
+**Major:**
+
+* This is a major new release.
+* Require C++20 for the new --timing features. Upgrading to a C++20 or
+  newer compiler is strongly recommended.
+* Support the Active and NBA scheduling regions as defined by the
+  SystemVerilog standard (IEEE 1800-2017 chapter 4). This means all generated
+  clocks are now simulated correctly (#3278, #3384). [Geza Lore, Shunyao CAD]
+* Support timing controls (delays, event controls in any location, wait
+  statements) and forks. [Krzysztof Bieganski, Antmicro Ltd]
+  This may require adding --timing or --no-timing. See docs for details.
+* Introduce a new combinational logic optimizer (DFG), that can yield
+  significant performance improvements on some designs. [Geza Lore, Shunyao CAD]
+* Add --binary option as alias of --main --exe --build --timing (#3625).
+  For designs where C++ was only used to make a simple no-I/O testbench, we
+  recommend abandoning that C++, and instead letting Verilator build it
+  with --binary (or --main).
+
+**Minor:**
+
+* Split UNUSED warning into genvar, param, and signal warnings (#3607). [Topa Topino]
+* Support standalone 'this' in classes (#2594) (#3248) (#3675). [Arkadiusz Kozdra, Antmicro Ltd]
+* Support tristate select/extend (#3604). [Ryszard Rozak, Antmicro Ltd>
+* Support linting for top module interfaces (#3635). [Kanad Kanhere]
+* Support virtual interfaces (#3654). [Arkadiusz Kozdra, Antmicro Ltd]
+* Support class type params without defaults (#3693). [Krzysztof Bieganski, Antmicro Ltd]
+* Support empty generate_regions (#3695). [mpb27]
+* Support access to constructs inside type parameters (#3702). [Arkadiusz Kozdra, Antmicro Ltd]
+* Add --dump-tree-dot to enable dumping Ast Tree .dot files (#3636). [Marcel Chang]
+* Add --get-supported to determine what features are in Verilator.
+* Add error on real edge event control.
+* Fix false LATCH warning on 'unique if' (#3088). [Rachit Nigam]
+* Fix cell assigning integer array parameters (#3299). [Michael Platzer]
+* Fix LSB error on --hierarchical submodules (#3539). [danbone]
+* Fix $display of fixed-width numbers (#3565). [Iztok Jeras]
+* Fix foreach and pre/post increment in functions (#3613). [Nandu Raj]
+* Fix linker errors in user-facing timing functions (#3657). [Krzysztof Bieganski, Antmicro Ltd]
+* Fix null access on optimized-out fork statements (#3658). [Krzysztof Bieganski, Antmicro Ltd]
+* Fix VPI inline module naming mismatch (#3690) (#3694). [Jiuyang Liu]
+* Fix deadlock in timeprecision when using systemC (#3707). [Kamil Rakoczy, Antmicro Ltd]
+* Fix width mismatch on inside operator (#3714). [Alex Torregrosa]
+
+
+Verilator 4.228 2022-10-01
+==========================
+
+**Announcement:**
+
+* The next release is anticipated to premiere Verilator Version 5.  Please
+  consider beta-testing the github 'develop-v5' branch, which will soon
+  merge into the github 'master' branch (#3383).
+
+**Minor:**
+
+* Support some IEEE signal strengths (#3601) (#3629). [Ryszard Rozak, Antmicro Ltd]
+* Add --main to generate main() C++ (previously was experimental only).
+* Add --build-jobs, and rework arguments for -j (#3623). [Kamil Rakoczy]
+* Rename --bin to --build-dep-bin.
+* Rename debug flags --dumpi-tree, --dumpi-graph, etc. [Geza Lore]
+* Fix thread safety in SystemC VL_ASSIGN_SBW/WSB (#3494) (#3513). [Mladen Slijepcevic]
+* Fix crash in gate optimization of circular logic (#3543). [Bill Flynn]
+* Fix arguments in non-static method call (#3547) (#3582). [Gustav Svensk]
+* Fix default --mod-prefix when --prefix is repeated (#3603). [Geza Lore]
+* Fix calling trace() after open() segfault (#3610) (#3627). [Yu-Sheng Lin]
+* Fix typedef'ed class conversion to Boolean (#3616). [Aleksander Kiryk]
+* Fix Verilation speed when disabled warnings (#3632). [Kamil Rakoczy, Antmicro Ltd]
+
+
+Verilator 4.226 2022-08-31
+==========================
+
+**Minor:**
+
+* Add --future0 and --future1 options.
+* Support class parameters (#2231) (#3541). [Arkadiusz Kozdra, Antmicro Ltd]
+* Support wildcard index associative arrays (#3501). [Arkadiusz Kozdra, Antmicro Ltd]
+* Support negated properties (#3572). [Aleksander Kiryk]
+* Support $test$plusargs(expr) (#3489).
+* Rename trace rolloverSize() (#3570).
+* Improve Verilation speed with --threads on large designs. [Geza Lore]
+* Improve Verilation memory by reducing V3Number (#3521). [Mariusz Glebocki, Antmicro Ltd]
+* Fix struct pattern assignment (#2328) (#3517). [Mostafa Gamal]
+* Fix public combo propagation issues (#2905). [Todd Strader]
+* Fix incorrect tristate logic (#3399) [shareefj, Vighnesh Iyer]
+* Fix incorrect bit op tree optimization (#3470). [algrobman]
+* Fix bisonpre for MSYS2 (#3471).
+* Fix max memory usage (#3483). [Kamil Rakoczy, Antmicro Ltd]
+* Fix empty string arguments to display (#3484). [Grulfen]
+* Fix table optimizing away display (#3488). [Stefan Post]
+* Fix unique_ptr memory header for MinGW64 (#3493).
+* Fix $dump system task with --output-split-cfuncs (#3495) (#3497). [Varun Koyyalagunta]
+* Fix wrong bit op tree optimization (#3509). [Nathan Graybeal]
+* Fix nested default assignment for struct pattern (#3511) (#3524). [Mostafa Gamal]
+* Fix sformat string incorrectly cleared (#3515) (#3519). [Gustav Svensk]
+* Fix segfault exporting non-existent package (#3535).
+* Fix void-cast queue pop_front or pop_back (#3542) (#3364). [Drew Ranck]
+* Fix case statement comparing string literal (#3544). [Gustav Svensk]
+* Fix === with some tristate constants (#3551). [Ryszard Rozak, Antmicro Ltd]
+* Fix converting classes to string (#3552). [Arkadiusz Kozdra, Antmicro Ltd]
+* Fix --hierarchical with order-based pin connections (#3583) (#3585). [Kelin9298]
+
+
+Verilator 4.224 2022-06-19
+==========================
+
+**Major:**
+
+* VCD tracing is now parallelized with --threads (#3449). [Geza Lore, Shunyao CAD]
+
+**Minor:**
+
+* Add -f<optimization> options to replace -O<letter> options (#3436).
+* Changed --no-merge-const-pool to -fno-merge-const-pool (#3436).
+* Changed --no-decoration to remove output whitespace (#3460). [Kamil Rakoczy]
+* Support compile time trace signal selection with tracing_on/off (#3323). [Shunyao CAD]
+* Support non-ANSI interface port declarations (#3439). [Geza Lore, Shunyao CAD]
+* Support concat assignment to packed array (#3446).
+* Improve conditional merging optimization (#3125). [Geza Lore, Shunyao CAD]
+* Define VM_TRACE_VCD when tracing in VCD format. [Geza Lore, Shunyao CAD]
+* Add assert when VerilatedContext is mis-deleted (#3121). [Rupert Swarbrick]
+* Internal prep work towards timing control. [Krzysztof Bieganski, Antmicro Ltd]
+* Fix hang with large case statement optimization (#3405). [Mike Urbach]
+* Fix UNOPTFLAT warning from initial static var (#3406). [Kamil Rakoczy]
+* Fix compile error when enable VL_LEAK_CHECKS (#3411). [HungMingWu]
+* Fix cmake rules to support higher-level targets (#3377) (#3386). [Martin Stadler]
+* Fix BLKANDNBLK on $readmem/$writemem (#3379). [Alex Solomatnikov]
+* Fix 'with' operator with type casting (#3387). [xiak95]
+* Fix incorrect conditional merging (#3409). [Raynard Qiao]
+* Fix passing VL_TRACE_FST_WRITER_THREAD in CMake build. [Geza Lore, Shunyao CAD]
+* Fix compile error under strict C++11 mode (#3463). [Kevin Kiningham]
+* Fix public unpacked input ports (#3465). [Todd Strader]
+
+
+Verilator 4.222 2022-05-02
+==========================
+
+**Minor:**
+
+* Split --prof-threads into --prof-exec and --prof-pgo (#3365). [Geza Lore, Shunyao CAD]
+* Deprecate 'vluint64_t' and similar types (#3255).
+* Raise error on assignment to const in initial blocks. [Geza Lore, Shunyao CAD]
+* Issue INITIALDLY/COMBDLY/BLKSEQ warnings consistent with Verilator execution. [Geza Lore, Shunyao CAD]
+* Support LoongArch ISA multithreading (#3353) (#3354). [Xi Zhang]
+* Fix MSVC localtime_s (#3124).
+* Fix Bison 3.8.2 error (#3366). [elike-ypq]
+* Fix rare bug in -Oz (V3Localize) (#3286). [Geza Lore, Shunyao CAD]
+* Fix tracing interfaces inside interfaces (#3309). [Kevin Millis]
+* Fix filenames with dots overwriting debug .vpp files (#3373).
+* Fix including VK_USER_OBJS in make library (#3370) (#3382). [Julien Margetts]
+* Fix hang in generate symbol references (#3391) (#3398). [Yoda Lee]
+* Fix missing #include <memory> (#3392). [Aliaksei Chapyzhenka]
+* Fix crash in recursive module inlining (#3393). [david-sawatzke]
+* Fix --protect-ids mangling names of library methods. [Geza Lore, Shunyao CAD]
+* Fix foreach segmentation fault (#3400). [Kamil Rakoczy]
+
+
+Verilator 4.220 2022-03-12
+==========================
+
+**Minor:**
+
+* Removed the deprecated lint_off flag -msg; use -rule instead.
+* Removed the deprecated "fl" attribute in XML output; use "loc" attribute instead.
+* Suppress WIDTH warning on negate using carry bit (#3295). [Peter Monsson]
+* Add trace dumpvars() call for selective runtime tracing (#3322). [Shunyao CAD]
+* Add VERILATOR_VERSION_INTEGER for determining API (#3343). [Larry Doolittle]
+* Improve various V3Combine algorithm details (#3328). [Yutetsu TAKATSUKASA]
+* Improve various V3Order algorithm details. [Geza Lore]
+* Fix MacOS arm64 build (#3285) (#3291). [Guokai Chen]
+* Fix signed number operation (#3294) (#3308). [Raynard Qiao]
+* Fix FST traces to include vector range (#3296) (#3297). [Jamie Iles]
+* Fix skipping public enum values with four-state values (#3303).
+* Fix $readmem file not found to be warning not error (#3310). [Alexander Grobman]
+* Fix class stringification on wide arrays (#3312). [Iru Cai]
+* Fix $fscanf etc to return -1 on EOF (#3313). [Jose Tejada]
+* Fix public function arguments that are arrayed (#3316). [pawel256]
+* Fix unnamedblk error on foreach (#3321). [Aliaksei Chapyzhenka]
+* Fix crash in recursive module inlining (#3324). [Larry Doolittle]
+* Fix VL_RESTORER behavior on passing a lvalue reference (#3326). [HungMingWu]
+* Fix compile error with --trace-fst --sc (#3332). [leavinel]
+* Fix cast to array types (#3333). [Todd Strader]
+* Fix Vdeeptemp error with --threads and --compiler clang (#3338). [Per Karlsson]
+
+
+Verilator 4.218 2022-01-17
+==========================
+
+**Major:**
+
+* Primary inputs and outputs (VL_INW/VL_OUTW) now use VlWide type.
+  In general this should be backward compatible, but may lead to some
+  wrapper code needing changes.
+* Option --cdc is deprecated and is planned for removal,
+  file a bug if this is still being used.
+
+**Minor:**
+
+* Support class static members (#2233).
+* Support force/release (#2431) (#2593). [Shunyao CAD]
+* Add 'forceable' attribute to allow forcing from C++. (#3272). [Geza Lore, Shunyao CAD]
+* Support lower dimension looping in foreach loops (#3172). [Ehab Ibrahim]
+* Support up to 64 bit enums for .next/.prev/.name (#3244). [Alexander Grobman]
+* Reduce .rodata footprint of trace initialization (#3250). [Geza Lore, Shunyao CAD]
+* Support FST tracing in hierarchical Verilation (#3251). [Yutetsu TAKATSUKASA]
+* Use C++11 standard types for MacOS portability (#3254) (#3257). [Adrien Le Masle]
+* Fix make support for BSD ar (#2999) (#3256). [Julie Schwartz]
+* Fix bad ending address on $readmem (#3205). [Julie Schwartz]
+* Fix MSWIN compile error (#2681). [Unai Martinez-Corral]
+* Fix break under foreach loop (#3230).
+* Fix VL_STREAML_FAST_QQI with 64 bit left-hand-side (#3232) (#3235). [Adrien Le Masle]
+* Fix $sformat of inputs/outputs (#3236). [Adrien Le Masle]
+* Fix associative array first method as statement (#3228). [Adrien Le Masle]
+* Fix associative array foreach loop (#3229).
+* Fix $fclose not accepting expressions (#3237). [Julie Schwartz]
+* Fix $random not updating seed (#3238). [Julie Schwartz]
+* Fix top level param overwrite when package has same param (#3241) (#3247). [Adrien Le Masle]
+* Fix spurious UNUSED by ignoring inout pin connections (#3242). [Julie Schwartz]
+* Fix splitting of _eval and other top level functions. [Geza Lore, Shunyao CAD]
+* Fix internal error by inout port (#3258). [Yutetsu TAKATSUKASA]
+* Fix GCC 11 compile error (#3273). [HungMingWu]
+
+
+Verilator 4.216 2021-12-05
+==========================
+
+**Major:**
+
+* Add --lib-create, similar to --protect-lib but without protections.
+* Support tracing through --hierarchical/--lib-create libraries (#3200).
+
+**Minor:**
+
+* Internal code cleanups and improvements. [Geza Lore]
+* Improve --thread Verilation-time performance.
+* Support task name in $display %m (#3211). [Julie Schwartz]
+* Make 'bit', 'logic' and 'time' types unsigned by default. [Geza Lore]
+* Optimize $random concatenates/selects (#3114).
+* Fix array method names with parenthesis (#3181) (#3183). [Teng Huang]
+* Fix split_var assign merging (#3177) (#3179). [Yutetsu TAKATSUKASA]
+* Fix wrong bit op tree optimization (#3185). [Yutetsu TAKATSUKASA]
+* Fix some SliceSels not being constants (#3186) (#3218). [Michaël Lefebvre]
+* Fix nested generate if genblk naming (#3189). [yanx21]
+* Fix hang on recursive definition error (#3199). [Jonathan Kimmitt]
+* Fix display of signed without format (#3204). [Julie Schwartz]
+* Fix display of empty string constant (#3207) (#3215). [Julie Schwartz]
+* Fix incorrect width after and-or optimization (#3208). [Julie Schwartz]
+* Fix $fopen etc on integer arrays (#3214). [adrienlemasle]
+* Fix $size on dynamic strings (#3216).
+* Fix %0 format on $value$plusargs (#3217).
+* Fix timescale portability on Arm64 (#3222).
+
+
+Verilator 4.214 2021-10-17
+==========================
+
+**Major:**
+
+* Add profile-guided optimization of mtasks (#3150).
+
+**Minor:**
+
+* Verilator_gantt has removed the ASCII graphics, use the VCD output instead.
+* Verilator_gantt now shows the predicted mtask times, eval times, and additional statistics.
+* Verilator_gantt data files now include processor information, to allow later processing.
+* Support displaying x and z in $display task (#3107) (#3109). [Iru Cai]
+* Fix verilator_profcfunc profile accounting (#3115).
+* Fix display has no time units on class function (#3116). [Damien Pretet]
+* Fix removing if statement with side effect in condition (#3131). [Alexander Grobman]
+* Fix --waiver-output for multiline warnings (#2429) (#3141). [Keith Colbert]
+* Fix internal error on bad widths (#3140) (#3145). [Zhanglei Wang]
+* Fix crash on clang 12/13 (#3148). [Kouping Hsu]
+* Fix cygwin compile error due to missing -std=gnu++14 (#3149). [Sun Kim]
+* Fix $urandom_range when the range is 0 ... UINT_MAX (#3161). [Iru Cai]
+* Fix constructor-parameter argument comma-separation in C++ (#3162). [Matthew Ballance]
+* Fix missing install of vl_file_copy/vl_hier_graph (#3165). [Popolon]
+* Fix calling new with arguments in same class (#3166). [Matthew Ballance]
+* Fix false EOFNEWLINE warning when DOS carriage returns present (#3171).
+
+
+Verilator 4.212 2021-09-01
+==========================
+
+**Minor:**
+
+* Fix re-evaluation of logic dependent on state set in DPI exports (#3091). [Geza Lore]
+* Support unpacked array localparams in tasks/functions (#3078). [Geza Lore]
+* Support timeunit/timeprecision in $unit.
+* Support assignment patterns as children of pins (#3041). [Krzysztof Bieganski, Antmicro Ltd]
+* Add --instr-count-dpi to tune assumed DPI import cost for multithreaded
+  model scheduling. Default value changed to 200 (#3068). [Yinan Xu]
+* Output files are split based on the set of headers required
+  in order to aid incremental compilation via ccache (#3071). [Geza Lore]
+* Parameter values are now emitted as 'static constexpr' instead of enum.
+  C++ direct references to parameters might require updating (#3077). [Geza Lore]
+* Refactored Verilated include files; include verilated.h not verilated_heavy.h.
+* Add header guards on Dpi.h generated files (#2979). [Tood Strader]
+* Add XML ccall, constpool, initarray, and if/while begins (#3080). [Steven Hugg]
+* Add error when constant function under a generate (#3103). [Don Owen]
+* Fix -G to treat simple integer literals as signed (#3060). [Anikin1610]
+* Fix emitted string array initializers (#2895). [Iztok Jeras]
+* Fix bitop tree optimization dropping necessary & operator (#3096). [Flavien Solt]
+* Fix internal error on wide -x-initial unique (#3106). [Alexandre Joannou]
+* Fix traces to show array instances with brackets (#3092) (#3095). [Pieter Kapsenberg]
+
+
 Verilator 4.210 2021-07-07
 ==========================
 
@@ -26,7 +334,7 @@ Verilator 4.210 2021-07-07
 
 * Add --prof-c to pass profiling to compiler (#3059). [Alexander Grobman]
 * Optimize a lot more model variables into function locals (#3027). [Geza Lore]
-* Support middle-of-design nested topmodules (#3026). [Dan Petrisko]
+* Support middle-of-design nested top modules (#3026). [Dan Petrisko]
 * Remove deprecated --no-relative-cfuncs option (#3024). [Geza Lore]
 * Remove deprecated --inhibit-sim option (#3035). [Geza Lore]
 * Merge const static data globally into a new constant pool (#3013). [Geza Lore]
@@ -55,7 +363,7 @@ Verilator 4.204 2021-06-12
 * Prep work towards better ccache hashing/performance. [Geza Lore]
 * Fix assertion failure in bitOpTree optimization (#2891) (#2899). [Raynard Qiao]
 * Fix DPI functions not seen as vpiModule (#2893). [Todd Strader]
-* Fix bounds check in VL_SEL_IWII (#2910). [Krzysztof Bieganski]
+* Fix bounds check in VL_SEL_IWII (#2910). [Krzysztof Bieganski, Antmicro Ltd]
 * Fix slowdown in elaboration (#2911). [Nathan Graybeal]
 * Fix initialization of assoc in assoc array (#2914). [myftptoyman]
 * Fix make support for gmake 3.x (#2920) (#2921). [Philipp Wagner]
@@ -65,10 +373,10 @@ Verilator 4.204 2021-06-12
 * Fix to emit 'else if' without nesting (#2944). [Geza Lore]
 * Fix part select issues in LATCH warning (#2948) (#2938). [Julien Margetts]
 * Fix to not emit empty files with low split limits (#2961). [Geza Lore]
-* Fix merging of assignments in C++ code (#2970). [Ruper Swarbrick]
+* Fix merging of assignments in C++ code (#2970). [Rupert Swarbrick]
 * Fix unused variable warnings (#2991). [Pieter Kapsenberg]
 * Fix --protect-ids when using SV classes (#2994). [Geza Lore]
-* Fix constant function calls with uninit value (#2995). [yanx21]
+* Fix constant function calls with uninitialized value (#2995). [yanx21]
 * Fix Makefiles to support Windows EXEEXT usage (#3008). [Miodrag Milanovic]
 
 
@@ -106,7 +414,7 @@ Verilator 4.202 2021-04-24
 * Fix Cygwin example compile issues (#2856). [Mark Shaw]
 * Fix select of with index variable (#2880). [Alexander Grobman]
 * Fix cmake version number to be numeric (#2881). [Yuri Victorovich]
-* Fix MinGW not supportting 'localtime_r' (#2882). [HyungKi Jeong]
+* Fix MinGW not supporting 'localtime_r' (#2882). [HyungKi Jeong]
 * Fix cast from packed, typedef'ed interface signal (#2884). [Todd Strader]
 * Fix VPI package reported as vpiModule (#2885). [Todd Strader]
 * Fix dumping waveforms to multiple FST files (#2889). [David Metz]
@@ -170,7 +478,7 @@ Verilator 4.108 2021-01-10
 **Major:**
 
 * Many VPI changes for IEEE compatibility, which may alter behavior from previous releases.
-* Support randomize() class method and rand (#2607). [Krzysztof Bieganski]
+* Support randomize() class method and rand (#2607). [Krzysztof Bieganski, Antmicro Ltd]
 
 **Minor:**
 
@@ -230,7 +538,7 @@ Verilator 4.104 2020-11-14
 * Support queue and associative array 'with' statements (#2616).
 * Support queue slicing (#2326).
 * Support associative array pattern assignments and defaults.
-* Support static methods and typedefs in classes (#2615). [Krzysztof Bieganski]
+* Support static methods and typedefs in classes (#2615). [Krzysztof Bieganski, Antmicro Ltd]
 * Add error on typedef referencing self (#2539). [Cody Piersall]
 * With --debug, turn off address space layout randomization.
 * Fix iteration over mutating list bug in VPI (#2588). [Kaleb Barrett]
@@ -253,7 +561,7 @@ Verilator 4.102 2020-10-15
 * Support # as a comment in -f files (#2497). [phantom-killua]
 * Support 'this' (#2585). [Rafal Kapuscik]
 * Support defines for FST tracing (#2592). [Markus Krause]
-* Support non-overapping implication inside properties (#1292). [Peter Monsson]
+* Support non-overlapping implication inside properties (#1292). [Peter Monsson]
 * Fix timescale with --hierarchical (#2554). [Yutetsu TAKATSUKASA]
 * Fix cmake build with --hierarchical (#2560). [Yutetsu TAKATSUKASA]
 * Fix -G dropping public indication (#2561). [Andrew Goessling]
@@ -279,7 +587,7 @@ Verilator 4.100 2020-09-07
 * Support (with limitations) class extern, class extends, virtual class.
 * Support $urandom, $urandom_range without stability.
 * Support assume property. [Peter Monsson]
-* Support non-overapping implication inside properties (#1292). [Peter Monsson]
+* Support non-overlapping implication inside properties (#1292). [Peter Monsson]
 * Fix false DECLFILENAME on black-boxed modules (#2430). [Philipp Wagner]
 * Fix naming of "id : begin" blocks.
 * Fix class constructor error on assignments to const.
@@ -3679,7 +3987,7 @@ Verilator 0.0 1994-07-08
 Copyright
 =========
 
-Copyright 2001-2021 by Wilson Snyder. This program is free software; you
+Copyright 2001-2022 by Wilson Snyder. This program 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.

MANIFEST.SKIP

@@ -1,76 +0,0 @@
-\.ccache/
-\.clang-format
-\.clang-tidy
-\.git/
-\.git$
-\.github/
-\.svn/
-\.(bak|old)/
-\.(bak|old)$
-\.tar\.
-.*\.tgz
-.*\.log
-\..*\.swp
-.*\.tmp
-.*\.tidy
-.*\.tex
-.*\.key
-.*\.vcd
-.*\.1
-\.codacy\.yml
-\.travis\.yml
-/_build/
-/build/
-/obj_dbg/
-/obj_dir/
-/obj_dist/
-/obj_iv/
-/obj_ms/
-/obj_nc/
-/obj_opt/
-/obj_vcs/
-/obj_vlt/
-/obj_vltmt/
-INCA_libs/
-/cov_work/
-/logs/
-^Makefile$
-README.html
-bin/verilator_bin.*
-bin/verilator_coverage_bin.*
-docs/.*\.html$
-docs/_build/
-docs/clang-format.txt$
-docs/doxygen-doc/.*
-docs/spelling.txt
-examples/xml_py/copied/
-examples/xml_py/graph.*
-sonar-project.properties
-src/Makefile$
-src/Makefile_obj$
-include/verilated.mk$
-test_regress/.gdbinit$
-test_regress/transcript
-codecov.yml
-config.cache$
-config.status$
-verilator\.log
-verilator\.tex
-verilator-config.cmake$
-verilator-config-version.cmake$
-verilator.pc$
-verilator_bin.*
-verilator_coverage_bin.*
-.vcsmx_rebuild$
-ncverilog.history
-autom4te\.cache/
-nodist/
-ci/
-/simv$
-/simv.daidir/
-/vc_hdrs.h$
-/csrc/
-obj_dir.*
-TAGS
-gmon.out
-.*~

Makefile.in

@@ -7,7 +7,7 @@
 #
 #*****************************************************************************
 #
-# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -107,6 +107,7 @@ SUBDIRS = docs src test_regress \
 	examples/cmake_tracing_c \
 	examples/cmake_tracing_sc \
 	examples/cmake_protect_lib \
+	examples/make_hello_binary \
 	examples/make_hello_c \
 	examples/make_hello_sc \
 	examples/make_tracing_c \
@@ -118,98 +119,6 @@ INFOS = verilator.html verilator.pdf
 
 INFOS_OLD = README README.html README.pdf
 
-# Files that can be generated, but should be up to date for a distribution.
-DISTDEP = info Makefile
-
-DISTFILES1 = $(INFOS) .gitignore \
-	*.in *.ac \
-	Artistic \
-	Changes \
-	LICENSE \
-	MANIFEST.SKIP \
-	README.rst \
-	verilator-config.cmake.in \
-	verilator-config-version.cmake.in \
-	bin/verilator \
-	bin/verilator_ccache_report \
-	bin/verilator_coverage \
-	bin/verilator_difftree \
-	bin/verilator_gantt \
-	bin/verilator_includer \
-	bin/verilator_profcfunc \
-	docs/.gitignore \
-	docs/CONTRIBUTING.rst \
-	docs/CONTRIBUTORS \
-	docs/Makefile \
-	docs/_static/*.png \
-	docs/_static/css/* \
-	docs/bin/* \
-	docs/gen/* \
-	docs/guide/*.py \
-	docs/guide/*.rst \
-	docs/guide/figures/* \
-	docs/install.rst \
-	docs/internals.rst \
-	docs/internals.rst \
-	docs/verilated.dox \
-	docs/xml.rst \
-	install-sh configure *.pod \
-	include/*.[chv]* \
-	include/*.in \
-	include/.*ignore \
-	include/gtkwave/*.[chv]* \
-	include/vltstd/*.[chv]* \
-	.*attributes */.*attributes  */*/.*attributes \
-	src/.*ignore src/*.in src/*.cpp src/*.[chly] \
-	src/astgen src/bisonpre src/*fix src/cppcheck_filtered \
-	src/config_rev \
-	src/vlcovgen src/mkinstalldirs \
-	src/.gdbinit \
-	src/*.pl src/*.pod \
-	examples/*/.*ignore examples/*/Makefile* \
-	examples/*/*.[chv]* examples/*/vl_* \
-	examples/*/CMakeLists.txt \
-
-DISTFILES2 = \
-	test_*/.*ignore test_*/Makefile* test_*/*.cpp \
-	test_*/*.pl test_*/*.v test_*/*.vc test_*/*.vh \
-	test_regress/*.pl \
-	test_regress/Makefile \
-	test_regress/Makefile_obj \
-	test_regress/input.vc \
-	test_regress/CMakeLists.txt \
-	test_regress/t/t*/*.sv* \
-	test_regress/t/t*/*.v* \
-	test_regress/t/t*/*/*.sv* \
-	test_regress/t/t*/*/*.v* \
-	test_regress/t/t*/*.cpp \
-	test_regress/t/t*/CMakeLists.txt \
-	test_regress/t/*.cpp \
-	test_regress/t/*.h \
-	test_regress/t/*.dat \
-	test_regress/t/*.mem \
-	test_regress/t/*.out \
-	test_regress/t/*.pl \
-	test_regress/t/*.pf \
-	test_regress/t/*.v* \
-
-INST_PROJ_FILES = \
-	bin/verilator \
-	bin/verilator_ccache_report \
-	bin/verilator_coverage \
-	bin/verilator_gantt \
-	bin/verilator_includer \
-	bin/verilator_profcfunc \
-	include/verilated.mk \
-	include/*.[chv]* \
-	include/gtkwave/*.[chv]* \
-	include/vltstd/*.[chv]* \
-
-INST_PROJ_BIN_FILES = \
-	bin/verilator_bin$(EXEEXT) \
-	bin/verilator_bin_dbg$(EXEEXT) \
-	bin/verilator_coverage_bin_dbg$(EXEEXT) \
-
 EXAMPLES_FIRST = \
 	examples/make_hello_c \
 	examples/make_hello_sc \
@@ -217,7 +126,7 @@ EXAMPLES_FIRST = \
 EXAMPLES = $(EXAMPLES_FIRST) $(filter-out $(EXAMPLES_FIRST), $(sort $(wildcard examples/*)))
 
 # See uninstall also - don't put wildcards in this variable, it might uninstall other stuff
-VL_INST_MAN_FILES = verilator.1 verilator_coverage.1 verilator_gantt.1 verilator_profcfunc.1
+VL_INST_MAN_FILES = verilator.1 verilator_coverage.1
 
 default: all
 all: all_nomsg msg_test
@@ -299,8 +208,10 @@ VL_INST_INC_SRCDIR_FILES = \
 	include/vltstd/*.[chv]* \
 
 VL_INST_DATA_SRCDIR_FILES = \
-	examples/*/*.[chv]*  examples/*/Makefile* \
-	examples/*/CMakeLists.txt
+	examples/*/*.[chv]* \
+	examples/*/CMakeLists.txt \
+	examples/*/Makefile* \
+	examples/*/vl_* \
 
 installbin:
 	$(MKINSTALLDIRS) $(DESTDIR)$(bindir)
@@ -333,6 +244,7 @@ installdata:
 	; for p in $(VL_INST_INC_SRCDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
@@ -368,6 +280,7 @@ uninstall:
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/gtkwave
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/vltstd
 	-rmdir $(DESTDIR)$(pkgdatadir)/include
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
@@ -386,44 +299,7 @@ uninstall:
 install: all_nomsg install-all
 install-all: installbin installman installdata install-msg
 
-install-here: installman ftp
-
-ifeq ($(VERILATOR_AUTHOR_SITE),1)	# Local... Else don't burden users
-DISTNAMEREV = $(shell sed -e '/DTVERSION/!d' -e 's/.*verilator_\([^"]*\).*/\1/' -e q ${srcdir}/src/config_rev.h)
-
-VERILATOR_CAD_DIR = $(CAD_DIR)/verilator/$(DISTNAMEREV)/$(DIRPROJECT_ARCH)
-INST_PROJ_CVS = cp_if_cvs_diff
-
-install-cadtools: dist
-	@echo "Install-project to $(CAD_DIR)"
-	strip bin/verilator_bin*
-	strip bin/verilator_coverage_bin*
-	$(MAKE) install-cadtools-quick
-	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/man/man1
-	for p in $(VL_INST_MAN_FILES) ; do \
-	  $(INSTALL_DATA) $$p $(VERILATOR_CAD_DIR)/man/man1/$$p; \
-	done
-	$(INST_PROJ_CVS) $(DISTNAME).tgz $(VERILATOR_CAD_DIR)/verilator.tgz
-	rm $(DISTNAME).tgz
-
-install-cadtools-quick:
-ifeq ($(CFG_WITH_DEFENV),yes)
-	@echo "%Error: Reconfigure with './configure --disable-defenv' to avoid hardcoded paths."
-	false
-endif
-	@echo "Install-cadtools-quick (no strip) to $(VERILATOR_CAD_DIR)"
-	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/include/gtkwave
-	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/include/vltstd
-	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/bin
-	for p in $(INST_PROJ_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(VERILATOR_CAD_DIR)/$$p; \
-	done
-	for p in $(INST_PROJ_BIN_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(VERILATOR_CAD_DIR)/$$p; \
-	done
-
-# VERILATOR_AUTHOR_SITE
-endif
+install-here: installman info
 
 # Use --xml flag to see the cppcheck code to use for suppression
 CPPCHECK_CPP = $(wildcard \
@@ -449,16 +325,18 @@ cppcheck: $(CPPCHECK_DEP)
 	$(CPPCHECK) $(CPPCHECK_FLAGS) -DVL_DEBUG=1 -DVL_CPPCHECK=1 -DVL_THREADED=1 $(CPPCHECK_INC) $<
 
 CLANGTIDY = clang-tidy
-CLANGTIDY_FLAGS = -config='' -checks='-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables'
-CLANGTIDY_DEP = $(subst .h,.h.tidy,$(CPPCHECK_H)) \
-	$(subst .cpp,.cpp.tidy,$(CPPCHECK_CPP))
+CLANGTIDY_FLAGS = -config='' \
+	-header-filter='.*' \
+	-checks='-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables,-cppcoreguidelines-avoid-goto,-modernize-avoid-c-arrays,-readability-magic-numbers,-readability-simplify-boolean-expr,-cppcoreguidelines-macro-usage' \
+
+CLANGTIDY_DEP = $(subst .cpp,.cpp.tidy,$(CPPCHECK_CPP))
 CLANGTIDY_DEFS = -DVL_DEBUG=1 -DVL_THREADED=1 -DVL_CPPCHECK=1
 
 clang-tidy: $(CLANGTIDY_DEP)
 %.cpp.tidy: %.cpp
 	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) | 2>&1 tee $@
 %.h.tidy: %.h
-	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) | 2>&1 tee $@
+	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) -x c++-header | 2>&1 tee $@
 
 analyzer-src:
 	-rm -rf src/obj_dbg
@@ -470,17 +348,20 @@ analyzer-include:
 
 format: clang-format yapf format-pl-exec
 
-CLANGFORMAT = clang-format-11
+CLANGFORMAT = clang-format-14
 CLANGFORMAT_FLAGS = -i
 CLANGFORMAT_FILES = $(CPPCHECK_CPP) $(CPPCHECK_H) $(CPPCHECK_YL) test_regress/t/*.c* test_regress/t/*.h
 
 clang-format:
-	@$(CLANGFORMAT) --version | egrep 11.0 > /dev/null \
-		|| echo "*** You are not using clang-format 11.0, indents may differ from master's ***"
+	@$(CLANGFORMAT) --version | egrep 14.0 > /dev/null \
+		|| echo "*** You are not using clang-format-14, indents may differ from master's ***"
 	$(CLANGFORMAT) $(CLANGFORMAT_FLAGS) $(CLANGFORMAT_FILES)
 
 PY_PROGRAMS = \
 	bin/verilator_ccache_report \
+	bin/verilator_difftree \
+	bin/verilator_gantt \
+	bin/verilator_profcfunc \
 	examples/xml_py/vl_file_copy \
 	examples/xml_py/vl_hier_graph \
 	docs/guide/conf.py \
@@ -512,10 +393,10 @@ yapf:
 FLAKE8 = flake8
 FLAKE8_FLAGS = \
 	--extend-exclude=fastcov.py \
-	--ignore=E123,E129,E251,E501,W503,W504,E701
+	--ignore=E123,E129,E251,E402,E501,W503,W504,E701
 
 PYLINT = pylint
-PYLINT_FLAGS = --disable=R0801
+PYLINT_FLAGS = --score=n --disable=R0801
 
 lint-py:
 	-$(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
@@ -524,9 +405,6 @@ lint-py:
 format-pl-exec:
 	-chmod a+x test_regress/t/*.pl
 
-
-ftp: info
-
 install-msg:
 	@echo
 	@echo "Installed binaries to $(DESTDIR)$(bindir)/verilator"
@@ -597,15 +475,6 @@ TAGS:	$(TAGFILES)
 doxygen:
 	$(MAKE) -C docs doxygen
 
-######################################################################
-# Test targets
-
-dist-file-list:
-	@echo "begin-dist-file-list:";  # Scripts look for this
-	@echo $(wildcard $(DISTFILES1))
-	@echo $(wildcard $(DISTFILES2))
-	@echo "end-dist-file-list:";  # Scripts look for this
-
 ######################################################################
 # Distributions
 
@@ -613,36 +482,16 @@ DISTTITLE := Verilator $(word 1,$(PACKAGE_VERSION))
 DISTNAME := verilator-$(word 1,$(PACKAGE_VERSION))
 DISTDATEPRE := $(word 2,$(PACKAGE_VERSION))
 DISTDATE := $(subst /,-,$(DISTDATEPRE))
-
 DISTTAGNAME := $(subst .,_,$(subst -,_,$(DISTNAME)))
 
 tag:
 	svnorcvs tag $(DISTTAGNAME)
 
-# Don't depend on DISTFILES because there's no rule for "standards.info*".
-dist: $(DISTDEP) maintainer-copy
-	-rm -fr $(DISTNAME)
-	for file in $(DISTFILES1); do \
-	  mkdir -p `dirname $(DISTNAME)/$$file` >/dev/null ; \
-	  ln $$file $(DISTNAME)/$$file \
-	  || { echo copying $$file instead; cp -p $$file $(DISTNAME)/$$file;}; \
-	done; true;
-	for file in $(DISTFILES2); do \
-	  mkdir -p `dirname $(DISTNAME)/$$file` >/dev/null ; \
-	  ln $$file $(DISTNAME)/$$file \
-	  || { echo copying $$file instead; cp -p $$file $(DISTNAME)/$$file;}; \
-	done; true;
-	chmod -R a+r $(DISTNAME)
-	tar chf $(DISTNAME).tar $(DISTNAME)
-	gzip --force --best $(DISTNAME).tar
-	mv $(DISTNAME).tar.gz $(DISTNAME).tgz
-	rm -fr $(DISTNAME)
-
 maintainer-diff:
 	svnorcvs diff $(DISTTAGNAME)
 
 preexist:
 	svnorcvs nexists $(DISTTAGNAME)
 
-maintainer-dist: preexist dist tag
-	svnorcvs release $(DISTNAME).tgz
+maintainer-dist: preexist tag
+	svnorcvs release $(DISTTAGNAME)

README.rst

@@ -5,6 +5,8 @@
     :target: https://www.gnu.org/licenses/lgpl-3.0]
 .. image:: https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg
     :target: https://opensource.org/licenses/Artistic-2.0
+.. image:: https://repology.org/badge/tiny-repos/verilator.svg?header=distro%20packages
+    :target: https://repology.org/project/verilator/versions
 .. image:: https://api.codacy.com/project/badge/Grade/fa78caa433c84a4ab9049c43e9debc6f
     :target: https://www.codacy.com/gh/verilator/verilator
 .. image:: https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg
@@ -12,20 +14,21 @@
 .. image:: https://github.com/verilator/verilator/workflows/build/badge.svg
     :target: https://github.com/verilator/verilator/actions?query=workflow%3Abuild
 
+
 Welcome to Verilator
 ====================
 
 .. list-table::
 
    * - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
-        * Accepts synthesizable Verilog or SystemVerilog
+        * Accepts Verilog or SystemVerilog
         * Performs lint code-quality checks
         * Compiles into multithreaded C++, or SystemC
         * Creates XML to front-end your own tools
      - |Logo|
    * - |verilator multithreaded performance|
      - **Fast**
-        * Outperforms many commercial simulators
+        * Outperforms many closed-source commercial simulators
         * Single- and multi-threaded output models
    * - **Widely Used**
         * Wide industry and academic deployment
@@ -52,25 +55,25 @@ performing lint checks, and optionally inserting assertion checks and
 coverage-analysis points. It outputs single- or multi-threaded .cpp and .h
 files, the "Verilated" code.
 
-The user writes a little C++/SystemC wrapper file, which instantiates the
-"Verilated" model of the user's top level module. These C++/SystemC files
-are then compiled by a C++ compiler (gcc/clang/MSVC++). The resulting
-executable performs the design simulation. Verilator also supports linking
-its generated libraries, optionally encrypted, into other simulators.
+These Verilated C++/SystemC files are then compiled by a C++ compiler
+(gcc/clang/MSVC++), optionally along with a user's own C++/SystemC wrapper
+file to instantiate the Verilated model. Executing the resulting executable
+performs the design simulation. Verilator also supports linking Verilated
+generated libraries, optionally encrypted, into other simulators.
 
 Verilator may not be the best choice if you are expecting a full featured
-replacement for NC-Verilog, VCS or another commercial Verilog simulator, or
-if you are looking for a behavioral Verilog simulator e.g. for a quick
-class project (we recommend `Icarus Verilog`_ for this.) However, if you
-are looking for a path to migrate SystemVerilog to C++ or SystemC, or your
-team is comfortable writing just a touch of C++ code, Verilator is the tool
-for you.
+replacement for a closed-source Verilog simulator, need SDF annotation,
+mixed-signal simulation, or are doing a quick class project (we recommend
+`Icarus Verilog`_ for classwork.)  However, if you are looking for a path
+to migrate SystemVerilog to C++/SystemC, or want high speed simulation of
+synthesizable designs containing limited verification constructs, Verilator
+is the tool for you.
 
 
 Performance
 ===========
 
-Verilator does not simply convert Verilog HDL to C++ or SystemC. Rather,
+Verilator does not directly translate Verilog HDL to C++ or SystemC. Rather,
 Verilator compiles your code into a much faster optimized and optionally
 thread-partitioned model, which is in turn wrapped inside a C++/SystemC
 module. The results are a compiled Verilog model that executes even on a
@@ -81,9 +84,11 @@ multithreading (yielding 200-1000x total over interpreted simulators).
 
 Verilator has typically similar or better performance versus the
 closed-source Verilog simulators (Carbon Design Systems Carbonator,
-Modelsim, Cadence Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic
-CVer/CVC). But, Verilator is open-sourced, so you can spend on computes
-rather than licenses. Thus Verilator gives you the best cycles/dollar.
+Modelsim/Questa, Cadence Incisive/NC-Verilog, Synopsys VCS, VTOC, and
+Pragmatic CVer/CVC). But, Verilator is open-sourced, so you can spend on
+computes rather than licenses. Thus Verilator gives you the best
+cycles/dollar.
+
 
 Installation & Documentation
 ============================
@@ -134,7 +139,7 @@ Related Projects
 Open License
 ============
 
-Verilator is Copyright 2003-2021 by Wilson Snyder. (Report bugs to
+Verilator is Copyright 2003-2022 by Wilson Snyder. (Report bugs to
 `Verilator Issues <https://verilator.org/issues>`_.)
 
 Verilator is free software; you can redistribute it and/or modify it under

bin/verilator

@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 ######################################################################
 #
-# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -34,11 +34,11 @@ my $opt_quiet_exit;
 
 # No arguments can't do anything useful.  Give help
 if ($#ARGV < 0) {
-    pod2usage(-exitstatus=>2, -verbose=>0);
+    pod2usage(-exitstatus => 2, -verbose => 0);
 }
 
 # Insert debugging options up front
-push @ARGV, (split ' ',$ENV{VERILATOR_TEST_FLAGS}||"");
+push @ARGV, (split ' ', $ENV{VERILATOR_TEST_FLAGS} || "");
 
 # We sneak a look at the flags so we can do some pre-environment checks
 # All flags will hit verilator...
@@ -46,7 +46,7 @@ foreach my $sw (@ARGV) {
     push @Opt_Verilator_Sw, $sw;
 }
 
-Getopt::Long::config("no_auto_abbrev","pass_through");
+Getopt::Long::config("no_auto_abbrev", "pass_through");
 if (! GetOptions(
           # Major operating modes
           "help"        => \&usage,
@@ -60,7 +60,7 @@ if (! GetOptions(
           # Additional parameters
           "<>"          => sub {},      # Ignored
     )) {
-    pod2usage(-exitstatus=>2, -verbose=>0);
+    pod2usage(-exitstatus => 2, -verbose => 0);
 }
 
 if ($opt_gdbbt && !gdb_works()) {
@@ -73,12 +73,12 @@ if ($opt_gdbbt && !gdb_works()) {
 # Starting with that, escape all special chars for the shell;
 # The shell will undo the escapes and the verilator binary should
 # then see exactly the contents of @Opt_Verilator_Sw.
-my @quoted_sw = map {sh_escape($_)} @Opt_Verilator_Sw;
+my @quoted_sw = map { sh_escape($_) } @Opt_Verilator_Sw;
 if ($opt_gdb) {
     # Generic GDB interactive
     run (aslr_off()
-         .($ENV{VERILATOR_GDB}||"gdb")
-         ." ".verilator_bin()
+         . ($ENV{VERILATOR_GDB} || "gdb")
+         . " " . verilator_bin()
          # Note, uncomment to set breakpoints before running:
          #  ." -ex 'break main'"
 
@@ -87,42 +87,41 @@ if ($opt_gdb) {
          # escapes as you would expect in a double-quoted string.
          # That's not true for a single-quoted string, where \'
          # actually terminates the string -- not what we want!
-         ." -ex \"run ".join(' ', @quoted_sw)."\""
-         ." -ex 'set width 0'"
-         ." -ex 'bt'");
+         . " -ex \"run " . join(' ', @quoted_sw) . "\""
+         . " -ex 'set width 0'"
+         . " -ex 'bt'");
 } elsif ($opt_rr) {
     # Record with rr
     run (aslr_off()
-         ."rr record ".verilator_bin()
-         ." ".join(' ', @quoted_sw));
+         . "rr record " . verilator_bin()
+         . " " . join(' ', @quoted_sw));
 } elsif ($opt_gdbbt && $Debug) {
     # Run under GDB to get gdbbt
     run (aslr_off()
-         ."gdb"
-         ." ".verilator_bin()
-         ." --batch --quiet --return-child-result"
-         ." -ex \"run ".join(' ', @quoted_sw)."\""
-         ." -ex 'set width 0'"
-         ." -ex 'bt' -ex 'quit'");
+         . "gdb"
+         . " " . verilator_bin()
+         . " --batch --quiet --return-child-result"
+         . " -ex \"run " . join(' ', @quoted_sw)."\""
+         . " -ex 'set width 0'"
+         . " -ex 'bt' -ex 'quit'");
 } elsif ($Debug) {
     # Debug
-    run(aslr_off()
-        .verilator_bin()." ".join(' ',@quoted_sw));
+    run(aslr_off() . verilator_bin() . " " . join(' ', @quoted_sw));
 } else {
     # Normal, non gdb
-    run(verilator_bin()." ".join(' ',@quoted_sw));
+    run(verilator_bin() . " " . join(' ', @quoted_sw));
 }
 
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    pod2usage(-verbose => 2, -exitval => 0, -output => \*STDOUT);
 }
 
 sub debug {
     shift;
     my $level = shift;
-    $Debug = $level||3;
+    $Debug = $level || 3;
 }
 
 #######################################################################
@@ -163,13 +162,13 @@ sub verilator_bin {
 sub gdb_works {
     $! = undef;  # Cleanup -x
     system("gdb /bin/echo"
-           ." --batch-silent --quiet --return-child-result"
-           ." -ex 'run -n'"  # `echo -n`
-           ." -ex 'set width 0'"
-           ." -ex 'bt'"
-           ." -ex 'quit'");
+           . " --batch-silent --quiet --return-child-result"
+           . " -ex 'run -n'"  # `echo -n`
+           . " -ex 'set width 0'"
+           . " -ex 'bt'"
+           . " -ex 'quit'");
     my $status = $?;
-    return $status==0;
+    return $status == 0;
 }
 
 sub aslr_off {
@@ -185,7 +184,7 @@ sub run {
     # Run command, check errors
     my $command = shift;
     $! = undef;  # Cleanup -x
-    print "\t$command\n" if $Debug>=3;
+    print "\t$command\n" if $Debug >= 3;
     system($command);
     my $status = $?;
     if ($status) {
@@ -193,7 +192,7 @@ sub run {
             warn "%Error: verilator: Misinstalled, or VERILATOR_ROOT might need to be in environment\n";
         }
         if ($Debug) {  # For easy rerunning
-            warn "%Error: export VERILATOR_ROOT=".($ENV{VERILATOR_ROOT}||"")."\n";
+            warn "%Error: export VERILATOR_ROOT=" . ($ENV{VERILATOR_ROOT} || "") . "\n";
             warn "%Error: $command\n";
         }
         if ($status & 127) {
@@ -201,13 +200,13 @@ sub run {
                 || ($status & 127) == 8  # SIGFPA
                 || ($status & 127) == 11) {  # SIGSEGV
                 warn "%Error: Verilator internal fault, sorry. "
-                    ."Suggest trying --debug --gdbbt\n" if !$Debug;
+                    . "Suggest trying --debug --gdbbt\n" if !$Debug;
             } elsif (($status & 127) == 6) {  # SIGABRT
                 warn "%Error: Verilator aborted. "
-                    ."Suggest trying --debug --gdbbt\n" if !$Debug;
+                    . "Suggest trying --debug --gdbbt\n" if !$Debug;
             } else {
                 warn "%Error: Verilator threw signal $status. "
-                    ."Suggest trying --debug --gdbbt\n" if !$Debug;
+                    . "Suggest trying --debug --gdbbt\n" if !$Debug;
             }
         }
         if (!$opt_quiet_exit && ($status != 256 || $Debug)) {  # i.e. not normal exit(1)
@@ -245,6 +244,7 @@ Verilator - Translate and simulate SystemVerilog code using C++/SystemC
 
     verilator --help
     verilator --version
+    verilator --binary -j 0 [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
     verilator --cc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
     verilator --sc [options] [source_files.v]... [opt_c_files.cpp/c/cc/a/o/so]
     verilator --lint-only -Wall [source_files.v]...
@@ -283,35 +283,43 @@ detailed descriptions of these arguments.
     --autoflush                 Flush streams after all $displays
     --bbox-sys                  Blackbox unknown $system calls
     --bbox-unsup                Blackbox unsupported language features
-    --bin <filename>            Override Verilator binary
+    --binary                    Build model binary
     --build                     Build model executable/library after Verilation
-     -CFLAGS <flags>            C++ compiler arguments for makefile
+    --build-dep-bin <filename>  Override build dependency Verilator binary
+    --build-jobs <jobs>         Parallelism for --build
     --cc                        Create C++ output
     --cdc                       Clock domain crossing analysis
+     -CFLAGS <flags>            C++ compiler arguments for makefile
     --clk <signal-name>         Mark specified signal as clock
-    --make <build-tool>         Generate scripts for specified build tool
+    --no-clk <signal-name>      Prevent marking specified signal as clock
     --compiler <compiler-name>  Tune for specified C++ compiler
     --converge-limit <loops>    Tune convergence settle time
     --coverage                  Enable all coverage
     --coverage-line             Enable line coverage
     --coverage-max-width <width>   Maximum array depth for coverage
     --coverage-toggle           Enable toggle coverage
-    --coverage-user             Enable SVL user coverage
     --coverage-underscore       Enable coverage of _signals
+    --coverage-user             Enable SVL user coverage
      -D<var>[=<value>]          Set preprocessor define
     --debug                     Enable debugging
     --debug-check               Enable debugging assertions
     --no-debug-leak             Disable leaking memory in --debug mode
     --debugi <level>            Enable debugging at a specified level
     --debugi-<srcfile> <level>  Enable debugging a source file at a level
+    --no-decoration             Disable comments and symbol decorations
     --default-language <lang>   Default language to parse
      +define+<var>=<value>      Set preprocessor define
     --dpi-hdr-only              Only produce the DPI header file
     --dump-defines              Show preprocessor defines with -E
-    --dump-tree                 Enable dumping .tree files
-    --dump-treei <level>        Enable dumping .tree files at a level
-    --dump-treei-<srcfile> <level>  Enable dumping .tree file at a source file at a level
+    --dump-dfg                  Enable dumping DfgGraphs to .dot files
+    --dump-graph                Enable dumping V3Graphs to .dot files
+    --dump-tree                 Enable dumping Ast .tree files
     --dump-tree-addrids         Use short identifiers instead of addresses
+    --dump-<srcfile>            Enable dumping everything in source file
+    --dumpi-dfg <level>         Enable dumping DfgGraphs to .dot files at level
+    --dumpi-graph <level>       Enable dumping V3Graphs to .dot files at level
+    --dumpi-tree <level>        Enable dumping Ast .tree files at level
+    --dumpi-<srcfile> <level>   Enable dumping everything in source file at level
      -E                         Preprocess, but do not compile
     --error-limit <value>       Abort after this number of errors
     --exe                       Link to create executable
@@ -320,60 +328,63 @@ detailed descriptions of these arguments.
      -f <file>                  Parse arguments from a file
      -FI <file>                 Force include of a file
     --flatten                   Force inlining of all modules, tasks and functions
+     -fno-<optimization>        Disable internal optimization stage
      -G<name>=<value>           Overwrite top-level parameter
+    --gate-stmts <value>        Tune gate optimizer depth
     --gdb                       Run Verilator under GDB interactively
     --gdbbt                     Run Verilator under GDB for backtrace
     --generate-key              Create random key for --protect-key
     --getenv <var>              Get environment variable with defaults
+    --get-supported <feature>   Get if feature is supported
     --help                      Display this help
     --hierarchical              Enable hierarchical Verilation
      -I<dir>                    Directory to search for includes
-     -j <jobs>                  Parallelism for --build
-    --gate-stmts <value>        Tune gate optimizer depth
     --if-depth <value>          Tune IFDEPTH warning
      +incdir+<dir>              Directory to search for includes
     --inline-mult <value>       Tune module inlining
-     -LDFLAGS <flags>           Linker pre-object arguments for makefile
+    --instr-count-dpi <value>   Assumed dynamic instruction count of DPI imports
+     -j <jobs>                  Parallelism for --build (alias to --build-jobs)
     --l2-name <value>           Verilog scope name of the top module
     --language <lang>           Default language standard to parse
+     -LDFLAGS <flags>           Linker pre-object arguments for makefile
+    --lib-create <name>         Create a DPI library
      +libext+<ext>+[ext]...     Extensions for finding modules
     --lint-only                 Lint, but do not make output
+    --make <build-tool>         Generate scripts for specified build tool
      -MAKEFLAGS <flags>         Arguments to pass to make during --build
+    --main                      Generate C++ main() file
     --max-num-width <value>     Maximum number width (default: 64K)
-    --MMD                       Create .d dependency files
-    --MP                        Create phony dependency targets
     --Mdir <directory>          Name of output object directory
-    --no-merge-const-pool       Disable merging of different types in const pool
+    --MMD                       Create .d dependency files
     --mod-prefix <topname>      Name to prepend to lower classes
-    --no-clk <signal-name>      Prevent marking specified signal as clock
-    --no-decoration             Disable comments and symbol decorations
-    --no-pins64                 Don't use vluint64_t's for 33-64 bit sigs
-    --no-skip-identical         Disable skipping identical output
+    --MP                        Create phony dependency targets
      +notimingchecks            Ignored
      -O0                        Disable optimizations
      -O3                        High performance optimizations
      -O<optimization-letter>    Selectable optimizations
      -o <executable>            Name of final executable
     --no-order-clock-delay      Disable ordering clock enable assignments
-    --no-verilate               Skip verilation and just compile previously Verilated code.
+    --no-verilate               Skip Verilation, only compile previously Verilated code
     --output-split <statements>          Split .cpp files into pieces
     --output-split-cfuncs <statements>   Split model functions
     --output-split-ctrace <statements>   Split tracing functions
      -P                         Disable line numbers and blanks with -E
     --pins-bv <bits>            Specify types for top level ports
-    --pins-sc-uint              Specify types for top level ports
     --pins-sc-biguint           Specify types for top level ports
+    --pins-sc-uint              Specify types for top level ports
     --pins-uint8                Specify types for top level ports
+    --no-pins64                 Don't use uint64_t's for 33-64 bit sigs
     --pipe-filter <command>     Filter all input through a script
     --pp-comments               Show preprocessor comments with -E
     --prefix <topname>          Name of top level class
+    --private                   Debugging; see docs
     --prof-c                    Compile C++ code with profiling
     --prof-cfuncs               Name functions for profiling
-    --prof-threads              Enable generating gantt chart data for threads
-    --protect-key <key>         Key for symbol protection
+    --prof-exec                 Enable generating execution profile for gantt chart
+    --prof-pgo                  Enable generating profiling data for PGO
     --protect-ids               Hash identifier names for obscurity
+    --protect-key <key>         Key for symbol protection
     --protect-lib <name>        Create a DPI protected library
-    --private                   Debugging; see docs
     --public                    Debugging; see docs
     --public-flat-rw            Mark all variables, etc as public_flat_rw
      -pvalue+<name>=<value>     Overwrite toplevel parameter
@@ -384,6 +395,7 @@ detailed descriptions of these arguments.
     --rr                        Run Verilator and record with rr
     --savable                   Enable model save-restore
     --sc                        Create SystemC output
+    --no-skip-identical         Disable skipping identical output
     --stats                     Create statistics file
     --stats-vars                Provide statistics on variables
      -sv                        Enable SystemVerilog parsing
@@ -391,6 +403,8 @@ detailed descriptions of these arguments.
     --threads <threads>         Enable multithreading
     --threads-dpi <mode>        Enable multithreaded DPI
     --threads-max-mtasks <mtasks>  Tune maximum mtask partitioning
+    --timing                    Enable timing support
+    --no-timing                 Disable timing support
     --timescale <timescale>     Sets default timescale
     --timescale-override <timescale>  Overrides all timescales
     --top <topname>             Alias of --top-module
@@ -403,7 +417,7 @@ detailed descriptions of these arguments.
     --trace-max-width <width>   Maximum array depth for tracing
     --trace-params              Enable tracing of parameters
     --trace-structs             Enable tracing structure names
-    --trace-threads <threads>   Enable waveform creation on separate threads
+    --trace-threads <threads>   Enable FST waveform creation on separate threads
     --trace-underscore          Enable tracing of _signals
      -U<var>                    Undefine preprocessor define
     --unroll-count <loops>      Tune maximum loop iterations
@@ -411,6 +425,7 @@ detailed descriptions of these arguments.
     --unused-regexp <regexp>    Tune UNUSED lint signals
      -V                         Verbose version and config
      -v <filename>              Verilog library
+    --no-verilate               Skip verilation and just compile previously Verilated code.
      +verilog1995ext+<ext>      Synonym for +1364-1995ext+<ext>
      +verilog2001ext+<ext>      Synonym for +1364-2001ext+<ext>
     --version                   Displays program version and exits
@@ -425,6 +440,9 @@ detailed descriptions of these arguments.
      -Wno-lint                  Disable all lint warnings
      -Wno-style                 Disable all style warnings
      -Wpedantic                 Warn on compliance-test issues
+     -Wwarn-<message>           Enable specified warning message
+     -Wwarn-lint                Enable lint warning message
+     -Wwarn-style               Enable style warning message
     --x-assign <mode>           Assign non-initial Xs to this value
     --x-initial <mode>          Assign initial Xs to this value
     --x-initial-edge            Enable initial X->0 and X->1 edge triggers
@@ -444,9 +462,10 @@ description of these arguments.
      +verilator+error+limit+<value>    Set error limit
      +verilator+help                   Display help
      +verilator+noassert               Disable assert checking
-     +verilator+prof+threads+file+<filename>  Set profile filename
-     +verilator+prof+threads+start+<value>    Set profile starting point
-     +verilator+prof+threads+window+<value>   Set profile duration
+     +verilator+prof+exec+file+<filename>  Set execution profile filename
+     +verilator+prof+exec+start+<value>    Set execution profile starting point
+     +verilator+prof+exec+window+<value>   Set execution profile duration
+     +verilator+prof+vlt+file+<filename>   Set PGO profile filename
      +verilator+rand+reset+<value>     Set random reset technique
      +verilator+seed+<value>           Set random seed
      +verilator+V                      Verbose version and config
@@ -457,7 +476,7 @@ description of these arguments.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
+Copyright 2003-2022 by Wilson Snyder. This program is free software; you can
 redistribute it and/or modify the Verilator internals under the terms of
 either the GNU Lesser General Public License Version 3 or the Perl Artistic
 License Version 2.0.

bin/verilator_ccache_report

@@ -14,7 +14,7 @@ parser = argparse.ArgumentParser(
     formatter_class=argparse.RawDescriptionHelpFormatter,
     description="""Report ccache behavior of a Verilated model build.""",
     epilog=
-    """Copyright 2002-2021 by Wilson Snyder. This program is free software; you
+    """Copyright 2002-2022 by Wilson Snyder. This program 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.

bin/verilator_coverage

@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 ######################################################################
 #
-# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -30,7 +30,7 @@ $Debug = 0;
 
 # No arguments can't do anything useful.  Give help
 if ($#ARGV < 0) {
-    pod2usage(-exitstatus=>2, -verbose=>0);
+    pod2usage(-exitstatus => 2, -verbose => 0);
 }
 
 # We sneak a look at the flags so we can do some pre-environment checks
@@ -40,7 +40,7 @@ foreach my $sw (@ARGV) {
     push @Opt_Verilator_Sw, $sw;
 }
 
-Getopt::Long::config("no_auto_abbrev","pass_through");
+Getopt::Long::config("no_auto_abbrev", "pass_through");
 if (! GetOptions (
           # Major operating modes
           "help"        => \&usage,
@@ -49,23 +49,23 @@ if (! GetOptions (
           # Additional parameters
           "<>"          => sub {},      # Ignored
     )) {
-    pod2usage(-exitstatus=>2, -verbose=>0);
+    pod2usage(-exitstatus => 2, -verbose => 0);
 }
 
 # Normal, non gdb
 run(verilator_coverage_bin()
-    ." ".join(' ',@Opt_Verilator_Sw));
+    . " " . join(' ', @Opt_Verilator_Sw));
 
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    pod2usage(-verbose => 2, -exitval => 0, -output => \*STDOUT);
 }
 
 sub debug {
     shift;
     my $level = shift;
-    $Debug = $level||3;
+    $Debug = $level || 3;
 }
 
 #######################################################################
@@ -107,7 +107,7 @@ sub run {
     # Run command, check errors
     my $command = shift;
     $! = undef;  # Cleanup -x
-    print "\t$command\n" if $Debug>=3;
+    print "\t$command\n" if $Debug >= 3;
     system($command);
     my $status = $?;
     if ($status) {
@@ -115,11 +115,11 @@ sub run {
             warn "%Error: verilator_coverage: Misinstalled, or VERILATOR_ROOT might need to be in environment\n";
         }
         if ($Debug) {  # For easy rerunning
-            warn "%Error: export VERILATOR_ROOT=".($ENV{VERILATOR_ROOT}||"")."\n";
+            warn "%Error: export VERILATOR_ROOT=" . ($ENV{VERILATOR_ROOT} || "") . "\n";
             warn "%Error: $command\n";
         }
         if ($status & 127) {
-            if (($status & 127) == 8 || ($status & 127) == 11) { # SIGFPA or SIGSEGV
+            if (($status & 127) == 8 || ($status & 127) == 11) {  # SIGFPA or SIGSEGV
                 warn "%Error: Verilator_coverage internal fault, sorry.\n" if !$Debug;
             } elsif (($status & 127) == 6) {  # SIGABRT
                 warn "%Error: Verilator_coverage aborted.\n" if !$Debug;
@@ -187,7 +187,7 @@ L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+Copyright 2003-2022 by Wilson Snyder. This program is free software; you
 can redistribute it and/or modify the Verilator internals under the terms
 of either the GNU Lesser General Public License Version 3 or the Perl
 Artistic License Version 2.0.

bin/verilator_difftree

@@ -1,233 +1,139 @@
-#!/usr/bin/env perl
-# See copyright, etc in below POD section.
+#!/usr/bin/env python3
+# pylint: disable=C0103,C0114,C0116
 ######################################################################
 
-use warnings;
-use Getopt::Long;
-use IO::File;
-use Pod::Usage;
-use strict;
-use vars qw($Debug);
+import argparse
+import collections
+import glob
+import os.path
+import re
+import sys
 
-#======================================================================
-# main
 
-$Debug = 0;
-my $Opt_A;
-my $Opt_B;
-my $Opt_Lineno = 1;
-autoflush STDOUT 1;
-autoflush STDERR 1;
-Getopt::Long::config("no_auto_abbrev");
-if (! GetOptions(
-          "help"        => \&usage,
-          "debug"       => \&debug,
-          "<>"          => \&parameter,
-          "lineno!"     => \$Opt_Lineno,
-    )) {
-    die "%Error: Bad usage, try 'verilator_difftree --help'\n";
-}
+def diff(a, b):
 
-defined $Opt_A or die "%Error: No old diff filename\n";
-defined $Opt_B or die "%Error: No new diff filename\n";
+    if not os.path.exists(a):
+        sys.exit("%Error: No old diff filename found: " + a)
+    if not os.path.exists(b):
+        sys.exit("%Error: No new diff filename found: " + b)
 
--e $Opt_A or die "%Error: No old diff filename found: $Opt_A\n";
--e $Opt_B or die "%Error: No new diff filename found: $Opt_B\n";
+    if os.path.isdir(a) and os.path.isdir(b):
+        diff_dir(a, b)
+    elif os.path.isfile(a) and os.path.isfile(b):
+        diff_file(a, b)
+    else:
+        sys.exit("%Error: Mix of files and dirs")
 
-if (-d $Opt_A && -d $Opt_B) {
-    diff_dir($Opt_A, $Opt_B);
-} elsif (-f $Opt_A && -f $Opt_B) {
-    diff_file($Opt_A, $Opt_B);
-} else {
-    die "%Error: Mix of files and dirs\n";
-}
 
-sub diff_dir {
-    my $a = shift;
-    my $b = shift;
+def diff_dir(a, b):
     # Diff all files under two directories
-    my %files;
+    files = collections.defaultdict(lambda: {})
 
-    foreach my $fn (glob("$a/*.tree")) {
-        (my $base = $fn) =~ s!.*/!!;
-        $files{$base}{a} = $fn;
-    }
-    foreach my $fn (glob("$b/*.tree")) {
-        (my $base = $fn) =~ s!.*/!!;
-        $files{$base}{b} = $fn;
-    }
-    my $any;
-    foreach my $base (sort (keys %files)) {
-        my $a = $files{$base}{a};
-        my $b = $files{$base}{b};
-        next if !$a || !$b;
-        print "="x70,"\n";
-        print "= $a <-> $b\n";
-        diff_file($a,$b);
-        $any = 1;
-    }
-    $any or warn("%Warning: No .tree files found that have similar base names:\n    "
-                 .join("\n    ", sort keys %files),"\n");
-}
+    for fn in glob.glob(a + "/*.tree"):
+        base = re.sub(r'.*/', '', fn)
+        files[base]['a'] = fn
+    for fn in glob.glob(b + "/*.tree"):
+        base = re.sub(r'.*/', '', fn)
+        files[base]['b'] = fn
 
-sub diff_file {
-    my $a = shift;
-    my $b = shift;
+    anyfile = False
+    for base in sorted(files.keys()):
+        if ('a' not in files[base]) or ('b' not in files[base]):
+            continue
+        a = files[base]['a']
+        b = files[base]['b']
+        print("=" * 70)
+        print("= %s <-> %s" % (a, b))
+        diff_file(a, b)
+        anyfile = True
+    if not anyfile:
+        sys.stderr.write(
+            "%Warning: No .tree files found that have similar base names\n")
+
+
+def diff_file(a, b):
     # Compare the two tree files
-    (my $short_a = $a) =~ s/[^a-zA-Z0-9.]+/_/g;
-    (my $short_b = $b) =~ s/[^a-zA-Z0-9.]+/_/g;
-    my $tmp_a = "/tmp/${$}_${short_a}.a";
-    my $tmp_b = "/tmp/${$}_${short_b}.b";
+    short_a = re.sub(r'[^a-zA-Z0-9.]+', '_', a)
+    short_b = re.sub(r'[^a-zA-Z0-9.]+', '_', b)
+    tmp_a = "/tmp/%s_%s.a" % (os.getpid(), short_a)
+    tmp_b = "/tmp/%s_%s.b" % (os.getpid(), short_b)
 
-    my $vera = version_from($a);
-    my $verb = version_from($b);
-    my $verCvt = (($vera < 0x3900 && $verb >= 0x3900)
-                  || ($vera >= 0x3900 && $verb < 0x3900));
+    # Version conversion deprecated, but for future...
+    # vera = version_from(a)
+    # verb = version_from(b)
+    # verCvt = ((vera < 0x3900 and verb >= 0x3900)
+    #            or (vera >= 0x3900 and verb < 0x3900))
 
-    filter($a, $tmp_a, $verCvt);
-    filter($b, $tmp_b, $verCvt);
-    system("diff -u $tmp_a $tmp_b");
-    unlink $tmp_a;
-    unlink $tmp_b;
-}
+    filterf(a, tmp_a)
+    filterf(b, tmp_b)
+    os.system("diff -u " + tmp_a + " " + tmp_b)
+    os.unlink(tmp_a)
+    os.unlink(tmp_b)
 
-sub version_from {
-    my $fn = shift;
+
+def version_from(filename):
     # Return dump format
-    my $f1 = IO::File->new ($fn) or die "%Error: $! $fn,";
-    while (defined (my $line=$f1->getline())) {
-        last if $. > 10;
-        return hex $1 if $line =~ /\(format (0x[0-9.]+)\)/;
-    }
-    return 1.0;
-}
+    with open(filename) as fh:
+        lineno = 0
+        for line in fh:
+            if lineno > 10:
+                break
+            match = re.search(r'format (0x[0-9.]+)', line)
+            if match:
+                return hex(match.group(1))
+    return 1.0
 
-sub filter {
-    my $fn1 = shift;
-    my $fn2 = shift;
-    my $verCvt = shift;
+
+def filterf(fn1, fn2):
     # Remove hex numbers before diffing
-    my $f1 = IO::File->new ($fn1) or die "%Error: $! $fn1,";
-    my $f2 = IO::File->new ($fn2,"w") or die "%Error: $! $fn2,";
-    while (defined (my $line=$f1->getline())) {
-      same_line:
-        next if $line =~ / This=/;
-        $line =~ s/0x[a-f0-9]+/0x/g;
-        $line =~ s/<e[0-9]+\#?>/<e>/g;
-        $line =~ s/{[a-z]*\d+}/{}/g if !$Opt_Lineno;
-        if ($verCvt) {
-            next if $line =~ /^     NETLIST/;
-            if ($line =~ /: ([A-Z]+) /) {
-                my $type = $1;
-                next if $type =~ 'DTYPE';
-                if ($type eq 'TYPETABLE' || $type eq 'RANGE') {
-                    $line =~ /^(\s+\S+:) /; my $prefix = $1;
-                    while (defined ($line=$f1->getline())) {
-                        next if $line =~ /^\s+[a-z]/;  # Table body
-                        next if $line =~ /^${prefix}[0-9]:/;
-                        goto same_line;
-                    }
-                    next;
-                }
-            }
-        }
-        print $f2 $line;
-    }
-    $f1->close;
-    $f2->close;
-}
+    with open(fn1) as fh1:
+        with open(fn2, "w") as fh2:
+            for line in fh1:
+                if re.search(r' This=', line):
+                    continue
+                line = re.sub(r'0x[a-f0-9]+', '0x', line)
+                line = re.sub(r'<e[0-9]+\#?>', '<e>', line)
+                if not Args.no_lineno:
+                    line = re.sub(r'{[a-z]*\d+}', '{}', line)
+                fh2.write(line)
 
-#----------------------------------------------------------------------
 
-sub usage {
-    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
-    exit(1);  # Unreachable
-}
+######################################################################
+######################################################################
 
-sub debug {
-    $Debug = 1;
-}
-
-sub parameter {
-    my $param = shift;
-    if (!defined $Opt_A) {
-        $Opt_A = $param;
-    } elsif (!defined $Opt_B) {
-        $Opt_B = $param;
-    } else {
-        die "%Error: Unknown parameter: $param\n";
-    }
-}
-
-#######################################################################
-
-sub run {
-    # Run a system command, check errors
-    my $command = shift;
-    print "\t$command\n";
-    system "$command";
-    my $status = $?;
-    ($status == 0) or die "%Error: Command Failed $command, $status, stopped";
-}
-
-#######################################################################
-__END__
-
-=pod
-
-=head1 NAME
-
-verilator_difftree - Compare two Verilator debugging trees
-
-=head1 SYNOPSIS
-
-  verilator_difftree .../a/a.tree  .../b/a.tree
-  verilator_difftree .../a         .../b
-
-=head1 DESCRIPTION
-
-Verilator_difftree is used for debugging Verilator tree output files.  It
-performs a diff between two files, or all files common between two
+parser = argparse.ArgumentParser(
+    allow_abbrev=False,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    description="""Compare two Verilator debugging trees""",
+    epilog=
+    """Verilator_difftree is used for debugging Verilator tree output files.
+It performs a diff between two files, or all files common between two
 directories, ignoring irrelevant pointer differences.
 
-=head1 ARGUMENTS
+For documentation see
+https://verilator.org/guide/latest/exe_verilator_difftree.html
 
-=over 4
-
-=item --help
-
-Displays this message and program version and exits.
-
-=item --nolineno
-
-Do not show differences in line numbering.
-
-=back
-
-=head1 DISTRIBUTION
-
-The latest version is available from L<https://verilator.org>.
-
-Copyright 2005-2021 by Wilson Snyder. This program is free software; you
+Copyright 2005-2022 by Wilson Snyder. This program 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.
 
-SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
 
-=head1 AUTHORS
+parser.add_argument('--debug',
+                    action='store_const',
+                    const=9,
+                    help='enable debug')
+parser.add_argument('--no-lineno',
+                    action='store_false',
+                    help='do not show differences in line numbering')
+parser.add_argument('filea', help='input file a to diff')
+parser.add_argument('fileb', help='input file b to diff')
 
-Wilson Snyder <[email protected]>
-
-=head1 SEE ALSO
-
-C<verilator>
-
-and L<https://verilator.org/verilator_doc.html> for detailed documentation.
-
-=cut
+Args = parser.parse_args()
+diff(Args.filea, Args.fileb)
 
 ######################################################################
-### Local Variables:
-### compile-command: "$V4/bin/verilator_difftree  {$V4D,$V4}/test_regress/obj_dir/t_EXAMPLE/V*_03_*.tree"
-### End:
+# Local Variables:
+# compile-command: "./verilator_difftree ../test_regress/t/t_difftree.{a,b}.tree"
+# End:

bin/verilator_includer

@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 # DESCRIPTION: Print include statements for each ARGV
 #
-# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -10,11 +10,11 @@
 
 require 5.005;
 use warnings;
-print "// DESCR"."IPTION: Generated by verilator_includer via makefile\n";
+print "// DESCR" . "IPTION: Generated by verilator_includer via makefile\n";
 foreach my $param (@ARGV) {
     if ($param =~ /^-D([^=]+)=(.*)/) {
-        print "#define $1 $2\n"
+        print "#define $1 $2\n";
     } else {
-        print "#include \"$param\"\n"
+        print "#include \"$param\"\n";
     }
 }

bin/verilator_profcfunc

@@ -1,248 +1,204 @@
-#!/usr/bin/env perl
-# See copyright, etc in below POD section.
+#!/usr/bin/env python3
+# pylint: disable=C0103,C0114,C0116,R0914,R0912,R0915,eval-used
 ######################################################################
 
-require 5.006_001;
-use warnings;
-use Getopt::Long;
-use IO::File;
-use Pod::Usage;
-eval { use Data::Dumper;  $Data::Dumper::Indent = 1; }; # Debug, ok if missing
-use strict;
-use vars qw($Debug);
+import argparse
+import collections
+import re
+# from pprint import pprint
 
-#======================================================================
+######################################################################
 
 
-#======================================================================
-# main
+def profcfunc(filename):
+    funcs = {}
 
-$Debug = 0;
-my $Opt_File;
-autoflush STDOUT 1;
-autoflush STDERR 1;
-Getopt::Long::config("no_auto_abbrev");
-if (! GetOptions(
-          "help"        => \&usage,
-          "debug"       => \&debug,
-          "<>"          => \&parameter,
-    )) {
-    die "%Error: Bad usage, try 'verilator_profcfunc --help'\n";
-}
+    with open(filename) as fh:
 
-defined $Opt_File or die "%Error: No filename given\n";
+        for line in fh:
+            #                  %time      cumesec   selfsec     calls     {stuff}   name
+            match = re.match(
+                r'^\s*([0-9.]+)\s+[0-9.]+\s+([0-9.]+)\s+([0-9.]+)\s+[^a-zA-Z_]*([a-zA-Z_].*)$',
+                line)
+            if match:
+                pct = float(match.group(1))
+                sec = float(match.group(2))
+                calls = float(match.group(3))
+                func = match.group(4)
+                if func not in funcs:
+                    funcs[func] = {'pct': 0, 'sec': 0, 'calls': 0}
+                funcs[func]['pct'] += pct
+                funcs[func]['sec'] += sec
+                funcs[func]['calls'] += calls
+                continue
 
-profcfunc($Opt_File);
-
-#----------------------------------------------------------------------
-
-sub usage {
-    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
-    exit(1);  # Unreachable
-}
-
-sub debug {
-    $Debug = 1;
-}
-
-sub parameter {
-    my $param = shift;
-    if (!defined $Opt_File) {
-        $Opt_File = $param;
-    } else {
-        die "%Error: Unknown parameter: $param\n";
-    }
-}
-
-#######################################################################
-
-sub profcfunc {
-    my $filename = shift;
-    # Remove hex numbers before diffing
-    my $fh = IO::File->new ($filename) or die "%Error: $! $filename,";
-
-    my %funcs;
-
-    while (defined (my $line=$fh->getline())) {
-        #                  %time      cumesec   selfsec     calls     {stuff}   name
-        if ($line =~ /^\s*([0-9.]+)\s+[0-9.]+\s+([0-9.]+)\s+([0-9.]+)\s+[^a-zA-Z_]*([a-zA-Z_].*)$/) {
-            my $pct=$1; my $sec=$2; my $calls=$3; my $func=$4;
-            $funcs{$func}{pct} += $pct;
-            $funcs{$func}{sec} += $sec;
-            $funcs{$func}{calls} += $calls;
-        }
-        # Older gprofs have no call column for single-call functions
-        #                  %time      cumesec   selfsec      {stuff}   name
-        elsif ($line =~ /^\s*([0-9.]+)\s+[0-9.]+\s+([0-9.]+)\s+[^a-zA-Z_]*([a-zA-Z_].*)$/) {
-            my $pct=$1; my $sec=$2; my $calls=1; my $func=$3;
-            $funcs{$func}{pct} += $pct;
-            $funcs{$func}{sec} += $sec;
-            $funcs{$func}{calls} += $calls;
-        }
-    }
-    $fh->close;
+            # Older gprofs have no call column for single-call functions
+            #                  %time      cumesec   selfsec      {stuff}   name
+            match = re.match(
+                r'^\s*([0-9.]+)\s+[0-9.]+\s+([0-9.]+)\s+[^a-zA-Z_]*([a-zA-Z_].*)$',
+                line)
+            if match:
+                pct = float(match.group(1))
+                sec = float(match.group(2))
+                calls = 1
+                func = match.group(3)
+                if func not in funcs:
+                    funcs[func] = {'pct': 0, 'sec': 0, 'calls': 0}
+                funcs[func]['pct'] += pct
+                funcs[func]['sec'] += sec
+                funcs[func]['calls'] += calls
+                continue
 
     # Find modules
-    my %pointer_mods;
-    my %verilated_mods;
-    foreach my $func (keys %funcs) {
-        if ($func =~ /(.*)::_eval\(([a-zA-Z_0-9]+__Syms).*\)$/) {
-            $verilated_mods{$1} = qr/^$1/;
-            $pointer_mods{$2} = $1;
-        }
-    }
-    #print Dumper(\%pointer_mods, \%verilated_mods);
+    verilated_mods = {}
+    for func in funcs:
+        match = re.search(r'(.*)::eval(_step)?\(', func)
+        if match:
+            prefix = match.group(1)
+            if Args.debug:
+                print("-got _eval %s   prefix=%s" % (func, prefix))
+            verilated_mods[prefix] = re.compile(r'^' + prefix)
+    # pprint(verilated_mods)
 
-    # Resort by Verilog name
-    my %vfuncs;
-    my %groups;
-    foreach my $func (keys %funcs) {
-        my $pct = $funcs{$func}{pct};
-        my $vfunc = $func;
-        my $design;
+    # Sort by Verilog name
+    vfuncs = {}
+    groups = {}
+    groups['type'] = collections.defaultdict(lambda: 0)
+    groups['design'] = collections.defaultdict(lambda: 0)
+    groups['module'] = collections.defaultdict(lambda: 0)
 
-        if ($func =~ /\(([a-zA-Z_0-9]+__Syms)/) {
-            $design = $pointer_mods{$1};
-        }
+    for func in funcs:
+        pct = funcs[func]['pct']
+        vfunc = func
 
-        foreach my $vde (keys %verilated_mods) {
-            last if $design;
-            if ($func =~ /$verilated_mods{$vde}/) {
-                $design=$vde;
-                last;
-            }
-        }
+        funcarg = re.sub(r'^.*\(', '', func)
 
-        if ($vfunc =~ /__PROF__([a-zA-Z_0-9]+)__l?([0-9]+)\(/) {
-            $vfunc     = sprintf("VBlock    %s:%d", $1, $2);
-            $groups{type}{"Verilog Blocks under $design"} += $pct;
-            $groups{design}{$design} += $pct;
-            $groups{module}{$1} += $pct;
-        } else {
-            if ($design) {
-                $vfunc = sprintf("VCommon   %s", $func);
-                $groups{type}{"Common code under $design"} += $pct;
-                $groups{design}{$design} += $pct;
-                $groups{module}{$design." common code"} += $pct;
-            } elsif ($func =~ /^VL_[A-Z0-9_]+/
-                     || $func =~ /^_?vl_[a-zA-Z0-9_]+/
-                     || $func =~ /^verilated/i) {
-                $vfunc = sprintf("VLib      %s", $func);
-                $groups{type}{'VLib'} += $pct;
-                $groups{design}{'VLib'} += $pct;
-                $groups{module}{'VLib'} += $pct;
-            } elsif ($func =~ /^_mcount_private/) {
-                $vfunc = sprintf("Prof      %s", $func);
-                $groups{type}{'Prof'} += $pct;
-                $groups{design}{'Prof'} += $pct;
-                $groups{module}{'Prof'} += $pct;
-            } else {
-                $vfunc = sprintf("C++       %s", $func);
-                $groups{type}{'C++'} += $pct;
-                $groups{design}{'C++'} += $pct;
-                $groups{module}{'C++'} += $pct;
-            }
-        }
-        $vfuncs{$vfunc} = $funcs{$func};
-    }
+        design = None
+        for vde in verilated_mods:
+            if verilated_mods[vde].match(func) or verilated_mods[vde].match(
+                    funcarg):
+                design = vde
+                break
+
+        vdesign = "-"
+
+        prof_match = re.search(r'__PROF__([a-zA-Z_0-9]+)__l?([0-9]+)\(', vfunc)
+        if design and prof_match:
+            linefunc = prof_match.group(1)
+            lineno = int(prof_match.group(2))
+            vfunc = "VBlock    %s:%d" % (linefunc, lineno)
+            vdesign = design
+            groups['type']["Verilog Blocks under " + design] += pct
+            groups['design'][design] += pct
+            groups['module'][linefunc] += pct
+        elif design:
+            vfunc = "VCommon   " + func
+            vdesign = design
+            groups['type']["Common code under " + design] += pct
+            groups['design'][design] += pct
+            groups['module'][design + " common code"] += pct
+        elif re.match(r'(VL_[A-Z0-9_]+|_?vl_[a-zA-Z0-9_]+|Verilated)', vfunc):
+            vfunc = "VLib      " + func
+            groups['type']['VLib'] += pct
+            groups['design']['VLib'] += pct
+            groups['module']['VLib'] += pct
+        elif re.match(r'^_mcount_private', vfunc):
+            vfunc = "Prof      " + func
+            groups['type']['Prof'] += pct
+            groups['design']['Prof'] += pct
+            groups['module']['Prof'] += pct
+        else:
+            vfunc = "C++       " + func
+            groups['type']['C++'] += pct
+            groups['design']['C++'] += pct
+            groups['module']['C++'] += pct
+
+        if vfunc not in vfuncs:
+            vfuncs[vfunc] = funcs[func]
+            vfuncs[vfunc]['design'] = vdesign
+        else:
+            vfuncs[vfunc]['pct'] += funcs[func]['pct']
+            vfuncs[vfunc]['calls'] += funcs[func]['calls']
+            vfuncs[vfunc]['sec'] += funcs[func]['sec']
+
+    for ftype in ['type', 'design', 'module']:
+        missing = 100
+        for item in groups[ftype].keys():
+            missing -= groups[ftype][item]
+        groups[ftype]["\377Unaccounted for/rounding error"] = missing
+
+        print("Overall summary by %s:" % ftype)
+        print("  %-6s  %s" % ("% time", ftype))
+        for what in sorted(groups[ftype].keys()):
+            # \377 used to establish sort order
+            pwhat = re.sub(r'^\377', '', what)
+            print("  %6.2f  %s" % (groups[ftype][what], pwhat))
+        print()
+
+    design_width = 1
+    for func in vfuncs:
+        if design_width < len(vfuncs[func]['design']):
+            design_width = len(vfuncs[func]['design'])
+
+    print("Verilog code profile:")
+    print("   These are split into three categories:")
+    print("      C++:     Time in non-Verilated C++ code")
+    print("      Prof:    Time in profile overhead")
+    print("      VBlock:  Time attributable to a block in a" +
+          " Verilog file and line")
+    print("      VCommon: Time in a Verilated module," +
+          " due to all parts of the design")
+    print("      VLib:    Time in Verilated common libraries," +
+          " called by the Verilated code")
+    print()
+
+    print("  %   cumulative   self              ")
+    print((" time   seconds   seconds      calls   %-" + str(design_width) +
+           "s  type      filename and line number") % "design")
+
+    cume = 0
+    for func in sorted(vfuncs.keys(),
+                       key=lambda f: vfuncs[f]['sec'],
+                       reverse=True):
+        cume += vfuncs[func]['sec']
+        print(("%6.2f %9.2f %8.2f %10d   %-" + str(design_width) + "s  %s") %
+              (vfuncs[func]['pct'], cume, vfuncs[func]['sec'],
+               vfuncs[func]['calls'], vfuncs[func]['design'], func))
 
 
-    foreach my $type (qw(type design module)) {
-        my $missing = 100;
-        foreach (sort (keys %{$groups{$type}})) {
-            $missing -= $groups{$type}{$_};
-        }
-        if ($missing) {
-            $groups{$type}{"\377Unaccounted for/rounding error"} = $missing;
-        }
+######################################################################
+######################################################################
 
-        print("Overall summary by $type:\n");
-        printf("  %-6s  %s\n","% time",$type);
-        foreach my $what (sort (keys %{$groups{$type}})) {
-            (my $pwhat = $what) =~ s/^\377//;  # Just used to establish sort order
-            printf("  %6.2f  %s\n", $groups{$type}{$what}, $pwhat);
-        }
-        print("\n");
-    }
-
-    print("Verilog code profile:\n");
-    print("   These are split into three categories:\n");
-    print("      C++:     Time in non-Verilated C++ code\n");
-    print("      Prof:    Time in profile overhead\n");
-    print("      VBlock:  Time attributable to a block in a Verilog file and line\n");
-    print("      VCommon: Time in a Verilated module, due to all parts of the design\n");
-    print("      VLib:    Time in Verilated common libraries, called by the Verilated code\n");
-    print("\n");
-
-    print("  %   cumulative   self              \n");
-    print(" time   seconds   seconds    calls   type      filename and line number\n");
-
-    my $cume = 0;
-    foreach my $func (sort {$vfuncs{$b}{sec} <=> $vfuncs{$a}{sec}
-                            || $a cmp $b}
-                      (keys %vfuncs)) {
-        $cume += $vfuncs{$func}{sec};
-        printf +("%6.2f %9.2f %8.2f %8d   %s\n",
-                 $vfuncs{$func}{pct},
-                 $cume, $vfuncs{$func}{sec},
-                 $vfuncs{$func}{calls},
-                 $func);
-    }
-}
-
-#######################################################################
-__END__
-
-=pod
-
-=head1 NAME
-
-verilator_profcfunc - Read gprof report created with --prof-cfuncs
-
-=head1 SYNOPSIS
-
-  verilator --prof-cfuncs ....
-  gcc ....
-  {run executable}
-  gprof
-  verilator_profcfuncs gprof.out
-
-=head1 DESCRIPTION
-
-Verilator_profcfunc reads a profile report created by gprof.  The names of
+parser = argparse.ArgumentParser(
+    allow_abbrev=False,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    description="""Read gprof report created with --prof-cfuncs""",
+    epilog=
+    """Verilator_profcfunc reads a profile report created by gprof.  The names of
 the functions are then transformed, assuming the user used Verilator's
 --prof-cfuncs, and a report printed showing the percentage of time, etc,
 in each Verilog block.
 
 For documentation see
-L<https://verilator.org/guide/latest/exe_verilator_profcfuncs.html>.
+https://verilator.org/guide/latest/exe_verilator_profcfunc.html
 
-=head1 ARGUMENT SUMMARY
-
-    <filename>  Input file (gprof.out)
-    --help      Display this help
-
-=head1 DISTRIBUTION
-
-The latest version is available from L<https://verilator.org>.
-
-Copyright 2007-2021 by Wilson Snyder. This program is free software; you
+Copyright 2002-2022 by Wilson Snyder. This program 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.
 
-SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
 
-=head1 SEE ALSO
+parser.add_argument('--debug',
+                    action='store_const',
+                    const=9,
+                    help='enable debug')
+parser.add_argument('filename', help='input gprof output to process')
 
-C<verilator>
-
-and L<https://verilator.org/guide/latest/exe_verilator_profcfuncs.html> for
-detailed documentation.
-
-=cut
+Args = parser.parse_args()
+profcfunc(Args.filename)
 
 ######################################################################
-### Local Variables:
-### compile-command: "$V4/bin/verilator_profcfunc  $V4/test_c/obj_dir/V*_03_*.tree $V4N/test_c/obj_dir/V*_03_*.tree"
-### End:
+# Local Variables:
+# compile-command: "./verilator_profcfunc ../test_regress/t/t_profcfunc.gprof"
+# End:

ci/ci-install.bash

@@ -19,6 +19,10 @@ set -x
 
 cd $(dirname "$0")/..
 
+# Avoid occasional cpan failures "Issued certificate has expired."
+export PERL_LWP_SSL_VERIFY_HOSTNAME=0
+echo "check_certificate = off" >> ~/.wgetrc
+
 fatal() {
   echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
 }
@@ -54,8 +58,12 @@ if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
 
   if [ "$CI_OS_NAME" = "linux" ]; then
     sudo apt-get update
-    sudo apt-get install libfl-dev libgoogle-perftools-dev ccache
-    if [ "$CI_RUNS_ON" = "ubuntu-20.04" ]; then
+    sudo apt-get install libfl-dev ccache
+    if [ "$CI_RUNS_ON" != "ubuntu-22.04" ]; then
+      # Some conflict of libunwind verison on 22.04, can live without it for now
+      sudo apt-get install libgoogle-perftools-dev
+    fi
+    if [ "$CI_RUNS_ON" = "ubuntu-20.04" ] || [ "$CI_RUNS_ON" = "ubuntu-22.04" ]; then
       sudo apt-get install libsystemc libsystemc-dev
     fi
     if [ "$COVERAGE" = 1 ]; then
@@ -85,7 +93,7 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
     sudo apt-get update
     # libfl-dev needed for internal coverage's test runs
     sudo apt-get install gdb gtkwave lcov libfl-dev ccache
-    if [ "$CI_RUNS_ON" = "ubuntu-20.04" ]; then
+    if [ "$CI_RUNS_ON" = "ubuntu-20.04" ] || [ "$CI_RUNS_ON" = "ubuntu-22.04" ]; then
       sudo apt-get install libsystemc-dev
     fi
     if [ "$CI_M32" = 1 ]; then

ci/docker/buildenv/Dockerfile

@@ -6,7 +6,7 @@
 # Version 2.0.
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-FROM ubuntu:20.04
+FROM ubuntu:22.04
 
 RUN apt-get update \
     && DEBIAN_FRONTEND=noninteractive \

ci/docker/buildenv/README.rst

@@ -8,7 +8,7 @@ Verilator build. It uses the following parameters:
 
 -  Source revision (default: master)
 
--  Compiler (GCC 9.3.0, clang 10.0.0, default: 9.3.0)
+-  Compiler (GCC 10.3.0, clang 10.0.0, default: 10.3.0)
 
 The container is published as ``verilator/verilator-buildenv`` on `docker
 hub

ci/docker/run/Dockerfile

@@ -6,7 +6,7 @@
 # Version 2.0.
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-FROM ubuntu:20.04
+FROM ubuntu:22.04
 
 RUN apt-get update \
     && DEBIAN_FRONTEND=noninteractive \

codecov.yml

@@ -1,6 +1,6 @@
 # DESCRIPTION: codecov.io config
 #
-# Copyright 2020-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2020-2022 by Wilson Snyder. This program 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.

configure.ac

@@ -1,20 +1,20 @@
 # DESCRIPTION: Process this file with autoconf to produce a configure script.
 #
-# Copyright 2003-2021 by Wilson Snyder. Verilator is free software; you
+# Copyright 2003-2022 by Wilson Snyder. 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.
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-#AC_INIT([Verilator],[#.### YYYY-MM-DD])
-#AC_INIT([Verilator],[#.### devel])
-AC_INIT([Verilator],[4.210 2021-07-07],
-        [https://verilator.org],
-        [verilator],[https://verilator.org])
 # When releasing, also update header of Changes file
 # and commit using "devel release" or "Version bump" message
 # Then 'make maintainer-dist'
+#AC_INIT([Verilator],[#.### YYYY-MM-DD])
+#AC_INIT([Verilator],[#.### devel])
+AC_INIT([Verilator],[5.002 2022-10-29],
+        [https://verilator.org],
+        [verilator],[https://verilator.org])
 
-AC_CONFIG_HEADER(src/config_build.h)
+AC_CONFIG_HEADERS(src/config_build.h)
 AC_CONFIG_FILES(Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake)
 
 # Version
@@ -22,6 +22,8 @@ AC_MSG_RESULT([configuring for $PACKAGE_STRING])
 PACKAGE_VERSION_NUMBER=`AS_ECHO("$PACKAGE_VERSION") | sed 's/ .*//g'`
 AC_SUBST(PACKAGE_VERSION_NUMBER)
 AC_DEFINE_UNQUOTED([PACKAGE_VERSION_NUMBER_STRING],["$PACKAGE_VERSION_NUMBER"],[Package version as a number])
+VERILATOR_VERSION_INTEGER=`AS_ECHO("$PACKAGE_VERSION") | [sed 's/\([0-9]\)\.\([0-9][0-9][0-9]\) .*/\1\2000/g']`
+AC_SUBST(VERILATOR_VERSION_INTEGER)
 
 # Ignore automake flags passed by Ubuntu builds
 AC_ARG_ENABLE([dependency-tracking],
@@ -143,10 +145,10 @@ AC_SUBST(CFG_WITH_LONGTESTS)
 AC_MSG_RESULT($CFG_WITH_LONGTESTS)
 
 # Compiler flags (ensure they are not empty to avoid configure defaults)
-CFLAGS+=" "
-CPPFLAGS+=" "
-CXXFLAGS+=" "
-LDFLAGS+=" "
+CFLAGS="$CFLAGS "
+CPPFLAGS="$CPPFLAGS "
+CXXFLAGS="$CXXFLAGS "
+LDFLAGS="$LDFLAGS "
 
 # Checks for programs.
 AC_PROG_CC
@@ -346,33 +348,23 @@ AC_SUBST(CFG_CXXFLAGS_PROFILE)
 
 # Flag to select newest language standard supported
 # Macros work such that first option that passes is the one we take
-# Currently enabled gnu++14/c++14 due to packaged SystemC dependency
-# gnu++17 is the newest that Verilator supports
-# std++03 is the oldest that Verilator supports
+# Currently enable c++17/c++14 due to packaged SystemC dependency
+# c++17 is the newest that Verilator is regularly tested to support
+# c++11 is the oldest that Verilator supports
+# gnu is requried for Cygwin to compile verilated.h successfully
 #_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++20)
-#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++17)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++14)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++11)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++03)
 #_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++20)
-#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++17)
+case "$(which lsb_release 2>&1 > /dev/null && lsb_release -d)" in
+*Arch*Linux* | *Ubuntu*22.04*)
+_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++17)
+_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++17)
+;;
+esac
+_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++14)
 _MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++14)
+_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++11)
 _MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++11)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++03)
 AC_SUBST(CFG_CXXFLAGS_STD_NEWEST)
-# And likewise oldest standard (same list above, backwards)
-# This is used for internal testing
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=c++03)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=c++11)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=c++14)
-#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=c++17)
-#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=c++20)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=gnu++03)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=gnu++11)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=gnu++14)
-#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=gnu++17)
-#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=gnu++20)
-AC_SUBST(CFG_CXXFLAGS_STD_OLDEST)
 
 # Flags for compiling Verilator internals including parser, and Verilated files
 # These turn on extra warnings and are only used with 'configure --enable-ccwarn'
@@ -382,6 +374,36 @@ _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_WEXTRA,-Wlogical-op)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_WEXTRA,-Wthread-safety)
 AC_SUBST(CFG_CXXFLAGS_WEXTRA)
 
+# Flags for coroutine support for dynamic scheduling
+_MY_CXX_CHECK_IFELSE(
+  -fcoroutines-ts,
+  [CFG_CXXFLAGS_COROUTINES="-fcoroutines-ts"],
+  [CFG_CXXFLAGS_COROUTINES="-fcoroutines"])
+AC_SUBST(CFG_CXXFLAGS_COROUTINES)
+
+# HAVE_COROUTINES
+# Check if coroutines are supported at all
+AC_MSG_CHECKING([whether coroutines are supported by $CXX])
+ACO_SAVE_CXXFLAGS="$CXXFLAGS"
+CXXFLAGS="$CXXFLAGS $CFG_CXXFLAGS_COROUTINES"
+AC_LINK_IFELSE(
+    [AC_LANG_PROGRAM([
+#ifdef __clang__
+#define __cpp_impl_coroutine 1
+#endif
+#include <coroutine>
+    ],[[]])],
+    [_my_result=yes
+     AC_DEFINE([HAVE_COROUTINES],[1],[Defined if coroutines are supported by $CXX])],
+    [AC_LINK_IFELSE(
+        [AC_LANG_PROGRAM([#include <experimental/coroutine>],[[]])],
+        [_my_result=yes
+         AC_DEFINE([HAVE_COROUTINES],[1],[Defined if coroutines are supported by $CXX])],
+        [_my_result=no])])
+AC_MSG_RESULT($_my_result)
+CXXFLAGS="$ACO_SAVE_CXXFLAGS"
+AC_SUBST(HAVE_COROUTINES)
+
 # Flags for compiling Verilator internals including parser always
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Qunused-arguments)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-faligned-new)

docs/.gitignore

@@ -2,3 +2,4 @@
 *.html
 *.pdf
 _build
+guide/spelling.txt

docs/CONTRIBUTORS

@@ -3,18 +3,25 @@ under the Developer Certificate of Origin (https://developercertificate.org/).
 
 Please see the Verilator manual for 200+ additional contributors. Thanks to all.
 
+Adrien Le Masle
 Ahmed El-Mahmoudy
+Aleksander Kiryk
 Alex Chadwick
 Àlex Torregrosa
+Aliaksei Chapyzhenka
 Ameya Vikram Singh
 Andreas Kuster
+Arkadiusz Kozdra
 Chris Randall
+Chuxuan Wang
 Conor McCullough
 Dan Petrisko
+Daniel Bates
 David Horton
 David Metz
 David Stanford
 David Turner
+Drew Ranck
 Drew Taussig
 Driss Hafdi
 Edgar E. Iglesias
@@ -26,47 +33,67 @@ Geza Lore
 Gianfranco Costamagna
 Glen Gibb
 Graham Rushton
+Guokai Chen
+Gustav Svensk
 Harald Heckmann
 Howard Su
 Huang Rui
+Huanghuang Zhou
+HungMingWu
 HyungKi Jeong
+Iru Cai
+Ivan Vnučec
 Iztok Jeras
+Jake Merdich
 James Hanlon
 James Hutchinson
 James Pallister
 Jamey Hicks
+Jamie Iles
 Jan Van Winkel
 Jean Berniolles
 Jeremy Bennett
+Jiuyang Liu
 John Coiner
 John Demme
 Jonathan Drolet
 Josh Redford
+Julie Schwartz
 Julien Margetts
 Kaleb Barrett
+Kamil Rakoczy
 Kanad Kanhere
+Keith Colbert
 Kevin Kiningham
 Krzysztof Bieganski
 Kuba Ober
+Larry Doolittle
 Ludwig Rogiers
 Lukasz Dalek
 Maarten De Braekeleer
 Maciej Sobkowski
+Marcel Chang
 Marco Widmer
+Mariusz Glebocki
 Markus Krause
 Marlon James
 Marshal Qiao
 Martin Schmidt
+Martin Stadler
 Matthew Ballance
 Michael Killough
+Michaël Lefebvre
 Mike Popoloski
 Miodrag Milanović
+Mladen Slijepcevic
 Morten Borup Petersen
+Mostafa Gamal
 Nandu Raj
 Nathan Kohagen
 Nathan Myers
 Patrick Stewart
 Paul Wright
+Pawel Sagan
 Peter Horvath
 Peter Monsson
 Philipp Wagner
@@ -75,27 +102,38 @@ Pieter Kapsenberg
 Piotr Binkowski
 Qingyao Sun
 Rafal Kapuscik
+Raynard Qiao
 Richard Myers
 Rupert Swarbrick
+Ryszard Rozak
 Samuel Riedel
 Sean Cross
 Sebastien Van Cauwenberghe
 Sergi Granell
 Stefan Wallentowitz
 Stephen Henry
+Steven Hugg
+Teng Huang
 Tim Snyder
 Tobias Rosenkranz
 Tobias Wölfel
 Todd Strader
 Tomasz Gorochowik
+Topa Topino
 Tymoteusz Blazejczyk
 Udi Finkelstein
 Unai Martinez-Corral
+Varun Koyyalagunta
 Vassilis Papaefstathiou
 Veripool API Bot
 Victor Besyakov
+William D. Jones
 Wilson Snyder
+Xi Zhang
+Yoda Lee
 Yossi Nivin
 Yuri Victorovich
 Yutetsu TAKATSUKASA
+Yu-Sheng Lin
 Yves Mathieu
+Zhanglei Wang

docs/Makefile

@@ -5,7 +5,7 @@
 #
 # Code available from: https://verilator.org
 #
-# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -35,6 +35,7 @@ default:
 # Intermediate rules
 
 vl-extract: ../bin/verilator ../Changes
+	ln -sf ../spelling.txt guide/spelling.txt
 	mkdir -p _build/gen
 	$(PYTHON3) bin/vl_sphinx_extract ../bin/verilator
 	sed 's/`/\&96;/g' < ../Changes > _build/gen/Changes
@@ -77,6 +78,7 @@ clean mostlyclean distclean maintainer-clean::
 	rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs *.idx
 	rm -f *.ev *.evs *.ov *.ovs *.cv *.cvs *.ma *.mas
 	rm -f *.tex
+	rm -f guide/spelling.txt
 
 distclean maintainer-clean::
 	rm -f *.info* *.1 *.html *.pdf $(INFOS)

docs/bin/vl_sphinx_extract

@@ -40,7 +40,7 @@ parser = argparse.ArgumentParser(
     formatter_class=argparse.RawDescriptionHelpFormatter,
     description="""Read a file and extract documentation data.""",
     epilog=
-    """ Copyright 2021-2021 by Wilson Snyder.  This package is free software;
+    """ Copyright 2021-2022 by Wilson Snyder.  This package 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.

docs/bin/vl_sphinx_fix

@@ -55,7 +55,7 @@ parser = argparse.ArgumentParser(
     formatter_class=argparse.RawDescriptionHelpFormatter,
     description="""Post-process Sphinx HTML.""",
     epilog=
-    """ Copyright 2021-2021 by Wilson Snyder.  This package is free software;
+    """ Copyright 2021-2022 by Wilson Snyder.  This package 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.

docs/gen/ex_DIDNOTCONVERGE_faulty.rst

@@ -0,0 +1,6 @@
+.. comment: generated by t_lint_didnotconverge_bad
+.. code-block:: sv
+   :linenos:
+
+      always_comb b = ~a;
+      always_comb a = b;

docs/gen/ex_DIDNOTCONVERGE_msg.rst

@@ -0,0 +1,5 @@
+.. comment: generated by t_lint_didnotconverge_bad
+.. code-block::
+
+   -V{t#,#}         'stl' region trigger index 1 is active: @([hybrid] a)
+   %Error: t/t_lint_didnotconverge_bad.v:7: Settle region did not converge.

docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_lint_didnotconverge_nodbg_bad
+.. code-block::
+
+   %Error: t/t_lint_didnotconverge_bad.v:7: Settle region did not converge.

docs/gen/ex_STMTDLY_faulty.rst

@@ -0,0 +1,5 @@
+.. comment: generated by t_lint_stmtdly_bad
+.. code-block:: sv
+   :emphasize-lines: 1
+
+         #100 $finish;  //<--- Warning

docs/gen/ex_STMTDLY_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_lint_stmtdly_bad
+.. code-block::
+
+   %Warning-STMTDLY: example.v:1:7 Ignoring delay on this statement due to --no-timing

docs/guide/changes.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ****************

docs/guide/conf.py

@@ -1,4 +1,4 @@
-# pylint: disable=C0103,C0114,C0116,E0402,W0622
+# pylint: disable=C0103,C0114,C0116,C0301,E0402,W0622
 #
 # Configuration file for Verilator's Sphinx documentation builder.
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
@@ -13,6 +13,7 @@ from datetime import datetime
 import os
 import re
 import sys
+
 sys.path.insert(0, os.path.abspath('./_ext'))
 
 import sphinx_rtd_theme  # pylint: disable=wrong-import-position,
@@ -36,7 +37,7 @@ def setup(app):
 # -- Project information
 
 project = 'Verilator'
-copyright = '2021 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
+copyright = '2022 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
 author = 'Wilson Snyder'
 
 # The master toctree document.

docs/guide/connecting.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Connecting:
@@ -86,58 +86,20 @@ Connecting to C++
 In C++ output mode (:vlopt:`--cc`), the Verilator generated model class is a
 simple C++ class.  The user must write a C++ wrapper and main loop for the
 simulation, which instantiates the model class, and link with the Verilated
-model.  Here is a simple example:
+model.
 
-.. code-block:: C++
+Refer to ``examples/make_tracing_c`` in the distribution for a detailed
+commented example.
 
-         #include <verilated.h>          // Defines common routines
-         #include <iostream>             // Need std::cout
-         #include "Vtop.h"               // From Verilating "top.v"
+Top level IO signals are read and written as members of the model.  You
+call the model's :code:`eval()` method to evaluate the model.  When the
+simulation is complete call the model's :code:`final()` method to execute
+any SystemVerilog final blocks, and complete any assertions. If using
+:vlopt:`--timing`, there are two additional functions for checking if
+there are any events pending in the simulation due to delays, and for
+retrieving the simulation time of the next delayed event. See
+:ref:`Evaluation Loop`.
 
-         Vtop *top;                      // Instantiation of model
-
-         vluint64_t main_time = 0;       // Current simulation time
-         // This is a 64-bit integer to reduce wrap over issues and
-         // allow modulus.  This is in units of the timeprecision
-         // used in Verilog (or from --timescale-override)
-
-         double sc_time_stamp() {        // Called by $time in Verilog
-             return main_time;           // converts to double, to match
-                                         // what SystemC does
-         }
-
-         int main(int argc, char** argv) {
-             Verilated::commandArgs(argc, argv);   // Remember args
-
-             top = new Vtop;             // Create model
-
-             top->reset_l = 0;           // Set some inputs
-
-             while (!Verilated::gotFinish()) {
-                 if (main_time > 10) {
-                     top->reset_l = 1;   // Deassert reset
-                 }
-                 if ((main_time % 10) == 1) {
-                     top->clk = 1;       // Toggle clock
-                 }
-                 if ((main_time % 10) == 6) {
-                     top->clk = 0;
-                 }
-                 top->eval();            // Evaluate model
-                 cout << top->out << endl;       // Read a output
-                 main_time++;            // Time passes...
-             }
-
-             top->final();               // Done simulating
-             //    // (Though this example doesn't get here)
-             delete top;
-         }
-
-
-Note top level IO signals are read and written as members of the model.  You
-call the :code:`eval()` method to evaluate the model.  When the simulation is
-complete call the :code:`final()` method to execute any SystemVerilog final
-blocks, and complete any assertions. See :ref:`Evaluation Loop`.
 
 
 Connecting to SystemC
@@ -150,7 +112,7 @@ netlist as an instantiation.
 The SC_MODULE gets the same pinout as the Verilog module, with the
 following type conversions: Pins of a single bit become bool.  Pins 2-32
 bits wide become uint32_t's.  Pins 33-64 bits wide become sc_bv's or
-vluint64_t's depending on the :vlopt:`--no-pins64` option.  Wider pins
+uint64_t's depending on the :vlopt:`--no-pins64` option.  Wider pins
 become sc_bv's.  (Uints simulate the fastest so are used where possible.)
 
 Model internals, including lower level sub-modules are not pure SystemC
@@ -200,7 +162,7 @@ DPI System Task/Functions
 -------------------------
 
 Verilator extends the DPI format to allow using the same scheme to
-efficiently add system functions.  Simply use a dollar-sign prefixed system
+efficiently add system functions.  Use a dollar-sign prefixed system
 function name for the import, but note it must be escaped.
 
 .. code-block:: sv
@@ -257,7 +219,9 @@ with respect to that top level module, then the scope could be set with
 
      #include "svdpi.h"
      ...
-     svSetScope(svGetScopeFromName("TOP.dut"));
+     const svScope scope = svGetScopeFromName("TOP.dut");
+     assert(scope);  // Check for nullptr if scope not found
+     svSetScope(scope);
 
 (Remember that Verilator adds a "TOP" to the top of the module hierarchy.)
 
@@ -422,12 +386,12 @@ accesses the above signal "readme" would be:
 
 .. code-block:: bash
 
-     cat >sim_main.cpp <<'<<EOF'
+     cat >sim_main.cpp <<'EOF'
        #include "Vour.h"
        #include "verilated.h"
        #include "verilated_vpi.h"  // Required to get definitions
 
-       vluint64_t main_time = 0;   // See comments in first example
+       uint64_t main_time = 0;   // See comments in first example
        double sc_time_stamp() { return main_time; }
 
        void read_and_check() {
@@ -444,14 +408,15 @@ accesses the above signal "readme" would be:
 
        int main(int argc, char** argv, char** env) {
            Verilated::commandArgs(argc, argv);
-           Vour* top = new Vour;
-           Verilated::internalsDump();  // See scopes to help debug
-           while (!Verilated::gotFinish()) {
+           const std::unique_ptr<VerilatedContext> contextp{new VerilatedContext};
+           const std::unique_ptr<Vour> top{new Vour{contextp.get()}};
+
+           contextp->internalsDump();  // See scopes to help debug
+           while (!contextp->gotFinish()) {
                top->eval();
                VerilatedVpi::callValueCbs();  // For signal callbacks
                read_and_check();
            }
-           delete top;
            return 0;
        }
      EOF
@@ -478,10 +443,25 @@ there is only a single design, you would call :code:`eval_step()` then
 :code:`eval_end_step()`; in fact :code:`eval()` 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:
+
+   * :code:`designp->eventsPending()`, which returns :code:`true` if there are
+     any delayed events pending,
+   * :code:`designp->nextTimeSlot()`, which returns the simulation time of the
+     next delayed event. This method can only be called if
+     :code:`designp->nextTimeSlot()` returned :code:`true`.
+
+Call :code:`eventsPending()` to check if you should continue with the
+simulation, and then :code:`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.
+
 When :code:`eval()` (or :code:`eval_step()`) is called Verilator looks for
 changes in clock signals and evaluates related sequential always blocks,
-such as computing always_ff @ (posedge...) outputs.  Then Verilator
-evaluates combinatorial logic.
+such as computing always_ff @ (posedge...) outputs. With :vlopt:`--timing`, it
+resumes any delayed processes awaiting the current simulation time. Then
+Verilator evaluates combinational logic.
 
 Note combinatorial logic is not computed before sequential always blocks
 are computed (for speed reasons). Therefore it is best to set any non-clock
@@ -506,7 +486,7 @@ structure.  If a ``VerilatedContext`` is not created prior to creating a
 model, a default global one is created automatically.
 
 The ``Verilated::`` methods, including the ``Verilated::commandArgs`` call
-shown above, simply call VerilatedContext methods using the default global
+shown above, call VerilatedContext methods using the default global
 VerilatedContext.  (Technically they operate on the last one used by a
 given thread.)  If you are using multiple simulation contexts you should
 not use the Verilated:: methods, and instead always use VerilatedContext

docs/guide/contributing.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 *******************************

docs/guide/contributors.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ************************
@@ -13,7 +13,8 @@ When possible, please instead report bugs at `Verilator Issues
 
 Primary author is Wilson Snyder <[email protected]>.
 
-Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
+Major concepts by Paul Wasson, Duane Galbi, John Coiner, Geza Lore, Yutetsu
+Takatsukasa, and Jie Xu.
 
 
 Contributors
@@ -22,99 +23,111 @@ Contributors
 Many people have provided ideas and other assistance with Verilator.
 
 Verilator is receiving major development support from the `CHIPS Alliance
-<https://chipsalliance.org>`_.
+<https://chipsalliance.org>`_, `Antmicro Ltd <https://antmicro.com>`_ and
+`Shunyao CAD <https://shunyaocad.com>`_.
 
 Previous major corporate sponsors of Verilator, by providing significant
 contributions of time or funds included include: Atmel Corporation, Cavium
 Inc., Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd.,
 Hicamp Systems, Intel Corporation, Mindspeed Technologies Inc., MicroTune
 Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus Networks Inc.,
-and SiCortex Inc.
+SiCortex Inc, and Shunyao CAD.
 
-The people who have contributed major functionality are: Byron Bradley,
-Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Geza Lore, Todd
-Strader, Stefan Wallentowitz, Paul Wasson, Jie Xu, and Wilson Snyder.
-Major testers included Jeff Dutton, Jonathon Donaldson, Ralf Karge, David
-Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov, Sebastien Van
-Cauwenberghe, Gene Weber, and Clifford Wolf.
+The people who have contributed major functionality are: Krzysztof
+Bieganski, Byron Bradley, Jeremy Bennett, Lane Brooks, John Coiner, Duane
+Galbi, Geza Lore, Todd Strader, Stefan Wallentowitz, Paul Wasson, Jie Xu,
+and Wilson Snyder.  Major testers included Jeff Dutton, Jonathon Donaldson,
+Ralf Karge, David Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov,
+Sebastien Van Cauwenberghe, Gene Weber, and Clifford Wolf.
 
 Some of the people who have provided ideas, and feedback for Verilator
-include: David Addison, Nikana Anastasiadis, Vasu Arasanipalai, Jens Arm,
-Tariq B. Ahmad, Sharad Bagri, Matthew Ballance, Andrew Bardsley, Matthew
-Barr, Geoff Barrett, Kaleb Barrett, Julius Baxter, Jeremy Bennett, Michael
-Berman, Jean Berniolles, Victor Besyakov, Moinak Bhattacharyya, Krzysztof
-Bieganski, David Binderman, Piotr Binkowski, Johan Bjork, David Black,
-Tymoteusz Blazejczyk, Daniel Bone, Morten Borup Petersen, Gregg Bouchard,
-Christopher Boumenot, Nick Bowler, Byron Bradley, Bryan Brady, Charlie
-Brej, J Briquet, Lane Brooks, John Brownlee, Jeff Bush, Lawrence Butcher,
-Tony Bybell, Iru Cai, Ted Campbell, Chris Candler, Lauren Carlson, Donal
-Casey, Alex Chadwick, Terry Chen, Yi-Chung Chen, Enzo Chi, Robert A. Clark,
-Ryan Clarke, Allan Cochrane, John Coiner, Gianfranco Costamagna, Sean
-Cross, George Cuan, Joe DErrico, Lukasz Dalek, Gunter Dannoritzer, Ashutosh
-Das, Maarten De Braekeleer, Bernard Deadman, Alberto Del Rio, John Demme,
-Mike Denio, John Deroo, Philip Derrick, John Dickol, Ruben Diez, Danny
-Ding, Jacko Dirks, Ivan Djordjevic, Jonathon Donaldson, Sebastian Dressler,
-Alex Duller, Jeff Dutton, Tomas Dzetkulic, Richard E George, Edgar
-E. Iglesias, Usuario Eda, Charles Eddleston, Chandan Egbert, Jan Egil Ruud,
-Joe Eiler, Ahmed El-Mahmoudy, Trevor Elbourne, Mats Engstrom, Charles Eric
-LaForest, Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Udi Finkelstein,
-Brian Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi, Benjamin Gartner,
-Christian Gelinek, Peter Gerst, Glen Gibb, Michael Gielda, Barbara Gigerl,
-Shankar Giri, Dan Gisselquist, Petr Gladkikh, Sam Gladstone, Andrew
-Goessling, Amir Gonnen, Chitlesh Goorah, Tomasz Gorochowik, Kai Gossner,
-Sergi Granell, Al Grant, Alexander Grobman, Xuan Guo, Driss Hafdi, Neil
+include:
+
+David Addison, Tariq B. Ahmad, Nikana Anastasiadis, Vasu Arasanipalai, Jens
+Arm, Sharad Bagri, Matthew Ballance, Andrew Bardsley, Matthew Barr, Geoff
+Barrett, Kaleb Barrett, Julius Baxter, Jeremy Bennett, Michael Berman, Jean
+Berniolles, Victor Besyakov, Moinak Bhattacharyya, Krzysztof Bieganski,
+David Binderman, Piotr Binkowski, Johan Bjork, David Black, Tymoteusz
+Blazejczyk, Daniel Bone, Gregg Bouchard, Christopher Boumenot, Nick Bowler,
+Byron Bradley, Bryan Brady, Maarten De Braekeleer, Charlie Brej, J Briquet,
+Lane Brooks, John Brownlee, Jeff Bush, Lawrence Butcher, Tony Bybell, Iru
+Cai, Ted Campbell, Chris Candler, Lauren Carlson, Donal Casey, Alex
+Chadwick, Marcel Chang, Aliaksei Chapyzhenka, Guokai Chen, Terry Chen,
+Yi-Chung Chen, Enzo Chi, Robert A. Clark, Ryan Clarke, Allan Cochrane, John
+Coiner, Keith Colbert, Gianfranco Costamagna, Sean Cross, George Cuan, Joe
+DErrico, Lukasz Dalek, Gunter Dannoritzer, Ashutosh Das, Bernard Deadman,
+John Demme, Mike Denio, John Deroo, Philip Derrick, John Dickol, Ruben
+Diez, Danny Ding, Jacko Dirks, Ivan Djordjevic, Jonathon Donaldson, Larry
+Doolittle, Sebastian Dressler, Jonathan Drolet, Alex Duller, Jeff Dutton,
+Tomas Dzetkulic, Usuario Eda, Charles Eddleston, Chandan Egbert, Joe Eiler,
+Ahmed El-Mahmoudy, Trevor Elbourne, Mats Engstrom, Robert Farrell, Eugen
+Fekete, Fabrizio Ferrandi, Udi Finkelstein, Brian Flachs, Bill Flynn,
+Andrea Foletto, Bob Fredieu, Duane Galbi, Mostafa Gamal, Benjamin Gartner,
+Christian Gelinek, Richard E George, Peter Gerst, Glen Gibb, Michael
+Gielda, Barbara Gigerl, Shankar Giri, Dan Gisselquist, Petr Gladkikh, Sam
+Gladstone, Mariusz Glebocki, Andrew Goessling, Amir Gonnen, Chitlesh
+Goorah, Tomasz Gorochowik, Kai Gossner, Sergi Granell, Al Grant, Nathan
+Graybeal, Alexander Grobman, Graham Rushton, Xuan Guo, Driss Hafdi, Neil
 Hamilton, James Hanlon, Oyvind Harboe, Jannis Harder, Junji Hashimoto,
 Thomas Hawkins, Mitch Hayenga, Harald Heckmann, Robert Henry, Stephen
 Henry, David Hewson, Jamey Hicks, Joel Holdsworth, Andrew Holme, Hiroki
 Honda, Alex Hornung, Pierre-Henri Horrein, David Horton, Peter Horvath, Jae
-Hossell, Kuoping Hsu, Alan Hunter, James Hutchinson, Anderson Ignacio da
-Silva, Jamie Iles, Thomas J Whatson, Ben Jackson, Mark Jackson Pulver,
-Shareef Jalloq, Marlon James, Krzysztof Jankowski, HyungKi Jeong, Iztok
-Jeras, James Johnson, Christophe Joly, Franck Jullien, James Jung, Mike
-Kagen, Arthur Kahlich, Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi,
-Kanad Kanhere, Patricio Kaplan, Pieter Kapsenberg, Rafal Kapuscik, Ralf
-Karge, Dan Katz, Sol Katzman, Ian Kennedy, Michael Killough, Jonathan
-Kimmitt, Olof Kindgren, Kevin Kiningham, Dan Kirkham, Sobhan Klnv, Gernot
-Koch, Jack Koenig, Soon Koh, Nathan Kohagen, Steve Kolecki, Brett Koonce,
-Will Korteland, Wojciech Koszek, Varun Koyyalagunta, Markus Krause, David
-Kravitz, Roland Kruse, Andreas Kuster, Sergey Kvachonok, Ed Lander, Steve
-Lang, Stephane Laurent, Walter Lavino, Christian Leber, Larry Lee, Igor
-Lesik, John Li, Eivind Liland, Charlie Lind, Andrew Ling, Jiuyang Liu, Paul
-Liu, Derek Lockhart, Jake Longo, Geza Lore, Arthur Low, Stefan Ludwig, Dan
-Lussier, Fred Ma, Duraid Madina, Odd Magne Reitan, Affe Mao, Julien
-Margetts, Mark Marshall, Alfonso Martinez, Unai Martinez-Corral, Yves
-Mathieu, Patrick Maupin, Conor McCullough, Jason McMullan, Elliot Mednick,
-Wim Michiels, Miodrag Milanovic, Peter Monsson, Sean Moore, Dennis
-Muhlestein, John Murphy, Matt Myers, Nathan Myers, Richard Myers, Dimitris
-Nalbantis, Peter Nelson, Bob Newgard, Paul Nitza, Yossi Nivin, Pete Nixon,
-Lisa Noack, Mark Nodine, Kuba Ober, Andreas Olofsson, Baltazar Ortiz,
-Aleksander Osman, Don Owen, James Pallister, Vassilis Papaefstathiou, Brad
-Parker, Dan Petrisko, Maciej Piechotka, David Pierce, Cody Piersall,
-Dominic Plunkett, David Poole, Mike Popoloski, Roman Popov, Rich Porter,
-Niranjan Prabhu, Usha Priyadharshini, Prateek Puri, Marshal Qiao, Nandu
-Raj, Danilo Ramos, Chris Randall, Anton Rapp, Josh Redford, Frederic
-Requin, Dustin Richmond, Samuel Riedel, Eric Rippey, Oleg Rodionov, Ludwig
-Rogiers, Paul Rolfe, Arjen Roodselaar, Tobias Rosenkranz, Huang Rui, Denis
-Rystsov, John Sanguinetti, Galen Seitz, Joseph Shaker, Salman Sheikh, Yu
-Sheng Lin, Hao Shi, Mike Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Fan
-Shupei, Rodney Sinclair, Steven Slatter, Brian Small, Garrett Smith, Tim
-Snyder, Wilson Snyder, Maciej Sobkowski, Stan Sokorac, Alex Solomatnikov,
-Wei Song, Art Stamness, David Stanford, John Stevenson, Pete Stevenson,
-Patrick Stewart, Rob Stoddard, Todd Strader, John Stroebel, Sven Stucki,
-Howard Su, Emerson Suguimoto, Gene Sullivan, Wai Sum Mong, Qingyao Sun,
-Renga Sundararajan, Rupert Swarbrick, Yutetsu Takatsukasa, Thierry Tambe,
-Drew Taussig, Peter Tengstrand, Wesley Terpstra, Rui Terra, Stefan Thiede,
-Gary Thomas, Ian Thompson, Kevin Thompson, Mike Thyer, Hans Tichelaar,
-Viktor Tomov, Steve Tong, Alex Torregrosa, Michael Tresidder, David Turner,
-Neil Turton, Cong Van Nguyen, Hans Van Antwerpen, Jan Van Winkel, Sebastien
-Van Cauwenberghe, Laurens van Dam, Leendert van Doorn, Srini Vemuri, Yuri
+Hossell, Kuoping Hsu, Teng Huang, Steven Hugg, Alan Hunter, James
+Hutchinson, Ehab Ibrahim, Edgar E. Iglesias, Jamie Iles, Vighnesh Iyer, Ben
+Jackson, Shareef Jalloq, Marlon James, Krzysztof Jankowski, HyungKi Jeong,
+Iztok Jeras, Alexandre Joannou, James Johnson, Christophe Joly, Franck
+Jullien, James Jung, Mike Kagen, Arthur Kahlich, Kaalia Kahn, Guy-Armand
+Kamendje, Vasu Kandadi, Kanad Kanhere, Patricio Kaplan, Pieter Kapsenberg,
+Rafal Kapuscik, Ralf Karge, Per Karlsson, Dan Katz, Sol Katzman, Ian
+Kennedy, Michael Killough, Sun Kim, Jonathan Kimmitt, Olof Kindgren, Kevin
+Kiningham, Dan Kirkham, Aleksander Kiryk, Sobhan Klnv, Gernot Koch, Jack
+Koenig, Soon Koh, Nathan Kohagen, Steve Kolecki, Brett Koonce, Will
+Korteland, Wojciech Koszek, Varun Koyyalagunta, Arkadiusz Kozdra, Markus
+Krause, David Kravitz, Roland Kruse, Andreas Kuster, Sergey Kvachonok,
+Charles Eric LaForest, Ed Lander, Steve Lang, Stephane Laurent, Walter
+Lavino, Christian Leber, Larry Lee, Yoda Lee, Michaël Lefebvre, Igor Lesik,
+John Li, Eivind Liland, Yu Sheng Lin, Charlie Lind, Andrew Ling, Jiuyang
+Liu, Paul Liu, Derek Lockhart, Jake Longo, Geza Lore, Arthur Low, Stefan
+Ludwig, Dan Lussier, Fred Ma, Duraid Madina, Affe Mao, Julien Margetts,
+Mark Marshall, Alfonso Martinez, Unai Martinez-Corral, Adrien Le Masle,
+Yves Mathieu, Patrick Maupin, Conor McCullough, Jason McMullan, Elliot
+Mednick, David Metz, Wim Michiels, Miodrag Milanovic, Kevin Millis, Wai Sum
+Mong, Peter Monsson, Sean Moore, Dennis Muhlestein, John Murphy, Matt
+Myers, Nathan Myers, Richard Myers, Dimitris Nalbantis, Peter Nelson, Bob
+Newgard, Rachit Nigam, Paul Nitza, Yossi Nivin, Pete Nixon, Lisa Noack,
+Mark Nodine, Kuba Ober, Andreas Olofsson, Baltazar Ortiz, Aleksander Osman,
+Don Owen, James Pallister, Vassilis Papaefstathiou, Brad Parker, Morten
+Borup Petersen, Dan Petrisko, Maciej Piechotka, David Pierce, Cody
+Piersall, Michael Platzer, Dominic Plunkett, David Poole, Mike Popoloski,
+Roman Popov, Rich Porter, Stefan Post, Niranjan Prabhu, Damien Pretet, Usha
+Priyadharshini, Mark Jackson Pulver, Prateek Puri, Marshal Qiao, Nandu Raj,
+Kamil Rakoczy, Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh
+Redford, Odd Magne Reitan, Frederic Requin, Dustin Richmond, Samuel Riedel,
+Alberto Del Rio, Eric Rippey, Oleg Rodionov, Ludwig Rogiers, Paul Rolfe,
+Arjen Roodselaar, Tobias Rosenkranz, Ryszard Rozak, Huang Rui, Graham
+Rushton, Jan Egil Ruud, Denis Rystsov, John Sanguinetti, Martin Schmidt,
+Julie Schwartz, Galen Seitz, Joseph Shaker, Salman Sheikh, Hao Shi, Mike
+Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Fan Shupei, Anderson Ignacio
+da Silva, Rodney Sinclair, Ameya Vikram Singh, Steven Slatter, Mladen
+Slijepcevic, Brian Small, Garrett Smith, Tim Snyder, Wilson Snyder, Maciej
+Sobkowski, Stan Sokorac, Alex Solomatnikov, Flavien Solt, Wei Song, Trefor
+Southwell, Martin Stadler, Art Stamness, David Stanford, John Stevenson,
+Pete Stevenson, Patrick Stewart, Rob Stoddard, Todd Strader, John Stroebel,
+Sven Stucki, Howard Su, Emerson Suguimoto, Gene Sullivan, Qingyao Sun,
+Renga Sundararajan, Gustav Svensk, Rupert Swarbrick, Yutetsu Takatsukasa,
+Thierry Tambe, Drew Taussig, Jose Tejada, Peter Tengstrand, Wesley
+Terpstra, Rui Terra, Stefan Thiede, Gary Thomas, Ian Thompson, Kevin
+Thompson, Mike Thyer, Hans Tichelaar, Viktor Tomov, Steve Tong, Topa
+Topino, Alex Torregrosa, Michael Tresidder, David Turner, Neil Turton, Mike
+Urbach, Hans Van Antwerpen, Sebastien Van Cauwenberghe, Laurens van Dam,
+Leendert van Doorn, Cong Van Nguyen, Jan Van Winkel, Srini Vemuri, Yuri
 Victorovich, Bogdan Vukobratovic, Holger Waechtler, Philipp Wagner, Stefan
-Wallentowitz, Shawn Wang, Paul Wasson, Greg Waters, Thomas Watts, Eugene
-Weber, David Welch, Martin Whitaker, Marco Widmer, Leon Wildman, Daniel
-Wilkerson, Gerald Williams, Trevor Williams, Jeff Winston, Joshua Wise,
-Clifford Wolf, Tobias Wolfel, Johan Wouters, Paul Wright, Junyi Xi, Ding
-Xiaoliang, Jie Xu, Mandy Xu, Yinan Xu, Luke Yang, Amir Yazdanbakhsh, and
-Keyi Zhang.
+Wallentowitz, Shawn Wang, Zhanglei Wang, Paul Wasson, Greg Waters, Thomas
+Watts, Eugene Weber, David Welch, Thomas J Whatson, Martin Whitaker, Marco
+Widmer, Leon Wildman, Daniel Wilkerson, Gerald Williams, Trevor Williams,
+Jeff Winston, Joshua Wise, Clifford Wolf, Tobias Wolfel, Johan Wouters,
+Paul Wright, Junyi Xi, Ding Xiaoliang, Jie Xu, Mandy Xu, Yinan Xu, Luke
+Yang, Amir Yazdanbakhsh, Keyi Zhang, and Xi Zhang.
 
 Thanks to them, and all those we've missed including above, or wished to
 remain anonymous.
@@ -150,6 +163,10 @@ In 2018, Verilator 4.000 was released with multithreaded support.
 In 2019, Verilator joined the `CHIPS Alliance
 <https://chipsalliance.org>`_.
 
+In 2022, Verilator 5.000 was released with IEEE scheduling semantics,
+fork/join, delay handling, DFG performance optimizations, and other
+improvements.
+
 Currently, various language features and performance enhancements are added
-as the need arises.  Verilator is now about 3x faster than in 2002, and is
-faster than most (if not every) other simulator.
+as the need arises, with a focus towards getting to full Universal
+Verification Methodology (UVM, IEEE 1800.2-2017) support.

docs/guide/copyright.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 *********
@@ -8,7 +8,7 @@ Copyright
 The latest version of Verilator is available from `https://verilator.org
 <https://verilator.org>`_.
 
-Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+Copyright 2003-2022 by Wilson Snyder. This program is free software; you
 can redistribute it and/or modify the Verilator internals under the terms
 of either the GNU Lesser General Public License Version 3 or the Perl
 Artistic License Version 2.0.

docs/guide/deprecations.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 Deprecations
@@ -7,14 +7,37 @@ Deprecations
 The following deprecated items are scheduled for future removal:
 
 C++11 compiler support
-  Verilator currently requires C++11 or newer compilers.  Verilator will
-  require C++14 or newer compilers for both compiling Verilator and
-  compiling Verilated models no sooner than January 2022.
+  Verilator currently requires a C++20 or newer compiler for timing, and a
+  C++11 or newer compiler for no-timing.
 
-Configuration File -msg
-  The :vlopt:`lint_off` "-msg" option has been replaced with the "-rule"
-  option.  "-msg" is planned for removal no sooner than January 2021.
+  Verilator will require C++14 or newer compilers for both compiling
+  Verilator and compiling Verilated models with --no-timing no sooner than
+  January 2023.
 
-XML locations
-  The XML "fl" attribute has been replaced with the "loc" attribute.  "fl"
-  is planned for removal no sooner than January 2021.
+  Verilator will require C++20 or newer compilers for both compiling
+  Verilator and compiling all Verilated models no sooner than January 2025.
+
+Verilated_heavy.h
+  The legacy "verilated_heavy.h" include was replaced with just including
+  "verilated.h". Verilated_heavy.h is planned for removal no sooner than
+  July 2022.
+
+Option `--cdc`
+  The experimental `--cdc` option is believed to be generally unused and is
+  planned for removal no sooner than January 2023.
+
+Option `-O<letter>`
+  The debug `-O<letter>` options have been replaced with
+  `-fno-<optimization>` debug options to match GCC. The old options are
+  planned for removal no sooner than June 2023.
+
+Option `--prof-threads`
+  The `--prof-threads` option has been superseded by the `--prof-exec` and
+  `--prof-pgo` options and is planned for removal no sooner than April 2023.
+
+Verilated model options `+verilator+prof+threads+*`
+  The `+verilator+prof+threads+start`, `+verilator+prof+threads+window` and
+  `+verilator+prof+threads+file` options have been superseded by the
+  `+verilator+prof+exec+start`, `+verilator+prof+exec+window` and
+  `+verilator+prof+exec+file` options respectively and are planned for removal
+  no sooner than April 2023.

docs/guide/environment.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 Environment

docs/guide/example_binary.rst

@@ -0,0 +1,63 @@
+.. Copyright 2003-2022 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Example Create-Binary Execution:
+
+Example Create-Binary Execution
+===============================
+
+We'll compile this SystemVerilog example into a Verilated simulation binary.  For
+an example that discusses the next level of detail see :ref:`Example C++
+Execution`.
+
+.. include:: example_common_install.rst
+
+Now, let's create an example Verilog file:
+
+.. code-block:: bash
+
+     mkdir test_our
+     cd test_our
+
+     cat >our.v <<'EOF'
+       module our;
+          initial begin $display("Hello World"); $finish; end
+       endmodule
+     EOF
+
+Now we run Verilator on our little example.
+
+.. code-block:: bash
+
+     verilator --binary -j 0 -Wall our.v
+
+Breaking this command down:
+
+#. :vlopt:`--binary` telling Verilator to do everything needed to create a
+   simulation executable.
+
+#. :vlopt:`-j` `0` 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 now we run it:
+
+.. code-block:: bash
+
+     obj_dir/Vour
+
+And we get as output:
+
+.. code-block:: bash
+
+     Hello World
+     - our.v:2: Verilog $finish
+
+Really, you're better off using a Makefile to run the steps for you so when
+your source changes it will automatically run all of the appropriate steps.
+To aid this Verilator can create a makefile dependency file.  For examples
+that do this see the :file:`examples` directory in the distribution.

docs/guide/example_cc.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Example C++ Execution:
@@ -43,13 +43,10 @@ Now we run Verilator on our little example.
 
 .. code-block:: bash
 
-     verilator -Wall --cc --exe --build sim_main.cpp our.v
+     verilator --cc --exe --build -j 0 -Wall sim_main.cpp our.v
 
 Breaking this command down:
 
-#. :vlopt:`-Wall` so Verilator has stronger lint warnings
-   enabled.
-
 #. :vlopt:`--cc` to get C++ output (versus e.g. SystemC
    or only linting).
 
@@ -61,6 +58,12 @@ 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:`-Wall` so Verilator has stronger lint warnings
+   enabled.
+
 #. An finally, :command:`our.v` which is our SystemVerilog design file.
 
 Once Verilator completes we can see the generated C++ code under the

docs/guide/example_common_install.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 First you need Verilator installed, see :ref:`Installation`. In brief, if

docs/guide/example_dist.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Examples in the Distribution:
@@ -10,6 +10,8 @@ See the ``examples/`` directory that is part of the distribution, and
 is installed (in a OS-specific place, often in e.g.
 ``/usr/local/share/verilator/examples``).  These examples include:
 
+examples/make_hello_binary
+   Example GNU-make simple Verilog->binary conversion
 examples/make_hello_c
    Example GNU-make simple Verilog->C++ conversion
 examples/make_hello_sc

docs/guide/example_sc.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Example SystemC Execution:
@@ -43,7 +43,7 @@ Now we run Verilator on our little example:
 
 .. code-block:: bash
 
-     verilator -Wall --sc --exe sc_main.cpp our.v
+     verilator --sc --exe -Wall sc_main.cpp our.v
 
 This example does not use --build, therefore we need to explicitly compile
 it:

docs/guide/examples.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Examples:
@@ -17,6 +17,7 @@ This section covers the following examples:
    :maxdepth: 1
    :hidden:
 
+   example_binary.rst
    example_cc.rst
    example_sc.rst
    example_dist.rst

docs/guide/exe_sim.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Simulation Runtime Arguments:
@@ -8,7 +8,7 @@ Simulation Runtime Arguments
 
 The following are the arguments that may be passed to a Verilated
 executable, provided that executable calls
-:code:`Verilated::commandArgs()`.
+:code:`VerilatedContext*->commandArgs(argc, argv)`.
 
 All simulation runtime arguments begin with "+verilator", so that the
 user's executable may skip over all "+verilator" arguments when parsing its
@@ -38,30 +38,48 @@ Summary:
 
    Display help and exit.
 
-.. option:: +verilator+prof+threads+file+<filename>
+.. option:: +verilator+prof+exec+file+<filename>
 
-   When a model was Verilated using :vlopt:`--prof-threads`, sets the
+   When a model was Verilated using :vlopt:`--prof-exec`, sets the
    simulation runtime filename to dump to.  Defaults to
-   :file:`profile_threads.dat`.
+   :file:`profile_exec.dat`.
 
-.. option:: +verilator+prof+threads+start+<value>
+.. option:: +verilator+prof+exec+start+<value>
 
-   When a model was Verilated using :vlopt:`--prof-threads`, the simulation
+   When a model was Verilated using :vlopt:`--prof-exec`, the simulation
    runtime will wait until $time is at this value (expressed in units of
    the time precision), then start the profiling warmup, then
    capturing. Generally this should be set to some time that is well within
    the normal operation of the simulation, i.e. outside of reset. If 0, the
    dump is disabled. Defaults to 1.
 
-.. option:: +verilator+prof+threads+window+<value>
+.. option:: +verilator+prof+exec+window+<value>
 
-   When a model was Verilated using :vlopt:`--prof-threads`, after $time
-   reaches :vlopt:`+verilator+prof+threads+start+\<value\>`, Verilator will
+   When a model was Verilated using :vlopt:`--prof-exec`, after $time
+   reaches :vlopt:`+verilator+prof+exec+start+\<value\>`, Verilator will
    warm up the profiling for this number of eval() calls, then will capture
    the profiling of this number of eval() calls.  Defaults to 2, which
    makes sense for a single-clock-domain module where it's typical to want
    to capture one posedge eval() and one negedge eval().
 
+.. option:: +verilator+prof+threads+file+<filename>
+
+   Deprecated. Alias for :vlopt:`+verilator+prof+exec+file+\<filename\>`
+
+.. option:: +verilator+prof+threads+start+<value>
+
+   Deprecated. Alias for :vlopt:`+verilator+prof+exec+start+\<value\>`
+
+.. option:: +verilator+prof+threads+window+<value>
+
+   Deprecated. Alias for :vlopt:`+verilator+prof+exec+window+\<value\>`
+
+.. option:: +verilator+prof+vlt+file+<filename>
+
+   When a model was Verilated using :vlopt:`--prof-pgo`, sets the
+   profile-guided optimization data runtime filename to dump to.  Defaults
+   to :file:`profile.vlt`.
+
 .. option:: +verilator+rand+reset+<value>
 
    When a model was Verilated using :vlopt:`--x-initial unique
@@ -78,7 +96,7 @@ Summary:
 .. option:: +verilator+noassert
 
    Disable assert checking per runtime argument. This is the same as
-   calling :code:`Verilated::assertOn(false)` in the model.
+   calling :code:`VerilatedContext*->assertOn(false)` in the model.
 
 .. option:: +verilator+V
 

docs/guide/exe_verilator.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 verilator Arguments
@@ -99,10 +99,10 @@ Summary:
 .. option:: --bbox-sys
 
    Black box any unknown $system task or function calls.  System tasks will
-   simply become no-operations, and system functions will be replaced with
-   unsized zero.  Arguments to such functions will be parsed, but not
-   otherwise checked.  This prevents errors when linting in the presence of
-   company specific PLI calls.
+   become no-operations, and system functions will be replaced with unsized
+   zero.  Arguments to such functions will be parsed, but not otherwise
+   checked.  This prevents errors when linting in the presence of company
+   specific PLI calls.
 
    Using this argument will likely cause incorrect simulation.
 
@@ -115,12 +115,12 @@ Summary:
 
    Using this argument will likely cause incorrect simulation.
 
-.. option:: --bin <filename>
+.. option:: --binary
 
-   Rarely needed.  Override the default filename for Verilator itself.
-   When a dependency (.d) file is created, this filename will become a
-   source dependency, such that a change in this binary will have make
-   rebuild the output files.
+   Create a Verilated simulator binary.  Alias for :vlopt:`--main`
+   :vlopt:`--exe` :vlopt:`--build` :vlopt:`--timing`.
+
+   See also :vlopt:`-j`.
 
 .. option:: --build
 
@@ -129,15 +129,23 @@ Summary:
    is also used). Verilator manages the build itself, and for this --build
    requires GNU Make to be available on the platform.
 
-.. option:: -CFLAGS <flags>
+.. option:: --build-dep-bin <filename>
 
-   Add specified C compiler argument to the generated makefiles. For
-   multiple flags either pass them as a single argument with space
-   separators quoted in the shell (:command:`-CFLAGS "-a -b"`), or use
-   multiple -CFLAGS options (:command:`-CFLAGS -a -CFLAGS -b`).
+   Rarely needed.  When a dependency (.d) file is created, this filename
+   will become a source dependency, such that a change in this binary will
+   have make rebuild the output files.  Defaults to the full path to the
+   Verilator binary.
 
-   When make is run on the generated makefile these will be passed to the
-   C++ compiler (g++/clang++/msvc++).
+   This option was named `--bin` prior to version 4.228.
+
+.. option:: --build-jobs [<value>]
+
+   Specify the level of parallelism for :vlopt:`--build`. If zero, uses the
+   number of threads in the current hardware. Otherwise, the <value> must
+   be a positive integer specifying the maximum number of parallel build
+   jobs.
+
+   See also :vlopt:`-j`.
 
 .. option:: --cc
 
@@ -156,43 +164,40 @@ Summary:
    have interest in adding more traditional CDC checks, please contact the
    authors.
 
+.. option:: -CFLAGS <flags>
+
+   Add specified C compiler argument to the generated makefiles. For
+   multiple flags either pass them as a single argument with space
+   separators quoted in the shell (:command:`-CFLAGS "-a -b"`), or use
+   multiple -CFLAGS options (:command:`-CFLAGS -a -CFLAGS -b`).
+
+   When make is run on the generated makefile these will be passed to the
+   C++ compiler (g++/clang++/msvc++).
+
 .. option:: --clk <signal-name>
 
-   Sometimes it is quite difficult for Verilator to distinguish clock
-   signals from other data signals. Occasionally the clock signals can end
-   up in the checking list of signals which determines if further
-   evaluation is needed. This will heavily degrade the performance of a
-   Verilated model.
+   With :vlopt:`--clk`, the specified signal is marked as a clock signal.
 
-   With :vlopt:`--clk`, the specified signal-name is taken as a root clock
-   into the model, then Verilator will mark the signal as clocker and
-   propagate the clocker attribute automatically to other signals derived
-   from that. In this way, Verilator will try to avoid taking the clocker
-   signal into checking list.
-
-   Note signal-name is specified by the RTL hierarchy path. For example,
-   v.foo.bar.  If the signal is the input to top-module, the directly the
-   signal name. If you find it difficult to find the exact name, try to use
-   a :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the
+   The provided signal-name is specified using a RTL hierarchy path. For
+   example, v.foo.bar.  If the signal is the input to top-module, then
+   directly provide the signal name. Alternatively, use a
+   :option:`/*verilator&32;clocker*/` metacomment in RTL file to mark the
    signal directly.
 
-   If clock signals are assigned to vectors and then later used
-   individually, Verilator will attempt to decompose the vector and connect
-   the single-bit clock signals directly.  This should be transparent to
-   the user.
+   If clock signals are assigned to vectors and then later used as
+   individual bits, Verilator will attempt to decompose the vector and
+   connect the single-bit clock signals.
 
-.. option:: --make <build-tool>
+   In versions prior to 5.000, the clocker attribute is useful in cases where
+   Verilator does not properly distinguish clock signals from other data
+   signals. Using clocker will cause the signal indicated to be considered a
+   clock, and remove it from the combinatorial logic reevaluation checking
+   code. This may greatly improve performance.
 
-   Generates a script for the specified build tool.
+.. option:: --no-clk <signal-name>
 
-   Supported values are ``gmake`` for GNU Make and ``cmake`` for CMake.
-   Both can be specified together.  If no build tool is specified, gmake is
-   assumed.  The executable of gmake can be configured via environment
-   variable "MAKE".
-
-   When using :vlopt:`--build` Verilator takes over the responsibility of
-   building the model library/executable.  For this reason :option:`--make`
-   cannot be specified when using :vlopt:`--build`.
+   Prevent the specified signal from being marked as clock. See
+   :vlopt:`--clk`.
 
 .. option:: --compiler <compiler-name>
 
@@ -265,8 +270,8 @@ 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:`--dump-treei 3
-     <--dump-treei>`).
+   * 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
@@ -303,6 +308,13 @@ Summary:
    <--debugi>`). Higher levels produce more detailed messages.  See
    :vlopt:`--debug` for other implications of enabling debug.
 
+.. option:: --no-decoration
+
+   When creating output Verilated code, minimize comments, white space,
+   symbol names and other decorative items, at the cost of greatly reduced
+   readability. This may assist C++ compile times. This will not typically
+   change the ultimate model's performance, but may in some cases.
+
 .. option:: --default-language <value>
 
    Select the language to be used by default when first processing each
@@ -350,25 +362,31 @@ Summary:
 
        touch foo.v ; verilator -E --dump-defines foo.v
 
+.. option:: --dump-dfg
+
+   Rarely needed.  Enable dumping DfgGraph .dot debug files with dumping
+   level 3.
+
+.. option:: --dump-graph
+
+   Rarely needed.  Enable dumping V3Graph .dot debug files with dumping
+   level 3. Before Verilator 4.228, :vlopt:`--dump-tree` used
+   to include this option.
+
 .. option:: --dump-tree
 
-   Rarely needed.  Enable writing .tree debug files with dumping level 3,
+   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.
 
-.. option:: --dump-treei <level>
+.. option:: --dump-tree-dot
 
-.. option:: --dump-treei-<srcfile> <level>
-
-   Rarely needed - for developer use.  Set internal tree dumping level
-   globally to a specific dumping level or set the specified Verilator
-   source file to the specified tree dumping level (e.g.
-   :vlopt:`--dump-treei-V3Order 9 <--dump-treei>`).  Level 0 disables dumps
-   and is equivalent to :vlopt:`--no-dump-tree <--dump-tree>`.  Level 9
-   enables dumping of every stage.
+   Rarely needed.  Enable dumping Ast .tree.dot debug files in Graphviz
+   Dot format. This option implies :vlopt:`--dump-tree`, unless
+   :vlopt:`--dumpi-tree` was passed explicitly.
 
 .. option:: --dump-tree-addrids
 
@@ -379,6 +397,33 @@ Summary:
    by a newly allocated node after a node with the same address has been
    dumped then freed.
 
+.. option:: --dump-<srcfile>
+
+   Rarely needed - for developer use. Enable all dumping in the given
+   source file at level 3.
+
+.. option:: --dumpi-dfg <level>
+
+   Rarely needed - for developer use.  Set internal DfgGraph dumping level
+   globally to the specified value.
+
+.. option:: --dumpi-graph <level>
+
+   Rarely needed - for developer use.  Set internal V3Graph dumping level
+   globally to the specified value.
+
+.. option:: --dumpi-tree <level>
+
+   Rarely needed - for developer use.  Set internal Ast dumping level
+   globally to the specified value.
+
+.. option:: --dumpi-<srcfile> <level>
+
+   Rarely needed - for developer use. Set the dumping level in the
+   specified Verilator source file to the specified value (e.g.
+   `--dumpi-V3Order 9`).  Level 0 disables dumps and is equivalent to
+   `--no-dump-<srcfile>`.  Level 9 enables dumping of everything.
+
 .. option:: -E
 
    Preprocess the source code, but do not compile, similar to C++
@@ -446,6 +491,105 @@ Summary:
    flattening large designs may require significant CPU time, memory and
    storage.
 
+.. option:: -fno-acyc-simp
+
+.. option:: -fno-assemble
+
+.. option:: -fno-case
+
+.. option:: -fno-combine
+
+.. option:: -fno-const
+
+.. options: -fno-const-before-dfg
+
+   Do not apply any global expression folding prior to the DFG pass. This
+   option is solely for the purpose of DFG testing and should not be used
+   otherwise.
+
+.. option:: -fno-const-bit-op-tree
+
+.. option:: -fno-dedup
+
+.. option:: -fno-dfg
+
+   Disable all use of the DFG based combinational logic optimizer.
+   Alias for :vlopt:`-fno-dfg-pre-inline` and :vlopt:`-fno-dfg-post-inline`.
+
+.. option:: -fno-dfg-peephole
+
+   Disable the DFG peephole optimizer.
+
+.. option:: -fno-dfg-peephole-<pattern>
+
+   Disable individual DFG peephole optimizer pattern.
+
+.. option:: -fno-dfg-pre-inline
+
+   Do not apply the DFG optimizer before inlining.
+
+.. option:: -fno-dfg-post-inline
+
+   Do not apply the DFG optimizer after inlining.
+
+.. option:: -fno-expand
+
+.. option:: -fno-gate
+
+.. option:: -fno-inline
+
+.. option:: -fno-life
+
+.. option:: -fno-life-post
+
+.. option:: -fno-localize
+
+.. option:: -fno-merge-cond
+
+.. option:: -fno-merge-cond-motion
+
+.. option:: -fno-merge-const-pool
+
+.. option:: -fno-reloop
+
+.. option:: -fno-reorder
+
+.. option:: -fno-split
+
+.. option:: -fno-subst
+
+.. option:: -fno-subst-const
+
+.. option:: -fno-table
+
+   Rarely needed. Disables one of the internal optimization steps. These
+   are typically used only when recommended by a maintainer to help debug
+   or work around an issue.
+
+.. option:: -future0 <option>
+
+   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
+   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
+   implement :code:`--option`, :code:`-future0 option --option` would have
+   the :code:`-future0 option` ignored and the :code:`--option` would
+   function appropriately.
+
+.. option:: -future1 <option>
+
+   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
+   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.
+
 .. option:: -G<name>=<value>
 
    Overwrites the given parameter of the toplevel module. The value is
@@ -504,6 +648,15 @@ Summary:
    a newline and exit immediately. This can be useful in makefiles. See
    also :vlopt:`-V`, and the various :file:`*.mk` files.
 
+.. option:: --get-supported <feature>
+
+   If the given feature is supported, print "1" and exit
+   immediately. Otherwise, print a newline and exit immediately. This can
+   be useful in makefiles. See also :vlopt:`-V`, and the various
+   :file:`*.mk` files.
+
+   Feature may be one of the following: COROUTINES, SYSTEMC.
+
 .. option:: --help
 
    Displays this message and program version and exits.
@@ -536,28 +689,20 @@ Summary:
    times, but potentially faster simulation speed.  This setting is ignored
    for very small modules; they will always be inlined, if allowed.
 
+.. option:: --instr-count-dpi <value>
+
+   Assumed dynamic instruction count of the average DPI import. This is used
+   by the partitioning algorithm when creating a multithread model. The
+   default value is 200. Adjusting this to an appropriate value can yield
+   performance improvements in multithreaded models. Ignored when creating a
+   single threaded model.
+
 .. option:: -j [<value>]
 
-   Specify the level of parallelism for :vlopt:`--build`. The <value> must
-   be a positive integer specifying the maximum number of parallel build
-   jobs, or can be omitted. When <value> is omitted, the build will not try
-   to limit the number of parallel build jobs but attempt to execute all
-   independent build steps in parallel.
-
-.. option:: -LDFLAGS <flags>
-
-   Add specified C linker arguments to the generated makefiles.  For multiple
-   flags either pass them as a single argument with space separators quoted
-   in the shell (``-LDFLAGS "-a -b"``), or use multiple -LDFLAGS arguments
-   (``-LDFLAGS -a -LDFLAGS -b``).
-
-   When make is run on the generated makefile these will be passed to the
-   C++ linker (ld) **after** the primary file being linked.  This flag is
-   called :vlopt:`-LDFLAGS` as that's the traditional name in simulators;
-   it's would have been better called LDLIBS as that's the Makefile
-   variable it controls.  (In Make, LDFLAGS is before the first object,
-   LDLIBS after.  -L libraries need to be in the Make variable LDLIBS, not
-   LDFLAGS.)
+   Specify the level of parallelism for :vlopt:`--build` if
+   :vlopt:`--build-jobs` isn't provided. If zero, uses the number of threads
+   in the current hardware. Otherwise, the <value> must be a positive
+   integer specifying the maximum number of parallel build jobs.
 
 .. option:: --l2-name <value>
 
@@ -575,6 +720,40 @@ Summary:
    A synonym for :vlopt:`--default-language`, for compatibility with other
    tools and earlier versions of Verilator.
 
+.. option:: -LDFLAGS <flags>
+
+   Add specified C linker arguments to the generated makefiles.  For multiple
+   flags either pass them as a single argument with space separators quoted
+   in the shell (``-LDFLAGS "-a -b"``), or use multiple -LDFLAGS arguments
+   (``-LDFLAGS -a -LDFLAGS -b``).
+
+   When make is run on the generated makefile these will be passed to the
+   C++ linker (ld) **after** the primary file being linked.  This flag is
+   called :vlopt:`-LDFLAGS` as that's the traditional name in simulators;
+   it's would have been better called LDLIBS as that's the Makefile
+   variable it controls.  (In Make, LDFLAGS is before the first object,
+   LDLIBS after.  -L libraries need to be in the Make variable LDLIBS, not
+   LDFLAGS.)
+
+.. option:: --lib-create <name>
+
+   Produces C++, Verilog wrappers and a Makefile which can in turn produce
+   a DPI library which can be used by Verilator or other simulators along
+   with the corresponding Verilog wrapper.  The Makefile will build both a
+   static and dynamic version of the library named :file:`lib<name>.a` and
+   :file:`lib<name>.so` respectively.  This is done because some simulators
+   require a dynamic library, but the static library is arguably easier to
+   use if possible.  :vlopt:`--protect-lib` implies :vlopt:`--protect-ids`.
+
+   When using :vlopt:`--lib-create` it is advised to also use
+   :vlopt:`--timescale-override /1fs <--timescale-override>` to ensure the
+   model has a time resolution that is always compatible with the time
+   precision of the upper instantiating module.
+
+   Designs compiled using this option cannot use :vlopt:`--timing` with delays.
+
+   See also :vlopt:`--protect-lib`.
+
 .. option:: +libext+<ext>[+<ext>][...]
 
    Specify the extensions that should be used for finding modules.  If for
@@ -593,6 +772,19 @@ Summary:
    If the design is not to be completely Verilated see also the
    :vlopt:`--bbox-sys` and :vlopt:`--bbox-unsup` options.
 
+.. option:: --make <build-tool>
+
+   Generates a script for the specified build tool.
+
+   Supported values are ``gmake`` for GNU Make and ``cmake`` for CMake.
+   Both can be specified together.  If no build tool is specified, gmake is
+   assumed.  The executable of gmake can be configured via environment
+   variable "MAKE".
+
+   When using :vlopt:`--build` Verilator takes over the responsibility of
+   building the model library/executable.  For this reason :option:`--make`
+   cannot be specified when using :vlopt:`--build`.
+
 .. option:: -MAKEFLAGS <string>
 
    When using :vlopt:`--build`, add the specified argument to the invoked
@@ -602,22 +794,29 @@ Summary:
    (e.g. ``-MAKEFLAGS -l -MAKEFLAGS -k``). Use of this option should not be
    required for simple builds using the host toolchain.
 
+.. option:: --main
+
+   Generates a top-level C++ main() file that supports parsing arguments,
+   but does not drive any inputs.  This is sufficient to use for top-level
+   SystemVerilog designs that has no inputs.
+
+   This option can also be used once to generate a main .cpp file as a
+   starting point for editing.  Copy it outside the obj directory, manually
+   edit, and then pass the filename on later Verilator command line
+   invocations.
+
+   Typically used with :vlopt:`--timing` to support delay-generated clocks,
+   and :vlopt:`--build`.
+
+   Implies :vlopt:`--cc` if no other output mode was provided.
+
+   See also :vlopt:`--binary`.
+
 .. option:: --max-num-width <value>
 
    Set the maximum number literal width (e.g. in 1024'd22 this it the
    1024).  Defaults to 64K.
 
-.. option:: --MMD =item --no-MMD
-
-   Enable/disable creation of .d dependency files, used for make dependency
-   detection, similar to gcc -MMD option.  By default this option is
-   enabled for :vlopt:`--cc` or :vlopt:`--sc` modes.
-
-.. option:: --MP
-
-   When creating .d dependency files with :vlopt:`--MMD` option, make phony
-   targets.  Similar to :command:`gcc -MP` option.
-
 .. option:: --Mdir <directory>
 
    Specifies the name of the Make object directory.  All generated files
@@ -625,40 +824,23 @@ Summary:
    The directory is created if it does not exist and the parent directories
    exist; otherwise manually create the Mdir before calling Verilator.
 
-.. option:: --no-merge-const-pool
+.. option:: --MMD
 
-   Rarely needed.  In order to minimize cache footprint, values of different
-   data type, that are yet emitted identically in C++ are merged in the
-   constant pool.  This option disables this and causes every constant pool
-   entry with a distinct data type to be emitted separately.
+.. option:: --no-MMD
+
+   Enable/disable creation of .d dependency files, used for make dependency
+   detection, similar to gcc -MMD option.  By default this option is
+   enabled for :vlopt:`--cc` or :vlopt:`--sc` modes.
 
 .. option:: --mod-prefix <topname>
 
    Specifies the name to prepend to all lower level classes.  Defaults to
    the same as :vlopt:`--prefix`.
 
-.. option:: --no-clk <signal-name>
+.. option:: --MP
 
-   Prevent the specified signal from being marked as clock. See
-   :vlopt:`--clk`.
-
-.. option:: --no-decoration
-
-   When creating output Verilated code, minimize comments, white space,
-   symbol names and other decorative items, at the cost of greatly reduced
-   readability. This may assist C++ compile times. This will not typically
-   change the ultimate model's performance, but may in some cases.
-
-.. option:: --no-pins64
-
-   Backward compatible alias for :vlopt:`--pins-bv 33 <--pins-bv>`.
-
-.. option:: --no-skip-identical =item --skip-identical
-
-   Rarely needed.  Disables or enables skipping execution of Verilator if
-   all source files are identical, and all output files exist with newer
-   dates.  By default this option is enabled for :vlopt:`--cc` or
-   :vlopt:`--sc` modes only.
+   When creating .d dependency files with :vlopt:`--MMD` option, make phony
+   targets.  Similar to :command:`gcc -MP` option.
 
 .. option:: +notimingchecks
 
@@ -680,9 +862,9 @@ Summary:
 
    Rarely needed.  Enables or disables a specific optimizations, with the
    optimization selected based on the letter passed.  A lowercase letter
-   disables an optimization, an upper case letter enables it.  This is
-   intended for debugging use only; see the source code for
-   version-dependent mappings of optimizations to -O letters.
+   disables an optimization, an upper case letter enables it.  This option
+   is deprecated and the various `-f<optimization>` arguments should be
+   used instead.
 
 .. option:: -o <executable>
 
@@ -691,6 +873,10 @@ Summary:
 
 .. option:: --no-order-clock-delay
 
+   Deprecated and has no effect (ignored).
+
+   In versions prior to 5.000:
+
    Rarely needed.  Disables a bug fix for ordering of clock enables with
    delayed assignments.  This option should only be used when suggested by
    the developers.
@@ -737,15 +923,10 @@ Summary:
    With :vlopt:`-E`, disable generation of :code:`&96;line` markers and
    blank lines, similar to :command:`gcc -P`.
 
-.. option:: --pins64
-
-   Backward compatible alias for :vlopt:`--pins-bv 65 <--pins-bv>`.  Note
-   that's a 65, not a 64.
-
 .. option:: --pins-bv <width>
 
    Specifies SystemC inputs/outputs of greater than or equal to <width>
-   bits wide should use sc_bv's instead of uint32/vluint64_t's.  The
+   bits wide should use sc_bv's instead of uint32/uint64_t's.  The
    default is "--pins-bv 65", and the value must be less than or equal
    to 65.  Versions before Verilator 3.671 defaulted to "--pins-bv 33".
    The more sc_bv is used, the worse for performance.  Use the
@@ -774,6 +955,15 @@ Summary:
    of uint32_t.  Likewise pins of width 9-16 will use uint16_t instead of
    uint32_t.
 
+.. option:: --pins64
+
+   Backward compatible alias for :vlopt:`--pins-bv 65 <--pins-bv>`.  Note
+   that's a 65, not a 64.
+
+.. option:: --no-pins64
+
+   Backward compatible alias for :vlopt:`--pins-bv 33 <--pins-bv>`.
+
 .. option:: --pipe-filter <command>
 
    Rarely needed.  Verilator will spawn the specified command as a
@@ -803,12 +993,17 @@ Summary:
    prepended to the name of the :vlopt:`--top` option, or V prepended to
    the first Verilog filename passed on the command line.
 
+.. option:: --private
+
+   Opposite of :vlopt:`--public`.  Is the default; this option exists for
+   backwards compatibility.
+
 .. option:: --prof-c
 
    When compiling the C++ code, enable the compiler's profiling flag
    (e.g. :code:`g++ -pg`). See :ref:`Profiling`.
 
-   Using :vlopt:`--prof-cfuncs` also enables :vlopt:`prof-c`.
+   Using :vlopt:`--prof-cfuncs` also enables :vlopt:`--prof-c`.
 
 .. option:: --prof-cfuncs
 
@@ -820,29 +1015,21 @@ Summary:
    came from.  This allows gprof or oprofile reports to be correlated with
    the original Verilog source statements. See :ref:`Profiling`.
 
-   Using :vlopt:`--prof-cfuncs` also enables :vlopt:`prof-c`.
+   Using :vlopt:`--prof-cfuncs` also enables :vlopt:`--prof-c`.
+
+.. option:: --prof-exec
+
+   Enable collection of execution trace, that can be converted into a gantt
+   chart with verilator_gantt See :ref:`Execution Profiling`.
+
+.. option:: --prof-pgo
+
+   Enable collection of profiling data for profile guided Verilation. Currently
+   this is only useful with :vlopt:`--threads`. See :ref:`Thread PGO`.
 
 .. option:: --prof-threads
 
-   Enable gantt chart data collection for threaded builds. See :ref:`Thread
-   Profiling`.
-
-.. option:: --protect-key <key>
-
-   Specifies the private key for :vlopt:`--protect-ids`. For best security
-   this key should be 16 or more random bytes, a reasonable secure choice
-   is the output of :command:`verilator --generate-key` . Typically, a key
-   would be created by the user once for a given protected design library,
-   then every Verilator run for subsequent versions of that library would
-   be passed the same :vlopt:`--protect-key`. Thus, if the input Verilog is
-   similar between library versions (Verilator runs), the Verilated code
-   will likewise be mostly similar.
-
-   If :vlopt:`--protect-key` is not specified and a key is needed,
-   Verilator will generate a new key for every Verilator run. As the key is
-   not saved, this is best for security, but means every Verilator run will
-   give vastly different output even for identical input, perhaps harming
-   compile times (and certainly thrashing any "ccache").
+   Deprecated. Same as --prof-exec and --prof-pgo together.
 
 .. option:: --protect-ids
 
@@ -861,33 +1048,38 @@ Summary:
 
    Using DPI imports/exports is allowed and generally relatively safe in
    terms of information disclosed, which is limited to the DPI function
-   prototyptes.  Use of the VPI is not recommended as many design details
+   prototypes.  Use of the VPI is not recommended as many design details
    may be exposed, and an INSECURE warning will be issued.
 
+.. option:: --protect-key <key>
+
+   Specifies the private key for :vlopt:`--protect-ids`. For best security
+   this key should be 16 or more random bytes, a reasonable secure choice
+   is the output of :command:`verilator --generate-key` . Typically, a key
+   would be created by the user once for a given protected design library,
+   then every Verilator run for subsequent versions of that library would
+   be passed the same :vlopt:`--protect-key`. Thus, if the input Verilog is
+   similar between library versions (Verilator runs), the Verilated code
+   will likewise be mostly similar.
+
+   If :vlopt:`--protect-key` is not specified and a key is needed,
+   Verilator will generate a new key for every Verilator run. As the key is
+   not saved, this is best for security, but means every Verilator run will
+   give vastly different output even for identical input, perhaps harming
+   compile times (and certainly thrashing any "ccache").
+
 .. option:: --protect-lib <name>
 
-   Produces C++, Verilog wrappers and a Makefile which can in turn produce
-   a DPI library which can be used by Verilator or other simulators along
-   with the corresponding Verilog wrapper.  The Makefile will build both a
-   static and dynamic version of the library named :file:`lib<name>.a` and
-   :file:`lib<name>.so` respectively.  This is done because some simulators
-   require a dynamic library, but the static library is arguably easier to
-   use if possible.  :vlopt:`--protect-lib` implies :vlopt:`--protect-ids`.
+   Produces a DPI library similar to :vlopt:`--lib-create`, but hides
+   internal design details.  :vlopt:`--protect-lib` implies
+   :vlopt:`--protect-ids`, and :vlopt:`--lib-create`.
 
    This allows for the secure delivery of sensitive IP without the need for
    encrypted RTL (i.e. IEEE P1735).  See :file:`examples/make_protect_lib`
    in the distribution for a demonstration of how to build and use the DPI
    library.
 
-   When using :vlopt:`--protect-lib` it is advised to also use
-   :vlopt:`--timescale-override /1fs <--timescale-override>` to ensure the
-   model has a time resolution that is always compatible with the time
-   precision of the upper instantiating module.
-
-.. option:: --private
-
-   Opposite of :vlopt:`--public`.  Is the default; this option exists for
-   backwards compatibility.
+   Designs compiled using this option cannot use :vlopt:`--timing` with delays.
 
 .. option:: --public
 
@@ -981,6 +1173,15 @@ Summary:
 
    Specifies SystemC output mode; see also :vlopt:`--cc` option.
 
+.. option:: --skip-identical
+
+.. option:: --no-skip-identical
+
+   Rarely needed.  Disables or enables skipping execution of Verilator if
+   all source files are identical, and all output files exist with newer
+   dates.  By default this option is enabled for :vlopt:`--cc` or
+   :vlopt:`--sc` modes only.
+
 .. option:: --stats
 
    Creates a dump file with statistics on the design in
@@ -1018,7 +1219,8 @@ Summary:
    is not thread safe. With "--threads 1", the generated model is single
    threaded but may run in a multithreaded environment. With "--threads N",
    where N >= 2, the model is generated to run multithreaded on up to N
-   threads. See :ref:`Multithreading`.
+   threads. See :ref:`Multithreading`. This option also applies to
+   :vlopt:`--trace` (but not :vlopt:`--trace-fst`).
 
 .. option:: --threads-dpi all
 
@@ -1044,6 +1246,8 @@ Summary:
      Verilator assumes DPI pure imports are threadsafe, but non-pure DPI
      imports are not.
 
+   See also :vlopt:`--instr-count-dpi` option.
+
 .. option:: --threads-max-mtasks <value>
 
    Rarely needed.  When using :vlopt:`--threads`, specify the number of
@@ -1068,6 +1272,16 @@ Summary:
    module.  As "1fs" is the finest time precision it may be desirable to
    always use a precision of "1fs".
 
+.. option:: --timing
+
+.. option:: --no-timing
+
+   Enables/disables support for timing constructs such as delays, event
+   controls (unless it's at the top of a process), wait statements, and joins.
+   When disabled, timing control constructs are ignored the same way as they
+   were in earlier versions of Verilator. Enabling this feature requires a C++
+   compiler with coroutine support (GCC 10, Clang 5, or newer).
+
 .. option:: --top <topname>
 
 .. option:: --top-module <topname>
@@ -1094,7 +1308,8 @@ Summary:
    Having tracing compiled in may result in some small performance losses,
    even when tracing is not turned on during model execution.
 
-   See also :vlopt:`--trace-threads` option.
+   When using :vlopt:`--threads`, VCD tracing is parallelized, using the
+   same number of threads as passed to :vlopt:`--threads`.
 
 .. option:: --trace-coverage
 
@@ -1148,18 +1363,18 @@ Summary:
 .. option:: --trace-threads *threads*
 
    Enable waveform tracing using separate threads. This is typically faster
-   in simulation runtime but uses more total compute. This option is
-   independent of, and works with, both :vlopt:`--trace` and
-   :vlopt:`--trace-fst`.  Different trace formats can take advantage of
-   more trace threads to varying degrees. Currently VCD tracing can utilize
-   at most "--trace-threads 1", and FST tracing can utilize at most
-   "--trace-threads 2". This overrides :vlopt:`--no-threads` .
+   in simulation runtime but uses more total compute. This option only
+   applies to :vlopt:`--trace-fst`. FST tracing can utilize at most
+   "--trace-threads 2". This overrides :vlopt:`--no-threads`.
+
+   This option is accepted, but has absolutely no effect with
+   :vlopt:`--trace`, which respects :vlopt:`--threads` instead.
 
 .. option:: --trace-underscore
 
-   Enable tracing of signals that start with an underscore. Normally, these
-   signals are not output during tracing.  See also
-   :vlopt:`--coverage-underscore` option.
+   Enable tracing of signals or modules that start with an
+   underscore. Normally, these signals are not output during tracing.  See
+   also :vlopt:`--coverage-underscore` option.
 
 .. option:: -U<var>
 
@@ -1230,8 +1445,7 @@ Summary:
 
    Enable all code style warnings, including code style warnings that are
    normally disabled by default. Equivalent to :vlopt:`-Wwarn-lint`
-   :vlopt:`-Wwarn-style`.  Excludes some specialty warnings,
-   i.e. IMPERFECTSCH.
+   :vlopt:`-Wwarn-style`.  Excludes some specialty warnings.
 
 .. option:: -Werror-<message>
 
@@ -1274,7 +1488,8 @@ Summary:
    equivalent to ``-Wno-ALWCOMBORDER -Wno-BSSPACE -Wno-CASEINCOMPLETE
    -Wno-CASEOVERLAP -Wno-CASEX -Wno-CASTCONST -Wno-CASEWITHX -Wno-CMPCONST -Wno-COLONPLUS
    -Wno-ENDLABEL -Wno-IMPLICIT -Wno-LITENDIAN -Wno-PINCONNECTEMPTY
-   -Wno-PINMISSING -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED -Wno-UNUSED
+   -Wno-PINMISSING -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNSIGNED
+   -Wno-UNUSEDGENVAR -Wno-UNUSEDPARAM -Wno-UNUSEDSIGNAL
    -Wno-WIDTH`` plus the list shown for Wno-style.
 
    It is strongly recommended you cleanup your code rather than using this
@@ -1286,7 +1501,8 @@ Summary:
    Disable all code style related warning messages (note by default they are
    already disabled).  This is equivalent to ``-Wno-DECLFILENAME -Wno-DEFPARAM
    -Wno-EOFNEWLINE -Wno-IMPORTSTAR -Wno-INCABSPATH -Wno-PINCONNECTEMPTY
-   -Wno-PINNOCONNECT -Wno-SYNCASYNCNET -Wno-UNDRIVEN -Wno-UNUSED
+   -Wno-PINNOCONNECT -Wno-SYNCASYNCNET -Wno-UNDRIVEN
+   -Wno-UNUSEDGENVAR -Wno-UNUSEDPARAM -Wno-UNUSEDSIGNAL
    -Wno-VARHIDDEN``.
 
 .. option:: -Wpedantic
@@ -1315,7 +1531,7 @@ Summary:
    Enable all code style related warning messages.  This is equivalent to
    ``-Wwarn ASSIGNDLY -Wwarn-DECLFILENAME -Wwarn-DEFPARAM -Wwarn-EOFNEWLINE
    -Wwarn-INCABSPATH -Wwarn-PINNOCONNECT -Wwarn-SYNCASYNCNET -Wwarn-UNDRIVEN
-   -Wwarn-UNUSED -Wwarn-VARHIDDEN``.
+   -Wwarn-UNUSEDGENVAR -Wwarn-UNUSEDPARAM -Wwarn-UNUSEDSIGNAL -Wwarn-VARHIDDEN``.
 
 .. option:: --x-assign 0
 
@@ -1348,9 +1564,10 @@ Summary:
    .. note::
 
       This option applies only to values which are explicitly written as X
-      in the Verilog source code. Initial values of clocks are set to 0
-      unless `--x-initial-edge` is specified. Initial values of all other
-      state holding variables are controlled with `--x-initial`.
+      in modules (not classes) in the Verilog source code. Initial values
+      of clocks are set to 0 unless `--x-initial-edge` is
+      specified. Initial values of all other state holding variables are
+      controlled with `--x-initial`.
 
 .. option:: --x-initial 0
 
@@ -1483,6 +1700,10 @@ The grammar of configuration commands is as follows:
 
 .. option:: clock_enable -module "<modulename>" -var "<signame>"
 
+   Deprecated and has no effect (ignored).
+
+   In versions prior to 5.000:
+
    Indicate the signal is used to gate a clock, and the user takes
    responsibility for insuring there are no races related to it.
 
@@ -1496,9 +1717,9 @@ The grammar of configuration commands is as follows:
 
 .. option:: no_clocker -module "<modulename>" [-function "<funcname>"] -var "<signame>"
 
-   Indicate the signal is used as clock or not. This information is used by
-   Verilator to mark the signal as clocker and propagate the clocker
-   attribute automatically to derived signals. See :vlopt:`--clk`.
+   Indicates that the signal is used as clock or not. This information is
+   used by Verilator to mark the signal and any derived signals as
+   clocker.  See :vlopt:`--clk`.
 
    Same as :option:`/*verilator&32;clocker*/` metacomment.
 
@@ -1512,6 +1733,14 @@ The grammar of configuration commands is as follows:
 
    Same as :option:`/*verilator&32;coverage_block_off*/` metacomment.
 
+.. option:: forceable -module "<modulename>" -var "<signame>"
+
+   Generate public `<signame>__VforceEn` and `<signame>__VforceVal` signals
+   that can be used to 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 "<filename>" -lines <lineno>
 
 .. option:: parallel_case -file "<filename>" -lines <lineno>
@@ -1602,12 +1831,18 @@ The grammar of configuration commands is as follows:
    :option:`/*verilator&32;public_flat*/`, etc, metacomments. See
    e.g. :ref:`VPI Example`.
 
+.. option:: profile_data -mtask "<mtask_hash>" -cost <cost_value>
+
+   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:: sc_bv -module "<modulename>" [-task "<taskname>"] -var "<signame>"
 
 .. option:: sc_bv -module "<modulename>" [-function "<funcname>"] -var "<signame>"
 
    Sets the port to be of :code:`sc_bv<{width}>` type, instead of bool,
-   vluint32_t or vluint64_t.  Same as :option:`/*verilator&32;sc_bv*/`
+   uint32_t or uint64_t.  Same as :option:`/*verilator&32;sc_bv*/`
    metacomment.
 
 .. option:: sformat [-module "<modulename>"] [-task "<taskname>"] -var "<signame>"
@@ -1632,13 +1867,45 @@ The grammar of configuration commands is as follows:
 
    Same as :option:`/*verilator&32;split_var*/` metacomment.
 
+.. option:: timing_on  [-file "<filename>" [-lines <line> [ - <line>]]]
+
+.. option:: timing_off [-file "<filename>" [-lines <line> [ - <line>]]]
+
+   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`/:code:`join*` blocks are
+   converted into :code:`begin`/:code:`end` blocks.
+
+   Same as :option:`/*verilator&32;timing_on*/`,
+   :option:`/*verilator&32;timing_off*/` metacomments.
+
 .. option:: tracing_on  [-file "<filename>" [-lines <line> [ - <line> ]]]
 
 .. option:: tracing_off [-file "<filename>" [-lines <line> [ - <line> ]]]
 
-   Enable/disable waveform tracing for all future signals declared in the
-   specified filename (or wildcard with '\*' or '?', or all files if
-   omitted) and range of line numbers (or all lines if omitted).
+.. option:: tracing_on  [-scope "<scopename>" [-levels <levels> ]]
 
-   For tracing_off, instances below any module in the files/ranges
-   specified will also not be traced.
+.. option:: tracing_off [-scope "<scopename>" [-levels <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 take place after other file/line/module
+   based controls have indicated the signal should be traced.
+
+   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 meaning an additional
+   level of children below the provided scope, etc.

docs/guide/exe_verilator_coverage.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 verilator_coverage
@@ -67,7 +67,7 @@ which have low coverage are written to the output directory.
 
 Specifies if the coverage point does not include the count number of
 coverage hits, then the coverage point will be considered above the
-threashold, and the coverage report will put a "%" to indicate the coverage
+threshold, and the coverage report will put a "%" to indicate the coverage
 is not sufficient.  Defaults to 10.
 
 .. option:: --help

docs/guide/exe_verilator_gantt.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 verilator_gantt
@@ -10,42 +10,60 @@ starts and ends, and showing when each thread is busy or idle.
 
 For an overview of use of verilator_gantt, see :ref:`Profiling`.
 
-Gantt Chart Contents
---------------------
+Gantt Chart VCD
+---------------
 
-The generated Gantt chart has time on the X-axis. Times shown are to the
-scale printed, i.e. a certain about of time for each character width.  The
-Y-axis shows threads, each thread's execution is shown on one line.  That
-line shows "[" at the position in time when it executes.
+Verilated_gantt creates a value change dump (VCD) format dump file which
+may be viewed in a waveform viewer (e.g. C<GTKWave>):
 
-Following the "[" is the CPU number the task executed on, followed by zero
-or more "-" to make the width of the characters match the scaled execution
-time, followed by a "]".  If the scale is too small, the CPU number and
-mtask number will not be printed.  If the scale is very small, a "&"
-indicates multiple mtasks started at that time position.
+.. figure:: figures/fig_gantt_min.png
+
+   Example verilator_gantt output, as viewed with GTKWave.
+
+The viewed waveform chart has time on the X-axis, with one unit for each
+time tick of the system's high-performance counter.
 
-Also creates a value change dump (VCD) format dump file which may be viewed
-in a waveform viewer (e.g. C<GTKWave>).  See below.
 
 Gantt Chart VCD Signals
 -----------------------
 
-In waveforms there are the following signals. Most signals the "decimal"
-format will remove the leading zeros and make the traces easier to read.
+In waveforms there are the following signals. In GTKWave, using a data
+format of "decimal" will remove the leading zeros and make the traces
+easier to read.
 
-parallelism
+evals
+  Increments each time when eval_step was measured to be active.  This
+  allow visualization of how much time eval_step was active.
+
+eval_loop
+  Increments each time when the evaluation loop within eval_step was
+  measured to be active.  For best performance there is only a single
+  evaluation loop within each eval_step call, that is the eval_loop
+  waveform looks identical to the evals waveform.
+
+measured_parallelism
   The number of mtasks active at this time, for best performance this will
-  match the thread count. You may want to use an "analog step" format to
+  match the thread count. In GTKWave, use a data format of "analog step" to
   view this signal.
 
+predicted_parallelism
+  The number of mtasks Verilator predicted would be active at this time,
+  for best performance this will match the thread count. In GTKWave, use a
+  data format of "analog step" to view this signal.
+
 cpu#_thread
-  For the given CPU number, the thread number executing.
+  For the given CPU number, the thread number measured to be executing.
 
 mtask#_cpu
-  For the given mtask id, the CPU it is executing on.
+  For the given mtask id, the CPU it was measured to execute on.
 
 thread#_mtask
-  For the given thread number, the mtask id executing.
+  For the given thread number, the mtask id it was executing.
+
+predicted_thread#_mtask
+  For the given thread number, the mtask id Verilator predicted would be
+  executing.
+
 
 verilator_gantt Arguments
 -------------------------
@@ -54,19 +72,12 @@ verilator_gantt Arguments
 
 .. option:: <filename>
 
-The filename to read data from, defaults to "profile_threads.dat".
+The filename to read data from, defaults to "profile_exec.dat".
 
 .. option:: --help
 
 Displays a help summary, the program version, and exits.
 
-.. option:: --scale <n>
-
-Sets the number of time units per character on the X-axis of the generated
-Gantt chart.  (On x86, time units are rdtsc ticks.)  Defaults to 0, which
-will automatically compute a reasonable scale where no two mtasks need to
-fit into same character width's worth of scaled time.
-
 .. option:: --no-vcd
 
 Disables creating a .vcd file.

docs/guide/exe_verilator_profcfunc.rst

@@ -1,20 +1,24 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-verilator_profcfuncs
-====================
+verilator_profcfunc
+===================
 
 Verilator_profcfunc reads a profile report created by gprof.  The names of
 the functions are then transformed, assuming the user used Verilator's
 --prof-cfuncs, and a report printed showing the percentage of time, etc, in
 each Verilog block.
 
-For an overview of use of verilator_profcfuncs, see :ref:`Profiling`.
+Due to rounding errors in gprof reports, the input report's percentages may
+not total to 100%.  In the verilator_profcfunc report this will get
+reported as a rounding error.
 
-verilator_profcfuncs Arguments
-------------------------------
+For an overview of use of verilator_profcfunc, see :ref:`Profiling`.
 
-.. program:: verilator_profcfuncs
+verilator_profcfunc Arguments
+-----------------------------
+
+.. program:: verilator_profcfunc
 
 .. option:: <filename>
 

docs/guide/executables.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 *********************************
@@ -15,5 +15,5 @@ options to each executable.
    exe_verilator.rst
    exe_verilator_coverage.rst
    exe_verilator_gantt.rst
-   exe_verilator_profcfuncs.rst
+   exe_verilator_profcfunc.rst
    exe_sim.rst

docs/guide/extensions.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 *******************
@@ -48,6 +48,14 @@ or "`ifdef`"'s may break other tools.
    Verilog functions where the variable is flattened out, and also enable
    other optimizations.
 
+   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).
+
    If you will be reading or writing any Verilog variables inside the C++
    functions, the Verilog signals must be declared with
    :option:`/*verilator&32;public*/` metacomments.
@@ -143,6 +151,13 @@ or "`ifdef`"'s may break other tools.
    Take remaining text up to the next :option:`\`verilog` mode switch and
    treat it as Verilator configuration commands.  See :ref:`Configuration Files`.
 
+.. option:: `VERILATOR_TIMING
+
+   The VERILATOR_TIMING define is set when :vlopt:`--timing` is used to
+   allow an "\`ifdef" of code dependent on this feature.  Note this define
+   is not affected by the :option:`timing_off` configuration file option
+   nor timing metacomments.
+
 .. option:: `verilog
 
    Switch back to processing Verilog code after a
@@ -152,6 +167,10 @@ or "`ifdef`"'s may break other tools.
 
 .. option:: /*verilator&32;clock_enable*/
 
+   Deprecated and has no effect (ignored).
+
+   In versions prior to 5.000:
+
    Used after a signal declaration to indicate the signal is used to gate a
    clock, and the user takes responsibility for insuring there are no races
    related to it. (Typically by adding a latch, and running static timing
@@ -166,9 +185,7 @@ or "`ifdef`"'s may break other tools.
 
    The clock_enable attribute will cause the clock gate to be ignored in
    the scheduling algorithm, sometimes required for correct clock behavior,
-   and always improving performance.  It's also a good idea to enable the
-   :option:`IMPERFECTSCH` warning, to ensure all clock enables are properly
-   recognized.
+   and always improving performance.
 
    Same as :option:`clock_enable` configuration file option.
 
@@ -176,10 +193,7 @@ or "`ifdef`"'s may break other tools.
 
 .. option:: /*verilator&32;no_clocker*/
 
-   Used after a signal declaration to indicate the signal is used as clock
-   or not. This information is used by Verilator to mark the signal as
-   clocker and propagate the clocker attribute automatically to derived
-   signals. See :vlopt:`--clk`.
+   Specifies that the signal is used as clock or not. See :vlopt:`--clk`.
 
    Same as :option:`clocker` and :option:`no_clocker` in configuration
    files.
@@ -202,6 +216,20 @@ or "`ifdef`"'s may break other tools.
    (if appropriate :vlopt:`--coverage` flags are passed) after being
    disabled earlier with :option:`/*verilator&32;coverage_off*/`.
 
+.. option:: /*verilator&32;forceable*/
+
+   Specifies that the signal (net or variable) should be made forceable from
+   C++ code by generating public `<signame>__VforceEn` and
+   `<signame>__VforceVal` signals The force control signals are created as
+   :option:`public_flat` signals.
+
+   To force a marked signal from C++, set the corresponding `__VforceVal`
+   variable to the desired value, and the `__VforceEn` signal to the bit-mask
+   indicating which bits of the signal to force. To force all bits of the
+   target signal, set `__VforceEn` to all ones. To release the signal (or part
+   thereof), set appropriate bits of the `__VforceEn` signal to zero.
+
+   Same as :option:`forceable` in configuration  files.
 
 .. _verilator_hier_block:
 
@@ -424,7 +452,7 @@ or "`ifdef`"'s may break other tools.
 .. option:: /*verilator&32;sc_bv*/
 
    Used after a port declaration.  It sets the port to be of
-   :code:`sc_bv<{width}>` type, instead of bool, vluint32_t or vluint64_t.
+   :code:`sc_bv<{width}>` type, instead of bool, uint32_t or uint64_t.
    This may be useful if the port width is parameterized and the
    instantiating C++ code wants to always have a sc_bv so it can accept any
    width.  In general you should avoid using this attribute when not
@@ -482,6 +510,29 @@ or "`ifdef`"'s may break other tools.
    Verilator) text that should be passed through to the XML output as a tag,
    for use by downstream applications.
 
+.. option:: /*verilator&32;timing_off*/
+
+   Ignore all timing constructs after this metacomment. All timing controls
+   behave as if they were not there (the same way as with
+   :option:`--no-timing`), and :code:`fork`/:code:`join*` blocks are
+   converted into :code:`begin`/:code:`end` blocks.
+
+   Same as :option:`timing_off` configuration file option.
+
+.. option:: /*verilator&32;timing_on*/
+
+   Re-enable all timing constructs after this metacomment (only applicable
+   after :option:`timing_off`).
+
+   Same as :option:`timing_on` configuration file option.
+
+.. option:: /*verilator&32;trace_init_task*/
+
+   Attached to a DPI import to indicate that function should be called when
+   initializing tracing. This attribute is indented only to be used
+   internally in code that Verilator generates when :vlopt:`--lib-create`
+   or :vlopt:`--hierarchical` is used along with :vlopt:`--trace`.
+
 .. option:: /*verilator&32;tracing_off*/
 
    Disable waveform tracing for all future signals that are declared in

docs/guide/faq.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ******************************
@@ -35,15 +35,17 @@ simulators.
 Does Verilator run under Windows?
 """""""""""""""""""""""""""""""""
 
-Yes, using Cygwin.  Verilated output also compiles under Microsoft Visual
-C++, but this is not tested every release.
+Yes, ideally run Ubuntu under Windows Subsystem for Linux (WSL2).
+Alternatively use Cygwin, though this tends to be slower and is not
+regularly tested.  Verilated output also compiles under Microsoft Visual
+C++, but this is also not regularly tested.
 
 
 Can you provide binaries?
 """""""""""""""""""""""""
 
 You can install Verilator via the system package manager (apt, yum, etc.)
-on many Linux distributions, including Debian, Ubuntu, SuSE, RedHat, and
+on many Linux distributions, including Debian, Ubuntu, SuSE, Red Hat, and
 others.  These packages are provided by the Linux distributions and
 generally will lag the version of the mainline Verilator repository.  If no
 binary package is available for your distribution, how about you set one
@@ -70,23 +72,38 @@ a good thing for getting working silicon.
 Will Verilator output remain under my own license/copyright?
 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
-Yes, it's just like using GCC on your programs; this is why Verilator uses
-the "GNU **Lesser** Public License Version 3" instead of the more typical
-"GNU Public License".  See the licenses for details, but in brief, if you
-change Verilator itself or the header files Verilator includes, you must
-make the source code available under the GNU Lesser Public License.
-However, Verilator output (the Verilated code) only "include"s the licensed
-files, and so you are **not** required to open-source release any output
-from Verilator.
+Your SystemVerilog, VPI/DPI, or main() C++ code remains under your own license.
+
+It's just like how using GCC on your programs does not change the copyright
+of your program; this is why Verilator uses the "GNU **Lesser** Public
+License Version 3" instead of the more typical "GNU Public License".  See
+the licenses for details.
+
+Some examples:
+
+* Any SystemVerilog or other input fed into Verilator remain your own.
+
+* Any of your VPI/DPI C++ routines that Verilator calls remain your own.
+
+* Any of your main() C++ code that calls into Verilator remain your own.
+
+* If you change Verilator itself, for example changing or adding a file
+  under the src/ directory in the repository, you must make the source code
+  available under the GNU Lesser Public License.
+
+* If you change a header Verilator provides, for example under include/ in
+  the repository, you must make the source code available under the GNU
+  Lesser Public License.
 
 You also have the option of using the Perl Artistic License, which again
-does not require you to release your Verilog or generated code, and also
-allows you to modify Verilator for internal use without distributing the
-modified version.  But please contribute back to the community!
+does not require you to release your Verilog, C++, or generated code. This
+license also allows you to modify Verilator for internal use without
+distributing the modified version.  But please contribute back to the
+community!
 
-One limit is that you cannot under either license release a closed-source
-Verilog simulation product incorporating Verilator. That is you can have a
-commercial product, but must make the source code available.
+Under both license you can offer a commercial product that is based on
+Verilator either directly or embedded within.  However under both licenses,
+any changes you make to Verilator for such a product must be open sourced.
 
 As is standard with Open Source, contributions back to Verilator will be
 placed under the Verilator copyright and LGPL/Artistic license.  Small test
@@ -132,7 +149,8 @@ B. Or, for finer-grained control, or C++ files with multiple Verilated
           ...
           Verilated::traceEverOn(true);
           VerilatedVcdC* tfp = new VerilatedVcdC;
-          topp->trace(tfp, 99);  // Trace 99 levels of hierarchy
+          topp->trace(tfp, 99);  // Trace 99 levels of hierarchy (or see below)
+          // tfp->dumpvars(1, "t");  // trace 1 level under "t"
           tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
           ...
           while (contextp->time() < sim_time && !contextp->gotFinish()) {
@@ -351,8 +369,8 @@ also use the "import DPI" SystemVerilog feature to call C code (see the
 chapter above).  There is also limited VPI access to public signals.
 
 If you want something more complex, since Verilator emits standard C++
-code, you can simply write your own C++ routines that can access and modify
-signal values without needing any PLI interface code, and call it with
+code, you can write your own C++ routines that can access and modify signal
+values without needing any PLI interface code, and call it with
 $c("{any_c++_statement}").
 
 See the :ref:`Connecting` section.
@@ -442,7 +460,7 @@ the signal, as you would any other member variable.
 Signals are the smallest of 8-bit unsigned chars (equivalent to uint8_t),
 16-bit unsigned shorts (uint16_t), 32-bit unsigned longs (uint32_t), or
 64-bit unsigned long longs (uint64_t) that fits the width of the signal.
-Generally, you can use just uint32_t's for 1 to 32 bits, or vluint64_t for
+Generally, you can use just uint32_t's for 1 to 32 bits, or uint64_t for
 1 to 64 bits, and the compiler will properly up-convert smaller entities.
 Note even signed ports are declared as unsigned; you must sign extend
 yourself to the appropriate signal width.
@@ -479,7 +497,7 @@ by your code or you'll get strange results.
 Should a module be in Verilog or SystemC?
 """""""""""""""""""""""""""""""""""""""""
 
-Sometimes there is a block that just interconnects instances, and have a
+Sometimes there is a block that only interconnects instances, and have a
 choice as to if you write it in Verilog or SystemC.  Everything else being
 equal, best performance is when Verilator sees all of the design.  So, look
 at the hierarchy of your design, labeling instances as to if they are

docs/guide/files.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 *****
@@ -50,7 +50,7 @@ For --cc/--sc, it creates:
      - Make include file with class names (from --make gmake)
    * - *{prefix}*\ _hier.mk
      - Make file for hierarchy blocks (from --make gmake)
-   * - *{prefix|*\ _hierMkArgs.f
+   * - *{prefix}*\ _hierMkArgs.f
      - Arguments for hierarchical Verilation (from --make gmake)
    * - *{prefix}*\ _hierCMakeArgs.f
      - Arguments for hierarchical Verilation (from --make cmake)
@@ -62,19 +62,23 @@ For --cc/--sc, it creates:
      - Top level (SystemVerilog $root) internal header file
    * - *{prefix}*\ ___024root.cpp
      - Top level (SystemVerilog $root) internal C++ file
-   * - *{prefix}*___024root*{__n}*\ .cpp
-     - Additional top level internal C++ files (from --output-split)
+   * - *{prefix}*\ ___024root\ *{__n}*\ .cpp
+     - Additional top level internal C++ files
+   * - *{prefix}*\ ___024root\ *{__DepSet_hash__n}*\ .cpp
+     - Additional top level internal C++ files (hashed to reduce build times)
    * - *{prefix}*\ ___024root__Slow\ *{__n}*\ .cpp
      - Infrequent cold routines
-   * - *{prefix}*\ ___024root__Trace{__n}*\ .cpp
+   * - *{prefix}*\ ___024root\ *{__DepSet_hash__n}*\ .cpp
+     - Infrequent cold routines (hashed to reduce build times)
+   * - *{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
@@ -87,7 +91,9 @@ For --cc/--sc, it creates:
    * - *{prefix}{each_verilog_module}*\ .cpp
      - Lower level internal C++ files
    * - *{prefix}{each_verilog_module}{__n}*\ .cpp
-     - Additional lower C++ files (from --output-split)
+     - Additional lower C++ files
+   * - *{prefix}{each_verilog_module}{__DepSet_hash__n}*\ .cpp
+     - Additional lower C++ files (hashed to reduce build times)
 
 For --hierarchy mode, it creates:
 
@@ -120,7 +126,7 @@ In certain debug and other modes, it also creates:
      - Debugging graph files (from --debug)
    * - *{prefix}{misc}*\ .tree
      - Debugging files (from --debug)
-   * - {mod_prefix}_{each_verilog_module}*{__n}*\ .vpp
+   * - {mod_prefix}_{each_verilog_base_filename}*\ .vpp
      - Pre-processed verilog (from --debug)
 
 After running Make, the C++ compiler may produce the following:
@@ -145,3 +151,23 @@ After running Make, the C++ compiler may produce the following:
      - Intermediate dependencies
    * - *{prefix}{misc}*\ .o
      - Intermediate objects
+
+The Verilated executable may produce the following:
+
+.. list-table::
+
+   * - coverage.dat
+     - Code coverage output, and default input filename for :command:`verilator_coverage`
+   * - gmon.out
+     - GCC/clang code profiler output, often fed into :command:`verilator_profcfunc`
+   * - profile.vlt
+     - --prof-pgo data file for :ref:`Thread PGO`
+   * - profile_exec.dat
+     - --prof-exec data file for :command:`verilator_gantt`
+
+Verilator_gantt may produce the following:
+
+.. list-table::
+
+   * - profile_exec.vcd
+     - Gantt report waveform output

docs/guide/index.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ######################

docs/guide/install.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Installation:
@@ -23,6 +23,8 @@ package:
 
    apt-get install verilator   # On Ubuntu
 
+For other distributions refer to `Repology Verilator Distro Packages
+<https://repology.org/project/verilator>`__.
 
 .. _Git Install:
 
@@ -44,21 +46,20 @@ In brief, to install from git:
    #sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)
 
    git clone https://github.com/verilator/verilator   # Only first time
-   ## Note the URL above is not a page you can see with a browser, it's for git only
 
    # Every time you need to build:
    unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
    unset VERILATOR_ROOT  # For bash
    cd verilator
-   git pull        # Make sure git repository is up-to-date
-   git tag         # See what versions exist
+   git pull         # Make sure git repository is up-to-date
+   git tag          # See what versions exist
    #git checkout master      # Use development branch (e.g. recent bug fixes)
    #git checkout stable      # Use most recent stable release
    #git checkout v{version}  # Switch to specified release version
 
-   autoconf        # Create ./configure script
-   ./configure     # Configure and create Makefile
-   make -j         # Build Verilator itself
+   autoconf         # Create ./configure script
+   ./configure      # Configure and create Makefile
+   make -j `nproc`  # Build Verilator itself (if error, try just 'make')
    sudo make install
 
 
@@ -76,17 +77,17 @@ OS Requirements
 ---------------
 
 Verilator is developed and has primary testing on Ubuntu, with additional
-testing on FreeBSD and Apple OS-X. Versions have also built on Redhat
-Linux, HPUX and Solaris. It should run with minor porting on any
-GNU/Linux-ish platform. Verilator also works on Windows under Cygwin, and
-Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator
-itself) compiles under all the options above, plus using MSVC++.
+testing on FreeBSD and Apple OS-X. Versions have also built on Red Hat
+Linux, and other flavors of GNU/Linux-ish platforms. Verilator also works
+on Windows Subsystem for Linux (WSL2), Windows under Cygwin, and Windows
+under MinGW (gcc -mno-cygwin). Verilated output (not Verilator itself)
+compiles under all the options above, plus using MSVC++.
 
 
 Install Prerequisites
 ---------------------
 
-To build or run Verilator you need these standard packages:
+To build or run Verilator, you need these standard packages:
 
 ::
 
@@ -97,13 +98,20 @@ To build or run Verilator you need these standard packages:
    sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
    sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)
 
-To build or run the following are optional but should be installed for good
-performance:
+To build or run Verilator, the following are optional but should be installed
+for good performance:
 
 ::
 
    sudo apt-get install ccache  # If present at build, needed for run
-   sudo apt-get install libgoogle-perftools-dev numactl perl-doc
+   sudo apt-get install libgoogle-perftools-dev numactl
+
+The following is optional but is recommended for nicely rendered command line
+help when running Verilator:
+
+::
+
+   sudo apt-get install perl-doc
 
 To build Verilator you will need to install these packages; these do not
 need to be present to run Verilator:
@@ -116,8 +124,9 @@ Those developing Verilator itself may also want these (see internals.rst):
 
 ::
 
-   sudo apt-get install gdb graphviz cmake clang clang-format-11 gprof lcov
-   sudo pip3 install sphinx sphinx_rtd_theme breathe
+   sudo apt-get install gdb graphviz cmake clang clang-format-14 gprof lcov
+   sudo apt-get install yapf3
+   sudo pip3 install sphinx sphinx_rtd_theme sphinxcontrib-spelling breathe
    cpan install Pod::Perldoc
    cpan install Parallel::Forker
 
@@ -286,7 +295,7 @@ Compile Verilator:
 
 ::
 
-   make -j
+   make -j `nproc`  # Or if error on `nproc`, the number of CPUs in system
 
 
 Test

docs/guide/languages.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ***************
@@ -92,7 +92,73 @@ appropriate code to detect failing cases at simulation runtime and print an
 
 Verilator likewise also asserts any "unique" or "priority" SystemVerilog
 keywords on case statement, as well as "unique" on if statements.  However,
-"priority if" is currently simply ignored.
+"priority if" is currently ignored.
+
+
+Time
+====
+
+With :vlopt:`--timing`, all timing controls are supported:
+
+* delay statements,
+* event control statements not only at the top of a process,
+* intra-assignment timing controls,
+* net delays,
+* :code:`wait` statements,
+
+as well as all flavors of :code:`fork`.
+
+Compiling a verilated design that makes use of these features requires a
+compiler with C++20 coroutine support, e.g. Clang 5, GCC 10, or newer.
+
+:code:`#0` delays cause Verilator to issue the :option:`ZERODLY` warning, as
+they work differently than described in the LRM. They do not schedule process
+resumption in the Inactive region, though the process will get resumed in the
+same time slot.
+
+Rising/falling/turn-off delays are currently unsupported and cause the
+:option:`RISEFALLDLY` warning.
+
+Minimum/typical/maximum delays are currently unsupported. The typical delay is
+always the one chosen. Such expressions cause the :option:`MINTYPMAX` warning.
+
+Another consequence of using :vlopt:`--timing` is that the :vlopt:`--main`
+option generates a main file with a proper timing eval loop, eliminating the
+need for writing any driving C++ code. You can then simply compile the
+simulation (perhaps using :vlopt:`--build`) and run it.
+
+With :vlopt:`--no-timing`, all timing controls cause the :option:`NOTIMING`
+error, with the exception of:
+
+* 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,
+* net delays – they are ignored,
+* event controls at the top of the procedure,
+
+Forks cause this error as well, with the exception of:
+
+* forks with no statements,
+* :code:`fork..join` or :code:`fork..join_any` with one statement,
+* forks with :vlopt:`--bbox-unsup`.
+
+If neither :vlopt:`--timing` nor :vlopt:`--no-timing` is specified, all timing
+controls cause the :option:`NEEDTIMINGOPT` error, with the exception of event
+controls at the top of the process. Forks cause this error as well, with the
+exception of:
+
+* forks with no statements,
+* :code:`fork..join` or :code:`fork..join_any` with one statement,
+* forks with :vlopt:`--bbox-unsup`.
+
+Timing controls and forks can also be ignored in specific files or parts of
+files. The :option:`/*verilator&32;timing_off*/` and
+:option:`/*verilator&32;timing_off*/` metacomments will make Verilator ignore
+the encompassed timing controls and forks, regardless of the chosen
+:vlopt:`--timing` or :vlopt:`--no-timing` option. This can also be achieved
+using the :option:`timing_off` and :option:`timing_off` options in Verilator
+configuration files.
 
 
 .. _Language Limitations:
@@ -136,7 +202,7 @@ ___05F (5F is the hex code of an underscore.)
 Bind
 ----
 
-sVerilator only supports bind to a target module name, not to an
+Verilator only supports bind to a target module name, not to an
 instance path.
 
 
@@ -174,18 +240,12 @@ Structures and Unions
 ---------------------
 
 Presently Verilator only supports packed structs and packed unions.  Rand
-and randc tags on members are simply ignored.  All structures and unions
-are represented as a single vector, which means that generating one member
-of a structure from blocking, and another from non-blocking assignments is
+and randc tags on members are ignored.  All structures and unions are
+represented as a single vector, which means that generating one member of a
+structure from blocking, and another from non-blocking assignments is
 unsupported.
 
 
-Time
-----
-
-All delays (#) are ignored, as they are in synthesis.
-
-
 .. _Unknown States:
 
 Unknown States
@@ -276,17 +336,6 @@ probably expect, what C does. The default behavior of Verilog is
 different.)
 
 
-Generated Clocks
-----------------
-
-Verilator attempts to deal with generated and gated clocks correctly,
-however some cases cause problems in the scheduling algorithm which is
-optimized for performance.  The safest option is to have all clocks as
-primary inputs to the model, or wires directly attached to primary inputs.
-For proper behavior clock enables may also need the
-:option:`/*verilator&32;clock_enable*/` metacomment.
-
-
 Gate Primitives
 ---------------
 
@@ -336,6 +385,24 @@ Verilator does not support SEREs yet.  All assertion and coverage
 statements must be simple expressions that complete in one cycle.
 
 
+Force statement
+---------------
+
+Verilator supports the procedural `force` (and corresponding `release`)
+statement. The behavior of the `force` statement however does not entirely
+comply with the IEEE 1800 SystemVerilog standard. According to the standard,
+when a procedural statement of the form `force a = b;` is executed, the
+simulation should behave as if from that point forwards, a continuous
+assignment `assign a = b;` have been added to override the drivers of `a`.
+More specifically: the value of `a` should be updated, whenever the value of
+`b` changes, all the way until a `release a;` statement is executed.
+Verilator instead evaluates the current value of `b` at the time the `force`
+statement is executed, and forces `a` to that value, without updating it
+until a new `force` or `release` statement is encountered that applies to
+`a`. This non-standard behavior is nevertheless consistent with some other
+simulators.
+
+
 Encrypted Verilog
 -----------------
 
@@ -471,7 +538,7 @@ $test$plusargs, $value$plusargs
 
   .. code-block:: C++
 
-        Verilated::commandArgs(argc, argv);
+        {VerilatedContext*} ->commandArgs(argc, argv);
 
   to register the command line before calling $test$plusargs or
   $value$plusargs.

docs/guide/overview.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ********

docs/guide/simulating.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _Simulating:
@@ -7,9 +7,9 @@
 Simulating (Verilated-Model Runtime)
 ************************************
 
-This section describes items related to simulating, that using a Verilated
-model's executable.  For the runtime arguments to a simulated model, see
-:ref:`Simulation Runtime Arguments`.
+This section describes items related to simulating, that is, the use of a
+Verilated model's executable.  For the runtime arguments to a simulated
+model, see :ref:`Simulation Runtime Arguments`.
 
 
 .. _Benchmarking & Optimization:
@@ -26,7 +26,8 @@ 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`.
+non-conflicting hardware resources. See :ref:`Multithreading`. Also
+consider using profile-guided optimization, see :ref:`Thread PGO`.
 
 Minor Verilog code changes can also give big wins.  You should not have any
 UNOPTFLAT warnings from Verilator.  Fixing these warnings can result in
@@ -93,9 +94,7 @@ cases, for example regressions, it is usually worth spending extra
 compilation time to reduce total CPU time.
 
 If you will be running many simulations on a single model, you can
-investigate profile guided optimization. With GCC, using GCC's
-"-fprofile-arcs", then GCC's "-fbranch-probabilities" will yield another
-15% or so.
+investigate profile guided optimization. See :ref:`Compiler PGO`.
 
 Modern compilers also support link-time optimization (LTO), which can help
 especially if you link in DPI code. To enable LTO on GCC, pass "-flto" in
@@ -230,7 +229,7 @@ coverage point insertions into the model and collect the coverage data.
 
 To get the coverage data from the model, in the user wrapper code,
 typically at the end once a test passes, call
-:code:`Verilated::coveragep()->write` with an argument of the filename for
+:code:`Verilated::threadContextp()->coveragep()->write` with an argument of the filename for
 the coverage data file to write coverage data to (typically
 "logs/coverage.dat").
 
@@ -280,23 +279,25 @@ To use profiling:
    is being spent.
 
 
-.. _Thread Profiling:
+.. _Execution Profiling:
 
-Thread Profiling
-================
+Execution Profiling
+===================
 
-When using multithreaded mode (:vlopt:`--threads`), it is useful to see
-statistics and visualize how well the multiple CPUs are being utilized.
+For performance optimization, it is useful to see statistics and visualize how
+execution time is distributed in a verilated model.
 
-With the :vlopt:`--prof-threads` option, Verilator will:
+With the :vlopt:`--prof-exec` option, Verilator will:
 
-* Add code to the Verilated model to record the start and end time of each
-  macro-task across a number of calls to eval. (What is a macro-task?  See
-  the Verilator internals document (:file:`docs/internals.rst` in the
-  distribution.)
+* Add code to the Verilated model to record execution flow.
 
 * Add code to save profiling data in non-human-friendly form to the file
-  specified with :vlopt:`+verilator+prof+threads+file+\<filename\>`.
+  specified with :vlopt:`+verilator+prof+exec+file+\<filename\>`.
+
+* In multi-threaded models, add code to record the start and end time of each
+  macro-task across a number of calls to eval. (What is a macro-task?  See the
+  Verilator internals document (:file:`docs/internals.rst` in the
+  distribution.)
 
 The :command:`verilator_gantt` program may then be run to transform the
 saved profiling file into a nicer visual format and produce some related
@@ -306,7 +307,7 @@ statistics.
 
    Example verilator_gantt output, as viewed with GTKWave.
 
-   The parallelism shows the number of CPUs being used at a given moment.
+   The measured_parallelism shows the number of CPUs being used at a given moment.
 
    The cpu_thread section shows which thread is executing on each of the physical CPUs.
 
@@ -314,6 +315,7 @@ statistics.
 
 For more information see :command:`verilator_gantt`.
 
+
 .. _Profiling ccache efficiency:
 
 Profiling ccache efficiency
@@ -377,3 +379,121 @@ For example:
          os >> main_time;
          os >> *topp;
      }
+
+
+Profile-Guided Optimization
+===========================
+
+Profile-guided optimization is the technique where profiling data is
+collected by running your simulation executable, then this information is
+used to guide the next Verilation or compilation.
+
+There are two forms of profile-guided optimizations.  Unfortunately for
+best results they must each be performed from the highest level code to the
+lowest, which means performing them separately and in this order:
+
+* :ref:`Thread PGO`
+* :ref:`Compiler PGO`
+
+Other forms of PGO may be supported in the future, such as clock and reset
+toggle rate PGO, branch prediction PGO, statement execution time PGO, or
+others as they prove beneficial.
+
+
+.. _Thread PGO:
+
+Thread Profile-Guided Optimization
+----------------------------------
+
+Verilator supports profile-guided optimization (Verilation) of multi-threaded
+models (Thread PGO) to improve performance.
+
+When using multithreading, Verilator computes how long macro tasks take and
+tries to balance those across threads.  (What is a macro-task?  See the
+Verilator internals document (:file:`docs/internals.rst` in the
+distribution.)  If the estimations are incorrect, the threads will not be
+balanced, leading to decreased performance.  Thread PGO allows collecting
+profiling data to replace the estimates and better optimize these
+decisions.
+
+To use Thread PGO, Verilate the model with the :vlopt:`--prof-pgo` option. This
+will code to the verilated model to save profiling data for profile-guided
+optimization.
+
+Run the model executable. When the executable exits, it will create a
+profile.vlt file.
+
+Rerun Verilator, optionally omitting the :vlopt:`--prof-pgo` option,
+and adding the profile.vlt generated earlier to the command line.
+
+Note there is no Verilator equivalent to GCC's --fprofile-use. Verilator's
+profile data file (profile.vlt) can be placed on the verilator command line
+directly without any prefix.
+
+If results from multiple simulations are to be used in generating the
+optimization, multiple simulation's profile.vlt may be concatenated
+externally, or each of the files may be fed as separate command line
+options into Verilator.  Verilator will sum the profile results, so a
+longer running test will have proportionally more weight for optimization
+than a shorter running test.
+
+If you provide any profile feedback data to Verilator, and it cannot use
+it, it will issue the :option:`PROFOUTOFDATE` warning that threads were
+scheduled using estimated costs.  This usually indicates that the profile
+data was generated from different Verilog source code than Verilator is
+currently running against. Therefore, repeat the data collection phase to
+create new profiling data, then rerun Verilator with the same input source
+files and that new profiling data.
+
+
+.. _Compiler PGO:
+
+Compiler Profile-Guided Optimization
+------------------------------------
+
+GCC and Clang support compiler profile-guided optimization (PGO). This
+optimizes any C/C++ program including Verilated code.  Using compiler PGO
+typically yields improvements of 5-15% on both single-threaded and
+multi-threaded models.
+
+To use compiler PGO with GCC or Clang, please see the appropriate compiler
+documentation.  The process in GCC 10 was as follows:
+
+1. Compile the Verilated model with the compiler's "-fprofile-generate"
+   flag:
+
+   .. code-block:: bash
+
+      verilator [whatever_flags] --make \
+          -CFLAGS -fprofile-generate -LDFLAGS -fprofile-generate
+
+   or, if calling make yourself, add -fprofile-generate appropriately to your
+   Makefile.
+
+2. Run your simulation. This will create \*.gcda file(s) in the same
+   directory as the source files.
+
+3. Recompile the model with -fprofile-use. The compiler will read the
+   \*.gcda file(s).
+
+   For GCC:
+
+   .. code-block:: bash
+
+      verilator [whatever_flags] --build \
+          -CFLAGS "-fprofile-use -fprofile-correction"
+
+   For Clang:
+
+   .. code-block:: bash
+
+      llvm-profdata merge -output default.profdata *.profraw
+      verilator [whatever_flags] --build \
+          -CFLAGS "-fprofile-use -fprofile-correction"
+
+   or, if calling make yourself, add these CFLAGS switches appropriately to
+   your Makefile.
+
+Clang and GCC also support -fauto-profile which uses sample-based
+feedback-directed optimization.  See the appropriate compiler
+documentation.

docs/guide/verilating.rst

@@ -1,4 +1,4 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 **********
@@ -68,12 +68,11 @@ multi-core SoC.
 
 Verilator is run in hierarchical mode on the whole SoC.  Verilator will
 make two models, one for the CPU hierarchy block, and one for the SoC.  The
-Verialted code for the SoC will automatically call the CPU Verilated model.
+Verilated code for the SoC will automatically call the CPU Verilated model.
 
-The current hierarchical Verilation is based on protect-lib. Each hierarchy
-block is Verilated to a protect-lib. User modules of the hierarchy blocks
-will see a tiny wrapper generated by protect-lib instead of the actual
-design.
+The current hierarchical Verilation is based on :vlopt:`--lib-create`. Each
+hierarchy block is Verilated into a library. User modules of the hierarchy
+blocks will see a tiny wrapper generated by :vlopt:`--lib-create`.
 
 
 Usage
@@ -114,6 +113,8 @@ Hierarchy blocks have some limitations including:
   hierarchical model and pass up into another hierarchical model or the top
   module.
 
+* Delays are not allowed in hierarchy blocks.
+
 But, the following usage is supported:
 
 * Nested hierarchy blocks. A hierarchy block may instantiate other
@@ -216,9 +217,19 @@ be done by a "main thread". In most cases the eval thread and main thread
 are the same thread (i.e. the user's top C++ testbench runs on a single
 thread), but this is not required.
 
-The :vlopt:`--trace-threads` options can be used to produce trace dumps
-using multiple threads. If :vlopt:`--trace-threads` is set without
-:vlopt:`--threads`, then :vlopt:`--trace-threads` will imply
+When making frequent use of DPI imported functions in a multi-threaded
+model, it may be beneficial to performance to adjust the
+:vlopt:`--instr-count-dpi` option based on some experimentation. This
+influences the partitioning of the model by adjusting the assumed execution
+time of DPI imports.
+
+When using :vlopt:`--trace` to perform VCD tracing, the VCD trace
+construction is parallelized using the same number of threads as specified
+with :vlopt:`--threads`, and is executed on the same thread pool as the model.
+
+The :vlopt:`--trace-threads` options can be used with :vlopt:`--trace-fst`
+to offload FST tracing using multiple threads. If :vlopt:`--trace-threads` is
+given without :vlopt:`--threads`, then :vlopt:`--trace-threads` will imply
 :vlopt:`--threads 1 <--threads>`, i.e.: the support libraries will be
 thread safe.
 
@@ -226,12 +237,12 @@ With :vlopt:`--trace-threads 0 <--trace-threads>`, trace dumps are produced
 on the main thread. This again gives the highest single thread performance.
 
 With :vlopt:`--trace-threads {N} <--trace-threads>`, where N is at least 1,
-N additional threads will be created and managed by the trace files (e.g.:
-VerilatedVcdC or VerilatedFstC), to generate the trace dump. The main
-thread will be released to proceed with execution as soon as possible,
-though some blocking of the main thread is still necessary while capturing
-the trace. Different trace formats can utilize a various number of
-threads. See the :vlopt:`--trace-threads` option.
+up to N additional threads will be created and managed by the trace files
+(e.g.: VerilatedFstC), to offload construction of the trace dump. The main
+thread will be released to proceed with execution as soon as possible, though
+some blocking of the main thread is still necessary while capturing the
+trace. FST tracing can utilize up to 2 offload threads, so there is no use
+of setting :vlopt:`--trace-threads` higher than 2 at the moment.
 
 When running a multithreaded model, the default Linux task scheduler often
 works against the model, by assuming threads are short lived, and thus
@@ -260,7 +271,7 @@ This will limit memory to socket 0, and threads to cores 0, 1, 2, 3,
 (presumably on socket 0) optimizing performance.  Of course this must be
 adjusted if you want another simulator using e.g. socket 1, or if you
 Verilated with a different number of threads.  To see what CPUs are
-actually used, use :vlopt:`--prof-threads`.
+actually used, use :vlopt:`--prof-exec`.
 
 
 Multithreaded Verilog and Library Support
@@ -436,7 +447,7 @@ SystemC include directories and link to the SystemC libraries.
 
 .. describe:: TRACE_THREADS
 
-   Optional. Generated multi-threaded trace dumping, same as
+   Optional. Generated multi-threaded FST trace dumping, same as
    "--trace-threads".
 
 .. describe:: TOP_MODULE

docs/guide/warnings.rst

@@ -1,10 +1,11 @@
-.. Copyright 2003-2021 by Wilson Snyder.
+.. Copyright 2003-2022 by Wilson Snyder.
 .. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 *******************
 Errors and Warnings
 *******************
 
+.. _Disabling Warnings:
 
 Disabling Warnings
 ==================
@@ -12,7 +13,7 @@ Disabling Warnings
 Warnings may be disabled in multiple ways:
 
 #. Disable the warning in the source code.  When the warning is printed it
-   will include a warning code.  Simply surround the offending line with a
+   will include a warning code.  Surround the offending line with a
    :code:`/*verilator&32;lint_off*/` and :code:`/*verilator&32;lint_on*/`
    metacomment pair:
 
@@ -111,6 +112,8 @@ List Of Warnings
    simulators, however at one point this was a common style so disabled by
    default as a code style warning.
 
+   This warning is issued only if Verilator is run with :vlopt:`--no-timing`.
+
 
 .. option:: ASSIGNIN
 
@@ -130,9 +133,10 @@ List Of Warnings
 
 .. option:: BADSTDPRAGMA
 
-   Error that a pragma is badly formed, when that pragma is defined by IEEE1800-2017.
-   For example, an empty `pragma line, or an incorrect specified '`pragma protect'.
-   Note that 3rd party pragmas not defined by IEEE1800-2017 are ignored.
+   Error that a pragma is badly formed, when that pragma is defined by IEEE
+   1800-2017.  For example, an empty pragma line, or an incorrect specified
+   'pragma protect'.  Note that 3rd party pragmas not defined by IEEE
+   1800-2017 are ignored.
 
 
 .. option:: BLKANDNBLK
@@ -161,7 +165,7 @@ List Of Warnings
          always @(posedge clk)  foo[0] <= ...
          always_comb foo[1] = ...
 
-   Simply use a different register for the flop:
+   Instead use a different register for the flop:
 
    .. code-block:: sv
 
@@ -283,7 +287,7 @@ List Of Warnings
 
    .. TODO better example
 
-   Warns that it is simply better style to use casez, and "?" in place of
+   Warns that it is better style to use casez, and "?" in place of
    "x"'s.  See
    `http://www.sunburst-design.com/papers/CummingsSNUG1999Boston_FullParallelCase_rev1_1.pdf
    <http://www.sunburst-design.com/papers/CummingsSNUG1999Boston_FullParallelCase_rev1_1.pdf>`_
@@ -314,16 +318,16 @@ List Of Warnings
 
 .. option:: CLKDATA
 
-   .. TODO better example
+   Historical, never issued since version 5.000.
 
-   Warns that clock signal is mixed used with/as data signal. The checking
-   for this warning is enabled only if user has explicitly marked some
-   signal as clocker using command line option or in-source meta comment
-   (see :vlopt:`--clk`).
+   Warned that clock signal was mixed used with/as data signal. The
+   checking for this warning was enabled only if user has explicitly marked
+   some signal as clocker using command line option or in-source meta
+   comment (see :vlopt:`--clk`).
 
-   The warning can be disabled without affecting the simulation result. But
-   it is recommended to check the warning as this may degrade the
-   performance of the Verilated model.
+   The warning could be disabled without affecting the simulation
+   result. But it was recommended to check the warning as it may have
+   degraded the performance of the Verilated model.
 
 
 .. option:: CMPCONST
@@ -446,7 +450,7 @@ List Of Warnings
               p0();
          endmodule
 
-   Other tools with similar warnings: Veriable's forbid_defparam_rule.
+   Other tools with similar warnings: Verible's forbid_defparam_rule.
 
 
 .. option:: DEPRECATED
@@ -461,15 +465,11 @@ List Of Warnings
 
 .. option:: DETECTARRAY
 
-   .. TODO better example
+   Historical, never issued since version 3.862.
 
-   Error when Verilator tries to deal with a combinatorial loop that could
-   not be flattened, and which involves a datatype which Verilator cannot
-   handle, such as an unpacked struct or a large unpacked array. This
-   typically occurs when :vlopt:`-Wno-UNOPTFLAT <UNOPTFLAT>` has been used
-   to override an UNOPTFLAT warning (see below).
-
-   The solution is to break the loop, as described for UNOPTFLAT.
+   Was an error when Verilator tried to deal with a combinatorial loop that
+   could not be flattened, and which involves a datatype which Verilator
+   could not handle, such as an unpacked struct or a large unpacked array.
 
 
 .. option:: DIDNOTCONVERGE
@@ -481,39 +481,45 @@ List Of Warnings
 
    Faulty example:
 
-   .. code-block:: sv
+   .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_faulty.rst
 
-         always_comb b = ~a;
-         always_comb a = b
+   Results in at runtime (not when Verilated):
 
-   This code will toggle forever, and thus to prevent an infinite loop, the
-   executable will give the didn't converge error.
+   .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst
 
-   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 know if the logic
-   would eventually converge and assumed it would.
+   This is because the signals keep toggling even with out time
+   passing. Thus to prevent an infinite loop, the Verilated executable
+   gives the DIDNOTCONVERGE error.
+
+   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
+   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:
 
-   .. code-block::
+   .. include:: ../../docs/gen/ex_DIDNOTCONVERGE_msg.rst
 
-         CHANGE: filename.v:1: b
-         CHANGE: filename.v:2: a
-
-   This means that signal b and signal a keep changing, inspect the code
-   that modifies these signals.  Note if many signals are getting printed
-   then most likely all of them are oscillating.  It may also be that
-   e.g. "a" may be oscillating, then "a" feeds signal "c" which then is
-   also reported as oscillating.
+   The CHANGE line means that on the given filename and line number that
+   drove a signal, the signal 'a' kept changing. Inspect the code that
+   modifies these signals.  Note if many signals are getting printed then
+   most likely all of them are oscillating.  It may also be that e.g. "a"
+   may be oscillating, then "a" feeds signal "c" which then is also
+   reported as oscillating.
 
    One way DIDNOTCONVERGE may occur is flops are built out of gate
-   primitives.  error. Verilator does not support building flops or latches
-   out of gate primitives, and any such code must change to use behavioral
+   primitives. Verilator does not support building flops or latches out of
+   gate primitives, and any such code must change to use behavioral
    constructs (e.g. always_ff and always_latch).
 
+   Another way DIDNOTCONVERGE may occur is if # delays are used to generate
+   clocks if Verilator is run with :vlopt:`--no-timing`. In this mode,
+   Verilator ignores the delays and gives an :option:`ASSIGNDLY` or
+   :option:`STMTDLY` warning.  If these were suppressed, due to the absence of
+   the delay, the code may now oscillate.
+
    Finally, rare, more difficult cases can be debugged like a C++ program;
    either enter :command:`gdb` and use its tracing facilities, or edit the
    generated C++ code to add appropriate prints to see what is going on.
@@ -522,7 +528,7 @@ List Of Warnings
 .. option:: ENDCAPSULATED
 
    Warns that a class member is declared is local or protected, but is
-   being accessed from outside that class (if local) or a derrived class
+   being accessed from outside that class (if local) or a derived class
    (if protected).
 
    Ignoring this warning will only suppress the lint check, it will
@@ -572,7 +578,7 @@ List Of Warnings
    must end in newline, as otherwise for example :command:`cat` with the
    file as an argument may produce undesirable results.
 
-   Repair by adding a newline to the end of the file.
+   Repair by appending a newline to the end of the file.
 
    Disabled by default as this is a code style warning; it will simulate
    correctly.
@@ -583,9 +589,10 @@ List Of Warnings
 
 .. option:: GENCLK
 
-   Deprecated and no longer used as a warning.  Used to indicate that the
-   specified signal was is generated inside the model, and also being used
-   as a clock.
+   Historical, never issued since version 5.000.
+
+   Indicated that the specified signal was generated inside the model, and
+   was also being used as a clock.
 
 
 .. option:: HIERBLOCK
@@ -647,12 +654,12 @@ List Of Warnings
 
 .. option:: IMPERFECTSCH
 
-   .. TODO better example
+   Historical, never issued since version 5.000.
 
-   Warns that the scheduling of the model is not absolutely perfect, and
+   Warned that the scheduling of the model is not absolutely perfect, and
    some manual code edits may result in faster performance.  This warning
-   defaults to off, is not part of -Wall, and must be turned on explicitly
-   before the top module statement is processed.
+   defaulted to off, was not part of -Wall, and had to be turned on
+   explicitly before the top module statement is processed.
 
 
 .. option:: IMPLICIT
@@ -724,9 +731,9 @@ List Of Warnings
    Warns that a while or for statement has a condition that is always true.
    and thus results in an infinite loop if the statement ever executes.
 
-   This might be unintended behavior if the loop body contains statements
-   that in other simulators would make time pass, which Verilator is
-   ignoring due to e.g. ``STMTDLY`` warnings being disabled.
+   This might be unintended behavior if Verilator is run with
+   :vlopt:`--no-timing` and the loop body contains statements that would make
+   time pass otherwise.
 
    Ignoring this warning will only suppress the lint check, it will
    simulate correctly (i.e. hang due to the infinite loop).
@@ -787,13 +794,23 @@ List Of Warnings
    simulate correctly.
 
 
+.. option:: MINTYPMAX
+
+   .. code-block:: sv
+
+         #(3:5:8) clk = ~clk;
+
+   Warns that minimum, typical, and maximum delay expressions are currently
+   unsupported. Only the typical delay value is used by Verilator.
+
+
 .. option:: MODDUP
 
    .. TODO better example
 
    Warns that a module has multiple definitions.  Generally this indicates
-   a coding error, or a mistake in a library file and it's good practice to
-   have one module per file (and only put each file once on the command
+   a coding error, or a mistake in a library file, and it's good practice
+   to have one module per file (and only put each file once on the command
    line) to avoid these issues.  For some gate level netlists duplicates
    are sometimes unavoidable, and MODDUP should be disabled.
 
@@ -857,6 +874,13 @@ List Of Warnings
    input.
 
 
+.. option:: NEEDTIMINGOPT
+
+    Error when a timing-related construct, such as an event control or delay,
+    has been encountered, without specifying how Verilator should handle it
+    (neither :vlopt:`--timing` nor :vlopt:`--no-timing` option was provided).
+
+
 .. option:: NOLATCH
 
    .. TODO better example
@@ -869,6 +893,13 @@ List Of Warnings
    simulate correctly.
 
 
+.. option:: NOTIMING
+
+   Error when a timing-related construct that requires :vlopt:`--timing` has
+   been encountered. Issued only if Verilator is run with the
+   :vlopt:`--no-timing` option.
+
+
 .. option:: NULLPORT
 
    Warns that a null port was detected in the module definition port
@@ -918,7 +949,7 @@ List Of Warnings
    simulate correctly.
 
    Other tools with similar warnings: Icarus Verilog's portbind, "warning:
-   Instantiating module ... with dangling impot port (...)". Slang's
+   Instantiating module ... with dangling input port (...)". Slang's
    unconnected-port, "port '...' has no connection".
 
 
@@ -1005,9 +1036,25 @@ List Of Warnings
    a var/reg must be used as the target of procedural assignments.
 
 
+.. option:: PROFOUTOFDATE
+
+   Warns that threads were scheduled using estimated costs, despite the
+   fact that data was provided from profile-guided optimization (see
+   :ref:`Thread PGO`) as fed into Verilator using the
+   :option:`profile_data` configuration file option.  This usually
+   indicates that the profile data was generated from different Verilog
+   source code than Verilator is currently running against.
+
+   It is recommended to create new profiling data, then rerun Verilator
+   with the same input source files and that new profiling data.
+
+   Ignoring this warning may only slow simulations, it will simulate
+   correctly.
+
+
 .. option:: PROTECTED
 
-   Warning that a '`pragma protected' section was encountered. The code
+   Warning that a 'pragma protected' section was encountered. The code
    inside the protected region will be partly checked for correctness, but is
    otherwise ignored.
 
@@ -1090,6 +1137,16 @@ List Of Warnings
    "Duplicate macro arguments with name".
 
 
+.. option:: RISEFALLDLY
+
+   .. code-block:: sv
+
+         and #(1,2,3) AND (out, a, b);
+
+   Warns that rising, falling, and turn-off delays are currently unsupported.
+   The first (rising) delay is used for all cases.
+
+
 .. option:: SELRANGE
 
    Warns that a selection index will go out of bounds.
@@ -1183,9 +1240,27 @@ List Of Warnings
 
    Faulty example:
 
-   .. code-block:: sv
+   .. include:: ../../docs/gen/ex_STMTDLY_faulty.rst
 
-         #100 $finish;  //<--- Warning
+   Results in:
+
+   .. include:: ../../docs/gen/ex_STMTDLY_msg.rst
+
+   This warning is issued only if Verilator is run with :vlopt:`--no-timing`.
+   All delays on statements are ignored in this mode.  In many cases ignoring a
+   delay might be harmless, but if the delayed statement is, as in this
+   example, used to cause some important action at a later time, it might be an
+   important difference.
+
+   Some possible workarounds:
+
+   * Move the delayed statement into the C++ wrapper file, where the
+     stimulus and clock generation can be done in C++.
+
+   * Convert the statement into a FSM, or other statement that tests
+     against $time.
+
+   * Run Verilator with :vlopt:`--timing`.
 
 
 .. option:: SYMRSVDWORD
@@ -1317,23 +1392,12 @@ List Of Warnings
 
 .. option:: UNOPT
 
-   .. TODO better example
+   Historical, never issued since version 5.000.
 
-   Warns that due to some construct, optimization of the specified signal
-   or block is disabled.  The construct should be cleaned up to improve
-   simulation performance.
+   Warned that due to some construct, optimization of the specified signal
+   or block was disabled.
 
-   A less obvious case of this is when a module instantiates two
-   submodules.  Inside submodule A, signal I is input and signal O is
-   output.  Likewise in submodule B, signal O is an input and I is an
-   output.  A loop exists and a UNOPT warning will result if AI & AO both
-   come from and go to combinatorial blocks in both submodules, even if
-   they are unrelated always blocks.  This affects performance because
-   Verilator would have to evaluate each submodule multiple times to
-   stabilize the signals crossing between the modules.
-
-   Ignoring this warning will only slow simulations, it will simulate
-   correctly.
+   Ignoring this warning only slowed simulations, it simulated correctly.
 
 
 .. option:: UNOPTFLAT
@@ -1347,13 +1411,11 @@ List Of Warnings
    performance; two times better performance may be possible by fixing
    these warnings.
 
-   Unlike the ``UNOPT`` warning, this occurs after flattening the netlist,
-   and indicates a more basic problem, as the less obvious case described
-   under ``UNOPT`` does not apply.
-
    Often UNOPTFLAT is caused by logic that isn't truly circular as viewed by
    synthesis which analyzes interconnection per-bit, but is circular to
-   simulation which analyzes per-bus:
+   simulation which analyzes per-bus.
+
+   Faulty example:
 
    .. code-block:: sv
 
@@ -1401,15 +1463,15 @@ List Of Warnings
    the conflict. If you run with `--report-unoptflat` Verilator will
    suggest possible candidates for :option:`/*verilator&32;split_var*/`.
 
-   The UNOPTFLAT warning may also be due to clock enables, identified from
-   the reported path going through a clock gating instance.  To fix these,
-   use the clock_enable meta comment described above.
-
    The UNOPTFLAT warning may also occur where outputs from a block of logic
    are independent, but occur in the same always block.  To fix this, use
    the :option:`/*verilator&32;isolate_assignments*/` metacomment described
    above.
 
+   Prior to version 5.000, the UNOPTFLAT warning may also have been due to
+   clock enables, identified from the reported path going through a clock
+   gating instance.  To fix these, the clock_enable meta comment was used.
+
    To assist in resolving UNOPTFLAT, the option :vlopt:`--report-unoptflat`
    can be used, which will provide suggestions for variables that can be
    split up, and a graph of all the nodes connected in the loop. See the
@@ -1466,16 +1528,45 @@ List Of Warnings
    Error that a construct might be legal according to IEEE but is not
    currently supported by Verilator.
 
+   A typical workaround is to rewrite the construct into a simpler and more
+   common alternative language construct.
+
+   Alternatively, check if the construct is supported by other tools, and
+   if so please consider submitting a github pull request against the
+   Verilator sources to implement the missing unsupported feature.
+
    This error may be ignored with :vlopt:`--bbox-unsup`, however this will
-   make the design simulate incorrectly; see the details under
-   :vlopt:`--bbox-unsup`.
+   make the design simulate incorrectly and is only intended for lint
+   usage; see the details under :vlopt:`--bbox-unsup`.
 
 
 .. option:: UNUSED
 
+   Disabling/enabling UNUSED is equivalent to disabling/enabling the
+   `UNUSEDGENVAR`, `UNUSEDPARAM` and `UNUSEDSIGNAL` warnings.
+
+   Never issued since version 5.000.  Historically warned that a variable,
+   parameter, or signal was unused.
+
+.. option:: UNUSEDGENVAR
+
    .. TODO better example
 
-   Warns that the specified signal or parameter is never used/consumed.
+   Warns that the specified genvar is never used/consumed.
+
+
+.. option:: UNUSEDPARAM
+
+   .. TODO better example
+
+   Warns that the specified parameter is never used/consumed.
+
+
+.. option:: UNUSEDSIGNAL
+
+   .. TODO better example
+
+   Warns that the specified signal is never used/consumed.
    Verilator is fairly liberal in the usage calculations; making a signal
    public, a signal matching the :vlopt:`--unused-regexp` option (default
    "\*unused\*" or accessing only a single array element marks the entire
@@ -1588,6 +1679,16 @@ List Of Warnings
    To resolve, rename the variable to a unique name.
 
 
+.. option:: WAITCONST
+
+   .. code-block:: sv
+
+         wait(0);  // Blocks forever
+
+   Warns that a `wait` statement awaits a constant condition, which means it
+   either blocks forever or never blocks.
+
+
 .. option:: WIDTH
 
    Warns that based on width rules of Verilog:
@@ -1598,7 +1699,7 @@ List Of Warnings
    * A part select has a different size then needed to index into the
      packed or unpacked array (etc).
 
-   Verilator for attempts to track the minimum width of unsized constants
+   Verilator attempts to track the minimum width of unsized constants
    and will suppress the warning when the minimum width is appropriate to
    fit the required size.
 
@@ -1607,11 +1708,13 @@ List Of Warnings
 
    The recommendation is to fix these issues by:
 
-   * Resizing the variable or constant.  E.g. :code:`2'd2` instead of :code:`3'd2`.
+   * Resizing the variable or constant to match the needed size for the
+     expression.  E.g. :code:`2'd2` instead of :code:`3'd2`.
 
-   * Using :code:`'0` or :code:`'1`.
+   * Using :code:`'0` or :code:`'1` which automatically resize in an
+     expression.
 
-   * Using part select to narrow a variable. E.g. :code:`too_wide[1:0]`.
+   * Using part selects to narrow a variable. E.g. :code:`too_wide[1:0]`.
 
    * Using concatenate to widen a variable. E.g. :code:`{1'b1, too_narrow}`.
 
@@ -1653,3 +1756,11 @@ List Of Warnings
    The correct fix is to either size the 1 (:code:`32'h1`), or add the
    width to the parameter definition (:code:`parameter [31:0]`), or add the
    width to the parameter usage (:code:`{PAR[31:0], PAR[31:0]}`).
+
+
+.. option:: ZERODLY
+
+   Warns that `#0` delays do not schedule the process to be resumed in the
+   Inactive region. Such processes do get resumed in the same time slot
+   somewhere in the Active region. Issued only if Verilator is run with the
+   :vlopt:`--timing` option.

docs/internals.rst

@@ -96,10 +96,11 @@ this.
 Each ``AstNode`` has pointers to up to four children, accessed by the
 ``op1p`` through ``op4p`` methods. These methods are then abstracted in a
 specific Ast\* node class to a more specific name. For example with the
-``AstIf`` node (for ``if`` statements), ``ifsp`` calls ``op2p`` to give the
+``AstIf`` node (for ``if`` statements), ``thensp`` calls ``op2p`` to give the
 pointer to the AST for the "then" block, while ``elsesp`` calls ``op3p`` to
 give the pointer to the AST for the "else" block, or NULL if there is not
-one.
+one. These accessors are automatically generated by ``astgen`` after
+parsing the ``@astgen`` directives in the specific ``AstNode`` subclasses.
 
 ``AstNode`` has the concept of a next and previous AST - for example the
 next and previous statements in a block. Pointers to the AST for these
@@ -114,11 +115,11 @@ By convention, each function/method uses the variable ``nodep`` as a
 pointer to the ``AstNode`` currently being processed.
 
 
-``AstNVisitor``
+``VNVisitor``
 ^^^^^^^^^^^^^^^
 
 The passes are implemented by AST visitor classes. These are implemented by
-subclasses of the abstract class, ``AstNVisitor``. Each pass creates an
+subclasses of the abstract class, ``VNVisitor``. Each pass creates an
 instance of the visitor class, which in turn implements a method to perform
 the pass.
 
@@ -183,6 +184,568 @@ A number of predefined derived algorithm classes and access methods are
 provided and documented in ``V3GraphAlg.cpp``.
 
 
+``DfgGraph``
+^^^^^^^^^^^^^
+
+The data-flow graph based combinational logic optimizer (DFG optimizer)
+converts an ``AstModule`` into a ``DfgGraph``. The graph represents the
+combinational equations (~continuous assignments) in the module, and for the
+duration of the DFG passes, it takes over the role of the represented
+``AstModule``. The ``DfgGraph`` keeps holds of the represented ``AstModule``,
+and the ``AstModule`` retains all other logic that is not representable as a
+data-flow graph. At the end of optimization, the combinational logic
+represented by the ``DfgGraph`` is converted back into AST form and is
+re-inserted into the corresponding ``AstModule``. The ``DfgGraph`` is distinct
+from ``V3Graph`` for efficiency and other desirable properties which make
+writing DFG passes easier.
+
+
+``DfgVertex``
+^^^^^^^^^^^^^
+
+The ``DfgGraph`` represents combinational logic equations as a graph of
+``DfgVertex`` vertices. Each sub-class of ``DfgVertex`` corresponds to an
+expression (a sub-class of ``AstNodeMath``), a constanat, or a variable
+reference. LValues and RValues referencing the same storage location are
+represented by the same ``DfgVertex``. Consumers of such vertices read as the
+LValue, writers of such vertices write the RValue. The bulk of the final
+``DfgVertex`` sub-classes are generated by ``astgen`` from the corresponding
+``AstNode`` definitions.
+
+
+Scheduling
+----------
+
+Verilator implements the Active and NBA regions of the SystemVerilog scheduling
+model as described in IEEE 1800-2017 chapter 4, and in particular sections
+4.5 and Figure 4.1. The static (verilation time) scheduling of SystemVerilog
+processes is performed by code in the ``V3Sched`` namespace. The single
+entry-point to the scheduling algorithm is ``V3Sched::schedule``. Some
+preparatory transformations important for scheduling are also performed in
+``V3Active`` and ``V3ActiveTop``. High level evaluation functions are
+constructed by ``V3Order``, which ``V3Sched`` invokes on subsets of the logic
+in the design.
+
+Scheduling deals with the problem of evaluating 'logic' in the correct order
+and the correct number of times in order to compute the correct state of the
+SystemVerilog program. Throughout this section, we use the term 'logic' to
+refer to all SystemVerilog constructs that describe the evolution of the state
+of the program. In particular, all SystemVerilog processes and continuous
+assignments are considered 'logic', but not for example variable definitions
+without initialization or other miscellaneous constructs.
+
+
+Classes of logic
+^^^^^^^^^^^^^^^^
+
+The first step in the scheduling algorithm is to gather all the logic present
+in the design, and classify it based on the conditions under which the logic
+needs to be evaluated.
+
+The classes of logic we distinguish between are:
+
+- SystemVerilog ``initial`` processes, that need to be executed once at
+  startup.
+
+- Static variable initializers. These are a separate class as they need to be
+  executed before ``initial`` processes.
+
+- SystemVerilog ``final`` processes.
+
+- Combinational logic. Any process or construct that has an implicit
+  sensitivity list with no explicit sensitivities is considered 'combinational'
+  logic. This includes among other things, ``always @*`` and ``always_comb``
+  processes, and continuous assignments. Verilator also converts some other
+  ``always`` processes to combinational logic in ``V3Active`` as described
+  below.
+
+- Clocked logic. Any process or construct that has an explicit sensitivity
+  list, with no implicit sensitivities is considered 'clocked' (or
+  'sequential') logic. This includes among other things ``always`` and
+  ``always_ff`` processes with an explicit sensitivity list.
+
+Note that the distinction between clocked logic and combinational logic is only
+important for the scheduling algorithm within Verilator as we handle the two
+classes differently. It is possible to convert clocked logic into combinational
+logic if the explicit sensitivity list of the clocked logic is the same as the
+implicit sensitivity list of the equivalent combinational logic would be. The
+canonical examples are: ``always @(a) x = a;``, which is considered to be
+clocked logic by Verilator, and the equivalent ``assign x = a;``, which is
+considered to be combinational logic. ``V3Active`` in fact converts all clocked
+logic to combinational logic whenever possible, as this provides advantages for
+scheduling as described below.
+
+There is also a 'hybrid' logic class, which has both explicit and implicit
+sensitivities. This kind of logic does not arise from a SystemVerilog
+construct, but is created during scheduling to break combinational cycles.
+Details of this process and the hybrid logic class are described below.
+
+
+Scheduling of simple classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SystemVerilog ``initial`` and ``final`` blocks can be scheduled (executed) in an
+arbitrary order.
+
+Static variable initializers need to be executed in source code order in case
+there is a dependency between initializers, but the ordering of static variable
+initialization is otherwise not defined by the SystemVerilog standard
+(particularly, in the presence of hierarchical references in static variable
+initializers).
+
+The scheduling algorithm handles all three of these classes the same way and
+schedules the logic in these classes in source code order. This step yields the
+``_eval_static``, ``_eval_initial`` and ``_eval_final`` functions which execute
+the corresponding logic constructs.
+
+
+Scheduling of clocked and combinational logic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For performance, clocked and combinational logic needs to be ordered.
+Conceptually this minimizes the iterations through the evaluation loop
+presented in the reference algorithm in the SystemVerilog standard (IEEE
+1800-2017 section 4.5), by evaluating logic constructs in data-flow order.
+Without going into a lot of detail here, accept that well thought out ordering
+is crucial to good simulation performance, and also enables further
+optimizations later on.
+
+At the highest level, ordering is performed by ``V3Order::order``, which is
+invoked by ``V3Sched::schedule`` on various subsets of the combinational and
+clocked logic as described below. The important thing to highlight now is that
+``V3Order::order`` operates by assuming that the state of all variables driven
+by combinational logic are consistent with that combinational logic. While this
+might seem subtle, it is very important, so here is an example:
+
+::
+  always_comb d = q + 2;
+  always @(posedge clock) q <= d;
+
+
+During ordering, ``V3Order`` will assume that ``d`` equals ``q + 2`` at the
+beginning of an evaluation step. As a result it will order the clocked logic
+first, and all downstream combinational logic (like the assignment to ``d``)
+will execute after the clocked logic that drives inputs to the combinational
+logic, in data-flow (or dependency) order. At the end of the evaluation step,
+this ordering restores the invariant that variables driven by combinational
+logic are consistent with that combinational logic (i.e.: the circuit is in a
+settled/steady state).
+
+One of the most important optimizations for performance is to only evaluate
+combinational logic, if its inputs might have changed. For example, there is no
+point in evaluating the above assignment to ``d`` on a negative edge of the
+clock signal. Verilator does this by pushing the combinational logic into the
+same (possibly multiple) event domains as the logic driving the inputs to that
+combinational logic, and only evaluating the combinational logic if at least
+one driving domains have been triggered. The impact of this activity gating is
+very high (observed 100x slowdown on large designs when turning it off), it is
+the reason we prefer to convert clocked logic to combinational logic in
+``V3Active`` whenever possible.
+
+The ordering procedure described above works straight forward unless there are
+combinational logic constructs that are circularly dependent (a.k.a.: the
+UNOPTFLAT warning). Combinational scheduling loops can arise in sound
+(realizable) circuits as Verilator considers each SystemVerilog process as a
+unit of scheduling (albeit we do try to split processes into smaller ones to
+avoid this circularity problem whenever possible, this is not always possible).
+
+
+Breaking combinational loops
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Combinational loops are broken by the introduction of instances of the 'hybrid'
+logic class. As described in the previous section, combinational loops require
+iteration until the logic is settled, in order to restore the invariant that
+combinationally driven signals are consistent with the combinational logic.
+
+To achieve this, ``V3Sched::schedule`` calls ``V3Sched::breakCycles``, which
+builds a dependency graph of all combinational logic in the design, and then
+breaks all combinational cycles by converting all combinational logic that
+consumes a variable driven via a 'back-edge' into hybrid logic. Here
+'back-edge' just means a graph edge that points from a higher rank vertex to a
+lower rank vertex in some consistent ranking of the directed graph. Variables
+driven via a back-edge in the dependency graph are marked, and all
+combinational logic that depends on such variables is converted into hybrid
+logic, with the back-edge driven variables listed as explicit 'changed'
+sensitivities.
+
+Hybrid logic is handled by ``V3Order`` mostly in the same way as combinational
+logic, with two exceptions:
+
+- Explicit sensitivities of hybrid logic are ignored for the purposes of
+  data-flow ordering with respect to other combinational or hybrid logic. I.e.:
+  an explicit sensitivity suppresses the implicit sensitivity on the same
+  variable. This cold also be interpreted as ordering the hybrid logic as if
+  all variables listed as explicit sensitivities were substituted as constants
+  with their current values.
+
+- The explicit sensitivities are included as an additional driving domain of
+  the logic, and also cause evaluation when triggered.
+
+This means that hybrid logic is evaluated when either any of its implicit
+sensitivities might have been updated (the same way as combinational logic, by
+pushing it into the domains that write those variables), or if any of its
+explicit sensitivities are triggered.
+
+The effect of this transformation is that ``V3Order`` can proceed as if there
+are no combinational cycles (or alternatively, under the assumption that the
+back-edge driven variables don't change during one evaluation pass). The
+evaluation loop invoking the ordered code, will then re-invoke it on a follow
+on iteration, if any of the explicit sensitivities of hybrid logic have
+actually changed due to the previous invocation, iterating until all the
+combinational (including hybrid) logic have settled.
+
+One might wonder if there can be a race condition between clocked logic
+triggered due to a combinational signal change from the previous evaluation
+pass, and a combinational loop settling due to hybrid logic, if the clocked
+logic reads the not yet settled combinationally driven signal. Such a race is
+indeed possible, but our evaluation is consistent with the SystemVerilog
+scheduling semantics (IEEE 1800-2017 chapter 4), and therefore any program that
+exhibits such a race has non-deterministic behaviour according to the
+SystemVerilog semantics, so we accept this.
+
+
+Settling combinational logic after initialization
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+At the beginning of simulation, once static initializer and ``initial`` blocks
+have been executed, we need to evaluate all combinational logic, in order to
+restore the invariant utilized by ``V3Order`` that the state of all
+combinationally driven variables are consistent with the combinational logic.
+
+To achieve this, we invoke ``V3Order::order`` on all of the combinational and
+hybrid logic, and iterate the resulting evaluation function until no more
+hybrid logic is triggered. This yields the `_eval_settle` function which is
+invoked at the beginning of simulation, after the `_eval_initial`.
+
+
+Partitioning logic for correct NBA updates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``V3Order`` can order logic corresponding to non-blocking assignments (NBAs) to
+yield correct simulation results, as long as all the sensitivity expressions of
+clocked logic triggered in the Active scheduling region of the current time
+step are known up front. I.e.: the ordering of NBA updates is only correct if
+derived clocks that are computed in an Active region update (that is, via a
+blocking or continuous assignment) are known up front.
+
+We can ensure this by partitioning the logic into two regions. Note these
+regions are a concept of the Verilator scheduling algorithm and they do not
+directly correspond to the similarly named SystemVerilog scheduling regions
+as defined in the standard:
+
+- All logic (clocked, combinational and hybrid) that transitively feeds into,
+  or drives, via a non-blocking or continuous assignments (or via any update
+  that SystemVerilog executes in the Active scheduling region), a variable that
+  is used in the explicit sensitivity list of some clocked or hybrid logic, is
+  assigned to the 'act' region.
+
+- All other logic is assigned to the 'nba' region.
+
+For completeness, note that a subset of the 'act' region logic, specifically,
+the logic related to the pre-assignments of NBA updates (i.e.: AstAssignPre
+nodes), is handled separately, but is executed as part of the 'act' region.
+
+Also note that all logic representing the committing of an NBA (i.e.: Ast*Post)
+nodes) will be in the 'nba' region. This means that the evaluation of the 'act'
+region logic will not commit any NBA updates. As a result, the 'act' region
+logic can be iterated to compute all derived clock signals up front.
+
+The correspondence between the SystemVerilog Active and NBA scheduling regions,
+and the internal 'act' and 'nba' regions, is that 'act' contains all Active
+region logic that can compute a clock signal, while 'nba' contains all other
+Active and NBA region logic. For example, if the only clocks in the design are
+top level inputs, then 'act' will be empty, and 'nba' will contain the whole of
+the design.
+
+The partitioning described above is performed by ``V3Sched::partition``.
+
+
+Replication of combinational logic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We will separately invoke ``V3Order::order`` on the 'act' and 'nba' region
+logic.
+
+Combinational logic that reads variables driven from both 'act' and 'nba'
+region logic has the problem of needing to be re-evaluated even if only one of
+the regions updates an input variable. We could pass additional trigger
+expressions between the regions to make sure combinational logic is always
+re-evaluated, or we can replicate combinational logic that is driven from
+multiple regions, by copying it into each region that drives it. Experiments
+show this simple replication works well performance-wise (and notably
+``V3Combine`` is good at combining the replicated code), so this is what we do
+in ``V3Sched::replicateLogic``.
+
+In ``V3Sched::replicateLogic``, in addition to replicating logic into the 'act'
+and 'nba' regions, we also replicate combinational (and hybrid) logic that
+depends on top level inputs. These become a separate 'ico' region (Input
+Combinational logic), which we will always evaluate at the beginning of a
+time-step to ensure the combinational invariant holds even if input signals
+have changed. Note that this eliminates the need of changing data and clock
+signals on separate evaluations, as was necessary with earlier versions of
+Verilator).
+
+
+Constructing the top level `_eval` function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To construct the top level `_eval` function, which updates the state of the
+circuit to the end of the current time step, we invoke ``V3Order::order``
+separately on the 'ico', 'act' and 'nba' logic, which yields the `_eval_ico`,
+`_eval_act`, and `_eval_nba` functions. We then put these all together with the
+corresponding functions that compute the respective trigger expressions into
+the top level `_eval` function, which on the high level has the form:
+
+::
+  void _eval() {
+    // Update combinational logic dependent on top level inptus ('ico' region)
+    while (true) {
+      _eval__triggers__ico();
+      // If no 'ico' region trigger is active
+      if (!ico_triggers.any()) break;
+      _eval_ico();
+    }
+
+
+    // Iterate 'act' and 'nba' regions together
+    while (true) {
+
+      // Iterate 'act' region, this computes all derived clocks updaed in the
+      // Active scheduling region, but does not commit any NBAs that executed
+      // in 'act' region logic.
+      while (true) {
+        _eval__triggers__act();
+        // If no 'act' region trigger is active
+        if (!act_triggers.any()) break;
+        // Remember what 'act' triggers were active, 'nba' uses the same
+        latch_act_triggers_for_nba();
+        _eval_act();
+      }
+
+
+      // If no 'nba' region trigger is active
+      if (!nba_triggers.any()) break;
+
+      // Evaluate all other Active region logic, and commti NBAs
+      _eval_nba();
+    }
+  }
+
+
+Timing
+------
+
+Timing support in Verilator utilizes C++ coroutines, which is a new feature in
+C++20. The basic idea is to represent processes and tasks that await a certain
+event or simulation time as coroutines. These coroutines get suspended at the
+await, and resumed whenever the triggering event occurs, or at the expected
+simulation time.
+
+There are several runtime classes used for managing such coroutines defined in
+``verilated_timing.h`` and ``verilated_timing.cpp``.
+
+``VlCoroutineHandle``
+^^^^^^^^^^^^^^^^^^^^^
+
+A thin wrapper around an ``std::coroutine_handle<>``. It forces move semantics,
+destroys the coroutine if it remains suspended at the end of the design's
+lifetime, and prevents multiple ``resume`` calls in the case of
+``fork..join_any``.
+
+``VlCoroutine``
+^^^^^^^^^^^^^^^
+
+Return value of all coroutines. Together with the promise type contained
+within, it allows for chaining coroutines – resuming coroutines from up the
+call stack. The calling coroutine's handle is saved in the promise object as a
+continuation, that is, the coroutine that must be resumed after the promise's
+coroutine finishes. This is necessary as C++ coroutines are stackless, meaning
+each one is suspended independently of others in the call graph.
+
+``VlDelayScheduler``
+^^^^^^^^^^^^^^^^^^^^
+
+This class manages processes suspended by delays. There is one instance of this
+class per design. Coroutines ``co_await`` this object's ``delay`` function.
+Internally, they are stored in a heap structure sorted by simulation time in
+ascending order. When ``resume`` is called on the delay scheduler, all
+coroutines awaiting the current simulation time are resumed. The current
+simulation time is retrieved from a ``VerilatedContext`` object.
+
+``VlTriggerScheduler``
+^^^^^^^^^^^^^^^^^^^^^^
+
+This class manages processes that await events (triggers). There is one such
+object per each trigger awaited by coroutines. Coroutines ``co_await`` this
+object's ``trigger`` function. They are stored in two stages – `uncommitted`
+and `ready`. First, they land in the `uncommitted` stage, and cannot be
+resumed. The ``resume`` function resumes all coroutines from the `ready` stage
+and moves `uncommitted` coroutines into `ready`. The ``commit`` function only
+moves `uncommitted` coroutines into `ready`.
+
+This split is done to avoid self-triggering and triggering coroutines multiple
+times. See the `Scheduling with timing` section for details on how this is
+used.
+
+``VlDynamicTriggerScheduler``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Like ``VlTriggerScheduler``, ``VlDynamicTriggerScheduler`` manages processes
+that await triggers. However, it does not rely on triggers evaluated externally
+by the 'act' trigger eval function. Instead, it is also responsible for trigger
+evaluation. Coroutines that make use of this scheduler must adhere to a certain
+procedure:
+
+::
+  __Vtrigger = 0;
+  <locals and inits required for trigger eval>
+  while (!__Vtrigger) {
+      co_await __VdynSched.evaluation();
+      <pre updates>;
+      __Vtrigger = <trigger eval>;
+      [optionally] co_await __VdynSched.postUpdate();
+      <post updates>;
+  }
+  co_await __VdynSched.resumption();
+
+The coroutines get resumed at trigger evaluation time, evaluate their local
+triggers, optionally await the post update step, and if the trigger is set,
+await proper resumption in the 'act' eval step.
+
+``VlForkSync``
+^^^^^^^^^^^^^^
+
+Used for synchronizing ``fork..join`` and ``fork..join_any``. Forking
+coroutines ``co_await`` its ``join`` function, and forked ones call ``done``
+when they're finished. Once the required number of coroutines (set using
+``setCounter``) finish execution, the forking coroutine is resumed.
+
+Awaitable utilities
+^^^^^^^^^^^^^^^^^^^
+
+There are also two small utility awaitable types:
+
+* ``VlNow`` is an awaitable that suspends and immediately resumes coroutines.
+  It is used for forcing a coroutine to be moved onto the heap. See the `Forks`
+  section for more detail.
+* ``VlForever`` is used for blocking a coroutine forever. See the `Timing pass`
+  section for more detail.
+
+Timing pass
+^^^^^^^^^^^
+
+The visitor in ``V3Timing.cpp`` transforms each timing control into a ``co_await``.
+
+* event controls are turned into ``co_await`` on a trigger scheduler's
+  ``trigger`` method. The awaited trigger scheduler is the one corresponding to
+  the sentree referenced by the event control. This sentree is also referenced
+  by the ``AstCAwait`` node, to be used later by the static scheduling code.
+* if an event control waits on a local variable or class member, it uses a
+  local trigger which it evaluates inline. It awaits a dynamic trigger
+  scheduler multiple times: for trigger evaluation, updates, and resumption.
+  The dynamic trigger scheduler is responsible for resuming the coroutine at
+  the correct point of evaluation.
+* delays are turned into ``co_await`` on a delay scheduler's ``delay`` method.
+  The created ``AstCAwait`` nodes also reference a special sentree related to
+  delays, to be used later by the static scheduling code.
+* ``join`` and ``join_any`` are turned into ``co_await`` on a ``VlForkSync``'s
+  ``join`` method. Each forked process gets a ``VlForkSync::done`` call at the
+  end.
+
+Assignments with intra-assignment timing controls are simplified into
+assignments after those timing controls, with the LHS and RHS values evaluated
+before them and stored in temporary variables.
+
+``wait`` statements are transformed into while loops that check the condition
+and then await changes in variables used in the condition. If the condition is
+always false, the ``wait`` statement is replaced by a ``co_await`` on a
+``VlForever``. This is done instead of a return in case the ``wait`` is deep in
+a call stack (otherwise the coroutine's caller would continue execution).
+
+Each sub-statement of a ``fork`` is put in an ``AstBegin`` node for easier
+grouping. In a later step, each of these gets transformed into a new, separate
+function. See the `Forks` section for more detail.
+
+Processes that use awaits are marked as suspendable. Later, during ``V3Sched``,
+they are transformed into coroutines. Functions that use awaits get the return
+type of ``VlCoroutine``. This immediately makes them coroutines. Note that if a
+process calls a function that is a coroutine, the call gets wrapped in an
+await, which means the process itself will be marked as suspendable. A virtual
+function is a coroutine if any of its overriding or overridden functions are
+coroutines. The visitor keeps a dependency graph of functions and processes to
+handle such cases.
+
+Scheduling with timing
+^^^^^^^^^^^^^^^^^^^^^^
+
+Timing features in Verilator are built on top of the static scheduler. Triggers
+are used for determining which delay or trigger schedulers should resume. A
+special trigger is used for the delay scheduler. This trigger is set if there
+are any coroutines awaiting the current simulation time
+(``VlDelayScheduler::awaitingCurrentTime()``).
+
+All triggers used by a suspendable process are mapped to variables written in
+that process. When ordering code using ``V3Order``, these triggers are provided
+as external domains of these variables. This ensures that the necessary
+combinational logic is triggered after a coroutine resumption.
+
+There are two functions for managing timing logic called by ``_eval()``:
+
+* ``_timing_commit()``, 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.
+
+Thanks to this separation, a coroutine awaiting a trigger cannot be suspended
+and resumed in the same iteration, and it cannot be resumed before it suspends.
+
+All coroutines are committed and resumed in the 'act' eval loop. With timing
+features enabled, the ``_eval()`` function takes this form:
+
+::
+  void _eval() {
+    while (true) {
+      _eval__triggers__ico();
+      if (!ico_triggers.any()) break;
+      _eval_ico();
+    }
+
+    while (true) {
+      while (true) {
+        _eval__triggers__act();
+
+        // Commit all non-triggered coroutines
+        _timing_commit();
+
+        if (!act_triggers.any()) break;
+        latch_act_triggers_for_nba();
+
+        // Resume all triggered coroutines
+        _timing_resume();
+
+        _eval_act();
+      }
+      if (!nba_triggers.any()) break;
+      _eval_nba();
+    }
+  }
+
+Forks
+^^^^^
+
+After the scheduling step, forks sub-statements are transformed into separate
+functions, and these functions are called in place of the sub-statements. These
+calls must be without ``co_await``, so that suspension of a forked process
+doesn't suspend the forking process.
+
+In forked processes, references to local variables are only allowed in
+``fork..join``, as this is the only case that ensures the lifetime of these
+locals is at least as long as the execution of the forked processes. This is
+where ``VlNow`` is used, to ensure the locals are moved to the heap before they
+are passed by reference to the forked processes.
+
+
 Multithreaded Mode
 ------------------
 
@@ -268,13 +831,13 @@ Estimating Logic Costs
 
 To compute the cost of any given path through the graph, Verilator
 estimates an execution cost for each task. Each macro-task has an execution
-cost which is simply the sum of its tasks' costs. We assume that
-communication overhead and synchronization overhead are zero, so the cost
-of any given path through the graph is simply the sum of macro-task
-execution costs. Sarkar does almost the same thing, except that he has
-nonzero estimates for synchronization costs.
+cost which is the sum of its tasks' costs. We assume that communication
+overhead and synchronization overhead are zero, so the cost of any given
+path through the graph is the sum of macro-task execution costs. Sarkar
+does almost the same thing, except that he has nonzero estimates for
+synchronization costs.
 
-Verilator's cost estimates are assigned by ``InstrCountCostVisitor``.  This
+Verilator's cost estimates are assigned by ``InstrCountVisitor``.  This
 class is perhaps the most fragile piece of the multithread
 implementation. It's easy to have a bug where you count something cheap
 (eg. accessing one element of a huge array) as if it were expensive (eg.
@@ -301,7 +864,7 @@ prerequisites on other threads have finished.
 
 The synchronization cost is cheap if the prereqs are done. If they're not,
 fragmentation (idle CPU cores waiting) is possible. This is the major
-source of overhead in this approach. The ``--prof-threads`` switch and the
+source of overhead in this approach. The ``--prof-exec`` switch and the
 ``verilator_gantt`` script can visualize the time lost to such
 fragmentation.
 
@@ -405,6 +968,9 @@ routines in the sources to rely more heavily on randomness, and
 generally try harder not to keep input nodes together when we have the
 option to scramble things.
 
+Profile-guided optimization make this a bit better, by adjusting mtask
+scheduling, but this does not yet guide the packing into mtasks.
+
 
 Performance Regression
 """"""""""""""""""""""
@@ -498,32 +1064,117 @@ code:
 The ``astgen`` Script
 ---------------------
 
-Some of the code implementing passes is extremely repetitive, and must be
-implemented for each sub-class of ``AstNode``. However, while repetitive,
-there is more variability than can be handled in C++ macros.
+The ``astgen`` script is used to generate some of the repetitive C++ code
+related to the ``AstNode`` type hierarchy. An example is the abstract ``visit``
+methods in ``VNVisitor``. There are other uses, please see the ``*__gen*``
+files in the bulid directories and the ``astgen`` script itself for details.  A
+description of the more advanced features of ``astgen`` are provided here.
 
-In Verilator this is implemented by using a script, ``astgen`` to
-pre-process the C++ code. For example in ``V3Const.cpp`` this is used to
-implement the ``visit()`` functions for each binary operation using the
-``TREEOP`` macro.
 
-The original C source code is transformed into C code in the ``obj_opt``
+Generating ``AstNode`` members
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some of the member s of ``AstNode`` sub-classes are generated by ``astgen``.
+These are emitted as pre-processor macro definitions, which then need to be
+added to the ``AstNode`` sub-classes they correspond to. Specifically ``class
+AstFoo`` should contain an instance of ``ASTGEN_MEMBERS_AstFoo;`` at class
+scope.  The ``astgen`` script checks and errors if this is not present. The
+method generated depends on whether the class is a concrete final class, or an
+abstract ``AstNode*`` base-class, and on ``@astgen`` directives present in
+comment sections in the body of the ``AstNode`` sub-class definitions.
+
+
+List of ``@astgen`` directives
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``@astgen`` directives in comments contained in the body of ``AstNode``
+sub-class definitions are parsed and contribute to the code generated by
+``astgen``. The general syntax is ``@astgen <keywords> := <description>``,
+where ``<keywords>`` determines what is being defined, and ``<description>`` is
+a ``<keywords>`` dependent description of the definition. The list of
+``@astgen`` directives is as follows:
+
+
+``op<N>`` operand  directives
+"""""""""""""""""""""""""""""
+
+The ``op1``, ``op2``, ``op3`` and ``op4`` directives are used to describe the
+name and type of the up to 4 child operands of a node. The syntax of the
+``<description>`` field is ``<identifier> : <type>``, where ``<identifier>``
+will be used as the base name of the generated operand accessors, and
+``<type>`` is one of:
+
+1. An ``AstNode`` sub-class, defining the operand to be of that type, always
+   no-null, and with an always null ``nextp()``. That is, the child node is
+   always present, and is a single ``AstNode`` (as opposed to a list).
+
+2. ``Optional[<AstNode sub-class>]``. This is just like in point 1 above, but
+   defines the child node to be optional, meaning it may be null.
+
+3. ``List[AstNode sub-class]`` describes a list operand, which means the child
+   node may have a non-null ``nextp()`` and in addition the child itself may be
+   null, representing an empty list.
+
+
+An example of the full syntax of the directive is
+``@astgen op1 := lhsp : AstNodeMath``.
+
+``astnode`` generates accessors for the child nodes based on these directives.
+For non-list children, the names of the getter and setter both are that of the
+given ``<identifier>``. For list type children, the getter is ``<identifier>``,
+and instead of the setter, there an ``add<Identifier>`` method is generated
+that appends new nodes (or lists of nodes) to the child list.
+
+
+``alias op<N>`` operand alias directives
+""""""""""""""""""""""""""""""""""""""""
+
+If a super-class already defined a name and type for a child node using the
+``op<N>`` directive, but a more appropriate name exists in the context of a
+sub-class, then the alias directive can be used to introduce an additional name
+for the child node. The is ``alias op<N> := <identifier>`` where
+``<identifier>`` is the new name. ``op<N>`` must have been defined in some
+super-class of the current node.
+
+Example: ``@astgen alias op1 := condp``
+
+
+Generating ``DfgVertex`` sub-classes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Most of the ``DfgVertex`` sub-classes are generated by ``astgen``, from the
+definitions of the corresponding ``AstNode`` vertices.
+
+
+Additional features of ``astgen``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to generating ``AstNode`` members as described above,
+``astgen`` is also use to handle some of the repetitive implementation code
+that is still variable enough not to be handled in C++ macros.
+
+In particular, ``astgen`` is used to pre-process some of the C++ source
+files. For example in ``V3Const.cpp``, it is used to implement the
+``visit()`` functions for each binary operation using the ``TREEOP`` macro.
+
+The original C++ source code is transformed into C++ code in the ``obj_opt``
 and ``obj_dbg`` sub-directories (the former for the optimized version of
 Verilator, the latter for the debug version). So for example
 ``V3Const.cpp`` into ``V3Const__gen.cpp``.
 
 
-Visitor Functions -----------------
+Visitor Functions
+-----------------
 
 Verilator uses the "Visitor" design pattern to implement its refinement and
 optimization passes. This allows separation of the pass algorithm from the
 AST on which it operates. Wikipedia provides an introduction to the concept
 at https://en.wikipedia.org/wiki/Visitor_pattern.
 
-As noted above, all visitors are derived classes of ``AstNVisitor``. All
+As noted above, all visitors are derived classes of ``VNVisitor``. All
 derived classes of ``AstNode`` implement the ``accept`` method, which takes
-as argument a reference to an instance or a ``AstNVisitor`` derived class
-and applies the visit method of the ``AstNVisitor`` to the invoking AstNode
+as argument a reference to an instance or a ``VNVisitor`` derived class
+and applies the visit method of the ``VNVisitor`` to the invoking AstNode
 instance (i.e. ``this``).
 
 One possible difficulty is that a call to ``accept`` may perform an edit
@@ -601,8 +1252,8 @@ There are three ways data is passed between visitor functions.
 Iterators
 ---------
 
-``AstNVisitor`` provides a set of iterators to facilitate walking over
-the tree. Each operates on the current ``AstNVisitor`` class (as this)
+``VNVisitor`` provides a set of iterators to facilitate walking over
+the tree. Each operates on the current ``VNVisitor`` class (as this)
 and takes an argument type ``AstNode*``.
 
 ``iterate``
@@ -814,7 +1465,7 @@ which you can install using cpan.
 
 There are some traps to avoid when running regression tests
 
-- When checking the MANIFEST, the test will barf on unexpected code in the
+- When checking the MANIFEST, the test will fail on unexpected code in the
   Verilator tree. So make sure to keep any such code outside the tree.
 
 - Not all Linux systems install Perldoc by default. This is needed for the
@@ -1056,6 +1707,16 @@ Similarly the ``NETLIST`` has a list of modules referred to by its
 ``op1p()`` pointer.
 
 
+.tree.dot Output
+----------------
+
+``*.tree.dot`` files are dumps of the AST Tree in `Graphviz
+<https://www.graphviz.org>`__ dot format. This can be used to
+visualize the AST Tree. The vertices correspond to ``AstNode``
+instances, and the edges represent the pointers (``op1p``,
+ ``op2p``, etc) between the nodes.
+
+
 Debugging with GDB
 ------------------
 
@@ -1150,8 +1811,9 @@ Generally what would you do to add a new feature?
    language and has a lot of back-and-forth with Verilator's grammar. Copy
    the appropriate rules to src/verilog.y and modify the productions.
 
-4. If a new Ast type is needed, add it to V3AstNodes.h. Follow the
-   convention described above about the AstNode type hierarchy.
+4. If a new Ast type is needed, add it to the appropriate V3AstNode*.h.
+   Follow the convention described above about the AstNode type hierarchy.
+   Ordering of definitions is enforced by ``astgen``.
 
 5. Now you can run "test_regress/t/t_<newtestcase>.pl --debug" and it'll
    probably fail but you'll see a
@@ -1180,10 +1842,10 @@ Verilator ideally would support all of IEEE, and has the goal to get close
 to full support. However the following IEEE sections and features are not
 anticipated to be ever implemented for the reasons indicated.
 
-IEEE 1800-2017 3.3 recursive modules
+IEEE 1800-2017 3.3 modules within modules
     Little/no tool support, and arguably not a good practice.
 IEEE 1800-2017 6.12 "shortreal"
-    Little/no tool support, and easily simply promoted to real.
+    Little/no tool support, and easily promoted to real.
 IEEE 1800-2017 11.11 Min, typ, max
     No SDF support so will always use typical.
 IEEE 1800-2017 11.12 "let"
@@ -1205,7 +1867,7 @@ IEEE 1800-2017 33 Config
 Distribution
 ============
 
-Copyright 2008-2021 by Wilson Snyder. Verilator is free software; you can
+Copyright 2008-2022 by Wilson Snyder. 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.
 

docs/spelling.txt

@@ -2,15 +2,19 @@ ABCp
 Accellera
 Affe
 Aleksander
+Alexandre
 Ami
 Amir
 Anastasiadis
+Anikin
+Antmicro
 Antonin
 Antwerpen
 Arasanipalai
 Arjen
 Asciidoc
 Ashutosh
+Ast
 Atmel
 Aurelien
 Bagri
@@ -70,6 +74,7 @@ Eda
 Eddleston
 Egbert
 Egil
+Ehab
 Eiler
 Eivind
 El
@@ -82,6 +87,7 @@ Fabrizio
 Fekete
 Ferrandi
 Flachs
+Flavien
 Foletto
 Forker
 Francillon
@@ -104,7 +110,10 @@ Goessling
 Gonnen
 Goorah
 Gossner
+Graphviz
+Graybeal
 Grobman
+Grulfen
 Gunter
 Guo
 Hao
@@ -121,10 +130,12 @@ Hornung
 Hossell
 Hsu
 Hyperthreading
+Ibrahim
 Iles
 Inlines
 Inout
 Iru
+Iyer
 Iztok
 Jacko
 Jae
@@ -134,6 +145,7 @@ Jannis
 Jens
 Jeras
 Jiuyang
+Joannou
 Joly
 Jullien
 Junji
@@ -147,8 +159,10 @@ Kamendje
 Kandadi
 Kaplan
 Karge
+Karlsson
 Katz
 Katzman
+Kelin
 Keren
 Keyi
 Kimmitt
@@ -161,6 +175,7 @@ Kolecki
 Koonce
 Korteland
 Koszek
+Kouping
 Kravitz
 Krolnik
 Kruse
@@ -194,6 +209,7 @@ Mednick
 Michiels
 Microsystems
 Milanovic
+Millis
 MinW
 Mindspeed
 Miodrag
@@ -224,12 +240,14 @@ Petr
 Piechotka
 Piersall
 Plunkett
+Popolon
 Popov
 Prabhat
 Prabhu
 Prateek
 Pre
 Preprocess
+Pretet
 Priyadharshini
 Pullup
 Pulver
@@ -262,12 +280,15 @@ Shi
 Shinkarovsky
 Shirakawa
 Shuba
+Shunyao
 Slatter
 SoC
 Sobhan
 Sokorac
 Solaris
 Solomatnikov
+Solt
+Southwell
 Srini
 Stamness
 Stephane
@@ -286,6 +307,7 @@ SystemVerilog
 Takatsukasa
 Tambe
 Tariq
+Tejada
 Tengstrand
 Terpstra
 Thiede
@@ -293,8 +315,10 @@ Thierry
 Thyer
 Tichelaar
 Tomov
+Tood
 Topa
 Tota
+Trefor
 Tresidder
 Tri
 Tristate
@@ -304,11 +328,13 @@ Ubixum
 Uints
 Undefines
 Unsized
+Urbach
 Uselib
 Usha
 Usuario
 VERILATOR
 Vasu
+Vdeeptemp
 Vdly
 Vemumtab
 Vemuri
@@ -320,6 +346,7 @@ Verilating
 Verilation
 Verilator
 Verilog
+Vighnesh
 Viktor
 Vm
 Vukobratovic
@@ -351,9 +378,12 @@ Zhang
 abirkmanis
 accessor
 accessors
+adrienlemasle
 agrobman
+ahouska
 al
 ala
+algrobman
 andit
 ar
 architected
@@ -372,8 +402,13 @@ backtrace
 backtraces
 basename
 bbox
+benchmarking
 biguint
 biops
+bisonpre
+bitOpTree
+bitOpTree
+bitop
 bitstoreal
 blackbox
 bokke
@@ -389,6 +424,7 @@ casez
 casted
 cb
 ccache
+ccall
 cdc
 ceil
 celldefine
@@ -411,7 +447,10 @@ concat
 concats
 config
 const
+constexpr
+constpool
 coredump
+coroutine
 countbits
 countones
 cout
@@ -426,6 +465,7 @@ da
 dat
 datadir
 datafiles
+david
 ddd
 deassign
 debugi
@@ -433,7 +473,9 @@ defenv
 defname
 defparam
 demangling
+dep
 der
+dereference
 desassign
 destructor
 detections
@@ -449,6 +491,7 @@ dsvf
 dtor
 dumpall
 dumpfile
+dumpi
 dumplimit
 dumpoff
 dumpon
@@ -462,6 +505,7 @@ dumpvars
 dut
 dx
 elab
+elike
 elsif
 endcase
 endcelldefine
@@ -480,15 +524,18 @@ enums
 env
 envvar
 eof
+errae
 erroring
 et
 eval
+evals
 exe
 executables
 expr
 extern
 fanin
 fasttrace
+fauto
 fbranch
 fclose
 fdisplay
@@ -502,7 +549,9 @@ filesystem
 filt
 flto
 flushCall
+fno
 fopen
+forceable
 foreach
 fprintf
 fprofile
@@ -521,6 +570,7 @@ funcs
 fwrite
 gantt
 gcc
+gcda
 gdb
 genblk
 genvar
@@ -552,6 +602,7 @@ incdir
 includer
 inferfaces
 inhibitSim
+initarray
 initializer
 initializers
 inits
@@ -562,6 +613,7 @@ inouts
 inserted
 instantiation
 instantiations
+intra
 iostream
 ish
 isunbounded
@@ -570,6 +622,7 @@ killua
 lang
 lcov
 ld
+leavinel
 len
 libext
 libgoogle
@@ -584,6 +637,7 @@ ln
 loc
 localparam
 localparams
+localtime
 logicals
 longint
 lsb
@@ -618,6 +672,7 @@ multithreaded
 multithreading
 mutexes
 mux
+myftptoyman
 mysignal
 namespace
 nand
@@ -642,15 +697,19 @@ onehot
 ooo
 oprofile
 oversubscription
+parallelized
 param
 parameterized
 params
 parens
+pawel
 pc
 pdf
 perf
 perftools
+pgo
 picoChip
+pinIndex
 pinout
 plusargs
 pmos
@@ -676,10 +735,11 @@ prev
 printf
 printtimescale
 profcfunc
-profcfuncs
+profiler
 prototyptes
 ps
 pthread
+ptr
 pulldown
 pulldowns
 pullup
@@ -704,12 +764,15 @@ regs
 reloop
 resetall
 respecified
+rodata
+rolloverSize
 rr
 rst
 runtime
 runtimes
 rw
 sVerilator
+sawatzke
 sc
 scalared
 sccanf
@@ -717,6 +780,7 @@ seg
 setuphold
 sformat
 sformatf
+shareefj
 shortint
 shortreal
 signame
@@ -725,6 +789,7 @@ specparam
 splitme
 spp
 sqrt
+src
 srcdir
 srcfile
 sscanf
@@ -744,6 +809,7 @@ subcells
 subexpressions
 submodule
 submodules
+substring
 sv
 svBitVal
 svBitVecVal
@@ -778,6 +844,7 @@ trunc
 txt
 typ
 typedef
+typedef'ed
 typedefed
 typedefs
 typename
@@ -791,6 +858,7 @@ uniquified
 unistd
 unlink
 unlinked
+unnamedblk
 unopt
 unoptflat
 unoptimizable
@@ -840,11 +908,14 @@ writeme
 writemem
 writememb
 writememh
+xiak
 xin
 xml
 xnor
 xout
 xuejiazidi
 yanx
+ypq
 yurivict
 zdave
+Øyvind

docs/xml.rst

@@ -46,9 +46,6 @@ The XML document consists of 4 sections within the top level
    hierarchy. Each instance is represented with the ``<cell>`` element
    with the following attributes:
 
-   -  ``fl`` (deprecated): The file id and line number where the module
-      was instanced. Use ``loc`` instead.
-
    -  ``loc``: The file id, first line number, last line number, first
       column number and last column number of the identifier where the
       module was instanced, separated by commas.
@@ -73,7 +70,7 @@ The XML document consists of 4 sections within the top level
 Distribution
 ============
 
-Copyright 2020-2021 by Wilson Snyder. Verilator is free software; you can
+Copyright 2020-2022 by Wilson Snyder. 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.
 

examples/cmake_hello_sc/Makefile

@@ -39,30 +39,12 @@ ifneq ($(CMAKE_GT_3_8),true)
 TARGET := oldcmake
 else
 
-# Test existence of SYSTEMC_INCLUDE and SYSTEMC_LIBDIR environment variabless
-ifneq (,$(SYSTEMC_INCLUDE))
-ifneq (,${SYSTEMC_LIBDIR})
-SYSTEMC_SET := true
-endif
-endif
-
-# Test existence of SYSTEMC_ROOT environment variable
-ifneq (SYSTEMC_SET, true)
-ifneq (,${SYSTEMC_ROOT})
-SYSTEMC_SET := true
-endif
-endif
-
-# Test existence of SYSTEMC environment variable
-ifneq (SYSTEMC_SET, true)
-ifneq (,${SYSTEMC})
-SYSTEMC_SET := true
-endif
-endif
+# Check if SC exists via a verilator call (empty if not)
+SYSTEMC_EXISTS := $(shell $(VERILATOR) --get-supported SYSTEMC)
 
 # Test whether SystemC is installed with CMake support
 # This will print a CMake error about processing arguments that can (currently) be ignored.
-ifneq (SYSTEMC_SET, true)
+ifneq (,$(SYSTEMC_EXISTS))
 FINDSC := $(shell mkdir -p build && cd build && cmake --find-package -DNAME=SystemCLanguage -DCMAKE_USE_PTHREADS_INIT=ON -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST -DThreads_FOUND=ON)
 ifneq (,$(findstring SystemCLanguage found,$(FINDSC)))
 SYSTEMC_SET := true
@@ -99,7 +81,7 @@ run:
 
 	@echo "-- DONE --------------------"
 	@echo "Note: Once this example is understood, see examples/cmake_tracing_sc."
-	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
+	@echo "Note: See also https://verilator.org/guide/latest/examples.html"
 
 clean mostlyclean distclean maintainer-clean:
 	@rm -rf build logs

examples/cmake_tracing_c/CMakeLists.txt

@@ -33,5 +33,5 @@ add_executable(example ../make_tracing_c/sim_main.cpp)
 # Add the Verilated circuit to the target
 verilate(example COVERAGE TRACE
   INCLUDE_DIRS "../make_tracing_c"
-  VERILATOR_ARGS -f ../make_tracing_c/input.vc -Os -x-assign 0
+  VERILATOR_ARGS -f ../make_tracing_c/input.vc -x-assign fast
   SOURCES ../make_tracing_c/top.v)

examples/cmake_tracing_sc/CMakeLists.txt

@@ -45,7 +45,7 @@ set_property(
 # Add the Verilated circuit to the target
 verilate(example SYSTEMC COVERAGE TRACE
   INCLUDE_DIRS "../make_tracing_sc"
-  VERILATOR_ARGS -f ../make_tracing_sc/input.vc -Os -x-assign 0
+  VERILATOR_ARGS -f ../make_tracing_sc/input.vc -x-assign fast
   SOURCES ../make_tracing_sc/top.v)
 
 verilator_link_systemc(example)

examples/cmake_tracing_sc/Makefile

@@ -39,30 +39,12 @@ ifneq ($(CMAKE_GT_3_8),true)
 TARGET := oldcmake
 else
 
-# Test existence of SYSTEMC_INCLUDE and SYSTEMC_LIBDIR environment variabless
-ifneq (,$(SYSTEMC_INCLUDE))
-ifneq (,${SYSTEMC_LIBDIR})
-SYSTEMC_SET := true
-endif
-endif
-
-# Test existence of SYSTEMC_ROOT environment variable
-ifneq (SYSTEMC_SET, true)
-ifneq (,${SYSTEMC_ROOT})
-SYSTEMC_SET := true
-endif
-endif
-
-# Test existence of SYSTEMC environment variable
-ifneq (SYSTEMC_SET, true)
-ifneq (,${SYSTEMC})
-SYSTEMC_SET := true
-endif
-endif
+# Check if SC exists via a verilator call (empty if not)
+SYSTEMC_EXISTS := $(shell $(VERILATOR) --get-supported SYSTEMC)
 
 # Test whether SystemC is installed with CMake support
 # This will print a CMake error about processing arguments that can (currently) be ignored.
-ifneq (SYSTEMC_SET, true)
+ifneq (,$(SYSTEMC_EXISTS))
 FINDSC := $(shell mkdir -p build && cd build && cmake --find-package -DNAME=SystemCLanguage -DCMAKE_USE_PTHREADS_INIT=ON -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST -DThreads_FOUND=ON)
 ifneq (,$(findstring SystemCLanguage found,$(FINDSC)))
 SYSTEMC_SET := true

examples/make_hello_binary/.gitignore

@@ -0,0 +1,6 @@
+*.dmp
+*.log
+*.csrc
+*.vcd
+obj_*
+logs

examples/make_hello_binary/Makefile

@@ -0,0 +1,49 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: Small Makefile
+#
+# This calls the object directory makefile.  That allows the objects to
+# be placed in the "current directory" which simplifies the Makefile.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+# Check for sanity to avoid later confusion
+
+ifneq ($(words $(CURDIR)),1)
+ $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)')
+endif
+
+######################################################################
+
+# This is intended to be a minimal example.  Before copying this to start a
+# real project, it is better to start with a more complete example,
+# e.g. examples/make_tracing_c.
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+endif
+
+default:
+	@echo "-- Verilator hello-world simple binary example"
+	@echo "-- VERILATE & BUILD --------"
+	$(VERILATOR) --binary -j 0 top.v
+	@echo "-- RUN ---------------------"
+	obj_dir/Vtop
+	@echo "-- DONE --------------------"
+	@echo "Note: Once this example is understood, see examples/make_hello_c."
+	@echo "Note: See also https://verilator.org/guide/latest/examples.html"
+
+######################################################################
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir *.log *.dmp *.vpd core

examples/make_hello_binary/top.v

@@ -0,0 +1,14 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2017 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+
+// See also https://verilator.org/guide/latest/examples.html"
+
+module top;
+   initial begin
+      $display("Hello World!");
+      $finish;
+   end
+endmodule

examples/make_hello_c/Makefile

@@ -40,7 +40,7 @@ default:
 	obj_dir/Vtop
 	@echo "-- DONE --------------------"
 	@echo "Note: Once this example is understood, see examples/make_tracing_c."
-	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
+	@echo "Note: See also https://verilator.org/guide/latest/examples.html"
 
 ######################################################################
 

examples/make_hello_c/sim_main.cpp

@@ -21,11 +21,14 @@ int main(int argc, char** argv, char** env) {
     // Prevent unused variable warnings
     if (false && argc && argv && env) {}
 
+    // Construct a VerilatedContext to hold simulation time, etc.
+    VerilatedContext* contextp = new VerilatedContext;
+
     // Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
-    Vtop* top = new Vtop;
+    Vtop* top = new Vtop{contextp};
 
     // Simulate until $finish
-    while (!Verilated::gotFinish()) {
+    while (!contextp->gotFinish()) {
 
         // Evaluate model
         top->eval();

examples/make_hello_c/top.v

@@ -4,7 +4,8 @@
 // any use, without warranty, 2017 by Wilson Snyder.
 // SPDX-License-Identifier: CC0-1.0
 
-// See also the EXAMPLE section in the verilator manpage/document.
+// See also https://verilator.org/guide/latest/examples.html"
+
 module top;
    initial begin
       $display("Hello World!");

examples/make_hello_sc/Makefile

@@ -33,7 +33,7 @@ VERILATOR = $(VERILATOR_ROOT)/bin/verilator
 endif
 
 # Check if SC exists via a verilator call (empty if not)
-SYSTEMC_EXISTS := $(shell $(VERILATOR) --getenv SYSTEMC_INCLUDE)
+SYSTEMC_EXISTS := $(shell $(VERILATOR) --get-supported SYSTEMC)
 
 ifneq ($(SYSTEMC_EXISTS),)
 default: run
@@ -49,7 +49,7 @@ run:
 	obj_dir/Vtop
 	@echo "-- DONE --------------------"
 	@echo "Note: Once this example is understood, see examples/make_tracing_sc."
-	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
+	@echo "Note: See also https://verilator.org/guide/latest/examples.html"
 
 ######################################################################
 

examples/make_hello_sc/top.v

@@ -4,7 +4,8 @@
 // any use, without warranty, 2017 by Wilson Snyder.
 // SPDX-License-Identifier: CC0-1.0
 
-// See also the EXAMPLE section in the verilator manpage/document.
+// See also https://verilator.org/guide/latest/examples.html"
+
 module top;
    initial begin
       $display("Hello World!");

examples/make_protect_lib/Makefile

@@ -33,7 +33,7 @@ VERILATOR_FLAGS =
 # Generate C++
 VERILATOR_FLAGS += -cc
 # Optimize
-VERILATOR_FLAGS += -Os -x-assign 0
+VERILATOR_FLAGS += -x-assign fast
 # Warn abount lint issues; may not want this on less solid designs
 VERILATOR_FLAGS += -Wall
 # This example does not use vl_time_stamp but rather

examples/make_protect_lib/sim_main.cpp

@@ -32,7 +32,7 @@ int main(int argc, char** argv, char** env) {
     // When tracing, the contents of the secret module will not be seen
     VerilatedVcdC* tfp = nullptr;
     const char* flag = contextp->commandArgsPlusMatch("trace");
-    if (flag && 0 == strcmp(flag, "+trace")) {
+    if (flag && 0 == std::strcmp(flag, "+trace")) {
         contextp->traceEverOn(true);
         VL_PRINTF("Enabling waves into logs/vlt_dump.vcd...\n");
         tfp = new VerilatedVcdC;

examples/make_protect_lib/top.v

@@ -4,7 +4,8 @@
 // any use, without warranty, 2019 by Todd Strader.
 // SPDX-License-Identifier: CC0-1.0
 
-// See also the EXAMPLE section in the verilator manpage/document.
+// See also https://verilator.org/guide/latest/examples.html"
+
 module top (input clk);
 
    integer cyc = 0;

examples/make_tracing_c/Makefile

@@ -36,7 +36,7 @@ VERILATOR_FLAGS += -cc --exe
 # Generate makefile dependencies (not shown as complicates the Makefile)
 #VERILATOR_FLAGS += -MMD
 # Optimize
-VERILATOR_FLAGS += -Os -x-assign 0
+VERILATOR_FLAGS += -x-assign fast
 # Warn abount lint issues; may not want this on less solid designs
 VERILATOR_FLAGS += -Wall
 # Make waveforms

examples/make_tracing_c/sim_main.cpp

@@ -34,6 +34,8 @@ int main(int argc, char** argv, char** env) {
     // Using unique_ptr is similar to
     // "VerilatedContext* contextp = new VerilatedContext" then deleting at end.
     const std::unique_ptr<VerilatedContext> contextp{new VerilatedContext};
+    // Do not instead make Vtop as a file-scope static variable, as the
+    // "C++ static initialization order fiasco" may cause a crash
 
     // Set debug level, 0 is off, 9 is highest presently used
     // May be overridden by commandArgs argument parsing
@@ -69,7 +71,7 @@ int main(int argc, char** argv, char** env) {
         // Historical note, before Verilator 4.200 Verilated::gotFinish()
         // was used above in place of contextp->gotFinish().
         // Most of the contextp-> calls can use Verilated:: calls instead;
-        // the Verilated:: versions simply assume there's a single context
+        // the Verilated:: versions just assume there's a single context
         // being used (per thread).  It's faster and clearer to use the
         // newer contextp-> versions.
 
@@ -103,8 +105,8 @@ int main(int argc, char** argv, char** env) {
         top->eval();
 
         // Read outputs
-        VL_PRINTF("[%" VL_PRI64 "d] clk=%x rstl=%x iquad=%" VL_PRI64 "x"
-                  " -> oquad=%" VL_PRI64 "x owide=%x_%08x_%08x\n",
+        VL_PRINTF("[%" PRId64 "] clk=%x rstl=%x iquad=%" PRIx64 " -> oquad=%" PRIx64
+                  " owide=%x_%08x_%08x\n",
                   contextp->time(), top->clk, top->reset_l, top->in_quad, top->out_quad,
                   top->out_wide[2], top->out_wide[1], top->out_wide[0]);
     }

examples/make_tracing_sc/Makefile

@@ -37,7 +37,7 @@ VERILATOR_FLAGS += -sc --exe
 # Generate makefile dependencies (not shown as complicates the Makefile)
 #VERILATOR_FLAGS += -MMD
 # Optimize
-VERILATOR_FLAGS += -Os -x-assign 0
+VERILATOR_FLAGS += -x-assign fast
 # Warn abount lint issues; may not want this on less solid designs
 VERILATOR_FLAGS += -Wall
 # Make waveforms
@@ -55,7 +55,7 @@ VERILATOR_FLAGS += --coverage
 VERILATOR_INPUT = -f input.vc top.v sc_main.cpp
 
 # Check if SC exists via a verilator call (empty if not)
-SYSTEMC_EXISTS := $(shell $(VERILATOR) --getenv SYSTEMC_INCLUDE)
+SYSTEMC_EXISTS := $(shell $(VERILATOR) --get-supported SYSTEMC)
 
 ######################################################################
 

examples/make_tracing_sc/sc_main.cpp

@@ -58,11 +58,11 @@ int sc_main(int argc, char* argv[]) {
 
     // Define interconnect
     sc_signal<bool> reset_l;
-    sc_signal<vluint32_t> in_small;
-    sc_signal<vluint64_t> in_quad;
+    sc_signal<uint32_t> in_small;
+    sc_signal<uint64_t> in_quad;
     sc_signal<sc_bv<70>> in_wide;
-    sc_signal<vluint32_t> out_small;
-    sc_signal<vluint64_t> out_quad;
+    sc_signal<uint32_t> out_small;
+    sc_signal<uint64_t> out_quad;
     sc_signal<sc_bv<70>> out_wide;
 
     // Construct the Verilated model, from inside Vtop.h
@@ -82,14 +82,14 @@ int sc_main(int argc, char* argv[]) {
 
     // You must do one evaluation before enabling waves, in order to allow
     // SystemC to interconnect everything for testing.
-    sc_start(1, SC_NS);
+    sc_start(SC_ZERO_TIME);
 
 #if VM_TRACE
     // If verilator was invoked with --trace argument,
     // and if at run time passed the +trace argument, turn on tracing
     VerilatedVcdSc* tfp = nullptr;
     const char* flag = Verilated::commandArgsPlusMatch("trace");
-    if (flag && 0 == strcmp(flag, "+trace")) {
+    if (flag && 0 == std::strcmp(flag, "+trace")) {
         cout << "Enabling waves into logs/vlt_dump.vcd...\n";
         tfp = new VerilatedVcdSc;
         top->trace(tfp, 99);  // Trace 99 levels of hierarchy

examples/xml_py/vl_file_copy

@@ -16,12 +16,13 @@ from shutil import copy2
 
 
 class VlFileCopy:
+
     def __init__(
-        self,
-        verilator_args,  # presently all verilator options are passed-thru
-        # ideally this script would check against options mentioned in help
+            self,
+            verilator_args,  # presently all verilator options are passed-thru
+            # ideally this script would check against options mentioned in help
         debug=0,
-        output_dir='copied'):  # directory name we output file uses
+            output_dir='copied'):  # directory name we output file uses
 
         self.debug = debug
 

examples/xml_py/vl_hier_graph

@@ -14,12 +14,13 @@ import xml.etree.ElementTree as ET
 
 
 class VlHierGraph:
+
     def __init__(
-        self,
-        verilator_args,  # presently all verilator options are passed-thru
-        # ideally this script would check against options mentioned in help
+            self,
+            verilator_args,  # presently all verilator options are passed-thru
+            # ideally this script would check against options mentioned in help
         debug=0,
-        output_filename='graph.dot'):  # output filename
+            output_filename='graph.dot'):  # output filename
         self.debug = debug
         self.next_vertex_number = 0
         self.name_to_number = {}

include/gtkwave/fstapi.c

@@ -140,6 +140,10 @@ void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint3
 #include <sys/sysctl.h>
 #endif
 
+#if defined(FST_MACOSX) || defined(__MINGW32__) || defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__)
+#define FST_UNBUFFERED_IO
+#endif
+
 #ifdef __GNUC__
 /* Boolean expression more often true than false */
 #define FST_LIKELY(x) __builtin_expect(!!(x), 1)
@@ -4577,12 +4581,11 @@ if(sectype == FST_BL_ZWRAPPER)
                 if(!fcomp) { tmpfile_close(&fcomp, &xc->f_nam); return(0); }
                 }
 
-#if defined(FST_MACOSX)
+#if defined(FST_UNBUFFERED_IO)
         setvbuf(fcomp, (char *)NULL, _IONBF, 0);   /* keeps gzip from acting weird in tandem with fopen */
 #endif
 
 #ifdef __MINGW32__
-        setvbuf(fcomp, (char *)NULL, _IONBF, 0);   /* keeps gzip from acting weird in tandem with fopen */
         xc->filename_unpacked = hf;
 #else
         if(hf)
@@ -4880,7 +4883,7 @@ if((!nam)||(!(xc->f=fopen(nam, "rb"))))
         char *hf = (char *)calloc(1, flen + 6);
         int rc;
 
-#if defined(__MINGW32__) || defined(FST_MACOSX)
+#if defined(FST_UNBUFFERED_IO)
         setvbuf(xc->f, (char *)NULL, _IONBF, 0);   /* keeps gzip from acting weird in tandem with fopen */
 #endif
 
@@ -4989,9 +4992,7 @@ unsigned int secnum = 0;
 int blocks_skipped = 0;
 fst_off_t blkpos = 0;
 uint64_t seclen, beg_tim;
-#ifdef FST_DEBUG
 uint64_t end_tim;
-#endif
 uint64_t frame_uclen, frame_clen, frame_maxhandle, vc_maxhandle;
 fst_off_t vc_start;
 fst_off_t indx_pntr, indx_pos;
@@ -5058,14 +5059,11 @@ for(;;)
         if(!seclen) break;
 
         beg_tim = fstReaderUint64(xc->f);
-#ifdef FST_DEBUG
-        end_tim =
-#endif
-        fstReaderUint64(xc->f);
+        end_tim = fstReaderUint64(xc->f);
 
         if(xc->limit_range_valid)
                 {
-                if(beg_tim < xc->limit_range_start)
+                if(end_tim < xc->limit_range_start)
                         {
                         blocks_skipped++;
                         blkpos += seclen;

include/verilated.mk.in

@@ -2,7 +2,7 @@
 ######################################################################
 # DESCRIPTION: Makefile commands for all verilated target files
 #
-# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -23,12 +23,12 @@ CFG_WITH_LONGTESTS = @CFG_WITH_LONGTESTS@
 CFG_CXXFLAGS_PROFILE = @CFG_CXXFLAGS_PROFILE@
 # Select newest language
 CFG_CXXFLAGS_STD_NEWEST = @CFG_CXXFLAGS_STD_NEWEST@
-# Select oldest language (for Verilator internal testing only)
-CFG_CXXFLAGS_STD_OLDEST = @CFG_CXXFLAGS_STD_OLDEST@
 # Compiler flags to use to turn off unused and generated code warnings, such as -Wno-div-by-zero
 CFG_CXXFLAGS_NO_UNUSED = @CFG_CXXFLAGS_NO_UNUSED@
 # Compiler flags that turn on extra warnings
 CFG_CXXFLAGS_WEXTRA = @CFG_CXXFLAGS_WEXTRA@
+# Compiler flags that enable coroutine support
+CFG_CXXFLAGS_COROUTINES = @CFG_CXXFLAGS_COROUTINES@
 # Linker libraries for multithreading
 CFG_LDLIBS_THREADS = @CFG_LDLIBS_THREADS@
 
@@ -58,6 +58,7 @@ VK_CPPFLAGS_ALWAYS += \
 		-DVM_SC=$(VM_SC) \
 		-DVM_TRACE=$(VM_TRACE) \
 		-DVM_TRACE_FST=$(VM_TRACE_FST) \
+		-DVM_TRACE_VCD=$(VM_TRACE_VCD) \
 		$(CFG_CXXFLAGS_NO_UNUSED) \
 
 ifeq ($(CFG_WITH_CCWARN),yes)	# Local... Else don't burden users
@@ -143,23 +144,9 @@ ifneq ($(VM_THREADS),0)
  endif
 endif
 
-ifneq ($(VM_TRACE_THREADS),0)
- ifneq ($(VM_TRACE_THREADS),)
-  ifeq ($(findstring -DVL_THREADED,$(CPPFLAGS)),)
-   $(error VM_TRACE_THREADS requires VM_THREADS)
-  endif
-  CPPFLAGS += -DVL_TRACE_THREADED
-  VK_C11=1
-  VK_LIBS_THREADED=1
- endif
-endif
-
-
-ifneq ($(VM_TRACE_FST_WRITER_THREAD),0)
- ifneq ($(VM_TRACE_FST_WRITER_THREAD),)
-  CPPFLAGS += -DVL_TRACE_FST_WRITER_THREAD
-  VK_C11=1
-  VK_LIBS_THREADED=1
+ifneq ($(VM_TIMING),0)
+ ifneq ($(VM_TIMING),)
+  CPPFLAGS += $(CFG_CXXFLAGS_COROUTINES)
  endif
 endif
 
@@ -188,13 +175,17 @@ VM_SLOW += $(VM_CLASSES_SLOW) $(VM_SUPPORT_SLOW)
 VK_FAST_OBJS = $(addsuffix .o, $(VM_FAST))
 VK_SLOW_OBJS = $(addsuffix .o, $(VM_SLOW))
 
-VK_USER_OBJS   = $(addsuffix .o, $(VM_USER_CLASSES))
+VK_USER_OBJS = $(addsuffix .o, $(VM_USER_CLASSES))
 
 # Note VM_GLOBAL_FAST and VM_GLOBAL_SLOW holds the files required from the
 # run-time library. In practice everything is actually in VM_GLOBAL_FAST,
 # but keeping the distinction for compatibility for now.
 VK_GLOBAL_OBJS = $(addsuffix .o, $(VM_GLOBAL_FAST) $(VM_GLOBAL_SLOW))
 
+# Need to re-build if the generated makefile changes, as compiler options might
+# have changed.
+$(VK_GLOBAL_OBJS): $(VM_PREFIX).mk
+
 ifneq ($(VM_PARALLEL_BUILDS),1)
   # Fast build for small designs: All .cpp files in one fell swoop. This
   # saves total compute, but can be slower if only a little changes. It is
@@ -225,7 +216,9 @@ endif
 	$(info Archive $(AR) -rcs $@ $^)
 	$(foreach L, $(filter-out %.a,$^), $(shell echo $L >>[email protected]_deplist.tmp))
 	@if test $(words $(filter %.a,$^)) -eq 0; then \
-		$(AR) -rcs $@ @[email protected]_deplist.tmp; \
+		$(RM) -f $@; \
+		cat [email protected]_deplist.tmp | xargs $(AR) -rc $@; \
+		$(AR) -s $@; \
 	else \
 		$(RM) -rf [email protected]; \
 		for archive in $(filter %.a,$^); do \
@@ -234,7 +227,9 @@ endif
 			$(AR) -x ../../$${archive}; \
 			cd ../..; \
 		done; \
-		$(AR) -rcs $@ @[email protected]_deplist.tmp [email protected]/*/*.o; \
+		$(RM) -f $@; \
+		cat [email protected]_deplist.tmp | xargs $(AR) -rc $@; \
+		$(AR) -rcs $@ [email protected]/*/*.o; \
 	fi \
 	; $(RM) -rf [email protected]_deplist.tmp [email protected]
 

include/verilated.v

@@ -2,7 +2,7 @@
 //
 // Code available from: https://verilator.org
 //
-// Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
+// Copyright 2003-2022 by Wilson Snyder. This program 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.

include/verilated_config.h.in

@@ -3,7 +3,7 @@
 //
 // Code available from: https://verilator.org
 //
-// Copyright 2003-2021 by Wilson Snyder. This program is free software; you can
+// Copyright 2003-2022 by Wilson Snyder. This program 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.
@@ -20,6 +20,11 @@
 // Autoconf substitutes this with the strings from AC_INIT.
 #define VERILATOR_PRODUCT "@PACKAGE_NAME@"
 
-/// Verilator version name, e.g. "1.000 2000-01-01"
+/// Verilator version name, e.g. "1.002 2000-01-01"
 // Autoconf substitutes this with the strings from AC_INIT.
 #define VERILATOR_VERSION "@PACKAGE_VERSION@"
+
+/// Verilator version number as integer
+/// As major * 100000 + minor * 1000, e.g. 1002000 == 1.002
+// Autoconf substitutes this with the strings from AC_INIT.
+#define VERILATOR_VERSION_INTEGER @VERILATOR_VERSION_INTEGER@

include/verilated_cov.cpp

@@ -3,7 +3,7 @@
 //
 // Code available from: https://verilator.org
 //
-// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
+// Copyright 2001-2022 by Wilson Snyder. This program 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.
@@ -22,13 +22,16 @@
 //=============================================================================
 
 #include "verilatedos.h"
-#include "verilated.h"
+
 #include "verilated_cov.h"
+
+#include "verilated.h"
 #include "verilated_cov_key.h"
 
 #include <deque>
 #include <fstream>
 #include <map>
+#include <utility>
 
 //=============================================================================
 // VerilatedCovConst
@@ -58,7 +61,7 @@ public:  // But only local to this file
         }
     }
     virtual ~VerilatedCovImpItem() = default;
-    virtual vluint64_t count() const = 0;
+    virtual uint64_t count() const = 0;
     virtual void zero() const = 0;
 };
 
@@ -68,22 +71,23 @@ public:  // But only local to this file
 // This isn't in the header file for auto-magic conversion because it
 // inlines to too much code and makes compilation too slow.
 
-template <class T> class VerilatedCoverItemSpec final : public VerilatedCovImpItem {
+template <class T>
+class VerilatedCoverItemSpec final : public VerilatedCovImpItem {
 private:
     // MEMBERS
     T* m_countp;  // Count value
 public:
     // METHODS
     // cppcheck-suppress truncLongCastReturn
-    virtual vluint64_t count() const override { return *m_countp; }
-    virtual void zero() const override { *m_countp = 0; }
+    uint64_t count() const override { return *m_countp; }
+    void zero() const override { *m_countp = 0; }
     // CONSTRUCTORS
     // cppcheck-suppress noExplicitConstructor
     explicit VerilatedCoverItemSpec(T* countp)
         : m_countp{countp} {
         *m_countp = 0;
     }
-    virtual ~VerilatedCoverItemSpec() override = default;
+    ~VerilatedCoverItemSpec() override = default;
 };
 
 //=============================================================================
@@ -102,7 +106,7 @@ private:
     using ItemList = std::deque<VerilatedCovImpItem*>;
 
     // MEMBERS
-    VerilatedMutex m_mutex;  // Protects all members
+    mutable VerilatedMutex m_mutex;  // Protects all members
     ValueIndexMap m_valueIndexes VL_GUARDED_BY(m_mutex);  // Unique arbitrary value for values
     IndexValueMap m_indexValues VL_GUARDED_BY(m_mutex);  // Unique arbitrary value for keys
     ItemList m_items VL_GUARDED_BY(m_mutex);  // List of all items
@@ -121,18 +125,14 @@ public:
 
 protected:
     friend class VerilatedCovContext;
-    virtual ~VerilatedCovImp() override { clearGuts(); }
-    static VerilatedCovImp& imp() VL_MT_SAFE {
-        static VerilatedCovImp s_singleton;
-        return s_singleton;
-    }
+    ~VerilatedCovImp() override { clearGuts(); }
 
 private:
     // PRIVATE METHODS
     int valueIndex(const std::string& value) VL_REQUIRES(m_mutex) {
         const auto iter = m_valueIndexes.find(value);
         if (iter != m_valueIndexes.end()) return iter->second;
-        m_nextIndex++;
+        ++m_nextIndex;
         assert(m_nextIndex > 0);  // Didn't rollover
         m_valueIndexes.emplace(value, m_nextIndex);
         m_indexValues.emplace(m_nextIndex, value);
@@ -143,8 +143,9 @@ private:
         std::string rtn;
         for (const char* pos = text.c_str(); *pos; ++pos) {
             if (!std::isprint(*pos) || *pos == '%' || *pos == '"') {
-                char hex[10];
-                VL_SNPRINTF(hex, 10, "%%%02X", pos[0]);
+                constexpr size_t LEN_MAX_HEX = 20;
+                char hex[LEN_MAX_HEX];
+                VL_SNPRINTF(hex, LEN_MAX_HEX, "%%%02X", pos[0]);
                 rtn += hex;
             } else {
                 rtn += *pos;
@@ -165,11 +166,11 @@ private:
                                          const std::string& value) VL_PURE {
         std::string name;
         if (key.length() == 1 && std::isalpha(key[0])) {
-            name += std::string("\001") + key;
+            name += std::string{"\001"} + key;
         } else {
-            name += std::string("\001") + dequote(key);
+            name += std::string{"\001"} + dequote(key);
         }
-        name += std::string("\002") + dequote(value);
+        name += std::string{"\002"} + dequote(value);
         return name;
     }
     static std::string combineHier(const std::string& old, const std::string& add) VL_PURE {
@@ -180,31 +181,32 @@ private:
         if (old.empty()) return add;
         if (add.empty()) return old;
 
-        const char* a = old.c_str();
-        const char* b = add.c_str();
+        const char* const a = old.c_str();
+        const char* const b = add.c_str();
 
         // Scan forward to first mismatch
         const char* apre = a;
         const char* bpre = b;
         while (*apre == *bpre) {
-            apre++;
-            bpre++;
+            ++apre;
+            ++bpre;
         }
 
         // We used to backup and split on only .'s but it seems better to be verbose
         // and not assume . is the separator
-        const std::string prefix = std::string(a, apre - a);
+        const size_t prefix_len = apre - a;
+        const std::string prefix = std::string{a, prefix_len};
 
         // Scan backward to last mismatch
         const char* apost = a + std::strlen(a) - 1;
         const char* bpost = b + std::strlen(b) - 1;
         while (*apost == *bpost && apost > apre && bpost > bpre) {
-            apost--;
-            bpost--;
+            --apost;
+            --bpost;
         }
 
         // Forward to . so we have a whole word
-        std::string suffix = *bpost ? std::string(bpost + 1) : "";
+        const std::string suffix = *bpost ? std::string{bpost + 1} : "";
 
         std::string out = prefix + "*" + suffix;
 
@@ -217,7 +219,7 @@ private:
         for (int i = 0; i < VerilatedCovConst::MAX_KEYS; ++i) {
             if (itemp->m_keys[i] != VerilatedCovConst::KEY_UNDEF) {
                 // We don't compare keys, only values
-                std::string val = m_indexValues[itemp->m_vals[i]];
+                const std::string val = m_indexValues[itemp->m_vals[i]];
                 if (std::string::npos != val.find(match)) {  // Found
                     return true;
                 }
@@ -229,7 +231,7 @@ private:
         // Little selftest
 #define SELF_CHECK(got, exp) \
     do { \
-        if ((got) != (exp)) VL_FATAL_MT(__FILE__, __LINE__, "", "%Error: selftest\n"); \
+        if ((got) != (exp)) VL_FATAL_MT(__FILE__, __LINE__, "", "%Error: selftest"); \
     } while (0)
         SELF_CHECK(combineHier("a.b.c", "a.b.c"), "a.b.c");
         SELF_CHECK(combineHier("a.b.c", "a.b"), "a.b*");
@@ -253,17 +255,17 @@ public:
     // PUBLIC METHODS
     void forcePerInstance(const bool flag) VL_MT_SAFE_EXCLUDES(m_mutex) {
         Verilated::quiesce();
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         m_forcePerInstance = flag;
     }
     void clear() VL_MT_SAFE_EXCLUDES(m_mutex) {
         Verilated::quiesce();
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         clearGuts();
     }
     void clearNonMatch(const char* const matchp) VL_MT_SAFE_EXCLUDES(m_mutex) {
         Verilated::quiesce();
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         if (matchp && matchp[0]) {
             ItemList newlist;
             for (const auto& itemp : m_items) {
@@ -278,29 +280,29 @@ public:
     }
     void zero() VL_MT_SAFE_EXCLUDES(m_mutex) {
         Verilated::quiesce();
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         for (const auto& itemp : m_items) itemp->zero();
     }
 
     // We assume there's always call to i/f/p in that order
     void inserti(VerilatedCovImpItem* itemp) VL_MT_SAFE_EXCLUDES(m_mutex) {
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         assert(!m_insertp);
         m_insertp = itemp;
     }
     void insertf(const char* const filenamep, const int lineno) VL_MT_SAFE_EXCLUDES(m_mutex) {
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         m_insertFilenamep = filenamep;
         m_insertLineno = lineno;
     }
     void insertp(const char* ckeyps[VerilatedCovConst::MAX_KEYS],
                  const char* valps[VerilatedCovConst::MAX_KEYS]) VL_MT_SAFE_EXCLUDES(m_mutex) {
-        const VerilatedLockGuard lock(m_mutex);
+        const VerilatedLockGuard lock{m_mutex};
         assert(m_insertp);
         // First two key/vals are filename
         ckeyps[0] = "filename";
         valps[0] = m_insertFilenamep;
-        std::string linestr = vlCovCvtToStr(m_insertLineno);
+        const std::string linestr = vlCovCvtToStr(m_insertLineno);
         ckeyps[1] = "lineno";
         valps[1] = linestr.c_str();
         // Default page if not specified
@@ -308,7 +310,8 @@ public:
         while (const char* foundp = std::strchr(fnstartp, '/')) fnstartp = foundp + 1;
         const char* fnendp = fnstartp;
         for (; *fnendp && *fnendp != '.'; fnendp++) {}
-        std::string page_default = "sp_user/" + std::string(fnstartp, fnendp - fnstartp);
+        const size_t page_len = fnendp - fnstartp;
+        const std::string page_default = "sp_user/" + std::string{fnstartp, page_len};
         ckeyps[2] = "page";
         valps[2] = page_default.c_str();
 
@@ -337,9 +340,9 @@ public:
                 // cout<<"   "<<__FUNCTION__<<"  "<<key<<" = "<<val<<endl;
                 m_insertp->m_keys[addKeynum] = valueIndex(key);
                 m_insertp->m_vals[addKeynum] = valueIndex(val);
-                addKeynum++;
+                ++addKeynum;
                 if (VL_UNCOVERABLE(!legalKey(key))) {
-                    std::string msg
+                    const std::string msg
                         = ("%Error: Coverage keys of one character, or letter+digit are illegal: "
                            + key);  // LCOV_EXCL_LINE
                     VL_FATAL_MT("", 0, "", msg.c_str());
@@ -353,22 +356,19 @@ public:
 
     void write(const char* filename) VL_MT_SAFE_EXCLUDES(m_mutex) {
         Verilated::quiesce();
-        const VerilatedLockGuard lock(m_mutex);
-#ifndef VM_COVERAGE
-        VL_FATAL_MT("", 0, "", "%Error: Called VerilatedCov::write when VM_COVERAGE disabled\n");
-#endif
+        const VerilatedLockGuard lock{m_mutex};
         selftest();
 
-        std::ofstream os(filename);
+        std::ofstream os{filename};
         if (os.fail()) {
-            std::string msg = std::string("%Error: Can't write '") + filename + "'";
+            const std::string msg = std::string{"%Error: Can't write '"} + filename + "'";
             VL_FATAL_MT("", 0, "", msg.c_str());
             return;
         }
         os << "# SystemC::Coverage-3\n";
 
         // Build list of events; totalize if collapsing hierarchy
-        std::map<const std::string, std::pair<std::string, vluint64_t>> eventCounts;
+        std::map<const std::string, std::pair<std::string, uint64_t>> eventCounts;
         for (const auto& itemp : m_items) {
             std::string name;
             std::string hier;
@@ -377,8 +377,9 @@ public:
 
             for (int i = 0; i < VerilatedCovConst::MAX_KEYS; ++i) {
                 if (itemp->m_keys[i] != VerilatedCovConst::KEY_UNDEF) {
-                    std::string key = VerilatedCovKey::shortKey(m_indexValues[itemp->m_keys[i]]);
-                    std::string val = m_indexValues[itemp->m_vals[i]];
+                    const std::string key
+                        = VerilatedCovKey::shortKey(m_indexValues[itemp->m_keys[i]]);
+                    const std::string val = m_indexValues[itemp->m_vals[i]];
                     if (key == VL_CIK_PER_INSTANCE) {
                         if (val != "0") per_instance = true;
                     }
@@ -434,11 +435,11 @@ void VerilatedCovContext::clearNonMatch(const char* matchp) VL_MT_SAFE {
 }
 void VerilatedCovContext::zero() VL_MT_SAFE { impp()->zero(); }
 void VerilatedCovContext::write(const char* filenamep) VL_MT_SAFE { impp()->write(filenamep); }
-void VerilatedCovContext::_inserti(vluint32_t* itemp) VL_MT_SAFE {
-    impp()->inserti(new VerilatedCoverItemSpec<vluint32_t>(itemp));
+void VerilatedCovContext::_inserti(uint32_t* itemp) VL_MT_SAFE {
+    impp()->inserti(new VerilatedCoverItemSpec<uint32_t>{itemp});
 }
-void VerilatedCovContext::_inserti(vluint64_t* itemp) VL_MT_SAFE {
-    impp()->inserti(new VerilatedCoverItemSpec<vluint64_t>(itemp));
+void VerilatedCovContext::_inserti(uint64_t* itemp) VL_MT_SAFE {
+    impp()->inserti(new VerilatedCoverItemSpec<uint64_t>{itemp});
 }
 void VerilatedCovContext::_insertf(const char* filename, int lineno) VL_MT_SAFE {
     impp()->insertf(filename, lineno);
@@ -510,9 +511,11 @@ VerilatedCovContext* VerilatedCov::threadCovp() VL_MT_SAFE {
 
 VerilatedCovContext* VerilatedContext::coveragep() VL_MT_SAFE {
     static VerilatedMutex s_mutex;
+    // cppcheck-suppress identicalInnerCondition
     if (VL_UNLIKELY(!m_coveragep)) {
-        const VerilatedLockGuard lock(s_mutex);
-        if (VL_LIKELY(!m_coveragep)) {  // Not redundant, prevents race
+        const VerilatedLockGuard lock{s_mutex};
+        // cppcheck-suppress identicalInnerCondition
+        if (VL_LIKELY(!m_coveragep)) {  // LCOV_EXCL_LINE // Not redundant, prevents race
             m_coveragep.reset(new VerilatedCovImp);
         }
     }

include/verilated_cov.h

@@ -3,7 +3,7 @@
 //
 // Code available from: https://verilator.org
 //
-// Copyright 2001-2021 by Wilson Snyder. This program is free software; you
+// Copyright 2001-2022 by Wilson Snyder. This program 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.
@@ -26,6 +26,7 @@
 #define VERILATOR_VERILATED_COV_H_
 
 #include "verilatedos.h"
+
 #include "verilated.h"
 
 #include <iostream>
@@ -34,22 +35,6 @@
 
 class VerilatedCovImp;
 
-//=============================================================================
-/// Conditionally compile statements only when doing coverage (when
-/// VM_COVERAGE is defined)
-
-// clang-format off
-#ifdef VM_COVERAGE
-# define VL_IF_COVER(stmts) \
-    do { stmts; } while (false)
-#else
-# define VL_IF_COVER(stmts) \
-    do { \
-        if (false) { stmts; } \
-    } while (false)
-#endif
-// clang-format on
-
 //=============================================================================
 /// Insert a item for coverage analysis.
 /// The first argument is a pointer to the count to be dumped.
@@ -72,7 +57,7 @@ class VerilatedCovImp;
 ///
 /// Example:
 ///
-///     vluint32_t m_cases[10];  // Storage for coverage data
+///     uint32_t m_cases[10];  // Storage for coverage data
 ///     constructor() {
 ///         // Initialize
 ///         for (int i = 0; i < 10; ++i) m_cases[i] = 0;
@@ -82,13 +67,17 @@ class VerilatedCovImp;
 ///     }
 
 #define VL_COVER_INSERT(covcontextp, countp, ...) \
-    VL_IF_COVER(covcontextp->_inserti(countp); covcontextp->_insertf(__FILE__, __LINE__); \
-                covcontextp->_insertp("hier", name(), __VA_ARGS__))
+    do { \
+        covcontextp->_inserti(countp); \
+        covcontextp->_insertf(__FILE__, __LINE__); \
+        covcontextp->_insertp("hier", name(), __VA_ARGS__); \
+    } while (false)
 
 //=============================================================================
 // Convert VL_COVER_INSERT value arguments to strings, is \internal
 
-template <class T> std::string vlCovCvtToStr(const T& t) VL_PURE {
+template <class T>
+std::string vlCovCvtToStr(const T& t) VL_PURE {
     std::ostringstream os;
     os << t;
     return os.str();
@@ -120,14 +109,15 @@ public:
     /// Zero coverage points
     void zero() VL_MT_SAFE;
 
-public:  // But Internal use only
+    // METHODS - public but Internal use only
+
     // Insert a coverage item
     // We accept from 1-30 key/value pairs, all as strings.
     // Call _insert1, followed by _insert2 and _insert3
     // Do not call directly; use VL_COVER_INSERT or higher level macros instead
     // _insert1: Remember item pointer with count.  (Not const, as may add zeroing function)
-    void _inserti(vluint32_t* itemp) VL_MT_SAFE;
-    void _inserti(vluint64_t* itemp) VL_MT_SAFE;
+    void _inserti(uint32_t* itemp) VL_MT_SAFE;
+    void _inserti(uint64_t* itemp) VL_MT_SAFE;
     // _insert2: Set default filename and line number
     void _insertf(const char* filename, int lineno) VL_MT_SAFE;
     // _insert3: Set parameters
@@ -157,8 +147,8 @@ protected:
     friend class VerilatedCovImp;
     // CONSTRUCTORS
     // Internal: Only made as part of VerilatedCovImp
-    VerilatedCovContext() {}
-    virtual ~VerilatedCovContext() {}
+    VerilatedCovContext() = default;
+    ~VerilatedCovContext() override = default;
 
     // METHODS
     // Internal: access to implementation class