Fix %m in hierarchical models (#8575)

The model of a hierarchical block, or of a --lib-create library, is
named after the %m of its instance in the parent model, but %m within it
also used to include the name of its top module (l2-name within the
partition), adding an extra level per block. %m now matches across
non-hierarchical, --hierarchical and manual --lib-create builds.

before: top.t.u_sub.sub.u_leaf.leaf
after:  top.t.u_sub.u_leaf

.clang-tidy

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

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,2 @@
+---
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/issue.md

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

.github/ISSUE_TEMPLATE/questions.md

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

.github/actions/artifact-cache/action.yml

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

.github/actions/install-deps/action.yml

@@ -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 }}

.github/actions/setup-venv/action.yml

@@ -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 }}

.github/actions/update-pr-label/action.yml

@@ -0,0 +1,62 @@
+---
+# DESCRIPTION: Github actions composite action
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Update PR label
+description: >-
+  Add or remove a label on a pull request. Does nothing unless the pull
+  request is still open and still at the commit the result is for, so that a
+  result superseded by a push does not label/unlabel the work that replaced it.
+
+inputs:
+  token:
+    description: "Token to label with"
+    required: true
+  pr-number:
+    description: "Number of the pull request"
+    required: true
+  head-sha:
+    description: "Commit the result is for"
+    required: true
+  label:
+    description: "Label to set"
+    required: true
+  set:
+    description: "'true' to add the label, 'false' to remove it"
+    required: true
+
+runs:
+  using: composite
+  steps:
+    - name: Set the label
+      shell: bash
+      env:
+        GH_TOKEN: ${{ inputs.token }}
+        REPO: ${{ github.repository }}
+        PR: ${{ inputs.pr-number }}
+        SHA: ${{ inputs.head-sha }}
+        LABEL: ${{ inputs.label }}
+        SET: ${{ inputs.set }}
+      run: |-
+        # The state and head of the pull request as they are now, and whether
+        # it carries the label already
+        read -r STATE HEAD LABELLED < <(gh pr view "${PR}" \
+          --repo "${REPO}" \
+          --json state,headRefOid,labels \
+          --jq '"\(.state) \(.headRefOid) \(any(.labels[]; .name == env.LABEL))"')
+        # Only act on a change, so a run does not reapply what is already set
+        if [ "${STATE}" != OPEN ]; then
+          # Only label open PRs
+          echo "PR #${PR} is ${STATE}"
+        elif [ "${HEAD}" != "${SHA}" ]; then
+          # Pushed to since, so this result is stale and a new run will decide
+          echo "PR #${PR} has moved on from ${SHA}"
+        elif [ "${SET}" = true ] && [ "${LABELLED}" = false ]; then
+          echo "Adding '${LABEL}' to PR #${PR}"
+          gh pr edit "${PR}" --repo "${REPO}" --add-label "${LABEL}"
+        elif [ "${SET}" = false ] && [ "${LABELLED}" = true ]; then
+          echo "Removing '${LABEL}' from PR #${PR}"
+          gh pr edit "${PR}" --repo "${REPO}" --remove-label "${LABEL}"
+        else
+          echo "No change to PR #${PR}"
+        fi

.github/actions/upload-pr-notification/action.yml

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

.github/workflows/build-test.yml

@@ -1,286 +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: build-test
-
-on:
-  push:
-    branches-ignore:
-      - 'dependabot/**'  # Avoid duplicates: only run the PR, not the push
-  pull_request:
-  workflow_dispatch:
-  schedule:
-    - cron: '0 0 * * 0'  # weekly
-
-permissions:
-  contents: read
-
-defaults:
-  run:
-    working-directory: repo
-
-concurrency:
-  # At most 1 job per branch. Auto cancel on pull requests and on all forks
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.repository != 'verilator/verilator' }}
-
-jobs:
-
-  build-2404-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: 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' || '' }}
-    uses: ./.github/workflows/reusable-build.yml
-    with:
-      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' || '' }}
-    uses: ./.github/workflows/reusable-build.yml
-    with:
-      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' || '' }}
-    uses: ./.github/workflows/reusable-build.yml
-    with:
-      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
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          path: repo
-      - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
-        with:
-          path: ${{ env.CCACHE_DIR }}
-          key: msbuild-msvc-cmake
-      - 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-2404-gcc:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ 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 }}
-      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}
-
-  test-2404-clang:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ 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 }}
-      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}
-
-  test-2204-gcc:
-    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ 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 }}
-      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}
-
-  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) }}

.github/workflows/contributor.yml

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

.github/workflows/coverage.yml

@@ -13,40 +13,88 @@ on:
 
 permissions:
   contents: read
+  actions: read
 
 defaults:
   run:
     shell: bash
 
 concurrency:
-  # At most 1 job per branch. Auto cancel all but scheduled jobs
-  group: ${{ github.workflow }}-${{ github.ref }}
+  # At most 1 job per branch. Auto cancel all but scheduled jobs.
+  # Of the pull request events, only one that starts a run, or that removes the
+  # 'pr: dev-coverage' label to cancel one, shares the group. The rest are
+  # skipped (a change of another label, or a payload that does not carry the
+  # label, like an 'opened' delivered after it was added), and a skipped run
+  # must not cancel the one in progress, so they are given a unique group.
+  # This way adding the label starts a run, removing it cancels the in-progress
+  # run, and anything else has no effect. Note such an event still creates a
+  # run of this workflow, which is skipped, and would then hide the one in
+  # progress on the pull request. 'pr-run-cleanup.yml' deletes those.
+  # Key pull request runs on the number: 'github.ref' is the base branch once
+  # the pull request is closed, so unlabel events would cancel base runs.
+  # NOTE: The last part of the group expression must be kept in sync with the
+  # 'start' job condition below: it maps to 'shared' exactly those events that
+  # satisfy that condition, plus the 'unlabeled' event of the gating label.
+  group: |-
+    ${{
+      github.workflow
+    }}-${{
+      (github.event_name == 'pull_request')
+      && format('pr-{0}', github.event.number) || github.ref
+    }}-${{
+      (github.event_name == 'pull_request'
+       && (((github.event.action == 'labeled' || github.event.action == 'unlabeled')
+            && github.event.label.name != 'pr: dev-coverage')
+           || (github.event.action != 'labeled'
+               && github.event.action != 'unlabeled'
+               && !contains(github.event.pull_request.labels.*.name, 'pr: dev-coverage'))))
+      && github.run_id || 'shared'
+    }}
   cancel-in-progress: ${{ github.event_name != 'schedule' }}
 
 jobs:
 
-  build:
-    name: Build
+  start:
+    name: Start
     # Only run scheduled jobs if explicitly enabled for that repo (e.g.: not on forks)
-    # Only run pull request jobs if labelled as needing an coverage run
+    # Only run pull request jobs if labelled as needing a coverage run
     # Always run workflow dispatch jobs
     if: |
       (github.event_name == 'schedule'
         && vars.ENABLE_SCHEDULED_JOBS == 'true') ||
       (github.event_name == 'pull_request'
-        && contains(github.event.pull_request.labels.*.name, 'pr: dev-coverage')) ||
+        && ((github.event.action == 'labeled'
+             && github.event.label.name == 'pr: dev-coverage')
+            || (github.event.action != 'labeled'
+                && github.event.action != 'unlabeled'
+                && contains(github.event.pull_request.labels.*.name, 'pr: dev-coverage')))) ||
       (github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-slim
+    steps:
+      - name: Save the pull request number
+        if: ${{ github.event_name == 'pull_request' }}
+        run: echo "${{ github.event.number }}" > pr-number.txt
+
+      - name: Upload the pull request number
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: pr-number
+          path: pr-number.txt
+          overwrite: true
+
+  build:
+    name: Build
+    needs: start
     uses: ./.github/workflows/reusable-build.yml
     with:
+      cc: gcc
+      dev-gcov: true
+      runs-on: ubuntu-26.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 +102,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-26.04
       suite: ${{ matrix.test }}${{ matrix.num }}
-      dev-gcov: 1
     strategy:
       fail-fast: false
       matrix:
@@ -71,13 +118,13 @@ jobs:
     name: Publish results to codecov.io
     needs: test
     if: ${{ contains(needs.*.result, 'success') && !cancelled() }}
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.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 +137,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@303a32d7a59b442fa8d48b6a1cc6825c09c847a5  # v7
         with:
           disable_file_fixes: true
           disable_search: true
@@ -104,28 +151,26 @@ jobs:
     name: Prepare HTML report
     needs: [build, test]
     if: ${{ contains(needs.*.result, 'success') && !cancelled() }}
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.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 +181,40 @@ 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 coverage status
         if: ${{ github.event_name == 'pull_request' }}
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          path: repo/coverage-status.txt
+          name: coverage-status
+          overwrite: true
+          # Not written if the coverage could not be read, see the script above
+          if-no-files-found: ignore
+
+      - name: Upload PR notification
+        if: ${{ github.event_name == 'pull_request' }}
+        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)
@@ -188,14 +222,14 @@ jobs:
     name: Create issue on failure
     needs: [publish-codecov, prepare-report]
     if: ${{ github.event_name == 'schedule' && github.repository == 'verilator/verilator' && github.run_attempt == 1 && failure() && !cancelled() }}
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-slim
     steps:
       # 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

.github/workflows/docker.yml

@@ -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@99012661954931238ded8c8b007157a8430204e1  # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069  # 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@c3c9e263c25d99ce0380d002d59b67737d91b0dc  # v7
         if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
         with:
           context: ${{ env.build_context }}

.github/workflows/format.yml

@@ -11,35 +11,76 @@ on:
 permissions:
   contents: write
 
+defaults:
+  run:
+    working-directory: repo
+
+concurrency:
+  # At most 1 run per branch: the job pushes what 'make format' changed, so
+  # concurrent runs on the same branch race on that push. Cancel the run in
+  # progress, as the newer one formats a tree that already holds its commits.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 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
+      # On the main repository, push as the Verilator CI app.
+      # Forks do not have the app, so fall back to GITHUB_TOKEN there.
+      - name: Generate access token
+        id: generate-token
+        if: ${{ github.repository == 'verilator/verilator' }}
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
         with:
