Version bump

Commentary: Changes update
Fix use-after-free of captured interface typedef in deleted generate branch (#8287 )
2026-10-02 16:13:34 +02:00 · 2026-09-05 08:28:17 -04:00 · 2026-09-05 08:27:32 -04:00 · 2026-09-04 14:27:11 -04:00 · 2026-09-04 11:01:10 -04:00 · 2026-09-04 11:00:10 -04:00
2324 changed files with 220297 additions and 36212 deletions
@@ -1,4 +1,4 @@
-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,-llvmlibc-*,-altera-*,-boost-use-ranges'
+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-do-while,-cppcoreguidelines-avoid-magic-numbers,-cppcoreguidelines-macro-usage,-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,-llvmlibc-*,-altera-*,-boost-use-ranges'
 WarningsAsErrors: ''
 HeaderFilterRegex: ''
 FormatStyle:     none
@@ -0,0 +1,2 @@
+---
+blank_issues_enabled: false
@@ -7,18 +7,34 @@ assignees: ''

 ---

+<!--
 Thanks for taking the time to report this.

-Can you please attach an example that shows the issue or missing feature?  (Must be openly licensed, completely self-contained so can directly run what you provide. Ideally use test_regress format, see https://veripool.org/guide/latest/contributing.html?highlight=test_regress#reporting-bugs)
+Please avoid attaching screenshots that show text - you can convert images to text using e.g. https://ocr.space
+
+Please remove this block when composing, and all other blocks starting with < !--.
+-->
+
+Can you please attach an example that shows the issue or missing feature?
+
+<!-- Please replace this with your answer. Examples must be openly licensed, completely self-contained so can directly run what you provide. Ideally use test_regress format, see https://veripool.org/guide/latest/contributing.html?highlight=test_regress#reporting-bugs -->

 What output from that test indicates it is wrong, and what is the correct or expected output?  (Or, please make test self-checking if possible.)

+<!-- Please replace this with your answer -->
+
 What 'verilator' command line do we use to run your example?

+<!-- Please replace this with your answer -->
+
 What 'verilator --version' are you using?  Did you try it with the git master version?  Did you try it with other simulators?

+<!-- Please replace this with your answer -->
+
 What OS and distribution are you using?

+<!-- Please replace this with your answer -->
+
 May we assist you in trying to fix this in Verilator yourself?

-(Please avoid attaching screenshots that show text - you can convert images to text using e.g. https://ocr.space)
+<!-- Please replace this with your answer - then hit "Preview" to see the formatted result before submitting.  -->
@@ -7,6 +7,14 @@ assignees: ''

 ---

+<!--
+Thanks for taking the time to report this.
+
+If reporting a bug or requesting a feature please hit BACK on your browser and use a different issue templates.
+
+Please remove this block when composing, and all other blocks starting with < !--.
+-->
+
 How may we help - what is your question?

-(If reporting a bug or requesting a feature please hit BACK on your browser and use a different issue templates.)
+<!-- Please replace this with your answer - then hit "Preview" to see the formatted result before submitting. -->
@@ -0,0 +1,165 @@
+---
+# DESCRIPTION: Github actions composite action
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Artifact cache
+description: >-
+  Cache a directory across workflow runs using a GitHub Actions artifact instead
+  of actions/cache (useful where artifacts are preferable, e.g. no 10 GB limit
+  on public repos). The base 'key' is scoped automatically: per pull request
+  (<key>-pr-<N>) or per branch (<key>-branch-<name>), and on a PR restore falls
+  back to the target branch's cache. Call once with mode=restore before the work
+  and once with mode=save after, passing the same 'key' and 'path'.
+
+  Branch-scoped restores are provenance-checked (the artifact must come from a
+  same-repo push to that branch) - artifact names are a global, unauthenticated
+  namespace, so otherwise a fork PR could forge one.
+
+  mode=restore calls the GitHub API via 'gh', so the caller's job must grant
+  'actions: read'.
+
+inputs:
+  mode:
+    description: "'restore' or 'save'"
+    required: true
+  path:
+    description: "Directory to cache (archived on save, extracted into on restore)"
+    required: true
+  key:
+    description: "Base artifact name; scoped per PR/branch automatically"
+    required: true
+  retention-days:
+    description: "Artifact retention in days (mode=save)"
+    required: false
+    default: '3'
+  token:
+    description: "Token for the GitHub API (mode=restore); defaults to the job's GITHUB_TOKEN"
+    required: false
+    default: ''
+
+outputs:
+  key:
+    description: "Echoes the input 'key', so a later save can reuse it without repeating the expression"
+    value: ${{ inputs.key }}
+  cache-hit:
+    description: "'true' if an artifact was restored (mode=restore)"
+    value: ${{ steps.restore.outputs.cache-hit }}
+
+runs:
+  using: composite
+  steps:
+    - name: Check mode
+      shell: bash
+      env:
+        MODE: ${{ inputs.mode }}
+      run: |
+        case "$MODE" in
+          restore|save) ;;
+          *) echo "::error::artifact-cache: 'mode' must be 'restore' or 'save' (got '$MODE')"; exit 1 ;;
+        esac
+
+    # Scope the base key: <key>-pr-<N> for pull requests (with the target branch
+    # as fallback), else <key>-branch-<name>. Refs come via env, not ${{ }}
+    # interpolation, so a branch name with shell metacharacters can't inject.
+    - name: Compute artifact name
+      id: name
+      shell: bash
+      env:
+        BASE_KEY: ${{ inputs.key }}
+        EVENT_NAME: ${{ github.event_name }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+        BASE_REF: ${{ github.event.pull_request.base.ref }}
+        REF_NAME: ${{ github.ref_name }}
+      run: |
+        set -euo pipefail
+        sanitize() { printf '%s' "$1" | tr '/' '-'; }  # artifact names cannot contain '/'
+        if [ "$EVENT_NAME" = pull_request ]; then
+          {
+            echo "primary=${BASE_KEY}-pr-${PR_NUMBER}"
+            echo "primary-branch="
+            echo "fallback=${BASE_KEY}-branch-$(sanitize "$BASE_REF")"
+            echo "fallback-branch=$BASE_REF"
+          } >> "$GITHUB_OUTPUT"
+        else
+          {
+            echo "primary=${BASE_KEY}-branch-$(sanitize "$REF_NAME")"
+            echo "primary-branch=$REF_NAME"
+            echo "fallback="
+            echo "fallback-branch="
+          } >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Restore artifact cache
+      id: restore
+      if: ${{ inputs.mode == 'restore' }}
+      continue-on-error: true  # a cold start is fine; a restore failure must not fail the caller
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token || github.token }}
+        CACHE_PATH: ${{ inputs.path }}
+        PRIMARY: ${{ steps.name.outputs.primary }}
+        PRIMARY_BRANCH: ${{ steps.name.outputs.primary-branch }}
+        FALLBACK: ${{ steps.name.outputs.fallback }}
+        FALLBACK_BRANCH: ${{ steps.name.outputs.fallback-branch }}
+      run: |
+        set -euo pipefail
+        mkdir -p "$CACHE_PATH"
+        # Newest non-expired artifact named $1 (empty if none). With a non-empty
+        # $2 (branch), require provenance: a same-repo run (head_repository_id ==
+        # repository_id) whose head branch is $2, so a fork cannot forge it.
+        newest_run_id() {
+          want="$1" br="$2" gh api \
+            "/repos/$GITHUB_REPOSITORY/actions/artifacts?name=$1&per_page=100" \
+            --jq '.artifacts[]
+                  | select(.expired == false and .name == env.want)
+                  | select(env.br == ""
+                           or (.workflow_run.head_branch == env.br
+                               and .workflow_run.head_repository_id == .workflow_run.repository_id))
+                  | [.created_at, (.workflow_run.id | tostring)] | @tsv' \
+            | sort | tail -n1 | cut -f2
+        }
+        restore() {  # $1=name $2=branch(empty ok); returns 0 on a successful restore
+          local name="$1" br="$2" rid tarball
+          [ -n "$name" ] || return 1
+          rid="$(newest_run_id "$name" "$br")" || return 1
+          [ -n "$rid" ] || return 1
+          echo "Restoring '$CACHE_PATH' from artifact '$name' (run $rid)"
+          gh run download "$rid" -R "$GITHUB_REPOSITORY" --name "$name" --dir "$RUNNER_TEMP/artifact-cache-dl" || return 1
+          # Each artifact holds a single tarball; match by extension so the inner
+          # filename is not part of the contract.
+          tarball="$(find "$RUNNER_TEMP/artifact-cache-dl" -name '*.tar.zst' -print -quit)"
+          [ -n "$tarball" ] || return 1
+          tar -I zstd -x -f "$tarball" -C "$CACHE_PATH"
+        }
+        if restore "$PRIMARY" "$PRIMARY_BRANCH"; then
+          echo "Restored from primary key"
+          echo "cache-hit=true" >> "$GITHUB_OUTPUT"
+        elif restore "$FALLBACK" "$FALLBACK_BRANCH"; then
+          echo "Restored from fallback key"
+          echo "cache-hit=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "No matching artifact found; starting cold"
+          echo "cache-hit=false" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Pack artifact cache
+      id: pack
+      if: ${{ inputs.mode == 'save' }}
+      shell: bash
+      env:
+        CACHE_PATH: ${{ inputs.path }}
+      run: |
+        set -euo pipefail
+        packdir="$(mktemp -d)"  # unique dir so concurrent saves cannot collide
+        tar -I 'zstd -T0' -cf "$packdir/cache.tar.zst" -C "$CACHE_PATH" .
+        echo "tarball=$packdir/cache.tar.zst" >> "$GITHUB_OUTPUT"
+
+    - name: Upload artifact cache
+      if: ${{ inputs.mode == 'save' }}
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+      with:
+        name: ${{ steps.name.outputs.primary }}
+        path: ${{ steps.pack.outputs.tarball }}
+        retention-days: ${{ inputs.retention-days }}
+        overwrite: true
+        compression-level: 0  # tarball is already zstd-compressed
@@ -0,0 +1,109 @@
+---
+# DESCRIPTION: Github actions composite action
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Install dependencies
+description: >-
+  Install the dependencies of a CI stage with 'ci/ci-install.bash', caching the
+  '.deb' files apt downloads for that stage, so a package is fetched from the
+  network at most once per runner image. On hosts that do not use apt this is
+  just the install, there is nothing to cache.
+
+inputs:
+  repo:
+    description: "Verilator checkout holding the ci/ scripts"
+    required: false
+    default: repo
+  stage:
+    description: "CI stage to install the dependencies of, e.g. 'build'"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Compute apt cache key
+      id: cachekey
+      if: ${{ runner.os == 'Linux' }}
+      shell: bash
+      working-directory: ${{ inputs.repo }}
+      env:
+        STAGE: ${{ inputs.stage }}
+      run: |
+        source ci/ci-common.bash
+        host="${DISTRO_ID:-$HOST_OS}${DISTRO_VERSION:+-$DISTRO_VERSION}"
+        echo "key=apt-${host}-${STAGE}" >> "$GITHUB_OUTPUT"
+
+    - name: Restore apt downloads
+      if: ${{ runner.os == 'Linux' }}
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
+      with:
+        path: ${{ runner.temp }}/apt-cache
+        key: ${{ steps.cachekey.outputs.key }}
+        restore-keys: |
+          ${{ steps.cachekey.outputs.key }}-
+
+    - name: Seed apt archive from cache
+      if: ${{ runner.os == 'Linux' }}
+      shell: bash
+      env:
+        APT_CACHE_DIR: ${{ runner.temp }}/apt-cache
+      run: |
+        set -euo pipefail
+        # Ask apt where it keeps its downloads, rather than assume
+        eval "$(apt-config shell ARCHIVES Dir::Cache::archives/d)"
+        ARCHIVES=${ARCHIVES%/}  # '/d' yields a trailing slash
+        # Wipe the archive first, so that whatever the runner image left behind is not stored
+        sudo apt-get -o DPkg::Lock::Timeout=60 clean
+        # The directory is absent when nothing was restored, e.g. on a cold start
+        if [ -d "$APT_CACHE_DIR" ] &&
+          [ -n "$(find "$APT_CACHE_DIR" -maxdepth 1 -name '*.deb' -print -quit)" ]; then
+          sudo cp "$APT_CACHE_DIR"/*.deb "$ARCHIVES"
+        fi
+
+    - name: Install dependencies
+      shell: bash
+      working-directory: ${{ inputs.repo }}
+      env:
+        STAGE: ${{ inputs.stage }}
+      run: ./ci/ci-install.bash "$STAGE"
+
+    - name: Collect apt downloads
+      id: collect
+      if: ${{ runner.os == 'Linux' }}
+      shell: bash
+      env:
+        APT_CACHE_DIR: ${{ runner.temp }}/apt-cache
+      run: |
+        set -euo pipefail
+        # Ask apt where it keeps its downloads, rather than assume
+        eval "$(apt-config shell ARCHIVES Dir::Cache::archives/d)"
+        ARCHIVES=${ARCHIVES%/}  # '/d' yields a trailing slash
+        # Sorted names of the '.deb' files in a directory, empty if it has none
+        list-debs() {
+          [ -d "$1" ] || return 0
+          find "$1" -maxdepth 1 -name '*.deb' -printf '%f\n' | sort
+        }
+        # Superseded downloads can no longer be fetched, so drop them
+        sudo apt-get -o DPkg::Lock::Timeout=60 autoclean
+        downloaded=$(list-debs "$ARCHIVES")
+        if [ -z "$downloaded" ]; then
+          echo "Apt kept no '.deb' files, nothing to cache"
+          exit 0
+        fi
+        if [ "$downloaded" = "$(list-debs "$APT_CACHE_DIR")" ]; then
+          echo "Downloads unchanged, keeping the restored cache entry"
+          exit 0
+        fi
+        # Mirror the archive, rather than add to it, so that the cache cannot
+        # grow without bound as package versions churn
+        mkdir -p "$APT_CACHE_DIR"
+        rm -f "$APT_CACHE_DIR"/*.deb
+        sudo cp "$ARCHIVES"/*.deb "$APT_CACHE_DIR"
+        echo "changed=true" >> "$GITHUB_OUTPUT"
+
+    - name: Save apt downloads
+      if: ${{ steps.collect.outputs.changed == 'true' }}
+      uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
+      with:
+        path: ${{ runner.temp }}/apt-cache
+        key: ${{ steps.cachekey.outputs.key }}-${{ github.run_id }}
@@ -0,0 +1,56 @@
+---
+# DESCRIPTION: Github actions composite action
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Set up Python venv
+description: >-
+  Restore, create, and optionally save the make-managed Python venv in a GitHub
+  Actions cache. The cache key combines the venv path (venvs are not
+  relocatable), the host OS and version, the Python major.minor version, and
+  the python-dev-requirements.txt hash, so any of those changing invalidates
+  it. Requires the already-configured Verilator tree to be present in 'repo'.
+
+inputs:
+  repo:
+    description: "Verilator checkout holding the Makefile and .venv"
+    required: false
+    default: repo
+  save:
+    description: "Save the cache on a miss (set true only on trusted branches)"
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - name: Compute Python venv cache key
+      id: cachekey
+      shell: bash
+      working-directory: ${{ inputs.repo }}
+      run: |
+        source ci/ci-common.bash
+        host="${DISTRO_ID:-$HOST_OS}${DISTRO_VERSION:+-$DISTRO_VERSION}"
+        pyver="$(python3 -c 'import sys; print("%d.%d" % sys.version_info[:2])')"
+        reqs="$(sha256sum python-dev-requirements.txt | cut -d' ' -f1)"
+        venv="${PWD#/}/.venv"  # absolute venv path (leading '/' trimmed)
+        echo "key=venv-${host}-py${pyver}-${reqs}-${venv//\//-}" >> "$GITHUB_OUTPUT"
+
+    - name: Restore Python venv
+      id: venv
+      uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
+      with:
+        path: ${{ inputs.repo }}/.venv
+        key: ${{ steps.cachekey.outputs.key }}
+
+    - name: Create Python venv
+      if: ${{ steps.venv.outputs.cache-hit != 'true' }}
+      shell: bash
+      working-directory: ${{ inputs.repo }}
+      run: make venv
+
+    - name: Save Python venv
+      if: ${{ inputs.save == 'true' && steps.venv.outputs.cache-hit != 'true' }}
+      uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
+      with:
+        path: ${{ inputs.repo }}/.venv
+        key: ${{ steps.venv.outputs.cache-primary-key }}
@@ -0,0 +1,74 @@
+---
+# DESCRIPTION: Github actions composite action
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Upload PR notification
+description: >-
+  Upload the 'pr-notification' artifact, holding a comment for 'pages.yml' to
+  post on a pull request. The given directory must hold the content of the
+  comment in 'body.txt', and its single line summary in 'hist.txt'.
+
+inputs:
+  path:
+    description: "Directory holding the notification contents"
+    required: true
+  key:
+    description: "Unique key for combining comments"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Validate
+      shell: bash
+      env:
+        NOTIFICATION_DIR: ${{ inputs.path }}
+        EVENT_NAME: ${{ github.event_name }}
+      run: |
+        # The notification is posted on the pull request of the triggering event
+        if [ "${EVENT_NAME}" != "pull_request" ]; then
+          echo "This action can only be used on a 'pull_request' run, but event is '${EVENT_NAME}'" >&2
+          exit 1
+        fi
+        # The content of the comment, and its single line summary
+        for f in body.txt hist.txt; do
+          if [ ! -f "${NOTIFICATION_DIR}/${f}" ]; then
+            echo "No '${f}' in '${NOTIFICATION_DIR}'" >&2
+            exit 1
+          fi
+        done
+        # Nothing else, so the artifact holds only what this action puts in it
+        EXTRA=$(find "${NOTIFICATION_DIR}" -mindepth 1 -not -name body.txt -not -name hist.txt)
+        if [ -n "${EXTRA}" ]; then
+          echo "Unexpected content in '${NOTIFICATION_DIR}':" >&2
+          echo "${EXTRA}" >&2
+          exit 1
+        fi
+        # 'ci-pages-notify.bash' stashes 'hist.txt' in an HTML comment, and later
+        # shows it in the history of the notifications superseding this one, so
+        # it must be a single line, and must neither open nor close an HTML comment
+        if [ $(wc -l < "${NOTIFICATION_DIR}/hist.txt") -ne 1 ]; then
+          echo "'hist.txt' must hold exactly one line" >&2
+          exit 1
+        fi
+        if grep -q -e '<!--' -e '-->' "${NOTIFICATION_DIR}/hist.txt"; then
+          echo "'hist.txt' must not contain '<!--' or '-->'" >&2
+          exit 1
+        fi
+
+    - name: Add metadata
+      shell: bash
+      env:
+        NOTIFICATION_DIR: ${{ inputs.path }}
+        NOTIFICATION_KEY: ${{ inputs.key }}
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+      run: |
+        echo "${NOTIFICATION_KEY}" > "${NOTIFICATION_DIR}/key.txt"
+        echo "${PR_NUMBER}" > "${NOTIFICATION_DIR}/pr-number.txt"
+        ls -lsha "${NOTIFICATION_DIR}"
+
+    - name: Upload notification
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+      with:
+        path: ${{ inputs.path }}
+        name: pr-notification
@@ -1,9 +1,8 @@
 ---
 # 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-test
+name: Regressions

 on:
  push:
@@ -16,6 +15,7 @@ on:

 permissions:
  contents: read
+  actions: read

 defaults:
  run:
@@ -28,259 +28,143 @@ concurrency:

 jobs:

-  build-2404-gcc:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
+  build-2604-gcc:
+    name: Build | 26.04 | gcc
    uses: ./.github/workflows/reusable-build.yml
    with:
+      cc: gcc
+      runs-on: ubuntu-26.04
+      sha: ${{ github.sha }}
+
+  build-2604-clang:
+    name: Build | 26.04 | clang
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: clang
+      dev-asan: true  # Build (and run) with address sanitizer
+      runs-on: ubuntu-26.04
+      sha: ${{ github.sha }}
+
+  build-2404-gcc:
+    name: Build | 24.04 | gcc
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: gcc
+      runs-on: ubuntu-24.04
      sha: ${{ github.sha }}
-      os: ${{ matrix.os }}
-      os-name: linux
-      cc: ${{ matrix.cc }}
-      dev-asan: ${{ matrix.asan }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: ubuntu-24.04, cc: gcc, asan: 0}

  build-2404-clang:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
+    name: Build | 24.04 | clang
    uses: ./.github/workflows/reusable-build.yml
    with:
+      cc: clang
+      runs-on: ubuntu-24.04
      sha: ${{ github.sha }}
-      os: ${{ matrix.os }}
-      os-name: linux
-      cc: ${{ matrix.cc }}
-      dev-asan: ${{ matrix.asan }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: ubuntu-24.04, cc: clang, asan: 1}

  build-2204-gcc:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
+    name: Build | 22.04 | gcc
    uses: ./.github/workflows/reusable-build.yml
    with:
+      cc: gcc
+      runs-on: ubuntu-22.04
      sha: ${{ github.sha }}
-      os: ${{ matrix.os }}
-      os-name: linux
-      cc: ${{ matrix.cc }}
-      dev-asan: ${{ matrix.asan }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: ubuntu-22.04, cc: gcc, asan: 0}

-  build-2204-clang:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
+  build-macos-15-clang:
+    name: Build | macos-15 | clang
    uses: ./.github/workflows/reusable-build.yml
    with:
+      cc: clang
+      runs-on: macos-15
      sha: ${{ github.sha }}
-      os: ${{ matrix.os }}
-      os-name: linux
-      cc: ${{ matrix.cc }}
-      dev-asan: ${{ matrix.asan }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: ubuntu-22.04, cc: clang, asan: 0}
-
-  build-osx-gcc:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
-    uses: ./.github/workflows/reusable-build.yml
-    with:
-      sha: ${{ github.sha }}
-      os: ${{ matrix.os }}
-      os-name: osx
-      cc: ${{ matrix.cc }}
-      dev-asan: ${{ matrix.asan }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: macos-15, cc: gcc, asan: 0}
-
-  build-osx-clang:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
-    uses: ./.github/workflows/reusable-build.yml
-    with:
-      sha: ${{ github.sha }}
-      os: ${{ matrix.os }}
-      os-name: osx
-      cc: ${{ matrix.cc }}
-      dev-asan: ${{ matrix.asan }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: macos-15, cc: clang, asan: 0}

  build-windows:
-    name: Build | ${{ matrix.os }} | ${{ matrix.cc }}
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - {os: windows-2025, cc: msvc}
-    env:
-      CI_OS_NAME: win
-      CCACHE_COMPRESS: 1
-      CCACHE_DIR: ${{ github.workspace }}/.ccache
-      CCACHE_LIMIT_MULTIPLE: 0.95
+    name: Build | windows-2025-vs2026 | msvc
+    runs-on: windows-2025-vs2026
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          path: repo
-      - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
+      - name: Cache win_flex_bison
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
        with:
-          path: ${{ env.CCACHE_DIR }}
-          key: msbuild-msvc-cmake
+          path: ${{ github.workspace }}/win_flex_bison
+          key: win_flex_bison
      - name: compile
-        env:
-          WIN_FLEX_BISON: ${{ github.workspace }}/.ccache
        run: ./ci/ci-win-compile.ps1
      - name: test build
        run: ./ci/ci-win-test.ps1
-      - name: Zip up repository
-        run: Compress-Archive -LiteralPath install -DestinationPath verilator.zip
-      - name: Upload zip archive
-        uses: actions/upload-artifact@v7
-        with:
-          path: ${{ github.workspace }}/repo/verilator.zip
-          name: verilator-win.zip
+
+  test-2604-gcc:
+    name: Test | 26.04 | gcc | ${{ matrix.suite }}
+    needs: build-2604-gcc
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      archive: ${{ needs.build-2604-gcc.outputs.archive }}
+      cc: gcc
+      runs-on: ubuntu-26.04
+      suite: ${{ matrix.suite }}
+    strategy:
+      fail-fast: false
+      matrix:
+        suite: [dist-vlt-0, dist-vlt-1, dist-vlt-2, dist-vlt-3, vltmt-0, vltmt-1, vltmt-2]
+
+  test-2604-clang:
+    name: Test | 26.04 | clang | ${{ matrix.suite }}
+    needs: build-2604-clang
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      archive: ${{ needs.build-2604-clang.outputs.archive }}
+      cc: clang
+      runs-on: ubuntu-26.04
+      suite: ${{ matrix.suite }}
+    strategy:
+      fail-fast: false
+      matrix:
+        suite: [dist-vlt-0, dist-vlt-1, dist-vlt-2, dist-vlt-3, vltmt-0, vltmt-1, vltmt-2]

  test-2404-gcc:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
+    name: Test | 24.04 | gcc | ${{ matrix.suite }}
    needs: build-2404-gcc
    uses: ./.github/workflows/reusable-test.yml
    with:
      archive: ${{ needs.build-2404-gcc.outputs.archive }}
-      os: ${{ matrix.os }}
-      cc: ${{ matrix.cc }}
-      reloc: ${{ matrix.reloc }}
+      cc: gcc
+      runs-on: ubuntu-24.04
      suite: ${{ matrix.suite }}
-      dev-gcov: 0
    strategy:
      fail-fast: false
      matrix:
-        include:
-          # Ubuntu 24.04 gcc
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: dist-vlt-0}
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: dist-vlt-1}
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: dist-vlt-2}
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: dist-vlt-3}
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: vltmt-0}
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: vltmt-1}
-          - {os: ubuntu-24.04, cc: gcc, reloc: 0, suite: vltmt-2}
+        suite: [dist-vlt-0, dist-vlt-1, dist-vlt-2, dist-vlt-3, vltmt-0, vltmt-1, vltmt-2]

  test-2404-clang:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
+    name: Test | 24.04 | clang | ${{ matrix.suite }}
    needs: build-2404-clang
    uses: ./.github/workflows/reusable-test.yml
    with:
      archive: ${{ needs.build-2404-clang.outputs.archive }}
-      os: ${{ matrix.os }}
-      cc: ${{ matrix.cc }}
-      reloc: ${{ matrix.reloc }}
+      cc: clang
+      reloc: true  # Test with relocated installation
+      runs-on: ubuntu-24.04
      suite: ${{ matrix.suite }}
-      dev-gcov: 0
    strategy:
      fail-fast: false
      matrix:
-        include:
-          # Ubuntu 24.04 clang
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: dist-vlt-0}
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: dist-vlt-1}
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: dist-vlt-2}
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: dist-vlt-3}
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: vltmt-0}
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: vltmt-1}
-          - {os: ubuntu-24.04, cc: clang, reloc: 0, suite: vltmt-2}
+        suite: [dist-vlt-0, dist-vlt-1, dist-vlt-2, dist-vlt-3, vltmt-0, vltmt-1, vltmt-2]

  test-2204-gcc:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
+    name: Test | 22.04 | gcc | ${{ matrix.suite }}
    needs: build-2204-gcc
    uses: ./.github/workflows/reusable-test.yml
    with:
      archive: ${{ needs.build-2204-gcc.outputs.archive }}
-      os: ${{ matrix.os }}
-      cc: ${{ matrix.cc }}
-      reloc: ${{ matrix.reloc }}
+      cc: gcc
+      runs-on: ubuntu-22.04
      suite: ${{ matrix.suite }}
-      dev-gcov: 0
    strategy:
      fail-fast: false
      matrix:
-        include:
-          # Ubuntu 22.04 gcc
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: dist-vlt-0}
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: dist-vlt-1}
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: dist-vlt-2}
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: dist-vlt-3}
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: vltmt-0}
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: vltmt-1}
-          - {os: ubuntu-22.04, cc: gcc, reloc: 0, suite: vltmt-2}
-
-  test-2204-clang:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
-    needs: build-2204-clang
-    uses: ./.github/workflows/reusable-test.yml
-    with:
-      archive: ${{ needs.build-2204-clang.outputs.archive }}
-      os: ${{ matrix.os }}
-      cc: ${{ matrix.cc }}
-      reloc: ${{ matrix.reloc }}
-      suite: ${{ matrix.suite }}
-      dev-gcov: 0
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          # Ubuntu 22.04 clang, also test relocation
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: dist-vlt-0}
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: dist-vlt-1}
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: dist-vlt-2}
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: dist-vlt-3}
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: vltmt-0}
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: vltmt-1}
-          - {os: ubuntu-22.04, cc: clang, reloc: 1, suite: vltmt-2}
+        suite: [dist-vlt-0, dist-vlt-1, dist-vlt-2, dist-vlt-3, vltmt-0, vltmt-1, vltmt-2]

  lint-py:
    name: Lint Python
    uses: ./.github/workflows/reusable-lint-py.yml
-
-  passed:
-    name: Test suite passed
-    if: always()
-    needs:
-      - build-2404-gcc
-      - build-2404-clang
-      - build-2204-gcc
-      - build-2204-clang
-      - build-osx-gcc
-      - build-osx-clang
-      - build-windows
-      - test-2404-gcc
-      - test-2404-clang
-      - test-2204-gcc
-      - test-2204-clang
-      - lint-py
-
-    runs-on: ubuntu-24.04
-
-    steps:
-      - name: Decide whether the needed jobs succeeded or failed
-        uses: re-actors/alls-green@release/v1
-        with:
-          jobs: ${{ toJSON(needs) }}
@@ -16,5 +16,5 @@ jobs:
    name: "'docs/CONTRIBUTORS' was signed"
    runs-on: ubuntu-24.04
    steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
      - run: test_regress/t/t_dist_contributors.py
@@ -13,6 +13,7 @@ on:

 permissions:
  contents: read
+  actions: read

 defaults:
  run:
@@ -38,15 +39,13 @@ jobs:
      (github.event_name == 'workflow_dispatch')
    uses: ./.github/workflows/reusable-build.yml
    with:
+      cc: gcc
+      dev-gcov: true
+      runs-on: ubuntu-24.04
      # For pull requests, build the head of the pull request branch, not the
      # merge commit, otherwise patch coverage would include the changes
      # between the root of the pull request and the target branch
      sha: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-      os: ubuntu-24.04
-      os-name: linux
-      cc: gcc
-      dev-asan: 0
-      dev-gcov: 1

  test:
    name: Test | ${{ matrix.test }}${{ matrix.num }}
@@ -54,11 +53,10 @@ jobs:
    uses: ./.github/workflows/reusable-test.yml
    with:
      archive: ${{ needs.build.outputs.archive }}
-      os: ubuntu-24.04
      cc: gcc
-      reloc: 0
+      dev-gcov: true
+      runs-on: ubuntu-24.04
      suite: ${{ matrix.test }}${{ matrix.num }}
-      dev-gcov: 1
    strategy:
      fail-fast: false
      matrix:
@@ -74,10 +72,10 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7

      - name: Download code coverage data
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          pattern: code-coverage-*
          path: obj_coverage
@@ -90,7 +88,7 @@ jobs:
          find obj_coverage -type f | paste -sd, | sed "s/^/files=/" >> "$GITHUB_OUTPUT"

      - name: Upload to codecov.io
-        uses: codecov/codecov-action@v6
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7
        with:
          disable_file_fixes: true
          disable_search: true
@@ -106,26 +104,24 @@ jobs:
    if: ${{ contains(needs.*.result, 'success') && !cancelled() }}
    runs-on: ubuntu-24.04
    steps:
-      - name: Install dependencies
-        run: |
-          echo 'set man-db/auto-update false' | sudo debconf-communicate >/dev/null
-          sudo dpkg-reconfigure man-db
-          sudo apt install lcov || \
-          sudo apt install lcov
-
      - name: Download repository archive
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          name: ${{ needs.build.outputs.archive }}
          path: ${{ github.workspace }}

      - name: Unpack repository archive
        run: |
-          tar -x -z -f ${{ needs.build.outputs.archive }}
+          tar --zstd -x -f ${{ needs.build.outputs.archive }}
          ls -lsha

+      - name: Install dependencies
+        uses: ./repo/.github/actions/install-deps
+        with:
+          stage: coverage
+
      - name: Download code coverage data
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          pattern: code-coverage-*
          path: repo/obj_coverage
@@ -136,51 +132,30 @@ jobs:
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
-          ls -lsha obj_coverage
-          # Combine reports from test jobs
-          nodist/fastcov.py -C obj_coverage/verilator-*.info --lcov -o obj_coverage/verilator.info
-          # For a PR, report patch coverage against the merge-base between the head of the PR and the target branch
+          ci/ci-coverage-report.bash \
+            ${{ github.run_id }} \
+            "${{ github.event_name == 'pull_request' && github.event.number || '' }}" \
+            "${{ github.event.pull_request.base.sha }}" \
+            "${{ github.event.pull_request.head.sha }}"
+          # Create the report artifact. Note there is no report if the patch is empty.
+          mkdir ../report-artifact
+          [ ! -d obj_coverage/report ] || mv obj_coverage/report ../report-artifact/
          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
-            COVERAGE_BASE=$(git rev-parse --short $(git merge-base ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }}))
-            make coverage-report COVERAGE_BASE=${COVERAGE_BASE} |& tee ${{ github.workspace }}/make-coverage-report.log
-          else
-            make coverage-report
-          fi
-          # Remove data files
-          rm -f obj_coverage/verilator*.info
-          # Some extra work for PRs only
-          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
-            # Save PR number in report
-            echo ${{ github.event.number }} > obj_coverage/pr-number.txt
-            # Generate notification comment content
-            mkdir -p notification
-            echo ${{ github.event.number }} > notification/pr-number.txt
-            NUM=$(gh run view ${{ github.run_id }} --json number --jq ".number")
-            URL=$(gh run view ${{ github.run_id }} --json url    --jq ".url")
-            echo "Patch coverage from PR workflow [#$NUM]($URL) (code coverage of lines changed relative to ${COVERAGE_BASE}):" > notification/body.txt
-            if [[ ! -f obj_coverage/empty-patch ]]; then
-              echo "<pre>" >> notification/body.txt
-              grep -E "(lines|branches)\.*:" ${{ github.workspace }}/make-coverage-report.log | sed "s/\.*:/:/" >> notification/body.txt || true
-              echo "</pre>" >> notification/body.txt
-              echo "Report: [${{ github.run_id }}](https://${{ github.repository_owner }}.github.io/verilator/coverage-reports/${{ github.run_id }}/index.html)" >> notification/body.txt
-            else
-              echo "Patch contains no code changes" >> notification/body.txt
-            fi
-            cat notification/body.txt
+            echo ${{ github.event.number }} > ../report-artifact/pr-number.txt
          fi

      - name: Upload report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
-          path: repo/obj_coverage
+          path: report-artifact
          name: coverage-report

-      - name: Upload notification
+      - name: Upload PR notification
        if: ${{ github.event_name == 'pull_request' }}
-        uses: actions/upload-artifact@v7
+        uses: ./repo/.github/actions/upload-pr-notification
        with:
          path: repo/notification
-          name: coverage-pr-notification
+          key: coverage

  # Create GitHub issue for failed scheduled jobs
  # This should always be the last job (we want an issue if anything breaks)
@@ -193,9 +168,9 @@ jobs:
      # Creating issues requires elevated privilege
      - name: Generate access token
        id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
        with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
          private-key: ${{ secrets.VERILATOR_CI_KEY }}
          owner: verilator
          repositories: verilator
@@ -39,7 +39,7 @@ jobs:

    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7

      - name: Extract context variables
        run: |
@@ -54,7 +54,7 @@ jobs:

      - name: Docker meta
        id: docker_meta
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302  # v6
        with:
          images: |
            ${{ vars.DOCKER_HUB_NAMESPACE }}/${{ env.image_name }}
@@ -64,21 +64,21 @@ jobs:
            type=raw,value=latest,enable=${{ inputs.add_latest_tag == true }}

      - name: Set up QEMU
-        uses: docker/setup-qemu-action@v4
+        uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8  # v4

      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e  # v4
        with:
          buildkitd-flags: --debug

      - name: Login to Docker Hub
-        uses: docker/login-action@v4
+        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f  # v4
        with:
          username: ${{ secrets.DOCKER_HUB_USER }}
          password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}

      - name: Build and Push to Docker
-        uses: docker/build-push-action@v7
+        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a  # v7
        if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
        with:
          context: ${{ env.build_context }}
@@ -11,38 +11,50 @@ on:
 permissions:
  contents: write

+defaults:
+  run:
+    working-directory: repo
+
 jobs:
  format:
    runs-on: ubuntu-24.04
    name: Ubuntu 24.04 | format
-    env:
-      CI_OS_NAME: linux
-      CI_RUNS_ON: ubuntu-24.04
-      CI_COMMIT: ${{ github.sha }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
+          path: repo
          token: ${{ secrets.GITHUB_TOKEN }}
+
      - name: Install packages for build
-        env:
-          CI_BUILD_STAGE_NAME: build
+        uses: ./repo/.github/actions/install-deps
+        with:
+          stage: format
+
+      - name: Configure git identity
        run: |
-          sudo apt install clang-format-18 || \
-          sudo apt install clang-format-18
          git config --global user.email "[email protected]"
          git config --global user.name "github action"
-      - name: Format code
+
+      - name: Configure
        run: |
          autoconf
          ./configure
-          make venv
+
+      - name: Set up Python venv
+        uses: ./repo/.github/actions/setup-venv
+        with:
+          save: ${{ github.ref == 'refs/heads/master' }}
+
+      - name: Format code
+        run: |
          source .venv/bin/activate
-          make -j 2 format CLANGFORMAT=clang-format-18
+          make -j 4 format CLANGFORMAT=clang-format-18
          git status
+
      - name: Push
        run: |-
          if [ -n "$(git status --porcelain)" ]; then
-            git commit . -m "Apply 'make format'" &&
+            git commit . -m "Apply 'make format' [ci skip]" &&
            git push origin
          fi
@@ -7,10 +7,10 @@ name: Pages
 on:
  push:
    branches: [master]
-    paths: ["ci/**", ".github/workflows"]
+    paths: ["ci/**", ".github/workflows/**"]
  workflow_dispatch:
  workflow_run:
-    workflows: ["Code coverage"]
+    workflows: ["Code coverage", "RTLMeter"]
    types: [completed]

 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -22,8 +22,11 @@ permissions:
 # Allow only one concurrent deployment, skipping runs queued between the run
 # in-progress and latest queued. However, do NOT cancel in-progress runs as we
 # want to allow these deployments to complete.
+# A skipped-upstream run does no work (see the build job's if:), so put it in its
+# own throwaway group: otherwise, as the newest queued run, it would cancel a
+# pending real run and then deploy nothing.
 concurrency:
-  group: "pages"
+  group: ${{ (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'skipped') && format('pages-skip-{0}', github.run_id) || 'pages' }}
  cancel-in-progress: false

 defaults:
@@ -34,21 +37,23 @@ jobs:
  build:
    name: Build content
    runs-on: ubuntu-24.04
+    # A skipped upstream run (e.g. Code coverage / RTLMeter on a branch push)
+    # still fires workflow_run; don't rebuild and redeploy for it. deploy and
+    # notify need this job, so they cascade-skip too.
+    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion != 'skipped' }}
    outputs:
-      coverage-pr-run-ids: ${{ steps.build.outputs.coverage-pr-run-ids }}
+      pr-run-ids: ${{ steps.build.outputs.pr-run-ids }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
      - name: Build pages
        id: build
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
-          bash -x ./ci/ci-pages.bash
-          ls -lsha
-          tree -L 3 pages
+          ./ci/ci-pages.bash
      - name: Upload pages artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
        with:
          path: pages

@@ -58,10 +63,17 @@ jobs:
    runs-on: ubuntu-24.04
    environment:
      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
+      url: ${{ steps.deploy-2.outputs.page_url || steps.deploy-1.outputs.page_url }}
    steps:
+      # GitHub's Pages backend intermittently fails a deployment mid-sync, retry
      - name: Deploy to GitHub Pages
-        uses: actions/deploy-pages@v5
+        id: deploy-1
+        continue-on-error: true
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5
+      - name: Deploy to GitHub Pages (retry)
+        id: deploy-2
+        if: steps.deploy-1.outcome == 'failure'
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5

  notify:
    name: Notify
@@ -70,18 +82,20 @@ jobs:
    if: ${{ github.repository == 'verilator/verilator' }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
      # Use the Verilator CI app to post the comment
      - name: Generate access token
        id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
        with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
          private-key: ${{ secrets.VERILATOR_CI_KEY }}
          permission-actions: write
          permission-pull-requests: write
      - name: Comment on PR
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
-          COVERAGE_PR_RUN_IDS: ${{ needs.build.outputs.coverage-pr-run-ids }}
-        run: bash -x ./ci/ci-pages-notify.bash
+          # Slug of the app the above token belongs to, see 'ci-pages-notify.bash'
+          GH_AUTHOR: ${{ steps.generate-token.outputs.app-slug }}
+          PR_RUN_IDS: ${{ needs.build.outputs.pr-run-ids }}
+        run: ./ci/ci-pages-notify.bash
@@ -0,0 +1,28 @@
+---
+# Build and push verilator docker image when tags are pushed to the repository.
+# The following variable(s) must be configured in the github repository:
+# DOCKER_HUB_NAMESPACE: docker hub namespace.
+# The following secrets must be configured in the github repository:
+# DOCKER_HUB_USER: user name for logging into docker hub
+# DOCKER_HUB_ACCESS_TOKEN: docker hub access token.
+name: Maintainance - PR conflict check
+
+on:
+  workflow_dispatch:
+  push:
+  pull_request_target:
+    types: [synchronize]
+permissions: {}
+
+jobs:
+  main:
+    runs-on: ubuntu-26.04
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: check if prs are dirty
+        uses: eps1lon/actions-label-merge-conflict@0273be72a0bbd58fcd71d0d6c02c209b50d1e5e1  # 3.1.0
+        with:
+          dirtyLabel: "pr-blocked: needs-rebase"
+          repoToken: "${{ secrets.GITHUB_TOKEN }}"
@@ -7,37 +7,47 @@ name: reusable-build
 on:
  workflow_call:
    inputs:
+      cc:
+        description: "Compiler to use: 'gcc' or 'clang'"
+        required: true
+        type: string
+      ccwarn:
+        description: "Build Verilator with warnings treated as errors (--enable-ccwarn)"
+        required: false
+        default: true
+        type: boolean
+      dev-asan:
+        description: "Build Verilator with the address sanitizer (--enable-dev-asan)"
+        required: false
+        default: false
+        type: boolean
+      dev-gcov:
+        description: "Build Verilator with gcov instrumentation (--enable-dev-gcov)"
+        required: false
+        default: false
+        type: boolean
+      install:
+        description: "Archive the Verilator installation, not the repo tree"
+        required: false
+        default: false
+        type: boolean
+      runs-on:
+        description: "Runner to build on, e.g. ubuntu-24.04"
+        required: true
+        type: string
      sha:
        description: "Commit SHA to build"
        required: true
        type: string
-      os:  # e.g. ubuntu-24.04
-        required: true
-        type: string
-      cc: # 'clang' or 'gcc'
-        required: true
-        type: string
-      os-name: # 'linux' or 'osx'
-        required: true
-        type: string
-      dev-asan:
-        required: true
-        type: number
-      dev-gcov:
-        required: true
-        type: number
    outputs:
      archive:
-        description: "Name of the built repository archive artifact"
+        description: "Name of the built archive artifact"
        value: ${{ jobs.build.outputs.archive }}

 env:
-  CI_OS_NAME: ${{ inputs.os-name }}
-  CCACHE_COMPRESS: 1
+  CACHE_BASE_KEY: build-${{ inputs.runs-on }}-${{ inputs.cc }}${{ inputs.ccwarn && '-ccwarn' || '' }}${{ inputs.dev-asan && '-asan' || '' }}${{ inputs.dev-gcov && '-gcov' || '' }}
+  CCACHE_COMPILERCHECK: content
  CCACHE_DIR: ${{ github.workspace }}/.ccache
-  CCACHE_LIMIT_MULTIPLE: 0.95
-  INSTALL_DIR: ${{ github.workspace }}/install
-  RELOC_DIR: ${{ github.workspace }}/relloc

 defaults:
  run:
@@ -48,52 +58,75 @@ jobs:

  build:
    name: Build
-    runs-on: ${{ inputs.os }}
+    runs-on: ${{ inputs.runs-on }}
    outputs:
      archive: ${{ steps.create-archive.outputs.archive }}
-    env:
-      CI_BUILD_STAGE_NAME: build
-      CI_DEV_ASAN: ${{ inputs.dev-asan }}
-      CI_DEV_GCOV: ${{ inputs.dev-gcov }}
-      CI_RUNS_ON: ${{ inputs.os }}
-      CXX: ${{ inputs.cc == 'clang' && 'clang++' || 'g++' }}
-      CACHE_BASE_KEY: build-${{ inputs.os }}-${{ inputs.cc }}
-      CCACHE_MAXSIZE: 1000M  # Per build matrix entry (* 5 = 5000M in total)
    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          path: repo
          ref: ${{ inputs.sha }}
-          fetch-depth: ${{ inputs.dev-gcov && '0' || '1' }}  # Coverage flow needs full history
+          # Coverage needs full history; install needs it for the 'git describe'
+          # behind 'verilator --version'
+          fetch-depth: ${{ (inputs.install || inputs.dev-gcov) && '0' || '1' }}
+
+      - name: Configure ccache
+        run: |
+          # ccache is unreliable on macOS, and does nothing with 'gcc --coverage'
+          if [ "${{ startsWith(inputs.runs-on, 'macos') }}" = true ] || [ "${{ inputs.dev-gcov }}" = true ]; then
+            echo "CCACHE_DISABLE=1" >> "$GITHUB_ENV"
+          fi

      - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
+        if: ${{ env.CCACHE_DISABLE != '1' }}
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
        env:
          CACHE_KEY: ${{ env.CACHE_BASE_KEY }}-ccache
        with:
          path: ${{ env.CCACHE_DIR }}
          key: ${{ env.CACHE_KEY }}-${{ inputs.sha }}
          restore-keys: |
-            ${{ env.CACHE_KEY }}-
+            ${{ env.CACHE_KEY }}

      - name: Install packages for build
-        run: ./ci/ci-install.bash
+        uses: ./repo/.github/actions/install-deps
+        with:
+          stage: build

      - name: Build
-        run: ./ci/ci-script.bash
+        run: |
+          ./ci/ci-build.bash \
+            --prefix ${{ github.workspace }}/install \
+            --compiler ${{ inputs.cc }} \
+            --light-debug \
+            ${{ inputs.ccwarn && '--ccwarn' || '' }} \
+            ${{ inputs.dev-asan && '--asan' || '' }} \
+            ${{ inputs.dev-gcov && '--gcov' || '' }}

-      - name: Create repository archive
+      - name: Install
+        if: ${{ inputs.install }}
+        run: make install
+
+      - name: Create archive
        id: create-archive
        working-directory: ${{ github.workspace }}
        run: |
-          # Name of the archive must be unique based on the build parameters
-          ARCHIVE=verilator-${{ inputs.sha }}-${{ inputs.os }}-${{ inputs.cc }}-${{ inputs.dev-asan }}-${{ inputs.dev-gcov }}.tar.gz
-          tar --posix -c -z -f $ARCHIVE repo
+          # Archive name, unique per build; flavour tags mark non-default builds
+          ARCHIVE="verilator-${{ inputs.sha }}-${{ inputs.runs-on }}-${{ inputs.cc }}"
+          ARCHIVE="$ARCHIVE${{ inputs.ccwarn && '-ccwarn' || '' }}"
+          ARCHIVE="$ARCHIVE${{ inputs.dev-asan && '-asan' || '' }}"
+          ARCHIVE="$ARCHIVE${{ inputs.dev-gcov && '-gcov' || '' }}"
+          ARCHIVE="$ARCHIVE.tar.zst"
+          # zstd compresses faster than gzip and decompresses far faster in the many downstream jobs
+          ZSTD_NBTHREADS=0 tar --posix --zstd -c -f "$ARCHIVE" ${{ inputs.install && 'install' || 'repo' }}
          echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"

-      - name: Upload repository archive
-        uses: actions/upload-artifact@v7
+      - name: Upload archive
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          path: ${{ github.workspace }}/${{ steps.create-archive.outputs.archive }}
          name: ${{ steps.create-archive.outputs.archive }}
+          overwrite: true
+          # Archive is already zstd-compressed; skip upload-artifact's zip pass
+          compression-level: 0
@@ -7,14 +7,6 @@ name: reusable-lint-py
 on:
  workflow_call:

-env:
-  CI_OS_NAME: linux
-  CI_BUILD_STAGE_NAME: build
-  CI_RUNS_ON: ubuntu-22.04
-  CCACHE_COMPRESS: 1
-  CCACHE_DIR: ${{ github.workspace }}/.ccache
-  CCACHE_LIMIT_MULTIPLE: 0.95
-
 defaults:
  run:
    shell: bash
@@ -27,23 +19,24 @@ jobs:
    name: Sub-lint | Python
    steps:
      - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          path: repo

-      - name: Install packages for build
-        run: ./ci/ci-install.bash
+      - name: Install dependencies
+        uses: ./repo/.github/actions/install-deps
+        with:
+          stage: lint-py

      - name: Configure
        run: |
          autoconf
          ./configure --enable-longtests --enable-ccwarn

-      - name: Install python dependencies
-        run: |
-          sudo apt install python3-clang || \
-          sudo apt install python3-clang
-          make venv
+      - name: Set up Python venv
+        uses: ./repo/.github/actions/setup-venv
+        with:
+          save: ${{ github.ref == 'refs/heads/master' }}

      - name: Lint
        run: |-
@@ -1,77 +0,0 @@
---
-# DESCRIPTION: Github actions config
-# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
-
-name: reusable-rtlmeter-build
-
-on:
-  workflow_call:
-    inputs:
-      runs-on:
-        description: "Runner to use, e.g.: ubuntu-24.04"
-        type: string
-        required: true
-      cc:
-        description: "Compiler to use: 'gcc' or 'clang'"
-        type: string
-        required: true
-
-defaults:
-  run:
-    shell: bash
-
-env:
-  CCACHE_DIR: ${{ github.workspace }}/ccache
-  CCACHE_MAXSIZE: 512M
-
-jobs:
-  build:
-    runs-on: ${{ inputs.runs-on }}
-    name: Build
-    steps:
-      - name: Install dependencies
-        run: |
-          echo "path-exclude /usr/share/doc/*"  | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-          echo "path-exclude /usr/share/man/*"  | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-          echo "path-exclude /usr/share/info/*" | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-          sudo apt update || \
-          sudo apt update
-          sudo apt install ccache mold help2man libfl-dev libjemalloc-dev libsystemc-dev || \
-          sudo apt install ccache mold help2man libfl-dev libjemalloc-dev libsystemc-dev
-
-      - name: Use saved ccache
-        uses: actions/cache@v5
-        with:
-          path: ccache
-          key: rtlmeter-build-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ github.run_id }}-${{ github.run_attempt }}
-          restore-keys: rtlmeter-build-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}
-
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          path: repo
-          fetch-depth: 0 # Required for 'git describe' used for 'verilator --version'
-
-      - name: Configure
-        working-directory: repo
-        run: |
-          autoconf
-          ./configure --prefix=${{ github.workspace }}/install CXX=${{ inputs.cc == 'clang' && 'clang++' || 'g++' }}
-
-      - name: Make
-        working-directory: repo
-        run: make -j $(nproc)
-
-      - name: Install
-        working-directory: repo
-        run: make install
-
-      - name: Tar up installation
-        run: tar --posix -c -z -f verilator-rtlmeter.tar.gz install
-
-      - name: Upload Verilator installation archive
-        uses: actions/upload-artifact@v7
-        with:
-          path: verilator-rtlmeter.tar.gz
-          name: verilator-rtlmeter-${{ inputs.runs-on }}-${{ inputs.cc }}
-          overwrite: true
@@ -19,6 +19,15 @@ on:
        description: "Compiler to use: 'gcc' or 'clang'"
        type: string
        required: true
+      verilator-archive-new:
+        description: "Name of the installation archive artifact from reusable-build, new version"
+        type: string
+        required: true
+      verilator-archive-old:
+        description: "Name of the installation archive artifact from reusable-build, old version"
+        type: string
+        required: false
+        default: ""
      # Note: The combination of 'cases' and 'run-name' must be unique for all
      # invocations of this workflow within a run of the parent workflow.
      # These two are used together to generate a unique results file name.
@@ -44,8 +53,8 @@ defaults:
    shell: bash

 env:
-  CCACHE_DIR: ${{ github.workspace }}/ccache
-  CCACHE_MAXSIZE: 512M
+  # RTLMeter measures compile/execute times, so caching must stay off to keep
+  # timings representative; ccache is still on PATH but acts as a pass-through
  CCACHE_DISABLE: 1

 jobs:
@@ -53,36 +62,21 @@ jobs:
    runs-on: ${{ inputs.runs-on }}
    name: Run
    steps:
+      - name: Checkout Verilator CI scripts
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          path: repo
+          sparse-checkout: |
+            .github/actions
+            ci
+
      - name: Install dependencies
-        run: |
-          echo "path-exclude /usr/share/doc/*"  | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-          echo "path-exclude /usr/share/man/*"  | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-          echo "path-exclude /usr/share/info/*" | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-          sudo apt update || \
-          sudo apt update
-          sudo apt install ccache mold libfl-dev libjemalloc-dev libsystemc-dev || \
-          sudo apt install ccache mold libfl-dev libjemalloc-dev libsystemc-dev
-
-      - name: Download Verilator installation archive
-        uses: actions/download-artifact@v8
+        uses: ./repo/.github/actions/install-deps
        with:
-          name: verilator-rtlmeter-${{ inputs.runs-on }}-${{ inputs.cc }}
-
-      - name: Unpack Verilator installation archive
-        run: |
-          tar -x -z -f verilator-rtlmeter.tar.gz
-          echo "${{ github.workspace }}/install/bin" >> $GITHUB_PATH
-
-      - name: Use saved ccache
-        if: ${{ env.CCACHE_DISABLE == 0 }}
-        uses: actions/cache@v5
-        with:
-          path: ${{ env.CCACHE_DIR }}
-          key: rtlmeter-run-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ inputs.cases }}-${{ inputs.compileArgs }}-${{ github.run_id }}-${{ github.run_attempt }}
-          restore-keys: rtlmeter-run-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ inputs.cases }}-${{ inputs.compileArgs }}
+          stage: rtlmeter-run

      - name: Checkout RTLMeter
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          repository: "verilator/rtlmeter"
          path: rtlmeter
@@ -91,40 +85,117 @@ jobs:
        working-directory: rtlmeter
        run: make venv

-      - name: Compile cases
+      ########################################################################
+      # Run with new Verilator
+      ########################################################################
+
+      - name: Download Verilator installation archive - new
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
+        with:
+          name: ${{ inputs.verilator-archive-new }}
+
+      - name: Unpack Verilator installation archive - new
+        run: |
+          tar --zstd -x -f ${{ inputs.verilator-archive-new }}
+          mv install verilator-new
+
+      - name: Compile cases - new
        working-directory: rtlmeter
        run: |
+          export PATH="${{ github.workspace }}/verilator-new/bin:$PATH"
          ./rtlmeter run --timeout 60 --verbose --cases='${{inputs.cases}}' --compileArgs='${{inputs.compileArgs}}' --executeArgs='${{inputs.executeArgs}}' --nExecute=0
+          ccache -svv

-      - name: Execute cases
+      - name: Execute cases - new
        working-directory: rtlmeter
        continue-on-error: true  # Do not fail on error, so we can at least save the successful results
        run: |
+          export PATH="${{ github.workspace }}/verilator-new/bin:$PATH"
          ./rtlmeter run --timeout 60 --verbose --cases='${{inputs.cases}}' --compileArgs='${{inputs.compileArgs}}' --executeArgs='${{inputs.executeArgs}}'

-      - name: Collate results
+      - name: Collate results - new
        id: results
        working-directory: rtlmeter
        run: |
+          export PATH="${{ github.workspace }}/verilator-new/bin:$PATH"
          # Use 'inputs.cases' and 'inputs.run-name' to generate a unique file name
          hash=$(md5sum <<< '${{ inputs.cases }} ${{ inputs.run-name }}' | awk '{print $1}')
          echo "hash=${hash}" >> $GITHUB_OUTPUT
          ./rtlmeter collate --runName "${{ inputs.run-name }}"  > ../results-${hash}.json

-      - name: Report results
+      - name: Report results - new
        working-directory: rtlmeter
        run: |
+          export PATH="${{ github.workspace }}/verilator-new/bin:$PATH"
          ./rtlmeter report --steps '*' --metrics '*' ../results-${{ steps.results.outputs.hash }}.json

-      - name: Upload results
-        uses: actions/upload-artifact@v7
+      - name: Upload results - new
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          path: results-${{ steps.results.outputs.hash }}.json
          name: rtlmeter-${{ inputs.tag }}-results-${{ steps.results.outputs.hash }}
          overwrite: true
          retention-days: 2

-      - name: Report status
+      - name: Report status - new
        working-directory: rtlmeter
        run: |-  # This will fail the job if any of the runs failed
+          export PATH="${{ github.workspace }}/verilator-new/bin:$PATH"
          ./rtlmeter run --verbose --cases='${{inputs.cases}}' --compileArgs='${{inputs.compileArgs}}' --executeArgs='${{inputs.executeArgs}}'
+          # Clean up for run with old version
+          rm -rf work
+          rm -rf ${{ github.workspace }}/verilator-new
+
+      ########################################################################
+      # Run with old Verilator **on same machine for consistency**
+      ########################################################################
+
+      - name: Download Verilator installation archive - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
+        with:
+          name: ${{ inputs.verilator-archive-old }}
+
+      - name: Unpack Verilator installation archive - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        run: |
+          tar --zstd -x -f ${{ inputs.verilator-archive-old }}
+          mv install verilator-old
+
+      - name: Compile cases - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        working-directory: rtlmeter
+        run: |
+          export PATH="${{ github.workspace }}/verilator-old/bin:$PATH"
+          ./rtlmeter run --timeout 60 --verbose --cases='${{inputs.cases}}' --compileArgs='${{inputs.compileArgs}}' --executeArgs='${{inputs.executeArgs}}' --nExecute=0
+          ccache -svv
+
+      - name: Execute cases - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        working-directory: rtlmeter
+        run: |
+          export PATH="${{ github.workspace }}/verilator-old/bin:$PATH"
+          ./rtlmeter run --timeout 60 --verbose --cases='${{inputs.cases}}' --compileArgs='${{inputs.compileArgs}}' --executeArgs='${{inputs.executeArgs}}'
+
+      - name: Collate results - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        working-directory: rtlmeter
+        run: |
+          export PATH="${{ github.workspace }}/verilator-old/bin:$PATH"
+          ./rtlmeter collate --runName "${{ inputs.run-name }}"  > ../reference-${{ steps.results.outputs.hash }}.json
+
+      - name: Report results - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        working-directory: rtlmeter
+        run: |
+          export PATH="${{ github.workspace }}/verilator-old/bin:$PATH"
+          ./rtlmeter report --steps '*' --metrics '*' ../reference-${{ steps.results.outputs.hash }}.json
+
+      - name: Upload results - old
+        if: ${{ inputs.verilator-archive-old != '' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          path: reference-${{ steps.results.outputs.hash }}.json
+          name: rtlmeter-${{ inputs.tag }}-reference-${{ steps.results.outputs.hash }}
+          overwrite: true
+          retention-days: 2
@@ -11,29 +11,37 @@ on:
        description: "Name of the repository archive artifact from reusable-build"
        required: true
        type: string
-      os:  # e.g. ubuntu-24.04
-        required: true
-        type: string
-      cc:  # gcc or clang
-        required: true
-        type: string
-      reloc:  # 0 or 1
-        required: true
-        type: number
-      suite:  # e.g. dist-vlt-0
+      cc:
+        description: "Compiler to use: 'gcc' or 'clang'"
        required: true
        type: string
      dev-gcov:
+        description: "Collect gcov coverage data from the test run"
+        required: false
+        default: false
+        type: boolean
+      reloc:
+        description: "Relocate the installation before testing"
+        required: false
+        default: false
+        type: boolean
+      runs-on:
+        description: "Runner to test on, e.g. ubuntu-24.04"
        required: true
-        type: number
+        type: string
+      suite:
+        description: "Test suite to run, e.g. dist-vlt-0"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  actions: read

 env:
-  CI_OS_NAME: linux
-  CCACHE_COMPRESS: 1
+  CCACHE_COMPILERCHECK: content
  CCACHE_DIR: ${{ github.workspace }}/.ccache
-  CCACHE_LIMIT_MULTIPLE: 0.95
-  INSTALL_DIR: ${{ github.workspace }}/install
-  RELOC_DIR: ${{ github.workspace }}/relloc
+  CXX: ${{ inputs.cc == 'clang' && 'clang++' || 'g++' }}

 defaults:
  run:
@@ -43,19 +51,12 @@ defaults:
 jobs:

  test:
-    runs-on: ${{ inputs.os }}
+    runs-on: ${{ inputs.runs-on }}
    name: Test
-    env:
-      CI_BUILD_STAGE_NAME: test
-      CI_RUNS_ON: ${{ inputs.os }}
-      CI_RELOC: ${{inputs.reloc }}
-      CXX: ${{ inputs.cc == 'clang' && 'clang++' || 'g++' }}
-      CACHE_BASE_KEY: test-${{ inputs.os }}-${{ inputs.cc }}-${{inputs.reloc }}-${{ inputs.suite }}
-      CCACHE_MAXSIZE: 100M  # Per build per suite (* 5 * 5 = 2500M in total)
    steps:

      - name: Download repository archive
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
          name: ${{ inputs.archive }}
          path: ${{ github.workspace }}
@@ -63,32 +64,44 @@ jobs:
      - name: Unpack repository archive
        working-directory: ${{ github.workspace }}
        run: |
-          tar -x -z -f ${{ inputs.archive }}
+          tar --zstd -x -f ${{ inputs.archive }}
          ls -lsha

-      - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
-        env:
-          CACHE_KEY: ${{ env.CACHE_BASE_KEY }}-ccache2
+      - name: Configure ccache
+        run: |
+          # ccache is unreliable on macOS, and does nothing with 'gcc --coverage'
+          if [ "${{ startsWith(inputs.runs-on, 'macos') }}" = true ] || [ "${{ inputs.dev-gcov }}" = true ]; then
+            echo "CCACHE_DISABLE=1" >> "$GITHUB_ENV"
+          fi
+
+      # Test-job ccache is stored as an artifact, not actions/cache
+      - name: Restore ccache
+        id: ccache
+        if: ${{ env.CCACHE_DISABLE != '1' }}
+        uses: ./repo/.github/actions/artifact-cache
        with:
+          mode: restore
          path: ${{ env.CCACHE_DIR }}
-          key: ${{ env.CACHE_KEY }}-${{ github.sha }}
-          restore-keys: |
-            ${{ env.CACHE_KEY }}-
+          key: ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ inputs.suite }}

      - name: Install test dependencies
-        run: |
-          ./ci/ci-install.bash
-          make venv
+        uses: ./repo/.github/actions/install-deps
+        with:
+          stage: test
+
+      - name: Set up Python venv
+        uses: ./repo/.github/actions/setup-venv
+        with:
+          save: ${{ github.ref == 'refs/heads/master' }}

      - name: Test
        id: run-test
        continue-on-error: true
-        env:
-          TESTS: ${{ inputs.suite }}
        run: |
          source .venv/bin/activate
-          ./ci/ci-script.bash
+          ./ci/ci-test.bash \
+            --suite ${{ inputs.suite }} \
+            ${{ inputs.reloc && format('--reloc {0}/reloc', github.workspace) || '' }}

      - name: Combine code coverage data
        if: ${{ inputs.dev-gcov }}
@@ -99,11 +112,21 @@ jobs:

      - name: Upload code coverage data
        if: ${{ inputs.dev-gcov }}
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          path: ${{ github.workspace }}/repo/obj_coverage/verilator-${{ inputs.suite }}.info
          name: code-coverage-${{ inputs.suite }}

+      - name: Save ccache
+        if: ${{ env.CCACHE_DISABLE != '1' && !cancelled() }}
+        uses: ./repo/.github/actions/artifact-cache
+        with:
+          mode: save
+          path: ${{ env.CCACHE_DIR }}
+          key: ${{ steps.ccache.outputs.key }}
+          # Keep master's cache around longer; PR/branch caches churn faster
+          retention-days: ${{ github.ref == 'refs/heads/master' && 7 || 3 }}
+
      - name: Fail job if a test failed
        if: ${{ steps.run-test.outcome == 'failure' && !cancelled() }}
        run: |-
@@ -1,48 +0,0 @@
---
-# 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: RTLMeter PR results
-
-on:
-  workflow_run:
-    workflows: [RTLMeter]
-    types: [completed]
-
-jobs:
-  publish:
-    name: Publish
-    runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' }}
-    permissions:
-      actions: read
-      pull-requests: write
-    steps:
-      - name: Download report
-        uses: actions/download-artifact@v8
-        with:
-          name: rtlmeter-pr-results
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Download PR number
-        uses: actions/download-artifact@v8
-        with:
-          name: pr-number
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-      # Use the Verilator CI app to post the comment
-      - name: Generate access token
-        id: generate-token
-        uses: actions/[email protected]
-        with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
-          private-key: ${{ secrets.VERILATOR_CI_KEY }}
-          permission-pull-requests: write
-      - name: Comment on PR
-        env:
-          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
-        run: |-
-          ls -la
-          cat report.txt
-          gh pr --repo ${{ github.repository }} comment $(cat pr-number.txt) --body-file report.txt
@@ -40,175 +40,237 @@ jobs:
      (github.event_name == 'workflow_dispatch') ||
      (github.event_name == 'push')
    runs-on: ubuntu-24.04
+    outputs:
+      old-sha: ${{ steps.start.outputs.old-sha }}
+      cases: ${{ steps.cases.outputs.cases }}
    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+
      - name: Startup
-        run: echo
+        id: start
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          [[ "${{ github.event_name }}" == 'pull_request' ]] || exit 0
+          # For a pull request, 'github.sha' is the test merge commit. Its
+          # first parent is the target branch commit it was merged with for this run.
+          OLD_SHA="$(gh api "repos/${{ github.repository }}/commits/${{ github.sha }}" --jq '.parents[0].sha')"
+          echo "old-sha=$OLD_SHA" >> "$GITHUB_OUTPUT"

-  build-gcc:
-    name: Build GCC
+      - name: Load RTLMeter cases
+        id: cases
+        run: echo "cases=$(ci/ci-rtlmeter-cases.py --event-name ${{ github.event_name }})" >> "$GITHUB_OUTPUT"
+
+  build-gcc-new:
+    name: Build New Verilator - GCC
    needs: start
-    uses: ./.github/workflows/reusable-rtlmeter-build.yml
+    uses: ./.github/workflows/reusable-build.yml
    with:
-      runs-on: ubuntu-24.04
      cc: gcc
-
-  build-clang:
-    name: Build Clang
-    needs: start
-    uses: ./.github/workflows/reusable-rtlmeter-build.yml
-    with:
+      ccwarn: false
+      install: true
      runs-on: ubuntu-24.04
+      sha: ${{ github.sha }}
+
+  build-clang-new:
+    name: Build New Verilator - Clang
+    needs: start
+    uses: ./.github/workflows/reusable-build.yml
+    with:
      cc: clang
+      ccwarn: false
+      install: true
+      runs-on: ubuntu-24.04
+      sha: ${{ github.sha }}
+
+  build-gcc-old:
+    name: Build Old Verilator - GCC
+    needs: start
+    if: ${{ needs.start.outputs.old-sha != '' }}
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: gcc
+      ccwarn: false
+      install: true
+      runs-on: ubuntu-24.04
+      sha: ${{ needs.start.outputs.old-sha }}
+
+  build-clang-old:
+    name: Build Old Verilator - Clang
+    needs: start
+    if: ${{ needs.start.outputs.old-sha != '' }}
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: clang
+      ccwarn: false
+      install: true
+      runs-on: ubuntu-24.04
+      sha: ${{ needs.start.outputs.old-sha }}

  run-gcc:
    name: Run GCC | ${{ matrix.cases }}
-    needs: build-gcc
+    needs:
+      - start
+      - build-gcc-new
+      - build-gcc-old
+    # Run even if 'build-*-old' was skipped (no old SHA), but not if any
+    # dependency failed, the workflow was cancelled, or 'start' was skipped
+    # (e.g. the workflow was not enabled, so there is nothing to run against).
+    if: ${{ !failure() && !cancelled() && needs.start.result == 'success' }}
    uses: ./.github/workflows/reusable-rtlmeter-run.yml
    with:
      tag: gcc
      runs-on: ubuntu-24.04
      cc: gcc
+      verilator-archive-new: ${{ needs.build-gcc-new.outputs.archive }}
+      verilator-archive-old: ${{ needs.build-gcc-old.outputs.archive }}
      cases: ${{ matrix.cases }}
      run-name: "gcc"
      compileArgs: ""
      executeArgs: ""
    strategy:
-      fail-fast: false
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      fail-fast: ${{ github.event_name == 'pull_request' }}
+      max-parallel: 7
      matrix:
-        cases:
-          - "BlackParrot:1x1:*"
-          - "BlackParrot:4x4:*"
-          - "Caliptra:default:*"
-          - "NVDLA:*"
-          - "OpenPiton:1x1:*"
-          - "OpenPiton:4x4:*"
-          - "OpenTitan:*"
-          - "VeeR-EH1:asic*"
-          - "VeeR-EH1:default*"
-          - "VeeR-EH1:hiperf*"
-          - "VeeR-EH2:asic*"
-          - "VeeR-EH2:default*"
-          - "VeeR-EH2:hiperf*"
-          - "VeeR-EL2:asic*"
-          - "VeeR-EL2:default*"
-          - "VeeR-EL2:hiperf*"
-          - "Vortex:mini:*"
-          - "Vortex:sane:*"
-          - "XiangShan:default-chisel3:* !*:linux"
-          - "XiangShan:default-chisel6:* !*:linux"
-          - "XiangShan:mini-chisel3:* !*:linux"
-          - "XiangShan:mini-chisel6:* !*:linux"
-          - "XuanTie-E902:*"
-          - "XuanTie-E906:*"
-          - "XuanTie-C906:*"
-          - "XuanTie-C910:*"
+        cases: ${{ fromJSON(needs.start.outputs.cases)['gcc'] }}

  run-clang:
    name: Run Clang | ${{ matrix.cases }}
-    needs: build-clang
+    needs:
+      - start
+      - build-clang-new
+      - build-clang-old
+    # Run even if 'build-*-old' was skipped (no old SHA), but not if any
+    # dependency failed, the workflow was cancelled, or 'start' was skipped
+    # (e.g. the workflow was not enabled, so there is nothing to run against).
+    if: ${{ !failure() && !cancelled() && needs.start.result == 'success' }}
    uses: ./.github/workflows/reusable-rtlmeter-run.yml
    with:
      tag: clang
      runs-on: ubuntu-24.04
      cc: clang
+      verilator-archive-new: ${{ needs.build-clang-new.outputs.archive }}
+      verilator-archive-old: ${{ needs.build-clang-old.outputs.archive }}
      cases: ${{ matrix.cases }}
      run-name: "clang --threads 4"
      compileArgs: "--threads 4"
      executeArgs: ""
    strategy:
-      fail-fast: false
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      fail-fast: ${{ github.event_name == 'pull_request' }}
+      max-parallel: 7
      matrix:
-        cases:
-          - "BlackParrot:1x1:*"
-          - "BlackParrot:4x4:*"
-          - "Caliptra:default:*"
-          - "NVDLA:*"
-          - "OpenPiton:1x1:*"
-          - "OpenPiton:4x4:*"
-          - "OpenTitan:*"
-          - "VeeR-EH1:asic*"
-          - "VeeR-EH1:default*"
-          - "VeeR-EH1:hiperf*"
-          - "VeeR-EH2:asic*"
-          - "VeeR-EH2:default*"
-          - "VeeR-EH2:hiperf*"
-          - "VeeR-EL2:asic*"
-          - "VeeR-EL2:default*"
-          - "VeeR-EL2:hiperf*"
-          - "Vortex:mini:*"
-          - "Vortex:sane:*"
-          - "XiangShan:default-chisel3:* !*:linux"
-          - "XiangShan:default-chisel6:* !*:linux"
-          - "XiangShan:mini-chisel3:* !*:linux"
-          - "XiangShan:mini-chisel6:* !*:linux"
-          - "XuanTie-E902:*"
-          - "XuanTie-E906:*"
-          - "XuanTie-C906:*"
-          - "XuanTie-C910:*"
+        cases: ${{ fromJSON(needs.start.outputs.cases)['clang'] }}

  run-gcc-hier:
    name: Run GCC hier | ${{ matrix.cases }}
-    needs: build-gcc
+    needs:
+      - start
+      - build-gcc-new
+      - build-gcc-old
+    # Run even if 'build-*-old' was skipped (no old SHA), but not if any
+    # dependency failed, the workflow was cancelled, or 'start' was skipped
+    # (e.g. the workflow was not enabled, so there is nothing to run against).
+    if: ${{ !failure() && !cancelled() && needs.start.result == 'success' }}
    uses: ./.github/workflows/reusable-rtlmeter-run.yml
    with:
      tag: gcc-hier
      runs-on: ubuntu-24.04
      cc: gcc
+      verilator-archive-new: ${{ needs.build-gcc-new.outputs.archive }}
+      verilator-archive-old: ${{ needs.build-gcc-old.outputs.archive }}
      cases: ${{ matrix.cases }}
      run-name: "gcc --hierarchical"
      compileArgs: "--hierarchical"
      executeArgs: ""
    strategy:
-      fail-fast: false
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      fail-fast: ${{ github.event_name == 'pull_request' }}
+      max-parallel: 6
      matrix:
-        cases:
-          - "BlackParrot:1x1:* !-hier"
-          - "BlackParrot:4x4:* !-hier"
-          - "NVDLA:* !-hier"
-          - "OpenPiton:1x1:* !-hier"
-          - "OpenPiton:4x4:* !-hier"
-          - "OpenPiton:8x8:* !-hier"
-          - "OpenPiton:16x16:dhry !-hier"
-          - "XuanTie-C910:* !-hier"
+        cases: ${{ fromJSON(needs.start.outputs.cases)['gcc-hier'] }}

  combine-results:
    name: Combine results
    needs: [run-gcc, run-clang, run-gcc-hier]
-    # Run if any of the dependencies have run, even if failed.
-    # That is: do not run if all skipped, or the workflow was cancelled.
-    if: ${{ (contains(needs.*.result, 'success') || contains(needs.*.result, 'failure')) && !cancelled() }}
+    # Skip if cancelled.
+    # On PRs, run if something succeeded and nothing failed.
+    # On non-PRs, run if anything succeeded or failed (so partial results are still published).
+    if: >-
+      ${{ !cancelled() && (
+               (github.event_name == 'pull_request' && (contains(needs.*.result, 'success') && !contains(needs.*.result, 'failure')))
+            || (github.event_name != 'pull_request' && (contains(needs.*.result, 'success') ||  contains(needs.*.result, 'failure')))
+          )}}
    runs-on: ubuntu-24.04
-    strategy:
-      fail-fast: false
-      matrix:
-        tag: [gcc, clang, gcc-hier]
+    outputs:
+      # The run tags, derived from the 'run-*' dependency job names
+      run-tags: ${{ steps.tags.outputs.tags }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+      # 'gh' resolves the repo from git otherwise, but this job has no checkout
+      # of this repo at the workspace root
+      GH_REPO: ${{ github.repository }}
    steps:
+      # Derive the run tags from the dependency job names ('run-<tag>')
+      - name: Determine run tags
+        id: tags
+        run: echo "tags=$(jq -r 'keys | map(sub("^run-"; "")) | join(" ")' <<< '${{ toJSON(needs) }}')" >> "$GITHUB_OUTPUT"
+
      - name: Checkout RTLMeter
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          repository: "verilator/rtlmeter"
          path: rtlmeter
+
      - name: Setup RTLMeter venv
        working-directory: rtlmeter
        run: make venv
+
      - name: Download all results
-        uses: actions/download-artifact@v8
-        with:
-          pattern: rtlmeter-${{ matrix.tag }}-results-*
-          path: all-results-${{ matrix.tag }}
-          merge-multiple: true
+        run: |
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            mkdir artifacts all-results-$tag
+            gh run download ${{ github.run_id }} --pattern "rtlmeter-$tag-results-*" --dir artifacts
+            mv $(find artifacts -name "*.json") all-results-$tag/
+            rm -rf artifacts
+          done
      - name: Combine results
        working-directory: rtlmeter
        run: |
-          ./rtlmeter collate ../all-results-${{ matrix.tag }}/*.json > ../all-results-${{ matrix.tag }}.json
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            ./rtlmeter collate ../all-results-$tag/*.json > ../all-results-$tag.json
+          done
      - name: Upload combined results
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
-          path: all-results-${{ matrix.tag }}.json
-          name: all-results-${{ matrix.tag }}
+          path: all-results-*.json
+          name: all-results
+          overwrite: true
+          retention-days: 30
+
+      # The reference (old) results only exist for pull requests, where the
+      # 'build-*-old' jobs run and the run jobs produce '*-reference-*' artifacts.
+      - name: Download reference results
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            mkdir artifacts all-reference-$tag
+            gh run download ${{ github.run_id }} --pattern "rtlmeter-$tag-reference-*" --dir artifacts
+            mv $(find artifacts -name "*.json") all-reference-$tag/
+            rm -rf artifacts
+          done
+      - name: Combine reference results
+        if: ${{ github.event_name == 'pull_request' }}
+        working-directory: rtlmeter
+        run: |
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            ./rtlmeter collate ../all-reference-$tag/*.json > ../all-reference-$tag.json
+          done
+      - name: Upload reference results
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          path: all-reference-*.json
+          name: all-reference
          overwrite: true
          retention-days: 30

@@ -224,28 +286,27 @@ jobs:
    runs-on: ubuntu-24.04
    steps:
      - name: Download combined results
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
        with:
-          pattern: all-results-*
+          name: all-results
          path: results
-          merge-multiple: true
      - name: Upload published results
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
          path: results/*.json
          name: published-results
      # Pushing to verilator/verilator-rtlmeter-results requires elevated permissions
      - name: Generate access token
        id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
        with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
          private-key: ${{ secrets.VERILATOR_CI_KEY }}
          owner: verilator
          repositories: verilator-rtlmeter-results
          permission-contents: write
      - name: Checkout verilator-rtlmeter-results
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          repository: "verilator/verilator-rtlmeter-results"
          token: ${{ steps.generate-token.outputs.token }}
@@ -272,116 +333,57 @@ jobs:
  prepare-pr-results:
    name: Prepare Pull Request results
    needs: combine-results
-    if: ${{ github.event_name == 'pull_request' && github.repository == 'verilator/verilator' && contains(needs.*.result, 'success') && !cancelled() }}
+    if: ${{ github.event_name == 'pull_request' && github.repository == 'verilator/verilator' && needs.combine-results.result == 'success' }}
    runs-on: ubuntu-24.04
    permissions:
      actions: read
    steps:
      - name: Checkout RTLMeter
-        uses: actions/checkout@v6
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
          repository: "verilator/rtlmeter"
          path: rtlmeter
+
      - name: Setup RTLMeter venv
        working-directory: rtlmeter
        run: make venv
-      - name: Download combined results
-        uses: actions/download-artifact@v8
+
+      - name: Checkout Verilator
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
        with:
-          pattern: all-results-*
-          path: all-results
-          merge-multiple: true
-      - name: Get scheduled run info
-        id: scheduled-info
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          ID=$(gh run --repo ${{ github.repository }} list --workflow RTLMeter --event schedule --status success --limit 1 --json databaseId --jq ".[0].databaseId")
-          echo "id=$ID" >> $GITHUB_OUTPUT
-          URL=$(gh run --repo ${{ github.repository }} view $ID --json url --jq ".url")
-          echo "url=$URL" >> $GITHUB_OUTPUT
-          NUM=$(gh run --repo ${{ github.repository }} view $ID --json number --jq ".number")
-          echo "num=$NUM" >> $GITHUB_OUTPUT
-          DATE=$(gh run --repo ${{ github.repository }} view $ID --json createdAt --jq ".createdAt")
-          echo "date=$DATE" >> $GITHUB_OUTPUT
-      - name: Download scheduled run results
-        uses: actions/download-artifact@v8
-        with:
-          name: published-results
-          path: nightly-results
-          run-id: ${{ steps.scheduled-info.outputs.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Compare results
-        working-directory: rtlmeter
-        run: |
-          for tag in gcc clang gcc-hier; do
-            ADATA=../nightly-results/all-results-${tag}.json
-            BDATA=../all-results/all-results-${tag}.json
-            touch ../verilate-${tag}.txt
-            touch ../execute-${tag}.txt
-            touch ../cppbuild-${tag}.txt
-            if [[ ! -e $ADATA ]]; then
-              continue
-            fi
-            ./rtlmeter compare --cases '* !Example:* !*:hello' --steps "verilate" --metrics "elapsed memory"              $ADATA $BDATA > ../verilate-${tag}.txt
-            cat ../verilate-${tag}.txt
-            ./rtlmeter compare --cases '* !Example:* !*:hello' --steps "execute"  --metrics "speed memory elapsed"        $ADATA $BDATA > ../execute-${tag}.txt
-            cat ../execute-${tag}.txt
-            ./rtlmeter compare --cases '* !Example:* !*:hello' --steps "cppbuild" --metrics "elapsed memory cpu codeSize" $ADATA $BDATA > ../cppbuild-${tag}.txt
-            cat ../cppbuild-${tag}.txt
-          done
+          path: verilator
+
      - name: Create report
+        id: report
+        working-directory: verilator
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
-          set -x
-          NUM=$(gh run --repo ${{ github.repository }} view ${{ github.run_id }} --json number --jq ".number")
-          URL=$(gh run --repo ${{ github.repository }} view ${{ github.run_id }} --json url    --jq ".url")
-          echo -n "Performance metrics for PR workflow [#$NUM]($URL) (B) compared to scheduled run" > report.txt
-          echo -n " [#${{ steps.scheduled-info.outputs.num }}](${{ steps.scheduled-info.outputs.url }}) (A)" >> report.txt
-          echo    " from ${{ steps.scheduled-info.outputs.date }}" >> report.txt
-          for tag in gcc clang gcc-hier; do
-            echo "" >> report.txt
-            if [[ $tag == "gcc" ]]; then
-              echo "<details open>" >> report.txt
-            else
-              echo "<details>" >> report.txt
-            fi
-            echo -n "<summary><strong><em>" >> report.txt
-            jq -rj ".[0].runName" all-results/all-results-${tag}.json >> report.txt
-            echo "</em></strong></summary>" >> report.txt
-            awk -v RS= -v tag=${tag} '{print > sprintf("frag-%02d-verilate-%s.txt",NR,tag)}' verilate-${tag}.txt
-            awk -v RS= -v tag=${tag} '{print > sprintf("frag-%02d-execute-%s.txt" ,NR,tag)}'  execute-${tag}.txt
-            awk -v RS= -v tag=${tag} '{print > sprintf("frag-$02d-cppbuild-%s.txt",NR,tag)}' cppbuild-${tag}.txt
-            for f in $(ls -1 frag-*-verilate-${tag}.txt | sort) $(ls -1 frag-*-execute-${tag}.txt | sort) $(ls -1 frag-*-cppbuild-${tag}.txt | sort); do
-              if [[ $f == frag-01-verilate-${tag}.txt || $f == frag-01-execute-${tag}.txt ]]; then
-                echo "<details open>" >> report.txt
-              else
-                echo "<details>" >> report.txt
-              fi
-              echo -n "<summary>" >> report.txt
-              head -n 1 $f | tr -d '\n' >> report.txt
-              echo "</summary>" >> report.txt
-              echo '<pre>' >> report.txt
-              tail -n +2 $f >> report.txt
-              echo '</pre>' >> report.txt
-              echo "</details>" >> report.txt
-            done
-            echo "</details>" >> report.txt
-          done
-          cat report.txt
+          ln -s ../rtlmeter rtlmeter
+          gh repo set-default ${{ github.repository }}
+          # Create run report - save status to fail job if the script did
+          STATUS=0
+          ci/ci-rtlmeter-report.bash ${{ github.run_id }} ${{ github.sha }} ${{ needs.combine-results.outputs.run-tags }} || STATUS=$?
+          echo "status=$STATUS" >> "$GITHUB_OUTPUT"
+          # Create the report artifact
+          mkdir ../report-artifact
+          mv rtlmeter-report/report ../report-artifact/
+          echo ${{ github.event.number }} > ../report-artifact/pr-number.txt
+
      - name: Upload report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
        with:
-          path: report.txt
-          name: rtlmeter-pr-results
-      - name: Save PR number
-        run: echo ${{ github.event.number }} > pr-number.txt
-      - name: Upload PR number
-        uses: actions/upload-artifact@v7
+          path: report-artifact
+          name: rtlmeter-report
+
+      - name: Upload PR notification
+        uses: ./verilator/.github/actions/upload-pr-notification
        with:
-          path: pr-number.txt
-          name: pr-number
+          path: verilator/rtlmeter-report/notification
+          key: rtlmeter
+
+      - name: Report status
+        run: exit ${{ steps.report.outputs.status }}

  # Create GitHub issue for failed scheduled jobs
  # This should always be the last job (we want an issue if anything breaks)
@@ -394,9 +396,9 @@ jobs:
      # Creating issues requires elevated privilege
      - name: Generate access token
        id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
        with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
          private-key: ${{ secrets.VERILATOR_CI_KEY }}
          owner: verilator
          repositories: verilator
@@ -0,0 +1,148 @@
+<!-- DESCRIPTION: Verilator: Repository-wide guidelines for AI coding agents
+     SPDX-FileCopyrightText: 2026-2026 Wilson Snyder
+     SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -->
+
+# Verilator Guidelines for AI Coding Agents
+
+These files are the general layer an agent loads first -- nearest file wins, so
+you read this repository-root file plus the one for the directory you are
+editing. They stay deliberately high-level: where to start, how the tree is laid
+out, and the conventions reviewers otherwise enforce by hand. They are an index,
+not the architecture reference -- for depth (how a pass works internally, the
+algorithms, node lifetime) they point you to `docs/internals.rst`. When the
+guidance here is not enough, that is where to look next.
+
+This file has two parts. **Orientation** gets you productive in the codebase from
+a cold start. **Before you open a PR** is the checklist of conventions reviewers
+otherwise have to enforce by hand -- read it before submitting any change.
+
+Then read the directory guide for the area you are editing:
+
+- [src/AGENTS.md](src/AGENTS.md) -- compiler C++ sources: AST, visitors, passes, parser, style
+- [include/AGENTS.md](include/AGENTS.md) -- runtime library (`verilated*`): C++14, MT-safety, fixed-width types
+- [test_regress/AGENTS.md](test_regress/AGENTS.md) -- regression tests: harness, drivers, golden files
+- [docs/AGENTS.md](docs/AGENTS.md) -- documentation (`*.rst`)
+
+______________________________________________________________________
+
+# Orientation
+
+## What Verilator is
+
+Verilator is a *compiler*, not an interpreter. It translates synthesizable (and
+much behavioral) SystemVerilog into a cycle-accurate C++ model that you then
+compile and run. Almost every decision is made at compile ("verilation") time;
+the generated C++ just advances state each evaluation. Optimize for verilation-
+time work over runtime work.
+
+## The pipeline is the spine
+
+A run is an ordered sequence of passes over one shared AST (abstract syntax
+tree). In source order:
+
+| Stage | What it does | Key files |
+|---|---|---|
+| Preprocess + parse | Lex and parse text into a raw AST -- builds nodes only, no semantic checks | `verilog.l`, `verilog.y` |
+| Link / elaborate | Resolve names, scopes, parameters; instantiate the hierarchy | `V3LinkParse`, `V3LinkDot`, `V3Param` |
+| Width / type | Assign and check data types and bit widths | `V3Width` |
+| Transform / optimize / schedule | Constant fold, lower language features, schedule events | `V3Const`, `V3Randomize`, `V3Assert*`, `V3Sched`, `V3Timing`, `V3Dfg` |
+| Emit | Lower the final AST to generated C++ | `V3EmitC*` |
+| Runtime | Library the generated model links against | `include/verilated*` |
+
+This table is the map; `docs/internals.rst` has the detail behind each stage.
+
+## Where to make a change
+
+Map the symptom to the pass that owns it, then start by reading that pass's
+top-of-file comment.
+
+| Symptom or feature area | Start in |
+|---|---|
+| Type/width error, "what type is this", implicit conversion | `V3Width` |
+| Name/scope/parameter resolution ("Can't find...", hierarchy) | `V3LinkDot`, `V3Param` |
+| `randomize` / `constraint` / `rand` / `randc` | `V3Randomize` |
+| `assert` / `property` / `sequence` / `cover` | `V3Assert`, `V3AssertPre`, `V3AssertNfa` |
+| `fork` / timing / `#delay` / NBA / event scheduling | `V3Sched`, `V3Timing`, `V3Fork` |
+| Syntax wrongly accepted or rejected | `verilog.y`, `verilog.l` |
+| Wrong generated C++ | `V3EmitC*` |
+| Runtime model behavior | `include/verilated*` |
+
+## Build and run a test
+
+- Build in the source tree: `autoconf && ./configure && make -j8`. Configure with
+  `--enable-ccwarn` so a new compiler warning stops the build.
+- Run one test from the repository root: `test_regress/t/t_<name>.py`.
+- Run the full regression with `make test`. The complete suite requires
+  configuring with `--enable-longtests` (works on every OS, including macOS).
+
+______________________________________________________________________
+
+# Before you open a PR
+
+## Scope and process
+
+- [ ] Searched open PRs and issues -- duplicating in-flight work wastes review time.
+- [ ] Fixed the general root cause, not just the reported case -- if it also
+  affects other modules/classes/interfaces, cover them or expect rejection.
+- [ ] PR is single-purpose. Refactors, drive-by fixes found along the way, and new
+  features each go in separate PRs; land standalone cleanups first.
+- [ ] Every bug fix has a test that fails *without* the fix; include the issue's
+  own reproducer when possible.
+- [ ] New code aims for 100% line coverage; branch coverage far below line coverage
+  signals guards callers never violate -- justify or remove them.
+- [ ] Ran `make format` (clang-format), `make cppcheck`, and `make lint-py`;
+  self-reviewed the diff for leftover debug code, stale comments, and
+  copy-paste errors.
+- [ ] Ran the full regression on at least one OS before submitting. Partial runs
+  are fine during development, but the submitted PR is expected to pass every
+  test.
+- [ ] Validated the code changes against recommendations in the AGENTS.md files.
+- [ ] Did not edit `docs/CONTRIBUTORS` (humans only) or `Changes` (maintainer
+  updates it near release).
+
+## Drafting a PR
+
+- [ ] When creating a pull request message, omit itemized lists of changed
+  files and changes, since reviewers already have access to the diff.
+
+## Pick the right diagnostic (and its required test)
+
+The API you choose determines which test must accompany the change.
+
+| API | Output | Meaning | Required test |
+|---|---|---|---|
+| `v3error("...")` | `%Error:` | User wrote invalid SystemVerilog | `t_*_bad*.v` + `.out` golden |
+| `v3error("Unsupported: ...")` | `%Error-UNSUPPORTED:` | Legal SV that Verilator does not yet support | `t_*_unsup*.v` + `.out` golden |
+| `v3warn(CODE, "...")` | `%Warning-CODE:` | Legal but suspicious code | warning test + `.out` golden |
+| `v3fatalSrc("...")` | `%Error: Internal Error` | Should-never-happen internal assertion | none -- not user-triggerable |
+
+- Every `v3error`/`v3warn` needs a test in `test_regress/t/` -- enforced by the
+  warn-coverage distribution test. `v3fatalSrc` is exempt.
+- Reserve "Unsupported:" for not-yet-implemented features, never for user mistakes.
+- When an error enforces a spec-defined restriction, cite the clause
+  (`IEEE 1800-2023 11.4.7`) so it is verifiable. Update `docs/guide/warnings.rst`
+  when adding or changing a warning.
+- On error paths, clean up or replace invalid AST (e.g. `AstConst::BitFalse`) so
+  later passes do not crash after the error.
+
+## Cross-cutting code rules
+
+- [ ] No non-ASCII characters in C++ sources or headers: write `--` (two ASCII
+  hyphens) rather than a Unicode em-dash, and a plain `'` rather than a smart
+  quote. At write time, not when CI complains.
+- [ ] Lists stay sorted: lexer/parser tokens, option declarations, enum values,
+  configure feature lists, documented option lists.
+- [ ] `bin/` scripts are Python (distributed cross-platform); `nodist/` may use
+  bash and platform-specific code (developer-only, not packaged).
+- [ ] Runtime code in `include/` targets C++14 (`--no-timing` builds must work);
+  C++20 only in timing code paths.
+- [ ] In `include/` public headers, prefix public classes with `Verilated`/`Vl`
+  and document the API with `///` comments.
+- [ ] A new code pattern is applied globally or not at all -- no one-off
+  convention in a single file.
+
+## Commits
+
+- Subject line is short and imperative and conventionally ends with the PR number:
+  `Support property case (#7721)`. A body is optional and common for non-trivial
+  changes.
@@ -16,7 +16,7 @@ cmake_minimum_required(VERSION 3.15)
 cmake_policy(SET CMP0091 NEW) # Use MSVC_RUNTIME_LIBRARY to select the runtime
 project(
    Verilator
-    VERSION 5.047
+    VERSION 5.052
    HOMEPAGE_URL https://verilator.org
    LANGUAGES CXX
 )
@@ -155,11 +155,12 @@ install(
 foreach(
    program
    verilator
-    verilator_gantt
    verilator_ccache_report
+    verilator_coverage
    verilator_difftree
-    verilator_profcfunc
+    verilator_gantt
    verilator_includer
+    verilator_profcfunc
 )
    install(PROGRAMS bin/${program} TYPE BIN)
 endforeach()
@@ -182,6 +183,6 @@ install(
    PATTERN "include/*.cpp"
    PATTERN "include/*.vlt"
    PATTERN "include/*.sv"
-    PATTERN "include/gtkwave/*.[chv]*"
+    PATTERN "include/fstcpp/*.[chv]*"
    PATTERN "include/vltstd/*.[chv]*"
 )
@@ -1,5 +1,7 @@
 .. for github, vim: syntax=reStructuredText

+.. Maintainers and agents, do not edit this file, it will be updated for you post- PR-merge.
+
 ===============================
 Revision History and Change Log
 ===============================
@@ -8,18 +10,412 @@ The changes in each Verilator version are described below.  The
 contributors that suggested or implemented a given issue are shown in []. Thanks!


-Verilator 5.047 devel
+Verilator 5.052 2026-09-05
 ==========================

 **Important:**

+* Verilator now supports UVM 2020-3.2; see (#1538) for limitations.
+
+**Other:**
+
+* Add comments as a branch description in coverage .info files (#7843). [Eryk Szpotanski]
+* Add --enable-light-debug configure option (#7886). [Geza Lore, Testorrent USA, Inc.]
+* Add user-provided DPI-C function declarations (#7626) (#7893). [Jakub Michalski]
+* Add error on static virtual functions (#7932). [Igor Zaworski, Antmicro Ltd.]
+* Add error when scalar is passed to array task argument (#7948). [Pawel Klopotek]
+* Add MULTIDRIVENPROC warning for signals driven by multiple plain always blocks (#7968). [Aisha]
+* Add FSM arc and state coverage to verilator_coverage .info output (#7972) (#7973). [Igor Zaworski, Antmicro Ltd.]
+* Add SIMILARNAME warning when variables have names that differ in case (#7992) (#8020) (#8186) (#8226) (#8233). [Paul Campbell]
+* Add Unigen2 constrained randomization algorithm (#8042). [Jakub Wasilewski, Antmicro Ltd.]
+* Add `+verilator+assert+lock` to ignore RTL assert control statements (#8086). [Sumanth Kadiyala]
+* Add NEVERMATCH warning when an SVA sequence can never match (#8176) (#8183). [Artur Bieniek, Antmicro Ltd.]
+* Remove and deprecate `--assert-unroll-limit`. (#8096). [Artur Bieniek, Antmicro Ltd.]
+* Support embedded covergroup member references (#7749) (#8015). [Marco Bartoli]
+* Support a sequence used as an event control (#7797) (#7846). [Yilou Wang]
+* Support `[\*N:$]` consecutive repetition (#7940). [Artur Bieniek, Antmicro Ltd.]
+* Support dynamic containers in unique constraints (#7947). [Adam Kostrzewski, Antmicro Ltd.]
+* Support delayed tristate gates (#7960) (#7961). [Patrick Creighton]
+* Support `default clocking` (#7984). [Kamil Danecki, Antmicro Ltd.]
+* Support embedded covergroup clocking events (#8028). [Marco Bartoli]
+* Support `weak`/`strong` keywords in property expressions (#8054). [Artur Bieniek, Antmicro Ltd.]
+* Support class handle covergroup arguments (#8071). [Marco Bartoli]
+* Support `soft foreach` constraints (#8174). [Kamil Danecki, Antmicro Ltd.]
+* Support overlong `within` sequences as never-matching (#8177). [Artur Bieniek, Antmicro Ltd.]
+* Support covergroup/function/task (ref/virtual/array) interface arguments (#8180). [Marco Bartoli]
+* Support covergroup events with reference members or ref arguments (#8201). [Marco Bartoli]
+* Support s_until/s_until_with in property expression (#8220). [Artur Bieniek, Antmicro Ltd.]
+* Support solve before with associative array (#8232). [Kamil Danecki, Antmicro Ltd.]
+* Optimize random initialization. [Geza Lore, Testorrent USA, Inc.]
+* Optimize more always blocks in DFG (#7775). [Geza Lore, Testorrent USA, Inc.]
+* Optimize assertion NFAs using bit-vector ring buffers (#7885). [Artur Bieniek, Antmicro Ltd.]
+* Optimize circular logic in DFG (#7902). [Geza Lore, Testorrent USA, Inc.]
+* Optimize VPI symbol registration and scope construction (#7936). [Nick Brereton]
+* Optimize bounded always properties using ring buffers (#8061) (#8092). [Artur Bieniek, Antmicro Ltd.]
+* Optimize VL_WORDS_I/VL_BYTES_I (#8095). [Geza Lore, Testorrent USA, Inc.]
+* Optimize consecutive and goto repetitions using ring buffers (#8096). [Artur Bieniek, Antmicro Ltd.]
+* Optimize temporary insertion for single bit replicates in DFG (#8110). [Geza Lore, Testorrent USA, Inc.]
+* Optimize mtask coarsening in multi-threaded scheduling (#8120). [Geza Lore, Testorrent USA, Inc.]
+* Optimize NFA delay-ring edge traversal, drop complexity to linear (#8145). [Artur Bieniek, Antmicro Ltd.]
+* Optimize associative constant patterns to fixed point (#8147) (#8209). [Geza Lore, Testorrent USA, Inc.]
+* Fix procedural tristate assignment overrides (#6785) (#8130). [Eddie Rydell]
+* Fix $finish continuing event loop (#7267) (#7950). [Artur Bieniek, Antmicro Ltd.]
+* Fix continuing on wait(0) (#7372) (#8231). [Szymon Gizler, Antmicro Ltd.]
+* Fix $display accepting streaming concat arguments (#7663) (#7890). [Jaeuk Lee]
+* Fix typedef clocking input sampling (#7688 partial) (#8204). [Marco Bartoli]
+* Fix DFG misoptimizing bound checks (#7755). [Jakub Michalski]
+* Fix unique0 case side effects (#7787). [Pawel Klopotek]
+* Fix mid-window disable iff (#7792) (#7869). [Yilou Wang]
+* Fix cleaning purity cache after assertions. [Geza Lore, Testorrent USA, Inc.]
+* Fix uncaught type error leading to invalid C++ output (#7814). [Geza Lore, Testorrent USA, Inc.]
+* Fix internal error for coverpoints that reference a covergroup formal parameter (#7853 partial) (#7889). [Matthew Ballance]
+* Fix immediate disable of fork join branches (#7856) (#7931). [Marco Bartoli]
+* Fix self-disable of named blocks with forks (Part of #7857) (#7996) (#8006). [Marco Bartoli]
+* Fix clang++ ambiguous overload of '==' operator (#7863). [Pawel Kojma, Antmicro Ltd.]
+* Fix heap-use-after-free in `VlRNG::VlRNG()` (#7865). [Dragon-Git]
+* Fix mixed-width inside and dist range bounds failing randomization (#7875). [Yilou Wang]
+* Fix solve-before over array variables failing randomization (#7876). [Yilou Wang]
+* Fix scoped randomize with array members under rand_mode (#7877). [Yilou Wang]
+* Fix dist constraint on a frozen variable failing randomization (#7878). [Yilou Wang]
+* Fix range delays with parameter bounds (#7882). [Artur Bieniek, Antmicro Ltd.]
+* Fix --coverage on labeled inline assert/cover property (#7898) (#7904). [Patrick Creighton]
+* Fix memory leak in VerilatedFst::close() (#7899). [Jakub Michalski]
+* Fix spurious FSM COVERIGN on comparisons (#7900) (#7908). [Yogish Sekhar]
+* Fix release of forced port nets (#7901) (#7907). [Artur Bieniek, Antmicro Ltd.]
+* Fix independent force of multiply instantiated signals (#7905). [Artur Bieniek, Antmicro Ltd.]
+* Fix scheduling of variables written in non-inlined functions in suspendable processes (#7909). [Igor Zaworski, Antmicro Ltd.]
+* Fix randomization of unreferenced rand members of unpacked structs (#7910) (#7911). [Philip Axer]
+* Fix VL_TO_STRING function for array of structs (#7912). [Kornel Uriasz, Antmicro Ltd.]
+* Fix queues falling into wrong template spec (#7914). [Adam Kostrzewski, Antmicro Ltd.]
+* Fix type resolution when a local name shadows a type name (#7915). [Pawel Klopotek]
+* Fix crash streaming an unpacked array of unpacked structs (#7917). [Nick Brereton]
+* Fix streaming concat as output-port lvalue into unpacked struct (#7918). [Nick Brereton]
+* Fix dropping variable writes across opaque calls (#7921) (#7933). [Philip Axer]
+* Fix dynamic array handling in solve...before (#7922). [Kornel Uriasz, Antmicro Ltd.]
+* Fix unlinked error with function call in derived class parameter (#7923). [Mateusz Gancarz, Antmicro Ltd.]
+* Fix scheduling of variables written in non-inlined functions in suspendable processes (#7924). [Igor Zaworski, Antmicro Ltd.]
+* Fix class parameter resolution (#7935).
+* Fix FSM detection of coverage-only branches (#7941) (#7942). [Patrick Creighton]
+* Fix use-after-free in V3LinkDotIfaceCapture (#7943). [Nick Brereton]
+* Fix sampled-value clocks in repeated assertions (#7944). [Artur Bieniek, Antmicro Ltd.]
+* Fix queued $finish/$stop request thread ordering (#7946 prep) (#7952). [Yilou Wang]
+* Fix NFA assertion scheduling to fix outcome counts (#7946). [Yilou Wang]
+* Fix DFG nested shifts with overflowing shift amount (#7955) (#7977).
+* Fix timing controls in interface tasks called via virtual interface (#7959). [Yilou Wang]
+* Fix lambda parameter types in queue min and max (#7962). [Bartosz Skorowski]
+* Fix solve-before dropping all soft constraints in randomize() (#7963). [Yilou Wang]
+* Fix generic interface param resolution in module/cell parameterization (#7970) (#7971). [David Garau]
+* Fix lost writes when select width exceeds variable width (#7975). [Bartosz Skorowski]
+* Fix $fgets being mis-optimized away (#7976). [G-A. Kamendje]
+* Fix SYNCASYNCNET false positive with changed non-edge logic (#7980). [Oron Port]
+* Fix variable scope in unique on dynamic array (#7981). [Kornel Uriasz, Antmicro Ltd.]
+* Fix table optimization causing not contextually convertible to bool error (#7983). [Jakub Michalski]
+* Fix wait fork trigger temporary split across generated functions (#7985) (#7986). [Marco Brambilla]
+* Fix randc cycling in a class that also uses solve...before (#7991 partial) (#8055). [Yilou Wang]
+* Fix solver session stability to avoid breaking randomize (#7991 partial). [Yilou Wang]
+* Fix simulation hang when the solver stops answering (#7991 partial) (#8129) (#8136). [Yilou Wang]
+* Fix randomize() with a user variable named 'item' (#7993) (#7994).
+* Fix UNSATCONSTR reporting constraint indices above 9 (#7995). [Yilou Wang]
+* Fix MULTIDRIVEN/MULTIDRIVENPROC warning suppression via lint_off (#8000). [Gilberto Abram]
+* Fix force not substituted into an unpacked array index (#8002).
+* Fix dist weights ignored when an item is not a literal (#8003).
+* Fix error when forcing an array element read at a run-time index (#8004).
+* Fix FSM coverage on empty reset branches (#8005) (#8064). [Yogish Sekhar]
+* Fix missing verilator_coverage in cmake install (#8008) (#8011).
+* Fix dist inside a foreach nested in a constraint if (#8016).
+* Fix gcov dump on warnings discarding later coverage counts (#8017). [Yilou Wang]
+* Fix unique constraint crash, guards, and size (#8018).
+* Fix Linux peak memory stat to use VmHWM (#8022) (#8070). [Tyrone Marhguy]
+* Fix assignment pattern key constant expressions (#8029) (#8030). [Josep Sans]
+* Fix skipping optimization for unpacked data types (#8031). [Kornel Uriasz, Antmicro Ltd.]
+* Fix gate deduplication with function arguments (#8038). [JOTEGO]
+* Fix conditional expression with parameterized classes (#8039). [Pawel Klopotek, Antmicro Ltd.]
+* Fix array size references in constraints (#8040). [Kornel Uriasz, Antmicro Ltd.]
+* Fix mid-range consecutive repetition rejects (#8041). [Artur Bieniek, Antmicro Ltd.]
+* Fix write access to dynamic arrays (#8043). [Bartosz Skorowski, Antmicro Ltd.]
+* Fix nondeterminism in trace stage (#8046). [Sumanth Kadiyala]
+* Fix force helpers in multiply instantiated modules (#8047). [Artur Bieniek, Antmicro Ltd.]
+* Fix pin to non-existent port with PINNOTFOUND suppressed (#8051) (#8052). [Nikolai Kumar]
+* Fix wildcard equality against a 4-state constant in an assertion (#8056) (#8057). [Nikolai Kumar]
+* Fix untyped datatype error on sampling functions with property arguments (#8060). [Artur Bieniek, Antmicro Ltd.]
+* Fix VPI cbValueChange for 1-bit select (#8063). [Bartłomiej Chmiel, Antmicro Ltd.]
+* Fix NFA assertion crash and mis-counted property if/case (#8074). [Yilou Wang]
+* Fix skipping non-constrained enum constraining when inside object of other class (#8075). [Kornel Uriasz, Antmicro Ltd.]
+* Fix use-after-free of captured interface typedef reference during parameter cloning (#8076). [em2machine]
+* Fix unintended side-effect insertion on associative array read (#8077). [Adam Kostrzewski, Antmicro Ltd.]
+* Fix undefined symbol solver error (#8080). [Igor Zaworski, Antmicro Ltd.]
+* Fix unpacked array element force with procedural assign (#8084) (#8085). [Nikolai Kumar]
+* Fix reading another parameter resolves to 0 in cloned modules (#8086)  (#8069). [em2machine]
+* Fix hierarchical class scope resolution (#8094). [Artur Bieniek, Antmicro Ltd.]
+* Fix segmentation fault on parameters (#8102) (#8149). [Sumanth Kadiyala]
+* Fix the clang compilation using precompiled headers (#8105). [Demin Han]
+* Fix invalid typedef (#8106). [Adam Kostrzewski, Antmicro Ltd.]
+* Fix R/W references to random builtin function seeds (#8112). [Geza Lore, Testorrent USA, Inc.]
+* Fix invalid C++ on cast (#8113). [Pawel Klopotek, Antmicro Ltd.]
+* Fix COVERIGN on SVA goto repetition (#8118). [Artur Bieniek, Antmicro Ltd.]
+* Fix unordered data hazards in multi-threaded scheduling (#8133). [Geza Lore, Testorrent USA, Inc.]
+* Fix public table offsets larger than 32 bits (#8135). [Sunimali Rathnayake]
+* Fix 'get-value' for empty constrained arrays (#8138). [Kornel Uriasz, Antmicro Ltd.]
+* Fix streaming concatenation uninitialized read-modify-write access (#8143). [Geza Lore, Testorrent USA, Inc.]
+* Fix unpacked array passing to logic task argument error (#8148). [Pawel Klopotek, Antmicro Ltd.]
+* Fix $past in final blocks on a sampling-tick finish (#8153). [Yilou Wang]
+* Fix array reference in reduction constraints (#8158). [Kornel Uriasz, Antmicro Ltd.]
+* Fix VPI force data corruption (#8160). [Jonathan Drolet]
+* Fix sampled-value functions output on the first cycle (#8162). [Artur Bieniek, Antmicro Ltd.]
+* Fix null pointer dereference in process destruction (#8171). [Andrii, Antmicro Ltd.]
+* Fix invalid conversion of queue (#8172). [Andrii, Antmicro Ltd.]
+* Fix crash on forward-referencing parameters (#8175). [Geza Lore, Testorrent USA, Inc.]
+* Fix crash on empty `#()` parameter list on class instance (#8182). [Geza Lore, Testorrent USA, Inc.]
+* Fix crash on multiple missing type parameters (#8184). [Geza Lore, Testorrent USA, Inc.]
+* Fix SVA bound limit guard, leave headroom for alignment, respect --max-num-width (#8192). [Artur Bieniek, Antmicro Ltd.]
+* Fix internal error on an enum literal inside a `with` lambda body (#8190) (#8193). [Aditya Shevade]
+* Fix internal error on backslash-quoted strings (#8198). [Henry Hsieh]
+* Fix backslash behavior in string literals (#8211). [Pawel Klopotek, Antmicro Ltd.]
+* Fix task inout pin resizing error (#8212). [Pawel Klopotek, Antmicro Ltd.]
+* Fix code generation for postponed region (#8218). [Geza Lore, Testorrent USA, Inc.]
+* Fix method calls to be a reorder barrier (#8222). [Matthew Ballance]
+* Fix errors on stream connected to instance port (#8234). [Geza Lore, Testorrent USA, Inc.]
+* Fix folding of short circuiting operators guarding member access (#8238). [Geza Lore, Testorrent USA, Inc.]
+* Fix MULTIDRIVENPROC on static loop induction variables (#8242). [Geza Lore, Testorrent USA, Inc.]
+* Fix multiply undefined behavior on signed int overflow (#8247) (#8248). [Paul Rigge]
+* Fix initial statements with gate optimization (#8250). [Prithayan Barua]
+* Fix segmentation fault on context destruction (#8265).
+* Fix mis-randomizing an unpacked struct member when not rand/randc (#8277) (#8278). [Aditya Shevade]
+* Fix std::randomize() with-clause array index arguments (#8279) (#8280). [Aditya Shevade]
+* Fix incorrect reference to sync/async in SYNCASYNCNET warning (#8281). [Andrii, Antmicro Ltd.]
+* Fix use-after-free of captured interface typedef in deleted generate branch (#8287). [Nick Brereton]
+
+
+Verilator 5.050 2026-07-01
+==========================
+
+**Important:**
+
+* Support covergroups, coverpoints, and bins (#784) (#7117) (#7728). [Matthew Ballance]
+* Support new FST writer API (#6871) (#6992). [Yu-Sheng Lin]
+  Use of FST may requiring installing liblz4 and/or liblz4-dev packages, see docs/install.rst.
+
+**Other:**
+
+* Add `+verilator+log+file` (#4505) (#7645). [Tracy Narine]
+* Add peak memory usage to `--stats`. [Geza Lore, Testorrent USA, Inc.]
+* Add error on mixed-initialization (#7352) (#7357).
+* Add `--coverage-per-instance` (#7636). [Yogish Sekhar]
+* Add NOTREDOP error on reduction and negation operators (#7417) (#7623) (#7624).
+* Add hierarchy-aware reporting to `verilator_coverage` (#7657). [Yogish Sekhar]
+* Add FINALDLY error (#7754). [Igor Zaworski, Antmicro Ltd.]
+* Deprecate isolate_assignments attribute (#7774) (#7144). [Geza Lore, Testorrent USA, Inc.]
+* Improve `--coverage-fsm` (#7490) (#7529) (#7561) (#7573) (#7619). [Yogish Sekhar]
+* Change `+verilator+seed` to default to 1, and 0 to randomly select (#7325) (#7516). [Miguel]
+* Change JSON to include parameter constant mnemonics for FSM Coverage (#7531). [Yogish Sekhar]
+* Support assert property `default disable iff` (#4848) (#7723). [Artur Bieniek, Antmicro Ltd.]
+* Support printing enum names for %p and %s (#5523) (#7338 repair) (#7521) (#7527). [Nick Brereton]
+* Support weak `until` / `until_with` property operators (#7290) (#7548) (#7685). [Yilou Wang]
+* Support `s_eventually` (#7291) (#7508). [Bartłomiej Chmiel, Antmicro Ltd.]
+* Support writing to inout in fork after timing (#7345). [Kamil Danecki, Antmicro Ltd.]
+* Support `always` / `always[m:n]` / `s_always[m:n]` property operators (#7482). [Yilou Wang]
+* Support rand_mode() on static rand class members (#7484) (#7510). [Yilou Wang]
+* Support `randomize() with (identifier_list) {constraint_block}` (#7486) (#7507). [Yilou Wang]
+* Support `obj.randomize(null)` (#7487) (#7509). [Yilou Wang]
+* Support functions on RHS of force (#7491). [Artur Bieniek, Antmicro Ltd.]
+* Support procedural continuous assign/deassign (#7493). [Artur Bieniek, Antmicro Ltd.]
+* Support randsequence production function ports (#7522). [Yilou Wang]
+* Support followed-by operators `#-#` and `#=#` in properties (#7523). [Yilou Wang]
+* Support expression coverage on assign statements (#7542) (#7543). [Thomas Brown]
+* Support TERMUX (#7559). [Laurent CHARRIER]
+* Support NBAs in initial blocks with delay/event controls (#7566) (#7600). [Muzaffer Kal]
+* Support SVA goto repetition with range `[->M:N]` (#7569). [Yilou Wang]
+* Support property abort operators (accept_on, reject_on) (#7578). [Yilou Wang]
+* Support procedural concurrent assertions with inferred clock (#7581). [Yilou Wang]
+* Support calling interface functions without parens (#7584). [Krzysztof Bieganski, Antmicro Ltd.]
+* Support streaming on queues (#7597). [Benjamin Collier, Secturion Systems, Inc.]
+* Support clocking event on a sequence declaration body (#7598) (#7793). [Yilou Wang]
+* Support generic interface arrays (#7604). [Krzysztof Bieganski, Antmicro Ltd.]
+* Support FSM detection in primitive wrappers (#7607). [Yogish Sekhar]
+* Support busses with mix of pullup/pulldown (#7632). [Lucas Amaral]
+* Support forceable on unpacked array variables (#7677) (#7678). [Nikolai Kumar]
+* Support pre/post increment/decrement inside && and || (#7683). [Nick Brereton]
+* Support streaming into 2-D unpacked arrays (#7686) (#7687). [Paul Swirhun]
+* Support if/if-else in properties (#7692). [Artur Bieniek, Antmicro Ltd.]
+* Support process::self().srand() (#7695). [Igor Zaworski, Antmicro Ltd.]
+* Support MacOS lldb (#7697). [Tracy Narine]
+* Support assoc array methods with wide value types (#7680). [pawelktk]
+* Support property case (#7682) (#7721). [Artur Bieniek, Antmicro Ltd.]
+* Support `s_until` and `s_until_with`(#7722). [Artur Bieniek, Antmicro Ltd.]
+* Support covergroup runtime model Phase A1 (#7728). [Matthew Ballance]
+* Support hierarchical reference cross members (#7749) (#7820). [Matthew Ballance]
+* Support reduction XOR/AND operations in constraints (#7753). [Kornel Uriasz, Antmicro Ltd.]
+* Support NBAs in initial blocks (#7754). [Igor Zaworski, Antmicro Ltd.]
+* Support assertion control system tasks in classes and interfaces (#7761). [Yilou Wang]
+* Support cover sequence statement (#7764). [Yilou Wang]
+* Support unpacked struct stream (#7767). [Nick Brereton]
+* Support $assertcontrol control_type from lock to kill (#7788). [Yilou Wang]
+* Support unbounded always [m:$] and strong s_always liveness (#7798). [Yilou Wang]
+* Support method calls on a sub-interface via a virtual interface (#7800). [Yilou Wang]
+* Support global $assertcontrol (#7807). [Artur Bieniek, Antmicro Ltd.]
+* Support VPI access to unpacked struct members (#7823). [Nick Brereton]
+* Support variable-length intersect in SVA sequences (#7835). [Yilou Wang]
+* Support dynamic loading of VPI extensions (#7727). [Matthew Ballance]
+* Optimize DFG cycle breaking to do less work (#7210). [Geza Lore, Testorrent USA, Inc.]
+* Optimize emitting to_string() for compiler speedup (#7468). [Jakub Michalski, Antmicro Ltd.]
+* Optimize additional DFG peephole cases (#7553). [Varun Koyyalagunta, Testorrent USA, Inc.]
+* Optimize forced signal handling (#7554 partial) (#7572) (#7594) (#7596). [Krzysztof Bieganski, Artur Bieniek, Antmicro Ltd.]
+* Optimize primitive runtime functions. [Geza Lore, Testorrent USA, Inc.]
+* Optimize if branches with same trailing statements (#7674). [Geza Lore, Testorrent USA, Inc.]
+* Optimize wide conditional expansion in V3Premit (#7691). [Geza Lore, Testorrent USA, Inc.]
+* Optimize VL_ONEHOT. [Geza Lore, Testorrent USA, Inc.]
+* Optimize formatting functions (#7701) (#7702) (#7703). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DPI import argument passing (#7704). [Geza Lore, Testorrent USA, Inc.]
+* Optimize runtime assertOn() checks (#7707). [Geza Lore, Testorrent USA, Inc.]
+* Optimize $countones and $onehot in DFG. [Geza Lore, Testorrent USA, Inc.]
+* Optimize procedural loop unrolling. [Geza Lore, Testorrent USA, Inc.]
+* Optimize V3Gate inlining heuristic (#7716). [Geza Lore, Testorrent USA, Inc.]
+* Optimize reset in DFG (#7737). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG with relaxed live variable analysis (#7739). [Geza Lore, Testorrent USA, Inc.]
+* Optimize conditional patterns sharing common MBSs/LSBs in DfgPeephole (#7760). [Geza Lore, Testorrent USA, Inc.]
+* Optimize bit select removal earlier in DFG (#7762). [Geza Lore, Testorrent USA, Inc.]
+* Optimize away proven redundant case statement assertions (#7771). [Geza Lore, Testorrent USA, Inc.]
+* Optimize table lookups in DFG (#7772). [Geza Lore, Testorrent USA, Inc.]
+* Optimize input combinational logic by change detection (#7784). [Geza Lore, Testorrent USA, Inc.]
+* Optimize decoder case statements into lookup tables (#7795). [Geza Lore, Testorrent USA, Inc.]
+* Optimize wide decoder case statements into decoder expressions (#7804). [Geza Lore, Testorrent USA, Inc.]
+* Optimize statically known oversize shifts (#7806). [Geza Lore, Testorrent USA, Inc.]
+* Optimize generated function inlining (#7811). [Geza Lore, Testorrent USA, Inc.]
+* Optimize bit-scan loops into most-set-bit or $countones (#7822). [Thomas Santerre]
+* Optimize additional expression patterns (#7824). [Geza Lore, Testorrent USA, Inc.]
+* Optimize module inlining heuristic (#7837). [Geza Lore, Testorrent USA, Inc.]
+* Fix `$bits` on unpacked structs (#4521) (#7796). [Nick Brereton]
+* Fix TSP variable ordering for mtasks (#5342) (#7610). [Muzaffer Kal]
+* Fix inlining static initializer in V3Gate (#5381) (#7503). [Andrew Nolte] [Geza Lore, Testorrent USA, Inc.]
+* Fix timed nested fork block with disable (#6720) (#7743). [Marco Bartoli]
+* Fix segmentation fault when using --trace with --lib-create (#7299) (#7518). [anonkey]
+* Fix cross-hierarchy tristate drivers of interface nets (#7339) (#7801). [Yilou Wang]
+* Fix destructive event state before dynamic waits (#7340). [Nick Brereton]
+* Fix ALWCOMBORDER on variable ordering (#7350) (#7608). [Cookie]
+* Fix false MULTIDRIVEN warning on always_ff variables (#7351) (#7621) (#7672).
+* Fix array pattern concatenation (#7401) (#7402). [Greg Davill]
+* Fix fairness in `std::semaphore` (#7435) (#7605). [Krzysztof Bieganski, Antmicro Ltd.]
+* Fix generic interface port forwarded to a nested instance (#7454) (#7457). [Yilou Wang]
+* Fix internal error on multi-cycle SVA under default clocking (#7472) (#7506). [Yilou Wang]
+* Fix internal error instead of missing prototype error (#7485). [Alex Solomatnikov]
+* Fix mailbox#(packed_struct) type mismatch with parameterized class (#7494) (#7495). [Nikolai Kumar]
+* Fix std::randomize internal error on static member of different class (#7498) (#7499). [Alex Solomatnikov]
+* Fix assert under assert error (#7500) (#7513). [Nikolai Kumar]
+* Fix std::unique_ptr with incomplete type for clang (#7501) (#7526).
+* Fix virtual interface method call inlining and IMPURE suppression (#7505). [Nikolay Puzanov]
+* Fix expression coverage in loops (#7511). [Todd Strader]
+* Fix $bits on local struct with chained-interface (#7515) (#7517).
+* Fix array indexing side effects in compound assignments (#7519) (#7540) (#7544). [Kamil Danecki, Antmicro Ltd.]
+* Fix class::localparam during elaboration (#7524) (#7534).
+* Fix dearray variable scope error (#7530) (#7602).
+* Fix nested parameterized class typedef chain (#7538). [Michael Rogenmoser]
+* Fix events in observed region (#7546). [Todd Strader]
+* Fix regression rejecting boolean `!x` inside sequence expressions (#7549) (#7551). [Yilou Wang]
+* Fix exponential expansion in V3Gate (#7550). [Geza Lore, Testorrent USA, Inc.]
+* Fix internal error on consecutive repetition with N > 256 (#7552) (#7603). [Yilou Wang]
+* Fix inherited rand array with .size + foreach constraint (#7558) (#7650). [Yilou Wang]
+* Fix biased bit distribution under value < (1 << N) constraints (#7563) (#7684). [Yilou Wang]
+* Fix HIERPARAM lint checking (#7570) (#7690). [em2machine]
+* Fix display of %m in non-first argument (#7574).
+* Fix floating point compile warning on min/max delays.
+* Fix force of unpacked arrays (#7579) (#7580). [Zubin Jain]
+* Fix property argument retaining type of the previous variable (#7582). [Jakub Michalski]
+* Fix NBA to whole arrays (#7583) (#7575). [Geza Lore, Testorrent USA, Inc.]
+* Fix wrong false assert for property local variables with cycle-delayed consequents (#7587) (#7651). [Yilou Wang]
+* Fix interface instance name collision (#7591) (#7593). [Stuart Morris]
+* Fix process comparison compile error with `--public-flat-rw` (#7592).
+* Fix CPU pinning when no 'core id' present (#7599). [Geza Lore, Testorrent USA, Inc.]
+* Fix access to parameters via class::localparam (#7609) (#7671). [em2machine]
+* Fix clocking-block sample of unpacked array (#7612) (#7613). [Nikolai Kumar]
+* Fix type parameters order (#7615) (#7653) (#7693). [Kamil Danecki, Antmicro Ltd.]
+* Fix unique_index method on assoc arrays with values differing from the keys (#7616). [Pawel Klopotek]
+* Fix wide equality comparison in unpacked structs (#7618). [Geza Lore, Testorrent USA, Inc.]
+* Fix force determinism (#7620) (#7637). [Artur Bieniek, Antmicro Ltd.]
+* Fix reference counting for modport task references (#7628). [Nick Brereton]
+* Fix internal error when handling typedefs containing parameterized class type members (#7635) (#7661). [em2machine]
+* Fix forceable signal with a procedural continuous assign (#7638) (#7639). [Zubin Jain]
+* Fix scheduling of virtual interface method writes (#7641). [Artur Bieniek, Antmicro Ltd.]
+* Fix implicit conversions of VlWide (#7642). [Geza Lore, Testorrent USA, Inc.]
+* Fix CASEINCOMPLETE to not warn on `unique0 case` (#7647).
+* Fix hierarchical coverage counts for duplicate no-inline module instances (#7649). [Yogish Sekhar]
+* Fix dropped iff guard on clocking inside task (#7658) (#7659). [Nikolai Kumar]
+* Fix runtime speed summary report. [Geza Lore, Testorrent USA, Inc.]
+* Fix reserved keywords reaching emitter (#7666). [Pawel Kojma, Antmicro Ltd.]
+* Fix width of unsized literal in property expression (#7668). [Artur Bieniek, Antmicro Ltd.]
+* Fix loss of events due to bit shift (#7670). [Artur Bieniek, Antmicro Ltd.]
+* Fix parameter read through locally-declared interface instance (#7679). [Nick Brereton]
+* Fix skipping nulls in $sscanf (#7689).
+* Fix bounds checks in expressions with read/write references (#7694). [Ryszard Rozak, Antmicro Ltd.]
+* Fix (const) ref default task argument handling (#7698). [Nick Brereton]
+* Fix `ref` argument type check for packed arrays with differing range directions (#7700). [Nick Brereton]
+* Fix ignoring not-found modules with encoded names (#7706). [Igor Zaworski, Antmicro Ltd.]
+* Fix MULTIDRIVEN in generates (#7709). [Todd Strader]
+* Fix parameter pollution when using class parameters (#7711) (#7763). [em2machine]
+* Fix Makefile action to not write to ${srcdir} (#7715). [Larry Doolittle]
+* Fix splitting functions containing fork logic (#7717). [Mateusz Gancarz, Antmicro Ltd.]
+* Fix optimizations of assignments with timing controls (#7718). [Ryszard Rozak, Antmicro Ltd.]
+* Fix s_eventually on interface (#7731) (#7733). [Marco Bartoli]
+* Fix parameter values in coverage bins widths (#7732) (#7734). [Marco Bartoli]
+* Fix configure fall back on dynamic malloc libraries (#7736). [Geza Lore, Testorrent USA, Inc.]
+* Fix crash on overlapping priority case. [Geza Lore, Testorrent USA, Inc.]
+* Fix s_eventually in parameterized interfaces (#7741). [Nick Brereton]
+* Fix dpi export pointers (#7742) (#7751). [Yilin Li]
+* Fix force on unpacked bit select (#7744) (#7745). [Nikolai Kumar]
+* Fix `$` as unsupported coverpoint-bin range bounds (#7750) (#7825). [Matthew Ballance]
+* Fix FSM detect unchecked casts and variable redeclaration (#7758). [Adam Kostrzewski, Antmicro Ltd.]
+* Fix no-scope internal error on virtual interface method calls (#7759). [Yilou Wang]
+* Fix `case (_) inside` with x wildcards (#7766). [Geza Lore, Testorrent USA, Inc.]
+* Fix not failing assertion when RHS of a range window rejects once (#7773). [Artur Bieniek, Antmicro Ltd.]
+* Fix $fflush and autoflush with --threads (#7782).
+* Fix out-of-bounds read value for 2-state types (#7785). [Jakub Michalski]
+* Fix `cover property` of an implication counting vacuous matches (#7789). [Yilou Wang]
+* Fix randomization of dynamic arrays of objects (#7790). [Ryszard Rozak, Antmicro Ltd.]
+* Fix randomize() with skipping derived pre/post_randomize (#7799). [Yilou Wang]
+* Fix skewed dist operator for arrays (#7802). [Jakub Wasilewski, Antmicro Ltd.]
+* Fix assertion when loop unrolling failed (#7810). [Geza Lore, Testorrent USA, Inc.]
+* Fix CASEINCOMPLETE for all uncovered enum items (#7815) (#7817). [Saksham]
+* Fix split optimization nested-class crash (#7826). [Igor Zaworski, Antmicro Ltd.]
+* Fix class/var named identically to an enclosing-scope type (#7827) (#7828). [Tom Jackson]
+* Fix performance on large package-scoped structs (#7830). [Wolfgang Mayerwieser]
+* Fix unclocked concurrent assertion misreported as unsupported  (#7831). [Yilou Wang]
+* Fix insertion of expression coverage statement (#7832). [Ryszard Rozak, Antmicro Ltd.]
+* Fix lifetime of expression coverage variable (#7834). [Ryszard Rozak, Antmicro Ltd.]
+* Fix disable iff ignored when its condition is held continuously true (#7841). [Yilou Wang]
+* Fix constant pool cache after dead scope removal (#7845). [Nick Brereton]
+* Fix covergroups without --coverage (#7848) (#7849). [Joshua Leahy]
+* Fix class scope '::' reference through an inherited type parameter (#7844). [Sergey Chusov]
+
+
+Verilator 5.048 2026-04-26
+==========================
+
+**Important:**
+
+* Displaying Verilator generated FST files will require an updated version
+  of Surfer (built from 'main', or the future numbered release 0.7.0).
+  No GTKWave update is necessary (#7255).
 * Support jemalloc as the default allocator on Linux (#7250). [Yangyu Chen]
  For better performance, `apt install libjemalloc-dev` or equivalent before running ./configure.

 **Other:**

-* Support inout inside SV interface (#3466) (#7134). [Nick Brereton]
+* Add VPI callback support to `--main` (#7145).
+* Add `--func-recursion-depth` option (#7175) (#7179).
+* Add `+verilator+solver+file` for debugging constraint solver (#7242).
+* Add `--coverage-fsm` for experimental FSM state and arc coverage (#7412). [Yogish Sekhar]
+* Add printed summary to verilator_coverage (#7438) (#7462). [Yogish Sekhar]
+* Deprecate `--structs-packed` (#7222).
+* Remove DFG extract optimization pass (#7394). [Geza Lore, Testorrent USA, Inc.]
+* Remove multi-threaded FST tracing (#7443). [Geza Lore, Testorrent USA, Inc.]
+* Improve assignment-compatibility type check (#2843) (#5666) (#7052). [Pawel Kojma, Antmicro Ltd.]
+* Improve error message when variable used as data type (#7318). [Ryszard Rozak, Antmicro Ltd.]
+* Improve E_UNSUPPORTED warning messages (#7329). [Eunseo Song]
+* Improve NFA-based multi-cycle SVA evaluation engine (#7430). [Yilou Wang]
+* Change array tracing to dump left index to right index (#7205). [Geza Lore, Testorrent USA, Inc.]
+* Change `--converge-limit` default to 10000 (#7209).
+* Support inout inside SV interface (#3466) (#7134) (#7708) (#7710). [Nick Brereton]
 * Support `##0` cycle delays (#4263) (#7298). [Yilou Wang]
+* Support multidimensional arrays of interfaces (#6230) (#7451). [em2machine]
 * Support array reduction methods with 'with' clause in constraints (#6455) (#6999). [Rahul Behl]
 * Support constraint imperfect distributions (#6811) (#7168). [Yilou Wang]
 * Support disable task by name (#6853) (#7136). [Nick Brereton]
@@ -39,14 +435,15 @@ Verilator 5.047 devel
 * Support modport export/import task prototypes and out-of-block definitions (#7277). [Yilou Wang]
 * Support very wide $display arguments (#7280). [Jakub Michalski]
 * Support named sequence declarations and instances in assertions  (#7283). [Yilou Wang]
-* Support `##` delay on implication RHS in SVA properties (#7284). [Yilou Wang]
+* Support `##`, `##[*]`, `##[+]`, `##[M:N]` cycle delays in assertions (#7284) (#7312) (#7377). [Yilou Wang]
 * Support boolean and/or in sequence expressions (#7285). [Yilou Wang]
 * Support property-local variables and sequence match items (#7286). [Yilou Wang]
-* Support 'until' property (partial #7290) (#7399). [Ryszard Rozak, Antmicro Ltd.]
+* Support 'until' and `until_with` property (#7290 partial) (#7399) (#7436). [Ryszard Rozak, Antmicro Ltd.]
+* Support implication operator with constraint_set (#7300) (#7448). [Yilou Wang]
 * Support array map() method (#7307) (#7316) (#7344). [Wei-Lun Chiu]
+* Support MacOS address sanitizer memory limit (#7308). [Marco Bartoli]
 * Support SVA goto repetition `[->N]` in concurrent assertions (#7310). [Yilou Wang]
 * Support consecutive repetition `[\*N]` in SVA properties (#7311). [Yilou Wang]
-* Support `##[*]`, `##[+]`, `##[M:N]`, `##[M:$]` cycle delays in assertions (#7312) (#7377). [Yilou Wang]
 * Support rise/fall delays (#7368). [Artur Bieniek, Antmicro Ltd.]
 * Support sequence intersect operator (#7374). [Yilou Wang]
 * Support sequence 'throughout' operator (#7378). [Yilou Wang]
@@ -55,19 +452,10 @@ Verilator 5.047 devel
 * Support nonconsecutive repetition [=N] in sequence expressions (#7397). [Yilou Wang]
 * Support per-process RNG for process::srandom() and object seeding (#7408) (#7415) (#7408). [Yilou Wang]
 * Support 2**n expressions in constraint randomization (#7422). [Yilou Wang]
-* Add VPI callback support to --main (#7145).
-* Add V3LiftExpr pass to lower impure expressions and calls (#7141) (#7164). [Geza Lore, Testorrent USA, Inc.]
-* Add --func-recursion-depth CLI option (#7175) (#7179).
-* Add `+verilator+solver+file` (#7242).
-* Add MacOS support for address sanitizer memory limit (#7308). [Marco Bartoli]
-* Deprecate `--structs-packed` (#7222).
-* Improve assignment-compatibility type check (#2843) (#5666) (#7052). [Pawel Kojma, Antmicro Ltd.]
-* Improve error message when variable used as data type (#7318). [Ryszard Rozak, Antmicro Ltd.]
-* Improve E_UNSUPPORTED warning messages (#7329). [Eunseo Song]
-* Change array tracing to dump left index to right index (#7205). [Geza Lore, Testorrent USA, Inc.]
-* Change `--converge-limit` default to 10000 (#7209).
-* Remove DFG extract optimization pass (#7394). [Geza Lore, Testorrent USA, Inc.]
+* Support IEEE-compliant force/release handling (#7391). [Artur Bieniek, Antmicro Ltd.]
+* Support sequence 'within' operator (#7461). [Yilou Wang]
 * Optimize trace code for faster compiles on repeated types (#6707) (#6832). [Todd Strader]
+* Optimize impure expressions and calls with new V3LiftExpr pass (#7141) (#7164). [Geza Lore, Testorrent USA, Inc.]
 * Optimize size of trace declaration object code (#7150). [Szymon Gizler, Antmicro Ltd.]
 * Optimize function call return value temporaries (#7152). [Geza Lore, Testorrent USA, Inc.]
 * Optimize conditional merging across some impure statements (#7159). [Geza Lore, Testorrent USA, Inc.]
@@ -79,11 +467,18 @@ Verilator 5.047 devel
 * Optimize more patterns in DfgPeephole (#7332). [Geza Lore, Testorrent USA, Inc.]
 * Optimize read references in DFG (#7354). [Geza Lore, Testorrent USA, Inc.]
 * Optimize DFG only once, after scoping (#7362). [Geza Lore, Testorrent USA, Inc.]
-* Optimize more DFG peephole patterns (#7423). [Geza Lore, Testorrent USA, Inc.]
+* Optimize more DFG peephole patterns (#7423) (#7452). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DfgBreakCycles IndependentBits analysis ordering (#7446). [Geza Lore, Testorrent USA, Inc.]
+* Optimize select patterns in DfgPeephole. [Geza Lore, Testorrent USA, Inc.]
+* Optimize temporary insertion in DfgPeephole. [Geza Lore, Testorrent USA, Inc.]
+* Optimize arithmetic right shift (>>>) in DfgBreakCycles (#7447). [Geza Lore, Testorrent USA, Inc.]
+* Optimize temporary insertion in DFG (#7459). [Geza Lore, Testorrent USA, Inc.]
+* Optimize mix of Concat/Extend assignments (#7479). [Geza Lore, Testorrent USA, Inc.]
 * Fix recursive default assignment for sub-arrays (#4589) (#7202). [Julian Carrier]
+* Fix tracing virtual interface member written from classes (#5044) (#7465). [Nikolay Puzanov]
 * Fix virtual interface member trigger convergence (#5116) (#7323). [Yilou Wang]
 * Fix shift width mismatch in constraint solver SMT emission (#5420) (#7265). [Yilou Wang]
-* Fix returning wrong type from static function in parameterized class (#5479) (#7387) (#7411) (#7418). [em2machine]
+* Fix returning wrong type from static function in parameterized class (#5479) (#7387) (#7411) (#7418) (#7445) (#7450). [em2machine]
 * Fix randomize size+element queue constraints (#5582) (#7225). [Rahul Behl, Testorrent USA, Inc.]
 * Fix null assignment to virtual interfaces (#5974) (#5990). [Maxim Fonarev]
 * Fix typedef scope resolution for parameterized class aliases (#5977) (#7319). [Nick Brereton]
@@ -150,7 +545,19 @@ Verilator 5.047 devel
 * Fix delete inside foreach skipping elements (#7407) (#7410)
 * Fix std::randomize in parameterized-derived class (#7409) (#7416). [Yilou Wang]
 * Fix virtual interface implied comparison with null (#7421). [Alex Solomatnikov]
-
+* Fix uvm_hdl_release_and_read to release value and check success (#7425). [Christian Hecken, Heidelberg University]
+* Fix inline constraint on array-indexed randomize target (#7431) (#7434). [Yilou Wang]
+* Fix modification of members of object with const handle (#7433). [Kamil Danecki, Antmicro Ltd.]
+* Fix `dist` under implication in constraints (#7440) (#7442). [Alex Solomatnikov] [Yilou Wang]
+* Fix std::randomize `inside` corrupting class-member queue operand (#7449) (#7456). [Yilou Wang]
+* Fix module parameters not re-evaluated upon instantiation (#7463) (#7477). [em2machine]
+* Fix function-in-constraint internal error on bare port return (#7473) (#7480). [Yilou Wang]
+* Fix access to static variable inside function (#7474) (#7475). [Alex Zhou]
+* Fix multiple inclusion of verilated_std.sv (#7478). [Larry Doolittle]
+* Fix std::randomize inside {typedef array} internal error (#7481). [Yilou Wang]
+* Fix module parameters not re-evaluated upon instantiation (#7463) (#7477). [em2machine]
+* Fix infinite recursion with VERILATOR_BIN (#7496) (#7497).
+* Add error on mixed declaration initialization with continuous assignment (#7352). [Zhi QU]

 Verilator 5.046 2026-02-28
 ==========================
@@ -313,7 +720,7 @@ Verilator 5.044 2026-01-01
 * Support clocking output delay `1step` (#6681). [Ondrej Ille]
 * Support parsing of dotted `bins_expression` (#6683). [Pawel Kojma, Antmicro Ltd.]
 * Support constant expression cycle delays in sequences (#6691). [Ryszard Rozak, Antmicro Ltd.]
-* Support general global constraints (#6709) (#6711). [Yilou Wang]
+* Support general global constraints (#6709) (#6711) (#7833) (#7838). [Yilou Wang]
 * Support complex std::randomize patterns (#6736) (#6737). [Yilou Wang]
 * Support `rand_mode` in global constraint gathering (#6740) (#6752). [Yilou Wang]
 * Support reduction or in constraints (#6840). [Pawel Kojma, Antmicro Ltd.]
@@ -657,7 +1064,7 @@ Verilator 5.038 2025-07-08
 * Support non-overlapping blocking/non-blocking assignments (#6137). [Geza Lore]
 * Support parameter forward types.
 * Support constant functions with left-hand-side concatenates.
-* Add PROCINITASSIGN on initial assignments to process variables (#2481). [Niraj Menon]
+* Add PROCINITASSIGN on initial assignments to process variables (#2481) (#7640). [Niraj Menon]
 * Add BADVLTPRAGMA on unknown Verilator pragmas (#5945). [Shou-Li Hsu]
 * Add ternary operator into branch coverage (#5880). [Ryszard Rozak, Antmicro Ltd.]
 * Add aggregate type error checks (#5570) (#5950). [Shou-Li Hsu]
@@ -2313,7 +2720,6 @@ Verilator 4.108 2021-01-10
 * Fix to ignore coverage on real ports (#2741) (#2745). [Paul Wright]


-
 Verilator 4.106 2020-12-02
 ==========================

@@ -2720,7 +3126,6 @@ Verilator 4.018 2019-08-29
 * Fix internal error on gate optimization of assign. (#1475) [Oyvind Harboe]


-
 Verilator 4.016 2019-06-16
 ==========================

@@ -5171,7 +5576,6 @@ Verilator 3.270 2004-10-15
 * Fix numeric fault when dividing by zero.


-
 Verilator 3.260 2004-10-07
 ==========================

@@ -5510,7 +5914,7 @@ Verilator 3.104 2003-04-30
 **Major:**

 * Indicate direction of ports with VL_IN and VL_OUT.
-* Allow $c32, etc, to specify width of the $c statement for VCS.
+* Allow $c32, etc, to specify width of the $c statement.
 * Numerous performance improvements, worth about 25%

 **Minor:**
@@ -1,9 +0,0 @@
-Copyright (c) <year> <owner>
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -94,6 +94,7 @@ CFG_WITH_DEFENV = @CFG_WITH_DEFENV@
 CFG_WITH_DEV_GCOV = @CFG_WITH_DEV_GCOV@
 CFG_WITH_LONGTESTS = @CFG_WITH_LONGTESTS@
 CFG_WITH_SOLVER = @CFG_WITH_SOLVER@
+GCOV = @GCOV@
 PACKAGE_VERSION = @PACKAGE_VERSION@

 #### End of system configuration section. ####
@@ -260,7 +261,7 @@ VL_INST_INC_SRCDIR_FILES = \
  include/*.[chv]* \
  include/*.vlt \
  include/*.sv \
-  include/gtkwave/*.[chv]* \
+  include/fstcpp/*.[chv]* \
  include/vltstd/*.[chv]* \

 VL_INST_DATA_SRCDIR_FILES = \
@@ -292,15 +293,14 @@ installbin: | mkbindirs
 	done

 installredirect: installbin | mkbindirs
-	cp ${srcdir}/bin/redirect ${srcdir}/bin/redirect.tmp
-	perl -p -i -e 'use File::Spec;' \
-	           -e' $$path = File::Spec->abs2rel("$(realpath $(DESTDIR)$(bindir))", "$(realpath $(DESTDIR)$(pkgdatadir)/bin)");' \
-	           -e 's/RELPATH.*/"$$path";/g' -- "${srcdir}/bin/redirect.tmp"
-	cd $(srcdir)/bin; \
+	REDIR_SCRATCH=$$(mktemp redir_XXXXXX); \
+	perl -p -e 'use File::Spec;' \
+	        -e' $$path = File::Spec->abs2rel("$(realpath $(DESTDIR)$(bindir))", "$(realpath $(DESTDIR)$(pkgdatadir)/bin)");' \
+	        -e 's/RELPATH.*/"$$path";/g' -- "${srcdir}/bin/redirect" > $$REDIR_SCRATCH; \
 	for p in $(VL_INST_PUBLIC_SCRIPT_FILES) $(VL_INST_PUBLIC_BIN_FILES) ; do \
-		$(INSTALL_PROGRAM) redirect.tmp $(DESTDIR)$(pkgdatadir)/bin/$$p; \
-	done
-	rm ${srcdir}/bin/redirect.tmp
+		$(INSTALL_PROGRAM) $$REDIR_SCRATCH $(DESTDIR)$(pkgdatadir)/bin/$$p; \
+	done; \
+	rm $$REDIR_SCRATCH

 # Man files can either be part of the original kit, or built in current directory
 # So important we use $^ so VPATH is searched
@@ -311,7 +311,7 @@ installman: $(VL_INST_MAN_FILES)
 	done

 installdata:
-	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/include/gtkwave
+	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/include/fstcpp
 	$(MKINSTALLDIRS) $(DESTDIR)$(pkgdatadir)/include/vltstd
 	for p in $(VL_INST_INC_BLDDIR_FILES) ; do \
 		$(INSTALL_DATA) $$p $(DESTDIR)$(pkgdatadir)/$$p; \
@@ -356,7 +356,7 @@ uninstall:
 	-rm $(DESTDIR)$(pkgdatadir)/verilator-config.cmake
 	-rm $(DESTDIR)$(pkgdatadir)/verilator-config-version.cmake
 	-rmdir $(DESTDIR)$(pkgdatadir)/bin
-	-rmdir $(DESTDIR)$(pkgdatadir)/include/gtkwave
+	-rmdir $(DESTDIR)$(pkgdatadir)/include/fstcpp
 	-rmdir $(DESTDIR)$(pkgdatadir)/include/vltstd
 	-rmdir $(DESTDIR)$(pkgdatadir)/include
 	-rmdir $(DESTDIR)$(pkgdatadir)/examples/make_hello_binary
@@ -417,7 +417,7 @@ CPPCHECK_FLAGS += --cppcheck-build-dir=$(CPPCHECK_CACHE)
 CPPCHECK_FLAGS += -DVL_DEBUG=1 -DVL_CPPCHECK=1 -DINFILTER_PIPE=1 -D__GNUC__=1
 CPPCHECK_FLAGS += -j$(CPPCHECK_JOBS)
 CPPCHECK_INC = -I$(srcdir)/include
-CPPCHECK_INC += -I$(srcdir)/include/gtkwave
+CPPCHECK_INC += -I$(srcdir)/include/fstcpp
 CPPCHECK_INC += -I$(srcdir)/include/vltstd
 CPPCHECK_INC += -I$(srcdir)/src/obj_dbg
 CPPCHECK_INC += -I$(srcdir)/src
@@ -444,7 +444,7 @@ cppcheck:
 CLANGTIDY = clang-tidy
 CLANGTIDY_FLAGS = -config='' \
  -header-filter='.*' \
-  -checks='*,-abseil-*,-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables,-cppcoreguidelines-avoid-goto,-modernize-avoid-c-arrays,-readability-magic-numbers,-readability-simplify-boolean-expr,-cppcoreguidelines-macro-usage' \
+  -checks='*,-abseil-*,-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-avoid-do-while,-cppcoreguidelines-init-variables,-cppcoreguidelines-avoid-goto,-modernize-avoid-c-arrays,-readability-magic-numbers,-readability-simplify-boolean-expr,-cppcoreguidelines-macro-usage' \

 # Good checks: -checks='-*,bugprone-assignment-in-if-condition,google-build-using-namespace,google-readability-casting,modernize-use-default-member-init,modernize-use-emplace,modernize-use-equals-default,modernize-use-equals-delete,modernize-use-nullptr,performance-faster-string-find,readability-isolate-declaration,readability-redundant-control-flow,readability-redundant-member-init,readability-redundant-string-cstr,readability-uppercase-literal-suffix

@@ -467,9 +467,11 @@ analyzer-include:

 # Bash/sh files
 BASH_FILES = \
+  ci/ci-coverage-report.bash \
  ci/ci-install.bash \
  ci/ci-pages-notify.bash \
  ci/ci-pages.bash \
+  ci/ci-rtlmeter-report.bash \
  ci/ci-script.bash \
  ci/docker/run/hooks/post_push \
  ci/docker/run/verilator-docker \
@@ -496,6 +498,11 @@ MAKE_FILES = \
  src/Makefile*.in \
  test_regress/Makefile* \

+# Markdown
+MD_FILES = \
+  *.md \
+  */*.md \
+
 # Perl programs
 PERL_PROGRAMS = \
  bin/redirect \
@@ -532,15 +539,24 @@ PY_PROGRAMS = \
  src/vlcovgen \
  test_regress/*.py \
  test_regress/t/*.pf \
+  test_regress/t/randomize_solver_tamper.py \

 # Python files, subject to format but not lint
 PY_FILES = \
  $(PY_PROGRAMS) \
+  ci/*.py \
  test_regress/t/*.py \

 # Python files, test_regress tests
 PY_TEST_FILES = test_regress/t/*.py

+# reStructuredText Sphinx files
+RST_FILES = \
+  *.rst \
+  */*.rst \
+  ci/docker/*/*.rst \
+  docs/guide/*.rst \
+
 # YAML files
 YAML_FILES = \
  .*.yaml \
@@ -553,7 +569,7 @@ YAML_FILES = \
 # Format

 format:
-	$(MAKE) -j 5 format-c format-cmake format-exec format-py format-yaml
+	$(MAKE) -j 5 format-c format-cmake format-exec format-md format-py format-rst format-yaml

 BEAUTYSH = beautysh
 BEAUTYSH_FLAGS = --indent-size 2
@@ -590,6 +606,13 @@ format-make mbake:
 	$(MBAKE) --version
 	$(MBAKE) $(MBAKE_FLAGS) $(MAKE_FILES)

+MDFORMAT = mdformat
+MDFORMAT_FLAGS =
+
+format-md:
+	$(MDFORMAT) --version
+	$(MDFORMAT) $(MDFORMAT_FLAGS) $(MD_FILES)
+
 YAPF = yapf
 YAPF_FLAGS = -i --parallel

@@ -597,6 +620,13 @@ format-py yapf:
 	$(YAPF) --version
 	$(YAPF) $(YAPF_FLAGS) $(PY_FILES)

+DOCSTRFMT = docstrfmt
+DOCSTRFMT_FLAGS = --line-length 75 --indent-width 3 --keep-blanks --ordered-marker "\#" --preserve-adornments --no-center-section-titles
+
+format-rst:
+	$(DOCSTRFMT) --version
+	$(DOCSTRFMT) $(DOCSTRFMT_FLAGS) $(RST_FILES)
+
 YAMLFIX = YAMLFIX_WHITELINES=1 YAMLFIX_LINE_LENGTH=200 YAMLFIX_preserve_quotes=true yamlfix
 YAMLFIX_FLAGS =

@@ -669,22 +699,30 @@ COVERAGE_DIR := obj_coverage
 ifeq ($(CFG_WITH_DEV_GCOV),yes)

 # Figure out base and head refs for coverage report
-COVERAGE_REF_BASE := $(if $(COVERAGE_BASE),$(shell git rev-parse --short $(COVERAGE_BASE)))
+COVERAGE_REF_BASE := $(if $(COVERAGE_BASE),$(shell git rev-parse --short $(COVERAGE_BASE) 2>/dev/null))
+ifneq ($(COVERAGE_BASE),)
+ ifeq ($(COVERAGE_REF_BASE),)
+  $(error COVERAGE_BASE='$(COVERAGE_BASE)' is not a valid git revision)
+ endif
+endif
 COVERAGE_REF_HEAD := $(shell git rev-parse --short HEAD)
 override undefine COVERAGE_BASE # Use the above variabels instead

 # 'fastcov' setup
 FASTCOV := nodist/fastcov.py
 FASTCOV_OPT := -j $(shell nproc)
+FASTCOV_OPT += --gcov $(GCOV)
 FASTCOV_OPT += --lcov
 FASTCOV_OPT += --process-gcno
 FASTCOV_OPT += --branch-coverage
 FASTCOV_OPT += --dump-statistic
 # Files matching the following glob patterns will be excluded from coverage
 FASTCOV_OPT += --exclude-glob
-FASTCOV_OPT += '/usr/*'
+FASTCOV_OPT += '/usr/include/*'
+FASTCOV_OPT += '/usr/lib*/*'
+FASTCOV_OPT += '/usr/share/*'
 FASTCOV_OPT += '*examples/*'
-FASTCOV_OPT += '*include/gtkwave/*'
+FASTCOV_OPT += '*include/fstcpp/*'
 FASTCOV_OPT += '*src/obj_dbg/*'
 FASTCOV_OPT += '*src/obj_opt/*.yy.cpp'
 FASTCOV_OPT += '*src/obj_opt/V3Ast*'
@@ -723,6 +761,7 @@ GENHTML_OPT += --missed
 GENHTML_OPT += --rc branch_coverage=1
 GENHTML_OPT += --rc genhtml_hi_limit=100
 GENHTML_OPT += --ignore-errors negative
+GENHTML_OPT += --ignore-errors inconsistent
 ifeq ($(COVERAGE_REF_BASE),)
 GENHTML_OPT += --header-title "Code coverage for Verilator $(shell git describe --dirty)"
 else
@@ -754,7 +793,7 @@ $(COVERAGE_DIR)/verilator-patch.info: $(COVERAGE_DIR)/verilator.info
 	@echo "####################################################################"
 	rm -f $(COVERAGE_DIR)/empty-patch
 	git diff $(COVERAGE_REF_BASE) -- include src > $(COVERAGE_DIR)/filter.patch
-	[ -s $(COVERAGE_DIR)/filter.patch ]] || touch $(COVERAGE_DIR)/empty-patch
+	[ -s $(COVERAGE_DIR)/filter.patch ] || touch $(COVERAGE_DIR)/empty-patch
 	$(FASTCOV) -C $^ --lcov -o $@ --diff-filter $(COVERAGE_DIR)/filter.patch

 # Build coverage report
@@ -763,7 +802,7 @@ $(COVERAGE_DIR)/report/index.html: $(COVERAGE_DIR)/verilator$(if $(COVERAGE_REF_
 	@echo "# genhtml: Generating coverage report"
 	@echo "####################################################################"
 	@rm -rf $(COVERAGE_DIR)/report
-	[ -f $(COVERAGE_DIR)/empty-patch ]] || /usr/bin/time -f "That took %E" \
+	[ -f $(COVERAGE_DIR)/empty-patch ] || /usr/bin/time -f "That took %E" \
 	$(GENHTML) $(GENHTML_OPT) --output-directory $(COVERAGE_DIR)/report $^ || true
 	@# Uncommitted changes not tracked, force rebuild on next run if patch coverage
 	@$(if $(COVERAGE_REF_BASE),mv $(COVERAGE_DIR)/verilator-patch.info $(COVERAGE_DIR)/verilator-patch-last.info)
@@ -1,58 +1,65 @@
-.. Github doesn't render images unless absolute URL
-.. Do not know of a conditional tag, "only: github" nor "github display" works
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   Github doesn't render images unless absolute URL
+   Do not know of a conditional tag, "only: github" nor "github display" works
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

-|badge1| |badge2| |badge3| |badge4| |badge5| |badge7| |badge8|
+|badge1| |badge2| |badge3| |badge4| |badge5|
+
+|badge7| |badge8|

 .. |badge1| image:: https://img.shields.io/badge/Website-Verilator.org-181717.svg
   :target: https://verilator.org
+
 .. |badge2| image:: https://img.shields.io/badge/License-LGPL%20v3-blue.svg
   :target: https://www.gnu.org/licenses/lgpl-3.0
+
 .. |badge3| image:: https://img.shields.io/badge/License-Artistic%202.0-0298c3.svg
   :target: https://opensource.org/licenses/Artistic-2.0
+
 .. |badge4| image:: https://repology.org/badge/tiny-repos/verilator.svg?header=distro%20packages
   :target: https://repology.org/project/verilator/versions
+
 .. |badge5| image:: https://img.shields.io/docker/pulls/verilator/verilator
   :target: https://hub.docker.com/r/verilator/verilator
-.. |badge7| image:: https://github.com/verilator/verilator/workflows/build/badge.svg
-   :target: https://github.com/verilator/verilator/actions?query=workflow%3Abuild
+
+.. |badge7| image:: https://img.shields.io/github/actions/workflow/status/verilator/verilator/build-test.yml?branch=master&label=regressions
+   :target: https://github.com/verilator/verilator/actions/workflows/build-test.yml
+
 .. |badge8| image:: https://img.shields.io/github/actions/workflow/status/verilator/verilator/rtlmeter.yml?branch=master&event=schedule&label=benchmarks
   :target: https://verilator.github.io/verilator-rtlmeter-results

-
 Welcome to Verilator
 ====================

 .. list-table::

-   * - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
-        * Accepts Verilog or SystemVerilog
-        * Performs lint code-quality checks
-        * Compiles into multithreaded C++, or SystemC
-        * Creates JSON to front-end your own tools
+   - - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
+          - Accepts Verilog or SystemVerilog
+          - Performs lint code-quality checks
+          - Compiles into multithreaded C++, or SystemC
+          - Creates JSON to front-end your own tools
     - |Logo|
-   * - |verilator multithreaded performance|
+   - - |verilator multithreaded performance|
     - **Fast**
-        * Outperforms many closed-source commercial simulators
-        * Single- and multithreaded output models
-   * - **Widely Used**
-        * Wide industry and academic deployment
-        * Out-of-the-box support from Arm and RISC-V vendor IP
-        * Over 700 contributors
+          - Outperforms many closed-source commercial simulators
+          - Single- and multithreaded output models
+   - - **Widely Used**
+          - Wide industry and academic deployment
+          - Out-of-the-box support from Arm and RISC-V vendor IP
+          - Over 700 contributors
     - |verilator usage|
-   * - |verilator community|
+   - - |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
+          - 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
 ===================

@@ -77,7 +84,6 @@ SDF annotation, or mixed-signal simulation. However, if you are looking for
 a path to migrate SystemVerilog to C++/SystemC, or want high-speed
 simulation, Verilator is the tool for you.

-
 Performance
 ===========

@@ -96,7 +102,6 @@ Mentor ModelSim/Questa, 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 simulation cycles/dollar.

-
 Installation & Documentation
 ============================

@@ -115,7 +120,6 @@ For more information:

 - `Verilator issues <https://verilator.org/issues>`_

-
 Support
 =======

@@ -132,7 +136,6 @@ Verilator also supports and encourages commercial support models and
 organizations; please see `Verilator Commercial Support
 <https://verilator.org/verilator_commercial_support>`_.

-
 Related Projects
 ================

@@ -149,7 +152,6 @@ Related Projects
 - `Surfer <https://surfer-project.org/>`_ - Web or offline waveform viewer
  for Verilator traces.

-
 Open License
 ============

@@ -161,10 +163,17 @@ 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: https://steveicarus.github.io/iverilog
+
 .. _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
@@ -4,9 +4,9 @@ version = 1

 [[annotations]]
 path = [
+    "**/.clang-format",
    "**/.gitattributes",
    "**/.gitignore",
-    ".clang-format",
    ".clang-tidy",
    ".codacy.yml",
    ".devcontainer/devcontainer.json",
@@ -15,6 +15,7 @@ path = [
    ".style.yapf",
    "CITATION.cff",
    "CPPLINT.cfg",
+    "ci/docker/buildenv/wavetools.conf",
    "docs/CONTRIBUTORS",
    "docs/spelling.txt",
    "docs/verilated.dox",
@@ -27,6 +27,21 @@ use vars qw($Debug @Opt_Verilator_Sw);
 autoflush STDOUT 1;
 autoflush STDERR 1;

+# Guard against unbounded recursive re-entry. Hierarchical / --build flows
+# legitimately re-enter the wrapper a few levels deep (wrapper -> verilator_bin
+# -> make -> wrapper -> ...); a misconfigured VERILATOR_BIN, VERILATOR_GDB or
+# VERILATOR_VALGRIND that points back at this wrapper, however, recurses
+# without bound and exhausts the OS PID table. Use VERILATOR_RUNNING as a
+# depth counter and cap it well above any real nesting.
+my $verilator_running_max = 16;
+my $verilator_running_depth = ($ENV{VERILATOR_RUNNING} || 0) + 1;
+if ($verilator_running_depth > $verilator_running_max) {
+    die "%Error: verilator: re-entered $verilator_running_depth levels deep"
+        . " via \$VERILATOR_RUNNING; check that VERILATOR_BIN, VERILATOR_GDB"
+        . " and VERILATOR_VALGRIND do not resolve back to this wrapper script.\n";
+}
+$ENV{VERILATOR_RUNNING} = $verilator_running_depth;
+
 $Debug = 0;
 my $opt_aslr;
 my $opt_gdb;
@@ -86,9 +101,15 @@ if (defined $ENV{VERILATOR_ROOT}) {
    $ENV{VERILATOR_ROOT} = $verilator_root;
 }

-if ($opt_gdbbt && !gdb_works()) {
-    warn "-Info: --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
-    $opt_gdbbt = 0;
+my $lldb_selected = 0;
+if (($opt_gdb || $opt_gdbbt) && !gdb_works()) {
+    if (lldb_works()) {
+        $lldb_selected = 1;
+    } else {
+        warn "-Info: --gdb or --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
+        $opt_gdbbt = 0;
+        $opt_gdb = 0;
+    }
 }

 # Determine runtime flags and run
@@ -98,22 +119,35 @@ if ($opt_gdbbt && !gdb_works()) {
 # then see exactly the contents of @Opt_Verilator_Sw.
 my @quoted_sw = map { sh_escape($_) } @Opt_Verilator_Sw;
 if ($opt_gdb) {
-    # Generic GDB interactive
-    run (ulimit_stack_unlimited()
-         . aslr(0)
-         . ($ENV{VERILATOR_GDB} || "gdb")
-         . " " . verilator_bin()
-         # Note, uncomment to set breakpoints before running:
-         #  ." -ex 'break main'"
-
-         # Note, we must use double-quotes ("run <switches>")
-         # and not single ('run <switches>') below. Bash swallows
-         # escapes as you would expect in a double-quoted string.
-         # That's not true for a single-quoted string, where \'
-         # actually terminates the string -- not what we want!
-         . " -ex \"run " . join(' ', @quoted_sw) . "\""
-         . " -ex 'set width 0'"
-         . " -ex 'bt'");
+    # Note, we must use double-quotes ("run <switches>")
+    # and not single ('run <switches>') below. Bash swallows
+    # escapes as you would expect in a double-quoted string.
+    # That's not true for a single-quoted string, where \'
+    # actually terminates the string -- not what we want!
+    if ($lldb_selected) {
+        # Generic lldb interactive
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "lldb")
+             . " " . verilator_bin()
+             # Note, uncomment to set breakpoints before running:
+             #  . " -o 'b main'"
+             . " -o 'b exit'"  # Need break to keep process active for bt
+             . " -o \"run " . join(' ', @quoted_sw) . "\""
+             . " -o 'settings set term-width 1024'"
+             . " -o 'bt'");
+    } else {
+        # Generic GDB interactive
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "gdb")
+             . " " . verilator_bin()
+             # Note, uncomment to set breakpoints before running:
+             #  . " -ex 'break main'"
+             . " -ex \"run " . join(' ', @quoted_sw) . "\""
+             . " -ex 'set width 0'"
+             . " -ex 'bt'");
+    }
 } elsif ($opt_rr) {
    # Record with rr
    run (ulimit_stack_unlimited()
@@ -121,15 +155,27 @@ if ($opt_gdb) {
         . "rr record " . verilator_bin()
         . " " . join(' ', @quoted_sw));
 } elsif ($opt_gdbbt && $Debug) {
-    # Run under GDB to get gdbbt
-    run (ulimit_stack_unlimited()
-         . aslr(0)
-         . "gdb"
-         . " " . verilator_bin()
-         . " --batch --quiet --return-child-result"
-         . " -ex \"run " . join(' ', @quoted_sw)."\""
-         . " -ex 'set width 0'"
-         . " -ex 'bt' -ex 'quit'");
+    # Run under debugger to get gdbbt
+    if ($lldb_selected) {
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "lldb")
+             . " " . verilator_bin()
+             . " -o 'b exit'"  # Need break to keep process active for bt
+             . " --batch --source-quietly"
+             . " -o \"run " . join(' ', @quoted_sw)."\""
+             . " -o 'settings set term-width 1024'"
+             . " -o 'bt' -o 'quit'");
+    } else {
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "gdb")
+             . " " . verilator_bin()
+             . " --batch --quiet --return-child-result"
+             . " -ex \"run " . join(' ', @quoted_sw)."\""
+             . " -ex 'set width 0'"
+             . " -ex 'bt' -ex 'quit'");
+    }
 } elsif ($opt_valgrind) {
    # Run under valgrind
    my $valgrind_bin = ($ENV{VERILATOR_VALGRIND} || "valgrind --error-exitcode=1 --max-stackframe=2815880"
@@ -185,9 +231,9 @@ sub verilator_bin {

 sub gdb_works {
    $! = undef;  # Cleanup -x
-    system("gdb /bin/echo"
+    system("gdb /bin/sh"
           . " --batch-silent --quiet --return-child-result"
-           . " -ex 'run -n'"  # `echo -n`
+           . " -ex 'run -c exit'"  # `/bin/sh -c exit
           . " -ex 'set width 0'"
           . " -ex 'bt'"
           . " -ex 'quit'");
@@ -195,6 +241,18 @@ sub gdb_works {
    return $status == 0;
 }

+sub lldb_works {
+    $! = undef;  # Cleanup -x
+    # macOS system integrity stops attach to system binaries like /bin/sh
+    system("lldb --version"
+           . " --batch --source-quietly"
+           . " -o 'settings set term-width 1024'"
+           . " -o 'bt'"
+           . " -o 'quit'");
+    my $status = $?;
+    return $status == 0;
+}
+
 sub aslr {
    my $want_on = shift;
    $want_on = $opt_aslr if defined $opt_aslr;
@@ -342,6 +400,7 @@ detailed descriptions of these arguments.
    --no-aslr                   Disable address space layout randomization
    --no-assert                 Disable all assertions
    --no-assert-case            Disable unique/unique0/priority-case assertions
+    --assert-unroll-limit <iter> Max SVA assertion repetition before erroring
    --autoflush                 Flush streams after all $displays
    --bbox-sys                  Blackbox unknown $system calls
    --bbox-unsup                Blackbox unsupported language features
@@ -358,8 +417,10 @@ detailed descriptions of these arguments.
    --coverage                  Enable all coverage
    --coverage-expr             Enable expression coverage
    --coverage-expr-max <value>     Maximum permutations allowed for an expression
+    --coverage-fsm              Enable FSM state/arc coverage
    --coverage-line             Enable line coverage
    --coverage-max-width <width>   Maximum array depth for coverage
+    --coverage-per-instance     Enable per-instance coverage counters
    --coverage-toggle           Enable toggle coverage
    --coverage-underscore       Enable coverage of _signals
    --coverage-user             Enable SVL user coverage
@@ -377,8 +438,10 @@ detailed descriptions of these arguments.
    --diagnostics-sarif-output <filename>  Set SARIF diagnostics output file
    --dpi-hdr-only              Only produce the DPI header file
    --dump-<srcfile>            Enable dumping everything in source file
+    --dump-ast-patterns         Enable dumping Ast pattern statistics
    --dump-defines              Show preprocessor defines with -E
    --dump-dfg                  Enable dumping DfgGraphs to .dot files
+    --dump-dfg-patterns         Enable dumping Dfg pattern statistics
    --dump-graph                Enable dumping V3Graphs to .dot files
    --dump-inputs               Enable dumping preprocessed input files
    --dump-tree                 Enable dumping Ast .tree files
@@ -399,6 +462,8 @@ detailed descriptions of these arguments.
     -f <file>                  Parse arguments from a file
     -FI <file>                 Force include of a file
    --flatten                   Force inlining of all modules, tasks and functions
+    --fourstate                 Enable fourstate logic
+    --no-fourstate              Disable fourstate logic
    --func-recursion-depth <value>  Maximum recursive constant function depth
    --future0 <option>          Ignore an option for compatibility
    --future1 <option>          Ignore an option with argument for compatibility
@@ -526,7 +591,6 @@ detailed descriptions of these arguments.
    --trace-params              Enable tracing of parameters
    --trace-saif                Enable SAIF file creation
    --trace-structs             Enable tracing structure names
-    --trace-threads <threads>   Enable FST waveform creation on separate threads
    --no-trace-top              Do not emit traces for signals in the top module generated by verilator
    --trace-underscore          Enable tracing of _signals
    --trace-vcd                 Enable VCD waveform creation
@@ -572,11 +636,13 @@ description of these arguments.

 =for VL_SPHINX_EXTRACT "_build/gen/args_verilated.rst"

+     +verilator+assert+lock                Lock assertion status changes at startup
     +verilator+coverage+file+<filename>   Set coverage output filename
     +verilator+debug                      Enable debugging
     +verilator+debugi+<value>             Enable debugging at a level
     +verilator+error+limit+<value>        Set error limit
     +verilator+help                       Show help
+     +verilator+log+file+<filename>        Log stdout and stderr output to filename
     +verilator+noassert                   Disable assert checking
     +verilator+prof+exec+file+<filename>  Set execution profile filename
     +verilator+prof+exec+start+<value>    Set execution profile starting point
@@ -588,6 +654,7 @@ description of these arguments.
     +verilator+solver+file+<filename>     Set random solver log filename
     +verilator+V                          Show verbose version and config
     +verilator+version                    Show version and exit
+     +verilator+vpi+<library>[:<bootstrap>]  Load VPI shared library
     +verilator+wno+unsatconstr+<value>    Disable constraint warnings


@@ -157,6 +157,10 @@ verilator_coverage - Verilator coverage analyzer

    verilator_coverage --annotate <obj>

+    verilator_coverage --report summary,hier <datafiles>...
+
+    verilator_coverage --report hier <datafiles>...
+
    verilator_coverage  -write merged.dat <datafiles>...

    verilator_coverage  -write-info merged.info <datafiles>...
@@ -175,7 +179,10 @@ L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
    --annotate-points             Annotates info from each coverage point.
    --filter-type <regex>         Keep only records of given coverage type.
    --help                        Displays this message and version and exits.
+    --include-reset-arcs          Include reset arcs in FSM arc summaries.
+    --levels <depth>              Limit displayed hierarchy report depth.
    --rank                        Compute relative importance of tests.
+    --report <kind>[,<kind>...]   Generate reports: summary, hier, or hierarchy.
    --unlink                      With --write, unlink all inputs
    --version                     Displays program version and exits.
    --write <filename>            Write aggregate coverage results.
@@ -51,12 +51,17 @@ def profcfunc(filename: str) -> None:
    # Find modules
    verilated_mods = {}
    for func in funcs:
-        match = re.search(r'(.*)::eval(_step)?\(', func)
+        # Match only the model entry points: 'eval', 'eval_step', 'eval_end_step',
+        # and the 'evalXxx' region entry points, but not e.g. a user's '::evaluate'
+        match = re.match(r'([A-Za-z_][A-Za-z_0-9]*)::eval(_step|_end_step|[A-Z][A-Za-z_0-9]*)?\(',
+                         func)
        if match:
            prefix = match.group(1)
+            if prefix.startswith('Verilated'):  # Run-time library, not a model
+                continue
            if Args.debug:
                print("-got _eval %s   prefix=%s" % (func, prefix))
-            verilated_mods[prefix] = re.compile(r'^' + prefix)
+            verilated_mods[prefix] = re.compile(r'^' + re.escape(prefix))
    # pprint(verilated_mods)

    # Sort by Verilog name
@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI build job script
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+################################################################################
+# Executed in the 'build' stage.
+################################################################################
+
+# Destructive to the checkout (reconfigures and rebuilds); never run locally
+if [ "$GITHUB_ACTIONS" != "true" ]; then
+  echo "ERROR: $(basename "$0") must only be run in GitHub Actions CI" >&2
+  exit 1
+fi
+
+set -e
+set -x
+
+source "$(dirname "$0")/ci-common.bash"
+
+################################################################################
+# Parse arguments
+
+OPT_ASAN=0
+OPT_CCWARN=0
+OPT_GCOV=0
+OPT_LIGHT_DEBUG=0
+OPT_COMPILER=
+OPT_PREFIX=
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --asan) OPT_ASAN=1 ;;
+    --ccwarn) OPT_CCWARN=1 ;;
+    --compiler)
+      [ $# -ge 2 ] || fatal "--compiler requires an argument"
+      OPT_COMPILER="$2"
+      shift
+      ;;
+    --gcov) OPT_GCOV=1 ;;
+    --light-debug) OPT_LIGHT_DEBUG=1 ;;
+    --prefix)
+      [ $# -ge 2 ] || fatal "--prefix requires an argument"
+      OPT_PREFIX="$2"
+      shift
+      ;;
+    *) fatal "Unknown option: '$1'" ;;
+  esac
+  shift
+done
+
+[ -n "$OPT_COMPILER" ] || fatal "--compiler is required"
+[ -n "$OPT_PREFIX" ] || fatal "--prefix is required"
+
+# Map the compiler name to the executable name configure CXX expects
+case "$OPT_COMPILER" in
+  clang) CXX=clang++ ;;
+  gcc) CXX=g++ ;;
+  *) fatal "Unknown compiler: '$OPT_COMPILER'" ;;
+esac
+
+################################################################################
+# Configure
+
+CONFIGURE_ARGS="--prefix=$OPT_PREFIX --enable-longtests"
+if [ "$OPT_CCWARN" = 1 ]; then
+  CONFIGURE_ARGS="$CONFIGURE_ARGS --enable-ccwarn"
+fi
+if [ "$OPT_ASAN" = 1 ]; then
+  CONFIGURE_ARGS="$CONFIGURE_ARGS --enable-dev-asan"
+  CXX="$CXX -DVL_LEAK_CHECKS"
+  # Replaces VNUser's union with a std::variant to validate type usage.
+  # Only takes effect when the build is C++17 or newer.
+  CXX="$CXX -DVL_USER_TYPE_CHECKS"
+fi
+if [ "$OPT_GCOV" = 1 ]; then
+  CONFIGURE_ARGS="$CONFIGURE_ARGS --enable-dev-gcov"
+fi
+if [ "$OPT_LIGHT_DEBUG" = 1 ]; then
+  CONFIGURE_ARGS="$CONFIGURE_ARGS --enable-light-debug"
+fi
+autoconf
+./configure $CONFIGURE_ARGS CXX="$CXX"
+
+################################################################################
+# Build
+
+ccache -z
+BUILD_START=$SECONDS
+"$MAKE" -j "$NPROC" -k
+ccache -svv
+ccache --evict-older-than "$((SECONDS - BUILD_START + 60))s"
+ccache -svv
@@ -0,0 +1,35 @@
+# DESCRIPTION: Verilator: CI common definitions, sourced by the stage scripts
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+################################################################################
+# Common definitions sourced by the CI stage scripts; not executed directly.
+################################################################################
+
+fatal() {
+  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
+}
+
+case "$(uname -s)" in
+  Linux)
+    HOST_OS=linux
+    MAKE=make
+    NPROC=$(nproc)
+    # Distro id/version; subshell keeps os-release out of our namespace
+    if [ -r /etc/os-release ]; then
+      DISTRO_ID=$(. /etc/os-release; echo "$ID")
+      DISTRO_VERSION=$(. /etc/os-release; echo "$VERSION_ID")
+    fi
+    ;;
+  Darwin)
+    HOST_OS=macOS
+    MAKE=make
+    NPROC=$(sysctl -n hw.logicalcpu)
+    ;;
+  *)
+    fatal "Unknown host OS: '$(uname -s)'"
+    ;;
+esac
+
+export MAKE
@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI script for 'coverage.yml' results
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+# This script combines the code coverage data gathered by the test jobs into
+# the HTML report published on GitHub Pages, and for a pull request, builds the
+# content of the response comment posted on it.
+
+# Developer note: You should be able to run this script in your local checkout
+# if you have GitHub CLI (command 'gh') setup, authenticated ('gh auth login'),
+# and have set a default repository ('gh repo set-default').
+
+set -eo pipefail
+
+# Trace when running in the CI
+[ "$GITHUB_ACTIONS" != "true" ] || set -x
+
+# Arguments:
+#  1. run ID
+#  2. number of the pull request, or empty for a non-pull-request run
+#  3. base SHA of the pull request (pull requests only)
+#  4. head SHA of the pull request (pull requests only)
+RUN_ID=$1
+PR_NUMBER=$2
+PR_BASE_SHA=$3
+PR_HEAD_SHA=$4
+
+# Coverage data and report directory, uploaded as the 'coverage-report' artifact
+COVERAGE_DIR=obj_coverage
+ls -lsha ${COVERAGE_DIR}
+
+# Combine the reports from the test jobs
+nodist/fastcov.py -C ${COVERAGE_DIR}/verilator-*.info --lcov -o ${COVERAGE_DIR}/verilator.info
+
+# Create the report. For a pull request, report patch coverage against the
+# merge-base between the head of the pull request and the target branch. The
+# summary quoted in the notification below is only in the log of 'make'.
+MAKE_LOG=make-coverage-report.log
+if [ -n "${PR_NUMBER}" ]; then
+  COVERAGE_BASE=$(git rev-parse --short $(git merge-base ${PR_BASE_SHA} ${PR_HEAD_SHA}))
+  make coverage-report COVERAGE_BASE=${COVERAGE_BASE} |& tee ${MAKE_LOG}
+else
+  make coverage-report
+fi
+
+# Remove the data files, only the HTML report is published
+rm -f ${COVERAGE_DIR}/verilator*.info
+
+# The rest is for pull requests only
+if [ -z "${PR_NUMBER}" ]; then
+  exit 0
+fi
+
+# Get some metadata about the run
+RUN_NUM=$(gh run view ${RUN_ID} --json number --jq ".number")
+RUN_URL=$(gh run view ${RUN_ID} --json url    --jq ".url")
+
+# Repository owner and name of the default repository, used to build the
+# GitHub Pages URL of the report. The owner is lowercased, as required for the
+# '<owner>.github.io' Pages domain.
+PAGES_OWNER=$(gh repo view --json owner --jq '.owner.login' | tr '[:upper:]' '[:lower:]')
+PAGES_NAME=$(gh repo view --json name --jq '.name')
+
+REPORT_URL=https://${PAGES_OWNER}.github.io/${PAGES_NAME}/coverage-reports/${RUN_ID}/index.html
+
+###############################################################################
+# Create the PR notification
+###############################################################################
+
+NOTIFICATION_DIR=notification
+mkdir -p ${NOTIFICATION_DIR}
+
+cat > ${NOTIFICATION_DIR}/body.txt <<NOTIFICATION_TEMPLATE
+Patch coverage from PR workflow [#${RUN_NUM}](${RUN_URL}) (code coverage of lines changed relative to ${COVERAGE_BASE}):
+NOTIFICATION_TEMPLATE
+
+if [ -f ${COVERAGE_DIR}/empty-patch ]; then
+  # Patch is empty
+  cat >> ${NOTIFICATION_DIR}/body.txt <<SUMMARY_TEMPLATE
+Patch contains no code changes
+SUMMARY_TEMPLATE
+
+  echo "Workflow [#${RUN_NUM}](${RUN_URL}): patch contains no code changes" > ${NOTIFICATION_DIR}/hist.txt
+
+else
+  # Patch contains code changes
+
+  cat >> ${NOTIFICATION_DIR}/body.txt <<SUMMARY_TEMPLATE
+<pre>
+$(grep -E "(lines|branches)\.*:" ${MAKE_LOG} | sed "s/\.*:/:/" || true)
+</pre>
+Report: [${RUN_ID}](${REPORT_URL})
+
+Please get to 100% line coverage, and understand all branches; see the [developer docs](https://github.com/verilator/verilator/blob/master/docs/internals.rst#code-coverage-results)
+SUMMARY_TEMPLATE
+
+  echo "Workflow [#${RUN_NUM}](${RUN_URL}) report: [${RUN_ID}](${REPORT_URL})" > ${NOTIFICATION_DIR}/hist.txt
+fi
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # DESCRIPTION: Verilator: CI dependency install script
 #
-# SPDX-FileCopyrightText: 2020 Geza Lore
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ################################################################################
@@ -10,121 +10,211 @@
 # required by the particular build stage.
 ################################################################################

+# Installs system packages with sudo; never run locally
+if [ "$GITHUB_ACTIONS" != "true" ]; then
+  echo "ERROR: $(basename "$0") must only be run in GitHub Actions CI" >&2
+  exit 1
+fi
+
 set -e
 set -x

 cd $(dirname "$0")/..

-# Avoid occasional cpan failures "Issued certificate has expired."
-export PERL_LWP_SSL_VERIFY_HOSTNAME=0
-echo "check_certificate = off" >> ~/.wgetrc
+source "$(dirname "$0")/ci-common.bash"

-fatal() {
-  echo "ERROR: $(basename "$0"): $1" >&2; exit 1;
-}
+################################################################################
+# Parse arguments

-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 CI_OS_NAME: '$CI_OS_NAME'"
+# Which stage to install dependencies for
+STAGE="$1"
+
+################################################################################
+# Install dependencies
+
+if [ "$HOST_OS" = "macOS" ]; then
+  # The macos runner image ships an untrusted third-party tap we don't use;
+  # untap it so brew stops emitting a tap-trust warning. Force + '|| true' since
+  # untap fails if a formula was installed from it, which is harmless here.
+  brew untap --force aws/tap || true
 fi

-if [ "$CI_OS_NAME" = "linux" ]; then
-  # Avoid slow "processing triggers for man db"
-  echo "path-exclude /usr/share/doc/*"  | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-  echo "path-exclude /usr/share/man/*"  | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-  echo "path-exclude /usr/share/info/*" | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
-fi
-
-install-vcddiff() {
-  TMP_DIR="$(mktemp -d)"
-  git clone https://github.com/veripool/vcddiff "$TMP_DIR"
-  git -C "${TMP_DIR}" checkout 4db0d84a27e8f148b127e916fc71d650837955c5
-  "$MAKE" -C "${TMP_DIR}"
-  sudo cp "${TMP_DIR}/vcddiff" /usr/local/bin
+# Run 'sudo apt-get', with timeout, retrying if failed
+apt-get-retry() {
+  local _attempt
+  for _attempt in 1 2 3; do
+    [ "$_attempt" -eq 1 ] || sleep $((15 * _attempt))
+    sudo timeout --kill-after=30s 5m env DEBIAN_FRONTEND=noninteractive \
+      apt-get -o DPkg::Lock::Timeout=60 "$@" && return 0
+  done
+  fatal "'apt-get $*' failed on all attempts"
 }

-if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
+# Run 'brew', retrying if failed
+brew-retry() {
+  local _attempt
+  for _attempt in 1 2 3; do
+    [ "$_attempt" -eq 1 ] || sleep $((15 * _attempt))
+    brew "$@" && return 0
+  done
+  fatal "'brew $*' failed on all attempts"
+}
+
+install-wavediff() {
+  source ci/docker/buildenv/wavetools.conf
+  local _base_url="https://github.com/hudson-trading/wavetools/releases/download/${WAVETOOLS_VERSION}"
+  local _platform
+  if [ "$HOST_OS" = "linux" ]; then
+    _platform="linux-x86_64"
+  elif [ "$HOST_OS" = "macOS" ]; then
+    _platform="macos-arm64"
+  else
+    echo "WARNING: No wavetools binary available for HOST_OS=$HOST_OS, skipping"
+    return 0
+  fi
+  local _tmpdir
+  _tmpdir=$(mktemp -d)
+  local _archive="wavetools-${WAVETOOLS_VERSION}-${_platform}"
+  wget -q -O "${_tmpdir}/${_archive}.tar.gz" "${_base_url}/${_archive}.tar.gz"
+  tar -xzf "${_tmpdir}/${_archive}.tar.gz" -C "${_tmpdir}"
+  sudo cp "${_tmpdir}/${_archive}/wavediff" /usr/local/bin/wavediff
+  rm -rf "${_tmpdir}"
+}
+
+if [ "$STAGE" = "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 update
-    sudo apt-get install --yes ccache help2man libfl-dev ||
-    sudo apt-get install --yes ccache help2man libfl-dev
-    if [[ ! "$CI_RUNS_ON" =~ "ubuntu-22.04" ]]; then
-      # Some conflict of libunwind verison on 22.04, can live without it for now
-      sudo apt-get install --yes libjemalloc-dev ||
-      sudo apt-get install --yes libjemalloc-dev
-    fi
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-26.04" ]]; then
-      if [[ ! "$CI_RUNS_ON" =~ "-riscv" ]]; then
-        sudo apt-get install --yes libsystemc libsystemc-dev ||
-        sudo apt-get install --yes libsystemc libsystemc-dev
+  if [ "$HOST_OS" = "linux" ]; then
+    if [ "$DISTRO_ID" = "ubuntu" ]; then
+      PACKAGES=(
+        bear
+        ccache
+        help2man
+        libfl-dev
+        libsystemc-dev
+        mold
+      )
+      # libunwind conflict on 22.04, can live without libjemalloc there
+      if [ "$DISTRO_VERSION" != "22.04" ]; then
+        PACKAGES+=(libjemalloc-dev)
      fi
+      apt-get-retry update
+      apt-get-retry install --yes "${PACKAGES[@]}"
    fi
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-26.04" ]]; then
-      sudo apt-get install --yes bear mold ||
-      sudo apt-get install --yes bear mold
-    fi
-  elif [ "$CI_OS_NAME" = "osx" ]; then
-    brew update ||
-    brew update
-    brew install ccache perl gperftools autoconf bison flex help2man ||
-    brew install ccache perl gperftools autoconf bison flex help2man
-  elif [ "$CI_OS_NAME" = "freebsd" ]; then
-    sudo pkg install -y autoconf bison ccache gmake perl5
+  elif [ "$HOST_OS" = "macOS" ]; then
+    PACKAGES=(
+      autoconf
+      bison
+      ccache
+      flex
+      gperftools
+      help2man
+      perl
+    )
+    brew-retry update
+    brew-retry install "${PACKAGES[@]}"
  else
-    fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
+    fatal "Unknown HOST_OS: '$HOST_OS'"
  fi
-
-  if [ -n "$CCACHE_DIR" ]; then
-    mkdir -p "$CCACHE_DIR"
-  fi
-elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
+elif [ "$STAGE" = "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 ||
-    sudo apt-get update
-    # libfl-dev needed for internal coverage's test runs
-    sudo apt-get install --yes gdb gtkwave lcov libfl-dev ccache jq z3 ||
-    sudo apt-get install --yes gdb gtkwave lcov libfl-dev ccache jq z3
-    # Required for test_regress/t/t_dist_attributes.py
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-26.04" ]]; then
-      sudo apt-get install --yes python3-clang mold ||
-      sudo apt-get install --yes python3-clang mold
+  if [ "$HOST_OS" = "linux" ]; then
+    if [ "$DISTRO_ID" = "ubuntu" ]; then
+      PACKAGES=(
+        ccache
+        gdb
+        jq
+        lcov
+        libfl-dev
+        libsystemc-dev
+        mold
+        python3-clang
+        z3
+      )
+      apt-get-retry update
+      apt-get-retry install --yes "${PACKAGES[@]}"
    fi
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-26.04" ]]; then
-      if [[ ! "$CI_RUNS_ON" =~ "-riscv" ]]; then
-        sudo apt-get install --yes libsystemc libsystemc-dev ||
-        sudo apt-get install --yes libsystemc libsystemc-dev
-      fi
-    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 jq z3
-  elif [ "$CI_OS_NAME" = "freebsd" ]; then
-    # fst2vcd fails with "Could not open '<input file>', exiting."
-    sudo pkg install -y ccache gmake perl5 python3 jq z3
+  elif [ "$HOST_OS" = "macOS" ]; then
+    PACKAGES=(
+      ccache
+      jq
+      perl
+      z3
+    )
+    brew-retry update
+    brew-retry install "${PACKAGES[@]}"
  else
-    fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
+    fatal "Unknown HOST_OS: '$HOST_OS'"
  fi
  # Common installs
-  install-vcddiff
+  install-wavediff
  # Workaround -fsanitize=address crash
  sudo sysctl -w vm.mmap_rnd_bits=28
+elif [ "$STAGE" = "lint-py" ]; then
+  ##############################################################################
+  # Dependencies for nodist/clang_check_attributes
+
+  if [ "$HOST_OS" = "linux" ] && [ "$DISTRO_ID" = "ubuntu" ]; then
+    PACKAGES=(
+      python3-clang  # Not run, but importers are linted
+    )
+    apt-get-retry update
+    apt-get-retry install --yes "${PACKAGES[@]}"
+  fi
+elif [ "$STAGE" = "format" ]; then
+  ##############################################################################
+  # Dependencies of 'make format'
+
+  if [ "$HOST_OS" = "linux" ] && [ "$DISTRO_ID" = "ubuntu" ]; then
+    PACKAGES=(
+      clang-format-18  # Version pinned, so all of CI formats alike
+    )
+    apt-get-retry update
+    apt-get-retry install --yes "${PACKAGES[@]}"
+  fi
+elif [ "$STAGE" = "coverage" ]; then
+  ##############################################################################
+  # Dependencies of the coverage report job, which only collates what the
+  # 'test' stage jobs measured
+
+  if [ "$HOST_OS" = "linux" ] && [ "$DISTRO_ID" = "ubuntu" ]; then
+    PACKAGES=(
+      lcov
+    )
+    apt-get-retry update
+    apt-get-retry install --yes "${PACKAGES[@]}"
+  fi
+elif [ "$STAGE" = "rtlmeter-run" ]; then
+  ##############################################################################
+  # Dependencies of the RTLMeter jobs, which compile and run designs with an
+  # already built Verilator, so they need its runtime prerequisites only
+
+  if [ "$HOST_OS" = "linux" ] && [ "$DISTRO_ID" = "ubuntu" ]; then
+    PACKAGES=(
+      ccache
+      libfl-dev
+      libjemalloc-dev
+      libsystemc-dev
+      mold
+    )
+    apt-get-retry update
+    apt-get-retry install --yes "${PACKAGES[@]}"
+  fi
 else
  ##############################################################################
  # Unknown build stage
-  fatal "Unknown CI_BUILD_STAGE_NAME: '$CI_BUILD_STAGE_NAME'"
+  fatal "Unknown stage '$STAGE'"
 fi
+
+# Report where the tools we may have installed live (ok if some are missing)
+set +x
+echo "Tools:"
+for bin in autoconf bear bison ccache flex gdb help2man jq lcov mold perl wavediff z3; do
+  echo -n "  $bin: "
+  which "$bin" || echo "Not found"
+done
@@ -4,39 +4,164 @@
 # SPDX-FileCopyrightText: 2025 Geza Lore
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

-# Notify PRs via comment that their coverage reports are available
+# Notify PRs via comment that their workflow reports are available

-# Get the current repo URL - might differ on a fork
-readonly REPO_URL=$(gh repo view --json url --jq .url)
+# Note this deliberately does not 'set -e'. A run that cannot be notified, say
+# because its pull request was locked, must not hold up the notification of all
+# the others, so each failure below moves on to the next run instead. Its
+# artifact is then left in place, so it is retried on the next run of 'pages.yml'.
+
+# The account we post as, which is how we tell our own earlier notifications
+# from anybody else's comments. 'pages.yml' sets this to the slug of the app the
+# token belongs to. Set it to your own login when running this by hand. The 'jq'
+# filter below picks it up from the environment.
+if [ -z "${GH_AUTHOR:-}" ]; then
+  echo "GH_AUTHOR must hold the account we post as" >&2
+  exit 1
+fi
+echo "Posting as '${GH_AUTHOR}'"
+
+# Marker line separating the report from the history of the older reports
+readonly HISTORY_MARKER='<!-- Verilator CI notification history -->'
+# Opening line of the HTML comment stashing the history entry of the report
+# itself. It is not shown in its own history, only inherited by the ones
+# superseding it, hence it is kept out of sight until then.
+readonly NEXTHIST_MARKER='<!-- Verilator CI notification entry'

 # Create artifacts root directory
 ARTIFACTS_ROOT=artifacts
 mkdir -p ${ARTIFACTS_ROOT}

-for RUN_ID in ${COVERAGE_PR_RUN_IDS//,/ }; do
-  echo "@@@ Processing run ${RUN_ID}"
-
+for RUN_ID in ${PR_RUN_IDS//,/ }; do
  # Create workflow artifacts directory
  ARTIFACTS_DIR=${ARTIFACTS_ROOT}/${RUN_ID}
  mkdir -p ${ARTIFACTS_DIR}

  # Download artifact of this run, if exists
-  gh run download ${RUN_ID} --name coverage-pr-notification --dir ${ARTIFACTS_DIR} || true
-  ls -lsha ${ARTIFACTS_DIR}
+  gh run download ${RUN_ID} --name pr-notification --dir ${ARTIFACTS_DIR} &> /dev/null || true

  # Move on if no notification is required
  if [ ! -f ${ARTIFACTS_DIR}/pr-number.txt ]; then
-    echo "No notification found"
    continue
  fi
-  echo "Posting notification found"

-  cat ${ARTIFACTS_DIR}/body.txt
-  gh pr comment $(cat ${ARTIFACTS_DIR}/pr-number.txt) --body-file ${ARTIFACTS_DIR}/body.txt
+  PR_NUMBER=$(cat ${ARTIFACTS_DIR}/pr-number.txt)
+  echo "@@@ Run ${RUN_ID}: notifying PR #${PR_NUMBER}"

-  # Get the artifact ID
-  ARTIFACT_ID=$(gh api "repos/{owner}/{repo}/actions/runs/${RUN_ID}/artifacts" --jq '.artifacts[] | select(.name == "coverage-pr-notification") | .id')
+  # Everything below is created and validated by the 'upload-pr-notification'
+  # action. Move on if this artifact was not made by it, e.g. it is left over
+  # from an earlier version of the CI, so it does not hold up the other runs.
+  for f in body.txt key.txt hist.txt; do
+    if [ ! -f ${ARTIFACTS_DIR}/${f} ]; then
+      echo "Notification has no '${f}'" >&2
+      continue 2  # Note: continues the enclosing 'RUN_ID' loop
+    fi
+  done

-  # Delete it, so we only notify once
-  gh api --method DELETE "repos/{owner}/{repo}/actions/artifacts/${ARTIFACT_ID}"
+  # 'key.txt' holds the key naming the source of the notification. It goes on the
+  # first line of the comment as an HTML comment, so it is invisible when
+  # rendered, and is used below to find the stale notifications with the same
+  # key, which are then superseded by the new one and deleted.
+  COMMENT_MARKER="<!-- Verilator CI notification: $(cat ${ARTIFACTS_DIR}/key.txt) -->"
+
+  # Find the stale notifications from the same source on this PR. That is, our
+  # own comments with the same marker on their first line. Oldest first, as
+  # returned by the API. An app posts as '<slug>[bot]', so drop that suffix to
+  # compare against the slug. Move on if they cannot be listed, as without them
+  # we would post a duplicate instead of superseding them.
+  if ! COMMENT_MARKER="${COMMENT_MARKER}" \
+      gh api --paginate "repos/{owner}/{repo}/issues/${PR_NUMBER}/comments" \
+        --jq '.[]
+              | select((.user.login | rtrimstr("[bot]")) == env.GH_AUTHOR)
+              | select((.body | split("\n") | .[0] | rtrimstr("\r")) == env.COMMENT_MARKER)
+              | {id, body}' > ${ARTIFACTS_DIR}/stale.json; then
+    echo "Failed to list the comments of PR #${PR_NUMBER}" >&2
+    continue
+  fi
+
+  # Inherit the history of the newest stale notification. There should only ever
+  # be one, and it holds the whole history anyway, as each notification inherits
+  # the history of the one it superseded. Any older ones are only deleted below.
+  STALE_COUNT=$(wc -l < ${ARTIFACTS_DIR}/stale.json)
+  if [ ${STALE_COUNT} -gt 1 ]; then
+    echo "Found ${STALE_COUNT} stale notifications, only the newest is inherited from"
+  fi
+
+  HISTORY=${ARTIFACTS_DIR}/history.txt
+  touch ${HISTORY}
+  if [ ${STALE_COUNT} -gt 0 ]; then
+    tail -n 1 ${ARTIFACTS_DIR}/stale.json | jq -r '.body' | tr -d '\r' > ${ARTIFACTS_DIR}/stale-body.txt
+    # Its own entry, stashed in an HTML comment
+    awk -v marker="${NEXTHIST_MARKER}" '
+      $0 == marker { inside = 1; next }
+      !inside { next }
+      $0 == "-->" { exit }
+      NF { print }
+    ' ${ARTIFACTS_DIR}/stale-body.txt >> ${HISTORY}
+    # Followed by its history, without the enclosing '<details>' markup
+    awk -v marker="${HISTORY_MARKER}" '
+      $0 == marker { inside = 1; next }
+      !inside { next }
+      $0 == "<details>" || /^<summary>/ { next }
+      $0 == "</details>" { exit }
+      NF { print }
+    ' ${ARTIFACTS_DIR}/stale-body.txt >> ${HISTORY}
+  fi
+
+  # Assemble the comment. Starts with the marker and the report.
+  COMMENT=${ARTIFACTS_DIR}/comment.txt
+  cat > ${COMMENT} <<COMMENT_TEMPLATE
+${COMMENT_MARKER}
+$(cat ${ARTIFACTS_DIR}/body.txt)
+COMMENT_TEMPLATE
+
+  # Then the history inherited from the notifications this one supersedes, so
+  # the older reports remain reachable from the only remaining comment.
+  if [ -s ${HISTORY} ]; then
+    echo "History holds $(wc -l < ${HISTORY}) entries"
+    cat >> ${COMMENT} <<HISTORY_TEMPLATE
+${HISTORY_MARKER}
+<details>
+<summary>PR history</summary>
+
+$(cat ${HISTORY})
+</details>
+HISTORY_TEMPLATE
+  fi
+
+  # Finally this report's own history entry, stashed out of sight until a later
+  # notification inherits it.
+  cat >> ${COMMENT} <<NEXTHIST_TEMPLATE
+${NEXTHIST_MARKER}
+$(cat ${ARTIFACTS_DIR}/hist.txt)
+-->
+NEXTHIST_TEMPLATE
+
+  # Post it. Move on if this failed, without deleting anything below, otherwise
+  # the history held by the stale notifications would be lost.
+  if ! jq -Rs '{body: .}' ${COMMENT} \
+      | gh api --method POST "repos/{owner}/{repo}/issues/${PR_NUMBER}/comments" \
+          --input - > ${ARTIFACTS_DIR}/posted.json; then
+    echo "Failed to post this notification on PR #${PR_NUMBER}:" >&2
+    cat ${COMMENT} >&2
+    continue
+  fi
+  echo "Posted $(jq -r '.html_url' ${ARTIFACTS_DIR}/posted.json)"
+
+  # Delete the stale notifications, so only the new one remains
+  for COMMENT_ID in $(jq -r '.id' ${ARTIFACTS_DIR}/stale.json); do
+    echo "Deleting stale comment ${COMMENT_ID}"
+    gh api --method DELETE "repos/{owner}/{repo}/issues/comments/${COMMENT_ID}"
+  done
+
+  # Get the artifact IDs. Note there can be more than one artifact named
+  # 'pr-notification' for a single run, as the artifacts endpoint lists
+  # artifacts across all run attempts, and a re-run uploads a new one while
+  # keeping the previous attempt's artifact.
+  ARTIFACT_IDS=$(gh api "repos/{owner}/{repo}/actions/runs/${RUN_ID}/artifacts" --jq '.artifacts[] | select(.name == "pr-notification") | .id')
+
+  # Delete them all, so we only notify once
+  for ARTIFACT_ID in ${ARTIFACT_IDS}; do
+    gh api --method DELETE "repos/{owner}/{repo}/actions/artifacts/${ARTIFACT_ID}"
+  done
 done
@@ -5,8 +5,7 @@
 # SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 # This scipt build the content of the GitHub Pages for the repository.
-# Currently this only hosts code coverage reports, but it would be possible to
-# add any other contents to the page in parallel here.
+# Currently this hosts code coverage reports, and PR RTLMeter detailed reports.

 # Developer note: You should be able to run this script in your local checkout
 # if you have GitHub CLI (command 'gh') setup, authenticated ('gh auth login'),
@@ -25,6 +24,9 @@ if [[ -z "$GITHUB_OUTPUT" ]]; then
  GITHUB_OUTPUT=github-output.txt
 fi

+# Run IDs of PR jobs processed
+PR_RUN_IDS=""
+
 # Populates ${PAGES_ROOT}/coverage-reports
 compile_coverage_reports() {
  # We will process all runs up to and including this date. This is chosen to be
@@ -33,16 +35,13 @@ compile_coverage_reports() {

  # Gather all coverage workflow runs within the time window
  gh run list -w coverage.yml --limit 1000 --created ">=${OLDEST}" --json "databaseId,event,status,conclusion,createdAt,number" > recentRuns.json
-  echo @@@ Recent runs:
-  jq "." recentRuns.json

  # Select completd runs that were not cancelled or skipped, sort by descending run number
  jq 'sort_by(-.number) | map(select(.status == "completed" and (.conclusion == "success" or .conclusion == "failure")))' recentRuns.json > completedRuns.json
-  echo @@@ Completed with success or failure:
-  jq "." completedRuns.json
+  echo "@@@ $(jq length completedRuns.json) of $(jq length recentRuns.json) runs since ${OLDEST} completed with success or failure"

  # Create artifacts root directory
-  local ARTIFACTS_ROOT=artifacts
+  local ARTIFACTS_ROOT=artifacts-coverage
  mkdir -p ${ARTIFACTS_ROOT}

  # Create coverage reports root directory
@@ -53,9 +52,6 @@ compile_coverage_reports() {
  local CONTENTS=contents.tmp
  echo > ${CONTENTS}

-  # Run IDs of PR jobs processed
-  local PR_RUN_IDS=""
-
  # Iterate over all unique event types that triggered the workflows
  for EVENT in $(jq -r 'map(.event) | sort | unique | .[]' completedRuns.json); do
    echo "@@@ Processing '${EVENT}' runs"
@@ -65,35 +61,24 @@ compile_coverage_reports() {

    # For each worfklow run that was triggered by this event type
    for RUN_ID in $(jq ".[] | select(.event == \"${EVENT}\") |.databaseId" completedRuns.json); do
-      echo "@@@ Processing run ${RUN_ID}"
-
      # Extract the info of this run
      jq ".[] | select(.databaseId == $RUN_ID)" completedRuns.json > workflow.json
-      jq "." workflow.json

      # Record run ID of PR job
-      if [[ $EVENT == "pull_request" ]]; then
-        if [[ -z "$PR_RUN_IDS" ]]; then
-          PR_RUN_IDS="$RUN_ID"
-        else
-          PR_RUN_IDS="$PR_RUN_IDS,$RUN_ID"
-        fi
-      fi
+      [[ $EVENT != "pull_request" ]] || PR_RUN_IDS="$PR_RUN_IDS $RUN_ID"

      # Create workflow artifacts directory
      local ARTIFACTS_DIR=${ARTIFACTS_ROOT}/${RUN_ID}
      mkdir -p ${ARTIFACTS_DIR}

      # Download artifacts of this run, if exists
-      gh run download ${RUN_ID} --name coverage-report --dir ${ARTIFACTS_DIR} || true
-      ls -lsha ${ARTIFACTS_DIR}
+      gh run download ${RUN_ID} --name coverage-report --dir ${ARTIFACTS_DIR} &> /dev/null || true

      # Move on if no coverage report is available
      if [ ! -d ${ARTIFACTS_DIR}/report ]; then
-        echo "No coverage report found"
        continue
      fi
-      echo "Coverage report found"
+      echo "@@@ Run ${RUN_ID}: coverage report found"

      # Emit section header
      if [[ -n $EMIT_SECTION_HEADER ]]; then
@@ -148,7 +133,7 @@ CONTENTS_TEMPLATE

  <body>
  $(cat ${CONTENTS})
-  <h4>Assembled $(date --iso-8601=minutes --utc)</h1>
+  <h4>Assembled $(date --iso-8601=minutes --utc)</h4>
  <body>

  </html>
@@ -156,12 +141,128 @@ INDEX_TEMPLATE

  # Report size
  du -shc ${COVERAGE_ROOT}/*
+}

-  # Set output
-  echo "coverage-pr-run-ids=${PR_RUN_IDS}" >> $GITHUB_OUTPUT
+# Populates ${PAGES_ROOT}/rtlmeter-reports
+compile_rtlmeter_reports() {
+  # We will process all runs up to and including this date. This is chosen to be
+  # slightly less than the artifact retention period for simplicity.
+  local OLDEST=$(date --date="28 days ago" --iso-8601=date)
+
+  # Gather all RTLMeter workflow runs within the time window
+  gh run list -w rtlmeter.yml --limit 1000 --created ">=${OLDEST}" --json "databaseId,event,status,conclusion,createdAt,number" > recentRuns.json
+
+  # Select completd runs that were not cancelled or skipped, sort by descending run number
+  jq 'sort_by(-.number) | map(select(.status == "completed" and (.conclusion == "success" or .conclusion == "failure")))' recentRuns.json > completedRuns.json
+  echo "@@@ $(jq length completedRuns.json) of $(jq length recentRuns.json) runs since ${OLDEST} completed with success or failure"
+
+  # Create artifacts root directory
+  local ARTIFACTS_ROOT=artifacts-rtlmeter
+  mkdir -p ${ARTIFACTS_ROOT}
+
+  # Create rtlmeter reports root directory
+  local RTLMETER_ROOT=${PAGES_ROOT}/rtlmeter-reports
+  mkdir -p ${RTLMETER_ROOT}
+
+  # Create index page contents fragment
+  local CONTENTS=contents.tmp
+  echo > ${CONTENTS}
+
+  # Iterate over all unique event types that triggered the workflows
+  for EVENT in $(jq -r 'map(.event) | sort | unique | .[]' completedRuns.json); do
+    echo "@@@ Processing '${EVENT}' runs"
+
+    # Emit section header if a report exists with this event type
+    EMIT_SECTION_HEADER=1
+
+    # For each worfklow run that was triggered by this event type
+    for RUN_ID in $(jq ".[] | select(.event == \"${EVENT}\") |.databaseId" completedRuns.json); do
+      # Extract the info of this run
+      jq ".[] | select(.databaseId == $RUN_ID)" completedRuns.json > workflow.json
+
+      # Record run ID of PR job
+      [[ $EVENT != "pull_request" ]] || PR_RUN_IDS="$PR_RUN_IDS $RUN_ID"
+
+      # Create workflow artifacts directory
+      local ARTIFACTS_DIR=${ARTIFACTS_ROOT}/${RUN_ID}
+      mkdir -p ${ARTIFACTS_DIR}
+
+      # Download artifacts of this run, if exists
+      gh run download ${RUN_ID} --name rtlmeter-report --dir ${ARTIFACTS_DIR} &> /dev/null || true
+
+      # Move on if no RTLMeter report is available
+      if [ ! -d ${ARTIFACTS_DIR}/report ]; then
+        continue
+      fi
+      echo "@@@ Run ${RUN_ID}: RTLMeter report found"
+
+      # Emit section header
+      if [[ -n $EMIT_SECTION_HEADER ]]; then
+        unset EMIT_SECTION_HEADER
+        echo "<h4>RTLMeter reports for '${EVENT}' runs:</h4>" >> ${CONTENTS}
+      fi
+
+      # Create pages subdirectory
+      mv ${ARTIFACTS_DIR}/report ${RTLMETER_ROOT}/${RUN_ID}
+
+      # Add index page content
+      local WORKFLOW_CREATED=$(jq -r '.createdAt' workflow.json)
+      local WOFKRLOW_NUMBER=$(jq -r '.number' workflow.json)
+      cat >> ${CONTENTS} <<CONTENTS_TEMPLATE
+        Run <a href="${RUN_ID}/index.html">#${WOFKRLOW_NUMBER}</a>
+        | GitHub: <a href="${REPO_URL}/actions/runs/${RUN_ID}">${RUN_ID}</a>
+        | started at: ${WORKFLOW_CREATED}
+CONTENTS_TEMPLATE
+      if [ -e ${ARTIFACTS_DIR}/pr-number.txt ]; then
+        local PRNUMBER=$(cat ${ARTIFACTS_DIR}/pr-number.txt)
+        echo " | Pull request: <a href=\"${REPO_URL}/pull/${PRNUMBER}\">#${PRNUMBER}</a>" >> ${CONTENTS}
+      fi
+      echo "<br>" >> ${CONTENTS}
+    done
+
+    # Section break
+    if [[ -z "$EMIT_SECTION_HEADER" ]]; then
+      echo "<hr>" >> ${CONTENTS}
+    fi
+  done
+
+  # Write rtlmeter report index.html
+  cat > ${RTLMETER_ROOT}/index.html  <<INDEX_TEMPLATE
+  <html>
+
+  <head>
+    <title>Verilator CI RTLMeter reports</title>
+    <style>
+    body {
+      font-family: courier, serif;
+      background-color: #f3f3f3;
+      a {
+        color: #008fd7;
+      }
+    }
+    </style>
+  </head>
+
+  <body>
+  $(cat ${CONTENTS})
+  <h4>Assembled $(date --iso-8601=minutes --utc)</h4>
+  <body>
+
+  </html>
+INDEX_TEMPLATE
+
+  # Report size
+  du -shc ${RTLMETER_ROOT}/*
 }

 # Compilie coverage reports
 compile_coverage_reports;

+# Compile RTLMeter reports
+compile_rtlmeter_reports;
+
 # You can build any other content here to be put under ${PAGES_ROOT}
+
+# Set output to all affected unique PR run IDs (comma separated, no trailing comma)
+IDS=$(echo ${PR_RUN_IDS} | xargs -n1 | sort -u | paste -sd,)
+echo "pr-run-ids=${IDS}" >> $GITHUB_OUTPUT
@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+# DESCRIPTION: Verilator: RTLMeter cases to run in the rtlmeter.yml CI workflow
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+###############################################################################
+# Defines the RTLMeter cases to run in CI. This is consumed by the 'start' job
+# in rtlmeter.yml, which captures the printed JSON and feeds it to the run job
+# matrices.
+###############################################################################
+
+import argparse
+import json
+
+# Cases to run for scheduled runs, keyyed by the 'run tag' used in rtlmeter.yml
+# The associated priority is roughly the number of minutes it takes to run the
+# job, the emitted job matrix will try to start longest jobs first.
+
+# Cases to run for non-PR jobs (e.g.: nightly schedule)
+# fmt: off
+CASES = {
+    "gcc": [
+        ("BlackParrot:1x1:*",                    5),
+        ("BlackParrot:2x2:*",                    14),
+        ("BlackParrot:4x4:*",                    25),
+        ("Caliptra:default:*",                   19),
+        ("HummingbirdV2-E203:default:*",         3),
+        ("HummingbirdV2-E203:nodelay:*",         3),
+        ("NVDLA:*",                              29),
+        ("OpenPiton:1x1:*",                      4),
+        ("OpenPiton:2x2:*",                      7),
+        ("OpenPiton:4x4:*",                      10),
+        ("OpenTitan:*",                          16),
+        ("Servant:qerv:*",                       2),
+        ("Servant:serv:*",                       2),
+        ("VeeR-EH1:asic:*",                      4),
+        ("VeeR-EH1:default:*",                   6),
+        ("VeeR-EH1:hiperf:*",                    5),
+        ("VeeR-EH2:asic:*",                      13),
+        ("VeeR-EH2:default:*",                   6),
+        ("VeeR-EH2:hiperf:*",                    12),
+        ("VeeR-EL2:asic:*",                      4),
+        ("VeeR-EL2:default:*",                   4),
+        ("VeeR-EL2:hiperf:*",                    4),
+        ("Vortex:mini:*",                        3),
+        ("Vortex:sane:*",                        6),
+        ("XiangShan:default-chisel3:* !*:linux", 31),
+        ("XiangShan:default-chisel6:* !*:linux", 28),
+        ("XiangShan:mini-chisel3:* !*:linux",    13),
+        ("XiangShan:mini-chisel6:* !*:linux",    15),
+        ("XuanTie-C906:*",                       5),
+        ("XuanTie-C910:*",                       9),
+        ("XuanTie-E902:*",                       5),
+        ("XuanTie-E906:*",                       6),
+    ],
+    "clang": [
+        ("BlackParrot:1x1:*",                    5),
+        ("BlackParrot:2x2:*",                    9),
+        ("BlackParrot:4x4:*",                    12),
+        ("Caliptra:default:*",                   16),
+        ("HummingbirdV2-E203:default:*",         10),
+        ("HummingbirdV2-E203:nodelay:*",         10),
+        ("NVDLA:*",                              28),
+        ("OpenPiton:1x1:*",                      5),
+        ("OpenPiton:2x2:*",                      6),
+        ("OpenPiton:4x4:*",                      8),
+        ("OpenTitan:*",                          10),
+        ("Servant:qerv:phil",                    17),
+        ("Servant:serv:phil",                    15),
+        ("VeeR-EH1:asic:*",                      6),
+        ("VeeR-EH1:default:*",                   8),
+        ("VeeR-EH1:hiperf:*",                    5),
+        ("VeeR-EH2:asic:*",                      9),
+        ("VeeR-EH2:default:*",                   8),
+        ("VeeR-EH2:hiperf:*",                    7),
+        ("VeeR-EL2:asic:*",                      4),
+        ("VeeR-EL2:default:*",                   5),
+        ("VeeR-EL2:hiperf:*",                    5),
+        ("Vortex:mini:*",                        3),
+        ("Vortex:sane:*",                        5),
+        ("XiangShan:default-chisel3:* !*:linux", 21),
+        ("XiangShan:default-chisel6:* !*:linux", 19),
+        ("XiangShan:mini-chisel3:* !*:linux",    8),
+        ("XiangShan:mini-chisel6:* !*:linux",    8),
+        ("XuanTie-C906:*",                       3),
+        ("XuanTie-C910:*",                       7),
+        ("XuanTie-E902:*",                       7),
+        ("XuanTie-E906:*",                       7),
+    ],
+    "gcc-hier": [
+        ("BlackParrot:1x1:*",    4),
+        ("BlackParrot:2x2:*",    16),
+        ("BlackParrot:4x4:*",    25),
+        ("NVDLA:*",              25),
+        ("OpenPiton:16x16:dhry", 16),
+        ("OpenPiton:1x1:*",      4),
+        ("OpenPiton:2x2:*",      4),
+        ("OpenPiton:4x4:*",      4),
+        ("OpenPiton:8x8:*",      6),
+        ("XuanTie-C910:*",       7),
+    ],
+}
+# fmt: on
+
+# Cases to run for PR jobs
+# fmt: off
+CASES_PR = {
+    "gcc": [
+        ("BlackParrot:1x1:*",                    5),
+        ("BlackParrot:4x4:*",                    25),
+        ("Caliptra:default:*",                   19),
+        ("NVDLA:*",                              29),
+        ("HummingbirdV2-E203:default:*",         3),
+        ("HummingbirdV2-E203:nodelay:*",         3),
+        ("OpenPiton:1x1:*",                      4),
+        ("OpenPiton:4x4:*",                      10),
+        ("OpenTitan:*",                          16),
+        ("Servant:qerv:*",                       2),
+        ("Servant:serv:*",                       2),
+        ("VeeR-EH1:asic:*",                      4),
+        ("VeeR-EH1:default:*",                   6),
+        ("VeeR-EH1:hiperf:*",                    5),
+        ("VeeR-EH2:asic:*",                      13),
+        ("VeeR-EH2:default:*",                   6),
+        ("VeeR-EH2:hiperf:*",                    12),
+        ("VeeR-EL2:asic:*",                      4),
+        ("VeeR-EL2:default:*",                   4),
+        ("VeeR-EL2:hiperf:*",                    4),
+        ("Vortex:mini:*",                        3),
+        ("Vortex:sane:*",                        6),
+        ("XiangShan:default-chisel3:* !*:linux", 31),
+        ("XiangShan:default-chisel6:* !*:linux", 28),
+        ("XiangShan:mini-chisel3:* !*:linux",    13),
+        ("XiangShan:mini-chisel6:* !*:linux",    15),
+        ("XuanTie-C906:*",                       5),
+        ("XuanTie-C910:*",                       9),
+        ("XuanTie-E902:*",                       5),
+        ("XuanTie-E906:*",                       6),
+    ],
+    "clang": [
+        ("BlackParrot:1x1:*",                    5),
+        ("BlackParrot:4x4:*",                    12),
+        ("Caliptra:default:*",                   16),
+        ("NVDLA:*",                              28),
+        ("HummingbirdV2-E203:default:*",         10),
+        ("HummingbirdV2-E203:nodelay:*",         10),
+        ("OpenPiton:1x1:*",                      5),
+        ("OpenPiton:4x4:*",                      8),
+        ("OpenTitan:*",                          10),
+        ("Servant:qerv:phil",                    17),
+        ("Servant:serv:phil",                    15),
+        ("VeeR-EH1:asic:*",                      6),
+        ("VeeR-EH1:default:*",                   8),
+        ("VeeR-EH1:hiperf:*",                    5),
+        ("VeeR-EH2:asic:*",                      9),
+        ("VeeR-EH2:default:*",                   8),
+        ("VeeR-EH2:hiperf:*",                    7),
+        ("VeeR-EL2:asic:*",                      4),
+        ("VeeR-EL2:default:*",                   5),
+        ("VeeR-EL2:hiperf:*",                    5),
+        ("Vortex:mini:*",                        3),
+        ("Vortex:sane:*",                        5),
+        ("XiangShan:default-chisel3:* !*:linux", 21),
+        ("XiangShan:default-chisel6:* !*:linux", 19),
+        ("XiangShan:mini-chisel3:* !*:linux",    8),
+        ("XiangShan:mini-chisel6:* !*:linux",    8),
+        ("XuanTie-C906:*",                       3),
+        ("XuanTie-C910:*",                       7),
+        ("XuanTie-E902:*",                       7),
+        ("XuanTie-E906:*",                       7),
+    ],
+    "gcc-hier": [
+        ("BlackParrot:1x1:*",    4),
+        ("BlackParrot:4x4:*",    25),
+        ("NVDLA:*",              25),
+        ("OpenPiton:16x16:dhry", 16),
+        ("OpenPiton:1x1:*",      4),
+        ("OpenPiton:4x4:*",      4),
+        ("OpenPiton:8x8:*",      6),
+        ("XuanTie-C910:*",       7),
+    ],
+}
+# fmt: on
+
+parser = argparse.ArgumentParser(
+    description="Print the RTLMeter CI cases as JSON, keyed by run tag")
+parser.add_argument("--event-name",
+                    required=True,
+                    help="GitHub event name that triggered the workflow")
+parser.add_argument(
+    "--ci-testing",
+    action="store_true",
+    help="Print only the shortest (lowest priority) case per tag, to reduce CI testing time")
+args = parser.parse_args()
+
+# Pull requests use the reduced 'CASES_PR' set, other events (e.g.: the nightly
+# schedule) use the full 'CASES' set.
+is_pr = args.event_name == "pull_request"
+selected = CASES_PR if is_pr else CASES
+
+cases = {}
+for tag, entries in selected.items():
+    # Highest priority (longest) first
+    ordered = sorted(entries, key=lambda cp: cp[1], reverse=True)
+    # While tweaking the CI, keep only the shortest (lowest priority) case to minimise churn time
+    if args.ci_testing:
+        ordered = ordered[-1:]
+    # Case filters appended to every case for this tag/event
+    suffix = ""
+    # Filters out the non-hierarchical case variants for the hierarchical job
+    if tag == "gcc-hier":
+        suffix += " !-hier"
+    # Filter out hello tests on pull requests, these just add measurement noise
+    if is_pr:
+        suffix += " !*:hello"
+    cases[tag] = [case + suffix for case, _ in ordered]
+print(json.dumps(cases, separators=(",", ":")))
@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI script for 'rtlmeter.yml' PR results
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+# This script builds the content of the response comment posted on PRs
+# at the end of RTLMeter runs.
+
+# Developer note: You should be able to run this script in your local checkout
+# if you have GitHub CLI (command 'gh') setup, authenticated ('gh auth login'),
+# and have set a default repository ('gh repo set-default').
+
+# Trace when running in the CI
+[ "$GITHUB_ACTIONS" != "true" ] || set -x
+
+# Arguments:
+#  1. run ID
+#  2. SHA of the event that triggered the run (for a PR, the test merge commit)
+#  rest: run tags
+RUN_ID=$1; shift
+RUN_SHA=$1; shift
+RUNS="$@"
+
+# $VERILATOR_CHECKOUT/ci directory
+SCRIPT_DIR=$(readlink -f $(dirname ${BASH_SOURCE[0]}))
+
+# Move into a temporary directory
+rm -rf rtlmeter-report
+mkdir rtlmeter-report
+pushd rtlmeter-report &> /dev/null
+TMP_DIR=$(readlink -f .)
+
+# Download the combined results. 'combine-results' uploads a single artifact
+# for each version, holding the per-tag JSON files (e.g. all-results-gcc.json):
+#  - 'all-results'   for the new version
+#  - 'all-reference' for the old reference version
+mkdir new ref
+NEW_DIR=$(readlink -f new)
+REF_DIR=$(readlink -f ref)
+gh run download ${RUN_ID} --name all-results   --dir $NEW_DIR
+gh run download ${RUN_ID} --name all-reference --dir $REF_DIR
+
+# Get Some metadata about the runs
+RUN_URL=$(gh run view $RUN_ID --json url --jq ".url")
+RUN_NUM=$(gh run view $RUN_ID --json number --jq ".number")
+
+# Repository owner and name of the default repository, used to build the
+# GitHub Pages URL of the detailed report. The owner is lowercased, as required
+# for the '<owner>.github.io' Pages domain. Resolved here, while still in the
+# default repository's git context (before the 'cd rtlmeter' below).
+PAGES_OWNER=$(gh repo view --json owner --jq '.owner.login' | tr '[:upper:]' '[:lower:]')
+PAGES_NAME=$(gh repo view --json name --jq '.name')
+
+# The 'old' reference was built from the target branch base commit, which is
+# the first parent of the triggering merge commit (same as the 'start' job in
+# rtlmeter.yml). Resolved here, while still in the default repository's git
+# context (before the 'cd rtlmeter' below).
+REF_SHA=$(gh api "repos/{owner}/{repo}/commits/$RUN_SHA" --jq '.parents[0].sha')
+
+# Go back to root directory
+popd &> /dev/null
+# Go to RTLMeter directory
+cd rtlmeter
+
+# Compare results
+SUMMARY_ARGS=()
+for r in $RUNS; do
+  CMP_JSON=$TMP_DIR/cmp-$r.json
+  # Gather args for summary script
+  SUMMARY_ARGS+=($NEW_DIR/all-results-$r.json $CMP_JSON)
+  # Create JSON
+  ./rtlmeter compare --format json --steps "*" --metrics "*" \
+    $REF_DIR/all-reference-$r.json $NEW_DIR/all-results-$r.json > $CMP_JSON
+  # Also create detailed tables
+  ./rtlmeter compare --format ascii --steps 'verilate' --metrics '*' $REF_DIR/all-reference-$r.json $NEW_DIR/all-results-$r.json > $TMP_DIR/verilate-$r.txt
+  ./rtlmeter compare --format ascii --steps 'cppbuild' --metrics '*' $REF_DIR/all-reference-$r.json $NEW_DIR/all-results-$r.json > $TMP_DIR/cppbuild-$r.txt
+  ./rtlmeter compare --format ascii --steps 'execute'  --metrics '*' $REF_DIR/all-reference-$r.json $NEW_DIR/all-results-$r.json > $TMP_DIR/execute-$r.txt
+  # Chop them at new lines, into one table per file
+  awk -v RS= -v prefix=$TMP_DIR/$r-frag '{print > sprintf("%s-verilate-%02d.txt",prefix,NR)}' $TMP_DIR/verilate-$r.txt
+  awk -v RS= -v prefix=$TMP_DIR/$r-frag '{print > sprintf("%s-cppbuild-%02d.txt",prefix,NR)}' $TMP_DIR/cppbuild-$r.txt
+  awk -v RS= -v prefix=$TMP_DIR/$r-frag '{print > sprintf("%s-execute-%02d.txt" ,prefix,NR)}' $TMP_DIR/execute-$r.txt
+done
+
+# Create summary, suppress failure, but save the status reported to pass back.
+STATUS=0
+venv/bin/python3 $SCRIPT_DIR/ci-rtlmeter-report.py ${SUMMARY_ARGS[@]} > $TMP_DIR/summary.txt || STATUS=$?
+# Print it
+cat $TMP_DIR/summary.txt
+
+REPORT_URL=https://${PAGES_OWNER}.github.io/${PAGES_NAME}/rtlmeter-reports/${RUN_ID}/index.html
+
+###############################################################################
+# Create the PR notification
+###############################################################################
+
+NOTIFICATION_DIR=$TMP_DIR/notification
+mkdir -p $NOTIFICATION_DIR
+
+cat > ${NOTIFICATION_DIR}/body.txt <<NOTIFICATION_TEMPLATE
+Performance metrics for PR workflow [#$RUN_NUM]($RUN_URL), comparing:
+- target branch commit [${REF_SHA:0:9}](https://github.com/${PAGES_OWNER}/${PAGES_NAME}/commit/${REF_SHA}) (A)
+- with PR merge commit [${RUN_SHA:0:9}](https://github.com/${PAGES_OWNER}/${PAGES_NAME}/commit/${RUN_SHA}) (B)
+
+<details open>
+  <summary>Summary of all runs</summary>
+  <pre>
+$(cat $TMP_DIR/summary.txt)
+  </pre>
+</details>
+
+The reported numbers are the geometric means of the ratios of the metrics over all cases,
+less than 1 is a regression, greater than 1 is an improvement.
+The jobs run on variable and noisy runners, so some variance is expected between runs.
+
+Detailed report: [${RUN_ID}](${REPORT_URL})
+NOTIFICATION_TEMPLATE
+
+echo "Workflow [#$RUN_NUM]($RUN_URL) report: [${RUN_ID}](${REPORT_URL})" > ${NOTIFICATION_DIR}/hist.txt
+
+###############################################################################
+# Create detailed report
+###############################################################################
+
+REPORT=$TMP_DIR/body.html
+cat > $REPORT <<SUMMARY_TEMPLATE
+<h3>Summary of all runs</h3>
+<pre>
+$(cat $TMP_DIR/summary.txt)
+</pre>
+SUMMARY_TEMPLATE
+echo "<h3>Detailed results</h3>" >> $REPORT
+for r in $RUNS; do
+  RUN_NAME=$(jq -rj ".[0].runName" $NEW_DIR/all-results-$r.json)
+  echo "<h4>$RUN_NAME</h4>" >> $REPORT
+  for f in $(ls -1 $TMP_DIR/$r-frag-verilate-*.txt | sort) \
+           $(ls -1 $TMP_DIR/$r-frag-cppbuild-*.txt | sort) \
+           $(ls -1 $TMP_DIR/$r-frag-execute-*.txt | sort); do
+    cat >> $REPORT <<DETAIL_TAMPLATE
+    <details>
+      <summary>$(head -n 1 $f | tr -d '\n')</summary>
+      <pre>
+$(tail -n +2 $f)
+      </pre>
+    </details>
+DETAIL_TAMPLATE
+  done
+done
+
+# Turn the report into a proper HTML page
+mkdir -p ${TMP_DIR}/report
+cat > ${TMP_DIR}/report/index.html <<INDEX_TEMPLATE
+<html>
+
+  <head>
+    <title>Verilator RTLMeter report #${RUN_NUM}</title>
+    <style>
+    body {
+      font-family: courier, serif;
+      background-color: #f3f3f3;
+      a {
+        color: #008fd7;
+      }
+    }
+    </style>
+  </head>
+
+  <body>
+$(cat ${TMP_DIR}/body.html)
+  </body>
+
+</html>
+INDEX_TEMPLATE
+
+exit $STATUS
@@ -0,0 +1,137 @@
+# DESCRIPTION: Verilator: CI script for 'rtlmeter.yml' PR results
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+###############################################################################
+# This script runs with the venv of **RTLMeter**
+###############################################################################
+
+import sys
+import json
+import tabulate
+from typing import Final, List
+
+tabulate.PRESERVE_WHITESPACE = True
+tabulate.MIN_PADDING = 0
+
+_ASCII_TABLE_FORMAT: Final = tabulate.TableFormat(
+    lineabove=tabulate.Line("╒═", "═", "═╤═", "═╕"),
+    linebelowheader=tabulate.Line("╞═", "═", "═╪═", "═╡"),
+    linebelow=tabulate.Line("╘═", "═", "═╧═", "═╛"),
+    headerrow=tabulate.DataRow("│ ", " │ ", " │"),
+    datarow=tabulate.DataRow("│ ", " │ ", " │"),
+    linebetweenrows=None,
+    padding=0,
+    with_header_hide=None,
+)
+
+
+def printTable(table: List[List[str]], **kwargs) -> None:
+    print(tabulate.tabulate(table, tablefmt=_ASCII_TABLE_FORMAT, **kwargs))
+
+
+# fmt: off
+stepMetric = (
+    # Step,      Metric,    Status Brackets
+    ("execute",  "speed",   ("❌", 0.96, "⚠️", 0.98, "✅", 1.02, "💡", 1.04, "⭐")),
+    ("execute",  "memory",  ("❌", 0.90, "⚠️", 0.95, "✅", 1.05, "💡", 1.10, "⭐")),
+    ("verilate", "cpu",     ("❌", 0.96, "⚠️", 0.98, "✅", 1.02, "💡", 1.04, "⭐")),
+    ("verilate", "memory",  ("❌", 0.90, "⚠️", 0.95, "✅", 1.05, "💡", 1.10, "⭐")),
+    ("cppbuild", "cpu",     ("❌", 0.96, "⚠️", 0.98, "✅", 1.02, "💡", 1.04, "⭐")),
+    ("cppbuild", "memory",  ("❌", 0.90, "⚠️", 0.95, "✅", 1.05, "💡", 1.10, "⭐")),
+    ("cppbuild", "codeSize",("❌", 0.96, "⚠️", 0.98, "✅", 1.02, "💡", 1.04, "⭐")),
+    ("cppbuild", "elapsed", ("❌", 0.70, "⚠️", 0.85, "✅", 1.15, "💡", 1.30, "⭐")),
+)
+
+badgeLegend = [
+    ("❌", "Likely regression"),
+    ("⚠️", "Possible regression"),
+    ("✅", "Within acceptable range"),
+    ("💡", "Possible improvement"),
+    ("⭐", "Likely improvement"),
+]
+# fmt: on
+
+changedCycles = []
+table = []
+badgesToExplain = set()
+
+for ref, cmp in zip(sys.argv[1::2], sys.argv[2::2]):
+    with open(ref, "r", encoding="utf-8") as f:
+        ref_json = json.load(f)[0]
+    with open(cmp, "r", encoding="utf-8") as f:
+        cmp_json = json.load(f)
+    if table:
+        table.append(tabulate.SEPARATING_LINE)
+    runName = ref_json["runName"]
+
+    # Check simulated cycles match - it's ok to crash if this entry does not exist
+    for entry in cmp_json["execute"]["clocks"]["table"]:
+        case, _, _, (refCycles, _), (newCycles, _), _, _ = entry
+        refCycles = int(refCycles)
+        newCycles = int(newCycles)
+        if refCycles != newCycles:
+            changedCycles.append([runName, case, refCycles, newCycles])
+
+    # Check metrics
+    for step, metric, brackets in stepMetric:
+        if step not in cmp_json:
+            continue
+        data = cmp_json[step]
+        if metric not in data:
+            continue
+        data = data[metric]
+        minGain = float("inf")
+        maxGain = float("-inf")
+        meanGain = 1
+        count = 0
+        for _, _, _, (a, _), (b, _), g, _ in data["table"]:
+            # for wall clock and CPU time, ignore small values that just add noise
+            if metric == "elapsed" or metric == "cpu":
+                if a < 30 or b < 30:
+                    continue
+            minGain = min(minGain, g)
+            maxGain = max(maxGain, g)
+            meanGain *= g
+            count += 1
+        if count == 0:
+            continue
+        meanGain = meanGain**(1 / count)
+
+        status = brackets[0]
+        for limit, badge in zip(brackets[1::2], brackets[2::2]):
+            if meanGain >= limit:
+                status = badge
+        badgesToExplain.add(status)
+
+        table.append([
+            runName, step, ref_json["metrics"][metric]["header"], f"{meanGain:.2f}x  {status} ",
+            f"{minGain:.2f}x", f"{maxGain:.2f}x", f"{count}"
+        ])
+
+# Print changed cycles if any
+if changedCycles:
+    print("❌ simulated cycles changed (must be fixed):")
+    printTable(changedCycles,
+               headers=("Run", "Case", "Old Cycles", "New Cycles"),
+               colalign=("left", "left", "right", "right"),
+               disable_numparse=True)
+    print()
+
+# Print results
+printTable(
+    table,
+    headers=("Run", "Step", "Metric", "Improvement", "Min", "Max", "Samples"),
+    colalign=("left", "left", "left", "right", "right", "right", "right"),
+    disable_numparse=True,
+)
+
+# Explain badges
+print()
+for badge, legend in badgeLegend:
+    if badge in badgesToExplain:
+        print(f"  {badge} : {legend}")
+
+# Fail job if status changed
+sys.exit(0 if not changedCycles else 1)
@@ -1,208 +0,0 @@
-#!/usr/bin/env bash
-# DESCRIPTION: Verilator: CI main job script
-#
-# SPDX-FileCopyrightText: 2020 Geza Lore
-# 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)
-  # Disable ccache, doesn't always work in GitHub Actions
-  export OBJCACHE=
-elif [ "$CI_OS_NAME" = "freebsd" ]; then
-  export MAKE=gmake
-  NPROC=$(sysctl -n hw.ncpu)
-else
-  fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
-fi
-NPROC=$(expr $NPROC '+' 1)
-
-if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
-  ##############################################################################
-  # Build verilator
-
-  autoconf
-  CONFIGURE_ARGS="--enable-longtests --enable-ccwarn"
-  if [ "$CI_DEV_ASAN" = 1 ]; then
-    CONFIGURE_ARGS="$CONFIGURE_ARGS --enable-dev-asan"
-    CXX="$CXX -DVL_LEAK_CHECKS"
-  fi
-  if [ "$CI_DEV_GCOV" = 1 ]; then
-    CONFIGURE_ARGS="$CONFIGURE_ARGS --enable-dev-gcov"
-  fi
-  ./configure $CONFIGURE_ARGS --prefix="$INSTALL_DIR"
-  ccache -z
-  "$MAKE" -j "$NPROC" -k
-  # 22.04: ccache -s -v
-  ccache -s
-  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
-elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
-  ##############################################################################
-  # Run tests
-
-  export VERILATOR_TEST_NO_CONTRIBUTORS=1  # Separate workflow check
-  export VERILATOR_TEST_NO_LINT_PY=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
-    # TODO below may no longer be required as configure checks for -pg
-    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
-    # TODO below may no longer be required as configure checks for -pg
-    export VERILATOR_TEST_NO_GPROF=1 # gprof is a bit different on FreeBSD, disable
-  fi
-
-  TEST_REGRESS=test_regress
-  if [ "$CI_RELOC" == 1 ]; then
-    # Testing that the installation is relocatable.
-    "$MAKE" install
-    mkdir -p "$RELOC_DIR"
-    mv "$INSTALL_DIR" "$RELOC_DIR/relocated-install"
-    export VERILATOR_ROOT="$RELOC_DIR/relocated-install/share/verilator"
-    TEST_REGRESS="$RELOC_DIR/test_regress"
-    mv test_regress "$TEST_REGRESS"
-    NODIST="$RELOC_DIR/nodist"
-    mv nodist "$NODIST"
-    # Feeling brave?
-    find . -delete
-    ls -la .
-  fi
-
-  # Run the specified test
-  ccache -z
-  case $TESTS in
-    dist-vlt-0)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=0/4
-      ;;
-    dist-vlt-1)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=1/4
-      ;;
-    dist-vlt-2)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=2/4
-      ;;
-    dist-vlt-3)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=3/4
-      ;;
-    vltmt-0)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt --driver-clean" DRIVER_HASHSET=--hashset=0/3
-      ;;
-    vltmt-1)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt --driver-clean" DRIVER_HASHSET=--hashset=1/3
-      ;;
-    vltmt-2)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt --driver-clean" DRIVER_HASHSET=--hashset=2/3
-      ;;
-    coverage-dist)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist"
-      ;;
-    coverage-vlt-0)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=0/10
-      ;;
-    coverage-vlt-1)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=1/10
-      ;;
-    coverage-vlt-2)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=2/10
-      ;;
-    coverage-vlt-3)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=3/10
-      ;;
-    coverage-vlt-4)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=4/10
-      ;;
-    coverage-vlt-5)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=5/10
-      ;;
-    coverage-vlt-6)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=6/10
-      ;;
-    coverage-vlt-7)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=7/10
-      ;;
-    coverage-vlt-8)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=8/10
-      ;;
-    coverage-vlt-9)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=9/10
-      ;;
-    coverage-vltmt-0)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=0/10
-      ;;
-    coverage-vltmt-1)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=1/10
-      ;;
-    coverage-vltmt-2)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=2/10
-      ;;
-    coverage-vltmt-3)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=3/10
-      ;;
-    coverage-vltmt-4)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=4/10
-      ;;
-    coverage-vltmt-5)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=5/10
-      ;;
-    coverage-vltmt-6)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=6/10
-      ;;
-    coverage-vltmt-7)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=7/10
-      ;;
-    coverage-vltmt-8)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=8/10
-      ;;
-    coverage-vltmt-9)
-      "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=9/10
-      ;;
-    *)
-      fatal "Unknown TESTS: $TESTS"
-      ;;
-  esac
-
-  # To see load average (1 minute, 5 minute, 15 minute)
-  uptime
-  # 22.04: ccache -s -v
-  ccache -s
-
-else
-  ##############################################################################
-  # Unknown build stage
-  fatal "Unknown CI_BUILD_STAGE_NAME: '$CI_BUILD_STAGE_NAME'"
-fi
@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+# DESCRIPTION: Verilator: CI test job script
+#
+# SPDX-FileCopyrightText: 2026 Wilson Snyder
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+################################################################################
+# Executed in the 'test' stage.
+################################################################################
+
+# Destructive to the checkout (wipes most of it); never run locally
+if [ "$GITHUB_ACTIONS" != "true" ]; then
+  echo "ERROR: $(basename "$0") must only be run in GitHub Actions CI" >&2
+  exit 1
+fi
+
+set -e
+set -x
+
+source "$(dirname "$0")/ci-common.bash"
+
+################################################################################
+# Parse arguments
+
+OPT_RELOC=
+OPT_SUITE=
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --reloc)
+      [ $# -ge 2 ] || fatal "--reloc requires an argument"
+      OPT_RELOC="$2"
+      shift
+      ;;
+    --suite)
+      [ $# -ge 2 ] || fatal "--suite requires an argument"
+      OPT_SUITE="$2"
+      shift
+      ;;
+    *) fatal "Unknown option: '$1'" ;;
+  esac
+  shift
+done
+
+[ -n "$OPT_SUITE" ] || fatal "--suite is required"
+
+################################################################################
+# Run tests
+
+export VERILATOR_TEST_NO_CONTRIBUTORS=1  # Separate workflow check
+export VERILATOR_TEST_NO_LINT_PY=1  # Separate workflow check
+
+if [ "$HOST_OS" = "macOS" ]; then
+  export VERILATOR_TEST_NO_GDB=1  # No working GDB on macOS
+fi
+
+TEST_REGRESS=test_regress
+if [ -n "$OPT_RELOC" ]; then
+  # Testing that the installation is relocatable.
+  "$MAKE" install
+  # Install prefix, as configured into the Makefile at build time
+  INSTALL_DIR=$(sed -n 's/^prefix = //p' Makefile)
+  mkdir -p "$OPT_RELOC"
+  mv "$INSTALL_DIR" "$OPT_RELOC/relocated-install"
+  export VERILATOR_ROOT="$OPT_RELOC/relocated-install/share/verilator"
+  TEST_REGRESS="$OPT_RELOC/test_regress"
+  mv test_regress "$TEST_REGRESS"
+  NODIST="$OPT_RELOC/nodist"
+  mv nodist "$NODIST"
+  # Delete everything else, but keep the CI infrastructure
+  find . -mindepth 1 -maxdepth 1 ! -name .github ! -name ci -exec rm -rf {} +
+  ls -la .
+fi
+
+# Run the specified suite
+ccache -z
+TEST_START=$SECONDS
+case $OPT_SUITE in
+  dist-vlt-0)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=0/4
+    ;;
+  dist-vlt-1)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=1/4
+    ;;
+  dist-vlt-2)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=2/4
+    ;;
+  dist-vlt-3)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist --vlt --driver-clean" DRIVER_HASHSET=--hashset=3/4
+    ;;
+  vltmt-0)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt --driver-clean" DRIVER_HASHSET=--hashset=0/3
+    ;;
+  vltmt-1)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt --driver-clean" DRIVER_HASHSET=--hashset=1/3
+    ;;
+  vltmt-2)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt --driver-clean" DRIVER_HASHSET=--hashset=2/3
+    ;;
+  coverage-dist)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--dist"
+    ;;
+  coverage-vlt-0)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=0/10
+    ;;
+  coverage-vlt-1)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=1/10
+    ;;
+  coverage-vlt-2)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=2/10
+    ;;
+  coverage-vlt-3)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=3/10
+    ;;
+  coverage-vlt-4)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=4/10
+    ;;
+  coverage-vlt-5)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=5/10
+    ;;
+  coverage-vlt-6)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=6/10
+    ;;
+  coverage-vlt-7)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=7/10
+    ;;
+  coverage-vlt-8)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=8/10
+    ;;
+  coverage-vlt-9)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vlt" DRIVER_HASHSET=--hashset=9/10
+    ;;
+  coverage-vltmt-0)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=0/10
+    ;;
+  coverage-vltmt-1)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=1/10
+    ;;
+  coverage-vltmt-2)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=2/10
+    ;;
+  coverage-vltmt-3)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=3/10
+    ;;
+  coverage-vltmt-4)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=4/10
+    ;;
+  coverage-vltmt-5)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=5/10
+    ;;
+  coverage-vltmt-6)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=6/10
+    ;;
+  coverage-vltmt-7)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=7/10
+    ;;
+  coverage-vltmt-8)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=8/10
+    ;;
+  coverage-vltmt-9)
+    "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=9/10
+    ;;
+  *)
+    fatal "Unknown suite: $OPT_SUITE"
+    ;;
+esac
+ccache -svv
+ccache --evict-older-than "$((SECONDS - TEST_START + 60))s"
+ccache -svv
+uptime # To see load average
@@ -6,19 +6,33 @@

 Set-PSDebug -Trace 1

-if (-Not (Test-Path $PWD/../.ccache/win_bison.exe)) {
+$NPROC = $env:NUMBER_OF_PROCESSORS
+
+# Absolute path for the win_flex_bison install; CMake reads this from the environment
+$env:WIN_FLEX_BISON = "$(Resolve-Path ..)/win_flex_bison"
+
+if (-Not (Test-Path $env:WIN_FLEX_BISON/win_bison.exe)) {
    git clone --depth 1 https://github.com/lexxmark/winflexbison
    cd winflexbison
    mkdir build
    cd build
-    cmake .. --install-prefix $PWD/../../../.ccache
-    cmake --build . --config Release -j 3
-    cmake --install . --prefix $PWD/../../../.ccache
+    cmake .. --install-prefix $env:WIN_FLEX_BISON
+    cmake --build . --config Release -j $NPROC
+    cmake --install . --prefix $env:WIN_FLEX_BISON
    cd ../..
 }

+# Enter the MSVC developer shell so cl/link are on PATH for the Ninja generator
+$VsPath = & "${env:ProgramFiles(x86)}/Microsoft Visual Studio/Installer/vswhere.exe" -latest -products * -property installationPath
+Import-Module "$VsPath/Common7/Tools/Microsoft.VisualStudio.DevShell.dll"
+Enter-VsDevShell -VsInstallPath $VsPath -SkipAutomaticLocation -DevCmdArguments "-arch=x64 -host_arch=x64"
+
 mkdir build
 cd build
-cmake .. --install-prefix $PWD/../install
-cmake --build . --config Release -j 3
+# Ninja saturates all cores; the MSBuild generator only parallelizes across
+# projects and Verilator is a single target, so it compiles serially. /Od skips
+# optimization: this job only checks that Verilator builds and can verilate an
+# example, so an optimized binary is not needed and the codegen time dominates.
+cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release --install-prefix $PWD/../install "-DCMAKE_CXX_FLAGS_RELEASE=/Od /DNDEBUG"
+cmake --build .
 cmake --install . --prefix $PWD/../install
@@ -7,13 +7,17 @@

 Set-PSDebug -Trace 1

+$NPROC = $env:NUMBER_OF_PROCESSORS
+
 cd install
 $Env:VERILATOR_ROOT=$PWD
 cd examples/cmake_tracing_c
 mkdir build
 cd build
-cmake ..
-cmake --build . --config Release -j 3
+# /Od skips optimization; this only checks the example verilates and builds, so
+# an optimized binary is not needed (see ci-win-compile.ps1).
+cmake .. "-DCMAKE_CXX_FLAGS_RELEASE=/Od /DNDEBUG"
+cmake --build . --config Release -j $NPROC

 # TODO put this back in, see issue# 5163
 # Release/example.exe
@@ -53,10 +53,14 @@ RUN apt-get update \

 WORKDIR /tmp

-RUN git clone https://github.com/veripool/vcddiff.git && \
-    make -C vcddiff && \
-    cp -p vcddiff/vcddiff /usr/local/bin/vcddiff && \
-    rm -rf vcddiff
+COPY wavetools.conf /tmp/wavetools.conf
+ARG WGET_EXTRA_ARGS=
+RUN . /tmp/wavetools.conf && \
+    wget -q ${WGET_EXTRA_ARGS} -O /tmp/wavetools.tar.gz \
+    "https://github.com/hudson-trading/wavetools/releases/download/${WAVETOOLS_VERSION}/wavetools-${WAVETOOLS_VERSION}-linux-x86_64.tar.gz" && \
+    tar -xzf /tmp/wavetools.tar.gz -C /tmp && \
+    cp -p /tmp/wavetools-${WAVETOOLS_VERSION}-linux-x86_64/wavediff /usr/local/bin/wavediff && \
+    rm -rf /tmp/wavetools.tar.gz /tmp/wavetools-* /tmp/wavetools.conf

 COPY build.sh /tmp/build.sh

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _verilator build docker container:

@@ -0,0 +1 @@
+WAVETOOLS_VERSION=v0.1.2
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 Verilator Executable Docker Container
 =====================================
@@ -12,7 +12,7 @@
 # Then 'make maintainer-dist'
 #AC_INIT([Verilator],[#.### YYYY-MM-DD])
 #AC_INIT([Verilator],[#.### devel])
-AC_INIT([Verilator],[5.047 devel],
+AC_INIT([Verilator],[5.052 2026-09-05],
        [https://verilator.org],
        [verilator],[https://verilator.org])

@@ -129,6 +129,21 @@ AC_ARG_ENABLE([dev-gcov],
 AC_SUBST(CFG_WITH_DEV_GCOV)
 AC_MSG_RESULT($CFG_WITH_DEV_GCOV)

+# Flag to reduce the debug info in the debug executable to minimize its size
+AC_MSG_CHECKING(whether to reduce debug info in the debug executable)
+AC_ARG_ENABLE([light-debug],
+              [AS_HELP_STRING([--enable-light-debug],
+                              [Reduce the amount of debug information in the debug
+                               Verilator executable to minimize its size. Enable
+                               slight optimization. Enough for backtraces only.])],
+              [case "${enableval}" in
+                yes) CFG_WITH_LIGHT_DEBUG=yes ;;
+                no)  CFG_WITH_LIGHT_DEBUG=no ;;
+                *)   AC_MSG_ERROR([bad value '${enableval}' for --enable-light-debug]) ;;
+               esac],
+               CFG_WITH_LIGHT_DEBUG=no)
+AC_MSG_RESULT($CFG_WITH_LIGHT_DEBUG)
+
 # Special Substitutions - CFG_WITH_DEFENV
 AC_MSG_CHECKING(whether to use hardcoded paths)
 AC_ARG_ENABLE([defenv],
@@ -421,8 +436,18 @@ AC_DEFUN([_MY_LDLIBS_CHECK_OPT],
    _MY_LDLIBS_CHECK_IFELSE($2, $1="$$1 $2")
   ])

+AC_DEFUN([_MY_LDLIBS_CHECK_SET],
+   [# _MY_LDLIBS_CHECK_SET(variable, flag) -- Check if linker supports specific
+    # options. If it does, set variable to flag, only if not previously set
+    # (so the first supported flag wins and the rest are not tested).
+    if test "$$1" = ""; then
+       _MY_LDLIBS_CHECK_IFELSE($2, $1="$2")
+    fi
+   ])
+
 # Add the coverage flags early as they influence later checks.
 if test "$CFG_WITH_DEV_GCOV" = "yes"; then
+  CFG_GCOV_CXX="$CXX"
  _MY_CXX_CHECK_OPT(CXX,--coverage)
  # Otherwise inline may not show as uncovered
  #  If we use this then e.g. verilated.h functions properly show up
@@ -444,8 +469,32 @@ if test "$CFG_WITH_DEV_GCOV" = "yes"; then
  _MY_CXX_CHECK_OPT(CXX,-fprofile-abs-path)
  # Define so compiled code can know
  _MY_CXX_CHECK_OPT(CXX,-DVL_GCOV)
-  AC_DEFINE([HAVE_DEV_GCOV],[1],[Defined if compiled with code coverage collection for gcov])]
+  AC_DEFINE([HAVE_DEV_GCOV],[1],[Defined if compiled with code coverage collection for gcov])
+  if test "x$GCOV" = "x"; then GCOV=gcov; fi
+  AC_MSG_CHECKING([whether $GCOV reads coverage data from $CFG_GCOV_CXX])
+  CFG_GCOV_DIR=conftest.gcov.dir
+  rm -rf $CFG_GCOV_DIR
+  AS_MKDIR_P([$CFG_GCOV_DIR])
+  echo 'int main() { return 0; }' > $CFG_GCOV_DIR/conftest_gcov.cpp
+  CFG_GCOV_RES=no
+  if (cd $CFG_GCOV_DIR \
+      && $CFG_GCOV_CXX --coverage -o conftest_gcov conftest_gcov.cpp \
+      && ./conftest_gcov) >/dev/null 2>&1; then
+    (cd $CFG_GCOV_DIR && $GCOV conftest_gcov.gcda) >/dev/null 2>&1
+    if test -s $CFG_GCOV_DIR/conftest_gcov.cpp.gcov; then CFG_GCOV_RES=yes; fi
+  else
+    CFG_GCOV_RES=untested
+  fi
+  rm -rf $CFG_GCOV_DIR
+  AC_MSG_RESULT($CFG_GCOV_RES)
+  if test "$CFG_GCOV_RES" = "no"; then
+    AC_MSG_ERROR(['$GCOV' cannot read coverage data written by '$CFG_GCOV_CXX'.
+  Coverage collection would silently produce no data.
+  Pass a matching tool, e.g. GCOV=gcov-<version>
+  or configure without --enable-dev-gcov.])
+  fi
 fi
+AC_SUBST(GCOV)
 AC_SUBST(HAVE_DEV_GCOV)

 # Compiler flags to enable profiling
@@ -483,6 +532,11 @@ _MY_CXX_CHECK_CORO_SET(CFG_CXXFLAGS_COROUTINES,-std=gnu++20)
 AC_SUBST(CFG_CXXFLAGS_COROUTINES)
 AC_SUBST(HAVE_COROUTINES)

+# Check if the C++ compiler supports ThreadSanitizer
+_MY_CXX_CHECK_IFELSE(-fsanitize=thread,
+  [AC_DEFINE([HAVE_TSAN],[1],[Defined if ThreadSanitizer is supported by $CXX])])
+AC_SUBST(HAVE_TSAN)
+
 # Flags for compiling Verilator internals including parser always
 if test "$CFG_WITH_DEV_ASAN" = "yes"; then
  _MY_CXX_CHECK_IFELSE(-fsanitize=address -DVL_ASAN,
@@ -509,15 +563,27 @@ _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_PARSER,-Wno-unused)
 AC_SUBST(CFG_CXXFLAGS_PARSER)

 # Flags for compiling the debug version of Verilator (in addition to above CFG_CXXFLAGS_SRC)
-if test "$CFG_WITH_DEV_GCOV" = "no"; then # Do not optimize for the coverage build
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-Og)
+if test "$CFG_WITH_LIGHT_DEBUG" = "yes"; then
+  # Slight optimization and minimal compressed debug info. This is enough for
+  # --gdb/--gdbbt backtraces, but omits the bulk of the debug info, which
+  # significantly reduces object file sizes. For CI or release builds.
+  if test "$CFG_WITH_DEV_GCOV" = "no"; then # Do not optimize for the coverage build
+    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-Og)
+  fi
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-ggdb1)
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-fdebug-info-for-profiling) # For fully-qualified names with clang
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-gz)
+else
+  # Full debug: no optimization, full debug info, for development.
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-O0)
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-ggdb)
 fi
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-ggdb)
-_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_DBG,-gz)
 AC_SUBST(CFG_CXXFLAGS_DBG)

 # Flags for linking the debug version of Verilator (in addition to above CFG_LDFLAGS_SRC)
-_MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_DBG,-gz)
+if test "$CFG_WITH_LIGHT_DEBUG" = "yes"; then
+  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_DBG,-gz)
+fi
 AC_SUBST(CFG_LDFLAGS_DBG)

 # Flags for compiling the optimized version of Verilator (in addition to above CFG_CXXFLAGS_SRC)
@@ -580,6 +646,34 @@ m4_foreach([ldflag], [
 AC_SUBST(CFG_LDLIBS_THREADS)
 AC_SUBST(CFG_LDFLAGS_THREADS_CMAKE)

+# Find link flags for runtime VPI library loading (+verilator+vpi+<lib>).
+# The model executable must export its VPI symbols so the dlopen'd library can
+# resolve them: -rdynamic (GNU ld) or -Wl,-export_dynamic (Darwin); the first the
+# linker accepts wins.  -ldl provides dlopen/dlsym where it is a separate library.
+_MY_LDLIBS_CHECK_SET(CFG_LDFLAGS_DYNAMIC, -rdynamic)
+# -Wl,-export_dynamic contains a comma, so probe it directly rather than through
+# the _MY_LDLIBS_CHECK_* macros (which re-expand their flag argument unquoted).
+if test "$CFG_LDFLAGS_DYNAMIC" = ""; then
+  ACO_SAVE_LIBS="$LIBS"
+  LIBS="$LIBS -Wl,-export_dynamic"
+  AC_MSG_CHECKING([whether $CXX linker accepts -Wl,-export_dynamic])
+  AC_LINK_IFELSE(
+       [AC_LANG_PROGRAM([[]])],
+       [_my_result=yes
+        if test -s conftest.err; then
+          if grep -e "-export_dynamic" conftest.err >/dev/null; then
+            _my_result=no
+          fi
+        fi],
+       [_my_result=no])
+  AC_MSG_RESULT($_my_result)
+  LIBS="$ACO_SAVE_LIBS"
+  if test "$_my_result" = "yes"; then CFG_LDFLAGS_DYNAMIC="-Wl,-export_dynamic"; fi
+fi
+AC_SUBST(CFG_LDFLAGS_DYNAMIC)
+_MY_LDLIBS_CHECK_OPT(CFG_LDLIBS_DYNAMIC, -ldl)
+AC_SUBST(CFG_LDLIBS_DYNAMIC)
+
 # If 'mold' is installed, use it to link for faster buildtimes
 _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -fuse-ld=mold)
 _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_VERILATED, -fuse-ld=mold)
@@ -589,11 +683,6 @@ if test "$CFG_ENABLE_PARTIAL_STATIC" = "yes"; then
  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -static-libgcc)
  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -static-libstdc++)
  _MY_LDLIBS_CHECK_OPT(CFG_LDFLAGS_SRC, -Xlinker -gc-sections)
-  LTCMALLOC="-Wl,--whole-archive -l:libtcmalloc_minimal.a -Wl,--no-whole-archive"
-  LJEMALLOC="-Wl,--whole-archive -l:libjemalloc.a -Wl,--no-whole-archive"
-else
-  LTCMALLOC=-ltcmalloc_minimal
-  LJEMALLOC=-ljemalloc
 fi
 AC_SUBST(CFG_LDFLAGS_SRC)
 AC_SUBST(CFG_LDFLAGS_VERILATED)
@@ -609,51 +698,56 @@ _MY_LDLIBS_CHECK_OPT(CFG_LIBS, -latomic)
 _MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lbcrypt)
 _MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lpsapi)

-# Check if jemalloc is available based on --enable-jemalloc
-# jemalloc is preferred over tcmalloc when both are available
+# Figure out which malloc library to use:
+# - Prefer jemalloc over tcmalloc (it's faster)
+# - If partial static link enabled, prefer static libraries,
+#   but fall back on dynamic if static is not available
+
+# Test for jemalloc
 CFG_HAVE_JEMALLOC=no
-_MY_LDLIBS_CHECK_IFELSE(
-  $LJEMALLOC,
-  [if test "$CFG_WITH_JEMALLOC" != "no"; then
-    CFG_LIBS="$LJEMALLOC $CFG_LIBS";
-    CFG_HAVE_JEMALLOC=yes;
-    # If using jemalloc, add some extra options to make the compiler not assume
-    # it is using its own versions of the standard library functions
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-malloc)
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-calloc)
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-realloc)
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-free)
+if test "$CFG_WITH_JEMALLOC" != "no"; then
+  if test "$CFG_ENABLE_PARTIAL_STATIC" = "yes"; then
+    _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -Xlinker --whole-archive -l:libjemalloc.a -Xlinker --no-whole-archive)
+  fi
+  _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -ljemalloc)
+  if test "$CFG_LIBS_MALLOC" != ""; then
+    CFG_HAVE_JEMALLOC=yes
    AC_DEFINE([HAVE_JEMALLOC],[1],[Defined if have jemalloc])
-   fi],
-  [if test "$CFG_WITH_JEMALLOC" = "yes"; then
-    AC_MSG_ERROR([--enable-jemalloc was given but test for ${LJEMALLOC} failed])
-   fi])
+  elif test "$CFG_WITH_JEMALLOC" = "yes"; then
+    AC_MSG_ERROR([--enable-jemalloc was given but jemalloc is not available])
+  fi
+fi
 AC_SUBST(HAVE_JEMALLOC)

-# Check if tcmalloc is available based on --enable-tcmalloc
-# Only use tcmalloc if jemalloc was not found/enabled
-if test "$CFG_HAVE_JEMALLOC" = "yes"; then
-  AC_MSG_NOTICE([jemalloc found, skipping tcmalloc check])
-else
+# Test for tcmalloc
 CFG_HAVE_TCMALLOC=no
-_MY_LDLIBS_CHECK_IFELSE(
-  $LTCMALLOC,
-  [if test "$CFG_WITH_TCMALLOC" != "no"; then
-    CFG_LIBS="$LTCMALLOC $CFG_LIBS";
-    CFG_HAVE_TCMALLOC=yes;
-    # If using tcmalloc, add some extra options to make the compiler not assume
-    # it is using its own versions of the standard library functions
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-malloc)
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-calloc)
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-realloc)
-    _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-free)
+if test "$CFG_HAVE_JEMALLOC" = "yes"; then
+  AC_MSG_NOTICE([jemalloc found, skipping check for tcmalloc])
+elif test "$CFG_WITH_TCMALLOC" != "no"; then
+  if test "$CFG_ENABLE_PARTIAL_STATIC" = "yes"; then
+    _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -Xlinker --whole-archive -l:libtcmalloc_minimal.a -Xlinker --no-whole-archive)
+  fi
+  _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -ltcmalloc_minimal)
+  if test "$CFG_LIBS_MALLOC" != ""; then
+    CFG_HAVE_TCMALLOC=yes
    AC_DEFINE([HAVE_TCMALLOC],[1],[Defined if have tcmalloc])
-   fi],
-  [if test "$CFG_WITH_TCMALLOC" = "yes"; then
-    AC_MSG_ERROR([--enable-tcmalloc was given but test for ${LTCMALLOC} failed])
-   fi])
+  elif test "$CFG_WITH_TCMALLOC" = "yes"; then
+    AC_MSG_ERROR([--enable-tcmalloc was given but tcmalloc is not available])
+  fi
 fi
 AC_SUBST(HAVE_TCMALLOC)
+
+if test "$CFG_HAVE_JEMALLOC" = "yes" || test "$CFG_HAVE_TCMALLOC" = "yes"; then
+  # If using custom malloc, add some extra options to make the compiler not assume
+  # it is using its own versions of the standard library functions
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-malloc)
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-calloc)
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-realloc)
+  _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-fno-builtin-free)
+fi
+
+# Finished with libraries
+CFG_LIBS="$CFG_LIBS_MALLOC $CFG_LIBS"
 AC_SUBST(CFG_LIBS)

 # Need C++14 at least
@@ -0,0 +1,38 @@
+<!-- DESCRIPTION: Verilator: docs/ guidelines for AI coding agents
+     SPDX-FileCopyrightText: 2026-2026 Wilson Snyder
+     SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -->
+
+# docs/ Guidelines -- Verilator documentation (\*.rst)
+
+When to check: before editing anything under `docs/`.
+Read the repository-root [AGENTS.md](../AGENTS.md) first for process and cross-cutting rules.
+
+## Writing rules
+
+- Rewrap paragraphs after editing -- keep consistent line length in `*.rst` files.
+
+- Document only stable, implemented features -- never planned or in-development capabilities; prevents user confusion and support burden.
+
+- Explain WHAT and WHEN, not HOW -- conceptual purpose and practical use cases over implementation mechanics; describe behavior ("optimized as pure", not "treated as pure") and clarify ambiguous referents ("in the internals of Verilator").
+
+- Keep terminology consistent -- one term per concept; update docs when renaming code constructs; spell out full terms, avoiding abbreviations like "sim"/"sims".
+
+- Use "how many" for countable nouns (threads, tasks, workers) and "how much" for uncountable quantities.
+
+- Mark internal or experimental features "for internal use only" -- prevents user dependence and forced deprecation cycles later.
+
+- Use specific IEEE references: `IEEE {number}-{year}` plus the section (e.g. `Annex I`) -- a vague "IEEE spec requires" is unverifiable.
+
+- Document all flags with descriptions, not just syntax.
+
+## reStructuredText mechanics
+
+- Use the `:vlopt:` role for Verilator option references -- makes cross-references clickable and consistent.
+
+- Escape angle brackets (`\<`, `\>`) in link targets -- prevents broken links to command-line options.
+
+- Generate documentation examples with `test.extract` from `test_regress` test files -- examples stay synced with actually tested behavior.
+
+## Hard constraint
+
+- Never edit `docs/CONTRIBUTORS` -- only humans may, after reading and agreeing to its statement; remind the user instead.
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 Contributing to Verilator
 =========================
@@ -86,12 +87,44 @@ Do you have questions on Verilator?
  <https://verilator.org/forum>`__.


+AI Policy
+---------
+
+Verilator follows the Linux Foundation recommendations regarding the usage
+of Generative Large Language Model Artificial Intelligence (LLM-AI) tools
+and agents for all contributions to the project, including source code,
+test benches, and documentation.
+
+AI assistants and automated agents are not permitted to sign off on
+contributions. A human submitter is strictly responsible for reviewing,
+verifying, and testing all AI-generated content. By submitting, the
+contributor certifies that the generated content is effectively their work
+product and adheres to project standards. This accountability is affirmed
+when the human contributor signs the Developer Certificate of Origin (DCO)
+as outlined in ``docs/CONTRIBUTORS``.
+
+Contributors are encouraged to disclose the significant use of generative
+AI tools in their commit messages or Pull Request descriptions to maintain
+transparency.
+
+Contributors must ensure that the terms and conditions of the generative AI
+tool do not place any contractual restrictions on the tool's output that
+are inconsistent with Verilator's open-source licenses, the project's
+intellectual property policies, or the Open Source Definition.
+
+If any pre-existing copyrighted materials (including third-party
+open-source code or documentation) are included in the AI tool's output,
+the contributor must confirm prior to submission that they have explicit
+permission from the third-party owners to use, modify, and distribute those
+materials under terms compliant with Verilator's licensing policies.
+
+
 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/>`__.
+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!
@@ -1,14 +1,22 @@
 The contributors listed below have certified their Verilator contributions
-under the Developer Certificate of Origin (https://developercertificate.org/).
+under the Developer Certificate of Origin
+(https://developercertificate.org/).
+
+AI agents may not edit this file. As a human, you are agreeing to the
+contribution terms including the AI policy in ``docs/CONTRIBUTING.rst``.

 Please see the Verilator manual for 200+ additional contributors. Thanks to all.

+24bit-xjkp
 404allen404
 Adam Bagley
+Adam Kostrzewski
+Aditya Shevade
 Adrian Sampson
 Adrien Le Masle
 أحمد المحمودي (Ahmed El-Mahmoudy)
 Aidan McNay
+Aisha Salimgereyeva
 Aleksander Kiryk
 Alex Chadwick
 Alex Solomatnikov
@@ -21,14 +29,20 @@ Andrei Kostovski
 Andrew Miloradovsky
 Andrew Nolte
 Andrew Voznytsa
+Andrii Andrieiev
+anonkey
 Anthony Donlon
 Anthony Moore
+apocelipes
 Arkadiusz Kozdra
 Arthur Rosa
 Artur Bieniek
 AUDIY
 Aylon Chaim Porat
+Bartosz Skorowski
 Bartłomiej Chmiel
+Benjamin Collier
+BRDR LIFE
 Brian Li
 Cameron Kirk
 Cameron Waite
@@ -41,30 +55,41 @@ Chuxuan Wang
 Chykon
 Congcong Cai
 Conor McCullough
+Cookie
 Dan Ruelas-Petrisko
 Daniel Bates
 Danny Oler
 Dave Sargeant
+David Garau
 David Horton
 David Ledger
 David Metz
 David Stanford
 David Turner
+dependabot[bot]
 Dercury
+Demin Han
 Diego Roux
 Dominick Grochowina
 Don Williamson
+Dragon-Git
 Drew Ranck
 Drew Taussig
 Driss Hafdi
 Edgar E. Iglesias
+Eddie Rydell
+em2machine
+emmettifelts
+Eric Mejdrich
 Eric Müller
 Eric Rippey
-Eunseo Song
+Eryk Szpotański
 Ethan Sifferman
+Eunseo Song
 Eyck Jentzsch
 Fabian Keßler-Schulz
 Fan Shupei
+february cozzocrea
 Felix Neumärker
 Felix Yan
 Frans Skarman
@@ -87,6 +112,7 @@ Gökçe Aydos
 Han Qi
 Harald Heckmann
 Hennadii Chernyshchyk
+hjsanjana
 Howard Su
 Huang Rui
 Huanghuang Zhou
@@ -98,6 +124,8 @@ Ilya Barkov
 Iru Cai
 Ivan Vnučec
 Iztok Jeras
+JAEUK LEE
+Jaeuk Lee (이재욱)
 Jake Merdich
 Jakub Michalski
 Jakub Wasilewski
@@ -112,6 +140,8 @@ Jamie Iles
 Jan Van Winkel
 Jean Berniolles
 Jean-Nicolas Strauss
+Jeffrey Song
+jeffrey.song
 Jens Yuechao Liu
 Jeremy Bennett
 Jesse Taube
@@ -136,6 +166,8 @@ Jose Loyola
 Josep Sans
 Joseph Nwabueze
 Josh Redford
+Joshua Leahy
+JOTEGO (Jose Tejada)
 Julian Carrier
 Julian Daube
 Julie Schwartz
@@ -149,6 +181,7 @@ Kefa Chen
 Keith Colbert
 Kevin Kiningham
 Kevin Nygaard
+Kornel Uriasz
 Kritik Bhimani
 Krzysztof Bieganski
 Krzysztof Boronski
@@ -159,15 +192,19 @@ Krzysztof Sychla
 Kuba Ober
 Lan Zongwei
 Larry Doolittle
+Laurent CHARRIER
 Leela Pakanati
 Liam Braun
 Luca Colagrande
+Lucas Amaral
 Ludwig Rogiers
 Lukasz Dalek
+M2kar
 Maarten De Braekeleer
 Maciej Sobkowski
 Marcel Chang
 Marco Bartoli
+Marco Brambilla
 Marco Widmer
 Mariusz Glebocki
 Markus Krause
@@ -183,28 +220,36 @@ Maxim Fonarev
 Michael Bedford Taylor
 Michael Bikovitsky
 Michael Killough
+Michael Rogenmoser
 Michal Czyz
 Michaël Lefebvre
+Miguel Perez Andrade
 Mike Popoloski
 Miodrag Milanović
 Mladen Slijepcevic
 Morten Borup Petersen
 Mostafa Gamal
 Moubarak Jeje
+Muzaffer Kal
 Nandu Raj
 Natan Kreimer
 Nathan Graybeal
 Nathan Kohagen
 Nathan Myers
 Nick Brereton
+Nikolai Kumar
 Nikolay Puzanov
 Nolan Poe
 Oleh Maksymenko
+Patrick Creighton
 Patrick Stewart
 Paul Bowen-Huggett
+Paul Campbell
+Paul Rigge
 Paul Swirhun
 Paul Wright
 Pawel Jewstafjew
+Pawel Klopotek
 Pawel Kojma
 Pawel Sagan
 Pengcheng Xu
@@ -234,29 +279,40 @@ Rowan Goemans
 Rupert Swarbrick
 Ryan Ziegler
 Ryszard Rozak
+Saksham Gupta
 Samuel Riedel
 Sean Cross
 Sebastien Van Cauwenberghe
+Secturion
+Sergey Chusov
 Sergey Fedorov
 Sergi Granell
 Seth Pellegrino
+Shashvat Prabhu
 Shogo Yamazaki
 Shou-Li Hsu
+spomatasmd
 Srinivasan Venkataramanan
 Stefan Wallentowitz
 Stephen Henry
 Steven Hugg
+Stuart Morris
+sumpster
 Szymon Gizler
 Sören Tempel
+Sumanth Kadiyala
 Teng Huang
 Thomas Aldrian
+Thomas Brown
 Thomas Dybdahl Ahle
+Thomas Santerre
 Tim Hutt
 Tim Snyder
 Tobias Jensen
 Tobias Rosenkranz
 Tobias Wölfel
 Todd Strader
+Tom Jackson
 Tom Manner
 Tomasz Gorochowik
 Topa Topino
@@ -265,6 +321,7 @@ Tracy Narine
 Trung Nguyen
 Tudor Timi
 Tymoteusz Blazejczyk
+Tyrone Marhguy
 Udaya Raj Subedi
 Udi Finkelstein
 Unai Martinez-Corral
@@ -278,12 +335,15 @@ Vito Gamberini
 Wei-Lun Chiu
 William D. Jones
 Wilson Snyder
+Wolfgang Mayerwieser
 Xi Zhang
 Yan Xu
 Yangyu Chen
+Yilin Li
 Yilou Wang
 Yinan Xu
 Yoda Lee
+Yogish Sekhar
 Yossi Nivin
 Yu-Sheng Lin
 Yuri Victorovich
@@ -294,11 +354,7 @@ Zhen Yan
 Zhou Shen
 Zhouyi Shen
 Zixi Li
-apocelipes
-dependabot[bot]
-february cozzocrea
-sumpster
-em2machine
-emmettifelts
+Zubin Jain
 Àlex Torregrosa
 Ícaro Lima
+Sunimali Rathnayake
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 Verilator Documentation
 =======================
@@ -2,4 +2,4 @@
 .. code-block::

   -V{t#,#}         'stl' region trigger index 0 is active: @([hybrid] a)
-   %Error-DIDNOTCONVERGE: t/t_lint_didnotconverge_bad.v:7: Settle region did not converge after '--converge-limit' of 10000 tries
+   %Error-DIDNOTCONVERGE: Settle region did not converge after '--converge-limit' of 10000 tries
@@ -1,4 +1,4 @@
 .. comment: generated by t_lint_didnotconverge_nodbg_bad
 .. code-block::

-   %Error-DIDNOTCONVERGE: t/t_lint_didnotconverge_bad.v:7: Settle region did not converge after '--converge-limit' of 10000 tries
+   %Error-DIDNOTCONVERGE: Settle region did not converge after '--converge-limit' of 10000 tries
@@ -0,0 +1,7 @@
+.. comment: generated by t_finaldly_bad
+.. code-block:: sv
+   :linenos:
+   :emphasize-lines: 2
+
+     bit foo;
+     final foo <= 1;  // <--- Error
@@ -0,0 +1,6 @@
+.. comment: generated by t_finaldly_bad
+.. code-block::
+
+   %Error-FINALDLY: example.v:1:13 Non-blocking assignment '<=' in final block
+       9 |   final foo <= 1;
+         |             ^~
@@ -0,0 +1,6 @@
+.. comment: generated by t_lint_multidriven_proc_bad
+.. code-block:: sv
+   :linenos:
+
+     always @(posedge clk) q <= d;
+     always @(posedge clk) q <= ~d;
@@ -0,0 +1,13 @@
+.. comment: generated by t_lint_multidriven_proc_bad
+.. code-block:: sv
+   :linenos:
+
+     integer i;
+
+     always @(posedge clk) begin
+       for (i = 0; i < 4; i = i + 1) q1[i] <= d[i];
+     end
+
+     always @(posedge clk) begin
+       for (i = 0; i < 4; i = i + 1) q2[i] <= ~d[i];
+     end
@@ -0,0 +1,8 @@
+.. comment: generated by t_lint_multidriven_proc_bad
+.. code-block::
+
+   %Warning-MULTIDRIVENPROC: example.v:1:25 Variable written to in always block also written by another always block: 'q'
+                                                                  : ... note: In instance 't.u1'
+                             example.v:1:25
+      54 |   always @(posedge clk) q <= ~d;
+         |                         ^
@@ -0,0 +1,12 @@
+.. code-block:: sv
+    :linenos:
+    :emphasize-lines: 3,6
+
+    module t(input logic clk, input logic d, output logic q);
+
+        initial q = 1'b0;  // <--- Warning
+
+        always_ff @(posedge clk) begin
+        q <= d;  // <--- Warning
+        end
+    endmodule
@@ -0,0 +1,7 @@
+.. comment: generated by t_lint_notredop_bad
+.. code-block::
+
+   %Error-NOTREDOP: example.v:1:17 Logical not directly before reduction operator is illegal
+                                                 : ... Suggest use parentheses, e.g. '!(|expr)'
+      12 |   assign y[0] = !|v;
+         |                 ^
@@ -0,0 +1,6 @@
+.. comment: generated by t_lint_similarname_bad
+.. code-block:: sv
+   :linenos:
+
+     reg i;
+     wire I;
@@ -0,0 +1,9 @@
+.. comment: generated by t_lint_similarname_bad
+.. code-block::
+
+   %Warning-SIMILARNAME: example.v:1:8 Declaration overlaps another with different case: 'I'
+      13 |   wire I;
+         |        ^
+                         example.v:1:7 ... Location of original declaration
+      12 |   reg i;
+         |       ^
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ****************
 Revision History
@@ -44,7 +44,7 @@ def setup(app):
 # -- Project information

 project = 'Verilator'
-copyright = '2024 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
+copyright = '2026 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
 author = 'Wilson Snyder'

 # The master toctree document.
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _connecting:

@@ -28,13 +29,13 @@ The generated model class file manages all internal state required by the
 model, and exposes the following interface that allows interaction with the
 model:

-* Top level IO ports are exposed as references to the appropriate internal
+- Top level IO ports are exposed as references to the appropriate internal
  equivalents.

-* Public top level module instances are exposed as pointers to allow access
+- Public top level module instances are exposed as pointers to allow access
  to ``/* verilator public */`` items.

-* The root of the design hierarchy (as in SystemVerilog ``$root``) is
+- The root of the design hierarchy (as in SystemVerilog ``$root``) is
  exposed via the ``rootp`` member pointer to allow access to model
  internals, including ``/* verilator public_flat */`` items.

@@ -58,22 +59,22 @@ This means that user code that accesses internal signals in the model
 (likely including ``/* verilator public_flat */`` signals, as they are
 often inlined into the root scope) will need to be updated as follows:

-* No change required for accessing top level IO signals. These are directly
+- No change required for accessing top level IO signals. These are directly
  accessible in the model class via references.

-* No change required for accessing ``/* verilator public */`` items. These
+- No change required for accessing ``/* verilator public */`` items. These
  are directly accessible via sub-module pointers in the model class.

-* Accessing any other internal members, including
-  ``/* verilator public_flat */`` items requires the following changes:
+- Accessing any other internal members, including ``/* verilator
+  public_flat */`` items requires the following changes:

-  * Additionally include :file:`{prefix}___024root.h`. This header defines
+  - Additionally include :file:`{prefix}___024root.h`. This header defines
    type of the ``rootp`` pointer within the model class. Note the
    ``__024`` substring is the Verilator escape sequence for the ``$``
    character, i.e.: ``rootp`` points to the Verilated SystemVerilog
    ``$root`` scope.

-  * Replace ``modelp->internal->member`` references with
+  - Replace ``modelp->internal->member`` references with
    ``modelp->rootp->internal->member`` references, which contain one
    additional indirection via the ``rootp`` pointer.

@@ -91,13 +92,17 @@ model.
 Refer to ``examples/make_tracing_c`` in the distribution for a detailed
 commented example.

-Top level IO signals are read and written as members of the model. You call
-the model's ``eval()`` method to evaluate the model. When the simulation is
-complete call the model's ``final()`` method to execute any SystemVerilog
-final blocks, and complete any assertions. If using :vlopt:`--timing`,
-there are two additional functions for checking if there are any events
-pending in the simulation due to delays, and for retrieving the simulation
-time of the next delayed event. See :ref:`Evaluation Loop`.
+Top level IO signals are read and written as members of the model. All
+inputs must be sanitized, that is have no bits set above those
+corresponding to the width of the Verilog construct;
+:vlopt:`--runtime-debug` will assert this is correct.
+
+Call the model's ``eval()`` method to evaluate the model. When the
+simulation is complete call the model's ``final()`` method to execute any
+SystemVerilog final blocks, and complete any assertions. If using
+:vlopt:`--timing`, there are two additional functions for checking if there
+are any events pending in the simulation due to delays, and for retrieving
+the simulation time of the next delayed event. See :ref:`Evaluation Loop`.


 Connecting to SystemC
@@ -184,7 +189,7 @@ Verilog, put in our.v:

   initial begin
     $display("%x + %x = %x", 1, 2, add(1,2));
-   endtask
+   end

 Then after Verilating, Verilator will create a file Vour__Dpi.h with the
 prototype to call this function:
@@ -210,9 +215,9 @@ Verilator extends the DPI format to allow using the same scheme to
 efficiently add system functions. Use a dollar-sign prefixed system
 function name for the import, but note it must be escaped.

-.. code-block:: sv
+.. code-block::

-   export "DPI-C" function integer \$myRand;
+   import "DPI-C" function integer \$myRand;

   initial $display("myRand=%d", $myRand());

@@ -502,9 +507,9 @@ described above is just a wrapper which calls these two functions.
 3. If using delays and :vlopt:`--timing`, there are two additional methods
 the user should call:

-   * ``designp->eventsPending()``, which returns ``true`` if there are any
+   - ``designp->eventsPending()``, which returns ``true`` if there are any
     delayed events pending,
-   * ``designp->nextTimeSlot()``, which returns the simulation time of the
+   - ``designp->nextTimeSlot()``, which returns the simulation time of the
     next delayed event. This method can only be called if
     ``designp->eventsPending()`` returned ``true``.

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 *******************************
 Contributing and Reporting Bugs
@@ -86,7 +87,8 @@ Please refer to `sv-bugpoint README
 <https://github.com/antmicro/sv-bugpoint/blob/main/README.md>`_ for more
 information on how to use `sv-bugpoint`.

-.. Contributing
-.. ============
+..
+   Contributing
+   ============

 .. include:: ../CONTRIBUTING.rst
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ************************
 Contributors and Origins
@@ -29,10 +30,10 @@ Alliance <https://chipsalliance.org>`_, and `Antmicro Ltd
 Previous major corporate sponsors of Verilator, by providing significant
 contributions of time or funds include: Antmicro Ltd., Atmel Corporation,
 Compaq Corporation, Digital Equipment Corporation, Embecosm Ltd., Fractile
-Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed Technologies
-Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus
-Networks Inc., SiCortex Inc, Shunyao CAD, Tenstorrent USA, Inc. and Western
-Digital Inc.
+Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed
+Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems
+Inc., Nauticus Networks Inc., SiCortex Inc, Shunyao CAD, Tenstorrent USA,
+Inc. and Western Digital Inc.

 The contributors of major functionality are: Jeremy Bennett, Krzysztof
 Bieganski, Byron Bradley, Lane Brooks, John Coiner, Duane Galbi, Arkadiusz
@@ -142,18 +143,18 @@ Krzysztof Obłonczek, Danny Oler, Andreas Olofsson, Baltazar Ortiz,
 Aleksander Osman, Don Owen, Tim Paine, Deepa Palaniappan, James Pallister,
 Vassilis Papaefstathiou, Sanggyu Park, Brad Parker, Risto Pejašinović, Seth
 Pellegrino, Joel Peltonen, Morten Borup Petersen, Dan Petrisko, Thanh Tung
-Pham, Wesley Piard, Maciej Piechotka, David Pierce, Cody Piersall,
-T. Platz, Michael Platzer, Dominic Plunkett, Nolan Poe, Tuomas Poikela,
-George Polack, David Poole, Michael Popoloski, Roman Popov, Aylon Chaim
-Porat, Oron Port, Rich Porter, Rick Porter, Stefan Post, Niranjan Prabhu,
-Damien Pretet, Harald Pretl, Bill Pringlemeir, Usha Priyadharshini, Mark
-Jackson Pulver, Prateek Puri, Nikolay Puzanov, Han Qi, Jiacheng Qian,
-Marshal Qiao, Raynard Qiao, Yujia Qiao, Jasen Qin, Frank Qiu, Nandu Raj,
-Kamil Rakoczy, Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh
-Redford, Odd Magne Reitan, Frédéric Requin, Wajahat Riaz, Dustin Richmond,
-Samuel Riedel, Alberto Del Rio, Eric Rippey, Narcis Rodas, Oleg Rodionov,
-Ludwig Rogiers, Paul Rolfe, Michail Rontionov, Arjen Roodselaar, Arthur
-Rosa, Tobias Rosenkranz, Yernagula Roshit, Diego Roux, Ryszard Rozak, Dan
+Pham, Wesley Piard, Maciej Piechotka, David Pierce, Cody Piersall, T.
+Platz, Michael Platzer, Dominic Plunkett, Nolan Poe, Tuomas Poikela, George
+Polack, David Poole, Michael Popoloski, Roman Popov, Aylon Chaim Porat,
+Oron Port, Rich Porter, Rick Porter, Stefan Post, Niranjan Prabhu, Damien
+Pretet, Harald Pretl, Bill Pringlemeir, Usha Priyadharshini, Mark Jackson
+Pulver, Prateek Puri, Nikolay Puzanov, Han Qi, Jiacheng Qian, Marshal Qiao,
+Raynard Qiao, Yujia Qiao, Jasen Qin, Frank Qiu, Nandu Raj, Kamil Rakoczy,
+Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh Redford, Odd
+Magne Reitan, Frédéric Requin, Wajahat Riaz, Dustin Richmond, Samuel
+Riedel, Alberto Del Rio, Eric Rippey, Narcis Rodas, Oleg Rodionov, Ludwig
+Rogiers, Paul Rolfe, Michail Rontionov, Arjen Roodselaar, Arthur Rosa,
+Tobias Rosenkranz, Yernagula Roshit, Diego Roux, Ryszard Rozak, Dan
 Ruelas-Petrisko, Luca Rufer, Huang Rui, Graham Rushton, Jan Egil Ruud,
 Denis Rystsov, Pawel Sagan, Robert Sammelson, Adrian Sampson, John
 Sanguinetti, Josep Sans, Dave Sargeant, Luca Sasselli, Philippe Sauter,
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _verilator control files:

@@ -100,6 +101,27 @@ The grammar of control commands is as follows:

   Same as :option:`/*verilator&32;forceable*/` metacomment.

+.. option:: fsm_register_wrapper -module "<modulename>" -d "<port>" -q "<port>" -clock "<port>" [-reset "<port>"] [-reset_value "<param>"]
+
+   Declares that the specified module is a transparent FSM state-register
+   wrapper for FSM coverage extraction. One declaration applies to all
+   instances of that module.
+
+   The ``-d`` option names the wrapper input port carrying next-state data.
+   The ``-q`` option names the wrapper output port carrying registered state.
+   The ``-clock`` option names the wrapper clock port.
+
+   Verilator does not infer wrapper semantics from module or port naming
+   conventions. A wrapper module must be declared with this option before
+   Verilator will use instances of it to extract FSM state and transition
+   coverage.
+
+   The ``-reset`` and ``-reset_value`` options are optional. Reset arcs are
+   emitted only when both the reset polarity can be inferred from the
+   wrapper's event control and ``-reset_value`` names a static parameter value.
+   If reset metadata is incomplete, Verilator may still emit FSM state and
+   transition coverage without reset arcs.
+
 .. option:: full_case -file "<filename>" -lines <lineno>

   Same as ``//synthesis full_case``. When these synthesis directives
@@ -166,6 +188,10 @@ The grammar of control commands is as follows:

 .. option:: isolate_assignments -module "<modulename>" [-task "<taskname>"] -var "<signame>"

+   Deprecated and has no effect (ignored).
+
+   In versions before 5.050:
+
   Used to indicate that the assignments to this signal in any blocks
   should be isolated into new blocks. Same as
   :option:`/*verilator&32;isolate_assignments*/` metacomment.
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 *********
 Copyright
@@ -7,10 +8,10 @@ Copyright

 The latest version of Verilator is available from https://verilator.org.

-Copyright 2003-2026 by Wilson Snyder. Verilator is free software; you
-can redistribute it and/or modify the Verilator internals under the terms
-of either the GNU Lesser General Public License Version 3 or the Perl
-Artistic License Version 2.0.
+Copyright 2003-2026 by Wilson Snyder. Verilator is free software; you can
+redistribute it and/or modify the Verilator internals under the terms of
+either the GNU Lesser General Public License Version 3 or the Perl Artistic
+License Version 2.0.

 All Verilog and C++/SystemC code quoted within this documentation file is
 released as Creative Commons Public Domain (CC0). Many example files and
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 Deprecations
 ============
@@ -1,7 +1,8 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

-.. _Environment:
+.. _environment:

 Environment
 ===========
@@ -89,7 +90,8 @@ associated programs.
 .. 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".
+   "ddd". If not specified, it will use "gdb" if available, otherwise
+   "lldb" if available.

 .. option:: VERILATOR_NUMA_STRATEGY

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _example create-binary execution:

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _example c++ execution:

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 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,
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _examples in the distribution:

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _example systemc execution:

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _examples:

@@ -9,10 +10,10 @@ Examples

 This section covers the following examples:

-* :ref:`Example Create-Binary Execution`
-* :ref:`Example C++ Execution`
-* :ref:`Example SystemC Execution`
-* :ref:`Examples in the Distribution`
+- :ref:`Example Create-Binary Execution`
+- :ref:`Example C++ Execution`
+- :ref:`Example SystemC Execution`
+- :ref:`Examples in the Distribution`

 .. toctree::
   :maxdepth: 1
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _simulation runtime arguments:

@@ -20,6 +21,13 @@ Summary:

 Options:

+.. option:: +verilator+assert+lock
+
+   Only allow command line options to disable / enable assertions.
+   Disables RTL from changing assertion handling via ``$asserton``,
+   ``$assertoff``, and ``$assertcontrol``. Also prevents ``VerilatedContext*``
+   assertion control functions from updating assertion handling.
+
 .. option:: +verilator+coverage+file+<filename>

   When a model was Verilated using :vlopt:`--coverage`, sets the filename
@@ -48,6 +56,11 @@ Options:

   Display help and exit.

+.. option:: +verilator+log+file+<filename>
+
+   Log all stdout and stderr to the specified output filename. If not specified
+   the normal stdout/stderr streams are used.
+
 .. option:: +verilator+noassert

   Disable assert checking per runtime argument. This is the same as
@@ -108,13 +121,16 @@ Options:
   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`.
+   :ref:`Unknown States`.  Default is 0.

 .. 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.
+   simulation runtime random seed value. If not specified, the seed
+   defaults to 1. If specified as 0, a non-zero seed is generated at
+   startup; the picked value is exposed through ``$get_initial_random_seed``
+   so the run can be reproduced later by passing
+   ``+verilator+seed+<that_value>``.

 .. option:: +verilator+solver+file+<filename>

@@ -130,6 +146,20 @@ Options:

   Displays program version and exits.

+.. option:: +verilator+vpi+<library>[:<bootstrap>]
+
+   Load a VPI shared library before simulation starts. Only available when the
+   model was Verilated with :vlopt:`--vpi` and :vlopt:`--main` (or
+   :vlopt:`--binary`). ``<library>`` is the path to the shared library. If
+   ``:<bootstrap>`` is given, that named no-argument function is called;
+   otherwise the library's ``vlog_startup_routines`` array (IEEE 1800 38.37.2) is
+   invoked. May be repeated to load multiple libraries.
+
+   Runtime loading is supported on POSIX platforms only (it relies on the
+   executable exporting its VPI symbols to the loaded library); on Windows the
+   argument is rejected and the VPI code must instead be statically linked
+   into the model.
+
 .. option:: +verilator+wno+unsatconstr+<value>

   Disable unsatisfied constraint warnings at simulation runtime. When set to
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ===================
 verilator Arguments
@@ -113,6 +114,19 @@ Summary:
   In versions before 5.038, these were disabled by default, and `--assert`
   or `--assert-case` was required to enable case assertions.

+.. option:: --assert-unroll-limit <iterations>
+
+   Deprecated and has no effect (ignored).
+
+   In versions before 5.052:
+
+   Rarely needed. Specifies the maximum repetition or range count Verilator
+   will unroll inside an SVA concurrent assertion (e.g. ``[*N]``, ``[->M:N]``,
+   ``always[lo:hi]``). Beyond this, the assertion is rejected with an error
+   so that pathological counts do not blow up compile time or memory.
+
+   Defaults to 1024. Increase if a design needs larger repetition counts.
+
 .. option:: --autoflush

   After every $display or $fdisplay, flush the output stream. This ensures
@@ -281,7 +295,8 @@ Summary:
 .. option:: --coverage

   Enables all forms of coverage, an alias for :vlopt:`--coverage-line`
-   :vlopt:`--coverage-toggle` :vlopt:`--coverage-expr` :vlopt:`--coverage-user`.
+   :vlopt:`--coverage-toggle` :vlopt:`--coverage-expr` :vlopt:`--coverage-fsm`
+   :vlopt:`--coverage-user`.

 .. option:: --coverage-expr

@@ -293,6 +308,10 @@ Summary:
   covered for a given expression. Defaults to 32. Increasing may slow
   coverage simulations and make analyzing the results unwieldy.

+.. option:: --coverage-fsm
+
+   Enables native FSM state and arc coverage. See :ref:`FSM Coverage`.
+
 .. option:: --coverage-line

   Enables basic block line coverage analysis. See :ref:`Line Coverage`.
@@ -303,6 +322,20 @@ Summary:
   toggle coverage. Defaults to 256, as covering large vectors may greatly
   slow coverage simulations.

+.. option:: --coverage-per-instance
+
+   For Verilator-inserted coverage, preserve generated coverage counters and
+   ``.dat`` records per hierarchy instance. This option must be specified when
+   Verilating the model, together with one or more coverage instrumentation
+   options, for example :vlopt:`--coverage`, :vlopt:`--coverage-line`,
+   :vlopt:`--coverage-toggle`, :vlopt:`--coverage-expr`,
+   :vlopt:`--coverage-fsm`, or :vlopt:`--coverage-user`. It may increase
+   generated model size, counter memory, coverage write time, and ``.dat`` file
+   size.
+
+   This does not affect SystemVerilog ``cover``, which uses the IEEE-specified
+   coverage option ``per_instance``.
+
 .. option:: --coverage-toggle

   Enables adding signal toggle coverage. See :ref:`Toggle Coverage`.
@@ -315,8 +348,8 @@ Summary:

 .. option:: --coverage-user

-   Enables adding user-inserted functional coverage. See :ref:`User
-   Coverage`.
+   Enables adding user-inserted functional covergroup coverage. See
+   :ref:`Covergroup Coverage`.

 .. option:: -D<var>=<value>

@@ -462,6 +495,10 @@ Summary:
   Rarely needed - for developer use. Enable all dumping in the given
   source file at level 3.

+.. option:: --dump-ast-patterns
+
+   Rarely needed. Enable dumping AstNodeExpr pattern statistics.
+
 .. option:: --dump-defines

   With :vlopt:`-E`, suppress normal output, and instead print a list of
@@ -478,6 +515,10 @@ Summary:
   Rarely needed. Enable dumping DfgGraph .dot debug files with dumping
   level 3.

+.. option:: --dump-dfg-patterns
+
+   Rarely needed. Enable dumping DfgGraph pattern statistics.
+
 .. option:: --dump-graph

   Rarely needed. Enable dumping V3Graph .dot debug files with dumping
@@ -625,8 +666,28 @@ Summary:

 .. option:: -fno-assemble

+.. option:: -fno-bit-scan-loops
+
+   Rarely needed. Disable converting bit counting loops into built-in operations.
+
 .. option:: -fno-case

+   Rarely needed. Disable all case statement optimizations.
+
+   Alias for all other `-fno-case-*` options.
+
+.. option:: -fno-case-decoder
+
+   Rarely needed. Disable converting case statements into decoder tables.
+
+.. option:: -fno-case-table
+
+   Rarely needed. Disable converting case statements into table lookups.
+
+.. option:: -fno-case-tree
+
+   Rarely needed. Disable converting case statements into bit-wise branch trees.
+
 .. option:: -fno-combine

 .. option:: -fno-const
@@ -658,6 +719,10 @@ Summary:

 .. option:: -fno-dfg-break-cycles

+   Deprecated and has no effect (ignored).
+
+   In versions before 5.052:
+
   Rarely needed. Disable breaking combinational cycles during DFG.

 .. option:: -fno-dfg-peephole
@@ -705,12 +770,41 @@ Summary:
   this is not recommended as may cause additional warnings and ordering
   issues.

+.. option:: -fno-ico-change-detect
+
+   Rarely needed. Disable input change detection in the input combinational
+   ('ico') region. With change detection enabled (the default, unless
+   :vlopt:`--vpi` is passed), the input combinational logic is evaluated only
+   when a top level input has actually changed, rather than unconditionally on
+   the first scheduling iteration.
+
+   The change detection logic assumes a top level input only ever changes
+   externally between evaluations. The optimization is automatically disabled
+   for top level input signals that are written within the design. Accesses via
+   the VPI cannot be analyzed at compile time, therefore :vlopt:`--vpi`
+   disables this optimization for all inputs; it may be turned back on by
+   explicitly passing :vlopt:`-fico-change-detect <-fno-ico-change-detect>`.
+
 .. option:: -fno-inline

+   Rarely needed. Disable module inlining.
+
+.. option:: -fno-inline-cfuncs
+
+   Rarely needed. Disable inlining of small generated C++ functions into their
+   callers.
+
+   This optimization is automatically disabled when :vlopt:`--prof-cfuncs` is
+   used.
+
 .. option:: -fno-inline-funcs

+   Rarely needed. Disable inlining of SystemVerilog functions and tasks.
+
 .. option:: -fno-inline-funcs-eager

+   Rarely needed. Disable eager inlining of SystemVerilog functions and tasks.
+
 .. option:: -fno-life

 .. option:: -fno-life-post
@@ -749,6 +843,14 @@ Summary:
   automatically. Variables explicitly annotated with
   :option:`/*verilator&32;split_var*/` are still split.

+.. option:: --fourstate
+
+   Enables four-state logic support. Experimental, for developer use only.
+
+.. option:: --no-fourstate
+
+   Disables four-state logic support which is the default. Exists for forward compatibility.
+
 .. option:: --fslice-element-limit

   Rarely needed. Set the maximum array size (number of elements) for slice
@@ -842,7 +944,7 @@ Summary:
   :file:`*.mk` files.

   Feature may be one of the following: COROUTINES, DEV_ASAN, DEV_GCOV,
-   SYSTEMC.
+   SYSTEMC, TSAN.

 .. option:: --getenv <variable>

@@ -904,27 +1006,21 @@ Summary:

 .. option:: --inline-cfuncs <value>

-   Inline small C++ function (internal AstCFunc) calls directly into their
-   callers when the function has at most <value> nodes. This reduces
-   function call overhead when :vlopt:`--output-split-cfuncs` places
-   functions in separate compilation units that the C++ compiler cannot
-   inline.
+   Tune the inlining of small generated C++ function. Functions no bigger than
+   <value> nodes will be inlined if possible. The default is 20.

-   Set to 0 to disable this optimization. The default is 20.
-
-   This optimization is automatically disabled when :vlopt:`--prof-cfuncs`
-   or :vlopt:`--trace` is used.
+   See also :vlopt:`--inline-cfuncs-product` and :vlopt:`-fno-inline-cfuncs`.

 .. option:: --inline-cfuncs-product <value>

-   Tune the inlining of C++ function (internal AstCFunc) calls for larger
-   functions. When a function is too large to always inline (exceeds
-   :vlopt:`--inline-cfuncs` threshold), it may still be inlined if the
-   function size multiplied by the number of call sites is at most <value>.
+   Tune the inlining of small generated C++ function. If a function's node
+   count multiplied by the number of calls is not bigger than <value>, the
+   function will be inlined if possible.

-   This allows functions that are called only once or twice to be inlined
-   even if they exceed the small function threshold. Set to 0 to only inline
-   functions below the :vlopt:`--inline-cfuncs` threshold. The default is 200.
+   This allows functions that are called only once or twice to be inlined even
+   if they exceed the small function threshold. The default is 200.
+
+   See also :vlopt:`--inline-cfuncs` and :vlopt:`-fno-inline-cfuncs`.

 .. option:: --inline-mult <value>

@@ -1131,6 +1227,8 @@ Summary:
 .. option:: --max-num-width <value>

   Set the maximum number literal width (e.g., in 1024'd22 the 1024).
+   This also limits SVA cycle delay and temporal bound values.
+
   Defaults to 64K.

 .. option:: --Mdir <directory>
@@ -1825,7 +1923,7 @@ Summary:
 .. option:: --trace-fst

   Enable FST waveform tracing in the model. This overrides
-   :vlopt:`--trace`. See also :vlopt:`--trace-threads` option.
+   :vlopt:`--trace`.

 .. option:: --trace-max-array <depth>

@@ -1859,6 +1957,10 @@ Summary:

 .. option:: --trace-threads <threads>

+   Deprecated and has no effect.
+
+   In versions before 5.048:
+
   Enable waveform tracing using separate threads. This is typically faster
   in simulation runtime but uses more total compute. This option only
   applies to :vlopt:`--trace-fst`. FST tracing can utilize at most
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 verilator_coverage
 ==================
@@ -38,6 +39,10 @@ verilator_coverage Example Usage

   verilator_coverage --annotate obj_dir coverage.dat

+   verilator_coverage --report summary coverage.dat
+
+   verilator_coverage --report hier --levels 3 coverage.dat
+
   verilator_coverage --write merged.dat coverage.dat ...

   verilator_coverage --write-info merged.info coverage.dat ...
@@ -128,14 +133,32 @@ verilator_coverage Arguments

 .. option:: --filter-type <regex>

-   Skips records of coverage types that matches with <regex>
-   Possible values are `toggle`, `line`, `branch`, `expr`, `user` and
-   a wildcard with `\*` or `?`. The default value is `\*`.
+   Keeps records of coverage types that matches with <regex>
+   Possible values are `toggle`, `line`, `branch`, `expr`, `covergroup`,
+   `user`, `fsm_state`, `fsm_arc` and a wildcard with `\*` or `?`. The
+   default value is `\*`.
+
+   The `covergroup` type represents SystemVerilog functional coverage
+   including covergroups, coverpoints, bins, and cross coverage as defined
+   in IEEE 1800-2023 Section 19.

 .. option:: --help

   Displays a help summary, the program version, and exits.

+.. option:: --include-reset-arcs
+
+   Includes FSM reset arcs in the printed summaries and annotated output.
+   By default, reset arcs are tracked but summarized separately from the
+   non-reset FSM arcs.
+
+.. option:: --levels <depth>
+
+   With :option:`--report hierarchy`, limits displayed hierarchy depth.
+   Deeper descendants still roll-up into the visible parent totals. A depth
+   of 0 shows the top-level hierarchy roll-up. If negative or omitted, all
+   depths are shown.
+
 .. option:: --rank

   Prints an experimental report listing the relative importance of each
@@ -148,6 +171,18 @@ verilator_coverage Arguments
   contribute to overall coverage if all tests are run in the order of
   highest to the lowest rank.

+.. option:: --report <kind>[,<kind>...]
+
+   Generates a human-consumable report. Supported report kinds are
+   ``summary``, ``hier``, and ``hierarchy``. Multiple report kinds may be
+   comma-separated, for example ``summary,hier``. With no explicit
+   :option:`--report`, the legacy flat summary is printed. ``summary`` is
+   equivalent to the flat type summary. ``hier`` and ``hierarchy`` build a
+   deterministic hierarchy roll-up from ``hier`` fields. Collapsed wildcard
+   hierarchy can be reported, but it is not precise per-instance coverage.
+   If no hierarchy fields are present, a warning is printed and the flat
+   summary is shown instead.
+
 .. option:: --unlink

   With :option:`--write`, unlink all input files after the output has been
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 verilator_gantt
 ===============
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 verilator_profcfunc
 ===================
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 *********************************
 Executable and Argument Reference
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ===================
 Language Extensions
@@ -293,6 +294,25 @@ or "`ifdef`"'s may break other tools.
   (if appropriate :vlopt:`--coverage` flags are passed) after being
   disabled earlier with :option:`/*verilator&32;coverage_off*/`.

+.. option:: /*verilator&32;dpi_c_decl "<C function declaration>"*/
+
+   Specifies C function declaration that will be emitted for given DPI-C
+   function into the Verilator-generated __Dpi.h header, replacing the declaration
+   that Verilator would build by default using the Verilog function signature.
+
+   This enables use of C functions with types not specified in the
+   standard. For example, it enables use of functions that return ``char*``:
+
+   .. code-block:: sv
+
+      module t;
+        import "DPI-C" function string getenv(input string arg) /*verilator dpi_c_decl "char* getenv(const char*)"*/;
+
+        initial begin
+          $display("%s", getenv("HOME"));
+        end
+      endmodule
+
 .. option:: /*verilator&32;fargs <arguments>*/

   For Verilator developers only. When a source file containing these `fargs`
@@ -341,6 +361,10 @@ or "`ifdef`"'s may break other tools.

 .. option:: /*verilator&32;isolate_assignments*/

+   Deprecated and has no effect (ignored).
+
+   In versions before 5.050:
+
   Used after a signal declaration to indicate the assignments to this
   signal in any blocks should be isolated into new blocks. When large
   combinatorial block results in a :option:`UNOPTFLAT` warning, attaching
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ******************************
 FAQ/Frequently Asked Questions
@@ -82,17 +83,17 @@ the licenses for details.

 Some examples:

-* Any SystemVerilog or other input fed into Verilator remains your own.
+- Any SystemVerilog or other input fed into Verilator remains your own.

-* Any of your VPI/DPI C++ routines that Verilator calls remain your own.
+- Any of your VPI/DPI C++ routines that Verilator calls remain your own.

-* Any of your main() C++ code that calls into Verilator remains your own.
+- Any of your main() C++ code that calls into Verilator remains your own.

-* If you change Verilator itself, for example, changing or adding a file
+- If you change Verilator itself, for example, changing or adding a file
  under the src/ directory in the repository, you must make the source code
  available under the GNU Lesser Public License.

-* If you change a header Verilator provides, for example, under include/ in
+- If you change a header Verilator provides, for example, under include/ in
  the repository, you must make the source code available under the GNU
  Lesser Public License.

@@ -384,33 +385,33 @@ 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
+- 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 is large enough to be split due to the :vlopt:`--output-split`
  option.

-* Verilator emits any infrequently executed "cold" routines into separate
+- 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.
+- Use a recent compiler. Newer compilers tend to be faster.

-* Compile in parallel on many machines and use caching; see the web for the
+- Compile in parallel on many machines and use caching; see the web for the
  ccache, sccache, distcc, or 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 and :ref: `Profiling ccache efficiency`.

-* To reduce the compile time of classes that use a Verilated module (e.g.,
+- 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`.
+- Use :ref:`hierarchical verilation`.


 Why do so many files need to recompile when I add a signal?
@@ -498,12 +499,12 @@ equal, the 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 only SystemC instances below must be SystemC.

-* A module with a mix of Verilog and SystemC instances below must be
+- 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
+- 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
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 *****
 Files
@@ -42,138 +43,141 @@ For --cc/--sc, it creates:

 .. list-table::

-   * - *{prefix}*.json
+   - - *{prefix}*.json
     - JSON build definition compiling (from --make json)
-   * - *{prefix}*.mk
+   - - *{prefix}*.mk
     - Make include file for compiling (from --make gmake)
-   * - *{prefix}*\ _classes.mk
+   - - *{prefix}*\ _classes.mk
     - Make include file with class names (from --make gmake)
-   * - *{prefix}*.h
+   - - *{prefix}*.h
     - Model header
-   * - *{prefix}*.cpp
+   - - *{prefix}*.cpp
     - Model C++ file
-   * - *{prefix}*\ ___024root.h
+   - - *{prefix}*\ ___024root.h
     - Top-level internal header file (from SystemVerilog $root)
-   * - *{prefix}*\ ___024root.cpp
+   - - *{prefix}*\ ___024root.cpp
     - Top-level internal C++ file (from SystemVerilog $root)
-   * - *{prefix}*\ ___024root\ *{__n}*.cpp
+   - - *{prefix}*\ ___024root\ *{__n}*.cpp
     - Additional top-level internal C++ files
-   * - *{prefix}*\ ___024root__Slow\ *{__n}*.cpp
+   - - *{prefix}*\ ___024root__Slow\ *{__n}*.cpp
     - Infrequent cold routines
-   * - *{prefix}*\ ___024root__Trace\ *{__n}*.cpp
+   - - *{prefix}*\ ___024root__Trace\ *{__n}*.cpp
     - Wave file generation code (from --trace-\*)
-   * - *{prefix}*\ ___024root__Trace__Slow\ *{__n}*.cpp
+   - - *{prefix}*\ ___024root__Trace__Slow\ *{__n}*.cpp
     - Wave file generation code (from --trace-\*)
-   * - *{prefix}*\ __Dpi.h
+   - - *{prefix}*\ __Dpi.h
     - DPI import and export declarations (from --dpi)
-   * - *{prefix}*\ __Dpi.cpp
+   - - *{prefix}*\ __Dpi.cpp
     - Global DPI export wrappers (from --dpi)
-   * - *{prefix}*\ __Dpi_Export\ *{__n}*.cpp
+   - - *{prefix}*\ __Dpi_Export\ *{__n}*.cpp
     - DPI export wrappers scoped to this particular model (from --dpi)
-   * - *{prefix}*\ __Inlines.h
+   - - *{prefix}*\ __Inlines.h
     - Inline support functions
-   * - *{prefix}*\ __Syms.h
+   - - *{prefix}*\ __Syms.h
     - Global symbol table header
-   * - *{prefix}*\ __Syms.cpp
+   - - *{prefix}*\ __Syms.cpp
     - Global symbol table C++
-   * - *{prefix}{each_verilog_module}*.h
+   - - *{prefix}{each_verilog_module}*.h
     - Lower level internal header files
-   * - *{prefix}{each_verilog_module}*.cpp
+   - - *{prefix}{each_verilog_module}*.cpp
     - Lower level internal C++ files
-   * - *{prefix}{each_verilog_module}{__n}*.cpp
+   - - *{prefix}{each_verilog_module}{__n}*.cpp
     - Additional lower C++ files

 For --hierarchical mode, it creates:

 .. list-table::

-   * - V\ *{hier_block}*\ /
+   - - V\ *{hier_block}*/
     - Directory to Verilate each hierarchical block (from --hierarchical)
-   * - *{prefix}*\ __hierVer.d
+   - - *{prefix}*\ __hierVer.d
     - Make dependencies of the top module (from --hierarchical)
-   * - *{prefix}*\ _hier.mk
+   - - *{prefix}*\ _hier.mk
     - Make file for hierarchical blocks (from --make gmake)
-   * - *{prefix}*\ __hierMkJsonArgs.f
+   - - *{prefix}*\ __hierMkJsonArgs.f
     - Arguments for hierarchical Verilation (from --make json)
-   * - *{prefix}*\ __hierMkArgs.f
+   - - *{prefix}*\ __hierMkArgs.f
     - Arguments for hierarchical Verilation (from --make gmake)
-   * - *{prefix}*\ __hierParameters.v
+   - - *{prefix}*\ __hierParameters.v
     - Module parameters for hierarchical blocks
-   * - *{prefix}*\ __hier.dir
-     - Directory to store .dot, .vpp, .tree of top module (from --hierarchical)
+   - - *{prefix}*\ __hier.dir
+     - Directory to store .dot, .vpp, .tree of top module (from
+       --hierarchical)

 In specific debug and other modes, it also creates:

 .. list-table::

-   * - *{prefix}*.sarif
+   - - *{prefix}*.sarif
     - SARIF diagnostics (from --diagnostics-sarif)
-   * - *{prefix}*.tree.json
+   - - *{prefix}*.tree.json
     - JSON tree information (from --json-only)
-   * - *{prefix}*.tree.meta.json
+   - - *{prefix}*.tree.meta.json
     - JSON tree metadata (from --json-only)
-   * - *{prefix}*\ __cdc.txt
+   - - *{prefix}*\ __cdc.txt
     - Clock Domain Crossing checks (from --cdc)
-   * - *{prefix}*\ __stats.txt
+   - - *{prefix}*\ __stats.txt
     - Statistics (from --stats)
-   * - *{prefix}*\ __idmap.txt
+   - - *{prefix}*\ __idmap.txt
     - Symbol demangling (from --protect-ids)
-   * - *{prefix}*\ __ver.d
+   - - *{prefix}*\ __ver.d
     - Make dependencies (from -MMD)
-   * - *{prefix}*\ __verFiles.dat
+   - - *{prefix}*\ __verFiles.dat
     - Timestamps (from --skip-identical)
-   * - *{prefix}{misc}*.dot
+   - - *{prefix}{misc}*.dot
     - Debugging graph files (from --debug)
-   * - *{prefix}{misc}*.tree
+   - - *{prefix}{misc}*.tree
     - Debugging files (from --debug)
-   * - *{prefix}*\ __inputs.vpp
+   - - *{prefix}*\ __inputs.vpp
     - Pre-processed verilog for all files (from --debug)
-   * - *{prefix}*\ _ *{each_verilog_base_filename}*.vpp
+   - - *{prefix}*\ _ *{each_verilog_base_filename}*.vpp
     - Pre-processed verilog for each file (from --debug)

 After running Make, the C++ compiler may produce the following:

 .. list-table::

-   * - verilated{misc}*.d
+   - - verilated{misc}*.d
     - Intermediate dependencies
-   * - verilated{misc}*.o
+   - - verilated{misc}*.o
     - Intermediate objects
-   * - {mod_prefix}{misc}*.d
+   - - {mod_prefix}{misc}*.d
     - Intermediate dependencies
-   * - {mod_prefix}{misc}*.o
+   - - {mod_prefix}{misc}*.o
     - Intermediate objects
-   * - *{prefix}*\
+   - - *{prefix}*\
     - Final executable (from --exe)
-   * - lib\ *{prefix}*.a
+   - - lib\ *{prefix}*.a
     - Final archive (default lib mode)
-   * - libverilated.a
+   - - libverilated.a
     - Runtime for verilated model (default lib mode)
-   * - *{prefix}*\ __ALL.a
+   - - *{prefix}*\ __ALL.a
     - Library of all Verilated objects
-   * - *{prefix}*\ __ALL.cpp
+   - - *{prefix}*\ __ALL.cpp
     - Include of all code for single compile
-   * - *{prefix}{misc}*.d
+   - - *{prefix}{misc}*.d
     - Intermediate dependencies
-   * - *{prefix}{misc}*.o
+   - - *{prefix}{misc}*.o
     - Intermediate objects

 The Verilated executable may produce the following:

 .. list-table::

-   * - coverage.dat
-     - Code coverage output, and default input filename for :command:`verilator_coverage`
-   * - gmon.out
-     - GCC/clang code profiler output, often fed into :command:`verilator_profcfunc`
-   * - profile.vlt
+   - - coverage.dat
+     - Code coverage output, and default input filename for
+       :command:`verilator_coverage`
+   - - gmon.out
+     - GCC/clang code profiler output, often fed into
+       :command:`verilator_profcfunc`
+   - - profile.vlt
     - --prof-pgo data file for :ref:`Thread PGO`
-   * - profile_exec.dat
+   - - profile_exec.dat
     - --prof-exec data file for :command:`verilator_gantt`

 Verilator_gantt may produce the following:

 .. list-table::

-   * - profile_exec.vcd
+   - - profile_exec.vcd
     - Gantt report waveform output
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ######################
 Verilator User's Guide
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _cmakeinstallation:

@@ -16,16 +17,16 @@ Linux).
 Quick Install
 =============

-1. Install Python for your platform from https://www.python.org/downloads/.
-2. Install CMake for your platform from https://cmake.org/download/ or
+#. Install Python for your platform from https://www.python.org/downloads/.
+#. Install CMake for your platform from https://cmake.org/download/ or
   build it from source.
-3. If the compiler of your choice is MSVC, then install
+#. If the compiler of your choice is MSVC, then install
   https://visualstudio.microsoft.com/downloads/. If the compiler of your
   choice is Clang, then install https://releases.llvm.org/download.html or
   build it from source.
-4. For flex and bison use https://github.com/lexxmark/winflexbison to build
+#. For flex and bison use https://github.com/lexxmark/winflexbison to build
   and install.
-5. For build on Windows using MSVC set environment variable WIN_FLEX_BISON
+#. For build on Windows using MSVC set environment variable WIN_FLEX_BISON
   to install directory. For build on Windows/Linux/OS-X using ninja set
   the environment variable FLEX_INCLUDE to the directory containing
   FlexLexer.h and ensure that flex/bison is available within the PATH.
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _installation:

@@ -64,7 +65,7 @@ In brief, to install from git:
   #sudo apt-get install libgoogle-perftools-dev libjemalloc-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)
+   #sudo apt-get install zlibc zlib1g zlib1g-dev liblz4 liblz4-dev  # Ubuntu only (ignore if gives error)

   git clone https://github.com/verilator/verilator   # Only first time

@@ -116,7 +117,7 @@ To build or run Verilator, you need these standard packages:
   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)
+   sudo apt-get install zlibc zlib1g zlib1g-dev liblz4 liblz4-dev  # Ubuntu only (ignore if gives error)

 For SystemC:

@@ -170,6 +171,9 @@ once, after ``configure``:

 .. code-block:: bash

+   # Install dependencies
+   sudo apt install python3-pip
+
   # Create Python virutal environment in .venv:
   make venv

@@ -381,12 +385,10 @@ the files:

   make install

-
 .. Docker Build Environment

 .. include:: ../../ci/docker/buildenv/README.rst

-
 .. Docker Run Environment

 .. include:: ../../ci/docker/run/README.rst
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ***************
 Input Languages
@@ -38,14 +39,6 @@ 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 allowed syntax.
-
-Verilator has limited support for class and related object-oriented
-constructs.
-

 SystemVerilog 2012 (IEEE 1800-2012) Support
 -------------------------------------------
@@ -110,11 +103,11 @@ Time

 With :vlopt:`--timing`, all timing controls are supported:

-* delay statements,
-* event control statements not only at the top of a process,
-* intra-assignment timing controls,
-* net delays,
-* ``wait`` statements,
+- delay statements,
+- event control statements not only at the top of a process,
+- intra-assignment timing controls,
+- net delays,
+- ``wait`` statements,

 as well as all flavors of ``fork``.

@@ -136,26 +129,26 @@ simulation (perhaps using :vlopt:`--build`) and run it.
 With :vlopt:`--no-timing`, all timing controls cause the :option:`NOTIMING`
 error, except:

-* delay statements - they are ignored (as they are in synthesis), though they
-  do issue a :option:`STMTDLY` warning,
-* intra-assignment timing controls - they are ignored, though they do issue
+- delay statements - they are ignored (as they are in synthesis), though
+  they do issue a :option:`STMTDLY` warning,
+- intra-assignment timing controls - they are ignored, though they do issue
  an :option:`ASSIGNDLY` warning,
-* net delays - they are ignored,
-* event controls at the top of the procedure,
+- net delays - they are ignored,
+- event controls at the top of the procedure,

 Forks cause this error as well, except:

-* forks with no statements,
-* ``fork..join`` or ``fork..join_any`` with one statement,
-* forks with :vlopt:`--bbox-unsup`.
+- forks with no statements,
+- ``fork..join`` or ``fork..join_any`` with one statement,
+- forks with :vlopt:`--bbox-unsup`.

 If neither :vlopt:`--timing` nor :vlopt:`--no-timing` is specified, all
 timing controls cause the :option:`NEEDTIMINGOPT` error, except event
 controls at the top of the process. Forks cause this error as well, except:

-* forks with no statements,
-* ``fork..join`` or ``fork..join_any`` with one statement,
-* forks with :vlopt:`--bbox-unsup`.
+- forks with no statements,
+- ``fork..join`` or ``fork..join_any`` with one statement,
+- forks with :vlopt:`--bbox-unsup`.

 Timing controls and forks can also be ignored in specific files or parts of
 files. The :option:`/*verilator&32;timing_off*/` and
@@ -363,13 +356,15 @@ appropriate width.
 Assertions
 ----------

-Verilator is beginning to add support for assertions. Verilator currently
-only converts assertions to simple ``if (...) error`` statements, and
-coverage statements to increment the line counters described in the
-coverage section.
+Verilator partially supports assertions and assertion-driven functional
+coverage.

-Verilator does not support SEREs yet. All assertion and coverage statements
-must be simple expressions that complete in one cycle.
+Coverage
+--------
+
+Verilator partially supports SystemVerilog functional coverage with
+``covergroup``, ``coverpoint``, bins, cross coverage, and transition bins.
+See :ref:`Covergroup Coverage`.


 Encrypted Verilog
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ********
 Overview
@@ -47,9 +48,9 @@ The best place to get started is to try the :ref:`Examples`.
   uses the shorthand, e.g., "IEEE 1364-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, 2017, and 2023. The Verilator
-   documentation uses the shorthand e.g., "IEEE 1800-2023", to refer to
-   the, e.g., 2023 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, 2017, and 2023. The Verilator documentation uses the
+   shorthand e.g., "IEEE 1800-2023", to refer to the, e.g., 2023 version of
+   this standard.
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. _simulating:

@@ -65,7 +66,7 @@ The information in this report is:

 .. describe:: "allocated 123 MB"

-   Total memory used during simulation in megabytes.
+   Peak resident memory used during simulation in megabytes.


 .. _benchmarking & optimization:
@@ -184,7 +185,9 @@ 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:`Property Coverage`
+- :ref:`Covergroup Coverage`
+- :ref:`FSM Coverage`
 - :ref:`Line Coverage`
 - :ref:`Toggle Coverage`

@@ -192,22 +195,124 @@ When a model with coverage is executed, it will create a coverage file for
 collection and later analysis, see :ref:`Coverage Collection`.


-.. _user coverage:
+.. _property coverage:

-Functional Coverage
-------------------
+Property Coverage
+-----------------

 With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
-translate functional coverage points the user has inserted manually in
-SystemVerilog code through into the Verilated model.
+translate property coverage points the user has inserted manually in
+SystemVerilog code into the Verilated model.

-For example, the following SystemVerilog statement will add a coverage
-point under the coverage name "DefaultClock":
+For simple coverage points, use the ``cover property`` construct:

 .. code-block:: sv

   DefaultClock: cover property (@(posedge clk) cyc==3);

+This adds a coverage point that tracks whether the condition has been
+observed.
+
+.. _covergroup coverage:
+
+Covergroup Coverage
+-------------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
+translate covergroup coverage points the user has inserted manually in
+SystemVerilog code into the Verilated model. Verilator supports coverpoints
+with value and transition bins, and cross points.
+
+
+.. _fsm coverage:
+
+FSM Coverage
+------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-fsm`, Verilator can
+instrument a conservative subset of FSMs and report both state coverage
+(`fsm_state`) and transition coverage (`fsm_arc`).
+
+This feature is currently experimental and might change in subsequent
+releases. In particular, the native FSM coverage extraction heuristics,
+:vlopt:`--coverage-fsm`, and the Verilator-specific FSM metacomments below
+should be treated as subject to change while the interface settles.
+
+FSM extraction is intentionally narrow. The current implementation targets
+clocked state machines that can be recovered directly from the RTL. It
+recognizes scalar enum, parameter, localparam, and selected literal state
+encodings in these common forms:
+
+- Single-process FSMs, whose state dispatch is written as ``case (state)``
+  or as a top-level ``if`` / ``else if`` chain comparing the same state
+  variable against known state values
+- Two-process and three-block FSMs, where a clocked state register is
+  paired with a combinational next-state block using the same supported
+  ``case`` or top-level ``if`` / ``else if`` dispatch forms
+
+Scalar state encodings may be wider than 32 bits. This allows sparse state
+encodings, such as high-Hamming-distance enum or localparam values, to be
+preserved in the detected FSM model. Verilator uses the declared enum item
+name, parameter name, or localparam name as the reported state label where
+possible.
+
+Simple input guards are supported when they appear inside a recognized
+state branch, or as a top-level conjunction containing exactly one state
+comparison, such as ``(state_q == IDLE) && ready``. Directly traceable
+pre-decoded state aliases, such as ``assign idle_state = (state_q ==
+IDLE)``, may also be used in these guarded predicates.
+
+Verilator does not claim broad support for arbitrary predicate
+decomposition, one-hot inference, helper-function next-state recovery,
+deeply nested control recovery, or cross-module state alias tracing.
+
+The following metacomments may be attached to the state variable to steer
+the extracted coverage model:
+
+- ``/*verilator fsm_state*/`` forces the variable to be treated as FSM
+  state.
+- ``/*verilator fsm_reset_arc*/`` marks reset transitions as user-visible
+  reset arcs instead of defaulting to a hidden reset-only summary.
+- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch arcs that
+  would otherwise be skipped by the conservative extractor.
+
+State registers may also be wrapped by a transparent instance, for example
+a project flop wrapper or primitive. Such wrappers must be described
+explicitly with a VLT command file action before Verilator will use their
+data, state, clock, or reset connections for FSM extraction:
+
+.. code-block:: sv
+
+   `verilator_config
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i"
+
+The same command may be placed in a separate ``.vlt`` file:
+
+.. code-block:: sv
+
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i"
+
+Optional reset metadata may also be supplied:
+
+.. code-block:: sv
+
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i" \
+      -reset "rst_ni" -reset_value "ResetValue"
+
+Reset arcs are emitted only when the configured reset port has an inferable
+edge in the wrapper and the configured reset value parameter is statically
+resolvable. If reset metadata is incomplete, Verilator warns and may still
+emit FSM state and transition coverage, but reset arcs are omitted.
+
+Reset transitions are included in the collected data either way. By
+default, :command:`verilator_coverage` summarizes reset-only arcs rather
+than printing them alongside non-reset arcs. Use
+:option:`verilator_coverage --include-reset-arcs` to include those arcs in
+the printed summary and annotated output.
+
+Annotated output produced by :command:`verilator_coverage --annotate` will
+label FSM points with `fsm_state` and `fsm_arc`, and synthetic fallback
+transitions with `SYNTHETIC DEFAULT ARC`.

 .. _line coverage:

@@ -328,11 +433,11 @@ coverage point insertions into the model and collect the coverage data.

 To get the coverage data from the model, write the coverage with either:

-1. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump
+#. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump
   coverage when the test completes to the filename specified with
   :vlopt:`+verilator+coverage+file+\<filename\>`.

-2. In the user wrapper code, typically at the end once a test passes, call
+#. In the user wrapper code, typically at the end once a test passes, call
   ``Verilated::threadContextp()->coveragep()->write`` with an argument of
   the filename for the coverage data file to write coverage data to
   (typically "logs/coverage.dat").
@@ -397,12 +502,12 @@ how execution time is distributed in a verilated model.

 With the :vlopt:`--prof-exec` option, Verilator will:

-* Add code to the Verilated model to record execution flow.
+- Add code to the Verilated model to record execution flow.

-* Add code to save profiling data in non-human-friendly form to the file
+- Add code to save profiling data in non-human-friendly form to the file
  specified with :vlopt:`+verilator+prof+exec+file+\<filename\>`.

-* In multithreaded models, add code to record each macro-task's start and
+- In multithreaded models, add code to record each macro-task's start and
  end time across several calls to eval. (What is a macro-task? See the
  Verilator internals document (:file:`docs/internals.rst` in the
  distribution.)
@@ -502,8 +607,8 @@ There are two forms of profile-guided optimizations. Unfortunately, for
 best results, they must each be performed from the highest level code to
 the lowest, which means performing them separately and in this order:

-* :ref:`Thread PGO`
-* :ref:`Compiler PGO`
+- :ref:`Thread PGO`
+- :ref:`Compiler PGO`

 Other forms of PGO may be supported in the future, such as clock and reset
 toggle rate PGO, branch prediction PGO, statement execution time PGO, or
@@ -569,7 +674,7 @@ multithreaded models.
 Please see the appropriate compiler documentation to use PGO with GCC or
 Clang. The process in GCC 10 was as follows:

-1. Compile the Verilated model with the compiler's "-fprofile-generate"
+#. Compile the Verilated model with the compiler's "-fprofile-generate"
   flag:

   .. code-block:: bash
@@ -580,10 +685,10 @@ Clang. The process in GCC 10 was as follows:
   Or, if calling make yourself, add -fprofile-generate appropriately to
   your Makefile.

-2. Run your simulation. This will create \*.gcda file(s) in the same
+#. Run your simulation. This will create \*.gcda file(s) in the same
   directory as the source files.

-3. Recompile the model with -fprofile-use. The compiler will read the
+#. Recompile the model with -fprofile-use. The compiler will read the
   \*.gcda file(s).

   For GCC:
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 **********
 Verilating
@@ -7,21 +8,21 @@ Verilating

 Verilator may be used in five major ways:

-* With the :vlopt:`--binary` option, Verilator will translate the design
+- With the :vlopt:`--binary` option, Verilator will translate the design
  into an executable, via generating C++ and compiling it. See
  :ref:`Binary, C++ and SystemC Generation`.

-* With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate
+- With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate
  the design into C++ or SystemC code, respectively. See :ref:`Binary, C++
  and SystemC Generation`.

-* With the :vlopt:`--lint-only` option, Verilator will lint the design to
+- 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:`--json-only` option, Verilator will create JSON output
+- With the :vlopt:`--json-only` option, Verilator will create JSON output
  that may be used to feed into other user-designed tools.

-* With the :vlopt:`-E` option, Verilator will preprocess the code according
+- 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.
@@ -127,9 +128,9 @@ Usage
 Users need to mark one or more moderate-size modules as hierarchy block(s).
 There are two ways to mark a module:

-* Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code.
+- Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code.

-* Add a :option:`hier_block` line in the :ref:`Verilator Control Files`.
+- Add a :option:`hier_block` line in the :ref:`Verilator Control Files`.

 Then pass the :vlopt:`--hierarchical` option to Verilator.

@@ -145,28 +146,28 @@ Limitations

 Hierarchy blocks have some limitations, including:

-* Internals of the hierarchy block cannot be accessed using dot (.) from
+- Internals of the hierarchy block cannot be accessed using dot (.) from
  the upper module(s) or other hierarchy blocks, except that ports of a
  hierarchy block instance can be accessed from the directly enclosing
  nested hierarchy block, or from the top level non-hierarchical portions
  of the design if not a nested hierarchy block.

-* Modport cannot be used at the hierarchical block boundary.
+- Modport cannot be used at the hierarchical block boundary.

-* The simulation speed is likely not as fast as flat Verilation, in which
+- The simulation speed is likely not as fast as flat Verilation, in which
  all modules are globally scheduled.

-* Generated clocks may not work correctly if generated in the hierarchical
+- Generated clocks may not work correctly if generated in the hierarchical
  model and passed into another hierarchical model or the top module.

-* Delays are not allowed in hierarchy blocks.
+- Delays are not allowed in hierarchy blocks.

 But, the following usage is supported:

-* Nested hierarchy blocks. A hierarchy block may instantiate other
+- Nested hierarchy blocks. A hierarchy block may instantiate other
  hierarchy blocks.

-* Parameterized hierarchy block. Parameters of a hierarchy block can be
+- Parameterized hierarchy block. Parameters of a hierarchy block can be
  overridden using ``#(.param_name(value))`` construct.


@@ -262,23 +263,6 @@ construction is parallelized using the same number of threads as specified
 with :vlopt:`--threads`, and is executed on the same thread pool as the
 model.

-The :vlopt:`--trace-threads` options can be used with :vlopt:`--trace-fst`
-to offload FST tracing using multiple threads. If :vlopt:`--trace-threads`
-is given 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,
-up to N additional threads will be created and managed by the trace files
-(e.g., VerilatedFstC), to offload construction of the trace dump. The main
-thread will be released to proceed with execution as soon as possible,
-though some main thread blocking is still necessary while capturing the
-trace. FST tracing can utilize up to 2 offload threads, so there is no use
-of setting :vlopt:`--trace-threads` higher than 2 at the moment.
-
 When running a multithreaded model, the default Linux task scheduler often
 works against the model by assuming short-lived threads and thus it often
 schedules threads using multiple hyperthreads within the same physical
@@ -286,15 +270,14 @@ core. If there is no affinity already set, on Linux only, Verilator
 attempts to set thread-to-processor affinity in a reasonable way.

 Some newer Linux kernels handle thread assignment well. If running
-Verilator on such a system, automatic thread affinity may not be
-beneficial and may even reduce performance. In this case, environment
-variable :vlopt:`VERILATOR_NUMA_STRATEGY` may be set to ``none`` to
-disable automatic thread affinity. For more information, refer to
+Verilator on such a system, automatic thread affinity may not be beneficial
+and may even reduce performance. In this case, environment variable
+:vlopt:`VERILATOR_NUMA_STRATEGY` may be set to ``none`` to disable
+automatic thread affinity. For more information, refer to
 :ref:`Environment`.

 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.
+threading count fits) select unique physical cores on the same socket.

 As an example, if a model was Verilated with :vlopt:`--threads 4
 <--threads>`, we consult:
@@ -521,7 +504,10 @@ include directories and link to the SystemC libraries.

 .. describe:: TRACE_THREADS

-   Optional. Enable multithreaded FST trace; see :vlopt:`--trace-threads`.
+   Deprecated and has no effect.
+
+   In versions before 5.048: Optional. Enable multithreaded FST trace; see
+   :vlopt:`--trace-threads`.

 .. describe:: TRACE_VCD

@@ -637,5 +623,5 @@ The information in this report is:

 .. describe:: "allocated 123 MB"

-   Total memory used during build by Verilator executable (excludes
-   :vlopt:`--build` compiler's usage) in megabytes.
+   Peak resident memory used by the Verilator executable during build
+   (excludes :vlopt:`--build` compiler's usage) in megabytes.
@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 ===================
 Errors and Warnings
@@ -96,21 +97,21 @@ List Of Warnings

 .. option:: ALWCOMBORDER

-   .. TODO better example
-
-   Warns that an ``always_comb`` block has a variable that is set after it
-   is used. This may cause simulation-synthesis mismatches, as not all
-   simulators allow this ordering.
+   Warns that an ``always_comb`` block reads a variable before assigning it
+   later in the same block. Because statements in a procedural block execute
+   in source order, the read observes the variable's previous value for that
+   activation. This can imply latch/state-like behavior and is not purely
+   combinational.

   .. code-block:: sv

      always_comb begin
-        a = b;
-        b = 1;
+        y = a + tmp;  // Reads the previous value of tmp
+        tmp = b;
      end

-   Ignoring this warning will only suppress the lint check; it will
-   simulate correctly.
+   If the new value of ``tmp`` is intended, assign ``tmp`` before reading it.
+   Suppressing this warning may make results vary between simulators.


 .. option:: ALWNEVER
@@ -306,7 +307,7 @@ List Of Warnings
        else
          array[address] <= data;

-   While this is supported in typical synthesizeable code (including the
+   While this is supported in typical synthesizable code (including the
   example above), some complicated cases are not supported. Namely:

   1. If the above loop is inside a suspendable process or fork statement.
@@ -382,6 +383,9 @@ List Of Warnings
   non-enumerated values (IEEE 1800-2023 12.5.3). Verilator checks that
   illegal values are not hit, unless :vlopt:`--no-assert-case` was used.

+   Unique0 case statements will never cause this warning. (Although unique0
+   should be avoided in synthesizable code as may result in latch behavior.)
+
   Ignoring this warning will only suppress the lint check; it will
   simulate correctly.

@@ -521,6 +525,48 @@ List Of Warnings
   Suppressing this error will suppress the error message check; it will
   simulate as if the ``const`` as not present.

+.. option:: CONTASSINIT
+
+   Error that a continuous assignment is setting a variable with an initial
+   value. Use either the initial value or the continuous assignment, but not
+   both.
+
+   For example:
+
+   .. code-block:: sv
+      :emphasize-lines: 2,4
+
+      module t;
+        logic b = 1'b0;
+        logic a;
+        assign b = a; //<--- Error
+      endmodule
+
+   Results in:
+
+   .. code-block::
+
+      %Error-CONTASSINIT: example.sv:4:10: Continuous assignment to variable with initial value: 'b'
+                                                  : ... note: In instance 't'
+                                                  : ... Location of variable initialization
+          2 |   logic b = 1'b0;
+            |         ^
+                            example.sv:4:10: ... Location of continuous assignment
+          4 |   assign b = a;
+            |          ^
+      %Error: Exiting due to 1 error(s)
+
+   The following is legal because the driven variable does not have a declaration
+   initializer:
+
+   .. code-block:: sv
+
+      module t;
+        logic b;
+        logic a = 1'b0;
+        assign b = a;
+      endmodule
+

 .. option:: CONTASSREG

@@ -837,6 +883,34 @@ List Of Warnings
   with a newline."


+.. option:: FINALDLY
+
+   Error issued when a non-blocking assignment `<=` is used in a
+   `final` block.
+
+   This error can be disabled. If disabled, the assignment will be
+   executed as a `=` blocking assignment.
+
+   Faulty example:
+
+   .. include:: ../../docs/gen/ex_FINALDLY_faulty.rst
+
+   Results in:
+
+   .. include:: ../../docs/gen/ex_FINALDLY_msg.rst
+
+.. option:: FSMMULTI
+
+   Warns that the same always block contains multiple enum-typed case
+   statements that look like FSM candidates for native FSM coverage when
+   :vlopt:`--coverage-fsm` or :vlopt:`--coverage` is enabled.
+
+   Verilator's FSM coverage instruments only the first such candidate in
+   source order. Split the FSMs into separate always blocks, or explicitly
+   annotate the intended state variables and restructure the RTL for full
+   coverage of such multiple state machines.
+
+
 .. option:: FUNCTIMECTL

   Error that a function contains a time-controlling statement or call of a
@@ -944,6 +1018,13 @@ List Of Warnings
   port list, since these are references to interfaces/modports declared at a higher level and are
   already specialized. These types of accesses do not require waiving HIERPARAM.

+.. option:: IEEEMAYDEPRECATE
+
+   This feature is not yet deprecated, but may be in a future version of the IEEE standard.
+   This warning is to alert users that they may want to avoid using this feature, as it
+   may be removed in a future version of the IEEE standard, and thus may not be supported
+   in future versions of Verilator.
+
 .. option:: IFDEPTH

   Warns that if/if else statements have exceeded the depth specified with
@@ -1114,11 +1195,14 @@ List Of Warnings

 .. option:: INITIALDLY

-   .. TODO better example
+   Historical, never issued since version 5.050.

   Warns that the code has a delayed assignment inside of an ``initial`` or
   ``final`` block. If this message is suppressed, Verilator will convert
-   this to a non-delayed assignment. See also :option:`COMBDLY`.
+   this to a non-delayed assignment. With :vlopt:`--timing`, delayed
+   assignments in ``initial`` blocks that also contain a `#` delay
+   control, or `@` even control statement are scheduled as
+   non-blocking assignments. See also :option:`COMBDLY`.

   Ignoring this warning may make Verilator simulations differ from other
   simulators.
@@ -1347,9 +1431,11 @@ List Of Warnings

 .. option:: MULTIDRIVEN

-   Warns that the specified signal comes from multiple ``always``
-   blocks, each with different clocking. This warning does not look at
-   individual bits (see the example below).
+   Warns that the specified signal has multiple procedural drivers.
+
+   One case is when the signal comes from multiple ``always`` blocks,
+   each with different clocking. This warning does not look at individual
+   bits (see the example below).

   This is considered bad style, as the consumer of a given signal may be
   unaware of the inconsistent clocking, causing clock domain crossing
@@ -1363,11 +1449,74 @@ List Of Warnings

   .. include:: ../../docs/gen/ex_MULTIDRIVEN_msg.rst

-   Ignoring this warning will only slow simulations; it will simulate
-   correctly. It may, however, cause longer simulation runtimes due to
+   Another case is when a variable written in an ``always_comb`` or
+   ``always_ff`` block is also written by another process. IEEE 1800
+   requires variables written in these specialized always blocks to be
+   written only by that process.
+
+   Faulty ``always_ff`` example:
+
+   .. include:: ../../docs/gen/ex_MULTIDRIVEN_alwaysff_faulty.rst
+
+   To retain an initialization without adding another process, use a
+   declaration initializer (or, for synthesizable code, add a reset term):
+
+   .. code-block:: sv
+
+      logic q = 1'b0;
+
+      always_ff @(posedge clk) begin
+        q <= d;
+      end
+
+   A further case is when a signal named as a clocking block ``output`` is
+   also driven by a continuous assignment, or is named as an ``output`` of a
+   second clocking block. The clocking block drives the signal, so the design
+   and the testbench contend for it and the synchronous drive may be silently
+   lost. Declare the clocking block ``input`` if the intent is only to
+   observe the signal.
+
+   Ignoring this warning may hide clock domain crossing, timing, or
+   portability bugs. It may also cause longer simulation runtimes due to
   reduced optimizations.


+.. option:: MULTIDRIVENPROC
+
+   Warns that the whole of a variable is driven by more than one plain
+   ``always`` block. Unlike the :option:`MULTIDRIVEN` cases, plain
+   ``always`` blocks carry no ``always_comb``/``always_ff`` intent, so this
+   is legal SystemVerilog rather than an IEEE 1800 violation. It is,
+   however, typically a synthesis error: hardware cannot have a signal
+   driven by two separate sequential blocks, so the design usually will not
+   behave as the RTL simulation suggests.
+
+   Disabled by default as this is a code-style warning; it will simulate
+   correctly.
+
+   Faulty example:
+
+   .. include:: ../../docs/gen/ex_MULTIDRIVENPROC_faulty.rst
+
+   Results in:
+
+   .. include:: ../../docs/gen/ex_MULTIDRIVENPROC_msg.rst
+
+   Also warns when a signal named as a clocking block ``output`` is driven
+   by a plain ``always`` block. Driving a signal from both a clocking block
+   and a plain ``always`` block is a deliberate idiom in some testbenches,
+   so it is reported as MULTIDRIVENPROC rather than under the on-by-default
+   :option:`MULTIDRIVEN`.
+
+   To fix, drive the signal from a single ``always`` block, or use
+   ``always_ff``/``always_comb`` if the intent is a single specialized
+   process.
+
+   Does not warn for static variables used as loop induction variables:
+
+   .. include:: ../../docs/gen/ex_MULTIDRIVENPROC_loopidx.rst
+
+
 .. option:: MULTITOP

   .. TODO better example
@@ -1411,6 +1560,19 @@ List Of Warnings
   (neither :vlopt:`--timing` nor :vlopt:`--no-timing` option was provided).


+.. option:: NEVERMATCH
+
+   Warns that an SVA sequence is statically known to never match. Such a
+   sequence is legal SystemVerilog and is fully supported, the warning
+   only highlights a potential problem. For example, using the sequence as
+   the antecedent of an implication causes the implication to pass
+   vacuously. For an intersect sequence, ensure its operands can match
+   over a common length (IEEE 1800-2023 16.9.6).
+
+   Ignoring this warning will only suppress the lint check; it will
+   simulate correctly.
+
+
 .. option:: NEWERSTD

   Warns that a feature requires a newer standard of Verilog or SystemVerilog
@@ -1492,6 +1654,25 @@ List Of Warnings
   :vlopt:`--no-timing` option.


+.. option:: NOTREDOP
+
+   Error that a logical not operator is directly followed by an
+   unparenthesized reduction operator, such as ``!|a``. The IEEE 1800-2023 Annex A
+   grammar requires the operand of ``!`` to be a primary expression, not an
+   unparenthesized reduction expression.
+
+   For example:
+
+   .. include:: ../../docs/gen/ex_NOTREDOP_msg.rst
+
+   Some simulators support this syntax as an extension, but it is recommended to fix
+   these to match IEEE. To do so, add parentheses around the reduction expression,
+   for example use ``!(|a)`` instead of ``!|a``.
+
+   Suppressing this error will suppress the error message check; it will simulate
+   correctly.
+
+
 .. option:: NULLPORT

   Warns that a null port was detected in the module definition port
@@ -1524,7 +1705,12 @@ List Of Warnings
   ANSI-style `#(...)` declarations. IEEE 1800-2023 6.20.1 requires this
   error, but some simulators accept this syntax.

-   Faulty example:
+   Also issued with ANSI format where a parameter without default is
+   present in the top-level module, and as such Verilator cannot know how
+   to process that module. For such cases suggest adding a default so the
+   module can lint cleanly.
+
+   Faulty non-ANSI example:

   .. include:: ../../docs/gen/ex_PARAMNODEFAULT_faulty.rst

@@ -1534,8 +1720,8 @@ List Of Warnings

   To fix the issue, move to an ANSI-style declaration.

-   Suppressing this error will only suppress the IEEE-required check; it
-   will simulate correctly.
+   For the non-ANSI case, suppressing this error will only suppress the
+   IEEE-required check; it will simulate correctly.


 .. option:: PINCONNECTEMPTY
@@ -1707,12 +1893,18 @@ List Of Warnings

   .. include:: ../../docs/gen/ex_PROCASSINIT_fixed.rst

-   Alternatively, use an initial block for the initialization:
+   For non-``always_ff`` logic, alternatively use an initial block for
+   the initialization:

   .. code-block:: sv

      initial flop_out = 1;  // <--- Fixed

+   Do not use a separate initial block for a variable assigned by an
+   ``always_ff`` process, as IEEE 1800 requires an ``always_ff`` variable
+   to be written only by that process. Use a declaration initializer, or
+   initialize the variable from reset logic inside the ``always_ff``.
+
   Disabled by default as this is a code-style warning; it will simulate
   correctly.

@@ -1953,6 +2145,32 @@ List Of Warnings
   simulators.


+.. option:: SIMILARNAME
+
+   Warns that an entity name only differs from another in lexical case.
+
+   Faulty example:
+
+   .. include:: ../../docs/gen/ex_SIMILARNAME_faulty.rst
+
+   Results in:
+
+   .. include:: ../../docs/gen/ex_SIMILARNAME_msg.rst
+
+   Only declarations that can reach a downstream VLSI tool as a name are
+   checked, that is nets, variables, instances, named blocks (``begin``,
+   ``fork``, and generate blocks), functions and tasks. All of these can form
+   part of a flattened signal or scope name.  Other declarations, such as
+   parameters, localparams, genvars and typedefs, are elaborated away, and so
+   are not checked.
+
+   Disabled by default as this is a code-style warning; it will simulate
+   correctly.
+
+   This is a warning as some downstream VLSI tools do
+   not distinguish net and gate names with the same case.
+
+
 .. option:: SPECIFYIGN

   Warns that Verilator does not support certain constructs in
@@ -2247,11 +2465,6 @@ List Of Warnings
   the conflict. If you run with :vlopt:`--report-unoptflat`, Verilator will
   suggest possible candidates for :option:`/*verilator&32;split_var*/`.

-   The UNOPTFLAT warning may also occur where outputs from a block of logic
-   are independent, but occur in the same always block. To fix this, use
-   the :option:`/*verilator&32;isolate_assignments*/` metacomment described
-   above.
-
   Before version 5.000, the UNOPTFLAT warning may also have been due to
   clock enables, identified from the reported path going through a clock
   gating instance. To fix these, the clock_enable meta comment was used.
@@ -113,9 +113,9 @@ pointer to the ``AstNode`` currently being processed.

 There are notable sub-hierarchies of the ``AstNode`` sub-types, namely:

-1. All AST nodes representing data types derive from ``AstNodeDType``.
+#. All AST nodes representing data types derive from ``AstNodeDType``.

-2. All AST nodes representing expressions (i.e.: anything that stands for,
+#. All AST nodes representing expressions (i.e.: anything that stands for,
   or evaluates to a value) derive from ``AstNodeExpr``.


@@ -425,8 +425,9 @@ logic.

 To achieve this, we invoke ``V3Order::order`` on all of the combinational
 and hybrid logic, and iterate the resulting evaluation function until no
-more hybrid logic is triggered. This yields the `_eval_settle` function,
-which is invoked at the beginning of simulation after the `_eval_initial`.
+more hybrid logic is triggered. This yields the `_eval_stl` function, which
+the runtime event loop iterates at the beginning of simulation, after the
+`_eval_initial`.


 Partitioning logic for correct NBA updates
@@ -500,51 +501,66 @@ and clock signals on separate evaluations, as was necessary with earlier
 versions of Verilator).


-Constructing the top level `_eval` function
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Constructing the region evaluation functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-To construct the top level `_eval` function, which updates the state of the
-circuit to the end of the current time step, we invoke ``V3Order::order``
-separately on the 'ico', 'act' and 'nba' logic, which yields the
-`_eval_ico`, `_eval_act`, and `_eval_nba` functions. We then put these all
-together with the corresponding functions that compute the respective
-trigger expressions into the top level `_eval` function, which on the high
-level has the form:
+To update the state of the circuit to the end of the current time step, we
+invoke ``V3Order::order`` separately on the 'ico', 'act' and 'nba' logic,
+which yields the `_eval_body__ico`, `_eval_body__act`, and
+`_eval_body__nba` functions. Each of these is then combined with the
+function computing the respective trigger expressions into a single entry
+point per region, `_eval_ico`, `_eval_act` and `_eval_nba`. A region entry
+point evaluates one iteration of its region, and returns whether it did any
+work, meaning the region has not converged yet and must be evaluated again.
+On the high level, `_eval_act` has the form:

 .. code-block:: C++

-   void _eval() {
-      // Update combinational logic dependent on top level inputs ('ico' region)
-      while (true) {
-        _eval__triggers__ico();
-        // If no 'ico' region trigger is active
-        if (!ico_triggers.any()) break;
-        _eval_ico();
-      }
-
-      // Iterate 'act' and 'nba' regions together
-      while (true) {
-
-        // Iterate 'act' region, this computes all derived clocks updaed in the
-        // Active scheduling region, but does not commit any NBAs that executed
-        // in 'act' region logic.
-        while (true) {
-          _eval__triggers__act();
-          // If no 'act' region trigger is active
-          if (!act_triggers.any()) break;
-          // Remember what 'act' triggers were active, 'nba' uses the same
-          latch_act_triggers_for_nba();
-          _eval_act();
-        }
-
-        // If no 'nba' region trigger is active
-        if (!nba_triggers.any()) break;
-
-        // Evaluate all other Active region logic, and commit NBAs
-        _eval_nba();
-      }
+   bool _eval_act() {
+      _eval_triggers_vec__act();
+      // Remember what 'act' triggers were active, 'nba' uses the same
+      latch_act_triggers_for_nba();
+      const bool execute = act_triggers.any();
+      // Compute all derived clocks updated in the Active scheduling region,
+      // but do not commit any NBAs that executed in 'act' region logic.
+      if (execute) _eval_body__act();
+      return execute;
   }

+The loops iterating these regions are not generated. They live in the
+runtime library, in ``VerilatedEvalLoop``, and the model exposes its region
+entry points to it as virtual methods of ``VerilatedModel``. The generated
+model holds a ``VerilatedEvalLoop`` as a member, which its ``eval_step``
+runs, and which on the high level has the form:
+
+.. code-block:: C++
+
+   void VerilatedEvalLoop::evalImpl() {
+      // Update combinational logic dependent on top level inputs ('ico' region)
+      uint32_t icoIterCount = 0;
+      do {
+        if (++icoIterCount > m_convergeLimit) didNotConverge("Input combinational");
+      } while (m_model.evalIco(icoIterCount == 1));
+
+      // Iterate 'act' and 'nba' regions together
+      uint32_t nbaIterCount = 0;
+      do {
+        if (++nbaIterCount > m_convergeLimit) didNotConverge("NBA");
+        // Iterate the 'act' region to convergence
+        uint32_t actIterCount = 0;
+        do {
+          if (++actIterCount > m_convergeLimit) didNotConverge("Active");
+        } while (m_model.evalAct());
+        // Evaluate all other Active region logic, and commit NBAs
+      } while (m_model.evalNba());
+   }
+
+The remaining regions ('inact', 'obs' and 'react') nest around these in the
+same manner, each iterating the loops of all regions that precede it in the
+SystemVerilog scheduling order. The runtime event loop calls every region
+unconditionally, so scheduling emits an entry point for each one even when
+the design has no logic in it. Such an entry point immediately returns
+false, ending its loop after a single iteration.

 Timing
 ------
@@ -666,23 +682,23 @@ The second visitor in ``V3Timing.cpp``, ``TimingControlVisitor``, uses the
 information provided by ``TimingSuspendableVisitor`` and transforms each
 timing control into a ``co_await``.

-* event controls are turned into ``co_await`` on a trigger scheduler's
+- event controls are turned into ``co_await`` on a trigger scheduler's
  ``trigger`` method. The awaited trigger scheduler is the one
  corresponding to the sentree referenced by the event control. This
  sentree is also referenced by the ``AstCAwait`` node, to be used later by
  the static scheduling code.

-* if an event control waits on a local variable or class member, it uses a
+- if an event control waits on a local variable or class member, it uses a
  local trigger which it evaluates inline. It awaits a dynamic trigger
  scheduler multiple times: for trigger evaluation, updates, and
  resumption. The dynamic trigger scheduler is responsible for resuming the
  coroutine at the correct point of evaluation.

-* delays are turned into ``co_await`` on a delay scheduler's ``delay``
+- delays are turned into ``co_await`` on a delay scheduler's ``delay``
  method. The created ``AstCAwait`` nodes also reference a special sentree
  related to delays, to be used later by the static scheduling code.

-* ``join`` and ``join_any`` are turned into ``co_await`` on a
+- ``join`` and ``join_any`` are turned into ``co_await`` on a
  ``VlForkSync``'s ``join`` method. Each forked process gets a
  ``VlForkSync::done`` call at the end.

@@ -720,67 +736,59 @@ in that process. When ordering code using ``V3Order``, these triggers are
 provided as external domains of these variables. This ensures that the
 necessary combinational logic is triggered after a coroutine resumption.

-Every call to a `VlTriggerScheduler`'s `trigger()` method is preempt by
-a call to a proper `__VbeforeTrig` function which evaluates all the necessary
-triggers so, the information about order of suspension/resumption is not lost.
-The triggers necessary to evaluate are ones dependent on the same events
-as the `trigger()` - e.g.: if `triggers()` awaits for event `a` or `b`, then
-every trigger that depends on any of those shall be evaluated. If they wouldn't
-be evaluated and next coroutine after resumption would fire the event `a` then
-it is impossible to get to know whether await or fire on event `a` was called
-first - which is necessary to know.
+Every call to a `VlTriggerScheduler`'s `trigger()` method is preempt by a
+call to a proper `__VbeforeTrig` function which evaluates all the necessary
+triggers so, the information about order of suspension/resumption is not
+lost. The triggers necessary to evaluate are ones dependent on the same
+events as the `trigger()` - e.g.: if `triggers()` awaits for event `a` or
+`b`, then every trigger that depends on any of those shall be evaluated. If
+they wouldn't be evaluated and next coroutine after resumption would fire
+the event `a` then it is impossible to get to know whether await or fire on
+event `a` was called first - which is necessary to know.

-There are two functions for managing timing logic called by ``_eval()``:
+There are two functions for managing timing logic called by the 'act'
+region:

-* ``_timing_ready()``, which commits all coroutines whose triggers were
-  not set in the current iteration,
-* ``_timing_resume()``, which calls `resume()` on all trigger and delay
+- ``_timing_ready()``, which commits all coroutines whose triggers were not
+  set in the current iteration,
+- ``_timing_resume()``, which calls `resume()` on all trigger and delay
  schedulers whose triggers were set in the current iteration.

 Thanks to this separation a coroutine:

-* awaiting a trigger cannot be suspended and resumed in the same iteration
+- awaiting a trigger cannot be suspended and resumed in the same iteration
  (``test_regress/t/t_timing_eval_act.v``) - which is necessary to make
-  Verilator more predictable; this is the reason for introduction of 3rd stage
-  in `VlTriggerScheduler` and thanks to this it is guaranteed that downstream
-  logic will be evaluated before resumption (assuming that the coroutine wasn't
-  already triggered in previous iteration);
-* cannot be resumed before it is suspended -
+  Verilator more predictable; this is the reason for introduction of 3rd
+  stage in `VlTriggerScheduler` and thanks to this it is guaranteed that
+  downstream logic will be evaluated before resumption (assuming that the
+  coroutine wasn't already triggered in previous iteration);
+- cannot be resumed before it is suspended -
  ``test_regress/t/t_event_control_double_excessive.v``;
-* firing cannot cannot be lost
-  (``test_regress/t/t_event_control_double_lost.v``) - which is possible when
-  triggers are not evaluated right before awaiting.
+- firing cannot cannot be lost
+  (``test_regress/t/t_event_control_double_lost.v``) - which is possible
+  when triggers are not evaluated right before awaiting.

-All coroutines are committed and resumed in the 'act' eval loop. With
-timing features enabled, the ``_eval()`` function takes this form:
+All coroutines are committed and resumed in the 'act' region. With timing
+features enabled, the 'act' region entry point takes this form:

 ::

-   void _eval() {
-     while (true) {
-       _eval__triggers__ico();
-       if (!ico_triggers.any()) break;
-       _eval_ico();
-     }
-
-     while (true) {
-       while (true) {
-         _eval__triggers__act();
-
-         // Commit all non-triggered coroutines
-         _timing_commit();
-
-         if (!act_triggers.any()) break;
-         latch_act_triggers_for_nba();
-
-         // Resume all triggered coroutines
-         _timing_resume();
-
-         _eval_act();
-       }
-       if (!nba_triggers.any()) break;
-       _eval_nba();
+   bool _eval_act() {
+     _eval_triggers_vec__act();
+
+     // Commit all non-triggered coroutines
+     _timing_commit();
+
+     const bool execute = act_triggers.any();
+     if (execute) {
+       latch_act_triggers_for_nba();
+
+       // Resume all triggered coroutines
+       _timing_resume();
+
+       _eval_body__act();
     }
+     return execute;
   }

 Forks
@@ -937,13 +945,15 @@ macro-task's dataset fits in one core's local caches.

 To achieve spatial locality, we tag each variable with the set of
 macro-tasks that access it. Let's call this set the "footprint" of that
-variable. The variables in a given module have a set of footprints. We can
-order those footprints to minimize the distance between them (distance is
-the number of macro-tasks that are different across any two footprints) and
-then emit all variables into the struct in ordered-footprint order.
+variable. The variables in a given module have a set of footprints. We
+group variables with identical non-empty footprints, emit those groups in
+deterministic footprint-key order, then emit variables with no footprint
+information last.

-The footprint ordering is literally the traveling salesman problem, and we
-use a TSP-approximation algorithm to get close to an optimal sort.
+The first emitted variable in each footprint group is aligned to a
+cache-line boundary. This avoids false sharing between different macro-task
+footprints without building a complete pairwise-distance graph over all
+footprints, which would use excessive memory on very large models.

 This is an old idea. Simulators designed at DEC in the early 1990s used
 similar techniques to optimize both single-thread and multithread modes.
@@ -1080,9 +1090,17 @@ solver gets a setup query, then the definition of variables, then all the
 constraints (SMT assertions) about the variables. Since the solver has no
 information about the class' PRNG state, if the problem is satisfiable, the
 solution space is further constrained by adding extra random constraints,
-and querying the values satisfying the problem statement. The constraint is
-currently constructed as fixing a simple xor of randomly chosen bits of the
-variables being randomized.
+and querying the values satisfying the problem statement. The constraints
+are currently built by the UniGen2 algorithm ("On Parallel Scalable Uniform
+SAT Witness Generation", Chakraborty et al.). It first works out how many
+random xor equations are needed to split the solution space into cells of a
+size worth enumerating, then draws one cell and enumerates it, which gives
+a near-uniform sample of the whole space. Both the estimate and the
+leftover solutions are cached, so the following calls are answered without
+asking the solver again. Cases outside its assumptions, such as ``randc``
+variables or soft constraints, fall back to pinning every free bit to a
+random value, or, when arrays are involved, to asserting four random xor
+equations in a row.

 The runtime classes used for handling the randomization are defined in
 ``verilated_random.h`` and ``verilated_random.cpp``.
@@ -1298,15 +1316,15 @@ the ``<description>`` field is ``<identifier> : <type>``, where
 ``<identifier>`` will be used as the base name of the generated operand
 accessors, and ``<type>`` is one of:

-1. An ``AstNode`` sub-class, defining the operand to be of that type,
+#. An ``AstNode`` sub-class, defining the operand to be of that type,
   always no-null, and with an always null ``nextp()``. That is, the child
   node is always present, and is a single ``AstNode`` (as opposed to a
   list).

-2. ``Optional[<AstNode sub-class>]``. This is just like in point 1 above,
+#. ``Optional[<AstNode sub-class>]``. This is just like in point 1 above,
   but defines the child node to be optional, meaning it may be null.

-3. ``List[AstNode sub-class]`` describes a list operand, which means the
+#. ``List[AstNode sub-class]`` describes a list operand, which means the
   child node may have a non-null ``nextp()`` and in addition the child
   itself may be null, representing an empty list.

@@ -1393,7 +1411,7 @@ calling ``accept`` on ``AstIf`` will look in turn for:

 There are three ways data is passed between visitor functions.

-1. A visitor-class member variable. This is generally for passing "parent"
+#. A visitor-class member variable. This is generally for passing "parent"
   information down to children. ``m_modp`` is a common example. It's set
   to NULL in the constructor, where that node (``AstModule`` visitor) sets
   it, then the children are iterated, then it's cleared. Children under an
@@ -1403,7 +1421,7 @@ There are three ways data is passed between visitor functions.
   visitor; otherwise exiting the lower for will lose the upper for's
   setting.

-2. User attributes. Each ``AstNode`` (**Note.** The AST node, not the
+#. User attributes. Each ``AstNode`` (**Note.** The AST node, not the
   visitor) has five user attributes, which may be accessed as an integer
   using the ``user1()`` through ``user4()`` methods, or as a pointer (of
   type ``AstNUser``) using the ``user1p()`` through ``user4p()`` methods
@@ -1434,7 +1452,7 @@ There are three ways data is passed between visitor functions.
   so it's ok to call fairly often. For example, it's commonly called on
   every module.

-3. Parameters can be passed between the visitors in close to the "normal"
+#. Parameters can be passed between the visitors in close to the "normal"
   function caller to callee way. This is the second ``vup`` parameter of
   type ``AstNUser`` that is ignored on most of the visitor functions.
   V3Width does this, but it proved messier than the above and is
@@ -1568,8 +1586,8 @@ For all tests to pass, you must install the following packages:

 - SystemC to compile the SystemC outputs, see https://systemc.org

- vcddiff to find differences in VCD outputs. See the readme at
-  https://github.com/veripool/vcddiff
+- wavediff to find differences in waveform outputs. See the readme at
+  https://github.com/hudson-trading/wavetools

 - Cmake for build paths that use it.

@@ -1701,7 +1719,7 @@ can have significant variance. Experience shows that a ~20% time difference
 can be reliably measured on GitHub hosted runners, and smaller differences
 are noticeable over a few days of reruns as trends emerge from the noise.

-Code coverage
+Code Coverage
 -------------

 Code coverage for developing Verilator itself can be collected using
@@ -1750,6 +1768,31 @@ example, to see coverage of changes compared to upstream, use:

   make coverage-view COVERAGE_BASE=origin/master

+
+Code Coverage Results
+---------------------
+
+When code coverage is complete, line coverage should be at 100%. Branch
+coverage is not required to be at 100%, but all uncovered branches should
+be understood as to why.
+
+For lines which are impossible, use ``// LCOV_EXCL_LINE``, or ``//
+LCOV_EXCL_START`` and ``// LCOV_EXCL_STOP`` regions.
+
+For branches which are impossible, use the ``VL_UNCOVERABLE(condition)``
+macro around uncoverable conditions, otherwise use ``//
+LCOV_EXCL_BR_LINE``.
+
+The assertions ``UASSERT`` and similar are automatically excluded from
+coverage, and as such should not require exclusion meta comments.
+
+As getting to complete code coverage typically takes many passes,
+developers should please iterate coverage improvements using a personal
+machine, or a personal branch on GitHub with personal action runners,
+rather than the Verilator GitHub runners, to avoid lots of mail to watchers
+and CI queue blockage.
+
+
 Fuzzing
 -------

@@ -2099,19 +2142,19 @@ To print a node:
 ``src/.gdbinit`` and ``src/.gdbinit.py`` define handy utilities for working
 with JSON AST dumps. For example:

-* ``jstash nodep`` - Perform a JSON AST dump and save it into GDB value
+- ``jstash nodep`` - Perform a JSON AST dump and save it into GDB value
  history (e.g. ``$1``)

-* ``jtree nodep`` - Perform a JSON AST dump and pretty print it using
+- ``jtree nodep`` - Perform a JSON AST dump and pretty print it using
  ``astsee_verilator``.
-* ``jtree $1`` - Pretty print a dump that was previously saved by
+- ``jtree $1`` - Pretty print a dump that was previously saved by
  ``jstash``.
-* ``jtree nodep -d '.file, .timeunit'`` - Perform a JSON AST dump, filter
+- ``jtree nodep -d '.file, .timeunit'`` - Perform a JSON AST dump, filter
  out some fields and pretty print it.

-* ``jtree 0x55555613dca0`` - Pretty print using address literal (rather
+- ``jtree 0x55555613dca0`` - Pretty print using address literal (rather
  than actual pointer).
-* ``jtree $1 nodep`` - Diff ``nodep`` against an older dump.
+- ``jtree $1 nodep`` - Diff ``nodep`` against an older dump.

 A detailed description of ``jstash`` and ``jtree`` can be displayed using
 ``gdb``'s ``help`` command.
@@ -2136,13 +2179,14 @@ backtrace. You will typically see a frame sequence something like:
 Bisecting bad transformations
 -----------------------------

-If a bad transformation in the internals of Verilator causes a failure only at
-runtime, it can be found fairly automatically by only applying the transform a
-limited number of times, then performing a bisection search over the limit to
-pinpoint the exact transformation that introduces the failure.
+If a bad transformation in the internals of Verilator causes a failure only
+at runtime, it can be found fairly automatically by only applying the
+transform a limited number of times, then performing a bisection search
+over the limit to pinpoint the exact transformation that introduces the
+failure.

-To facilitate this an instance of the ``V3DebugBisect`` class can be used in
-conjunction with the ``verilator_bisect`` script.
+To facilitate this an instance of the ``V3DebugBisect`` class can be used
+in conjunction with the ``verilator_bisect`` script.

 In the offending algorithm, create a static instance of ``V3DebugBisect``:

@@ -2150,55 +2194,91 @@ In the offending algorithm, create a static instance of ``V3DebugBisect``:

   static V3DebugBisect s_debugBisect{"TransformName"};

-Call the ``stop`` method before applying a transformation, and do not proceed
-if it returns ``false``. Then use ``verilator_bisect`` to search an interval of
-values. You need to provide an arbitrary discriminator command, this should run
-Verilator, then any necessary checks (e.g.: simulation) to detect that the
-failure is still present. It should exit with a non-zero status if the failure
-is still present. The discriminator command can otherwise be arbitrarily
-complex, the actual search limit is passed via environment variables. E.g.:
+Call the ``stop`` method before applying a transformation, and do not
+proceed if it returns ``false``. Then use ``verilator_bisect`` to search an
+interval of values. You need to provide an arbitrary discriminator command,
+this should run Verilator, then any necessary checks (e.g.: simulation) to
+detect that the failure is still present. It should exit with a non-zero
+status if the failure is still present. The discriminator command can
+otherwise be arbitrarily complex, the actual search limit is passed via
+environment variables. E.g.:

 ::

-  bin/verilator_bisect DfgPeephole 0 1000 test_regress/t/t_myothertest.py
+   bin/verilator_bisect DfgPeephole 0 1000 test_regress/t/t_myothertest.py

-An additional command can be run before the discriminator command. E.g.  this
-will run RTLMeter, but first removes its working directory so the models are
-recompiled on every step:
+An additional command can be run before the discriminator command. E.g.
+this will run RTLMeter, but first removes its working directory so the
+models are recompiled on every step:

 ::

-  bin/verilator_bisect --pre "rm -rf work-bisect" DfgPeephole 0 10000000 \
-    rtlmeter run --cases "..." --workRoot=work-bisect
+   bin/verilator_bisect --pre "rm -rf work-bisect" DfgPeephole 0 10000000 \
+     rtlmeter run --cases "..." --workRoot=work-bisect
+
+When the bisection ends, the first value that makes the discriminator
+command fail is printed, which identifies the exact offending application
+of the transform.
+
+Debugging Non-Deterministic Results
+-----------------------------------
+
+The Verilator binary should be deterministic, producing the same Verilated
+C++ and stdout when run multiple times with the same inputs. A common
+source of non-determinism is (mis-)use of pointers in container
+comparisons, causing arbitrary changes im memory layout to make container
+comparisons differ, and in turn creating differences in Ast layout, and
+ultimately different C++ code.
+
+To debug this, compile Verilator with the `VL_ALLOC_RANDOM_CHECKS` define,
+then Verilator may be run with a seed e.g. `-debug-alloc-random 22` and
+`-debug-alloc-random 33` which will randomly change the memory allocation
+order. If multiple seeds are run, `verilator_difftree` may then be used to
+see where netlists start to differ. Once the Ast difference is determined,
+the debugging tips above can then further isolate the C++ code causing a
+specific node to be created or changed.
+
+The typical fix is to add a comparison operator to the problematic
+container, e.g. compare using `AstNodeComparator` or by `name()`.
+
+The following script is an example of this debugging:
+
+.. code-block:: bash
+
+   # Before this: ./configure CXX="g++ -DVL_ALLOC_RANDOM_CHECKS" && make -j
+   # Example script for finding nondeterminism
+   cd $VERILATOR_ROOT
+   set -e
+   t=t_split_var_0  # Test name
+   test_regress/t/$t.py --debug --debug-alloc-random 33 --dumpi-tree 9 --obj-suffix .33
+   test_regress/t/$t.py --debug --debug-alloc-random 66 --dumpi-tree 9 --obj-suffix .66
+   bin/verilator_difftree test_regress/obj_vlt/$t{.33,.66} | grep -v CFILE | grep -v "^ " | grep -v /tmp | grep -v @@

-When the bisection ends, the first value that makes the discriminator command
-fail is printed, which identifies the exact offending application of the
-transform.

 Adding a New Feature
 ====================

 Generally, what would you do to add a new feature?

-1. File an issue (if there isn't already) so others know what you're
+#. File an issue (if there isn't already) so others know what you're
   working on.

-2. Make a testcase in the test_regress/t/t_EXAMPLE format, see `Testing`.
+#. Make a testcase in the test_regress/t/t_EXAMPLE format, see `Testing`.

-3. If grammar changes are needed, look at the IEEE 1800-2023 Appendix A, as
+#. If grammar changes are needed, look at the IEEE 1800-2023 Appendix A, as
   src/verilog.y generally follows the same rule layout.

-4. If a new Ast type is needed, add it to the appropriate V3AstNode*.h.
+#. If a new Ast type is needed, add it to the appropriate V3AstNode*.h.
   Follow the convention described above about the AstNode type hierarchy.
   Ordering of definitions is enforced by ``astgen``.

-5. Now you can run ``test_regress/t/t_<newtestcase>.py --debug`` and it'll
+#. Now you can run ``test_regress/t/t_<newtestcase>.py --debug`` and it'll
   probably fail, but you'll see a
   ``test_regress/obj_dir/t_<newtestcase>/*.tree`` file which you can
   examine to see if the parsing worked. See also the sections above on
   debugging.

-6. Modify the later visitor functions to process the new feature as needed.
+#. Modify the later visitor functions to process the new feature as needed.


 Adding a New Pass
@@ -2241,9 +2321,6 @@ IEEE 1800-2023 31 Timing checks
 IEEE 1800-2023 32 SDF annotation
   No longer relevant with static timing analysis tools.

-IEEE 1800-2023 33 Config
-   Little industry use.
-

 Test Driver
 ===========
@@ -2687,6 +2764,55 @@ xsim_flags / xsim_flags2 / xsim_run_flags
   only for use with the Xilinx XSim simulator.


+Version Release Process
+=======================
+
+This section documents the process to release a new version. This is not
+intended to be run by other than the primary repository admins.
+
+#. If activity requires, announce release pending as GitHub issue.
+#. Check all test suites pass:
+
+   - rtlmeter (or wait until overnight cron passes).
+   - sv-tests (run manually or wait a few days and check proper version was
+     tested).
+   - uvm (currently requires private accellera access).
+   - verilator-ext-tests: ``make pull && make clean && make test``
+
+#. Check documentation:
+
+   - ``nodist/log_changes # and update Changes``
+   - ``make spelling # and check warnings``
+   - ``make docs # and check warnings``
+
+#. Prepare release:
+
+   - edit ``Changes`` to update version banner.
+   - edit ``configure.ac`` to change version number and "devel" to proper
+     ISO-format date.
+   - edit ``CMakeLists.txt`` version number.
+
+#. Test and release:
+
+   - ``git commit -am "Version bump"``
+   - ``make distclean && autoconf && ./configure && make test``
+   - ``make maintainer-dist``
+
+#. Wait for GitHub CI build actions to pass.
+#. File announcement issue at verilator-announce, pasting in ``Changes``
+   information.
+#. Devel release:
+
+   - edit ``Changes``, ``configure.ac``, ``CMakeLists.txt`` to devel and
+     devel version number.
+   - ``git commit -am "devel release"``
+   - ``make distclean && autoconf && ./configure && make test``
+   - ``git push``
+
+#. Merge GitHub pull requests tagged ``status:merge-after-release``.
+#. Check ``docs/guide/deprecations.rst`` for things due to remove.
+
+
 Distribution
 ============

@@ -2695,6 +2821,7 @@ the terms of either the GNU Lesser General Public License Version 3 or the
 Perl Artistic License Version 2.0.

 SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+
 SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0

 .. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png
@@ -1,6 +1,7 @@
-.. for github, vim: syntax=reStructuredText
-.. SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
-.. SPDX-License-Identifier: CC0-1.0
+..
+   for github, vim: syntax=reStructuredText
+   SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
+   SPDX-License-Identifier: CC0-1.0

 Security Policy
 ===============
@@ -32,6 +32,7 @@ Bagri
 Balboni
 Baltazar
 Bardsley
+Barua
 Benchmarking
 Berman
 Bhagavatula
@@ -180,6 +181,7 @@ Guo
 Gustafsson
 Güzel
 Hameed
+Hamming
 Hammoud
 Hao
 Haojin
@@ -197,6 +199,7 @@ Holme
 Homebrew
 Hornung
 Hossell
+Hsieh
 Hsu
 Huggett
 Hutt
@@ -333,6 +336,7 @@ Muhlestein
 Multithreaded
 Multithreading
 Mykyta
+NFA
 NOUNOPTFLAT
 NaN
 Nalbantis
@@ -387,6 +391,7 @@ Preprocess
 Pretet
 Pretl
 Pringlemeir
+Prithayan
 Priyadharshini
 Pullup
 Pulver
@@ -428,6 +433,7 @@ Sasselli
 Sauter
 Scharrer
 Schless
+Secturion
 Seitz
 Shahid
 Shahrestani
@@ -474,6 +480,7 @@ Syms
 Synopsys
 SystemC
 SystemVerilog
+Szpotanski
 Takatsukasa
 Tambe
 Tarik
@@ -509,6 +516,7 @@ Ueno
 Uints
 Undefine
 Undefines
+Unigen
 Unsized
 Uppal
 Urbach
@@ -534,6 +542,7 @@ Verilog
 Vighnesh
 Viktor
 Vilp
+VlRNG
 VlWide
 Vlip
 Vm
@@ -578,6 +587,7 @@ Yujia
 Yurii
 Zaruba
 Zhang
+Zhi
 abirkmanis
 accessor
 accessors
@@ -589,6 +599,7 @@ al
 ala
 alejandro
 algrobman
+allocator
 andit
 ar
 architected
@@ -639,6 +650,7 @@ casez
 casted
 castro
 cb
+cbValueChange
 ccache
 ccall
 cdc
@@ -665,6 +677,7 @@ concatenatable
 concats
 conf
 config
+consequents
 const
 constexpr
 constification
@@ -678,6 +691,8 @@ countones
 cout
 covergroup
 covergroups
+coverpoint
+coverpoints
 cpp
 cppstyle
 cpu
@@ -696,8 +711,10 @@ datafiles
 david
 ddd
 de
+dearray
 deassign
 debugi
+deduplication
 defenv
 defname
 defparam
@@ -810,6 +827,7 @@ fs
 fscanf
 fseek
 fsiegle
+fsm
 fst
 fstrict
 ftell
@@ -837,6 +855,7 @@ gotFinish
 goto
 gprof
 gtkwave
+hdl
 hdr
 hdzhangdoc
 hh
@@ -851,6 +870,7 @@ hx
 hyperthreading
 hyperthreads
 icecream
+ico
 idmap
 ifdef
 ifdefed
@@ -860,6 +880,7 @@ impot
 incdir
 includer
 incrementing
+inferable
 inferfaces
 informationals
 inhibitSim
@@ -895,6 +916,7 @@ libext
 libgoogle
 libjemalloc
 liblist
+liblz
 libsystemc
 libtcmalloc
 libverilated
@@ -904,6 +926,8 @@ linters
 linux
 liu
 livelock
+liveness
+lldb
 ln
 loc
 localparam
@@ -911,6 +935,7 @@ localparams
 localtime
 logicals
 longint
+lookups
 lossy
 lsb
 lubc
@@ -930,6 +955,7 @@ misconnected
 misconversion
 misdetecting
 misoptimized
+misoptimizing
 missized
 mk
 mno
@@ -978,11 +1004,13 @@ noprivate
 noreturn
 notif
 nullptr
+num
 numactl
 onehot
 ooo
 oprofile
 ortegon
+output
 oversized
 oversubscription
 parallelized
@@ -1071,12 +1099,14 @@ recrem
 recurse
 recurses
 redeclaring
+reentrant
 regs
 reloop
 replaceShiftOp
 reproducibility
 resetall
 respecified
+reusability
 rodata
 rolloverSize
 rr
@@ -1107,6 +1137,7 @@ specparam
 splitme
 spp
 sqrt
+srand
 srandom
 src
 srcdir
@@ -1153,6 +1184,7 @@ tcmalloc
 tcmalloc
 tenghtt
 testbench
+testbenches
 threadsafe
 threashold
 timeInc
@@ -1187,6 +1219,7 @@ typename
 uint
 un
 unbased
+unclocked
 uncomment
 undef
 undefineall
@@ -1202,6 +1235,7 @@ unnamedblk
 unopt
 unoptflat
 unoptimizable
+unparenthesized
 unroller
 unsatisfiable
 unsized
@@ -1211,6 +1245,7 @@ upcasting
 urandom
 uselib
 utimes
+uvm
 uwire
 uwires
 valgrind
@@ -1257,6 +1292,7 @@ vpm
 vpp
 warmup
 wavealloca
+wavediff
 waveforms
 whitespace
 widthed
--- a/Show More
+++ b/Show More