Version bump

* Tests: Add a test to reproduce #2891

* Fix assertion failure in binary op tree opt.

.clang-format

@@ -20,7 +20,7 @@ AlwaysBreakBeforeMultilineStrings: false
 AlwaysBreakTemplateDeclarations: false
 BinPackArguments: true
 BinPackParameters: true
-BraceWrapping:   
+BraceWrapping:
   AfterClass:      false
   AfterControlStatement: false
   AfterEnum:       false
@@ -55,12 +55,12 @@ DerivePointerAlignment: false
 DisableFormat:   false
 ExperimentalAutoDetectBinPacking: false
 FixNamespaceComments: true
-ForEachMacros:   
+ForEachMacros:
   - foreach
   - Q_FOREACH
   - BOOST_FOREACH
 IncludeBlocks:   Preserve
-IncludeCategories: 
+IncludeCategories:
   - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
     Priority:        2
   - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
@@ -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

.gitattributes

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

.github/ISSUE_TEMPLATE/bug_report.md

@@ -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: ''

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

.gitignore

@@ -1,5 +1,6 @@
 \#*
 .#*
+.nfs*
 *~
 *.tidy
 *.old
@@ -14,6 +15,8 @@
 *.tex
 *.pdf
 /Makefile
+/.ccache
+/artifact/
 README
 TAGS
 autom4te.cache
@@ -33,4 +36,6 @@ verilator_coverage_bin*
 verilator.pc
 verilator-config.cmake
 verilator-config-version.cmake
+**/__pycache__/*
+**/_build/*
 **/obj_dir/*

.travis.yml

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

MANIFEST.SKIP

@@ -1,3 +1,4 @@
+\.ccache/
 \.clang-format
 \.clang-tidy
 \.git/
@@ -18,11 +19,13 @@
 .*\.1
 \.codacy\.yml
 \.travis\.yml
+/_build/
 /build/
 /obj_dbg/
 /obj_dir/
 /obj_dist/
 /obj_iv/
+/obj_ms/
 /obj_nc/
 /obj_opt/
 /obj_vcs/
@@ -36,15 +39,18 @@ README.html
 bin/verilator_bin.*
 bin/verilator_coverage_bin.*
 docs/.*\.html$
-docs/Makefile$
+docs/_build/
 docs/clang-format.txt$
 docs/doxygen-doc/.*
+docs/spelling.txt
 examples/xml_py/copied/
 examples/xml_py/graph.*
+sonar-project.properties
 src/Makefile$
 src/Makefile_obj$
 include/verilated.mk$
 test_regress/.gdbinit$
+test_regress/transcript
 codecov.yml
 config.cache$
 config.status$
@@ -66,4 +72,5 @@ ci/
 /csrc/
 obj_dir.*
 TAGS
+gmon.out
 .*~

Makefile.in

@@ -7,7 +7,7 @@
 #
 #*****************************************************************************
 #
-# 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.
@@ -51,10 +51,12 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
 MAKEINFO = makeinfo
 POD2TEXT = pod2text
-POD2LATEXFIX = $(srcdir)/src/pod2latexfix
 MKINSTALLDIRS = $(SHELL) $(srcdir)/src/mkinstalldirs
 PERL = @PERL@
 
+# Version (for docs/guide/conf.py)
+PACKAGE_VERSION_NUMBER = @PACKAGE_VERSION_NUMBER@
+
 # Destination prefix for RPMs
 DESTDIR =
 
@@ -89,7 +91,6 @@ datarootdir = @datarootdir@
 CFG_WITH_CCWARN = @CFG_WITH_CCWARN@
 CFG_WITH_DEFENV = @CFG_WITH_DEFENV@
 CFG_WITH_LONGTESTS = @CFG_WITH_LONGTESTS@
-CFG_WITH_THREADED = @CFG_WITH_THREADED@
 PACKAGE_VERSION = @PACKAGE_VERSION@
 
 #### End of system configuration section. ####
@@ -112,20 +113,20 @@ SUBDIRS = docs src test_regress \
 	examples/make_protect_lib \
 	examples/xml_py \
 
-INFOS = verilator.txt verilator.html verilator.pdf
+INFOS = verilator.html verilator.pdf
 
 INFOS_OLD = README README.html README.pdf
 
 # Files that can be generated, but should be up to date for a distribution.
 DISTDEP = info Makefile
 
-DISTFILES_INC = $(INFOS) .gitignore \
+DISTFILES1 = $(INFOS) .gitignore \
 	*.in *.ac \
 	Artistic \
 	Changes \
 	LICENSE \
 	MANIFEST.SKIP \
-	README.adoc \
+	README.rst \
 	verilator-config.cmake.in \
 	verilator-config-version.cmake.in \
 	bin/verilator \
@@ -135,16 +136,21 @@ 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/verilator_logo.png \
-	docs/xml.adoc \
+	docs/Makefile \
+	docs/_static/*.png \
+	docs/_static/css/* \
+	docs/bin/* \
+	docs/gen/* \
+	docs/guide/*.py \
+	docs/guide/*.rst \
+	docs/guide/figures/* \
+	docs/install.rst \
+	docs/internals.rst \
+	docs/internals.rst \
+	docs/verilated.dox \
+	docs/xml.rst \
 	install-sh configure *.pod \
 	include/*.[chv]* \
 	include/*.in \
@@ -154,12 +160,15 @@ 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 \
 	examples/*/.*ignore examples/*/Makefile* \
 	examples/*/*.[chv]* examples/*/vl_* \
 	examples/*/CMakeLists.txt \
+
+DISTFILES2 = \
 	test_*/.*ignore test_*/Makefile* test_*/*.cpp \
 	test_*/*.pl test_*/*.v test_*/*.vc test_*/*.vh \
 	test_regress/*.pl \
@@ -171,6 +180,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 \
@@ -196,8 +207,6 @@ INST_PROJ_BIN_FILES = \
 	bin/verilator_bin_dbg \
 	bin/verilator_coverage_bin_dbg \
 
-DISTFILES := $(DISTFILES_INC)
-
 EXAMPLES_FIRST = \
 	examples/make_hello_c \
 	examples/make_hello_sc \
@@ -218,7 +227,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
@@ -261,20 +270,14 @@ info: $(INFOS)
 %.1: ${srcdir}/bin/%
 	pod2man $< $@
 
-verilator.txt: ${srcdir}/bin/verilator
-	$(POD2TEXT) $< $@
-
-verilator.html: ${srcdir}/bin/verilator
-	pod2html $< >$@
+.PHONY: verilator.html
+verilator.html:
+	$(MAKE) -C docs html
 
 # PDF needs DIST variables; but having configure.ac as dependency isn't detected
-verilator.pdf: ${srcdir}/bin/verilator Makefile $(POD2LATEXFIX)
-	pod2latex --full --out verilator.tex $<
-	$(PERL) $(POD2LATEXFIX) "$(DISTTITLE)" "${DISTDATE}" < verilator.tex > verilator2.tex
-	mv verilator2.tex verilator.tex
-	pdflatex verilator.tex
-	pdflatex verilator.tex
-	-rm -f verilator.toc verilator.aux verilator.idx verilator.out
+.PHONY: verilator.pdf
+verilator.pdf: Makefile
+	$(MAKE) -C docs verilator.pdf
 
 # See uninstall also - don't put wildcards in this variable, it might uninstall other stuff
 VL_INST_BIN_FILES = verilator verilator_bin verilator_bin_dbg verilator_coverage_bin_dbg \
@@ -420,12 +423,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
@@ -435,18 +442,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
@@ -456,13 +464,61 @@ 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) $(CPPCHECK_CPP) $(CPPCHECK_H)
+	$(CLANGFORMAT) $(CLANGFORMAT_FLAGS) $(CLANGFORMAT_FILES)
+
+PY_PROGRAMS = \
+	examples/xml_py/vl_file_copy \
+	examples/xml_py/vl_hier_graph \
+	docs/guide/conf.py \
+	docs/guide/vl_sphinx_extract \
+	docs/guide/vl_sphinx_extract \
+	docs/guide/vl_doxygen_filter \
+	src/astgen \
+	src/bisonpre \
+	src/config_rev \
+	src/cppcheck_filtered \
+	src/flexfix \
+	src/vlcovgen \
+	nodist/code_coverage \
+	nodist/dot_importer \
+	nodist/fuzzer/actual_fail \
+	nodist/fuzzer/generate_dictionary \
+	nodist/install_test \
+
+PY_FILES = \
+	$(PY_PROGRAMS) \
+	nodist/code_coverage.dat \
+
+YAPF = yapf3
+YAPF_FLAGS = -i
+
+yapf:
+	$(YAPF) $(YAPF_FLAGS) $(PY_FILES)
+
+FLAKE8 = flake8
+FLAKE8_FLAGS = \
+	--extend-exclude=fastcov.py \
+	--ignore=E123,E129,E251,E501,W503,W504,E701
+
+PYLINT = pylint
+PYLINT_FLAGS = --disable=R0801
+
+lint-py:
+	-$(FLAKE8) $(FLAKE8_FLAGS) $(PY_PROGRAMS)
+	-$(PYLINT) $(PYLINT_FLAGS) $(PY_PROGRAMS)
+
+format-pl-exec:
+	-chmod a+x test_regress/t/*.pl
+
 
 ftp: info
 
@@ -516,6 +572,7 @@ clean mostlyclean distclean maintainer-clean::
 	rm -rf test_*/obj_dir
 	rm -rf nodist/fuzzer/dictionary
 	rm -rf nodist/obj_dir
