Version bump

**   Add simulation context (VerilatedContext) to allow multiple fully independent
      models to be in the same process.  Please see the updated examples.
**   Add context->time() and context->timeInc() API calls, to set simulation time.
      These now are recommended in place of the legacy sc_time_stamp().

.clang-format

@@ -13,7 +13,7 @@ AllowShortBlocksOnASingleLine: true
 AllowShortCaseLabelsOnASingleLine: true
 AllowShortFunctionsOnASingleLine: All
 AllowShortIfStatementsOnASingleLine: true
-AllowShortLoopsOnASingleLine: false
+AllowShortLoopsOnASingleLine: true
 AlwaysBreakAfterDefinitionReturnType: None
 AlwaysBreakAfterReturnType: None
 AlwaysBreakBeforeMultilineStrings: false
@@ -104,7 +104,7 @@ SpacesInContainerLiterals: true
 SpacesInCStyleCastParentheses: false
 SpacesInParentheses: false
 SpacesInSquareBrackets: false
-Standard:        Cpp03
+Standard:        Cpp11
 TabWidth:        8
 UseTab:          Never
 ...

.clang-tidy

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

.codacy.yml

@@ -3,3 +3,4 @@ exclude_paths:
   - '.github/**'
   - 'ci/build_verilator.sh'
   - 'include/vltstd/**'
+  - 'nodist/fastcov.py'

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,6 +1,6 @@
 ---
 name: Bug report
-about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/.github/blob/master/CONTRIBUTING.adoc)
+about: Something isn't working as expected, and it isn't "Unsupported." (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
 title: ''
 labels: new
 assignees: ''
@@ -11,4 +11,6 @@ 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.)
 
-May we assist you in trying to fix this yourself?
+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

@@ -1,6 +1,6 @@
 ---
 name: Feature Request
-about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/.github/blob/master/CONTRIBUTING.adoc)
+about: Request something should be supported, or a new feature added. (Note our contributor agreement at https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst)
 title: ''
 labels: new
 assignees: ''

.github/ISSUE_TEMPLATE/questions.md

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

.github/PULL_REQUEST_TEMPLATE.md

@@ -1 +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.
+We appreciate your contributing to Verilator.  If this is your first commit, please add your name to docs/CONTRIBUTORS, and read our contributing guidelines in docs/CONTRIBUTING.rst.

.github/workflows/build.yml

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

.github/workflows/clang-format.yml

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

.github/workflows/contributor.yml

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

.github/workflows/coverage.yml

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

.gitignore

@@ -1,5 +1,6 @@
 \#*
 .#*
+.nfs*
 *~
 *.tidy
 *.old
@@ -14,6 +15,8 @@
 *.tex
 *.pdf
 /Makefile
+/.ccache
+/artifact/
 README
 TAGS
 autom4te.cache

.travis.yml

@@ -1,179 +0,0 @@
-# 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.
-
-version: ~> 1.0
-
-os: linux
-language: cpp
-cache: ccache
-
-env:
-  global:
-    - VERILATOR_CACHE=$HOME/verilator_cache
-    - VERILATOR_ROOT=$PWD
-    - VERILATOR_NUM_JOBS=$(echo `nproc` + 1 | bc)
-    - VERILATOR_CONFIG_FLAGS="--enable-maintainer-mode --enable-longtests"
-    - VERILATOR_AUTHOR_SITE=1
-    - OBJCACHE=ccache
-
-cache:
-  directories:
-    - $VERILATOR_CACHE
-
-before_install:
-# Perl modules needed for testing
-  - yes yes | sudo cpan -fi Unix::Processors Parallel::Forker Bit::Vector
-  - sudo apt-get install gdb gtkwave
-  - sudo apt-get install libgoogle-perftools-dev
-before_script:
-  - bash -x ci/build_vcddiff.sh
-  - bash -x ci/build_verilator.sh
-after_script:
-  - ccache -s
-
-stages:
-  - "Build Verilator"
-  - test
-
-jobs:
-  include:
-    - if: type != cron
-      stage: "Build Verilator"
-      name: Build Verilator
-      compiler: gcc
-      script: echo "Done building Verilator"
-# Non-cron build will just run on whatever linux flavor we get
-    - if: type != cron
-      stage: test
-      name: Dist test
-      compiler: gcc
-      script: ci/test.sh dist
-    - if: type != cron
-      stage: test
-      name: Vlt test
-      compiler: gcc
-      script: ci/test.sh vlt
-    - if: type != cron
-      stage: test
-      name: Vltmt test
-      compiler: gcc
-      script: ci/test.sh vltmt
-# Cron builds try different OS/compiler combinations
-    - if: type = cron
-      stage: "Build Verilator"
-      name: Build xenial gcc Verilator
-      os: linux
-      dist: xenial
-      compiler: gcc
-      script: echo "Done building Verilator"
-    - if: type = cron
-      stage: test
-      name: Xenial gcc dist test
-      os: linux
-      dist: xenial
-      compiler: gcc
-      script: ci/test.sh dist
-    - if: type = cron
-      stage: test
-      name: Xenial gcc vlt test
-      os: linux
-      dist: xenial
-      compiler: gcc
-      script: ci/test.sh vlt
-    - if: type = cron
-      stage: test
-      name: Xenial gcc vltmt test
-      os: linux
-      dist: xenial
-      compiler: gcc
-      script: ci/test.sh vltmt
-    - if: type = cron
-      stage: "Build Verilator"
-      name: Build xenial clang Verilator
-      os: linux
-      dist: xenial
-      compiler: clang
-      script: echo "Done building Verilator"
-    - if: type = cron
-      stage: test
-      name: Xenial clang dist test
-      os: linux
-      dist: xenial
-      compiler: clang
-      script: ci/test.sh dist
-    - if: type = cron
-      stage: test
-      name: Xenial clang vlt test
-      os: linux
-      dist: xenial
-      compiler: clang
-      script: ci/test.sh vlt
-    - if: type = cron
-      stage: test
-      name: Xenial clang vltmt test
-      os: linux
-      dist: xenial
-      compiler: clang
-      script: ci/test.sh vltmt
-#    - if: type = cron
-#      stage: "Build Verilator"
-#      name: Build OSX gcc Verilator
-#      os: osx
-#      compiler: gcc
-#      script: echo "Done building Verilator"
-#    - if: type = cron
-#      stage: test
-#      name: OSX gcc dist test
-#      os: osx
-#      compiler: gcc
-#      script: ci/test.sh dist
-#    - if: type = cron
-#      stage: test
-#      name: OSX gcc vlt test
-#      os: osx
-#      compiler: gcc
-#      script: ci/test.sh vlt
-#    - if: type = cron
-#      stage: test
-#      name: OSX gcc vltmt test
-#      os: osx
-#      compiler: gcc
-#      script: ci/test.sh vltmt
-    - if: type = cron
-      stage: "Build Verilator"
-      name: Build trusty gcc Verilator
-      os: linux
-      dist: trusty
-      compiler: gcc
-      script: echo "Done building Verilator"
-    - if: type = cron
-      stage: test
-      name: Trusty gcc dist test
-      os: linux
-      dist: trusty
-      compiler: gcc
-      script: ci/test.sh dist
-    - if: type = cron
-      stage: test
-      name: Trusty gcc vlt test
-      os: linux
-      dist: trusty
-      compiler: gcc
-      script: ci/test.sh vlt
-    - if: type = cron
-      stage: test
-      os: linux
-      dist: trusty
-      name: Trusty gcc vltmt test
-      compiler: gcc
-      script: ci/test.sh vltmt
-
-notifications:
-  email:
-    if: repo = verilator/verilator
-    recipients:
-      - [email protected]
-      - [email protected]

MANIFEST.SKIP

@@ -1,3 +1,4 @@
+\.ccache/
 \.clang-format
 \.clang-tidy
 \.git/
@@ -23,12 +24,13 @@
 /obj_dir/
 /obj_dist/
 /obj_iv/
+/obj_ms/
 /obj_nc/
 /obj_opt/
 /obj_vcs/
 /obj_vlt/
 /obj_vltmt/
-/INCA_libs/
+INCA_libs/
 /cov_work/
 /logs/
 ^Makefile$
@@ -37,13 +39,17 @@ 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.*
+sonar-project.properties
 src/Makefile$
 src/Makefile_obj$
 include/verilated.mk$
 test_regress/.gdbinit$
+test_regress/transcript
+codecov.yml
 config.cache$
 config.status$
 verilator\.log
@@ -64,4 +70,5 @@ ci/
 /csrc/
 obj_dir.*
 TAGS
+gmon.out
 .*~

Makefile.in

@@ -7,15 +7,11 @@
 #
 #*****************************************************************************
 #
-# 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
+# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
 # Lesser General Public License Version 3 or the Perl Artistic License
 # Version 2.0.
-#
-# Verilator is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 #
 #****************************************************************************/
 #
@@ -93,7 +89,6 @@ datarootdir = @datarootdir@
 CFG_WITH_CCWARN = @CFG_WITH_CCWARN@
 CFG_WITH_DEFENV = @CFG_WITH_DEFENV@
 CFG_WITH_LONGTESTS = @CFG_WITH_LONGTESTS@
-CFG_WITH_THREADED = @CFG_WITH_THREADED@
 PACKAGE_VERSION = @PACKAGE_VERSION@
 
 #### End of system configuration section. ####
@@ -129,7 +124,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	Changes \
 	LICENSE \
 	MANIFEST.SKIP \
-	README.adoc \
+	README.rst \
 	verilator-config.cmake.in \
 	verilator-config-version.cmake.in \
 	bin/verilator \
@@ -139,16 +134,16 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	bin/verilator_includer \
 	bin/verilator_profcfunc \
 	docs/.gitignore \
-	docs/CONTRIBUTING.adoc \
+	docs/CONTRIBUTING.rst \
 	docs/CONTRIBUTORS \
 	docs/Makefile.in \
 	docs/TODO \
 	docs/doxygen-mainpage \
 	docs/doxygen.config \
-	docs/install.adoc \
-	docs/internals.adoc \
+	docs/install.rst \
+	docs/internals.rst \
 	docs/verilator_logo.png \
-	docs/xml.adoc \
+	docs/xml.rst \
 	install-sh configure *.pod \
 	include/*.[chv]* \
 	include/*.in \
@@ -158,6 +153,7 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	.*attributes */.*attributes  */*/.*attributes \
 	src/.*ignore src/*.in src/*.cpp src/*.[chly] \
 	src/astgen src/bisonpre src/*fix src/cppcheck_filtered \
+	src/config_rev \
 	src/vlcovgen src/mkinstalldirs \
 	src/.gdbinit \
 	src/*.pl src/*.pod \
@@ -175,6 +171,8 @@ DISTFILES_INC = $(INFOS) .gitignore \
 	test_regress/t/t*/*.v* \
 	test_regress/t/t*/*/*.sv* \
 	test_regress/t/t*/*/*.v* \
+	test_regress/t/t*/*.cpp \
+	test_regress/t/t*/CMakeLists.txt \
 	test_regress/t/*.cpp \
 	test_regress/t/*.h \
 	test_regress/t/*.dat \
@@ -208,12 +206,6 @@ EXAMPLES_FIRST = \
 
 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
 
@@ -228,7 +220,7 @@ all_nomsg: verilator_exe $(VL_INST_MAN_FILES)
 verilator_exe verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg:
 	@echo ------------------------------------------------------------
 	@echo "making verilator in src"
-	$(MAKE) -C src $(OBJCACHE_JOBS)
+	$(MAKE) -C src $(OBJCACHE_JOBS) $(CI_MAKE_SRC_TARGET)
 
 .PHONY:msg_test
 msg_test: all_nomsg
@@ -346,6 +338,7 @@ installdata:
 	$(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; \
@@ -380,8 +373,8 @@ uninstall:
 	-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)/cmake
 	-rmdir $(DESTDIR)$(pkgdatadir)
 	-rmdir $(DESTDIR)$(pkgconfigdir)
 
@@ -429,12 +422,16 @@ endif
 
 # Use --xml flag to see the cppcheck code to use for suppression
 CPPCHECK_CPP = $(wildcard \
+	$(srcdir)/examples/*/*.cpp \
 	$(srcdir)/include/*.cpp \
 	$(srcdir)/src/*.cpp )
 CPPCHECK_H = $(wildcard \
 	$(srcdir)/include/*.h \
 	$(srcdir)/src/*.h )
-CPPCHECK = src/cppcheck_filtered
+CPPCHECK_YL = $(wildcard \
+	$(srcdir)/src/*.y \
+	$(srcdir)/src/*.l )
+CPPCHECK = src/cppcheck_filtered cppcheck
 CPPCHECK_FLAGS = --enable=all --inline-suppr \
 	--suppress=unusedScopedObject --suppress=cstyleCast --suppress=useInitializationList \
 	--suppress=nullPointerRedundantCheck
@@ -444,18 +441,19 @@ CPPCHECK_INC = -I$(srcdir)/include -I$(srcdir)/src/obj_dbg -I$(srcdir)/src
 
 cppcheck: $(CPPCHECK_DEP)
 %.cppcheck: %.cpp
-	$(CPPCHECK) $(CPPCHECK_FLAGS) -DVL_DEBUG=1 -DVL_CPPCHECK=1 $(CPPCHECK_INC) $<
+	$(CPPCHECK) $(CPPCHECK_FLAGS) -DVL_DEBUG=1 -DVL_CPPCHECK=1 -DVL_THREADED=1 $(CPPCHECK_INC) $<
 
 CLANGTIDY = clang-tidy
-CLANGTIDY_FLAGS = -config=''
+CLANGTIDY_FLAGS = -config='' -checks='-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables'
 CLANGTIDY_DEP = $(subst .h,.h.tidy,$(CPPCHECK_H)) \
 	$(subst .cpp,.cpp.tidy,$(CPPCHECK_CPP))
+CLANGTIDY_DEFS = -DVL_DEBUG=1 -DVL_THREADED=1 -DVL_CPPCHECK=1
 
-clangtidy: $(CLANGTIDY_DEP)
+clang-tidy: $(CLANGTIDY_DEP)
 %.cpp.tidy: %.cpp
-	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- -DVL_DEBUG=1 -DVL_CPPCHECK=1 $(CPPCHECK_INC) | 2>&1 tee $@
+	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) | 2>&1 tee $@
 %.h.tidy: %.h
-	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- -DVL_DEBUG=1 -DVL_CPPCHECK=1 $(CPPCHECK_INC) | 2>&1 tee $@
+	$(CLANGTIDY) $(CLANGTIDY_FLAGS) $< -- $(CLANGTIDY_DEFS) $(CPPCHECK_INC) | 2>&1 tee $@
 
 analyzer-src:
 	-rm -rf src/obj_dbg
@@ -465,6 +463,58 @@ analyzer-include:
 	-rm -rf examples/*/obj*
 	scan-build $(MAKE) -k examples
 