-          token: ${{ secrets.GITHUB_TOKEN }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
+          private-key: ${{ secrets.VERILATOR_CI_KEY }}
+          owner: verilator
+          repositories: verilator
+          permission-contents: write
+
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          path: repo
+          token: ${{ steps.generate-token.outputs.token || secrets.GITHUB_TOKEN }}
+
       - name: Install packages for build
+        uses: ./repo/.github/actions/install-deps
+        with:
+          stage: format
+
+      - name: Configure git identity
         env:
-          CI_BUILD_STAGE_NAME: build
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          APP_SLUG: ${{ steps.generate-token.outputs.app-slug }}
         run: |
-          sudo apt install clang-format-18 || \
-          sudo apt install clang-format-18
-          git config --global user.email "action@example.com"
-          git config --global user.name "github action"
-      - name: Format code
+          if [ -n "$APP_SLUG" ]; then
+            user_id=$(gh api "/users/${APP_SLUG}[bot]" --jq .id)
+            git config --global user.email "${user_id}+${APP_SLUG}[bot]@users.noreply.github.com"
+            git config --global user.name "${APP_SLUG}[bot]"
+          else
+            git config --global user.email "[email protected]"
+            git config --global user.name "github action"
+          fi
+
+      - 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

.github/workflows/pages.yml

@@ -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@v5
+        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@368f82528645a54fb793d4d04e342629a3f51346  # v5
+      - name: Deploy to GitHub Pages (retry)
+        id: deploy-2
+        if: steps.deploy-1.outcome == 'failure'
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346  # 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

.github/workflows/pr-automation.yml

@@ -0,0 +1,281 @@
+---
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+# Drives the automation of a pull request.
+
+name: Maintenance - PR automation
+
+on:
+  pull_request_target:  # 'pull_request' can have no write permissions
+    types: [opened, synchronize, reopened, closed]
+  workflow_run:  # To react to the result of a workflow on a pull request
+    workflows: ["Code coverage", "RTLMeter", "Regression"]
+    types: [completed]
+  push:  # A pull request can start conflicting when its base branch moves
+    branches: [master]
+permissions:
+  contents: read  # To check out the local action, everything else uses the CI app token
+
+defaults:
+  run:
+    shell: bash
+
+# One job per event source, to avoid startup churn. Use separate gated steps for actions
+jobs:
+  pr-event:
+    name: PR event
+    if: |
+      github.repository == 'verilator/verilator'
+      && github.event_name == 'pull_request_target'
+    runs-on: ubuntu-slim
+    steps:
+      # Label as the CI app, and not with 'github.token', as events from the
+      # latter do not create workflow runs, so the labels would drive nothing
+      - name: Generate access token
+        id: generate-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          client-id: ${{ vars.VERILATOR_CI_ID }}
+          private-key: ${{ secrets.VERILATOR_CI_KEY }}
+          permission-pull-requests: write
+
+      - name: "Add 'pr: regression' label on open"
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        if: ${{ github.event.action == 'opened' || github.event.action == 'reopened' }}
+        run: |-
+          gh pr edit "${{ github.event.number }}" \
+            --repo "${{ github.repository }}" \
+            --add-label 'pr: regression'
+
+      - name: "Optionally add 'pr: dev-coverage' label on open"
+        if: ${{ github.event.action == 'opened' || github.event.action == 'reopened' }}
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |-
+          # Grab changed files
+          FILES=$(gh api --paginate \
+            "repos/${{ github.repository }}/pulls/${{ github.event.number }}/files" \
+            --jq '.[].filename')
+          echo "Files changed:"
+          echo "${FILES}"
+          # Add label if src or include chagned
+          if grep -q -E '^(src|include)/' <<< "${FILES}"; then
+            gh pr edit "${{ github.event.number }}" \
+              --repo "${{ github.repository }}" \
+              --add-label 'pr: dev-coverage'
+          fi
+
+      - name: "Remove all 'pr*' labels on close"
+        if: ${{ github.event.action == 'closed' }}
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |-
+          # Filter in 'jq', so an empty result is not an error, as it is with 'grep'
+          LABELS=$(gh api \
+            "repos/${{ github.repository }}/issues/${{ github.event.number }}/labels?per_page=100" \
+            --jq '[.[].name | select(startswith("pr"))] | join(",")')
+          if [ -n "${LABELS}" ]; then
+            echo "Removing labels: ${LABELS}"
+            gh pr edit "${{ github.event.number }}" \
+              --repo "${{ github.repository }}" \
+              --remove-label "${LABELS}"
+          fi
+
+  conflicting:
+    name: Conflict check
+    # A pull request can start conflicting when its own head moves, or when the
+    # base branch moves under it, so sweep the open pull requests on both.
+    if: |
+      github.repository == 'verilator/verilator'
+      && (github.event_name == 'push'
+          || (github.event_name == 'pull_request_target'
+              && github.event.action == 'synchronize'))
+    runs-on: ubuntu-slim
+    steps:
+      # Label as the CI app, and not with 'github.token', as events from the
+      # latter do not create workflow runs, so the labels would drive nothing
+      - name: Generate access token
+        id: generate-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          client-id: ${{ vars.VERILATOR_CI_ID }}
+          private-key: ${{ secrets.VERILATOR_CI_KEY }}
+          permission-pull-requests: write
+
+      - name: "Update the 'pr-blocked: needs-rebase' label"
+        uses: eps1lon/actions-label-merge-conflict@0273be72a0bbd58fcd71d0d6c02c209b50d1e5e1  # 3.1.0
+        with:
+          dirtyLabel: "pr-blocked: needs-rebase"
+          repoToken: ${{ steps.generate-token.outputs.token }}
+
+  regression-complete:
+    name: Regression complete
+    if: |
+      github.repository == 'verilator/verilator'
+      && github.event_name == 'workflow_run'
+      && github.event.workflow_run.name == 'Regression'
+      && github.event.workflow_run.event == 'pull_request'
+      && (github.event.workflow_run.conclusion == 'success'
+          || github.event.workflow_run.conclusion == 'failure')
+    runs-on: ubuntu-slim
+    steps:
+      # Label as the CI app, and not with 'github.token', as events from the
+      # latter do not create workflow runs, so the labels would drive nothing
+      - name: Generate access token
+        id: generate-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          client-id: ${{ vars.VERILATOR_CI_ID }}
+          private-key: ${{ secrets.VERILATOR_CI_KEY }}
+          permission-actions: read
+          permission-pull-requests: write
+
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          sparse-checkout: .github/actions/update-pr-label
+
+      - name: Get the pull request number
+        id: pr
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |-
+          # The run tells us which pull request it was for
+          if ! gh run download "${{ github.event.workflow_run.id }}" --name pr-number; then
+            echo "Run has no 'pr-number' artifact"
+            exit 0
+          fi
+          echo "number=$(cat pr-number.txt)" >> "$GITHUB_OUTPUT"
+
+      - name: "Update the 'pr-blocked: fix-regression' label"
+        if: ${{ steps.pr.outputs.number }}
+        uses: ./.github/actions/update-pr-label
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          pr-number: ${{ steps.pr.outputs.number }}
+          head-sha: ${{ github.event.workflow_run.head_sha }}
+          label: "pr-blocked: fix-regression"
+          set: ${{ github.event.workflow_run.conclusion == 'failure' }}
+
+  rtlmeter-complete:
+    name: RTLMeter complete
+    if: |
+      github.repository == 'verilator/verilator'
+      && github.event_name == 'workflow_run'
+      && github.event.workflow_run.name == 'RTLMeter'
+      && github.event.workflow_run.event == 'pull_request'
+      && (github.event.workflow_run.conclusion == 'success'
+          || github.event.workflow_run.conclusion == 'failure')
+    runs-on: ubuntu-slim
+    steps:
+      # Label as the CI app, and not with 'github.token', as events from the
+      # latter do not create workflow runs, so the labels would drive nothing
+      - name: Generate access token
+        id: generate-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          client-id: ${{ vars.VERILATOR_CI_ID }}
+          private-key: ${{ secrets.VERILATOR_CI_KEY }}
+          permission-actions: read
+          permission-pull-requests: write
+
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          sparse-checkout: .github/actions/update-pr-label
+
+      - name: Get the pull request number
+        id: pr
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |-
+          # The run tells us which pull request it was for
+          if ! gh run download "${{ github.event.workflow_run.id }}" --name pr-number; then
+            echo "Run has no 'pr-number' artifact"
+            exit 0
+          fi
+          echo "number=$(cat pr-number.txt)" >> "$GITHUB_OUTPUT"
+
+      - name: "Update the 'pr-blocked: fix-rtlmeter' label"
+        if: ${{ steps.pr.outputs.number }}
+        uses: ./.github/actions/update-pr-label
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          pr-number: ${{ steps.pr.outputs.number }}
+          head-sha: ${{ github.event.workflow_run.head_sha }}
+          label: "pr-blocked: fix-rtlmeter"
+          set: ${{ github.event.workflow_run.conclusion == 'failure' }}
+
+  coverage-complete:
+    name: Coverage complete
+    if: |
+      github.repository == 'verilator/verilator'
+      && github.event_name == 'workflow_run'
+      && github.event.workflow_run.name == 'Code coverage'
+      && github.event.workflow_run.event == 'pull_request'
+      && (github.event.workflow_run.conclusion == 'success'
+          || github.event.workflow_run.conclusion == 'failure')
+    runs-on: ubuntu-slim
+    steps:
+      # Label as the CI app, and not with 'github.token', as events from the
+      # latter do not create workflow runs, so the labels would drive nothing
+      - name: Generate access token
+        id: generate-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
+        with:
+          client-id: ${{ vars.VERILATOR_CI_ID }}
+          private-key: ${{ secrets.VERILATOR_CI_KEY }}
+          permission-actions: read
+          permission-pull-requests: write
+
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          sparse-checkout: .github/actions/update-pr-label
+
+      - name: Get the pull request number
+        id: pr
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |-
+          # The run tells us which pull request it was for
+          if ! gh run download "${{ github.event.workflow_run.id }}" --name pr-number; then
+            echo "Run has no 'pr-number' artifact"
+            exit 0
+          fi
+          echo "number=$(cat pr-number.txt)" >> "$GITHUB_OUTPUT"
+
+      - name: "Update the 'pr-blocked: fix-dev-coverage' label"
+        if: ${{ steps.pr.outputs.number }}
+        uses: ./.github/actions/update-pr-label
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          pr-number: ${{ steps.pr.outputs.number }}
+          head-sha: ${{ github.event.workflow_run.head_sha }}
+          label: "pr-blocked: fix-dev-coverage"
+          set: ${{ github.event.workflow_run.conclusion == 'failure' }}
+
+      - name: Get the line coverage
+        id: coverage
+        if: ${{ github.event.workflow_run.conclusion == 'success' }}
+        env:
+          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
+        run: |-
+          # Whether every line the patch touches is covered
+          if ! gh run download "${{ github.event.workflow_run.id }}" --name coverage-status; then
+            echo "Run has no 'coverage-status' artifact"
+            exit 0
+          fi
+          echo "covered=$(cat coverage-status.txt)" >> "$GITHUB_OUTPUT"
+
+      - name: "Update the 'pr-blocked: improve-coverage' label"
+        if: ${{ steps.pr.outputs.number && steps.coverage.outputs.covered }}
+        uses: ./.github/actions/update-pr-label
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          pr-number: ${{ steps.pr.outputs.number }}
+          head-sha: ${{ github.event.workflow_run.head_sha }}
+          label: "pr-blocked: improve-coverage"
+          set: ${{ steps.coverage.outputs.covered != 'true' }}

.github/workflows/pr-blocked.yml

@@ -0,0 +1,52 @@
+---
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+# Fails while a pull request carries a 'pr-blocked:*' label, so that it can be
+# used as a required status check to hold up the merge. The labels themselves
+# are set by hand, or by 'pr-automation.yml'.
+#
+# Note this runs from the pull request's own merge commit, so a pull request
+# can change the check itself, but any such change shows up in its review.
+#
+# It also runs on a push, and not only on a label change, as a check run is
+# reported against the head commit, and so every head needs one of its own.
+
+name: Maintenance - PR blocked
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+
+permissions:
+  pull-requests: read
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}
+  cancel-in-progress: true
+
+jobs:
+  not-blocked:
+    name: Not blocked
+    runs-on: ubuntu-slim
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - name: "Check for 'pr-blocked:*' labels"
+        run: |-
+          # Note these are the labels the pull request has now, and not the ones
+          # in 'github.event', which is a snapshot that can be stale when
+          # several are changed in one go
+          BLOCKED=$(gh pr view "${{ github.event.number }}" \
+            --repo "${{ github.repository }}" \
+            --json labels \
+            --jq '[.labels[].name | select(startswith("pr-blocked:"))] | join(", ")')
+          if [ -n "${BLOCKED}" ]; then
+            echo "::error::${BLOCKED}"
+            exit 1
+          fi
+          echo "Not blocked"

