Version bump

* Tests:Add some more signals to t_const_opt_red.v

* Optimize bit op trees such as ~a[2] & a[1] & ~a[0] to 3'b010 == (3'111 & a)

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Apply clang-format

* Don't edit and-or tree.

* Call matchBitOpTree() after V3Expand does its job.

* Internals: Rename newNodep -> newp. No functional change is intended.

* Internals: Remove m_sels. No functional change is intended.

* Internals: Remove stringstream. No functional change is intended.

* Internals: Use V3Number::bitIs1(). No functional change is intended.

* Internals: Use V3Number instead of std::map. Resolved laek. Result should be same.

* Internals: Resolve overload of setPolarity. No functional change is intended.

* Internals: Pass failure reason. No functional change is intended.

* Internals: Add VNUser::toPtr(). No functional change is intended.

* Internals: Use user4 instead of std::map. No functional change is intended.

* Catch up with the AST style aftre V3Expand

* Internals: Rename Context to VarInfo. No functional change is intended.

* Add some more test case

* tests:Add stats to tests
Update stats in t_merge_cond.pl as matchBitopTree does some of them.

* insert CCast if necessary

* small optimization to remove redundant bit mask

* No quick exit even when unoptimizable node is found.

* Simplify removing redundant And

* simplify

* Revert "Internals: Add VNUser::toPtr(). No functional change is intended."

This reverts commit f98dce10db.

* Consider AstWordSel and cleanup

* Update test

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Update src/V3Const.cpp

Co-authored-by: Wilson Snyder <[email protected]>

* Apply clang-format

* Internals: rename variables. No functional change is intended.

Co-authored-by: Wilson Snyder <[email protected]>
Co-authored-by: github action <[email protected]>

.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,4 @@
+*.v linguist-language=SystemVerilog
+*.vh linguist-language=SystemVerilog
+*.sv linguist-language=SystemVerilog
+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.adoc)
+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.adoc)
+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.adoc)
+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.adoc.

.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.adoc, 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,44 @@
+# DESCRIPTION: Github actions config
+# This name is key to badges in README.adoc, so we use the name build
+# 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,100 @@
+# 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: ${{ matrix.os }}
+      CACHE_KEY: ${{ matrix.os }}-${{ matrix.compiler.cc }}-coverage
+    steps:
+
+    - uses: actions/checkout@v2
+
+    - 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 dependencies for build
+      env:
+        CI_BUILD_STAGE_NAME: build
+      run: ./ci/ci-install.bash
+
+    - name: Build Verilator
+      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
+        include:
+        - { test: dist, num: '' }
+    name: test-${{ matrix.test }}${{ matrix.num }}
+    runs-on: ubuntu-20.04
+    env:
+      CI_BUILD_STAGE_NAME: test
+      CI_RUNS_ON: ${{ matrix.os }}
+      CACHE_KEY: ${{ matrix.os }}-${{ matrix.compiler.cc }}-coverage
+    steps:
+
+    - uses: actions/checkout@v2
+
+    - 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,4 +1,8 @@
+\#*
+.#*
+.nfs*
 *~
+*.tidy
 *.old
 *.gz
 *.gz.uu
@@ -6,16 +10,30 @@
 *.info
 *.log
 *.1
+.*.swp
 *.tmp
 *.tex
+*.pdf
 /Makefile
+/.ccache
+/artifact/
 README
+TAGS
+autom4te.cache
+compile_commands.json
 config.cache
 config.status
 configure
 dddrun*
+doxygen-doc
 gdbrun*
+gmon.out
+ncverilog.history
+internals.txt
 verilator.txt
-verilator.pdf
 verilator_bin*
-autom4te.cache
+verilator_coverage_bin*
+verilator.pc
+verilator-config.cmake
+verilator-config-version.cmake
+**/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

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ 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.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser 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
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

MANIFEST.SKIP

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

Makefile.in

@@ -3,21 +3,15 @@
 #
 # This file is part of Verilator.
 #
-# Author: Wilson Snyder <wsnyder@wsnyder.org>
-#
-# Code available from: http://www.veripool.org/verilator
+# Code available from: https://verilator.org
 #
 #*****************************************************************************
 #
-# Copyright 2003-2009 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
 #
 #****************************************************************************/
 #
@@ -44,9 +38,6 @@
 #      reconstructed with this Makefile.  This typically includes
 #      everything deleted by distclean, plus more: C source files
 #      produced by Bison, tags tables, info files, and so on.
-#
-# make extraclean
-#      Still more severe - delete backup and autosave files, too.
 
 #### Start of system configuration section. ####
 
@@ -54,11 +45,14 @@ srcdir = @srcdir@
 VPATH = @srcdir@
 HOST = @HOST@
 
+DOXYGEN = doxygen
 INSTALL = @INSTALL@
 INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
 MAKEINFO = makeinfo
-TEXI2DVI = texi2dvi
+POD2TEXT = pod2text
+POD2LATEXFIX = $(srcdir)/src/pod2latexfix
+MKINSTALLDIRS = $(SHELL) $(srcdir)/src/mkinstalldirs
 PERL = @PERL@
 
 # Destination prefix for RPMs
@@ -71,7 +65,7 @@ exec_prefix = @exec_prefix@
 # Directory in which to install scripts.
 bindir = @bindir@
 
-# Directory in which to install scripts.
+# Directory in which to install manpages.
 mandir = @mandir@
 
 # Directory in which to install library files.
@@ -84,254 +78,467 @@ infodir = @infodir@
 # Generally ${prefix}/share/verilator
 pkgdatadir = @pkgdatadir@
 
+# Directory in which to install pkgconfig file
+# Generally ${prefix}/share/pkgconfig
+pkgconfigdir = @pkgconfigdir@
+
 # Directory in which to install data across multiple architectures
 datarootdir = @datarootdir@
 
 # Compile options
+CFG_WITH_CCWARN = @CFG_WITH_CCWARN@
 CFG_WITH_DEFENV = @CFG_WITH_DEFENV@
+CFG_WITH_LONGTESTS = @CFG_WITH_LONGTESTS@
+PACKAGE_VERSION = @PACKAGE_VERSION@
 
 #### End of system configuration section. ####
 ######################################################################
 
+.SUFFIXES:
+
 SHELL = /bin/sh
 
-SUBDIRS = src test_verilated test_c test_sc test_sp test_regress test_vcs
+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 verilator.txt verilator.html verilator.1 verilator.pdf
+INFOS = verilator.txt 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
-# Files to distribute.
-DISTBIN = $(wildcard bin/verilator-*)
 
-DISTFILES_INC = $(INFOS) .gitignore Artistic COPYING *.in *.ac \
-	Changes README TODO \
+DISTFILES_INC = $(INFOS) .gitignore \
+	*.in *.ac \
+	Artistic \
+	Changes \
+	LICENSE \
 	MANIFEST.SKIP \
-	bin/* \
-	install-sh configure mkinstalldirs *.texi \
-	include/verilated*.[chv]* \
+	README.adoc \
+	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 \
+	docs/.gitignore \
+	docs/CONTRIBUTING.adoc \
+	docs/CONTRIBUTORS \
+	docs/Makefile.in \
+	docs/TODO \
+	docs/doxygen-mainpage \
+	docs/doxygen.config \
+	docs/install.adoc \
+	docs/internals.adoc \
+	docs/verilator_logo.png \
+	docs/xml.adoc \
+	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/.*ignore src/*.in src/*.cpp src/*.[chly] \
+	src/astgen src/bisonpre src/*fix src/cppcheck_filtered \
+	src/config_rev \
+	src/vlcovgen src/mkinstalldirs \
+	src/.gdbinit \
 	src/*.pl src/*.pod \
+	examples/*/.*ignore examples/*/Makefile* \
+	examples/*/*.[chv]* examples/*/vl_* \
+	examples/*/CMakeLists.txt \
 	test_*/.*ignore test_*/Makefile* test_*/*.cpp \
-	test_*/*.pl test_*/*.v test_*/*.vc test_*/vlint \
-	test_verilated/vgen*.pl \
+	test_*/*.pl test_*/*.v test_*/*.vc test_*/*.vh \
+	test_regress/*.pl \
+	test_regress/Makefile \
+	test_regress/Makefile_obj \
+	test_regress/input.vc \
+	test_regress/CMakeLists.txt \
+	test_regress/t/t*/*.sv* \
+	test_regress/t/t*/*.v* \
+	test_regress/t/t*/*/*.sv* \
+	test_regress/t/t*/*/*.v* \
+	test_regress/t/t*/*.cpp \
+	test_regress/t/t*/CMakeLists.txt \
 	test_regress/t/*.cpp \
 	test_regress/t/*.h \
 	test_regress/t/*.dat \
 	test_regress/t/*.mem \
 	test_regress/t/*.out \
 	test_regress/t/*.pl \
+	test_regress/t/*.pf \
 	test_regress/t/*.v* \
-	verilator.* \
 
 INST_PROJ_FILES = \
 	bin/verilator \
+	bin/verilator_coverage \
+	bin/verilator_gantt \
 	bin/verilator_includer \
 	bin/verilator_profcfunc \
-	include/verilated.[chv]* \
 	include/verilated.mk \
-	include/verilatedos.[chv]* \
+	include/*.[chv]* \
+	include/gtkwave/*.[chv]* \
+	include/vltstd/*.[chv]* \
 
 INST_PROJ_BIN_FILES = \
-	verilator_bin \
-	verilator_bin_dbg \
+	bin/verilator_bin \
+	bin/verilator_bin_dbg \
+	bin/verilator_coverage_bin_dbg \
 
 DISTFILES := $(DISTFILES_INC)
 
-VL_INST_MAN_FILES = verilator.1
+EXAMPLES_FIRST = \
+	examples/make_hello_c \
+	examples/make_hello_sc \
 
+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
 all_nomsg: verilator_exe $(VL_INST_MAN_FILES)
 
 .PHONY:verilator_exe
-verilator_exe verilator_bin verilator_bin_dbg:
+.PHONY:verilator_bin
+.PHONY:verilator_bin_dbg
+.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) )
+	@echo "making verilator in src"
+	$(MAKE) -C src $(OBJCACHE_JOBS) $(CI_MAKE_SRC_TARGET)
 
 .PHONY:msg_test
-msg_test:
+msg_test: all_nomsg
 	@echo "Build complete!"
 	@echo
-	@echo "Type 'make test' to test."
+	@echo "Now type 'make test' to test."
 	@echo
 
-.PHONY:test
-ifeq ($(VERILATOR_AUTHOR_SITE),1)	# Local... Else don't burden users
-test: test_vcs test_c test_sc test_sp test_verilated test_regress
+.PHONY: test
+ifeq ($(CFG_WITH_LONGTESTS),yes)	# Local... Else don't burden users
+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: test_c test_sc test_sp
+test: smoke-test examples
 endif
 	@echo "Tests passed!"
 	@echo
-	@echo "Type 'make install' to install documentation."
+	@echo "Now type 'make install' to install."
+	@echo "Or type 'make' inside an examples subdirectory."
 	@echo
 
-test_vcs: all_nomsg
-	@(cd test_vcs && $(MAKE))
-test_c: all_nomsg
-	@(cd test_c && $(MAKE))
-test_c_debug: all_nomsg
-	@(cd test_c && $(MAKE) test_debug)
-test_sc: all_nomsg
-	@(cd test_sc && $(MAKE))
-test_sc_debug: all_nomsg
-	@(cd test_sc && $(MAKE) test_debug)
-test_sp: all_nomsg
-	@(cd test_sp && $(MAKE))
-test_sp_debug: all_nomsg
-	@(cd test_sp && $(MAKE) test_debug)
-test_verilated: all_nomsg
-	@(cd test_verilated && $(MAKE))
+smoke-test: all_nomsg
+	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 \
+	  $(MAKE) -C $$p VERILATOR_ROOT=`pwd` || exit 10; \
+	done
+
+.PHONY: docs
+docs: info
 
 info: $(INFOS)
 
-# Use --no-split to avoid creating filenames > 14 chars.
-verilator.1: bin/verilator
+%.1: ${srcdir}/bin/%
 	pod2man $< $@
 
-verilator.txt: bin/verilator
-	pod2text $< $@
+verilator.txt: ${srcdir}/bin/verilator
+	$(POD2TEXT) $< $@
 
-verilator.html: bin/verilator
+verilator.html: ${srcdir}/bin/verilator
 	pod2html $< >$@
 
-verilator.pdf: bin/verilator $(DISTCONFIG)
-	pod2latex --full --out verilator.tex bin/verilator
-	cat < verilator.tex \
-	   | sed 's/\\begin{document}/\\usepackage[left=1.7in,right=1.7in,top=1.3in,bottom=1.3in]{geometry}\n\\begin{document}/' \
-	   | sed 's/\\begin{document}/\\usepackage[pdftex,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,linkbordercolor={0 0 1}]{hyperref}\n\\begin{document}/' \
-	   | sed 's/\\begin{document}/\\usepackage{fancyhdr} \\pagestyle{fancy}\n\\begin{document}/' \
-	   | sed 's/\\begin{document}/\\setlength{\\parindent}{0pt} \\setlength{\\parskip}{\\baselineskip}\n\\begin{document}/' \
-	   | sed 's/\\begin{document}/\\title{$(DISTTITLE)} \\date{${DISTDATE}} \\author{Wilson Snyder\\\\ http:\/\/www.veripool.org}\n\\begin{document}/' \
-	   | sed 's/\\begin{document}/\\lhead[$(DISTTITLE)]{$(DISTTITLE)}\n\\begin{document}/' \
-	   | sed 's/\\tableofcontents/\\begin{titlepage} \\maketitle \\end{titlepage}\n\\tableofcontents/' \
-	   > verilator2.tex
+# PDF needs DIST variables; but having configure.ac as dependency isn't detected
+verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX)
+	pod2latex --full --out verilator.tex $<
+	$(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
 
-INSTALL: install.texi
-	$(MAKEINFO) -I$(srcdir) $(srcdir)/install.texi --output=$@ \
-	--no-headers --no-validate
-
-README: readme.texi
-	$(MAKEINFO) -I$(srcdir) $(srcdir)/readme.texi --output=$@ \
-	--no-headers --no-validate
-
-# See uninstall also
-VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg \
-	verilator_includer verilator_profcfunc
+# 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_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.
-installbin:
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(bindir)
-	( cd bin ; $(INSTALL_PROGRAM) verilator $(DESTDIR)$(bindir)/verilator )
-	( cd bin ; $(INSTALL_PROGRAM) verilator_profcfunc $(DESTDIR)$(bindir)/verilator_profcfunc )
-	( $(INSTALL_PROGRAM) verilator_bin $(DESTDIR)$(bindir)/verilator_bin )
-	( $(INSTALL_PROGRAM) verilator_bin_dbg $(DESTDIR)$(bindir)/verilator_bin_dbg )
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/bin
-	( cd bin ; $(INSTALL_PROGRAM) verilator_includer $(DESTDIR)$(pkgdatadir)/bin/verilator_includer )
 
-installman:
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(mandir)/man1
-	for p in $(VL_INST_MAN_FILES) ; do \
-	  $(INSTALL_PROGRAM) $$p $(DESTDIR)$(mandir)/man1/$$p; \
+VL_INST_INC_BLDDIR_FILES = \
+	include/verilated_config.h \
+	include/verilated.mk \
+
+# 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:
+	$(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 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
+installman: $(VL_INST_MAN_FILES)
+	$(MKINSTALLDIRS) $(DESTDIR)$(mandir)/man1
+	for p in $^ ; do \
+	  $(INSTALL_DATA) $$p $(DESTDIR)$(mandir)/man1/$$p; \
 	done
 
 installdata:
-	$(SHELL) ${srcdir}/mkinstalldirs $(DESTDIR)$(pkgdatadir)/examples
-	cp -r include $(DESTDIR)$(pkgdatadir)
-	cp -r test_c  $(DESTDIR)$(pkgdatadir)/examples
-	cp -r test_sc $(DESTDIR)$(pkgdatadir)/examples
-	cp -r test_sp $(DESTDIR)$(pkgdatadir)/examples
-	cp -r test_v  $(DESTDIR)$(pkgdatadir)/examples
+	$(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
+	cd $(srcdir) \
+	; for p in $(VL_INST_INC_SRCDIR_FILES) ; do \
+	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
+	done
+	$(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
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgconfigdir)
+	$(INSTALL_DATA) verilator.pc $(DESTDIR)$(pkgconfigdir)
+	$(INSTALL_DATA) verilator-config.cmake $(DESTDIR)$(pkgdatadir)
+	$(INSTALL_DATA) verilator-config-version.cmake $(DESTDIR)$(pkgdatadir)
 
-VL_INST_DATA_FILES = verilator.1
-install: all_nomsg installbin installman installdata install-msg
+# We don't trust rm -rf, so rmdir instead as it will fail if user put in other files
+uninstall:
+	-cd $(DESTDIR)$(bindir) && rm -f $(VL_INST_BIN_FILES)
+	-cd $(DESTDIR)$(pkgdatadir)/bin && rm -f $(VL_INST_BIN_FILES)
+	-cd $(DESTDIR)$(mandir)/man1 && rm -f $(VL_INST_MAN_FILES)
+	-cd $(DESTDIR)$(pkgdatadir) && rm -f $(VL_INST_INC_BLDDIR_FILES)
+	-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/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)
+
+install: all_nomsg install-all
+install-all: installbin installman installdata install-msg
 
 install-here: installman ftp
 
 ifeq ($(VERILATOR_AUTHOR_SITE),1)	# Local... Else don't burden users
-DIRPROJECT := $(shell project_dir --project)
+DISTNAMEREV = $(shell sed -e '/DTVERSION/!d' -e 's/.*verilator_\([^"]*\).*/\1/' -e q ${srcdir}/src/config_rev.h)
+
+VERILATOR_CAD_DIR = $(CAD_DIR)/verilator/$(DISTNAMEREV)/$(DIRPROJECT_ARCH)
 INST_PROJ_CVS = cp_if_cvs_diff
 
