Version bump

Change the Travis builds to use workspaces and persistent ccache

We proceed in 2 stages (as before, but using workspaces for
persistence):
1. In the 'build' stage, we clone the repo, build it and
   save the whole checkout ($TRAVIS_BUILD_DIR) as a workspace
2. In the 'test' stage, rather than cloning the repo, multiple jobs
   pull down the same workspace we built to run the tests from

This enables:
- Reuse of the build in multiple test jobs (this is what we used the Travis
  cache for before)
- Each job having a separate persistent Travis cache, which now only
  contains the ccache. This means all jobs, including 'build' and 'test'
  jobs can make maximum use of ccache across runs. This drastically cuts
  down build times when the ccache hits, which is very often the case for
  'test' jobs. Also, the separate caches only store the objects build by
  the particular job that owns the cache, so we can keep the per job
  ccache small.

If the commit message contains '[travis ccache clear]', the ccache will
be cleared at the beginning of the build. This can be used to test build
complete within the 50 minute timeout imposed by Travis, even without a
persistent ccache.

.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:        Cpp03
+TabWidth:        8
+UseTab:          Never
+...
+

.clang-tidy

@@ -0,0 +1,9 @@
+Checks:          'clang-diagnostic-*,clang-analyzer-*,*,-modernize*,-hicpp*,-android-cloexec-fopen,-cert-dcl50-cpp,-cert-env33-c,-cert-err34-c,-cert-err58-cpp,-clang-analyzer-core.UndefinedBinaryOperatorResult,-clang-analyzer-security*,-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-default-arguments,-fuchsia-overloaded-operator,-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,-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/.github/blob/master/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/.github/blob/master/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/.github/blob/master/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"

.gitignore

@@ -1,4 +1,7 @@
+\#*
+.#*
 *~
+*.tidy
 *.old
 *.gz
 *.gz.uu
@@ -6,16 +9,28 @@
 *.info
 *.log
 *.1
+.*.swp
 *.tmp
 *.tex
+*.pdf
 /Makefile
 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/*

.travis.yml

@@ -0,0 +1,118 @@
+# DESCRIPTION: Travis-CI config
+#
+# Copyright 2003-2020 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
+
+version: ~> 1.0
+
+language: cpp
+
+cache:
+  directories:
+    - $HOME/.ccache
+
+env:
+  global:
+    - VERILATOR_ROOT=$TRAVIS_BUILD_DIR
+
+# The list and order of build stages
+stages:
+  - build # Build Verilator
+  - test  # Run tests
+
+# Dump info about the environment for debugging
+before_install:
+  # To dump the script that Travis itself is executing, add 'cat $0' here
+  - cd "$TRAVIS_BUILD_DIR" # Skipping the git clone in later stages requires this
+  - export CCACHE_MAXSIZE=$(ci/travis-ccache-size.bash) # Set here after the 'cd'
+  - env | sort
+  - ls -lA .
+  - ls -lA bin
+  - g++ -E -dM -c -x c++ /dev/null | sort
+  - clang++ -E -dM -c -x c++ /dev/null | sort
+
+# Install all dependencies
+install:
+  - ./ci/travis-install.bash
+
+before_script:
+  # ccache maintenance
+  - ./ci/travis-ccache-maint.bash
+  # On Focal, set the SystemC installation location
+  - |
+    if [ "$TRAVIS_DIST" = "focal" ]; then
+      export SYSTEMC_INCLUDE=/usr/include
+      export SYSTEMC_LIBDIR=/usr/lib/x86_64-linux-gnu
+    fi
+
+before_cache:
+  - ccache -s -z
+
+# All jobs run the same script
+script: ./ci/travis-script.bash
+
+# Enumerate all the jobs
+jobs:
+  include:
+    ############################################################################
+    # Jobs in the 'build' stage
+    ############################################################################
+    # GCC builds
+    - {stage: build, if: type  = cron, os: linux, dist: trusty, compiler: gcc,   workspaces: {create: {name: trusty-gcc,   paths: .}}}
+    - {stage: build, if: type  = cron, os: linux, dist: xenial, compiler: gcc,   workspaces: {create: {name: xenial-gcc,   paths: .}}}
+    - {stage: build, if: type  = cron, os: linux, dist: bionic, compiler: gcc,   workspaces: {create: {name: bionic-gcc,   paths: .}}}
+    - {stage: build,                   os: linux, dist: focal,  compiler: gcc,   workspaces: {create: {name: focal-gcc,    paths: .}}}
+    # Clang builds
+    - {stage: build, if: type  = cron, os: linux, dist: xenial, compiler: clang, workspaces: {create: {name: xenial-clang, paths: .}}}
+    - {stage: build,                   os: linux, dist: focal,  compiler: clang, workspaces: {create: {name: focal-clang,  paths: .}}}
+    # Coverage build
+    - {stage: build, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {create: {name: coverage,     paths: .}}, env: COVERAGE=1}
+    ############################################################################
+    # Jobs in the 'test' stage
+    ############################################################################
+    # GCC tests
+    - {stage: test, if: type  = cron, os: linux, dist: trusty, compiler: gcc,   workspaces: {use: trusty-gcc},   git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: trusty, compiler: gcc,   workspaces: {use: trusty-gcc},   git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: trusty, compiler: gcc,   workspaces: {use: trusty-gcc},   git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: trusty, compiler: gcc,   workspaces: {use: trusty-gcc},   git: {clone: false}, env: TESTS=vltmt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: gcc,   workspaces: {use: xenial-gcc},   git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: gcc,   workspaces: {use: xenial-gcc},   git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: gcc,   workspaces: {use: xenial-gcc},   git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: gcc,   workspaces: {use: xenial-gcc},   git: {clone: false}, env: TESTS=vltmt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: bionic, compiler: gcc,   workspaces: {use: bionic-gcc},   git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: bionic, compiler: gcc,   workspaces: {use: bionic-gcc},   git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: bionic, compiler: gcc,   workspaces: {use: bionic-gcc},   git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: bionic, compiler: gcc,   workspaces: {use: bionic-gcc},   git: {clone: false}, env: TESTS=vltmt-1}
+    - {stage: test, if: type != cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc},    git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type != cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc},    git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc},    git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc},    git: {clone: false}, env: TESTS=vltmt-1}
+    # Clang tests
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: clang, workspaces: {use: xenial-clang}, git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: clang, workspaces: {use: xenial-clang}, git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: clang, workspaces: {use: xenial-clang}, git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: xenial, compiler: clang, workspaces: {use: xenial-clang}, git: {clone: false}, env: TESTS=vltmt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: clang, workspaces: {use: focal-clang},  git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: clang, workspaces: {use: focal-clang},  git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type != cron, os: linux, dist: focal,  compiler: clang, workspaces: {use: focal-clang},  git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type != cron, os: linux, dist: focal,  compiler: clang, workspaces: {use: focal-clang},  git: {clone: false}, env: TESTS=vltmt-1}
+    # Coverage tests
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-dist}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vlt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vlt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vlt-2}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vlt-3}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vltmt-0}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vltmt-1}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vltmt-2}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: coverage},     git: {clone: false}, env: TESTS=coverage-vltmt-3}
+
+notifications:
+  email:
+    if: repo = verilator/verilator
+    recipients:
+      - [email protected]
+      - [email protected]

Artistic

@@ -0,0 +1,197 @@
+Artistic License 2.0
+
+Copyright (c) 2000-2006, The Perl Foundation.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+Preamble
+********
+
+This license establishes the terms under which a given free software
+Package may be copied, modified, distributed, and/or redistributed.  The
+intent is that the Copyright Holder maintains some artistic control over
+the development of that Package while still keeping the Package
+available as open source and free software.
+
+You are always permitted to make arrangements wholly outside of this
+license directly with the Copyright Holder of a given Package.  If the
+terms of this license do not permit the full use that you propose to
+make of the Package, you should contact the Copyright Holder and seek a
+different licensing arrangement.
+
+Definitions
+***********
+
+"Copyright Holder" means the individual(s) or organization(s) named in
+the copyright notice for the entire Package.
+
+"Contributor" means any party that has contributed code or other
+material to the Package, in accordance with the Copyright Holder's
+procedures.
+
+"You" and "your" means any person who would like to copy, distribute, or
+modify the Package.
+
+"Package" means the collection of files distributed by the Copyright
+Holder, and derivatives of that collection and/or of those files.  A
+given Package may consist of either the Standard Version, or a Modified
+Version.
+
+"Distribute" means providing a copy of the Package or making it
+accessible to anyone else, or in the case of a company or organization,
+to others outside of your company or organization.
+
+"Distributor Fee" means any fee that you charge for Distributing this
+Package or providing support for this Package to another party.  It does
+not mean licensing fees.
+
+"Standard Version" refers to the Package if it has not been modified, or
+has been modified only in ways explicitly requested by the Copyright
+Holder.
+
+"Modified Version" means the Package, if it has been changed, and such
+changes were not explicitly requested by the Copyright Holder.
+
+"Original License" means this Artistic License as Distributed with the
+Standard Version of the Package, in its current version or as it may be
+modified by The Perl Foundation in the future.
+
+"Source" form means the source code, documentation source, and
+configuration files for the Package.
+
+"Compiled" form means the compiled bytecode, object code, binary, or any
+other form resulting from mechanical transformation or translation of
+the Source form.
+
+Permission for Use and Modification Without Distribution
+********************************************************
+
+(1) You are permitted to use the Standard Version and create and use
+Modified Versions for any purpose without restriction, provided that you
+do not Distribute the Modified Version.
+
+Permissions for Redistribution of the Standard Version
+******************************************************
+
+(2) You may Distribute verbatim copies of the Source form of the
+Standard Version of this Package in any medium without restriction,
+either gratis or for a Distributor Fee, provided that you duplicate all
+of the original copyright notices and associated disclaimers.  At your
+discretion, such verbatim copies may or may not include a Compiled form
+of the Package.
+
+(3) You may apply any bug fixes, portability changes, and other
+modifications made available from the Copyright Holder.  The resulting
+Package will still be considered the Standard Version, and as such will
+be subject to the Original License.
+
+Distribution of Modified Versions of the Package as Source
+**********************************************************
+
+(4) You may Distribute your Modified Version as Source (either gratis or
+for a Distributor Fee, and with or without a Compiled form of the
+Modified Version) provided that you clearly document how it differs from
+the Standard Version, including, but not limited to, documenting any
+non-standard features, executables, or modules, and provided that you do
+at least ONE of the following:
+
+(a) make the Modified Version available to the Copyright Holder of the
+Standard Version, under the Original License, so that the Copyright
+Holder may include your modifications in the Standard Version.
+
+(b) ensure that installation of your Modified Version does not prevent
+the user installing or running the Standard Version.  In addition, the
+Modified Version must bear a name that is different from the name of the
+Standard Version.
+
+(c) allow anyone who receives a copy of the Modified Version to make the
+Source form of the Modified Version available to others under
+
+(i) the Original License or
+
+(ii) a license that permits the licensee to freely copy, modify and
+redistribute the Modified Version using the same licensing terms that
+apply to the copy that the licensee received, and requires that the
+Source form of the Modified Version, and of any works derived from it,
+be made freely available in that license fees are prohibited but
+Distributor Fees are allowed.
+
+Distribution of Compiled Forms of the Standard Version or Modified
+******************************************************************
+Versions without the Source
+***************************
+
+(5) You may Distribute Compiled forms of the Standard Version without
+the Source, provided that you include complete instructions on how to
+get the Source of the Standard Version.  Such instructions must be valid
+at the time of your distribution.  If these instructions, at any time
+while you are carrying out such distribution, become invalid, you must
+provide new instructions on demand or cease further distribution.  If
+you provide valid instructions or cease distribution within thirty days
+after you become aware that the instructions are invalid, then you do
+not forfeit any of your rights under this license.
+
+(6) You may Distribute a Modified Version in Compiled form without the
+Source, provided that you comply with Section 4 with respect to the
+Source of the Modified Version.
+
+Aggregating or Linking the Package
+**********************************
+
+(7) You may aggregate the Package (either the Standard Version or
+Modified Version) with other packages and Distribute the resulting
+aggregation provided that you do not charge a licensing fee for the
+Package.  Distributor Fees are permitted, and licensing fees for other
+components in the aggregation are permitted.  The terms of this license
+apply to the use and Distribution of the Standard or Modified Versions
+as included in the aggregation.
+
+(8) You are permitted to link Modified and Standard Versions with other
+works, to embed the Package in a larger work of your own, or to build
+stand-alone binary or bytecode versions of applications that include the
+Package, and Distribute the result without restriction, provided the
+result does not expose a direct interface to the Package.
+
+Items That are Not Considered Part of a Modified Version
+********************************************************
+
+(9) Works (including, but not limited to, modules and scripts) that
+merely extend or make use of the Package, do not, by themselves, cause
+the Package to be a Modified Version.  In addition, such works are not
+considered parts of the Package itself, and are not subject to the terms
+of this license.
+
+General Provisions
+******************
+
+(10) Any use, modification, and distribution of the Standard or Modified
+Versions is governed by this Artistic License.  By using, modifying or
+distributing the Package, you accept this license.  Do not use, modify,
+or distribute the Package, if you do not accept this license.
+
+(11) If your Modified Version has been derived from a Modified Version
+made by someone other than you, you are nevertheless required to ensure
+that your Modified Version complies with the requirements of this
+license.
+
+(12) This license does not grant you the right to use any trademark,
+service mark, tradename, or logo of the Copyright Holder.
+
+(13) This license includes the non-exclusive, worldwide, free-of-charge
+patent license to make, have made, use, offer to sell, sell, import and
+otherwise transfer the Package with respect to any patent claims
+licensable by the Copyright Holder that are necessarily infringed by the
+Package.  If you institute patent litigation (including a cross-claim or
+counterclaim) against any party alleging that the Package constitutes
+direct or contributory patent infringement, then this Artistic License
+to you shall terminate on the date that such litigation is filed.
+
+(14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT
+HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES.  THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT
+PERMITTED BY YOUR LOCAL LAW.  UNLESS REQUIRED BY LAW, NO COPYRIGHT
+HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE
+OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

COPYING

@@ -1,339 +0,0 @@
-		    GNU GENERAL PUBLIC LICENSE
-		       Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
-			    Preamble
-
-  The licenses for most software are designed to take away your
-freedom to share and change it.  By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users.  This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it.  (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.)  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
-this service 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 make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
-  For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have.  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.
-
-  We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
-  Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software.  If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
-  Finally, any free program is threatened constantly by software
-patents.  We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary.  To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
-  The precise terms and conditions for copying, distribution and
-modification follow.
-
-		    GNU GENERAL PUBLIC LICENSE
-   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
-  0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License.  The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language.  (Hereinafter, translation is included without limitation in
-the term "modification".)  Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope.  The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
-  1. You may copy and distribute 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 and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
-  2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
-    a) You must cause the modified files to carry prominent notices
-    stating that you changed the files and the date of any change.
-
-    b) You must cause any work that you distribute or publish, that in
-    whole or in part contains or is derived from the Program or any
-    part thereof, to be licensed as a whole at no charge to all third
-    parties under the terms of this License.
-
-    c) If the modified program normally reads commands interactively
-    when run, you must cause it, when started running for such
-    interactive use in the most ordinary way, to print or display an
-    announcement including an appropriate copyright notice and a
-    notice that there is no warranty (or else, saying that you provide
-    a warranty) and that users may redistribute the program under
-    these conditions, and telling the user how to view a copy of this
-    License.  (Exception: if the Program itself is interactive but
-    does not normally print such an announcement, your work based on
-    the Program is not required to print an announcement.)
-
-These requirements apply to the modified work as a whole.  If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works.  But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
-  3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
-    a) Accompany it with the complete corresponding machine-readable
-    source code, which must be distributed under the terms of Sections
-    1 and 2 above on a medium customarily used for software interchange; or,
-
-    b) Accompany it with a written offer, valid for at least three
-    years, to give any third party, for a charge no more than your
-    cost of physically performing source distribution, a complete
-    machine-readable copy of the corresponding source code, to be
-    distributed under the terms of Sections 1 and 2 above on a medium
-    customarily used for software interchange; or,
-
-    c) Accompany it with the information you received as to the offer
-    to distribute corresponding source code.  (This alternative is
-    allowed only for noncommercial distribution and only if you
-    received the program in object code or executable form with such
-    an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it.  For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable.  However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-
-  4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License.  Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
-  5. You are not required to accept this License, since you have not
-signed it.  However, nothing else grants you permission to modify or
-distribute the Program or its derivative works.  These actions are
-prohibited by law if you do not accept this License.  Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
-  6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions.  You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
-  7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-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
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all.  For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices.  Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-
-  8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded.  In such case, this License incorporates
-the limitation as if written in the body of this License.
-
-  9. The Free Software Foundation may publish revised and/or new versions
-of the 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 a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation.  If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
-  10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission.  For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this.  Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
-			    NO WARRANTY
-
-  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, 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.
-
-  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE 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.
-
-		     END OF TERMS AND CONDITIONS
-
-	Appendix: 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
-convey 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) 19yy  <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 2 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, write to the Free Software
-    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
-    Gnomovision version 69, Copyright (C) 19yy name of author
-    Gnomovision 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, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary.  Here is a sample; alter the names:
-
-  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
-  `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
-  <signature of Ty Coon>, 1 April 1989
-  Ty Coon, President of Vice
-
-This 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 Library General
-Public License instead of this License.

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,69 @@
-^CVS/
-/CVS/
+\.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_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$
+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
+.*~

Makefile.in

@@ -3,20 +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
-# General Public License or the Perl Artistic License.
-#
-# 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.
+# Copyright 2003-2020 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
 #
 #****************************************************************************/
 #
@@ -43,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. ####
 
@@ -53,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
@@ -70,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.
@@ -83,249 +78,432 @@ 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@
+CFG_WITH_THREADED = @CFG_WITH_THREADED@
+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 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]* \
-	include/verilatedos.[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/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/*.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)
 
 .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_includer $(DESTDIR)$(bindir)/verilator_includer )
-	( 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:
-	@echo "Install-project-quick (no strip) to $(DIRPROJECT)"
+install-cadtools-quick:
+ifeq ($(CFG_WITH_DEFENV),yes)
+	@echo "%Error: Reconfigure with './configure --disable-defenv' to avoid hardcoded paths."
+	false
+endif
+	@echo "Install-cadtools-quick (no strip) to $(VERILATOR_CAD_DIR)"
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/include/gtkwave
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/include/vltstd
+	$(MKINSTALLDIRS) $(VERILATOR_CAD_DIR)/bin
 	for p in $(INST_PROJ_FILES) ; do \
-	  $(INST_PROJ_CVS) $$p $(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)/include/*.cpp \
+	$(srcdir)/src/*.cpp )
+CPPCHECK_H = $(wildcard \
+	$(srcdir)/include/*.h \
+	$(srcdir)/src/*.h )
+CPPCHECK = src/cppcheck_filtered
+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 $(CPPCHECK_INC) $<
+
+CLANGTIDY = clang-tidy
+CLANGTIDY_FLAGS = -config=''
+CLANGTIDY_DEP = $(subst .h,.h.tidy,$(CPPCHECK_H)) \
+	$(subst .cpp,.cpp.tidy,$(CPPCHECK_CPP))
+
+clangtidy: $(CLANGTIDY_DEP)
+%.cpp.tidy: %.cpp
+	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- -DVL_DEBUG=1 -DVL_CPPCHECK=1 $(CPPCHECK_INC) | 2>&1 tee $@
+%.h.tidy: %.h
+	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- -DVL_DEBUG=1 -DVL_CPPCHECK=1 $(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
+
+CLANGFORMAT = clang-format
+CLANGFORMAT_FLAGS = -i
+
+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) $(CPPCHECK_CPP) $(CPPCHECK_H)
+
 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::
@@ -334,17 +512,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
 
@@ -353,17 +543,18 @@ dist-file-list:
 	@echo $(wildcard $(DISTFILES))
 	@echo "end-dist-file-list:";  # Scripts look for this
 
+print-cfg-with-threaded:
+	@echo $(CFG_WITH_THREADED)
+
 ######################################################################
 # 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://travis-ci.com/verilator/verilator.svg?branch=master[Build Status (Travis CI),link=https://travis-ci.com/verilator/verilator]
+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-2020 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,153 +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
-// General Public License or the Perl Artistic License.
-
-
-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-2020 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-2020 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,29 @@
-: # -*-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);
 
 #======================================================================
 
+# Old version 1 dump nodes with no dtypep's
+our %Ver1_Non_Dtyped = map {$_ => 1} qw(
+  ACTIVE ALWAYS ALWAYSPOST ALWAYSPUBLIC ATTROF BEGIN BREAK CASE CASEITEM
+  CCALL CELL CELLINLINE CFILE CFUNC CHANGEDET CLOCKING COMMENT CONTINUE
+  COVERDECL COVERINC COVERTOGGLE CRETURN CSTMT DEFPARAM DISABLE DISPLAY DOT
+  DPIEXPORT FCLOSE FFLUSH FINAL FINISH FOPEN GENCASE GENERATE GENFOR GENIF
+  IF IMPLICIT INITARRAY INITIAL JUMPGO JUMPLABEL MODULE NETLIST
+  NOTFOUNDMODULE PACKAGE PACKAGEIMPORT PARSEREF PIN PORT PRAGMA PRIMITIVE
+  PSLASSERT PSLCOVER PSLDEFCLOCK PULL RANGE READMEM REPEAT RETURN SCCTOR
+  SCDTOR SCHDR SCIMP SCIMPHDR SCINT SCOPE SELBIT SELEXTRACT SELMINUS
+  SELPLUS SENGATE SENITEM SENTREE SFORMAT SFORMATF STOP SYSIGNORE SYSTEMT
+  TASK TASKREF TEXT TOPSCOPE TYPEDEFFWD TYPETABLE UCSTMT UDPTABLE
+  UDPTABLELINE UNTILSTABLE VASSERT WHILE );
 
 #======================================================================
 # main
@@ -24,12 +34,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 +51,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 +65,98 @@ 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);
-    system("diff $tmp_a $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/;
+            $line =~ s!\@dt=0x\(G?/?([^)]+)\)!$1!g;  # NEW: @dt -> OLD: non @dt format
+            #                                        # Below Ver1_Non_Dtyped may replace above further
+            if ($line =~ /: ([A-Z]+) /) {
+                my $type = $1;
+                next if $type =~ 'DTYPE';
+                if ($type eq 'TYPETABLE' || $type eq 'RANGE') {
+                    $line =~ /^(\s+\S+:) /; my $prefix = $1;
+                    while (defined ($line=$f1->getline())) {
+                        next if $line =~ /^\s+[a-z]/;  # Table body
+                        next if $line =~ /^${prefix}[0-9]:/;
+                        goto same_line;
+                    }
+                    next;
+                }
+                if ($Ver1_Non_Dtyped{$type}) {
+                    $line =~ s! w[0-9]+!!g;
+                }
+            }
+            $line =~ s!\@dt=0$!NoW!g;   # NEW: dt=null -> common format
+            $line =~ s!\@dt=0 !NoW !g;  # NEW: dt=null -> common format
+            $line =~ s! s?w0$! NoW!g;   # OLD: no width -> common format
+            $line =~ s! s?w0 ! NoW !g;  # OLD: no width -> common format
+        }
+        print $f2 $line;
     }
     $f1->close;
     $f2->close;
@@ -106,8 +165,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 +176,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 +231,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
+Copyright 2005-2020 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 or the Perl Artistic License.
+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 +252,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,561 @@
+#!/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);
+    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 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);
+    printf "  Total cpus used           = %d\n", scalar(keys %{$Global{cpus}});
+    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});
+    printf "  Longest-thread efficiency = %0.1f%%\n", $long_efficiency*100;
+    my $mt_efficiency = $mt_mtask_time/($Global{last_end}*$nthreads);
+    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";
+    print "  min log(p2e) = $min_p2e  from mtask $min_mtask (predict $Mtasks{$min_mtask}{predict}, elapsed $Mtasks{$min_mtask}{elapsed})\n";
+    print "  max log(p2e) = $max_p2e  from mtask $max_mtask (predict $Mtasks{$max_mtask}{predict}, elapsed $Mtasks{$max_mtask}{elapsed})\n";
+
+    my $stddev = stddev(\@p2e_ratios);
+    my $mean = mean(\@p2e_ratios);
+    print "  mean = " . ($mean) . "\n";
+    print "  stddev = " . ($stddev) . "\n";
+    print "  e ^ stddev = " . exp($stddev). "\n";
+    print "\n";
+}
+
+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);
+    }
+
+    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-2020 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 program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# General Public License or the Perl Artistic License.
+# Copyright 2003-2020 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.  This package is free software; you
+Copyright 2007-2020 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 or the Perl Artistic License.
+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/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 Unix::Processors Parallel::Forker Bit::Vector
+
+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
+    perl -i -pe 's/VERILATOR_ROOT = \/usr\/local\/share\/verilator/VERILATOR_ROOT = vlt/g' ${obj_dir}/*.mk
+fi

ci/travis-ccache-maint.bash

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: Travis 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="${TRAVIS_PULL_REQUEST_SHA:-$TRAVIS_COMMIT}"
+if git log --format=%B -n 1 "$COMMIT" | grep -q -i '\[travis\s\+ccache\s\+clear\]'; then
+  echo "Flushing ccache due to commit message"
+  ccache -C
+fi
+
+# Dump stats, then zero stats
+ccache -s -z

ci/travis-ccache-size.bash

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: Travis CI ccache sizer
+#
+# 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 computes the size of the ccache to be used for a job. We want the
+# ccache to be just big enough to be able to hold a whole build so a re-build
+# of the same does not miss in the cache due to capacity, but we don't want the
+# ccache too big as pulling it down from the network takes time, and it is
+# unlikely objects from much earlier builds would be useful.
+################################################################################
+
+fatal() {
+  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
+}
+
+if [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
+  if [ "$COVERAGE" == 1 ]; then
+    echo "1024M"
+  else
+    echo "768M"
+  fi
+elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
+  if [[ $TESTS == coverage-* ]]; then
+    echo "1536M"
+  else
+    echo "256M"
+  fi
+else
+  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
+fi

ci/travis-install.bash

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: Travis 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.
+################################################################################
+
+# Note that Travis runs "apt-get update" when "apt-get install" is used in the
+# .travis.yml file directly, but since we invoke it via this script, we need to
+# run it manually where requried, otherwise some packages cannot be found.
+
+set -e
+set -x
+
+fatal() {
+  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
+}
+
+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 [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
+  ##############################################################################
+  # Dependencies of jobs in the 'build' stage, i.e.: packages required to
+  # build Verilator
+
+  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
+    time sudo apt-get update
+    sudo apt-get install libfl-dev
+    sudo apt-get install libgoogle-perftools-dev
+    if [ "$COVERAGE" = 1 ]; then
+      yes yes | sudo cpan -fi Unix::Processors Parallel::Forker
+    fi
+  else
+    fatal "Unknown os: '$TRAVIS_OS_NAME'"
+  fi
+elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
+  ##############################################################################
+  # Dependencies of jobs in the 'test' stage, i.e.: packages required to
+  # run the tests
+
+  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
+    sudo apt-get update
+    sudo apt-get install gdb gtkwave lcov
+    if [ "$TRAVIS_DIST" = "focal" ]; then
+      sudo apt-get install libsystemc-dev
+    fi
+    yes yes | sudo cpan -fi Unix::Processors Parallel::Forker
+    # Not listing Bit::Vector as slow to install, and only skips one test
+    install-vcddiff
+  else
+    fatal "Unknown os: '$TRAVIS_OS_NAME'"
+  fi
+else
+  ##############################################################################
+  # Unknown build stage
+  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
+fi

ci/travis-script.bash

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: Travis 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 .travis.yml spec simple. We pass job parameters via
+# environment variables using 'env' keys. Having different 'env' keys in jobs
+# ensures they use different Travis build caches.
+################################################################################
+
+set -e
+set -x
+
+fatal() {
+  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
+}
+
+if [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
+  ##############################################################################
+  # Build verilator
+
+  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
+    if [ "$COVERAGE" != 1 ]; then
+      autoconf
+      ./configure --enable-longtests --enable-ccwarn
+      make -j $(nproc)
+    else
+      nodist/code_coverage --stages 1-2
+    fi
+  else
+    fatal "Unknown os: '$TRAVIS_OS_NAME'"
+  fi
+elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
+  ##############################################################################
+  # Run tests
+
+  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
+    # Run the specified test
+    case $TESTS in
+      dist-vlt-0)
+        make -C test_regress SCENARIOS="--dist --vlt" DRIVER_HASHSET=--hashset=0/2
+        ;;
+      dist-vlt-1)
+        make -C test_regress SCENARIOS="--dist --vlt" 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-dist)
+        nodist/code_coverage --stages 3- --scenarios=--dist
+        ;;
+      coverage-vlt-0)
+        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=0/4
+        ;;
+      coverage-vlt-1)
+        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=1/4
+        ;;
+      coverage-vlt-2)
+        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=2/4
+        ;;
+      coverage-vlt-3)
+        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=3/4
+        ;;
+      coverage-vltmt-0)
+        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=0/4
+        ;;
+      coverage-vltmt-1)
+        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=1/4
+        ;;
+      coverage-vltmt-2)
+        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=2/4
+        ;;
+      coverage-vltmt-3)
+        nodist/code_coverage --stages 3- --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
+    fatal "Unknown os: '$TRAVIS_OS_NAME'"
+  fi
+else
+  ##############################################################################
+  # Unknown build stage
+  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
+fi

codecov.yml

@@ -0,0 +1,38 @@
+# DESCRIPTION: codecov.io config
+#
+# Copyright 2020-2020 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: "70...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,35 +1,153 @@
-dnl DESCRIPTION: Process this file with autoconf to produce a configure script.
-dnl Copyright 2003-2009 by Wilson Snyder. This program is free software; you can
-dnl redistribute it and/or modify it under the terms of either the GNU
-dnl General Public License or the Perl Artistic License.
+# DESCRIPTION: Process this file with autoconf to produce a configure script.
+#
+# Copyright 2003-2020 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.036 2020-06-06],
+        [https://verilator.org],
+        [verilator],[https://verilator.org])
+# When releasing, also update header of Changes file
+# and commit using "devel release" or "Version bump" message
 
-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)
+
+# CFG_WITH_PREC11
+AC_MSG_CHECKING(whether allow pre-C++11)
+AC_ARG_ENABLE([prec11],
+              [AS_HELP_STRING([--enable-prec11],
+                              [enable pre-C++11 compilers for Verilator binary
+                               and Verilated makefiles])],
+              [case "${enableval}" in
+                yes) CFG_WITH_PREC11=yes ;;
+                no)  CFG_WITH_PREC11=no ;;
+                *)   AC_MSG_ERROR([bad value ${enableval} for --enable-prec11]) ;;
+               esac],
+              [CFG_WITH_PREC11=no;]
+              )
+AC_SUBST(CFG_WITH_PREC11)
+AC_MSG_RESULT($CFG_WITH_PREC11)
+
+# Compiler flags
+CFLAGS+=" -I${includedir}"
+CPPFLAGS+=" -I${includedir}"
+CXXFLAGS+=" -I${includedir}"
+LDFLAGS+=" -L${libdir}"
+
+# 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
@@ -44,33 +162,310 @@ if test "x$YACC" = "x" ; then
    AC_MSG_ERROR([Cannot find "bison" in your PATH, please install it])
 fi
 
-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)
+
+# Set CFG_WITH_THREADED if can support threading
+AC_MSG_CHECKING(whether $CXX supports Verilated threads)
+ACO_SAVE_CXXFLAGS="$CXXFLAGS"
+CXXFLAGS="$CXXFLAGS $CFG_CXXFLAGS_STD_NEWEST $CFG_CXXFLAGS_NO_UNUSED"
+AC_LINK_IFELSE(
+     [AC_LANG_PROGRAM([#include <thread>], [[ ]])],
+     [_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])
+CFG_WITH_THREADED=$_my_result
+AC_SUBST(CFG_WITH_THREADED)
+AC_MSG_RESULT($CFG_WITH_THREADED)
+CXXFLAGS="$ACO_SAVE_CXXFLAGS"
+
+# Check compiler flag
+if test "$CFG_WITH_THREADED" = "no" ; then
+   if test "$CFG_WITH_PREC11" = "no" ; then
+      AC_MSG_NOTICE([[]])
+      AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
+
+Verilator plans to require a C++11 or newer compiler in a future release,
+unless sufficient people report problems. Therefore, if you do not have a
+C++11 compiler, please post a message to
+https://www.veripool.org/boards/3/topics/2580-Verilator-Requiring-C-11-compiler
+indicating your OS and when you think C++11 might be ok, and then rerun
+configure with the --enable-prec11 argument. Thanks.]])
+
+   fi
+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)])
+AC_COMPILE_IFELSE(
+    [AC_LANG_PROGRAM([[#include <systemc.h>
+                     ]],[])],
+    [_my_result=yes
+     AC_DEFINE([HAVE_SYSTEMC_H],[1],[Defined if have systemc.h])],
+    [_my_result=no])
+AC_MSG_RESULT($_my_result)
+AC_SUBST(HAVE_SYSTEMC_H)
+
+# 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 'make'])
+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 Travis CI to provide continuous integration. You may
+   want to setup Travis CI 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,66 @@
+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
+Chris Randall
+Dan Petrisko
+David Horton
+David Stanford
+Driss Hafdi
+Eric Rippey
+Garrett Smith
+Geza Lore
+Gianfranco Costamagna
+Glen Gibb
+Howard Su
+Huang Rui
+Iztok Jeras
+James Hanlon
+James Hutchinson
+Jamey Hicks
+Jan Van Winkel
+Jeremy Bennett
+John Coiner
+John Demme
+Julien Margetts
+Kanad Kanhere
+Kevin Kiningham
+Kuba Ober
+Ludwig Rogiers
+Lukasz Dalek
+Maarten De Braekeleer
+Maciej Sobkowski
+Marco Widmer
+Matthew Ballance
+Michael Killough
+Mike Popoloski
+Nathan Kohagen
+Nathan Myers
+Patrick Stewart
+Peter Horvath
+Peter Monsson
+Philipp Wagner
+Pieter Kapsenberg
+Qingyao Sun
+Richard Myers
+Sean Cross
+Sebastien Van Cauwenberghe
+Sergi Granell
+Stefan Wallentowitz
+Stephen Henry
+Tim Snyder
+Tobias Rosenkranz
+Tobias Wölfel
+Todd Strader
+Tomasz Gorochowik
+Tymoteusz Blazejczyk
+Vassilis Papaefstathiou
+Veripool API Bot
+Wilson Snyder
+Yossi Nivin
+Yuri Victorovich
+Yutetsu TAKATSUKASA
+Yves Mathieu

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-2020 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,113 @@
+// DESCRIPTION: Verilator: List of To Do issues.
+//
+// Copyright 2004-2020 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/XNOR/AND/OR bit selection trees
+   Foo = A[1] ^ A[2] ^ A[3] etc are better as ^ ( A & 32'b...1110 )
+** Combine variables into wider elements
+   Parallel statements on different bits should become single signal
+   Variables that are always consumed in "parallel" can be joined
+** Duplicate assignments in gate optimization
+   Common to have many separate posedge blocks, each with identical
+   reset_r <= rst_in
+** If signal is used only once (not counting trace), always gate substitute
+   Don't merge if any combining would form circ logic (out goes back to in)
+** Multiple assignments each bit can become single assign with concat
+   Make sure a SEL of a CONCAT can get the single bit back.
+** Usually blocks/values
+   Enable only after certain time, so VL_TIME_I(32) > 0x1e gets eliminated out
+** Better ordering of a<=b, b<=c, put all refs to 'b' next to each other to optimize caching
+** I-cache packing improvements (what/how?)
+** Data cache organization (order of vars in class)
+   First have clocks,
+   then bools instead of uint32_t's
+   then based on what sense list they come from, all outputs, then all inputs
+   finally have any signals part of a "usually" block, or constant.
+** Rather then tracking widths, have a MSB...LSB of this expression
+   (or better, a bitmask of bits relevant in this expression)
+** Track recirculation and convert into clock-enables
+** Clock enables should become new clocking domains for speed
+** If floped(a) & flopped(b) and no other a&b, then instead flop(a&b).
+** Sort by output bitselects so can combine more assignments (see DDP example dx_dm signal)

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,305 @@
+= 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://git.veripool.org/git/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.  Versions have
+also built on Redhat Linux, Apple OS-X, 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
+
+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 Unix::Processors
+   cpan install Parallel::Forker
+   cpan install Bit::Vector
+
+==== 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://git.veripool.org/git/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-2020 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-2020 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
+
+	@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
+
+	@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
+
+	@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
+
+	@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
+
+	@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;
+
+    // Fin
+    exit(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,52 @@
+// -*- 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
+#if (SYSTEMC_VERSION >= 20070314)
+    sc_start(1, SC_NS);
+#else
+    sc_start(1);
+#endif
+
+    // Simulate until $finish
+    while (!Verilated::gotFinish()) {
+#if (SYSTEMC_VERSION >= 20070314)
+        sc_start(1, SC_NS);
+#else
+        sc_start(1);
+#endif
+    }
+
+    // Final model cleanup
+    top->final();
+
+    // Fin
+    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 '-L../obj_dir_secret -lverilated_secret -static' 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,75 @@
+// 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 = NULL;
+    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 = NULL;
+    }
+#endif
+
+    // Destroy model
+    delete top;
+    top = NULL;
+
+    // Fin
+    exit(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,106 @@
+// 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"
+
+// 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"
+    Vtop* top = new Vtop;  // Or use a const unique_ptr, or the VL_UNIQUE_PTR wrapper
+
+    // 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
+
+    // Destroy model
+    delete top;
+    top = NULL;
+
+    // Fin
+    exit(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,158 @@
+// -*- 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>
+#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();
+
+    // Defaults time
+#if (SYSTEMC_VERSION > 20011000)
+#else
+    sc_time dut(1.0, sc_ns);
+    sc_set_default_time_unit(dut);
+#endif
+
+    // Define clocks
+#if (SYSTEMC_VERSION >= 20070314)
+    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);
+#else
+    sc_clock clk("clk", 10, 0.5, 3, true);
+    sc_clock fastclk("fastclk", 2, 0.5, 2, true);
+#endif
+
+    // 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
+    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.
+#if (SYSTEMC_VERSION >= 20070314)
+    sc_start(1, SC_NS);
+#else
+    sc_start(1);
+#endif
+
+#if VM_TRACE
+    // If verilator was invoked with --trace argument,
+    // and if at run time passed the +trace argument, turn on tracing
+    VerilatedVcdSc* tfp = NULL;
+    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
+#if (SYSTEMC_VERSION >= 20070314)
+        sc_start(1, SC_NS);
+#else
+        sc_start(1);
+#endif
+    }
+
+    // Final model cleanup
+    top->final();
+
+    // Close trace if opened
+#if VM_TRACE
+    if (tfp) {
+        tfp->close();
+        tfp = NULL;
+    }
+#endif
+
+    //  Coverage analysis (since test passed)
+#if VM_COVERAGE
+    Verilated::mkdir("logs");
+    VerilatedCov::write("logs/coverage.dat");
+#endif
+
+    // Destroy model
+    delete top;
+    top = NULL;
+
+    // Fin
+    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
+PYTHON = python3
+
+PYTHON_VERSION := $(shell ${PYTHON} --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"
+	$(PYTHON) 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"
+	$(PYTHON) 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,114 @@
+#!/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,138 @@
+#!/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:

include/.gitignore

@@ -1 +1,2 @@
 verilated.mk
+verilated_config.h