.github/workflows/pr-run-cleanup.yml

@@ -0,0 +1,42 @@
+---
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+# Deletes the skipped runs of the label gated workflows on pull requests.
+#
+# GitHub shows only the latest run of a workflow on a pull request, so a run
+# that was skipped hides an earlier run that is actually still in progress, and
+# the pull request then reads as though that workflow had finished and
+# everything is green. Every label change creates a run of every workflow that
+# triggers on label events, and label events cannot be filtered by label name
+# under 'on', so these runs cannot be prevented. Deleting them restores the
+# in-progress run in the UI.
+
+name: Maintenance - PR run cleanup
+
+on:
+  workflow_run:
+    workflows: ["Code coverage", "Regression", "RTLMeter"]
+    types: [completed]
+
+permissions:
+  actions: write
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  delete-skipped-run:
+    name: Delete skipped run
+    if: |
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'skipped'
+    runs-on: ubuntu-slim
+    steps:
+      - name: Delete run
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |-
+          echo "Deleting skipped '${{ github.event.workflow_run.name }}' run #${{ github.event.workflow_run.run_number }}"
+          gh api --method DELETE "repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}"

.github/workflows/regression.yml

@@ -0,0 +1,265 @@
+---
+# DESCRIPTION: Github actions config
+# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+
+name: Regression
+
+on:
+  push:
+    branches-ignore:
+      - 'dependabot/**'  # Avoid duplicates: only run the PR, not the push
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * 0'  # weekly
+
+permissions:
+  contents: read
+  actions: read
+
+defaults:
+  run:
+    working-directory: repo
+
+concurrency:
+  # At most 1 job per branch. Auto cancel on pull requests and on all forks.
+  # Of the pull request events, only one that starts a run, or that removes the
+  # 'pr: regression' label to cancel one, shares the group. The rest are
+  # skipped (a change of another label, or a payload that does not carry the
+  # label, like an 'opened' delivered after it was added), and a skipped run
+  # must not cancel the one in progress, so they are given a unique group.
+  # This way adding the label starts a run, removing it cancels the in-progress
+  # run, and anything else has no effect. Note such an event still creates a
+  # run of this workflow, which is skipped, and would then hide the one in
+  # progress on the pull request. 'pr-run-cleanup.yml' deletes those.
+  # Key pull request runs on the number: 'github.ref' is the base branch once
+  # the pull request is closed, so unlabel events would cancel base runs.
+  # NOTE: The last part of the group expression must be kept in sync with the
+  # 'start' job condition below: it maps to 'shared' exactly those events that
+  # satisfy that condition, plus the 'unlabeled' event of the gating label.
+  group: |-
+    ${{
+      github.workflow
+    }}-${{
+      (github.event_name == 'pull_request')
+      && format('pr-{0}', github.event.number) || github.ref
+    }}-${{
+      (github.event_name == 'pull_request'
+       && (((github.event.action == 'labeled' || github.event.action == 'unlabeled')
+            && github.event.label.name != 'pr: regression')
+           || (github.event.action != 'labeled'
+               && github.event.action != 'unlabeled'
+               && !contains(github.event.pull_request.labels.*.name, 'pr: regression'))))
+      && github.run_id || 'shared'
+    }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' || github.repository != 'verilator/verilator' }}
+
+jobs:
+
+  start:
+    name: Start
+    # Only run pull request jobs if labelled as needing a regression run.
+    # Always run push, workflow dispatch and scheduled jobs
+    if: |
+      (github.event_name == 'pull_request'
+        && ((github.event.action == 'labeled'
+             && github.event.label.name == 'pr: regression')
+            || (github.event.action != 'labeled'
+                && github.event.action != 'unlabeled'
+                && contains(github.event.pull_request.labels.*.name, 'pr: regression')))) ||
+      (github.event_name == 'push') ||
+      (github.event_name == 'workflow_dispatch') ||
+      (github.event_name == 'schedule')
+    runs-on: ubuntu-slim
+    defaults:
+      run:
+        working-directory: .  # The workflow default is not checked out here
+    steps:
+      - name: Enabled
+        run: echo "Regression is enabled for this run"
+
+      - name: Save the pull request number
+        if: ${{ github.event_name == 'pull_request' }}
+        run: echo "${{ github.event.number }}" > pr-number.txt
+
+      - name: Upload the pull request number
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: pr-number
+          path: pr-number.txt
+          overwrite: true
+
+  build-2604-gcc:
+    name: Build | 26.04 | gcc
+    needs: start
+    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
+    needs: start
+    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
+    needs: start
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: gcc
+      runs-on: ubuntu-24.04
+      sha: ${{ github.sha }}
+
+  build-2404-clang:
+    name: Build | 24.04 | clang
+    needs: start
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: clang
+      runs-on: ubuntu-24.04
+      sha: ${{ github.sha }}
+
+  build-2204-gcc:
+    name: Build | 22.04 | gcc
+    needs: start
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: gcc
+      runs-on: ubuntu-22.04
+      sha: ${{ github.sha }}
+
+  build-macos-26-clang:
+    name: Build | macos-26 | clang
+    needs: start
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      cc: clang
+      runs-on: macos-26
+      sha: ${{ github.sha }}
+
+  build-windows:
+    name: Build | windows-2025-vs2026 | msvc
+    needs: start
+    runs-on: windows-2025-vs2026
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7
+        with:
+          path: repo
+      - name: Cache win_flex_bison
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
+        with:
+          path: ${{ github.workspace }}/win_flex_bison
+          key: win_flex_bison
+      - name: compile
+        run: ./ci/ci-win-compile.ps1
+      - name: test build
+        run: ./ci/ci-win-test.ps1
+
+  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 | 24.04 | gcc | ${{ matrix.suite }}
+    needs: build-2404-gcc
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      archive: ${{ needs.build-2404-gcc.outputs.archive }}
+      cc: gcc
+      runs-on: ubuntu-24.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-clang:
+    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 }}
+      cc: clang
+      reloc: true  # Test with relocated installation
+      runs-on: ubuntu-24.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-2204-gcc:
+    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 }}
+      cc: gcc
+      runs-on: ubuntu-22.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]
+
+  lint-py:
+    name: Lint Python
+    needs: start
+    uses: ./.github/workflows/reusable-lint-py.yml
+
+  passed:
+    name: Regression tests passed  # This job is used as a required status check on PRs
+    if: ${{ !cancelled() && needs.start.result != 'skipped' }}
+    needs:
+      - start
+      - build-2604-gcc
+      - build-2604-clang
+      - build-2404-gcc
+      - build-2404-clang
+      - build-2204-gcc
+      - build-macos-26-clang
+      - build-windows
+      - test-2604-gcc
+      - test-2604-clang
+      - test-2404-gcc
+      - test-2404-clang
+      - test-2204-gcc
+      - lint-py
+    runs-on: ubuntu-slim
+    steps:
+      - name: Check all needed jobs succeeded
+        working-directory: .
+        run: jq -e 'all(.result == "success")' <<< '${{ toJSON(needs) }}'

.github/workflows/reusable-build.yml

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

.github/workflows/reusable-lint-py.yml

@@ -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,25 @@ 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:
+          # Check the event too: 'github.ref' is the base branch on a closed pull request
+          save: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/master' }}
 
       - name: Lint
         run: |-

.github/workflows/reusable-rtlmeter-build.yml

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

.github/workflows/reusable-rtlmeter-run.yml

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

.github/workflows/reusable-test.yml

@@ -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,45 @@ 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:
+          # Check the event too: 'github.ref' is the base branch on a closed pull request
+          save: ${{ github.event_name != 'pull_request' && 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 +113,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.event_name != 'pull_request' && github.ref == 'refs/heads/master' && 7 || 3 }}
+
       - name: Fail job if a test failed
         if: ${{ steps.run-test.outcome == 'failure' && !cancelled() }}
         run: |-

.github/workflows/rtlmeter-pr-results.yml

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

.github/workflows/rtlmeter.yml

@@ -22,8 +22,36 @@ defaults:
     shell: bash
 
 concurrency:
-  # At most 1 job per branch. Auto cancel all but scheduled jobs
-  group: ${{ github.workflow }}-${{ github.ref }}
+  # At most 1 job per branch. Auto cancel all but scheduled jobs.
+  # Of the pull request events, only one that starts a run, or that removes the
+  # 'pr: rtlmeter' label to cancel one, shares the group. The rest are
+  # skipped (a change of another label, or a payload that does not carry the
+  # label, like an 'opened' delivered after it was added), and a skipped run
+  # must not cancel the one in progress, so they are given a unique group.
+  # This way adding the label starts a run, removing it cancels the in-progress
+  # run, and anything else has no effect. Note such an event still creates a
+  # run of this workflow, which is skipped, and would then hide the one in
+  # progress on the pull request. 'pr-run-cleanup.yml' deletes those.
+  # Key pull request runs on the number: 'github.ref' is the base branch once
+  # the pull request is closed, so unlabel events would cancel base runs.
+  # NOTE: The last part of the group expression must be kept in sync with the
+  # 'start' job condition below: it maps to 'shared' exactly those events that
+  # satisfy that condition, plus the 'unlabeled' event of the gating label.
+  group: |-
+    ${{
+      github.workflow
+    }}-${{
+      (github.event_name == 'pull_request')
+      && format('pr-{0}', github.event.number) || github.ref
+    }}-${{
+      (github.event_name == 'pull_request'
+       && (((github.event.action == 'labeled' || github.event.action == 'unlabeled')
+            && github.event.label.name != 'pr: rtlmeter')
+           || (github.event.action != 'labeled'
+               && github.event.action != 'unlabeled'
+               && !contains(github.event.pull_request.labels.*.name, 'pr: rtlmeter'))))
+      && github.run_id || 'shared'
+    }}
   cancel-in-progress: ${{ github.event_name != 'schedule' }}
 
 jobs:
@@ -36,179 +64,257 @@ jobs:
       (github.event_name == 'schedule'
         && vars.ENABLE_SCHEDULED_JOBS == 'true') ||
       (github.event_name == 'pull_request'
-        && contains(github.event.pull_request.labels.*.name, 'pr: rtlmeter')) ||
+        && ((github.event.action == 'labeled'
+             && github.event.label.name == 'pr: rtlmeter')
+            || (github.event.action != 'labeled'
+                && github.event.action != 'unlabeled'
+                && contains(github.event.pull_request.labels.*.name, 'pr: rtlmeter')))) ||
       (github.event_name == 'workflow_dispatch') ||
       (github.event_name == 'push')
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.04
+    outputs:
+      old-sha: ${{ steps.start.outputs.old-sha }}
+      cases: ${{ steps.cases.outputs.cases }}
     steps:
+      - name: Save the pull request number
+        if: ${{ github.event_name == 'pull_request' }}
+        run: echo "${{ github.event.number }}" > pr-number.txt
+
+      - name: Upload the pull request number
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          name: pr-number
+          path: pr-number.txt
+          overwrite: true
+
+      - 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
+      ccwarn: false
+      install: true
+      runs-on: ubuntu-26.04
+      sha: ${{ github.sha }}
 
-  build-clang:
-    name: Build Clang
+  build-clang-new:
+    name: Build New Verilator - Clang
     needs: start
-    uses: ./.github/workflows/reusable-rtlmeter-build.yml
+    uses: ./.github/workflows/reusable-build.yml
     with:
-      runs-on: ubuntu-24.04
       cc: clang
+      ccwarn: false
+      install: true
+      runs-on: ubuntu-26.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-26.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-26.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
+      runs-on: ubuntu-26.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
+      runs-on: ubuntu-26.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
+      runs-on: ubuntu-26.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() }}
-    runs-on: ubuntu-24.04
-    strategy:
-      fail-fast: false
-      matrix:
-        tag: [gcc, clang, gcc-hier]
+    # 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-26.04
+    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
 
@@ -221,31 +327,30 @@ jobs:
     # dashboard UI currently assumes there is only one data point per
     # calendar day. Results from reruns can be imported manually if needed.
     if: ${{ github.event_name == 'schedule' && github.repository == 'verilator/verilator' && github.run_attempt == 1 && contains(needs.*.result, 'success') && !cancelled() }}
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.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 +377,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() }}
-    runs-on: ubuntu-24.04
+    if: ${{ github.event_name == 'pull_request' && github.repository == 'verilator/verilator' && needs.combine-results.result == 'success' }}
+    runs-on: ubuntu-26.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)
@@ -389,14 +435,14 @@ jobs:
     name: Create issue on failure
     needs: publish-scheduled-results
     if: ${{ github.event_name == 'schedule' && github.repository == 'verilator/verilator' && github.run_attempt == 1 && failure() && !cancelled() }}
-    runs-on: ubuntu-24.04
+    runs-on: ubuntu-26.04
     steps:
       # 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

AGENTS.md

@@ -0,0 +1,149 @@
+<!-- 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 tests 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 tests 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
+  issue number being fixed. No need for the PR number this will be added
+  during git squash. e.g `Support property case (#7721)`. The commit body message is
+  optional and common for non-trivial changes.

CMakeLists.txt

@@ -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.048
+    VERSION 5.053
     HOMEPAGE_URL https://verilator.org
     LANGUAGES CXX
 )
@@ -93,7 +93,36 @@ if(OBJCACHE_ENABLED)
 endif()
 
 find_package(BISON)
-find_package(FLEX)
+# Prefer the header installed with the selected generator, including through
+# symlinks such as Homebrew's bin/flex. Explicit cache entries take precedence.
+find_program(
+    FLEX_EXECUTABLE
+    NAMES flex win-flex win_flex
+    DOC "Path to the flex executable"
+)
+if(NOT FLEX_EXECUTABLE)
+    message(
+        FATAL_ERROR
+        "Cannot find Flex; set FLEX_EXECUTABLE to its executable path"
+    )
+endif()
+get_filename_component(flex_real_executable "${FLEX_EXECUTABLE}" REALPATH)
+get_filename_component(flex_bin_dir "${flex_real_executable}" DIRECTORY)
+find_path(
+    FLEX_INCLUDE_DIR
+    FlexLexer.h
+    PATHS "${flex_bin_dir}/../include" "${flex_bin_dir}"
+    NO_DEFAULT_PATH
+    DOC "Path to the flex headers"
+)
+find_path(FLEX_INCLUDE_DIR FlexLexer.h)
+if(NOT FLEX_INCLUDE_DIR)
+    message(
+        FATAL_ERROR
+        "Cannot find FlexLexer.h; set FLEX_INCLUDE_DIR to its directory"
+    )
+endif()
+mark_as_advanced(FLEX_EXECUTABLE FLEX_INCLUDE_DIR)
 
 # Build
 #set_property(GLOBAL PROPERTY JOB_POOLS one_job=1)
@@ -155,11 +184,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 +212,6 @@ install(
     PATTERN "include/*.cpp"
     PATTERN "include/*.vlt"
     PATTERN "include/*.sv"
-    PATTERN "include/gtkwave/*.[chv]*"
+    PATTERN "include/fstcpp/*.[chv]*"
     PATTERN "include/vltstd/*.[chv]*"
 )

Changes

@@ -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,6 +10,530 @@ The changes in each Verilator version are described below.  The
 contributors that suggested or implemented a given issue are shown in []. Thanks!
 
 
+Verilator 5.053 devel
+==========================
+
+**Other:**
+
+* Add covergroup runtime registry (#8134). [Matthew Ballance]
+* Add initial support for solo `binsof` (#8298). [Marco Bartoli]
+* Add `-fno-dead-members` and optimize dead class member functions (#8830).
+* Add `--coverage-max-bins` and `--coverage-max-real-bins` (#8499). [Marco Bartoli]
+* Remove deprecated `--structs-packed`.
+* Change internal module inlining to after V3Scope (#1539) (#8453). [Geza Lore, Testorrent USA, Inc.]
+* Change JSON dumps to suppress empty strings, etc.
+* Change `--protect` to use SHA512 per IEEE 1735.
+* Support multi-dimensional module instance arrays (#2675) (#8476). [Geza Lore, Testorrent USA, Inc.]
+* Support VPI interface references (#8081). [Todd Strader]
+* Support nested array and associative array element member access in constraint 1/4 - pre-cleanup (#8237). [Kamil Danecki, Antmicro Ltd.]
+* Support unique constraint inside std::randomize (#8241). [Kornel Uriasz, Antmicro Ltd.]
+* Support nested array and associative array element member access in constraint (#8244). [Kamil Danecki, Antmicro Ltd.]
+* Support rand dynamic arrays used inside `with` clause of randomize (#8246). [Kamil Danecki, Antmicro Ltd.]
+* Support multiplicity in SVA shapes that use NFA rings (#8267). [Artur Bieniek, Antmicro Ltd.]
+* Support non-overlapped property implications correctly (#8268). [Artur Bieniek, Antmicro Ltd.]
+* Support logic and set operations on binsof (#8306). [Marco Bartoli]
+* Support `illegal_bins` and `ignore_bins` for cross bins (#8372). [Marco Bartoli]
+* Support `iff` in covergroup bins (#8406) (#8407). [Marco Bartoli]
+* Support enclosing cross identifiers in bin selections (#8416). [Marco Bartoli]
+* Support dynamic cross layouts and fix covergroup bin exclusions priority (#8424). [Marco Bartoli]
+* Support automatic bins for enum coverpoints (#8462) (#8464). [David Harris]
+* Support empty queue literals as function and task arguments (#8501) (#8502). [Francesco Urbani]
+* Support covergroup fixed-size bin arrays (#8514). [Marco Bartoli]
+* Support wildcard bins (#8516). [Marco Bartoli]
+* Support coverpoint bin `with` filters (#8518). [Marco Bartoli]
+* Support waiting on clocking block event through modport (#8403) (#8530). [Saqib Khan]
+* Optimize NBA shadow copies for partial writes (#8266). [Artur Bieniek, Antmicro Ltd.]
+* Optimize recursion depth in DFG circular driver tracing (#8272). [Drew Risinger]
+* Optimize DFG synthesis symbol table ordering (#8282). [Geza Lore, Testorrent USA, Inc.]
+* Optimize redundant vertex cache lookups in DFG peephole (#8283). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG vertex iteration callbacks (#8284). [Geza Lore, Testorrent USA, Inc.]
+* Optimize redundant memoization in DFG CSE (#8285). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG synthesis of simple continuous assignments (#8286). [Geza Lore, Testorrent USA, Inc.]
+* Optimize more selects in DFG (#8292). [Geza Lore, Testorrent USA, Inc.]
+* Optimize netlist teardown when about to exit (#8294). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG algorithms with an open addressing hash table (#8307). [Geza Lore, Testorrent USA, Inc.]
+* Optimize data-type type chain recursion (#8310). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG vertex input edge storage (#8313). [Geza Lore, Testorrent USA, Inc.]
+* Optimize successive whole-element array assignments (#8316). [Patrick Creighton]
+* Optimize unnecessary per-vertex allocations in NFA lowering (#8319). [Artur Bieniek, Antmicro Ltd.]
+* Optimize duplicate lookup in NFA property recursion guard (#8321). [Artur Bieniek, Antmicro Ltd.]
+* Optimize NBA assertions by keeping all writers before readers (#8326). [Artur Bieniek, Antmicro Ltd.]
+* Optimize wide four-state constant operations in V3Number (#8333). [CatalpaEel]
+* Optimize split pass (#8385). [Geza Lore, Testorrent USA, Inc.]
+* Optimize covergroup bin metadata lookup (#8404). [Marco Bartoli]
+* Optimize dead ports (#8426). [Geza Lore, Testorrent USA, Inc.]
+* Optimize instance port connections by aliasing rather than by assignment (#8427). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG temporary sharing across module instances (#8456). [Michael Bedford Taylor]
+* Optimize modport resolution with many interface instances (#8496) (#8497). [Deanyone Su]
+* Optimize covergroup bin generation (#8499). [Marco Bartoli]
+* Optimize through-package variables in DFG. [Geza Lore, Testorrent USA, Inc.]
+* Optimize assertion control queries (#8547). [Artur Bieniek, Antmicro Ltd.]
+* Optimize sched-initial/static/final split to once per sub-function (#8549). [Krzysztof Bieganski, Antmicro Ltd.]
+* Optimize exhaustive case if-chains with an unconditional else (#8554). [Nick Brereton]
+* Move module inlining after V3Scope (#8453) (#1539). [Geza Lore, Testorrent USA, Inc.]
+* Fix array slice crash when used as a bare value (#5132) (#8262). [Marco Frank]
+* Fix function reference into generate case block (#5312) (#8532). [Hongseok Choi]
+* Fix pattern type matching against nested aggregates (#7304).
+* Fix covergroup-internal references multi-threaded ordering (#7779) (#8255). [Matthew Ballance]
+* Fix typedef through a parameterized sub-interface (#7943 repair) (#8124) (#8128). [em2machine]
+* Fix detecting non-inlined awaits in V3Delayed.cpp (#7982). [Igor Zaworski, Antmicro Ltd.]
+* Fix phased `solve...before` diversity (#8189) (#8194). [Aditya Shevade]
+* Fix array-size constraint on arrays inside base class (#8219). [Kornel Uriasz, Antmicro Ltd.]
+* Fix multidimensional packed array type handling (#8235). [Artur Bieniek, Antmicro Ltd.]
+* Fix library method argument references (#8252). [Geza Lore, Testorrent USA, Inc.]
+* Fix CMake to call Verilator Perl wrapper (#8269) (#8270) (#8311). [Drew Risinger]
+* Fix real values and unenforced rand/randc type-eligibility rules in constraints (#8273) (#8275) (#8276). [Aditya Shevade]
+* Fix assignment pattern default fill of an array of unpacked structs (#8289). [Nick Brereton]
+* Fix escape strings in pattern formatting (#8297). [Marco Bartoli]
+* Fix DECLFILENAME warning on nested declarations (#8302). [Martijn Wobbes]
+* Fix cache of boundary vertices in DFG cycle-breaking (#8308). [Shriyans Sahoo]
+* Fix property and sequence line coverage (#8314). [Andrii, Antmicro Ltd.]
+* Fix wide typed pattern formatting primitives (#8325). [Marco Bartoli]
+* Fix circular class inheritance hang (#8324) (#8545). [Saqib Khan]
+* Fix V3InstrCount with recursive functions (#8327) (#8361). [Geza Lore, Testorrent USA, Inc.]
+* Fix parameterized class nested in a parameterized interface (#8328) (#8329). [Kristof Marien]
+* Fix printing signed enums and wide enum names (#8338). [Marco Bartoli]
+* Fix ignoring cross_auto_bin_max instead of hard error (#8340). [Marco Bartoli]
+* Fix wide enum names (#8344) (#8362) (#8365) (#8366). [Marco Bartoli]
+* Fix class-qualified self reference to a typedef in a parameterized class (#8348) (#8349). [Dragon-Git]
+* Fix crash when elaborating a covergroup option through a forward class (#8351) (#8352). [Kristof Marien]
+* Fix missing implicit net for bufif/notif/nmos/pmos data input (#8353) (#8354). [Mike Murunov]
+* Fix %p format on class members (#8360). [Marco Bartoli]
+* Fix Docker compilation with --trace-fst (#8370). [Giuseppe Manzoni]
+* Fix NFA rings for bounded SVA delays (#8371). [Artur Bieniek, Antmicro Ltd.]
+* Fix DFG driver tracing of partial assignments (#8377) (#8397). [Geza Lore, Testorrent USA, Inc.]
+* Fix unique constraint with multiple arrays (#8378). [Kornel Uriasz, Antmicro Ltd.]
+* Fix access types of refs and inouts (#8380). [Igor Zaworski, Antmicro Ltd.]
+* Fix copy constructor of classes with constraints (#8381). [Ryszard Rozak, Antmicro Ltd.]
+* Fix C++ clang 18 compiler with -fno-slp-vectorize (#8383). [Geza Lore, Testorrent USA, Inc.]
+* Fix reevaluation of method calls in wait conditions (#8391). [Jesús Alberto López Soto]
+* Fix weighted dist constraints in presence of other constraints (#8392). [Kornel Uriasz, Antmicro Ltd.]
+* Fix error on non-existent interface ports (#8393). [Andrii Andrieiev, Antmicro Ltd.]
+* Fix compile-time blowup forcing large unpacked arrays (#8395). [Jonathan Drolet]
+* Fix false MULTIDRIVEN for writes in tasks never executed (#8401). [Artur Bieniek, Antmicro Ltd.]
+* Fix $c() inside a DPI export (#8402). [Nazar Zibilyuk]
+* Fix covergroup constructor initialization (#8410). [Marco Bartoli]
+* Fix issues with configuring flex during build on MacOS (#8412). [Kaleb Barrett]
+* Fix interface modport resolution against non-scope symbol tables (#8420). [Geza Lore, Testorrent USA, Inc.]
+* Fix FSM coverage hierarchy being emitted as an absolute path (#8421). [Geza Lore, Testorrent USA, Inc.]
+* Fix MSYS header include search to be after toolchain headers (#8422). [Kaleb Barrett]
+* Fix losing coverage declarations if first in a module body (#8425). [Geza Lore, Testorrent USA, Inc.]
+* Fix force read update sensitivity performance (#8431) (#8433). [Jonathan Drolet]
+* Fix streaming dynamic arrays with different element types failing to compile (#8434) (#8435). [Kristof Marien]
+* Fix internal error when task without C function is left in the tree (#8437). [Artur Bieniek, Antmicro Ltd.]
+* Fix nested random dynamic arrays internal error (#8438) (#8439). [Kristof Marien]
+* Fix elaboration of classes reached through deferred references (#8440) (#8510). [Ethan Sifferman]
+* Fix VPI discoverability of forceable unpacked struct members (#8445). [Bartłomiej Chmiel, Antmicro Ltd.]
+* Fix compound types in anonymous structs (#8449). [Artur Bieniek, Antmicro Ltd.]
+* Fix internal error on covergroup in a specialized parameterized class (#8450) (#8452). [David Harris]
+* Fix data race in type handling (#8451). [Tynan McAuley]
+* Fix $sscanf/$fscanf returning -1 after a partial match (#8457) (#8459). [David Harris]
+* Fix covergroup '0/'1 bin values not filling to coverpoint width (#8458) (#8460). [David Harris]
+* Fix embedded covergroup calling an enclosing class method (#8461) (#8463). [David Harris]
+* Fix unsized condition not reduced to one bit (#8465) (#8466). [David Harris]
+* Fix comma emission for nested JSON scopes (#8469) (#8474). [Noam Gallmann]
+* Fix model failing when host has fewer cores than --threads (#8475). [Artur Bieniek, Antmicro Ltd.]
+* Fix `##0` synchronous drive overriding later drives (#8482). [Marco Bartoli]
+* Fix disable fork and wait fork affecting pending NBA updates (#8483). [Marco Bartoli]
+* Fix nonblocking event trigger never firing in suspendable processes (#8485). [Marco Bartoli]
+* Fix setting status of finished process immediately (#8503). [Ryszard Rozak, Antmicro Ltd.]
+* Fix constant oversized shifts in V3Premit. [Geza Lore, Testorrent USA, Inc.]
+* Fix semaphore waiting on killed process (#8505). [Ryszard Rozak, Antmicro Ltd.]
+* Fix mis-setting of process state from FINISHED to KILLED (#8506). [Ryszard Rozak, Antmicro Ltd.]
+* Fix rand_mode(0) not preserving dynamic array of struct values used in a dist constraint (#8508) (#8509). [Kristof Marien]
+* Fix duplicate struct declaration when inlining (#8515). [Ethan Sifferman]
+* Fix bear version detection if uninstalled. [Geza Lore, Testorrent USA, Inc.]
+* Fix enums inside randomize() with (#8517). [Kornel Uriasz, Antmicro Ltd.]
+* Fix emitting public parameters (#8520). [Geza Lore, Testorrent USA, Inc.]
+* Fix verilator_coverage report to align with get_coverage() (#8522) (#8524) (#8531). [Marco Bartoli]
+* Fix verilator_coverage reports rounding incomplete coverage to 100.0% (#8523). [Jordan Carlin]
+* Fix extern class method rejects matching virtual interface argument type (#8525) (#8526). [Kristof Marien]
+* Fix of queue pop return value access (#8529) (#8511). [Igor Zaworski, Antmicro Ltd.]
+* Fix derived class construction resets inherited per-instance rand_mode state (#8527) (#8528). [Kristof Marien]
+* Fix crash on class handle passed to string port (#8536) (#8538). [Noam Gallmann]
+* Fix stack depth calculations over calls (#8544). [Nick Brereton]
+* Fix cascading errors after unsupported class dot reference in parameter value (#8551). [Martijn Wobbes, Antmicro Ltd.]
+* Fix vpi_put_value crash on NULL value pointer (#8553). [Nick Brereton]
+* Fix --hierarchical parameter specialization name collisions (#8555) (#8565). [Marco Bartoli]
+* Fix dehash of a suffix after a hashed name (#8556). [Ethan Sifferman]
+
+
+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
 ==========================
 
@@ -35,7 +561,7 @@ Verilator 5.048 2026-04-26
 * 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). [Nick Brereton]
+* 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]
@@ -179,7 +705,7 @@ Verilator 5.048 2026-04-26
 * 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
 ==========================
@@ -342,7 +868,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.]
@@ -686,7 +1212,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]
@@ -1477,7 +2003,7 @@ Verilator 5.016 2023-09-16
 * Optimize Verilator executable size by refactoring error reporting routines (#4446). [Anthony Donlon]
 * Optimize Verilation runtime pointers and graphs (#4396) (#4397) (#4398). [Krzysztof Bieganski, Antmicro Ltd]
 * Optimize preparations towards multithreaded Verilation (#4291) (#4463) (#4476) (#4477) (#4479).  [Kamil Rakoczy, Antmicro Ltd]
-* Fix Windows filename format, etc (#3873) (#4421). [Anthony Donlon].
+* Fix Windows filename format, etc (#3873) (#4421). [Anthony Donlon]
 * Fix t_dist_cppstyle Perl performance issue (#4085). [Srinivasan Venkataramanan]
 * Fix using type in parameterized classes without #() (#4281) (#4440). [Anthony Donlon]
 * Fix false INFINITELOOP on forever..mailbox.get() (#4323). [Srinivasan Venkataramanan]
@@ -2342,7 +2868,6 @@ Verilator 4.108 2021-01-10
 * Fix to ignore coverage on real ports (#2741) (#2745). [Paul Wright]
 
 
-
 Verilator 4.106 2020-12-02
 ==========================
 
@@ -2749,7 +3274,6 @@ Verilator 4.018 2019-08-29
 * Fix internal error on gate optimization of assign. (#1475) [Oyvind Harboe]
 
 
-
 Verilator 4.016 2019-06-16
 ==========================
 
@@ -3264,7 +3788,7 @@ Verilator 3.880 2015-12-19
 * Fix model restore crash. (#1013) [Jason McMullan]
 * Fix arrayed instances to unpacked of same size. (#1015) [Varun Koyyalagunta]
 * Fix slices of unpacked arrays with non-zero LSBs.
-* Fix ternary operation with unpacked array. (#1017) [Varun Koyyalagunta].
+* Fix ternary operation with unpacked array. (#1017) [Varun Koyyalagunta]
 
 
 Verilator 3.878 2015-11-01
@@ -3354,7 +3878,7 @@ Verilator 3.870 2015-02-12
 
 * Suppress COMBDLY when inside always_latch. (#864) [Iztok Jeras]
 * Support cast operator with expression size. (#865) [Iztok Jeras]
-* Add warning on slice selection out of bounds. (#875) [Cong Van Nguyen].
+* Add warning on slice selection out of bounds. (#875) [Cong Van Nguyen]
 * Fix member select error broke in 3.868. (#867) [Iztok Jeras]
 * Fix $sccanf from string. (#866) [David Pierce]
 * Fix VM_PARALLEL_BUILDS broke in 3.868. (#870) [Hiroki Honda]
@@ -5200,7 +5724,6 @@ Verilator 3.270 2004-10-15
 * Fix numeric fault when dividing by zero.
 
 
-
 Verilator 3.260 2004-10-07
 ==========================
 
@@ -5539,7 +6062,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:**

LICENSES/BSD-2-Clause.txt

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

Makefile.in

@@ -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*'
@@ -709,6 +747,7 @@ FASTCOV_OPT += BROKEN_RTN
 FASTCOV_OPT += NUM_ASSERT
 FASTCOV_OPT += SELF_CHECK
 FASTCOV_OPT += UASSERT
+FASTCOV_OPT += UDEBUGONLY
 FASTCOV_OPT += UINFO
 FASTCOV_OPT += assert
 FASTCOV_OPT += 'if (VL_UNCOVERABLE'
@@ -723,6 +762,8 @@ 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
+GENHTML_OPT += --ignore-errors empty
 ifeq ($(COVERAGE_REF_BASE),)
 GENHTML_OPT += --header-title "Code coverage for Verilator $(shell git describe --dirty)"
 else
@@ -754,7 +795,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 +804,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)

README.rst

@@ -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/regression.yml?branch=master&label=regression
+   :target: https://github.com/verilator/verilator/actions/workflows/regression.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, including UVM
+          - 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
 ===================
 
@@ -68,15 +75,14 @@ instantiate the model. The resulting Verilated executable performs the
 design simulation. Verilator also supports linking Verilator-generated
 libraries, optionally encrypted, into other simulators.
 
-Verilator supports all design constructs, most verification constructs,
-intra-assignment delays (e.g, `#10`), and events. Tristate-bus (`z`) and
-unknowns (`x`) are handled in limited contexts, in a special manor for
-performance. It currently may not be the best choice if you are expecting a
-full-featured replacement for a closed-source Verilog simulator, performing
-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.
-
+Verilator supports all design constructs, most verification constructs
+including UVM, intra-assignment delays (e.g, `#10`), and events.
+Tristate-bus (`z`) and unknowns (`x`) are handled in limited contexts, in a
+special manor for performance. It currently may not be the best choice if
+you are expecting a full-featured replacement for a closed-source Verilog
+simulator, performing 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

REUSE.toml

@@ -4,9 +4,9 @@ version = 1
 
 [[annotations]]
 path = [
+    "**/.clang-format",
     "**/.gitattributes",
     "**/.gitignore",
-    ".clang-format",
     ".clang-tidy",
     ".codacy.yml",
     ".devcontainer/devcontainer.json",

bin/verilator

@@ -101,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
@@ -113,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()
@@ -136,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"
@@ -200,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'");
@@ -210,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;
@@ -357,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
@@ -375,7 +419,10 @@ detailed descriptions of these arguments.
     --coverage-expr-max <value>     Maximum permutations allowed for an expression
     --coverage-fsm              Enable FSM state/arc coverage
     --coverage-line             Enable line coverage
+    --coverage-max-bins <value>        Maximum bins of an integral coverpoint bins declaration
+    --coverage-max-real-bins <value>   Maximum bins of a real coverpoint bins declaration
     --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
@@ -393,6 +440,7 @@ 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
@@ -416,6 +464,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
@@ -588,11 +638,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
@@ -604,6 +656,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
 
 

bin/verilator_coverage

@@ -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>...
@@ -176,7 +180,9 @@ L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
     --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.

bin/verilator_profcfunc

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

ci/ci-build.bash

@@ -0,0 +1,103 @@
+#!/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
+if [ "$(uname -s)" = Darwin ]; then
+  # Force the use of the Homebrew flex over the one included as part of the
+  # Apple SDK that's preinstalled on the MacOS Github Action runners.
+  FLEX_PREFIX=$(brew --prefix flex)
+  export LEX="$FLEX_PREFIX/bin/flex"
+  export CPPFLAGS="${CPPFLAGS:+$CPPFLAGS }-I$FLEX_PREFIX/include"
+fi
+autoconf
+./configure $CONFIGURE_ARGS CXX="$CXX"
+
+################################################################################
+# Build
+
+ccache -z
+BUILD_START=$SECONDS
+"$MAKE" -j "$NPROC" -k
+# Second make to get failures at bottom, to avoid needing to
+# scroll up GitHub action logs (to see first errors half-way up)
+"$MAKE" -j "$NPROC" -k
+ccache -svv
+ccache --evict-older-than "$((SECONDS - BUILD_START + 60))s"
+ccache -svv

ci/ci-common.bash

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

ci/ci-coverage-report.bash

@@ -0,0 +1,133 @@
+#!/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
+
+###############################################################################
+# Create the coverage status
+###############################################################################
+
+# 'pr-automation.yml' labels the pull request from this. Note it is only
+# written when the coverage could actually be determined, so that a report we
+# could not read leaves the labels of the pull request alone.
+
+if [ -f ${COVERAGE_DIR}/empty-patch ]; then
+  # Nothing to cover, so count it as covered
+  COVERED=true
+else
+  # Take the counts, and not the percentage, which is rounded. The line reads
+  # for example "  lines......: 100.00% (60 of 60 lines)"
+  COUNTS=$(sed -nE 's/^ *lines\.*: *[0-9.]+% \(([0-9]+) of ([0-9]+) lines\).*/\1 \2/p' \
+             ${MAKE_LOG} | tail -n 1)
+  HIT=${COUNTS%% *}
+  TOTAL=${COUNTS##* }
+  if [ -z "${TOTAL}" ]; then
+    echo "Could not read the line coverage from ${MAKE_LOG}" >&2
+    COVERED=
+  elif [ "${HIT}" = "${TOTAL}" ]; then
+    COVERED=true
+  else
+    COVERED=false
+  fi
+fi
+
+if [ -n "${COVERED}" ]; then
+  echo "Line coverage complete: ${COVERED}"
+  echo "${COVERED}" > coverage-status.txt
+fi

ci/ci-install.bash

@@ -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,141 +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
+
+# 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
+
+# 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_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'"
-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
+# 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 [ "$CI_OS_NAME" = "linux" ]; then
+  if [ "$HOST_OS" = "linux" ]; then
     _platform="linux-x86_64"
-  elif [ "$CI_OS_NAME" = "osx" ]; then
+  elif [ "$HOST_OS" = "macOS" ]; then
     _platform="macos-arm64"
-  elif [ "$CI_OS_NAME" = "windows" ]; then
-    _platform="windows-x86_64"
   else
-    echo "WARNING: No wavetools binary available for CI_OS_NAME=$CI_OS_NAME, skipping"
+    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}"
-  if [ "$CI_OS_NAME" = "windows" ]; then
-    wget -q -O "${_tmpdir}/${_archive}.zip" "${_base_url}/${_archive}.zip"
-    unzip -o "${_tmpdir}/${_archive}.zip" -d "${_tmpdir}"
-  else
-    wget -q -O "${_tmpdir}/${_archive}.tar.gz" "${_base_url}/${_archive}.tar.gz"
-    tar -xzf "${_tmpdir}/${_archive}.tar.gz" -C "${_tmpdir}"
-  fi
+  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 [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
+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-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

ci/ci-pages-notify.bash

@@ -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?name=pr-notification" --jq '.artifacts[].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

ci/ci-pages.bash

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

ci/ci-rtlmeter-cases.py

@@ -0,0 +1,226 @@
+#!/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),
+        ("HammerBlade:16x8:*",                   5),
+        ("HammerBlade:2x1:*",                    3),
+        ("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),
+        ("HammerBlade:16x8:*",                   4),
+        ("HammerBlade:2x1:*",                    2),
+        ("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),
+        ("HammerBlade:16x8:*",                   5),
+        ("HammerBlade:2x1:*",                    3),
+        ("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),
+        ("HammerBlade:16x8:*",                   4),
+        ("HammerBlade:2x1:*",                    2),
+        ("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=(",", ":")))

ci/ci-rtlmeter-report.bash

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

ci/ci-rtlmeter-report.py

@@ -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)

ci/ci-script.bash

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

ci/ci-test.bash

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

ci/ci-win-compile.ps1

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

ci/ci-win-test.ps1

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

ci/docker/buildenv/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
 
 .. _verilator build docker container:
 

ci/docker/run/Dockerfile

@@ -29,6 +29,7 @@ RUN apt-get update \
                         python3 \
                         zlib1g \
                         zlib1g-dev \
+                        liblz4-dev \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 

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
 
 Verilator Executable Docker Container
 =====================================

configure.ac

@@ -12,7 +12,7 @@
 # Then 'make maintainer-dist'
 #AC_INIT([Verilator],[#.### YYYY-MM-DD])
 #AC_INIT([Verilator],[#.### devel])
-AC_INIT([Verilator],[5.048 2026-04-26],
+AC_INIT([Verilator],[5.053 devel],
         [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],
@@ -249,6 +264,7 @@ fi
 python3_version=$($PYTHON3 --version | head -1)
 AC_MSG_RESULT([$PYTHON3 --version = $python3_version])
 
+AC_ARG_VAR([LEX], [Flex executable])
 AC_CHECK_PROG(LEX,flex,flex)
 if test "x$LEX" = "x" ; then
    AC_MSG_ERROR([Cannot find "flex" in your PATH, please install it])
@@ -256,6 +272,22 @@ fi
 flex_version=$($LEX --version | head -1)
 AC_MSG_RESULT([$LEX --version = $flex_version])
 
+# Use the header installed with the selected generator.
+flex_include=$($PYTHON3 -c '
+import pathlib
+import shutil
+import sys
+print(pathlib.Path(shutil.which(sys.argv@<:@1@:>@) or sys.argv@<:@1@:>@).resolve().parent.parent / "include")
+' "$LEX")
+if test -f "$flex_include/FlexLexer.h"; then
+   if test -n "$MSYSTEM"; then
+      # Search MSYS Flex headers after the active toolchain's system headers.
+      CPPFLAGS="$CPPFLAGS -idirafter $flex_include"
+   else
+      CPPFLAGS="$CPPFLAGS -I$flex_include"
+   fi
+fi
+
 AC_CHECK_PROG(YACC,bison,bison)
 if test "x$YACC" = "x" ; then
    AC_MSG_ERROR([Cannot find "bison" in your PATH, please install it])
@@ -421,8 +453,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 +486,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 +549,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 +580,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 +663,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 +700,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 +715,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

docs/AGENTS.md

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

docs/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
 
 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!

docs/CONTRIBUTORS

@@ -1,14 +1,23 @@
 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.
 
+00>> Please insert into sorted position, and see header as to agreement
+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,17 +30,24 @@ 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
+CatalpaEel
 Chih-Mao Chen
 Chris Bachhuber
 Chris Randall
@@ -41,33 +57,48 @@ Chuxuan Wang
 Chykon
 Congcong Cai
 Conor McCullough
+Cookie
 Dan Ruelas-Petrisko
 Daniel Bates
 Danny Oler
 Dave Sargeant
+David Garau
+David Harris
 David Horton
 David Ledger
 David Metz
 David Stanford
 David Turner
+Deanyone Su
+dependabot[bot]
 Dercury
+Demin Han
 Diego Roux
 Dominick Grochowina
 Don Williamson
+Dragon-Git
 Drew Ranck
+Drew Risinger
 Drew Taussig
 Driss Hafdi
 Edgar E. Iglesias
+Edmund Lam
+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
+Francesco Urbani
 Frans Skarman
 Fuad Ismail
 Furqan Nadir
@@ -88,6 +119,8 @@ Gökçe Aydos
 Han Qi
 Harald Heckmann
 Hennadii Chernyshchyk
+hjsanjana
+Hongseok Choi
 Howard Su
 Huang Rui
 Huanghuang Zhou
@@ -99,6 +132,8 @@ Ilya Barkov
 Iru Cai
 Ivan Vnučec
 Iztok Jeras
+JAEUK LEE
+Jaeuk Lee (이재욱)
 Jake Merdich
 Jakub Michalski
 Jakub Wasilewski
@@ -113,9 +148,12 @@ Jamie Iles
 Jan Van Winkel
 Jean Berniolles
 Jean-Nicolas Strauss
+Jeffrey Song
+jeffrey.song
 Jens Yuechao Liu
 Jeremy Bennett
 Jesse Taube
+Jesús Alberto López Soto
 Jevin Sweval
 Jiacheng Qian
 Jiamin Zhu
@@ -137,6 +175,8 @@ Jose Loyola
 Josep Sans
 Joseph Nwabueze
 Josh Redford
+Joshua Leahy
+JOTEGO (Jose Tejada)
 Julian Carrier
 Julian Daube
 Julie Schwartz
@@ -150,6 +190,8 @@ Kefa Chen
 Keith Colbert
 Kevin Kiningham
 Kevin Nygaard
+Kornel Uriasz
+Kristof Marien
 Kritik Bhimani
 Krzysztof Bieganski
 Krzysztof Boronski
@@ -160,9 +202,11 @@ Krzysztof Sychla
 Kuba Ober
 Lan Zongwei
 Larry Doolittle
+Laurent CHARRIER
 Leela Pakanati
 Liam Braun
 Luca Colagrande
+Lucas Amaral
 Ludwig Rogiers
 Lukasz Dalek
 M2kar
@@ -170,11 +214,14 @@ Maarten De Braekeleer
 Maciej Sobkowski
 Marcel Chang
 Marco Bartoli
+Marco Brambilla
+Marco Frank
 Marco Widmer
 Mariusz Glebocki
 Markus Krause
 Marlon James
 Marshal Qiao
+Martijn Wobbes
 Martin Schmidt
 Martin Stadler
 Mateusz Gancarz
@@ -185,28 +232,39 @@ Maxim Fonarev
 Michael Bedford Taylor
 Michael Bikovitsky
 Michael Killough
+Michael Rogenmoser
 Michal Czyz
 Michaël Lefebvre
+Miguel Perez Andrade
+Mike Murunov
 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
+Nazar Zibilyuk
 Nick Brereton
+Nikolai Kumar
 Nikolay Puzanov
+Noam Gallmann
 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
@@ -236,29 +294,44 @@ Rowan Goemans
 Rupert Swarbrick
 Ryan Ziegler
 Ryszard Rozak
+Saksham Gupta
 Samuel Riedel
+Saqib Khan
 Sean Cross
 Sebastien Van Cauwenberghe
+Secturion
+Sergey Chusov
 Sergey Fedorov
 Sergi Granell
 Seth Pellegrino
+Shashvat Prabhu
 Shogo Yamazaki
 Shou-Li Hsu
+Shriyans Sahoo
+spomatasmd
 Srinivasan Venkataramanan
 Stefan Wallentowitz
 Stephen Henry
 Steven Hugg
+Stuart Morris
+sumpster
 Szymon Gizler
+Szymon Jędras
 Sören Tempel
+Sumanth Kadiyala
+Sunimali Rathnayake
 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
@@ -267,8 +340,11 @@ Tracy Narine
 Trung Nguyen
 Tudor Timi
 Tymoteusz Blazejczyk
+Tynan McAuley
+Tyrone Marhguy
 Udaya Raj Subedi
 Udi Finkelstein
+UnsignedByte
 Unai Martinez-Corral
 Valentin Atepalikhin
 Varun Koyyalagunta
@@ -280,12 +356,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
@@ -296,12 +375,7 @@ Zhen Yan
 Zhou Shen
 Zhouyi Shen
 Zixi Li
-apocelipes
-dependabot[bot]
-february cozzocrea
-sumpster
-em2machine
-emmettifelts
+Zubin Jain
 Àlex Torregrosa
 Ícaro Lima
-Yogish Sekhar
+ÍÍ>> Please insert into sorted position, and see header as to agreement

docs/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
 
 Verilator Documentation
 =======================

docs/gen/ex_DIDNOTCONVERGE_msg.rst

@@ -1,5 +1,5 @@
 .. comment: generated by t_lint_didnotconverge_bad
 .. 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
+   -V{t#,#}         'stl' region trigger index 0 is active: @([hybrid] b)
+   %Error-DIDNOTCONVERGE: Settle region did not converge after '--converge-limit' of 10000 tries

docs/gen/ex_DIDNOTCONVERGE_nodbg_msg.rst

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

docs/gen/ex_FINALDLY_faulty.rst

@@ -0,0 +1,7 @@
+.. comment: generated by t_finaldly_bad
+.. code-block:: sv
+   :linenos:
+   :emphasize-lines: 2
+
+     bit foo;
+     final foo <= 1;  // <--- Error

docs/gen/ex_FINALDLY_msg.rst

@@ -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;
+         |             ^~

docs/gen/ex_MULTIDRIVENPROC_faulty.rst

@@ -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;

docs/gen/ex_MULTIDRIVENPROC_loopidx.rst

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

docs/gen/ex_MULTIDRIVENPROC_msg.rst

@@ -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;
+         |                         ^

docs/gen/ex_MULTIDRIVEN_alwaysff_faulty.rst

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

docs/gen/ex_NOTREDOP_msg.rst

@@ -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;
+         |                 ^

docs/gen/ex_SIMILARNAME_faulty.rst

@@ -0,0 +1,6 @@
+.. comment: generated by t_lint_similarname_bad
+.. code-block:: sv
+   :linenos:
+
+     reg i;
+     wire I;

docs/gen/ex_SIMILARNAME_msg.rst

@@ -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;
+         |       ^

docs/guide/changes.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
 
 ****************
 Revision History

docs/guide/connecting.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
 
 .. _connecting:
 
@@ -28,17 +29,41 @@ 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.
 
 
+.. _model header include macros:
+
+Model Header Include Macros
+---------------------------
+
+Code compiled with the generated :file:`{prefix}.mk`, or with the CMake
+``verilate()`` command, gets preprocessor macros that expand to the model
+header includes, so user C++ need not hard-code the :vlopt:`--prefix`:
+
+.. code-block:: C++
+
+   #include VM_PREFIX_INCLUDE      // e.g. <Vtop.h>
+   #include VM_PREFIX_INCLUDE_DPI  // e.g. <Vtop__Dpi.h>
+
+``VM_PREFIX_INCLUDE_DPI`` is defined only when Verilator generates the
+:file:`{prefix}__Dpi.h` header, which is the case for designs with DPI and
+also for public-signal access such as :vlopt:`--public-flat-rw`. Using it
+otherwise is a compile-time error.
+
+A target built from several models defines each macro once, naming the
+first model, as one target has one set of preprocessor definitions. Code
+that must reach a second model's header names it directly.
+
+
 .. _porting from pre 4.210:
 
 Model interface changes in version 4.210
@@ -58,22 +83,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 +116,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 +213,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:
@@ -202,6 +231,9 @@ command line, or the link), you'd then:
    #include "Vour__Dpi.h"
    int add(int a, int b) { return a+b; }
 
+Rather than hard-coding the prefix, ``#include VM_PREFIX_INCLUDE_DPI`` may
+be used instead; see :ref:`Model Header Include Macros`.
+
 
 DPI System Task/Functions
 -------------------------
@@ -210,9 +242,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 +534,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``.
 

docs/guide/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
 
 *******************************
 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

docs/guide/contributors.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,

docs/guide/control.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
 
 .. _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.

docs/guide/copyright.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
 
 *********
 Copyright

docs/guide/deprecations.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
 
 Deprecations
 ============
@@ -17,14 +18,6 @@ C++14 compiler support
    the Ubuntu LTS versions of GCC and clang use C++20 by default, estimated
    May 2028.)
 
-`--structs-packed` option
-   The :vlopt:`--structs-packed` option was introduced when Verilator was
-   first implementing unpacked structs. That feature has been stable now
-   for multiple years, so :vlopt:`--structs-packed` should no longer be
-   used. Thus :vlopt:`--structs-packed` will change to a no-operation flag
-   and the related :option:`UNPACKED` warning will never be issued no
-   sooner than September 2026.
-
 tcmalloc support
    Verilator currently supports the default malloc, tcmalloc, or jemalloc.
    As jemalloc has better performance, support for tcmalloc may be removed

docs/guide/environment.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
 
 .. _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
 

docs/guide/example_binary.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
 
 .. _example create-binary execution:
 

docs/guide/example_cc.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
 
 .. _example c++ execution:
 

docs/guide/example_common_install.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
 
 First you need Verilator installed, see :ref:`Installation`. In brief, if
 you installed Verilator using the package manager of your operating system,

docs/guide/example_dist.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
 
 .. _examples in the distribution:
 

docs/guide/example_sc.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
 
 .. _example systemc execution:
 

docs/guide/examples.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
 
 .. _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

docs/guide/exe_sim.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
 
 .. _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

docs/guide/exe_verilator.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
 
 ===================
 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
@@ -302,12 +316,53 @@ Summary:
 
    Enables basic block line coverage analysis. See :ref:`Line Coverage`.
 
+.. option:: --coverage-max-bins <value>
+
+   Rarely needed. Specifies the maximum number of bins one covergroup bins
+   declaration of an integral coverpoint may create: an array of bins such
+   as ``bins b[] = {[0:$]}``, automatic bins ``bins auto[N]``, or the
+   automatic bins of a coverpoint from ``option.auto_bin_max``. Defaults to
+   1024, and may be at most 4294967295 (``2**32 - 1``).
+
+   A larger array of bins is ignored with a :option:`COVERIGN` warning, a
+   larger ``bins auto[N]`` is an error, and a larger
+   ``option.auto_bin_max`` is reduced to this limit with a
+   :option:`COVERIGN` warning. Increasing the limit increases the memory
+   the model uses for the bins. See also
+   :vlopt:`--coverage-max-real-bins`.
+
+.. option:: --coverage-max-real-bins <value>
+
+   Rarely needed. Specifies the maximum number of values of one array of
+   bins of a coverpoint of a ``real`` expression, such as
+   ``bins b[] = {[1:10]}``, each of which is a bin compared separately.
+   Defaults to 1024, and may be at most 4294967295 (``2**32 - 1``).
+
+   A larger array of bins is ignored with a :option:`COVERIGN` warning.
+   Increasing the limit increases the size of the generated code, which
+   grows with the number of these bins. See also
+   :vlopt:`--coverage-max-bins`.
+
 .. option:: --coverage-max-width <width>
 
    Rarely needed. Specify the maximum bit width of a signal subject to
    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`.
@@ -320,8 +375,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>
 
@@ -467,6 +522,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
@@ -634,8 +693,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
@@ -654,6 +733,8 @@ Summary:
 
 .. option:: -fno-dead-cells
 
+.. option:: -fno-dead-methods
+
 .. option:: -fno-dedup
 
 .. option:: -fno-dfg
@@ -667,6 +748,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
@@ -714,18 +799,51 @@ 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
 
 .. option:: -fno-lift-expr
 
+   Deprecated and has no effect (ignored).
+
+   In versions before 5.054: Disable lifting of expressions out of statements.
+
 .. option:: -fno-localize
 
 .. option:: -fno-merge-cond
@@ -734,6 +852,11 @@ Summary:
 
 .. option:: -fno-merge-const-pool
 
+   Deprecated and has no effect (ignored).
+
+   In versions before 5.054: Disable merging constant pool entries that have
+   the same value but different data types.
+
 .. option:: -fno-reloop
 
 .. option:: -fno-reorder
@@ -758,6 +881,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
@@ -851,7 +982,7 @@ Summary:
    :file:`*.mk` files.
 
    Feature may be one of the following: COROUTINES, DEV_ASAN, DEV_GCOV,
-   SYSTEMC.
+   SYSTEMC, TSAN.
 
 .. option:: --getenv <variable>
 
@@ -913,27 +1044,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>
 
@@ -1140,6 +1265,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>
@@ -1701,12 +1828,11 @@ Summary:
 
 .. option:: --structs-packed
 
-   Deprecated; discontinue use of this option.
+   Removed in 5.054.
 
-   Converts all unpacked structures to packed structures, and issues an
-   :option:`UNPACKED` warning. Specifying this option allows for backward
-   compatibility with versions before Verilator 5.006, when Verilator would
-   always pack unpacked structures.
+   Converted all unpacked structures to packed structures, Specifying this
+   option allowed for backward compatibility with versions before Verilator
+   5.006, when Verilator would always pack unpacked structures.
 
 .. option:: -sv
 
@@ -2178,7 +2304,7 @@ Summary:
      If using `--x-assign unique`, use the
      :vlopt:`+verilator+rand+reset+2 <+verilator+rand+reset+\<value\>>`
      runtime option, and seed the runtime random number generator such that
-     each regression run gets a different randomization sequence with
+     each regression test run gets a different randomization sequence with
      :vlopt:`+verilator+seed+\<value\>`. You'll probably also want to print
      any seeds selected, and code to enable rerunning with that same seed,
      so you can reproduce bugs.
@@ -2207,7 +2333,7 @@ Summary:
      If using `--x-initial unique`, use the
      :vlopt:`+verilator+rand+reset+2 <+verilator+rand+reset+\<value\>>`
      runtime option, and seed the runtime random number generator such that
-     each regression run gets a different randomization sequence with
+     each regression test run gets a different randomization sequence with
      :vlopt:`+verilator+seed+\<value\>`. You'll probably also want to print
      any seeds selected, and code to enable rerunning with that same seed,
      so you can reproduce bugs.

docs/guide/exe_verilator_coverage.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
 
 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,10 +133,14 @@ verilator_coverage Arguments
 
 .. option:: --filter-type <regex>
 
-   Skips records of coverage types that matches with <regex>
-   Possible values are `toggle`, `line`, `branch`, `expr`, `user`,
-   `fsm_state`, `fsm_arc` 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
 
@@ -143,6 +152,13 @@ verilator_coverage Arguments
    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
@@ -155,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

docs/guide/exe_verilator_gantt.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
 
 verilator_gantt
 ===============

docs/guide/exe_verilator_profcfunc.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
 
 verilator_profcfunc
 ===================

docs/guide/executables.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
 
 *********************************
 Executable and Argument Reference

docs/guide/extensions.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
 
 ===================
 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

docs/guide/faq.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
 
 ******************************
 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

docs/guide/files.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
 
 *****
 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

docs/guide/index.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
 
 ######################
 Verilator User's Guide

docs/guide/install-cmake.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
 
 .. _cmakeinstallation:
 
@@ -16,18 +17,18 @@ 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
+   the CMake variable FLEX_INCLUDE_DIR to the directory containing
    FlexLexer.h and ensure that flex/bison is available within the PATH.
 
 To obtain Verilator sources download

docs/guide/install.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
 
 .. _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,7 +171,10 @@ once, after ``configure``:
 
 .. code-block:: bash
 
-   # Create Python virutal environment in .venv:
+   # Install dependencies
+   sudo apt install python3-pip
+
+   # Create Python virtual environment in .venv:
    make venv
 
    # Or alternatively, to put it somewhere else:
@@ -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

docs/guide/languages.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

docs/guide/overview.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
 
 ********
 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.

docs/guide/simulating.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
 
 .. _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:
@@ -152,7 +153,7 @@ experience depends on the use case, and some experimentation can pay
 dividends. For a speedy debug cycle during development, especially on large
 designs where C++ compilation speed can dominate, consider using lower
 optimization to get to an executable faster. For throughput-oriented use
-cases, for example, regressions, it is usually worth spending extra
+cases, for example, regression testing, it is usually worth spending extra
 compilation time to reduce total CPU time.
 
 If you will be running many simulations on a single model, you can
@@ -184,7 +185,8 @@ 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`
@@ -193,30 +195,43 @@ 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 single-process FSMs and report both
-state coverage (`fsm_state`) and transition coverage (`fsm_arc`).
+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,
@@ -224,21 +239,70 @@ releases. In particular, the native FSM coverage extraction heuristics,
 should be treated as subject to change while the interface settles.
 
 FSM extraction is intentionally narrow. The current implementation targets
-clocked, enum-driven state machines that can be recovered directly from the
-RTL. It does not claim broad support for two-process FSMs, one-hot
-inference, helper-function next-state recovery, or deeply nested control
-recovery.
+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.
+- ``/*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
@@ -250,7 +314,6 @@ 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:
 
 Line Coverage
@@ -370,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").
@@ -439,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.)
@@ -544,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
@@ -611,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
@@ -622,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:

docs/guide/verilating.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
 
 **********
 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.
 
 
@@ -622,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.

docs/guide/warnings.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
 
 ===================
 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
@@ -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
 
@@ -546,6 +592,10 @@ List Of Warnings
    ``covergroup``, ``coverpoint``, and coverage options, and the
    construct was ignored.
 
+   This includes crosses whose normal-bin Cartesian product exceeds
+   ``2**32 - 1`` tuples.  The limit is checked during Verilation for both
+   automatic and explicit cross bins.
+
    Disabling the :option:`UNSUPPORTED` error also disables this warning.
 
    Ignoring this warning may make Verilator ignore lint checking on the
@@ -837,6 +887,22 @@ 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
@@ -956,6 +1022,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
@@ -1126,11 +1199,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.
@@ -1359,9 +1435,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
@@ -1375,11 +1453,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
@@ -1423,6 +1564,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
@@ -1504,6 +1658,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
@@ -1724,12 +1897,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.
 
@@ -1970,6 +2149,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
@@ -2264,11 +2469,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.
@@ -2303,14 +2503,10 @@ List Of Warnings
 
 .. option:: UNPACKED
 
-   Warns that unpacked structs and unions are not supported because
-   :vlopt:`--structs-packed` was used, or by up through version 5.004.
+   Historical, never issued since version 5.004.
 
-   Ignoring this warning will make Verilator treat the structure as packed,
-   which may make Verilator simulations differ from other simulators. This
-   downgrading may also result in what would typically be a legal unpacked
-   struct/array inside an unpacked struct/array becoming an illegal
-   unpacked struct/array inside a packed struct/array.
+   Warned that unpacked structs and unions were not supported, or disabled
+   by the since-removed `--structs-packed` option.
 
 
 .. option:: UNSATCONSTR

docs/internals.rst

@@ -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.
 
@@ -730,57 +746,49 @@ 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 -
+- 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.
@@ -1021,15 +1031,6 @@ Profile-guided optimization make this a bit better, by adjusting mtask
 scheduling, but this does not yet guide the packing into mtasks.
 
 
-Performance Regression
-++++++++++++++++++++++
-
-It would be nice if we had a regression of large designs, with some
-diversity of design styles, to test on both single- and multithreaded
-modes. This would help to avoid performance regressions, and also to
-evaluate the optimizations while minimizing the impact of parasitic noise.
-
-
 Per-Instance Classes
 ++++++++++++++++++++
 
@@ -1080,9 +1081,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 +1307,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 +1402,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 +1412,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 +1443,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
@@ -1627,7 +1636,7 @@ There are some traps to avoid when running regression tests
   Hat/Fedora/Centos offer *perl-Pod-Perldoc*', while Debian/Ubuntu/Linux
   Mint offer \`perl-doc'.
 
-- Running regression may exhaust resources on some Linux systems,
+- Running regression tests may exhaust resources on some Linux systems,
   particularly file handles and user processes. Increase these to
   respectively 16,384 and 4,096. The method of doing this is
   system-dependent, but on Fedora Linux it would require editing the
@@ -1701,7 +1710,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 +1759,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 +2133,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.
@@ -2177,30 +2211,65 @@ 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 @@
+
+
 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
@@ -2243,9 +2312,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
 ===========
@@ -2347,7 +2413,7 @@ driver.py Non-Scenario Arguments
 .. option:: --quiet
 
    Suppress all output except for failures and progress messages every 15
-   seconds. Intended for use only in automated regressions. See also
+   seconds. Intended for use only in automated regression testing. See also
    ``--rerun``, and ``--verbose`` which is not the opposite of ``--quiet``.
 
 .. option:: --rerun
@@ -2689,6 +2755,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
 ============