-install-project: dist
-	@echo "Install-project to $(DIRPROJECT)"
-	strip verilator_bin*
-	$(MAKE) install-project-quick
-	for p in verilator.1 ; do \
-	  $(INSTALL_PROGRAM) -m 0666 $$p $(DIRPROJECT_PREFIX)/man/man1/$$p; \
+install-cadtools: dist
+	@echo "Install-project to $(CAD_DIR)"
+	strip bin/verilator_bin*
+	strip bin/verilator_coverage_bin*
+	$(MAKE) install-cadtools-quick
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/man/man1
+	for p in $(VL_INST_MAN_FILES) ; do \
+	  $(INSTALL_DATA) $$p $(VERILATOR_CAD_DIR)/man/man1/$$p; \
 	done
-	$(INST_PROJ_CVS) $(DISTNAME).tgz $(DIRPROJECT)/hw/utils/verilator/verilator.tgz
+	$(INST_PROJ_CVS) $(DISTNAME).tgz $(VERILATOR_CAD_DIR)/verilator.tgz
 	rm $(DISTNAME).tgz
 
-install-project-quick:
+install-cadtools-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)"
+	@echo "Install-cadtools-quick (no strip) to $(VERILATOR_CAD_DIR)"
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/include/gtkwave
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/include/vltstd
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/bin
 	for p in $(INST_PROJ_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(DIRPROJECT)/hw/utils/verilator/$$p; \
+	  $(INST_PROJ_CVS) $$p $(VERILATOR_CAD_DIR)/$$p; \
 	done
 	for p in $(INST_PROJ_BIN_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(DIRPROJECT)/hw/utils/verilator/$$p-$(DIRPROJECT_ARCH); \
+	  $(INST_PROJ_CVS) $$p $(VERILATOR_CAD_DIR)/$$p; \
 	done
+
+# VERILATOR_AUTHOR_SITE
 endif
 
+# Use --xml flag to see the cppcheck code to use for suppression
+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=nullPointerRedundantCheck
+CPPCHECK_FLAGS += --xml
+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 -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
+	scan-build $(MAKE) -k verilator_coverage_bin_dbg verilator_bin_dbg
+
+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)
+
+YAPF = yapf3
+YAPF_FLAGS = -i
+YAPF_FILES = \
+	examples/xml_py/vl_file_copy \
+	examples/xml_py/vl_hier_graph \
+	src/astgen \
+	src/bisonpre \
+	src/config_rev \
+	src/cppcheck_filtered \
+	src/flexfix \
+	src/vlcovgen \
+	nodist/code_coverage \
+	nodist/code_coverage.dat \
+	nodist/dot_importer \
+	nodist/fuzzer/actual_fail \
+	nodist/fuzzer/generate_dictionary \
+	nodist/install_test \
+
+yapf:
+	$(YAPF) $(YAPF_FLAGS) $(YAPF_FILES)
+
+format-pl-exec:
+	-chmod a+x test_regress/t/*.pl
+
+
 ftp: info
 
 install-msg:
-	@echo "Installed!"
 	@echo
-	@echo "Add to your startup file (for bash or csh, as appropriate):"
-	@echo "	export VERILATOR_ROOT="`pwd`
-	@echo "	setenv VERILATOR_ROOT "`pwd` " ; export VERILATOR_ROOT "
+	@echo "Installed binaries to $(DESTDIR)$(bindir)/verilator"
+	@echo "Installed man to $(DESTDIR)$(mandir)/man1"
+	@echo "Installed examples to $(DESTDIR)$(pkgdatadir)/examples"
 	@echo
-	@echo "See 'verilator.txt' for documentation."
+	@echo "For documentation see 'man verilator' or 'verilator --help'"
+	@echo "For forums and to report bugs see https://verilator.org"
 	@echo
 
-uninstall:
-	-cd $(DESTDIR)$(mandir)/man1 && rm -f $(VL_INST_MAN_FILES)
-	-cd $(DESTDIR)$(bindir) && rm -f $(VL_INST_BIN_FILES)
-	-rm -f $(DESTDIR)$(pkgdatadir)
+IN_WILD := ${srcdir}/*.in ${srcdir}/*/*.in
 
-# autoheader might not change config_build.h.in, so touch a stamp file.
-IN_WILD := ${srcdir}/*.in ${srcdir}/*/*.in ${srcdir}/*/*/*.in \
-	*.in */*.in */*.in
-
-${srcdir}/config_build.h.in: stamp-h.in
-${srcdir}/stamp-h.in: configure.ac $(wildcard $(IN_WILD))
+# autoheader might not change config_build.h.in, so touch it
+${srcdir}/config_build.h: ${srcdir}/config_build.h.in configure
 	cd ${srcdir} && autoheader
-	echo timestamp > ${srcdir}/stamp-h.in
-config_build.h: stamp-h
-stamp-h: config_build.h.in config.status
-	./config.status
-Makefile: Makefile.in config.status
-	./config.status
-src/Makefile: src/Makefile.in config.status
+	touch $@
+Makefile: Makefile.in config.status $(IN_WILD)
 	./config.status
+src/Makefile: src/Makefile.in Makefile
 config.status: configure
 	./config.status --recheck
+
 configure: configure.ac
+ifeq ($(CFG_WITH_CCWARN),yes)	# Local... Else don't burden users
+	autoconf --warnings=all
+else
 	autoconf
+endif
 
 maintainer-clean::
 	@echo "This command is intended for maintainers to use;"
-	@echo "rebuilding the deleted files requires makeinfo."
-	rm -f *.info* $(INFOS) faq.html verilator.html 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::
@@ -340,17 +547,29 @@ 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 nodist/fuzzer/dictionary
+	rm -rf nodist/obj_dir
 
 distclean maintainer-clean::
-	rm -f Makefile config.status config.cache config.log verilator_bin* TAGS
-	rm -f include/verilated.mk
+	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*
+	rm -f include/verilated.mk include/verilated_config.h
 
-TAGFILES=${srcdir}/*/*.cpp ${srcdir}/*/*.h ${srcdir}/*/[a-z]*.in \
-	${srcdir}/[a-z]*.in ${srcdir}/*.texi
+TAGFILES=${srcdir}/*/*.cpp ${srcdir}/*/*.h ${srcdir}/*/*.in \
+	${srcdir}/*.in ${srcdir}/*.pod
 
 TAGS:	$(TAGFILES)
 	etags $(TAGFILES)
 
+.PHONY: doxygen
+
+doxygen:
+	$(MAKE) -C docs doxygen
+
 ######################################################################
 # Test targets
 
@@ -362,14 +581,12 @@ dist-file-list:
 ######################################################################
 # Distributions
 
-DISTCONFIG = src/config_build.h.in
-
-DISTTITLE := $(shell sed -e '/DTVERSION/!d' -e 's/[^0-9]*\([0-9.a-z]*\).*/verilator-\1/' -e 's/v/V/' -e q $(DISTCONFIG))
-DISTNAME := $(shell sed -e '/DTVERSION/!d' -e 's/[^0-9]*\([0-9.a-z]*\).*/verilator-\1/' -e q $(DISTCONFIG))
-DISTDATEPRE := $(shell sed -e '/DTVERSION/!d' -e 's/.*\([1-2][0-9][0-9][0-9].[0-9]*[0-9].[0-9]*[0-9]\).*/\1/' -e q $(DISTCONFIG))
+DISTTITLE := Verilator $(word 1,$(PACKAGE_VERSION))
+DISTNAME := verilator-$(word 1,$(PACKAGE_VERSION))
+DISTDATEPRE := $(word 2,$(PACKAGE_VERSION))
+DISTDATE := $(subst /,-,$(DISTDATEPRE))
 
 DISTTAGNAME := $(subst .,_,$(subst -,_,$(DISTNAME)))
-DISTDATE := $(subst /,-,$(DISTDATEPRE))
 
 tag:
 	svnorcvs tag $(DISTTAGNAME)

README.adoc

@@ -0,0 +1,154 @@
+// Github doesn't render images unless absolute URL
+:!toc:
+
+ifdef::env-github[]
+image:https://img.shields.io/badge/License-LGPL%20v3-blue.svg[license LGPLv3,link=https://www.gnu.org/licenses/lgpl-3.0]
+image:https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg[license Artistic-2.0,link=https://opensource.org/licenses/Artistic-2.0]
+image:https://api.codacy.com/project/badge/Grade/fa78caa433c84a4ab9049c43e9debc6f[Code Quality,link=https://www.codacy.com/gh/verilator/verilator]
+image:https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg[Coverage,link=https://codecov.io/gh/verilator/verilator]
+image:https://github.com/verilator/verilator/workflows/build/badge.svg[Build Status (GitHub),link=https://github.com/verilator/verilator/actions?query=workflow%3Abuild]
+endif::[]
+
+ifdef::env-github[]
+:link_verilator_contributing: link:docs/CONTRIBUTING.adoc
+:link_verilator_install: link:docs/install.adoc
+endif::[]
+ifndef::env-github[]
+:link_verilator_contributing: https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.adoc
+:link_verilator_install: https://verilator.org/install
+endif::[]
+:link_verilator_commercial_support: https://verilator.org/verilator_commercial_support
+
+== Welcome to Verilator
+
+[cols="a,a",indent=0,frame="none",grid="rows"]
+|===
+^.^| *Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.*
++++ <br/> +++ &bullet; Accepts synthesizable Verilog or SystemVerilog
++++ <br/> +++ &bullet; Performs lint code-quality checks
++++ <br/> +++ &bullet; Compiles into multithreaded {cpp}, or SystemC
++++ <br/> +++ &bullet; Creates XML to front-end your own tools
+<.^|image:https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200]
+
+>.^|image:https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png[,388,178]
+^.^| *Fast*
++++ <br/> +++ &bullet; Outperforms many commercial simulators
++++ <br/> +++ &bullet; Single- and multi-threaded output models
+
+^.^| *Widely Used*
++++ <br/> +++ &bullet; Wide industry and academic deployment
++++ <br/> +++ &bullet; Out-of-the-box support from Arm, and RISC-V vendor IP
+<.^|image:https://www.veripool.org/img/verilator_usage_400x200-min.png[,400,200]
+
+>.^|image:https://www.veripool.org/img/verilator_community_400x125-min.png[,400,125]
+^.^| *Community Driven & Openly Licensed*
++++ <br/> +++ &bullet; Guided by the https://chipsalliance.org/[CHIPS Alliance] and https://www.linuxfoundation.org/[Linux Foundation]
++++ <br/> +++ &bullet; Open, and free as in both speech and beer
++++ <br/> +++ &bullet; More simulation for your verification budget
+
+^.^| *Commercial Support Available*
++++ <br/> +++ &bullet; Commercial support contracts
++++ <br/> +++ &bullet; Design support contracts
++++ <br/> +++ &bullet; Enhancement contracts
+<.^|image:https://www.veripool.org/img/verilator_support_400x125-min.png[,400,125]
+
+|===
+
+== 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 {cpp}/SystemC wrapper file, which instantiates the
+"Verilated" model of the user's top level module.  These {cpp}/SystemC
+files are then compiled by a {cpp} 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 http://iverilog.icarus.com[Icarus Verilog] for
+this.)  However, if you are looking for a path to migrate SystemVerilog to
+{cpp} or SystemC, or your team is comfortable writing just a touch of {cpp}
+code, Verilator is the tool for you.
+
+== Performance
+
+Verilator does not simply convert Verilog HDL to {cpp} or SystemC.  Rather,
+Verilator compiles your code into a much faster optimized and optionally
+thread-partitioned model, which is in turn wrapped inside a
+{cpp}/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 http://iverilog.icarus.com[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.
+
+For more information on how Verilator stacks up to some of the other
+closed-sourced and open-sourced Verilog simulators, see the
+https://www.veripool.org/verilog_sim_benchmarks.html[Verilog Simulator
+Benchmarks].  (If you benchmark Verilator, please see the notes in the
+https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)], and also
+if possible post on the forums the results; there may be additional tweaks
+possible.)
+
+== Installation & Documentation
+
+For more information:
+
+* {link_verilator_install}[Verilator installation and package directory
+  structure]
+
+* https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
+or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)]
+
+* https://github.com/verilator/verilator-announce[Subscribe to verilator announcements]
+
+* https://verilator.org/forum[Verilator forum]
+
+* https://verilator.org/issues[Verilator issues]
+
+== Support
+
+Verilator is a community project, guided by the
+https://chipsalliance.org/[CHIPS Alliance] under the
+https://www.linuxfoundation.org/[Linux Foundation].
+
+We appreciate and welcome your contributions in whatever form; please see
+{link_verilator_contributing}[Contributing to Verilator].  Thanks to our
+https://verilator.org/verilator_doc.html#CONTRIBUTORS[Contributors and
+Sponsors].
+
+Verilator also supports and encourages commercial support models and
+organizations; please see {link_verilator_commercial_support}[Verilator
+Commercial Support].
+
+== Related Projects
+
+* http://gtkwave.sourceforge.net/[GTKwave] - Waveform viewer for Verilator
+traces.
+
+* http://iverilog.icarus.com[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
+https://verilator.org/issues[Verilator 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.

TODO