+format: clang-format yapf format-pl-exec
+
+CLANGFORMAT = clang-format
+CLANGFORMAT_FLAGS = -i
+CLANGFORMAT_FILES = $(CPPCHECK_CPP) $(CPPCHECK_H) $(CPPCHECK_YL) test_regress/t/*.c* test_regress/t/*.h
+
+clang-format:
+	@$(CLANGFORMAT) --version | egrep 10.0 > /dev/null \
+		|| echo "*** You are not using clang-format 10.0, indents may differ from master's ***"
+	$(CLANGFORMAT) $(CLANGFORMAT_FLAGS) $(CLANGFORMAT_FILES)
+
+PY_PROGRAMS = \
+	examples/xml_py/vl_file_copy \
+	examples/xml_py/vl_hier_graph \
+	src/astgen \
+	src/bisonpre \
+	src/config_rev \
+	src/cppcheck_filtered \
+	src/flexfix \
+	src/vlcovgen \
+	nodist/code_coverage \
+	nodist/dot_importer \
+	nodist/fuzzer/actual_fail \
+	nodist/fuzzer/generate_dictionary \
+	nodist/install_test \
+
+PY_FILES = \
+	$(PY_PROGRAMS) \
+	nodist/code_coverage.dat \
+
+YAPF = yapf3
+YAPF_FLAGS = -i
+
+yapf:
+	$(YAPF) $(YAPF_FLAGS) $(PY_FILES)
+
+FLAKE8 = flake8
+FLAKE8_FLAGS = \
+	--extend-exclude=fastcov.py \
+	--ignore=E123,E129,E251,E501,W503,W504,E701
+
+PYLINT = pylint
+PYLINT_FLAGS = --disable=R0801
+
+lint-py:
+	$(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
+	$(PYLINT) $(PYLINT_FLAGS) $(PY_PROGRAMS)
+
+format-pl-exec:
+	-chmod a+x test_regress/t/*.pl
+
+
 ftp: info
 
 install-msg:
@@ -544,9 +594,6 @@ dist-file-list:
 	@echo $(wildcard $(DISTFILES))
 	@echo "end-dist-file-list:";  # Scripts look for this
 
-print-cfg-with-threaded:
-	@echo $(CFG_WITH_THREADED)
-
 ######################################################################
 # Distributions
 

README.adoc

@@ -1,151 +0,0 @@
-// 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/48478c986f13400682ffe4a5e0939b3a[Code Quality,link=https://www.codacy.com/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"]
-|===
-^.^| *Welcome to Verilator, the fastest free Verilog HDL simulator.*
-+++ <br/> +++ &bullet; Accepts synthesizable Verilog or SystemVerilog
-+++ <br/> +++ &bullet; Performs lint code-quality checks
-+++ <br/> +++ &bullet; Compiles into multithreaded {cpp}, SystemC, or (soon) {cpp}-under-Python
-+++ <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 synthesizable 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 synthesizable
-Verilog to {cpp} or SystemC, and 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
-than only translate, Verilator compiles your code into a much faster
-optimized and optionally thread-partitioned model, which is in turn wrapped
-inside a {cpp}/SystemC/Python 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 commercial
-Verilog simulators (Carbon Design Systems Carbonator, Modelsim, Cadence
-Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic CVer/CVC). But,
-Verilator is free, so you can spend on computes rather than licenses. Thus
-Verilator gives you more cycles/dollar than anything else available.
-
-For more information on how Verilator stacks up to some of the other
-commercial and free 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://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.rst

@@ -0,0 +1,160 @@
+.. Github doesn't render images unless absolute URL
+.. Do not know of a conditional tag, "only: github" nor "github display" works
+
+.. image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
+    :target: https://www.gnu.org/licenses/lgpl-3.0]
+.. image:: https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg
+    :target: https://opensource.org/licenses/Artistic-2.0
+.. image:: https://api.codacy.com/project/badge/Grade/fa78caa433c84a4ab9049c43e9debc6f
+    :target: https://www.codacy.com/gh/verilator/verilator
+.. image:: https://codecov.io/gh/verilator/verilator/branch/master/graph/badge.svg
+    :target: https://codecov.io/gh/verilator/verilator
+.. image:: https://github.com/verilator/verilator/workflows/build/badge.svg
+    :target: https://github.com/verilator/verilator/actions?query=workflow%3Abuild
+
+Welcome to Verilator
+====================
+
+.. list-table::
+
+   * - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
+        * Accepts synthesizable Verilog or SystemVerilog
+        * Performs lint code-quality checks
+        * Compiles into multithreaded C++, or SystemC
+        * Creates XML to front-end your own tools
+     - |Logo|
+   * - |verilator multithreaded performance bg min|
+     - **Fast**
+        * Outperforms many commercial simulators
+        * Single- and multi-threaded output models
+   * - **Widely Used**
+        * Wide industry and academic deployment
+        * Out-of-the-box support from Arm, and RISC-V vendor IP
+     - |verilator usage 400x200 min|
+   * - |verilator community 400x125 min|
+     - **Community Driven & Openly Licensed**
+        * Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
+        * Open, and free as in both speech and beer
+        * More simulation for your verification budget
+   * - **Commercial Support Available**
+        * Commercial support contracts
+        * Design support contracts
+        * Enhancement contracts
+     - |verilator support 400x125 min|
+
+
+What Verilator Does
+===================
+
+Verilator is invoked with parameters similar to GCC or Synopsys's VCS.  It
+"Verilates" the specified Verilog or SystemVerilog code by reading it,
+performing lint checks, and optionally inserting assertion checks and
+coverage-analysis points. It outputs single- or multi-threaded .cpp and .h
+files, the "Verilated" code.
+
+The user writes a little C++/SystemC wrapper file, which instantiates the
+"Verilated" model of the user's top level module. These C++/SystemC files
+are then compiled by a C++ compiler (gcc/clang/MSVC++). The resulting
+executable performs the design simulation. Verilator also supports linking
+its generated libraries, optionally encrypted, into other simulators.
+
+Verilator may not be the best choice if you are expecting a full featured
+replacement for NC-Verilog, VCS or another commercial Verilog simulator, or
+if you are looking for a behavioral Verilog simulator e.g. for a quick
+class project (we recommend `Icarus Verilog`_ for this.) However, if you
+are looking for a path to migrate SystemVerilog to C++ or SystemC, or your
+team is comfortable writing just a touch of C++ code, Verilator is the tool
+for you.
+
+
+Performance
+===========
+
+Verilator does not simply convert Verilog HDL to C++ or SystemC. Rather,
+Verilator compiles your code into a much faster optimized and optionally
+thread-partitioned model, which is in turn wrapped inside a C++/SystemC
+module. The results are a compiled Verilog model that executes even on a
+single-thread over 10x faster than standalone SystemC, and on a single
+thread is about 100 times faster than interpreted Verilog simulators such
+as `Icarus Verilog`_. Another 2-10x speedup might be gained from
+multithreading (yielding 200-1000x total over interpreted simulators).
+
+Verilator has typically similar or better performance versus the
+closed-source Verilog simulators (Carbon Design Systems Carbonator,
+Modelsim, Cadence Incisive/NC-Verilog, Synopsys VCS, VTOC, and Pragmatic
+CVer/CVC). But, Verilator is open-sourced, so you can spend on computes
+rather than licenses. Thus Verilator gives you the best cycles/dollar.
+
+For more information on how Verilator stacks up to some of the other
+closed-sourced and open-sourced Verilog simulators, see the `Verilog
+Simulator Benchmarks
+<https://www.veripool.org/verilog_sim_benchmarks.html>`_.  (If you
+benchmark Verilator, please see the notes in the `Verilator manual (PDF)
+<https://verilator.org/verilator_doc.pdf>`_, and also if possible post on
+the forums the results; there may be additional tweaks possible.)
+
+
+Installation & Documentation
+============================
+
+For more information:
+
+- `Verilator installation and package directory structure
+  <https://verilator.org/install>`_
+
+- `Verilator manual (HTML) <https://verilator.org/verilator_doc.html>`_,
+  or `Verilator manual (PDF) <https://verilator.org/verilator_doc.pdf>`_
+
+- `Subscribe to verilator announcements
+  <https://github.com/verilator/verilator-announce>`_
+
+- `Verilator forum <https://verilator.org/forum>`_
+
+- `Verilator issues <https://verilator.org/issues>`_
+
+
+Support
+=======
+
+Verilator is a community project, guided by the `CHIPS Alliance`_ under the
+`Linux Foundation`_.
+
+We appreciate and welcome your contributions in whatever form; please see
+`Contributing to Verilator
+<https://github.com/verilator/verilator/blob/master/docs/CONTRIBUTING.rst>`_.
+Thanks to our `Contributors and Sponsors
+<https://verilator.org/verilator_doc.html#CONTRIBUTORS>`_.
+
+Verilator also supports and encourages commercial support models and
+organizations; please see `Verilator Commercial Support
+<https://verilator.org/verilator_commercial_support>`_.
+
+
+Related Projects
+================
+
+- `GTKwave <http://gtkwave.sourceforge.net/>`_ - Waveform viewer for
+  Verilator traces.
+
+- `Icarus Verilog`_ - Icarus is a full featured interpreted Verilog
+  simulator. If Verilator does not support your needs, perhaps Icarus may.
+
+
+Open License
+============
+
+Verilator is Copyright 2003-2021 by Wilson Snyder. (Report bugs to
+`Verilator Issues <https://verilator.org/issues>`_.)
+
+Verilator is free software; you can redistribute it and/or modify it under
+the terms of either the GNU Lesser General Public License Version 3 or the
+Perl Artistic License Version 2.0. See the documentation for more details.
+
+.. _CHIPS Alliance: https://chipsalliance.org
+.. _Icarus Verilog: http://iverilog.icarus.com
+.. _Linux Foundation: https://www.linuxfoundation.org
+.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png
+.. |verilator multithreaded performance bg min| image:: https://www.veripool.org/img/verilator_multithreaded_performance_bg-min.png
+.. |verilator usage 400x200 min| image:: https://www.veripool.org/img/verilator_usage_400x200-min.png
+.. |verilator community 400x125 min| image:: https://www.veripool.org/img/verilator_community_400x125-min.png
+.. |verilator support 400x125 min| image:: https://www.veripool.org/img/verilator_support_400x125-min.png

bin/verilator_coverage

@@ -1,16 +1,11 @@
 #!/usr/bin/env perl
 ######################################################################
 #
-# Copyright 2003-2020 by Wilson Snyder. This program is free software; you
+# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
 # can redistribute it and/or modify it under the terms of either the GNU
 # Lesser General Public License Version 3 or the Perl Artistic License
 # Version 2.0.
 #
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
 ######################################################################
 
 require 5.006_001;
@@ -161,22 +156,27 @@ verilator_coverage - Verilator coverage analyzer
 
     verilator_coverage  -write merged.dat -read <datafiles>...
 
-Verilator_coverage processes Verilator coverage reports.
+    verilator_coverage  -write-info merged.info -read <datafiles>...
 
-With --anotate, it reads the specified data file and generates annotated
-source code with coverage metrics annotated.  If multiple coverage points
-exist on the same line, additional lines will be inserted to report the
-additional points.
+Verilator_coverage processes Verilated model-generated coverage reports.
 
-Additional Verilog-standard arguments specify the search paths necessary to
-find the source code that the coverage analysis was performed on.
+With --annotate, it reads the specified coverage data file and generates
+annotated source code with coverage metrics annotated.  If multiple
+coverage points exist on the same source code line, additional lines will
+be inserted to report the additional points.
 
-To get correct coverage percentages, you may wish to read logs/coverage.dat
-into Emacs and do a M-x keep-lines to include only those statistics of
-interest.
+Additional Verilog-XL-style standard arguments specify the search paths
+necessary to find the source code that the coverage analysis was performed
+on.
 
-For Verilog conditions that should never occur, you should add a $stop
-statement.  This will remove the coverage during the next build.
+To filter those items to be included in coverage, you may read
+logs/coverage.dat into an editor and do a M-x keep-lines to include only
+those statistics of interest and save to a new .dat file.
+
+For Verilog conditions that should never occur, either add a $stop
+statement to the appropriate statement block, or see the Verilator
+documentation on "// verilator coverage_off" and "coverage_off".  This will
+remove the coverage points after the model is re-Verilated.
 
 =head1 ARGUMENTS
 
@@ -184,12 +184,12 @@ statement.  This will remove the coverage during the next build.
 
 =item I<filename>
 
-Specify input data file, may be repeated to read multiple inputs.  If no
+Specify input data file. May be repeated to read multiple inputs.  If no
 data file is specified, by default coverage.dat is read.
 
 =item --annotate I<output_directory>
 
-Sprcifies the directory name that source files with annotated coverage data
+Specifies the directory name that source files with annotated coverage data
 should be written to.
 
 =item --annotate-all
@@ -229,8 +229,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
 
@@ -269,10 +281,12 @@ Specifies a module search directory.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2003-2020 by Wilson Snyder.  Verilator is free software; you can
-redistribute it and/or modify the Verilator internals under the terms of
-either the GNU Lesser General Public License Version 3 or the Perl Artistic
-License Version 2.0.
+Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+can redistribute it and/or modify the Verilator internals under the terms
+of either the GNU Lesser General Public License Version 3 or the Perl
+Artistic License Version 2.0.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 AUTHORS
 
@@ -280,7 +294,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

@@ -9,22 +9,6 @@ use Pod::Usage;
 use strict;
 use vars qw($Debug);
 
-#======================================================================
-
-# Old version 1 dump nodes with no dtypep's
-our %Ver1_Non_Dtyped = map {$_ => 1} qw(
-  ACTIVE ALWAYS ALWAYSPOST ALWAYSPUBLIC ATTROF BEGIN BREAK CASE CASEITEM
-  CCALL CELL CELLINLINE CFILE CFUNC CHANGEDET CLOCKING COMMENT CONTINUE
-  COVERDECL COVERINC COVERTOGGLE CRETURN CSTMT DEFPARAM DISABLE DISPLAY DOT
-  DPIEXPORT FCLOSE FFLUSH FINAL FINISH FOPEN GENCASE GENERATE GENFOR GENIF
-  IF IMPLICIT INITARRAY INITIAL JUMPGO JUMPLABEL MODULE NETLIST
-  NOTFOUNDMODULE PACKAGE PACKAGEIMPORT PARSEREF PIN PORT PRAGMA PRIMITIVE
-  PSLASSERT PSLCOVER PSLDEFCLOCK PULL RANGE READMEM REPEAT RETURN SCCTOR
-  SCDTOR SCHDR SCIMP SCIMPHDR SCINT SCOPE SELBIT SELEXTRACT SELMINUS
-  SELPLUS SENGATE SENITEM SENTREE SFORMAT SFORMATF STOP SYSIGNORE SYSTEMT
-  TASK TASKREF TEXT TOPSCOPE TYPEDEFFWD TYPETABLE UCSTMT UDPTABLE
-  UDPTABLELINE UNTILSTABLE VASSERT WHILE );
-
 #======================================================================
 # main
 
@@ -133,8 +117,6 @@ sub filter {
         $line =~ s/{[a-z]*\d+}/{}/g if !$Opt_Lineno;
         if ($verCvt) {
             next if $line =~ /^     NETLIST/;
-            $line =~ s!\@dt=0x\(G?/?([^)]+)\)!$1!g;  # NEW: @dt -> OLD: non @dt format
-            #                                        # Below Ver1_Non_Dtyped may replace above further
             if ($line =~ /: ([A-Z]+) /) {
                 my $type = $1;
                 next if $type =~ 'DTYPE';
@@ -147,14 +129,7 @@ sub filter {
                     }
                     next;
                 }
-                if ($Ver1_Non_Dtyped{$type}) {
-                    $line =~ s! w[0-9]+!!g;
-                }
             }
-            $line =~ s!\@dt=0$!NoW!g;   # NEW: dt=null -> common format
-            $line =~ s!\@dt=0 !NoW !g;  # NEW: dt=null -> common format
-            $line =~ s! s?w0$! NoW!g;   # OLD: no width -> common format
-            $line =~ s! s?w0 ! NoW !g;  # OLD: no width -> common format
         }
         print $f2 $line;
     }
@@ -233,9 +208,12 @@ Do not show differences in line numbering.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2005-2020 by Wilson Snyder.  This package is free software; you can
-redistribute it and/or modify it under the terms of either the GNU Lesser
-General Public License Version 3 or the Perl Artistic License Version 2.0.
+Copyright 2005-2021 by Wilson Snyder. This program is free software; you
+can redistribute it and/or modify it under the terms of either the GNU
+Lesser General Public License Version 3 or the Perl Artistic License
+Version 2.0.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 AUTHORS
 

bin/verilator_gantt

@@ -60,6 +60,7 @@ sub process {
     my $filename = shift;
 
     read_data($filename);
+    read_cpuinfo();
     report();
 }
 
@@ -70,7 +71,7 @@ sub read_data {
 
     %Global = (rdtsc_cycle_time => 0);
 
-    my $fh = IO::File->new ($filename) or die "%Error: $! $filename,";
+    my $fh = IO::File->new("<$filename") or die "%Error: $! $filename,";
     while (my $line = $fh->getline) {
         if ($line =~ m/VLPROF mtask\s(\d+)\sstart\s(\d+)\send\s(\d+)\selapsed\s(\d+)\spredict_time\s(\d+)\scpu\s(\d+)\son thread (\d+)/) {
             my $mtask = $1;
@@ -113,6 +114,27 @@ sub read_data {
     }
 }
 
+sub read_cpuinfo {
+    my $filename = "/proc/cpuinfo";
+    my $fh = IO::File->new("<$filename") or return;
+    my $cpu;
+    while (my $line = $fh->getline) {
+        chomp $line;
+        if ($line =~ m/^processor\s*:\s*(\d+)\s*$/) {
+            $cpu = $1;
+        }
+        if ($cpu && $line =~ m/^([a-z_ ]+)\s*:\s*(.*)$/) {
+            my ($term, $value) = ($1, $2);
+            $term =~ s/\s+$//;
+            $term =~ s/\s+/_/;
+            $value =~ s/\s+$//;
+            $Global{cpuinfo}{$cpu}{$term} = $value;
+        }
+    }
+}
+
+#######################################################################
+
 sub report {
     print "Verilator Gantt report\n";
 
@@ -123,13 +145,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;
         }
     }
 
@@ -156,14 +178,15 @@ sub report {
     print "\nAnalysis:\n";
     printf "  Total threads             = %d\n", $nthreads;
     printf "  Total mtasks              = %d\n", scalar(keys %Mtasks);
-    printf "  Total cpus used           = %d\n", scalar(keys %{$Global{cpus}});
+    my $ncpus = scalar(keys %{$Global{cpus}});
+    printf "  Total cpus used           = %d\n", $ncpus;
     printf "  Total yields              = %d\n", $Global{stats}{yields};
     printf "  Total eval time           = %d rdtsc ticks\n", $Global{last_end};
     printf "  Longest mtask time        = %d rdtsc ticks\n", $long_mtask_time;
     printf "  All-thread mtask time     = %d rdtsc ticks\n", $mt_mtask_time;
-    my $long_efficiency = $long_mtask_time/($Global{last_end});
+    my $long_efficiency = $long_mtask_time/($Global{last_end} || 1);
     printf "  Longest-thread efficiency = %0.1f%%\n", $long_efficiency*100;
-    my $mt_efficiency = $mt_mtask_time/($Global{last_end}*$nthreads);
+    my $mt_efficiency = $mt_mtask_time/($Global{last_end}*$nthreads || 1);
     printf "  All-thread efficiency     = %0.1f%%\n", $mt_efficiency*100;
     printf "  All-thread speedup        = %0.1f\n", $mt_efficiency*$nthreads;
     if ($Global{rdtsc_cycle_time} > 0) {
@@ -197,17 +220,72 @@ sub report {
     }
 
     print "\nStatistics:\n";
-    print "  min log(p2e) = $min_p2e  from mtask $min_mtask (predict $Mtasks{$min_mtask}{predict}, elapsed $Mtasks{$min_mtask}{elapsed})\n";
-    print "  max log(p2e) = $max_p2e  from mtask $max_mtask (predict $Mtasks{$max_mtask}{predict}, elapsed $Mtasks{$max_mtask}{elapsed})\n";
+    printf "  min log(p2e) = %0.3f", $min_p2e;
+    print "  from mtask $min_mtask (predict $Mtasks{$min_mtask}{predict},";
+    print " elapsed $Mtasks{$min_mtask}{elapsed})\n";
+    printf "  max log(p2e) = %0.3f", $max_p2e;
+    print "  from mtask $max_mtask (predict $Mtasks{$max_mtask}{predict},";
+    print " elapsed $Mtasks{$max_mtask}{elapsed})\n";
 
     my $stddev = stddev(\@p2e_ratios);
     my $mean = mean(\@p2e_ratios);
-    print "  mean = " . ($mean) . "\n";
-    print "  stddev = " . ($stddev) . "\n";
-    print "  e ^ stddev = " . exp($stddev). "\n";
+    printf "  mean = %0.3f\n", $mean;
+    printf "  stddev = %0.3f\n", $stddev;
+    printf "  e ^ stddev = %0.3f\n", exp($stddev);
+
+    report_cpus();
+
+    if ($nthreads > $ncpus) {
+        print "\n";
+        print "%Warning: There were fewer CPUs ($ncpus) then threads ($nthreads).\n";
+        print "        : See docs on use of numactl.\n";
+    } else {
+        if ($Global{cpu_socket_cores_warning}) {
+            print "\n";
+            print "%Warning: Multiple threads scheduled on same hyperthreaded core.\n";
+            print "        : See docs on use of numactl.\n";
+        }
+        if ($Global{cpu_sockets_warning}) {
+            print "\n";
+            print "%Warning: Threads scheduled on multiple sockets.\n";
+            print "        : See docs on use of numactl.\n";
+        }
+    }
     print "\n";
 }
 
+sub report_cpus {
+    print "\nCPUs:\n";
+    # Test - show all cores
+    # for (my $i=0; $i<73; ++$i) { $Global{cpus}{$i} ||= {cpu_time => 0}; }
+
+    $Global{cpu_sockets} ||= {};
+    $Global{cpu_socket_cores} ||= {};
+
+    foreach my $cpu (sort {$a <=> $b} keys %{$Global{cpus}}) {
+        printf "  cpu %d: ", $cpu;
+        printf "cpu_time=%d", $Global{cpus}{$cpu}{cpu_time};
+
+        my $socket = $Global{cpuinfo}{$cpu}{physical_id};
+        $Global{cpu_sockets}{$socket}++ if defined $socket;
+        printf " socket=%d", $socket if defined $socket;
+
+        my $core = $Global{cpuinfo}{$cpu}{core_id};
+        $Global{cpu_socket_cores}{$socket."__".$core}++ if defined $socket && defined $core;
+        printf " core=%d", $core if defined $core;
+
+        my $model = $Global{cpuinfo}{$cpu}{model_name};
+        printf "  %s", $model if defined $model;
+        print "\n";
+    }
+
+    $Global{cpu_sockets_warning} = 1
+        if (scalar keys %{$Global{cpu_sockets}} > 1);
+    foreach my $scn (values %{$Global{cpu_socket_cores}}) {
+        $Global{cpu_socket_cores_warning} = 1 if $scn > 1;
+    }
+}
+
 sub report_graph {
     my $time_per = $Opt_Time_Per_Char;
     if ($time_per == 0) {
@@ -219,6 +297,7 @@ sub report_graph {
         }
         # One more step so we can fit more labels
         $time_per = int($time_per/2);
+        $time_per ||= 1;
     }
 
     my ($graph, $conflicts) = _make_graph($time_per);
@@ -465,9 +544,9 @@ scale printed, i.e. a certain about of time for each character width.  The
 Y-axis shows threads, each thread's execution is shown on one line.  That
 line shows "[" at the position in time when it executes.
 
-Following the "[" is the cpu number the task executed on, followed by zero
+Following the "[" is the CPU number the task executed on, followed by zero
 or more "-" to make the width of the characters match the scaled execution
-time, followed by a "]".  If the scale is too small, the cpu number and
+time, followed by a "]".  If the scale is too small, the CPU number and
 mtask number will not be printed.  If the scale is very small, a "&"
 indicates multiple mtasks started at that time position.
 
@@ -538,9 +617,12 @@ verilator_gantt.vcd.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2018-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.
+Copyright 2018-2021 by Wilson Snyder. This program is free software; you
+can redistribute it and/or modify it under the terms of either the GNU
+Lesser General Public License Version 3 or the Perl Artistic License
+Version 2.0.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 AUTHORS
 

bin/verilator_includer

@@ -1,9 +1,11 @@
 #!/usr/bin/env perl
 # DESCRIPTION: Print include statements for each ARGV
 #
-# Copyright 2003-2020 by Wilson Snyder. This package is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU Lesser
-# General Public License Version 3 or the Perl Artistic License Version 2.0.
+# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
+# Lesser General Public License Version 3 or the Perl Artistic License
+# Version 2.0.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 ######################################################################
 
 require 5.005;

bin/verilator_profcfunc

@@ -228,9 +228,12 @@ Displays this message and program version and exits.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2007-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.
+Copyright 2007-2021 by Wilson Snyder. This program is free software; you
+can redistribute it and/or modify it under the terms of either the GNU
+Lesser General Public License Version 3 or the Perl Artistic License
+Version 2.0.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 =head1 AUTHORS
 

ci/build_vcddiff.sh

@@ -1,18 +0,0 @@
-#!/bin/bash
-# DESCRIPTION: Verilator: Build script for vcddiff
-#
-# Copyright 2019 by Todd Strader. 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.
-set -e
-
-# NB: it would be better to add this via a PPA
-
-TMP_DIR=$(mktemp -d)
-
-git -C "${TMP_DIR}" clone https://github.com/veripool/vcddiff
-VCDDIFF_DIR=${TMP_DIR}/vcddiff
-git -C "${VCDDIFF_DIR}" checkout 5112f88b7ba8818dce9dfb72619e64a1fc19542c
-make -C "${VCDDIFF_DIR}"
-sudo cp "${VCDDIFF_DIR}/vcddiff" /usr/local/bin

ci/build_verilator.sh

@@ -1,64 +0,0 @@
-#!/bin/bash
-# DESCRIPTION: Verilator: Travis CI build script
-#
-# Copyright 2019 by Todd Strader. 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 script builds and caches the Verilator binaries for Travis CI
-# (and possibly other CI platforms).  The Verilator CI system uses this
-# script, but other CI systems that depend on Verilator may also use
-# the script.
-# see: https://github.com/verilator/verilator_ext_tests/blob/master/.travis.yml
-# To use this script, either checkout Verilator as part of the CI build
-# process or add Verilator as a Git submodule.  Verilator tarballs can
-# not be used as the script relies on Git revisions for caching.
-set -e
-
-if [ -z "${VERILATOR_NUM_JOBS}" ]; then
-    VERILATOR_NUM_JOBS=$(nproc)
-fi
-
-# Caching would be simpler if we installed without VERILATOR_ROOT, but
-#   it's needed for driver.pl outside of the repo
-if [ -z "${VERILATOR_ROOT}" ]; then
-    echo "VERILATOR_ROOT not set"
-    exit -1
-fi
-
-if [ -z "${VERILATOR_CACHE}" ]; then
-    echo "VERILATOR_CACHE not set"
-    exit -1
-fi
-
-VERILATOR_REV=$(cd "${VERILATOR_ROOT}" && git rev-parse HEAD)
-echo "Found Verilator rev ${VERILATOR_REV}"
-
-CACHED_REV_FILE=${VERILATOR_CACHE}/.rev.txt
-
-if [[ ! -f "${CACHED_REV_FILE}" || \
-      $(< "${CACHED_REV_FILE}") != "${VERILATOR_REV}" ]]; then
-    echo "Building Verilator"
-
-    # Unsure why Travis monkies with the capitalization of the stage name, but it does
-    if [[ -n ${TRAVIS_BUILD_STAGE_NAME} && \
-         ${TRAVIS_BUILD_STAGE_NAME} != "Build verilator" ]]; then
-      echo "WARNING: Building Verilator in Travis build stage other than \"Build verilator\": ${TRAVIS_BUILD_STAGE_NAME}"
-    fi
-
-    cd "${VERILATOR_ROOT}"
-    autoconf && ./configure ${VERILATOR_CONFIG_FLAGS} && make -j ${VERILATOR_NUM_JOBS}
-    # Copy the Verilator build artifacts
-    mkdir -p "${VERILATOR_CACHE}"
-    rm -rf ${VERILATOR_CACHE}/*
-    cp bin/*bin* "${VERILATOR_CACHE}"
-    # Remember the Git revision
-    echo "${VERILATOR_REV}" > "${CACHED_REV_FILE}"
-else
-    echo "Using cached Verilator"
-    cd "${VERILATOR_ROOT}"
-    # Create include/verilated_config.h and maybe other things
-    autoconf && ./configure ${VERILATOR_CONFIG_FLAGS}
-    cp ${VERILATOR_CACHE}/* bin
-fi

ci/ci-ccache-maint.bash

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI ccache maintenance
+#
+# Copyright 2020 by Geza Lore. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
+# Lesser General Public License Version 3 or the Perl Artistic License
+# Version 2.0.
+#
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+################################################################################
+# This script is run in 'before_script', once ccache has been set up.
+################################################################################
+
+set -e
+set -x
+
+# Show version
+ccache --version
+
+# Flush ccache if requested in commit message
+COMMIT="${CI_PULL_REQUEST_SHA:-$CI_COMMIT}"
+if git log --format=%B -n 1 "$COMMIT" | grep -q -i '\[CI\s\+ccache\s\+clear\]'; then
+  echo "Flushing ccache due to commit message"
+  ccache -C
+fi
+
+# Dump stats, then zero stats
+ccache -s -z

ci/ci-install.bash

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

ci/ci-script.bash

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

ci/docker/buildenv/Dockerfile

@@ -1,49 +1,46 @@
 # 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.
+# 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:18.04
+FROM ubuntu:20.04
 
 RUN apt-get update \
     && DEBIAN_FRONTEND=noninteractive \
        apt-get install --no-install-recommends -y \
-                        autoconf=2.69-11 \
-                        bc=1.07.1-2 \
-                        bison=2:3.0.4.dfsg-1build1 \
-                        build-essential=12.4ubuntu1 \
-                        ca-certificates=20180409 \
-                        cmake=3.10.2-1ubuntu2.18.04.1 \
-                        flex=2.6.4-6 \
-                        gdb=8.1-0ubuntu3.2 \
-                        gcc-6=6.5.0-2ubuntu1~18.04 \
-                        gcc-5=5.5.0-12ubuntu1 \
-                        gcc-4.8=4.8.5-4ubuntu8 \
-                        git=1:2.17.1-1ubuntu0.5 \
-                        gtkwave=3.3.86-1 \
-                        g++-6=6.5.0-2ubuntu1~18.04 \
-                        g++-5=5.5.0-12ubuntu1 \
-                        g++-4.8=4.8.5-4ubuntu8 \
-                        libfl2=2.6.4-6 \
-                        libfl-dev=2.6.4-6 \
-                        numactl=2.0.11-2.1ubuntu0.1 \
-                        perl=5.26.1-6ubuntu0.3 \
-                        python3=3.6.7-1~18.04 \
-                        wget=1.19.4-1ubuntu2.2 \
-                        zlibc=0.9k-4.3 \
-                        zlib1g=1:1.2.11.dfsg-0ubuntu2 \
-                        zlib1g-dev=1:1.2.11.dfsg-0ubuntu2 \
+                        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
 
-COPY build-systemc.sh /tmp/
-RUN ./build-systemc.sh
-
-RUN cpan install -fi Unix::Processors Parallel::Forker Bit::Vector
+RUN cpan install -fi Parallel::Forker
 
 RUN git clone https://github.com/veripool/vcddiff.git && \
     make -C vcddiff && \
@@ -54,4 +51,6 @@ COPY build.sh /tmp/build.sh
 
 ENV VERILATOR_AUTHOR_SITE=1
 
+WORKDIR /work
+
 ENTRYPOINT [ "/tmp/build.sh" ]

ci/docker/buildenv/README.adoc

@@ -1,50 +0,0 @@
-= Verilator Build Environment
-
-This container is set up to compile and test a Verilator build based
-on the following parameters:
-
-* Source repository (default: https://github.com/verilator/verilator)
-* Source revision (default: master)
-* GCC version (4.8.5, 5.5.0, 6.5.0, 7.4.0, default: 7.4.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 of current master:
-
-    docker run -ti verilator/verilator-buildenv
-
-To also run tests:
-
-    docker run -ti verilator/verilator-buildenv test
-
-Change the compiler:
-
-    docker run -ti -e CC=gcc-4.8 -e CXX=g++-4.8 verilator/verilator-buildenv test
-
-The tests that involve gdb are not working due to security restrictions.
-To run those too:
-
-....
-docker run -ti -v ${PWD}:/tmp/repo -e REPO=/tmp/repo -e REV=`git rev-parse --short HEAD` -e CC=gcc-4.8 -e CXX=g++-4.8 --cap-add=SYS_PTRACE --security-opt seccomp=unconfined verilator/verilator-buildenv test
-....
-
-You may want to avoid pushing your changes to a remote repository and
-instead use a local working copy. You can mount the local working copy
-path as a volume and use this as repo. Be careful, that it can only
-use committed changes, so you may want to use a work-in-progress
-commit or so. 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
-....
-
-== Under the Hood
-
-To rebuild the image, simply run:
-
-    docker build .
-
-It will build SystemC in all supported compiler variants to reduce the
-impact on testing cycles. A build script will be the entrypoint to the
-container that will perform a standard build and test procedure.

ci/docker/buildenv/README.rst

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

ci/docker/buildenv/build-systemc.sh

@@ -1,29 +0,0 @@
-#!/bin/bash -e
-# DESCRIPTION: Build SystemC in Ubuntu 18.04 with  different g++/gcc
-#
-# 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.
-
-build_variant () {
-    version=$($1 --version | grep gcc | awk '{print $4}')
-    mkdir "/usr/local/systemc-2.3.3-gcc$version"
-    mkdir build
-    cd build
-    ../configure --prefix="/usr/local/systemc-2.3.3-gcc$version" CC="$1" CXX="$2" LD="$2"
-    make -j
-    make install
-    cd ..
-    rm -r build
-}
-
-wget https://www.accellera.org/images/downloads/standards/systemc/systemc-2.3.3.tar.gz
-tar -xzf systemc-2.3.3.tar.gz
-cd systemc-2.3.3
-build_variant gcc g++
-build_variant gcc-6 g++-6
-build_variant gcc-5 g++-5
-build_variant gcc-4.8 g++-4.8
-cd ..
-rm -r systemc-2.3.3*

ci/docker/buildenv/build.sh

@@ -1,22 +1,17 @@
 #!/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.
+# 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++}"
 
-GCCVERSION=$(${CC} --version | grep gcc | awk '{print $4}')
-
-export SYSTEMC_INCLUDE="/usr/local/systemc-2.3.3-gcc${GCCVERSION}/include"
-export SYSTEMC_LIBDIR="/usr/local/systemc-2.3.3-gcc${GCCVERSION}/lib-linux64"
-export LD_LIBRARY_PATH=${SYSTEMC_LIBDIR}
-
 SRCS=$PWD/verilator
 
 git clone "$REPO" "$SRCS"

ci/docker/run/Dockerfile

@@ -1,24 +1,28 @@
 # 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.
+# 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:18.04
+FROM ubuntu:20.04
 
 RUN apt-get update \
+    && DEBIAN_FRONTEND=noninteractive \
     && apt-get install --no-install-recommends -y \
-                        autoconf=2.69-11 \
-                        bc=1.07.1-2 \
-                        bison=2:3.0.4.dfsg-1build1 \
-                        build-essential=12.4ubuntu1 \
-                        ca-certificates=20180409 \
-                        flex=2.6.4-6 \
-                        git=1:2.17.1-1ubuntu0.5 \
-                        libfl-dev=2.6.4-6 \
-                        perl=5.26.1-6ubuntu0.3 \
-                        python3=3.6.7-1~18.04 \
+                        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/*
 

ci/docker/run/README.adoc

@@ -1,49 +0,0 @@
-= Docker Container as Verilator executable
-
-This allows you to run Verilator easily as a docker image, e.g.:
-
-    docker run -ti verilator/verilator:latest --version
-
-This is in particular useful to compare against older version or to
-check when an issue was introduced.
-
-You will need to give it access to your files as a volume and fix the
-user rights:
-
-....
-docker run -ti -v ${PWD}:/work --user $(id -u):$(id -g) verilator/verilator:latest --cc test.v
-....
-
-The caveat is that it can only access files below the current
-directory then, a workaround is to adopt the volume and set
-`-workdir`.
-
-There is a convenience script in this folder that wraps around the
-docker calls:
-
-    $ verilator-docker 3.922 --version
-    Verilator 3.922 2018-03-17 rev UNKNOWN_REV
-
-Finally, 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
-
-The other files in this folder all for building the containers and to
-store in them. You could use it to build Verilator at a specific
-commit:
-
-    docker build --build-arg SOURCE_COMMIT=<commit> .
-
-== Internals
-
-The Dockerfile is pretty straight-forward, it builds Verilator and
-removes the tree after that to reduce the image size. It sets a
-wrapper script (`verilator-wrap.sh`) as entrypoint. This script calls
-Verilator but also copies the verilated runtime files to the `obj_dir`
-or the `-Mdir` respectively. This allows the user to build the C++
-output with the matching runtime files. The wrapper patches the
-generated Makefile accordingly.
-
-There is also a hook defined that is run by docker hub via automated
-builds.

ci/docker/run/README.rst

@@ -0,0 +1,74 @@
+=====================================
+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

@@ -1,9 +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.FROM ubuntu:18.04
+# 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

@@ -1,10 +1,11 @@
 #!/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.FROM ubuntu:18.04
+# 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

ci/docker/run/verilator-docker

@@ -1,10 +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.
+# 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

@@ -1,13 +1,18 @@
-#!/bin/bash -e
+#!/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.
+# 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+')
@@ -22,5 +27,5 @@ if [ -e ${obj_dir} ]; then
     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
+    sed -i 's/VERILATOR_ROOT = \/usr\/local\/share\/verilator/VERILATOR_ROOT = vlt/g' ${obj_dir}/*.mk
 fi

ci/test.sh

@@ -1,26 +0,0 @@
-#!/bin/bash
-# DESCRIPTION: Verilator: Travis CI test script
-#
-# Copyright 2019 by Todd Strader. 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.
-set -e
-
-export DRIVER_FLAGS='-j 0 --quiet --rerun'
-
-case $1 in
-    dist)
-        make -C test_regress SCENARIOS=--dist
-        ;;
-    vlt)
-        make -C test_regress SCENARIOS=--vlt
-        ;;
-    vltmt)
-        make -C test_regress SCENARIOS=--vltmt
-        ;;
-    *)
-    echo "Usage: test.sh (dist|vlt|vltmt)"
-    exit -1
-    ;;
-esac

codecov.yml

@@ -0,0 +1,38 @@
+# DESCRIPTION: codecov.io config
+#
+# Copyright 2020-2021 by Wilson Snyder. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
+# Lesser General Public License Version 3 or the Perl Artistic License
+# Version 2.0.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+####################
+# Validate:
+#  curl --data-binary @codecov.yml https://codecov.io/validate
+
+codecov:
+  require_ci_to_pass: no
+
+coverage:
+  precision: 2
+  round: down
+  range: "50...100"
+  ignore:
+    - "ci"
+    - "docs"
+    - "examples"
+    - "include/gtkwave"
+    - "include/vltstd"
+    - "test_regress"
+
+parsers:
+  gcov:
+    branch_detection:
+      conditional: yes
+      loop: yes
+      method: no
+      macro: no
+
+comment:
+  layout: "reach,diff,flags,tree"
+  behavior: default
+  require_changes: yes

configure.ac

@@ -1,21 +1,26 @@
 # DESCRIPTION: Process this file with autoconf to produce a configure script.
 #
-# Copyright 2003-2020 by Wilson Snyder. Verilator is free software; you can
-# redistribute it and/or modify it under the terms of either the GNU Lesser
+# Copyright 2003-2021 by Wilson Snyder. Verilator is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU Lesser
 # General Public License Version 3 or the Perl Artistic License Version 2.0.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 #AC_INIT([Verilator],[#.### YYYY-MM-DD])
 #AC_INIT([Verilator],[#.### devel])
-AC_INIT([Verilator],[4.028 2020-02-06],
+AC_INIT([Verilator],[4.200 2021-03-12],
         [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 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],
@@ -108,27 +113,11 @@ AC_ARG_ENABLE([longtests],
 AC_SUBST(CFG_WITH_LONGTESTS)
 AC_MSG_RESULT($CFG_WITH_LONGTESTS)
 
-# CFG_WITH_PREC11
-AC_MSG_CHECKING(whether allow pre-C++11)
-AC_ARG_ENABLE([prec11],
-              [AS_HELP_STRING([--enable-prec11],
-                              [enable pre-C++11 compilers for Verilator binary
-                               and Verilated makefiles])],
-              [case "${enableval}" in
-                yes) CFG_WITH_PREC11=yes ;;
-                no)  CFG_WITH_PREC11=no ;;
-                *)   AC_MSG_ERROR([bad value ${enableval} for --enable-prec11]) ;;
-               esac],
-              [CFG_WITH_PREC11=no;]
-              )
-AC_SUBST(CFG_WITH_PREC11)
-AC_MSG_RESULT($CFG_WITH_PREC11)
-
-# Compiler flags
-CFLAGS+=" -I${includedir}"
-CPPFLAGS+=" -I${includedir}"
-CXXFLAGS+=" -I${includedir}"
-LDFLAGS+=" -L${libdir}"
+# Compiler flags (ensure they are not empty to avoid configure defaults)
+CFLAGS+=" "
+CPPFLAGS+=" "
+CXXFLAGS+=" "
+LDFLAGS+=" "
 
 # Checks for programs.
 AC_PROG_CC
@@ -149,14 +138,31 @@ AC_PATH_PROG(PERL,perl)
 if test "x$PERL" = "x" ; then
    AC_MSG_ERROR([Cannot find "perl" in your PATH, please install it])
 fi
+
+AC_PATH_PROG(PYTHON3,python3)
+if test "x$PYTHON3" = "x" ; then
+   AC_MSG_ERROR([Cannot find "python3" in your PATH, please install it])
+fi
+
 AC_PATH_PROG(LEX,flex)
 if test "x$LEX" = "x" ; then
    AC_MSG_ERROR([Cannot find "flex" in your PATH, please install it])
 fi
+flex_version=$($LEX --version | head -1)
+AC_MSG_RESULT([$LEX --version = $flex_version])
+
 AC_PATH_PROG(YACC,bison)
 if test "x$YACC" = "x" ; then
    AC_MSG_ERROR([Cannot find "bison" in your PATH, please install it])
 fi
+bison_version=$($YACC --version | head -1)
+AC_MSG_RESULT([$YACC --version = $bison_version])
+
+AC_CHECK_PROG(OBJCACHE,ccache,ccache)
+if test "x$OBJCACHE" != "x" ; then
+  objcache_version=$($OBJCACHE --version | head -1)
+  AC_MSG_RESULT([objcache is $OBJCACHE --version = $objcache_version])
+fi
 
 # Checks for libraries.
 
@@ -301,7 +307,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)
 
@@ -328,6 +333,7 @@ m4_foreach([cflag],[
         [-mno-cet],
         [-Qunused-arguments],
         [-Wno-bool-operation],
+        [-Wno-tautological-bitwise-compare],
         [-Wno-parentheses-equality],
         [-Wno-sign-compare],
         [-Wno-uninitialized],
@@ -369,8 +375,13 @@ 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,
@@ -388,12 +399,17 @@ _MY_LDLIBS_CHECK_IFELSE(
    fi])
 AC_SUBST(CFG_LIBS)
 
-# Set CFG_WITH_THREADED if can support threading
-AC_MSG_CHECKING(whether $CXX supports Verilated threads)
-ACO_SAVE_CXXFLAGS="$CXXFLAGS"
-CXXFLAGS="$CXXFLAGS $CFG_CXXFLAGS_STD_NEWEST $CFG_CXXFLAGS_NO_UNUSED"
-AC_LINK_IFELSE(
-     [AC_LANG_PROGRAM([#include <thread>], [[ ]])],
+# Need C++11 at least
+#Alternative: AX_CXX_COMPILE_STDCXX([11])
+AC_DEFUN([_MY_CXX_CHECK_CXX_VER],
+   [# _MY_CXX_CHECK_CXX_VER(flag) -- Check if compiler runs C++11
+    # Set $_my_result
+    AC_LINK_IFELSE(
+     [AC_LANG_PROGRAM([#include <thread>
+#if (__cplusplus < 201103L)
+# error "Too old"
+#endif
+    ], [[ ]])],
      [_my_result=yes
       if test -s conftest.err; then
         if grep -e "$1" conftest.err >/dev/null; then
@@ -401,24 +417,24 @@ AC_LINK_IFELSE(
         fi
       fi],
      [_my_result=no])
-CFG_WITH_THREADED=$_my_result
-AC_SUBST(CFG_WITH_THREADED)
-AC_MSG_RESULT($CFG_WITH_THREADED)
+   ])
 
-# Check compiler flag
-if test "$CFG_WITH_THREADED" = "no" ; then
-   if test "$CFG_WITH_PREC11" = "no" ; then
-      AC_MSG_NOTICE([[]])
-      AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
+AC_MSG_CHECKING(whether $CXX supports C++11)
+_MY_CXX_CHECK_CXX_VER()
+AC_MSG_RESULT($_my_result)
+if test "$_my_result" = "no" ; then
+   CXXFLAGS="$CXXFLAGS $CFG_CXXFLAGS_STD_NEWEST"
+   CFG_CXX_FLAGS_CMAKE="$CFG_CXX_FLAGS_CMAKE $CFG_CXXFLAGS_STD_NEWEST"
+   AC_MSG_CHECKING(whether $CXX supports C++11 with $CFG_CXXFLAGS_STD_NEWEST)
+   _MY_CXX_CHECK_CXX_VER()
+   AC_MSG_RESULT($_my_result)
+fi
+if test "$_my_result" = "no" ; then
+   AC_MSG_NOTICE([[]])
+   AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
 
-Verilator plans to require a C++11 or newer compiler in a future release,
-unless sufficient people report problems. Therefore, if you do not have a
-C++11 compiler, please post a message to
-https://www.veripool.org/boards/3/topics/2580-Verilator-Requiring-C-11-compiler
-indicating your OS and when you think C++11 might be ok, and then rerun
-configure with the --enable-prec11 argument. Thanks.]])
+Verilator requires a C++11 or newer compiler.]])
 
-   fi
 fi
 
 # Checks for library functions.
@@ -426,6 +442,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/CONTRIBUTING.adoc

@@ -1,82 +0,0 @@
-= 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 certify your
-   contribution using email.
-
-* Your test contributions are generally considered released into the public
-  domain, unless you request otherwise or put a GNU/Artistic license on
-  your test 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/CONTRIBUTING.rst

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

docs/CONTRIBUTORS

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

docs/Makefile.in

@@ -7,15 +7,11 @@
 #
 #*****************************************************************************
 #
-# 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
+# Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+# can redistribute it and/or modify it under the terms of either the GNU
 # Lesser General Public License Version 3 or the Perl Artistic License
 # Version 2.0.
-#
-# Verilator is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 #
 #****************************************************************************/
 #
