Version bump

* Tests: Add a test to reproduce #2891

* Fix assertion failure in binary op tree opt.

.clang-format

@@ -0,0 +1,111 @@
+---
+Language:        Cpp
+# BasedOnStyle:  LLVM
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: DontAlign
+AlignOperands:   true
+AlignTrailingComments: false
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: true
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: false
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: All
+BreakBeforeBraces: Attach
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeComma
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:     99
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
+    Priority:        2
+  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
+    Priority:        3
+  - Regex:           '.*'
+    Priority:        1
+IncludeIsMainRegex: '(Test)?$'
+IndentCaseLabels: false
+IndentPPDirectives: None
+IndentWidth:     4
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    false
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Cpp11
+TabWidth:        8
+UseTab:          Never
+...
+

.clang-tidy

@@ -0,0 +1,9 @@
+Checks:          '*,-hicpp*,-android-cloexec-fopen,-cert-dcl50-cpp,-cert-env33-c,-cert-err34-c,-cert-err58-cpp,-clang-analyzer-core.UndefinedBinaryOperatorResult,-clang-analyzer-security*,-cppcoreguidelines-avoid-magic-numbers,-cppcoreguidelines-no-malloc,-cppcoreguidelines-owning-memory,-cppcoreguidelines-pro-bounds-array-to-pointer-decay,-cppcoreguidelines-pro-bounds-array-to-pointer-decay,-cppcoreguidelines-pro-bounds-constant-array-index,-cppcoreguidelines-pro-bounds-pointer-arithmetic,-cppcoreguidelines-pro-type-const-cast,-cppcoreguidelines-pro-type-reinterpret-cast,-cppcoreguidelines-pro-type-static-cast-downcast,-cppcoreguidelines-pro-type-union-access,-cppcoreguidelines-pro-type-vararg,-cppcoreguidelines-special-member-functions,-fuchsia-*,-google-default-arguments,-google-readability-todo,-google-runtime-references,-llvm-header-guard,-llvm-include-order,-misc-string-integer-assignment,-misc-string-literal-with-embedded-nul,-modernize-use-auto,-modernize-use-trailing-return-type,-readability-braces-around-statements,-readability-container-size-empty,-readability-delete-null-pointer,-readability-else-after-return,-readability-implicit-bool-conversion,-readability-named-parameter,-readability-static-accessed-through-instance'
+WarningsAsErrors: ''
+HeaderFilterRegex: ''
+FormatStyle:     none
+CheckOptions:
+  - key:             google-readability-braces-around-statements.ShortStatementLines
+    value:           '2'
+  - key:             google-readability-namespace-comments.SpacesBeforeComments
+    value:           '2'

.codacy.yml

@@ -0,0 +1,6 @@
+---
+exclude_paths:
+  - '.github/**'
+  - 'ci/build_verilator.sh'
+  - 'include/vltstd/**'
+  - 'nodist/fastcov.py'

.gitattributes

@@ -0,0 +1,5 @@
+*.v linguist-language=SystemVerilog
+*.vh linguist-language=SystemVerilog
+*.sv linguist-language=SystemVerilog
+Changes linguist-language=reStructuredText
+nodist linguist-detectable=false

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,16 @@
+---
+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)
+title: ''
+labels: new
+assignees: ''
+
+---
+
+Thanks for taking the time to report this.
+
+Can you attach an example that shows the issue?  (Must be openly licensed, ideally in test_regress format.)
+
+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?

.github/ISSUE_TEMPLATE/feature.md

@@ -0,0 +1,16 @@
+---
+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)
+title: ''
+labels: new
+assignees: ''
+
+---
+
+Thanks for taking the time to report this.
+
+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?

.github/ISSUE_TEMPLATE/questions.md

@@ -0,0 +1,10 @@
+---
+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)
+title: ''
+labels: new
+assignees: ''
+
+---
+
+How may we help - what is your question?

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1 @@
+We appreciate your contributing to Verilator.  If this is your first commit, please add your name to docs/CONTRIBUTORS, and read our contributing guidelines in docs/CONTRIBUTING.rst.

.github/labels.toml

@@ -0,0 +1,199 @@
+["area: assertions"]
+color = "ffffe8"
+name = "area: assertions"
+description = "Issue involves assertions"
+
+["area: configure/compiling"]
+color = "ffffe8"
+name = "area: configure/compiling"
+description = "Issue involves configuring or compilating Verilator itself"
+
+["area: coverage"]
+color = "ffffe8"
+name = "area: coverage"
+description = "Issue involves coverage generation"
+
+["area: data-types"]
+color = "ffffe8"
+name = "area: data-types"
+description = "Issue involves data-types"
+
+["area: documentation"]
+color = "ffffe8"
+name = "area: documentation"
+description = "Issue involves documentation"
+
+["area: elaboration"]
+color = "ffffe8"
+name = "area: elaboration"
+description = "Issue involves elaboration phase"
+
+["area: invoking/options"]
+color = "ffffe8"
+name = "area: invoking/options"
+description = "Issue involves options passed to Verilator"
+
+["area: lint"]
+color = "ffffe8"
+name = "area: lint"
+description = "Issue involves SystemVerilog lint checking"
+
+["area: parser"]
+color = "ffffe8"
+name = "area: parser"
+description = "Issue involves SystemVerilog parsing"
+
+["area: performance"]
+color = "ffffe8"
+name = "area: performance"
+description = "Issue involves performance issues"
+
+["area: portability"]
+color = "ffffe8"
+name = "area: portability"
+description = "Issue involves operating system/compiler portability"
+
+["area: runtime result"]
+color = "ffffe8"
+name = "area: runtime result"
+description = "Issue involves an incorrect runtine result from Verilated model"
+
+["area: scheduling"]
+color = "ffffe8"
+name = "area: scheduling"
+description = "Issue involves scheduling/ordering of events"
+
+["area: tests"]
+color = "ffffe8"
+name = "area: tests"
+description = "Issue involves the testing system"
+
+["area: usability"]
+color = "ffffe8"
+name = "area: usability"
+description = "Issue involves general usability"
+
+["effort: days"]
+color = "d0c0b0"
+name = "effort: days"
+description = "Expect this issue to require roughly days of invested effort to resolve"
+
+["effort: hours"]
+color = "f5e6d6"
+name = "effort: hours"
+description = "Expect this issue to require roughly hours of invested effort to resolve"
+
+["effort: minutes"]
+color = "f5e6d6"
+name = "effort: minutes"
+description = "Expect this issue to require less than an hour of invested effort to resolve"
+
+["effort: weeks"]
+color = "d0c0b0"
+name = "effort: weeks"
+description = "Expect this issue to require weeks or more of invested effort to resolve"
+
+["good first issue"]
+color = "7057ff"
+name = "good first issue"
+description = "Good for newcomers"
+
+["help wanted"]
+color = "008672"
+name = "help wanted"
+description = "Extra attention is needed"
+
+["new"]
+color = "ff4400"
+name = "new"
+description = "New issue, not yet seen by maintainers"
+
+["resolution: abandoned"]
+color = "cfd3d7"
+name = "resolution: abandoned"
+description = "Closed; not enough information or otherwise never finished"
+
+["resolution: answered"]
+color = "cfd3d7"
+name = "resolution: answered"
+description = "Closed; only applies to questions which were answered"
+
+["resolution: duplicate"]
+color = "cfd3d7"
+name = "resolution: duplicate"
+description = "Closed; issue or pull request already exists"
+
+["resolution: external"]
+color = "cfd3d7"
+name = "resolution: external"
+description = "Closed; passed to another tool's bug tracker"
+
+["resolution: fixed"]
+color = "cfd3d7"
+name = "resolution: fixed"
+description = "Closed; fixed"
+
+["resolution: invalid"]
+color = "cfd3d7"
+name = "resolution: invalid"
+description = "Closed; issue or pull request is no longer relevant"
+
+["resolution: no fix needed"]
+color = "cfd3d7"
+name = "resolution: no fix needed"
+description = "Closed; no fix required (not a bug)"
+
+["resolution: wontfix"]
+color = "cfd3d7"
+name = "resolution: wontfix"
+description = "Closed; work won't continue on an issue or pull request"
+
+["status: asked reporter"]
+color = "ffffff"
+name = "status: asked reporter"
+description = "Bug is waiting for reporter to answer a question"
+
+["status: assigned"]
+color = "a0f0ff"
+name = "status: assigned"
+description = "Issue is assigned to someone to work on"
+
+["status: blocked"]
+color = "00007f"
+name = "status: blocked"
+description = "Issue is waiting for another bug, when other bug is fixed, then goes to 'status: assigned'"
+
+["status: discussion"]
+color = "d876e3"
+name = "status: discussion"
+description = "Issue is waiting for discussions to resolve"
+
+["status: ready"]
+color = "b6c92a"
+name = "status: ready"
+description = "Issue is ready for someone to fix; then goes to 'status: assigned'"
+
+["type: bug"]
+color = "d73a4a"
+name = "type: bug"
+description = "Defect"
+
+["type: feature-IEEE"]
+color = "cfccff"
+name = "type: feature-IEEE"
+description = "Request to add new feature, described in IEEE 1800"
+
+["type: feature-non-IEEE"]
+color = "cfccff"
+name = "type: feature-non-IEEE"
+description = "Request to add new feature, outside IEEE 1800"
+
+["type: maintenance"]
+color = "cfccff"
+name = "type: maintenance"
+description = "Internal maintenance task"
+
+["type: q and a"]
+color = "84ba34"
+name = "type: q and a"
+description = "Question and answer about some feature or user question"

.github/workflows/build.yml

@@ -0,0 +1,137 @@
+# DESCRIPTION: Github actions config
+# This name is key to badges in README.rst, so we use the name build
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: build
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+  schedule:
+  - cron: '0 0 * * 0' # weekly
+
+env:
+  CI_OS_NAME: linux
+  CI_COMMIT: ${{ github.sha }}
+  CCACHE_COMPRESS: 1
+  CCACHE_DIR: ${{ github.workspace }}/.ccache
+  CCACHE_MAXSIZE: 2Gi  # 2GiB for clang and gcc, 4GiB in total
+
+jobs:
+
+
+  Matrix:
+    runs-on: ubuntu-latest
+    name: Generate Build matrix
+    outputs:
+      matrix: ${{ steps.generate.outputs.matrix }}
+    steps:
+    - uses: actions/checkout@v2
+    - id: generate
+      name: Run 'generate_matrix.sh'
+      run: |
+        if [ '${{ github.event_name}}' = 'pull_request' ]; then
+          matrix='[ "ubuntu-20.04" ]'
+        else
+          matrix='[ "ubuntu-16.04", "ubuntu-18.04", "ubuntu-20.04" ]'
+        fi
+        echo "::set-output name=matrix::$matrix"
+
+
+  Build:
+    needs: Matrix
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ fromJson(needs.Matrix.outputs.matrix) }}
+        debug: [ opt, dbg ]
+        compiler:
+          - { cc: clang, cxx: clang++ }
+          - { cc: gcc,   cxx: g++     }
+    runs-on: ${{ matrix.os }}
+    name: Build | ${{ matrix.os }} | ${{ matrix.compiler.cc }} | ${{ matrix.debug }}
+    env:
+      CI_BUILD_STAGE_NAME: build
+      CI_RUNS_ON: ${{ matrix.os }}
+      CI_MAKE_SRC_TARGET: ${{ matrix.debug }}
+      CC: ${{ matrix.compiler.cc }}
+      CXX: ${{ matrix.compiler.cxx }}
+      CACHE_KEY: ${{ matrix.os }}-${{ matrix.compiler.cc }}
+    steps:
+
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Cache
+      uses: actions/cache@v2
+      env:
+        cache-name: ccache
+      with:
+        path: ${{ github.workspace }}/.ccache
+        key: ${{ env.CACHE_KEY }}-${{ env.cache-name }}-${{ github.sha }}
+        restore-keys: ${{ env.CACHE_KEY }}-${{ env.cache-name }}
+
+    - name: Install packages for build
+      run: ./ci/ci-install.bash
+
+    - name: Build
+      run: |
+        ./ci/ci-script.bash
+        tar cvzf verilator-${{ matrix.os}}-${CI_COMMIT}-${{ matrix.compiler.cc }}-${{ matrix.debug }}.tgz ./bin
+
+    - uses: actions/upload-artifact@v2
+      with:
+        path: verilator-${{ matrix.os}}-${{ env.CI_COMMIT }}-${{ matrix.compiler.cc }}-${{ matrix.debug }}.tgz
+
+
+  Test:
+    needs: [ Matrix, Build ]
+    strategy:
+      fail-fast: false
+      max-parallel: 8
+      matrix:
+        os: ${{ fromJson(needs.Matrix.outputs.matrix) }}
+        compiler:
+          - { cc: clang, cxx: clang++ }
+          - { cc: gcc,   cxx: g++     }
+        suite:
+          - dist-vlt-0
+          - dist-vlt-1
+          - vltmt-0
+          - vltmt-1
+    runs-on: ${{ matrix.os }}
+    name: Test | ${{ matrix.os }} | ${{ matrix.compiler.cc }} | ${{ matrix.suite }}
+    env:
+      CI_BUILD_STAGE_NAME: test
+      CI_RUNS_ON: ${{ matrix.os }}
+      CC: ${{ matrix.compiler.cc }}
+      CXX: ${{ matrix.compiler.cxx }}
+      CACHE_KEY: ${{ matrix.os }}-${{ matrix.compiler.cc }}
+    steps:
+
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Cache
+      uses: actions/cache@v2
+      env:
+        cache-name: ccache
+      with:
+        path: ${{ github.workspace }}/.ccache
+        key: ${{ env.CACHE_KEY }}-${{ env.cache-name }}-${{ github.sha }}
+        restore-keys: ${{ env.CACHE_KEY }}-${{ env.cache-name }}
+
+    - uses: actions/download-artifact@v2
+
+    - name: Install Verilator and test dependencies
+      run: |
+        tar xvzf artifact/verilator-${{ matrix.os}}-${CI_COMMIT}-${{ matrix.compiler.cc }}-opt.tgz
+        tar xvzf artifact/verilator-${{ matrix.os}}-${CI_COMMIT}-${{ matrix.compiler.cc }}-dbg.tgz
+        rm -rf artifact
+        ./ci/ci-install.bash
+
+    - name: Test
+      env:
+        TESTS: ${{ matrix.suite }}
+      run: ./ci/ci-script.bash

.github/workflows/clang-format.yml

@@ -0,0 +1,43 @@
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: clang-format
+
+on:
+  push:
+  pull_request_target:
+  workflow_dispatch:
+
+jobs:
+  format:
+    runs-on: ubuntu-20.04
+    name: Ubuntu 20.04 | format
+    env:
+      CI_OS_NAME: linux
+      CI_RUNS_ON: ubuntu-20.04
+      CI_COMMIT: ${{ github.sha }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Install packages for build
+        env:
+          CI_BUILD_STAGE_NAME: build
+        run: |
+          bash ci/ci-install.bash &&
+          sudo apt-get install clang-10 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-10 &&
+          git status
+      - name: Push
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            git commit . -m "Apply clang-format" &&
+            git push origin
+          fi

.github/workflows/contributor.yml

@@ -0,0 +1,17 @@
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Contributor Agreement
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  Test:
+    name: "'docs/CONTRIBUTORS' was signed"
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v2
+    - run: test_regress/t/t_dist_contributors.pl

.github/workflows/coverage.yml

@@ -0,0 +1,109 @@
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: coverage
+
+on:
+  workflow_dispatch:
+  schedule:
+  - cron: '0 0 * * 0' # weekly
+
+env:
+  CI_OS_NAME: linux
+  CI_COMMIT: ${{ github.sha }}
+  CCACHE_COMPRESS: 1
+  CCACHE_DIR: ${{ github.workspace }}/.ccache
+  CCACHE_MAXSIZE: 2Gi  # 2GiB for clang and gcc, 4GiB in total
+  COVERAGE: 1
+
+jobs:
+
+
+  Build:
+    runs-on: ubuntu-20.04
+    env:
+      CI_BUILD_STAGE_NAME: build
+      CI_RUNS_ON: ubuntu-20.04
+      CACHE_KEY: ubuntu-20.04-${{ matrix.compiler.cc }}-coverage
+    steps:
+
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Cache
+      uses: actions/cache@v2
+      env:
+        cache-name: ccache
+      with:
+        path: ${{ github.workspace }}/.ccache
+        key: ${{ env.CACHE_KEY }}-${{ env.cache-name }}-${{ github.sha }}
+        restore-keys: coverage-${{ env.cache-name }}
+
+    - name: Install packages for build
+      env:
+        CI_BUILD_STAGE_NAME: build
+      run: ./ci/ci-install.bash
+
+    - name: Build
+      run: |
+        ./ci/ci-script.bash
+        tar cvzf verilator-${CI_COMMIT}-coverage.tgz bin src/obj*/*.o src/obj*/*.gcno
+
+    - uses: actions/upload-artifact@v2
+      with:
+        path: verilator-${{ env.CI_COMMIT }}-coverage.tgz
+
+
+  Test:
+    needs: Build
+    strategy:
+      fail-fast: false
+      matrix:
+        test:
+        - vlt-
+        - vltmt-
+        num:
+        - 0
+        - 1
+        - 2
+        - 3
+        - 4
+        - 5
+        - 6
+        - 7
+        - 8
+        - 9
+        include:
+        - { test: dist, num: '' }
+    runs-on: ubuntu-20.04
+    name: test-${{ matrix.test }}${{ matrix.num }}
+    env:
+      CI_BUILD_STAGE_NAME: test
+      CI_RUNS_ON: ubuntu-20.04
+      CACHE_KEY: ubuntu-20.04-${{ matrix.compiler.cc }}-coverage
+    steps:
+
+    - name: Checkout
+      uses: actions/checkout@v2
+
+    - name: Cache
+      uses: actions/cache@v2
+      env:
+        cache-name: ccache
+      with:
+        path: ${{ github.workspace }}/.ccache
+        key: ${{ env.CACHE_KEY }}-${{ env.cache-name }}-${{ github.sha }}
+        restore-keys: coverage-${{ env.cache-name }}
+
+    - uses: actions/download-artifact@v2
+
+    - name: Install Verilator and test dependencies
+      run: |
+        tar xvzf artifact/verilator-${CI_COMMIT}-coverage.tgz
+        touch src/obj*/*.o src/obj*/*.gcno
+        ./ci/ci-install.bash
+
+    - name: Test
+      env:
+        TESTS: coverage-${{ matrix.test }}${{ matrix.num }}
+      run: ./ci/ci-script.bash

.gitignore

@@ -1,6 +1,8 @@
 \#*
 .#*
+.nfs*
 *~
+*.tidy
 *.old
 *.gz
 *.gz.uu
@@ -13,9 +15,12 @@
 *.tex
 *.pdf
 /Makefile
+/.ccache
+/artifact/
 README
 TAGS
 autom4te.cache
+compile_commands.json
 config.cache
 config.status
 configure
@@ -29,4 +34,8 @@ verilator.txt
 verilator_bin*
 verilator_coverage_bin*
 verilator.pc
+verilator-config.cmake
+verilator-config-version.cmake
+**/__pycache__/*
+**/_build/*
 **/obj_dir/*

COPYING

@@ -1,674 +0,0 @@
-                    GNU GENERAL PUBLIC LICENSE
-                       Version 3, 29 June 2007
-
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-                            Preamble
-
-  The GNU General Public License is a free, copyleft license for
-software and other kinds of works.
-
-  The licenses for most software and other practical works are designed
-to take away your freedom to share and change the works.  By contrast,
-the GNU General Public License is intended to guarantee your freedom to
-share and change all versions of a program--to make sure it remains free
-software for all its users.  We, the Free Software Foundation, use the
-GNU General Public License for most of our software; it applies also to
-any other work released this way by its authors.  You can apply it to
-your programs, too.
-
-  When we speak of free software, we are referring to freedom, not
-price.  Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-them if you wish), that you receive source code or can get it if you
-want it, that you can change the software or use pieces of it in new
-free programs, and that you know you can do these things.
-
-  To protect your rights, we need to prevent others from denying you
-these rights or asking you to surrender the rights.  Therefore, you have
-certain responsibilities if you distribute copies of the software, or if
-you modify it: responsibilities to respect the freedom of others.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must pass on to the recipients the same
-freedoms that you received.  You must make sure that they, too, receive
-or can get the source code.  And you must show them these terms so they
-know their rights.
-
-  Developers that use the GNU GPL protect your rights with two steps:
-(1) assert copyright on the software, and (2) offer you this License
-giving you legal permission to copy, distribute and/or modify it.
-
-  For the developers' and authors' protection, the GPL clearly explains
-that there is no warranty for this free software.  For both users' and
-authors' sake, the GPL requires that modified versions be marked as
-changed, so that their problems will not be attributed erroneously to
-authors of previous versions.
-
-  Some devices are designed to deny users access to install or run
-modified versions of the software inside them, although the manufacturer
-can do so.  This is fundamentally incompatible with the aim of
-protecting users' freedom to change the software.  The systematic
-pattern of such abuse occurs in the area of products for individuals to
-use, which is precisely where it is most unacceptable.  Therefore, we
-have designed this version of the GPL to prohibit the practice for those
-products.  If such problems arise substantially in other domains, we
-stand ready to extend this provision to those domains in future versions
-of the GPL, as needed to protect the freedom of users.
-
-  Finally, every program is threatened constantly by software patents.
-States should not allow patents to restrict development and use of
-software on general-purpose computers, but in those that do, we wish to
-avoid the special danger that patents applied to a free program could
-make it effectively proprietary.  To prevent this, the GPL assures that
-patents cannot be used to render the program non-free.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-                       TERMS AND CONDITIONS
-
-  0. Definitions.
-
-  "This License" refers to version 3 of the GNU General Public License.
-
-  "Copyright" also means copyright-like laws that apply to other kinds of
-works, such as semiconductor masks.
-
-  "The Program" refers to any copyrightable work licensed under this
-License.  Each licensee is addressed as "you".  "Licensees" and
-"recipients" may be individuals or organizations.
-
-  To "modify" a work means to copy from or adapt all or part of the work
-in a fashion requiring copyright permission, other than the making of an
-exact copy.  The resulting work is called a "modified version" of the
-earlier work or a work "based on" the earlier work.
-
-  A "covered work" means either the unmodified Program or a work based
-on the Program.
-
-  To "propagate" a work means to do anything with it that, without
-permission, would make you directly or secondarily liable for
-infringement under applicable copyright law, except executing it on a
-computer or modifying a private copy.  Propagation includes copying,
-distribution (with or without modification), making available to the
-public, and in some countries other activities as well.
-
-  To "convey" a work means any kind of propagation that enables other
-parties to make or receive copies.  Mere interaction with a user through
-a computer network, with no transfer of a copy, is not conveying.
-
-  An interactive user interface displays "Appropriate Legal Notices"
-to the extent that it includes a convenient and prominently visible
-feature that (1) displays an appropriate copyright notice, and (2)
-tells the user that there is no warranty for the work (except to the
-extent that warranties are provided), that licensees may convey the
-work under this License, and how to view a copy of this License.  If
-the interface presents a list of user commands or options, such as a
-menu, a prominent item in the list meets this criterion.
-
-  1. Source Code.
-
-  The "source code" for a work means the preferred form of the work
-for making modifications to it.  "Object code" means any non-source
-form of a work.
-
-  A "Standard Interface" means an interface that either is an official
-standard defined by a recognized standards body, or, in the case of
-interfaces specified for a particular programming language, one that
-is widely used among developers working in that language.
-
-  The "System Libraries" of an executable work include anything, other
-than the work as a whole, that (a) is included in the normal form of
-packaging a Major Component, but which is not part of that Major
-Component, and (b) serves only to enable use of the work with that
-Major Component, or to implement a Standard Interface for which an
-implementation is available to the public in source code form.  A
-"Major Component", in this context, means a major essential component
-(kernel, window system, and so on) of the specific operating system
-(if any) on which the executable work runs, or a compiler used to
-produce the work, or an object code interpreter used to run it.
-
-  The "Corresponding Source" for a work in object code form means all
-the source code needed to generate, install, and (for an executable
-work) run the object code and to modify the work, including scripts to
-control those activities.  However, it does not include the work's
-System Libraries, or general-purpose tools or generally available free
-programs which are used unmodified in performing those activities but
-which are not part of the work.  For example, Corresponding Source
-includes interface definition files associated with source files for
-the work, and the source code for shared libraries and dynamically
-linked subprograms that the work is specifically designed to require,
-such as by intimate data communication or control flow between those
-subprograms and other parts of the work.
-
-  The Corresponding Source need not include anything that users
-can regenerate automatically from other parts of the Corresponding
-Source.
-
-  The Corresponding Source for a work in source code form is that
-same work.
-
-  2. Basic Permissions.
-
-  All rights granted under this License are granted for the term of
-copyright on the Program, and are irrevocable provided the stated
-conditions are met.  This License explicitly affirms your unlimited
-permission to run the unmodified Program.  The output from running a
-covered work is covered by this License only if the output, given its
-content, constitutes a covered work.  This License acknowledges your
-rights of fair use or other equivalent, as provided by copyright law.
-
-  You may make, run and propagate covered works that you do not
-convey, without conditions so long as your license otherwise remains
-in force.  You may convey covered works to others for the sole purpose
-of having them make modifications exclusively for you, or provide you
-with facilities for running those works, provided that you comply with
-the terms of this License in conveying all material for which you do
-not control copyright.  Those thus making or running the covered works
-for you must do so exclusively on your behalf, under your direction
-and control, on terms that prohibit them from making any copies of
-your copyrighted material outside their relationship with you.
-
-  Conveying under any other circumstances is permitted solely under
-the conditions stated below.  Sublicensing is not allowed; section 10
-makes it unnecessary.
-
-  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
-
-  No covered work shall be deemed part of an effective technological
-measure under any applicable law fulfilling obligations under article
-11 of the WIPO copyright treaty adopted on 20 December 1996, or
-similar laws prohibiting or restricting circumvention of such
-measures.
-
-  When you convey a covered work, you waive any legal power to forbid
-circumvention of technological measures to the extent such circumvention
-is effected by exercising rights under this License with respect to
-the covered work, and you disclaim any intention to limit operation or
-modification of the work as a means of enforcing, against the work's
-users, your or third parties' legal rights to forbid circumvention of
-technological measures.
-
-  4. Conveying Verbatim Copies.
-
-  You may convey verbatim copies of the Program's source code as you
-receive it, in any medium, provided that you conspicuously and
-appropriately publish on each copy an appropriate copyright notice;
-keep intact all notices stating that this License and any
-non-permissive terms added in accord with section 7 apply to the code;
-keep intact all notices of the absence of any warranty; and give all
-recipients a copy of this License along with the Program.
-
-  You may charge any price or no price for each copy that you convey,
-and you may offer support or warranty protection for a fee.
-
-  5. Conveying Modified Source Versions.
-
-  You may convey a work based on the Program, or the modifications to
-produce it from the Program, in the form of source code under the
-terms of section 4, provided that you also meet all of these conditions:
-
-    a) The work must carry prominent notices stating that you modified
-    it, and giving a relevant date.
-
-    b) The work must carry prominent notices stating that it is
-    released under this License and any conditions added under section
-    7.  This requirement modifies the requirement in section 4 to
-    "keep intact all notices".
-
-    c) You must license the entire work, as a whole, under this
-    License to anyone who comes into possession of a copy.  This
-    License will therefore apply, along with any applicable section 7
-    additional terms, to the whole of the work, and all its parts,
-    regardless of how they are packaged.  This License gives no
-    permission to license the work in any other way, but it does not
-    invalidate such permission if you have separately received it.
-
-    d) If the work has interactive user interfaces, each must display
-    Appropriate Legal Notices; however, if the Program has interactive
-    interfaces that do not display Appropriate Legal Notices, your
-    work need not make them do so.
-
-  A compilation of a covered work with other separate and independent
-works, which are not by their nature extensions of the covered work,
-and which are not combined with it such as to form a larger program,
-in or on a volume of a storage or distribution medium, is called an
-"aggregate" if the compilation and its resulting copyright are not
-used to limit the access or legal rights of the compilation's users
-beyond what the individual works permit.  Inclusion of a covered work
-in an aggregate does not cause this License to apply to the other
-parts of the aggregate.
-
-  6. Conveying Non-Source Forms.
-
-  You may convey a covered work in object code form under the terms
-of sections 4 and 5, provided that you also convey the
-machine-readable Corresponding Source under the terms of this License,
-in one of these ways:
-
-    a) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by the
-    Corresponding Source fixed on a durable physical medium
-    customarily used for software interchange.
-
-    b) Convey the object code in, or embodied in, a physical product
-    (including a physical distribution medium), accompanied by a
-    written offer, valid for at least three years and valid for as
-    long as you offer spare parts or customer support for that product
-    model, to give anyone who possesses the object code either (1) a
-    copy of the Corresponding Source for all the software in the
-    product that is covered by this License, on a durable physical
-    medium customarily used for software interchange, for a price no
-    more than your reasonable cost of physically performing this
-    conveying of source, or (2) access to copy the
-    Corresponding Source from a network server at no charge.
-
-    c) Convey individual copies of the object code with a copy of the
-    written offer to provide the Corresponding Source.  This
-    alternative is allowed only occasionally and noncommercially, and
-    only if you received the object code with such an offer, in accord
-    with subsection 6b.
-
-    d) Convey the object code by offering access from a designated
-    place (gratis or for a charge), and offer equivalent access to the
-    Corresponding Source in the same way through the same place at no
-    further charge.  You need not require recipients to copy the
-    Corresponding Source along with the object code.  If the place to
-    copy the object code is a network server, the Corresponding Source
-    may be on a different server (operated by you or a third party)
-    that supports equivalent copying facilities, provided you maintain
-    clear directions next to the object code saying where to find the
-    Corresponding Source.  Regardless of what server hosts the
-    Corresponding Source, you remain obligated to ensure that it is
-    available for as long as needed to satisfy these requirements.
-
-    e) Convey the object code using peer-to-peer transmission, provided
-    you inform other peers where the object code and Corresponding
-    Source of the work are being offered to the general public at no
-    charge under subsection 6d.
-
-  A separable portion of the object code, whose source code is excluded
-from the Corresponding Source as a System Library, need not be
-included in conveying the object code work.
-
-  A "User Product" is either (1) a "consumer product", which means any
-tangible personal property which is normally used for personal, family,
-or household purposes, or (2) anything designed or sold for incorporation
-into a dwelling.  In determining whether a product is a consumer product,
-doubtful cases shall be resolved in favor of coverage.  For a particular
-product received by a particular user, "normally used" refers to a
-typical or common use of that class of product, regardless of the status
-of the particular user or of the way in which the particular user
-actually uses, or expects or is expected to use, the product.  A product
-is a consumer product regardless of whether the product has substantial
-commercial, industrial or non-consumer uses, unless such uses represent
-the only significant mode of use of the product.
-
-  "Installation Information" for a User Product means any methods,
-procedures, authorization keys, or other information required to install
-and execute modified versions of a covered work in that User Product from
-a modified version of its Corresponding Source.  The information must
-suffice to ensure that the continued functioning of the modified object
-code is in no case prevented or interfered with solely because
-modification has been made.
-
-  If you convey an object code work under this section in, or with, or
-specifically for use in, a User Product, and the conveying occurs as
-part of a transaction in which the right of possession and use of the
-User Product is transferred to the recipient in perpetuity or for a
-fixed term (regardless of how the transaction is characterized), the
-Corresponding Source conveyed under this section must be accompanied
-by the Installation Information.  But this requirement does not apply
-if neither you nor any third party retains the ability to install
-modified object code on the User Product (for example, the work has
-been installed in ROM).
-
-  The requirement to provide Installation Information does not include a
-requirement to continue to provide support service, warranty, or updates
-for a work that has been modified or installed by the recipient, or for
-the User Product in which it has been modified or installed.  Access to a
-network may be denied when the modification itself materially and
-adversely affects the operation of the network or violates the rules and
-protocols for communication across the network.
-
-  Corresponding Source conveyed, and Installation Information provided,
-in accord with this section must be in a format that is publicly
-documented (and with an implementation available to the public in
-source code form), and must require no special password or key for
-unpacking, reading or copying.
-
-  7. Additional Terms.
-
-  "Additional permissions" are terms that supplement the terms of this
-License by making exceptions from one or more of its conditions.
-Additional permissions that are applicable to the entire Program shall
-be treated as though they were included in this License, to the extent
-that they are valid under applicable law.  If additional permissions
-apply only to part of the Program, that part may be used separately
-under those permissions, but the entire Program remains governed by
-this License without regard to the additional permissions.
-
-  When you convey a copy of a covered work, you may at your option
-remove any additional permissions from that copy, or from any part of
-it.  (Additional permissions may be written to require their own
-removal in certain cases when you modify the work.)  You may place
-additional permissions on material, added by you to a covered work,
-for which you have or can give appropriate copyright permission.
-
-  Notwithstanding any other provision of this License, for material you
-add to a covered work, you may (if authorized by the copyright holders of
-that material) supplement the terms of this License with terms:
-
-    a) Disclaiming warranty or limiting liability differently from the
-    terms of sections 15 and 16 of this License; or
-
-    b) Requiring preservation of specified reasonable legal notices or
-    author attributions in that material or in the Appropriate Legal
-    Notices displayed by works containing it; or
-
-    c) Prohibiting misrepresentation of the origin of that material, or
-    requiring that modified versions of such material be marked in
-    reasonable ways as different from the original version; or
-
-    d) Limiting the use for publicity purposes of names of licensors or
-    authors of the material; or
-
-    e) Declining to grant rights under trademark law for use of some
-    trade names, trademarks, or service marks; or
-
-    f) Requiring indemnification of licensors and authors of that
-    material by anyone who conveys the material (or modified versions of
-    it) with contractual assumptions of liability to the recipient, for
-    any liability that these contractual assumptions directly impose on
-    those licensors and authors.
-
-  All other non-permissive additional terms are considered "further
-restrictions" within the meaning of section 10.  If the Program as you
-received it, or any part of it, contains a notice stating that it is
-governed by this License along with a term that is a further
-restriction, you may remove that term.  If a license document contains
-a further restriction but permits relicensing or conveying under this
-License, you may add to a covered work material governed by the terms
-of that license document, provided that the further restriction does
-not survive such relicensing or conveying.
-
-  If you add terms to a covered work in accord with this section, you
-must place, in the relevant source files, a statement of the
-additional terms that apply to those files, or a notice indicating
-where to find the applicable terms.
-
-  Additional terms, permissive or non-permissive, may be stated in the
-form of a separately written license, or stated as exceptions;
-the above requirements apply either way.
-
-  8. Termination.
-
-  You may not propagate or modify a covered work except as expressly
-provided under this License.  Any attempt otherwise to propagate or
-modify it is void, and will automatically terminate your rights under
-this License (including any patent licenses granted under the third
-paragraph of section 11).
-
-  However, if you cease all violation of this License, then your
-license from a particular copyright holder is reinstated (a)
-provisionally, unless and until the copyright holder explicitly and
-finally terminates your license, and (b) permanently, if the copyright
-holder fails to notify you of the violation by some reasonable means
-prior to 60 days after the cessation.
-
-  Moreover, your license from a particular copyright holder is
-reinstated permanently if the copyright holder notifies you of the
-violation by some reasonable means, this is the first time you have
-received notice of violation of this License (for any work) from that
-copyright holder, and you cure the violation prior to 30 days after
-your receipt of the notice.
-
-  Termination of your rights under this section does not terminate the
-licenses of parties who have received copies or rights from you under
-this License.  If your rights have been terminated and not permanently
-reinstated, you do not qualify to receive new licenses for the same
-material under section 10.
-
-  9. Acceptance Not Required for Having Copies.
-
-  You are not required to accept this License in order to receive or
-run a copy of the Program.  Ancillary propagation of a covered work
-occurring solely as a consequence of using peer-to-peer transmission
-to receive a copy likewise does not require acceptance.  However,
-nothing other than this License grants you permission to propagate or
-modify any covered work.  These actions infringe copyright if you do
-not accept this License.  Therefore, by modifying or propagating a
-covered work, you indicate your acceptance of this License to do so.
-
-  10. Automatic Licensing of Downstream Recipients.
-
-  Each time you convey a covered work, the recipient automatically
-receives a license from the original licensors, to run, modify and
-propagate that work, subject to this License.  You are not responsible
-for enforcing compliance by third parties with this License.
-
-  An "entity transaction" is a transaction transferring control of an
-organization, or substantially all assets of one, or subdividing an
-organization, or merging organizations.  If propagation of a covered
-work results from an entity transaction, each party to that
-transaction who receives a copy of the work also receives whatever
-licenses to the work the party's predecessor in interest had or could
-give under the previous paragraph, plus a right to possession of the
-Corresponding Source of the work from the predecessor in interest, if
-the predecessor has it or can get it with reasonable efforts.
-
-  You may not impose any further restrictions on the exercise of the
-rights granted or affirmed under this License.  For example, you may
-not impose a license fee, royalty, or other charge for exercise of
-rights granted under this License, and you may not initiate litigation
-(including a cross-claim or counterclaim in a lawsuit) alleging that
-any patent claim is infringed by making, using, selling, offering for
-sale, or importing the Program or any portion of it.
-
-  11. Patents.
-
-  A "contributor" is a copyright holder who authorizes use under this
-License of the Program or a work on which the Program is based.  The
-work thus licensed is called the contributor's "contributor version".
-
-  A contributor's "essential patent claims" are all patent claims
-owned or controlled by the contributor, whether already acquired or
-hereafter acquired, that would be infringed by some manner, permitted
-by this License, of making, using, or selling its contributor version,
-but do not include claims that would be infringed only as a
-consequence of further modification of the contributor version.  For
-purposes of this definition, "control" includes the right to grant
-patent sublicenses in a manner consistent with the requirements of
-this License.
-
-  Each contributor grants you a non-exclusive, worldwide, royalty-free
-patent license under the contributor's essential patent claims, to
-make, use, sell, offer for sale, import and otherwise run, modify and
-propagate the contents of its contributor version.
-
-  In the following three paragraphs, a "patent license" is any express
-agreement or commitment, however denominated, not to enforce a patent
-(such as an express permission to practice a patent or covenant not to
-sue for patent infringement).  To "grant" such a patent license to a
-party means to make such an agreement or commitment not to enforce a
-patent against the party.
-
-  If you convey a covered work, knowingly relying on a patent license,
-and the Corresponding Source of the work is not available for anyone
-to copy, free of charge and under the terms of this License, through a
-publicly available network server or other readily accessible means,
-then you must either (1) cause the Corresponding Source to be so
-available, or (2) arrange to deprive yourself of the benefit of the
-patent license for this particular work, or (3) arrange, in a manner
-consistent with the requirements of this License, to extend the patent
-license to downstream recipients.  "Knowingly relying" means you have
-actual knowledge that, but for the patent license, your conveying the
-covered work in a country, or your recipient's use of the covered work
-in a country, would infringe one or more identifiable patents in that
-country that you have reason to believe are valid.
-
-  If, pursuant to or in connection with a single transaction or
-arrangement, you convey, or propagate by procuring conveyance of, a
-covered work, and grant a patent license to some of the parties
-receiving the covered work authorizing them to use, propagate, modify
-or convey a specific copy of the covered work, then the patent license
-you grant is automatically extended to all recipients of the covered
-work and works based on it.
-
-  A patent license is "discriminatory" if it does not include within
-the scope of its coverage, prohibits the exercise of, or is
-conditioned on the non-exercise of one or more of the rights that are
-specifically granted under this License.  You may not convey a covered
-work if you are a party to an arrangement with a third party that is
-in the business of distributing software, under which you make payment
-to the third party based on the extent of your activity of conveying
-the work, and under which the third party grants, to any of the
-parties who would receive the covered work from you, a discriminatory
-patent license (a) in connection with copies of the covered work
-conveyed by you (or copies made from those copies), or (b) primarily
-for and in connection with specific products or compilations that
-contain the covered work, unless you entered into that arrangement,
-or that patent license was granted, prior to 28 March 2007.
-
-  Nothing in this License shall be construed as excluding or limiting
-any implied license or other defenses to infringement that may
-otherwise be available to you under applicable patent law.
-
-  12. No Surrender of Others' Freedom.
-
-  If conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License.  If you cannot convey a
-covered work so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you may
-not convey it at all.  For example, if you agree to terms that obligate you
-to collect a royalty for further conveying from those to whom you convey
-the Program, the only way you could satisfy both those terms and this
-License would be to refrain entirely from conveying the Program.
-
-  13. Use with the GNU Affero General Public License.
-
-  Notwithstanding any other provision of this License, you have
-permission to link or combine any covered work with a work licensed
-under version 3 of the GNU Affero General Public License into a single
-combined work, and to convey the resulting work.  The terms of this
-License will continue to apply to the part which is the covered work,
-but the special requirements of the GNU Affero General Public License,
-section 13, concerning interaction through a network will apply to the
-combination as such.
-
-  14. Revised Versions of this License.
-
-  The Free Software Foundation may publish revised and/or new versions of
-the GNU General Public License from time to time.  Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-  Each version is given a distinguishing version number.  If the
-Program specifies that a certain numbered version of the GNU General
-Public License "or any later version" applies to it, you have the
-option of following the terms and conditions either of that numbered
-version or of any later version published by the Free Software
-Foundation.  If the Program does not specify a version number of the
-GNU General Public License, you may choose any version ever published
-by the Free Software Foundation.
-
-  If the Program specifies that a proxy can decide which future
-versions of the GNU General Public License can be used, that proxy's
-public statement of acceptance of a version permanently authorizes you
-to choose that version for the Program.
-
-  Later license versions may give you additional or different
-permissions.  However, no additional obligations are imposed on any
-author or copyright holder as a result of your choosing to follow a
-later version.
-
-  15. Disclaimer of Warranty.
-
-  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
-APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
-HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
-OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
-THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
-PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
-IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
-ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
-
-  16. Limitation of Liability.
-
-  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
-THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
-GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
-USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
-DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
-PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
-EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
-SUCH DAMAGES.
-
-  17. Interpretation of Sections 15 and 16.
-
-  If the disclaimer of warranty and limitation of liability provided
-above cannot be given local legal effect according to their terms,
-reviewing courts shall apply local law that most closely approximates
-an absolute waiver of all civil liability in connection with the
-Program, unless a warranty or assumption of liability accompanies a
-copy of the Program in return for a fee.
-
-                     END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-    <program>  Copyright (C) <year>  <name of author>
-    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, your program's commands
-might be different; for a GUI interface, you would use an "about box".
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
-
-  The GNU General Public License does not permit incorporating your program
-into proprietary programs.  If your program is a subroutine library, you
-may consider it more useful to permit linking proprietary applications with
-the library.  If this is what you want to do, use the GNU Lesser General
-Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.

LICENSE

@@ -1,7 +1,7 @@
-		   GNU LESSER GENERAL PUBLIC LICENSE
+                   GNU LESSER GENERAL PUBLIC LICENSE
                        Version 3, 29 June 2007
 
- Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  Everyone is permitted to copy and distribute verbatim copies
  of this license document, but changing it is not allowed.
 

MANIFEST.SKIP

@@ -1,6 +1,9 @@
-^CVS/
-/CVS/
+\.ccache/
+\.clang-format
+\.clang-tidy
 \.git/
+\.git$
+\.github/
 \.svn/
 \.(bak|old)/
 \.(bak|old)$
@@ -9,30 +12,52 @@
 .*\.log
 \..*\.swp
 .*\.tmp
+.*\.tidy
 .*\.tex
 .*\.key
 .*\.vcd
 .*\.1
-/obj_dir/
+\.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/
-/obj_dist/
-/INCA_libs/
+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\.log
+verilator\.tex
+verilator-config.cmake$
+verilator-config-version.cmake$
 verilator.pc$
 verilator_bin.*
 verilator_coverage_bin.*
@@ -40,11 +65,12 @@ verilator_coverage_bin.*
 ncverilog.history
 autom4te\.cache/
 nodist/
+ci/
 /simv$
 /simv.daidir/
 /vc_hdrs.h$
 /csrc/
-doxygen-doc/.*
-obj_dir/.*
+obj_dir.*
 TAGS
+gmon.out
 .*~

Makefile.in

@@ -3,19 +3,15 @@
 #
 # This file is part of Verilator.
 #
-# Code available from: http://www.veripool.org/verilator
+# Code available from: https://verilator.org
 #
 #*****************************************************************************
 #
-# Copyright 2003-2018 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
+# Copyright 2003-2021 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.
-#
-# Verilator is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 #
 #****************************************************************************/
 #
@@ -55,9 +51,12 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
 MAKEINFO = makeinfo
 POD2TEXT = pod2text
-POD2LATEXFIX = $(srcdir)/src/pod2latexfix
+MKINSTALLDIRS = $(SHELL) $(srcdir)/src/mkinstalldirs
 PERL = @PERL@
 
+# Version (for docs/guide/conf.py)
+PACKAGE_VERSION_NUMBER = @PACKAGE_VERSION_NUMBER@
+
 # Destination prefix for RPMs
 DESTDIR =
 
@@ -82,7 +81,7 @@ infodir = @infodir@
 pkgdatadir = @pkgdatadir@
 
 # Directory in which to install pkgconfig file
-# Generall ${prefix}/share/pkgconfig
+# Generally ${prefix}/share/pkgconfig
 pkgconfigdir = @pkgconfigdir@
 
 # Directory in which to install data across multiple architectures
@@ -92,7 +91,6 @@ datarootdir = @datarootdir@
 CFG_WITH_CCWARN = @CFG_WITH_CCWARN@
 CFG_WITH_DEFENV = @CFG_WITH_DEFENV@
 CFG_WITH_LONGTESTS = @CFG_WITH_LONGTESTS@
-CFG_WITH_THREADED = @CFG_WITH_THREADED@
 PACKAGE_VERSION = @PACKAGE_VERSION@
 
 #### End of system configuration section. ####
@@ -102,46 +100,88 @@ PACKAGE_VERSION = @PACKAGE_VERSION@
 
 SHELL = /bin/sh
 
-SUBDIRS = src test_regress \
-	examples/hello_world_c  examples/hello_world_sc \
-	examples/tracing_c  examples/tracing_sc \
+SUBDIRS = docs src test_regress \
+	examples/cmake_hello_c \
+	examples/cmake_hello_sc \
+	examples/cmake_tracing_c \
+	examples/cmake_tracing_sc \
+	examples/cmake_protect_lib \
+	examples/make_hello_c \
+	examples/make_hello_sc \
+	examples/make_tracing_c \
+	examples/make_tracing_sc \
+	examples/make_protect_lib \
+	examples/xml_py \
 
-INFOS = README README.html README.pdf internals.txt internals.html \
-        internals.pdf verilator.txt verilator.html verilator.pdf \
-	$(VL_INST_MAN_FILES)
+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
 
-DISTFILES_INC = $(INFOS) .gitignore Artistic COPYING COPYING.LESSER \
+DISTFILES1 = $(INFOS) .gitignore \
 	*.in *.ac \
-	Changes TODO \
+	Artistic \
+	Changes \
+	LICENSE \
 	MANIFEST.SKIP \
+	README.rst \
+	verilator-config.cmake.in \
+	verilator-config-version.cmake.in \
 	bin/verilator \
 	bin/verilator_coverage \
 	bin/verilator_difftree \
+	bin/verilator_gantt \
 	bin/verilator_includer \
 	bin/verilator_profcfunc \
-	doxygen-mainpage doxygen.config veripool-logo.png \
-	install-sh configure mkinstalldirs *.pod \
+	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/vlcovgen \
+	src/config_rev \
+	src/vlcovgen src/mkinstalldirs \
 	src/.gdbinit \
 	src/*.pl src/*.pod \
 	examples/*/.*ignore examples/*/Makefile* \
-	examples/*/*.[chv]* examples/*/*.pl \
+	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 \
@@ -154,10 +194,12 @@ DISTFILES_INC = $(INFOS) .gitignore Artistic COPYING COPYING.LESSER \
 INST_PROJ_FILES = \
 	bin/verilator \
 	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 = \
@@ -165,13 +207,14 @@ INST_PROJ_BIN_FILES = \
 	bin/verilator_bin_dbg \
 	bin/verilator_coverage_bin_dbg \
 
-DISTFILES := $(DISTFILES_INC)
+EXAMPLES_FIRST = \
+	examples/make_hello_c \
+	examples/make_hello_sc \
 
-ifeq ($(OBJCACHE_JOBS),)
-ifneq ($(OBJCACHE_HOSTS),)
-export OBJCACHE_JOBS := -j $(shell objcache --jobs "$(OBJCACHE_HOSTS)")
-endif
-endif
+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
 
 default: all
 all: all_nomsg msg_test
@@ -183,8 +226,8 @@ all_nomsg: verilator_exe $(VL_INST_MAN_FILES)
 .PHONY:verilator_coverage_bin_dbg
 verilator_exe verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg:
 	@echo ------------------------------------------------------------
-	@echo "making verilator in src" ; \
-	  (cd src && $(MAKE) $(OBJCACHE_JOBS) )
+	@echo "making verilator in src"
+	$(MAKE) -C src $(OBJCACHE_JOBS) $(CI_MAKE_SRC_TARGET)
 
 .PHONY:msg_test
 msg_test: all_nomsg
@@ -195,7 +238,9 @@ msg_test: all_nomsg
 
 .PHONY: test
 ifeq ($(CFG_WITH_LONGTESTS),yes)	# Local... Else don't burden users
-test: smoke-test examples test_regress
+test: smoke-test test_regress
+# examples is part of test_regress's test_regress/t/t_a2_examples.pl
+# (because that allows it to run in parallel with other test_regress's)
 else
 test: smoke-test examples
 endif
@@ -206,79 +251,40 @@ endif
 	@echo
 
 smoke-test: all_nomsg
-	test_regress/t/t_a_first_cc.pl
-	test_regress/t/t_a_first_sc.pl
+	test_regress/t/t_a1_first_cc.pl
+	test_regress/t/t_a2_first_sc.pl
 
 test_regress: all_nomsg
-	@(cd test_regress && $(MAKE))
+	$(MAKE) -C test_regress
 
 examples: all_nomsg
-	for p in examples/* ; do \
+	for p in $(EXAMPLES) ; do \
 	  $(MAKE) -C $$p VERILATOR_ROOT=`pwd` || exit 10; \
 	done
 
+.PHONY: docs
+docs: info
+
 info: $(INFOS)
 
-# Use --no-split to avoid creating filenames > 14 chars.
 %.1: ${srcdir}/bin/%
 	pod2man $< $@
 
-verilator.txt: ${srcdir}/bin/verilator
-	$(POD2TEXT) $< $@
-
-verilator.html: ${srcdir}/bin/verilator
-	pod2html $< >$@
+.PHONY: verilator.html
+verilator.html:
+	$(MAKE) -C docs html
 
 # PDF needs DIST variables; but having configure.ac as dependency isn't detected
-verilator.pdf: ${srcdir}/bin/verilator Makefile
-	pod2latex --full --out verilator.tex ${srcdir}/bin/verilator
-	$(PERL) $(POD2LATEXFIX) "$(DISTTITLE)" "${DISTDATE}" < verilator.tex > verilator2.tex
-	mv verilator2.tex verilator.tex
-	pdflatex verilator.tex
-	pdflatex verilator.tex
-	-rm -f verilator.toc verilator.aux verilator.idx verilator.out
-
-README: README.pod
-	-rm -f $@
-	$(POD2TEXT) --loose $< > $@
-
-README.html: README.pod
-	pod2html $< >$@
-
-# PDF needs DIST variables; but having configure.ac as dependency isn't detected
-README.pdf: README.pod Makefile
-	pod2latex --full --out README.tex README.pod
-	$(PERL) $(POD2LATEXFIX) "$(DISTTITLE) README File" "${DISTDATE}" < README.tex > README2.tex
-	mv README2.tex README.tex
-	pdflatex README.tex
-	pdflatex README.tex
-	-rm -f README.toc README.aux README.idx README.out
-
-internals.txt: internals.pod
-	-rm -f $@
-	$(POD2TEXT) --loose $< > $@
-
-internals.html: internals.pod
-	pod2html $< >$@
-
-# PDF needs DIST variables; but having configure.ac as dependency isn't detected
-internals.pdf: internals.pod Makefile
-	pod2latex --full --out internals.tex internals.pod
-	$(PERL) $(POD2LATEXFIX) "$(DISTTITLE) Internals Manual" "${DISTDATE}" < internals.tex > internals2.tex
-	mv internals2.tex internals.tex
-	pdflatex internals.tex
-	pdflatex internals.tex
-	-rm -f internals.toc internals.aux internals.idx internals.out
+.PHONY: verilator.pdf
+verilator.pdf: Makefile
+	$(MAKE) -C docs verilator.pdf
 
 # See uninstall also - don't put wildcards in this variable, it might uninstall other stuff
 VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg \
-	verilator_coverage verilator_includer verilator_profcfunc
+	verilator_coverage verilator_gantt verilator_includer verilator_profcfunc
 # Some scripts go into both the search path and pkgdatadir,
 # so they can be found by the user, and under $VERILATOR_ROOT.
 
-# 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_profcfunc.1
-
 VL_INST_INC_BLDDIR_FILES = \
 	include/verilated_config.h \
 	include/verilated.mk \
@@ -286,33 +292,36 @@ VL_INST_INC_BLDDIR_FILES = \
 # Files under srcdir, instead of build time
 VL_INST_INC_SRCDIR_FILES = \
 	include/*.[chv]* \
+	include/gtkwave/*.[chv]* \
 	include/vltstd/*.[chv]* \
 
 VL_INST_DATA_SRCDIR_FILES = \
 	examples/*/*.[chv]*  examples/*/Makefile* \
+	examples/*/CMakeLists.txt
 
 installbin:
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(bindir)
+	$(MKINSTALLDIRS) $(DESTDIR)$(bindir)
 	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator $(DESTDIR)$(bindir)/verilator )
 	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_coverage $(DESTDIR)$(bindir)/verilator_coverage )
+	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_gantt $(DESTDIR)$(bindir)/verilator_gantt )
 	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_profcfunc $(DESTDIR)$(bindir)/verilator_profcfunc )
-	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_bin $(DESTDIR)$(bindir)/verilator_bin )
-	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_bin_dbg $(DESTDIR)$(bindir)/verilator_bin_dbg )
-	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_coverage_bin_dbg $(DESTDIR)$(bindir)/verilator_coverage_bin_dbg )
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/bin
+	( cd bin ; $(INSTALL_PROGRAM) verilator_bin $(DESTDIR)$(bindir)/verilator_bin )
+	( cd bin ; $(INSTALL_PROGRAM) verilator_bin_dbg $(DESTDIR)$(bindir)/verilator_bin_dbg )
+	( cd bin ; $(INSTALL_PROGRAM) verilator_coverage_bin_dbg $(DESTDIR)$(bindir)/verilator_coverage_bin_dbg )
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/bin
 	( cd ${srcdir}/bin ; $(INSTALL_PROGRAM) verilator_includer $(DESTDIR)$(pkgdatadir)/bin/verilator_includer )
 
 # Man files can either be part of the original kit, or built in current directory
-# So important we use $< so VPATH is searched
+# So important we use $^ so VPATH is searched
 installman: $(VL_INST_MAN_FILES)
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(mandir)/man1
-	cd $(srcdir) \
-	; for p in $(VL_INST_MAN_FILES) ; do \
+	$(MKINSTALLDIRS) $(DESTDIR)$(mandir)/man1
+	for p in $^ ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(mandir)/man1/$$p; \
 	done
 
 installdata:
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/include/vltstd
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/include/gtkwave
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/include/vltstd
 	for p in $(VL_INST_INC_BLDDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
@@ -320,16 +329,25 @@ installdata:
 	; for p in $(VL_INST_INC_SRCDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/examples/hello_world_c
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/examples/hello_world_sc
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/examples/tracing_c
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/examples/tracing_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_protect_lib
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_protect_lib
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/xml_py
 	cd $(srcdir) \
 	; for p in $(VL_INST_DATA_SRCDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgconfigdir)
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgconfigdir)
 	$(INSTALL_DATA) verilator.pc $(DESTDIR)$(pkgconfigdir)
+	$(INSTALL_DATA) verilator-config.cmake $(DESTDIR)$(pkgdatadir)
+	$(INSTALL_DATA) verilator-config-version.cmake $(DESTDIR)$(pkgdatadir)
 
 # We don't trust rm -rf, so rmdir instead as it will fail if user put in other files
 uninstall:
@@ -340,13 +358,23 @@ uninstall:
 	-cd $(DESTDIR)$(pkgdatadir) && rm -f $(VL_INST_INC_SRCDIR_FILES)
 	-cd $(DESTDIR)$(pkgdatadir) && rm -f $(VL_INST_DATA_SRCDIR_FILES)
 	-rm $(DESTDIR)$(pkgconfigdir)/verilator.pc
+	-rm $(DESTDIR)$(pkgdatadir)/verilator-config.cmake
+	-rm $(DESTDIR)$(pkgdatadir)/verilator-config-version.cmake
 	-rmdir $(DESTDIR)$(pkgdatadir)/bin
+	-rmdir $(DESTDIR)$(pkgdatadir)/include/gtkwave
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/vltstd
 	-rmdir $(DESTDIR)$(pkgdatadir)/include
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/hello_world_c
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/hello_world_sc
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/tracing_c
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/tracing_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_protect_lib
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_protect_lib
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/xml_py
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples
 	-rmdir $(DESTDIR)$(pkgdatadir)
 	-rmdir $(DESTDIR)$(pkgconfigdir)
@@ -359,40 +387,15 @@ 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)
 
-DIRPROJECT := $(shell project_dir --project)
 VERILATOR_CAD_DIR = $(CAD_DIR)/verilator/$(DISTNAMEREV)/$(DIRPROJECT_ARCH)
 INST_PROJ_CVS = cp_if_cvs_diff
 
-install-project: dist
-	@echo "Install-project to $(DIRPROJECT)"
-	strip bin/verilator_bin*
-	strip bin/verilator_coverage_bin*
-	$(MAKE) install-project-quick
-	for p in $(VL_INST_MAN_FILES) ; do \
-	  $(INSTALL_DATA) $$p $(DIRPROJECT_PREFIX)/man/man1/$$p; \
-	done
-	$(INST_PROJ_CVS) $(DISTNAME).tgz $(DIRPROJECT)/hw/utils/verilator/verilator.tgz
-	rm $(DISTNAME).tgz
-
-install-project-quick:
-ifeq ($(CFG_WITH_DEFENV),yes)
-	@echo "%Error: Reconfigure with './configure --disable-defenv' to avoid hardcoded paths."
-	false
-endif
-	@echo "Install-project-quick (no strip) to $(DIRPROJECT)"
-	for p in $(INST_PROJ_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(DIRPROJECT)/hw/utils/verilator/$$p; \
-	done
-	for p in $(INST_PROJ_BIN_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(DIRPROJECT)/hw/utils/verilator/$$p-$(DIRPROJECT_ARCH); \
-	done
-
 install-cadtools: dist
 	@echo "Install-project to $(CAD_DIR)"
 	strip bin/verilator_bin*
 	strip bin/verilator_coverage_bin*
 	$(MAKE) install-cadtools-quick
-	$(SHELL) ${srcdir}/mkinstalldirs $(VERILATOR_CAD_DIR)/man/man1
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/man/man1
 	for p in $(VL_INST_MAN_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(VERILATOR_CAD_DIR)/man/man1/$$p; \
 	done
@@ -405,8 +408,9 @@ ifeq ($(CFG_WITH_DEFENV),yes)
 	false
 endif
 	@echo "Install-cadtools-quick (no strip) to $(VERILATOR_CAD_DIR)"
-	$(SHELL) ${srcdir}/mkinstalldirs $(VERILATOR_CAD_DIR)/include/vltstd
-	$(SHELL) ${srcdir}/mkinstalldirs $(VERILATOR_CAD_DIR)/bin
+	$(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
@@ -418,17 +422,39 @@ endif
 endif
 
 # Use --xml flag to see the cppcheck code to use for suppression
-CPPCHECK = src/cppcheck_filtered
+CPPCHECK_CPP = $(wildcard \
+	$(srcdir)/examples/*/*.cpp \
+	$(srcdir)/include/*.cpp \
+	$(srcdir)/src/*.cpp )
+CPPCHECK_H = $(wildcard \
+	$(srcdir)/include/*.h \
+	$(srcdir)/src/*.h )
+CPPCHECK_YL = $(wildcard \
+	$(srcdir)/src/*.y \
+	$(srcdir)/src/*.l )
+CPPCHECK = src/cppcheck_filtered cppcheck
 CPPCHECK_FLAGS = --enable=all --inline-suppr \
-	--suppress=unusedScopedObject --suppress=cstyleCast --suppress=useInitializationList
+	--suppress=unusedScopedObject --suppress=cstyleCast --suppress=useInitializationList \
+	--suppress=nullPointerRedundantCheck
 CPPCHECK_FLAGS += --xml
-CPPCHECK_CPP = $(wildcard $(srcdir)/include/*.cpp $(srcdir)/src/*.cpp)
 CPPCHECK_DEP = $(subst .cpp,.cppcheck,$(CPPCHECK_CPP))
 CPPCHECK_INC = -I$(srcdir)/include -I$(srcdir)/src/obj_dbg -I$(srcdir)/src
 
 cppcheck: $(CPPCHECK_DEP)
 %.cppcheck: %.cpp
-	$(CPPCHECK) $(CPPCHECK_FLAGS) -DVL_DEBUG=1 -DVL_CPPCHECK=1 $(CPPCHECK_INC) $<
+	$(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_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 $@
 
 analyzer-src:
 	-rm -rf src/obj_dbg
@@ -438,6 +464,62 @@ analyzer-include:
 	-rm -rf examples/*/obj*
 	scan-build $(MAKE) -k examples
 
+format: clang-format yapf format-pl-exec
+
+CLANGFORMAT = clang-format
+CLANGFORMAT_FLAGS = -i
+CLANGFORMAT_FILES = $(CPPCHECK_CPP) $(CPPCHECK_H) $(CPPCHECK_YL) test_regress/t/*.c* test_regress/t/*.h
+
+clang-format:
+	@$(CLANGFORMAT) --version | egrep 10.0 > /dev/null \
+		|| echo "*** You are not using clang-format 10.0, indents may differ from master's ***"
+	$(CLANGFORMAT) $(CLANGFORMAT_FLAGS) $(CLANGFORMAT_FILES)
+
+PY_PROGRAMS = \
+	examples/xml_py/vl_file_copy \
+	examples/xml_py/vl_hier_graph \
+	docs/guide/conf.py \
+	docs/guide/vl_sphinx_extract \
+	docs/guide/vl_sphinx_extract \
+	docs/guide/vl_doxygen_filter \
+	src/astgen \
+	src/bisonpre \
+	src/config_rev \
+	src/cppcheck_filtered \
+	src/flexfix \
+	src/vlcovgen \
+	nodist/code_coverage \
+	nodist/dot_importer \
+	nodist/fuzzer/actual_fail \
+	nodist/fuzzer/generate_dictionary \
+	nodist/install_test \
+
+PY_FILES = \
+	$(PY_PROGRAMS) \
+	nodist/code_coverage.dat \
+
+YAPF = yapf3
+YAPF_FLAGS = -i
+
+yapf:
+	$(YAPF) $(YAPF_FLAGS) $(PY_FILES)
+
+FLAKE8 = flake8
+FLAKE8_FLAGS = \
+	--extend-exclude=fastcov.py \
+	--ignore=E123,E129,E251,E501,W503,W504,E701
+
+PYLINT = pylint
+PYLINT_FLAGS = --disable=R0801
+
+lint-py:
+	-$(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
+	-$(PYLINT) $(PYLINT_FLAGS) $(PY_PROGRAMS)
+
+format-pl-exec:
+	-chmod a+x test_regress/t/*.pl
+
+
 ftp: info
 
 install-msg:
@@ -447,7 +529,7 @@ install-msg:
 	@echo "Installed examples to $(DESTDIR)$(pkgdatadir)/examples"
 	@echo
 	@echo "For documentation see 'man verilator' or 'verilator --help'"
-	@echo "For forums and to report bugs see http://www.veripool.org/verilator"
+	@echo "For forums and to report bugs see https://verilator.org"
 	@echo
 
 IN_WILD := ${srcdir}/*.in ${srcdir}/*/*.in
@@ -471,13 +553,13 @@ endif
 
 maintainer-clean::
 	@echo "This command is intended for maintainers to use;"
-	@echo "rebuilding the deleted files requires makeinfo."
-	rm -f *.info* *.1 $(INFOS) configure
+	@echo "rebuilding the deleted files requires autoconf."
+	rm -f configure
 
 clean mostlyclean distclean maintainer-clean maintainer-copy::
 	for dir in $(SUBDIRS); do \
 	  echo making $@ in $$dir ; \
-	  (cd $$dir && $(MAKE) $@) ; \
+	  $(MAKE) -C $$dir $@ ; \
 	done
 
 clean mostlyclean distclean maintainer-clean::
@@ -486,10 +568,14 @@ 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 -rf examples/*/obj_dir* examples/*/logs
 	rm -rf test_*/obj_dir
-	rm -rf examples/*/obj_dir examples/*/logs
+	rm -rf nodist/fuzzer/dictionary
+	rm -rf nodist/obj_dir
+	rm -rf verilator.txt
 
 distclean maintainer-clean::
+	rm -f *.info* *.1 $(INFOS) $(INFOS_OLD) $(VL_INST_MAN_FILES)
 	rm -f Makefile config.status config.cache config.log TAGS
 	rm -f verilator_bin* verilator_coverage_bin*
 	rm -f bin/verilator_bin* bin/verilator_coverage_bin*
@@ -504,19 +590,17 @@ TAGS:	$(TAGFILES)
 .PHONY: doxygen
 
 doxygen:
-	$(DOXYGEN) doxygen.config
+	$(MAKE) -C docs doxygen
 
 ######################################################################
 # Test targets
 
 dist-file-list:
 	@echo "begin-dist-file-list:";  # Scripts look for this
-	@echo $(wildcard $(DISTFILES))
+	@echo $(wildcard $(DISTFILES1))
+	@echo $(wildcard $(DISTFILES2))
 	@echo "end-dist-file-list:";  # Scripts look for this
 
-print-cfg-with-threaded:
-	@echo $(CFG_WITH_THREADED)
-
 ######################################################################
 # Distributions
 
@@ -533,7 +617,12 @@ tag:
 # Don't depend on DISTFILES because there's no rule for "standards.info*".
 dist: $(DISTDEP) maintainer-copy
 	-rm -fr $(DISTNAME)
-	for file in $(DISTFILES); do \
+	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;}; \

README.pod

@@ -1,204 +0,0 @@
-# DESCRIPTION: DOCUMENT source run through perl to produce README file
-# Use 'make README' to produce the output file
-
-=pod
-
-=head1 NAME
-
-This is the Verilator package README file.
-
-=head1 DISTRIBUTION
-
-http://www.veripool.org/verilator
-
-This package is Copyright 2003-2018 by Wilson Snyder.  (Report bugs to
-L<http://www.veripool.org/>.)
-
-Verilator is free software; you can redistribute it and/or modify it under
-the terms of either the GNU Lesser General Public License Version 3 or the
-Perl Artistic License Version 2.0.  (See the documentation for more
-details.)
-
-This program is distributed in the hope that it will be useful, but WITHOUT
-ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
-more details.
-
-=head1 DESCRIPTION
-
-Verilator converts synthesizable (generally not behavioral) Verilog code
-into C++ or SystemC code.  It is not a complete simulator, just a
-translator.
-
-Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
-reads the specified Verilog code, lints it, and optionally adds coverage
-code.  For C++ format, it outputs .cpp and .h files.  For SystemC format,
-it outputs .cpp and .h files using the standard SystemC headers.
-
-The resulting files are then compiled with C++.  The user writes a little
-C++ wrapper file, which instantiates the top level module.  This is
-compiled in C++, and linked with the Verilated files.
-
-The resulting executable will perform the actual simulation.
-
-=head1 SUPPORTED SYSTEMS
-
-Verilator is developed and has primary testing on Ubuntu.  Versions have
-also built on Redhat Linux, Macs OS-X, HPUX and Solaris.  It should run
-with minor porting on any Linix-ish platform.  Verilator also works on
-Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin).  Verilated
-output (not Verilator itself) compiles under MSVC++ 2008 and newer.
-
-=head1 INSTALLATION
-
-For more details see
-L<http://www.veripool.org/projects/verilator/wiki/Installing>.
-
-If you will be modifying Verilator, you should use the "git" method as it
-will let you track changes.
-
-=over 4
-
-=item
-
-The latest version is available at L<http://www.veripool.org/verilator>.
-
-Download the latest package from that site, and decompress.
-
-    tar xvzf verilator_version.tgz
-
-=item
-
-If you will be using SystemC (vs straight C++ output), download SystemC
-from L<http://www.systemc.org>.  Follow their installation instructions.
-You will need to set SYSTEMC_INCLUDE to point to the include directory with
-systemc.h in it, and SYSTEMC_LIBDIR to points to the directory with
-libsystemc.a in it.  (Older installations may set SYSTEMC and SYSTEMC_ARCH
-instead.)
-
-=item
-
-You will need the C<flex> and C<bison> packages installed.
-
-=item
-
-C<cd> to the Verilator directory containing this README.
-
-=item
-
-You now have to decide how you're going to eventually install the kit.
-
-Note Verilator builds the current value of VERILATOR_ROOT, SYSTEMC_INCLUDE,
-and SYSTEMC_LIBDIR as defaults into the executable, so try to have them
-correct before configuring.
-
-=over 4
-
-=item 1.
-
-Our personal favorite is to always run Verilator from the kit directory.
-This allows the easiest experimentation and upgrading.  It's also how most
-EDA tools operate; to run you point to the tarball, no install is needed.
-
-    export VERILATOR_ROOT=`pwd`   # if your shell is bash
-    setenv VERILATOR_ROOT `pwd`   # if your shell is csh
-    ./configure
-
-=item 2.
-
-To install globally onto a "cad" disk with multiple versions of every tool,
-and add it to path using Modules/modulecmd:
-
-    unset VERILATOR_ROOT      # if your shell is bash
-    unsetenv VERILATOR_ROOT   # if your shell is csh
-    # For the tarball, use the version number instead of git describe
-    ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`
-
-    After installing you'll want a module file like the following:
-
-    set install_root /CAD_DISK/verilator/{version-number-used-above}
-    unsetenv VERILATOR_ROOT
-    prepend-path PATH $install_root/bin
-    prepend-path MANPATH $install_root/man
-    prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
-
-=item 3.
-
-The next option is to install it globally, using the normal system paths:
-
-    unset VERILATOR_ROOT      # if your shell is bash
-    unsetenv VERILATOR_ROOT   # if your shell is csh
-    ./configure
-
-=item 4.
-
-Alternatively you can configure a prefix that install will populate, as
-most GNU tools support:
-
-    unset VERILATOR_ROOT      # if your shell is bash
-    unsetenv VERILATOR_ROOT   # if your shell is csh
-    ./configure --prefix /opt/verilator-VERSION
-
-Then after installing you will need to add /opt/verilator-VERSION/bin to
-PATH.
-
-=back
-
-=item
-
-Type C<make> to compile Verilator.
-
-Type C<make test> to check the compilation.
-
-Configure with C<--enable-longtests> for more complete developer tests.
-Additional packages may be required for these tests.
-
-You may get a error about a typedef conflict for uint32_t.  Edit
-verilated.h to change the typedef to work, probably to @samp{typedef
-unsigned long uint32_t;}.
-
-=item
-
-If you used the VERILATOR_ROOT scheme you're done.  Programs should set the
-environment variable VERILATOR_ROOT to point to this distribution, then
-execute $VERILATOR_ROOT/bin/verilator, which will find the path to all
-needed files.
-
-If you used the prefix scheme, now do a C<make install>.  To run verilator,
-have the verilator binary directory in your PATH (this should already be
-true if using the default configure), and make sure VERILATOR_ROOT is not
-set.
-
-You may now wish to consult the examples directory. Type C<make> inside any
-example directory to run the example.
-
-=back
-
-=head1 USAGE DOCUMENTATION
-
-Detailed documentation and the man page can be seen by running:
-
-    bin/verilator --help
-
-or reading verilator.txt in the same directory as this README.
-
-=head1 DIRECTORY STRUCTURE
-
-The directories in the kit after de-taring are as follows:
-
-    bin/verilator               => Compiler Wrapper invoked to Verilate code
-    include/                    => Files that should be in your -I compiler path
-    include/verilated*.cpp      => Global routines to link into your simulator
-    include/verilated*.h        => Global headers
-    include/verilated.v         => Stub defines for linting
-    include/verilated.mk        => Common makefile
-    src/                        => Translator source code
-    examples/hello_world_c      => Example simple Verilog->C++ conversion
-    examples/hello_world_sc     => Example simple Verilog->SystemC conversion
-    examples/tracing_c          => Example Verilog->C++ with tracing
-    examples/tracing_sc         => Example Verilog->SystemC with tracing
-    test_regress                => Internal tests
-
-=head1 LIMITATIONS
-
-See verilator.txt (or execute C<bin/verilator --help>) for limitations.

README.rst

@@ -0,0 +1,151 @@
+.. Github doesn't render images unless absolute URL
+.. Do not know of a conditional tag, "only: github" nor "github display" works
+
+.. image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
+    :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://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
+    :target: https://codecov.io/gh/verilator/verilator
+.. 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
+        * 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
+        * Single- and multi-threaded output models
+   * - **Widely Used**
+        * Wide industry and academic deployment
+        * Out-of-the-box support from Arm, and RISC-V vendor IP
+     - |verilator usage|
+   * - |verilator community|
+     - **Community Driven & Openly Licensed**
+        * Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
+        * Open, and free as in both speech and beer
+        * More simulation for your verification budget
+   * - **Commercial Support Available**
+        * Commercial support contracts
+        * Design support contracts
+        * Enhancement contracts
+     - |verilator support|
+
+
+What Verilator Does
+===================
+
+Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
+"Verilates" the specified Verilog or SystemVerilog code by reading it,
+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.
+
+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.
+
+
+Performance
+===========
+
+Verilator does not simply convert 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
+single-thread over 10x faster than standalone SystemC, and on a single
+thread is about 100 times faster than interpreted Verilog simulators such
+as `Icarus Verilog`_. Another 2-10x speedup might be gained from
+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.
+
+Installation & Documentation
+============================
+
+For more information:
+
+- `Verilator installation and package directory structure
+  <https://verilator.org/install>`_
+
+- `Verilator manual (HTML) <https://verilator.org/verilator_doc.html>`_,
+  or `Verilator manual (PDF) <https://verilator.org/verilator_doc.pdf>`_
+
+- `Subscribe to verilator announcements
+  <https://github.com/verilator/verilator-announce>`_
+
+- `Verilator forum <https://verilator.org/forum>`_
+
+- `Verilator issues <https://verilator.org/issues>`_
+
+
+Support
+=======
+
+Verilator is a community project, guided by the `CHIPS Alliance`_ under the
+`Linux Foundation`_.
+
+We appreciate and welcome your contributions in whatever form; please see
+`Contributing to Verilator
+<https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst>`_.
+Thanks to our `Contributors and Sponsors
+<https://verilator.org/guide/latest/contributors.html>`_.
+
+Verilator also supports and encourages commercial support models and
+organizations; please see `Verilator Commercial Support
+<https://verilator.org/verilator_commercial_support>`_.
+
+
+Related Projects
+================
+
+- `GTKwave <http://gtkwave.sourceforge.net/>`_ - Waveform viewer for
+  Verilator traces.
+
+- `Icarus Verilog`_ - Icarus is a full featured interpreted Verilog
+  simulator. If Verilator does not support your needs, perhaps Icarus may.
+
+
+Open License
+============
+
+Verilator is Copyright 2003-2021 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
+the terms of either the GNU Lesser General Public License Version 3 or the
+Perl Artistic License Version 2.0. See the documentation for more details.
+
+.. _CHIPS Alliance: https://chipsalliance.org
+.. _Icarus Verilog: http://iverilog.icarus.com
+.. _Linux Foundation: https://www.linuxfoundation.org
+.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png
+.. |verilator multithreaded performance| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png
+.. |verilator usage| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png
+.. |verilator community| image:: https://www.veripool.org/img/verilator_community_400x125-min.png
+.. |verilator support| image:: https://www.veripool.org/img/verilator_support_400x125-min.png

TODO

@@ -1,123 +0,0 @@
-// DESCRIPTION: Verilator: List of To Do issues.
-//
-// Copyright 2004-2018 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.
-
-
-Language support:
-	* Fix ordering of each bit separately in a signal (mips)
-		assign b[3:0] = b[7:4];  assign b[7:4] = in;
-	* Support UDP gate primitives/ cell libraries
-		(have code for combos - problem is sequential udps)
-	* Function to eval combo logic after /*verilator public*/ functions [gwaters]
-	* Support generated clocks (correctness)
-	* Real numbers
-	* Recursive functions
-	* Verilog configuration files
-	* Structs/unions (have starting point)
-	* DPI to define C/C++ calls from Verilog
-	* Expression coverage (see notes)
-	* Better tristate support
-
-Long-term Features
-	* Assertions
-	* Tristate support
-	* Multithreaded execution
-
-Configure/Make/Install
-	* Distribute with flex/bison already expanded?
-	  Flex library not needed.  Probably too difficult to be worth it.
-
-Testing:
-	* Capture all inputs into global "rerun it" file
-	* Code to make wrapper that sets signals, so can do comparison checks
-	* New random program generator
-	* Better graph viewer with search and zoom
-	* Port and test against opencores.org code
-	* // verilator debug in code so can see only tree affecting those nodes
-
-Usability:
-	* Detect and pre-remove most UNOPTFLATs (4.000)
-	* Better reporting of unopt problems, including what lines of code
-	* Report more errors (all of them?) before exiting [Eugene Weber]
-	* Auto-create scons config files
-	* Print version/etc message at runtime. (4.000?)
-	  Include number of lines of code, percent comments, code complexity measurement
-	  <-80chars------------------------------------------------------------------->
-	  Verilator 3.600 - The fast free open-sourced simulator.  Copyright 2001-2013.
-	  Verilated #### modules, #### instances, ##### sigs,
-	  	    #### non-comment lines, ##### ops, ### KB model size
-
-Lint:
-	* CDCRSTLOGIC should allow filtering with paths
-	  "waive CDCRSTLOGIC --from a.b.sig  --to a.c.sig --via OR"
-
-Internal Code:
-	* A Visitor class that understands how to traverse data types
-	* V3Graph should be templated container type, taking in Vertex + Edge types
-	* Instead of string, have an VEncodedString/VIdString which contains __DOT__ish
-	  things, to reduce bugs.  Also add _20 trailing space to \ encoded names. (4.000)
-
-Runtime:
-	* New evalulation loop   ~/src/verilator/notes/event_loop.txt (4.000?)
-	* Remove all private internal functions from top level wrapper header, move
-	  to new level (4.000?)
-	* Completely standalone simulation (4.000)
-	   main() records arguments for $test$plusvars
-	   instantiates top,
-	   does tracing  (support $dump?)
-	   calls top->simulateForever()
-	   exits
-
-Performance:
-	* Latch optimizations
-	* Constant propagation
-		Extra cleaning AND:  1 & ((VARREF >> 1) | ((&VARREF >> 1) & VARREF))
-		Extra shift (perhaps due to clean): if (1 & CAST (VARREF >> #))
-	* Gated clock and latch conversion to flops.  [JeanPaul Vanitegem]
-		Could propagate the AND into pos/negedges and let domaining optimize.
-	* Negedge reset
-		Switch to remove negedges that don't matter
-		Can't remove async resets from control flops (like in syncronizers)
-	* If all references to array have a constant index, blow up into separate signals-per-index
-	* Bit-multiply for faster bit swapping and a=b[1,3,2] random bit reorderings.
-	* Move _last sets and all other combo logic inside master
-		if() that triggers on all possible sense items
-	* Rewrite and combine V3Life, V3Subst
-		If block temp only ever set in one place to constant, propagate it
-			Used in t_mem for array delayed assignments
-		Replace variables if set later in same cfunc branch
-			See for example duplicate sets of _narrow in cycle 90/91 of t_select_plusloop
-	* Same assignment on both if branches
-		"if (a) { ... b=2; } else { ... b=2;}" -> "b=2; if ..."
-		Careful though, as b could appear in the statement or multiple times in statement
-		(Could just require exatly two 'b's in statement)
-	* Simplify XOR/XNOR/AND/OR bit selection trees
-		Foo = A[1] ^ A[2] ^ A[3] etc are better as ^ ( A & 32'b...1110 )
-	* Combine variables into wider elements
-		Parallel statements on different bits should become single signal
-		Variables that are always consumed in "parallel" can be joined
-	* Duplicate assignments in gate optimization
-		Common to have many separate posedge blocks, each with identical
-		reset_r <= rst_in
-	* If signal is used only once (not counting trace), always gate substitute
-		Don't merge if any combining would form circ logic (out goes back to in)
-	* Multiple assignments each bit can become single assign with concat
-		Make sure a SEL of a CONCAT can get the single bit back.
-	* Usually blocks/values
-		Enable only after certain time, so VL_TIME_I(32) > 0x1e gets eliminated out
-	* Better ordering of a<=b, b<=c, put all refs to 'b' next to each other to optimize caching
-	* I-cache packing improvements (what/how?)
-	* Data cache organization (order of vars in class)
-		First have clocks,
-		then bools instead of uint32_t's
-		then based on what sense list they come from, all outputs, then all inputs
-		finally have any signals part of a "usually" block, or constant.
-	* Rather then tracking widths, have a MSB...LSB of this expression
-		(or better, a bitmask of bits relevant in this expression)
-	* Track recirculation and convert into clock-enables
-	* Clock enables should become new clocking domains for speed
-	* If floped(a) & flopped(b) and no other a&b, then instead flop(a&b).
-	* Sort by output bitselects so can combine more assignments (see DDP example dx_dm signal)

bin/verilator_coverage

@@ -1,29 +1,15 @@
-: # -*-Mode: perl;-*- use perl, wherever it is
-eval 'exec perl -wS $0 ${1+"$@"}'
-  if 0;
+#!/usr/bin/env perl
 ######################################################################
 #
-# Copyright 2003-2018 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2021 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.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
 ######################################################################
 
 require 5.006_001;
 use warnings;
-BEGIN {
-    if ($ENV{DIRPROJECT} && $ENV{DIRPROJECT_PERL_BOOT}) {
-	# Magic to allow author testing of perl packages in local directory
-	require $ENV{DIRPROJECT}."/".$ENV{DIRPROJECT_PERL_BOOT};
-    }
-}
-
 use Getopt::Long;
 use FindBin qw($RealBin $RealScript);
 use IO::File;
@@ -31,7 +17,7 @@ use Pod::Usage;
 use Cwd qw(abs_path getcwd);
 
 use strict;
-use vars qw ($Debug @Opt_Verilator_Sw);
+use vars qw($Debug @Opt_Verilator_Sw);
 
 #######################################################################
 #######################################################################
@@ -54,26 +40,26 @@ 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,
-	  "debug:s"	=> \&debug,
-	  # "version!"	=> \&version,	# Also passthru'ed
-	  # Additional parameters
-	  "<>"		=> sub {},	# Ignored
+          # Major operating modes
+          "help"        => \&usage,
+          "debug:s"     => \&debug,
+          # "version!"  => \&version,   # Also passthru'ed
+          # Additional parameters
+          "<>"          => sub {},      # Ignored
     )) {
     pod2usage(-exitstatus=>2, -verbose=>0);
 }
 
 # Normal, non gdb
-run (verilator_coverage_bin()
-     ." ".join(' ',@Opt_Verilator_Sw));
+run(verilator_coverage_bin()
+    ." ".join(' ',@Opt_Verilator_Sw));
 
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
 }
 
 sub debug {
@@ -90,23 +76,25 @@ sub verilator_coverage_bin {
     my $bin = "";
     # Use VERILATOR_ROOT if defined, else assume verilator_bin is in the search path
     my $basename = ($ENV{VERILATOR_COVERAGE_BIN}
-		    || "verilator_coverage_bin_dbg");
+                    || "verilator_coverage_bin_dbg");
     if (defined($ENV{VERILATOR_ROOT})) {
-	my $dir = $ENV{VERILATOR_ROOT};
-	if (-x "$dir/bin/$basename") {  # From a "make install" into VERILATOR_ROOT
-	    $bin = "$dir/bin/$basename";
-	} else {
-	    $bin = "$dir/$basename";  # From pointing to kit directory
-	}
+        my $dir = $ENV{VERILATOR_ROOT};
+        if (-x "$dir/bin/$basename"
+            || -x "$dir/bin/$basename.exe") {  # From a "make install" into VERILATOR_ROOT
+            $bin = "$dir/bin/$basename";
+        } else {
+            $bin = "$dir/$basename";  # From pointing to kit directory
+        }
     } else {
-	if (-x "$RealBin/$basename") {
-	    $bin = "$RealBin/$basename";  # From path/to/verilator with verilator_bin installed
-	} else {
-	    $bin = $basename;  # Find in PATH
-	}
-	# Note we don't look under bin/$basename which would be right if running
-	# in the kit dir. Running that would likely break, since
-	# VERILATOR_ROOT wouldn't be set and Verilator won't find internal files.
+        if (-x "$RealBin/$basename"
+            || -x "$RealBin/$basename.exe") {
+            $bin = "$RealBin/$basename";  # From path/to/verilator with verilator_bin installed
+        } else {
+            $bin = $basename;  # Find in PATH
+        }
+        # Note we don't look under bin/$basename which would be right if running
+        # in the kit dir. Running that would likely break, since
+        # VERILATOR_ROOT wouldn't be set and Verilator won't find internal files.
     }
     return $bin;
 }
@@ -123,23 +111,28 @@ sub run {
     system($command);
     my $status = $?;
     if ($status) {
-	if ($! =~ /no such file or directory/i) {
-	    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: $command\n";
-	}
-	if ($status & 127) {
-	    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;
-	    } else {
-		warn "%Error: Verilator_coverage threw signal $status.\n" if !$Debug;
-	    }
-	}
-	die "%Error: Command Failed $command\n";
+        if ($! =~ /no such file or directory/i) {
+            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: $command\n";
+        }
+        if ($status & 127) {
+            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;
+            } else {
+                warn "%Error: Verilator_coverage threw signal $status.\n" if !$Debug;
+            }
+        }
+        if ($status != 256 || $Debug) {  # i.e. not normal exit(1)
+            warn "%Error: Command Failed $command\n";
+        }
+        exit $! if $!;  # errno
+        exit $? >> 8 if $? >> 8;  # child exit status
+        exit 255;  # last resort
     }
 }
 
@@ -163,129 +156,53 @@ verilator_coverage - Verilator coverage analyzer
 
     verilator_coverage  -write merged.dat -read <datafiles>...
 
-Verilator_coverage processes Verilator coverage reports.
+    verilator_coverage  -write-info merged.info -read <datafiles>...
 
-With --anotate, it reads the specified data file and generates annotated
-source code with coverage metrics annotated.  If multiple coverage points
-exist on the same line, additional lines will be inserted to report the
-additional points.
+Verilator_coverage processes Verilated model-generated coverage reports.
 
-Additional Verilog-standard arguments specify the search paths necessary to
-find the source code that the coverage analysis was performed on.
+For documentation see
+L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
 
-To get correct coverage percentages, you may wish to read logs/coverage.dat
-into Emacs and do a M-x keep-lines to include only those statistics of
-interest.
+=head1 ARGUMENT SUMMARY
 
-For Verilog conditions that should never occur, you should add a $stop
-statement.  This will remove the coverage during the next build.
+    <filename>    Specify input data filename, default "coverage.dat"
+    --annotate <output_dir>       Directory name for source annotation.
+    --annotate-all                All files should be shown.
+    --annotate-min <count>        Minimum occurrence count for uncovered.
+    --help                        Displays this message and version and exits.
+    --rank                        Compute relative importance of tests.
+    --unlink                      With --write, unlink all inputs
+    --version                     Displays program version and exits.
+    --write <filename>            Write aggregate coverage results.
+    --write-info <filename.info>  Write lcov .info.
 
-=head1 ARGUMENTS
-
-=over 4
-
-=item I<filename>
-
-Specify input data file, may be repeated to read multiple inputs.  If no
-data file is specified, by default coverage.dat is read.
-
-=item --annotate I<output_directory>
-
-Sprcifies the directory name that source files with annotated coverage data
-should be written to.
-
-=item --annotate-all
-
-Specifies all files should be shown.  By default, only those source files
-which have low coverage are written to the output directory.
-
-=item --annotate-min I<count>
-
-Specifies the minimum occurrence count that should be flagged if the
-coverage point does not include a specified threshold.  Defaults to 10.
-
-=item --help
-
-Displays this message and program version and exits.
-
-=item --rank
-
-Print an experimental report listing the relative importance of each test
-in covering all of the coverage points.  The report shows "Covered" which
-indicates the number of points that test covers; a test is considered to
-cover a point if it has a bucket count of at least 1. The "rank" column has
-a higher number t indicate the test is more important, and rank 0 means the
-test does not need to be run to cover the points.  "RankPts" indicates the
-number of coverage points this test will contribute to overall coverage if
-all tests are run in the order of highest to lowest rank.
-
-=item --unlink
-
-When using --write to combine coverage data, unlink all input files after
-the output has been created.
-
-=item --version
-
-Displays program version and exits.
-
-=item --write I<filename>
-
-Specifies the aggregate coverage results, summed across all the files,
-should be written to the given filename.  This is useful in scripts to
-combine many sequential runs into one master coverage file.
-
-=back
-
-=head1 VERILOG ARGUMENTS
-
-The following arguments are compatible with GCC, VCS and most Verilog
-programs.
-
-=over 4
-
-=item +libext+I<ext>+I<ext>...
-
-Defines the extensions for Verilog files.
-
-=item +define+I<var>+I<value>
-=item -DI<var>=I<value>
-
-Defines the given variable.
-
-=item +incdir+I<dir>
-=item -II<dir>
-
-Specifies a directory for finding include files.
-
-=item -f I<file>
-
-Specifies a file containing additional command line arguments.
-
-=item -y I<dir>
-
-Specifies a module search directory.
-
-=back
+    +libext+I<ext>+I<ext>...      Extensions for Verilog files.
+    +define+I<var>+I<value>       Defines the given variable.
+    -DI<var>=I<value>             Defines the given variable.
+    +incdir+I<dir>                Add directory for finding include files.
+    -II<dir>                      Add directory for finding include files.
+    -y I<dir>                     Specifies module search directory.
 
 =head1 DISTRIBUTION
 
-The latest version is available from L<http://www.veripool.org/>.
+The latest version is available from L<https://verilator.org>.
 
-Copyright 2003-2018 by Wilson Snyder.  Verilator 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.
+Copyright 2003-2021 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.
 
-=head1 AUTHORS
-
-Wilson Snyder <[email protected]>
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 SEE ALSO
 
-C<verilator>
+C<verilator>, C<lcov>
 
 L<verilator_coverage --help> which is the source for this document.
 
+and L<https://verilator.org/guide/latest/exe_verilator_coverage.html> for
+detailed documentation.
+
 =cut
 
 ######################################################################

bin/verilator_difftree

@@ -1,32 +1,13 @@
-: # -*-Mode: perl;-*- use perl, wherever it is
-eval 'exec perl -wS $0 ${1+"$@"}'
-  if 0;
+#!/usr/bin/env perl
 # See copyright, etc in below POD section.
 ######################################################################
 
-require 5.006_001;
 use warnings;
 use Getopt::Long;
 use IO::File;
 use Pod::Usage;
 use strict;
-use vars qw ($Debug);
-
-#======================================================================
-
-# Old version 1 dump nodes with no dtypep's
-our %Ver1_Non_Dtyped = map {$_ => 1} qw(
-  ACTIVE ALWAYS ALWAYSPOST ALWAYSPUBLIC ATTROF BEGIN BREAK CASE CASEITEM
-  CCALL CELL CELLINLINE CFILE CFUNC CHANGEDET CLOCKING COMMENT CONTINUE
-  COVERDECL COVERINC COVERTOGGLE CRETURN CSTMT DEFPARAM DISABLE DISPLAY DOT
-  DPIEXPORT FCLOSE FFLUSH FINAL FINISH FOPEN GENCASE GENERATE GENFOR GENIF
-  IF IMPLICIT INITARRAY INITIAL JUMPGO JUMPLABEL MODULE NETLIST
-  NOTFOUNDMODULE PACKAGE PACKAGEIMPORT PARSEREF PIN PORT PRAGMA PRIMITIVE
-  PSLASSERT PSLCOVER PSLDEFCLOCK PULL RANGE READMEM REPEAT RETURN SCCTOR
-  SCDTOR SCHDR SCIMP SCIMPHDR SCINT SCOPE SELBIT SELEXTRACT SELMINUS
-  SELPLUS SENGATE SENITEM SENTREE SFORMAT SFORMATF STOP SYSIGNORE SYSTEMT
-  TASK TASKREF TEXT TOPSCOPE TYPEDEFFWD TYPETABLE UCSTMT UDPTABLE
-  UDPTABLELINE UNTILSTABLE VASSERT WHILE );
+use vars qw($Debug);
 
 #======================================================================
 # main
@@ -37,12 +18,12 @@ 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,
+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";
 }
@@ -54,9 +35,9 @@ defined $Opt_B or die "%Error: No new diff filename\n";
 -e $Opt_B or die "%Error: No new diff filename found: $Opt_B\n";
 
 if (-d $Opt_A && -d $Opt_B) {
-    diff_dir ($Opt_A, $Opt_B);
+    diff_dir($Opt_A, $Opt_B);
 } elsif (-f $Opt_A && -f $Opt_B) {
-    diff_file ($Opt_A, $Opt_B);
+    diff_file($Opt_A, $Opt_B);
 } else {
     die "%Error: Mix of files and dirs\n";
 }
@@ -68,25 +49,25 @@ sub diff_dir {
     my %files;
 
     foreach my $fn (glob("$a/*.tree")) {
-	(my $base = $fn) =~ s!.*/!!;
-	$files{$base}{a} = $fn;
+        (my $base = $fn) =~ s!.*/!!;
+        $files{$base}{a} = $fn;
     }
     foreach my $fn (glob("$b/*.tree")) {
-	(my $base = $fn) =~ s!.*/!!;
-	$files{$base}{b} = $fn;
+        (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;
+        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");
+    $any or warn("%Warning: No .tree files found that have similar base names:\n    "
+                 .join("\n    ", sort keys %files),"\n");
 }
 
 sub diff_file {
@@ -101,10 +82,10 @@ sub diff_file {
     my $vera = version_from($a);
     my $verb = version_from($b);
     my $verCvt = (($vera < 0x3900 && $verb >= 0x3900)
-		  || ($vera >= 0x3900 && $verb < 0x3900));
+                  || ($vera >= 0x3900 && $verb < 0x3900));
 
-    filter ($a, $tmp_a, $verCvt);
-    filter ($b, $tmp_b, $verCvt);
+    filter($a, $tmp_a, $verCvt);
+    filter($b, $tmp_b, $verCvt);
     system("diff -u $tmp_a $tmp_b");
     unlink $tmp_a;
     unlink $tmp_b;
@@ -115,8 +96,8 @@ sub version_from {
     # 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.]+)\)/;
+        last if $. > 10;
+        return hex $1 if $line =~ /\(format (0x[0-9.]+)\)/;
     }
     return 1.0;
 }
@@ -130,36 +111,27 @@ sub filter {
     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/;
-	    $line =~ s!\@dt=0x\(G?/?([^)]+)\)!$1!g;  # NEW: @dt -> OLD: non @dt format
-	    #					     # Below Ver1_Non_Dtyped may replace above further
-	    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;
-		}
-		if ($Ver1_Non_Dtyped{$type}) {
-		    $line =~ s! w[0-9]+!!g;
-		}
-	    }
-	    $line =~ s!\@dt=0$!NoW!g;   # NEW: dt=null -> common format
-	    $line =~ s!\@dt=0 !NoW !g;  # NEW: dt=null -> common format
-	    $line =~ s! s?w0$! NoW!g;   # OLD: no width -> common format
-	    $line =~ s! s?w0 ! NoW !g;  # OLD: no width -> common format
-	}
-	print $f2 $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;
@@ -168,8 +140,8 @@ sub filter {
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
-    exit (1);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
 }
 
 sub debug {
@@ -179,11 +151,11 @@ sub debug {
 sub parameter {
     my $param = shift;
     if (!defined $Opt_A) {
-	$Opt_A = $param;
+        $Opt_A = $param;
     } elsif (!defined $Opt_B) {
-	$Opt_B = $param;
+        $Opt_B = $param;
     } else {
-	die "%Error: Unknown parameter: $param\n";
+        die "%Error: Unknown parameter: $param\n";
     }
 }
 
@@ -234,11 +206,14 @@ Do not show differences in line numbering.
 
 =head1 DISTRIBUTION
 
-The latest version is available from L<http://www.veripool.org/verilator>.
+The latest version is available from L<https://verilator.org>.
 
-Copyright 2005-2018 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.
+Copyright 2005-2021 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
 
 =head1 AUTHORS
 
@@ -248,6 +223,8 @@ Wilson Snyder <[email protected]>
 
 C<verilator>
 
+and L<https://verilator.org/verilator_doc.html> for detailed documentation.
+
 =cut
 
 ######################################################################

bin/verilator_gantt

@@ -0,0 +1,576 @@
+#!/usr/bin/env perl
+# See copyright, etc in below POD section.
+######################################################################
+
+use warnings;
+use strict;
+use Getopt::Long;
+use IO::File;
+use Pod::Usage;
+use vars qw($Debug);
+
+$Debug = 0;
+my $Opt_File;
+my $Opt_Time_Per_Char = 0;  # rdtsc ticks per char in gantt chart, 0=auto
+my $opt_vcd = "profile_threads.vcd";
+
+our %Threads;
+our %Mtasks;
+our %Global;
+
+autoflush STDOUT 1;
+autoflush STDERR 1;
+Getopt::Long::config("no_auto_abbrev");
+if (! GetOptions(
+          "help"        => \&usage,
+          "scale=i"     => \$Opt_Time_Per_Char,
+          "debug"       => sub { $Debug = 1; },
+          "vcd=s"       => \$opt_vcd,
+          "no-vcd!"     => sub { $opt_vcd = undef; },
+          "<>"          => \&parameter,
+    )) {
+    die "%Error: Bad usage, try 'verilator_gantt --help'\n";
+}
+
+$Opt_File = "profile_threads.dat" if !defined $Opt_File;
+
+process($Opt_File);
+write_vcd($opt_vcd) if defined $opt_vcd;
+exit(0);
+
+#######################################################################
+
+sub usage {
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
+}
+
+sub parameter {
+    my $param = shift;
+    if (!defined $Opt_File) {
+        $Opt_File = $param;
+    } else {
+        die "%Error: Unknown parameter: $param\n";
+    }
+}
+
+#######################################################################
+
+sub process {
+    my $filename = shift;
+
+    read_data($filename);
+    read_cpuinfo();
+    report();
+}
+
+#######################################################################
+
+sub read_data {
+    my $filename = shift;
+
+    %Global = (rdtsc_cycle_time => 0);
+
+    my $fh = IO::File->new("<$filename") or die "%Error: $! $filename,";
+    while (my $line = $fh->getline) {
+        if ($line =~ m/VLPROF mtask\s(\d+)\sstart\s(\d+)\send\s(\d+)\selapsed\s(\d+)\spredict_time\s(\d+)\scpu\s(\d+)\son thread (\d+)/) {
+            my $mtask = $1;
+            my $start = $2;
+            my $end = $3;
+            my $elapsed_time = $4;
+            my $predict_time = $5;
+            my $cpu = $6;
+            my $thread = $7;
+            $Threads{$thread}{$start}{mtask} = $mtask;
+            $Threads{$thread}{$start}{end} = $end;
+            $Threads{$thread}{$start}{cpu} = $cpu;
+
+            if (!exists $Mtasks{$mtask}{elapsed}) {
+                $Mtasks{$mtask}{elapsed} = 0;
+            }
+            $Mtasks{$mtask}{elapsed} += $elapsed_time;
+            $Mtasks{$mtask}{predict} = $predict_time;
+            $Mtasks{$mtask}{end} = max($Mtasks{$mtask}{end}, $end);
+        }
+        elsif ($line =~ /^VLPROFTHREAD/) {}
+        elsif ($line =~ m/VLPROF arg\s+(\S+)\+([0-9.])\s*$/
+               || $line =~ m/VLPROF arg\s+(\S+)\s+([0-9.])\s*$/) {
+            $Global{args}{$1} = $2;
+        }
+        elsif ($line =~ m/VLPROF stat\s+(\S+)\s+([0-9.]+)/) {
+            $Global{stats}{$1} = $2;
+        }
+        elsif ($line =~ /^#/) {}
+        elsif ($Debug) {
+            chomp $line;
+            print "Unk: $line\n";
+        }
+        # TODO -- this is parsing text printed by a client.
+        # Really, verilator proper should generate this
+        # if it's useful...
+        if ($line =~ m/rdtsc time = (\d+) ticks/) {
+            $Global{rdtsc_cycle_time} = $1;
+        }
+    }
+}
+
+sub read_cpuinfo {
+    my $filename = "/proc/cpuinfo";
+    my $fh = IO::File->new("<$filename") or return;
+    my $cpu;
+    while (my $line = $fh->getline) {
+        chomp $line;
+        if ($line =~ m/^processor\s*:\s*(\d+)\s*$/) {
+            $cpu = $1;
+        }
+        if ($cpu && $line =~ m/^([a-z_ ]+)\s*:\s*(.*)$/) {
+            my ($term, $value) = ($1, $2);
+            $term =~ s/\s+$//;
+            $term =~ s/\s+/_/;
+            $value =~ s/\s+$//;
+            $Global{cpuinfo}{$cpu}{$term} = $value;
+        }
+    }
+}
+
+#######################################################################
+
+sub report {
+    print "Verilator Gantt report\n";
+
+    print "\nArgument settings:\n";
+    foreach my $arg (sort keys %{$Global{args}}) {
+        my $plus = ($arg =~ /^\+/) ? "+" : " ";
+        printf "  %s%s%d\n", $arg, $plus, $Global{args}{$arg};
+    }
+
+    my $nthreads = scalar keys %Threads;
+    $Global{cpus} = {};
+    foreach my $thread (keys %Threads) {
+        # Make potentially multiple characters per column
+        foreach my $start (keys %{$Threads{$thread}}) {
+            my $cpu = $Threads{$thread}{$start}{cpu};
+            my $elapsed = $Threads{$thread}{$start}{end} - $start;
+            $Global{cpus}{$cpu}{cpu_time} += $elapsed;
+        }
+    }
+
+    my $mt_mtask_time = 0;
+    my $long_mtask_time = 0;
+    my $last_end = 0;
+    foreach my $mtask (keys %Mtasks) {
+        $mt_mtask_time += $Mtasks{$mtask}{elapsed};
+        $last_end = max($last_end, $Mtasks{$mtask}{end});
+        $long_mtask_time = max($long_mtask_time, $Mtasks{$mtask}{elapsed});
+    }
+    $Global{last_end} = $last_end;
+
+    report_graph();
+
+    # If we know cycle time in the same (rdtsc) units,
+    # this will give us an actual utilization number,
+    # (how effectively we keep the cores busy.)
+    #
+    # It also gives us a number we can compare against
+    # serial mode, to estimate the overhead of data sharing,
+    # which will show up in the total elapsed time. (Overhead
+    # of synchronization and scheduling should not.)
+    print "\nAnalysis:\n";
+    printf "  Total threads             = %d\n", $nthreads;
+    printf "  Total mtasks              = %d\n", scalar(keys %Mtasks);
+    my $ncpus = scalar(keys %{$Global{cpus}});
+    printf "  Total cpus used           = %d\n", $ncpus;
+    printf "  Total yields              = %d\n", $Global{stats}{yields};
+    printf "  Total eval time           = %d rdtsc ticks\n", $Global{last_end};
+    printf "  Longest mtask time        = %d rdtsc ticks\n", $long_mtask_time;
+    printf "  All-thread mtask time     = %d rdtsc ticks\n", $mt_mtask_time;
+    my $long_efficiency = $long_mtask_time/($Global{last_end} || 1);
+    printf "  Longest-thread efficiency = %0.1f%%\n", $long_efficiency*100;
+    my $mt_efficiency = $mt_mtask_time/($Global{last_end}*$nthreads || 1);
+    printf "  All-thread efficiency     = %0.1f%%\n", $mt_efficiency*100;
+    printf "  All-thread speedup        = %0.1f\n", $mt_efficiency*$nthreads;
+    if ($Global{rdtsc_cycle_time} > 0) {
+        my $ut = $mt_mtask_time / $Global{rdtsc_cycle_time};
+        print "tot_mtask_cpu=$mt_mtask_time cyc=$Global{rdtsc_cycle_time} ut=$ut\n";
+    }
+
+    my @p2e_ratios;
+    my $min_p2e = 1000000;
+    my $min_mtask;
+    my $max_p2e = -1000000;
+    my $max_mtask;
+    foreach my $mtask (sort keys %Mtasks) {
+        if ($Mtasks{$mtask}{elapsed} > 0) {
+            if ($Mtasks{$mtask}{predict} == 0) {
+                $Mtasks{$mtask}{predict} = 1;  # don't log(0) below
+            }
+            my $p2e_ratio = log( $Mtasks{$mtask}{predict} / $Mtasks{$mtask}{elapsed} );
+            #print "log(p2e $mtask) = $p2e_ratio   (predict $Mtasks{$mtask}{predict}, elapsed $Mtasks{$mtask}{elapsed})\n";
+            push @p2e_ratios, $p2e_ratio;
+
+            if ($p2e_ratio > $max_p2e) {
+                $max_p2e = $p2e_ratio;
+                $max_mtask = $mtask;
+            }
+            if ($p2e_ratio < $min_p2e) {
+                $min_p2e = $p2e_ratio;
+                $min_mtask = $mtask;
+            }
+        }
+    }
+
+    print "\nStatistics:\n";
+    printf "  min log(p2e) = %0.3f", $min_p2e;
+    print "  from mtask $min_mtask (predict $Mtasks{$min_mtask}{predict},";
+    print " elapsed $Mtasks{$min_mtask}{elapsed})\n";
+    printf "  max log(p2e) = %0.3f", $max_p2e;
+    print "  from mtask $max_mtask (predict $Mtasks{$max_mtask}{predict},";
+    print " elapsed $Mtasks{$max_mtask}{elapsed})\n";
+
+    my $stddev = stddev(\@p2e_ratios);
+    my $mean = mean(\@p2e_ratios);
+    printf "  mean = %0.3f\n", $mean;
+    printf "  stddev = %0.3f\n", $stddev;
+    printf "  e ^ stddev = %0.3f\n", exp($stddev);
+
+    report_cpus();
+
+    if ($nthreads > $ncpus) {
+        print "\n";
+        print "%Warning: There were fewer CPUs ($ncpus) then threads ($nthreads).\n";
+        print "        : See docs on use of numactl.\n";
+    } else {
+        if ($Global{cpu_socket_cores_warning}) {
+            print "\n";
+            print "%Warning: Multiple threads scheduled on same hyperthreaded core.\n";
+            print "        : See docs on use of numactl.\n";
+        }
+        if ($Global{cpu_sockets_warning}) {
+            print "\n";
+            print "%Warning: Threads scheduled on multiple sockets.\n";
+            print "        : See docs on use of numactl.\n";
+        }
+    }
+    print "\n";
+}
+
+sub report_cpus {
+    print "\nCPUs:\n";
+    # Test - show all cores
+    # for (my $i=0; $i<73; ++$i) { $Global{cpus}{$i} ||= {cpu_time => 0}; }
+
+    $Global{cpu_sockets} ||= {};
+    $Global{cpu_socket_cores} ||= {};
+
+    foreach my $cpu (sort {$a <=> $b} keys %{$Global{cpus}}) {
+        printf "  cpu %d: ", $cpu;
+        printf "cpu_time=%d", $Global{cpus}{$cpu}{cpu_time};
+
+        my $socket = $Global{cpuinfo}{$cpu}{physical_id};
+        $Global{cpu_sockets}{$socket}++ if defined $socket;
+        printf " socket=%d", $socket if defined $socket;
+
+        my $core = $Global{cpuinfo}{$cpu}{core_id};
+        $Global{cpu_socket_cores}{$socket."__".$core}++ if defined $socket && defined $core;
+        printf " core=%d", $core if defined $core;
+
+        my $model = $Global{cpuinfo}{$cpu}{model_name};
+        printf "  %s", $model if defined $model;
+        print "\n";
+    }
+
+    $Global{cpu_sockets_warning} = 1
+        if (scalar keys %{$Global{cpu_sockets}} > 1);
+    foreach my $scn (values %{$Global{cpu_socket_cores}}) {
+        $Global{cpu_socket_cores_warning} = 1 if $scn > 1;
+    }
+}
+
+sub report_graph {
+    my $time_per = $Opt_Time_Per_Char;
+    if ($time_per == 0) {
+        $time_per = ($Global{last_end} / 40);  # Start with 40 columns
+        while ($time_per > 10) {
+            my ($graph, $conflicts) = _make_graph($time_per);
+            last if !$conflicts;
+            $time_per = int($time_per/2);
+        }
+        # One more step so we can fit more labels
+        $time_per = int($time_per/2);
+        $time_per ||= 1;
+    }
+
+    my ($graph, $conflicts) = _make_graph($time_per);
+
+    print "\nThread gantt graph:\n";
+    print "  Legend: One character width = $time_per rdtsc ticks\n";
+    print "  Legend: '&' = multiple mtasks in this period (character width)\n";
+
+    my $scale = "   <-".$Global{last_end}." rdtsc total";
+    for (my $col = length($scale);  # -2 for '->' below
+         $col < ($Global{last_end}/$time_per); ++$col) {
+        $scale .= "-";
+    }
+    print "  $scale->\n";
+
+    foreach my $thread (sort keys %{$graph}) {
+        print "  t: ";
+        _print_graph_line($graph->{$thread}, '');
+    }
+}
+
+sub _make_graph {
+    my $time_per = shift;
+
+    my $graph = {};  # {thread}{column}{char=>'x' or chars=>#}
+    my $conflicts = 0;
+    foreach my $thread (keys %Threads) {
+        # Make potentially multiple characters per column
+        foreach my $start (sort {$a <=> $b} keys %{$Threads{$thread}}) {
+            my $end = $Threads{$thread}{$start}{end};
+            my $mtask = $Threads{$thread}{$start}{mtask};
+            my $cpu = $Threads{$thread}{$start}{cpu};
+
+            my $startcol = _time_col($time_per, $start);
+            my $endcol = _time_col($time_per, $end);
+
+            my $label = "[";
+            $label .= "$cpu";  # Maybe make optional in future
+            my $width = $endcol - $startcol + 1;
+            while (length($label) < ($width-1)) {  # -1 for ']'
+                $label .= "-";
+            }
+            $label .= "]";
+            $graph->{$thread}[$startcol]{char} .= $label;
+        }
+        if ($Debug) {
+            print "# Multicol: "; _print_graph_line($graph->{$thread}, '|');
+        }
+        # Expand line to one char per column
+        for (my $col = 0; $col <= $#{$graph->{$thread}}; ++$col) {
+            if (my $chars = $graph->{$thread}[$col]{char}) {
+                my $ok = 1;
+                for (my $coladd = 1; $coladd<length($chars); ++$coladd) {
+                    if ($graph->{$thread}[$col + $coladd]{char}) {
+                        $ok = 0; last;
+                    }
+                }
+                if (!$ok) {
+                    if ($chars =~ /\[.*\[/) {  # Two begins or more
+                        $conflicts++;
+                        $graph->{$thread}[$col]{char} = "&";
+                    } else {
+                        $graph->{$thread}[$col]{char} = "[";
+                    }
+                    for (my $coladd = 1; $coladd<length($chars); ++$coladd) {
+                        if ($graph->{$thread}[$col + $coladd]{char}) {
+                            last;
+                        } else {
+                            $graph->{$thread}[$col + $coladd]{char} = 'x';
+                        }
+                    }
+                } else {
+                    my $coladd = 0;
+                    foreach my $char (split //, $chars) {
+                        $graph->{$thread}[$col+$coladd]{char} = $char;
+                        ++$coladd;
+                    }
+                }
+            }
+        }
+        if ($Debug) {
+            print "# Singlcol: "; _print_graph_line($graph->{$thread}, '|');
+        }
+    }
+    print "# Conflicts $conflicts\n" if $Debug;
+    return ($graph, $conflicts);
+}
+
+sub _print_graph_line {
+    my $graph_thread = shift;
+    my $sep = shift;
+    for (my $col = 0; $col <= $#{$graph_thread}; ++$col) {
+        my $c = $graph_thread->[$col]{char}; $c=' ' if !defined $c;
+        print $c, $sep;
+    }
+    print "\n";
+}
+
+sub _time_col {
+    my $time_per = shift;
+    my $time = shift;
+    return int($time/$time_per);
+}
+
+#######################################################################
+
+sub write_vcd {
+    my $filename = shift;
+    print "Writing $filename\n";
+    my $fh = IO::File->new(">$filename") or die "%Error: $! $filename,";
+    my $vcd = {values => {},  # {<time>}{<code>} = value
+               sigs => {},  # {<module>}{<sig}} = code
+               code => 0,
+    };
+
+    my %parallelism;
+    foreach my $thread (keys %Threads) {
+        my $mcode = ($vcd->{sigs}{threads}{"thread${thread}_mtask"} ||= $vcd->{code}++);
+        foreach my $start (sort {$a <=> $b} keys %{$Threads{$thread}}) {
+            my $end = $Threads{$thread}{$start}{end};
+            my $mtask = $Threads{$thread}{$start}{mtask};
+            my $cpu = $Threads{$thread}{$start}{cpu};
+            $vcd->{values}{$start}{$mcode} = $mtask;
+            $vcd->{values}{$end}{$mcode} = undef;
+            $parallelism{$start}++;
+            $parallelism{$end}--;
+
+            my $ccode = $vcd->{sigs}{cpus}{"cpu${cpu}_thread"} ||= $vcd->{code}++;
+            $vcd->{values}{$start}{$ccode} = $thread;
+            $vcd->{values}{$end}{$ccode} = undef;
+
+            my $mcode = $vcd->{sigs}{mtasks}{"mtask${mtask}_cpu"} ||= $vcd->{code}++;
+            $vcd->{values}{$start}{$mcode} = $cpu;
+            $vcd->{values}{$end}{$mcode} = undef;
+        }
+    }
+    {
+        my $pcode = ($vcd->{sigs}{Stats}{"parallelism"} ||= $vcd->{code}++);
+        my $value = 0;
+        foreach my $time (sort {$a<=>$b} keys %parallelism) {
+            $value += $parallelism{$time};
+            $vcd->{values}{$time}{$pcode} = $value;
+        }
+    }
+
+    $fh->print('$version Generated by verilator_gantt $end'."\n");
+    $fh->print('$timescale 1ns $end'."\n");
+    $fh->print("\n");
+
+    my %all_codes;
+    $fh->print(' $scope module gantt $end'."\n");
+    foreach my $module (sort keys %{$vcd->{sigs}}) {
+        $fh->printf('  $scope module %s $end'."\n", $module);
+        foreach my $sig (sort keys %{$vcd->{sigs}{$module}}) {
+            my $code = $vcd->{sigs}{$module}{$sig};
+            $fh->printf('   $var wire 32 v%x %s [31:0] $end'."\n",
+                        $code, $sig);
+            $all_codes{$code} = 1;
+        }
+        $fh->print('  $upscope $end'."\n");
+    }
+    $fh->print(' $upscope $end'."\n");
+    $fh->print('$enddefinitions $end'."\n");
+    $fh->print("\n");
+
+    my $first = 1;
+    foreach my $time (sort {$a <=> $b} keys %{$vcd->{values}}) {
+        if ($first) {
+            $first = 0;
+            # Start with Z for any signals without time zero data
+            foreach my $code (keys %all_codes) {
+                if (!defined $vcd->{values}{$time}{$code}) {
+                    $vcd->{values}{$time}{$code} = undef;
+                }
+            }
+        }
+        $fh->printf("#%d\n", $time);
+        foreach my $code (sort keys %{$vcd->{values}{$time}}) {
+            my $value = $vcd->{values}{$time}{$code};
+            if (defined $value) {
+                $fh->printf("b%b v%x\n", $value, $code);
+            } else {
+                $fh->printf("bz v%x\n", $code);
+            }
+        }
+    }
+}
+
+#######################################################################
+# Similar to Statistics::Basic functions, but avoid a package dependency
+
+sub max {
+    my $n = $_[0]; shift;
+    while (defined $_[0]) {
+        $n = $_[0] if !defined $n || $_[0] > $n;
+        shift;
+    }
+    return $n;
+}
+
+sub mean {
+    my $arrayref = shift;
+    my $n = 0;
+    my $sum = 0;
+    foreach my $v (@$arrayref) {
+        $sum += $v;
+        $n++;
+    }
+    return undef if !$n;
+    return $sum/$n;
+}
+
+sub stddev {
+    my $arrayref = shift;
+    my $n = 0;
+    my $sum = 0;
+    my $sumsq = 0;
+    foreach my $v (@$arrayref) {
+        $sum += $v;
+        $sumsq += $v**2;
+        $n++;
+    }
+    return undef if !$n;
+    return sqrt(($sumsq/$n) - ($sum/$n)**2);
+}
+
+#######################################################################
+__END__
+
+=pod
+
+=head1 NAME
+
+verilator_gantt - Create Gantt chart of multi-threaded execution
+
+=head1 SYNOPSIS
+
+Verilator_gantt creates a visual representation to help analyze Verilator
+multithreaded simulation performance, by showing when each macro-task
+starts and ends, and showing when each thread is busy or idle.
+
+For documentation see
+L<https://verilator.org/guide/latest/exe_verilator_gantt.html>.
+
+=head1 ARGUMENT SUMMARY
+
+    <filename>    Filename to read data from, default "profile_threads.dat".
+    --help        Displays this message and program version and exits.
+    --scale I<n>  Number of characters per time step.
+    --no-vcd      Do not create a VCD file.
+    --vcd <filename>   Set output filename for vcd dump, default "verilator_gantt.vcd."
+
+=head1 DISTRIBUTION
+
+The latest version is available from L<https://verilator.org>.
+
+Copyright 2018-2021 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
+
+=head1 SEE ALSO
+
+C<verilator>
+
+and L<https://verilator.org/guide/latest/exe_verilator_gantt.html> for
+detailed documentation.
+
+=cut
+
+######################################################################
+### Local Variables:
+### compile-command: "$V4/bin/verilator_gantt $V4/test_regress/obj_vltmt/t_gantt/vlt_sim.log"
+### End:

bin/verilator_includer

@@ -1,11 +1,11 @@
-: # -*-Mode: perl;-*- use perl, wherever it is
-eval 'exec perl -wS $0 ${1+"$@"}'
-  if 0;
+#!/usr/bin/env perl
 # DESCRIPTION: Print include statements for each ARGV
 #
-# Copyright 2003-2018 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.
+# Copyright 2003-2021 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
 ######################################################################
 
 require 5.005;

bin/verilator_profcfunc

@@ -1,6 +1,4 @@
-: # -*-Mode: perl;-*- use perl, wherever it is
-eval 'exec perl -wS $0 ${1+"$@"}'
-  if 0;
+#!/usr/bin/env perl
 # See copyright, etc in below POD section.
 ######################################################################
 
@@ -11,7 +9,7 @@ use IO::File;
 use Pod::Usage;
 eval { use Data::Dumper;  $Data::Dumper::Indent = 1; }; # Debug, ok if missing
 use strict;
-use vars qw ($Debug);
+use vars qw($Debug);
 
 #======================================================================
 
@@ -23,12 +21,12 @@ $Debug = 0;
 my $Opt_File;
 autoflush STDOUT 1;
 autoflush STDERR 1;
-Getopt::Long::config ("no_auto_abbrev");
-if (! GetOptions (
-		  "help"	=> \&usage,
-		  "debug"	=> \&debug,
-		  "<>"		=> \&parameter,
-		  )) {
+Getopt::Long::config("no_auto_abbrev");
+if (! GetOptions(
+          "help"        => \&usage,
+          "debug"       => \&debug,
+          "<>"          => \&parameter,
+    )) {
     die "%Error: Bad usage, try 'verilator_profcfunc --help'\n";
 }
 
@@ -39,8 +37,8 @@ profcfunc($Opt_File);
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
-    exit (1);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
 }
 
 sub debug {
@@ -50,9 +48,9 @@ sub debug {
 sub parameter {
     my $param = shift;
     if (!defined $Opt_File) {
-	$Opt_File = $param;
+        $Opt_File = $param;
     } else {
-	die "%Error: Unknown parameter: $param\n";
+        die "%Error: Unknown parameter: $param\n";
     }
 }
 
@@ -66,13 +64,13 @@ sub profcfunc {
     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;
-	}
+        #                  %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_].*)$/) {
@@ -88,10 +86,10 @@ sub profcfunc {
     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;
-	}
+        if ($func =~ /(.*)::_eval\(([a-zA-Z_0-9]+__Syms).*\)$/) {
+            $verilated_mods{$1} = qr/^$1/;
+            $pointer_mods{$2} = $1;
+        }
     }
     #print Dumper(\%pointer_mods, \%verilated_mods);
 
@@ -99,72 +97,72 @@ sub profcfunc {
     my %vfuncs;
     my %groups;
     foreach my $func (keys %funcs) {
-	my $pct = $funcs{$func}{pct};
-	my $vfunc = $func;
-	my $design;
+        my $pct = $funcs{$func}{pct};
+        my $vfunc = $func;
+        my $design;
 
-	if ($func =~ /\(([a-zA-Z_0-9]+__Syms)/) {
-	    $design = $pointer_mods{$1};
-	}
+        if ($func =~ /\(([a-zA-Z_0-9]+__Syms)/) {
+            $design = $pointer_mods{$1};
+        }
 
-	foreach my $vde (keys %verilated_mods) {
-	    last if $design;
-	    if ($func =~ /$verilated_mods{$vde}/) {
-		$design=$vde;
-		last;
-	    }
-	}
+        foreach my $vde (keys %verilated_mods) {
+            last if $design;
+            if ($func =~ /$verilated_mods{$vde}/) {
+                $design=$vde;
+                last;
+            }
+        }
 
-	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};
+        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};
     }
 
 
     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;
-	}
+        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("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");
@@ -181,14 +179,14 @@ sub profcfunc {
 
     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);
+                            || $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);
     }
 }
 
@@ -212,36 +210,36 @@ verilator_profcfunc - Read gprof report created with --prof-cfuncs
 =head1 DESCRIPTION
 
 Verilator_profcfunc reads a profile report created by gprof.  The names of
-the functions are then transformed, assuming the user used verilator's
+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.
 
-=head1 ARGUMENTS
+For documentation see
+L<https://verilator.org/guide/latest/exe_verilator_profcfuncs.html>.
 
-=over 4
+=head1 ARGUMENT SUMMARY
 
-=item --help
-
-Displays this message and program version and exits.
-
-=back
+    <filename>  Input file (gprof.out)
+    --help      Display this help
 
 =head1 DISTRIBUTION
 
-The latest version is available from L<http://www.veripool.org/>.
+The latest version is available from L<https://verilator.org>.
 
-Copyright 2007-2018 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.
+Copyright 2007-2021 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.
 
-=head1 AUTHORS
-
-Wilson Snyder <[email protected]>
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 SEE ALSO
 
 C<verilator>
 
+and L<https://verilator.org/guide/latest/exe_verilator_profcfuncs.html> for
+detailed documentation.
+
 =cut
 
 ######################################################################

ci/ci-ccache-maint.bash

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI ccache maintenance
+#
+# Copyright 2020 by Geza Lore. 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
+
+################################################################################
+# This script is run in 'before_script', once ccache has been set up.
+################################################################################
+
+set -e
+set -x
+
+# Show version
+ccache --version
+
+# Flush ccache if requested in commit message
+COMMIT="${CI_PULL_REQUEST_SHA:-$CI_COMMIT}"
+if git log --format=%B -n 1 "$COMMIT" | grep -q -i '\[CI\s\+ccache\s\+clear\]'; then
+  echo "Flushing ccache due to commit message"
+  ccache -C
+fi
+
+# Dump stats, then zero stats
+ccache -s -z

ci/ci-install.bash

@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI dependency install script
+#
+# Copyright 2020 by Geza Lore. 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
+
+################################################################################
+# This script runs in the 'install' phase of all jobs, in all stages. We try to
+# minimize the time spent in this by selectively installing only the components
+# required by the particular build stage.
+################################################################################
+
+set -e
+set -x
+
+cd $(dirname "$0")/..
+
+fatal() {
+  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
+}
+
+if [ "$CI_OS_NAME" = "linux" ]; then
+  MAKE=make
+elif [ "$CI_OS_NAME" = "osx" ]; then
+  MAKE=make
+elif [ "$CI_OS_NAME" = "freebsd" ]; then
+  MAKE=gmake
+else
+  fatal "Unknown os: '$CI_OS_NAME'"
+fi
+
+install-vcddiff() {
+  TMP_DIR="$(mktemp -d)"
+  git clone https://github.com/veripool/vcddiff "$TMP_DIR"
+  git -C "${TMP_DIR}" checkout 5112f88b7ba8818dce9dfb72619e64a1fc19542c
+  "$MAKE" -C "${TMP_DIR}"
+  sudo cp "${TMP_DIR}/vcddiff" /usr/local/bin
+}
+
+if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
+  ##############################################################################
+  # Dependencies of jobs in the 'build' stage, i.e.: packages required to
+  # build Verilator
+
+  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 libsystemc libsystemc-dev
+    fi
+    if [ "$COVERAGE" = 1 ]; then
+      yes yes | sudo cpan -fi Parallel::Forker
+    fi
+    if [ "$M32" = 1 ]; then
+      sudo apt-get install gcc-multilib g++-multilib
+    fi
+  elif [ "$CI_OS_NAME" = "osx" ]; then
+    brew update
+    brew install ccache perl gperftools
+  elif [ "$CI_OS_NAME" = "freebsd" ]; then
+    sudo pkg install -y autoconf bison ccache gmake perl5
+  else
+    fatal "Unknown os: '$CI_OS_NAME'"
+  fi
+
+  if [ -n "$CCACHE_DIR" ]; then
+    mkdir -p "$CCACHE_DIR" && ./ci/ci-ccache-maint.bash
+  fi
+elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
+  ##############################################################################
+  # Dependencies of jobs in the 'test' stage, i.e.: packages required to
+  # run the tests
+
+  if [ "$CI_OS_NAME" = "linux" ]; 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
+      sudo apt-get install libsystemc-dev
+    fi
+    if [ "$M32" = 1 ]; then
+      sudo apt-get install lib32z1-dev gcc-multilib g++-multilib
+    fi
+  elif [ "$CI_OS_NAME" = "osx" ]; then
+    brew update
+    # brew cask install gtkwave # fst2vcd hangs at launch, so don't bother
+    brew install ccache perl
+  elif [ "$CI_OS_NAME" = "freebsd" ]; then
+    # fst2vcd fails with "Could not open '<input file>', exiting."
+    sudo pkg install -y ccache gmake perl5 python3
+  else
+    fatal "Unknown os: '$CI_OS_NAME'"
+  fi
+  # Common installs
+  if [ "$CI_RUNS_ON" != "ubuntu-14.04" ]; then
+    CI_CPAN_REPO=https://cpan.org
+  fi
+  yes yes | sudo cpan -M $CI_CPAN_REPO -fi Parallel::Forker
+  install-vcddiff
+
+  autoconf
+  ./configure --enable-longtests --enable-ccwarn
+else
+  ##############################################################################
+  # Unknown build stage
+  fatal "Unknown build stage: '$CI_BUILD_STAGE_NAME'"
+fi

ci/ci-script.bash

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI main job script
+#
+# Copyright 2020 by Geza Lore. 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
+
+################################################################################
+# This is the main script executed in the 'script' phase by all jobs. We use a
+# single script to keep the CI setting simple. We pass job parameters via
+# environment variables using 'env' keys.
+################################################################################
+
+set -e
+set -x
+
+fatal() {
+  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
+}
+
+if [ "$CI_OS_NAME" = "linux" ]; then
+  export MAKE=make
+  NPROC=$(nproc)
+elif [ "$CI_OS_NAME" = "osx" ]; then
+  export MAKE=make
+  NPROC=$(sysctl -n hw.logicalcpu)
+elif [ "$CI_OS_NAME" = "freebsd" ]; then
+  export MAKE=gmake
+  NPROC=$(sysctl -n hw.ncpu)
+else
+  fatal "Unknown os: '$CI_OS_NAME'"
+fi
+
+if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
+  ##############################################################################
+  # Build verilator
+
+  if [ "$COVERAGE" != 1 ]; then
+    autoconf
+    ./configure --enable-longtests --enable-ccwarn
+    "$MAKE" -j "$NPROC" -k
+    if [ "$CI_OS_NAME" = "osx" ]; then
+      file bin/verilator_bin
+      file bin/verilator_bin_dbg
+      md5 bin/verilator_bin
+      md5 bin/verilator_bin_dbg
+      stat bin/verilator_bin
+      stat bin/verilator_bin_dbg
+    fi
+  else
+    nodist/code_coverage --stages 0-2
+  fi
+elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
+  ##############################################################################
+  # Run tests
+
+  export VERILATOR_TEST_NO_CONTRIBUTORS=1  # Separate workflow check
+
+  if [ "$CI_OS_NAME" = "osx" ]; then
+    export VERILATOR_TEST_NO_GDB=1  # Pain to get GDB to work on OS X
+    export VERILATOR_TEST_NO_GPROF=1  # Apple Clang has no -pg
+    # export PATH="/Applications/gtkwave.app/Contents/Resources/bin:$PATH" # fst2vcd
+    file bin/verilator_bin
+    file bin/verilator_bin_dbg
+    md5 bin/verilator_bin
+    md5 bin/verilator_bin_dbg
+    stat bin/verilator_bin
+    stat bin/verilator_bin_dbg
+    # For some reason, the dbg exe is corrupted by this point ('file' reports
+    # it as data rather than a Mach-O). Unclear if this is an OS X issue or
+    # CI's. Remove the file and re-link...
+    rm bin/verilator_bin_dbg
+    "$MAKE" -j "$NPROC" -k
+  elif [ "$CI_OS_NAME" = "freebsd" ]; then
+    export VERILATOR_TEST_NO_GDB=1 # Disable for now, ideally should run
+    export VERILATOR_TEST_NO_GPROF=1 # gprof is a bit different on FreeBSD, disable
+  fi
+
+  # Run sanitize on Ubuntu 20.04 only
+  [ "$CI_RUNS_ON" = 'ubuntu-20.04' ] && sanitize='--sanitize' || sanitize=''
+
+  # Run the specified test
+  case $TESTS in
+    dist-vlt-0)
+      "$MAKE" -C test_regress SCENARIOS="--dist --vlt $sanitize" DRIVER_HASHSET=--hashset=0/2
+      ;;
+    dist-vlt-1)
+      "$MAKE" -C test_regress SCENARIOS="--dist --vlt $sanitize" DRIVER_HASHSET=--hashset=1/2
+      ;;
+    vltmt-0)
+      "$MAKE" -C test_regress SCENARIOS=--vltmt DRIVER_HASHSET=--hashset=0/2
+      ;;
+    vltmt-1)
+      "$MAKE" -C test_regress SCENARIOS=--vltmt DRIVER_HASHSET=--hashset=1/2
+      ;;
+    coverage-all)
+      nodist/code_coverage --stages 1-
+      ;;
+    coverage-dist)
+      nodist/code_coverage --stages 1- --scenarios=--dist
+      ;;
+    coverage-vlt-0)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=0/10
+      ;;
+    coverage-vlt-1)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=1/10
+      ;;
+    coverage-vlt-2)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=2/10
+      ;;
+    coverage-vlt-3)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=3/10
+      ;;
+    coverage-vlt-4)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=4/10
+      ;;
+    coverage-vlt-5)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=5/10
+      ;;
+    coverage-vlt-6)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=6/10
+      ;;
+    coverage-vlt-7)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=7/10
+      ;;
+    coverage-vlt-8)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=8/10
+      ;;
+    coverage-vlt-9)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=9/10
+      ;;
+    coverage-vltmt-0)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=0/10
+      ;;
+    coverage-vltmt-1)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=1/10
+      ;;
+    coverage-vltmt-2)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=2/10
+      ;;
+    coverage-vltmt-3)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=3/10
+      ;;
+    coverage-vltmt-4)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=4/10
+      ;;
+    coverage-vltmt-5)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=5/10
+      ;;
+    coverage-vltmt-6)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=6/10
+      ;;
+    coverage-vltmt-7)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=7/10
+      ;;
+    coverage-vltmt-8)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=8/10
+      ;;
+    coverage-vltmt-9)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=9/10
+      ;;
+    *)
+      fatal "Unknown test: $TESTS"
+      ;;
+  esac
+  # Upload coverage data
+  if [[ $TESTS == coverage-* ]]; then
+    bash <(cat ci/coverage-upload.sh) -f nodist/obj_dir/coverage/app_total.info
+  fi
+else
+  ##############################################################################
+  # Unknown build stage
+  fatal "Unknown build stage: '$CI_BUILD_STAGE_NAME'"
+fi

ci/docker/buildenv/Dockerfile

@@ -0,0 +1,56 @@
+# DESCRIPTION: Dockerfile for env to build and fully test Verilator
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+FROM ubuntu:20.04
+
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive \
+       apt-get install --no-install-recommends -y \
+                        autoconf \
+                        bc \
+                        bison \
+                        build-essential \
+                        ca-certificates \
+                        ccache \
+                        clang \
+                        cmake \
+                        flex \
+                        gdb \
+                        git \
+                        gtkwave \
+                        libfl2 \
+                        libfl-dev \
+                        libgoogle-perftools-dev \
+                        libsystemc \
+                        libsystemc-dev \
+                        numactl \
+                        perl \
+                        python3 \
+                        wget \
+                        zlibc \
+                        zlib1g \
+                        zlib1g-dev \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /tmp
+
+RUN cpan install -fi Parallel::Forker
+
+RUN git clone https://github.com/veripool/vcddiff.git && \
+    make -C vcddiff && \
+    cp -p vcddiff/vcddiff /usr/local/bin/vcddiff && \
+    rm -rf vcddiff
+
+COPY build.sh /tmp/build.sh
+
+ENV VERILATOR_AUTHOR_SITE=1
+
+WORKDIR /work
+
+ENTRYPOINT [ "/tmp/build.sh" ]

ci/docker/buildenv/README.rst

@@ -0,0 +1,63 @@
+Verilator Build Docker Container
+================================
+
+This Verilator Build Docker Container is set up to compile and test a
+Verilator build. It uses the following parameters:
+
+-  Source repository (default: https://github.com/verilator/verilator)
+
+-  Source revision (default: master)
+
+-  Compiler (GCC 9.3.0, clang 10.0.0, default: 9.3.0)
+
+The container is published as ``verilator/verilator-buildenv`` on `docker
+hub
+<https://hub.docker.com/repository/docker/verilator/verilator-buildenv>`__.
+
+To run the basic build using the current Verilator master:
+
+::
+
+   docker run -ti verilator/verilator-buildenv
+
+To also run tests:
+
+::
+
+   docker run -ti verilator/verilator-buildenv test
+
+To change the compiler:
+
+::
+
+   docker run -ti -e CC=clang-10 -e CXX=clang++-10 verilator/verilator-buildenv test
+
+The tests that involve gdb are not working due to security restrictions.
+To run those too:
+
+::
+
+   docker run -ti -e CC=clang-10 -e CXX=clang++-10 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
+
+Rather then building using a remote git repository you may prefer to use a
+working copy on the local filesystem. Mount the local working copy path as
+a volume and use that in place of git. When doing this be careful to have
+all changes committed to the local git area. To build the current HEAD from
+top of a repository:
+
+::
+
+   docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
+
+
+Rebuilding
+----------
+
+To rebuild the Verilator-buildenv docker image, run:
+
+::
+
+   docker build .
+
+This will also build SystemC under all supported compiler variants to
+reduce the SystemC testing time.

ci/docker/buildenv/build.sh

@@ -0,0 +1,25 @@
+#!/bin/bash -e
+# DESCRIPTION: Build Verilator (inside container)
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+: "${REPO:=https://github.com/verilator/verilator}"
+: "${REV:=master}"
+: "${CC:=gcc}"
+: "${CXX:=g++}"
+
+SRCS=$PWD/verilator
+
+git clone "$REPO" "$SRCS"
+cd "$SRCS"
+git checkout "$REV"
+autoconf
+./configure --enable-longtests
+make -j $(nproc)
+if [ "${1:-''}" == "test" ]; then
+    make test
+fi

ci/docker/run/Dockerfile

@@ -0,0 +1,51 @@
+# DESCRIPTION: Dockerfile for image to run Verilator inside
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+FROM ubuntu:20.04
+
+RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive \
+    && apt-get install --no-install-recommends -y \
+                        autoconf \
+                        bc \
+                        bison \
+                        build-essential \
+                        ca-certificates \
+                        ccache \
+                        flex \
+                        git \
+                        libfl-dev \
+                        libgoogle-perftools-dev \
+                        perl \
+                        python3 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+ARG REPO=https://github.com/verilator/verilator
+ARG SOURCE_COMMIT=master
+
+WORKDIR /tmp
+
+# Add an exception for the linter, we want to cd here in one layer
+# to reduce the number of layers (and thereby size).
+# hadolint ignore=DL3003
+RUN git clone "${REPO}" verilator && \
+    cd verilator && \
+    git checkout "${SOURCE_COMMIT}" && \
+    autoconf && \
+    ./configure && \
+    make -j "$(nproc)" && \
+    make install && \
+    cd .. && \
+    rm -r verilator
+
+COPY verilator-wrap.sh /usr/local/bin/verilator-wrap.sh
+
+WORKDIR /work
+
+ENTRYPOINT [ "/usr/local/bin/verilator-wrap.sh" ]

ci/docker/run/README.rst

@@ -0,0 +1,73 @@
+Verilator Executable Docker Container
+=====================================
+
+The Verilator Executable Docker Container allows you to run Verilator
+easily as a docker image, e.g.:
+
+::
+
+   docker run -ti verilator/verilator:latest --version
+
+This will install the container, run the latest Verilator and print
+Verilator's version.
+
+Containers are automatically built for all released versions, so you may
+easily compare results across versions, e.g.:
+
+::
+
+   docker run -ti verilator/verilator:4.030 --version
+
+Verilator needs to read and write files on the local system. To simplify
+this process, use the ``verilator-docker`` convenience script. This script
+takes the version number, and all remaining arguments are passed through to
+Verilator. e.g.:
+
+::
+
+   ./verilator-docker 4.030 --version
+
+or
+
+::
+
+   ./verilator-docker 4.030 --cc test.v
+
+If you prefer not to use ``verilator-docker`` you must give the container
+access to your files as a volume with appropriate user rights.  For example
+to Verilate test.v:
+
+::
+
+   docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
+
+This method can only access files below the current directory. An
+alternative is setup the volume ``-workdir``.
+
+You can also work in the container by setting the entrypoint (don't forget
+to mount a volume if you want your work persistent):
+
+::
+
+   docker run -ti --entrypoint /bin/bash verilator/verilator:latest
+
+You can also use the container to build Verilator at a specific commit:
+
+::
+
+   docker build --build-arg SOURCE_COMMIT=<commit> .
+
+
+Internals
+---------
+
+The Dockerfile builds Verilator and removes the tree when completed to
+reduce the image size. The entrypoint is set as a wrapper script
+(``verilator-wrap.sh``). That script 1. calls Verilator, and 2. copies the
+Verilated runtime files to the ``obj_dir`` or the ``-Mdir``
+respectively. This allows the user to have the files to they may later
+build the C++ output with the matching runtime files. The wrapper also
+patches the Verilated Makefile accordingly.
+
+There is also a hook defined that is run by docker hub via automated
+builds.

ci/docker/run/hooks/build

@@ -0,0 +1,10 @@
+#!/bin/bash
+# DESCRIPTION: Docker hub hook to pass SOURCE_COMMIT
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+docker build --build-arg SOURCE_COMMIT=${SOURCE_COMMIT} -f $DOCKERFILE_PATH -t $IMAGE_NAME .

ci/docker/run/hooks/post_push

@@ -0,0 +1,13 @@
+#!/bin/bash
+# DESCRIPTION: Docker hub hook to tag the latest release (stable)
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+if [ "$SOURCE_BRANCH"="stable" ]; then
+    docker tag $IMAGE_NAME $DOCKER_REPO:latest
+    docker push $DOCKER_REPO:latest
+fi

ci/docker/run/verilator-docker

@@ -0,0 +1,11 @@
+#!/bin/bash
+# DESCRIPTION: Wrap a verilator call to run a docker container
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+docker pull verilator/verilator:$1 >/dev/null
+docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:$1 "${@:2}"

ci/docker/run/verilator-wrap.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# DESCRIPTION: Wrap a Verilator call and copy vlt includes
+#              (inside docker container)
+#
+# Copyright 2020 by Stefan Wallentowitz. 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
+
+perl /usr/local/bin/verilator "$@"
+status=$?
+if [ $status -ne 0 ]; then
+    exit $status
+fi
+
+# Check if user set an obj_dir
+obj_dir=$(echo " $@" | grep -oP '\s--Mdir\s*\K\S+')
+if [ "$obj_dir" == "" ]; then
+    obj_dir="obj_dir"
+fi
+
+# If the run was successful: Copy required files to allow build without this container
+if [ -e ${obj_dir} ]; then
+    # Copy files required for the build
+    mkdir -p ${obj_dir}/vlt
+    cp -r /usr/local/share/verilator/bin ${obj_dir}/vlt
+    cp -r /usr/local/share/verilator/include ${obj_dir}/vlt
+    # Point Makefile to that folder
+    sed -i 's/VERILATOR_ROOT = \/usr\/local\/share\/verilator/VERILATOR_ROOT = vlt/g' ${obj_dir}/*.mk
+fi

codecov.yml

@@ -0,0 +1,38 @@
+# DESCRIPTION: codecov.io config
+#
+# Copyright 2020-2021 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
+####################
+# Validate:
+#  curl --data-binary @codecov.yml https://codecov.io/validate
+
+codecov:
+  require_ci_to_pass: no
+
+coverage:
+  precision: 2
+  round: down
+  range: "50...100"
+  ignore:
+    - "ci"
+    - "docs"
+    - "examples"
+    - "include/gtkwave"
+    - "include/vltstd"
+    - "test_regress"
+
+parsers:
+  gcov:
+    branch_detection:
+      conditional: yes
+      loop: yes
+      method: no
+      macro: no
+
+comment:
+  layout: "reach,diff,flags,tree"
+  behavior: default
+  require_changes: yes

configure.ac

@@ -1,20 +1,27 @@
 # DESCRIPTION: Process this file with autoconf to produce a configure script.
 #
-# Copyright 2003-2018 by Wilson Snyder. Verilator is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU Lesser
+# Copyright 2003-2021 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],[3.926 2018-08-22],[https://www.veripool.org/verilator],
-        [verilator],[https://www.veripool.org/verilator])
+AC_INIT([Verilator],[4.202 2021-04-24],
+        [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_CONFIG_HEADER(src/config_build.h)
-AC_CONFIG_FILES(Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc)
+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
 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])
 
 # Ignore automake flags passed by Ubuntu builds
 AC_ARG_ENABLE([dependency-tracking],
@@ -24,11 +31,43 @@ AC_ARG_ENABLE([maintainer-mode],
 AC_ARG_ENABLE([silent-rules],
               [AS_HELP_STRING([--disable-silent-rules], [ignored])])
 
+# Flag to enable linking specific libraries statically
+AC_MSG_CHECKING(whether to perform partial static linking of Verilator binary)
+AC_ARG_ENABLE([partial-static],
+              [AS_HELP_STRING([--disable-partial-static],
+                              [By default, for Verilation peformance, Verilator
+                               is linked against some of its dependencies
+                               statically. Use this to link the Verilator binary
+                               fully dynamically.])],
+              [case "${enableval}" in
+                yes) CFG_ENABLE_PARTIAL_STATIC=yes ;;
+                no)  CFG_ENABLE_PARTIAL_STATIC=no ;;
+                *)   AC_MSG_ERROR([bad value '${enableval}' for --disable-partial-static]) ;;
+               esac],
+               CFG_ENABLE_PARTIAL_STATIC=yes)
+AC_MSG_RESULT($CFG_ENABLE_PARTIAL_STATIC)
+
+# Flag to enable linking Verilator with tcmalloc if available
+AC_MSG_CHECKING(whether to use tcmalloc)
+AC_ARG_ENABLE([tcmalloc],
+              [AS_HELP_STRING([--enable-tcmalloc],
+                              [Use libtcmalloc_minimal for faster dynamic memory
+                               management in Verilator binary@<:@default=check@:>@])],
+              [case "${enableval}" in
+                yes) CFG_WITH_TCMALLOC=yes ;;
+                no)  CFG_WITH_TCMALLOC=no ;;
+                *)   AC_MSG_ERROR([bad value '${enableval}' for --enable-tcmalloc]) ;;
+               esac],
+              [CFG_WITH_TCMALLOC=check;])
+AC_MSG_RESULT($CFG_WITH_TCMALLOC)
+
 # Special Substitutions - CFG_WITH_DEFENV
 AC_MSG_CHECKING(whether to use hardcoded paths)
 AC_ARG_ENABLE([defenv],
               [AS_HELP_STRING([--disable-defenv],
-                              [disable using some hardcoded data paths extracted from some default environment variables (the default is to use hardcoded paths)])],
+                              [disable using some hardcoded data paths extracted
+                              from some default environment variables (the default
+                              is to use hardcoded paths) in Verilator binary])],
               [case "${enableval}" in
                 yes) CFG_WITH_DEFENV=yes ;;
                 no)  CFG_WITH_DEFENV=no ;;
@@ -42,7 +81,8 @@ AC_MSG_RESULT($CFG_WITH_DEFENV)
 AC_MSG_CHECKING(whether to show and stop on compilation warnings)
 AC_ARG_ENABLE([ccwarn],
               [AS_HELP_STRING([--enable-ccwarn],
-                              [enable showing and stopping on compilation warnings])],
+                              [enable showing and stopping on compilation warnings
+                               in Verilator binrary and Verilated makefiles])],
               [case "${enableval}" in
                 yes) CFG_WITH_CCWARN=yes ;;
                 no)  CFG_WITH_CCWARN=no ;;
@@ -74,26 +114,11 @@ AC_ARG_ENABLE([longtests],
 AC_SUBST(CFG_WITH_LONGTESTS)
 AC_MSG_RESULT($CFG_WITH_LONGTESTS)
 
-# CFG_WITH_PREC11
-AC_MSG_CHECKING(whether allow pre-C++11)
-AC_ARG_ENABLE([prec11],
-              [AS_HELP_STRING([--enable-prec11],
-                              [enable pre-C++11 compilers])],
-              [case "${enableval}" in
-                yes) CFG_WITH_PREC11=yes ;;
-                no)  CFG_WITH_PREC11=no ;;
-                *)   AC_MSG_ERROR([bad value ${enableval} for --enable-prec11]) ;;
-               esac],
-              [CFG_WITH_PREC11=no;]
-              )
-AC_SUBST(CFG_WITH_PREC11)
-AC_MSG_RESULT($CFG_WITH_PREC11)
-
-# Compiler flags
-CFLAGS=-I${includedir}
-CPPFLAGS=-I${includedir}
-CXXFLAGS=-I${includedir}
-LDFLAGS=-L${libdir}
+# Compiler flags (ensure they are not empty to avoid configure defaults)
+CFLAGS+=" "
+CPPFLAGS+=" "
+CXXFLAGS+=" "
+LDFLAGS+=" "
 
 # Checks for programs.
 AC_PROG_CC
@@ -114,14 +139,31 @@ AC_PATH_PROG(PERL,perl)
 if test "x$PERL" = "x" ; then
    AC_MSG_ERROR([Cannot find "perl" in your PATH, please install it])
 fi
+
+AC_PATH_PROG(PYTHON3,python3)
+if test "x$PYTHON3" = "x" ; then
+   AC_MSG_ERROR([Cannot find "python3" in your PATH, please install it])
+fi
+
 AC_PATH_PROG(LEX,flex)
 if test "x$LEX" = "x" ; then
    AC_MSG_ERROR([Cannot find "flex" in your PATH, please install it])
 fi
+flex_version=$($LEX --version | head -1)
+AC_MSG_RESULT([$LEX --version = $flex_version])
+
 AC_PATH_PROG(YACC,bison)
 if test "x$YACC" = "x" ; then
    AC_MSG_ERROR([Cannot find "bison" in your PATH, please install it])
 fi
+bison_version=$($YACC --version | head -1)
+AC_MSG_RESULT([$YACC --version = $bison_version])
+
+AC_CHECK_PROG(OBJCACHE,ccache,ccache)
+if test "x$OBJCACHE" != "x" ; then
+  objcache_version=$($OBJCACHE --version | head -1)
+  AC_MSG_RESULT([objcache is $OBJCACHE --version = $objcache_version])
+fi
 
 # Checks for libraries.
 
@@ -189,29 +231,69 @@ AC_DEFUN([_MY_CXX_CHECK_OPT],
     fi
    ])
 
+AC_DEFUN([_MY_LDLIBS_CHECK_FLAG],
+   [# _MY_LDLIBS_CHECK_FLAG(flag) -- Check if linker supports specific options
+    # Set $_my_result appropriately
+    ACO_SAVE_LIBS="$LIBS"
+    LIBS="$LIBS $1"
+    AC_MSG_CHECKING([whether $CXX linker accepts $1])
+    AC_LINK_IFELSE(
+         [AC_LANG_PROGRAM([[]])],
+         [_my_result=yes
+          if test -s conftest.err; then
+            if grep -e "$1" conftest.err >/dev/null; then
+              _my_result=no
+            fi
+          fi],
+         [_my_result=no])
+    AC_MSG_RESULT($_my_result)
+    LIBS="$ACO_SAVE_LIBS"
+   ])
+
+AC_DEFUN([_MY_LDLIBS_CHECK_IFELSE],
+   [# _MY_LDLIBS_CHECK_IFELSE(flag,action-if-supported,action-if-not-supported)
+    # Check if linker supports specific flag, if it does do action-if-supported
+    # otherwise do action-if-not-supported
+    _MY_LDLIBS_CHECK_FLAG($1)
+    if test "$_my_result" = "yes" ; then
+      true
+      $2
+    else
+      true
+      $3
+    fi
+   ])
+
+AC_DEFUN([_MY_LDLIBS_CHECK_OPT],
+   [# _MY_LDLIBS_CHECK_OPT(variable, flag) -- Check if linker supports specific
+    # options. If it does, append flag to variable.
+    _MY_LDLIBS_CHECK_IFELSE($2, $1="$$1 $2")
+   ])
+
 # Flag to select newest language standard supported
 # Macros work such that first option that passes is the one we take
+# gnu++17 code is clean, but SystemC in 2018 doesn't link with it (bug1339)
 # gnu++14 is the newest that Verilator supports
 # std++03 is the oldest that Verilator supports
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=gnu++17)
+#_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++17)
+#_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++17)
 _MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_NEWEST,-std=c++14)
 _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=std++03)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=std++11)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=std++14)
-_MY_CXX_CHECK_SET(CFG_CXXFLAGS_STD_OLDEST,-std=std++17)
+_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=std++17)
 _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++17)
 AC_SUBST(CFG_CXXFLAGS_STD_OLDEST)
 
 # Flags for compiling Verilator internals including parser, and Verilated files
@@ -225,9 +307,7 @@ AC_SUBST(CFG_CXXFLAGS_WEXTRA)
 # 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)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-delete-null-pointer-checks)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-unused-parameter)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-undefined-bool-conversion)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-shadow)
 AC_SUBST(CFG_CXXFLAGS_SRC)
 
@@ -244,25 +324,93 @@ AC_SUBST(CFG_CXXFLAGS_PARSER)
 # without this flag, even though there's a conditional to prevent the divide.
 # We still don't add no-div-by-zero as it throws message to stdout, though doesn't die.
 #_MY_CXX_CHECK_OPT(-Wno-div-by-zero)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-faligned-new)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-fbracket-depth=4096)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Qunused-arguments)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-bool-operation)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-parentheses-equality)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-sign-compare)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-uninitialized)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-unused-but-set-variable)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-unused-parameter)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-unused-variable)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-shadow)
+# For some reason -faligned-new does not work under Travis w/ clang but the
+# configure test doesn't catch this either
+AS_IF([test "x$TRAVIS_COMPILER" != xclang], [_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-faligned-new)])
+CFG_CXX_FLAGS_CMAKE="-faligned-new"
+m4_foreach([cflag],[
+        [-fbracket-depth=4096],
+        [-fcf-protection=none],
+        [-mno-cet],
+        [-Qunused-arguments],
+        [-Wno-bool-operation],
+        [-Wno-tautological-bitwise-compare],
+        [-Wno-parentheses-equality],
+        [-Wno-sign-compare],
+        [-Wno-uninitialized],
+        [-Wno-unused-but-set-variable],
+        [-Wno-unused-parameter],
+        [-Wno-unused-variable],
+        [-Wno-shadow]],[
+    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,cflag)
+    # CMake will test what flags work itself, so pass all flags through to it
+    CFG_CXX_FLAGS_CMAKE="$CFG_CXX_FLAGS_CMAKE cflag"
+    ])
 AC_SUBST(CFG_CXXFLAGS_NO_UNUSED)
+AC_SUBST(CFG_CXX_FLAGS_CMAKE)
 
-# Set CFG_WITH_THREADED if can support threading
-AC_MSG_CHECKING(whether $CXX supports Verilated threads)
-ACO_SAVE_CXXFLAGS="$CXXFLAGS"
-CXXFLAGS="$CXXFLAGS $CFG_CXXFLAGS_STD_NEWEST $CFG_CXXFLAGS_NO_UNUSED"
-AC_LINK_IFELSE(
-     [AC_LANG_PROGRAM([#include <thread>], [[ ]])],
+# Find multithread linker flags
+m4_foreach([ldflag], [
+        [-mt],
+        [-pthread],
+        [-lpthread],
+        [-latomic]],[
+    _MY_LDLIBS_CHECK_OPT(CFG_LDLIBS_THREADS,ldflag)
+    # CMake will test what flags work itself, so pass all flags through to it
+    CFG_LDFLAGS_THREADS_CMAKE="$CFG_LDFLAGS_THREADS_CMAKE ldflag"
+    ])
+AC_SUBST(CFG_LDLIBS_THREADS)
+AC_SUBST(CFG_LDFLAGS_THREADS_CMAKE)
+
+# When linking partially statically
+if test "$CFG_ENABLE_PARTIAL_STATIC" = "yes"; then
+  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -static-libgcc)
+  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -static-libstdc++)
+  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -Xlinker -gc-sections)
+  LTCMALLOC=-l:libtcmalloc_minimal.a
+else
+  LTCMALLOC=-ltcmalloc_minimal
+fi
+AC_SUBST(CFG_LDFLAGS_SRC)
+
+# The pthread library is required by tcmalloc, so add it if it exists. If it
+# does not, the tcmalloc check below will fail anyway, and linking against
+# pthreads is harmless otherwise.
+CFG_LIBS="$LIBS $CFG_LIBS"
+_MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lpthread)
+
+# Check libraries for MingW
+_MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lbcrypt)
+_MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lpsapi)
+
+# Check if tcmalloc is available based on --enable-tcmalloc
+_MY_LDLIBS_CHECK_IFELSE(
+  $LTCMALLOC,
+  [if test "$CFG_WITH_TCMALLOC" != "no"; then
+    CFG_LIBS="$LTCMALLOC $CFG_LIBS";
+    # If using tcmalloc, add some extra options to make the compiler not assume
+    # it is using it's own versions of the standard library functions
+    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-malloc)
+    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-calloc)
+    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-realloc)
+    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-free)
+   fi],
+  [if test "$CFG_WITH_TCMALLOC" = "yes"; then
+    AC_MSG_ERROR([--enable-tcmalloc was given but test for ${LTCMALLOC} failed])
+   fi])
+AC_SUBST(CFG_LIBS)
+
+# Need C++11 at least
+#Alternative: AX_CXX_COMPILE_STDCXX([11])
+AC_DEFUN([_MY_CXX_CHECK_CXX_VER],
+   [# _MY_CXX_CHECK_CXX_VER(flag) -- Check if compiler runs C++11
+    # Set $_my_result
+    AC_LINK_IFELSE(
+     [AC_LANG_PROGRAM([#include <thread>
+#if (__cplusplus < 201103L)
+# error "Too old"
+#endif
+    ], [[ ]])],
      [_my_result=yes
       if test -s conftest.err; then
         if grep -e "$1" conftest.err >/dev/null; then
@@ -270,24 +418,24 @@ AC_LINK_IFELSE(
         fi
       fi],
      [_my_result=no])
-CFG_WITH_THREADED=$_my_result
-AC_SUBST(CFG_WITH_THREADED)
-AC_MSG_RESULT($CFG_WITH_THREADED)
+   ])
 
-# Check compiler flag
-if test "$CFG_WITH_THREADED" = "no" ; then
-   if test "$CFG_WITH_PREC11" = "no" ; then
-      AC_MSG_NOTICE([[]])
-      AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
+AC_MSG_CHECKING(whether $CXX supports C++11)
+_MY_CXX_CHECK_CXX_VER()
+AC_MSG_RESULT($_my_result)
+if test "$_my_result" = "no" ; then
+   CXXFLAGS="$CXXFLAGS $CFG_CXXFLAGS_STD_NEWEST"
+   CFG_CXX_FLAGS_CMAKE="$CFG_CXX_FLAGS_CMAKE $CFG_CXXFLAGS_STD_NEWEST"
+   AC_MSG_CHECKING(whether $CXX supports C++11 with $CFG_CXXFLAGS_STD_NEWEST)
+   _MY_CXX_CHECK_CXX_VER()
+   AC_MSG_RESULT($_my_result)
+fi
+if test "$_my_result" = "no" ; then
+   AC_MSG_NOTICE([[]])
+   AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
 
-Verilator plans to require a C++11 or newer compiler in a future release,
-unless sufficient people report problems. Therefore, if you do not have a
-C++11 compiler, please post a message to
-https://www.veripool.org/boards/3/topics/2580-Verilator-Requiring-C-11-compiler
-indicating your OS and when you think C++11 might be ok, and then rerun
-configure with the --enable-prec11 argument. Thanks.]])
+Verilator requires a C++11 or newer compiler.]])
 
-   fi
 fi
 
 # Checks for library functions.
@@ -295,6 +443,24 @@ AC_CHECK_MEMBER([struct stat.st_mtim.tv_nsec],
     [AC_DEFINE([HAVE_STAT_NSEC],[1],[Defined if struct stat has st_mtim.tv_nsec])],
     [], [#include <sys/stat.h>])
 
+# HAVE_SYSTEMC
+# - If found the default search path has it, so support is always enabled.
+# - If not found or not system-wide, user can set SYSTEMC_INCLUDE.
+# AC_CHECK_HEADERS seems to not locate on Travis-CI but include does work.
+AC_MSG_CHECKING([whether SystemC is found (in system path)])
+ACO_SAVE_LIBS="$LIBS"
+LIBS="$LIBS -lsystemc"
+AC_LINK_IFELSE(
+    [AC_LANG_PROGRAM([[#include <systemc.h>
+                     extern "C" int sc_main(int argc, char* argv[]) {}
+                     ]],[[sc_version()]])],
+    [_my_result=yes
+     AC_DEFINE([HAVE_SYSTEMC],[1],[Defined if have SystemC library])],
+    [_my_result=no])
+AC_MSG_RESULT($_my_result)
+LIBS="$ACO_SAVE_LIBS"
+AC_SUBST(HAVE_SYSTEMC)
+
 # Checks for system services
 
 # Other install directories

docs/.gitignore

@@ -0,0 +1,4 @@
+*.1
+*.html
+*.pdf
+_build

docs/CONTRIBUTING.rst

@@ -0,0 +1,92 @@
+Contributing to Verilator
+=========================
+
+Thanks for using Verilator! We welcome your contributions in whatever form.
+
+This contributing document contains some suggestions that may make
+contributions flow more efficiently.
+
+
+Did you find a bug?
+-------------------
+
+- Please **Ensure the bug was not already reported** by searching
+  `Verilator Issues <https://verilator.org/issues>`__.
+
+- If you're unable to find an open issue addressing the problem, `open a
+  new Verilator issue <https://verilator.org/issues/new>`__.
+
+  - Be sure to include a **code sample** or an **executable test case**
+    demonstrating the bug and expected behavior that is not occurring.
+
+  - The ideal example works against other simulators, and is in the
+    test_regress/t test format, as described in `docs/internals
+    <internals.rst>`__.
+
+
+Did you write a patch that fixes a bug?
+---------------------------------------
+
+- Please `Open a new issue <https://verilator.org/issues/new>`__.
+
+- You may attach a patch to the issue, or (preferred) may request a
+  GitHub pull request.
+
+  - Verilator uses GitHub Actions to provide continuous integration.  You
+    may want to enable Actions on your GitHub branch to ensure your changes
+    keep the tests passing. See `docs/internals <internals.rst>`__.
+
+- Your source-code contributions must be certified as open source,
+  under the `Developer Certificate of
+  Origin <https://developercertificate.org/>`__. On your first
+  contribution, you must either:
+
+  - Have your patch include the addition of your name to `docs/CONTRIBUTORS
+    <CONTRIBUTORS>`__ (preferred).
+
+  - Use "git -s" as part of your commit. This adds a "signed-of-by"
+    attribute which will certify your contribution as described in the
+    `Signed-of-By convention
+    <https://github.com/wking/signed-off-by/blob/master/Documentation/SubmittingPatches>`__.
+
+  - Email, or post in an issue a statement that you certify your
+    contributions.
+
+  - In any of these cases your name will be added to `docs/CONTRIBUTORS
+    <CONTRIBUTORS>`__ and you are agreeing all future contributions are
+    also certified.
+
+  - We occasionally accept contributions where people do not want their
+    name published. Please email us; you must still privately certify your
+    contribution.
+
+- Your test contributions are generally considered released into the
+  Creative Commons Public Domain (CC0), unless you request otherwise or
+  put a GNU/Artistic license on your file.
+
+- Most important is we get your patch. If you’d like to clean up
+  indentation and related issues ahead of our feedback, that is
+  appreciated; please see the coding conventions in `docs/internals
+  <internals.rst>`__.
+
+
+Do you have questions?
+----------------------
+
+- Please see FAQ section and rest of the `Verilator
+  manual <https://verilator.org/verilator_doc.html>`__, or `Verilator
+  manual (PDF) <https://verilator.org/verilator_doc.pdf>`__.
+
+- Ask any question in the `Verilator forum
+  <https://verilator.org/forum>`__.
+
+
+Code of Conduct
+---------------
+
+- Our contributors and participants pledge to make participation in our
+  project and our community a positive experience for everyone. We follow
+  the `Contributor Covenant version 1.4
+  <https://www.contributor-covenant.org/version/1/4/code-of-conduct/>`__.
+
+Thanks!

docs/CONTRIBUTORS

@@ -0,0 +1,96 @@
+The contributors listed below have certified their Verilator contributions
+under the Developer Certificate of Origin (https://developercertificate.org/).
+
+Please see the Verilator manual for 200+ additional contributors. Thanks to all.
+
+Ahmed El-Mahmoudy
+Alex Chadwick
+Àlex Torregrosa
+Andreas Kuster
+Chris Randall
+Conor McCullough
+Dan Petrisko
+David Horton
+David Metz
+David Stanford
+David Turner
+Drew Taussig
+Driss Hafdi
+Edgar E. Iglesias
+Eric Rippey
+Fan Shupei
+Garrett Smith
+Geza Lore
+Gianfranco Costamagna
+Glen Gibb
+Graham Rushton
+Harald Heckmann
+Howard Su
+Huang Rui
+HyungKi Jeong
+Iztok Jeras
+James Hanlon
+James Hutchinson
+James Pallister
+Jamey Hicks
+Jan Van Winkel
+Jean Berniolles
+Jeremy Bennett
+John Coiner
+John Demme
+Josh Redford
+Julien Margetts
+Kaleb Barrett
+Kanad Kanhere
+Kevin Kiningham
+Krzysztof Bieganski
+Kuba Ober
+Ludwig Rogiers
+Lukasz Dalek
+Maarten De Braekeleer
+Maciej Sobkowski
+Marco Widmer
+Markus Krause
+Marlon James
+Marshal Qiao
+Matthew Ballance
+Michael Killough
+Mike Popoloski
+Morten Borup Petersen
+Nandu Raj
+Nathan Kohagen
+Nathan Myers
+Patrick Stewart
+Paul Wright
+Peter Horvath
+Peter Monsson
+Philipp Wagner
+Pierre-Henri Horrein
+Pieter Kapsenberg
+Piotr Binkowski
+Qingyao Sun
+Rafal Kapuscik
+Richard Myers
+Rupert Swarbrick
+Samuel Riedel
+Sean Cross
+Sebastien Van Cauwenberghe
+Sergi Granell
+Stefan Wallentowitz
+Stephen Henry
+Tim Snyder
+Tobias Rosenkranz
+Tobias Wölfel
+Todd Strader
+Tomasz Gorochowik
+Tymoteusz Blazejczyk
+Udi Finkelstein
+Unai Martinez-Corral
+Vassilis Papaefstathiou
+Veripool API Bot
+Victor Besyakov
+Wilson Snyder
+Yossi Nivin
+Yuri Victorovich
+Yutetsu TAKATSUKASA
+Yves Mathieu

docs/Makefile

@@ -0,0 +1,82 @@
+#*****************************************************************************
+# DESCRIPTION: Verilator documentation: Makefile pre-configure version
+#
+# This file is part of Verilator.
+#
+# Code available from: https://verilator.org
+#
+# Copyright 2003-2021 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
+#
+######################################################################
+#
+# This file is intended only to be called from the top-level Verilator Makefile.
+
+RST2HTML = rst2html
+PYTHON3 = python3
+DOXYGEN = doxygen
+SPHINXOPTS ?= -c guide
+SPHINXBUILD ?= sphinx-build
+
+SOURCEDIR = guide
+BUILDDIR = _build
+
+######################################################################
+
+.SUFFIXES:
+
+default:
+	@echo "error: make not supported here, run 'make docs' from Verilator top-level"
+
+######################################################################
+# Intermediate rules
+
+vl-extract: ../bin/verilator ../Changes
+	mkdir -p _build/gen
+	$(PYTHON3) bin/vl_sphinx_extract ../bin/verilator
+	sed 's/`/\&96;/g' < ../Changes > _build/gen/Changes
+
+######################################################################
+# HTML
+
+server: html
+	cd _build/html && $(PYTHON3) -m http.server
+
+%.html: %.rst
+	$(RST2HTML) $< $@
+
+######################################################################
+# PDF
+
+.PHONY: verilator.pdf
+
+verilator.pdf: pdf
+pdf:
+	$(MAKE) vl-extract
+	$(MAKE) latex
+	$(PYTHON3) bin/vl_sphinx_fix _build
+	$(MAKE) -C _build/latex
+	cp _build/latex/verilator.pdf ..
+
+######################################################################
+
+html latex linkcheck spelling::
+	$(MAKE) vl-extract
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+	$(PYTHON3) bin/vl_sphinx_fix _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+clean mostlyclean distclean maintainer-clean::
+	rm -f $(SCRIPTS) *.tmp
+	rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
+	rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs *.idx
+	rm -f *.ev *.evs *.ov *.ovs *.cv *.cvs *.ma *.mas
+	rm -f *.tex
+
+distclean maintainer-clean::
+	rm -f *.info* *.1 *.html *.pdf $(INFOS)

docs/_static/css/vlt_sphinx.css

@@ -0,0 +1,16 @@
+/*Verilator blue #008fd7; set in html*/
+.wy-side-nav-search > div.version {
+    color: #111;
+}
+.fa-github::before, .icon-github::before {
+    content: "";
+}
+.fa-home::before, .icon-home::before {
+    content: "";
+}
+.fa-arrow-circle-right::before, .icon-circle-arrow-right::before {
+    content: "";
+}
+.fa-arrow-circle-left::before, .icon-circle-arrow-left::before {
+    content: "";
+}

docs/bin/vl_sphinx_extract

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# pylint: disable=C0112,C0114,C0116,C0301,R0903
+# -*- Python -*- See copyright, etc below
+######################################################################
+
+import argparse
+import re
+
+#######################################################################
+
+class VlSphinxExtract:
+    debug = 0
+    SkipBasenames = {}
+
+    def process(self, filename):
+        with open(filename) as fhr:
+            fhw = None
+            for line in fhr:
+                # =for VL_SPHINX_EXTRACT "file_to_write_to"
+                match = re.search(r'VL_SPHINX_EXTRACT +"([^"]+)"', line)
+                if match:
+                    outname = match.group(1)
+                    print("Writing %s" % outname)
+                    fhw = open(outname, "w")
+                    fhw.write(
+                        ".. comment: generated by vl_sphinx_extract from " +
+                        filename + "\n")
+                    fhw.write(".. code-block::\n")
+                elif re.match(r'^[=a-zA-Z0-9_]', line):
+                    fhw = None
+                elif fhw:
+                    fhw.write(line)
+
+
+#######################################################################
+
+parser = argparse.ArgumentParser(
+    allow_abbrev=False,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    description="""Read a file and extract documentation data.""",
+    epilog=
+    """ Copyright 2021-2021 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.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
+
+parser.add_argument('--debug',
+                    action='store_const',
+                    const=9,
+                    help='enable debug')
+parser.add_argument('path', help='path to extract from')
+Args = parser.parse_args()
+
+o = VlSphinxExtract()
+o.debug = Args.debug
+o.process(Args.path)
+
+######################################################################
+# Local Variables:
+# compile-command: "./vl_sphinx_extract --debug ../../bin/verilator"
+# End:

docs/bin/vl_sphinx_fix

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+# pylint: disable=C0112,C0114,C0116,C0301,R0903
+# -*- Python -*- See copyright, etc below
+######################################################################
+
+import argparse
+import os
+import re
+
+#######################################################################
+
+
+class VlSphinxFix:
+    debug = 0
+    SkipBasenames = {}
+
+    def process(self, path):
+        if os.path.isdir(path):
+            for basefile in os.listdir(path):
+                file = os.path.join(path, basefile)
+                if ((basefile != ".") and (basefile != "..")
+                        and basefile not in self.SkipBasenames
+                        and not os.path.islink(file)):
+                    self.process(file)
+        elif re.search(r'\.(html|tex)$', path):
+            self._edit(path)
+
+    def _edit(self, filename):
+        is_html = re.search(r'\.(html)$', filename)
+        with open(filename) as fhr:
+            origfile = fhr.read()
+            wholefile = origfile
+            # Option doesn't like spaces, so we use
+            # :option:`/*verilator&32;metacomment*/`
+            wholefile = re.sub(r'verilator-32-', r'verilator-', wholefile)
+            if is_html:
+                wholefile = re.sub(r'&32;', r' ', wholefile)
+                wholefile = re.sub(r'&96;', r'`', wholefile)
+            else:
+                wholefile = re.sub(r'&32;', r' ', wholefile)
+                wholefile = re.sub(r'&96;', r'`', wholefile)
+            if wholefile != origfile:
+                if self.debug:
+                    print("Edit %s" % filename)
+                tempname = filename + ".tmp"
+                with open(tempname, "w") as fhw:
+                    fhw.write(wholefile)
+                os.rename(tempname, filename)
+
+
+#######################################################################
+
+parser = argparse.ArgumentParser(
+    allow_abbrev=False,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    description="""Post-process Sphinx HTML.""",
+    epilog=
+    """ Copyright 2021-2021 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.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
+
+parser.add_argument('--debug',
+                    action='store_const',
+                    const=9,
+                    help='enable debug')
+parser.add_argument('path', help='path to edit')
+Args = parser.parse_args()
+
+o = VlSphinxFix()
+o.debug = Args.debug
+o.process(Args.path)
+
+######################################################################
+# Local Variables:
+# compile-command: "./vl_sphinx_fix --debug _build"
+# End:

docs/gen/ex_USERERROR_faulty.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block:: sv
+
+         $error("User elaboration-time error");

docs/gen/ex_USERERROR_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block::
+
+   %Warning-USERERROR: example.v:1:7 User elaboration-time error

docs/gen/ex_USERFATAL_faulty.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block:: sv
+
+         $fatal(0, "User elaboration-time fatal");

docs/gen/ex_USERFATAL_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block::
+
+   %Warning-USERFATAL: example.v:1:7 User elaboration-time fatal

docs/gen/ex_USERINFO_faulty.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block:: sv
+
+         $info("User elaboration-time info");

docs/gen/ex_USERINFO_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block::
+
+   -Info: example.v:1:7 User elaboration-time info

docs/gen/ex_USERWARN_faulty.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block:: sv
+
+         $warning("User elaboration-time warning");

docs/gen/ex_USERWARN_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_assert_comp_bad
+.. code-block::
+
+   %Warning-USERWARN: example.v:1:7 User elaboration-time warning

docs/gen/ex_VARHIDDEN_faulty.rst

@@ -0,0 +1,8 @@
+.. comment: generated by t_var_bad_hide_docs
+.. code-block:: sv
+   :linenos:
+   :emphasize-lines: 2
+
+   module t;
+      integer t;  //<--- Warning ('t' hidden by module 't')
+   endmodule

docs/gen/ex_VARHIDDEN_msg.rst

@@ -0,0 +1,5 @@
+.. comment: generated by t_var_bad_hide_docs
+.. code-block::
+
+   %Warning-VARHIDDEN: example.v:2:12 Declaration of signal hides declaration in upper scope: 't'
+                       example.v:1:8 ... Location of original declaration

docs/gen/ex_WIDTH_1_faulty.rst

@@ -0,0 +1,8 @@
+.. comment: generated by t_lint_width_docs_bad
+.. code-block:: sv
+   :linenos:
+   :emphasize-lines: 3
+
+      int array[5];
+      bit [1:0] rd_addr;
+      wire int rd_value = array[rd_addr];  //<--- Warning

docs/gen/ex_WIDTH_1_fixed.rst

@@ -0,0 +1,5 @@
+.. comment: generated by t_lint_width_docs_bad
+.. code-block:: sv
+   :emphasize-lines: 1
+
+      wire int rd_value = array[{1'b0, rd_addr}];  //<--- Fixed

docs/gen/ex_WIDTH_1_msg.rst

@@ -0,0 +1,4 @@
+.. comment: generated by t_lint_width_docs_bad
+.. code-block::
+
+   %Warning-WIDTH: example.v:3:29 Bit extraction of array[4:0] requires 3 bit index, not 2 bits.

docs/guide/changes.rst

@@ -0,0 +1,16 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+****************
+Revision History
+****************
+
+.. COMMENT above header must use ### so there is an extra level of headers
+   here so the index won't show the huge list of revisions when clicking on
+   "Revision History" in the sidebar.
+
+Changes are contained in the :file:`Changes` file of the distribution, and
+also summarized below.  To subscribe to new versions see `Verilator
+Announcements <https://github.com/verilator/verilator-announce>`_.
+
+.. include:: ../_build/gen/Changes

docs/guide/conf.py

@@ -0,0 +1,229 @@
+# pylint: disable=E402
+#
+# Configuration file for Verilator's Sphinx documentation builder.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+#
+# This file only contains overridden options. For a full list:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+#
+# ----------------------------------------------------------------------
+# -- Path setup
+
+from datetime import datetime
+import os
+import re
+import shutil
+import sys
+sys.path.insert(0, os.path.abspath('./_ext'))
+
+import sphinx_rtd_theme
+
+
+def get_vlt_version():
+    filename = "../../Makefile"
+    with open(filename) as fh:
+        for line in fh:
+            match = re.search(r"PACKAGE_VERSION_NUMBER *= *([a-z0-9.]+)", line)
+            if match:
+                return match.group(1)
+    return "unknown"
+
+
+def setup(app):
+    app.add_css_file('css/vlt_sphinx.css')
+
+
+# ----------------------------------------------------------------------
+# -- Project information
+
+project = 'Verilator'
+copyright = '2021 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
+author = 'Wilson Snyder'
+
+# The master toctree document.
+master_doc = "index"
+
+version = get_vlt_version()
+release = get_vlt_version()
+
+rst_prolog = """
+.. role:: vlopt(option)
+"""
+
+# ----------------------------------------------------------------------
+# -- General configuration
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+# To install:
+#   sudo install enchant
+#   sudo pip3 install sphinx sphinx_rtd_theme breathe sphinxcontrib-spelling
+# We keep this list empty for now to avoid needing dependencies
+extensions = []
+# extensions = ['breathe', 'sphinxcontrib.spelling']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    '_build', 'Thumbs.db', '.DS_Store', 'internals.rst', 'xml.rst', 'gen/ex_*',
+    'CONTRIBUTING.rst'
+]
+
+# Warn about refs
+nitpicky = True
+nitpicky_ignore = []
+
+# Number figures for referencing
+numfig = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = [".rst"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# Date format to ISO
+today_fmt = datetime.now().strftime("%F")
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = True
+
+# TODO could use this for internals<->guide references
+# intersphinx_mapping = { 'sphinx': ('https://sphinx-doc.org/', None), }
+
+# ----------------------------------------------------------------------
+# -- Options for HTML output
+
+# html_baseurl =
+
+html_domain_indices = False
+
+html_logo = "../_static/verilator_192_150_min.png"
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+html_theme_options = {
+    'analytics_id': 'G-D27B0C9QEB',
+    'logo_only': True,
+    'style_nav_header_background': "#45acf8",  # Default is #2980B9
+    # 'canonical_url':
+}
+
+html_context = {
+    'display_github': True,
+    'github_user': 'verilator',
+    'github_repo': 'verilator',
+    'github_version': 'master/docs/guide/',
+}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['../_static']
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+html_show_sphinx = False
+
+html_copy_source = False
+html_show_sourcelink = False
+
+html_use_index = False
+
+html_favicon = "../_static/verilator_32x32_min.png"
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+# html_extra_path = []
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# ----------------------------------------------------------------------
+# -- Options for Latex output
+
+latex_logo = "../_static/verilator_logo.png"
+
+latex_elements = {
+    'extraclassoptions': 'openany,oneside',
+    'papersize': 'letterpaper',
+    'makeindex': '',
+    'printindex': '',
+    # 'pointsize': '10pt',
+    # 'preamble': '',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+# latex_documents = [
+#    (
+#        master_doc,
+#        "Verilog-to-Routing.tex",
+#        "Verilog-to-Routing Documentation",
+#        "VTR Developers",
+#        "manual",
+#    ),
+# ]
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+# latex_show_urls = False
+
+latex_domain_indices = False
+
+# ----------------------------------------------------------------------
+# -- Options for manual page output
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+# man_pages = [(master_doc, "verilog-to-routing", "Verilog-to-Routing Documentation", [author], 1)]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False
+
+# ----------------------------------------------------------------------
+# -- Options for spelling
+
+spelling_word_list_filename = ['spelling.txt']
+spelling_ignore_contributor_names = True
+
+# ----------------------------------------------------------------------
+# -- Options for doxygen
+
+#if shutil.which("doxygen"):
+#    breathe_projects = {
+#        "verilated": "../_build/doxygen/verilated/xml",
+#    }
+#    breathe_default_project = "verilated"
+#
+#    if not os.environ.get("SKIP_DOXYGEN", None) == "True":
+#        for prjname, prjdir in breathe_projects.items():
+#            print("Generating doxygen files for {}...".format(prjname))
+#            os.makedirs(prjdir, exist_ok=True)
+#            cmd = "cd ../_doxygen && doxygen {}.dox".format(prjname)
+#            subprocess.call(cmd, shell=True)
+#    else:
+#        for prjname, prjdir in breathe_projects.items():
+#            assert os.path.exists(prjdir) == True, "Regenerate doxygen XML for {}".format(prjname)
+
+breathe_projects = {"verilated": "_build/doxygen/verilated/xml/"}
+breathe_default_project = "verilated"
+breathe_default_members = ('members')

docs/guide/connecting.rst

@@ -0,0 +1,451 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Connecting:
+
+******************************
+Connecting to Verilated Models
+******************************
+
+.. _Connecting to C++:
+
+Connecting to C++
+=================
+
+Verilator creates a :file:`{prefix}.h` and :file:`{prefix}.cpp` file for
+the top level module, together with additional .h and .cpp files for
+internals. See the :file:`examples` directory in the kit for examples.  See
+:ref:`Files Read/Written` for information on all the files it writes.
+
+After the model is created, there will be a :file:`{prefix}.mk` file that
+may be used with Make to produce a :file:`{prefix}__ALL.a` file with all
+required objects in it.
+
+The user must write a C++ wrapper and main loop for the simulation, to link
+with the Verilated model.  Here is a simple example:
+
+.. code-block:: C++
+
+         #include <verilated.h>          // Defines common routines
+         #include <iostream>             // Need std::cout
+         #include "Vtop.h"               // From Verilating "top.v"
+
+         Vtop *top;                      // Instantiation of module
+
+         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 instance
+
+             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 signals are read and written as member variables 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
+=====================
+
+Verilator will convert the top level module to a SC_MODULE.  This module
+will attach directly into a SystemC 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
+become sc_bv's.  (Uints simulate the fastest so are used where possible.)
+
+Lower modules are not pure SystemC code.  This is a feature, as using the
+SystemC pin interconnect scheme everywhere would reduce performance by an
+order of magnitude.
+
+
+Direct Programming Interface (DPI)
+==================================
+
+Verilator supports SystemVerilog Direct Programming Interface import and
+export statements.  Only the SystemVerilog form ("DPI-C") is supported, not
+the original Synopsys-only DPI.
+
+DPI Example
+-----------
+
+In the SYSTEMC example above, if you wanted to import C++ functions into
+Verilog, put in our.v:
+
+.. code-block::
+
+    import "DPI-C" function int add (input int a, input int b);
+
+    initial begin
+       $display("%x + %x = %x", 1, 2, add(1,2));
+    endtask
+
+Then after Verilating, Verilator will create a file Vour__Dpi.h with the
+prototype to call this function:
+
+.. code-block:: C++
+
+     extern int add(int a, int b);
+
+From the sc_main.cpp file (or another .cpp file passed to the Verilator
+command line, or the link), you'd then:
+
+.. code-block:: C++
+
+     #include "svdpi.h"
+     #include "Vour__Dpi.h"
+     int add(int a, int b) { return a+b; }
+
+
+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
+function name for the import, but note it must be escaped.
+
+.. code-block:: sv
+
+    export "DPI-C" function integer \$myRand;
+
+    initial $display("myRand=%d", $myRand());
+
+Going the other direction, you can export Verilog tasks so they can be
+called from C++:
+
+.. code-block:: sv
+
+    export "DPI-C" task publicSetBool;
+
+    task publicSetBool;
+       input bit in_bool;
+       var_bool = in_bool;
+    endtask
+
+Then after Verilating, Verilator will create a file Vour__Dpi.h with the
+prototype to call this function:
+
+.. code-block:: C++
+
+     extern void publicSetBool(svBit in_bool);
+
+From the sc_main.cpp file, you'd then:
+
+.. code-block:: C++
+
+     #include "Vour__Dpi.h"
+     publicSetBool(value);
+
+Or, alternatively, call the function under the design class.  This isn't
+DPI compatible but is easier to read and better supports multiple designs.
+
+.. code-block:: C++
+
+     #include "Vour__Dpi.h"
+     Vour::publicSetBool(value);
+     // or top->publicSetBool(value);
+
+Note that if the DPI task or function accesses any register or net within
+the RTL, it will require a scope to be set. This can be done using the
+standard functions within svdpi.h, after the module is instantiated, but
+before the task(s) and/or function(s) are called.
+
+For example, if the top level module is instantiated with the name "dut"
+and the name references within tasks are all hierarchical (dotted) names
+with respect to that top level module, then the scope could be set with
+
+.. code-block:: C++
+
+     #include "svdpi.h"
+     ...
+     svSetScope(svGetScopeFromName("TOP.dut"));
+
+(Remember that Verilator adds a "TOP" to the top of the module hierarchy.)
+
+Scope can also be set from within a DPI imported C function that has been
+called from Verilog by querying the scope of that function. See the
+sections on DPI Context Functions and DPI Header Isolation below and the
+comments within the svdpi.h header for more information.
+
+
+DPI Imports that access signals
+-------------------------------
+
+If a DPI import accesses a signal through the VPI Verilator will not be
+able to know what variables are accessed and may schedule the code
+inappropriately.  Ideally pass the values as inputs/outputs so the VPI is
+not required.  Alternatively a workaround is to use a non-inlined task as a
+wrapper:
+
+.. code-block::
+
+     logic din;
+
+     // This DPI function will read "din"
+     import "DPI-C" context function void dpi_that_accesses_din();
+
+     always @(...)
+        dpi_din_args(din);
+
+     task dpi_din_args(input din);
+        /* verilator no_inline_task */
+        dpi_that_accesses_din();
+     endtask
+
+
+DPI Display Functions
+---------------------
+
+Verilator allows writing $display like functions using this syntax:
+
+.. code-block::
+
+    import "DPI-C" function void
+          \$my_display(input string formatted /*verilator sformat*/ );
+
+The :option:`/*verilator&32;sformat*/` metacomment indicates that this
+function accepts a $display like format specifier followed by any number of
+arguments to satisfy the format.
+
+
+DPI Context Functions
+---------------------
+
+Verilator supports IEEE DPI Context Functions.  Context imports pass the
+simulator context, including calling scope name, and filename and line
+number to the C code.  For example, in Verilog:
+
+.. code-block::
+
+    import "DPI-C" context function int dpic_line();
+    initial $display("This is line %d, again, line %d\n", `line, dpic_line());
+
+This will call C++ code which may then use the svGet\* functions to read
+information, in this case the line number of the Verilog statement that
+invoked the dpic_line function:
+
+.. code-block:: C++
+
+    int dpic_line() {
+        // Get a scope:  svScope scope = svGetScope();
+
+        const char* scopenamep = svGetNameFromScope(scope);
+        assert(scopenamep);
+
+        const char* filenamep = "";
+        int lineno = 0;
+        if (svGetCallerInfo(&filenamep, &lineno)) {
+            printf("dpic_line called from scope %s on line %d\n",
+               scopenamep, lineno);
+            return lineno;
+        } else {
+            return 0;
+        }
+    }
+
+See the IEEE Standard for more information.
+
+
+DPI Header Isolation
+--------------------
+
+Verilator places the IEEE standard header files such as svdpi.h into a
+separate include directory, vltstd (VeriLaTor STandarD).  When compiling
+most applications $VERILATOR_ROOT/include/vltstd would be in the include
+path along with the normal $VERILATOR_ROOT/include.  However, when
+compiling Verilated models into other simulators which have their own
+svdpi.h and similar standard files with different contents, the vltstd
+directory should not be included to prevent picking up incompatible
+definitions.
+
+
+Public Functions
+----------------
+
+Instead of DPI exporting, there's also Verilator public functions, which
+are slightly faster, but less compatible.
+
+
+Verification Procedural Interface (VPI)
+=======================================
+
+Verilator supports a limited subset of the VPI.  This subset allows
+inspection, examination, value change callbacks, and depositing of values
+to public signals only.
+
+VPI is enabled with the Verilator :vlopt:`--vpi` option.
+
+To access signals via the VPI, Verilator must be told exactly which signals
+are to be accessed.  This is done using the Verilator public pragmas
+documented below.
+
+Verilator has an important difference from an event based simulator; signal
+values that are changed by the VPI will not immediately propagate their
+values, instead the top level header file's :code:`eval()` method must be
+called.  Normally this would be part of the normal evaluation (i.e. the
+next clock edge), not as part of the value change.  This makes the
+performance of VPI routines extremely fast compared to event based
+simulators, but can confuse some test-benches that expect immediate
+propagation.
+
+Note the VPI by its specified implementation will always be much slower
+than accessing the Verilator values by direct reference
+(structure->module->signame), as the VPI accessors perform lookup in
+functions at simulation runtime requiring at best hundreds of instructions,
+while the direct references are evaluated by the compiler and result in
+only a couple of instructions.
+
+For signal callbacks to work the main loop of the program must call
+:code:`VerilatedVpi::callValueCbs()`.
+
+
+.. _VPI Example:
+
+VPI Example
+-----------
+
+In the below example, we have readme marked read-only, and writeme which if
+written from outside the model will have the same semantics as if it
+changed on the specified clock edge.
+
+.. code-block:: bash
+
+     cat >our.v <<'EOF'
+       module our (input clk);
+          reg readme   /*verilator public_flat_rd*/;
+          reg writeme  /*verilator public_flat_rw @(posedge clk) */;
+          initial $finish;
+       endmodule
+     EOF
+
+There are many online tutorials and books on the VPI, but an example that
+accesses the above signal "readme" would be:
+
+.. code-block:: bash
+
+     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
+       double sc_time_stamp() { return main_time; }
+
+       void read_and_check() {
+           vpiHandle vh1 = vpi_handle_by_name((PLI_BYTE8*)"TOP.our.readme", NULL);
+           if (!vh1) vl_fatal(__FILE__, __LINE__, "sim_main", "No handle found");
+           const char* name = vpi_get_str(vpiName, vh1);
+           printf("Module name: %s\n", name);  // Prints "readme"
+
+           s_vpi_value v;
+           v.format = vpiIntVal;
+           vpi_get_value(vh1, &v);
+           printf("Value of v: %d\n", v.value.integer);  // Prints "readme"
+       }
+
+       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()) {
+               top->eval();
+               VerilatedVpi::callValueCbs();  // For signal callbacks
+               read_and_check();
+           }
+           delete top;
+           return 0;
+       }
+     EOF
+
+
+.. _Evaluation Loop:
+
+Wrappers and Model Evaluation Loop
+==================================
+
+When using SystemC, evaluation of the Verilated model is managed by the
+SystemC kernel, and for the most part can be ignored.  When using C++, the
+user must call :code:`eval()`, or :code:`eval_step()` and
+:code:`eval_end_step()`.
+
+1. When there is a single design instantiated at the C++ level that needs
+to evaluate within a given context, call :code:`designp->eval()`.
+
+2. When there are multiple designs instantiated at the C++ level that need
+to evaluate within a context, call :code:`first_designp->eval_step()` then
+:code:`->eval_step()` on all other designs.  Then call
+:code:`->eval_end_step()` on the first design then all other designs.  If
+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.
+
+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.
+
+Note combinatorial logic is not computed before sequential always blocks
+are computed (for speed reasons). Therefore it is best to set any non-clock
+inputs up with a separate :code:`eval()` call before changing clocks.
+
+Alternatively, if all always_ff statements use only the posedge of clocks,
+or all inputs go directly to always_ff statements, as is typical, then you
+can change non-clock inputs on the negative edge of the input clock, which
+will be faster as there will be fewer :code:`eval()` calls.
+
+For more information on evaluation, see :file:`docs/internals.rst` in the
+distribution.
+
+
+Verilated and VerilatedContext
+==============================
+
+Multiple Verilated models may be part of the same simulation context, that
+is share a VPI interface, sense of time, and common settings.  This common
+simulation context information is stored in a ``VerilatedContext``
+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
+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
+methods called on the appropriate VerilatedContext object.
+
+For methods available under Verilated and VerilatedContext see
+:file:`include/verilated.h` in the distribution.

docs/guide/contributing.rst

@@ -0,0 +1,68 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+*******************************
+Contributing and Reporting Bugs
+*******************************
+
+Announcements
+=============
+
+To get notified of new releases and other important announcements, go to
+`Verilator announcement repository
+<https://github.com/verilator/verilator-announce>`__ and follow the
+instructions there.
+
+
+Reporting Bugs
+==============
+
+First, check the :ref:`Language Limitations` section.
+
+Next, try the :vlopt:`--debug` option.  This will enable additional
+internal assertions, and may help identify the problem.
+
+Finally, reduce your code to the smallest possible routine that exhibits
+the bug.  Even better, create a test in the :file:`test_regress/t`
+directory, as follows:
+
+.. code-block:: bash
+
+       cd test_regress
+       cp -p t/t_EXAMPLE.pl t/t_BUG.pl
+       cp -p t/t_EXAMPLE.v t/t_BUG.v
+
+There are many hints on how to write a good test in the
+:file:`test_regress/driver.pl` documentation which can be seen by running:
+
+.. code-block:: bash
+
+       cd $VERILATOR_ROOT  # Need the original distribution kit
+       test_regress/driver.pl --help
+
+Edit :file:`t/t_BUG.pl` to suit your example; you can do anything you want
+in the Verilog code there; just make sure it retains the single clk input
+and no outputs.  Now, the following should fail:
+
+.. code-block:: bash
+
+       cd $VERILATOR_ROOT  # Need the original distribution kit
+       cd test_regress
+       t/t_BUG.pl  # Run on Verilator
+       t/t_BUG.pl --debug # Run on Verilator, passing --debug to Verilator
+       t/t_BUG.pl --vcs  # Run on VCS simulator
+       t/t_BUG.pl --nc|--iv|--ghdl  # Likewise on other simulators
+
+The test driver accepts a number of options, many of which mirror the main
+Verilator options. For example the previous test could have been run with
+debugging enabled.  The full set of test options can be seen by running
+:command:`driver.pl --help` as shown above.
+
+Finally, report the bug at `Verilator Issues
+<https://verilator.org/issues>`_.  The bug will become publicly visible; if
+this is unacceptable, mail the bug report to ``[email protected]``.
+
+
+.. Contributing
+.. ============
+.. include:: ../CONTRIBUTING.rst

docs/guide/contributors.rst

@@ -0,0 +1,155 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+************************
+Contributors and Origins
+************************
+
+Authors
+=======
+
+When possible, please instead report bugs at `Verilator Issues
+<https://verilator.org/issues>`_.
+
+Primary author is Wilson Snyder <[email protected]>.
+
+Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
+
+
+Contributors
+============
+
+Many people have provided ideas and other assistance with Verilator.
+
+Verilator is receiving major development support from the `CHIPS Alliance
+<https://chipsalliance.org>`_.
+
+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.
+
+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.
+
+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
+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
+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.
+
+Thanks to them, and all those we've missed including above, or wished to
+remain anonymous.
+
+Historical Origins
+==================
+
+Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group at
+Digital Equipment Corporation.  The Verilog code that was converted to C
+was then merged with a C based CPU model of the Alpha processor and
+simulated in a C based environment called CCLI.
+
+In 1995 Verilator started being used also for Multimedia and Network
+Processor development inside Digital.  Duane Galbi took over active
+development of Verilator, and added several performance enhancements.  CCLI
+was still being used as the shell.
+
+In 1998, through the efforts of existing DECies, mainly Duane Galbi,
+Digital graciously agreed to release the source code.  (Subject to the code
+not being resold, which is compatible with the GNU Public License.)
+
+In 2001, Wilson Snyder took the kit, and added a SystemC mode, and called
+it Verilator2.  This was the first packaged public release.
+
+In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator from
+scratch in C++.  This added many optimizations, yielding about a 2-5x
+performance gain.
+
+In 2009, major SystemVerilog and DPI language support was added.
+
+In 2018, Verilator 4.000 was released with multithreaded support.
+
+In 2019, Verilator joined the `CHIPS Alliance
+<https://chipsalliance.org>`_.
+
+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.

docs/guide/copyright.rst

@@ -0,0 +1,19 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+*********
+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
+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.
+
+All Verilog and C++/SystemC code quoted within this documentation file are
+released as Creative Commons Public Domain (CC0).  Many example files and
+test files are likewise released under CC0 into effectively the Public
+Domain as described in the files themselves.

docs/guide/deprecations.rst

@@ -0,0 +1,28 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+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.
+
+No-Relative-Cfuncs Option
+  The :vlopt:`--no-relative-cfuncs` option is not be required by any C++11
+  compliant compiler and is planned for removal no sooner than July 2021.
+
+Inhibit-Sim Option
+  The :vlopt:`--inhibit-sim` option is planned for removal no sooner than
+  July 2021.
+
+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.
+
+XML locations
+  The XML "fl" attribute has been replaced with the "loc" attribute.  "fl"
+  is planned for removal no sooner than January 2021.

docs/guide/environment.rst

@@ -0,0 +1,93 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+Environment
+===========
+
+This section describes the environment variables used by Verilator and
+associated programs.
+
+.. option:: LD_LIBRARY_PATH
+
+   A generic Linux/OS variable specifying what directories have shared
+   object (.so) files.  This path should include SystemC and any other
+   shared objects needed at simulation runtime.
+
+.. option:: MAKE
+
+   Names the executable of the make command invoked when using the
+   :vlopt:`--build` option.  Some operating systems may require "gmake" to
+   this variable to launch GNU make.  If this variable is not specified,
+   "make" is used.
+
+.. option:: OBJCACHE
+
+   Optionally specifies a caching or distribution program to place in front
+   of all runs of the C++ compiler.  For example, "ccache".  If using
+   :command:`distcc` or :command:`icecc`/:command:`icecream`, they would
+   generally be run under :command:`ccache`; see the documentation for
+   those programs.  If OBJCACHE is not set, and at configure time ccache
+   was present, ccache will be used as a default.
+
+.. option:: SYSTEMC
+
+   Deprecated.  Used only if :option:`SYSTEMC_INCLUDE` or
+   :option:`SYSTEMC_LIBDIR` is not set.  If set, specifies the directory
+   containing the SystemC distribution.  If not specified, it will come
+   from a default optionally specified at configure time (before Verilator
+   was compiled).
+
+.. option:: SYSTEMC_ARCH
+
+   Deprecated.  Used only if :option:`SYSTEMC_LIBDIR` is not set.
+   Specifies the architecture name used by the SystemC kit.  This is the
+   part after the dash in the "lib-{...}" directory name created by a
+   :command:`make` in the SystemC distribution.  If not set, Verilator will
+   try to intuit the proper setting, or use the default optionally
+   specified at configure time (before Verilator was compiled).
+
+.. option:: SYSTEMC_CXX_FLAGS
+
+   Specifies additional flags that are required to be passed to GCC when
+   building the SystemC model.  System 2.3.0 may need this set to
+   "-pthread".
+
+.. option:: SYSTEMC_INCLUDE
+
+   If set, specifies the directory containing the systemc.h header file. If
+   not specified, it will come from a default optionally specified at
+   configure time (before Verilator was compiled), or computed from
+   SYSTEMC/include.
+
+.. option:: SYSTEMC_LIBDIR
+
+   If set, specifies the directory containing the libsystemc.a library. If
+   not specified, it will come from a default optionally specified at
+   configure time (before Verilator was compiled), or computed from
+   SYSTEMC/lib-SYSTEMC_ARCH.
+
+.. option:: VERILATOR_BIN
+
+   If set, specifies an alternative name of the ``verilator`` binary.  May
+   be used for debugging and selecting between multiple operating system
+   builds.
+
+.. option:: VERILATOR_COVERAGE_BIN
+
+   If set, specifies an alternative name of the ``verilator_coverage``
+   binary.  May be used for debugging and selecting between multiple
+   operating system builds.
+
+.. option:: VERILATOR_GDB
+
+   If set, the command to run when using the :vlopt:`--gdb` option, such as
+   "ddd".  If not specified, it will use "gdb".
+
+.. option:: VERILATOR_ROOT
+
+   Specifies the directory containing the distribution kit.  This is used
+   to find the executable, Perl library, and include files.  If not
+   specified, it will come from a default optionally specified at configure
+   time (before Verilator was compiled).  It should not be specified if
+   using a pre-compiled Verilator package as the hard-coded value should be
+   correct.  See :ref:`Installation`.

docs/guide/example_cc.rst

@@ -0,0 +1,92 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Example C++ Execution:
+
+Example C++ Execution
+=====================
+
+We'll compile this example into C++.  For an extended and commented version
+of what this C++ code is doing, see
+:file:`examples/make_tracing_c/sim_main.cpp` in the distribution.
+
+.. include:: example_common_install.rst
+
+Now, let's create an example Verilog, and C++ wrapper 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
+
+     cat >sim_main.cpp <<'EOF'
+       #include "Vour.h"
+       #include "verilated.h"
+       int main(int argc, char** argv, char** env) {
+           VerilatedContext* contextp = new VerilatedContext;
+           contextp->commandArgs(argc, argv);
+           Vour* top = new Vour{contextp};
+           while (!contextp->gotFinish()) { top->eval(); }
+           delete top;
+           delete contextp;
+           return 0;
+       }
+     EOF
+
+Now we run Verilator on our little example.
+
+.. code-block:: bash
+
+     verilator -Wall --cc --exe --build 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).
+
+#. :vlopt:`--exe`, along with our :command:`sim_main.cpp` wrapper file, so
+   the build will create an executable instead of only a library.
+
+#. :vlopt:`--build` so Verilator will call make itself. This is we don't
+   need to manually call make as a separate step. You can also write your
+   own compile rules, and run make yourself as we show in :ref:`Example
+   SystemC Execution`.)
+
+#. An finally, :command:`our.v` which is our SystemVerilog design file.
+
+Once Verilator completes we can see the generated C++ code under the
+:file:`obj_dir` directory.
+
+.. code-block:: bash
+
+     ls -l obj_dir
+
+(See :ref:`Files Read/Written` for descriptions of some of the files that
+were created.)
+
+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_common_install.rst

@@ -0,0 +1,16 @@
+.. Copyright 2003-2021 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
+you installed Verilator using the package manager of your operating system,
+or did a :command:`make install` to place Verilator into your default path,
+you do not need anything special in your environment, and should not have
+VERILATOR_ROOT set.  However, if you installed Verilator from sources and
+want to run Verilator out of where you compiled Verilator, you need to
+point to the kit:
+
+.. code-block:: bash
+
+     # See above; don't do this if using an OS-distributed Verilator
+     export VERILATOR_ROOT=/path/to/where/verilator/was/installed
+     export PATH=$VERILATOR_ROOT/bin:$PATH

docs/guide/example_dist.rst

@@ -0,0 +1,40 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Examples in the Distribution:
+
+Examples in the Distribution
+============================
+
+See the ``examples/`` directory that is part of the distribution, and
+is installed (in a OS-specific place, often in e.g.
+``/usr/local/share/verilator/examples``).  These examples include:
+
+examples/make_hello_c
+   Example GNU-make simple Verilog->C++ conversion
+examples/make_hello_sc
+   Example GNU-make simple Verilog->SystemC conversion
+examples/make_tracing_c
+   Example GNU-make Verilog->C++ with tracing
+examples/make_tracing_sc
+   Example GNU-make Verilog->SystemC with tracing
+examples/make_protect_lib
+   Example using --protect-lib
+examples/cmake_hello_c
+   Example building make_hello_c with CMake
+examples/cmake_hello_sc
+   Example building make_hello_sc with CMake
+examples/cmake_tracing_c
+   Example building make_tracing_c with CMake
+examples/cmake_tracing_sc
+   Example building make_tracing_sc with CMake
+examples/cmake_protect_lib
+   Example building make_protect_lib with CMake
+
+To run an example copy the example to a new directory and run it.
+
+::
+
+      cp -rp {path_to}/examples/make_hello_c make_hello_c
+      cd make_hello_c
+      make

docs/guide/example_sc.rst

@@ -0,0 +1,73 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Example SystemC Execution:
+
+Example SystemC Execution
+=========================
+
+This is an example similar to the :ref:`Example C++ Execution`, but using
+SystemC. We'll also explicitly run make.
+
+.. include:: example_common_install.rst
+
+Now, let's create an example Verilog, and SystemC wrapper file:
+
+.. code-block:: bash
+
+     mkdir test_our_sc
+     cd test_our_sc
+
+     cat >our.v <<'EOF'
+       module our (clk);
+          input clk;  // Clock is required to get initial activation
+          always @(posedge clk)
+             begin $display("Hello World"); $finish; end
+       endmodule
+     EOF
+
+     cat >sc_main.cpp <<'EOF'
+       #include "Vour.h"
+       int sc_main(int argc, char** argv) {
+           Verilated::commandArgs(argc, argv);
+           sc_clock clk{"clk", 10, SC_NS, 0.5, 3, SC_NS, true};
+           Vour* top = new Vour{"top"};
+           top->clk(clk);
+           while (!Verilated::gotFinish()) { sc_start(1, SC_NS); }
+           delete top;
+           return 0;
+       }
+     EOF
+
+Now we run Verilator on our little example:
+
+.. code-block:: bash
+
+     verilator -Wall --sc --exe sc_main.cpp our.v
+
+This example does not use --build, therefore we need to explicitly compile
+it:
+
+.. code-block:: bash
+
+     make -j -C obj_dir -f Vour.mk Vour
+
+And now we run it:
+
+.. code-block:: bash
+
+     obj_dir/Vour
+
+And we get, after the SystemC banner, the same output as the C++ example:
+
+.. code-block:: bash
+
+     SystemC 2.3.3-Accellera
+
+     Hello World
+     - our.v:4: 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.
+For examples that do this see the :file:`examples` directory in the
+distribution.

docs/guide/examples.rst

@@ -0,0 +1,22 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Examples:
+
+========
+Examples
+========
+
+This section covers the following examples:
+
+* :ref:`Example C++ Execution`
+* :ref:`Example SystemC Execution`
+* :ref:`Examples in the Distribution`
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   example_cc.rst
+   example_sc.rst
+   example_dist.rst

docs/guide/exe_sim.rst

@@ -0,0 +1,89 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Simulation Runtime Arguments:
+
+Simulation Runtime Arguments
+============================
+
+The following are the arguments that may be passed to a Verilated
+executable, provided that executable calls
+:code:`Verilated::commandArgs()`.
+
+All simulation runtime arguments begin with "+verilator", so that the
+user's executable may skip over all "+verilator" arguments when parsing its
+command line.
+
+Summary:
+
+   .. include:: ../_build/gen/args_verilated.rst
+
+
+.. option:: +verilator+debug
+
+   Enable simulation runtime debugging.  Equivalent to
+   :vlopt:`+verilator+debugi+4 <+verilator+debugi+\<value\>>`.
+
+.. option:: +verilator+debugi+<value>
+
+   Enable simulation runtime debugging at the provided level.
+
+.. option:: +verilator+error+limit+<value>
+
+   Set number of non-fatal errors (e.g. assertion failures) before exiting
+   simulation runtime. Also affects number of $stop calls needed before
+   exit. Defaults to 1.
+
+.. option:: +verilator+help
+
+   Display help and exit.
+
+.. option:: +verilator+prof+threads+file+<filename>
+
+   When a model was Verilated using :vlopt:`--prof-threads`, sets the
+   simulation runtime filename to dump to.  Defaults to
+   :file:`profile_threads.dat`.
+
+.. option:: +verilator+prof+threads+start+<value>
+
+   When a model was Verilated using :vlopt:`--prof-threads`, 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>
+
+   When a model was Verilated using :vlopt:`--prof-threads`, after $time
+   reaches :vlopt:`+verilator+prof+threads+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+rand+reset+<value>
+
+   When a model was Verilated using :vlopt:`--x-initial unique
+   <--x-initial>`, sets the simulation runtime initialization technique.  0
+   = Reset to zeros. 1 = Reset to all-ones.  2 = Randomize.  See
+   :ref:`Unknown States`.
+
+.. option:: +verilator+seed+<value>
+
+   For $random and :vlopt:`--x-initial unique <--x-initial>`, set the
+   simulation runtime random seed value.  If zero or not specified picks a
+   value from the system random number generator.
+
+.. option:: +verilator+noassert
+
+   Disable assert checking per runtime argument. This is the same as
+   calling :code:`Verilated::assertOn(false)` in the model.
+
+.. option:: +verilator+V
+
+   Shows the verbose version, including configuration information.
+
+.. option:: +verilator+version
+
+   Displays program version and exits.

docs/guide/exe_verilator_coverage.rst

@@ -0,0 +1,114 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+verilator_coverage
+==================
+
+Verilator_coverage processes Verilated model-generated coverage reports.
+
+With --annotate, it reads the specified coverage data file and generates
+annotated source code with coverage metrics annotated.  If multiple
+coverage points exist on the same source code line, additional lines will
+be inserted to report the additional points.
+
+Additional Verilog-XL-style standard arguments specify the search paths
+necessary to find the source code that the coverage analysis was performed
+on.
+
+To filter those items to be included in coverage, you may read
+logs/coverage.dat into an editor and do a M-x keep-lines to include only
+those statistics of interest and save to a new .dat file.
+
+For Verilog conditions that should never occur, either add a $stop
+statement to the appropriate statement block, or see
+:option:`/*verilator&32;coverage_off*/`.  This will remove the coverage
+points after the model is re-Verilated.
+
+For an overview of use of verilator_coverage, see :ref:`Coverage Analysis`.
+
+
+verilator_coverage Example Usage
+--------------------------------
+
+..
+
+    verilator_coverage --help
+    verilator_coverage --version
+
+    verilator_coverage --annotate <obj>
+
+    verilator_coverage  -write merged.dat -read <datafiles>...
+
+    verilator_coverage  -write-info merged.info -read <datafiles>...
+
+
+verilator_coverage Arguments
+----------------------------
+
+.. program:: verilator_coverage
+
+.. option:: <filename>
+
+Specifies the input coverage data file.  Multiple filenames may be provided
+to read multiple inputs.  If no data file is specified, by default
+"coverage.dat" will be read.
+
+.. option:: --annotate <output_directory>
+
+Specifies the directory name that source files with annotated coverage data
+should be written to.
+
+.. option:: --annotate-all
+
+Specifies all files should be shown.  By default, only those source files
+which have low coverage are written to the output directory.
+
+.. option:: --annotate-min <count>
+
+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
+is not sufficient.  Defaults to 10.
+
+.. option:: --help
+
+Displays a help summary, the program version, and exits.
+
+.. option:: --rank
+
+Prints an experimental report listing the relative importance of each test
+in covering all of the coverage points.  The report shows "Covered" which
+indicates the number of points that test covers; a test is considered to
+cover a point if it has a bucket count of at least 1. The "rank" column has
+a higher number t indicate the test is more important, and rank 0 means the
+test does not need to be run to cover the points.  "RankPts" indicates the
+number of coverage points this test will contribute to overall coverage if
+all tests are run in the order of highest to lowest rank.
+
+.. option:: --unlink
+
+With :option:`--write`, unlink all input files after the output
+has been successfully created.
+
+.. option:: --version
+
+Displays program version and exits.
+
+.. option:: --write <filename>
+
+Specifies the aggregate coverage results, summed across all the files,
+should be written to the given filename in verilator_coverage data format.
+This is useful for use in scripts to combine many coverage data files
+(likely generated from random test runs) into one master coverage file.
+
+.. option:: --write-info <filename.info>
+
+Specifies the aggregate coverage results, summed across all the files,
+should be written to the given filename in :command:`lcov` .info format.
+This may be used to feed into :command:`lcov` to aggregate or generate
+reports.
+
+The info format loses data compared to the Verilator coverage data format;
+the info will all forms of coverage converted to line style coverage, and
+if there are multiple coverage points on a single line, the minimum
+coverage across those points will be used to report coverage of the line.

docs/guide/exe_verilator_gantt.rst

@@ -0,0 +1,76 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+verilator_gantt
+===============
+
+Verilator_gantt creates a visual representation to help analyze Verilator
+multithreaded simulation performance, by showing when each macro-task
+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
+--------------------
+
+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.
+
+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.
+
+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.
+
+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
+  view this signal.
+
+cpu#_thread
+  For the given CPU number, the thread number executing.
+
+mtask#_cpu
+  For the given mtask id, the CPU it is executing on.
+
+thread#_mtask
+  For the given thread number, the mtask id executing.
+
+verilator_gantt Arguments
+-------------------------
+
+.. program:: verilator_gantt
+
+.. option:: <filename>
+
+The filename to read data from, defaults to "profile_threads.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.
+
+.. option:: --vcd <filename>
+
+Sets the output filename for vcd dump. Default is "verilator_gantt.vcd".

docs/guide/exe_verilator_profcfuncs.rst

@@ -0,0 +1,25 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+verilator_profcfuncs
+====================
+
+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`.
+
+verilator_profcfuncs Arguments
+------------------------------
+
+.. program:: verilator_profcfuncs
+
+.. option:: <filename>
+
+The :command:`gprof`-generated filename to read data from. Typically "gprof.out".
+
+.. option:: --help
+
+Displays a help summary, the program version, and exits.

docs/guide/executables.rst

@@ -0,0 +1,19 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+*********************************
+Executable and Argument Reference
+*********************************
+
+This section describes the executables that are part of Verilator, and the
+options to each executable.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   exe_verilator.rst
+   exe_verilator_coverage.rst
+   exe_verilator_gantt.rst
+   exe_verilator_profcfuncs.rst
+   exe_sim.rst

docs/guide/extensions.rst

@@ -0,0 +1,490 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+*******************
+Language Extensions
+*******************
+
+The following additional constructs are the extensions Verilator supports
+on top of standard Verilog code.  Using these features outside of comments
+or "`ifdef`"'s may break other tools.
+
+.. option:: `__FILE__
+
+   The :option:`\`__FILE__` define expands to the current filename as a
+   string, like C++'s __FILE__.  This Verilator feature added in 2006 was
+   incorporated into the IEEE 1800-2009 standard.
+
+.. option:: `__LINE__
+
+   The :option:`\`__LINE__` define expands to the current filename as a
+   string, like C++'s __LINE__.  This Verilator feature added in 2006 was
+   incorporated into the IEEE 1800-2009 standard.
+
+.. option:: `error [string]
+
+   This will report an error when encountered, like C++'s #error.
+
+.. option:: $c([string], ...);
+
+   The string will be embedded directly in the output C++ code at the point
+   where the surrounding Verilog code is compiled.  It may either be a
+   standalone statement (with a trailing ; in the string), or a function
+   that returns up to a 32-bit number (without a trailing ;). This can be
+   used to call C++ functions from your Verilog code.
+
+   String arguments will be put directly into the output C++ code.
+   Expression arguments will have the code to evaluate the expression
+   inserted.  Thus to call a C++ function, :code:`$c("func(",a,")")` will
+   result in :code:`func(a)` in the output C++ code.  For input arguments,
+   rather than hard-coding variable names in the string
+   :code:`$c("func(a)")`, instead pass the variable as an expression
+   ::code:`$c("func(",a,")")`.  This will allow the call to work inside
+   Verilog functions where the variable is flattened out, and also enable
+   other optimizations.
+
+   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.
+
+   You may also append an arbitrary number to $c, generally the width of
+   the output; :code:`signal_32_bits = $c32("...");`.  This allows for
+   compatibility with other simulators which require a differently named
+   PLI function name for each different output width.
+
+.. option:: $display, $write, $fdisplay, $fwrite, $sformat, $swrite
+
+   Format arguments may use C fprintf sizes after the % escape.  Per the
+   Verilog standard, %x prints a number with the natural width, and %0x
+   prints a number with minimum width.  Verilator extends this so %5x
+   prints 5 digits per the C standard (this is unspecified in Verilog, but
+   was incorporated into the 1800-2009).
+
+.. option:: `coverage_block_off
+
+   Specifies the entire begin/end block should be ignored for coverage
+   analysis.  Must be inside a code block, e.g. within a begin/end pair.
+   Same as :option:`coverage_block_off` in :ref:`Configuration Files`.
+
+.. option:: `systemc_header
+
+   Take remaining text up to the next :option:`\`verilog` or
+   :option:`\`systemc_... <\`systemc_header>` mode switch and place it
+   verbatim into the output .h file's header.  Must be placed as a module
+   item, e.g. directly inside a module/endmodule pair. Despite the name of
+   this macro, this also works in pure C++ code.
+
+.. option:: `systemc_ctor
+
+   Take remaining text up to the next :option:`\`verilog` or
+   :option:`\`systemc_... <\`systemc_header>` mode switch and place it
+   verbatim into the C++ class constructor.  Must be placed as a module
+   item, e.g. directly inside a module/endmodule pair. Despite the name of
+   this macro, this also works in pure C++ code.
+
+.. option:: `systemc_dtor
+
+   Take remaining text up to the next :option:`\`verilog` or
+   :option:`\`systemc_... <\`systemc_header>` mode switch and place it
+   verbatim into the C++ class destructor.  Must be placed as a module
+   item, e.g. directly inside a module/endmodule pair. Despite the name of
+   this macro, this also works in pure C++ code.
+
+.. option:: `systemc_interface
+
+   Take remaining text up to the next :option:`\`verilog` or
+   :option:`\`systemc_... <\`systemc_header>` mode switch and place it
+   verbatim into the C++ class interface.  Must be placed as a module item,
+   e.g. directly inside a module/endmodule pair. Despite the name of this
+   macro, this also works in pure C++ code.
+
+.. option:: `systemc_imp_header
+
+   Take remaining text up to the next :option:`\`verilog` or
+   :option:`\`systemc_... <\`systemc_header>` mode switch and place it
+   verbatim into the header of all files for this C++ class implementation.
+   Must be placed as a module item, e.g. directly inside a module/endmodule
+   pair. Despite the name of this macro, this also works in pure C++ code.
+
+.. option:: `systemc_implementation
+
+   Take remaining text up to the next :option:`\`verilog` or
+   :option:`\`systemc_... <\`systemc_header>` mode switch and place it
+   verbatim into a single file of the C++ class implementation.  Must be
+   placed as a module item, e.g. directly inside a module/endmodule
+   pair. Despite the name of this macro, this also works in pure C++ code.
+
+   If you will be reading or writing any Verilog variables in the C++
+   functions, the Verilog signals must be declared with a
+   :option:`/*verilator&32;public*/` metacomment.  See also the public task
+   feature; writing an accessor may result in cleaner code.
+
+.. option:: `SYSTEMVERILOG
+
+   The SYSTEMVERILOG, SV_COV_START and related standard defines are set by
+   default when :vlopt:`--language <--language>` is "1800-\*".
+
+.. option:: `VERILATOR
+
+.. option:: `verilator
+
+.. option:: `verilator3
+
+   The VERILATOR, verilator and verilator3 defines are set by default so
+   you may "\`ifdef" around tool specific constructs.
+
+.. option:: `verilator_config
+
+   Take remaining text up to the next :option:`\`verilog` mode switch and
+   treat it as Verilator configuration commands.  See :ref:`Configuration Files`.
+
+.. option:: `verilog
+
+   Switch back to processing Verilog code after a
+   :option:`\`systemc_... <\`systemc_header>` mode switch.  The Verilog
+   code returns to the last language mode specified with
+   "\`begin_keywords", or SystemVerilog if none was specified.
+
+.. option:: /*verilator&32;clock_enable*/
+
+   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
+   analysis.) For example:
+
+   .. code-block:: sv
+
+         reg enable_r /*verilator clock_enable*/;
+         wire gated_clk = clk & enable_r;
+         always_ff @(posedge clk)
+            enable_r <= enable_early;
+
+   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.
+
+   Same as :option:`clock_enable` configuration file option.
+
+.. option:: /*verilator&32;clocker*/
+
+.. 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`.
+
+   Same as :option:`clocker` and :option:`no_clocker` in configuration
+   files.
+
+.. option:: /*verilator&32;coverage_block_off*/
+
+   Specifies the entire begin/end block should be ignored for coverage
+   analysis purposes.
+
+   Same as :option:`coverage_block_off` configuration file option.
+
+.. option:: /*verilator&32;coverage_off*/
+
+   Specifies that following lines of code should have coverage disabled.
+   Often used to ignore an entire module for coverage analysis purposes.
+
+.. option:: /*verilator&32;coverage_on*/
+
+   Specifies that following lines of code should have coverage re-enabled
+   (if appropriate :vlopt:`--coverage` flags are passed) after being
+   disabled earlier with :option:`/*verilator&32;coverage_off*/`.
+
+
+.. _verilator_hier_block:
+
+.. option:: /*verilator&32;hier_block*/
+
+   Specifies that the module is a unit of hierarchical Verilation.  This
+   metacomment must be between :code:`module module_name(...);` and
+   :code:`endmodule`.  The module will not be inlined nor uniquified for
+   each instance in hierarchical Verilation.  Note that the metacomment is
+   ignored unless the :vlopt:`--hierarchical` option is specified.
+
+   See :ref:`Hierarchical Verilation`.
+
+.. option:: /*verilator&32;inline_module*/
+
+   Specifies the module the comment appears in may be inlined into any
+   modules that use this module.  This is useful to speed up simulation
+   runtime.  Note if using :vlopt:`--public` that signals under inlined
+   submodules will be named :code:`{submodule}__DOT__{subsignal}` as C++
+   does not allow "." in signal names.
+
+   Same as :option:`inline` configuration file option.
+
+.. option:: /*verilator&32;isolate_assignments*/
+
+   Used after a signal declaration to indicate the assignments to this
+   signal in any blocks should be isolated into new blocks.  When there is
+   a large combinatorial block that is resulting in an ``UNOPTFLAT``
+   warning, attaching this to the signal causing a false loop may clear up
+   the problem.
+
+   IE, with the following:
+
+   .. code-block:: sv
+
+         reg splitme /* verilator isolate_assignments*/;
+         // Note the placement of the semicolon above
+         always_comb begin
+           if (....) begin
+              splitme = ....;
+              other assignments
+           end
+         end
+
+   Verilator will internally split the block that assigns to "splitme" into
+   two blocks:
+
+   It would then internally break it into (sort of):
+
+   .. code-block:: sv
+
+         // All assignments excluding those to splitme
+         always_comb begin
+           if (....) begin
+              other assignments
+           end
+         end
+         // All assignments to splitme
+         always_comb begin
+           if (....) begin
+              splitme = ....;
+           end
+         end
+
+   Same as :option:`isolate_assignments` configuration file option.
+
+.. option:: /*verilator&32;lint_off <msg>*/
+
+   Disable the specified warning message for any warnings following the
+   comment.
+
+.. option:: /*verilator&32;lint_on <msg>*/
+
+   Re-enable the specified warning message for any warnings following the
+   comment.
+
+.. option:: /*verilator&32;lint_restore*/
+
+   After a :code:`/*verilator&32;lint_save*/`, pop the stack containing lint
+   message state.  Often this is useful at the bottom of include files.
+
+.. option:: /*verilator&32;lint_save*/
+
+   Push the current state of what lint messages are turned on or turned off
+   to a stack.  Later meta-comments may then lint_on or lint_off specific
+   messages, then return to the earlier message state by using
+   :code:`/*verilator&32;lint_restore*/`.  For example:
+
+   .. code-block:: sv
+
+         // verilator lint_save
+         // verilator lint_off WIDTH
+         ...  // code needing WIDTH turned off
+         // verilator lint_restore
+
+   If WIDTH was on before the lint_off, it will now be restored to on, and
+   if it was off before the lint_off it will remain off.
+
+.. option:: /*verilator&32;no_inline_module*/
+
+   Specifies the module the comment appears in should not be inlined into
+   any modules that use this module.
+
+   Same as :option:`no_inline` configuration file option.
+
+.. option:: /*verilator&32;no_inline_task*/
+
+   Used in a function or task variable definition section to specify the
+   function or task should not be inlined into where it is used.  This may
+   reduce the size of the final executable when a task is used a very large
+   number of times.  For this flag to work, the task and tasks below it
+   must be pure; they cannot reference any variables outside the task
+   itself.
+
+   Same as :option:`no_inline` configuration file option.
+
+.. option:: /*verilator&32;public*/ (on parameter)
+
+   Used after a parameter declaration to indicate the emitted C code should
+   have the parameter values visible. Due to C++ language restrictions,
+   this may only be used on 64-bit or narrower integral enumerations.
+
+   .. code-block:: sv
+
+         parameter [2:0] PARAM /*verilator public*/ = 2'b0;
+
+.. option:: /*verilator&32;public*/ (on typedef enum)
+
+   Used after an enum typedef declaration to indicate the emitted C code
+   should have the enum values visible. Due to C++ language restrictions,
+   this may only be used on 64-bit or narrower integral enumerations.
+
+   .. code-block:: sv
+
+         typedef enum logic [2:0] { ZERO = 3'b0 } pub_t /*verilator public*/;
+
+.. option:: /*verilator&32;public*/ (on variable)
+
+   Used after an input, output, register, or wire declaration to indicate
+   the signal should be declared so that C code may read or write the value
+   of the signal.  This will also declare this module public, otherwise use
+   :code:`/*verilator&32;public_flat*/`.
+
+   Instead of using public variables, consider instead making a DPI or
+   public function that accesses the variable.  This is nicer as it
+   provides an obvious entry point that is also compatible across
+   simulators.
+
+   Same as :option:`public` configuration file option.
+
+.. option:: /*verilator&32;public*/ (on task/function)
+
+   Used inside the declaration section of a function or task declaration to
+   indicate the function or task should be made into a C++ function, public
+   to outside callers.  Public tasks will be declared as a void C++
+   function, public functions will get the appropriate non-void (bool,
+   uint32_t, etc) return type.  Any input arguments will become C++
+   arguments to the function.  Any output arguments will become C++
+   reference arguments.  Any local registers/integers will become function
+   automatic variables on the stack.
+
+   Wide variables over 64 bits cannot be function returns, to avoid
+   exposing complexities.  However, wide variables can be input/outputs;
+   they will be passed as references to an array of 32-bit numbers.
+
+   Generally, only the values of stored state (flops) should be written, as
+   the model will NOT notice changes made to variables in these functions.
+   (Same as when a signal is declared public.)
+
+   You may want to use DPI exports instead, as it's compatible with other
+   simulators.
+
+   Same as :option:`public` configuration file option.
+
+.. option:: /*verilator&32;public_flat*/ (on variable)
+
+   Used after an input, output, register, or wire declaration to indicate
+   the signal should be declared so that C code may read or write the value
+   of the signal.  This will not declare this module public, which means
+   the name of the signal or path to it may change based upon the module
+   inlining which takes place.
+
+   Same as :option:`public_flat` configuration file option.
+
+.. option:: /*verilator&32;public_flat_rd*/ (on variable)
+
+   Used after an input, output, register, or wire declaration to indicate
+   the signal should be declared public_flat (see above), but read-only.
+
+   Same as :option:`public_flat_rd` configuration file option.
+
+.. option:: /*verilator&32;public_flat_rw @(<edge_list>)*/ (on variable)
+
+   Used after an input, output, register, or wire declaration to indicate
+   the signal should be declared public_flat_rd (see above), and also
+   writable, where writes should be considered to have the timing specified
+   by the given sensitivity edge list.  Set for all variables, ports and
+   wires using the :vlopt:`--public-flat-rw` option.
+
+   Same as :option:`public_flat_rw` configuration file option.
+
+.. option:: /*verilator&32;public_module*/
+
+   Used after a module statement to indicate the module should not be
+   inlined (unless specifically requested) so that C code may access the
+   module.  Verilator automatically sets this attribute when the module
+   contains any public signals or \`systemc_ directives.  Also set for all
+   modules when using the :vlopt:`--public` option.
+
+   Same as :option:`public` configuration file option.
+
+.. option:: /*verilator&32;sc_clock*/
+
+   Deprecated and ignored.  Previously used after an input declaration to
+   indicate the signal should be declared in SystemC as a sc_clock instead
+   of a bool.  This was needed in SystemC 1.1 and 1.2 only; versions 2.0
+   and later do not require clock pins to be sc_clocks and this is no
+   longer needed and is ignored.
+
+.. 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.
+   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
+   necessary as with increasing usage of sc_bv the performance decreases
+   significantly.
+
+   Same as :option:`sc_bv` configuration file option.
+
+.. option:: /*verilator&32;sformat*/
+
+   Attached to the final argument of type "input string" of a function or
+   task to indicate the function or task should pass all remaining
+   arguments through $sformatf.  This allows creation of DPI functions with
+   $display like behavior.  See the :file:`test_regress/t/t_dpi_display.v`
+   file for an example.
+
+   Same as :option:`sformat` configuration file option.
+
+.. option:: /*verilator&32;split_var*/
+
+   Attached to a variable or a net declaration to break the variable into
+   multiple pieces typically to resolve ``UNOPTFLAT`` performance issues.
+   Typically the variables to attach this to are recommended by Verilator
+   itself, see :option:`UNOPTFLAT`.
+
+   For example, Verilator will internally convert a variable with the
+   metacomment such as:
+
+   .. code-block:: sv
+
+         logic [7:0] x [0:1]  /*verilator split_var*/;
+
+   To:
+
+   .. code-block:: sv
+
+         logic [7:0] x__BRA__0__KET__ /*verilator split_var*/;
+         logic [7:0] x__BRA__1__KET__ /*verilator split_var*/;
+
+   Note that the generated packed variables retain the split_var
+   metacomment because they may be split into further smaller pieces
+   according to the access patterns.
+
+   This only supports unpacked arrays, packed arrays, and packed structs of
+   integer types (reg, logic, bit, byte, int...); otherwise if a split was
+   requested but cannot occur a SPLITVAR warning is issued.  Splitting
+   large arrays may slow down the Verilation speed, so use this only on
+   variables that require it.
+
+   Same as :option:`split_var` configuration file option.
+
+.. option:: /*verilator&32;tag <text...>*/
+
+   Attached after a variable or structure member to indicate opaque (to
+   Verilator) text that should be passed through to the XML output as a tag,
+   for use by downstream applications.
+
+.. option:: /*verilator&32;tracing_off*/
+
+   Disable waveform tracing for all future signals that are declared in
+   this module, or instances below this module.  Often this is placed just
+   after a primitive's module statement, so that the entire module and
+   instances below it are not traced.
+
+.. option:: /*verilator&32;tracing_on*/
+
+   Re-enable waveform tracing for all future signals or instances that are
+   declared.

docs/guide/faq.rst

@@ -0,0 +1,495 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+******************************
+FAQ/Frequently Asked Questions
+******************************
+
+.. Extra heading level here so sidebar index looks nice
+
+Questions
+=========
+
+Can I contribute?
+"""""""""""""""""
+
+Please contribute!  Just submit a pull request, or raise an issue to
+discuss if looking for something to help on.  For more information see our
+contributor agreement.
+
+
+How widely is Verilator used?
+"""""""""""""""""""""""""""""
+
+Verilator is used by many of the largest silicon design companies, large
+organizations such as CERN, and even by college student projects.
+
+Verilator is one of the "big 4" simulators, meaning one of the 4 main
+SystemVerilog simulators available, namely the closed-source products Synopsys
+VCS (tm), Mentor Questa/ModelSim (tm), Cadence
+Xcelium/Incisive/NC-Verilog/NC-Sim (tm), and the open-source Verilator.
+The three closed-source offerings are often collectively called the "big 3"
+simulators.
+
+
+Does Verilator run under Windows?
+"""""""""""""""""""""""""""""""""
+
+Yes, using Cygwin.  Verilated output also compiles under Microsoft Visual
+C++, but this is not tested every release.
+
+
+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
+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
+up?
+
+
+How can it be faster than (name-a-big-3-closed-source-simulator)?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Generally, the implied part of the question is "... with all of the
+manpower they can put into developing it."
+
+Most simulators have to be compliant with the complete IEEE 1364 (Verilog)
+and IEEE 1800 (SystemVerilog) standards, meaning they have to be event
+driven.  This prevents them from being able to reorder blocks and make
+netlist-style optimizations, which are where most of the gains come from.
+
+You should not be scared by non-compliance.  Your synthesis tool isn't
+compliant with the whole standard to start with, so your simulator need not
+be either.  Verilator is closer to the synthesis interpretation, so this is
+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.
+
+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!
+
+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.
+
+As is standard with Open Source, contributions back to Verilator will be
+placed under the Verilator copyright and LGPL/Artistic license.  Small test
+cases will be released into the public domain so they can be used anywhere,
+and large tests under the LGPL/Artistic, unless requested otherwise.
+
+
+Why is running Verilator (to create a model) so slow?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Verilator may require more memory than the resulting simulator will
+require, as Verilator internally creates all of the state of the resulting
+generated simulator in order to optimize it.  If it takes more than a few
+minutes or so (and you're not using :vlopt:`--debug` since debug mode is
+disk bound), see if your machine is paging; most likely you need to run it
+on a machine with more memory. Very large designs are known to have topped
+64 GB resident set size.  Alternatively, see :ref:`Hierarchical Verilation`.
+
+
+How do I generate waveforms (traces) in C++?
+""""""""""""""""""""""""""""""""""""""""""""
+
+See also the next question for tracing in SystemC mode.
+
+A. Pass the :vlopt:`--trace` option to Verilator, and in your top level C
+   code, call ``Verilated::traceEverOn(true)``.  Then you may use
+   ``$dumpfile`` and ``$dumpvars`` to enable traces, same as with any
+   Verilog simulator. See ``examples/make_tracing_c`` in the distribution.
+
+B. Or, for finer-grained control, or C++ files with multiple Verilated
+   modules you may also create the trace purely from C++.  Create a
+   VerilatedVcdC object, and in your main loop call
+   ``trace_object->dump(time)`` every time step, and finally call
+   ``trace_object->close()``.
+
+   .. code-block:: C++
+      :emphasize-lines: 1,5-8,12
+
+      #include "verilated_vcd_c.h"
+      ...
+      int main(int argc, char** argv, char** env) {
+          ...
+          Verilated::traceEverOn(true);
+          VerilatedVcdC* tfp = new VerilatedVcdC;
+          topp->trace(tfp, 99);  // Trace 99 levels of hierarchy
+          tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
+          ...
+          while (Verilated::time() < sim_time && !Verilated::gotFinish()) {
+              Verilated::timeInc(1);
+              tfp->dump(main_time);
+          }
+          tfp->close();
+      }
+
+You also need to compile :file:`verilated_vcd_c.cpp` and add it to your
+link, preferably by adding the dependencies in your Makefile's
+:code:`$(VK_GLOBAL_OBJS)` link rule.  This is done for you if using the
+Verilator :vlopt:`--exe` option.
+
+you can call :code:`trace_object->trace()` on multiple Verilated objects
+with the same trace file if you want all data to land in the same output
+file.
+
+
+How do I generate waveforms (traces) in SystemC?
+""""""""""""""""""""""""""""""""""""""""""""""""
+
+A. Pass the :vlopt:`--trace` option to Verilator, and in your top level
+   :code:`sc_main()`, call :code:`Verilated::traceEverOn(true)`.  Then you
+   may use :code:`$dumpfile` and code:`$dumpvars` to enable traces, same as
+   with any Verilog simulator, see the non-SystemC example in
+   :file:`examples/make_tracing_c`. This will trace only the module
+   containing the :code:`$dumpvar`.
+
+B. Or, you may create a trace purely from SystemC, which may trace all
+   Verilated designs in the SystemC model. Create a VerilatedVcdSc object
+   as you would create a normal SystemC trace file.  For an example, see
+   the call to ``VerilatedVcdSc`` in the
+   :file:`examples/make_tracing_sc/sc_main.cpp` file of the distribution,
+   and below.
+
+C. Alternatively you may use the C++ trace mechanism described in the
+   previous question, note the timescale and timeprecision will be
+   inherited from your SystemC settings.
+
+   .. code-block:: C++
+      :emphasize-lines: 1,5-8
+
+      #include "verilated_vcd_sc.h"
+      ...
+      int main(int argc, char** argv, char** env) {
+          ...
+          Verilated::traceEverOn(true);
+          VerilatedVcdSc* tfp = new VerilatedVcdSc;
+          topp->trace(tfp, 99);  // Trace 99 levels of hierarchy
+          tfp->open("obj_dir/t_trace_ena_cc/simx.vcd");
+          ...
+          sc_start(1);
+          ...
+          tfp->close();
+      }
+
+
+
+You also need to compile :file:`verilated_vcd_sc.cpp` and
+:file:`verilated_vcd_c.cpp` and add them to your link, preferably by adding
+the dependencies in your Makefile's :code:`$(VK_GLOBAL_OBJS)` link rule.
+This is done for you if using the Verilator :vlopt:`--exe` option.
+
+You can call :code:`->trace()` on multiple Verilated objects with the same
+trace file if you want all data to land in the same output file.
+
+When using SystemC 2.3, the SystemC library must have been built with the
+experimental simulation phase callback based tracing disabled. This is
+disabled by default when building SystemC with its configure based build
+system, but when building SystemC with CMake, you must pass
+``-DENABLE_PHASE_CALLBACKS_TRACING=OFF`` to disable this feature.
+
+
+How do I generate FST waveforms (traces) in C++ or SystemC?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+FST is a trace file format developed by GTKWave.  Verilator provides basic
+FST support.  To dump traces in FST format, add the :vlopt:`--trace-fst`
+option to Verilator and either A. use :code:`$dumpfile & $dumpvars` in
+Verilog as described in the VCD example above,
+
+Or, in C++ change the include described in the VCD example above:
+
+.. code-block:: C++
+
+      #include "verilated_fst_c.h"
+      VerilatedFstC* tfp = new VerilatedFstC;
+
+
+Or, in SystemC change the include described in the VCD example above:
+
+.. code-block:: C++
+
+      #include "verilated_fst_sc.h"
+      VerilatedFstC* tfp = new VerilatedFstSc;
+
+
+Note that currently supporting both FST and VCD in a single simulation is
+impossible, but such requirement should be rare.  You can however ifdef
+around the trace format in your C++ main loop, and select VCD or FST at
+build time, should you require.
+
+
+How do I view waveforms (aka dumps or traces)?
+""""""""""""""""""""""""""""""""""""""""""""""
+
+Verilator creates standard VCD (Value Change Dump) and FST files.  VCD
+files are viewable with the open source GTKWave (recommended) or Dinotrace
+(legacy) programs, or any of the many closed-source offerings; FST is
+supported only by GTKWave.
+
+
+How do I speed up writing large waveform (trace) files?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+A. Instead of calling ``VerilatedVcdC->open`` or ``$dumpvars`` at the
+   beginning of time, delay calling it until the time stamp where you want
+   tracing to begin.
+
+B. Add the :option:`/*verilator&32;tracing_off*/` metacomment to any very
+   low level modules you never want to trace (such as perhaps library
+   cells).
+
+C. Use the :vlopt:`--trace-depth` option to limit the depth of tracing, for
+   example :vlopt:`--trace-depth 1 <--trace-depth>` to see only the top
+   level signals.
+
+D. You can also consider using FST tracing instead of VCD. FST dumps are a
+   fraction of the size of the equivalent VCD. FST tracing can be slower
+   than VCD tracing, but it might be the only option if the VCD file size
+   is prohibitively large.
+
+E. Be sure you write your trace files to a local solid-state drive, instead
+   of to a network drive.  Network drives are generally far slower.
+
+
+Where is the translate_off command?  (How do I ignore a construct?)
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Translate on/off pragmas are generally a bad idea, as it's easy to have
+mismatched pairs, and you can't see what another tool sees by just
+preprocessing the code.  Instead, use the preprocessor; Verilator defines
+the ``\`VERILATOR`` define for you, so just wrap the code in an ifndef
+region:
+
+ .. code-block:: sv
+    :emphasize-lines: 1
+
+    `ifndef VERILATOR
+       Something_Verilator_Dislikes;
+    `endif
+
+Most synthesis tools similarly define SYNTHESIS for you.
+
+
+Why do I get "unexpected 'do'" or "unexpected 'bit'" errors?
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+The words \ ``do``\ , \ ``bit``\ , \ ``ref``\ , \ ``return``\ , and others
+are reserved keywords in SystemVerilog.  Older Verilog code might use these
+as identifiers.  You should change your code to not use them to ensure it
+works with newer tools.  Alternatively, surround them by the Verilog
+2005/SystemVerilog begin_keywords pragma to indicate Verilog 2001 code.
+
+.. code-block:: sv
+   :emphasize-lines: 1
+
+   `begin_keywords "1364-2001"
+      integer bit; initial bit = 1;
+   `end_keywords
+
+
+If you want the whole design to be parsed as Verilog 2001, see the
+:vlopt:`--default-language` option.
+
+
+How do I prevent my assertions from firing during reset?
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Call :code:`Verilated::assertOn(false)` before you first call the model,
+then turn it back on after reset.  It defaults to true.  When false, all
+assertions controlled by :vlopt:`--assert` are disabled.
+
+
+Why do I get "undefined reference to sc_time_stamp()?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+In Verilator 4.200 and later, using the timeInc function is recommended
+instead.  See the :ref:`Connecting to C++` examples.  Some linkers (MSVC++)
+still require :code:`sc_time_stamp()` to be defined, either define this
+with :code:`double sc_time_stamp() { return 0; }` or compile the Verilated
+code with :code:`-CFLAGS -DVL_TIME_CONTEXT`.
+
+Prior to Verilator 4.200, the :code:`sc_time_stamp()` function needs to be
+defined in C++ (non SystemC) to return the current simulation time.
+
+
+Why do I get "undefined reference to \`VL_RAND_RESET_I' or \`Verilated::...'"?
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+You need to link your compiled Verilated code against the
+:code:`verilated.cpp` file found in the include directory of the Verilator
+kit.  This is one target in the ``$(VK_GLOBAL_OBJS)`` make variable, which
+should be part of your Makefile's link rule.  If you use :vlopt:`--exe`,
+this is done for you.
+
+
+Is the PLI supported?
+"""""""""""""""""""""
+
+Only somewhat.  More specifically, the common PLI-ish calls $display,
+$finish, $stop, $time, $write are converted to C++ equivalents.  You can
+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
+$c("{any_c++_statement}").
+
+See the :ref:`Connecting` section.
+
+
+How do I make a Verilog module that contain a C++ object?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+You need to add the object to the structure that Verilator creates, then
+use $c to call a method inside your object.  The
+:file:`test_regress/t/t_extend_class` files in the distribution show an
+example of how to do this.
+
+
+How do I get faster build times?
+""""""""""""""""""""""""""""""""
+
+* When running make, pass the make variable VM_PARALLEL_BUILDS=1 so that
+  builds occur in parallel. Note this is now set by default if an output
+  file was large enough to be split due to the :vlopt:`--output-split`
+  option.
+
+* Verilator emits any infrequently executed "cold" routines into separate
+  __Slow.cpp files. This can accelerate compilation as optimization can be
+  disabled on these routines. See the OPT_FAST and OPT_SLOW make variables
+  and :ref:`Benchmarking & Optimization`.
+
+* Use a recent compiler.  Newer compilers tend to be faster.
+
+* Compile in parallel on many machines and use caching; see the web for the
+  ccache, distcc and icecream packages. ccache will skip GCC runs between
+  identical source builds, even across different users.  If ccache was
+  installed when Verilator was built it is used, or see OBJCACHE
+  environment variable to override this. Also see the
+  :vlopt:`--output-split` option.
+
+* To reduce the compile time of classes that use a Verilated module (e.g. a
+  top CPP file) you may wish to add a
+  :option:`/*verilator&32;no_inline_module*/` metacomment to your top level
+  module. This will decrease the amount of code in the model's Verilated
+  class, improving compile times of any instantiating top level C++ code,
+  at a relatively small cost of execution performance.
+
+* Use :ref:`hierarchical verilation`.
+
+
+Why do so many files need to recompile when I add a signal?
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+Adding a new signal requires the symbol table to be recompiled.  Verilator
+uses one large symbol table, as that results in 2-3 less assembly
+instructions for each signal access.  This makes the execution time 10-15%
+faster, but can result in more compilations when something changes.
+
+
+How do I access Verilog functions/tasks in C?
+"""""""""""""""""""""""""""""""""""""""""""""
+
+Use the SystemVerilog Direct Programming Interface.  You write a Verilog
+function or task with input/outputs that match what you want to call in
+with C.  Then mark that function as a DPI export function.  See the DPI
+chapter in the IEEE Standard.
+
+
+How do I access C++ functions/tasks in Verilog?
+"""""""""""""""""""""""""""""""""""""""""""""""
+
+Use the SystemVerilog Direct Programming Interface.  You write a Verilog
+function or task with input/outputs that match what you want to call in
+with C.  Then mark that function as a DPI import function.  See the DPI
+chapter in the IEEE Standard.
+
+
+How do I access signals in C?
+"""""""""""""""""""""""""""""
+
+The best thing to do is to make a SystemVerilog "export DPI" task or
+function that accesses that signal, as described in the DPI chapter in the
+manual and DPI tutorials on the web.  This will allow Verilator to better
+optimize the model and should be portable across simulators.
+
+If you really want raw access to the signals, declare the signals you will
+be accessing with a :option:`/*verilator&32;public*/` metacomment before
+the closing semicolon.  Then scope into the C++ class to read the value of
+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
+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.
+
+Signals wider than 64 bits are stored as an array of 32-bit uint32_t's.
+Thus to read bits 31:0, access signal[0], and for bits 63:32, access
+signal[1].  Unused bits (for example bit numbers 65-96 of a 65-bit vector)
+will always be zero.  If you change the value you must make sure to pack
+zeros in the unused bits or core-dumps may result, because Verilator strips
+array bound checks where it believes them to be unnecessary to improve
+performance.
+
+In the SYSTEMC example above, if you had in our.v:
+
+ .. code-block:: sv
+
+      input clk /*verilator public*/;
+      // Note the placement of the semicolon above
+
+From the sc_main.cpp file, you'd then:
+
+ .. code-block:: C++
+
+      #include "Vour.h"
+      #include "Vour_our.h"
+      cout << "clock is " << top->our->clk << endl;
+
+
+In this example, clk is a bool you can read or set as any other variable.
+The value of normal signals may be set, though clocks shouldn't be changed
+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
+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
+SystemC or Verilog.  Then:
+
+* A module with only SystemC instances below must be SystemC.
+
+* A module with a mix of Verilog and SystemC instances below must be
+  SystemC. (As Verilator cannot connect to lower-level SystemC instances.)
+
+* A module with only Verilog instances below can be either, but for best
+  performance should be Verilog.  (The exception is if you have a design
+  that is instantiated many times; in this case Verilating one of the lower
+  modules and instantiating that Verilated instances multiple times into a
+  SystemC module *may* be faster.)

docs/guide/files.rst

@@ -0,0 +1,141 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+*****
+Files
+*****
+
+.. _Files in the Distribution:
+
+Files in the Git Tree
+=====================
+
+The following is a summary of the files in the Git Tree (distribution) of
+Verilator:
+
+::
+
+   Changes                     => Version history
+   README.rst                  => This document
+   bin/verilator               => Compiler wrapper invoked to Verilate code
+   docs/                       => Additional documentation
+   examples/                   => Examples (see manual for descriptions)
+   include/                    => Files that should be in your -I compiler path
+   include/verilated*.cpp      => Global routines to link into your simulator
+   include/verilated*.h        => Global headers
+   include/verilated.mk        => Common Makefile
+   src/                        => Translator source code
+   test_regress                => Internal tests
+
+
+.. _Files Read/Written:
+
+Files Read/Written
+==================
+
+All output files are placed in the output directory specified with the
+:vlopt:`--Mdir` option, or "obj_dir" if not specified.
+
+Verilator creates the following files in the output directory:
+
+For --cc/--sc, it creates:
+
+.. list-table::
+
+   * - *{prefix}*\ .cmake
+     - CMake include script for compiling (from --make cmake)
+   * - *{prefix}*\ .mk
+     - Make include file for compiling (from --make gmake)
+   * - *{prefix}*\ _classes.mk
+     - Make include file with class names (from --make gmake)
+   * - *{prefix}*\ _hier.mk
+     - Make file for hierarchy blocks (from --make gmake)
+   * - *{prefix|*\ _hierMkArgs.f
+     - Arguments for hierarchical Verilation (from --make gmake)
+   * - *{prefix}*\ _hierCMakeArgs.f
+     - Arguments for hierarchical Verilation (from --make cmake)
+   * - *{prefix}*\ .cpp
+     - Top level C++ file
+   * - *{prefix}{__n}*\ .cpp
+     - Additional top C++ files (from --output-split)
+   * - *{prefix}*\ .h
+     - Top level header
+   * - *{prefix}*\ __Slow\ *{__n}*\ .cpp
+     - Infrequent cold routines
+   * - *{prefix}*\ __Dpi.cpp
+     - DPI import and export wrappers (from --dpi)
+   * - *{prefix}*\ __Dpi.h
+     - DPI import and export declarations (from --dpi)
+   * - *{prefix}*\ __Inlines.h
+     - Inline support functions
+   * - *{prefix}*\ __Syms.cpp
+     - Global symbol table C++
+   * - *{prefix}*\ __Syms.h
+     - Global symbol table header
+   * - *{prefix}*\ __Trace{__n}*\ .cpp
+     - Wave file generation code (from --trace)
+   * - *{prefix}*\ __Trace__Slow{__n}*\ .cpp
+     - Wave file generation code (from --trace)
+   * - *{prefix}{each_verilog_module}*\ .cpp
+     - Lower level internal C++ files
+   * - *{prefix}{each_verilog_module}*\ .h
+     - Lower level internal header files
+   * - *{prefix}{each_verilog_module}{__n}*\ .cpp
+     - Additional lower C++ files (from --output-split)
+
+For --hierarchy mode, it creates:
+
+.. list-table::
+
+   * - V\ *{hier_block}*\ /
+     - Directory to Verilate each hierarchy block (from --hierarchy)
+   * - *{prefix}*\ __hierVer.d
+     - Make dependencies of the top module (from --hierarchy)
+   * - *{prefix}*\ __hier.dir
+     - Directory to store .dot, .vpp, .tree of top module (from --hierarchy)
+
+In certain debug and other modes, it also creates:
+
+.. list-table::
+
+   * - *{prefix}*\ .xml
+     - XML tree information (from --xml)
+   * - *{prefix}*\ __cdc.txt
+     - Clock Domain Crossing checks (from --cdc)
+   * - *{prefix}*\ __stats.txt
+     - Statistics (from --stats)
+   * - *{prefix}*\ __idmap.txt
+     - Symbol demangling (from --protect-ids)
+   * - *{prefix}*\ __ver.d
+     - Make dependencies (from -MMD)
+   * - *{prefix}*\ __verFiles.dat
+     - Timestamps (from --skip-identical)
+   * - *{prefix}{misc}*\ .dot
+     - Debugging graph files (from --debug)
+   * - *{prefix}{misc}*\ .tree
+     - Debugging files (from --debug)
+   * - {mod_prefix}_{each_verilog_module}*{__n}*\ .vpp
+     - Pre-processed verilog (from --debug)
+
+After running Make, the C++ compiler may produce the following:
+
+.. list-table::
+
+   * - verilated{misc}*\ .d
+     - Intermediate dependencies
+   * - verilated{misc}*\ .o
+     - Intermediate objects
+   * - {mod_prefix}{misc}*\ .d
+     - Intermediate dependencies
+   * - {mod_prefix}{misc}*\ .o
+     - Intermediate objects
+   * - *{prefix}*\
+     - Final executable (from --exe)
+   * - *{prefix}*\ __ALL.a
+     - Library of all Verilated objects
+   * - *{prefix}*\ __ALL.cpp
+     - Include of all code for single compile
+   * - *{prefix}{misc}*\ .d
+     - Intermediate dependencies
+   * - *{prefix}{misc}*\ .o
+     - Intermediate objects

docs/guide/index.rst

@@ -0,0 +1,41 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+######################
+Verilator User's Guide
+######################
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Getting Started
+
+   overview.rst
+   examples.rst
+   install.rst
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User's Guide
+
+   verilating.rst
+   connecting.rst
+   simulating.rst
+   contributing.rst
+   faq.rst
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference Guide
+
+   languages.rst
+   extensions.rst
+   executables.rst
+   warnings.rst
+   files.rst
+   environment.rst
+   deprecations.rst
+   contributors.rst
+   changes.rst
+   copyright.rst

docs/guide/install.rst

@@ -0,0 +1,321 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Installation:
+
+************
+Installation
+************
+
+This section discusses how to install Verilator.
+
+.. _Package Manager Quick Install:
+
+Package Manager Quick Install
+=============================
+
+Using a distribution's package manager is the easiest way to get
+started. (Note packages are unlikely to have the most recent version, so
+:ref:`Git Install`, might be a better alternative.) To install as a
+package:
+
+::
+
+   apt-get install verilator   # On Ubuntu
+
+
+.. _Git Install:
+
+Git Quick Install
+=================
+
+Installing Verilator from Git provides the most flexibility. For additional
+options and details see :ref:`Detailed Build Instructions` below.
+
+In brief, to install from git:
+
+::
+
+   # Prerequisites:
+   #sudo apt-get install git perl python3 make autoconf g++ flex bison ccache
+   #sudo apt-get install libgoogle-perftools-dev numactl perl-doc
+   #sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
+   #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)
+
+   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 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
+   sudo make install
+
+
+.. _Detailed Build Instructions:
+
+Detailed Build Instructions
+===========================
+
+This section describes details of the build process, and assumes you are
+building from Git. For using a pre-built binary for your Linux
+distribution, see instead :ref:`Package Manager Quick Install`.
+
+
+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++.
+
+
+Install Prerequisites
+---------------------
+
+To build or run Verilator you need these standard packages:
+
+::
+
+   sudo apt-get install git perl python3 make
+   sudo apt-get install g++  # Alternatively, clang
+   sudo apt-get install libgz  # Non-Ubuntu (ignore if gives error)
+   sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
+   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:
+
+::
+
+   sudo apt-get install ccache  # If present at build, needed for run
+   sudo apt-get install libgoogle-perftools-dev numactl perl-doc
+
+To build Verilator you will need to install these packages; these do not
+need to be present to run Verilator:
+
+::
+
+   sudo apt-get install git autoconf flex bison
+
+Those developing Verilator itself may also want these (see internals.rst):
+
+::
+
+   sudo apt-get install gdb graphviz cmake clang clang-format gprof lcov
+   sudo pip3 install sphinx sphinx_rtd_theme breathe
+   cpan install Pod::Perldoc
+   cpan install Parallel::Forker
+
+
+Install SystemC
+^^^^^^^^^^^^^^^
+
+If you will be using SystemC (vs straight C++ output), download `SystemC
+<https://www.accellera.org/downloads/standards/systemc>`__.  Follow their
+installation instructions. You will need to set the
+:option:`SYSTEMC_INCLUDE` environment variable to point to the include
+directory with ``systemc.h`` in it, and set the :option:`SYSTEMC_LIBDIR`
+environment variable to point to the directory with ``libsystemc.a`` in it.
+
+
+Install GTKWave
+^^^^^^^^^^^^^^^
+
+To make use of Verilator FST tracing you will want `GTKwave
+<http://gtkwave.sourceforge.net/>`__ installed, however this is not
+required at Verilator build time.
+
+
+Obtain Sources
+--------------
+
+Get the sources from the git repository: (You need do this only once,
+ever.)
+
+::
+
+   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
+
+Enter the checkout and determine what version/branch to use:
+
+::
+
+   cd verilator
+   git pull        # Make sure we're up-to-date
+   git tag         # See what versions exist
+   #git checkout master      # Use development branch (e.g. recent bug fix)
+   #git checkout stable      # Use most recent release
+   #git checkout v{version}  # Switch to specified release version
+
+
+Auto Configure
+--------------
+
+Create the configuration script:
+
+::
+
+   autoconf        # Create ./configure script
+
+
+Eventual Installation Options
+-----------------------------
+
+Before configuring the build, you have to decide how you're going to
+eventually install Verilator onto your system. Verilator will be compiling
+the current value of the environment variables :option:`VERILATOR_ROOT`,
+:option:`SYSTEMC_INCLUDE`, and :option:`SYSTEMC_LIBDIR` as defaults into
+the executable, so they must be correct before configuring.
+
+These are the installation options:
+
+
+1. Run-in-Place from VERILATOR_ROOT
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Our personal favorite is to always run Verilator in-place from its Git
+directory. This allows the easiest experimentation and upgrading, and
+allows many versions of Verilator to co-exist on a system.
+
+::
+
+   export VERILATOR_ROOT=`pwd`   # if your shell is bash
+   setenv VERILATOR_ROOT `pwd`   # if your shell is csh
+   ./configure
+   # Running will use files from $VERILATOR_ROOT, so no install needed
+
+Note after installing (below steps), a calling program or shell must set
+the environment variable :option:`VERILATOR_ROOT` to point to this Git
+directory, then execute ``$VERILATOR_ROOT/bin/verilator``, which will find
+the path to all needed files.
+
+
+2. Install into a specific location
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may eventually be installing onto a project/company-wide "CAD" tools
+disk that may support multiple versions of every tool. Tell configure the
+eventual destination directory name.  We recommend the destination location
+include the Verilator version name:
+
+::
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   # For the tarball, use the version number instead of git describe
+   ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`
+
+Note after installing (below steps), if you use `modulecmd
+<http://modules.sourceforge.net/>`__, you'll want a module file like the
+following:
+
+::
+
+   set install_root /CAD_DISK/verilator/{version-number-used-above}
+   unsetenv VERILATOR_ROOT
+   prepend-path PATH $install_root/bin
+   prepend-path MANPATH $install_root/man
+   prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
+
+
+3. Install into a Specific Path
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You may eventually install Verilator into a specific installation prefix,
+as most GNU tools support:
+
+::
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   ./configure --prefix /opt/verilator-VERSION
+
+Then after installing (below steps) you will need to add
+``/opt/verilator-VERSION/bin`` to your ``$PATH`` environment variable.
+
+
+4. Install System Globally
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The final option is to eventually install Verilator globally, using
+configure's default system paths:
+
+::
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   ./configure
+
+Then after installing (below) the binaries should be in a location that is
+already in your ``$PATH`` environment variable.
+
+
+Configure
+---------
+
+The command to configure the package was described in the previous step.
+Developers should configure to have more complete developer tests.
+Additional packages may be required for these tests.
+
+::
+
+   export VERILATOR_AUTHOR_SITE=1    # Put in your .bashrc
+   ./configure --enable-longtests  ...above options...
+
+
+Compile
+-------
+
+Compile Verilator:
+
+::
+
+   make -j
+
+
+Test
+----
+
+Check the compilation by running self-tests:
+
+::
+
+   make test
+
+
+Install
+-------
+
+If you used any install option other than the `1. Run-in-Place from
+VERILATOR_ROOT <#_1_run_in_place_from_verilator_root>`__ scheme, install
+the files:
+
+::
+
+   make install
+
+
+.. Docker Build Environment
+
+.. include:: ../../ci/docker/buildenv/README.rst
+
+
+.. Docker Run Environment
+
+.. include:: ../../ci/docker/run/README.rst

docs/guide/languages.rst

@@ -0,0 +1,477 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+***************
+Input Languages
+***************
+
+This section describes the languages Verilator takes as input.  See also
+:ref:`Configuration Files`.
+
+
+Language Standard Support
+=========================
+
+Verilog 2001 (IEEE 1364-2001) Support
+-------------------------------------
+
+Verilator supports most Verilog 2001 language features.  This includes
+signed numbers, "always @\*", generate statements, multidimensional arrays,
+localparam, and C-style declarations inside port lists.
+
+
+Verilog 2005 (IEEE 1364-2005) Support
+-------------------------------------
+
+Verilator supports most Verilog 2005 language features.  This includes the
+\`begin_keywords and \`end_keywords compiler directives, $clog2, and the
+uwire keyword.
+
+
+SystemVerilog 2005 (IEEE 1800-2005) Support
+-------------------------------------------
+
+Verilator supports ==? and !=? operators, ++ and -- in some contexts,
+$bits, $countbits, $countones, $error, $fatal, $info, $isunknown, $onehot,
+$onehot0, $unit, $warning, always_comb, always_ff, always_latch, bit, byte,
+chandle, const, do-while, enum, export, final, import, int, interface,
+logic, longint, modport, package, program, shortint, struct, time, typedef,
+union, var, void, priority case/if, and unique case/if.
+
+It also supports .name and .\* interconnection.
+
+Verilator partially supports concurrent assert and cover statements; see
+the enclosed coverage tests for the syntax which is allowed.
+
+Verilator has limited support for class and related object-oriented
+constructs.
+
+
+SystemVerilog 2012 (IEEE 1800-2012) Support
+-------------------------------------------
+
+Verilator implements a full SystemVerilog-compliant preprocessor, including
+function call-like preprocessor defines, default define arguments,
+\`__FILE__, \`__LINE__ and \`undefineall.
+
+
+SystemVerilog 2017 (IEEE 1800-2017) Support
+-------------------------------------------
+
+Verilator supports the 2017 "for" loop constructs, and several minor
+cleanups IEEE made in 1800-2017.
+
+
+Verilog AMS Support
+-------------------
+
+Verilator implements a very small subset of Verilog AMS (Verilog Analog and
+Mixed-Signal Extensions) with the subset corresponding to those VMS
+keywords with near equivalents in the Verilog 2005 or SystemVerilog 2009
+languages.
+
+AMS parsing is enabled with :vlopt:`--language VAMS <--language>` or
+:vlopt:`--language 1800+VAMS <--language>`.
+
+At present Verilator implements ceil, exp, floor, ln, log, pow, sqrt,
+string, and wreal.
+
+
+Synthesis Directive Assertion Support
+-------------------------------------
+
+With the :vlopt:`--assert` option, Verilator reads any :code:`//synopsys
+full_case` or :code:`//synopsys parallel_case` directives.  The same
+applies to any :code:`//ambit synthesis`, :code:`//cadence` or
+:code:`//pragma` directives of the same form.
+
+When these synthesis directives are discovered, Verilator will either
+formally prove the directive to be true, or failing that, will insert the
+appropriate code to detect failing cases at simulation runtime and print an
+"Assertion failed" error message.
+
+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.
+
+
+.. _Language Limitations:
+
+Language Limitations
+====================
+
+This section describes the language limitations of Verilator. Many of these
+restrictions are by intent.
+
+Synthesis Subset
+----------------
+
+Verilator supports the Synthesis subset with other verification constructs
+being added over time. Verilator also simulates events as Synopsys's Design
+Compiler would; namely given a block of the form:
+
+.. code-block:: sv
+
+        always @(x) y = x & z;
+
+This will recompute y when there is even a potential for change in x or a
+change in z, that is when the flops computing x or z evaluate (which is
+what Design Compiler will synthesize.)  A compliant simulator would only
+calculate y if x changes.  We recommend using always_comb to make the code
+run the same everywhere.  Also avoid putting $displays in combo blocks, as
+they may print multiple times when not desired, even on compliant
+simulators as event ordering is not specified.
+
+
+Signal Naming
+-------------
+
+To avoid conflicts with C symbol naming, any character in a signal name
+that is not alphanumeric nor a single underscore will be replaced by __0hh
+where hh is the hex code of the character. To avoid conflicts with
+Verilator's internal symbols, any double underscore are replaced with
+___05F (5F is the hex code of an underscore.)
+
+
+Bind
+----
+
+sVerilator only supports bind to a target module name, not to an
+instance path.
+
+
+Class
+-----
+
+Verilator class support is limited but in active development.  Verilator
+supports members, and methods. Verilator does not support class static
+members, class extend, or class parameters.
+
+
+Dotted cross-hierarchy references
+---------------------------------
+
+Verilator supports dotted references to variables, functions and tasks in
+different modules. The portion before the dot must have a constant value;
+for example a[2].b is acceptable, while a[x].b is generally not.
+
+References into generated and arrayed instances use the instance names
+specified in the Verilog standard; arrayed instances are named
+``{instanceName}[{instanceNumber}]`` in Verilog, which becomes
+``{instanceName}__BRA__{instanceNumber}__KET__`` inside the generated C++
+code.
+
+
+Latches
+-------
+
+Verilator is optimized for edge sensitive (flop based) designs.  It will
+attempt to do the correct thing for latches, but most performance
+optimizations will be disabled around the latch.
+
+
+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
+unsupported.
+
+
+Time
+----
+
+All delays (#) are ignored, as they are in synthesis.
+
+
+.. _Unknown States:
+
+Unknown States
+--------------
+
+Verilator is mostly a two state simulator, not a four state simulator.
+However, it has two features which uncover most initialization bugs
+(including many that a four state simulator will miss.)
+
+Identity comparisons (=== or !==) are converted to standard ==/!= when
+neither side is a constant.  This may make the expression yield a different
+result compared to a four state simulator.  An === comparison to X will
+always be false, so that Verilog code which checks for uninitialized logic
+will not fire.
+
+Assigning X to a variable will actually assign a constant value as
+determined by the :vlopt:`--x-assign` option.  This allows runtime
+randomization, thus if the value is actually used, the random value should
+cause downstream errors.  Integers also get randomized, even though the
+Verilog 2001 specification says they initialize to zero.  Note however that
+randomization happens at initialization time and hence during a single
+simulation run, the same constant (but random) value will be used every
+time the assignment is executed.
+
+All variables, depending on :vlopt:`--x-initial` setting, are typically
+randomly initialized using a function.  By running several random
+simulation runs you can determine that reset is working correctly.  On the
+first run, have the function initialize variables to zero.  On the second,
+have it initialize variables to one.  On the third and following runs have
+it initialize them randomly.  If the results match, reset works.  (Note
+this is what the hardware will really do.)  In practice, just setting all
+variables to one at startup finds most problems (since typically control
+signals are active-high).
+
+:vlopt:`--x-assign` applies to variables explicitly initialized or assigned
+an X. Uninitialized clocks are initialized to zero, while all other state
+holding variables are initialized to a random value.  Event driven
+simulators will generally trigger an edge on a transition from X to 1
+(posedge) or X to 0 (negedge). However, by default, since clocks are
+initialized to zero, Verilator will not trigger an initial negedge. Some
+code (particularly for reset) may rely on X->0 triggering an edge. The
+:vlopt:`--x-initial-edge` option enables this behavior. Comparing runs with
+and without this option will find such problems.
+
+
+Tri/Inout
+---------
+
+Verilator converts some simple tristate structures into two state.  Pullup,
+pulldown, bufif0, bufif1, notif0, notif1, pmos, nmos, tri0 and tri1 are
+also supported.  Simple comparisons with :code:`=== 1'bz` are also
+supported.
+
+An assignment of the form:
+
+.. code-block:: sv
+
+        inout driver;
+        wire driver = (enable) ? output_value : 1'bz;
+
+Will be converted to:
+
+.. code-block:: sv
+
+        input driver;       // Value being driven in from "external" drivers
+        output driver__en;  // True if driven from this module
+        output driver__out; // Value being driven from this module
+
+External logic will be needed to combine these signals with any external
+drivers.
+
+Tristate drivers are not supported inside functions and tasks; an inout
+there will be considered a two state variable that is read and written
+instead of a four state variable.
+
+
+Functions & Tasks
+-----------------
+
+All functions and tasks will be inlined (will not become functions in C.)
+The only support provided is for simple statements in tasks (which may
+affect global variables).
+
+Recursive functions and tasks are not supported.  All inputs and outputs
+are automatic, as if they had the Verilog 2001 "automatic" keyword
+prepended.  (If you don't know what this means, Verilator will do what you
+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
+---------------
+
+The 2-state gate primitives (and, buf, nand, nor, not, or, xnor, xor) are
+directly converted to behavioral equivalents.  The 3-state and MOS gate
+primitives are not supported.  Tables are not supported.
+
+
+Specify blocks
+--------------
+
+All specify blocks and timing checks are ignored. All min:typ:max delays
+use the typical value.
+
+
+Array Initialization
+--------------------
+
+When initializing a large array, you need to use non-delayed assignments.
+Verilator will tell you when this needs to be fixed; see the BLKLOOPINIT
+error for more information.
+
+
+Array Out of Bounds
+-------------------
+
+Writing a memory element that is outside the bounds specified for the array
+may cause a different memory element inside the array to be written
+instead.  For power-of-2 sized arrays, Verilator will give a width warning
+and the address.  For non-power-of-2-sizes arrays, index 0 will be written.
+
+Reading a memory element that is outside the bounds specified for the array
+will give a width warning and wrap around the power-of-2 size.  For
+non-power-of-2 sizes, it will return a unspecified constant of the
+appropriate width.
+
+
+Assertions
+----------
+
+Verilator is beginning to add support for assertions.  Verilator currently
+only converts assertions to simple :code:`if (...) error` statements, and
+coverage statements to increment the line counters described in the
+coverage section.
+
+Verilator does not support SEREs yet.  All assertion and coverage
+statements must be simple expressions that complete in one cycle.
+
+
+Encrypted Verilog
+-----------------
+
+Open source simulators like Verilator are unable to use encrypted RTL
+(i.e. IEEE P1735).  Talk to your IP vendor about delivering IP blocks via
+Verilator's :vlopt:`--protect-lib` feature.
+
+
+Language Keyword Limitations
+============================
+
+This section describes specific limitations for each language keyword.
+
+.. Hack to get long definition list:
+.. |cmdslong1| replace:: \`__FILE__, \`__LINE__, \`begin_keywords,
+   \`begin_keywords, \`begin_keywords, \`begin_keywords, \`begin_keywords,
+   \`define, \`else, \`elsif, \`end_keywords, \`endif, \`error, \`ifdef,
+   \`ifndef, \`include, \`line, \`systemc_ctor, \`systemc_dtor,
+   \`systemc_header, \`systemc_imp_header, \`systemc_implementation,
+   \`systemc_interface, \`undef, \`verilog
+
+|cmdslong1|
+  Fully supported.
+
+
+.. Hack to get long definition list:
+
+.. |cmdslong2| replace:: always, always_comb, always_ff, always_latch, and,
+   assign, begin, buf, byte, case, casex, casez, default, defparam,
+   do-while, else, end, endcase, endfunction, endgenerate, endmodule,
+   endspecify, endtask, final, for, function, generate, genvar, if,
+   initial, inout, input, int, integer, localparam, logic, longint,
+   macromodule, module, nand, negedge, nor, not, or, output, parameter,
+   posedge, reg, scalared, shortint, signed, supply0, supply1, task, time,
+   tri, typedef, var, vectored, while, wire, xnor, xor
+
+|cmdslong2|
+  Generally supported.
+
+++, -- operators
+  Increment/decrement can only be used as standalone statements or in
+  certain limited cases.
+
+'{} operator
+  Assignment patterns with order based, default, constant integer (array)
+  or member identifier (struct/union) keys are supported.  Data type keys
+  and keys which are computed from a constant expression are not supported.
+
+\`uselib
+  Uselib, a vendor specific library specification method, is ignored along
+  with anything following it until the end of that line.
+
+cast operator
+  Casting is supported only between simple scalar types, signed and
+  unsigned, not arrays nor structs.
+
+chandle
+  Treated as a "longint"; does not yet warn about operations that are
+  specified as illegal on chandles.
+
+disable
+  Disable statements may be used only if the block being disabled is a
+  block the disable statement itself is inside.  This was commonly used to
+  provide loop break and continue functionality before SystemVerilog added
+  the break and continue keywords.
+
+inside
+  Inside expressions may not include unpacked array traversal or $ as an
+  upper bound.  Case inside and case matches are also unsupported.
+
+interface
+  Interfaces and modports, including with generated data types are
+  supported.  Generate blocks around modports are not supported, nor are
+  virtual interfaces nor unnamed interfaces.
+
+shortreal
+  Short floating point (shortreal) numbers are converted to real. Most
+  other simulators either do not support float, or convert likewise.
+
+specify specparam
+  All specify blocks and timing checks are ignored.
+
+uwire
+  Verilator does not perform warning checking on uwires, it treats the
+  uwire keyword as if it were the normal wire keyword.
+
+$bits, $countbits, $countones, $finish, $isunknown, $onehot, $onehot0, $signed, $stime, $stop, $time, $unsigned,
+  Generally supported.
+
+$dump/$dumpports and related
+  $dumpfile or $dumpports will create a VCD or FST file (which is based on
+  the :vlopt:`--trace` option given when the model was Verilated). This
+  will take effect starting at the next eval() call.  If you have multiple
+  Verilated designs under the same C model, then this will dump signals
+  only from the design containing the $dumpvars.
+
+  $dumpvars and $dumpports module identifier is ignored; the traced
+  instances will always start at the top of the design. The levels argument
+  is also ignored, use tracing_on/tracing_off pragmas instead.
+
+  $dumpportson/$dumpportsoff/$dumpportsall/$dumpportslimit filename
+  argument is ignored, only a single trace file may be active at once.
+
+  $dumpall/$dumpportsall, $dumpon/$dumpportson, $dumpoff/$dumpportsoff, and
+  $dumplimit/$dumpportlimit are currently ignored.
+
+$error, $fatal, $info, $warning.
+  Generally supported.
+
+$exit, $finish, $stop
+  The rarely used optional parameter to $finish and $stop is ignored. $exit
+  is aliased to $finish.
+
+$fopen, $fclose, $fdisplay, $ferror, $feof, $fflush, $fgetc, $fgets, $fscanf, $fwrite, $fscanf, $sscanf
+  Generally supported.
+
+$fullskew, $hold, $nochange, $period, $recovery, $recrem, $removal, $setup, $setuphold, $skew, $timeskew, $width
+  All specify blocks and timing checks are ignored.
+
+$random, $urandom, $urandom_range
+  Use :vlopt:`+verilator+seed+\<value\>` runtime option to set the seed if
+  there is no $random nor $urandom optional argument to set the seed.
+  There is one random seed per C thread, not per module for $random, nor
+  per object for random stability of $urandom/$urandom_range.
+
+$readmemb, $readmemh
+  Read memory commands are supported.  Note Verilator and the Verilog
+  specification does not include support for readmem to multi-dimensional
+  arrays.
+
+$test$plusargs, $value$plusargs
+  Supported, but the instantiating C++/SystemC wrapper must call
+
+  .. code-block:: C++
+
+        Verilated::commandArgs(argc, argv);
+
+  to register the command line before calling $test$plusargs or
+  $value$plusargs.

docs/guide/overview.rst

@@ -0,0 +1,55 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+********
+Overview
+********
+
+Welcome to Verilator!
+
+The Verilator package converts Verilog [#]_ and SystemVerilog [#]_ hardware
+description language (HDL) designs into a C++ or SystemC model that after
+compiling can be executed.  Verilator is not a traditional simulator, but a
+compiler.
+
+Verilator is typically used as follows:
+
+1. The :command:`verilator` executable is invoked with parameters similar
+to GCC, or other simulators such as Cadence Verilog-XL/NC-Verilog, or
+Synopsys VCS.  Verilator reads the specified SystemVerilog code, lints it,
+optionally adds coverage and waveform tracing support, and compiles the
+design into a source level multithreaded C++ or SystemC "model".  The
+resulting model's C++ or SystemC code is output as .cpp and .h files. This
+is referred to as "Verilating" and the process is "to Verilate"; the output
+is a "Verilated" model.
+
+2. For simulation, a small user written C++ wrapper file is required, the
+"wrapper".  This wrapper defines the C++ standard function "main()" which
+instantiates the Verilated model as a C++/SystemC object.
+
+3. The user C++ wrapper, the files created by Verilator, a "runtime
+library" provided by Verilator, and if applicable SystemC libraries are
+then compiled using a C++ compiler to create a simulation executable.
+
+4. The resulting executable will perform the actual simulation, during
+"simulation runtime".
+
+5. If appropriately enabled, the executable may also generate waveform
+traces of the design that may be viewed.  It may also create coverage
+analysis data for post-analysis.
+
+The best place to get started is to try the :ref:`Examples`.
+
+
+.. [#] Verilog is defined by the `Institute of Electrical and Electronics
+       Engineers (IEEE) Standard for Verilog Hardware Description
+       Language`, Std. 1364, released in 1995, 2001, and 2005.  The
+       Verilator documentation uses the shorthand e.g. "IEEE 1394-2005" to
+       refer to the e.g. 2005 version of this standard.
+
+.. [#] SystemVerilog is defined by the `Institute of Electrical and
+       Electronics Engineers (IEEE) Standard for SystemVerilog - Unified
+       Hardware Design, Specification, and Verification Language`, Standard
+       1800, released in 2005, 2009, 2012, and 2017.  The Verilator
+       documentation uses the shorthand e.g. "IEEE 1800-2017" to refer to
+       the e.g. 2017 version of this standard.

docs/guide/simulating.rst

@@ -0,0 +1,352 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Simulating:
+
+************************************
+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`.
+
+
+.. _Benchmarking & Optimization:
+
+Benchmarking & Optimization
+===========================
+
+For best performance, run Verilator with the :vlopt:`-O3`
+:vlopt:`--x-assign fast <--x-assign>` :vlopt:`--x-initial fast
+<--x-initial>` :vlopt:`--noassert <--assert>` options.  The :vlopt:`-O3`
+option will require longer time to run Verilator, and :vlopt:`--x-assign
+fast <--x-assign>` :vlopt:`--x-initial fast <--x-assign>` may increase the
+risk of reset bugs in trade for performance; see the above documentation
+for these options.
+
+If using Verilated multithreaded, use ``numactl`` to ensure you are using
+non-conflicting hardware resources. See :ref:`Multithreading`.
+
+Minor Verilog code changes can also give big wins.  You should not have any
+UNOPTFLAT warnings from Verilator.  Fixing these warnings can result in
+huge improvements; one user fixed their one UNOPTFLAT warning by making a
+simple change to a clock latch used to gate clocks and gained a 60%
+performance improvement.
+
+Beyond that, the performance of a Verilated model depends mostly on your
+C++ compiler and size of your CPU's caches. Experience shows that large
+models are often limited by the size of the instruction cache, and as such
+reducing code size if possible can be beneficial.
+
+The supplied $VERILATOR_ROOT/include/verilated.mk file uses the OPT,
+OPT_FAST, OPT_SLOW and OPT_GLOBAL variables to control optimization. You
+can set these when compiling the output of Verilator with Make, for
+example:
+
+.. code-block:: bash
+
+     make OPT_FAST="-Os -march=native" -f Vour.mk Vour__ALL.a
+
+OPT_FAST specifies optimization options for those parts of the model that
+are on the fast path. This is mostly code that is executed every
+cycle. OPT_SLOW applies to slow-path code, which executes rarely, often
+only once at the beginning or end of simulation. Note that OPT_SLOW is
+ignored if VM_PARALLEL_BUILDS is not 1, in which case all generated code
+will be compiled in a single compilation unit using OPT_FAST. See also the
+Verilator :vlopt:`--output-split` option. The OPT_GLOBAL variable applies
+to common code in the runtime library used by Verilated models (shipped in
+$VERILATOR_ROOT/include). Additional C++ files passed on the verilator
+command line use OPT_FAST. The OPT variable applies to all compilation
+units in addition to the specific "OPT" variables described above.
+
+You can also use the :vlopt:`-CFLAGS` and/or :vlopt:`-LDFLAGS` options on
+the verilator command line to pass arguments directly to the compiler or
+linker.
+
+The default values of the "OPT" variables are chosen to yield good
+simulation speed with reasonable C++ compilation times. To this end,
+OPT_FAST is set to "-Os" by default. Higher optimization such as "-O2" or
+"-O3" may help (though often they provide only a very small performance
+benefit), but compile times may be excessively large even with medium sized
+designs. Compilation times can be improved at the expense of simulation
+speed by reducing optimization, for example with OPT_FAST="-O0". Often good
+simulation speed can be achieved with OPT_FAST="-O1 -fstrict-aliasing" but
+with improved compilation times. Files controlled by OPT_SLOW have little
+effect on performance and therefore OPT_SLOW is empty by default
+(equivalent to "-O0") for improved compilation speed. In common use-cases
+there should be little benefit in changing OPT_SLOW.  OPT_GLOBAL is set to
+"-Os" by default and there should rarely be a need to change it. As the
+runtime library is small in comparison to a lot of Verilated models,
+disabling optimization on the runtime library should not have a serious
+effect on overall compilation time, but may have detrimental effect on
+simulation speed, especially with tracing. In addition to the above, for
+best results use OPT="-march=native", the latest Clang compiler (about 10%
+faster than GCC), and link statically.
+
+Generally the answer to which optimization level gives the best user
+experience depends on the use case and some experimentation can pay
+dividends. For a speedy debug cycle during development, especially on large
+designs where C++ compilation speed can dominate, consider using lower
+optimization to get to an executable faster. For throughput oriented use
+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.
+
+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
+both compilation and link. Note LTO may cause excessive compile times on
+large designs.
+
+Unfortunately, using the optimizer with SystemC files can result in
+compilation taking several minutes. (The SystemC libraries have many little
+inlined functions that drive the compiler nuts.)
+
+If you are using your own makefiles, you may want to compile the Verilated
+code with ``--MAKEFLAGS -DVL_INLINE_OPT=inline``. This will inline
+functions, however this requires that all cpp files be compiled in a single
+compiler run.
+
+You may uncover further tuning possibilities by profiling the Verilog code.
+See :ref:`profiling`.
+
+When done optimizing, please let the author know the results.  We like to
+keep tabs on how Verilator compares, and may be able to suggest additional
+improvements.
+
+
+.. _Coverage Analysis:
+
+Coverage Analysis
+=================
+
+Verilator supports adding code to the Verilated model to support
+SystemVerilog code coverage.  With :vlopt:`--coverage`, Verilator enables
+all forms of coverage:
+
+* :ref:`User Coverage`
+* :ref:`Line Coverage`
+* :ref:`Toggle Coverage`
+
+When a model with coverage is executed, it will create a coverage file for
+collection and later analysis, see :ref:`Coverage Collection`.
+
+
+.. _User Coverage:
+
+Functional Coverage
+-------------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
+translate functional coverage points which the user has inserted manually
+into the SystemVerilog design, into the Verilated model.
+
+Currently, all functional coverage points are specified using SystemVerilog
+assertion syntax which must be separately enabled with :vlopt:`--assert`.
+
+For example, the following SystemVerilog statement will add a coverage
+point, under the coverage name "DefaultClock":
+
+.. code-block:: sv
+
+    DefaultClock: cover property (@(posedge clk) cyc==3);
+
+
+.. _Line Coverage:
+
+Line Coverage
+-------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-line`, Verilator will
+automatically add coverage analysis at each code flow change point (e.g. at
+branches).  At each such branch a unique counter is incremented.  At the
+end of a test, the counters along with the filename and line number
+corresponding to each counter are written into the coverage file.
+
+Verilator automatically disables coverage of branches that have a $stop in
+them, as it is assumed $stop branches contain an error check that should
+not occur.  A :option:`/*verilator&32;coverage_block_off*/` metacomment
+will perform a similar function on any code in that block or below, or
+:option:`/*verilator&32;coverage_off*/` and
+:option:`/*verilator&32;coverage_on*/` will disable and enable coverage
+respectively around a block of code.
+
+Verilator may over-count combinatorial (non-clocked) blocks when those
+blocks receive signals which have had the UNOPTFLAT warning disabled; for
+most accurate results do not disable this warning when using coverage.
+
+
+.. _Toggle Coverage:
+
+Toggle Coverage
+---------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-toggle`, Verilator will
+automatically add toggle coverage analysis  into the Verilated model.
+
+Every bit of every signal in a module has a counter inserted.  The counter
+will increment on every edge change of the corresponding bit.
+
+Signals that are part of tasks or begin/end blocks are considered local
+variables and are not covered.  Signals that begin with underscores (see
+:vlopt:`--coverage-underscore`), are integers, or are very wide (>256 bits
+total storage across all dimensions, see :vlopt:`--coverage-max-width`) are
+also not covered.
+
+Hierarchy is compressed, such that if a module is instantiated multiple
+times, coverage will be summed for that bit across **all** instantiations
+of that module with the same parameter set.  A module instantiated with
+different parameter values is considered a different module, and will get
+counted separately.
+
+Verilator makes a minimally-intelligent decision about what clock domain
+the signal goes to, and only looks for edges in that clock domain.  This
+means that edges may be ignored if it is known that the edge could never be
+seen by the receiving logic.  This algorithm may improve in the future.
+The net result is coverage may be lower than what would be seen by looking
+at traces, but the coverage is a more accurate representation of the
+quality of stimulus into the design.
+
+There may be edges counted near time zero while the model stabilizes.  It's
+a good practice to zero all coverage just before releasing reset to prevent
+counting such behavior.
+
+A :option:`/*verilator&32;coverage_off*/`
+:option:`/*verilator&32;coverage_on*/` metacomment pair can be used around
+signals that do not need toggle analysis, such as RAMs and register files.
+
+
+.. _Coverage Collection:
+
+Coverage Collection
+-------------------
+
+When any coverage flag was used to Verilate, Verilator will add appropriate
+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
+the coverage data file to write coverage data to (typically
+"logs/coverage.dat").
+
+Run each of your tests in different directories, potentially in parallel.
+Each test will create a :file:`logs/coverage.dat` file.
+
+After running all of the tests, execute the :command:`verilator_coverage`
+command, passing arguments pointing to the filenames of all of the
+individual coverage files.  :command:`verilator_coverage` will reads the
+:file:`logs/coverage.dat` file(s), and create an annotated source code
+listing showing code coverage details.
+
+:command:`verilator_coverage` may also be used for test grading, that is
+computing which tests are important to fully cover the design.
+
+For an example, see the :file:`examples/make_tracing_c/logs` directory.
+Grep for lines starting with '%' to see what lines Verilator believes need
+more coverage.
+
+Additional options of :command:`verilator_coverage` allow for merging of
+coverage data files or other transformations.
+
+Info files can be written by verilator_coverage for import to
+:command:`lcov`.  This enables use of :command:`genhtml` for HTML reports
+and importing reports to sites such as `https://codecov.io
+<https://codecov.io>`_.
+
+
+.. _Profiling:
+
+Code Profiling
+==============
+
+The Verilated model may be code-profiled using GCC or Clang's C++ profiling
+mechanism.  Verilator provides additional flags to help map the resulting
+C++ profiling results back to the original Verilog code responsible for the
+profiled C++ code functions.
+
+To use profiling:
+
+#. Use Verilator's :vlopt:`--prof-cfuncs`.
+#. Use Verilator's :vlopt:`-CFLAGS "-g -pg" <-CFLAGS>` to pass the
+   profiling flags through to GCC/Clang.
+#. Build and run the simulation model.
+#. The model will create gmon.out.
+#. Run :command:`gprof` to see where in the C++ code the time is spent.
+#. Run the gprof output through the :command:`verilator_profcfunc` program
+   and it will tell you what Verilog line numbers on which most of the time
+   is being spent.
+
+
+.. _Thread Profiling:
+
+Thread Profiling
+================
+
+When using multithreaded mode (:vlopt:`--threads`), it is useful to see
+statistics and visualize how well the multiple CPUs are being utilized.
+
+With the :vlopt:`--prof-threads` 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 save profiling data in non-human-friendly form to the file
+  specified with :vlopt:`+verilator+prof+threads+file+\<filename\>`.
+
+The :command:`verilator_gantt` program may then be run to transform the
+saved profiling file into a nicer visual format and produce some related
+statistics.
+
+.. figure:: figures/fig_gantt_min.png
+
+   Example verilator_gantt output, as viewed with GTKWave.
+
+   The 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.
+
+   The thread_mtask section shows which macro-task is running on a given thread.
+
+For more information see :command:`verilator_gantt`.
+
+.. _Save/Restore:
+
+Save/Restore
+============
+
+The intermediate state of a Verilated model may be saved, so that it may
+later be restored.
+
+To enable this feature, use :vlopt:`--savable`.  There are limitations in
+what language features are supported along with :vlopt:`--savable`; if you
+attempt to use an unsupported feature Verilator will throw an error.
+
+To use save/restore, the user wrapper code must create a VerilatedSerialize
+or VerilatedDeserialze object then calling the :code:`<<` or :code:`>>`
+operators on the generated model and any other data the process needs
+saved/restored.  These functions are not thread safe, and are typically
+called only by a main thread.
+
+For example:
+
+.. code-block:: C++
+
+     void save_model(const char* filenamep) {
+         VerilatedSave os;
+         os.open(filenamep);
+         os << main_time;  // user code must save the timestamp, etc
+         os << *topp;
+     }
+     void restore_model(const char* filenamep) {
+         VerilatedRestore os;
+         os.open(filenamep);
+         os >> main_time;
+         os >> *topp;
+     }

docs/guide/verilating.rst

@@ -0,0 +1,482 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+**********
+Verilating
+**********
+
+Verilator may be used in five major ways:
+
+* With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate
+  the design into C++ or SystemC code respectively.  See :ref:`C++ and
+  SystemC Generation`.
+
+* With the :vlopt:`--lint-only` option, Verilator will lint the design to
+  check for warnings but will not typically create any output files.
+
+* With the :vlopt:`--xml-only` option, Verilator will create XML output
+  that may be used to feed into other user-designed tools.  See
+  :file:`docs/xml.rst` in the distribution.
+
+* With the :vlopt:`-E` option, Verilator will preprocess the code according
+  to IEEE preprocessing rules, and write the output to standard out. This
+  is useful to feed other tools, and to debug how "\`define" statements are
+  expanded.
+
+
+.. _C++ and SystemC Generation:
+
+C++ and SystemC Generation
+==========================
+
+Verilator will translate a SystemVerilog design into C++ with the
+:vlopt:`--cc` option, or into SystemC with the :vlopt:`--sc` option.
+
+When using these options:
+
+#. Verilator reads the input Verilog code, determines all "top modules" that
+   is modules or programs that are not used as instances under other cells.
+   If :vlopt:`--top-module` is used, then that determines the top module and
+   all other top modules are removed, otherwise a :vlopt:`MULTITOP` warning
+   is given.
+
+#. Verilator writes the C++/SystemC code to output files into the
+   :vlopt:`--Mdir` option-specified directory, or defaults to "obj_dir".
+   The prefix is set with :vlopt:`--prefix`, or defaults to the name of the
+   top module.
+
+#. If :vlopt:`--exe` is used, Verilator creates makefiles to generate a
+   simulation executable, otherwise it creates makefiles to generate an
+   archive (.a) containing the objects.
+
+#. If :vlopt:`--build` option was used, it calls :ref:`GNU Make` or
+   :ref:`CMake` to build the model.
+
+Once a model is built it is then typically run, see :ref:`Simulating`.
+
+
+.. _Hierarchical Verilation:
+
+Hierarchical Verilation
+=======================
+
+Large designs may take long (e.g. 10+ minutes) and huge memory (e.g. 100+
+GB) to Verilate.  In hierarchical mode, the user manually selects some
+large lower-level hierarchy blocks to separate from the larger design. For
+example a core may be the hierarchy block, and separated out of a
+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.
+
+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.
+
+
+Usage
+-----
+
+Users need to mark one or more moderate size module as hierarchy block(s).
+There are two ways to mark a module:
+
+* Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code.
+
+* Add a :option:`hier_block` line in a the :ref:`Configuration Files`.
+
+Then pass the :vlopt:`--hierarchical` option to Verilator
+
+Compilation is the same as when not using hierarchical mode.
+
+.. code-block:: bash
+
+    make -C obj_dir -f Vtop_module_name.mk
+
+
+Limitations
+-----------
+
+Hierarchy blocks have some limitations including:
+
+* The hierarchy block cannot be accessed using dot (.) from upper module(s)
+  or other hierarchy blocks.
+
+* Signals in the block cannot be traced.
+
+* Modport cannot be used at the hierarchical block boundary.
+
+* The simulation speed is likely to not be as fast as flat Verilation, in
+  which all modules are globally scheduled.
+
+* Generated clocks may not work correctly if they are generated in the
+  hierarchical model and pass up into another hierarchical model or the top
+  module.
+
+But, the following usage is supported:
+
+* Nested hierarchy blocks. A hierarchy block may instantiate other
+  hierarchy blocks.
+
+* Parameterized hierarchy block. Parameters of a hierarchy block can be
+  overridden using :code:`#(.param_name(value))` construct.
+
+
+.. _Overlapping Verilation and Compilation:
+
+Overlapping Verilation and Compilation
+--------------------------------------
+
+Verilator needs to run 2 + *N* times in hierarchical Verilation, where *N*
+is the number of hierarchy blocks. One of the two is for the top module
+which refers wrappers of all other hierarchy blocks.  The second one of the
+two is the initial run that searches modules marked with
+:option:`/*verilator&32;hier_block*/` metacomment and creates a plan and
+write in :file:`{prefix}_hier.mk`.  This initial run internally invokes
+other *N* + 1 runs, so you don't have to care about these *N* + 1 times of
+run. The additional *N* is the Verilator run for each hierarchical block.
+
+If ::vlopt:`-j {jobs} <-j>` option is specified, Verilation for hierarchy
+blocks runs in parallel.
+
+If :vlopt:`--build` option is specified, C++ compilation also runs as soon
+as a hierarchy block is Verilated. C++ compilation and Verilation for other
+hierarchy blocks run simultaneously.
+
+
+Cross Compilation
+=================
+
+Verilator supports cross-compiling Verilated code.  This is generally used
+to run Verilator on a Linux system and produce C++ code that is then compiled
+on Windows.
+
+Cross compilation involves up to three different OSes.  The build system is
+where you configured and compiled Verilator, the host system where you run
+Verilator, and the target system where you compile the Verilated code and
+run the simulation.
+
+Currently, Verilator requires the build and host system type to be the
+same, though the target system type may be different.  To support this,
+:command:`./configure` and make Verilator on the build system.  Then, run
+Verilator on the host system.  Finally, the output of Verilator may be
+compiled on the different target system.
+
+To support this, none of the files that Verilator produces will reference
+any configure generated build-system specific files, such as
+:file:`config.h` (which is renamed in Verilator to :file:`config_build.h`
+to reduce confusion.)  The disadvantage of this approach is that
+:file:`include/verilatedos.h` must self-detect the requirements of the
+target system, rather than using configure.
+
+The target system may also require edits to the Makefiles, the simple
+Makefiles produced by Verilator presume the target system is the same type
+as the build system.
+
+
+.. _Multithreading:
+
+Multithreading
+==============
+
+Verilator supports multithreaded simulation models.
+
+With :vlopt:`--no-threads`, the default, the model is not thread safe, and
+any use of more than one thread calling into one or even different
+Verilated models may result in unpredictable behavior. This gives the
+highest single thread performance.
+
+With :vlopt:`--threads 1 <--threads>`, the generated model is single
+threaded, however the support libraries are multithread safe. This allows
+different instantiations of model(s) to potentially each be run under a
+different thread. All threading is the responsibility of the user's C++
+testbench.
+
+With :vlopt:`--threads {N} <--threads>`, where N is at least 2, the
+generated model will be designed to run in parallel on N threads. The
+thread calling eval() provides one of those threads, and the generated
+model will create and manage the other N-1 threads. It's the client's
+responsibility not to oversubscribe the available CPU cores. Under CPU
+oversubscription, the Verilated model should not livelock nor deadlock,
+however, you can expect performance to be far worse than it would be with
+proper ratio of threads and CPU cores.
+
+The remainder of this section describe behavior with :vlopt:`--threads 1
+<--threads>` or :vlopt:`--threads {N} <--threads>` (not
+:vlopt:`--no-threads`).
+
+:code:`VL_THREADED` is defined in the C++ code when compiling a threaded
+Verilated module, causing the Verilated support classes become threadsafe.
+
+The thread used for constructing a model must be the same thread that calls
+:code:`eval()` into the model, this is called the "eval thread". The thread
+used to perform certain global operations such as saving and tracing must
+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
+:vlopt:`--threads 1 <--threads>`, i.e.: the support libraries will be
+thread safe.
+
+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.
+
+When running a multithreaded model, the default Linux task scheduler often
+works against the model, by assuming threads are short lived, and thus
+often schedules threads using multiple hyperthreads within the same
+physical core. For best performance use the :command:`numactl` program to
+(when the threading count fits) select unique physical cores on the same
+socket. The same applies for :vlopt:`--trace-threads` as well.
+
+As an example, if a model was Verilated with :vlopt:`--threads 4
+<--threads>`, we consult:
+
+.. code-block:: bash
+
+    egrep 'processor|physical id|core id' /proc/cpuinfo
+
+To select cores 0, 1, 2, and 3 that are all located on the same socket (0)
+but different physical cores.  (Also useful is :command:`numactl
+--hardware`, or :command:`lscpu` but those doesn't show Hyperthreading
+cores.) Then we execute:
+
+.. code-block:: bash
+
+    numactl -m 0 -C 0,1,2,3 -- verilated_executable_name
+
+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`.
+
+
+Multithreaded Verilog and Library Support
+-----------------------------------------
+
+$display/$stop/$finish are delayed until the end of an eval() call in order
+to maintain ordering between threads. This may result in additional tasks
+completing after the $stop or $finish.
+
+If using :vlopt:`--coverage`, the coverage routines are fully thread safe.
+
+If using the DPI, Verilator assumes pure DPI imports are thread safe,
+balancing performance versus safety. See :vlopt:`--threads-dpi`.
+
+If using :vlopt:`--savable`, the save/restore classes are not multithreaded
+and must be called only by the eval thread.
+
+If using :vlopt:`--sc`, the SystemC kernel is not thread safe, therefore
+the eval thread and main thread must be the same.
+
+If using :vlopt:`--trace`, the tracing classes must be constructed and
+called from the main thread.
+
+If using :vlopt:`--vpi`, since SystemVerilog VPI was not architected by
+IEEE to be multithreaded, Verilator requires all VPI calls are only made
+from the main thread.
+
+
+.. _GNU Make:
+
+GNU Make
+========
+
+Verilator defaults to creating GNU Make makefiles for the model.  Verilator
+will call make automatically when the :vlopt:'--build' option is used.
+
+If calling Verilator from a makefile, the :vlopt:'-MMD' option will create
+a dependency file which will allow Make to only run Verilator if input
+Verilog files change.
+
+.. _CMake:
+
+CMake
+=====
+
+Verilator can be run using CMake, which takes care of both running
+Verilator and compiling the output. There is a CMake example in the
+examples/ directory. The following is a minimal CMakeLists.txt that would
+build the code listed in :ref:`Example C++ Execution`
+
+.. code-block:: CMake
+
+     project(cmake_example)
+     find_package(verilator HINTS $ENV{VERILATOR_ROOT})
+     add_executable(Vour sim_main.cpp)
+     verilate(Vour SOURCES our.v)
+
+:code:`find_package` will automatically find an installed copy of
+Verilator, or use a local build if VERILATOR_ROOT is set.
+
+It is recommended to use CMake >= 3.12 and the Ninja generator, though
+other combinations should work. To build with CMake, change to the folder
+containing CMakeLists.txt and run:
+
+.. code-block:: bash
+
+     mkdir build
+     cd build
+     cmake -GNinja ..
+     ninja
+
+Or to build with your system default generator:
+
+.. code-block:: bash
+
+     mkdir build
+     cd build
+     cmake ..
+     cmake --build .
+
+If you're building the example you should have an executable to run:
+
+.. code-block:: bash
+
+     ./Vour
+
+The package sets the CMake variables verilator_FOUND, VERILATOR_ROOT and
+VERILATOR_BIN to the appropriate values, and also creates a verilate()
+function. verilate() will automatically create custom commands to run
+Verilator and add the generated C++ sources to the target specified.
+
+Verilate in CMake
+-----------------
+
+.. code-block:: CMake
+
+     verilate(target SOURCES source ... [TOP_MODULE top] [PREFIX name]
+              [TRACE] [TRACE_FST] [SYSTEMC] [COVERAGE]
+              [INCLUDE_DIRS dir ...] [OPT_SLOW ...] [OPT_FAST ...]
+              [OPT_GLOBAL ..] [DIRECTORY dir] [VERILATOR_ARGS ...])
+
+Lowercase and ... should be replaced with arguments, the uppercase parts
+delimit the arguments and can be passed in any order, or left out entirely
+if optional.
+
+verilate(target ...) can be called multiple times to add other Verilog
+modules to an executable or library target.
+
+When generating Verilated SystemC sources, you should also include the
+SystemC include directories and link to the SystemC libraries.
+
+.. describe:: target
+
+   Name of a target created by add_executable or add_library.
+
+.. describe:: COVERAGE
+
+   Optional. Enables coverage if present, equivalent to "VERILATOR_ARGS
+   --coverage"
+
+.. describe:: DIRECTORY
+
+   Optional. Set the verilator output directory. It is preferable to use
+   the default, which will avoid collisions with other files.
+
+.. describe:: INCLUDE_DIRS
+
+   Optional. Sets directories that Verilator searches (same as -y).
+
+.. describe:: OPT_SLOW
+
+   Optional. Set compiler options for the slow path. You may want to reduce
+   the optimization level to improve compile times with large designs.
+
+.. describe:: OPT_FAST
+
+   Optional. Set compiler options for the fast path.
+
+.. describe:: OPT_GLOBAL
+
+   Optional. Set compiler options for the common runtime library used by
+   Verilated models.
+
+.. describe:: PREFIX
+
+   Optional. Sets the Verilator output prefix. Defaults to the name of the
+   first source file with a "V" prepended. Must be unique in each call to
+   verilate(), so this is necessary if you build a module multiple times
+   with different parameters. Must be a valid C++ identifier, i.e. contains
+   no white space and only characters A-Z, a-z, 0-9 or _.
+
+.. describe:: SOURCES
+
+   List of Verilog files to Verilate. Must have at least one file.
+
+.. describe:: SYSTEMC
+
+   Optional. Enables SystemC mode, defaults to C++ if not specified.
+
+   When using Accellera's SystemC with CMake support, a CMake target is
+   available that simplifies the SystemC steps. This will only work if the
+   SystemC installation can be found by CMake. This can be configured by
+   setting the CMAKE_PREFIX_PATH variable during CMake configuration.
+
+   Don't forget to set the same C++ standard for the Verilated sources as
+   the SystemC library. This can be specified using the SYSTEMC_CXX_FLAGS
+   environment variable.
+
+.. describe:: TOP_MODULE
+
+   Optional. Sets the name of the top module. Defaults to the name of the
+   first file in the SOURCES array.
+
+.. describe:: TRACE
+
+   Optional. Enables VCD tracing if present, equivalent to "VERILATOR_ARGS
+   --trace".
+
+.. describe:: TRACE_FST
+
+   Optional. Enables FST tracing if present, equivalent to "VERILATOR_ARGS
+   --trace-fst".
+
+.. describe:: VERILATOR_ARGS
+
+   Optional. Extra arguments to Verilator. Do not specify :vlopt:`--Mdir`
+   or :vlopt:`--prefix` here, use DIRECTORY or PREFIX.
+
+
+SystemC Link in CMake
+---------------------
+
+Verilator's CMake support provides a convenience function to automatically
+find and link to the SystemC library.  It can be used as:
+
+.. code-block:: CMake
+
+     verilator_link_systemc(target)
+
+where target is the name of your target.
+
+The search paths can be configured by setting some variables:
+
+.. describe:: SYSTEMC_INCLUDE
+
+   Sets the direct path to the SystemC includes.
+
+.. describe:: SYSTEMC_LIBDIR
+
+   Sets the direct path to the SystemC libraries.
+
+.. describe:: SYSTEMC_ROOT
+
+   Sets the installation prefix of an installed SystemC library.
+
+.. describe:: SYSTEMC
+
+   Sets the installation prefix of an installed SystemC library. (Same as
+   SYSTEMC_ROOT).

docs/spelling.txt

@@ -0,0 +1,850 @@
+ABCp
+Accellera
+Affe
+Aleksander
+Ami
+Amir
+Anastasiadis
+Antonin
+Antwerpen
+Arasanipalai
+Arjen
+Asciidoc
+Ashutosh
+Atmel
+Aurelien
+Bagri
+Baltazar
+Bardsley
+Benchmarking
+Berman
+Bhagavatula
+Bhattacharyya
+Binderman
+Bleiweiss
+Bogdan
+Bouchard
+Boumenot
+Brej
+Briquet
+Brownlee
+Buckenmaier
+Bybell
+CMake
+Cai
+Cavium
+Cfuncs
+Chandan
+Chitlesh
+Christophe
+Cochrane
+Cuan
+Cygwin
+DErrico
+Da
+Danilo
+Dannoritzer
+Das
+Dcache
+Deadman
+Debacker
+Defparams
+Denio
+Deprecations
+Deroo
+Dickol
+Diez
+Dimitris
+Dinotrace
+Djordjevic
+Dobbie
+Dockerfile
+Donal
+Doorn
+Doxygen
+Dressler
+Duraid
+Dutton
+Dzetkulic
+Eda
+Eddleston
+Egbert
+Egil
+Eiler
+Eivind
+El
+Elbourne
+Embecosm
+Engstrom
+Enzo
+Eugen
+Fabrizio
+Fekete
+Ferrandi
+Flachs
+Foletto
+Forker
+Francillon
+Fredieu
+GTKWave
+Galbi
+Gantt
+Gartner
+Gelinek
+Geoff
+Gernot
+Gerst
+Gielda
+Gigerl
+Gileadi
+Giri
+Gisselquist
+Gladkikh
+Goessling
+Gonnen
+Goorah
+Gossner
+Grobman
+Gunter
+Guo
+Hao
+Harboe
+Hashimoto
+Hayenga
+Hewson
+Hicamp
+Hiroki
+Holdsworth
+Holme
+Homebrew
+Hornung
+Hossell
+Hsu
+Hyperthreading
+Iles
+Inlines
+Inout
+Iru
+Iztok
+Jacko
+Jae
+Jalloq
+Jankowski
+Jannis
+Jens
+Jeras
+Jiuyang
+Joly
+Jullien
+Junji
+Junyi
+Kaalia
+Kagen
+Kahlich
+Kahn
+Kai
+Kamendje
+Kandadi
+Kaplan
+Karge
+Katz
+Katzman
+Keren
+Keyi
+Kimmitt
+Kindgren
+Kirkham
+Klnv
+Koenig
+Koh
+Kolecki
+Koonce
+Korteland
+Koszek
+Kravitz
+Krolnik
+Kruse
+Kumashikar
+Kuoping
+Kurachi
+Laeufer
+Laurens
+Lavino
+Leber
+Leendert
+Lesik
+Liland
+Liu
+Lockhart
+Longo
+Lussier
+MMD
+MODDUP
+MTasks
+Madina
+Magne
+Mahesh
+Mahmoudy
+Makefile
+Makefiles
+Matveyenko
+Maupin
+Mdir
+Mednick
+Michiels
+Microsystems
+Milanovic
+MinW
+Mindspeed
+Miodrag
+ModelSim
+Modport
+Moinak
+Mong
+Muhlestein
+Multithreaded
+Multithreading
+NOUNOPTFLAT
+Nalbantis
+Narayan
+Nauticus
+Newgard
+Nikana
+Niranjan
+Nitza
+Noack
+Nodine
+Oleg
+Olof
+Olofsson
+Oyvind
+PLI
+Patricio
+Petr
+Piechotka
+Piersall
+Plunkett
+Popov
+Prabhat
+Prabhu
+Prateek
+Pre
+Preprocess
+Priyadharshini
+Pullup
+Pulver
+Puri
+Questa
+Ralf
+Rapp
+Redhat
+Reitan
+Renga
+Requin
+Rodionov
+Rolfe
+Roodselaar
+Runtime
+Ruud
+Rystsov
+STandarD
+Salman
+Sanguinetti
+Sanjay
+Scharrer
+Seitz
+Shankar
+Shanshan
+Sharad
+Shareef
+Sheng
+Shi
+Shinkarovsky
+Shirakawa
+Shuba
+Slatter
+SoC
+Sobhan
+Sokorac
+Solaris
+Solomatnikov
+Srini
+Stamness
+Stephane
+Stoddard
+Stroebel
+Strouble
+Stucki
+Su
+Suguimoto
+Sundararajan
+Suse
+Syms
+Synopsys
+SystemC
+SystemVerilog
+Takatsukasa
+Tambe
+Tariq
+Tengstrand
+Terpstra
+Thiede
+Thierry
+Thyer
+Tichelaar
+Tomov
+Topa
+Tota
+Tresidder
+Tri
+Tristate
+Turton
+UNOPTFLAT
+Ubixum
+Uints
+Undefines
+Unsized
+Uselib
+Usha
+Usuario
+VERILATOR
+Vasu
+Vdly
+Vemumtab
+Vemuri
+Veriable
+Verialted
+Verilate
+Verilated
+Verilating
+Verilation
+Verilator
+Verilog
+Viktor
+Vm
+Vukobratovic
+Wai
+Wasson
+Welch
+Werror
+Wfuture
+Whatson
+Wildman
+Wim
+Wno
+Wojciech
+Wolfel
+Wouters
+Wpedantic
+Wwarn
+XSim
+Xcelium
+Xiaoliang
+Xuan
+Xuanqi
+Yazdanbakhsh
+Yi
+Yinan
+Yosys
+Yu
+Zhang
+abirkmanis
+accessor
+accessors
+agrobman
+al
+ala
+andit
+ar
+architected
+args
+arrarys
+assertOn
+async
+ato
+atoi
+autoconf
+autoflush
+bXXXX
+backend
+backslashed
+backtrace
+backtraces
+basename
+bbox
+biguint
+biops
+bitstoreal
+blackbox
+bokke
+brancoliticus
+buf
+bufif
+buildenv
+bv
+bvs
+callValueCbs
+casex
+casez
+casted
+cb
+ccache
+cdc
+ceil
+celldefine
+cerr
+cfunc
+cfuncs
+chandle
+chandles
+changeDetect
+chenguokai
+clk
+clocker
+cmake
+cmos
+combinational
+combinatorial
+commandArgsPlusMatch
+compilable
+concat
+concats
+config
+const
+coredump
+countbits
+countones
+cout
+cpp
+cpu
+ctor
+ctrace
+cutable
+cygwin
+dM
+da
+dat
+datadir
+datafiles
+ddd
+deassign
+debugi
+defenv
+defname
+defparam
+demangling
+der
+desassign
+destructor
+detections
+dev
+devel
+dir
+displayb
+distcc
+doxygen
+dpiGetContext
+dpic
+dsvf
+dtor
+dumpall
+dumpfile
+dumplimit
+dumpoff
+dumpon
+dumpportlimit
+dumpports
+dumpportsall
+dumpportslimit
+dumpportsoff
+dumpportson
+dumpvars
+dut
+dx
+elab
+elsif
+endcase
+endcelldefine
+endfunction
+endgenerate
+endian
+endif
+endmodule
+endprotect
+endspecify
+endtask
+engr
+entrypoint
+enum
+enums
+env
+envvar
+eof
+erroring
+et
+eval
+exe
+executables
+expr
+extern
+fanin
+fasttrace
+fbranch
+fclose
+fdisplay
+feedthrus
+feof
+ferror
+fflush
+fgetc
+fgets
+filesystem
+filt
+flto
+flushCall
+fopen
+foreach
+fprintf
+fprofile
+fread
+frewind
+fs
+fscanf
+fseek
+fsiegle
+fst
+fstrict
+ftell
+fullskew
+func
+funcs
+fwrite
+gantt
+gcc
+gdb
+genblk
+genvar
+genvars
+getenv
+getline
+gmake
+gmon
+gotFinish
+gprof
+gtkwave
+hdr
+hdzhangdoc
+hh
+hier
+hierCMakeArgs
+hierMkArgs
+hierVer
+hx
+hyperthreads
+icecream
+idmap
+ifdef
+ifdefed
+iff
+ifndef
+impot
+incdir
+includer
+inferfaces
+inhibitSim
+initializer
+initializers
+inits
+inlined
+inlining
+inout
+inouts
+inserted
+instantiation
+instantiations
+iostream
+ish
+isunbounded
+isunknown
+killua
+lang
+lcov
+ld
+len
+libext
+libgoogle
+libsystemc
+libtcmalloc
+linkers
+linter
+linux
+liu
+livelock
+ln
+loc
+localparam
+localparams
+logicals
+longint
+lsb
+lvalue
+lxt
+macromodule
+makefile
+makefiles
+manpages
+metacomment
+metacomments
+mis
+misconnected
+misconversion
+missized
+mk
+mno
+modport
+modports
+msg
+msvc
+mtask
+mtasks
+mulithreaded
+mult
+multidim
+multiinterfaces
+multiline
+multipling
+multithread
+multithreaded
+multithreading
+mutexes
+mux
+mysignal
+namespace
+nand
+nanduraj
+nasties
+negedge
+negedges
+netlist
+netlists
+nettype
+nmos
+noassert
+nochange
+noconfig
+nol
+nonblocking
+noprivate
+noreturn
+notif
+nullptr
+onehot
+ooo
+oprofile
+oversubscription
+param
+parameterized
+params
+parens
+pc
+pdf
+perf
+perftools
+picoChip
+pinout
+plusargs
+pmos
+poping
+portbind
+portlists
+posedge
+posix
+postfix
+pragma
+pragmas
+pre
+precisions
+predefines
+prepend
+prepended
+preprocess
+preprocessed
+preprocessing
+preprocessor
+prerelease
+prev
+printf
+printtimescale
+profcfunc
+profcfuncs
+prototyptes
+ps
+pthread
+pulldown
+pulldowns
+pullup
+pvalue
+pwd
+qrq
+radix
+randc
+rarr
+rdtsc
+reStructuredText
+readme
+readmem
+readmemb
+readmemh
+realpath
+realtime
+recoding
+recrem
+redeclaring
+regs
+reloop
+resetall
+respecified
+rr
+rst
+runtime
+runtimes
+rw
+sVerilator
+sc
+scalared
+sccanf
+seg
+setuphold
+sformat
+sformatf
+shortint
+shortreal
+signame
+sp
+specparam
+splitme
+spp
+sqrt
+srcdir
+srcfile
+sscanf
+stderr
+stdin
+stdout
+stime
+stmts
+strcasecmp
+stringification
+stringified
+stringify
+struct
+structs
+subcell
+subcells
+subexpressions
+submodule
+submodules
+sv
+svBitVal
+svBitVecVal
+svGet
+svLogicVal
+svdpi
+swrite
+sys
+systemc
+testbench
+threadsafe
+threashold
+timeInc
+timeformat
+timeprecision
+timeskew
+timeunit
+tinshark
+tm
+tolower
+toolchain
+topcell
+toplevel
+toupper
+traceEverOn
+tran
+treei
+tri
+tristate
+tristates
+trunc
+txt
+typ
+typedef
+typedefed
+typedefs
+typename
+uint
+un
+undef
+undefineall
+undriven
+ungetc
+uniquified
+unistd
+unlink
+unlinked
+unopt
+unoptflat
+unoptimizable
+unroller
+unsized
+unsup
+untyped
+urandom
+uselib
+uwire
+uwires
+vc
+vcd
+vcddiff
+vcoverage
+vec
+ver
+verFiles
+verible
+verilate
+verilated
+verilator
+verilog
+verilogmod
+verimake
+vl
+vlopt
+vlt
+vltstd
+vluint
+vpi
+vpiLeftRange
+vpiModule
+vpiSize
+vpiSuppressVal
+vpiTimeUnit
+vpiType
+vpm
+vpp
+warmup
+waveforms
+whitespace
+widthed
+wreal
+writeb
+writeme
+writemem
+writememb
+writememh
+xin
+xml
+xnor
+xout
+xuejiazidi
+yanx
+yurivict
+zdave

docs/verilated.dox

@@ -0,0 +1,41 @@
+PROJECT_NAME           = "Verilog to Routing - ABC"
+INPUT                  = ../../include
+OUTPUT_DIRECTORY       = _build/doxygen/verilated
+
+EXTRACT_ALL            = NO
+EXTRACT_LOCAL_CLASSES  = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+FULL_PATH_NAMES        = NO
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES
+HIDE_FRIEND_COMPOUNDS  = YES
+HIDE_IN_BODY_DOCS      = YES
+HIDE_UNDOC_CLASSES     = YES
+HIDE_UNDOC_MEMBERS     = YES
+INTERNAL_DOCS          = NO
+OPTIMIZE_OUTPUT_FOR_C  = NO
+RECURSIVE              = NO
+SHOW_INCLUDE_FILES     = NO
+WARN_IF_UNDOCUMENTED   = NO
+
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = \
+                         "DOXYGEN=1" \
+                         "VL_ATTR_NORETURN=" \
+                         "VL_ATTR_PRINTF()=" \
+                         "VL_ATTR_WEAK=" \
+                         "VL_GUARDED_BY()=" \
+                         "VL_MT_SAFE=" \
+                         "VL_MT_SAFE_EXCLUDES()=" \
+                         "VL_MT_SAFE_POSTINIT=" \
+                         "VL_MT_UNSAFE=" \
+                         "VL_MT_UNSAFE_ONE=" \
+                         "VL_NOT_FINAL=" \
+                         "VL_PURE=" \
+                         "VL_REQUIRES()=" \
+                         "VL_THREAD_LOCAL=" \
+                         "__restrict=" \

docs/xml.rst

@@ -0,0 +1,80 @@
+|Logo|
+
+***************************
+Verilator XML Output Format
+***************************
+
+Introduction
+============
+
+This document describes Verilator's XML output. For more general
+information please see `verilator.org <https://verilator.org>`__.
+
+
+General
+=======
+
+Verilator's XML output is enabled with the ``--xml-only`` flag. It contains
+limited information about the elaborated design including files, modules,
+instance hierarchy, logic and data types. There is no formal schema since
+part of the structure of the XML document matches the compiled code which
+would require the schema to describe legal SystemVerilog structure. The
+intended usage is to enable other downstream tools to take advantage of
+Verilator's parser.
+
+
+Structure
+=========
+
+The XML document consists of 4 sections within the top level
+``verilator_xml`` element:
+
+``<files>``\ ... ``</files>``
+   This section contains a list of all design files read, including the
+   built-in constructs and the command line as their own entries. Each
+   ``<file>`` has an attribute ``id`` which is a short ASCII string
+   unique to that file. Other elements' ``loc`` attributes use this id
+   to refer to a particular file.
+
+``<module_files>``\ ... ``</module_files>``
+   All files containing Verilog module definitions are listed in this
+   section. This element's contents is a subset of the ``<files>``
+   element's contents.
+
+``<cells>``\ ... ``</cells>``
+   The cells section of the XML document contains the design instance
+   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.
+
+   -  ``name``: The instance name.
+
+   -  ``submodname``: The module name uniquified with particular
+      parameter values (if any).
+
+   -  ``hier``: The full hierarchy path.
+
+``<netlist>``\ ... ``</netlist>``
+   The netlist section contains a number of
+   ``<module>``\ ... ``</module>`` elements, each describing the
+   contents of that module, and a single ``<typetable>``\ ...
+   ``</typetable>`` element which lists all used types used within the
+   modules. Each type has a numeric ``id`` attribute that is referred to
+   by elements in the ``<module>`` elements using the ``dtype_id``
+   attribute.
+
+
+Distribution
+============
+
+Copyright 2020-2021 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.
+
+.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png