@@ -1,154 +0,0 @@
-// DESCRIPTION: Verilator: List of To Do issues.
-//
-// Copyright 2004-2009 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.
-
-
-Features:
-	Finish 3.400 new ordering fixes
-	Latch optimizations {Need here}
-	Task I/Os connecting to non-simple variables.
-	Fix nested casez statements expanding into to huge C++. [JeanPaul Vanitegem]
-	Fix FileLine memory inefficiency
-	Fix ordering of each bit separately in a signal (mips)
-		assign b[3:0] = b[7:4];  assign b[7:4] = in;
-	Support gate primitives/ cell libraries from xilinx, etc
-	Assign dont_care value to an 1'bzzz assignment
-	Function to eval combo logic after /*verilator public*/ functions [gwaters]
-	Support generated clocks (correctness)
-	?gcov coverage
-	Selectable SystemC types based on widths (see notes below)
-	Compile time
-		Inline first level trace routines
-	Coverage
-		Points should be per-scope like everything else rather then per-module
-		Expression coverage (see notes)
-	Constant functions for widths, etc, IE   "input [log2(PARAM):0] xx;"
-	More Verilog 2001 Support
-		(* *) Attributes  (just ignore -- preprocessor?)
-		Real numbers (NEVER)
-		Recursive functions (NEVER)
-		Verilog configuration files (NEVER)
-	DPI to define C/C++ calls from Verilog
-
-Long-term Features
-	Assertions
-	VHDL parser  [Philips]
-	Tristate support
-	SystemPerl integration
-	Multithreaded execution
-	Front end parser integration into Verilog-Perl like Netlist
-
-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
-
-Usability:
-	Better reporting of unopt problems, including what lines of code
-	Report more errors (all of them?) before exiting [Eugene Weber]
-
-Internal Code:
-	Eliminate the AstNUser* passed to all visitors; its only needed in V3Width,
-	and removing it will speed up and simplify all the other code.
-	V3Graph should be templated container type, taking in Vertex + Edge types
-
-Performance:
-	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
-	Multithreaded execution
-	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
-	Allow Split of case statements without a $display/$stop
-	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)
-
-	All of the temp vars that get set, exp pre_ vars and never feedback
-	(not flops) don't need to be stored in the structs, but instead can
-	be per-invocation, and even better register-colored-like to reuse
-	the space.  This will greatly reduce the data footprint.
-
-
-//**********************************************************************
-//* Detailed notes on 'todo' features
-
-Selectable SystemC types based on widths (see notes below)
-	Statements:
-		verilator sc_type    uint32_t  {override specific I/O signals}
-		verilator sc_typedef width 1     bool
-		verilator sc_typedef width 2-32  uint32_t
-		verilator sc_typedef width 33-64 uint64_t
-		verilator sc_typedef width 65+   sc_bv<width>	//<< programmable width
-	Replace `systemc_clock, --pins64
-	Have accessor function with type overloading to get or set the pin value.
-	(Get rid of getdatap mess?)
-
-//**********************************************************************
-//* Eventual tristate bus Stuff allowed (old verilator)
-
- 1) Tristate assignments must be continuous assignments
-    The RHS of a tristate assignment can be the following
-       a) a node (tristate or non-tristate)
-       b) a constant (must be all or no z's)
-	    x'b0, x'bz, x{x'bz}, x{x'b0} -> are allowed
-       c) a conditional whose possible values are (a) or (b)
-
- 2) One can lose that fact that a node is a tristate node.  This happens
-    if a tristate node is assigned to a 'standard' node, or is used on
-    RHS of a conditional. The following infer tristate signals:
-       a) inout <SIGNAL>
-       b) tri <SIGNAL>
-       c) assigning to 'Z' (maybe through a conditional)
-    Note: tristate-ness of an output port determined only by
-          statements in the module (not the instances it calls)
-
- 4) Tristate variables can't be multidimensional arrays
- 5) Only check tristate contention between modules (not within!)
- 6) Only simple compares with 'Z' are allowed (===)
-

bin/verilator_coverage

@@ -0,0 +1,300 @@
+#!/usr/bin/env perl
+######################################################################
+#
+# 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.
+#
+######################################################################
+
+require 5.006_001;
+use warnings;
+use Getopt::Long;
+use FindBin qw($RealBin $RealScript);
+use IO::File;
+use Pod::Usage;
+use Cwd qw(abs_path getcwd);
+
+use strict;
+use vars qw($Debug @Opt_Verilator_Sw);
+
+#######################################################################
+#######################################################################
+# main
+
+autoflush STDOUT 1;
+autoflush STDERR 1;
+
+$Debug = 0;
+
+# No arguments can't do anything useful.  Give help
+if ($#ARGV < 0) {
+    pod2usage(-exitstatus=>2, -verbose=>0);
+}
+
+# We sneak a look at the flags so we can do some pre-environment checks
+# All flags will hit verilator...
+foreach my $sw (@ARGV) {
+    $sw = "'$sw'" if $sw =~ m![^---a-zA-Z0-9_/\\:.+]!;
+    push @Opt_Verilator_Sw, $sw;
+}
+
+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
+    )) {
+    pod2usage(-exitstatus=>2, -verbose=>0);
+}
+
+# Normal, non gdb
+run(verilator_coverage_bin()
+    ." ".join(' ',@Opt_Verilator_Sw));
+
+#----------------------------------------------------------------------
+
+sub usage {
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+}
+
+sub debug {
+    shift;
+    my $level = shift;
+    $Debug = $level||3;
+}
+
+#######################################################################
+#######################################################################
+# Builds
+
+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");
+    if (defined($ENV{VERILATOR_ROOT})) {
+        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"
+            || -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;
+}
+
+#######################################################################
+#######################################################################
+# Utilities
+
+sub run {
+    # Run command, check errors
+    my $command = shift;
+    $! = undef;  # Cleanup -x
+    print "\t$command\n" if $Debug>=3;
+    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;
+            }
+        }
+        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
+    }
+}
+
+#######################################################################
+#######################################################################
+package main;
+__END__
+
+=pod
+
+=head1 NAME
+
+verilator_coverage - Verilator coverage analyzer
+
+=head1 SYNOPSIS
+
+    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 processes Verilator coverage reports.
+
+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.
+
+Additional Verilog-standard arguments specify the search paths necessary to
+find the source code that the coverage analysis was performed on.
+
+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.
+
+For Verilog conditions that should never occur, you should add a $stop
+statement.  This will remove the coverage during the next build.
+
+=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 in verilator_coverage data format.
+This is useful in scripts to combine many sequential runs into one master
+coverage file.
+
+=item --write-info I<filename.info>
+
+Specifies the aggregate coverage results, summed across all the files,
+should be written to the given filename in C<lcov> .info format.
+This may be used to use C<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.
+
+=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
+
+=head1 DISTRIBUTION
+
+The latest version is available from L<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.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+=head1 AUTHORS
+
+Wilson Snyder <[email protected]>
+
+=head1 SEE ALSO
+
+C<verilator>, C<lcov>
+
+L<verilator_coverage --help> which is the source for this document.
+
+=cut
+
+######################################################################

bin/verilator_difftree

@@ -1,19 +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);
-
-#======================================================================
-
+use vars qw($Debug);
 
 #======================================================================
 # main
@@ -24,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";
 }
@@ -41,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";
 }
@@ -55,49 +49,89 @@ 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);
+        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");
 }
 
 sub diff_file {
     my $a = shift;
     my $b = shift;
     # Compare the two tree files
-    my $tmp_a = "/tmp/$$.a";
-    my $tmp_b = "/tmp/$$.b";
+    (my $short_a = $a) =~ s/[^a-zA-Z0-9.]+/_/g;
+    (my $short_b = $b) =~ s/[^a-zA-Z0-9.]+/_/g;
+    my $tmp_a = "/tmp/${$}_${short_a}.a";
+    my $tmp_b = "/tmp/${$}_${short_b}.b";
 
-    filter ($a, $tmp_a);
-    filter ($b, $tmp_b);
+    my $vera = version_from($a);
+    my $verb = version_from($b);
+    my $verCvt = (($vera < 0x3900 && $verb >= 0x3900)
+                  || ($vera >= 0x3900 && $verb < 0x3900));
+
+    filter($a, $tmp_a, $verCvt);
+    filter($b, $tmp_b, $verCvt);
     system("diff -u $tmp_a $tmp_b");
     unlink $tmp_a;
     unlink $tmp_b;
 }
 
+sub version_from {
+    my $fn = shift;
+    # Return dump format
+    my $f1 = IO::File->new ($fn) or die "%Error: $! $fn,";
+    while (defined (my $line=$f1->getline())) {
+        last if $. > 10;
+        return hex $1 if $line =~ /\(format (0x[0-9.]+)\)/;
+    }
+    return 1.0;
+}
+
 sub filter {
     my $fn1 = shift;
     my $fn2 = shift;
+    my $verCvt = shift;
     # Remove hex numbers before diffing
     my $f1 = IO::File->new ($fn1) or die "%Error: $! $fn1,";
     my $f2 = IO::File->new ($fn2,"w") or die "%Error: $! $fn2,";
     while (defined (my $line=$f1->getline())) {
-	next if $line =~ / This=/;
-	$line =~ s/0x[a-f0-9]+/0x/g;
-	$line =~ s/<e[0-9]+\#?>/<e>/g;
-	$line =~ s/{\d+}/{}/g if !$Opt_Lineno;
-	print $f2 $line;
+      same_line:
+        next if $line =~ / This=/;
+        $line =~ s/0x[a-f0-9]+/0x/g;
+        $line =~ s/<e[0-9]+\#?>/<e>/g;
+        $line =~ s/{[a-z]*\d+}/{}/g if !$Opt_Lineno;
+        if ($verCvt) {
+            next if $line =~ /^     NETLIST/;
+            if ($line =~ /: ([A-Z]+) /) {
+                my $type = $1;
+                next if $type =~ 'DTYPE';
+                if ($type eq 'TYPETABLE' || $type eq 'RANGE') {
+                    $line =~ /^(\s+\S+:) /; my $prefix = $1;
+                    while (defined ($line=$f1->getline())) {
+                        next if $line =~ /^\s+[a-z]/;  # Table body
+                        next if $line =~ /^${prefix}[0-9]:/;
+                        goto same_line;
+                    }
+                    next;
+                }
+            }
+        }
+        print $f2 $line;
     }
     $f1->close;
     $f2->close;
@@ -106,8 +140,8 @@ sub filter {
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval => 2);
-    exit (1);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
 }
 
 sub debug {
@@ -117,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";
     }
 }
 
@@ -172,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-2009 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
 
@@ -190,5 +227,5 @@ C<verilator>
 
 ######################################################################
 ### Local Variables:
-### compile-command: "$V4/bin/verilator_difftree  $V4/test_c/obj_dir/V*_03_*.tree $V4N/test_c/obj_dir/V*_03_*.tree"
+### compile-command: "$V4/bin/verilator_difftree  {$V4D,$V4}/test_regress/obj_dir/t_EXAMPLE/V*_03_*.tree"
 ### End:

bin/verilator_gantt

@@ -0,0 +1,640 @@
+#!/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
+
+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.
+
+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.
+
+=head1 USAGE
+
+  Build with --prof-threads.
+
+  Run a sim with +verilator+prof+threads+window 2.
+
+  This will create profile_threads.dat.
+
+  Then run:
+
+  verilator_gantt profile_threads.dat
+
+  The report will be printed on standard output, this also generates
+  profile_threads.vcd
+
+  View profile_threads.vcd in a waveform viewer.
+
+=head1 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.
+
+=head1 ARGUMENTS
+
+=over 4
+
+=item I<filename>
+
+The filename to read data from, defaults to "profile_threads.dat".
+
+=item --help
+
+Displays this message and program version and exits.
+
+=item --scale I<n>
+
+On the X-axis of the generated Gantt chart, each character represents this
+many time units. (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.
+
+=item --no-vcd
+
+=item --vcd I<filename>
+
+Set output filename for vcd dump, or disable. Default is
+verilator_gantt.vcd.
+
+=back
+
+=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 AUTHORS
+
+Wilson Snyder <[email protected]>
+
+=head1 SEE ALSO
+
+C<verilator>
+
+=cut
+
+######################################################################
+### Local Variables:
+### compile-command: "$V4/bin/verilator_gantt $V4/test_regress/obj_vltmt/t_gantt/vlt_sim.log"
+### End:

bin/verilator_includer

@@ -1,15 +1,20 @@
-: # -*-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-2009 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;
 use warnings;
+print "// DESCR"."IPTION: Generated by verilator_includer via makefile\n";
 foreach my $param (@ARGV) {
-    print "#include \"$param\"\n"
+    if ($param =~ /^-D([^=]+)=(.*)/) {
+        print "#define $1 $2\n"
+    } else {
+        print "#include \"$param\"\n"
+    }
 }

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);
-    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,21 @@ 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_].*)$/) {
+            my $pct=$1; my $sec=$2; my $calls=1; my $func=$3;
+            $funcs{$func}{pct} += $pct;
+            $funcs{$func}{sec} += $sec;
+            $funcs{$func}{calls} += $calls;
+        }
     }
     $fh->close;
 
@@ -80,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);
 
@@ -91,67 +97,81 @@ 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;
-	    } 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;
-	}
+    foreach my $type (qw(type design module)) {
+        my $missing = 100;
+        foreach (sort (keys %{$groups{$type}})) {
+            $missing -= $groups{$type}{$_};
+        }
+        if ($missing) {
+            $groups{$type}{"\377Unaccounted for/rounding error"} = $missing;
+        }
 
-	print("Overall summary by $type:\n");
-	printf("  %-6s  %s\n","% time",$type);
-	foreach my $what (sort (keys %{$groups{$type}})) {
-	    (my $pwhat = $what) =~ s/^\377//;  # Just used to establish sort order
-	    printf("  %6.2f  %s\n", $groups{$type}{$what}, $pwhat);
-	}
-	print("\n");
+        print("Overall summary by $type:\n");
+        printf("  %-6s  %s\n","% time",$type);
+        foreach my $what (sort (keys %{$groups{$type}})) {
+            (my $pwhat = $what) =~ s/^\377//;  # Just used to establish sort order
+            printf("  %6.2f  %s\n", $groups{$type}{$what}, $pwhat);
+        }
+        print("\n");
     }
 
     print("Verilog code profile:\n");
     print("   These are split into three categories:\n");
     print("      C++:     Time in non-Verilated C++ code\n");
+    print("      Prof:    Time in profile overhead\n");
     print("      VBlock:  Time attributable to a block in a Verilog file and line\n");
     print("      VCommon: Time in a Verilated module, due to all parts of the design\n");
+    print("      VLib:    Time in Verilated common libraries, called by the Verilated code\n");
     print("\n");
 
     print("  %   cumulative   self              \n");
@@ -159,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);
     }
 }
 
@@ -177,11 +197,11 @@ __END__
 
 =head1 NAME
 
-verilator_profcfunc - Read gprof report created with --profile-cfuncs
+verilator_profcfunc - Read gprof report created with --prof-cfuncs
 
 =head1 SYNOPSIS
 
-  verilator --profile-cfuncs ....
+  verilator --prof-cfuncs ....
   gcc --ggdb -pg ....
   {run executable}
   gprof
@@ -190,8 +210,8 @@ verilator_profcfunc - Read gprof report created with --profile-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
---profile-cfuncs, and a report printed showing the percentage of time, etc,
+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
@@ -206,11 +226,14 @@ Displays this message and program version and exits.
 
 =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-2009 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.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 AUTHORS
 

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,141 @@
+#!/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/4
+      ;;
+    coverage-vlt-1)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=1/4
+      ;;
+    coverage-vlt-2)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=2/4
+      ;;
+    coverage-vlt-3)
+      nodist/code_coverage --stages 1- --scenarios=--vlt --hashset=3/4
+      ;;
+    coverage-vltmt-0)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=0/4
+      ;;
+    coverage-vltmt-1)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=1/4
+      ;;
+    coverage-vltmt-2)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=2/4
+      ;;
+    coverage-vltmt-3)
+      nodist/code_coverage --stages 1- --scenarios=--vltmt --hashset=3/4
+      ;;
+    *)
+      fatal "Unknown test: $TESTS"
+      ;;
+  esac
+  # Upload coverage data to codecov.io
+  if [[ $TESTS == coverage-* ]]; then
+    bash <(curl -s https://codecov.io/bash) -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.adoc

@@ -0,0 +1,49 @@
+= Verilator Docker Build Environment
+
+This Verilator Build 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
+https://hub.docker.com/repository/docker/verilator/verilator-buildenv[docker hub].
+
+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.adoc

@@ -0,0 +1,59 @@
+= 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,77 +1,475 @@
-dnl DESCRIPTION: Process this file with autoconf to produce a configure script.
-dnl
-dnl Copyright 2003-2009 by Wilson Snyder. Verilator is free software; you can
-dnl redistribute it and/or modify it under the terms of either the GNU Lesser
-dnl General Public License Version 3 or the Perl Artistic License Version 2.0.
+# DESCRIPTION: Process this file with autoconf to produce a configure script.
+#
+# 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],[4.110 2021-02-25],
+        [https://verilator.org],
+        [verilator],[https://verilator.org])
+# When releasing, also update header of Changes file
+# and commit using "devel release" or "Version bump" message
+# Then 'make maintainer-dist'
 
-AC_INIT(src/Verilator.cpp)
 AC_CONFIG_HEADER(src/config_build.h)
+AC_CONFIG_FILES(Makefile docs/Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake)
 
-dnl Special Substitutions
-AC_ARG_ENABLE(defenv,
-   [AS_HELP_STRING([--disable-defenv], [disable hardcoded default environment variables])],
-   CFG_WITH_DEFENV=$enableval,
-   CFG_WITH_DEFENV=yes)
+# Version
+AC_MSG_RESULT([configuring for $PACKAGE_STRING])
+PACKAGE_VERSION_NUMBER=`AS_ECHO("$PACKAGE_VERSION") | sed 's/ .*//g'`
+AC_SUBST(PACKAGE_VERSION_NUMBER)
+
+# Ignore automake flags passed by Ubuntu builds
+AC_ARG_ENABLE([dependency-tracking],
+              [AS_HELP_STRING([--disable-dependency-tracking], [ignored])])
+AC_ARG_ENABLE([maintainer-mode],
+              [AS_HELP_STRING([--enable-maintainer-mode], [ignored])])
+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) in Verilator binary])],
+              [case "${enableval}" in
+                yes) CFG_WITH_DEFENV=yes ;;
+                no)  CFG_WITH_DEFENV=no ;;
+                *)   AC_MSG_ERROR([bad value ${enableval} for --disable-defenv]) ;;
+               esac],
+              CFG_WITH_DEFENV=yes)
 AC_SUBST(CFG_WITH_DEFENV)
+AC_MSG_RESULT($CFG_WITH_DEFENV)
 
-dnl Compiler flags
-CXX=g++
-CFLAGS=-I${includedir}
-CPPFLAGS=-I${includedir}
-CXXFLAGS=-I${includedir}
-LDFLAGS=-L${libdir}
+# Special Substitutions - CFG_WITH_CCWARN
+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
+                               in Verilator binrary and Verilated makefiles])],
+              [case "${enableval}" in
+                yes) CFG_WITH_CCWARN=yes ;;
+                no)  CFG_WITH_CCWARN=no ;;
+                *)   AC_MSG_ERROR([bad value ${enableval} for --enable-ccwarn]) ;;
+               esac],
+              [case "x${VERILATOR_AUTHOR_SITE}" in
+                x)   CFG_WITH_CCWARN=no ;;
+                *)   CFG_WITH_CCWARN=yes ;;
+               esac]
+              )
+AC_SUBST(CFG_WITH_CCWARN)
+AC_MSG_RESULT($CFG_WITH_CCWARN)
 
-dnl Checks for programs.
+# Special Substitutions - CFG_WITH_LONGTESTS
+AC_MSG_CHECKING(whether to run long tests)
+AC_ARG_ENABLE([longtests],
+              [AS_HELP_STRING([--enable-longtests],
+                              [enable running long developer tests])],
+              [case "${enableval}" in
+                yes) CFG_WITH_LONGTESTS=yes ;;
+                no)  CFG_WITH_LONGTESTS=no ;;
+                *)   AC_MSG_ERROR([bad value ${enableval} for --enable-longtests]) ;;
+               esac],
+              [case "x${VERILATOR_AUTHOR_SITE}" in
+                x)   CFG_WITH_LONGTESTS=no ;;
+                *)   CFG_WITH_LONGTESTS=yes ;;
+               esac]
+              )
+AC_SUBST(CFG_WITH_LONGTESTS)
+AC_MSG_RESULT($CFG_WITH_LONGTESTS)
+
+# Compiler flags (ensure they are not empty to avoid configure defaults)
+CFLAGS+=" "
+CPPFLAGS+=" "
+CXXFLAGS+=" "
+LDFLAGS+=" "
+
+# Checks for programs.
 AC_PROG_CC
 AC_PROG_CXX
 AC_PROG_INSTALL
 
 AC_LANG_PUSH(C++)
+cxx_version=$($CXX --version | head -1)
+AC_MSG_RESULT([compiler is $CXX --version = $cxx_version])
 AC_MSG_CHECKING([that C++ compiler can compile simple program])
-AC_TRY_RUN([int main() { return 0; }],
-           AC_MSG_RESULT(yes),
-           AC_MSG_RESULT(no);AC_MSG_ERROR([a working C++ compiler is required]))
+AC_RUN_IFELSE(
+   [AC_LANG_SOURCE([int main() { return 0; }])],
+    AC_MSG_RESULT(yes),
+    AC_MSG_RESULT(no);AC_MSG_ERROR([a working C++ compiler is required]),
+    AC_MSG_RESULT(yes))
 
 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])
 
-dnl Checks for libraries.
+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
 
-dnl Checks for header files.
-AC_HEADER_STDC
-AC_HEADER_SYS_WAIT
-AC_CHECK_HEADERS(fcntl.h unistd.h inttypes.h sys/file.h sys/time.h sys/un.h math.h stdint.h mingw/stdint.h)
+# Checks for libraries.
 
-dnl Checks for typedefs, structures
+# Checks for typedefs, structures
 AC_CHECK_TYPE(size_t,unsigned int)
-AC_CHECK_TYPE(uint_t,unsigned int)
-AC_CHECK_TYPE(ulong_t,unsigned long)
 AC_TYPE_SIZE_T
-AC_STRUCT_TM
 
-dnl Checks for compiler characteristics.
+# Checks for compiler characteristics.
 AC_C_INLINE
 
-dnl Checks for library functions.
+AC_LINK_IFELSE(
+     [AC_LANG_PROGRAM([#include <new>], [[int* a=new int; delete a; ]])],
+     [], [AC_MSG_ERROR([$CXX does not seem to successfully compile a simple C++ program])])
 
-dnl Checks for system services
+AC_DEFUN([_MY_CXX_CHECK_FLAG],
+   [# _MY_CXX_CHECK_FLAG(flag) -- Check if compiler supports specific options
+    # Set $_my_result appropriately
+    ACO_SAVE_CXXFLAGS="$CXXFLAGS"
+    # -Werror needed otherwise unknown -Wno-div-by-zero won't report problems
+    # new/delete is needed to find -faligned-new link problem on Darwin
+    CXXFLAGS="$CXXFLAGS $1 -Werror"
+    AC_MSG_CHECKING([whether $CXX accepts $1])
+    AC_LINK_IFELSE(
+         [AC_LANG_PROGRAM([#include <new>], [[int* a=new int; delete a; ]])],
+         [_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])
+    # GCC is annoying, trying to be helpful, it postpones unknown -Wno-
+    # options if there's no error We want to see them regardless, so try
+    # forcing an error and see if we get a gcc warning
+    AC_COMPILE_IFELSE(
+         [AC_LANG_PROGRAM([[an_error "intentional-error-for-test.h"
+                          ]],[])],
+         [], # Ignore ok exit
+         [if test -s conftest.err; then
+            if grep -e "$1" conftest.err >/dev/null; then
+              _my_result=no
+            fi
+          fi])
+    AC_MSG_RESULT($_my_result)
+    CXXFLAGS="$ACO_SAVE_CXXFLAGS"
+   ])
 
-dnl Other install directories
+AC_DEFUN([_MY_CXX_CHECK_SET],
+   [# _MY_CXX_CHECK_SET(variable,flag) -- Check if compiler supports specific options
+    # If it does, set variable to flag, only if not previously set
+    if test "$$1" = ""; then
+       _MY_CXX_CHECK_FLAG($2)
+       if test "$_my_result" = "yes" ; then
+          $1="$2"
+       fi
+    fi
+   ])
+
+AC_DEFUN([_MY_CXX_CHECK_OPT],
+   [# _MY_CXX_CHECK_OPT(flag) -- Check if compiler supports specific options
+    # If it does, append flag to variable
+    _MY_CXX_CHECK_FLAG($2)
+    if test "$_my_result" = "yes" ; then
+       $1="$$1 $2"
+    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++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++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=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)
+AC_SUBST(CFG_CXXFLAGS_STD_OLDEST)
+
+# Flags for compiling Verilator internals including parser, and Verilated files
+# These turn on extra warnings and are only used with 'configure --enable-ccwarn'
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_WEXTRA,-Wextra)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_WEXTRA,-Wfloat-conversion)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_WEXTRA,-Wlogical-op)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_WEXTRA,-Wthread-safety)
+AC_SUBST(CFG_CXXFLAGS_WEXTRA)
+
+# Flags for 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,-Wno-unused-parameter)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-shadow)
+AC_SUBST(CFG_CXXFLAGS_SRC)
+
+# Flags for compiling Verilator parser always (in addition to above CFG_CXXFLAGS_SRC)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_PARSER,-Wno-char-subscripts)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_PARSER,-Wno-null-conversion)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_PARSER,-Wno-parentheses-equality)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_PARSER,-Wno-unused)
+AC_SUBST(CFG_CXXFLAGS_PARSER)
+
+# Flags for Verilated makefile
+# For example, -Wno-div-by-zero isn't in 4.1.2
+# Random code often does / 0.  Unfortunately VL_DIV_I(0,0) will warn
+# 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)
+# 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)
+
+# 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
+          _my_result=no
+        fi
+      fi],
+     [_my_result=no])
+   ])
+
+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 requires a C++11 or newer compiler.]])
+
+fi
+
+# Checks for library functions.
+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
 pkgdatadir=${datadir}/verilator
 AC_SUBST(pkgdatadir)
+pkgconfigdir=${datadir}/pkgconfig
+AC_SUBST(pkgconfigdir)
 
-AC_OUTPUT(Makefile src/Makefile src/Makefile_obj include/verilated.mk)
+AC_OUTPUT
 
 AC_MSG_RESULT([])
-AC_MSG_RESULT([Now type 'gmake'])
+AC_MSG_RESULT([Now type 'make' (or sometimes 'gmake') to build Verilator.])
 AC_MSG_RESULT([])

docs/.gitignore

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

docs/CONTRIBUTING.adoc

@@ -0,0 +1,82 @@
+= How to contribute 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
+  https://verilator.org/issues[Verilator Issues].
+
+* If you're unable to find an open issue addressing the problem,
+  https://verilator.org/issues/new[open a new Verilator issue].
+
+** 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
+   link:internals.adoc[docs/internals].
+
+==== Did you write a patch that fixes a bug?
+
+* Please https://verilator.org/issues/new[Open a new issue].
+
+* 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 link:internals.adoc[docs/internals].
+
+* Your source-code contributions must be certified as open source, under
+  the https://developercertificate.org/[Developer Certificate of
+  Origin]. On your first contribution, you must either:
+
+** Have your patch include the addition of your name to
+   link:CONTRIBUTORS[docs/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
+   https://github.com/wking/signed-off-by/blob/master/Documentation/SubmittingPatches[Signed-of-By
+   convention].
+
+** Email, or post in an issue a statement that you certify your
+   contributions.
+
+** In any of these cases your name will be added to
+   link:CONTRIBUTORS[docs/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
+  link:internals.adoc[docs/internals].
+
+==== Do you have questions?
+
+* Please see FAQ section and rest of the
+  https://verilator.org/verilator_doc.html[Verilator manual],
+  or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
+
+* Ask any question in the
+  https://verilator.org/forum[Verilator 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 https://www.contributor-covenant.org/version/1/4/code-of-conduct.html[Contributor
+  Covenant version 1.4].
+
+Thanks!

docs/CONTRIBUTORS

@@ -0,0 +1,91 @@
+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 Stanford
+Driss Hafdi
+Edgar E. Iglesias
+Eric Rippey
+Fan Shupei
+Garrett Smith
+Geza Lore
+Gianfranco Costamagna
+Glen Gibb
+Harald Heckmann
+Howard Su
+Huang Rui
+Iztok Jeras
+James Hanlon
+James Hutchinson
+Jamey Hicks
+James Pallister
+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
+Unai Martinez-Corral
+Victor Besyakov
+Vassilis Papaefstathiou
+Veripool API Bot
+Wilson Snyder
+Yossi Nivin
+Yuri Victorovich
+Yutetsu TAKATSUKASA
+Yves Mathieu
+HyungKi Jeong

docs/Makefile.in

@@ -0,0 +1,50 @@
+#*****************************************************************************
+# 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.
+
+#### Start of system configuration section. ####
+
+ASCIIDOCTOR = asciidoctor
+DOXYGEN = doxygen
+
+#### End of system configuration section. ####
+######################################################################
+
+.SUFFIXES:
+
+default:
+	@echo "error: make not supported here, run 'make docs' from Verilator top-level"
+
+%.html: %.adoc
+	$(ASCIIDOCTOR) $< -n -o $@
+
+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)
+	rm -f Makefile
+
+.PHONY: doxygen
+
+doxygen:
+	$(DOXYGEN) doxygen.config

docs/TODO

@@ -0,0 +1,111 @@
+// DESCRIPTION: Verilator: List of To Do issues.
+//
+// Copyright 2004-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
+
+* 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)
+** Recursive functions
+** Verilog configuration files
+** Expression coverage (see notes)
+** Better tristate support
+** UVM
+
+* Long-term Features
+** Assertions
+** Tristate support
+
+* Testing:
+** Code to make wrapper that sets signals, so can do comparison checks
+** New random program generator
+** Better graph viewer with search and zoom
+
+* Usability:
+** Detect and pre-remove most UNOPTFLATs
+** 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.
+
+* 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
+** Completely standalone simulation
+    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/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.
+** 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)

docs/doxygen-mainpage

@@ -0,0 +1,6 @@
+/*! \mainpage Verilator Doxygen Documentation
+ *
+ * \section intro_sec Introduction
+ *
+ * This is a full doxygen analysis of the Verilator source tree.
+ */

docs/install.adoc

@@ -0,0 +1,303 @@
+= Verilator Installation
+:toc: right
+
+// Github doesn't render unless absolute URL
+image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
+
+== Introduction
+
+This discusses how to install Verilator.  For more general information
+please see https://verilator.org[verilator.org].
+
+== Quick-start
+
+=== Install From a Package Manager
+
+Using a distribution's package manager is the easiest way to get
+started. (Note packages are unlikely to have the most recent version, so
+Git, below, maybe a better alternative.) To install as a package:
+
+   apt-get install verilator
+
+If this works, skip down to <<Running Verilator>>.
+
+=== Docker
+
+Verilator is available in pre-built Docker containers. See
+https://github.com/verilator/verilator/blob/master/ci/docker/run/README.adoc
+
+=== Git
+
+Installing Verilator with Git provides the most flexibility.
+For additional options and details see the additional sections below.  In
+brief:
+
+// Also update README
+....
+# Prerequisites:
+#sudo apt-get install git make autoconf g++ flex bison
+#sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
+#sudo apt-get install libfl-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
+make
+sudo make install
+# Now see "man verilator" or online verilator.pdf's for the example tutorials
+....
+
+If this works, skip down to <<Running Verilator>>.
+
+== Detailed Build Instructions
+
+This section describes details of the build process, and assumes you are
+building from Git or a tarball.  For using a pre-built binary for your
+Linux distribution, see instead <<Install From a Package Manager>>.
+
+=== 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 MSVC++.
+
+=== Install Prerequisites
+
+To build or run Verilator you need these standard packages:
+
+   sudo apt-get install 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 libfl-dev 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.adoc):
+
+   sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
+   cpan install Pod::Perldoc
+   cpan install Parallel::Forker
+
+==== Install SystemC
+
+If you will be using SystemC (vs straight C++ output), download
+https://www.accellera.org/downloads/standards/systemc[SystemC].
+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.)
+
+==== Install GTKWave
+
+To make use of Verilator FST tracing you will want
+http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not
+required at Verilator build time.
+
+=== Obtain Sources
+
+You may use Git or a tarball for the sources.  Git is the supported option.
+(If using a historical build that uses a tarball, tarballs are obtained
+from https://www.veripool.org/projects/verilator/wiki/Download[Verilator
+Downloads]; we presume you know how to use it, and is not described here.)
+
+Get the sources from the 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 the kit.  Verilator will be compiling the current value
+of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults
+into the executable, so they must be correct before configuring.
+
+These are the 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 `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 CAD Disk
+
+You may eventually be installing onto a project/company-wide "CAD" tools
+disk that may support multiple versions of every tool.  Target the build to
+a destination directory name that includes 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
+http://modules.sourceforge.net/[modulecmd], you'll want a module file like
+the following:
+
+.modulecmd's verilator/version file
+----
+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 `$PATH`.
+
+==== 4. Install System Globally
+
+The final option is to eventually install Verilator globally, using the
+normal system paths:
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   ./configure
+
+Then after installing (below) the binary directories should already be in
+your `$PATH`.
+
+=== 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 but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
+install to the OS-standard place:
+
+   make install
+
+== Running Verilator
+
+To run Verilator, see the example sections in the
+https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
+or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
+
+Also see the `examples/` directory that is part of the kit, and is installed
+(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
+
+     cd examples/make_hello_c
+     make
+
+Note if you did a `make install` above you should not have `VERILATOR_ROOT`
+set in your environment; it is built into the executable.
+
+== Announcements
+
+To get notified of new releases, go to
+https://github.com/verilator/verilator-announce[Verilator announcement
+repository] and follow the instructions there.
+
+== Directory Structure
+
+Some relevant files and directories in this package are as follows:
+
+   Changes                     => Version history
+   README.adoc                 => This document
+   bin/verilator               => Compiler wrapper invoked to Verilate code
+   docs/                       => Additional documentation
+   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
+   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
+
+For files created after a design is Verilated, see the
+https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
+or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
+
+== License
+
+Copyright 2008-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