+	rm -rf verilator.txt
 
 distclean maintainer-clean::
 	rm -f *.info* *.1 $(INFOS) $(INFOS_OLD) $(VL_INST_MAN_FILES)
@@ -540,12 +597,10 @@ doxygen:
 
 dist-file-list:
 	@echo "begin-dist-file-list:";  # Scripts look for this
-	@echo $(wildcard $(DISTFILES))
+	@echo $(wildcard $(DISTFILES1))
+	@echo $(wildcard $(DISTFILES2))
 	@echo "end-dist-file-list:";  # Scripts look for this
 
-print-cfg-with-threaded:
-	@echo $(CFG_WITH_THREADED)
-
 ######################################################################
 # Distributions
 
@@ -562,7 +617,12 @@ tag:
 # Don't depend on DISTFILES because there's no rule for "standards.info*".
 dist: $(DISTDEP) maintainer-copy
 	-rm -fr $(DISTNAME)
-	for file in $(DISTFILES); do \
+	for file in $(DISTFILES1); do \
+	  mkdir -p `dirname $(DISTNAME)/$$file` >/dev/null ; \
+	  ln $$file $(DISTNAME)/$$file \
+	  || { echo copying $$file instead; cp -p $$file $(DISTNAME)/$$file;}; \
+	done; true;
+	for file in $(DISTFILES2); do \
 	  mkdir -p `dirname $(DISTNAME)/$$file` >/dev/null ; \
 	  ln $$file $(DISTNAME)/$$file \
 	  || { echo copying $$file instead; cp -p $$file $(DISTNAME)/$$file;}; \

README.adoc

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

README.rst

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

bin/verilator_coverage

@@ -1,7 +1,7 @@
 #!/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.
@@ -158,143 +158,51 @@ verilator_coverage - Verilator coverage analyzer
 
     verilator_coverage  -write-info merged.info -read <datafiles>...
 
-Verilator_coverage processes Verilator coverage reports.
+Verilator_coverage processes Verilated model-generated coverage reports.
 
-With --anotate, it reads the specified data file and generates annotated
-source code with coverage metrics annotated.  If multiple coverage points
-exist on the same line, additional lines will be inserted to report the
-additional points.
+For documentation see
+L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
 
-Additional Verilog-standard arguments specify the search paths necessary to
-find the source code that the coverage analysis was performed on.
+=head1 ARGUMENT SUMMARY
 
-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.
+    <filename>    Specify input data filename, default "coverage.dat"
+    --annotate <output_dir>       Directory name for source annotation.
+    --annotate-all                All files should be shown.
+    --annotate-min <count>        Minimum occurrence count for uncovered.
+    --help                        Displays this message and version and exits.
+    --rank                        Compute relative importance of tests.
+    --unlink                      With --write, unlink all inputs
+    --version                     Displays program version and exits.
+    --write <filename>            Write aggregate coverage results.
+    --write-info <filename.info>  Write lcov .info.
 
-For Verilog conditions that should never occur, you should add a $stop
-statement.  This will remove the coverage during the next build.
-
-=head1 ARGUMENTS
-
-=over 4
-
-=item I<filename>
-
-Specify input data file, may be repeated to read multiple inputs.  If no
-data file is specified, by default coverage.dat is read.
-
-=item --annotate I<output_directory>
-
-Sprcifies the directory name that source files with annotated coverage data
-should be written to.
-
-=item --annotate-all
-
-Specifies all files should be shown.  By default, only those source files
-which have low coverage are written to the output directory.
-
-=item --annotate-min I<count>
-
-Specifies the minimum occurrence count that should be flagged if the
-coverage point does not include a specified threshold.  Defaults to 10.
-
-=item --help
-
-Displays this message and program version and exits.
-
-=item --rank
-
-Print an experimental report listing the relative importance of each test
-in covering all of the coverage points.  The report shows "Covered" which
-indicates the number of points that test covers; a test is considered to
-cover a point if it has a bucket count of at least 1. The "rank" column has
-a higher number t indicate the test is more important, and rank 0 means the
-test does not need to be run to cover the points.  "RankPts" indicates the
-number of coverage points this test will contribute to overall coverage if
-all tests are run in the order of highest to lowest rank.
-
-=item --unlink
-
-When using --write to combine coverage data, unlink all input files after
-the output has been created.
-
-=item --version
-
-Displays program version and exits.
-
-=item --write I<filename>
-
-Specifies the aggregate coverage results, summed across all the files,
-should be written to the given filename in verilator_coverage data format.
-This is useful in scripts to combine many sequential runs into one master
-coverage file.
-
-=item --write-info I<filename.info>
-
-Specifies the aggregate coverage results, summed across all the files,
-should be written to the given filename in C<lcov> .info format.
-This may be used to use C<lcov> to aggregate or generate reports.
-
-The info format loses data compared to the Verilator coverage data format;
-the info will all forms of coverage converted to line style coverage, and
-if there are multiple coverage points on a single line, the minimum
-coverage across those points will be used to report coverage of the line.
-
-=back
-
-=head1 VERILOG ARGUMENTS
-
-The following arguments are compatible with GCC, VCS and most Verilog
-programs.
-
-=over 4
-
-=item +libext+I<ext>+I<ext>...
-
-Defines the extensions for Verilog files.
-
-=item +define+I<var>+I<value>
-=item -DI<var>=I<value>
-
-Defines the given variable.
-
-=item +incdir+I<dir>
-=item -II<dir>
-
-Specifies a directory for finding include files.
-
-=item -f I<file>
-
-Specifies a file containing additional command line arguments.
-
-=item -y I<dir>
-
-Specifies a module search directory.
-
-=back
+    +libext+I<ext>+I<ext>...      Extensions for Verilog files.
+    +define+I<var>+I<value>       Defines the given variable.
+    -DI<var>=I<value>             Defines the given variable.
+    +incdir+I<dir>                Add directory for finding include files.
+    -II<dir>                      Add directory for finding include files.
+    -y I<dir>                     Specifies module search directory.
 
 =head1 DISTRIBUTION
 
 The latest version is available from L<https://verilator.org>.
 
-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 the Verilator internals under the terms
 of either the GNU Lesser General Public License Version 3 or the Perl
 Artistic License Version 2.0.
 
 SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-=head1 AUTHORS
-
-Wilson Snyder <[email protected]>
-
 =head1 SEE ALSO
 
 C<verilator>, C<lcov>
 
 L<verilator_coverage --help> which is the source for this document.
 
+and L<https://verilator.org/guide/latest/exe_verilator_coverage.html> for
+detailed documentation.
+
 =cut
 
 ######################################################################

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,7 +208,7 @@ Do not show differences in line numbering.
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2005-2020 by Wilson Snyder. This program is free software; you
+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.
@@ -248,6 +223,8 @@ Wilson Snyder <[email protected]>
 
 C<verilator>
 
+and L<https://verilator.org/verilator_doc.html> for detailed documentation.
+
 =cut
 
 ######################################################################

bin/verilator_gantt

@@ -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";
 
@@ -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);
@@ -456,103 +535,39 @@ verilator_gantt - Create Gantt chart of multi-threaded execution
 
 =head1 SYNOPSIS
 
-Creates a visual representation to help analyze Verilator multithreaded
-simulation performance, by showing when each macro-task starts and ends,
-and showing when each thread is busy or idle.
+Verilator_gantt creates a visual representation to help analyze Verilator
+multithreaded simulation performance, by showing when each macro-task
+starts and ends, and showing when each thread is busy or idle.
 
-The generated Gantt chart has time on the X-axis. Times shown are to the
-scale printed, i.e. a certain about of time for each character width.  The
-Y-axis shows threads, each thread's execution is shown on one line.  That
-line shows "[" at the position in time when it executes.
+For documentation see
+L<https://verilator.org/guide/latest/exe_verilator_gantt.html>.
 
-Following the "[" is the cpu number the task executed on, followed by zero
-or more "-" to make the width of the characters match the scaled execution
-time, followed by a "]".  If the scale is too small, the cpu number and
-mtask number will not be printed.  If the scale is very small, a "&"
-indicates multiple mtasks started at that time position.
+=head1 ARGUMENT SUMMARY
 
