Version bump

cint.mainInt(nodep) walks the tree and populates m_ctorVarsVec.
Reuse EmitCImp cint for the slow mainImp() emition steps to make sure
we emit constructor calls to setup SystemC sc_module names.

.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
+...
+

.codacy.yml

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

.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,5 +1,6 @@
 \#*
 .#*
+.nfs*
 *~
 *.tidy
 *.old
@@ -17,6 +18,7 @@
 README
 TAGS
 autom4te.cache
+compile_commands.json
 config.cache
 config.status
 configure
@@ -30,4 +32,6 @@ verilator.txt
 verilator_bin*
 verilator_coverage_bin*
 verilator.pc
+verilator-config.cmake
+verilator-config-version.cmake
 **/obj_dir/*

.travis.yml

@@ -1,111 +1,148 @@
 # DESCRIPTION: Travis-CI config
 #
-# Copyright 2003-2019 by Todd Strader. Verilator is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU Lesser
-# General Public License Version 3 or the Perl Artistic License Version 2.0.
+# Copyright 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
 
-matrix:
-  include:
-# Non-cron build will just run on whatever linux flavor we get
-    - if: type != cron
-      os: linux
-      compiler: gcc
-      env:
-        - SCENARIOS=--dist
-    - if: type != cron
-      os: linux
-      compiler: gcc
-      env:
-        - SCENARIOS=--vlt
-    - if: type != cron
-      os: linux
-      compiler: gcc
-      env:
-        - SCENARIOS=--vltmt
-# Cron builds try different OS/compiler combinations
-    - if: type = cron
-      dist: xenial
-      compiler: gcc
-      env:
-        - SCENARIOS=--dist
-    - if: type = cron
-      dist: xenial
-      compiler: gcc
-      env:
-        - SCENARIOS=--vlt
-    - if: type = cron
-      dist: xenial
-      compiler: gcc
-      env:
-        - SCENARIOS=--vltmt
-    - if: type = cron
-      dist: xenial
-      compiler: clang
-      env:
-        - SCENARIOS=--dist
-    - if: type = cron
-      dist: xenial
-      compiler: clang
-      env:
-        - SCENARIOS=--vlt
-    - if: type = cron
-      dist: xenial
-      compiler: clang
-      env:
-        - SCENARIOS=--vltmt
-#    - if: type = cron
-#      os: osx
-#      compiler: gcc
-#      env:
-#        - SCENARIOS=--dist
-#    - if: type = cron
-#      os: osx
-#      compiler: gcc
-#      env:
-#        - SCENARIOS=--vlt
-#    - if: type = cron
-#      os: osx
-#      compiler: gcc
-#      env:
-#        - SCENARIOS=--vltmt
-    - if: type = cron
-      dist: trusty
-      compiler: gcc
-      env:
-        - SCENARIOS=--dist
-    - if: type = cron
-      dist: trusty
-      compiler: gcc
-      env:
-        - SCENARIOS=--vlt
-    - if: type = cron
-      dist: trusty
-      compiler: gcc
-      env:
-        - SCENARIOS=--vltmt
+cache:
+  directories:
+    - $HOME/.ccache
 
-cache: ccache
+env:
+  global:
+    - VERILATOR_ROOT=$TRAVIS_BUILD_DIR
 
-# Some tests require gdb
-addons:
-  apt:
-    packages:
-      - gdb
+# The list and order of build stages
+stages:
+  - build # Build Verilator
+  - test  # Run tests
 
+# Dump info about the environment for debugging
 before_install:
-# Perl modules needed for testing
-  - yes yes | sudo cpan -fi Unix::Processors Parallel::Forker Bit::Vector
+  # 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:
-  - export VLT_JOBS=$((`nproc` + 1))
-  - export OBJCACHE=ccache
-  - export VERILATOR_ROOT=`pwd`
-  - autoconf
-script:
-  - >
-    ./configure --enable-maintainer-mode --enable-longtests &&
-    make -j $VLT_JOBS &&
-    make test_regress DRIVER_FLAGS="-j 0 --quiet --rerun"
-after_script:
-  - ccache -s
+  # ccache maintenance
+  - ./ci/travis-ccache-maint.bash
+  # Don't produce core dumps (esp. on FreeBSD)
+  - ulimit -c 0
+  # On Focal, set the SystemC installation location
+  - |
+    if [ "$TRAVIS_DIST" = "focal" ] && [ "$M32" != "1" ]; then
+      export SYSTEMC_INCLUDE=/usr/include
+      export SYSTEMC_LIBDIR=/usr/lib/x86_64-linux-gnu
+    fi
+  # Override compiler for M32
+  - |
+    if [ "$M32" = "1" ]; then
+      export CC="$CC -m32"
+      export CXX="$CXX -m32"
+      unset M32 # verilated.mk actually references $(M32) so unset
+    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}
+    # 32-bit build
+    - {stage: build, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {create: {name: focal-gcc-m32, paths: .}}, env: M32=1}
+    # OS X build
+    - {stage: build, if: type  = cron, os: osx, osx_image: xcode11.6, compiler: clang, workspaces: {create: {name: osx-xcode11.6, paths: .}}}
+    # FreeBSD build
+    - {stage: build, if: type  = cron, os: freebsd, compiler: clang, workspaces: {create: {name: freebsd, paths: .}}}
+    ############################################################################
+    # 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}
+    # 32-bit tests
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc-m32}, git: {clone: false}, env: [M32=1, TESTS=dist-vlt-0]}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc-m32}, git: {clone: false}, env: [M32=1, TESTS=dist-vlt-1]}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc-m32}, git: {clone: false}, env: [M32=1, TESTS=vltmt-0]}
+    - {stage: test, if: type  = cron, os: linux, dist: focal,  compiler: gcc,   workspaces: {use: focal-gcc-m32}, git: {clone: false}, env: [M32=1, TESTS=vltmt-1]}
+    # OS X tests
+    - {stage: test, if: type  = cron, os: osx, osx_image: xcode11.6, compiler: clang, workspaces: {use: osx-xcode11.6},  git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: osx, osx_image: xcode11.6, compiler: clang, workspaces: {use: osx-xcode11.6},  git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: osx, osx_image: xcode11.6, compiler: clang, workspaces: {use: osx-xcode11.6},  git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: osx, osx_image: xcode11.6, compiler: clang, workspaces: {use: osx-xcode11.6},  git: {clone: false}, env: TESTS=vltmt-1}
+    # FreeBSD tests
+    - {stage: test, if: type  = cron, os: freebsd, compiler: clang, workspaces: {use: freebsd}, git: {clone: false}, env: TESTS=dist-vlt-0}
+    - {stage: test, if: type  = cron, os: freebsd, compiler: clang, workspaces: {use: freebsd}, git: {clone: false}, env: TESTS=dist-vlt-1}
+    - {stage: test, if: type  = cron, os: freebsd, compiler: clang, workspaces: {use: freebsd}, git: {clone: false}, env: TESTS=vltmt-0}
+    - {stage: test, if: type  = cron, os: freebsd, compiler: clang, workspaces: {use: freebsd}, git: {clone: false}, env: TESTS=vltmt-1}
+
+notifications:
+  email:
+    if: repo = verilator/verilator
+    recipients:
+      - [email protected]
+      - [email protected]

MANIFEST.SKIP

@@ -1,6 +1,8 @@
+\.clang-format
 \.clang-tidy
 \.git/
 \.git$
+\.github/
 \.svn/
 \.(bak|old)/
 \.(bak|old)$
@@ -14,31 +16,42 @@
 .*\.key
 .*\.vcd
 .*\.1
+\.codacy\.yml
 \.travis\.yml
-/obj_dir/
+/build/
 /obj_dbg/
+/obj_dir/
+/obj_dist/
+/obj_iv/
 /obj_nc/
 /obj_opt/
 /obj_vcs/
 /obj_vlt/
 /obj_vltmt/
-/obj_dist/
-/INCA_libs/
+INCA_libs/
 /cov_work/
 /logs/
 ^Makefile$
+README.html
 bin/verilator_bin.*
 bin/verilator_coverage_bin.*
+docs/.*\.html$
 docs/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.*
@@ -46,10 +59,11 @@ verilator_coverage_bin.*
 ncverilog.history
 autom4te\.cache/
 nodist/
+ci/
 /simv$
 /simv.daidir/
 /vc_hdrs.h$
 /csrc/
-obj_dir/.*
+obj_dir.*
 TAGS
 .*~

Makefile.in

@@ -3,19 +3,15 @@
 #
 # This file is part of Verilator.
 #
-# Code available from: http://www.veripool.org/verilator
+# Code available from: https://verilator.org
 #
 #*****************************************************************************
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
+# Copyright 2003-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.
-#
-# Verilator is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 #
 #****************************************************************************/
 #
@@ -103,13 +99,22 @@ PACKAGE_VERSION = @PACKAGE_VERSION@
 
 SHELL = /bin/sh
 
-SUBDIRS = src test_regress \
-	examples/hello_world_c  examples/hello_world_sc \
-	examples/tracing_c  examples/tracing_sc \
+SUBDIRS = docs src test_regress \
+	examples/cmake_hello_c \
+	examples/cmake_hello_sc \
+	examples/cmake_tracing_c \
+	examples/cmake_tracing_sc \
+	examples/cmake_protect_lib \
+	examples/make_hello_c \
+	examples/make_hello_sc \
+	examples/make_tracing_c \
+	examples/make_tracing_sc \
+	examples/make_protect_lib \
+	examples/xml_py \
 
-INFOS = README README.html README.pdf internals.txt internals.html \
-        internals.pdf verilator.txt verilator.html verilator.pdf \
-	$(VL_INST_MAN_FILES)
+INFOS = verilator.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
@@ -120,6 +125,9 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	Changes \
 	LICENSE \
 	MANIFEST.SKIP \
+	README.adoc \
+	verilator-config.cmake.in \
+	verilator-config-version.cmake.in \
 	bin/verilator \
 	bin/verilator_coverage \
 	bin/verilator_difftree \