docs/xml.adoc

@@ -0,0 +1,72 @@
+= Verilator XML Output
+:toc: right
+
+// Github doesn't render unless absolute URL
+image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
+
+== Introduction
+
+This document describes Verilator's XML output. For more general information
+please see https://verilator.org[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.
+// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

examples/cmake_hello_c/.gitignore

@@ -0,0 +1 @@
+build*

examples/cmake_hello_c/CMakeLists.txt

@@ -0,0 +1,36 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake Example: Small CMakeLists.txt
+#
+# This is an example cmake script to build a verilog to systemc project
+# using cmake and verilator.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+# This example builds the tracing_c example using CMake
+# To use it, run the following:
+
+# cd /path/to/verilator/examples/cmake_c
+# rm -rf build && mkdir build && cd build
+# cmake ..
+# cmake --build .
+
+cmake_minimum_required(VERSION 3.8)
+project(cmake_hello_c)
+
+find_package(verilator HINTS $ENV{VERILATOR_ROOT} ${VERILATOR_ROOT})
+if (NOT verilator_FOUND)
+  message(FATAL_ERROR "Verilator was not found. Either install it, or set the VERILATOR_ROOT environment variable")
+endif()
+
+# Create a new executable target that will contain all your sources
+add_executable(example ../make_hello_c/sim_main.cpp)
+
+# Add the Verilated circuit to the target
+verilate(example
+  INCLUDE_DIRS "../make_hello_c"
+  SOURCES ../make_hello_c/top.v)

examples/cmake_hello_c/Makefile