-Also creates a value change dump (VCD) format dump file which may be viewed
-in a waveform viewer (e.g. C<GTKWave>).  See below.
-
-=head1 USAGE
-
-  Build with --prof-threads.
-
-  Run a sim with +verilator+prof+threads+window 2.
-
-  This will create profile_threads.dat.
-
-  Then run:
-
-  verilator_gantt profile_threads.dat
-
-  The report will be printed on standard output, this also generates
-  profile_threads.vcd
-
-  View profile_threads.vcd in a waveform viewer.
-
-=head1 VCD SIGNALS
-
-In waveforms there are the following signals. Most signals the "decimal"
-format will remove the leading zeros and make the traces easier to read.
-
-parallelism: The number of mtasks active at this time, for best performance
-this will match the thread count. You may want to use an "analog step"
-format to view this signal.
-
-cpu#_thread: For the given CPU number, the thread number executing.
-
-mtask#_cpu; For the given mtask id, the CPU it is executing on.
-
-thread#_mtask: For the given thread number, the mtask id executing.
-
-=head1 ARGUMENTS
-
-=over 4
-
-=item I<filename>
-
-The filename to read data from, defaults to "profile_threads.dat".
-
-=item --help
-
-Displays this message and program version and exits.
-
-=item --scale I<n>
-
-On the X-axis of the generated Gantt chart, each character represents this
-many time units. (On x86, time units are rdtsc ticks.)  Defaults to 0,
-which will automatically compute a reasonable scale where no two mtasks
-need to fit into same character width's worth of scaled time.
-
-=item --no-vcd
-
-=item --vcd I<filename>
-
-Set output filename for vcd dump, or disable. Default is
-verilator_gantt.vcd.
-
-=back
+    <filename>    Filename to read data from, default "profile_threads.dat".
+    --help        Displays this message and program version and exits.
+    --scale I<n>  Number of characters per time step.
+    --no-vcd      Do not create a VCD file.
+    --vcd <filename>   Set output filename for vcd dump, default "verilator_gantt.vcd."
 
 =head1 DISTRIBUTION
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2018-2020 by Wilson Snyder. This program is free software; you
+Copyright 2018-2021 by Wilson Snyder. This program is free software; you
 can redistribute it and/or modify it under the terms of either the GNU
 Lesser General Public License Version 3 or the Perl Artistic License
 Version 2.0.
 
 SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-=head1 AUTHORS
-
-Wilson Snyder <[email protected]>
-
 =head1 SEE ALSO
 
 C<verilator>
 
+and L<https://verilator.org/guide/latest/exe_verilator_gantt.html> for
+detailed documentation.
+
 =cut
 
 ######################################################################

bin/verilator_includer

@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 # DESCRIPTION: Print include statements for each ARGV
 #
-# 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.

bin/verilator_profcfunc

@@ -214,35 +214,32 @@ the functions are then transformed, assuming the user used Verilator's
 --prof-cfuncs, and a report printed showing the percentage of time, etc,
 in each Verilog block.
 
-=head1 ARGUMENTS
+For documentation see
+L<https://verilator.org/guide/latest/exe_verilator_profcfuncs.html>.
 
-=over 4
+=head1 ARGUMENT SUMMARY
 
-=item --help
-
-Displays this message and program version and exits.
-
-=back
+    <filename>  Input file (gprof.out)
+    --help      Display this help
 
 =head1 DISTRIBUTION
 
 The latest version is available from L<https://verilator.org>.
 
-Copyright 2007-2020 by Wilson Snyder. This program is free software; you
+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
-
-Wilson Snyder <[email protected]>
-
 =head1 SEE ALSO
 
 C<verilator>
 
+and L<https://verilator.org/guide/latest/exe_verilator_profcfuncs.html> for
+detailed documentation.
+
 =cut
 
 ######################################################################

ci/ci-ccache-maint.bash

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# DESCRIPTION: Verilator: Travis CI ccache maintenance
+# 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
@@ -19,8 +19,8 @@ set -x
 ccache --version
 
 # Flush ccache if requested in commit message
-COMMIT="${TRAVIS_PULL_REQUEST_SHA:-$TRAVIS_COMMIT}"
-if git log --format=%B -n 1 "$COMMIT" | grep -q -i '\[travis\s\+ccache\s\+clear\]'; then
+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

ci/ci-install.bash

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

ci/ci-script.bash

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

ci/docker/buildenv/Dockerfile

@@ -40,7 +40,7 @@ RUN apt-get update \
 
 WORKDIR /tmp
 
-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 && \

ci/docker/buildenv/README.adoc

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

ci/docker/buildenv/README.rst

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

ci/docker/run/README.adoc

@@ -1,59 +0,0 @@
-= 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/README.rst

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

ci/docker/run/verilator-wrap.sh

@@ -27,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/travis-ccache-size.bash