@@ -23,8 +19,8 @@
 
 #### Start of system configuration section. ####
 
-ASCIIDOCTOR = asciidoctor
 DOXYGEN = doxygen
+RST2HTML = rst2html
 
 #### End of system configuration section. ####
 ######################################################################
@@ -34,8 +30,8 @@ DOXYGEN = doxygen
 default:
 	@echo "error: make not supported here, run 'make docs' from Verilator top-level"
 
-%.html: %.adoc
-	$(ASCIIDOCTOR) $< -n -o $@
+%.html: %.rst
+	$(RST2HTML) $< $@
 
 clean mostlyclean distclean maintainer-clean::
 	rm -f $(SCRIPTS) *.tmp

docs/TODO

@@ -1,9 +1,10 @@
 // DESCRIPTION: Verilator: List of To Do issues.
 //
-// Copyright 2004-2020 by Wilson Snyder. This program is free software; you can
+// Copyright 2004-2021 by Wilson Snyder. This program is free software; you can
 // redistribute it and/or modify it under the terms of either the GNU
 // Lesser General Public License Version 3 or the Perl Artistic License
 // Version 2.0.
+// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 * Language support:
 ** Fix ordering of each bit separately in a signal (mips)
@@ -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
@@ -90,7 +84,7 @@
    "if (a) { ... b=2; } else { ... b=2;}" -> "b=2; if ..."
    Careful though, as b could appear in the statement or multiple times in statement
    (Could just require exatly two 'b's in statement)
-** Simplify XOR/XNOR/AND/OR bit selection trees
+** Simplify XOR/AND/OR bit selection trees
    Foo = A[1] ^ A[2] ^ A[3] etc are better as ^ ( A & 32'b...1110 )
 ** Combine variables into wider elements
    Parallel statements on different bits should become single signal
@@ -102,8 +96,6 @@
    Don't merge if any combining would form circ logic (out goes back to in)
 ** Multiple assignments each bit can become single assign with concat
    Make sure a SEL of a CONCAT can get the single bit back.
-** Usually blocks/values
-   Enable only after certain time, so VL_TIME_I(32) > 0x1e gets eliminated out
 ** Better ordering of a<=b, b<=c, put all refs to 'b' next to each other to optimize caching
 ** I-cache packing improvements (what/how?)
 ** Data cache organization (order of vars in class)

docs/install.adoc

@@ -1,303 +0,0 @@
-= Verilator Installation
-:toc: right
-
-// Github doesn't render unless absolute URL
-image::https://www.veripool.org/img/verilator_256_200_min.png[Logo,256,200,role="right"]
-
-== Introduction
-
-This discusses how to install Verilator.  For more general information
-please see https://verilator.org[verilator.org].
-
-== Quick-start
-
-=== Install From a Package Manager
-
-Using a distribution's package manager is the easiest way to get
-started. (Note packages are unlikely to have the most recent version, so
-Git, below, maybe a better alternative.) To install as a package:
-
-   apt-get install verilator
-
-If this works, skip down to <<Running Verilator>>.
-
-=== Docker
-
-Verilator is available in pre-built Docker containers. See
-https://github.com/verilator/verilator/blob/master/ci/docker/run/README.adoc
-
-=== Git
-
-Installing Verilator with Git provides the most flexibility.
-For additional options and details see the additional sections below.  In
-brief:
-
-// Also update README
-....
-# Prerequisites:
-#sudo apt-get install git make autoconf g++ flex bison
-#sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
-#sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
-
-git clone https://git.veripool.org/git/verilator   # Only first time
-## Note the URL above is not a page you can see with a browser, it's for git only
-
-# Every time you need to build:
-unsetenv VERILATOR_ROOT  # For csh; ignore error if on bash
-unset VERILATOR_ROOT  # For bash
-cd verilator
-git pull        # Make sure git repository is up-to-date
-git tag         # See what versions exist
-#git checkout master      # Use development branch (e.g. recent bug fixes)
-#git checkout stable      # Use most recent stable release
-#git checkout v{version}  # Switch to specified release version
-
-autoconf        # Create ./configure script
-./configure
-make
-sudo make install
-# Now see "man verilator" or online verilator.pdf's for the example tutorials
-....
-
-If this works, skip down to <<Running Verilator>>.
-
-== Detailed Build Instructions
-
-This section describes details of the build process, and assumes you are
-building from Git or a tarball.  For using a pre-built binary for your
-Linux distribution, see instead <<Install From a Package Manager>>.
-
-=== OS Requirements
-
-Verilator is developed and has primary testing on Ubuntu.  Versions have
-also built on Redhat Linux, Apple OS-X, HPUX and Solaris.  It should run
-with minor porting on any GNU/Linux-ish platform.  Verilator also works on
-Windows under Cygwin, and Windows under MinGW (gcc -mno-cygwin).  Verilated
-output (not Verilator itself) compiles under all the options above, plus
-MSVC++.
-
-=== Install Prerequisites
-
-To build Verilator you will need to install some standard packages:
-
-   sudo apt-get install git
-   sudo apt-get install autoconf
-   sudo apt-get install flex bison
-
-The following are optional, but improve compilation speed:
-
-   sudo apt-get install libgoogle-perftools-dev
-
-Additionally, to build or run Verilator you need these standard packages:
-
-   sudo apt-get install perl python3
-   sudo apt-get install 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)
-
-Those developing Verilator may also want these (see internals.adoc):
-
-   sudo apt-get install gdb asciidoctor graphviz
-   cpan install Pod::Perldoc
-   cpan install Unix::Processors
-
-==== Install SystemC
-
-If you will be using SystemC (vs straight C++ output), download
-https://www.accellera.org/downloads/standards/systemc[SystemC].
-Follow their installation instructions.  You will need to set `SYSTEMC_INCLUDE`
-to point to the include directory with `systemc.h` in it, and `SYSTEMC_LIBDIR`
-to points to the directory with `libsystemc.a` in it.  (Older installations
-may set `SYSTEMC` and `SYSTEMC_ARCH` instead.)
-
-==== Install GTKWave
-
-To make use of Verilator FST tracing you will want
-http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not
-required at Verilator build time.
-
-=== Obtain Sources
-
-You may use Git or a tarball for the sources.  Git is the supported option.
-(If using a historical build that uses a tarball, tarballs are obtained
-from https://www.veripool.org/projects/verilator/wiki/Download[Verilator
-Downloads]; we presume you know how to use it, and is not described here.)
-
-Get the sources from the repository: (You need do this only once, ever.)
-
-   git clone https://git.veripool.org/git/verilator   # Only first time
-   ## Note the URL above is not a page you can see with a browser, it's for git only
-
-Enter the checkout and determine what version/branch to use:
-
-   cd verilator
-   git pull        # Make sure we're up-to-date
-   git tag         # See what versions exist
-   #git checkout master      # Use development branch (e.g. recent bug fix)
-   #git checkout stable      # Use most recent release
-   #git checkout v{version}  # Switch to specified release version
-
-=== Auto Configure
-
-Create the configuration script:
-
-   autoconf        # Create ./configure script
-
-=== Eventual Installation Options
-
-Before configuring the build, you have to decide how you're going to
-eventually install the kit.  Verilator will be compiling the current value
-of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults
-into the executable, so they must be correct before configuring.
-
-These are the options:
-
-==== 1. Run-in-Place from VERILATOR_ROOT
-
-Our personal favorite is to always run Verilator in-place from its Git
-directory.  This allows the easiest experimentation and upgrading, and
-allows many versions of Verilator to co-exist on a system.
-
-   export VERILATOR_ROOT=`pwd`   # if your shell is bash
-   setenv VERILATOR_ROOT `pwd`   # if your shell is csh
-   ./configure
-   # Running will use files from $VERILATOR_ROOT, so no install needed
-
-Note after installing (below steps), a calling program or shell must set
-the environment variable `VERILATOR_ROOT` to point to this Git directory,
-then execute `$VERILATOR_ROOT/bin/verilator`, which will find the path to
-all needed files.
-
-==== 2. Install into a CAD Disk
-
-You may eventually be installing onto a project/company-wide "CAD" tools
-disk that may support multiple versions of every tool.  Target the build to
-a destination directory name that includes the Verilator version name:
-
-   unset VERILATOR_ROOT      # if your shell is bash
-   unsetenv VERILATOR_ROOT   # if your shell is csh
-   # For the tarball, use the version number instead of git describe
-   ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`
-
-Note after installing (below steps), if you use
-http://modules.sourceforge.net/[modulecmd], you'll want a module file like
-the following:
-
-.modulecmd's verilator/version file
-----
-set install_root /CAD_DISK/verilator/{version-number-used-above}
-unsetenv VERILATOR_ROOT
-prepend-path PATH $install_root/bin
-prepend-path MANPATH $install_root/man
-prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
-----
-
-==== 3. Install into a Specific Path
-
-You may eventually install Verilator into a specific installation prefix,
-as most GNU tools support:
-
-   unset VERILATOR_ROOT      # if your shell is bash
-   unsetenv VERILATOR_ROOT   # if your shell is csh
-   ./configure --prefix /opt/verilator-VERSION
-
-Then after installing (below steps) you will need to add
-`/opt/verilator-VERSION/bin` to `$PATH`.
-
-==== 4. Install System Globally
-
-The final option is to eventually install Verilator globally, using the
-normal system paths:
-
-   unset VERILATOR_ROOT      # if your shell is bash
-   unsetenv VERILATOR_ROOT   # if your shell is csh
-   ./configure
-
-Then after installing (below) the binary directories should already be in
-your `$PATH`.
-
-=== Configure
-
-The command to configure the package was described in the previous step.
-Developers should configure to have more complete developer tests.
-Additional packages may be required for these tests.
-
-   export VERILATOR_AUTHOR_SITE=1    # Put in your .bashrc
-   ./configure --enable-longtests  ...above options...
-
-=== Compile
-
-Compile Verilator:
-
-   make -j
-
-=== Test
-
-Check the compilation by running self-tests:
-
-   make test
-
-=== Install
-
-If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
-install to the OS-standard place:
-
-   make install
-
-== Running Verilator
-
-To run Verilator, see the example sections in the
-https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
-or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-Also see the `examples/` directory that is part of the kit, and is installed
-(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
-
-     cd examples/make_hello_c
-     make
-
-Note if you did a `make install` above you should not have `VERILATOR_ROOT`
-set in your environment; it is built into the executable.
-
-== Announcements
-
-To get notified of new releases, login to
-https://www.veripool.org[Veripool], and click the "watch" button near the
-top right under https://www.veripool.org/projects/verilator/news[Verilator
-News].
-
-== 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.

docs/install.rst

@@ -0,0 +1,397 @@
+|Logo|
+
+======================
+Verilator Installation
+======================
+
+.. contents::
+   :depth: 3
+
+Introduction
+============
+
+This discusses how to install Verilator. For more general information
+please see `verilator.org <https://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 <#_running_verilator>`__.
+
+
+Docker
+------
+
+Verilator is available in pre-built Docker containers. See
+https://github.com/verilator/verilator/blob/master/ci/docker/run/README.rst
+
+
+Git
+---
+
+Installing Verilator with Git provides the most flexibility. For
+additional options and details see the additional sections below. In
+brief:
+
+::
+
+   # 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 <#_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 <#_install_from_a_package_manager>`__.
+
+
+OS Requirements
+---------------
+
+Verilator is developed and has primary testing on Ubuntu, with additional
+testing on FreeBSD and Apple OS-X. Versions have also built on Redhat
+Linux, HPUX and Solaris. It should run with minor porting on any
+GNU/Linux-ish platform. Verilator also works on Windows under Cygwin, and
+Windows under MinGW (gcc -mno-cygwin). Verilated output (not Verilator
+itself) compiles under all the options above, plus MSVC++.
+
+
+Install Prerequisites
+---------------------
+
+To build or run Verilator you need these standard packages:
+
+::
+
+   sudo apt-get install perl python3 make
+   sudo apt-get install g++  # Alternatively, clang
+   sudo apt-get install libgz  # Non-Ubuntu (ignore if gives error)
+   sudo apt-get install libfl2 libfl-dev zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)
+
+To build or run the following are optional but should be installed for good
+performance:
+
+::
+
+   sudo apt-get install ccache  # If present at build, needed for run
+   sudo apt-get install libgoogle-perftools-dev numactl perl-doc
+
+To build Verilator you will need to install these packages; these do not
+need to be present to run Verilator:
+
+::
+
+   sudo apt-get install git autoconf flex bison
+
+Those developing Verilator itself may also want these (see internals.rst):
+
+::
+
+   sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
+   cpan install Pod::Perldoc
+   cpan install Parallel::Forker
+
+
+Install SystemC
+~~~~~~~~~~~~~~~
+
+If you will be using SystemC (vs straight C++ output), download `SystemC
+<https://www.accellera.org/downloads/standards/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 `GTKwave
+<http://gtkwave.sourceforge.net/>`__ 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 `Verilator Downloads
+<https://www.veripool.org/projects/verilator/wiki/Download>`__; 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 `modulecmd
+<http://modules.sourceforge.net/>`__, 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
+<#_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 `Verilator manual (HTML)
+<https://verilator.org/verilator_doc.html>`__, or `Verilator manual (PDF)
+<https://verilator.org/verilator_doc.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 `Verilator announcement repository
+<https://github.com/verilator/verilator-announce>`__ and follow the
+instructions there.
+
+
+Directory Structure
+===================
+
+Some relevant files and directories in this package are as follows:
+
+::
+
+   Changes                     => Version history
+   README.rst                 => 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 `Verilator manual
+(HTML) <https://verilator.org/verilator_doc.html>`__, or `Verilator
+manual (PDF) <https://verilator.org/verilator_doc.pdf>`__.
+
+
+License
+=======
+
+Copyright 2008-2021 by Wilson Snyder. Verilator is free software; you can
+redistribute it and/or modify it under the terms of either the GNU Lesser
+General Public License Version 3 or the Perl Artistic License Version 2.0.
+
+.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png

docs/internals.adoc

@@ -1,989 +0,0 @@
-= Verilator Internals Documentation
-: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 file discusses internal and programming details for Verilator.  It's a
-reference for developers and debugging problems.
-
-See also the Verilator internals presentation at https://www.veripool.org.
-
-== Code Flows
-
-=== Verilator Flow
-
-The main flow of Verilator can be followed by reading the Verilator.cpp
-`process()` function:
-
-. First, the files specified on the command line are read.  Reading
-involves preprocessing, then lexical analysis with Flex and parsing with
-Bison.  This produces an abstract syntax tree (AST) representation of the
-design, which is what is visible in the .tree files described below.
-
-. Verilator then makes a series of passes over the AST, progressively
-refining and optimizing it.
-
-. Cells in the AST first linked, which will read and parse additional files
-as above.
-
-. Functions, variable and other references are linked to their definitions.
-
-. Parameters are resolved and the design is elaborated.
-
-. Verilator then performs many additional edits and optimizations on the
-hierarchical design.  This includes coverage, assertions, X elimination,
-inlining, constant propagation, and dead code elimination.
-
-. References in the design are then pseudo-flattened.  Each module's
-variables and functions get "Scope" references.  A scope reference is an
-occurrence of that un-flattened variable in the flattened hierarchy.  A
-module that occurs only once in the hierarchy will have a single scope and
-single VarScope for each variable.  A module that occurs twice will have a
-scope for each occurrence, and two VarScopes for each variable.  This
-allows optimizations to proceed across the flattened design, while still
-preserving the hierarchy.
-
-. Additional edits and optimizations proceed on the pseudo-flat design.
-These include module references, function inlining, loop unrolling,
-variable lifetime analysis, lookup table creation, always splitting, and
-logic gate simplifications (pushing inverters, etc).
-
-. Verilator orders the code.  Best case, this results in a single "eval"
-function which has all always statements flowing from top to bottom with no
-loops.
-
-. Verilator mostly removes the flattening, so that code may be shared
-between multiple invocations of the same module.  It localizes variables,
-combines identical functions, expands macros to C primitives, adds branch
-prediction hints, and performs additional constant propagation.
-
-. Verilator finally writes the C++ modules.
-
-=== Key Classes Used in the Verilator Flow
-
-==== `AstNode`
-
-The AST is represented at the top level by the class `AstNode`. This
-abstract class has derived classes for the individual components
-(e.g. `AstGenerate` for a generate block) or groups of components
-(e.g. `AstNodeFTask` for functions and tasks, which in turn has `AstFunc`
-and `AstTask` as derived classes). An important property of the `AstNode`
-type hierarchy is that all non-final subclasses of `AstNode` (i.e.: those
-which themselves have subclasses) must be abstract as well, and be named
-with the prefix `AstNode*`. The `astgen` (see below) script relies on this.
-
-Each `AstNode` has pointers to up to four children, accessed by the `op1p`
-through `op4p` methods.  These methods are then abstracted in a specific
-Ast* node class to a more specific name.  For example with the `AstIf` node
-(for `if` statements), `ifsp` calls `op2p` to give the pointer to the AST
-for the "then" block, while `elsesp` calls `op3p` to give the pointer to
-the AST for the "else" block, or NULL if there is not one.
-
-`AstNode` has the concept of a next and previous AST - for example the next
-and previous statements in a block. Pointers to the AST for these
-statements (if they exist) can be obtained using the `back` and `next`
-methods.
-
-It is useful to remember that the derived class `AstNetlist` is at the top
-of the tree, so checking for this class is the standard way to see if you
-are at the top of the tree.
-
-By convention, each function/method uses the variable `nodep` as a pointer
-to the `AstNode` currently being processed.
-
-==== `AstNVisitor`
-
-The passes are implemented by AST visitor classes.  These are implemented
-by subclasses of the abstract class, `AstNVisitor`. Each pass creates an
-instance of the visitor class, which in turn implements a method to perform
-the pass.
-
-==== `V3Graph`
-
-A number of passes use graph algorithms, and the class `V3Graph` is
-provided to represent those graphs. Graphs are directed, and algorithms are
-provided to manipulate the graphs and to output them in
-https://www.graphviz.org[GraphViz] dot format. `V3Graph.h` provides
-documentation of this class.
-
-==== `V3GraphVertex`
-
-`V3GraphVertex` is the base class for vertices in a graph. Vertices have
-an associated `fanout`, `color` and `rank`, which may be used in algorithms
-for ordering the graph. A generic `user`/`userp` member variable is also
-provided.
-
-Virtual methods are provided to specify the name, color, shape and style to
-be used in dot output. Typically users provide derived classes from
-`V3GraphVertex` which will reimplement these methods.
-
-Iterators are provided to access in and out edges. Typically these are used
-in the form:
-
-   for (V3GraphEdge *edgep = vertexp->inBeginp();
-      edgep;
-      edgep = edgep->inNextp()) {
-
-==== `V3GraphEdge`
-
-`V3GraphEdge` is the base class for directed edges between pairs of
-vertices. Edges have an associated `weight` and may also be made
-`cutable`. A generic `user`/`userp` member variable is also provided.
-
-Accessors, `fromp` and `top` return the "from" and "to" vertices
-respectively.
-
-Virtual methods are provided to specify the label, color and style to be
-used in dot output. Typically users provided derived classes from
-`V3GraphEdge` which will reimplement these methods.
-
-==== `V3GraphAlg`
-
-This is the base class for graph algorithms. It implements a `bool` method,
-`followEdge` which algorithms can use to decide whether an edge is
-followed. This method returns true if the graph edge has weight greater
-than one and a user function, `edgeFuncp` (supplied in the constructor)
-returns `true`.
-
-A number of predefined derived algorithm classes and access methods are
-provided and documented in `V3GraphAlg.cpp`.
-
-=== Multithreaded Mode
-
-In `--threads` mode, the frontend of the Verilator pipeline is the same as
-serial mode, up until V3Order.
-
-`V3Order` builds a fine-grained, statement-level dependency graph that
-governs the ordering of code within a single `eval()` call. In serial mode,
-that dependency graph is used to order all statements into a total serial
-order.  In parallel mode, the same dependency graph is the starting point
-for a partitioner (`V3Partition`).
-
-The partitioner's goal is to coarsen the fine-grained graph into a coarser
-graph, while maintaining as much available parallelism as possible. Often
-the partitioner can transform an input graph with millions of nodes into a
-coarsened execution graph with a few dozen nodes, while maintaining enough
-parallelism to take advantage of a modern multicore CPU. Runtime
-synchronization cost is not prohibitive with so few nodes.
-
-==== Partitioning
-
-Our partitioner is similar to the one Vivek Sarkar described in his 1989
-paper _Partitioning and Scheduling Parallel Programs for Multiprocessors_.
-
-Let's define some terms:
-
-==== Par Factor
-
-The available parallelism or "par-factor" of a DAG is the total cost to
-execute all nodes, divided by the cost to execute the longest critical path
-through the graph. This is the speedup you would get from running the graph
-in parallel, if given infinite CPU cores available and communication and
-synchronization are zero.
-
-==== Macro Task
-
-When the partitioner coarsens the graph, it combines nodes together. Each
-fine-grained node represents an atomic "task"; combined nodes in the
-coarsened graph are "macro-tasks". This term comes from Sarkar. Each
-macro-task executes from start to end on one processor, without any
-synchronization to any other macro-task during its
-execution. (Synchronization only happens before the macro-task begins or
-after it ends.)
-
-==== Edge Contraction
-
-Verilator's partitioner, like Sarkar's, primarily relies on "edge
-contraction" to coarsen the graph. It starts with one macro-task per atomic
-task and iteratively combines pairs of edge-connected macro-tasks.
-
-==== Local Critical Path
-
-Each node in the graph has a "local" critical path. That's the critical
-path from the start of the graph to the start of the node, plus the node's
-cost, plus the critical path from the end of the node to the end of the
-graph.
-
-Sarkar calls out an important trade-off: coarsening the graph reduces
-runtime synchronization overhead among the macro-tasks, but it tends to
-increase the critical path through the graph and thus reduces par-factor.
-
-Sarkar's partitioner, and ours, chooses pairs of macro-tasks to merge such
-that the growth in critical path is minimized. Each candidate merge would
-result in a new node, which would have some local critical path. We choose
-the candidate that would produce the shortest local critical path. Repeat
-until par-factor falls to a target threshold. It's a greedy algorithm, and
-it's not guaranteed to produce the best partition (which Sarkar proves is
-NP-hard).
-
-==== Estimating Logic Costs
-
-To compute the cost of any given path through the graph, Verilator
-estimates an execution cost for each task. Each macro-task has an execution
-cost which is simply the sum of its tasks' costs. We assume that
-communication overhead and synchronization overhead are zero, so the cost
-of any given path through the graph is simply the sum of macro-task
-execution costs. Sarkar does almost the same thing, except that he has
-nonzero estimates for synchronization costs.
-
-Verilator's cost estimates are assigned by `InstrCountCostVisitor`.  This
-class is perhaps the most fragile piece of the multithread implementation.
-It's easy to have a bug where you count something cheap (eg. accessing one
-element of a huge array) as if it were expensive (eg. by counting it as if
-it were an access to the entire array.) Even without such gross bugs, the
-estimates this produce are only loosely predictive of actual runtime cost.
-Multithread performance would be better with better runtime costs
-estimates.  This is an area to improve.
-
-==== Scheduling Macro-Tasks at Runtime
-
-After coarsening the graph, we must schedule the macro-tasks for runtime.
-Sarkar describes two options: you can dynamically schedule tasks at
-runtime, with a runtime graph follower. Sarkar calls this the
-"macro-dataflow model."  Verilator does not support this; early experiments
-with this approach had poor performance.
-
-The other option is to statically assign macro-tasks to threads, with each
-thread running its macro-tasks in a static order. Sarkar describes this in
-Chapter 5. Verilator takes this static approach. The only dynamic aspect is
-that each macro task may block before starting, to wait until its
-prerequisites on other threads have finished.
-
-The synchronization cost is cheap if the prereqs are done. If they're not,
-fragmentation (idle CPU cores waiting) is possible. This is the major
-source of overhead in this approach. The `--prof-threads` switch and the
-`verilator_gantt` script can visualize the time lost to such fragmentation.
-
-==== Locating Variables for Best Spatial Locality
-
-After scheduling all code, we attempt to locate variables in memory such
-that variables accessed by a single macro-task are close together in
-memory.  This provides "spatial locality" -- when we pull in a 64-byte
-cache line to access a 2-byte variable, we want the other 62 bytes to be
-ones we'll also likely access soon, for best cache performance.
-
-This turns out to be critical for performance. It should allow Verilator to
-scale to very large models. We don't rely on our working set fitting in any
-CPU cache; instead we essentially "stream" data into caches from
-memory. It's not literally streaming, where the address increases
-monotonically, but it should have similar performance characteristics, so
-long as each macro-task's dataset fits in one core's local caches.
-
-To achieve spatial locality, we tag each variable with the set of
-macro-tasks that access it. Let's call this set the "footprint" of that
-variable. The variables in a given module have a set of footprints. We can
-order those footprints to minimize the distance between them (distance is
-the number of macro-tasks that are different across any two footprints) and
-then emit all variables into the struct in ordered-footprint order.
-
-The footprint ordering is literally the traveling salesman problem, and we
-use a TSP-approximation algorithm to get close to an optimal sort.
-
-This is an old idea. Simulators designed at DEC in the early 1990s used
-similar techniques to optimize both single-thread and multi-thread modes.
-(Verilator does not optimize variable placement for spatial locality in
-serial mode; that is a possible area for improvement.)
-
-==== Improving Multithreaded Performance Further (a TODO list)
-
-===== Wave Scheduling
-
-To allow the Verilated model to run in parallel with the testbench, it
-might be nice to support "wave" scheduling, in which work on a cycle begins
-before `eval()` is called or continues after `eval()` returns.  For now all
-work on a cycle happens during the `eval()` call, leaving Verilator's
-threads idle while the testbench (everything outside `eval()`) is
-working. This would involve fundamental changes within the partitioner,
-however, it's probably the best bet for hiding testbench latency.
-
-===== Efficient Dynamic Scheduling
-
-To scale to more than a few threads, we may revisit a fully dynamic
-scheduler. For large (>16 core) systems it might make sense to dedicate an
-entire core to scheduling, so that scheduler data structures would fit in
-its L1 cache and thus the cost of traversing priority-ordered ready lists
-would not be prohibitive.
-
-===== Static Scheduling with Runtime Repack
-
-We could modify the static scheduling approach by gathering actual
-macro-task execution times at run time, and dynamically re-packing the
-macro-tasks into the threads also at run time. Say, re-pack once every
-10,000 cycles or something. This has the potential to do better than our
-static estimates about macro-task run times. It could potentially react to
-CPU cores that aren't performing equally, due to NUMA or thermal throttling
-or nonuniform competing memory traffic or whatever.
-
-===== Clock Domain Balancing
-
-Right now Verilator makes no attempt to balance clock domains across
-macro-tasks. For a multi-domain model, that could lead to bad gantt chart
-fragmentation. This could be improved if it's a real problem in practice.
-
-===== Other Forms of MTask Balancing
-
-The largest source of runtime overhead is idle CPUs, which happens due to
-variance between our predicted runtime for each MTask and its actual
-runtime. That variance is magnified if MTasks are homogeneous, containing
-similar repeating logic which was generally close together in source code
-and which is still packed together even after going through Verilator's
-digestive tract.
-
-If Verilator could avoid doing that, and instead would take source logic
-that was close together and distribute it across MTasks, that would
-increase the diversity of any given MTask, and this should reduce variance
-in the cost estimates.
-
-One way to do that might be to make various "tie breaker" comparison
-routines in the sources to rely more heavily on randomness, and generally
-try harder not to keep input nodes together when we have the option to
-scramble things.
-
-===== Performance Regression
-
-It would be nice if we had a regression of large designs, with some
-diversity of design styles, to test on both single- and multi-threaded
-modes. This would help to avoid performance regressions, and also to
-evaluate the optimizations while minimizing the impact of parasitic noise.
-
-===== Per-Instance Classes
-
-If we have multiple instances of the same module, and they partition
-differently (likely; we make no attempt to partition them the same) then
-the variable sort will be suboptimal for either instance.  A possible
-improvement would be to emit a unique class for each instance of a module,
-and sort its variables optimally for that instance's code stream.
-
-=== Verilated Flow
-
-The evaluation loop outputted by Verilator is designed to allow a single
-function to perform evaluation under most situations.
-
-On the first evaluation, the Verilated code calls initial blocks, and then
-"settles" the modules, by evaluating functions (from always statements)
-until all signals are stable.
-
-On other evaluations, the Verilated code detects what input signals have
-changes.  If any are clocks, it calls the appropriate sequential functions
-(from `always @ posedge` statements).  Interspersed with sequential functions
-it calls combo functions (from `always @*`).  After this is complete, it
-detects any changes due to combo loops or internally generated clocks, and
-if one is found must reevaluate the model again.
-
-For SystemC code, the `eval()` function is wrapped in a SystemC
-`SC_METHOD`, sensitive to all inputs.  (Ideally it would only be sensitive
-to clocks and combo inputs, but tracing requires all signals to cause
-evaluation, and the performance difference is small.)
-
-If tracing is enabled, a callback examines all variables in the design for
-changes, and writes the trace for each change.  To accelerate this process
-the evaluation process records a bitmask of variables that might have
-changed; if clear, checking those signals for changes may be skipped.
-
-== Coding Conventions
-
-=== Compiler Version and C++11
-
-Verilator supports GCC 4.4.7 and newer.  GCC 4.4.7 does not support C++11,
-therefore C++11 is generally not required.  Exceptions may be made to
-require C++11 for features that are only practical with C++11,
-e.g. threads.
-
-=== Indentation and Naming Style
-
-We will work with contributors to fix up indentation style issues, but it
-is appreciated if you could match our style:
-
-* All files should contain the magic header to ensure standard indentation:
-+
-   // -*- mode: C++; c-file-style: "cc-mode" -*-
-+
-This sets indentation to the `cc-mode` defaults.  (Verilator predates a
-CC-mode change of several years ago which overrides the defaults with GNU
-style indentation; the `c-set-style` undoes that.)
-
-* Use 4 spaces per level, and no tabs.
-
-* Use 2 spaces between the end of source and the beginning of a comment.
-
-* Use 1 space after if/for/switch/while and similar keywords.
-
-* No spaces before semicolons, nor between a function's name and open
-parenthesis (only applies to functions; if/else has a following space).
-
-* Use "mixedCapsSymbols" instead of "underlined_symbols".
-
-* Uas a "p" suffix on variables that are pointers, e.g. "nodep".
-
-* Comment every member variable.
-
-=== The `astgen` Script
-
-Some of the code implementing passes is extremely repetitive, and must be
-implemented for each sub-class of `AstNode`. However, while repetitive,
-there is more variability than can be handled in C++ macros.
-
-In Verilator this is implemented by using a Perl script, `astgen` to
-pre-process the C++ code. For example in `V3Const.cpp` this is used to
-implement the `visit()` functions for each binary operation using the
-`TREEOP` macro.
-
-The original C++ source code is transformed into C++ code in the `obj_opt`
-and `obj_dbg` sub-directories (the former for the optimized version of
-Verilator, the latter for the debug version). So for example `V3Const.cpp`
-into `V3Const__gen.cpp`.
-
-=== Visitor Functions
-
-Verilator uses the "Visitor" design pattern to implement its refinement and
-optimization passes. This allows separation of the pass algorithm from the
-AST on which it operates. Wikipedia provides an introduction to the concept
-at https://en.wikipedia.org/wiki/Visitor_pattern.
-
-As noted above, all visitors are derived classes of `AstNVisitor`. All
-derived classes of `AstNode` implement the `accept` method, which takes as
-argument a reference to an instance or a `AstNVisitor` derived class and
-applies the visit method of the `AstNVisitor` to the invoking AstNode
-instance (i.e. `this`).
-
-One possible difficulty is that a call to `accept` may perform an edit
-which destroys the node it receives as argument. The
-`acceptSubtreeReturnEdits` method of `AstNode` is provided to apply
-`accept` and return the resulting node, even if the original node is
-destroyed (if it is not destroyed it will just return the original node).
-
-The behavior of the visitor classes is achieved by overloading the `visit`
-function for the different `AstNode` derived classes. If a specific
-implementation is not found, the system will look in turn for overloaded
-implementations up the inheritance hierarchy. For example calling `accept`
-on `AstIf` will look in turn for:
-
-   void visit(AstIf* nodep)
-   void visit(AstNodeIf* nodep)
-   void visit(AstNodeStmt* nodep)
-   void visit(AstNode* nodep)
-
-There are three ways data is passed between visitor functions.
-
-1. A visitor-class member variable.  This is generally for passing "parent"
-information down to children.  `m_modp` is a common example.  It's set to
-NULL in the constructor, where that node (`AstModule` visitor) sets it,
-then the children are iterated, then it's cleared.  Children under an
-`AstModule` will see it set, while nodes elsewhere will see it clear.  If
-there can be nested items (for example an `AstFor` under an `AstFor`) the
-variable needs to be save-set-restored in the `AstFor` visitor, otherwise
-exiting the lower for will lose the upper for's setting.
-
-2. User attributes.  Each `AstNode` (*Note.* The AST node, not the visitor)
-has five user attributes, which may be accessed as an integer using the
-`user1()` through `user5()` methods, or as a pointer (of type `AstNUser`)
-using the `user1p()` through `user5p()` methods (a common technique lifted
-from graph traversal packages).
-+
-A visitor first clears the one it wants to use by calling
-`AstNode::user#ClearTree()`, then it can mark any node's `user#()` with whatever
-data it wants.  Readers just call `nodep->user()`, but may need to cast
-appropriately, so you'll often see `VN_CAST(nodep->userp(), SOMETYPE)`.
-At the top of each visitor are comments describing how the `user()` stuff
-applies to that visitor class.  For example:
-+
-   // NODE STATE
-   // Cleared entire netlist
-   //   AstModule::user1p()     // bool. True to inline this module
-+
-This says that at the `AstNetlist` `user1ClearTree()` is called.  Each
-`AstModule`'s `user1()` is used to indicate if we're going to inline it.
-+
-These comments are important to make sure a `user#()` on a given `AstNode`
-type is never being used for two different purposes.
-+
-Note that calling `user#ClearTree` is fast, it doesn't walk the tree, so
-it's ok to call fairly often.  For example, it's commonly called on every
-module.
-
-3. Parameters can be passed between the visitors in close to the "normal"
-function caller to callee way.  This is the second `vup` parameter of type
-`AstNUser` that is ignored on most of the visitor functions.  V3Width does
-this, but it proved more messy than the above and is deprecated.  (V3Width
-was nearly the first module written.  Someday this scheme may be removed,
-as it slows the program down to have to pass vup everywhere.)
-
-=== Iterators
-
-`AstNVisitor` provides a set of iterators to facilitate walking over the
-tree. Each operates on the current `AstNVisitor` class (as this) and takes
-an argument type `AstNode*`.
-
-`iterate`::
-
-Applies the `accept` method of the `AstNode` to the visitor function.
-
-`iterateAndNextIgnoreEdit`::
-
-Applies the `accept` method of each `AstNode` in a list (i.e. connected by
-`nextp` and `backp` pointers).
-
-`iterateAndNextNull`::
-
-Applies the `accept` method of each `AstNode` in a list, only if the
-provided node is non-NULL. If a node is edited by the call to `accept`,
-apply `accept` again, until the node does not change.
-
-`iterateListBackwards`::
-
-Applies the `accept` method of each `AstNode` in a list, starting with the
-last one.
-
-`iterateChildren`::
-
-Applies the `iterateAndNextNull` method on each child `op1p` through `op4p`
-in turn.
-
-`iterateChildrenBackwards`::
-
-Applies the `iterateListBackwards` method on each child `op1p` through
-`op4p` in turn.
-
-==== Caution on Using Iterators When Child Changes
-
-Visitors often replace one node with another node; V3Width and V3Const are
-major examples.  A visitor which is the parent of such a replacement needs
-to be aware that calling iteration may cause the children to change.  For
-example:
-
-   // nodep->lhsp() is 0x1234000
-   iterateAndNextNull(nodep->lhsp());  // and under covers nodep->lhsp() changes
-   // nodep->lhsp() is 0x5678400
-   iterateAndNextNull(nodep->lhsp());
-
-Will work fine, as even if the first iterate causes a new node to take the
-place of the `lhsp()`, that edit will update `nodep->lhsp()` and the second
-call will correctly see the change. Alternatively:
-
-   lp = nodep->lhsp();
-   // nodep->lhsp() is 0x1234000, lp is 0x1234000
-   iterateAndNextNull(lp); **lhsp=NULL;**  // and under covers nodep->lhsp() changes
-   // nodep->lhsp() is 0x5678400, lp is 0x1234000
-   iterateAndNextNull(lp);
-
-This will cause bugs or a core dump, as lp is a dangling pointer.  Thus it
-is advisable to set lhsp=NULL shown in the *'s above to make sure these
-dangles are avoided.  Another alternative used in special cases mostly in
-V3Width is to use acceptSubtreeReturnEdits, which operates on a single node
-and returns the new pointer if any.  Note acceptSubtreeReturnEdits does not
-follow `nextp()` links.
-
-   lp = acceptSubtreeReturnEdits(lp)
-
-=== Identifying Derived Classes
-
-A common requirement is to identify the specific `AstNode` class we are
-dealing with. For example a visitor might not implement separate `visit`
-methods for `AstIf` and `AstGenIf`, but just a single method for the base
-class:
-
-   void visit (AstNodeIf* nodep)
-
-However that method might want to specify additional code if it is called
-for `AstGenIf`. Verilator does this by providing a `VN_IS` method for each
-possible node type, which returns true if the node is of that type (or
-derived from that type).  So our `visit` method could use:
-
-   if (VN_IS(nodep, AstGenIf) {
-     <code specific to AstGenIf>
-   }
-
-Additionally the `VN_CAST` method converts pointers similar to C++
-`dynamic_cast`. This either returns a pointer to the object cast to that
-type (if it is of class `SOMETYPE`, or a derived class of `SOMETYPE`) or
-else NULL.  (However, for true/false tests use `VN_IS` as that is faster.)
-
-== Testing
-
-For an overview of how to write a test see the BUGS section of the
-Verilator primary manual.
-
-It is important to add tests for failures as well as success (for example
-to check that an error message is correctly triggered).
-
-Tests that fail should by convention have the suffix `_bad` in their name,
-and include `fails = 1` in either their `compile` or `execute` step as
-appropriate.
-
-=== Preparing to Run Tests
-
-For all tests to pass you must install the following packages:
-
-* SystemC to compile the SystemC outputs, see http://systemc.org
-
-* Parallel::Forker from CPAN to run tests in parallel, you can install this
-with e.g. "sudo cpan install Parallel::Forker".
-
-* vcddiff to find differences in VCD outputs. See the readme at
-https://github.com/veripool/vcddiff
-
-=== Controlling the Test Driver
-
-Test drivers are written in PERL. All invoke the main test driver script,
-which can provide detailed help on all the features available when writing
-a test driver.
-
-   test_regress/t/driver.pl --help
-
-For convenience, a summary of the most commonly used features is provided
-here. All drivers require a call to `compile` subroutine to compile the
-test. For run-time tests, this is followed by a call to the `execute`
-subroutine. Both of these functions can optionally be provided with a hash
-table as argument specifying additional options.
-
-The test driver assumes by default that the source Verilog file name
-matches the PERL driver name. So a test whose driver is `t/t_mytest.pl`
-will expect a Verilog source file `t/t_mytest.v`. This can be changed
-using the `top_filename` subroutine, for example
-
-   top_filename("t/t_myothertest.v");
-
-By default all tests will run with major simulators (Icarus Verilog, NC,
-VCS, ModelSim, etc) as well as Verilator, to allow results to be
-compared. However if you wish a test only to be used with Verilator, you
-can use the following:
-
-   scenarios(vlt => 1);
-
-Of the many options that can be set through arguments to `compiler` and
-`execute`, the following are particularly useful:
-
-`verilator_flags2`::
-
-A list of flags to be passed to verilator when compiling.
-
-`fails`::
-
-Set to 1 to indicate that the compilation or execution is intended to fail.
-
-For example the following would specify that compilation requires two
-defines and is expected to fail.
-
-   compile (
-      verilator_flags2 => ["-DSMALL_CLOCK -DGATED_COMMENT"],
-      fails => 1,
-      );
-
-=== Regression Testing for Developers
-
-Developers will also want to call ./configure with two extra flags:
-
-`--enable-ccwarn`::
-
-Causes the build to stop on warnings as well as errors. A good way to
-ensure no sloppy code gets added, however it can be painful when it comes
-to testing, since third party code used in the tests (e.g. SystemC) may not
-be warning free.
-
-`--enable-longtests`::
-
-In addition to the standard C, SystemC examples, also run the tests in the
-`test_regress` directory when using _make test_'.  This is disabled by
-default as SystemC installation problems would otherwise falsely indicate a
-Verilator problem.
-
-When enabling the long tests, some additional PERL modules are needed,
-which you can install using cpan.
-
-   cpan install Unix::Processors
-
-There are some traps to avoid when running regression tests
-
-* When checking the MANIFEST, the test will barf on unexpected code in the
-Verilator tree. So make sure to keep any such code outside the tree.
-
-* Not all Linux systems install Perldoc by default. This is needed for the
-`--help_' option to Verilator, and also for regression testing. This can be
-installed using cpan:
-+
-   cpan install Pod::Perldoc
-+
-Many Linux systems also offer a standard package for this. Red
-Hat/Fedora/Centos offer _perl-Pod-Perldoc_', while Debian/Ubuntu/Linux Mint
-offer `perl-doc'.
-
-* Running regression may exhaust resources on some Linux systems,
-particularly file handles and user processes. Increase these to
-respectively 16,384 and 4,096. The method of doing this is system
-dependent, but on Fedora Linux it would require editing the
-`/etc/security/limits.conf` file as root.
-
-=== Continuous Integration
-
-Verilator has a https://travis-ci.com/verilator/verilator[Travis CI environment]
-which automatically tests the master branch for test failures on new commits. It
-also runs a daily cron job to validate all of the tests against different OS and
-compiler versions.
-
-Developers can connect Travis CI to their GitHub account so that the CI
-environment can check their branches too by doing the following:
-
-* Go to https://github.com/marketplace/travis-ci and follow the prompts
-
-* Only the Open Source (FREE) version of Travis CI is required
-
-* Under a Travis CI project click More options > Settings in order to set up a
-cron job on a particular branch
-
-=== Fuzzing
-
-There are scripts included to facilitate fuzzing of Verilator.  These have
-been successfully used to find a number of bugs in the frontend.
-
-The scripts are based on using http://lcamtuf.coredump.cx/afl/[American fuzzy lop]
-on a Debian-like system.
-
-To get started, cd to "nodist/fuzzer/" and run "./all".  A sudo password
-may be required to setup the system for fuzzing.
-
-== Debugging
-
-=== --debug
-
-When you run with `--debug` there are two primary output file types placed
-into the obj_dir, .tree and .dot files.
-
-=== .dot Output
-
-Dot files are dumps of internal graphs in
-https://www.graphviz.org[Graphviz] dot format.  When a dot file is dumped,
-Verilator will also print a line on stdout that can be used to format the
-output, for example:
-
-   dot -Tps -o ~/a.ps obj_dir/Vtop_foo.dot
-
-You can then print a.ps.  You may prefer gif format, which doesn't get
-scaled so can be more useful with large graphs.
-
-For dynamic graph viewing consider
-http://zvtm.sourceforge.net/zgrviewer.html[ZGRViewer].  If you know of
-better viewers let us know; ZGRViewer isn't great for large graphs.
-
-=== .tree Output
-
-Tree files are dumps of the AST Tree and are produced between every major
-algorithmic stage.  An example:
-
-     NETLIST 0x90fb00 <e1> {a0}
-    1: MODULE 0x912b20 <e8822> {a8}  top  L2 [P]
-   *1:2: VAR 0x91a780 <e74#> {a22} @dt=0xa2e640(w32)  out_wide [O] WIRE
-    1:2:1: BASICDTYPE 0xa2e640 <e2149> {e24} @dt=this(sw32)  integer kwd=integer range=[31:0]
-
-The following summarizes the above example dump, with more detail on each
-field in the section below.
-
-[cols="20%,80%"]
-|===
-
-|`1:2:` | indicates the hierarchy of the `VAR` is the `op2p` pointer under
-the `MODULE`, which in turn is the `op1p` pointer under the `NETLIST`
-
-|`VAR` | is the AstNodeType.
-
-| `0x91a780` | is the address of this node.
-
-| `<e74>` | means the 74th edit to the netlist was the last modification to
-this node.
-
-| `{a22}` | indicates this node is related to line 22 in the source filename
-"a", where "a" is the first file read, "z" the 26th, and "aa" the 27th.
-
-| `@dt=0x...` | indicates the address of the data type this node contains.
-
-| `w32` | indicates the width is 32 bits.
-
-| `out_wide` | is the name of the node, in this case the name of the variable.
-
-| `[O]` |  are flags which vary with the type of node, in this case it means the
-variable is an output.
-
-|===
-
-In more detail the following fields are dumped common to all nodes. They
-are produced by the `AstNode::dump()` method:
-
-Tree Hierarchy::
-
-The dump lines begin with numbers and colons to indicate the child node
-hierarchy.  As noted above, `AstNode` has lists of items at the same level
-in the AST, connected by the `nextp()` and `prevp()` pointers. These appear
-as nodes at the same level. For example after inlining:
-
-    NETLIST 0x929c1c8 <e1> {a0} w0
-   1: MODULE 0x92bac80 <e3144> {e14} w0  TOP_t  L1 [P]
-   1:1: CELLINLINE 0x92bab18 <e3686#> {e14} w0  v -> t
-   1:1: CELLINLINE 0x92bc1d8 <e3688#> {e24} w0  v__DOT__i_test_gen -> test_gen
-   ...
-   1: MODULE 0x92b9bb0 <e503> {e47} w0  test_gen  L3
-   ...
-
-AstNode type::
-
-The textual name of this node AST type (always in capitals). Many of these
-correspond directly to Verilog entities (for example `MODULE` and
-`TASK`), but others are internal to Verilator (for example `NETLIST` and
-`BASICDTYPE`).
-
-Address of the node::
-
-A hexadecimal address of the node in memory. Useful for examining with the
-debugger.
-
-Last edit number::
-
-Of the form `<ennnn>` or `<ennnn#>` , where `nnnn` is the number
-of the last edit to modify this node. The trailing `#` indicates the node
-has been edited since the last tree dump (which typically means in the last
-refinement or optimization pass). GDB can watch for this, see << /Debugging >>.
-
-Source file and line::
-
-Of the form `{xxnnnn}`, where C{xx} is the filename letter (or
-letters) and `nnnn` is the line number within that file. The first file is
-`a`, the 26th is `z`, the 27th is `aa` and so on.
-
-User pointers::
-
-Shows the value of the node's user1p...user5p, if non-NULL.
-
-Data type::
-
-Many nodes have an explicit data type.  "@dt=0x..." indicates the address
-of the data type (AstNodeDType) this node uses.
-+
-If a data type is present and is numeric, it then prints the width of the
-item. This field is a sequence of flag characters and width data as follows:
-+
-* `s` if the node is signed.
-* `d` if the node is a double (i.e a floating point entity).
-* `w` always present, indicating this is the width field.
-* `u` if the node is unsized.
-* `/nnnn` if the node is unsized, where `nnnn` is the minimum width.
-
-Name of the entity represented by the node if it exists::
-
-For example for a `VAR` it is the name of the variable.
-
-Many nodes follow these fields with additional node specific
-information. Thus the `VARREF` node will print either `[LV]` or `[RV]`
-to indicate a left value or right value, followed by the node of the
-variable being referred to. For example:
-
-   1:2:1:1: VARREF 0x92c2598 <e509> {e24} w0  clk [RV] <- VAR 0x92a2e90 <e79> {e18} w0  clk [I] INPUT
-
-In general, examine the `dump()` method in `V3AstNodes.cpp` of the node
-type in question to determine additional fields that may be printed.
-
-The `MODULE` has a list of `CELLINLINE` nodes referred to by its
-`op1p()` pointer, connected by `nextp()` and `prevp()` pointers.
-
-Similarly the `NETLIST` has a list of modules referred to by its `op1p()`
-pointer.
-
-=== Debugging with GDB
-
-The test_regress/driver.pl script accepts `--debug --gdb` to start
-Verilator under gdb and break when an error is hit or the program is about
-to exit.  You can also use `--debug --gdbbt` to just backtrace and then
-exit gdb. To debug the Verilated executable, use `--gdbsim`.
-
-If you wish to start Verilator under GDB (or another debugger), then you
-can use `--debug` and look at the underlying invocation of
-`verilator_dbg`. For example
-
-   t/t_alw_dly.pl --debug
-
-shows it invokes the command:
-
-   ../verilator_bin_dbg --prefix Vt_alw_dly --x-assign unique --debug
-     -cc -Mdir obj_dir/t_alw_dly --debug-check -f input.vc t/t_alw_dly.v
-
-Start GDB, then `start` with the remaining arguments.
-
-   gdb ../verilator_bin_dbg
-   ...
-   (gdb) start --prefix Vt_alw_dly --x-assign unique --debug -cc -Mdir
-             obj_dir/t_alw_dly --debug-check  -f input.vc t/t_alw_dly.v
-             > obj_dir/t_alw_dly/vlt_compile.log
-   ...
-   Temporary breakpoint 1, main (argc=13, argv=0xbfffefa4, env=0xbfffefdc)
-       at ../Verilator.cpp:615
-   615         ios::sync_with_stdio();
-   (gdb)
-
-You can then continue execution with breakpoints as required.
-
-To break at a specific edit number which changed a node (presumably to find
-what made a <e####> line in the tree dumps):
-
-   watch AstNode::s_editCntGbl==####
-
-Then, when the watch fires, to break at every following change to that node:
-
-   watch m_editCount
-
-To print a node:
-
-   pn nodep
-   # or: call nodep->dumpGdb()  # aliased to "pn" in src/.gdbinit
-   pnt nodep
-   # or: call nodep->dumpTreeGdb()  # aliased to "pnt" in src/.gdbinit
-
-When GDB halts, it is useful to understand that the backtrace will commonly
-show the iterator functions between each invocation of `visit` in the
-backtrace. You will typically see a frame sequence something like
-
-   ...
-   visit()
-   iterateChildren()
-   iterateAndNext()
-   accept()
-   visit()
-   ...
-
-== Adding a New Feature
-
-Generally what would you do to add a new feature?
-
-. File an issue (if there isn't already) so others know what you're working on.
-
-. Make a testcase in the test_regress/t/t_EXAMPLE format, see << /TESTING >>.
-
-. If grammar changes are needed, look at the git version of VerilogPerl's
-src/VParseGrammar.y, as this grammar supports the full SystemVerilog
-language and has a lot of back-and-forth with Verilator's grammar.  Copy
-the appropriate rules to src/verilog.y and modify the productions.
-
-. If a new Ast type is needed, add it to V3AstNodes.h. Follow the convention
-described above about the AstNode type hierarchy.
-
-. Now you can run "test_regress/t/t_{new testcase}.pl --debug" and it'll
-probably fail but you'll see a test_regress/obj_dir/t_{newtestcase}/*.tree
-file which you can examine to see if the parsing worked. See also the
-sections above on debugging.
-
-. Modify the later visitor functions to process the new feature as needed.
-
-=== Adding a New Pass
-
-For more substantial changes you may need to add a new pass. The simplest
-way to do this is to copy the `.cpp` and `.h` files from an existing
-pass. You'll need to add a call into your pass from the `process()`
-function in `src/verilator.cpp`.
-
-To get your pass to build you'll need to add its binary filename to the
-list in `src/Makefile_obj.in` and reconfigure.
-
-== Distribution
-
-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.

docs/xml.adoc

@@ -1,65 +0,0 @@
-= 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 is 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.

docs/xml.rst

@@ -0,0 +1,81 @@
+|Logo|
+
+===========================
+Verilator XML Output Format
+===========================
+
+Introduction
+============
+
+This document describes Verilator's XML output. For more general
+information please see `verilator.org <https://verilator.org>`__.
+
+
+General
+=======
+
+Verilator's XML output is enabled with the ``--xml-only`` flag. It contains
+limited information about the elaborated design including files, modules,
+instance hierarchy, logic and data types. There is no formal schema since
+part of the structure of the XML document matches the compiled code which
+would require the schema to describe legal SystemVerilog structure. The
+intended usage is to enable other downstream tools to take advantage of
+Verilator's parser.
+
+
+Structure
+=========
+
+The XML document consists of 4 sections within the top level
+``verilator_xml`` element:
+
+``<files>``\ ... ``</files>``
+   This section contains a list of all design files read, including the
+   built-in constructs and the command line as their own entries. Each
+   ``<file>`` has an attribute ``id`` which is a short ASCII string
+   unique to that file. Other elements' ``loc`` attributes use this id
+   to refer to a particular file.
+
+``<module_files>``\ ... ``</module_files>``
+   All files containing Verilog module definitions are listed in this
+   section. This element's contents is a subset of the ``<files>``
+   element's contents.
+
+``<cells>``\ ... ``</cells>``
+   The cells section of the XML document contains the design instance
+   hierarchy. Each instance is represented with the ``<cell>`` element
+   with the following attributes:
+
+   -  ``fl`` (deprecated): The file id and line number where the module
+      was instanced. Use ``loc`` instead.
+
+   -  ``loc``: The file id, first line number, last line number, first
+      column number and last column number of the identifier where the
+      module was instanced, separated by commas.
+
+   -  ``name``: The instance name.
+
+   -  ``submodname``: The module name uniquified with particular
+      parameter values (if any).
+
+   -  ``hier``: The full hierarchy path.
+
+``<netlist>``\ ... ``</netlist>``
+   The netlist section contains a number of
+   ``<module>``\ ... ``</module>`` elements, each describing the
+   contents of that module, and a single ``<typetable>``\ ...
+   ``</typetable>`` element which lists all used types used within the
+   modules. Each type has a numeric ``id`` attribute that is referred to
+   by elements in the ``<module>`` elements using the ``dtype_id``
+   attribute.
+
+.. __distribution:
+
+Distribution
+============
+
+Copyright 2020-2021 by Wilson Snyder. Verilator is free software; you can
+redistribute it and/or modify it under the terms of either the GNU Lesser
+General Public License Version 3 or the Perl Artistic License Version 2.0.
+
+.. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png

examples/cmake_hello_c/CMakeLists.txt

@@ -5,10 +5,9 @@
 # This is an example cmake script to build a verilog to systemc project
 # using cmake and verilator.
 #
-# 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 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
 #
 ######################################################################
 

examples/cmake_hello_c/Makefile

@@ -6,10 +6,9 @@
 # This makefile is here for testing the examples and should
 # generally not be added to a CMake project.
 #
-# 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 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
 #
 ######################################################################
 
@@ -50,12 +49,12 @@ run:
 	@echo "-- Verilator CMake hello world example"
 
 	@echo
-	@echo "-- CMake ----------------"
+	@echo "-- VERILATE ----------------"
 	mkdir -p build && cd build && cmake ..
 
 	@echo
-	@echo "-- COMPILE -----------------"
-	cmake --build build
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
 
 	@echo
 	@echo "-- RUN ---------------------"

examples/cmake_hello_sc/CMakeLists.txt

@@ -5,10 +5,9 @@
 # This is an example cmake script to build a verilog to SystemC project
 # using CMake and Verilator.
 #
-# 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 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
 #
 ######################################################################
 

examples/cmake_hello_sc/Makefile

@@ -6,10 +6,9 @@
 # This makefile is here for testing the examples and should
 # generally not be added to a CMake project.
 #
-# 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 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
 #
 ######################################################################
 
@@ -86,12 +85,12 @@ run:
 	@echo "-- Verilator CMake SystemC hello-world simple example"
 
 	@echo
-	@echo "-- CMake ----------------"
+	@echo "-- VERILATE ----------------"
 	mkdir -p build && cd build && cmake ..
 
 	@echo
-	@echo "-- COMPILE -----------------"
-	cmake --build build
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
 
 	@echo
 	@echo "-- RUN ---------------------"

examples/cmake_protect_lib/CMakeLists.txt

@@ -5,10 +5,9 @@
 # This is an example cmake script to build a verilog to systemc project
 # using cmake and verilator.
 #
-# 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 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
 #
 ######################################################################
 

examples/cmake_protect_lib/Makefile

@@ -6,10 +6,9 @@
 # This makefile is here for testing the examples and should
 # generally not be added to a CMake project.
 #
-# 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 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
 #
 ######################################################################
 
@@ -50,12 +49,12 @@ run:
 	@echo "-- Verilator CMake protect_lib example"
 
 	@echo
-	@echo "-- CMake ----------------"
+	@echo "-- VERILATE ----------------"
 	mkdir -p build && cd build && cmake ..
 
 	@echo
-	@echo "-- COMPILE -----------------"
-	cmake --build build
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
 
 	@echo
 	@echo "-- RUN ---------------------"

examples/cmake_tracing_c/CMakeLists.txt

@@ -5,10 +5,9 @@
 # This is an example cmake script to build a verilog to systemc project
 # using cmake and verilator.
 #
-# 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 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
 #
 ######################################################################
 
@@ -34,5 +33,5 @@ add_executable(example ../make_tracing_c/sim_main.cpp)
 # Add the Verilated circuit to the target
 verilate(example COVERAGE TRACE
   INCLUDE_DIRS "../make_tracing_c"
-  VERILATOR_ARGS -f ../make_tracing_c/input.vc -O2 -x-assign 0
+  VERILATOR_ARGS -f ../make_tracing_c/input.vc -Os -x-assign 0
   SOURCES ../make_tracing_c/top.v)

examples/cmake_tracing_c/Makefile

@@ -6,10 +6,9 @@
 # This makefile is here for testing the examples and should
 # generally not be added to a CMake project.
 #
-# 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 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
 #
 ######################################################################
 
@@ -50,12 +49,12 @@ run:
 	@echo "-- Verilator CMake tracing example"
 
 	@echo
-	@echo "-- CMake ----------------"
+	@echo "-- VERILATE ----------------"
 	mkdir -p build && cd build && cmake ..
 
 	@echo
-	@echo "-- COMPILE -----------------"
-	cmake --build build
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
 
 	@echo
 	@echo "-- RUN ---------------------"

examples/cmake_tracing_sc/CMakeLists.txt

@@ -5,10 +5,9 @@
 # This is an example cmake script to build a verilog to SystemC project
 # using CMake and Verilator.
 #
-# 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 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
 #
 ######################################################################
 
@@ -41,7 +40,7 @@ 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 -O2 -x-assign 0
+  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

@@ -6,10 +6,9 @@
 # This makefile is here for testing the examples and should
 # generally not be added to a CMake project.
 #
-# 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 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
 #
 ######################################################################
 
@@ -86,12 +85,12 @@ run:
 	@echo "-- Verilator CMake SystemC tracing example"
 
 	@echo
-	@echo "-- CMake ----------------"
+	@echo "-- VERILATE ----------------"
 	mkdir -p build && cd build && cmake ..
 
 	@echo
-	@echo "-- COMPILE -----------------"
-	cmake --build build
+	@echo "-- BUILD -------------------"
+	cmake --build build -j
 
 	@echo
 	@echo "-- RUN ---------------------"

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-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 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
@@ -35,10 +34,8 @@ 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 --------------------"

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;
@@ -36,6 +37,6 @@ int main(int argc, char** argv, char** env) {
     // Destroy model
     delete top;
 
-    // Fin
-    exit(0);
+    // Return good completion status
+    return 0;
 }

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-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 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
@@ -44,10 +43,8 @@ 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 --------------------"

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,30 +23,23 @@ 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");
+    Vtop* top = new Vtop{"top"};
 
     // Initialize SC model
-#if (SYSTEMC_VERSION>=20070314)
-    sc_start(1,SC_NS);
-#else
-    sc_start(1);
-#endif
+    sc_start(1, SC_NS);
 
     // Simulate until $finish
     while (!Verilated::gotFinish()) {
-#if (SYSTEMC_VERSION>=20070314)
-        sc_start(1,SC_NS);
-#else
-        sc_start(1);
-#endif
+        // Simulate 1ns
+        sc_start(1, SC_NS);
     }
 
     // Final model cleanup
     top->final();
 
-    // Fin
+    // Return good completion status
     return 0;
 }

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/Makefile

@@ -5,10 +5,9 @@
 # This calls the object directory makefiles.  That allows the objects to
 # be placed in the "current directory" which simplifies the Makefile.
 #
-# Copyright 2019 by Todd Strader. 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
@@ -34,7 +33,7 @@ VERILATOR_FLAGS =
 # Generate C++
 VERILATOR_FLAGS += -cc
 # 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
@@ -69,7 +68,7 @@ run:
 	@echo " library (libverilated_secret.a) generated from the previous"
 	@echo " step"
 	@echo "---------------------------------------------------------------"
-	$(VERILATOR) $(TOP_VERILATOR_FLAGS) --exe -LDFLAGS '-L../obj_dir_secret -lverilated_secret -static' top.v obj_dir_secret/verilated_secret.sv sim_main.cpp
+	$(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 --------------------------------------"

examples/make_protect_lib/secret_impl.v

@@ -1,20 +1,23 @@
 // DESCRIPTION: Verilator: --protect-lib example secret module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2019 by Todd Strader.
+// 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;
+module secret_impl
+  (
+   input [31:0]        a,
+   input [31:0]        b,
+   output logic [31:0] x,
+   input               clk);
 
-   initial $display("%m: initialized");
+   logic [31:0]        accum_q = 0;
+   logic [31:0]        secret_value = 9;
+
+   initial $display("[%0t] %m: initialized", $time);
 
    always @(posedge clk) begin
       accum_q <= accum_q + a;

examples/make_protect_lib/sim_main.cpp

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: --protect-lib example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2019 by Todd Strader.
+// 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
@@ -12,30 +13,27 @@
 #include "Vtop.h"
 
 #if VM_TRACE
-# include <verilated_vcd_c.h>
+#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 (0 && argc && argv && env) {}
+    if (false && argc && argv && env) {}
 
-    Verilated::debug(0);
-    Verilated::randReset(2);
-    Verilated::commandArgs(argc, argv);
+    // Construct context to hold simulation time, etc
+    VerilatedContext* contextp = new VerilatedContext;
+    contextp->debug(0);
+    contextp->randReset(2);
+    contextp->commandArgs(argc, argv);
 
     // Construct the Verilated model, including the secret module
-    Vtop* top = new Vtop;
+    Vtop* top = new Vtop{contextp};
 
 #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);
+    VerilatedVcdC* tfp = nullptr;
+    const char* flag = contextp->commandArgsPlusMatch("trace");
+    if (flag && 0 == strcmp(flag, "+trace")) {
+        contextp->traceEverOn(true);
         VL_PRINTF("Enabling waves into logs/vlt_dump.vcd...\n");
         tfp = new VerilatedVcdC;
         top->trace(tfp, 99);
@@ -47,12 +45,12 @@ int main(int argc, char** argv, char** env) {
     top->clk = 0;
 
     // Simulate until $finish
-    while (!Verilated::gotFinish()) {
-        main_time++;
+    while (!contextp->gotFinish()) {
+        contextp->timeInc(1);
         top->clk = ~top->clk & 0x1;
         top->eval();
 #if VM_TRACE
-        if (tfp) tfp->dump(main_time);
+        if (tfp) tfp->dump(contextp->time());
 #endif
     }
 
@@ -61,12 +59,19 @@ int main(int argc, char** argv, char** env) {
 
     // Close trace if opened
 #if VM_TRACE
-    if (tfp) { tfp->close(); tfp = NULL; }
+    if (tfp) {
+        tfp->close();
+        tfp = nullptr;
+    }
 #endif
 
     // Destroy model
-    delete top; top = NULL;
+    delete top;
+    top = nullptr;
+    delete contextp;
+    contextp = nullptr;
 
-    // Fin
-    exit(0);
+    // Return good completion status
+    // Don't use exit() or destructor won't get called
+    return 0;
 }

examples/make_protect_lib/top.v

@@ -1,7 +1,8 @@
 // DESCRIPTION: Verilator: --protect-lib example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2019 by Todd Strader.
+// 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);

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-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 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
@@ -67,11 +66,13 @@ run:
 	$(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 ---------------------"

examples/make_tracing_c/Makefile_obj

@@ -5,10 +5,9 @@
 #
 # This is executed in the object directory, and called by ../Makefile
 #
-# 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 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,66 +1,59 @@
 // 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
 //======================================================================
 
+// For std::unique_ptr
+#include <memory>
+
 // Include common routines
 #include <verilated.h>
 
 // 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
-double sc_time_stamp() {
-    return main_time;  // Note does conversion to real, to match SystemC
-}
-
 int main(int argc, char** argv, char** env) {
     // This is a more complicated example, please also see the simpler examples/make_hello_c.
 
     // Prevent unused variable warnings
-    if (0 && argc && argv && env) {}
+    if (false && argc && argv && env) {}
+
+    // Create logs/ directory in case we have traces to put under it
+    Verilated::mkdir("logs");
+
+    // Construct a VerilatedContext to hold simulation time, etc.
+    // Multiple modules (made later below with Vtop) may share the same
+    // context to share time, or modules may have different contexts if
+    // they should be independent from each other.
+
+    // Using unique_ptr is similar to
+    // "VerilatedContext* contextp = new VerilatedContext" then deleting at end.
+    const std::unique_ptr<VerilatedContext> contextp{new VerilatedContext};
 
     // Set debug level, 0 is off, 9 is highest presently used
-    // May be overridden by commandArgs
-    Verilated::debug(0);
+    // May be overridden by commandArgs argument parsing
+    contextp->debug(0);
 
     // Randomization reset policy
-    // May be overridden by commandArgs
-    Verilated::randReset(2);
+    // May be overridden by commandArgs argument parsing
+    contextp->randReset(2);
+
+    // Verilator must compute traced signals
+    contextp->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);
+    contextp->commandArgs(argc, argv);
 
-    // 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
+    // Construct the Verilated model, from Vtop.h generated from Verilating "top.v".
+    // Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end.
+    // "TOP" will be the hierarchical name of the module.
+    const std::unique_ptr<Vtop> top{new Vtop{contextp.get(), "TOP"}};
 
-#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
+    // Set Vtop's input signals
     top->reset_l = !0;
-    top->fastclk = 0;
     top->clk = 0;
     top->in_small = 1;
     top->in_quad = 0x1234;
@@ -69,58 +62,60 @@ int main(int argc, char** argv, char** env) {
     top->in_wide[2] = 0x3;
 
     // Simulate until $finish
-    while (!Verilated::gotFinish()) {
-        main_time++;  // Time passes...
+    while (!contextp->gotFinish()) {
+        // Historical note, before Verilator 4.200 Verilated::gotFinish()
+        // was used above in place of contextp->gotFinish().
+        // Most of the contextp-> calls can use Verilated:: calls instead;
+        // the Verilated:: versions simply assume there's a single context
+        // being used (per thread).  It's faster and clearer to use the
+        // newer contextp-> versions.
 
-        // 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
-        }
+        contextp->timeInc(1);  // 1 timeprecision period passes...
+        // Historical note, before Verilator 4.200 a sc_time_stamp()
+        // function was required instead of using timeInc.  Once timeInc()
+        // is called (with non-zero), the Verilated libraries assume the
+        // new API, and sc_time_stamp() will no longer work.
 
-        // Assign some other inputs
-        top->in_quad += 0x12;
+        // Toggle a fast (time/2 period) clock
+        top->clk = !top->clk;
+
+        // Toggle control signals on an edge that doesn't correspond
+        // to where the controls are sampled; in this example we do
+        // this only on a negedge of clk, because we know
+        // reset is not sampled there.
+        if (!top->clk) {
+            if (contextp->time() > 1 && contextp->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. See the manual.)
         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",
+                  contextp->time(), top->clk, top->reset_l, top->in_quad, top->out_quad,
+                  top->out_wide[2], top->out_wide[1], top->out_wide[0]);
     }
 
     // Final model cleanup
     top->final();
 
-    // Close trace if opened
-#if VM_TRACE
-    if (tfp) { tfp->close(); tfp = NULL; }
-#endif
-
-    //  Coverage analysis (since test passed)
+    // Coverage analysis (calling write only after the test is known to pass)
 #if VM_COVERAGE
     Verilated::mkdir("logs");
-    VerilatedCov::write("logs/coverage.dat");
+    contextp->coveragep()->write("logs/coverage.dat");
 #endif
 
-    // Destroy model
-    delete top; top = NULL;
-
-    // Fin
-    exit(0);
+    // Return good completion status
+    // Don't use exit() or destructor won't get called
+    return 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,7 +1,8 @@
 // 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
@@ -10,16 +11,15 @@
 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-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 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
@@ -76,10 +75,12 @@ run:
 
 	@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
+# 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 ---------------------"

examples/make_tracing_sc/Makefile_obj

@@ -5,10 +5,9 @@
 #
 # This is executed in the object directory, and called by ../Makefile
 #
-# 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 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,10 +1,14 @@
 // -*- 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
 //======================================================================
 
+// For std::unique_ptr
+#include <memory>
+
 // SystemC global header
 #include <systemc.h>
 
@@ -23,16 +27,24 @@ int sc_main(int argc, char* argv[]) {
     // This is a more complicated example, please also see the simpler examples/make_hello_c.
 
     // Prevent unused variable warnings
-    if (0 && argc && argv) {}
+    if (false && argc && argv) {}
+
+    // Create logs/ directory in case we have traces to put under it
+    Verilated::mkdir("logs");
 
     // Set debug level, 0 is off, 9 is highest presently used
-    // May be overridden by commandArgs
+    // May be overridden by commandArgs argument parsing
     Verilated::debug(0);
 
     // Randomization reset policy
-    // May be overridden by commandArgs
+    // May be overridden by commandArgs argument parsing
     Verilated::randReset(2);
 
+#if VM_TRACE
+    // Before any evaluation, need to know to calculate those signals only used for tracing
+    Verilated::traceEverOn(true);
+#endif
+
     // 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);
@@ -40,63 +52,44 @@ int sc_main(int argc, char* argv[]) {
     // General logfile
     ios::sync_with_stdio();
 
-    // Defaults time
-#if (SYSTEMC_VERSION>20011000)
-#else
-    sc_time dut(1.0, sc_ns);
-    sc_set_default_time_unit(dut);
-#endif
-
     // Define clocks
-#if (SYSTEMC_VERSION>=20070314)
-    sc_clock clk     ("clk",    10,SC_NS, 0.5, 3,SC_NS, true);
-    sc_clock fastclk ("fastclk", 2,SC_NS, 0.5, 2,SC_NS, true);
-#else
-    sc_clock clk     ("clk",    10, 0.5, 3, true);
-    sc_clock fastclk ("fastclk", 2, 0.5, 2, true);
-#endif
+    sc_clock clk{"clk", 10, SC_NS, 0.5, 3, SC_NS, true};
+    sc_clock fastclk{"fastclk", 2, SC_NS, 0.5, 2, SC_NS, true};
 
     // Define interconnect
     sc_signal<bool> reset_l;
     sc_signal<vluint32_t> in_small;
     sc_signal<vluint64_t> in_quad;
-    sc_signal<sc_bv<70> > in_wide;
+    sc_signal<sc_bv<70>> in_wide;
     sc_signal<vluint32_t> out_small;
     sc_signal<vluint64_t> out_quad;
-    sc_signal<sc_bv<70> > out_wide;
+    sc_signal<sc_bv<70>> out_wide;
 
     // Construct the Verilated model, from inside Vtop.h
-    Vtop* top = new Vtop("top");
-    // Attach signals to the model
-    top->clk       (clk);
-    top->fastclk   (fastclk);
-    top->reset_l   (reset_l);
-    top->in_small  (in_small);
-    top->in_quad   (in_quad);
-    top->in_wide   (in_wide);
-    top->out_small (out_small);
-    top->out_quad  (out_quad);
-    top->out_wide  (out_wide);
+    // Using unique_ptr is similar to "Vtop* top = new Vtop" then deleting at end
+    const std::unique_ptr<Vtop> top{new Vtop{"top"}};
 
-#if VM_TRACE
-    // Before any evaluation, need to know to calculate those signals only used for tracing
-    Verilated::traceEverOn(true);
-#endif
+    // Attach Vtop's signals to this upper 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);
 
     // You must do one evaluation before enabling waves, in order to allow
     // SystemC to interconnect everything for testing.
-#if (SYSTEMC_VERSION>=20070314)
-    sc_start(1,SC_NS);
-#else
-    sc_start(1);
-#endif
+    sc_start(1, SC_NS);
 
 #if VM_TRACE
     // If verilator was invoked with --trace argument,
     // and if at run time passed the +trace argument, turn on tracing
-    VerilatedVcdSc* tfp = NULL;
+    VerilatedVcdSc* tfp = nullptr;
     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,18 +107,14 @@ 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);
-#else
-        sc_start(1);
-#endif
+        sc_start(1, SC_NS);
     }
 
     // Final model cleanup
@@ -133,18 +122,18 @@ 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 = nullptr;
+    }
 #endif
 
-    //  Coverage analysis (since test passed)
+    // Coverage analysis (calling write only after the test is known to pass)
 #if VM_COVERAGE
     Verilated::mkdir("logs");
     VerilatedCov::write("logs/coverage.dat");
 #endif
 
-    // Destroy model
-    delete top; top = NULL;
-
-    // Fin
+    // Return good completion status
     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,7 +1,8 @@
 // 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
@@ -10,16 +11,16 @@
 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/Makefile

@@ -2,10 +2,9 @@
 #
 # DESCRIPTION: Verilator Example: XML tests
 #
-# 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 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
 #
 ######################################################################
 
@@ -23,9 +22,9 @@ VERILATOR = $(VERILATOR_ROOT)/bin/verilator
 endif
 
 DOT = dot
-PYTHON = python3
+PYTHON3 = python3
 
-PYTHON_VERSION := $(shell ${PYTHON} --version 2>&1)
+PYTHON_VERSION := $(shell ${PYTHON3} --version 2>&1)
 PYTHON_VERSION_FULL := $(wordlist 2,4,$(subst ., ,${PYTHON_VERSION}))
 PYTHON_VERSION_MAJOR := $(word 1,${PYTHON_VERSION_FULL})
 PYTHON_VERSION_MINOR := $(word 2,${PYTHON_VERSION_FULL})
@@ -46,13 +45,13 @@ test: \
 
 test-vl_file_copy:
 	@echo "-- vl_file_copy example"
-	$(PYTHON) vl_file_copy -odir copied top.v
+	$(PYTHON3) vl_file_copy -odir copied top.v
 	@cmp copied/top.v top.v
 	@cmp copied/sub.v sub.v
 
 test-vl_hier_graph:
 	@echo "-- vl_hier_graph example"
-	$(PYTHON) vl_hier_graph -o graph.dot top.v
+	$(PYTHON3) vl_hier_graph -o graph.dot top.v
 	@echo "Manually run: " $(DOT) -Tpdf -o graph.pdf graph.dot
 
 ######################################################################

examples/xml_py/sub.v

@@ -1,13 +1,14 @@
 // DESCRIPTION: Verilator: Verilog Test module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2019 by Wilson Snyder.
+// 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,
+    input  TYPE_t in,
     output TYPE_t out
     );
 

examples/xml_py/top.v

@@ -1,21 +1,22 @@
 // DESCRIPTION: Verilator: Verilog example module
 //
-// This file ONLY is placed into the Public Domain, for any use,
-// without warranty, 2019 by Wilson Snyder.
+// 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,
+   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
    );
 
    sub #(.TYPE_t(logic [1:0])) sub_small

examples/xml_py/vl_file_copy

@@ -1,35 +1,41 @@
 #!/usr/bin/env python3
 # -*- Python -*- See copyright, etc below
+# pylint: disable=C0114,C0115,R0903
 ######################################################################
 
 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
+# 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
+    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)
+        vargs = [
+            '--xml-output',
+            xml_temp.name,
+            '--bbox-sys',  # Parse some stuff can't translate
+            '--bbox-unsup',
+            '--prefix vlxml'
+        ]  # So we know name of .xml output
+        vargs += verilator_args
+        self.run_verilator(vargs)
         self.tree = ET.parse(xml_temp.name)
 
         os.makedirs(output_dir, 0o777, True)
@@ -44,27 +50,29 @@ class VlFileCopy:
                     print("\tcp %s %s" % (filename, output_dir))
                 copy2(filename, output_dir)
 
-    def run_verilator(self, args):
+    def run_verilator(self, vargs):
         """Run Verilator command, check errors"""
         if os.getenv("VERILATOR_ROOT"):
             command = os.getenv("VERILATOR_ROOT") + "/bin/verilator"
         else:
             command = "verilator"
-        command += ' ' + ' '.join(args)
+        command += ' ' + ' '.join(vargs)
         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")
+            raise Exception("Command failed running Verilator with '" +
+                            command + "', stopped")
+
 
 #######################################################################
 
-if __name__=='__main__':
+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
+        """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.
 
@@ -72,8 +80,7 @@ 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.:
+        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
@@ -84,29 +91,35 @@ Example usage:
   -v <filename>              Verilog library
   -y <dir>                   Directory to search for modules
 
-This file ONLY is placed into the Public Domain, for any use, without
-warranty, 2019 by Wilson Snyder."""
-    )
-    parser.add_argument('-debug', '--debug',
-                        action='store_const', const=9,
+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,
+    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.")
+    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)
+    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:
+# 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

@@ -1,37 +1,40 @@
 #!/usr/bin/env python3
 # -*- Python -*- See copyright, etc below
+# pylint: disable=C0103,C0114,C0115,C0115,C0116,R0914
 ######################################################################
 
 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
+# 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
+    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)
+        vargs = [
+            '--xml-output',
+            xml_temp.name,
+            '--bbox-sys',  # Parse some stuff can't translate
+            '--bbox-unsup',
+            '--prefix vlxml'
+        ]  # So we know name of .xml output
+        vargs += verilator_args
+        self.run_verilator(vargs)
         self.tree = ET.parse(xml_temp.name)
 
         with open(output_filename, "w") as fh:
@@ -39,7 +42,9 @@ class VlHierGraph:
             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(
+                "  node [fontsize=8 shape=\"box\" margin=0.01 width=0 height=0]"
+            )
             fh.write("  edge [fontsize=6]")
             # Find cells
             root = self.tree.getroot()
@@ -48,8 +53,7 @@ class VlHierGraph:
                 # 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))
+                fh.write("  n%d [label=\"%s\"" % (mod_number, mod_name))
                 if module.get('topModule'):
                     fh.write(" color=\"red\" rank=1")
                 fh.write("];\n")
@@ -58,46 +62,47 @@ class VlHierGraph:
                     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%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:
+        if name not 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):
+    def run_verilator(self, vargs):
         """Run Verilator command, check errors"""
         if os.getenv("VERILATOR_ROOT"):
             command = os.getenv("VERILATOR_ROOT") + "/bin/verilator"
         else:
             command = "verilator"
-        command += ' ' + ' '.join(args)
+        command += ' ' + ' '.join(vargs)
         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")
+            raise Exception("Command failed running Verilator with '" +
+                            command + "', stopped")
+
 
 #######################################################################
 
-if __name__=='__main__':
+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
+        """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.:
+        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
@@ -108,29 +113,37 @@ Example usage:
   -v <filename>              Verilog library
   -y <dir>                   Directory to search for modules
 
-This file ONLY is placed into the Public Domain, for any use, without
-warranty, 2019 by Wilson Snyder."""
-    )
-    parser.add_argument('-debug', '--debug',
-                        action='store_const', const=9,
+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,
+    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.")
+    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)
+    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:
+# 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
  */
 
 /*
@@ -792,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;
@@ -1024,7 +1027,9 @@ if(!xc->curval_mem)
 
 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;
@@ -1801,19 +1806,23 @@ xc->already_in_flush = 0;
 static void *fstWriterFlushContextPrivate1(void *ctx)
 {
 struct fstWriterContext *xc = (struct fstWriterContext *)ctx;
+struct fstWriterContext *xc_parent;
 
+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
 free(xc->valpos_mem);
 free(xc->vchg_mem);
 tmpfile_close(&xc->tchn_handle, &xc->tchn_handle_nam);
+xc_parent = xc->xc_parent;
 free(xc);
 
+xc_parent->in_pthread = 0;
+pthread_mutex_unlock(&(xc_parent->mutex));
+
 return(NULL);
 }
 
@@ -1861,7 +1870,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);
         }
@@ -1943,6 +1960,12 @@ 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
                         }
                 }

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

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