@@ -0,0 +1,78 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake example usage
+#
+# This file shows usage of the CMake script.
+# This makefile is here for testing the examples and should
+# generally not be added to a CMake project.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+######################################################################
+
+# Check if CMake is installed and of correct version
+ifeq ($(shell which cmake),)
+TARGET := nocmake
+else
+CMAKE_VERSION := $(shell cmake --version | grep -Po '(\d[\.\d]+)')
+CMAKE_MAJOR := $(shell echo $(CMAKE_VERSION) | cut -f1 -d.)
+CMAKE_MINOR := $(shell echo $(CMAKE_VERSION) | cut -f2 -d.)
+CMAKE_GT_3_8 := $(shell [ $(CMAKE_MAJOR) -gt 3 -o \( $(CMAKE_MAJOR) -eq 3 -a $(CMAKE_MINOR) -ge 8 \) ] && echo true)
+ifeq ($(CMAKE_GT_3_8),true)
+TARGET := run
+else
+TARGET := oldcmake
+endif
+endif
+
+default: $(TARGET)
+
+run:
+	@echo
+	@echo "-- Verilator CMake hello world example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	mkdir -p build && cd build && cmake ..
+
+	@echo
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
+
+	@echo
+	@echo "-- RUN ---------------------"
+	build/example
+
+	@echo
+	@echo "-- DONE --------------------"
+	@echo
+
+clean mostlyclean distclean maintainer-clean:
+	@rm -rf build logs
+
+nocmake:
+	@echo
+	@echo "%Skip: CMake has not been found"
+	@echo
+
+oldcmake:
+	@echo
+	@echo "%Skip: CMake version is too old (need at least 3.8)"
+	@echo

examples/cmake_hello_sc/.gitignore

@@ -0,0 +1 @@
+build*

examples/cmake_hello_sc/CMakeLists.txt

@@ -0,0 +1,45 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake Example: Small CMakeLists.txt with SystemC
+#
+# This is an example cmake script to build a verilog to SystemC project
+# using CMake and Verilator.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+# This example builds the tracing_sc example using CMake
+# To use it, run the following:
+
+# cd /path/to/verilator/examples/cmake_sc
+# rm -rf build && mkdir build && cd build
+# cmake ..
+# cmake --build .
+
+cmake_minimum_required(VERSION 3.8)
+project(cmake_hello_sc)
+
+find_package(verilator HINTS $ENV{VERILATOR_ROOT} ${VERILATOR_ROOT})
+if (NOT verilator_FOUND)
+  message(FATAL_ERROR "Verilator was not found. Either install it, or set the VERILATOR_ROOT environment variable")
+endif()
+
+# SystemC dependencies
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_package(Threads REQUIRED)
+
+# Find SystemC using SystemC's CMake integration
+find_package(SystemCLanguage QUIET)
+
+# Create a new executable target that will contain all your sources
+add_executable(example ../make_hello_sc/sc_main.cpp)
+
+# Add the Verilated circuit to the target
+verilate(example SYSTEMC
+  INCLUDE_DIRS "../make_hello_sc"
+  SOURCES ../make_hello_sc/top.v)
+
+verilator_link_systemc(example)

examples/cmake_hello_sc/Makefile

@@ -0,0 +1,128 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake example usage
+#
+# This file shows usage of the CMake script.
+# This makefile is here for testing the examples and should
+# generally not be added to a CMake project.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+######################################################################
+
+# Check if CMake is installed and of correct version
+ifeq ($(shell which cmake),)
+	TARGET := nocmake
+else
+CMAKE_VERSION := $(shell cmake --version | grep -Po '(\d[\.\d]+)')
+CMAKE_MAJOR := $(shell echo $(CMAKE_VERSION) | cut -f1 -d.)
+CMAKE_MINOR := $(shell echo $(CMAKE_VERSION) | cut -f2 -d.)
+CMAKE_GT_3_8 := $(shell [ $(CMAKE_MAJOR) -gt 3 -o \( $(CMAKE_MAJOR) -eq 3 -a $(CMAKE_MINOR) -ge 8 \) ] && echo true)
+ifneq ($(CMAKE_GT_3_8),true)
+TARGET := oldcmake
+else
+
+# Test existence of SYSTEMC_INCLUDE and SYSTEMC_LIBDIR environment variabless
+ifneq (,$(SYSTEMC_INCLUDE))
+ifneq (,${SYSTEMC_LIBDIR})
+SYSTEMC_SET := true
+endif
+endif
+
+# Test existence of SYSTEMC_ROOT environment variable
+ifneq (SYSTEMC_SET, true)
+ifneq (,${SYSTEMC_ROOT})
+SYSTEMC_SET := true
+endif
+endif
+
+# Test existence of SYSTEMC environment variable
+ifneq (SYSTEMC_SET, true)
+ifneq (,${SYSTEMC})
+SYSTEMC_SET := true
+endif
+endif
+
+# Test whether SystemC is installed with CMake support
+# This will print a CMake error about processing arguments that can (currently) be ignored.
+ifneq (SYSTEMC_SET, true)
+FINDSC := $(shell mkdir -p build && cd build && cmake --find-package -DNAME=SystemCLanguage -DCMAKE_USE_PTHREADS_INIT=ON -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST -DThreads_FOUND=ON)
+ifneq (,$(findstring SystemCLanguage found,$(FINDSC)))
+SYSTEMC_SET := true
+endif
+endif
+
+ifeq ($(SYSTEMC_SET), true)
+TARGET := run
+else
+TARGET := nosc
+endif
+
+endif
+endif
+
+default: $(TARGET)
+
+run:
+	@echo
+	@echo "-- Verilator CMake SystemC hello-world simple example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	mkdir -p build && cd build && cmake ..
+
+	@echo
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
+
+	@echo
+	@echo "-- RUN ---------------------"
+	@mkdir -p logs
+	build/example
+
+	@echo "-- DONE --------------------"
+	@echo "Note: Once this example is understood, see examples/cmake_tracing_sc."
+	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
+
+clean mostlyclean distclean maintainer-clean:
+	@rm -rf build logs
+
+nocmake:
+	@echo
+	@echo "%Skip: CMake has not been found"
+	@echo
+
+oldcmake:
+	@echo
+	@echo "%Skip: CMake version is too old (need at least 3.8)"
+	@echo
+
+nosc:
+	@echo
+	@echo "%Skip: CMake could not find SystemC."
+	@echo "% Make sure that either:"
+	@echo "% - The environment variables SYSTEMC_INCLUDE and SYSTEMC_LIBDIR are exported."
+	@echo "% - Or, the environment variable SYSTEMC_ROOT is exported."
+	@echo "% - Or, The environment variable SYSTEMC is exported."
+	@echo "% - Or, if the SystemC installation provides CMake support,"
+	@echo "%   that its installation prefix is in CMAKE_PREFIX_PATH."
+	@echo "% Also that the C++ standard of the SystemC library is the same as this example."
+	@echo "% Please see the Verilator documentation's CMake section for more information."
+	@echo

examples/cmake_protect_lib/.gitignore

@@ -0,0 +1 @@
+build*

examples/cmake_protect_lib/CMakeLists.txt

@@ -0,0 +1,59 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake Example: Small CMakeLists.txt
+#
+# This is an example cmake script to build a verilog to systemc project
+# using cmake and verilator.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+# This example builds the tracing_c example using CMake
+# To use it, run the following:
+
+# cd /path/to/verilator/examples/cmake_c
+# rm -rf build && mkdir build && cd build
+# cmake ..
+# cmake --build .
+
+cmake_minimum_required(VERSION 3.8)
+project(cmake_protect_lib)
+
+find_package(verilator HINTS $ENV{VERILATOR_ROOT} ${VERILATOR_ROOT})
+if (NOT verilator_FOUND)
+  message(FATAL_ERROR "Verilator was not found. Either install it, or set the VERILATOR_ROOT environment variable")
+endif()
+
+# Create the main executable target
+add_executable(example ../make_protect_lib/sim_main.cpp)
+
+# Create a secret library
+add_library(verilated_secret STATIC) # or SHARED for a shared library
+target_link_libraries(example PRIVATE verilated_secret)
+# To create both libraries on CMake >= 3.12 replace the above 2 lines with the following:
+# add_library(verilated_secret OBJECT)
+# set_property(TARGET verilated_secret PROPERTY POSITION_INDEPENDENT_CODE 1)
+# add_library(verilated_secret_static STATIC  $<TARGET_OBJECTS:verilated_secret>)
+# set_target_properties(verilated_secret_static PROPERTIES OUTPUT_NAME verilated_secret)
+# add_library(verilated_secret_shared SHARED  $<TARGET_OBJECTS:verilated_secret>)
+# set_target_properties(verilated_secret_shared PROPERTIES OUTPUT_NAME verilated_secret)
+# target_link_libraries(example PRIVATE verilated_secret_static)
+
+# Setup random seed
+verilator_generate_key(KEY_INIT)
+set(PROTECT_KEY ${KEY_INIT} CACHE STRING "Random seed for protection")
+
+# Add the Verilated modules to the targets
+verilate(verilated_secret
+  VERILATOR_ARGS --protect-lib verilated_secret
+                 --protect-key ${PROTECT_KEY}
+  DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/verilated_secret
+  SOURCES ../make_protect_lib/secret_impl.v)
+
+# Include location of verilated_secret.sv wrapper
+verilate(example
+  VERILATOR_ARGS "-I${CMAKE_CURRENT_BINARY_DIR}/verilated_secret"
+  SOURCES ../make_protect_lib/top.v)

examples/cmake_protect_lib/Makefile

@@ -0,0 +1,78 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake example usage
+#
+# This file shows usage of the CMake script.
+# This makefile is here for testing the examples and should
+# generally not be added to a CMake project.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+######################################################################
+
+# Check if CMake is installed and of correct version
+ifeq ($(shell which cmake),)
+TARGET := nocmake
+else
+CMAKE_VERSION := $(shell cmake --version | grep -Po '(\d[\.\d]+)')
+CMAKE_MAJOR := $(shell echo $(CMAKE_VERSION) | cut -f1 -d.)
+CMAKE_MINOR := $(shell echo $(CMAKE_VERSION) | cut -f2 -d.)
+CMAKE_GT_3_8 := $(shell [ $(CMAKE_MAJOR) -gt 3 -o \( $(CMAKE_MAJOR) -eq 3 -a $(CMAKE_MINOR) -ge 8 \) ] && echo true)
+ifeq ($(CMAKE_GT_3_8),true)
+TARGET := run
+else
+TARGET := oldcmake
+endif
+endif
+
+default: $(TARGET)
+
+run:
+	@echo
+	@echo "-- Verilator CMake protect_lib example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	mkdir -p build && cd build && cmake ..
+
+	@echo
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
+
+	@echo
+	@echo "-- RUN ---------------------"
+	build/example
+
+	@echo
+	@echo "-- DONE --------------------"
+	@echo
+
+clean mostlyclean distclean maintainer-clean:
+	@rm -rf build logs
+
+nocmake:
+	@echo
+	@echo "%Skip: CMake has not been found"
+	@echo
+
+oldcmake:
+	@echo
+	@echo "%Skip: CMake version is too old (need at least 3.8)"
+	@echo

examples/cmake_tracing_c/.gitignore

@@ -0,0 +1,2 @@
+build*
+logs

examples/cmake_tracing_c/CMakeLists.txt

@@ -0,0 +1,37 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake Example: Small CMakeLists.txt with tracing
+#
+# This is an example cmake script to build a verilog to systemc project
+# using cmake and verilator.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+# This example builds the make_tracing_c example using CMake
+# To use it, run the following:
+
+# cd /path/to/verilator/examples/cmake_tracing_c
+# rm -rf build && mkdir build && cd build
+# cmake ..
+# cmake --build .
+
+cmake_minimum_required(VERSION 3.8)
+project(cmake_tracing_c)
+
+find_package(verilator HINTS $ENV{VERILATOR_ROOT} ${VERILATOR_ROOT})
+if (NOT verilator_FOUND)
+  message(FATAL_ERROR "Verilator was not found. Either install it, or set the VERILATOR_ROOT environment variable")
+endif()
+
+# Create a new executable target that will contain all your sources
+add_executable(example ../make_tracing_c/sim_main.cpp)
+
+# Add the Verilated circuit to the target
+verilate(example COVERAGE TRACE
+  INCLUDE_DIRS "../make_tracing_c"
+  VERILATOR_ARGS -f ../make_tracing_c/input.vc -Os -x-assign 0
+  SOURCES ../make_tracing_c/top.v)

examples/cmake_tracing_c/Makefile

@@ -0,0 +1,84 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake example usage
+#
+# This file shows usage of the CMake script.
+# This makefile is here for testing the examples and should
+# generally not be added to a CMake project.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+######################################################################
+
+# Check if CMake is installed and of correct version
+ifeq ($(shell which cmake),)
+TARGET := nocmake
+else
+CMAKE_VERSION := $(shell cmake --version | grep -Po '(\d[\.\d]+)')
+CMAKE_MAJOR := $(shell echo $(CMAKE_VERSION) | cut -f1 -d.)
+CMAKE_MINOR := $(shell echo $(CMAKE_VERSION) | cut -f2 -d.)
+CMAKE_GT_3_8 := $(shell [ $(CMAKE_MAJOR) -gt 3 -o \( $(CMAKE_MAJOR) -eq 3 -a $(CMAKE_MINOR) -ge 8 \) ] && echo true)
+ifeq ($(CMAKE_GT_3_8),true)
+TARGET := run
+else
+TARGET := oldcmake
+endif
+endif
+
+default: $(TARGET)
+
+run:
+	@echo
+	@echo "-- Verilator CMake tracing example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	mkdir -p build && cd build && cmake ..
+
+	@echo
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
+
+	@echo
+	@echo "-- RUN ---------------------"
+	@mkdir -p logs
+	build/example +trace
+
+	@echo
+	@echo "-- COVERAGE ----------------"
+	$(VERILATOR_COVERAGE) --annotate logs/annotated logs/coverage.dat
+
+	@echo
+	@echo "-- DONE --------------------"
+	@echo "To see waveforms, open vlt_dump.vcd in a waveform viewer"
+	@echo
+
+clean mostlyclean distclean maintainer-clean:
+	@rm -rf build logs
+
+nocmake:
+	@echo
+	@echo "%Skip: CMake has not been found"
+	@echo
+
+oldcmake:
+	@echo
+	@echo "%Skip: CMake version is too old (need at least 3.8)"
+	@echo

examples/cmake_tracing_sc/.gitignore

@@ -1,8 +1,7 @@
-*.old
 *.dmp
 *.log
 *.csrc
 *.vcd
 obj_*
 logs
-project
+build*

examples/cmake_tracing_sc/CMakeLists.txt

@@ -0,0 +1,46 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake Example: Small CMakeLists.txt with SystemC tracing
+#
+# This is an example cmake script to build a verilog to SystemC project
+# using CMake and Verilator.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+# This example builds the tracing_sc example using CMake
+# To use it, run the following:
+
+# cd /path/to/verilator/examples/cmake_tracing_sc
+# rm -rf build && mkdir build && cd build
+# cmake ..
+# cmake --build .
+
+cmake_minimum_required(VERSION 3.8)
+project(cmake_tracing_sc_example)
+
+find_package(verilator HINTS $ENV{VERILATOR_ROOT} ${VERILATOR_ROOT})
+if (NOT verilator_FOUND)
+  message(FATAL_ERROR "Verilator was not found. Either install it, or set the VERILATOR_ROOT environment variable")
+endif()
+
+# SystemC dependencies
+set(THREADS_PREFER_PTHREAD_FLAG ON)
+find_package(Threads REQUIRED)
+
+# Find SystemC using SystemC's CMake integration
+find_package(SystemCLanguage QUIET)
+
+# Create a new executable target that will contain all your sources
+add_executable(example ../make_tracing_sc/sc_main.cpp)
+
+# Add the Verilated circuit to the target
+verilate(example SYSTEMC COVERAGE TRACE
+  INCLUDE_DIRS "../make_tracing_sc"
+  VERILATOR_ARGS -f ../make_tracing_sc/input.vc -Os -x-assign 0
+  SOURCES ../make_tracing_sc/top.v)
+
+verilator_link_systemc(example)

examples/cmake_tracing_sc/Makefile