@@ -1,37 +0,0 @@
-#!/usr/bin/env bash
-# DESCRIPTION: Verilator: Travis CI ccache sizer
-#
-# Copyright 2020 by Geza Lore. This program is free software; you
-# can redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
-#
-# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
-
-################################################################################
-# This script computes the size of the ccache to be used for a job. We want the
-# ccache to be just big enough to be able to hold a whole build so a re-build
-# of the same does not miss in the cache due to capacity, but we don't want the
-# ccache too big as pulling it down from the network takes time, and it is
-# unlikely objects from much earlier builds would be useful.
-################################################################################
-
-fatal() {
-  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
-}
-
-if [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
-  if [ "$COVERAGE" == 1 ]; then
-    echo "1024M"
-  else
-    echo "768M"
-  fi
-elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
-  if [[ $TESTS == coverage-* ]]; then
-    echo "1536M"
-  else
-    echo "256M"
-  fi
-else
-  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
-fi

ci/travis-install.bash

@@ -1,72 +0,0 @@
-#!/usr/bin/env bash
-# DESCRIPTION: Verilator: Travis CI dependency install script
-#
-# Copyright 2020 by Geza Lore. This program is free software; you
-# can redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
-#
-# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
-
-################################################################################
-# This script runs in the 'install' phase of all jobs, in all stages. We try to
-# minimize the time spent in this by selectively installing only the components
-# required by the particular build stage.
-################################################################################
-
-# Note that Travis runs "apt-get update" when "apt-get install" is used in the
-# .travis.yml file directly, but since we invoke it via this script, we need to
-# run it manually where requried, otherwise some packages cannot be found.
-
-set -e
-set -x
-
-fatal() {
-  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
-}
-
-install-vcddiff() {
-  TMP_DIR="$(mktemp -d)"
-  git clone https://github.com/veripool/vcddiff "$TMP_DIR"
-  git -C "${TMP_DIR}" checkout 5112f88b7ba8818dce9dfb72619e64a1fc19542c
-  make -C "${TMP_DIR}"
-  sudo cp "${TMP_DIR}/vcddiff" /usr/local/bin
-}
-
-if [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
-  ##############################################################################
-  # Dependencies of jobs in the 'build' stage, i.e.: packages required to
-  # build Verilator
-
-  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
-    time sudo apt-get update
-    sudo apt-get install libfl-dev
-    sudo apt-get install libgoogle-perftools-dev
-    if [ "$COVERAGE" = 1 ]; then
-      yes yes | sudo cpan -fi Unix::Processors Parallel::Forker
-    fi
-  else
-    fatal "Unknown os: '$TRAVIS_OS_NAME'"
-  fi
-elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
-  ##############################################################################
-  # Dependencies of jobs in the 'test' stage, i.e.: packages required to
-  # run the tests
-
-  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
-    sudo apt-get update
-    sudo apt-get install gdb gtkwave lcov
-    if [ "$TRAVIS_DIST" = "focal" ]; then
-      sudo apt-get install libsystemc-dev
-    fi
-    yes yes | sudo cpan -fi Unix::Processors Parallel::Forker
-    # Not listing Bit::Vector as slow to install, and only skips one test
-    install-vcddiff
-  else
-    fatal "Unknown os: '$TRAVIS_OS_NAME'"
-  fi
-else
-  ##############################################################################
-  # Unknown build stage
-  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
-fi

ci/travis-script.bash

@@ -1,101 +0,0 @@
-#!/usr/bin/env bash
-# DESCRIPTION: Verilator: Travis CI main job script
-#
-# Copyright 2020 by Geza Lore. This program is free software; you
-# can redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
-#
-# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
-
-################################################################################
-# This is the main script executed in the 'script' phase by all jobs. We use a
-# single script to keep the .travis.yml spec simple. We pass job parameters via
-# environment variables using 'env' keys. Having different 'env' keys in jobs
-# ensures they use different Travis build caches.
-################################################################################
-
-set -e
-set -x
-
-fatal() {
-  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
-}
-
-if [ "$TRAVIS_BUILD_STAGE_NAME" = "build" ]; then
-  ##############################################################################
-  # Build verilator
-
-  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
-    if [ "$COVERAGE" != 1 ]; then
-      autoconf
-      ./configure --enable-longtests --enable-ccwarn
-      make -j $(nproc)
-    else
-      nodist/code_coverage --stages 1-2
-    fi
-  else
-    fatal "Unknown os: '$TRAVIS_OS_NAME'"
-  fi
-elif [ "$TRAVIS_BUILD_STAGE_NAME" = "test" ]; then
-  ##############################################################################
-  # Run tests
-
-  if [ "$TRAVIS_OS_NAME" = "linux" ]; then
-    # Run the specified test
-    case $TESTS in
-      dist-vlt-0)
-        make -C test_regress SCENARIOS="--dist --vlt" DRIVER_HASHSET=--hashset=0/2
-        ;;
-      dist-vlt-1)
-        make -C test_regress SCENARIOS="--dist --vlt" DRIVER_HASHSET=--hashset=1/2
-        ;;
-      vltmt-0)
-        make -C test_regress SCENARIOS=--vltmt DRIVER_HASHSET=--hashset=0/2
-        ;;
-      vltmt-1)
-        make -C test_regress SCENARIOS=--vltmt DRIVER_HASHSET=--hashset=1/2
-        ;;
-      coverage-dist)
-        nodist/code_coverage --stages 3- --scenarios=--dist
-        ;;
-      coverage-vlt-0)
-        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=0/4
-        ;;
-      coverage-vlt-1)
-        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=1/4
-        ;;
-      coverage-vlt-2)
-        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=2/4
-        ;;
-      coverage-vlt-3)
-        nodist/code_coverage --stages 3- --scenarios=--vlt --hashset=3/4
-        ;;
-      coverage-vltmt-0)
-        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=0/4
-        ;;
-      coverage-vltmt-1)
-        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=1/4
-        ;;
-      coverage-vltmt-2)
-        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=2/4
-        ;;
-      coverage-vltmt-3)
-        nodist/code_coverage --stages 3- --scenarios=--vltmt --hashset=3/4
-        ;;
-      *)
-        fatal "Unknown test: $TESTS"
-        ;;
-    esac
-    # Upload coverage data to codecov.io
-    if [[ $TESTS == coverage-* ]]; then
-      bash <(curl -s https://codecov.io/bash) -f nodist/obj_dir/coverage/app_total.info
-    fi
-  else
-    fatal "Unknown os: '$TRAVIS_OS_NAME'"
-  fi
-else
-  ##############################################################################
-  # Unknown build stage
-  fatal "Unknown build stage: '$TRAVIS_BUILD_STAGE_NAME'"
-fi

codecov.yml

@@ -1,6 +1,6 @@
 # DESCRIPTION: codecov.io config
 #
-# Copyright 2020-2020 by Wilson Snyder. This program is free software; you
+# 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.
@@ -15,7 +15,7 @@ codecov:
 coverage:
   precision: 2
   round: down
-  range: "70...100"
+  range: "50...100"
   ignore:
     - "ci"
     - "docs"

configure.ac

@@ -1,25 +1,27 @@
 # DESCRIPTION: Process this file with autoconf to produce a configure script.
 #
-# Copyright 2003-2020 by Wilson Snyder. Verilator is free software; you
+# 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.036 2020-06-06],
+AC_INIT([Verilator],[4.202 2021-04-24],
         [https://verilator.org],
         [verilator],[https://verilator.org])
 # When releasing, also update header of Changes file
 # and commit using "devel release" or "Version bump" message
+# Then 'make maintainer-dist'
 
 AC_CONFIG_HEADER(src/config_build.h)
-AC_CONFIG_FILES(Makefile docs/Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake)
+AC_CONFIG_FILES(Makefile src/Makefile src/Makefile_obj include/verilated.mk include/verilated_config.h verilator.pc verilator-config.cmake verilator-config-version.cmake)
 
 # Version
 AC_MSG_RESULT([configuring for $PACKAGE_STRING])
 PACKAGE_VERSION_NUMBER=`AS_ECHO("$PACKAGE_VERSION") | sed 's/ .*//g'`
 AC_SUBST(PACKAGE_VERSION_NUMBER)
+AC_DEFINE_UNQUOTED([PACKAGE_VERSION_NUMBER_STRING],["$PACKAGE_VERSION_NUMBER"],[Package version as a number])
 
 # Ignore automake flags passed by Ubuntu builds
 AC_ARG_ENABLE([dependency-tracking],
@@ -112,27 +114,11 @@ AC_ARG_ENABLE([longtests],
 AC_SUBST(CFG_WITH_LONGTESTS)
 AC_MSG_RESULT($CFG_WITH_LONGTESTS)
 
-# CFG_WITH_PREC11
-AC_MSG_CHECKING(whether allow pre-C++11)
-AC_ARG_ENABLE([prec11],
-              [AS_HELP_STRING([--enable-prec11],
-                              [enable pre-C++11 compilers 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
@@ -153,14 +139,25 @@ 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
@@ -403,12 +400,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
@@ -416,25 +418,24 @@ AC_LINK_IFELSE(
         fi
       fi],
      [_my_result=no])
-CFG_WITH_THREADED=$_my_result
-AC_SUBST(CFG_WITH_THREADED)
-AC_MSG_RESULT($CFG_WITH_THREADED)
-CXXFLAGS="$ACO_SAVE_CXXFLAGS"
+   ])
 
-# Check compiler flag
-if test "$CFG_WITH_THREADED" = "no" ; then
-   if test "$CFG_WITH_PREC11" = "no" ; then
-      AC_MSG_NOTICE([[]])
-      AC_MSG_ERROR([[the $CXX compiler appears to not support C++11.
+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.
@@ -447,14 +448,18 @@ AC_CHECK_MEMBER([struct stat.st_mtim.tv_nsec],
 # - If not found or not system-wide, user can set SYSTEMC_INCLUDE.
 # AC_CHECK_HEADERS seems to not locate on Travis-CI but include does work.
 AC_MSG_CHECKING([whether SystemC is found (in system path)])
-AC_COMPILE_IFELSE(
+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_H],[1],[Defined if have systemc.h])],
+     AC_DEFINE([HAVE_SYSTEMC],[1],[Defined if have SystemC library])],
     [_my_result=no])
 AC_MSG_RESULT($_my_result)
-AC_SUBST(HAVE_SYSTEMC_H)
+LIBS="$ACO_SAVE_LIBS"
+AC_SUBST(HAVE_SYSTEMC)
 
 # Checks for system services
 

docs/.gitignore

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

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 privately certify your
-   contribution.
-
-* Your test contributions are generally considered released into the
-  Creative Commons Public Domain (CC0), unless you request otherwise or put
-  a GNU/Artistic license on your file.
-
-* Most important is we get your patch. If you'd like to clean up
-  indentation and related issues ahead of our feedback, that is
-  appreciated; please see the coding conventions in
-  link:internals.adoc[docs/internals].
-
-==== Do you have questions?
-
-* Please see FAQ section and rest of the
-  https://verilator.org/verilator_doc.html[Verilator manual],
-  or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-* Ask any question in the
-  https://verilator.org/forum[Verilator forum].
-
-==== Code of Conduct
-
-* Our contributors and participants pledge to make participation in our
-  project and our community a positive experience for everyone.  We follow
-  the https://www.contributor-covenant.org/version/1/4/code-of-conduct.html[Contributor
-  Covenant version 1.4].
-
-Thanks!

docs/CONTRIBUTING.rst

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

docs/CONTRIBUTORS

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

docs/Makefile

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

docs/Makefile.in

@@ -1,50 +0,0 @@
-#*****************************************************************************
-# DESCRIPTION: Verilator documentation: Makefile pre-configure version
-#
-# This file is part of Verilator.
-#
-# Code available from: https://verilator.org
-#
-#*****************************************************************************
-#
-# Copyright 2003-2020 by Wilson Snyder. This program is free software; you
-# can redistribute it and/or modify it under the terms of either the GNU
-# Lesser General Public License Version 3 or the Perl Artistic License
-# Version 2.0.
-# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
-#
-#****************************************************************************/
-#
-# This file is intended only to be called from the top-level Verilator Makefile.
-
-#### Start of system configuration section. ####
-
-ASCIIDOCTOR = asciidoctor
-DOXYGEN = doxygen
-
-#### End of system configuration section. ####
-######################################################################
-
-.SUFFIXES:
-
-default:
-	@echo "error: make not supported here, run 'make docs' from Verilator top-level"
-
-%.html: %.adoc
-	$(ASCIIDOCTOR) $< -n -o $@
-
-clean mostlyclean distclean maintainer-clean::
-	rm -f $(SCRIPTS) *.tmp
-	rm -f *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.log
-	rm -f *.pg *.pgs *.toc *.tp *.tps *.vr *.vrs *.idx
-	rm -f *.ev *.evs *.ov *.ovs *.cv *.cvs *.ma *.mas
-	rm -f *.tex
-
-distclean maintainer-clean::
-	rm -f *.info* *.1 *.html *.pdf $(INFOS)
-	rm -f Makefile
-
-.PHONY: doxygen
-
-doxygen:
-	$(DOXYGEN) doxygen.config

docs/TODO

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

docs/_static/css/vlt_sphinx.css

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

docs/bin/vl_sphinx_extract

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+# pylint: disable=C0112,C0114,C0116,C0301,R0903
+# -*- Python -*- See copyright, etc below
+######################################################################
+
+import argparse
+import re
+
+#######################################################################
+
+class VlSphinxExtract:
+    debug = 0
+    SkipBasenames = {}
+
+    def process(self, filename):
+        with open(filename) as fhr:
+            fhw = None
+            for line in fhr:
+                # =for VL_SPHINX_EXTRACT "file_to_write_to"
+                match = re.search(r'VL_SPHINX_EXTRACT +"([^"]+)"', line)
+                if match:
+                    outname = match.group(1)
+                    print("Writing %s" % outname)
+                    fhw = open(outname, "w")
+                    fhw.write(
+                        ".. comment: generated by vl_sphinx_extract from " +
+                        filename + "\n")
+                    fhw.write(".. code-block::\n")
+                elif re.match(r'^[=a-zA-Z0-9_]', line):
+                    fhw = None
+                elif fhw:
+                    fhw.write(line)
+
+
+#######################################################################
+
+parser = argparse.ArgumentParser(
+    allow_abbrev=False,
+    formatter_class=argparse.RawDescriptionHelpFormatter,
+    description="""Read a file and extract documentation data.""",
+    epilog=
+    """ Copyright 2021-2021 by Wilson Snyder.  This package is free software;
+you can redistribute it and/or modify it under the terms of either the GNU
+Lesser General Public License Version 3 or the Perl Artistic License
+Version 2.0.
+
+SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0""")
+
+parser.add_argument('--debug',
+                    action='store_const',
+                    const=9,
+                    help='enable debug')
+parser.add_argument('path', help='path to extract from')
+Args = parser.parse_args()
+
+o = VlSphinxExtract()
+o.debug = Args.debug
+o.process(Args.path)
+
+######################################################################
+# Local Variables:
+# compile-command: "./vl_sphinx_extract --debug ../../bin/verilator"
+# End:

docs/bin/vl_sphinx_fix

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

docs/doxygen-mainpage

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

docs/gen/ex_USERERROR_faulty.rst

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

docs/gen/ex_USERERROR_msg.rst

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

docs/gen/ex_USERFATAL_faulty.rst

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

docs/gen/ex_USERFATAL_msg.rst

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

docs/gen/ex_USERINFO_faulty.rst

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

docs/gen/ex_USERINFO_msg.rst

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

docs/gen/ex_USERWARN_faulty.rst

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

docs/gen/ex_USERWARN_msg.rst

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

docs/gen/ex_VARHIDDEN_faulty.rst

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

docs/gen/ex_VARHIDDEN_msg.rst

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

docs/gen/ex_WIDTH_1_faulty.rst

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

docs/gen/ex_WIDTH_1_fixed.rst

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

docs/gen/ex_WIDTH_1_msg.rst

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

docs/guide/changes.rst

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

docs/guide/conf.py

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

docs/guide/connecting.rst

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

docs/guide/contributing.rst

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

docs/guide/contributors.rst

@@ -0,0 +1,155 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+************************
+Contributors and Origins
+************************
+
+Authors
+=======
+
+When possible, please instead report bugs at `Verilator Issues
+<https://verilator.org/issues>`_.
+
+Primary author is Wilson Snyder <[email protected]>.
+
+Major concepts by Paul Wasson, Duane Galbi, John Coiner and Jie Xu.
+
+
+Contributors
+============
+
+Many people have provided ideas and other assistance with Verilator.
+
+Verilator is receiving major development support from the `CHIPS Alliance
+<https://chipsalliance.org>`_.
+
+Previous major corporate sponsors of Verilator, by providing significant
+contributions of time or funds included include: Atmel Corporation, Cavium
+Inc., Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd.,
+Hicamp Systems, Intel Corporation, Mindspeed Technologies Inc., MicroTune
+Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus Networks Inc.,
+and SiCortex Inc.
+
+The people who have contributed major functionality are: Byron Bradley,
+Jeremy Bennett, Lane Brooks, John Coiner, Duane Galbi, Geza Lore, Todd
+Strader, Stefan Wallentowitz, Paul Wasson, Jie Xu, and Wilson Snyder.
+Major testers included Jeff Dutton, Jonathon Donaldson, Ralf Karge, David
+Hewson, Iztok Jeras, Wim Michiels, Alex Solomatnikov, Sebastien Van
+Cauwenberghe, Gene Weber, and Clifford Wolf.
+
+Some of the people who have provided ideas, and feedback for Verilator
+include: David Addison, Nikana Anastasiadis, Vasu Arasanipalai, Jens Arm,
+Tariq B. Ahmad, Sharad Bagri, Matthew Ballance, Andrew Bardsley, Matthew
+Barr, Geoff Barrett, Kaleb Barrett, Julius Baxter, Jeremy Bennett, Michael
+Berman, Jean Berniolles, Victor Besyakov, Moinak Bhattacharyya, Krzysztof
+Bieganski, David Binderman, Piotr Binkowski, Johan Bjork, David Black,
+Tymoteusz Blazejczyk, Daniel Bone, Morten Borup Petersen, Gregg Bouchard,
+Christopher Boumenot, Nick Bowler, Byron Bradley, Bryan Brady, Charlie
+Brej, J Briquet, Lane Brooks, John Brownlee, Jeff Bush, Lawrence Butcher,
+Tony Bybell, Iru Cai, Ted Campbell, Chris Candler, Lauren Carlson, Donal
+Casey, Alex Chadwick, Terry Chen, Yi-Chung Chen, Enzo Chi, Robert A. Clark,
+Ryan Clarke, Allan Cochrane, John Coiner, Gianfranco Costamagna, Sean
+Cross, George Cuan, Joe DErrico, Lukasz Dalek, Gunter Dannoritzer, Ashutosh
+Das, Maarten De Braekeleer, Bernard Deadman, Alberto Del Rio, John Demme,
+Mike Denio, John Deroo, Philip Derrick, John Dickol, Ruben Diez, Danny
+Ding, Jacko Dirks, Ivan Djordjevic, Jonathon Donaldson, Sebastian Dressler,
+Alex Duller, Jeff Dutton, Tomas Dzetkulic, Richard E George, Edgar
+E. Iglesias, Usuario Eda, Charles Eddleston, Chandan Egbert, Jan Egil Ruud,
+Joe Eiler, Ahmed El-Mahmoudy, Trevor Elbourne, Mats Engstrom, Charles Eric
+LaForest, Robert Farrell, Eugen Fekete, Fabrizio Ferrandi, Udi Finkelstein,
+Brian Flachs, Andrea Foletto, Bob Fredieu, Duane Galbi, Benjamin Gartner,
+Christian Gelinek, Peter Gerst, Glen Gibb, Michael Gielda, Barbara Gigerl,
+Shankar Giri, Dan Gisselquist, Petr Gladkikh, Sam Gladstone, Andrew
+Goessling, Amir Gonnen, Chitlesh Goorah, Tomasz Gorochowik, Kai Gossner,
+Sergi Granell, Al Grant, Alexander Grobman, Xuan Guo, Driss Hafdi, Neil
+Hamilton, James Hanlon, Oyvind Harboe, Jannis Harder, Junji Hashimoto,
+Thomas Hawkins, Mitch Hayenga, Harald Heckmann, Robert Henry, Stephen
+Henry, David Hewson, Jamey Hicks, Joel Holdsworth, Andrew Holme, Hiroki
+Honda, Alex Hornung, Pierre-Henri Horrein, David Horton, Peter Horvath, Jae
+Hossell, Kuoping Hsu, Alan Hunter, James Hutchinson, Anderson Ignacio da
+Silva, Jamie Iles, Thomas J Whatson, Ben Jackson, Mark Jackson Pulver,
+Shareef Jalloq, Marlon James, Krzysztof Jankowski, HyungKi Jeong, Iztok
+Jeras, James Johnson, Christophe Joly, Franck Jullien, James Jung, Mike
+Kagen, Arthur Kahlich, Kaalia Kahn, Guy-Armand Kamendje, Vasu Kandadi,
+Kanad Kanhere, Patricio Kaplan, Pieter Kapsenberg, Rafal Kapuscik, Ralf
+Karge, Dan Katz, Sol Katzman, Ian Kennedy, Michael Killough, Jonathan
+Kimmitt, Olof Kindgren, Kevin Kiningham, Dan Kirkham, Sobhan Klnv, Gernot
+Koch, Jack Koenig, Soon Koh, Nathan Kohagen, Steve Kolecki, Brett Koonce,
+Will Korteland, Wojciech Koszek, Varun Koyyalagunta, Markus Krause, David
+Kravitz, Roland Kruse, Andreas Kuster, Sergey Kvachonok, Ed Lander, Steve
+Lang, Stephane Laurent, Walter Lavino, Christian Leber, Larry Lee, Igor
+Lesik, John Li, Eivind Liland, Charlie Lind, Andrew Ling, Jiuyang Liu, Paul
+Liu, Derek Lockhart, Jake Longo, Geza Lore, Arthur Low, Stefan Ludwig, Dan
+Lussier, Fred Ma, Duraid Madina, Odd Magne Reitan, Affe Mao, Julien
+Margetts, Mark Marshall, Alfonso Martinez, Unai Martinez-Corral, Yves
+Mathieu, Patrick Maupin, Conor McCullough, Jason McMullan, Elliot Mednick,
+Wim Michiels, Miodrag Milanovic, Peter Monsson, Sean Moore, Dennis
+Muhlestein, John Murphy, Matt Myers, Nathan Myers, Richard Myers, Dimitris
+Nalbantis, Peter Nelson, Bob Newgard, Paul Nitza, Yossi Nivin, Pete Nixon,
+Lisa Noack, Mark Nodine, Kuba Ober, Andreas Olofsson, Baltazar Ortiz,
+Aleksander Osman, Don Owen, James Pallister, Vassilis Papaefstathiou, Brad
+Parker, Dan Petrisko, Maciej Piechotka, David Pierce, Cody Piersall,
+Dominic Plunkett, David Poole, Mike Popoloski, Roman Popov, Rich Porter,
+Niranjan Prabhu, Usha Priyadharshini, Prateek Puri, Marshal Qiao, Nandu
+Raj, Danilo Ramos, Chris Randall, Anton Rapp, Josh Redford, Frederic
+Requin, Dustin Richmond, Samuel Riedel, Eric Rippey, Oleg Rodionov, Ludwig
+Rogiers, Paul Rolfe, Arjen Roodselaar, Tobias Rosenkranz, Huang Rui, Denis
+Rystsov, John Sanguinetti, Galen Seitz, Joseph Shaker, Salman Sheikh, Yu
+Sheng Lin, Hao Shi, Mike Shinkarovsky, Rafael Shirakawa, Jeffrey Short, Fan
+Shupei, Rodney Sinclair, Steven Slatter, Brian Small, Garrett Smith, Tim
+Snyder, Wilson Snyder, Maciej Sobkowski, Stan Sokorac, Alex Solomatnikov,
+Wei Song, Art Stamness, David Stanford, John Stevenson, Pete Stevenson,
+Patrick Stewart, Rob Stoddard, Todd Strader, John Stroebel, Sven Stucki,
+Howard Su, Emerson Suguimoto, Gene Sullivan, Wai Sum Mong, Qingyao Sun,
+Renga Sundararajan, Rupert Swarbrick, Yutetsu Takatsukasa, Thierry Tambe,
+Drew Taussig, Peter Tengstrand, Wesley Terpstra, Rui Terra, Stefan Thiede,
+Gary Thomas, Ian Thompson, Kevin Thompson, Mike Thyer, Hans Tichelaar,
+Viktor Tomov, Steve Tong, Alex Torregrosa, Michael Tresidder, David Turner,
+Neil Turton, Cong Van Nguyen, Hans Van Antwerpen, Jan Van Winkel, Sebastien
+Van Cauwenberghe, Laurens van Dam, Leendert van Doorn, Srini Vemuri, Yuri
+Victorovich, Bogdan Vukobratovic, Holger Waechtler, Philipp Wagner, Stefan
+Wallentowitz, Shawn Wang, Paul Wasson, Greg Waters, Thomas Watts, Eugene
+Weber, David Welch, Martin Whitaker, Marco Widmer, Leon Wildman, Daniel
+Wilkerson, Gerald Williams, Trevor Williams, Jeff Winston, Joshua Wise,
+Clifford Wolf, Tobias Wolfel, Johan Wouters, Paul Wright, Junyi Xi, Ding
+Xiaoliang, Jie Xu, Mandy Xu, Yinan Xu, Luke Yang, Amir Yazdanbakhsh, and
+Keyi Zhang.
+
+Thanks to them, and all those we've missed including above, or wished to
+remain anonymous.
+
+Historical Origins
+==================
+
+Verilator was conceived in 1994 by Paul Wasson at the Core Logic Group at
+Digital Equipment Corporation.  The Verilog code that was converted to C
+was then merged with a C based CPU model of the Alpha processor and
+simulated in a C based environment called CCLI.
+
+In 1995 Verilator started being used also for Multimedia and Network
+Processor development inside Digital.  Duane Galbi took over active
+development of Verilator, and added several performance enhancements.  CCLI
+was still being used as the shell.
+
+In 1998, through the efforts of existing DECies, mainly Duane Galbi,
+Digital graciously agreed to release the source code.  (Subject to the code
+not being resold, which is compatible with the GNU Public License.)
+
+In 2001, Wilson Snyder took the kit, and added a SystemC mode, and called
+it Verilator2.  This was the first packaged public release.
+
+In 2002, Wilson Snyder created Verilator 3.000 by rewriting Verilator from
+scratch in C++.  This added many optimizations, yielding about a 2-5x
+performance gain.
+
+In 2009, major SystemVerilog and DPI language support was added.
+
+In 2018, Verilator 4.000 was released with multithreaded support.
+
+In 2019, Verilator joined the `CHIPS Alliance
+<https://chipsalliance.org>`_.
+
+Currently, various language features and performance enhancements are added
+as the need arises.  Verilator is now about 3x faster than in 2002, and is
+faster than most (if not every) other simulator.

docs/guide/copyright.rst

@@ -0,0 +1,19 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+*********
+Copyright
+*********
+
+The latest version of Verilator is available from `https://verilator.org
+<https://verilator.org>`_.
+
+Copyright 2003-2021 by Wilson Snyder. This program is free software; you
+can redistribute it and/or modify the Verilator internals under the terms
+of either the GNU Lesser General Public License Version 3 or the Perl
+Artistic License Version 2.0.
+
+All Verilog and C++/SystemC code quoted within this documentation file are
+released as Creative Commons Public Domain (CC0).  Many example files and
+test files are likewise released under CC0 into effectively the Public
+Domain as described in the files themselves.

docs/guide/deprecations.rst

@@ -0,0 +1,28 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+Deprecations
+============
+
+The following deprecated items are scheduled for future removal:
+
+C++11 compiler support
+  Verilator currently requires C++11 or newer compilers.  Verilator will
+  require C++14 or newer compilers for both compiling Verilator and
+  compiling Verilated models no sooner than January 2022.
+
+No-Relative-Cfuncs Option
+  The :vlopt:`--no-relative-cfuncs` option is not be required by any C++11
+  compliant compiler and is planned for removal no sooner than July 2021.
+
+Inhibit-Sim Option
+  The :vlopt:`--inhibit-sim` option is planned for removal no sooner than
+  July 2021.
+
+Configuration File -msg
+  The :vlopt:`lint_off` "-msg" option has been replaced with the "-rule"
+  option.  "-msg" is planned for removal no sooner than January 2021.
+
+XML locations
+  The XML "fl" attribute has been replaced with the "loc" attribute.  "fl"
+  is planned for removal no sooner than January 2021.

docs/guide/environment.rst

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

docs/guide/example_cc.rst

@@ -0,0 +1,92 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Example C++ Execution:
+
+Example C++ Execution
+=====================
+
+We'll compile this example into C++.  For an extended and commented version
+of what this C++ code is doing, see
+:file:`examples/make_tracing_c/sim_main.cpp` in the distribution.
+
+.. include:: example_common_install.rst
+
+Now, let's create an example Verilog, and C++ wrapper file:
+
+.. code-block:: bash
+
+     mkdir test_our
+     cd test_our
+
+     cat >our.v <<'EOF'
+       module our;
+          initial begin $display("Hello World"); $finish; end
+       endmodule
+     EOF
+
+     cat >sim_main.cpp <<'EOF'
+       #include "Vour.h"
+       #include "verilated.h"
+       int main(int argc, char** argv, char** env) {
+           VerilatedContext* contextp = new VerilatedContext;
+           contextp->commandArgs(argc, argv);
+           Vour* top = new Vour{contextp};
+           while (!contextp->gotFinish()) { top->eval(); }
+           delete top;
+           delete contextp;
+           return 0;
+       }
+     EOF
+
+Now we run Verilator on our little example.
+
+.. code-block:: bash
+
+     verilator -Wall --cc --exe --build sim_main.cpp our.v
+
+Breaking this command down:
+
+#. :vlopt:`-Wall` so Verilator has stronger lint warnings
+   enabled.
+
+#. :vlopt:`--cc` to get C++ output (versus e.g. SystemC
+   or only linting).
+
+#. :vlopt:`--exe`, along with our :command:`sim_main.cpp` wrapper file, so
+   the build will create an executable instead of only a library.
+
+#. :vlopt:`--build` so Verilator will call make itself. This is we don't
+   need to manually call make as a separate step. You can also write your
+   own compile rules, and run make yourself as we show in :ref:`Example
+   SystemC Execution`.)
+
+#. An finally, :command:`our.v` which is our SystemVerilog design file.
+
+Once Verilator completes we can see the generated C++ code under the
+:file:`obj_dir` directory.
+
+.. code-block:: bash
+
+     ls -l obj_dir
+
+(See :ref:`Files Read/Written` for descriptions of some of the files that
+were created.)
+
+And now we run it:
+
+.. code-block:: bash
+
+     obj_dir/Vour
+
+And we get as output:
+
+.. code-block:: bash
+
+     Hello World
+     - our.v:2: Verilog $finish
+
+Really, you're better off using a Makefile to run the steps for you so when
+your source changes it will automatically run all of the appropriate steps.
+To aid this Verilator can create a makefile dependency file.  For examples
+that do this see the :file:`examples` directory in the distribution.

docs/guide/example_common_install.rst

@@ -0,0 +1,16 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+First you need Verilator installed, see :ref:`Installation`. In brief, if
+you installed Verilator using the package manager of your operating system,
+or did a :command:`make install` to place Verilator into your default path,
+you do not need anything special in your environment, and should not have
+VERILATOR_ROOT set.  However, if you installed Verilator from sources and
+want to run Verilator out of where you compiled Verilator, you need to
+point to the kit:
+
+.. code-block:: bash
+
+     # See above; don't do this if using an OS-distributed Verilator
+     export VERILATOR_ROOT=/path/to/where/verilator/was/installed
+     export PATH=$VERILATOR_ROOT/bin:$PATH

docs/guide/example_dist.rst

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

docs/guide/example_sc.rst

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

docs/guide/examples.rst

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

docs/guide/exe_sim.rst

@@ -0,0 +1,89 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+.. _Simulation Runtime Arguments:
+
+Simulation Runtime Arguments
+============================
+
+The following are the arguments that may be passed to a Verilated
+executable, provided that executable calls
+:code:`Verilated::commandArgs()`.
+
+All simulation runtime arguments begin with "+verilator", so that the
+user's executable may skip over all "+verilator" arguments when parsing its
+command line.
+
+Summary:
+
+   .. include:: ../_build/gen/args_verilated.rst
+
+
+.. option:: +verilator+debug
+
+   Enable simulation runtime debugging.  Equivalent to
+   :vlopt:`+verilator+debugi+4 <+verilator+debugi+\<value\>>`.
+
+.. option:: +verilator+debugi+<value>
+
+   Enable simulation runtime debugging at the provided level.
+
+.. option:: +verilator+error+limit+<value>
+
+   Set number of non-fatal errors (e.g. assertion failures) before exiting
+   simulation runtime. Also affects number of $stop calls needed before
+   exit. Defaults to 1.
+
+.. option:: +verilator+help
+
+   Display help and exit.
+
+.. option:: +verilator+prof+threads+file+<filename>
+
+   When a model was Verilated using :vlopt:`--prof-threads`, sets the
+   simulation runtime filename to dump to.  Defaults to
+   :file:`profile_threads.dat`.
+
+.. option:: +verilator+prof+threads+start+<value>
+
+   When a model was Verilated using :vlopt:`--prof-threads`, the simulation
+   runtime will wait until $time is at this value (expressed in units of
+   the time precision), then start the profiling warmup, then
+   capturing. Generally this should be set to some time that is well within
+   the normal operation of the simulation, i.e. outside of reset. If 0, the
+   dump is disabled. Defaults to 1.
+
+.. option:: +verilator+prof+threads+window+<value>
+
+   When a model was Verilated using :vlopt:`--prof-threads`, after $time
+   reaches :vlopt:`+verilator+prof+threads+start+\<value\>`, Verilator will
+   warm up the profiling for this number of eval() calls, then will capture
+   the profiling of this number of eval() calls.  Defaults to 2, which
+   makes sense for a single-clock-domain module where it's typical to want
+   to capture one posedge eval() and one negedge eval().
+
+.. option:: +verilator+rand+reset+<value>
+
+   When a model was Verilated using :vlopt:`--x-initial unique
+   <--x-initial>`, sets the simulation runtime initialization technique.  0
+   = Reset to zeros. 1 = Reset to all-ones.  2 = Randomize.  See
+   :ref:`Unknown States`.
+
+.. option:: +verilator+seed+<value>
+
+   For $random and :vlopt:`--x-initial unique <--x-initial>`, set the
+   simulation runtime random seed value.  If zero or not specified picks a
+   value from the system random number generator.
+
+.. option:: +verilator+noassert
+
+   Disable assert checking per runtime argument. This is the same as
+   calling :code:`Verilated::assertOn(false)` in the model.
+
+.. option:: +verilator+V
+
+   Shows the verbose version, including configuration information.
+
+.. option:: +verilator+version
+
+   Displays program version and exits.

docs/guide/exe_verilator_coverage.rst

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

docs/guide/exe_verilator_gantt.rst

@@ -0,0 +1,76 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+verilator_gantt
+===============
+
+Verilator_gantt creates a visual representation to help analyze Verilator
+multithreaded simulation performance, by showing when each macro-task
+starts and ends, and showing when each thread is busy or idle.
+
+For an overview of use of verilator_gantt, see :ref:`Profiling`.
+
+Gantt Chart Contents
+--------------------
+
+The generated Gantt chart has time on the X-axis. Times shown are to the
+scale printed, i.e. a certain about of time for each character width.  The
+Y-axis shows threads, each thread's execution is shown on one line.  That
+line shows "[" at the position in time when it executes.
+
+Following the "[" is the CPU number the task executed on, followed by zero
+or more "-" to make the width of the characters match the scaled execution
+time, followed by a "]".  If the scale is too small, the CPU number and
+mtask number will not be printed.  If the scale is very small, a "&"
+indicates multiple mtasks started at that time position.
+
+Also creates a value change dump (VCD) format dump file which may be viewed
+in a waveform viewer (e.g. C<GTKWave>).  See below.
+
+Gantt Chart VCD Signals
+-----------------------
+
+In waveforms there are the following signals. Most signals the "decimal"
+format will remove the leading zeros and make the traces easier to read.
+
+parallelism
+  The number of mtasks active at this time, for best performance this will
+  match the thread count. You may want to use an "analog step" format to
+  view this signal.
+
+cpu#_thread
+  For the given CPU number, the thread number executing.
+
+mtask#_cpu
+  For the given mtask id, the CPU it is executing on.
+
+thread#_mtask
+  For the given thread number, the mtask id executing.
+
+verilator_gantt Arguments
+-------------------------
+
+.. program:: verilator_gantt
+
+.. option:: <filename>
+
+The filename to read data from, defaults to "profile_threads.dat".
+
+.. option:: --help
+
+Displays a help summary, the program version, and exits.
+
+.. option:: --scale <n>
+
+Sets the number of time units per character on the X-axis of the generated
+Gantt chart.  (On x86, time units are rdtsc ticks.)  Defaults to 0, which
+will automatically compute a reasonable scale where no two mtasks need to
+fit into same character width's worth of scaled time.
+
+.. option:: --no-vcd
+
+Disables creating a .vcd file.
+
+.. option:: --vcd <filename>
+
+Sets the output filename for vcd dump. Default is "verilator_gantt.vcd".

docs/guide/exe_verilator_profcfuncs.rst

@@ -0,0 +1,25 @@
+.. Copyright 2003-2021 by Wilson Snyder.
+.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+verilator_profcfuncs
+====================
+
+Verilator_profcfunc reads a profile report created by gprof.  The names of
+the functions are then transformed, assuming the user used Verilator's
+--prof-cfuncs, and a report printed showing the percentage of time, etc, in
+each Verilog block.
+
+For an overview of use of verilator_profcfuncs, see :ref:`Profiling`.
+
+verilator_profcfuncs Arguments
+------------------------------
+
+.. program:: verilator_profcfuncs
+
+.. option:: <filename>
+
+The :command:`gprof`-generated filename to read data from. Typically "gprof.out".
+
+.. option:: --help
+
+Displays a help summary, the program version, and exits.

docs/guide/executables.rst

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

docs/guide/extensions.rst

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

docs/guide/faq.rst

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

docs/guide/files.rst

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

docs/guide/index.rst

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

docs/guide/install.rst

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

docs/guide/languages.rst

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

docs/guide/overview.rst

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

docs/guide/simulating.rst

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

docs/guide/verilating.rst

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

docs/install.adoc

@@ -1,305 +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 or run Verilator you need these standard packages:
-
-   sudo apt-get install perl python3 make
-   sudo apt-get install g++  # Alternatively, clang
-   sudo apt-get install libgz  # Non-Ubuntu (ignore if gives error)
-   sudo apt-get install libfl2 libfl-dev zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)
-
-To build or run the following are optional but should be installed for
-good performance:
-
-   sudo apt-get install ccache  # If present at build, needed for run
-   sudo apt-get install libgoogle-perftools-dev numactl
-
-To build Verilator you will need to install these packages; these do not
-need to be present to run Verilator:
-
-   sudo apt-get install git autoconf flex bison
-
-Those developing Verilator itself may also want these (see internals.adoc):
-
-   sudo apt-get install gdb asciidoctor graphviz cmake clang clang-format gprof lcov
-   cpan install Pod::Perldoc
-   cpan install Unix::Processors
-   cpan install Parallel::Forker
-   cpan install Bit::Vector
-
-==== Install SystemC
-
-If you will be using SystemC (vs straight C++ output), download
-https://www.accellera.org/downloads/standards/systemc[SystemC].
-Follow their installation instructions.  You will need to set `SYSTEMC_INCLUDE`
-to point to the include directory with `systemc.h` in it, and `SYSTEMC_LIBDIR`
-to points to the directory with `libsystemc.a` in it.  (Older installations
-may set `SYSTEMC` and `SYSTEMC_ARCH` instead.)
-
-==== Install GTKWave
-
-To make use of Verilator FST tracing you will want
-http://gtkwave.sourceforge.net/[GTKwave] installed, however this is not
-required at Verilator build time.
-
-=== Obtain Sources
-
-You may use Git or a tarball for the sources.  Git is the supported option.
-(If using a historical build that uses a tarball, tarballs are obtained
-from https://www.veripool.org/projects/verilator/wiki/Download[Verilator
-Downloads]; we presume you know how to use it, and is not described here.)
-
-Get the sources from the repository: (You need do this only once, ever.)
-
-   git clone https://git.veripool.org/git/verilator   # Only first time
-   ## Note the URL above is not a page you can see with a browser, it's for git only
-
-Enter the checkout and determine what version/branch to use:
-
-   cd verilator
-   git pull        # Make sure we're up-to-date
-   git tag         # See what versions exist
-   #git checkout master      # Use development branch (e.g. recent bug fix)
-   #git checkout stable      # Use most recent release
-   #git checkout v{version}  # Switch to specified release version
-
-=== Auto Configure
-
-Create the configuration script:
-
-   autoconf        # Create ./configure script
-
-=== Eventual Installation Options
-
-Before configuring the build, you have to decide how you're going to
-eventually install the kit.  Verilator will be compiling the current value
-of `VERILATOR_ROOT`, `SYSTEMC_INCLUDE`, and `SYSTEMC_LIBDIR` as defaults
-into the executable, so they must be correct before configuring.
-
-These are the options:
-
-==== 1. Run-in-Place from VERILATOR_ROOT
-
-Our personal favorite is to always run Verilator in-place from its Git
-directory.  This allows the easiest experimentation and upgrading, and
-allows many versions of Verilator to co-exist on a system.
-
-   export VERILATOR_ROOT=`pwd`   # if your shell is bash
-   setenv VERILATOR_ROOT `pwd`   # if your shell is csh
-   ./configure
-   # Running will use files from $VERILATOR_ROOT, so no install needed
-
-Note after installing (below steps), a calling program or shell must set
-the environment variable `VERILATOR_ROOT` to point to this Git directory,
-then execute `$VERILATOR_ROOT/bin/verilator`, which will find the path to
-all needed files.
-
-==== 2. Install into a CAD Disk
-
-You may eventually be installing onto a project/company-wide "CAD" tools
-disk that may support multiple versions of every tool.  Target the build to
-a destination directory name that includes the Verilator version name:
-
-   unset VERILATOR_ROOT      # if your shell is bash
-   unsetenv VERILATOR_ROOT   # if your shell is csh
-   # For the tarball, use the version number instead of git describe
-   ./configure --prefix /CAD_DISK/verilator/`git describe | sed "s/verilator_//"`
-
-Note after installing (below steps), if you use
-http://modules.sourceforge.net/[modulecmd], you'll want a module file like
-the following:
-
-.modulecmd's verilator/version file
-----
-set install_root /CAD_DISK/verilator/{version-number-used-above}
-unsetenv VERILATOR_ROOT
-prepend-path PATH $install_root/bin
-prepend-path MANPATH $install_root/man
-prepend-path PKG_CONFIG_PATH $install_root/share/pkgconfig
-----
-
-==== 3. Install into a Specific Path
-
-You may eventually install Verilator into a specific installation prefix,
-as most GNU tools support:
-
-   unset VERILATOR_ROOT      # if your shell is bash
-   unsetenv VERILATOR_ROOT   # if your shell is csh
-   ./configure --prefix /opt/verilator-VERSION
-
-Then after installing (below steps) you will need to add
-`/opt/verilator-VERSION/bin` to `$PATH`.
-
-==== 4. Install System Globally
-
-The final option is to eventually install Verilator globally, using the
-normal system paths:
-
-   unset VERILATOR_ROOT      # if your shell is bash
-   unsetenv VERILATOR_ROOT   # if your shell is csh
-   ./configure
-
-Then after installing (below) the binary directories should already be in
-your `$PATH`.
-
-=== Configure
-
-The command to configure the package was described in the previous step.
-Developers should configure to have more complete developer tests.
-Additional packages may be required for these tests.
-
-   export VERILATOR_AUTHOR_SITE=1    # Put in your .bashrc
-   ./configure --enable-longtests  ...above options...
-
-=== Compile
-
-Compile Verilator:
-
-   make -j
-
-=== Test
-
-Check the compilation by running self-tests:
-
-   make test
-
-=== Install
-
-If you used any but the <<1. Run-in-Place from VERILATOR_ROOT>> scheme,
-install to the OS-standard place:
-
-   make install
-
-== Running Verilator
-
-To run Verilator, see the example sections in the
-https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
-or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-Also see the `examples/` directory that is part of the kit, and is installed
-(in a OS-specific place, often in e.g. `/usr/local/share/verilator/examples`).
-
-     cd examples/make_hello_c
-     make
-
-Note if you did a `make install` above you should not have `VERILATOR_ROOT`
-set in your environment; it is built into the executable.
-
-== Announcements
-
-To get notified of new releases, go to
-https://github.com/verilator/verilator-announce[Verilator announcement
-repository] and follow the instructions there.
-
-== Directory Structure
-
-Some relevant files and directories in this package are as follows:
-
-   Changes                     => Version history
-   README.adoc                 => This document
-   bin/verilator               => Compiler wrapper invoked to Verilate code
-   docs/                       => Additional documentation
-   examples/make_hello_c       => Example GNU-make simple Verilog->C++ conversion
-   examples/make_hello_sc      => Example GNU-make simple Verilog->SystemC conversion
-   examples/make_tracing_c     => Example GNU-make Verilog->C++ with tracing
-   examples/make_tracing_sc    => Example GNU-make Verilog->SystemC with tracing
-   examples/make_protect_lib   => Example using --protect-lib
-   examples/cmake_hello_c      => Example building make_hello_c with CMake
-   examples/cmake_hello_sc     => Example building make_hello_sc with CMake
-   examples/cmake_tracing_c    => Example building make_tracing_c with CMake
-   examples/cmake_tracing_sc   => Example building make_tracing_sc with CMake
-   examples/cmake_protect_lib  => Example building make_protect_lib with CMake
-   include/                    => Files that should be in your -I compiler path
-   include/verilated*.cpp      => Global routines to link into your simulator
-   include/verilated*.h        => Global headers
-   include/verilated.mk        => Common Makefile
-   src/                        => Translator source code
-   test_regress                => Internal tests
-
-For files created after a design is Verilated, see the
-https://verilator.org/verilator_doc.html[Verilator manual (HTML)],
-or https://verilator.org/verilator_doc.pdf[Verilator manual (PDF)].
-
-== License
-
-Copyright 2008-2020 by Wilson Snyder.  Verilator is free software; you can
-redistribute it and/or modify it under the terms of either the GNU Lesser
-General Public License Version 3 or the Perl Artistic License Version 2.0.
-// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0