@@ -127,12 +135,16 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	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 \
@@ -146,9 +158,15 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	src/.gdbinit \
 	src/*.pl src/*.pod \
 	examples/*/.*ignore examples/*/Makefile* \
-	examples/*/*.[chv]* examples/*/*.pl \
+	examples/*/*.[chv]* examples/*/vl_* \
+	examples/*/CMakeLists.txt \
 	test_*/.*ignore test_*/Makefile* test_*/*.cpp \
 	test_*/*.pl test_*/*.v test_*/*.vc test_*/*.vh \
+	test_regress/*.pl \
+	test_regress/Makefile \
+	test_regress/Makefile_obj \
+	test_regress/input.vc \
+	test_regress/CMakeLists.txt \
 	test_regress/t/t*/*.sv* \
 	test_regress/t/t*/*.v* \
 	test_regress/t/t*/*/*.sv* \
@@ -181,16 +199,13 @@ INST_PROJ_BIN_FILES = \
 DISTFILES := $(DISTFILES_INC)
 
 EXAMPLES_FIRST = \
-	examples/hello_world_c \
-	examples/hello_world_sc \
+	examples/make_hello_c \
+	examples/make_hello_sc \
 
 EXAMPLES = $(EXAMPLES_FIRST) $(filter-out $(EXAMPLES_FIRST), $(sort $(wildcard examples/*)))
 
-ifeq ($(OBJCACHE_JOBS),)
-ifneq ($(OBJCACHE_HOSTS),)
-export OBJCACHE_JOBS := -j $(shell objcache --jobs "$(OBJCACHE_HOSTS)")
-endif
-endif
+# 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
@@ -214,7 +229,9 @@ msg_test: all_nomsg
 
 .PHONY: test
 ifeq ($(CFG_WITH_LONGTESTS),yes)	# Local... Else don't burden users
-test: smoke-test examples test_regress
+test: smoke-test test_regress
+# examples is part of test_regress's test_regress/t/t_a2_examples.pl
+# (because that allows it to run in parallel with other test_regress's)
 else
 test: smoke-test examples
 endif
@@ -225,8 +242,8 @@ endif
 	@echo
 
 smoke-test: all_nomsg
-	test_regress/t/t_a_first_cc.pl
-	test_regress/t/t_a_first_sc.pl
+	test_regress/t/t_a1_first_cc.pl
+	test_regress/t/t_a2_first_sc.pl
 
 test_regress: all_nomsg
 	$(MAKE) -C test_regress
@@ -259,47 +276,12 @@ verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX)
 	pdflatex verilator.tex
 	-rm -f verilator.toc verilator.aux verilator.idx verilator.out
 
-README: README.pod
-	-rm -f $@
-	$(POD2TEXT) --loose $< > $@
-
-README.html: README.pod
-	pod2html $< >$@
-
-# PDF needs DIST variables; but having configure.ac as dependency isn't detected
-README.pdf: README.pod Makefile $(POD2LATEXFIX)
-	pod2latex --full --out README.tex $<
-	$(PERL) $(POD2LATEXFIX) "$(DISTTITLE) README File" "${DISTDATE}" < README.tex > README2.tex
-	mv README2.tex README.tex
-	pdflatex README.tex
-	pdflatex README.tex
-	-rm -f README.toc README.aux README.idx README.out
-
-internals.txt: internals.pod
-	-rm -f $@
-	$(POD2TEXT) --loose $< > $@
-
-internals.html: internals.pod
-	pod2html $< >$@
-
-# PDF needs DIST variables; but having configure.ac as dependency isn't detected
-internals.pdf: internals.pod Makefile $(POD2LATEXFIX)
-	pod2latex --full --out internals.tex $<
-	$(PERL) $(POD2LATEXFIX) "$(DISTTITLE) Internals Manual" "${DISTDATE}" < internals.tex > internals2.tex
-	mv internals2.tex internals.tex
-	pdflatex internals.tex
-	pdflatex internals.tex
-	-rm -f internals.toc internals.aux internals.idx internals.out
-
 # 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.
 
-# See uninstall also - don't put wildcards in this variable, it might uninstall other stuff
-VL_INST_MAN_FILES = verilator.1 verilator_coverage.1 verilator_gantt.1 verilator_profcfunc.1
-
 VL_INST_INC_BLDDIR_FILES = \
 	include/verilated_config.h \
 	include/verilated.mk \
@@ -312,6 +294,7 @@ VL_INST_INC_SRCDIR_FILES = \
 
 VL_INST_DATA_SRCDIR_FILES = \
 	examples/*/*.[chv]*  examples/*/Makefile* \
+	examples/*/CMakeLists.txt
 
 installbin:
 	$(MKINSTALLDIRS) $(DESTDIR)$(bindir)
@@ -343,16 +326,25 @@ installdata:
 	; for p in $(VL_INST_INC_SRCDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
-	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/hello_world_c
-	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/hello_world_sc
-	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/tracing_c
-	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/tracing_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_tracing_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/make_protect_lib
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_c
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_sc
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/cmake_protect_lib
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/examples/xml_py
 	cd $(srcdir) \
 	; for p in $(VL_INST_DATA_SRCDIR_FILES) ; do \
 	  $(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
 	done
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgconfigdir)
 	$(INSTALL_DATA) verilator.pc $(DESTDIR)$(pkgconfigdir)
+	$(INSTALL_DATA) verilator-config.cmake $(DESTDIR)$(pkgdatadir)
+	$(INSTALL_DATA) verilator-config-version.cmake $(DESTDIR)$(pkgdatadir)
 
 # We don't trust rm -rf, so rmdir instead as it will fail if user put in other files
 uninstall:
@@ -363,14 +355,23 @@ uninstall:
 	-cd $(DESTDIR)$(pkgdatadir) && rm -f $(VL_INST_INC_SRCDIR_FILES)
 	-cd $(DESTDIR)$(pkgdatadir) && rm -f $(VL_INST_DATA_SRCDIR_FILES)
 	-rm $(DESTDIR)$(pkgconfigdir)/verilator.pc
+	-rm $(DESTDIR)$(pkgdatadir)/verilator-config.cmake
+	-rm $(DESTDIR)$(pkgdatadir)/verilator-config-version.cmake
 	-rmdir $(DESTDIR)$(pkgdatadir)/bin
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/gtkwave
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/vltstd
 	-rmdir $(DESTDIR)$(pkgdatadir)/include
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/hello_world_c
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/hello_world_sc
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/tracing_c
-	-rmdir $(DESTDIR)$(pkgdatadir)/examples/tracing_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_tracing_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_protect_lib
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_hello_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_c
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_tracing_sc
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/cmake_protect_lib
+	-rmdir $(DESTDIR)$(pkgdatadir)/examples/xml_py
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples
 	-rmdir $(DESTDIR)$(pkgdatadir)
 	-rmdir $(DESTDIR)$(pkgconfigdir)
@@ -424,9 +425,13 @@ CPPCHECK_CPP = $(wildcard \
 CPPCHECK_H = $(wildcard \
 	$(srcdir)/include/*.h \
 	$(srcdir)/src/*.h )
+CPPCHECK_YL = $(wildcard \
+	$(srcdir)/src/*.y \
+	$(srcdir)/src/*.l )
 CPPCHECK = src/cppcheck_filtered
 CPPCHECK_FLAGS = --enable=all --inline-suppr \
-	--suppress=unusedScopedObject --suppress=cstyleCast --suppress=useInitializationList
+	--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
@@ -454,6 +459,14 @@ 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) $(CPPCHECK_YL)
+
 ftp: info
 
 install-msg:
@@ -463,7 +476,7 @@ install-msg:
 	@echo "Installed examples to $(DESTDIR)$(pkgdatadir)/examples"
 	@echo
 	@echo "For documentation see 'man verilator' or 'verilator --help'"
-	@echo "For forums and to report bugs see http://www.veripool.org/verilator"
+	@echo "For forums and to report bugs see https://verilator.org"
 	@echo
 
 IN_WILD := ${srcdir}/*.in ${srcdir}/*/*.in
@@ -502,12 +515,13 @@ 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 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 *.info* *.1 $(INFOS)
+	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*

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.

README.pod

@@ -1,284 +0,0 @@
-# DESCRIPTION: DOCUMENT source run through perl to produce README file
-# Use 'make README' to produce the output file
-
-=pod
-
-=for html <a href="https://travis-ci.com/verilator/verilator"><img src="https://travis-ci.com/verilator/verilator.svg?branch=master"></a>
-
-=head1 NAME
-
-Welcome to Verilator.  This is the Verilator package's README file.
-
-This document describes how to initially install Verilator.  For more
-general information please see L<http://verilator.org>.
-
-=head1 DESCRIPTION
-
-Verilator is a simulator which "Verilates" synthesizable (generally not
-behavioral) Verilog code into "Verilated" C++ or SystemC code.
-
-Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
-reads the specified Verilog code, lints it, and optionally adds coverage
-code.  For C++ format, it outputs .cpp and .h files.  For SystemC format,
-it outputs .cpp and .h files using the standard SystemC headers.
-
-The resulting files are then compiled with C++.  The user writes a little
-C++ wrapper file, which instantiates the top level module.  This is
-compiled in C++, and linked with the Verilated files.
-
-The resulting executable will perform the actual simulation.
-
-=head1 SUPPORTED SYSTEMS
-
-Verilator is developed and has primary testing on Ubuntu.  Versions have
-also built on Redhat Linux, Macs OS-X, HPUX and Solaris.  It should run
-with minor porting on any Linix-ish platform.  Verilator also works on
-Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin).  Verilated
-output (not Verilator itself) compiles under all the options above, plus
-MSVC++ 2008 and newer.
-
-=head1 INSTALLATION
-
-The following are detailed installation instructions.
-Alternatively, for a quick summary please see
-L<http://www.veripool.org/projects/verilator/wiki/Installing>.
-
-=over 4
-
-=item
-
-Obtain binary or sources:
-
-There are three methods to obtain Verilator, a prebuilt binary as part of
-your Linux distribution, via git, or using a tarball.  If you will be
-modifying Verilator, you should use the "git" method as it will let you
-track changes and hopefully contribute in the future.
-
-=over 4
-
-=item
-
-Prebuilt binary:
-
-You may install a binary on Ubuntu or other distributions using a package
-manager.  This is unlikely to be the most recent version.
-
-  apt-get install verilator
-
-You may now skip the remaining installation steps.
-
-=item
-
-Git:
-
-Get the sources from the repository.
-
-  git clone http://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
-
-=item
-
-Tarball:
-
-Get a recent tarball package from L<http://www.veripool.org/verilator>.
-Click the "Download" tab, scroll down to the latest package
-(i.e. verilator-#.###.tgz), download it, and decompress with:
-
-    tar xvzf verilator_#-###.tgz
-
-=back
-
-=item
-
-Install prerequisites:
-
-=over 4
-
-=item
-
-To use Verilator you will need the C<perl>, C<make> (or C<gmake>), and
-C<g++> (or C<clang>) packages. To compile Verilator in addition to the above you need the C<flex>,
-C<bison> and C<texi2html> packages installed.
-
-  sudo apt-get install git make autoconf g++ flex bisonz   # First time prerequisites
-  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)
-
-=item
-
-If you will be using SystemC (vs straight C++ output), download SystemC
-from L<http://www.systemc.org>.  Follow their installation instructions.
-You will need to set SYSTEMC_INCLUDE to point to the include directory with
-systemc.h in it, and SYSTEMC_LIBDIR to points to the directory with
-libsystemc.a in it.  (Older installations may set SYSTEMC and SYSTEMC_ARCH
-instead.)
-
-=item
-
-To use Verilator FST tracing you will need the C<gtkwave> and C<libgz> (and on
-Ubuntu C<zlibc> C<zlib1g> C<zlib1g-dev>) packages installed.
-
-=back
-
-=item
-
-Prepare for building:
-
-  cd verilator                # Needed if not already in the package
-  unsetenv VERILATOR_ROOT     # For csh; ignore error if on bash
-  unset VERILATOR_ROOT        # For bash; ignore error if on bash
-  # If using git:
-    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
-  #
-  autoconf                    # Create ./configure script
-
-=item
-
-Installation Choices
-
-You have to decide how you're going to eventually install the kit.
-
-Note Verilator builds the current value of VERILATOR_ROOT, SYSTEMC_INCLUDE,
-and SYSTEMC_LIBDIR as defaults into the executable, so try to have them
-correct before configuring.
-
-=over 4
-
-=item 1.
-
-Our personal favorite is to always run Verilator from its git directory.
-This allows the easiest experimentation and upgrading, and allows many
-versions of Verilator to co-exist on a system. To run you point to the
-program's files, no install is needed.
-
-    export VERILATOR_ROOT=`pwd`   # if your shell is bash
-    setenv VERILATOR_ROOT `pwd`   # if your shell is csh
-    ./configure
-
-Note after installing (below steps), a calling program should 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.
-
-=item 2.
-
-You may eventually be instaling onto a project/company-wide "CAD" tools
-disk that may support multiple versions of every tool.
-
-    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 C<modulecmd>, you'll want a
-module file like the following:
-
-    set install_root /CAD_DISK/verilator/{version-number-used-above}
-    unsetenv VERILATOR_ROOT
-    prepend-path PATH $install_root/bin
-    prepend-path MANPATH $install_root/man
-    prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
-
-=item 3.
-
-The next option is to eventually install it globally, using the normal system paths:
-
-    unset VERILATOR_ROOT      # if your shell is bash
-    unsetenv VERILATOR_ROOT   # if your shell is csh
-    ./configure
-
-Then after installing (below) the binary directories should already be in
-your PATH.
-
-=item 4.
-
-Finally, you may eventually install it 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.
-
-=back
-
-Note all of the options above did:
-
-    ./configure  ... some options ...
-
-Add to this line C<--enable-longtests> for more complete developer tests.
-Additional packages may be required for these tests.
-
-=item
-
-Type C<make> to compile Verilator.
-
-=item
-
-Type C<make test> to check the compilation.
-
-=item
-
-If you used the prefix scheme, now do a C<make install>.
-
-=item
-
-You may now wish to consult the examples directory. Type C<make> inside any
-example directory to run the example.
-
-=back
-
-=head1 USAGE DOCUMENTATION
-
-Detailed documentation and the man page can be seen by running:
-
-    bin/verilator --help
-
-or reading verilator.pdf in the same directory as this README.
-
-or see L<https://www.veripool.org/ftp/verilator_doc.pdf> (which is the most
-recent version and thus may differ in some respects from the version you installed).
-
-=head1 PACKAGE DIRECTORY STRUCTURE
-
-The directories in the package directory are as follows:
-
-    Changes                     => Version history
-    bin/verilator               => Compiler Wrapper invoked to Verilate code
-    docs/                       => Additional documentation
-    examples/hello_world_c      => Example simple Verilog->C++ conversion
-    examples/hello_world_sc     => Example simple Verilog->SystemC conversion
-    examples/tracing_c          => Example Verilog->C++ with tracing
-    examples/tracing_sc         => Example Verilog->SystemC with tracing
-    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
-    include/verilated.v         => Stub defines for linting
-    src/                        => Translator source code
-    test_regress                => Internal tests
-    verilator.pdf               => Primary documentation
-    verilator.txt               => Primary documentation (text)
-
-For files created after Verilation, see the manual.
-
-=head1 DISTRIBUTION
-
-This package is Copyright 2003-2019 by Wilson Snyder.  (Report bugs to
-L<http://www.veripool.org/>.)
-
-Verilator is free software; you can redistribute it and/or modify it under
-the terms of either the GNU Lesser General Public License Version 3 or the
-Perl Artistic License Version 2.0.  (See the documentation for more
-details.)
-
-This program is distributed in the hope that it will be useful, but WITHOUT
-ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
-more details.

bin/verilator_coverage

@@ -1,18 +1,11 @@
-: # -*-Mode: perl;-*- use perl, wherever it is
-eval 'exec perl -wS $0 ${1+"$@"}'
-  if 0;
+#!/usr/bin/env perl
 ######################################################################
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you
+# 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.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
 ######################################################################
 
 require 5.006_001;
@@ -66,7 +59,7 @@ run(verilator_coverage_bin()
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
 }
 
 sub debug {
@@ -134,7 +127,12 @@ sub run {
                 warn "%Error: Verilator_coverage threw signal $status.\n" if !$Debug;
             }
         }
-        die "%Error: Command Failed $command\n";
+        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
     }
 }
 
@@ -158,6 +156,8 @@ verilator_coverage - Verilator coverage analyzer
 
     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
@@ -226,8 +226,20 @@ Displays program version and exits.
 =item --write I<filename>
 
 Specifies the aggregate coverage results, summed across all the files,
-should be written to the given filename.  This is useful in scripts to
-combine many sequential runs into one master coverage file.
+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
 
@@ -264,12 +276,14 @@ Specifies a module search directory.
 
 =head1 DISTRIBUTION
 
-The latest version is available from L<http://www.veripool.org/>.
+The latest version is available from L<https://verilator.org>.
 
-Copyright 2003-2019 by Wilson Snyder.  Verilator is free software; you can
-redistribute it and/or modify the Verilator internals under the terms of
-either the GNU Lesser General Public License Version 3 or the Perl Artistic
-License Version 2.0.
+Copyright 2003-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
 
@@ -277,7 +291,7 @@ Wilson Snyder <[email protected]>
 
 =head1 SEE ALSO
 
-C<verilator>
+C<verilator>, C<lcov>
 
 L<verilator_coverage --help> which is the source for this document.
 

bin/verilator_difftree

@@ -1,10 +1,7 @@
-: # -*-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;
@@ -168,8 +165,8 @@ sub filter {
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
-    exit(1);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
 }
 
 sub debug {
@@ -234,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-2019 by Wilson Snyder.  This package is free software; you can
-redistribute it and/or modify it under the terms of either the GNU Lesser
-General Public License Version 3 or the Perl Artistic License Version 2.0.
+Copyright 2005-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
 

bin/verilator_gantt

@@ -1,11 +1,9 @@
-: # -*-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.
 ######################################################################
 
-use strict;
 use warnings;
+use strict;
 use Getopt::Long;
 use IO::File;
 use Pod::Usage;
@@ -43,8 +41,8 @@ exit(0);
 #######################################################################
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
-    exit(1);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
 }
 
 sub parameter {
@@ -125,13 +123,13 @@ sub report {
     }
 
     my $nthreads = scalar keys %Threads;
-    $Global{cpus}{cpu_time} = {};
+    $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_time}{$cpu} += $elapsed;
+            $Global{cpus}{$cpu}{cpu_time} += $elapsed;
         }
     }
 
@@ -538,11 +536,14 @@ verilator_gantt.vcd.
 
 =head1 DISTRIBUTION
 
-The latest version is available from L<http://www.veripool.org/>.
+The latest version is available from L<https://verilator.org>.
 
-Copyright 2018-2019 by Wilson Snyder.  Verilator is free software; you can
-redistribute it and/or modify it under the terms of either the GNU Lesser
-General Public License Version 3 or the Perl Artistic License Version 2.0.
+Copyright 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
 

bin/verilator_includer

@@ -1,11 +1,11 @@
-: # -*-Mode: perl;-*- use perl, wherever it is
-eval 'exec perl -wS $0 ${1+"$@"}'
-  if 0;
+#!/usr/bin/env perl
 # DESCRIPTION: Print include statements for each ARGV
 #
-# Copyright 2003-2019 by Wilson Snyder. This package is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU Lesser
-# General Public License Version 3 or the Perl Artistic License Version 2.0.
+# Copyright 2003-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;

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.
 ######################################################################
 
@@ -39,8 +37,8 @@ profcfunc($Opt_File);
 #----------------------------------------------------------------------
 
 sub usage {
-    pod2usage(-verbose=>2, -exitval=>2, -output=>\*STDOUT);
-    exit(1);
+    pod2usage(-verbose=>2, -exitval=>0, -output=>\*STDOUT);
+    exit(1);  # Unreachable
 }
 
 sub debug {
@@ -228,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-2019 by Wilson Snyder.  Verilator is free software; you can
-redistribute it and/or modify it under the terms of either the GNU Lesser
-General Public License Version 3 or the Perl Artistic License Version 2.0.
+Copyright 2007-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
 

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,104 @@
+#!/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;
+}
+
+if [ "$TRAVIS_OS_NAME" = "linux" ]; then
+  MAKE=make
+elif [ "$TRAVIS_OS_NAME" = "osx" ]; then
+  MAKE=make
+elif [ "$TRAVIS_OS_NAME" = "freebsd" ]; then
+  MAKE=gmake
+else
+  fatal "Unknown os: '$TRAVIS_OS_NAME'"
+fi
+
+install-vcddiff() {
+  TMP_DIR="$(mktemp -d)"
+  git clone https://github.com/veripool/vcddiff "$TMP_DIR"
+  git -C "${TMP_DIR}" checkout 5112f88b7ba8818dce9dfb72619e64a1fc19542c
+  "$MAKE" -C "${TMP_DIR}"
+  sudo cp "${TMP_DIR}/vcddiff" /usr/local/bin
+}
+
+if [ "$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
+    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
+    if [ "$M32" = 1 ]; then
+      sudo apt-get install gcc-multilib g++-multilib
+    fi
+  elif [ "$TRAVIS_OS_NAME" = "osx" ]; then
+    brew update
+    brew install ccache perl gperftools
+  elif [ "$TRAVIS_OS_NAME" = "freebsd" ]; then
+    sudo pkg install -y autoconf bison ccache gmake perl5
+  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
+    if [ "$M32" = 1 ]; then
+      sudo apt-get install lib32z1-dev gcc-multilib g++-multilib
+    fi
+  elif [ "$TRAVIS_OS_NAME" = "osx" ]; then
+    brew update
+    # brew cask install gtkwave # fst2vcd hangs at launch, so don't bother
+    brew install ccache perl
+  elif [ "$TRAVIS_OS_NAME" = "freebsd" ]; then
+    # fst2vcd fails with "Could not open '<input file>', exiting."
+    sudo pkg install -y ccache gmake perl5 python3
+  else
+    fatal "Unknown os: '$TRAVIS_OS_NAME'"
+  fi
+  # Common installs
+  if [ "$TRAVIS_DIST" != "trusty" ]; then
+    TRAVIS_CPAN_REPO=https://cpan.org
+  fi
+  # Not listing Bit::Vector as slow to install, and only skips one test
+  yes yes | sudo cpan -M $TRAVIS_CPAN_REPO -fi Unix::Processors Parallel::Forker
+  install-vcddiff
+else
+  ##############################################################################
+  # Unknown build stage
+  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
+fi

ci/travis-script.bash

@@ -0,0 +1,134 @@
+#!/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_OS_NAME" = "linux" ]; then
+  export MAKE=make
+  NPROC=$(nproc)
+elif [ "$TRAVIS_OS_NAME" = "osx" ]; then
+  export MAKE=make
+  NPROC=$(sysctl -n hw.logicalcpu)
+elif [ "$TRAVIS_OS_NAME" = "freebsd" ]; then
+  export MAKE=gmake
+  NPROC=$(sysctl -n hw.ncpu)
+else
+  fatal "Unknown os: '$TRAVIS_OS_NAME'"
+fi
+
+if [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
+  ##############################################################################
+  # Build verilator
+
+  if [ "$COVERAGE" != 1 ]; then
+    autoconf
+    ./configure --enable-longtests --enable-ccwarn
+    "$MAKE" -j "$NPROC"
+    if [ "$TRAVIS_OS_NAME" = "osx" ]; then
+      file bin/verilator_bin
+      file bin/verilator_bin_dbg
+      md5 bin/verilator_bin
+      md5 bin/verilator_bin_dbg
+      stat bin/verilator_bin
+      stat bin/verilator_bin_dbg
+    fi
+  else
+    nodist/code_coverage --stages 1-2
+  fi
+elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
+  ##############################################################################
+  # Run tests
+
+  if [ "$TRAVIS_OS_NAME" = "osx" ]; then
+    export VERILATOR_TEST_NO_GDB=1 # Pain to get GDB to work on OS X
+    export VERILATOR_TEST_NO_GPROF=1 # Apple Clang has no -pg
+    # export PATH="/Applications/gtkwave.app/Contents/Resources/bin:$PATH" # fst2vcd
+    file bin/verilator_bin
+    file bin/verilator_bin_dbg
+    md5 bin/verilator_bin
+    md5 bin/verilator_bin_dbg
+    stat bin/verilator_bin
+    stat bin/verilator_bin_dbg
+    # For some reason, the dbg exe is corrupted by this point ('file' reports
+    # it as data rather than a Mach-O). Unclear if this is an OS X issue or
+    # one for Travis. Remove the file and re-link...
+    rm bin/verilator_bin_dbg
+    "$MAKE" -j "$NPROC"
+  elif [ "$TRAVIS_OS_NAME" = "freebsd" ]; then
+    export VERILATOR_TEST_NO_GDB=1 # Disable for now, ideally should run
+    export VERILATOR_TEST_NO_GPROF=1 # gprof is a bit different on FreeBSD, disable
+  fi
+
+  # Run 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
+  ##############################################################################
+  # 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,21 +1,26 @@
 # DESCRIPTION: Process this file with autoconf to produce a configure script.
 #
-# Copyright 2003-2019 by Wilson Snyder. Verilator is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU Lesser
+# Copyright 2003-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.018 2019-08-29],
-        [https://www.veripool.org/verilator],
-        [verilator],[https://www.veripool.org/verilator])
+AC_INIT([Verilator],[4.040 2020-08-15],
+        [https://verilator.org],
+        [verilator],[https://verilator.org])
 # When releasing, also update header of Changes file
 # and commit using "devel release" or "Version bump" message
+# Then 'make maintainer-dist'
 
 AC_CONFIG_HEADER(src/config_build.h)
-AC_CONFIG_FILES(Makefile docs/Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc)
+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)
 
+# 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],
@@ -25,11 +30,43 @@ AC_ARG_ENABLE([maintainer-mode],
 AC_ARG_ENABLE([silent-rules],
               [AS_HELP_STRING([--disable-silent-rules], [ignored])])
 
+# Flag to enable linking specific libraries statically
+AC_MSG_CHECKING(whether to perform partial static linking of Verilator binary)
+AC_ARG_ENABLE([partial-static],
+              [AS_HELP_STRING([--disable-partial-static],
+                              [By default, for Verilation peformance, Verilator
+                               is linked against some of its dependencies
+                               statically. Use this to link the Verilator binary
+                               fully dynamically.])],
+              [case "${enableval}" in
+                yes) CFG_ENABLE_PARTIAL_STATIC=yes ;;
+                no)  CFG_ENABLE_PARTIAL_STATIC=no ;;
+                *)   AC_MSG_ERROR([bad value '${enableval}' for --disable-partial-static]) ;;
+               esac],
+               CFG_ENABLE_PARTIAL_STATIC=yes)
+AC_MSG_RESULT($CFG_ENABLE_PARTIAL_STATIC)
+
+# Flag to enable linking Verilator with tcmalloc if available
+AC_MSG_CHECKING(whether to use tcmalloc)
+AC_ARG_ENABLE([tcmalloc],
+              [AS_HELP_STRING([--enable-tcmalloc],
+                              [Use libtcmalloc_minimal for faster dynamic memory
+                               management in Verilator binary@<:@default=check@:>@])],
+              [case "${enableval}" in
+                yes) CFG_WITH_TCMALLOC=yes ;;
+                no)  CFG_WITH_TCMALLOC=no ;;
+                *)   AC_MSG_ERROR([bad value '${enableval}' for --enable-tcmalloc]) ;;
+               esac],
+              [CFG_WITH_TCMALLOC=check;])
+AC_MSG_RESULT($CFG_WITH_TCMALLOC)
+
 # Special Substitutions - CFG_WITH_DEFENV
 AC_MSG_CHECKING(whether to use hardcoded paths)
 AC_ARG_ENABLE([defenv],
               [AS_HELP_STRING([--disable-defenv],
-                              [disable using some hardcoded data paths extracted from some default environment variables (the default is to use hardcoded paths)])],
+                              [disable using some hardcoded data paths extracted
+                              from some default environment variables (the default
+                              is to use hardcoded paths) in Verilator binary])],
               [case "${enableval}" in
                 yes) CFG_WITH_DEFENV=yes ;;
                 no)  CFG_WITH_DEFENV=no ;;
@@ -43,7 +80,8 @@ AC_MSG_RESULT($CFG_WITH_DEFENV)
 AC_MSG_CHECKING(whether to show and stop on compilation warnings)
 AC_ARG_ENABLE([ccwarn],
               [AS_HELP_STRING([--enable-ccwarn],
-                              [enable showing and stopping on compilation warnings])],
+                              [enable showing and stopping on compilation warnings
+                               in Verilator binrary and Verilated makefiles])],
               [case "${enableval}" in
                 yes) CFG_WITH_CCWARN=yes ;;
                 no)  CFG_WITH_CCWARN=no ;;
@@ -77,24 +115,25 @@ 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])],
+AC_ARG_ENABLE([prec11-final],
+              [AS_HELP_STRING([--enable-prec11-final],
+                              [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]) ;;
+                *)   AC_MSG_ERROR([bad value ${enableval} for --enable-prec11-final]) ;;
                esac],
               [CFG_WITH_PREC11=no;]
               )
 AC_SUBST(CFG_WITH_PREC11)
 AC_MSG_RESULT($CFG_WITH_PREC11)
 
-# Compiler flags
-CFLAGS+=" -I${includedir}"
-CPPFLAGS+=" -I${includedir}"
-CXXFLAGS+=" -I${includedir}"
-LDFLAGS+=" -L${libdir}"
+# Compiler flags (ensure they are not empty to avoid configure defaults)
+CFLAGS+=" "
+CPPFLAGS+=" "
+CXXFLAGS+=" "
+LDFLAGS+=" "
 
 # Checks for programs.
 AC_PROG_CC
@@ -115,14 +154,26 @@ AC_PATH_PROG(PERL,perl)
 if test "x$PERL" = "x" ; then
    AC_MSG_ERROR([Cannot find "perl" in your PATH, please install it])
 fi
+
 AC_PATH_PROG(LEX,flex)
 if test "x$LEX" = "x" ; then
    AC_MSG_ERROR([Cannot find "flex" in your PATH, please install it])
 fi
+flex_version=$($LEX --version | head -1)
+AC_MSG_RESULT([$LEX --version = $flex_version])
+
 AC_PATH_PROG(YACC,bison)
 if test "x$YACC" = "x" ; then
    AC_MSG_ERROR([Cannot find "bison" in your PATH, please install it])
 fi
+bison_version=$($YACC --version | head -1)
+AC_MSG_RESULT([$YACC --version = $bison_version])
+
+AC_CHECK_PROG(OBJCACHE,ccache,ccache)
+if test "x$OBJCACHE" != "x" ; then
+  objcache_version=$($OBJCACHE --version | head -1)
+  AC_MSG_RESULT([objcache is $OBJCACHE --version = $objcache_version])
+fi
 
 # Checks for libraries.
 
@@ -209,15 +260,26 @@ AC_DEFUN([_MY_LDLIBS_CHECK_FLAG],
     LIBS="$ACO_SAVE_LIBS"
    ])
 
-AC_DEFUN([_MY_LDLIBS_CHECK_OPT],
-   [# _MY_LDLIBS_CHECK_OPT(flag) -- Check if linker supports specific options
-    # If it does, append flag to variable
-    _MY_LDLIBS_CHECK_FLAG($2)
+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
-       $1="$$1 $2"
+      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)
@@ -256,7 +318,6 @@ AC_SUBST(CFG_CXXFLAGS_WEXTRA)
 _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-undefined-bool-conversion)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-shadow)
 AC_SUBST(CFG_CXXFLAGS_SRC)
 
@@ -276,24 +337,78 @@ AC_SUBST(CFG_CXXFLAGS_PARSER)
 # 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)])
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-fbracket-depth=4096)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Qunused-arguments)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-bool-operation)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-parentheses-equality)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-sign-compare)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-uninitialized)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-unused-but-set-variable)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-unused-parameter)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-unused-variable)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_NO_UNUSED,-Wno-shadow)
+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
-_MY_LDLIBS_CHECK_OPT(CFG_LDLIBS_THREADS,-mt)
-_MY_LDLIBS_CHECK_OPT(CFG_LDLIBS_THREADS,-pthread)
-_MY_LDLIBS_CHECK_OPT(CFG_LDLIBS_THREADS,-lpthread)
-_MY_LDLIBS_CHECK_OPT(CFG_LDLIBS_THREADS,-latomic)
+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)
@@ -311,6 +426,7 @@ AC_LINK_IFELSE(
 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
@@ -318,12 +434,11 @@ if test "$CFG_WITH_THREADED" = "no" ; then
       AC_MSG_NOTICE([[]])
       AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
 
-Verilator plans to require a C++11 or newer compiler in a future release,
-unless sufficient people report problems. Therefore, if you do not have a
-C++11 compiler, please post a message to
-https://www.veripool.org/boards/3/topics/2580-Verilator-Requiring-C-11-compiler
-indicating your OS and when you think C++11 might be ok, and then rerun
-configure with the --enable-prec11 argument. Thanks.]])
+Verilator will require a C++11 or newer compiler for all releases starting
+September 2020.  Please investigate a C++11 build environment now so you
+will be ready.  Until then you may rerun configure with the
+--enable-prec11-final argument to enable reduced functionality with such
+older compilers. Thanks.]])
 
    fi
 fi
@@ -333,6 +448,24 @@ AC_CHECK_MEMBER([struct stat.st_mtim.tv_nsec],
     [AC_DEFINE([HAVE_STAT_NSEC],[1],[Defined if struct stat has st_mtim.tv_nsec])],
     [], [#include <sys/stat.h>])
 
+# HAVE_SYSTEMC
+# - If found the default search path has it, so support is always enabled.
+# - If not found or not system-wide, user can set SYSTEMC_INCLUDE.
+# AC_CHECK_HEADERS seems to not locate on Travis-CI but include does work.
+AC_MSG_CHECKING([whether SystemC is found (in system path)])
+ACO_SAVE_LIBS="$LIBS"
+LIBS="$LIBS -lsystemc"
+AC_LINK_IFELSE(
+    [AC_LANG_PROGRAM([[#include <systemc.h>
+                     extern "C" int sc_main(int argc, char* argv[]) {}
+                     ]],[[sc_version()]])],
+    [_my_result=yes
+     AC_DEFINE([HAVE_SYSTEMC],[1],[Defined if have SystemC library])],
+    [_my_result=no])
+AC_MSG_RESULT($_my_result)
+LIBS="$ACO_SAVE_LIBS"
+AC_SUBST(HAVE_SYSTEMC)
+
 # Checks for system services
 
 # Other install directories

docs/.gitignore

@@ -1 +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

@@ -1,17 +1,73 @@
 The contributors listed below have certified their Verilator contributions
-under the Developer Certificate of Origin
-(https://developercertificate.org/).
+under the Developer Certificate of Origin (https://developercertificate.org/).
 
-Please see the Verilator manual for additional contributors.
+Please see the Verilator manual for 200+ additional contributors. Thanks to all.
 
+Ahmed El-Mahmoudy
 Alex Chadwick
+Chris Randall
+Conor McCullough
+Dan Petrisko
+David Horton
+David Stanford
+Driss Hafdi
+Edgar E. Iglesias
+Eric Rippey
+Fan Shupei
+Garrett Smith
+Geza Lore
 Gianfranco Costamagna
+Glen Gibb
+Harald Heckmann
+Howard Su
+Huang Rui
+Iztok Jeras
+James Hanlon
+James Hutchinson
+Jamey Hicks
+Jan Van Winkel
 Jeremy Bennett
 John Coiner
+John Demme
+Josh Redford
+Julien Margetts
 Kanad Kanhere
+Kevin Kiningham
+Kuba Ober
+Ludwig Rogiers
+Lukasz Dalek
 Maarten De Braekeleer
+Maciej Sobkowski
+Marco Widmer
+Marshal Qiao
+Matthew Ballance
+Michael Killough
+Mike Popoloski
+Nathan Kohagen
+Nathan Myers
+Patrick Stewart
+Peter Horvath
+Peter Monsson
 Philipp Wagner
+Pieter Kapsenberg
+Piotr Binkowski
+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

@@ -3,19 +3,15 @@
 #
 # This file is part of Verilator.
 #
-# Code available from: http://www.veripool.org/verilator
+# Code available from: https://verilator.org
 #
 #*****************************************************************************
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
+# Copyright 2003-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.
-#
-# Verilator is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 #
 #****************************************************************************/
 #
@@ -23,6 +19,7 @@
 
 #### Start of system configuration section. ####
 
+ASCIIDOCTOR = asciidoctor
 DOXYGEN = doxygen
 
 #### End of system configuration section. ####
@@ -33,6 +30,9 @@ DOXYGEN = doxygen
 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
@@ -41,7 +41,7 @@ clean mostlyclean distclean maintainer-clean::
 	rm -f *.tex
 
 distclean maintainer-clean::
-	rm -f *.info* *.1 $(INFOS)
+	rm -f *.info* *.1 *.html *.pdf $(INFOS)
 	rm -f Makefile
 
 .PHONY: doxygen

docs/TODO

@@ -1,9 +1,10 @@
 // DESCRIPTION: Verilator: List of To Do issues.
 //
-// Copyright 2004-2019 by Wilson Snyder. This program is free software; you can
+// 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)
@@ -22,17 +23,10 @@
 ** Assertions
 ** Tristate support
 
-* Configure/Make/Install
-** Distribute with flex/bison already expanded?
-   Flex library not needed.  Probably too difficult to be worth it.
-
 * Testing:
-** Capture all inputs into global "rerun it" file
 ** Code to make wrapper that sets signals, so can do comparison checks
 ** New random program generator
 ** Better graph viewer with search and zoom
-** Port and test against opencores.org code
-** // verilator debug in code so can see only tree affecting those nodes
 
 * Usability:
 ** Detect and pre-remove most UNOPTFLATs

docs/doxygen-mainpage

@@ -3,4 +3,4 @@
  * \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://github.com/verilator/verilator   # Only first time
+## Note the URL above is not a page you can see with a browser, it's for git only
+
+# Every time you need to build:
+unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
+unset VERILATOR_ROOT  # For bash
+cd verilator
+git pull        # Make sure git repository is up-to-date
+git tag         # See what versions exist
+#git checkout master      # Use development branch (e.g. recent bug fixes)
+#git checkout stable      # Use most recent stable release
+#git checkout v{version}  # Switch to specified release version
+
+autoconf        # Create ./configure script
+./configure
+make
+sudo make install
+# Now see "man verilator" or online verilator.pdf's for the example tutorials
+....
+
+If this works, skip down to <<Running Verilator>>.
+
+== Detailed Build Instructions
+
+This section describes details of the build process, and assumes you are
+building from Git or a tarball.  For using a pre-built binary for your
+Linux distribution, see instead <<Install From a Package Manager>>.
+
+=== OS Requirements
+
+Verilator is developed and has primary testing on Ubuntu.  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 perl-doc
+
+To build Verilator you will need to install these packages; these do not
+need to be present to run Verilator:
+
+   sudo apt-get install git autoconf flex bison
+
+Those developing Verilator itself may also want these (see internals.adoc):
+
+   sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
+   cpan install Pod::Perldoc
+   cpan install 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://github.com/verilator/verilator   # Only first time
+   ## Note the URL above is not a page you can see with a browser, it's for git only
+
+Enter the checkout and determine what version/branch to use:
+
+   cd verilator
+   git pull        # Make sure we're up-to-date
+   git tag         # See what versions exist
+   #git checkout master      # Use development branch (e.g. recent bug fix)
+   #git checkout stable      # Use most recent release
+   #git checkout v{version}  # Switch to specified release version
+
+=== Auto Configure
+
+Create the configuration script:
+
+   autoconf        # Create ./configure script
+
+=== Eventual Installation Options
+
+Before configuring the build, you have to decide how you're going to
+eventually install the kit.  Verilator will be compiling the current value
+of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults
+into the executable, so they must be correct before configuring.
+
+These are the options:
+
+==== 1. Run-in-Place from VERILATOR_ROOT
+
+Our personal favorite is to always run Verilator in-place from its Git
+directory.  This allows the easiest experimentation and upgrading, and
+allows many versions of Verilator to co-exist on a system.
+
+   export VERILATOR_ROOT=`pwd`   # if your shell is bash
+   setenv VERILATOR_ROOT `pwd`   # if your shell is csh
+   ./configure
+   # Running will use files from $VERILATOR_ROOT, so no install needed
+
+Note after installing (below steps), a calling program or shell must set
+the environment variable `VERILATOR_ROOT` to point to this Git directory,
+then execute `$VERILATOR_ROOT/bin/verilator`, which will find the path to
+all needed files.
+
+==== 2. Install into a CAD Disk
+
+You may eventually be installing onto a project/company-wide "CAD" tools
+disk that may support multiple versions of every tool.  Target the build to
+a destination directory name that includes the Verilator version name:
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   # For the tarball, use the version number instead of git describe
+   ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`
+
+Note after installing (below steps), if you use
+http://modules.sourceforge.net/[modulecmd], you'll want a module file like
+the following:
+
+.modulecmd's verilator/version file
+----
+set install_root /CAD_DISK/verilator/{version-number-used-above}
+unsetenv VERILATOR_ROOT
+prepend-path PATH $install_root/bin
+prepend-path MANPATH $install_root/man
+prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
+----
+
+==== 3. Install into a Specific Path
+
+You may eventually install Verilator into a specific installation prefix,
+as most GNU tools support:
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   ./configure --prefix /opt/verilator-VERSION
+
+Then after installing (below steps) you will need to add
+`/opt/verilator-VERSION/bin` to `$PATH`.
+
+==== 4. Install System Globally
+
+The final option is to eventually install Verilator globally, using the
+normal system paths:
+
+   unset VERILATOR_ROOT      # if your shell is bash
+   unsetenv VERILATOR_ROOT   # if your shell is csh
+   ./configure
+
+Then after installing (below) the binary directories should already be in
+your `$PATH`.
+
+=== Configure
+
+The command to configure the package was described in the previous step.
+Developers should configure to have more complete developer tests.
+Additional packages may be required for these tests.
+
+   export VERILATOR_AUTHOR_SITE=1    # Put in your .bashrc
+   ./configure --enable-longtests  ...above options...
+
+=== Compile
+
+Compile Verilator:
+
+   make -j
+
+=== Test
+
+Check the compilation by running self-tests:
+
+   make test
+
+=== Install
+
+If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
+install to the OS-standard place:
+
+   make install
+
+== Running Verilator
+
+To run Verilator, see the example sections in the
+https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
+or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
+
+Also see the `examples/` directory that is part of the kit, and is installed
+(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
+
+     cd examples/make_hello_c
+     make
+
+Note if you did a `make install` above you should not have `VERILATOR_ROOT`
+set in your environment; it is built into the executable.
+
+== Announcements
+
+To get notified of new releases, go to
+https://github.com/verilator/verilator-announce[Verilator announcement
+repository] and follow the instructions there.
+
+== Directory Structure
+
+Some relevant files and directories in this package are as follows:
+
+   Changes                     => Version history
+   README.adoc                 => This document
+   bin/verilator               => Compiler wrapper invoked to Verilate code
+   docs/                       => Additional documentation
+   examples/make_hello_c       => Example GNU-make simple Verilog->C++ conversion
+   examples/make_hello_sc      => Example GNU-make simple Verilog->SystemC conversion
+   examples/make_tracing_c     => Example GNU-make Verilog->C++ with tracing
+   examples/make_tracing_sc    => Example GNU-make Verilog->SystemC with tracing
+   examples/make_protect_lib   => Example using --protect-lib
+   examples/cmake_hello_c      => Example building make_hello_c with CMake
+   examples/cmake_hello_sc     => Example building make_hello_sc with CMake
+   examples/cmake_tracing_c    => Example building make_tracing_c with CMake
+   examples/cmake_tracing_sc   => Example building make_tracing_sc with CMake
+   examples/cmake_protect_lib  => Example building make_protect_lib with CMake
+   include/                    => Files that should be in your -I compiler path
+   include/verilated*.cpp      => Global routines to link into your simulator
+   include/verilated*.h        => Global headers
+   include/verilated.mk        => Common Makefile
+   src/                        => Translator source code
+   test_regress                => Internal tests
+
+For files created after a design is Verilated, see the
+https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
+or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
+
+== License
+
+Copyright 2008-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

@@ -0,0 +1,7 @@
+*.dmp
+*.log
+*.csrc
+*.vcd
+obj_*
+logs
+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/Makefile

@@ -5,10 +5,9 @@
 # This calls the object directory makefile.  That allows the objects to
 # be placed in the "current directory" which simplifies the Makefile.
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
+# This 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
@@ -21,7 +20,7 @@ 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/tracing_c.
+# 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
@@ -35,14 +34,12 @@ endif
 
 default:
 	@echo "-- Verilator hello-world simple example"
-	@echo "-- VERILATE ----------------"
-	$(VERILATOR) -cc --exe top.v sim_main.cpp
-	@echo "-- COMPILE -----------------"
-	$(MAKE) -j 4 -C obj_dir -f Vtop.mk
+	@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/tracing_c."
+	@echo "Note: Once this example is understood, see examples/make_tracing_c."
 	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
 
 ######################################################################

examples/make_hello_c/sim_main.cpp

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2017 by Wilson Snyder.
+// 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
@@ -18,7 +19,7 @@ int main(int argc, char** argv, char** env) {
     // e.g. examples/c_tracing.
 
     // Prevent unused variable warnings
-    if (0 && argc && argv && env) {}
+    if (false && argc && argv && env) {}
 
     // Construct the Verilated model, from Vtop.h generated from Verilating "top.v"
     Vtop* top = new Vtop;

examples/make_hello_c/top.v

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2017 by Wilson Snyder.
+// 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;

examples/make_hello_sc/Makefile

@@ -5,10 +5,9 @@
 # This calls the object directory makefile.  That allows the objects to
 # be placed in the "current directory" which simplifies the Makefile.
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
+# This 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
@@ -21,7 +20,7 @@ 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/tracing_sc.
+# 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
@@ -44,14 +43,12 @@ endif
 
 run:
 	@echo "-- Verilator hello-world simple example"
-	@echo "-- VERILATE ----------------"
-	$(VERILATOR) -sc --exe top.v sc_main.cpp
-	@echo "-- COMPILE -----------------"
-	$(MAKE) -j 4 -C obj_dir -f Vtop.mk
+	@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/tracing_sc."
+	@echo "Note: Once this example is understood, see examples/make_tracing_sc."
 	@echo "Note: Also see the EXAMPLE section in the verilator manpage/document."
 
 ######################################################################

examples/make_hello_sc/sc_main.cpp

@@ -1,8 +1,9 @@
 // -*- SystemC -*-
 // DESCRIPTION: Verilator Example: Top level main for invoking SystemC model
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2017 by Wilson Snyder.
+// 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
@@ -22,22 +23,22 @@ int sc_main(int argc, char* argv[]) {
     // e.g. examples/c_tracing.
 
     // Prevent unused variable warnings
-    if (0 && argc && argv) {}
+    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);
+#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);
+#if (SYSTEMC_VERSION >= 20070314)
+        sc_start(1, SC_NS);
 #else
         sc_start(1);
 #endif

examples/make_hello_sc/top.v

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2017 by Wilson Snyder.
+// 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;

examples/make_protect_lib/.gitignore

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

examples/make_protect_lib/Makefile

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

examples/make_protect_lib/secret_impl.v

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

examples/make_protect_lib/sim_main.cpp

@@ -0,0 +1,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/Makefile

@@ -5,10 +5,9 @@
 # This calls the object directory makefile.  That allows the objects to
 # be placed in the "current directory" which simplifies the Makefile.
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
+# This 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
@@ -38,7 +37,7 @@ VERILATOR_FLAGS += -cc --exe
 # Generate makefile dependencies (not shown as complicates the Makefile)
 #VERILATOR_FLAGS += -MMD
 # Optimize
-VERILATOR_FLAGS += -O2 -x-assign 0
+VERILATOR_FLAGS += -Os -x-assign 0
 # Warn abount lint issues; may not want this on less solid designs
 VERILATOR_FLAGS += -Wall
 # Make waveforms
@@ -52,6 +51,9 @@ VERILATOR_FLAGS += --coverage
 # 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
 
@@ -61,22 +63,26 @@ run:
 
 	@echo
 	@echo "-- VERILATE ----------------"
-	$(VERILATOR) $(VERILATOR_FLAGS) -f input.vc top.v sim_main.cpp
+	$(VERILATOR) $(VERILATOR_FLAGS) $(VERILATOR_INPUT)
 
 	@echo
-	@echo "-- COMPILE -----------------"
-# To compile, we can either just do what Verilator asks,
-# or call a submakefile where we can override the rules ourselves
-#	$(MAKE) -j 4 -C obj_dir -f Vtop.mk
-	$(MAKE) -j 4 -C obj_dir -f ../Makefile_obj
+	@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

examples/make_tracing_c/Makefile_obj

@@ -5,10 +5,9 @@
 #
 # This is executed in the object directory, and called by ../Makefile
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
+# This 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
 #
 #######################################################################
 
@@ -38,7 +37,7 @@ endif
 # 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 = -O2 -fstrict-aliasing
+OPT_FAST = -Os -fstrict-aliasing
 #OPT_FAST = -O
 #OPT_FAST =
 

examples/make_tracing_c/sim_main.cpp

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2017 by Wilson Snyder.
+// 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
@@ -10,11 +11,6 @@
 // Include model header, generated from Verilating "top.v"
 #include "Vtop.h"
 
-// If "verilator --trace" is used, include the tracing class
-#if VM_TRACE
-# include <verilated_vcd_c.h>
-#endif
-
 // Current simulation time (64-bit unsigned)
 vluint64_t main_time = 0;
 // Called by $time in Verilog
@@ -23,10 +19,10 @@ double sc_time_stamp() {
 }
 
 int main(int argc, char** argv, char** env) {
-    // This is a more complicated example, please also see the simpler examples/hello_world_c.
+    // This is a more complicated example, please also see the simpler examples/make_hello_c.
 
     // Prevent unused variable warnings
-    if (0 && argc && argv && env) {}
+    if (false && argc && argv && env) {}
 
     // Set debug level, 0 is off, 9 is highest presently used
     // May be overridden by commandArgs
@@ -36,31 +32,21 @@ int main(int argc, char** argv, char** env) {
     // 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
 
-#if VM_TRACE
-    // If verilator was invoked with --trace argument,
-    // and if at run time passed the +trace argument, turn on tracing
-    VerilatedVcdC* tfp = NULL;
-    const char* flag = Verilated::commandArgsPlusMatch("trace");
-    if (flag && 0==strcmp(flag, "+trace")) {
-        Verilated::traceEverOn(true);  // Verilator must compute traced signals
-        VL_PRINTF("Enabling waves into logs/vlt_dump.vcd...\n");
-        tfp = new VerilatedVcdC;
-        top->trace(tfp, 99);  // Trace 99 levels of hierarchy
-        Verilated::mkdir("logs");
-        tfp->open("logs/vlt_dump.vcd");  // Open the dump file
-    }
-#endif
-
     // Set some inputs
     top->reset_l = !0;
-    top->fastclk = 0;
     top->clk = 0;
     top->in_small = 1;
     top->in_quad = 0x1234;
@@ -72,46 +58,39 @@ int main(int argc, char** argv, char** env) {
     while (!Verilated::gotFinish()) {
         main_time++;  // Time passes...
 
-        // Toggle clocks and such
-        top->fastclk = !top->fastclk;
-        if ((main_time % 10) == 3) {
-            top->clk = 1;
-        }
-        if ((main_time % 10) == 8) {
-            top->clk = 0;
-        }
-        if (main_time > 1 && main_time < 10) {
-            top->reset_l = !1;  // Assert reset
-        } else {
-            top->reset_l = !0;  // Deassert reset
-        }
+        // Toggle a fast (time/2 period) clock
+        top->clk = !top->clk;
 
-        // Assign some other inputs
-        top->in_quad += 0x12;
+        // 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();
 
-#if VM_TRACE
-        // Dump trace data for this cycle
-        if (tfp) tfp->dump(main_time);
-#endif
-
         // 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]);
+                  " -> 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();
 
-    // 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");
@@ -119,7 +98,8 @@ int main(int argc, char** argv, char** env) {
 #endif
 
     // Destroy model
-    delete top; top = NULL;
+    delete top;
+    top = NULL;
 
     // Fin
     exit(0);

examples/make_tracing_c/sub.v

@@ -1,31 +1,17 @@
 // DESCRIPTION: Verilator: Verilog Test module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2003 by Wilson Snyder.
+// 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
@@ -37,8 +23,6 @@ module sub
       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");

examples/make_tracing_c/top.v

@@ -1,25 +1,25 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2003 by Wilson Snyder.
+// 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/hello_world_c.
+// 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,
+   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
+   input [1:0]        in_small,
+   input [39:0]       in_quad,
+   input [69:0]       in_wide
    );
 
    // Connect up the outputs, using some trivial logic
@@ -31,11 +31,15 @@ module top
    sub sub (/*AUTOINST*/
             // Inputs
             .clk                        (clk),
-            .fastclk                    (fastclk),
             .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
 

examples/make_tracing_sc/Makefile

@@ -5,10 +5,9 @@
 # This calls the object directory makefile.  That allows the objects to
 # be placed in the "current directory" which simplifies the Makefile.
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
+# This 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
@@ -38,7 +37,7 @@ VERILATOR_FLAGS += -sc --exe
 # Generate makefile dependencies (not shown as complicates the Makefile)
 #VERILATOR_FLAGS += -MMD
 # Optimize
-VERILATOR_FLAGS += -O2 -x-assign 0
+VERILATOR_FLAGS += -Os -x-assign 0
 # Warn abount lint issues; may not want this on less solid designs
 VERILATOR_FLAGS += -Wall
 # Make waveforms
@@ -52,6 +51,9 @@ VERILATOR_FLAGS += --coverage
 # 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)
 
@@ -69,22 +71,26 @@ run:
 
 	@echo
 	@echo "-- VERILATE ----------------"
-	$(VERILATOR) $(VERILATOR_FLAGS) -f input.vc top.v sc_main.cpp
+	$(VERILATOR) $(VERILATOR_FLAGS) $(VERILATOR_INPUT)
 
 	@echo
-	@echo "-- COMPILE ----------------="
-# To compile, we can either just do what Verilator asks,
-# or call a submakefile where we can override the rules ourselves
-#	$(MAKE) -j 4 -C obj_dir -f Vtop.mk
-	$(MAKE) -j 4 -C obj_dir -f ../Makefile_obj
+	@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
@@ -92,6 +98,7 @@ run:
 	@echo "To see waveforms, open vlt_dump.vcd in a waveform viewer"
 	@echo
 
+
 ######################################################################
 # Other targets
 

examples/make_tracing_sc/Makefile_obj

@@ -5,10 +5,9 @@
 #
 # This is executed in the object directory, and called by ../Makefile
 #
-# Copyright 2003-2019 by Wilson Snyder. This program is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
+# This 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
 #
 #######################################################################
 
@@ -38,15 +37,15 @@ 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) -I$(SYSTEMC_INCLUDE)
-# LDFLAGS  += $(SYSTEMC_CXX_FLAGS) -L$(SYSTEMC_LIBDIR)
+# 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 = -O2 -fstrict-aliasing
+OPT_FAST = -Os -fstrict-aliasing
 #OPT_FAST = -O
 #OPT_FAST =
 

examples/make_tracing_sc/sc_main.cpp

@@ -1,8 +1,9 @@
 // -*- SystemC -*-
 // DESCRIPTION: Verilator Example: Top level main for invoking SystemC model
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2017 by Wilson Snyder.
+// 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
@@ -20,10 +21,10 @@
 #include "Vtop.h"
 
 int sc_main(int argc, char* argv[]) {
-    // This is a more complicated example, please also see the simpler examples/hello_world_c.
+    // This is a more complicated example, please also see the simpler examples/make_hello_c.
 
     // Prevent unused variable warnings
-    if (0 && argc && argv) {}
+    if (false && argc && argv) {}
 
     // Set debug level, 0 is off, 9 is highest presently used
     // May be overridden by commandArgs
@@ -37,23 +38,26 @@ int sc_main(int argc, char* argv[]) {
     // 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)
+#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);
+#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);
+    sc_clock clk("clk", 10, 0.5, 3, true);
+    sc_clock fastclk("fastclk", 2, 0.5, 2, true);
 #endif
 
     // Define interconnect
@@ -68,15 +72,15 @@ int sc_main(int argc, char* argv[]) {
     // 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);
+    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
@@ -85,8 +89,8 @@ int sc_main(int argc, char* argv[]) {
 
     // You must do one evaluation before enabling waves, in order to allow
     // SystemC to interconnect everything for testing.
-#if (SYSTEMC_VERSION>=20070314)
-    sc_start(1,SC_NS);
+#if (SYSTEMC_VERSION >= 20070314)
+    sc_start(1, SC_NS);
 #else
     sc_start(1);
 #endif
@@ -96,7 +100,7 @@ int sc_main(int argc, char* argv[]) {
     // 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")) {
+    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
@@ -114,15 +118,15 @@ int sc_main(int argc, char* argv[]) {
 #endif
 
         // Apply inputs
-        if (VL_TIME_Q() > 1 && VL_TIME_Q() < 10) {
+        if (sc_time_stamp() > sc_time(1, SC_NS) && sc_time_stamp() < sc_time(10, SC_NS)) {
             reset_l = !1;  // Assert reset
-        } else if (VL_TIME_Q() > 1) {
+        } else {
             reset_l = !0;  // Deassert reset
         }
 
         // Simulate 1ns
-#if (SYSTEMC_VERSION>=20070314)
-        sc_start(1,SC_NS);
+#if (SYSTEMC_VERSION >= 20070314)
+        sc_start(1, SC_NS);
 #else
         sc_start(1);
 #endif
@@ -133,7 +137,10 @@ int sc_main(int argc, char* argv[]) {
 
     // Close trace if opened
 #if VM_TRACE
-    if (tfp) { tfp->close(); tfp = NULL; }
+    if (tfp) {
+        tfp->close();
+        tfp = NULL;
+    }
 #endif
 
     //  Coverage analysis (since test passed)
@@ -143,7 +150,8 @@ int sc_main(int argc, char* argv[]) {
 #endif
 
     // Destroy model
-    delete top; top = NULL;
+    delete top;
+    top = NULL;
 
     // Fin
     return 0;

examples/make_tracing_sc/sub.v

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: Verilog Test module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2003 by Wilson Snyder.
+// 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

examples/make_tracing_sc/top.v

@@ -1,25 +1,26 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2003 by Wilson Snyder.
+// 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/hello_world_c.
+// 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,
+   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
+   input [1:0]        in_small,
+   input [39:0]       in_quad,
+   input [69:0]       in_wide
    );
 
    // Connect up the outputs, using some trivial logic

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/gtkwave/fastlz.c

@@ -22,6 +22,8 @@
   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
   THE SOFTWARE.
+
+  SPDX-License-Identifier: MIT
 */
 
 #include "fastlz.h"

include/gtkwave/fastlz.h

@@ -22,6 +22,8 @@
   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
   THE SOFTWARE.
+
+  SPDX-License-Identifier: MIT
 */
 
 #ifndef FASTLZ_H

include/gtkwave/fst_config.h

@@ -3,7 +3,7 @@
 /* config.h.in.  Generated from configure.ac by autoheader.  */
 
 /* Define to 1 if you have <alloca.h> and it should be used (not on Ultrix). */
-#if !defined(__MINGW32__)
+#if !defined(__MINGW32__) && !defined(__FreeBSD__)
 # define HAVE_ALLOCA_H 1
 #endif
 

include/gtkwave/fstapi.c

@@ -18,6 +18,8 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
  */
 
 /*
@@ -37,13 +39,15 @@
  *
  */
 
-// Verilator: use hardcoded config file
-//#include <config.h>
-#include "fst_config.h"
+#ifndef FST_CONFIG_INCLUDE
+# define FST_CONFIG_INCLUDE <config.h>
+#endif
+#include FST_CONFIG_INCLUDE
 
 #include "fstapi.h"
 #include "fastlz.h"
 #include "lz4.h"
+#include <errno.h>
 
 #ifndef HAVE_LIBPTHREAD
 #undef FST_WRITER_PARALLEL
@@ -130,6 +134,16 @@ void **JenkinsIns(void *base_i, const unsigned char *mem, uint32_t length, uint3
 #include <sys/sysctl.h>
 #endif
 
+#ifdef __GNUC__
+/* Boolean expression more often true than false */
+#define FST_LIKELY(x) __builtin_expect(!!(x), 1)
+/* Boolean expression more often false than true */
+#define FST_UNLIKELY(x) __builtin_expect(!!(x), 0)
+#else
+#define FST_LIKELY(x) (!!(x))
+#define FST_UNLIKELY(x) (!!(x))
+#endif
+
 #define FST_APIMESS "FSTAPI  | "
 
 /***********************/
@@ -725,6 +739,9 @@ off_t hier_file_len;
 uint32_t *valpos_mem;
 unsigned char *curval_mem;
 
+unsigned char *outval_mem; /* for two-state / Verilator-style value changes */
+uint32_t outval_alloc_siz;
+
 char *filename;
 
 fstHandle maxhandle;
@@ -777,6 +794,7 @@ pthread_t thread;
 pthread_attr_t thread_attr;
 struct fstWriterContext *xc_parent;
 #endif
+unsigned in_pthread : 1;
 
 size_t fst_orig_break_size;
 size_t fst_orig_break_add_size;
@@ -954,6 +972,19 @@ fflush(xc->handle);
 /*
  * mmap functions
  */
+static void fstWriterMmapSanity(void *pnt, const char *file, int line, const char *usage)
+{
+#if !defined(__CYGWIN__) && !defined(__MINGW32__)
+if(pnt == MAP_FAILED)
+	{
+	fprintf(stderr, "fstMmap() assigned to %s failed: errno: %d, file %s, line %d.\n", usage, errno, file, line);
+	perror("Why");
+	pnt = NULL;
+	}
+#endif
+}
+
+
 static void fstWriterCreateMmaps(struct fstWriterContext *xc)
 {
 off_t curpos = ftello(xc->handle);
@@ -976,19 +1007,29 @@ fflush(xc->handle);
 if(!xc->valpos_mem)
         {
         fflush(xc->valpos_handle);
-        xc->valpos_mem = (uint32_t *)fstMmap(NULL, xc->maxhandle * 4 * sizeof(uint32_t), PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->valpos_handle), 0);
+	errno = 0;
+	if(xc->maxhandle)
+		{
+	        fstWriterMmapSanity(xc->valpos_mem = (uint32_t *)fstMmap(NULL, xc->maxhandle * 4 * sizeof(uint32_t), PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->valpos_handle), 0), __FILE__, __LINE__, "xc->valpos_mem");
+		}
         }
 if(!xc->curval_mem)
         {
         fflush(xc->curval_handle);
-        xc->curval_mem = (unsigned char *)fstMmap(NULL, xc->maxvalpos, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->curval_handle), 0);
+	errno = 0;
+	if(xc->maxvalpos)
+		{
+	        fstWriterMmapSanity(xc->curval_mem = (unsigned char *)fstMmap(NULL, xc->maxvalpos, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->curval_handle), 0), __FILE__, __LINE__, "xc->curval_handle");
+		}
         }
 }
 
 
 static void fstDestroyMmaps(struct fstWriterContext *xc, int is_closing)
 {
+#if !defined __CYGWIN__ && !defined __MINGW32__
 (void)is_closing;
+#endif
 
 fstMunmap(xc->valpos_mem, xc->maxhandle * 4 * sizeof(uint32_t));
 xc->valpos_mem = NULL;
@@ -1684,7 +1725,8 @@ fflush(xc->tchn_handle);
 tlen = ftello(xc->tchn_handle);
 fstWriterFseeko(xc, xc->tchn_handle, 0, SEEK_SET);
 
-tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->tchn_handle), 0);
+errno = 0;
+fstWriterMmapSanity(tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->tchn_handle), 0), __FILE__, __LINE__, "tmem");
 if(tmem)
         {
         unsigned long destlen = tlen;
@@ -1765,10 +1807,9 @@ static void *fstWriterFlushContextPrivate1(void *ctx)
 {
 struct fstWriterContext *xc = (struct fstWriterContext *)ctx;
 
+pthread_mutex_lock(&(xc->xc_parent->mutex));
 fstWriterFlushContextPrivate2(xc);
 
-pthread_mutex_unlock(&(xc->xc_parent->mutex));
-
 #ifdef FST_REMOVE_DUPLICATE_VC
 free(xc->curval_mem);
 #endif
@@ -1777,6 +1818,9 @@ free(xc->vchg_mem);
 tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam);
 free(xc);
 
+xc->xc_parent->in_pthread = 0;
+pthread_mutex_unlock(&(xc->xc_parent->mutex));
+
 return(NULL);
 }
 
@@ -1824,7 +1868,15 @@ if(xc->parallel_enabled)
         xc->section_header_only = 0;
         xc->secnum++;
 
+	while (xc->in_pthread) 
+		{ 
+		pthread_mutex_lock(&xc->mutex); 
+		pthread_mutex_unlock(&xc->mutex); 
+		};
+
         pthread_mutex_lock(&xc->mutex);
+	xc->in_pthread = 1;
+        pthread_mutex_unlock(&xc->mutex);
 
         pthread_create(&xc->thread, &xc->thread_attr, fstWriterFlushContextPrivate1, xc2);
         }
@@ -1876,7 +1928,7 @@ if(xc)
 
 if(xc && !xc->already_in_close && !xc->already_in_flush)
         {
-        unsigned char *tmem;
+        unsigned char *tmem = NULL;
         off_t fixup_offs, tlen, hlen;
 
         xc->already_in_close = 1; /* never need to zero this out as it is freed at bottom */
@@ -1892,7 +1944,7 @@ if(xc && !xc->already_in_close && !xc->already_in_flush)
                 xc->skip_writing_section_hdr = 1;
                 if(!xc->size_limit_locked)
                         {
-                        if(xc->is_initial_time) /* simulation time never advanced so mock up the changes as time zero ones */
+                        if(FST_UNLIKELY(xc->is_initial_time)) /* simulation time never advanced so mock up the changes as time zero ones */
                                 {
                                 fstHandle dupe_idx;
 
@@ -1906,15 +1958,31 @@ if(xc && !xc->already_in_close && !xc->already_in_flush)
 #ifdef FST_WRITER_PARALLEL
                         pthread_mutex_lock(&xc->mutex);
                         pthread_mutex_unlock(&xc->mutex);
+
+			while (xc->in_pthread) 
+				{ 
+				pthread_mutex_lock(&xc->mutex); 
+				pthread_mutex_unlock(&xc->mutex); 
+				};
 #endif
                         }
                 }
         fstDestroyMmaps(xc, 1);
+	if(xc->outval_mem)
+		{
+		free(xc->outval_mem); xc->outval_mem = NULL;
+		xc->outval_alloc_siz = 0;
+		}
 
         /* write out geom section */
         fflush(xc->geom_handle);
         tlen = ftello(xc->geom_handle);
-        tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->geom_handle), 0);
+	errno = 0;
+	if(tlen)
+		{
+	        fstWriterMmapSanity(tmem = (unsigned char *)fstMmap(NULL, tlen, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->geom_handle), 0), __FILE__, __LINE__, "tmem");
+		}
+
         if(tmem)
                 {
                 unsigned long destlen = tlen;
@@ -2022,14 +2090,18 @@ if(xc && !xc->already_in_close && !xc->already_in_flush)
                         {
                         int lz4_maxlen;
                         unsigned char *mem;
-                        unsigned char *hmem;
+                        unsigned char *hmem = NULL;
                         int packed_len;
 
                         fflush(xc->handle);
 
                         lz4_maxlen = LZ4_compressBound(xc->hier_file_len);
                         mem = (unsigned char *)malloc(lz4_maxlen);
-                        hmem = (unsigned char *)fstMmap(NULL, xc->hier_file_len, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->hier_handle), 0);
+			errno = 0;
+			if(xc->hier_file_len)
+				{
+	                        fstWriterMmapSanity(hmem = (unsigned char *)fstMmap(NULL, xc->hier_file_len, PROT_READ|PROT_WRITE, MAP_SHARED, fileno(xc->hier_handle), 0), __FILE__, __LINE__, "hmem");
+				}
                         packed_len = LZ4_compress((char *)hmem, (char *)mem, xc->hier_file_len);
                         fstMunmap(hmem, xc->hier_file_len);
 
@@ -2845,12 +2917,12 @@ const unsigned char *buf = (const unsigned char *)val;
 uint32_t offs;
 int len;
 
-if((xc) && (handle <= xc->maxhandle))
+if(FST_LIKELY((xc) && (handle <= xc->maxhandle)))
         {
         uint32_t fpos;
         uint32_t *vm4ip;
 
-        if(!xc->valpos_mem)
+        if(FST_UNLIKELY(!xc->valpos_mem))
                 {
                 xc->vc_emitted = 1;
                 fstWriterCreateMmaps(xc);
@@ -2860,17 +2932,17 @@ if((xc) && (handle <= xc->maxhandle))
         vm4ip = &(xc->valpos_mem[4*handle]);
 
         len  = vm4ip[1];
-        if(len) /* len of zero = variable length, use fstWriterEmitVariableLengthValueChange */
+        if(FST_LIKELY(len)) /* len of zero = variable length, use fstWriterEmitVariableLengthValueChange */
                 {
-                if(!xc->is_initial_time)
+                if(FST_LIKELY(!xc->is_initial_time))
                         {
                         fpos = xc->vchg_siz;
 
-                        if((fpos + len + 10) > xc->vchg_alloc_siz)
+                        if(FST_UNLIKELY((fpos + len + 10) > xc->vchg_alloc_siz))
                                 {
                                 xc->vchg_alloc_siz += (xc->fst_break_add_size + len); /* +len added in the case of extremely long vectors and small break add sizes */
                                 xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz);
-                                if(!xc->vchg_mem)
+                                if(FST_UNLIKELY(!xc->vchg_mem))
                                         {
                                         fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitValueChange, exiting.\n");
                                         exit(255);
@@ -2955,18 +3027,139 @@ if((xc) && (handle <= xc->maxhandle))
         }
 }
 
+void fstWriterEmitValueChange32(void *ctx, fstHandle handle,
+                                uint32_t bits, uint32_t val) {
+        char buf[32];
+        char *s = buf;
+        uint32_t i;
+        for (i = 0; i < bits; ++i)
+        {
+                *s++ = '0' + ((val >> (bits - i - 1)) & 1);
+        }
+        fstWriterEmitValueChange(ctx, handle, buf);
+}
+void fstWriterEmitValueChange64(void *ctx, fstHandle handle,
+                                uint32_t bits, uint64_t val) {
+        char buf[64];
+        char *s = buf;
+        uint32_t i;
+        for (i = 0; i < bits; ++i)
+        {
+                *s++ = '0' + ((val >> (bits - i - 1)) & 1);
+        }
+        fstWriterEmitValueChange(ctx, handle, buf);
+}
+void fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle,
+                                   uint32_t bits, const uint32_t *val) {
+        struct fstWriterContext *xc = (struct fstWriterContext *)ctx;
+        if (FST_UNLIKELY(bits <= 32))
+        {
+                fstWriterEmitValueChange32(ctx, handle, bits, val[0]);
+        }
+        else if(FST_LIKELY(xc))
+        {
+                int bq = bits / 32;
+                int br = bits & 31;
+                int i;
+                int w;
+                uint32_t v;
+                unsigned char* s;
+                if (FST_UNLIKELY(bits > xc->outval_alloc_siz))
+                {
+                        xc->outval_alloc_siz = bits*2 + 1;
+                        xc->outval_mem = (unsigned char*)realloc(xc->outval_mem, xc->outval_alloc_siz);
+                        if (FST_UNLIKELY(!xc->outval_mem))
+                        {
+                                fprintf(stderr,
+                                        FST_APIMESS "Could not realloc() in fstWriterEmitValueChangeVec32, exiting.\n");
+                                exit(255);
+                        }
+                }
+                s = xc->outval_mem;
+                {
+                        w = bq;
+                        v = val[w];
+                        for (i = 0; i < br; ++i)
+                        {
+                                *s++ = '0' + ((v >> (br - i - 1)) & 1);
+                        }
+                }
+                for (w = bq - 1; w >= 0; --w)
+                {
+                        v = val[w];
+                        for (i = (32 - 4); i >= 0; i -= 4) {
+                                s[0] = '0' + ((v >> (i + 3)) & 1);
+                                s[1] = '0' + ((v >> (i + 2)) & 1);
+                                s[2] = '0' + ((v >> (i + 1)) & 1);
+                                s[3] = '0' + ((v >> (i + 0)) & 1);
+                                s += 4;
+                        }
+                }
+                fstWriterEmitValueChange(ctx, handle, xc->outval_mem);
+        }
+}
+void fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle,
+                                   uint32_t bits, const uint64_t *val) {
+        struct fstWriterContext *xc = (struct fstWriterContext *)ctx;
+        if (FST_UNLIKELY(bits <= 64))
+        {
+                fstWriterEmitValueChange64(ctx, handle, bits, val[0]);
+        }
+        else if(FST_LIKELY(xc))
+        {
+                int bq = bits / 64;
+                int br = bits & 63;
+                int i;
+                int w;
+                uint32_t v;
+                unsigned char* s;
+                if (FST_UNLIKELY(bits > xc->outval_alloc_siz))
+                {
+                        xc->outval_alloc_siz = bits*2 + 1;
+                        xc->outval_mem = (unsigned char*)realloc(xc->outval_mem, xc->outval_alloc_siz);
+                        if (FST_UNLIKELY(!xc->outval_mem))
+                        {
+                                fprintf(stderr,
+                                        FST_APIMESS "Could not realloc() in fstWriterEmitValueChangeVec64, exiting.\n");
+                                exit(255);
+                        }
+                }
+                s = xc->outval_mem;
+                {
+                        w = bq;
+                        v = val[w];
+                        for (i = 0; i < br; ++i)
+                        {
+                                *s++ = '0' + ((v >> (br - i - 1)) & 1);
+                        }
+                }
+                for (w = bq - 1; w >= 0; --w) {
+                        v = val[w];
+                        for (i = (64 - 4); i >= 0; i -= 4)
+                        {
+                                s[0] = '0' + ((v >> (i + 3)) & 1);
+                                s[1] = '0' + ((v >> (i + 2)) & 1);
+                                s[2] = '0' + ((v >> (i + 1)) & 1);
+                                s[3] = '0' + ((v >> (i + 0)) & 1);
+                                s += 4;
+                        }
+                }
+                fstWriterEmitValueChange(ctx, handle, xc->outval_mem);
+        }
+}
+
 
 void fstWriterEmitVariableLengthValueChange(void *ctx, fstHandle handle, const void *val, uint32_t len)
 {
 struct fstWriterContext *xc = (struct fstWriterContext *)ctx;
 const unsigned char *buf = (const unsigned char *)val;
 
-if((xc) && (handle <= xc->maxhandle))
+if(FST_LIKELY((xc) && (handle <= xc->maxhandle)))
         {
         uint32_t fpos;
         uint32_t *vm4ip;
 
-        if(!xc->valpos_mem)
+        if(FST_UNLIKELY(!xc->valpos_mem))
                 {
                 xc->vc_emitted = 1;
                 fstWriterCreateMmaps(xc);
@@ -2976,15 +3169,15 @@ if((xc) && (handle <= xc->maxhandle))
         vm4ip = &(xc->valpos_mem[4*handle]);
 
         /* there is no initial time dump for variable length value changes */
-        if(!vm4ip[1]) /* len of zero = variable length */
+        if(FST_LIKELY(!vm4ip[1])) /* len of zero = variable length */
                 {
                 fpos = xc->vchg_siz;
 
-                if((fpos + len + 10 + 5) > xc->vchg_alloc_siz)
+                if(FST_UNLIKELY((fpos + len + 10 + 5) > xc->vchg_alloc_siz))
                         {
                         xc->vchg_alloc_siz += (xc->fst_break_add_size + len + 5); /* +len added in the case of extremely long vectors and small break add sizes */
                         xc->vchg_mem = (unsigned char *)realloc(xc->vchg_mem, xc->vchg_alloc_siz);
-                        if(!xc->vchg_mem)
+                        if(FST_UNLIKELY(!xc->vchg_mem))
                                 {
                                 fprintf(stderr, FST_APIMESS "Could not realloc() in fstWriterEmitVariableLengthValueChange, exiting.\n");
                                 exit(255);
@@ -3006,7 +3199,7 @@ unsigned int i;
 int skip = 0;
 if(xc)
         {
-        if(xc->is_initial_time)
+        if(FST_UNLIKELY(xc->is_initial_time))
                 {
                 if(xc->size_limit_locked)       /* this resets xc->is_initial_time to one */
                         {

include/gtkwave/fstapi.h

@@ -18,6 +18,8 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
  */
 
 #ifndef FST_API_H
@@ -355,6 +357,14 @@ fstHandle       fstWriterCreateVar2(void *ctx, enum fstVarType vt, enum fstVarDi
 void            fstWriterEmitDumpActive(void *ctx, int enable);
 void 		fstWriterEmitEnumTableRef(void *ctx, fstEnumHandle handle);
 void            fstWriterEmitValueChange(void *ctx, fstHandle handle, const void *val);
+void            fstWriterEmitValueChange32(void *ctx, fstHandle handle,
+                        uint32_t bits, uint32_t val);
+void            fstWriterEmitValueChange64(void *ctx, fstHandle handle,
+                        uint32_t bits, uint64_t val);
+void            fstWriterEmitValueChangeVec32(void *ctx, fstHandle handle,
+                        uint32_t bits, const uint32_t *val);
+void            fstWriterEmitValueChangeVec64(void *ctx, fstHandle handle,
+                        uint32_t bits, const uint64_t *val);
 void            fstWriterEmitVariableLengthValueChange(void *ctx, fstHandle handle, const void *val, uint32_t len);
 void            fstWriterEmitTimeChange(void *ctx, uint64_t tim);
 void            fstWriterFlushContext(void *ctx);

include/gtkwave/lz4.c

@@ -27,6 +27,8 @@
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+   SPDX-License-Identifier: BSD-2-Clause
+
    You can contact the author at :
    - LZ4 source repository : https://github.com/Cyan4973/lz4
    - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c

include/gtkwave/lz4.h

@@ -28,6 +28,8 @@
    (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
    OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+   SPDX-License-Identifier: BSD-2-Clause
+
    You can contact the author at :
    - LZ4 source repository : https://github.com/Cyan4973/lz4
    - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c

include/gtkwave/wavealloca.h

@@ -18,6 +18,8 @@
  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  * DEALINGS IN THE SOFTWARE.
+ *
+ * SPDX-License-Identifier: MIT
  */
 
 #ifndef WAVE_ALLOCA_H
@@ -33,9 +35,6 @@
 #else
 #include <malloc.h>
 #endif
-#elif defined(_MSC_VER)
-#include <malloc.h>
-#define alloca _alloca
 #endif
 #define wave_alloca alloca
 #endif