@@ -0,0 +1,133 @@
+######################################################################
+#
+# DESCRIPTION: Verilator CMake example usage
+#
+# This file shows usage of the CMake script.
+# This makefile is here for testing the examples and should
+# generally not be added to a CMake project.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+######################################################################
+
+# Check if CMake is installed and of correct version
+ifeq ($(shell which cmake),)
+	TARGET := nocmake
+else
+CMAKE_VERSION := $(shell cmake --version | grep -Po '(\d[\.\d]+)')
+CMAKE_MAJOR := $(shell echo $(CMAKE_VERSION) | cut -f1 -d.)
+CMAKE_MINOR := $(shell echo $(CMAKE_VERSION) | cut -f2 -d.)
+CMAKE_GT_3_8 := $(shell [ $(CMAKE_MAJOR) -gt 3 -o \( $(CMAKE_MAJOR) -eq 3 -a $(CMAKE_MINOR) -ge 8 \) ] && echo true)
+ifneq ($(CMAKE_GT_3_8),true)
+TARGET := oldcmake
+else
+
+# Test existence of SYSTEMC_INCLUDE and SYSTEMC_LIBDIR environment variabless
+ifneq (,$(SYSTEMC_INCLUDE))
+ifneq (,${SYSTEMC_LIBDIR})
+SYSTEMC_SET := true
+endif
+endif
+
+# Test existence of SYSTEMC_ROOT environment variable
+ifneq (SYSTEMC_SET, true)
+ifneq (,${SYSTEMC_ROOT})
+SYSTEMC_SET := true
+endif
+endif
+
+# Test existence of SYSTEMC environment variable
+ifneq (SYSTEMC_SET, true)
+ifneq (,${SYSTEMC})
+SYSTEMC_SET := true
+endif
+endif
+
+# Test whether SystemC is installed with CMake support
+# This will print a CMake error about processing arguments that can (currently) be ignored.
+ifneq (SYSTEMC_SET, true)
+FINDSC := $(shell mkdir -p build && cd build && cmake --find-package -DNAME=SystemCLanguage -DCMAKE_USE_PTHREADS_INIT=ON -DCOMPILER_ID=GNU -DLANGUAGE=CXX -DMODE=EXIST -DThreads_FOUND=ON)
+ifneq (,$(findstring SystemCLanguage found,$(FINDSC)))
+SYSTEMC_SET := true
+endif
+endif
+
+ifeq ($(SYSTEMC_SET), true)
+TARGET := run
+else
+TARGET := nosc
+endif
+
+endif
+endif
+
+default: $(TARGET)
+
+run:
+	@echo
+	@echo "-- Verilator CMake SystemC tracing example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	mkdir -p build && cd build && cmake ..
+
+	@echo
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
+
+	@echo
+	@echo "-- RUN ---------------------"
+	@mkdir -p logs
+	build/example +trace
+
+	@echo
+	@echo "-- COVERAGE ----------------"
+	$(VERILATOR_COVERAGE) --annotate logs/annotated logs/coverage.dat
+
+	@echo
+	@echo "-- DONE --------------------"
+	@echo "To see waveforms, open vlt_dump.vcd in a waveform viewer"
+	@echo
+
+clean mostlyclean distclean maintainer-clean:
+	@rm -rf build logs
+
+nocmake:
+	@echo
+	@echo "%Skip: CMake has not been found"
+	@echo
+
+oldcmake:
+	@echo
+	@echo "%Skip: CMake version is too old (need at least 3.8)"
+	@echo
+
+nosc:
+	@echo
+	@echo "%Skip: CMake could not find SystemC."
+	@echo "% Make sure that either:"
+	@echo "% - The environment variables SYSTEMC_INCLUDE and SYSTEMC_LIBDIR are exported."
+	@echo "% - Or, the environment variable SYSTEMC_ROOT is exported."
+	@echo "% - Or, The environment variable SYSTEMC is exported."
+	@echo "% - Or, if the SystemC installation provides CMake support,"
+	@echo "%   that its installation prefix is in CMAKE_PREFIX_PATH."
+	@echo "% Also that the C++ standard of the SystemC library is the same as this example."
+	@echo "% Please see the Verilator documentation's CMake section for more information."
+	@echo

examples/make_hello_c/.gitignore

@@ -3,4 +3,4 @@
 *.csrc
 *.vcd
 obj_*
-project
+logs

examples/make_hello_c/Makefile

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

examples/make_hello_c/sim_main.cpp

@@ -0,0 +1,42 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2017 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+//======================================================================
+
+// Include common routines
+#include <verilated.h>
+
+// Include model header, generated from Verilating "top.v"
+#include "Vtop.h"
+
+int main(int argc, char** argv, char** env) {
+    // See a similar example walkthrough in the verilator manpage.
+
+    // This is intended to be a minimal example.  Before copying this to start a
+    // real project, it is better to start with a more complete example,
+    // e.g. examples/c_tracing.
+
+    // Prevent unused variable warnings
+    if (false && argc && argv && env) {}
+
+    // Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
+    Vtop* top = new Vtop;
+
+    // Simulate until $finish
+    while (!Verilated::gotFinish()) {
+
+        // Evaluate model
+        top->eval();
+    }
+
+    // Final model cleanup
+    top->final();
+
+    // Destroy model
+    delete top;
+
+    // Return good completion status
+    return 0;
+}

examples/make_hello_c/top.v

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

examples/make_hello_sc/.gitignore

@@ -1,8 +1,6 @@
-*.old
 *.dmp
 *.log
 *.csrc
 *.vcd
 obj_*
 logs
-project

examples/make_hello_sc/Makefile

@@ -0,0 +1,64 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: Small Makefile
+#
+# This calls the object directory makefile.  That allows the objects to
+# be placed in the "current directory" which simplifies the Makefile.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+# Check for sanity to avoid later confusion
+
+ifneq ($(words $(CURDIR)),1)
+ $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)')
+endif
+
+######################################################################
+
+# This is intended to be a minimal example.  Before copying this to start a
+# real project, it is better to start with a more complete example,
+# e.g. examples/make_tracing_sc.
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+endif
+
+# Check if SC exists via a verilator call (empty if not)
+SYSTEMC_EXISTS := $(shell $(VERILATOR) --getenv SYSTEMC_INCLUDE)
+
+ifneq ($(SYSTEMC_EXISTS),)
+default: run
+else
+default: nosc
+endif
+
+run:
+	@echo "-- Verilator hello-world simple example"
+	@echo "-- VERILATE & COMPILE ------"
+	$(VERILATOR) -sc --exe --build -j top.v sc_main.cpp
+	@echo "-- RUN ---------------------"
+	obj_dir/Vtop
+	@echo "-- DONE --------------------"
+	@echo "Note: Once this example is understood, see examples/make_tracing_sc."
+	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
+
+######################################################################
+
+nosc:
+	@echo
+	@echo "%Skip: SYSTEMC_INCLUDE not in environment"
+	@echo "(If you have SystemC see the README, and rebuild Verilator)"
+	@echo
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir *.log *.dmp *.vpd core

examples/make_hello_sc/sc_main.cpp

@@ -0,0 +1,45 @@
+// -*- SystemC -*-
+// DESCRIPTION: Verilator Example: Top level main for invoking SystemC model
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2017 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+//======================================================================
+
+// SystemC global header
+#include <systemc.h>
+
+// Include common routines
+#include <verilated.h>
+
+// Include model header, generated from Verilating "top.v"
+#include "Vtop.h"
+
+int sc_main(int argc, char* argv[]) {
+    // See a similar example walkthrough in the verilator manpage.
+
+    // This is intended to be a minimal example.  Before copying this to start a
+    // real project, it is better to start with a more complete example,
+    // e.g. examples/c_tracing.
+
+    // Prevent unused variable warnings
+    if (false && argc && argv) {}
+
+    // Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
+    Vtop* top = new Vtop("top");
+
+    // Initialize SC model
+    sc_start(1, SC_NS);
+
+    // Simulate until $finish
+    while (!Verilated::gotFinish()) {
+        // Simulate 1ns
+        sc_start(1, SC_NS);
+    }
+
+    // Final model cleanup
+    top->final();
+
+    // Return good completion status
+    return 0;
+}

examples/make_hello_sc/top.v

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

examples/make_protect_lib/.gitignore

@@ -0,0 +1,2 @@
+obj_*
+logs

examples/make_protect_lib/Makefile

@@ -0,0 +1,96 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: --protect-lib Makefile
+#
+# This calls the object directory makefiles.  That allows the objects to
+# be placed in the "current directory" which simplifies the Makefile.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+# Check for sanity to avoid later confusion
+
+ifneq ($(words $(CURDIR)),1)
+ $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)')
+endif
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+endif
+
+VERILATOR_FLAGS =
+# Generate C++
+VERILATOR_FLAGS += -cc
+# Optimize
+VERILATOR_FLAGS += -Os -x-assign 0
+# Warn abount lint issues; may not want this on less solid designs
+VERILATOR_FLAGS += -Wall
+# Make waveforms
+TOP_VERILATOR_FLAGS = $(VERILATOR_FLAGS) --trace
+
+######################################################################
+default: run
+
+run:
+	@echo
+	@echo "-- Verilator --protect-lib example -_--------------------------"
+
+	@echo
+	@echo "-- VERILATE secret module -------------------------------------"
+	@echo " --protect-lib will produce both a static and shared library"
+	@echo " In this example the static library is used, but some"
+	@echo " simulators may require the shared library."
+	@echo "---------------------------------------------------------------"
+	$(VERILATOR) $(VERILATOR_FLAGS) --protect-lib verilated_secret -Mdir obj_dir_secret/ secret_impl.v
+
+	@echo
+	@echo "-- COMPILE protected library ----------------------------------"
+	@echo " This builds verilated_secret.sv, libverilated_secret.a and"
+	@echo " libverilated_secret.so which can be distributed apart from"
+	@echo " the source"
+	@echo "---------------------------------------------------------------"
+	$(MAKE) -j 4 -C obj_dir_secret -f Vsecret_impl.mk
+
+	@echo
+	@echo "-- VERILATE top module ----------------------------------------"
+	@echo " Use the SystemVerilog wrapper (verilated_secret.sv) and the"
+	@echo " library (libverilated_secret.a) generated from the previous"
+	@echo " step"
+	@echo "---------------------------------------------------------------"
+	$(VERILATOR) $(TOP_VERILATOR_FLAGS) --exe -LDFLAGS '../obj_dir_secret/libverilated_secret.a' top.v obj_dir_secret/verilated_secret.sv sim_main.cpp
+
+	@echo
+	@echo "-- COMPILE entire design --------------------------------------"
+	$(MAKE) -j 4 -C obj_dir -f Vtop.mk
+
+	@echo
+	@echo "-- RUN --------------------------------------------------------"
+	@mkdir -p logs
+	obj_dir/Vtop +trace
+
+	@echo
+	@echo "-- DONE -------------------------------------------------------"
+	@echo "To see waveforms, open logs/vlt_dump.vcd in a waveform viewer"
+	@echo
+
+
+######################################################################
+# Other targets
+
+show-config:
+	$(VERILATOR) -V
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir* logs *.log core

examples/make_protect_lib/secret_impl.v

@@ -0,0 +1,30 @@
+// DESCRIPTION: Verilator: --protect-lib example secret module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2019 by Todd Strader.
+// SPDX-License-Identifier: CC0-1.0
+
+// This module will be used as libsecret.a or libsecret.so without
+// exposing the source.
+
+module secret_impl
+  (
+   input [31:0]        a,
+   input [31:0]        b,
+   output logic [31:0] x,
+   input               clk);
+
+   logic [31:0]        accum_q = 0;
+   logic [31:0]        secret_value = 9;
+
+   initial $display("%m: initialized");
+
+   always @(posedge clk) begin
+      accum_q <= accum_q + a;
+      if (accum_q > 10)
+        x <= b;
+      else
+        x <= a + b + secret_value;
+   end
+
+endmodule

examples/make_protect_lib/sim_main.cpp

@@ -0,0 +1,76 @@
+// DESCRIPTION: Verilator: --protect-lib example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2019 by Todd Strader.
+// SPDX-License-Identifier: CC0-1.0
+//======================================================================
+
+// See examples/tracing_c for notes on tracing
+
+// Include common routines
+#include <verilated.h>
+
+#include "Vtop.h"
+
+#if VM_TRACE
+#include <verilated_vcd_c.h>
+#endif
+
+vluint64_t main_time = 0;
+double sc_time_stamp() { return main_time; }
+
+int main(int argc, char** argv, char** env) {
+    if (false && argc && argv && env) {}
+
+    Verilated::debug(0);
+    Verilated::randReset(2);
+    Verilated::commandArgs(argc, argv);
+
+    // Construct the Verilated model, including the secret module
+    Vtop* top = new Vtop;
+
+#if VM_TRACE
+    // When tracing, the contents of the secret module will not be seen
+    VerilatedVcdC* tfp = nullptr;
+    const char* flag = Verilated::commandArgsPlusMatch("trace");
+    if (flag && 0 == strcmp(flag, "+trace")) {
+        Verilated::traceEverOn(true);
+        VL_PRINTF("Enabling waves into logs/vlt_dump.vcd...\n");
+        tfp = new VerilatedVcdC;
+        top->trace(tfp, 99);
+        Verilated::mkdir("logs");
+        tfp->open("logs/vlt_dump.vcd");
+    }
+#endif
+
+    top->clk = 0;
+
+    // Simulate until $finish
+    while (!Verilated::gotFinish()) {
+        main_time++;
+        top->clk = ~top->clk & 0x1;
+        top->eval();
+#if VM_TRACE
+        if (tfp) tfp->dump(main_time);
+#endif
+    }
+
+    // Final model cleanup
+    top->final();
+
+    // Close trace if opened
+#if VM_TRACE
+    if (tfp) {
+        tfp->close();
+        tfp = nullptr;
+    }
+#endif
+
+    // Destroy model
+    delete top;
+    top = nullptr;
+
+    // Return good completion status
+    // Don't use exit() or destructor won't get called
+    return 0;
+}

examples/make_protect_lib/top.v

@@ -0,0 +1,35 @@
+// DESCRIPTION: Verilator: --protect-lib example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2019 by Todd Strader.
+// SPDX-License-Identifier: CC0-1.0
+
+// See also the EXAMPLE section in the verilator manpage/document.
+module top (input clk);
+
+   integer cyc = 0;
+   logic [31:0] a = 0;
+   logic [31:0] b = 0;
+   logic [31:0] x;
+
+   verilated_secret secret (.a, .b, .x, .clk);
+
+   always @(posedge clk) begin
+      $display("[%0t] cyc=%0d a=%0d b=%0d x=%0d", $time, cyc, a, b, x);
+      cyc <= cyc + 1;
+      if (cyc == 0) begin
+         a <= 5;
+         b <= 7;
+      end else if (cyc == 1) begin
+         a <= 6;
+         b <= 2;
+      end else if (cyc == 2) begin
+         a <= 1;
+         b <= 9;
+      end else if (cyc > 3) begin
+         $display("Done");
+         $finish;
+      end
+   end
+
+endmodule

examples/make_tracing_c/.gitignore

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

examples/make_tracing_c/Makefile

@@ -0,0 +1,102 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: Small Makefile
+#
+# This calls the object directory makefile.  That allows the objects to
+# be placed in the "current directory" which simplifies the Makefile.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+# Check for sanity to avoid later confusion
+
+ifneq ($(words $(CURDIR)),1)
+ $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)')
+endif
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+
+VERILATOR_FLAGS =
+# Generate C++ in executable form
+VERILATOR_FLAGS += -cc --exe
+# Generate makefile dependencies (not shown as complicates the Makefile)
+#VERILATOR_FLAGS += -MMD
+# Optimize
+VERILATOR_FLAGS += -Os -x-assign 0
+# Warn abount lint issues; may not want this on less solid designs
+VERILATOR_FLAGS += -Wall
+# Make waveforms
+VERILATOR_FLAGS += --trace
+# Check SystemVerilog assertions
+VERILATOR_FLAGS += --assert
+# Generate coverage analysis
+VERILATOR_FLAGS += --coverage
+# Run Verilator in debug mode
+#VERILATOR_FLAGS += --debug
+# Add this trace to get a backtrace in gdb
+#VERILATOR_FLAGS += --gdbbt
+
+# Input files for Verilator
+VERILATOR_INPUT = -f input.vc top.v sim_main.cpp
+
+######################################################################
+default: run
+
+run:
+	@echo
+	@echo "-- Verilator tracing example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	$(VERILATOR) $(VERILATOR_FLAGS) $(VERILATOR_INPUT)
+
+	@echo
+	@echo "-- BUILD -------------------"
+# To compile, we can either
+# 1. Pass --build to Verilator by editing VERILATOR_FLAGS above.
+# 2. Or, run the make rules Verilator does:
+#	$(MAKE) -j -C obj_dir -f Vtop.mk
+# 3. Or, call a submakefile where we can override the rules ourselves:
+	$(MAKE) -j -C obj_dir -f ../Makefile_obj
+
+	@echo
+	@echo "-- RUN ---------------------"
+	@rm -rf logs
+	@mkdir -p logs
+	obj_dir/Vtop +trace
+
+	@echo
+	@echo "-- COVERAGE ----------------"
+	@rm -rf logs/annotated
+	$(VERILATOR_COVERAGE) --annotate logs/annotated logs/coverage.dat
+
+	@echo
+	@echo "-- DONE --------------------"
+	@echo "To see waveforms, open vlt_dump.vcd in a waveform viewer"
+	@echo
+
+
+######################################################################
+# Other targets
+
+show-config:
+	$(VERILATOR) -V
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir logs *.log *.dmp *.vpd coverage.dat core

examples/make_tracing_c/Makefile_obj

@@ -0,0 +1,57 @@
+# -*- Makefile -*-
+#######################################################################
+#
+# DESCRIPTION: Verilator Example: Makefile for inside object directory
+#
+# This is executed in the object directory, and called by ../Makefile
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+#######################################################################
+
+default: Vtop
+
+# Include the rules made by Verilator
+include Vtop.mk
+
+# Use OBJCACHE (ccache) if using gmake and its installed
+COMPILE.cc = $(OBJCACHE) $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
+
+#######################################################################
+# Compile flags
+
+# Override some default compile flags
+CPPFLAGS += -MMD -MP
+CPPFLAGS += -DVL_DEBUG=1
+# Turn on some more flags (when configured appropriately)
+# For testing inside Verilator, "configure --enable-ccwarn" will do this
+# automatically; otherwise you may want this unconditionally enabled
+ifeq ($(CFG_WITH_CCWARN),yes)	# Local... Else don't burden users
+USER_CPPFLAGS_WALL += -W -Werror -Wall
+endif
+
+# See the benchmarking section of bin/verilator.
+# Support class optimizations.  This includes the tracing and symbol table.
+# SystemC takes minutes to optimize, thus it is off by default.
+OPT_SLOW =
+# Fast path optimizations.  Most time is spent in these classes.
+OPT_FAST = -Os -fstrict-aliasing
+#OPT_FAST = -O
+#OPT_FAST =
+
+#######################################################################
+# Linking final exe -- presumes have a sim_main.cpp
+
+# Special compile rule
+sim_main.o: sim_main.cpp $(VM_PREFIX).h
+
+######################################################################
+######################################################################
+# Automatically understand dependencies
+
+DEPS := $(wildcard *.d)
+ifneq ($(DEPS),)
+include $(DEPS)
+endif

examples/make_tracing_c/input.vc

@@ -0,0 +1,2 @@
+// This file typically lists flags required by a large project, e.g. include directories
++librescan +libext+.v+.sv+.vh+.svh -y .

examples/make_tracing_c/sim_main.cpp

@@ -0,0 +1,107 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2017 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+//======================================================================
+
+// For std::unique_ptr
+#include <memory>
+
+// Include common routines
+#include <verilated.h>
+
+// Include model header, generated from Verilating "top.v"
+#include "Vtop.h"
+
+// Current simulation time (64-bit unsigned)
+vluint64_t main_time = 0;
+// Called by $time in Verilog
+double sc_time_stamp() {
+    return main_time;  // Note does conversion to real, to match SystemC
+}
+
+int main(int argc, char** argv, char** env) {
+    // This is a more complicated example, please also see the simpler examples/make_hello_c.
+
+    // Prevent unused variable warnings
+    if (false && argc && argv && env) {}
+
+    // Set debug level, 0 is off, 9 is highest presently used
+    // May be overridden by commandArgs
+    Verilated::debug(0);
+
+    // Randomization reset policy
+    // May be overridden by commandArgs
+    Verilated::randReset(2);
+
+    // Verilator must compute traced signals
+    Verilated::traceEverOn(true);
+
+    // Pass arguments so Verilated code can see them, e.g. $value$plusargs
+    // This needs to be called before you create any model
+    Verilated::commandArgs(argc, argv);
+
+    // Create logs/ directory in case we have traces to put under it
+    Verilated::mkdir("logs");
+
+    // Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
+    // Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end
+    const std::unique_ptr<Vtop> top{new Vtop};
+
+    // Set some inputs
+    top->reset_l = !0;
+    top->clk = 0;
+    top->in_small = 1;
+    top->in_quad = 0x1234;
+    top->in_wide[0] = 0x11111111;
+    top->in_wide[1] = 0x22222222;
+    top->in_wide[2] = 0x3;
+
+    // Simulate until $finish
+    while (!Verilated::gotFinish()) {
+        main_time++;  // Time passes...
+
+        // Toggle a fast (time/2 period) clock
+        top->clk = !top->clk;
+
+        // Toggle control signals on an edge that doesn't correspond
+        // to where the controls are sampled; in this example we do
+        // this only on a negedge of clk, because we know
+        // reset is not sampled there.
+        if (!top->clk) {
+            if (main_time > 1 && main_time < 10) {
+                top->reset_l = !1;  // Assert reset
+            } else {
+                top->reset_l = !0;  // Deassert reset
+            }
+            // Assign some other inputs
+            top->in_quad += 0x12;
+        }
+
+        // Evaluate model
+        // (If you have multiple models being simulated in the same
+        // timestep then instead of eval(), call eval_step() on each, then
+        // eval_end_step() on each.)
+        top->eval();
+
+        // Read outputs
+        VL_PRINTF("[%" VL_PRI64 "d] clk=%x rstl=%x iquad=%" VL_PRI64 "x"
+                  " -> oquad=%" VL_PRI64 "x owide=%x_%08x_%08x\n",
+                  main_time, top->clk, top->reset_l, top->in_quad, top->out_quad, top->out_wide[2],
+                  top->out_wide[1], top->out_wide[0]);
+    }
+
+    // Final model cleanup
+    top->final();
+
+    //  Coverage analysis (since test passed)
+#if VM_COVERAGE
+    Verilated::mkdir("logs");
+    VerilatedCov::write("logs/coverage.dat");
+#endif
+
+    // Return good completion status
+    // Don't use exit() or destructor won't get called
+    return 0;
+}

examples/make_tracing_c/sub.v

@@ -0,0 +1,42 @@
+// DESCRIPTION: Verilator: Verilog Test module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2003 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+// ======================================================================
+
+module sub
+  (
+   input clk,
+   input reset_l
+   );
+
+   // Example counter/flop
+   reg [31:0] count_c;
+   always_ff @ (posedge clk) begin
+      if (!reset_l) begin
+         /*AUTORESET*/
+         // Beginning of autoreset for uninitialized flops
+         count_c <= 32'h0;
+         // End of automatics
+      end
+      else begin
+         count_c <= count_c + 1;
+         if (count_c >= 3) begin
+            // This write is a magic value the Makefile uses to make sure the
+            // test completes successfully.
+            $write("*-* All Finished *-*\n");
+            $finish;
+         end
+      end
+   end
+
+   // An example assertion
+   always_ff @ (posedge clk) begin
+      AssertionExample: assert (!reset_l || count_c<100);
+   end
+
+   // And example coverage analysis
+   cover property (@(posedge clk) count_c==3);
+
+endmodule

examples/make_tracing_c/top.v

@@ -0,0 +1,46 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2003 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+// ======================================================================
+
+// This is intended to be a complex example of several features, please also
+// see the simpler examples/make_hello_c.
+
+module top
+  (
+   // Declare some signals so we can see how I/O works
+   input              clk,
+   input              reset_l,
+
+   output wire [1:0]  out_small,
+   output wire [39:0] out_quad,
+   output wire [69:0] out_wide,
+   input [1:0]        in_small,
+   input [39:0]       in_quad,
+   input [69:0]       in_wide
+   );
+
+   // Connect up the outputs, using some trivial logic
+   assign out_small = ~reset_l ? '0 : (in_small + 2'b1);
+   assign out_quad  = ~reset_l ? '0 : (in_quad + 40'b1);
+   assign out_wide  = ~reset_l ? '0 : (in_wide + 70'b1);
+
+   // And an example sub module. The submodule will print stuff.
+   sub sub (/*AUTOINST*/
+            // Inputs
+            .clk                        (clk),
+            .reset_l                    (reset_l));
+
+   // Print some stuff as an example
+   initial begin
+      if ($test$plusargs("trace") != 0) begin
+         $display("[%0t] Tracing to logs/vlt_dump.vcd...\n", $time);
+         $dumpfile("logs/vlt_dump.vcd");
+         $dumpvars();
+      end
+      $display("[%0t] Model running...\n", $time);
+   end
+
+endmodule

examples/make_tracing_sc/.gitignore

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

examples/make_tracing_sc/Makefile

@@ -0,0 +1,116 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: Small Makefile
+#
+# This calls the object directory makefile.  That allows the objects to
+# be placed in the "current directory" which simplifies the Makefile.
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+# Check for sanity to avoid later confusion
+
+ifneq ($(words $(CURDIR)),1)
+ $(error Unsupported: GNU Make cannot build in directories containing spaces, build elsewhere: '$(CURDIR)')
+endif
+
+######################################################################
+# Set up variables
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+VERILATOR_COVERAGE = verilator_coverage
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+VERILATOR_COVERAGE = $(VERILATOR_ROOT)/bin/verilator_coverage
+endif
+
+VERILATOR_FLAGS =
+# Generate SystemC in executable form
+VERILATOR_FLAGS += -sc --exe
+# Generate makefile dependencies (not shown as complicates the Makefile)
+#VERILATOR_FLAGS += -MMD
+# Optimize
+VERILATOR_FLAGS += -Os -x-assign 0
+# Warn abount lint issues; may not want this on less solid designs
+VERILATOR_FLAGS += -Wall
+# Make waveforms
+VERILATOR_FLAGS += --trace
+# Check SystemVerilog assertions
+VERILATOR_FLAGS += --assert
+# Generate coverage analysis
+VERILATOR_FLAGS += --coverage
+# Run Verilator in debug mode
+#VERILATOR_FLAGS += --debug
+# Add this trace to get a backtrace in gdb
+#VERILATOR_FLAGS += --gdbbt
+
+# Input files for Verilator
+VERILATOR_INPUT = -f input.vc top.v sc_main.cpp
+
+# Check if SC exists via a verilator call (empty if not)
+SYSTEMC_EXISTS := $(shell $(VERILATOR) --getenv SYSTEMC_INCLUDE)
+
+######################################################################
+
+ifneq ($(SYSTEMC_EXISTS),)
+default: run
+else
+default: nosc
+endif
+
+run:
+	@echo
+	@echo "-- Verilator tracing example"
+
+	@echo
+	@echo "-- VERILATE ----------------"
+	$(VERILATOR) $(VERILATOR_FLAGS) $(VERILATOR_INPUT)
+
+	@echo
+	@echo "-- COMPILE -----------------"
+# To compile, we can either
+# 1. Pass --build to Verilator by editing VERILATOR_FLAGS above.
+# 2. Or, run the make rules Verilator does:
+#	$(MAKE) -j -C obj_dir -f Vtop.mk
+# 3. Or, call a submakefile where we can override the rules ourselves:
+	$(MAKE) -j -C obj_dir -f ../Makefile_obj
+
+	@echo
+	@echo "-- RUN ---------------------"
+	@rm -rf logs
+	@mkdir -p logs
+	obj_dir/Vtop +trace
+
+	@echo
+	@echo "-- COVERAGE ----------------"
+	@rm -rf logs/annotated
+	$(VERILATOR_COVERAGE) --annotate logs/annotated logs/coverage.dat
+
+	@echo
+	@echo "-- DONE --------------------"
+	@echo "To see waveforms, open vlt_dump.vcd in a waveform viewer"
+	@echo
+
+
+######################################################################
+# Other targets
+
+nosc:
+	@echo
+	@echo "%Skip: SYSTEMC_INCLUDE not in environment"
+	@echo "(If you have SystemC see the README, and rebuild Verilator)"
+	@echo
+
+show-config:
+	$(VERILATOR) -V
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir logs *.log *.dmp *.vpd coverage.dat core

examples/make_tracing_sc/Makefile_obj

@@ -0,0 +1,65 @@
+# -*- Makefile -*-
+#######################################################################
+#
+# DESCRIPTION: Verilator Example: Makefile for inside object directory
+#
+# This is executed in the object directory, and called by ../Makefile
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+#######################################################################
+
+default: Vtop
+
+# Include the rules made by Verilator
+include Vtop.mk
+
+# Use OBJCACHE (ccache) if using gmake and its installed
+COMPILE.cc = $(OBJCACHE) $(CXX) $(CXXFLAGS) $(CPPFLAGS) $(TARGET_ARCH) -c
+
+#######################################################################
+# Compile flags
+
+# Override some default compile flags
+CPPFLAGS += -MMD -MP
+CPPFLAGS += -DVL_DEBUG=1
+# SystemC isn't too clean
+CPPFLAGS += -Wno-deprecated
+# Turn on some more flags (when configured appropriately)
+# For testing inside Verilator, "configure --enable-ccwarn" will do this
+# automatically; otherwise you may want this unconditionally enabled
+ifeq ($(CFG_WITH_CCWARN),yes)	# Local... Else don't burden users
+USER_CPPFLAGS_WALL += -W -Werror -Wall
+endif
+
+# If you build your own rules from scratch, note you need to include
+# SystemC as follows (Vtop.mk file includes verilated.mk with these
+# already).
+# CPPFLAGS += $(SYSTEMC_CXX_FLAGS) $(addprefix -I, $(SYSTEMC_INCLUDE))
+# LDFLAGS  += $(SYSTEMC_CXX_FLAGS) $(addprefix -L, $(SYSTEMC_LIBDIR))
+
+# See the benchmarking section of bin/verilator.
+# Support class optimizations.  This includes the tracing and symbol table.
+# SystemC takes minutes to optimize, thus it is off by default.
+OPT_SLOW =
+# Fast path optimizations.  Most time is spent in these classes.
+OPT_FAST = -Os -fstrict-aliasing
+#OPT_FAST = -O
+#OPT_FAST =
+
+#######################################################################
+# Linking final exe -- presumes have a sim_main.cpp
+
+# Special compile rule
+sim_main.o: sim_main.cpp $(VM_PREFIX).h
+
+######################################################################
+######################################################################
+# Automatically understand dependencies
+
+DEPS := $(wildcard *.d)
+ifneq ($(DEPS),)
+include $(DEPS)
+endif

examples/make_tracing_sc/input.vc

@@ -0,0 +1,2 @@
+// This file typically lists flags required by a large project, e.g. include directories
++librescan +libext+.v+.sv+.vh+.svh -y .

examples/make_tracing_sc/sc_main.cpp

@@ -0,0 +1,139 @@
+// -*- SystemC -*-
+// DESCRIPTION: Verilator Example: Top level main for invoking SystemC model
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2017 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+//======================================================================
+
+// For std::unique_ptr
+#include <memory>
+
+// SystemC global header
+#include <systemc.h>
+
+// Include common routines
+#include <verilated.h>
+#if VM_TRACE
+#include <verilated_vcd_sc.h>
+#endif
+
+#include <sys/stat.h>  // mkdir
+
+// Include model header, generated from Verilating "top.v"
+#include "Vtop.h"
+
+int sc_main(int argc, char* argv[]) {
+    // This is a more complicated example, please also see the simpler examples/make_hello_c.
+
+    // Prevent unused variable warnings
+    if (false && argc && argv) {}
+
+    // Set debug level, 0 is off, 9 is highest presently used
+    // May be overridden by commandArgs
+    Verilated::debug(0);
+
+    // Randomization reset policy
+    // May be overridden by commandArgs
+    Verilated::randReset(2);
+
+    // Pass arguments so Verilated code can see them, e.g. $value$plusargs
+    // This needs to be called before you create any model
+    Verilated::commandArgs(argc, argv);
+
+    // Create logs/ directory in case we have traces to put under it
+    Verilated::mkdir("logs");
+
+    // General logfile
+    ios::sync_with_stdio();
+
+    // Define clocks
+    sc_clock clk{"clk", 10, SC_NS, 0.5, 3, SC_NS, true};
+    sc_clock fastclk{"fastclk", 2, SC_NS, 0.5, 2, SC_NS, true};
+
+    // Define interconnect
+    sc_signal<bool> reset_l;
+    sc_signal<vluint32_t> in_small;
+    sc_signal<vluint64_t> in_quad;
+    sc_signal<sc_bv<70>> in_wide;
+    sc_signal<vluint32_t> out_small;
+    sc_signal<vluint64_t> out_quad;
+    sc_signal<sc_bv<70>> out_wide;
+
+    // Construct the Verilated model, from inside Vtop.h
+    // Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end
+    const std::unique_ptr<Vtop> top{new Vtop{"top"}};
+
+    // Attach signals to the model
+    top->clk(clk);
+    top->fastclk(fastclk);
+    top->reset_l(reset_l);
+    top->in_small(in_small);
+    top->in_quad(in_quad);
+    top->in_wide(in_wide);
+    top->out_small(out_small);
+    top->out_quad(out_quad);
+    top->out_wide(out_wide);
+
+#if VM_TRACE
+    // Before any evaluation, need to know to calculate those signals only used for tracing
+    Verilated::traceEverOn(true);
+#endif
+
+    // You must do one evaluation before enabling waves, in order to allow
+    // SystemC to interconnect everything for testing.
+    sc_start(1, SC_NS);
+
+#if VM_TRACE
+    // If verilator was invoked with --trace argument,
+    // and if at run time passed the +trace argument, turn on tracing
+    VerilatedVcdSc* tfp = nullptr;
+    const char* flag = Verilated::commandArgsPlusMatch("trace");
+    if (flag && 0 == strcmp(flag, "+trace")) {
+        cout << "Enabling waves into logs/vlt_dump.vcd...\n";
+        tfp = new VerilatedVcdSc;
+        top->trace(tfp, 99);  // Trace 99 levels of hierarchy
+        Verilated::mkdir("logs");
+        tfp->open("logs/vlt_dump.vcd");
+    }
+#endif
+
+    // Simulate until $finish
+    while (!Verilated::gotFinish()) {
+#if VM_TRACE
+        // Flush the wave files each cycle so we can immediately see the output
+        // Don't do this in "real" programs, do it in an abort() handler instead
+        if (tfp) tfp->flush();
+#endif
+
+        // Apply inputs
+        if (sc_time_stamp() > sc_time(1, SC_NS) && sc_time_stamp() < sc_time(10, SC_NS)) {
+            reset_l = !1;  // Assert reset
+        } else {
+            reset_l = !0;  // Deassert reset
+        }
+
+        // Simulate 1ns
+        sc_start(1, SC_NS);
+    }
+
+    // Final model cleanup
+    top->final();
+
+    // Close trace if opened
+#if VM_TRACE
+    if (tfp) {
+        tfp->close();
+        tfp = nullptr;
+    }
+#endif
+
+    //  Coverage analysis (since test passed)
+#if VM_COVERAGE
+    Verilated::mkdir("logs");
+    VerilatedCov::write("logs/coverage.dat");
+#endif
+
+    // Return good completion status
+    return 0;
+}

examples/make_tracing_sc/sub.v

@@ -0,0 +1,59 @@
+// DESCRIPTION: Verilator: Verilog Test module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2003 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+// ======================================================================
+
+module sub
+  (
+   input clk,
+   input fastclk,
+   input reset_l
+   );
+
+   // Example counter/flop
+   reg [31:0] count_f;
+   always_ff @ (posedge fastclk) begin
+      if (!reset_l) begin
+         /*AUTORESET*/
+         // Beginning of autoreset for uninitialized flops
+         count_f <= 32'h0;
+         // End of automatics
+      end
+      else begin
+         count_f <= count_f + 1;
+      end
+   end
+
+   // Another example flop
+   reg [31:0] count_c;
+   always_ff @ (posedge clk) begin
+      if (!reset_l) begin
+         /*AUTORESET*/
+         // Beginning of autoreset for uninitialized flops
+         count_c <= 32'h0;
+         // End of automatics
+      end
+      else begin
+         count_c <= count_c + 1;
+         if (count_c >= 3) begin
+            $display("[%0t] fastclk is %0d times faster than clk\n",
+                     $time, count_f/count_c);
+            // This write is a magic value the Makefile uses to make sure the
+            // test completes successfully.
+            $write("*-* All Finished *-*\n");
+            $finish;
+         end
+      end
+   end
+
+   // An example assertion
+   always_ff @ (posedge clk) begin
+      AssertionExample: assert(!reset_l || count_c<100);
+   end
+
+   // And example coverage analysis
+   cover property (@(posedge clk) count_c==3);
+
+endmodule

examples/make_tracing_sc/top.v

@@ -0,0 +1,43 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2003 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+// ======================================================================
+
+// This is intended to be a complex example of several features, please also
+// see the simpler examples/make_hello_c.
+
+module top
+  (
+   // Declare some signals so we can see how I/O works
+   input              clk,
+   input              fastclk,
+   input              reset_l,
+
+   output wire [1:0]  out_small,
+   output wire [39:0] out_quad,
+   output wire [69:0] out_wide,
+   input [1:0]        in_small,
+   input [39:0]       in_quad,
+   input [69:0]       in_wide
+   );
+
+   // Connect up the outputs, using some trivial logic
+   assign out_small = ~reset_l ? '0 : (in_small + 2'b1);
+   assign out_quad  = ~reset_l ? '0 : (in_quad + 40'b1);
+   assign out_wide  = ~reset_l ? '0 : (in_wide + 70'b1);
+
+   // And an example sub module. The submodule will print stuff.
+   sub sub (/*AUTOINST*/
+            // Inputs
+            .clk                        (clk),
+            .fastclk                    (fastclk),
+            .reset_l                    (reset_l));
+
+   // Print some stuff as an example
+   initial begin
+      $display("[%0t] Model running...\n", $time);
+   end
+
+endmodule

examples/xml_py/.gitignore

@@ -0,0 +1,6 @@
+obj_*
+copied
+*.csv
+*.dot
+*.dmp
+*.pdf

examples/xml_py/Makefile

@@ -0,0 +1,61 @@
+######################################################################
+#
+# DESCRIPTION: Verilator Example: XML tests
+#
+# This file ONLY is placed under the Creative Commons Public Domain, for
+# any use, without warranty, 2020 by Wilson Snyder.
+# SPDX-License-Identifier: CC0-1.0
+#
+######################################################################
+
+# This makefile is not intended to be useful as an example itself,
+# it is just to run the small example scripts in this directory.
+
+# If $VERILATOR_ROOT isn't in the environment, we assume it is part of a
+# package install, and verilator is in your path. Otherwise find the
+# binary relative to $VERILATOR_ROOT (such as when inside the git sources).
+ifeq ($(VERILATOR_ROOT),)
+VERILATOR = verilator
+else
+export VERILATOR_ROOT
+VERILATOR = $(VERILATOR_ROOT)/bin/verilator
+endif
+
+DOT = dot
+PYTHON3 = python3
+
+PYTHON_VERSION := $(shell ${PYTHON3} --version 2>&1)
+PYTHON_VERSION_FULL := $(wordlist 2,4,$(subst ., ,${PYTHON_VERSION}))
+PYTHON_VERSION_MAJOR := $(word 1,${PYTHON_VERSION_FULL})
+PYTHON_VERSION_MINOR := $(word 2,${PYTHON_VERSION_FULL})
+PYTHON_GE_3_5 := $(shell [ ${PYTHON_VERSION_MAJOR} -eq 3 -a ${PYTHON_VERSION_MINOR} -ge 5 ] && echo true)
+
+ifeq (${PYTHON_GE_3_5},true)
+default: test
+else
+default: python_message
+endif
+
+python_message:
+	@echo "Found Python version ${PYTHON_VERSION}, but require >= 3.5"
+
+test: \
+	test-vl_file_copy \
+	test-vl_hier_graph \
+
+test-vl_file_copy:
+	@echo "-- vl_file_copy example"
+	$(PYTHON3) vl_file_copy -odir copied top.v
+	@cmp copied/top.v top.v
+	@cmp copied/sub.v sub.v
+
+test-vl_hier_graph:
+	@echo "-- vl_hier_graph example"
+	$(PYTHON3) vl_hier_graph -o graph.dot top.v
+	@echo "Manually run: " $(DOT) -Tpdf -o graph.pdf graph.dot
+
+######################################################################
+
+maintainer-copy::
+clean mostlyclean distclean maintainer-clean::
+	-rm -rf obj_dir *.log *.csv *.dmp *.dot *.vpd *.pdf core copied

examples/xml_py/sub.v

@@ -0,0 +1,18 @@
+// DESCRIPTION: Verilator: Verilog Test module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2019 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+// ======================================================================
+
+module sub
+  #(parameter type TYPE_t = logic)
+   (
+    input  TYPE_t in,
+    output TYPE_t out
+    );
+
+   // Some simple logic
+   always_comb out = ~ in;
+
+endmodule

examples/xml_py/top.v

@@ -0,0 +1,33 @@
+// DESCRIPTION: Verilator: Verilog example module
+//
+// This file ONLY is placed under the Creative Commons Public Domain, for
+// any use, without warranty, 2019 by Wilson Snyder.
+// SPDX-License-Identifier: CC0-1.0
+// ======================================================================
+
+module top
+  (
+   input              clk,
+   input              fastclk,
+   input              reset_l,
+
+   output wire [1:0]  out_small,
+   output wire [39:0] out_quad,
+   output wire [69:0] out_wide,
+   input [1:0]        in_small,
+   input [39:0]       in_quad,
+   input [69:0]       in_wide
+   );
+
+   sub #(.TYPE_t(logic [1:0])) sub_small
+     (.in(in_small),
+      .out(out_small));
+
+   sub #(.TYPE_t(logic [39:0])) sub_quad
+     (.in(in_quad),
+      .out(out_quad));
+
+   sub #(.TYPE_t(logic [69:0])) sub_wide
+     (.in(in_wide),
+      .out(out_wide));
+endmodule

examples/xml_py/vl_file_copy

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+# -*- Python -*- See copyright, etc below
+######################################################################
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+from shutil import copy2
+from pprint import pprint, pformat
+
+#######################################################################
+
+
+class VlFileCopy:
+    def __init__(
+        self,
+        verilator_args,  # presently all verilator options are passed-thru
+        # ideally this script would check against options mentioned in help
+        debug=0,
+        output_dir='copied'):  # directory name we output file uses
+        self.debug = debug
+
+        xml_temp = tempfile.NamedTemporaryFile()
+
+        args = [
+            '--xml-output',
+            xml_temp.name,
+            '--bbox-sys',  # Parse some stuff can't translate
+            '--bbox-unsup',
+            '--prefix vlxml'
+        ]  # So we know name of .xml output
+        args += verilator_args
+        self.run_verilator(args)
+        self.tree = ET.parse(xml_temp.name)
+
+        os.makedirs(output_dir, 0o777, True)
+
+        # Find and copy the files
+        root = self.tree.getroot()
+        xfiles = root.find('files')
+        for xfile in xfiles.findall('file'):
+            filename = xfile.get('filename')
+            if not re.match('^<', filename):  # e.g. <built-in>
+                if self.debug:
+                    print("\tcp %s %s" % (filename, output_dir))
+                copy2(filename, output_dir)
+
+    def run_verilator(self, args):
+        """Run Verilator command, check errors"""
+        if os.getenv("VERILATOR_ROOT"):
+            command = os.getenv("VERILATOR_ROOT") + "/bin/verilator"
+        else:
+            command = "verilator"
+        command += ' ' + ' '.join(args)
+        if self.debug:
+            print("\t%s " % command)
+        status = subprocess.call(command, shell=True)
+        if status != 0:
+            raise Exception("Command failed running Verilator with '" +
+                            command + "', stopped")
+
+
+#######################################################################
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        allow_abbrev=False,
+        formatter_class=argparse.RawTextHelpFormatter,
+        description=
+        """Example of using Verilator XML output to copy a list of files to an
+output directory (-odir, defaults to 'copied'), e.g. to easily create a
+tarball of the design to pass to others.
+
+Example usage:
+     vl_file_copy -f input.vc top.v -odir mycopy
+     # This will make at least mycopy/top.v
+""",
+        epilog="""All other arguments are pass-thru to Verilator: e.g.:
+
+  +define+<var>=<value>      Set preprocessor define
+  -F <file>                  Parse options from a file, relatively
+  -f <file>                  Parse options from a file
+  -G<name>=<value>           Overwrite toplevel parameter
+  +incdir+<dir>              Directory to search for includes
+  +libext+<ext>+[ext]...     Extensions for finding modules
+  -v <filename>              Verilog library
+  -y <dir>                   Directory to search for modules
+
+This file ONLY is placed under the Creative Commons Public Domain, for
+any use, without warranty, 2019 by Wilson Snyder.
+SPDX-License-Identifier: CC0-1.0
+""")
+    parser.add_argument('-debug',
+                        '--debug',
+                        action='store_const',
+                        const=9,
+                        help='enable debug')
+    parser.add_argument('-odir',
+                        '--odir',
+                        action='store',
+                        metavar='directory',
+                        required=True,
+                        help='target output directory')
+    (args, rem) = parser.parse_known_args()
+
+    print(
+        "NOTE: vl_file_copy is only an example starting point for writing your own tool."
+    )
+    # That is:
+    # 1. We will accept basic patches
+    # 2. We are not expecting to make this globally useful. (e.g. we don't cleanup obj_dir)
+    # 3. "make install" will not install this.
+    # 4. This has not had production-worthy validation.
+
+    fc = VlFileCopy(output_dir=args.odir, debug=args.debug, verilator_args=rem)
+
+######################################################################
+### Local Variables:
+### compile-command: "./vl_file_copy -h ; VERILATOR_ROOT=$V4 ./vl_file_copy +define+thru top.v"
+### End:

examples/xml_py/vl_hier_graph

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# -*- Python -*- See copyright, etc below
+######################################################################
+
+import argparse
+import os
+import re
+import subprocess
+import sys
+import tempfile
+import xml.etree.ElementTree as ET
+from shutil import copy2
+from pprint import pprint, pformat
+
+#######################################################################
+
+
+class VlHierGraph:
+    def __init__(
+        self,
+        verilator_args,  # presently all verilator options are passed-thru
+        # ideally this script would check against options mentioned in help
+        debug=0,
+        output_filename='graph.dot'):  # output filename
+        self.debug = debug
+        self.next_vertex_number = 0
+        self.name_to_number = {}
+
+        xml_temp = tempfile.NamedTemporaryFile()
+
+        args = [
+            '--xml-output',
+            xml_temp.name,
+            '--bbox-sys',  # Parse some stuff can't translate
+            '--bbox-unsup',
+            '--prefix vlxml'
+        ]  # So we know name of .xml output
+        args += verilator_args
+        self.run_verilator(args)
+        self.tree = ET.parse(xml_temp.name)
+
+        with open(output_filename, "w") as fh:
+            # For more serious purposes, use the python graphviz package instead
+            fh.write("digraph {\n")
+            fh.write("  dpi=300;\n")
+            fh.write("  order=LR;\n")
+            fh.write(
+                "  node [fontsize=8 shape=\"box\" margin=0.01 width=0 height=0]"
+            )
+            fh.write("  edge [fontsize=6]")
+            # Find cells
+            root = self.tree.getroot()
+            netlist = root.find('netlist')
+            for module in netlist.findall('module'):
+                # origNames are before parameterization, name if after
+                mod_name = module.get('name')
+                mod_number = self.name_to_vertex_number(mod_name)
+                fh.write("  n%d [label=\"%s\"" % (mod_number, mod_name))
+                if module.get('topModule'):
+                    fh.write(" color=\"red\" rank=1")
+                fh.write("];\n")
+
+                for instance in module.findall('instance'):
+                    inst_name = instance.get('name')
+                    def_name = instance.get('defName')
+                    def_number = self.name_to_vertex_number(def_name)
+                    fh.write("  n%d->n%d [label=\"%s\"];\n" %
+                             (mod_number, def_number, inst_name))
+
+            fh.write("}\n")
+
+    def name_to_vertex_number(self, name):
+        if not name in self.name_to_number:
+            self.next_vertex_number += 1
+            self.name_to_number[name] = self.next_vertex_number
+        return self.name_to_number[name]
+
+    def run_verilator(self, args):
+        """Run Verilator command, check errors"""
+        if os.getenv("VERILATOR_ROOT"):
+            command = os.getenv("VERILATOR_ROOT") + "/bin/verilator"
+        else:
+            command = "verilator"
+        command += ' ' + ' '.join(args)
+        if self.debug:
+            print("\t%s " % command)
+        status = subprocess.call(command, shell=True)
+        if status != 0:
+            raise Exception("Command failed running Verilator with '" +
+                            command + "', stopped")
+
+
+#######################################################################
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(
+        allow_abbrev=False,
+        formatter_class=argparse.RawTextHelpFormatter,
+        description=
+        """Example of using Verilator XML output to create a .dot file showing the
+design module hierarchy.
+
+Example usage:
+     vl_hier_graph -f input.vc top.v -o graph.dot
+     dot -Tpdf -o graph.pdf graph.dot
+""",
+        epilog="""All other arguments are pass-thru to Verilator: e.g.:
+
+  +define+<var>=<value>      Set preprocessor define
+  -F <file>                  Parse options from a file, relatively
+  -f <file>                  Parse options from a file
+  -G<name>=<value>           Overwrite toplevel parameter
+  +incdir+<dir>              Directory to search for includes
+  +libext+<ext>+[ext]...     Extensions for finding modules
+  -v <filename>              Verilog library
+  -y <dir>                   Directory to search for modules
+
+This file ONLY is placed under the Creative Commons Public Domain, for
+any use, without warranty, 2019 by Wilson Snyder.
+SPDX-License-Identifier: CC0-1.0
+""")
+    parser.add_argument('-debug',
+                        '--debug',
+                        action='store_const',
+                        const=9,
+                        help='enable debug')
+    parser.add_argument('-o',
+                        '--o',
+                        action='store',
+                        metavar='filename',
+                        required=True,
+                        help='output filename')
+    (args, rem) = parser.parse_known_args()
+
+    print(
+        "NOTE: vl_hier_graph is only an example starting point for writing your own tool."
+    )
+    # That is:
+    # 1. We will accept basic patches
+    # 2. We are not expecting to make this globally useful. (e.g. we don't cleanup obj_dir)
+    # 3. "make install" will not install this.
+    # 4. This has not had production-worthy validation.
+
+    fc = VlHierGraph(output_filename=args.o,
+                     debug=args.debug,
+                     verilator_args=rem)
+
+######################################################################
+### Local Variables:
+### compile-command: "./vl_hier_graph -h ; VERILATOR_ROOT=$V4 ./vl_hier_graph +define+thru top.v"
+### End: