Version bump

Fixes #7848.

.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/workflows/build-test.yml

@@ -28,6 +28,38 @@ concurrency:
 
 jobs:
 
+  build-2604-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-26.04, cc: gcc, asan: 0}
+
+  build-2604-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-26.04, cc: clang, asan: 1}
+
   build-2404-gcc:
     name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
     uses: ./.github/workflows/reusable-build.yml
@@ -58,7 +90,7 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {os: ubuntu-24.04, cc: clang, asan: 1}
+          - {os: ubuntu-24.04, cc: clang, asan: 0}
 
   build-2204-gcc:
     name: Build | ${{ matrix.os }} | ${{ matrix.cc }}${{ matrix.asan && ' | asan' || '' }}
@@ -76,22 +108,6 @@ jobs:
         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
@@ -131,18 +147,18 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - {os: windows-2025, cc: msvc}
+          - {os: windows-2025-vs2026, 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
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           path: repo
       - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
         with:
           path: ${{ env.CCACHE_DIR }}
           key: msbuild-msvc-cmake
@@ -155,11 +171,59 @@ jobs:
       - name: Zip up repository
         run: Compress-Archive -LiteralPath install -DestinationPath verilator.zip
       - name: Upload zip archive
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: ${{ github.workspace }}/repo/verilator.zip
           name: verilator-win.zip
 
+  test-2604-gcc:
+    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
+    needs: build-2604-gcc
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      archive: ${{ needs.build-2604-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 26.04 gcc
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: dist-vlt-0}
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: dist-vlt-1}
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: dist-vlt-2}
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: dist-vlt-3}
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: vltmt-0}
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: vltmt-1}
+          - {os: ubuntu-26.04, cc: gcc, reloc: 0, suite: vltmt-2}
+
+  test-2604-clang:
+    name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
+    needs: build-2604-clang
+    uses: ./.github/workflows/reusable-test.yml
+    with:
+      archive: ${{ needs.build-2604-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 26.04 clang
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: dist-vlt-0}
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: dist-vlt-1}
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: dist-vlt-2}
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: dist-vlt-3}
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: vltmt-0}
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: vltmt-1}
+          - {os: ubuntu-26.04, cc: clang, reloc: 0, suite: vltmt-2}
+
   test-2404-gcc:
     name: Test | ${{ matrix.os }} | ${{ matrix.cc }} | ${{ matrix.reloc && 'reloc | ' || '' }} ${{ matrix.suite }}
     needs: build-2404-gcc
@@ -232,55 +296,6 @@ jobs:
           - {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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       - run: test_regress/t/t_dist_contributors.py

.github/workflows/coverage.yml

@@ -74,10 +74,10 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
       - name: Download code coverage data
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           pattern: code-coverage-*
           path: obj_coverage
@@ -90,7 +90,7 @@ jobs:
           find obj_coverage -type f | paste -sd, | sed "s/^/files=/" >> "$GITHUB_OUTPUT"
 
       - name: Upload to codecov.io
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f  # v7
         with:
           disable_file_fixes: true
           disable_search: true
@@ -114,7 +114,7 @@ jobs:
           sudo apt install lcov
 
       - name: Download repository archive
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           name: ${{ needs.build.outputs.archive }}
           path: ${{ github.workspace }}
@@ -125,7 +125,7 @@ jobs:
           ls -lsha
 
       - name: Download code coverage data
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           pattern: code-coverage-*
           path: repo/obj_coverage
@@ -163,6 +163,8 @@ jobs:
               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
+              echo "" >> notification/body.txt
+              echo "Please get to 100% line coverage, and understand all branches; see https://github.com/verilator/verilator/blob/master/docs/internals.rst#code-coverage-results" >> notification/body.txt
             else
               echo "Patch contains no code changes" >> notification/body.txt
             fi
@@ -170,17 +172,17 @@ jobs:
           fi
 
       - name: Upload report
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: repo/obj_coverage
           name: coverage-report
 
       - name: Upload notification
         if: ${{ github.event_name == 'pull_request' }}
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: repo/notification
-          name: coverage-pr-notification
+          name: pr-notification
 
   # Create GitHub issue for failed scheduled jobs
   # This should always be the last job (we want an issue if anything breaks)
@@ -193,9 +195,9 @@ jobs:
       # Creating issues requires elevated privilege
       - name: Generate access token
         id: generate-token
-        uses: actions/create-github-app-token@v2.2.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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
       - name: Extract context variables
         run: |
@@ -54,7 +54,7 @@ jobs:
 
       - name: Docker meta
         id: docker_meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # 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@v3
+        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3  # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4
         with:
           buildkitd-flags: --debug
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4
         with:
           username: ${{ secrets.DOCKER_HUB_USER }}
           password: ${{ secrets.DOCKER_HUB_ACCESS_TOKEN }}
 
       - name: Build and Push to Docker
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7
         if: startsWith(github.ref, 'refs/tags/v') || github.event_name == 'workflow_dispatch'
         with:
           context: ${{ env.build_context }}

.github/workflows/format.yml

@@ -21,7 +21,7 @@ jobs:
       CI_COMMIT: ${{ github.sha }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
       - name: Install packages for build
@@ -38,11 +38,11 @@ jobs:
           ./configure
           make venv
           source .venv/bin/activate
-          make -j 2 format CLANGFORMAT=clang-format-18
+          make -j 4 format CLANGFORMAT=clang-format-18
           git status
       - name: Push
         run: |-
           if [ -n "$(git status --porcelain)" ]; then
-            git commit . -m "Apply 'make format'" &&
+            git commit . -m "Apply 'make format' [ci skip]" &&
             git push origin
           fi

.github/workflows/no-pulls.yml

@@ -0,0 +1,15 @@
+---
+# Block PRs against stable branch
+name: "Check PR not against 'stable'"
+on:
+  pull_request:
+    branches: [stable]
+
+jobs:
+  block-pr:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail and block PR
+        run: |-
+          echo "Error: Pull requests directly to 'stable' are not allowed. Please PR against 'master'."
+          exit 1

.github/workflows/pages.yml

@@ -10,7 +10,7 @@ on:
     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
@@ -35,20 +35,20 @@ jobs:
     name: Build content
     runs-on: ubuntu-24.04
     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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       - name: Build pages
         id: build
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          bash -x ./ci/ci-pages.bash
+          ./ci/ci-pages.bash
           ls -lsha
           tree -L 3 pages
       - name: Upload pages artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9  # v5
         with:
           path: pages
 
@@ -61,7 +61,7 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Deploy to GitHub Pages
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128  # v5
 
   notify:
     name: Notify
@@ -70,18 +70,18 @@ jobs:
     if: ${{ github.repository == 'verilator/verilator' }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
       # Use the Verilator CI app to post the comment
       - name: Generate access token
         id: generate-token
-        uses: actions/create-github-app-token@v2.2.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
+          PR_RUN_IDS: ${{ needs.build.outputs.pr-run-ids }}
+        run: ./ci/ci-pages-notify.bash

.github/workflows/reusable-build.yml

@@ -61,14 +61,14 @@ jobs:
       CCACHE_MAXSIZE: 1000M  # Per build matrix entry (* 5 = 5000M in total)
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           path: repo
           ref: ${{ inputs.sha }}
           fetch-depth: ${{ inputs.dev-gcov && '0' || '1' }}  # Coverage flow needs full history
 
       - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
         env:
           CACHE_KEY: ${{ env.CACHE_BASE_KEY }}-ccache
         with:
@@ -93,7 +93,7 @@ jobs:
           echo "archive=$ARCHIVE" >> "$GITHUB_OUTPUT"
 
       - name: Upload repository archive
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: ${{ github.workspace }}/${{ steps.create-archive.outputs.archive }}
           name: ${{ steps.create-archive.outputs.archive }}

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

@@ -27,7 +27,7 @@ jobs:
     name: Sub-lint | Python
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           path: repo
 

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

@@ -15,6 +15,14 @@ on:
         description: "Compiler to use: 'gcc' or 'clang'"
         type: string
         required: true
+      sha:
+        description: "Git SHA to build"
+        type: string
+        required: true
+    outputs:
+      archive:
+        description: "Name of the built installation archive artifact"
+        value: ${{ jobs.build.outputs.archive }}
 
 defaults:
   run:
@@ -26,8 +34,10 @@ env:
 
 jobs:
   build:
-    runs-on: ${{ inputs.runs-on }}
     name: Build
+    runs-on: ${{ inputs.runs-on }}
+    outputs:
+      archive: ${{ steps.create-archive.outputs.archive }}
     steps:
       - name: Install dependencies
         run: |
@@ -36,20 +46,24 @@ jobs:
           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 libgoogle-perftools-dev libsystemc-dev || \
-          sudo apt install ccache mold help2man libfl-dev libgoogle-perftools-dev libsystemc-dev
+          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
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # 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 }}
+          key: rtlmeter-build-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ inputs.sha }}-${{ github.run_id }}-${{ github.run_attempt }}
+          restore-keys: |
+            rtlmeter-build-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ inputs.sha }}-${{ github.run_id }}
+            rtlmeter-build-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}-${{ inputs.sha }}
+            rtlmeter-build-ccache-${{ inputs.runs-on }}-${{ inputs.cc }}
 
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           path: repo
+          ref: ${{ inputs.sha }}
           fetch-depth: 0 # Required for 'git describe' used for 'verilator --version'
 
       - name: Configure
@@ -67,11 +81,16 @@ jobs:
         run: make install
 
       - name: Tar up installation
-        run: tar --posix -c -z -f verilator-rtlmeter.tar.gz install
+        id: create-archive
+        run: |
+          SHA=$(git -C repo rev-parse HEAD)
+          ARCHIVE=verilator-$SHA-rtlmeter-${{ inputs.runs-on }}-${{ inputs.cc }}.tar.gz
+          tar --posix -c -z -f $ARCHIVE install
+          echo "archive=$ARCHIVE" >> $GITHUB_OUTPUT
 
       - name: Upload Verilator installation archive
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
-          path: verilator-rtlmeter.tar.gz
-          name: verilator-rtlmeter-${{ inputs.runs-on }}-${{ inputs.cc }}
+          path: ${{ steps.create-archive.outputs.archive }}
+          name: ${{ steps.create-archive.outputs.archive }}
           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-rtlmeter-build, new version"
+        type: string
+        required: true
+      verilator-archive-old:
+        description: "Name of the installation archive artifact from reusable-rtlmeter-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.
@@ -60,29 +69,11 @@ jobs:
           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 libgoogle-perftools-dev libsystemc-dev || \
-          sudo apt install ccache mold libfl-dev libgoogle-perftools-dev libsystemc-dev
-
-      - name: Download Verilator installation archive
-        uses: actions/download-artifact@v7
-        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 }}
+          sudo apt install ccache mold libfl-dev libjemalloc-dev libsystemc-dev || \
+          sudo apt install ccache mold libfl-dev libjemalloc-dev libsystemc-dev
 
       - name: Checkout RTLMeter
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           repository: "verilator/rtlmeter"
           path: rtlmeter
@@ -91,40 +82,125 @@ jobs:
         working-directory: rtlmeter
         run: make venv
 
-      - name: Compile cases
+      - name: Use saved ccache
+        if: ${{ env.CCACHE_DISABLE == 0 }}
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # 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 }}
+
+      ########################################################################
+      # 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 -x -z -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@v6
+      - 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 -x -z -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

@@ -55,7 +55,7 @@ jobs:
     steps:
 
       - name: Download repository archive
-        uses: actions/download-artifact@v7
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
           name: ${{ inputs.archive }}
           path: ${{ github.workspace }}
@@ -67,7 +67,7 @@ jobs:
           ls -lsha
 
       - name: Cache $CCACHE_DIR
-        uses: actions/cache@v5
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9  # v5
         env:
           CACHE_KEY: ${{ env.CACHE_BASE_KEY }}-ccache2
         with:
@@ -99,11 +99,13 @@ jobs:
 
       - name: Upload code coverage data
         if: ${{ inputs.dev-gcov }}
-        uses: actions/upload-artifact@v6
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: ${{ github.workspace }}/repo/obj_coverage/verilator-${{ inputs.suite }}.info
           name: code-coverage-${{ inputs.suite }}
 
       - name: Fail job if a test failed
         if: ${{ steps.run-test.outcome == 'failure' && !cancelled() }}
-        run: exit 1
+        run: |-
+          echo "Click on '> Tests' arrow above (or on other steps), to expand it, and see the failure reasons"
+          exit 1

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

@@ -11,6 +11,8 @@ on:
     - cron: '0 2 * * *'  # Daily, starting at 02:00 UTC
   pull_request:
     types: [opened, synchronize, reopened, labeled, unlabeled]
+  push:
+    branches: ['ci-rtlmeter/**']
 
 permissions:
   contents: read
@@ -35,183 +37,232 @@ jobs:
         && vars.ENABLE_SCHEDULED_JOBS == 'true') ||
       (github.event_name == 'pull_request'
         && contains(github.event.pull_request.labels.*.name, 'pr: rtlmeter')) ||
-      (github.event_name == 'workflow_dispatch')
+      (github.event_name == 'workflow_dispatch') ||
+      (github.event_name == 'push')
     runs-on: ubuntu-24.04
+    outputs:
+      old-sha: ${{ steps.start.outputs.old-sha }}
+      cases: ${{ steps.cases.outputs.cases }}
     steps:
-      - name: Startup
-        run: echo
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
-  build-gcc:
-    name: Build GCC
+      - name: Startup
+        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"
+
+      - 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
     with:
       runs-on: ubuntu-24.04
       cc: gcc
+      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
     with:
       runs-on: ubuntu-24.04
       cc: clang
+      sha: ${{ github.sha }}
+
+  build-gcc-old:
+    name: Build Old Verilator - GCC
+    needs: start
+    if: ${{ needs.start.outputs.old-sha != '' }}
+    uses: ./.github/workflows/reusable-rtlmeter-build.yml
+    with:
+      runs-on: ubuntu-24.04
+      cc: gcc
+      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-rtlmeter-build.yml
+    with:
+      runs-on: ubuntu-24.04
+      cc: clang
+      sha: ${{ needs.start.outputs.old-sha }}
 
   run-gcc:
     name: Run GCC | ${{ matrix.cases }}
-    needs: build-gcc
+    needs:
+      - start
+      - build-gcc-new
+      - build-gcc-old
+    # Run even if 'build-*-old' was skipped (no old SHA), but not if any
+    # dependency failed, the workflow was cancelled, or 'start' was skipped
+    # (e.g. the workflow was not enabled, so there is nothing to run against).
+    if: ${{ !failure() && !cancelled() && needs.start.result == 'success' }}
     uses: ./.github/workflows/reusable-rtlmeter-run.yml
     with:
       tag: gcc
       runs-on: ubuntu-24.04
       cc: gcc
+      verilator-archive-new: ${{ needs.build-gcc-new.outputs.archive }}
+      verilator-archive-old: ${{ needs.build-gcc-old.outputs.archive }}
       cases: ${{ matrix.cases }}
       run-name: "gcc"
       compileArgs: ""
       executeArgs: ""
     strategy:
-      fail-fast: false
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      fail-fast: ${{ github.event_name == 'pull_request' }}
+      max-parallel: 7
       matrix:
-        cases:
-          - "BlackParrot:1x1:*"
-          - "BlackParrot:2x2:*"
-          - "BlackParrot:4x4:*"
-          - "Caliptra:default:*"
-          - "NVDLA:*"
-          - "OpenPiton:1x1:*"
-          - "OpenPiton:2x2:*"
-          - "OpenPiton:4x4:*"
-          - "OpenTitan:*"
-          - "VeeR-EH1:asic*"
-          - "VeeR-EH1:default*"
-          - "VeeR-EH1:hiperf*"
-          - "VeeR-EH2:asic*"
-          - "VeeR-EH2:default*"
-          - "VeeR-EH2:hiperf*"
-          - "VeeR-EL2:asic*"
-          - "VeeR-EL2:default*"
-          - "VeeR-EL2:hiperf*"
-          - "Vortex:mini:*"
-          - "Vortex:sane:*"
-          - "XiangShan:default-chisel3:* !*:linux"
-          - "XiangShan:default-chisel6:* !*:linux"
-          - "XiangShan:mini-chisel3:* !*:linux"
-          - "XiangShan:mini-chisel6:* !*:linux"
-          - "XuanTie-E902:*"
-          - "XuanTie-E906:*"
-          - "XuanTie-C906:*"
-          - "XuanTie-C910:*"
+        cases: ${{ fromJSON(needs.start.outputs.cases)['gcc'] }}
 
   run-clang:
     name: Run Clang | ${{ matrix.cases }}
-    needs: build-clang
+    needs:
+      - start
+      - build-clang-new
+      - build-clang-old
+    # Run even if 'build-*-old' was skipped (no old SHA), but not if any
+    # dependency failed, the workflow was cancelled, or 'start' was skipped
+    # (e.g. the workflow was not enabled, so there is nothing to run against).
+    if: ${{ !failure() && !cancelled() && needs.start.result == 'success' }}
     uses: ./.github/workflows/reusable-rtlmeter-run.yml
     with:
       tag: clang
       runs-on: ubuntu-24.04
       cc: clang
+      verilator-archive-new: ${{ needs.build-clang-new.outputs.archive }}
+      verilator-archive-old: ${{ needs.build-clang-old.outputs.archive }}
       cases: ${{ matrix.cases }}
       run-name: "clang --threads 4"
       compileArgs: "--threads 4"
       executeArgs: ""
     strategy:
-      fail-fast: false
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      fail-fast: ${{ github.event_name == 'pull_request' }}
+      max-parallel: 7
       matrix:
-        cases:
-          - "BlackParrot:1x1:*"
-          - "BlackParrot:2x2:*"
-          - "BlackParrot:4x4:*"
-          - "Caliptra:default:*"
-          - "NVDLA:*"
-          - "OpenPiton:1x1:*"
-          - "OpenPiton:2x2:*"
-          - "OpenPiton:4x4:*"
-          - "OpenTitan:*"
-          - "VeeR-EH1:asic*"
-          - "VeeR-EH1:default*"
-          - "VeeR-EH1:hiperf*"
-          - "VeeR-EH2:asic*"
-          - "VeeR-EH2:default*"
-          - "VeeR-EH2:hiperf*"
-          - "VeeR-EL2:asic*"
-          - "VeeR-EL2:default*"
-          - "VeeR-EL2:hiperf*"
-          - "Vortex:mini:*"
-          - "Vortex:sane:*"
-          - "XiangShan:default-chisel3:* !*:linux"
-          - "XiangShan:default-chisel6:* !*:linux"
-          - "XiangShan:mini-chisel3:* !*:linux"
-          - "XiangShan:mini-chisel6:* !*:linux"
-          - "XuanTie-E902:*"
-          - "XuanTie-E906:*"
-          - "XuanTie-C906:*"
-          - "XuanTie-C910:*"
+        cases: ${{ fromJSON(needs.start.outputs.cases)['clang'] }}
 
   run-gcc-hier:
     name: Run GCC hier | ${{ matrix.cases }}
-    needs: build-gcc
+    needs:
+      - start
+      - build-gcc-new
+      - build-gcc-old
+    # Run even if 'build-*-old' was skipped (no old SHA), but not if any
+    # dependency failed, the workflow was cancelled, or 'start' was skipped
+    # (e.g. the workflow was not enabled, so there is nothing to run against).
+    if: ${{ !failure() && !cancelled() && needs.start.result == 'success' }}
     uses: ./.github/workflows/reusable-rtlmeter-run.yml
     with:
       tag: gcc-hier
       runs-on: ubuntu-24.04
       cc: gcc
+      verilator-archive-new: ${{ needs.build-gcc-new.outputs.archive }}
+      verilator-archive-old: ${{ needs.build-gcc-old.outputs.archive }}
       cases: ${{ matrix.cases }}
       run-name: "gcc --hierarchical"
       compileArgs: "--hierarchical"
       executeArgs: ""
     strategy:
-      fail-fast: false
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      fail-fast: ${{ github.event_name == 'pull_request' }}
+      max-parallel: 6
       matrix:
-        cases:
-          - "BlackParrot:1x1:* !-hier"
-          - "BlackParrot:2x2:* !-hier"
-          - "BlackParrot:4x4:* !-hier"
-          - "NVDLA:* !-hier"
-          - "OpenPiton:1x1:* !-hier"
-          - "OpenPiton:2x2:* !-hier"
-          - "OpenPiton:4x4:* !-hier"
-          - "OpenPiton:8x8:* !-hier"
-          - "OpenPiton:16x16:dhry !-hier"
-          - "XuanTie-C910:* !-hier"
+        cases: ${{ fromJSON(needs.start.outputs.cases)['gcc-hier'] }}
 
   combine-results:
     name: Combine results
     needs: [run-gcc, run-clang, run-gcc-hier]
-    # Run if any of the dependencies have run, even if failed.
-    # That is: do not run if all skipped, or the workflow was cancelled.
-    if: ${{ (contains(needs.*.result, 'success') || contains(needs.*.result, 'failure')) && !cancelled() }}
+    # Skip if cancelled.
+    # On PRs, run if something succeeded and nothing failed.
+    # On non-PRs, run if anything succeeded or failed (so partial results are still published).
+    if: >-
+      ${{ !cancelled() && (
+               (github.event_name == 'pull_request' && (contains(needs.*.result, 'success') && !contains(needs.*.result, 'failure')))
+            || (github.event_name != 'pull_request' && (contains(needs.*.result, 'success') ||  contains(needs.*.result, 'failure')))
+          )}}
     runs-on: ubuntu-24.04
-    strategy:
-      fail-fast: false
-      matrix:
-        tag: [gcc, clang, gcc-hier]
+    outputs:
+      # The run tags, derived from the 'run-*' dependency job names
+      run-tags: ${{ steps.tags.outputs.tags }}
+    env:
+      GH_TOKEN: ${{ github.token }}
+      # 'gh' resolves the repo from git otherwise, but this job has no checkout
+      # of this repo at the workspace root
+      GH_REPO: ${{ github.repository }}
     steps:
+      # Derive the run tags from the dependency job names ('run-<tag>')
+      - name: Determine run tags
+        id: tags
+        run: echo "tags=$(jq -r 'keys | map(sub("^run-"; "")) | join(" ")' <<< '${{ toJSON(needs) }}')" >> "$GITHUB_OUTPUT"
+
       - name: Checkout RTLMeter
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # 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@v7
-        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@v6
+        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
 
@@ -227,28 +278,27 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Download combined results
-        uses: actions/download-artifact@v7
+        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@v6
+        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@v2.2.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@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           repository: "verilator/verilator-rtlmeter-results"
           token: ${{ steps.generate-token.outputs.token }}
@@ -275,116 +325,61 @@ jobs:
   prepare-pr-results:
     name: Prepare Pull Request results
     needs: combine-results
-    if: ${{ github.event_name == 'pull_request' && github.repository == 'verilator/verilator' && contains(needs.*.result, 'success') && !cancelled() }}
+    if: ${{ github.event_name == 'pull_request' && github.repository == 'verilator/verilator' && needs.combine-results.result == 'success' }}
     runs-on: ubuntu-24.04
     permissions:
       actions: read
     steps:
       - name: Checkout RTLMeter
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # 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@v7
+
+      - name: Checkout Verilator
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # 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@v7
-        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
+          # Create the notification artifact
+          mkdir ../notification-artifact
+          mv rtlmeter-report/notification.txt ../notification-artifact/body.txt
+          echo ${{ github.event.number }} > ../notification-artifact/pr-number.txt
+
       - name: Upload report
-        uses: actions/upload-artifact@v6
+        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@v6
+          path: report-artifact
+          name: rtlmeter-report
+
+      - name: Upload notification
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
-          path: pr-number.txt
-          name: pr-number
+          path: notification-artifact
+          name: pr-notification
+
+      - 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)
@@ -397,9 +392,9 @@ jobs:
       # Creating issues requires elevated privilege
       - name: Generate access token
         id: generate-token
-        uses: actions/create-github-app-token@v2.2.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,142 @@
+<!-- DESCRIPTION: Verilator: Repository-wide guidelines for AI coding agents
+     SPDX-FileCopyrightText: 2026-2026 Wilson Snyder
+     SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -->
+
+# Verilator Guidelines for AI Coding Agents
+
+These files are the general layer an agent loads first -- nearest file wins, so
+you read this repository-root file plus the one for the directory you are
+editing. They stay deliberately high-level: where to start, how the tree is laid
+out, and the conventions reviewers otherwise enforce by hand. They are an index,
+not the architecture reference -- for depth (how a pass works internally, the
+algorithms, node lifetime) they point you to `docs/internals.rst`. When the
+guidance here is not enough, that is where to look next.
+
+This file has two parts. **Orientation** gets you productive in the codebase from
+a cold start. **Before you open a PR** is the checklist of conventions reviewers
+otherwise have to enforce by hand -- read it before submitting any change.
+
+Then read the directory guide for the area you are editing:
+
+- [src/AGENTS.md](src/AGENTS.md) -- compiler C++ sources: AST, visitors, passes, parser, style
+- [include/AGENTS.md](include/AGENTS.md) -- runtime library (`verilated*`): C++14, MT-safety, fixed-width types
+- [test_regress/AGENTS.md](test_regress/AGENTS.md) -- regression tests: harness, drivers, golden files
+- [docs/AGENTS.md](docs/AGENTS.md) -- documentation (`*.rst`)
+
+______________________________________________________________________
+
+# Orientation
+
+## What Verilator is
+
+Verilator is a *compiler*, not an interpreter. It translates synthesizable (and
+much behavioral) SystemVerilog into a cycle-accurate C++ model that you then
+compile and run. Almost every decision is made at compile ("verilation") time;
+the generated C++ just advances state each evaluation. Optimize for verilation-
+time work over runtime work.
+
+## The pipeline is the spine
+
+A run is an ordered sequence of passes over one shared AST (abstract syntax
+tree). In source order:
+
+| Stage | What it does | Key files |
+|---|---|---|
+| Preprocess + parse | Lex and parse text into a raw AST -- builds nodes only, no semantic checks | `verilog.l`, `verilog.y` |
+| Link / elaborate | Resolve names, scopes, parameters; instantiate the hierarchy | `V3LinkParse`, `V3LinkDot`, `V3Param` |
+| Width / type | Assign and check data types and bit widths | `V3Width` |
+| Transform / optimize / schedule | Constant fold, lower language features, schedule events | `V3Const`, `V3Randomize`, `V3Assert*`, `V3Sched`, `V3Timing`, `V3Dfg` |
+| Emit | Lower the final AST to generated C++ | `V3EmitC*` |
+| Runtime | Library the generated model links against | `include/verilated*` |
+
+This table is the map; `docs/internals.rst` has the detail behind each stage.
+
+## Where to make a change
+
+Map the symptom to the pass that owns it, then start by reading that pass's
+top-of-file comment.
+
+| Symptom or feature area | Start in |
+|---|---|
+| Type/width error, "what type is this", implicit conversion | `V3Width` |
+| Name/scope/parameter resolution ("Can't find...", hierarchy) | `V3LinkDot`, `V3Param` |
+| `randomize` / `constraint` / `rand` / `randc` | `V3Randomize` |
+| `assert` / `property` / `sequence` / `cover` | `V3Assert`, `V3AssertPre`, `V3AssertNfa` |
+| `fork` / timing / `#delay` / NBA / event scheduling | `V3Sched`, `V3Timing`, `V3Fork` |
+| Syntax wrongly accepted or rejected | `verilog.y`, `verilog.l` |
+| Wrong generated C++ | `V3EmitC*` |
+| Runtime model behavior | `include/verilated*` |
+
+## Build and run a test
+
+- Build in the source tree: `autoconf && ./configure && make -j8`. Configure with
+  `--enable-ccwarn` so a new compiler warning stops the build.
+- Run one test from the repository root: `test_regress/t/t_<name>.py`.
+- Run the full regression with `make test`. The complete suite requires
+  configuring with `--enable-longtests` (works on every OS, including macOS).
+
+______________________________________________________________________
+
+# Before you open a PR
+
+## Scope and process
+
+- [ ] Searched open PRs and issues -- duplicating in-flight work wastes review time.
+- [ ] Fixed the general root cause, not just the reported case -- if it also
+  affects other modules/classes/interfaces, cover them or expect rejection.
+- [ ] PR is single-purpose. Refactors, drive-by fixes found along the way, and new
+  features each go in separate PRs; land standalone cleanups first.
+- [ ] Every bug fix has a test that fails *without* the fix; include the issue's
+  own reproducer when possible.
+- [ ] New code aims for 100% line coverage; branch coverage far below line coverage
+  signals guards callers never violate -- justify or remove them.
+- [ ] Ran `make format` (clang-format), `make cppcheck`, and `make lint-py`;
+  self-reviewed the diff for leftover debug code, stale comments, and
+  copy-paste errors.
+- [ ] Ran the full regression on at least one OS before submitting. Partial runs
+  are fine during development, but the submitted PR is expected to pass every
+  test.
+- [ ] Did not edit `docs/CONTRIBUTORS` (humans only) or `Changes` (maintainer
+  updates it near release).
+
+## Pick the right diagnostic (and its required test)
+
+The API you choose determines which test must accompany the change.
+
+| API | Output | Meaning | Required test |
+|---|---|---|---|
+| `v3error("...")` | `%Error:` | User wrote invalid SystemVerilog | `t_*_bad*.v` + `.out` golden |
+| `v3error("Unsupported: ...")` | `%Error-UNSUPPORTED:` | Legal SV that Verilator does not yet support | `t_*_unsup*.v` + `.out` golden |
+| `v3warn(CODE, "...")` | `%Warning-CODE:` | Legal but suspicious code | warning test + `.out` golden |
+| `v3fatalSrc("...")` | `%Error: Internal Error` | Should-never-happen internal assertion | none -- not user-triggerable |
+
+- Every `v3error`/`v3warn` needs a test in `test_regress/t/` -- enforced by the
+  warn-coverage distribution test. `v3fatalSrc` is exempt.
+- Reserve "Unsupported:" for not-yet-implemented features, never for user mistakes.
+- When an error enforces a spec-defined restriction, cite the clause
+  (`IEEE 1800-2023 11.4.7`) so it is verifiable. Update `docs/guide/warnings.rst`
+  when adding or changing a warning.
+- On error paths, clean up or replace invalid AST (e.g. `AstConst::BitFalse`) so
+  later passes do not crash after the error.
+
+## Cross-cutting code rules
+
+- [ ] No non-ASCII characters in C++ sources or headers: write `--` (two ASCII
+  hyphens) rather than a Unicode em-dash, and a plain `'` rather than a smart
+  quote. At write time, not when CI complains.
+- [ ] Lists stay sorted: lexer/parser tokens, option declarations, enum values,
+  configure feature lists, documented option lists.
+- [ ] `bin/` scripts are Python (distributed cross-platform); `nodist/` may use
+  bash and platform-specific code (developer-only, not packaged).
+- [ ] Runtime code in `include/` targets C++14 (`--no-timing` builds must work);
+  C++20 only in timing code paths.
+- [ ] In `include/` public headers, prefix public classes with `Verilated`/`Vl`
+  and document the API with `///` comments.
+- [ ] A new code pattern is applied globally or not at all -- no one-off
+  convention in a single file.
+
+## Commits
+
+- Subject line is short and imperative and conventionally ends with the PR number:
+  `Support property case (#7721)`. A body is optional and common for non-trivial
+  changes.

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.046
+    VERSION 5.050
     HOMEPAGE_URL https://verilator.org
     LANGUAGES CXX
 )
@@ -182,6 +182,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,379 @@ The changes in each Verilator version are described below.  The
 contributors that suggested or implemented a given issue are shown in []. Thanks!
 
 
+Verilator 5.050 2026-07-01
+==========================
+
+**Important:**
+
+* Support covergroups, coverpoints, and bins (#784) (#7117) (#7728). [Matthew Ballance]
+* Support new FST writer API (#6871) (#6992). [Yu-Sheng Lin]
+  Use of FST may requiring installing liblz4 and/or liblz4-dev packages, see docs/install.rst.
+
+**Other:**
+
+* Add `+verilator+log+file` (#4505) (#7645). [Tracy Narine]
+* Add peak memory usage to `--stats`. [Geza Lore, Testorrent USA, Inc.]
+* Add error on mixed-initialization (#7352) (#7357).
+* Add `--coverage-per-instance` (#7636). [Yogish Sekhar]
+* Add NOTREDOP error on reduction and negation operators (#7417) (#7623) (#7624).
+* Add hierarchy-aware reporting to `verilator_coverage` (#7657). [Yogish Sekhar]
+* Add FINALDLY error (#7754). [Igor Zaworski, Antmicro Ltd.]
+* Deprecate isolate_assignments attribute (#7774) (#7144). [Geza Lore, Testorrent USA, Inc.]
+* Improve `--coverage-fsm` (#7490) (#7529) (#7561) (#7573) (#7619). [Yogish Sekhar]
+* Change `+verilator+seed` to default to 1, and 0 to randomly select (#7325) (#7516). [Miguel]
+* Change JSON to include parameter constant mnemonics for FSM Coverage (#7531). [Yogish Sekhar]
+* Support assert property `default disable iff` (#4848) (#7723). [Artur Bieniek, Antmicro Ltd.]
+* Support printing enum names for %p and %s (#5523) (#7338 repair) (#7521) (#7527). [Nick Brereton]
+* Support weak `until` / `until_with` property operators (#7290) (#7548) (#7685). [Yilou Wang]
+* Support `s_eventually` (#7291) (#7508). [Bartłomiej Chmiel, Antmicro Ltd.]
+* Support writing to inout in fork after timing (#7345). [Kamil Danecki, Antmicro Ltd.]
+* Support `always` / `always[m:n]` / `s_always[m:n]` property operators (#7482). [Yilou Wang]
+* Support rand_mode() on static rand class members (#7484) (#7510). [Yilou Wang]
+* Support `randomize() with (identifier_list) {constraint_block}` (#7486) (#7507). [Yilou Wang]
+* Support `obj.randomize(null)` (#7487) (#7509). [Yilou Wang]
+* Support functions on RHS of force (#7491). [Artur Bieniek, Antmicro Ltd.]
+* Support procedural continuous assign/deassign (#7493). [Artur Bieniek, Antmicro Ltd.]
+* Support randsequence production function ports (#7522). [Yilou Wang]
+* Support followed-by operators `#-#` and `#=#` in properties (#7523). [Yilou Wang]
+* Support expression coverage on assign statements (#7542) (#7543). [Thomas Brown]
+* Support TERMUX (#7559). [Laurent CHARRIER]
+* Support NBAs in initial blocks with delay/event controls (#7566) (#7600). [Muzaffer Kal]
+* Support SVA goto repetition with range `[->M:N]` (#7569). [Yilou Wang]
+* Support property abort operators (accept_on, reject_on) (#7578). [Yilou Wang]
+* Support procedural concurrent assertions with inferred clock (#7581). [Yilou Wang]
+* Support calling interface functions without parens (#7584). [Krzysztof Bieganski, Antmicro Ltd.]
+* Support streaming on queues (#7597). [Benjamin Collier, Secturion Systems, Inc.]
+* Support clocking event on a sequence declaration body (#7598) (#7793). [Yilou Wang]
+* Support generic interface arrays (#7604). [Krzysztof Bieganski, Antmicro Ltd.]
+* Support FSM detection in primitive wrappers (#7607). [Yogish Sekhar]
+* Support busses with mix of pullup/pulldown (#7632). [Lucas Amaral]
+* Support forceable on unpacked array variables (#7677) (#7678). [Nikolai Kumar]
+* Support pre/post increment/decrement inside && and || (#7683). [Nick Brereton]
+* Support streaming into 2-D unpacked arrays (#7686) (#7687). [Paul Swirhun]
+* Support if/if-else in properties (#7692). [Artur Bieniek, Antmicro Ltd.]
+* Support process::self().srand() (#7695). [Igor Zaworski, Antmicro Ltd.]
+* Support MacOS lldb (#7697). [Tracy Narine]
+* Support assoc array methods with wide value types (#7680). [pawelktk]
+* Support property case (#7682) (#7721). [Artur Bieniek, Antmicro Ltd.]
+* Support `s_until` and `s_until_with`(#7722). [Artur Bieniek, Antmicro Ltd.]
+* Support covergroup runtime model Phase A1 (#7728). [Matthew Ballance]
+* Support hierarchical reference cross members (#7749) (#7820). [Matthew Ballance]
+* Support reduction XOR/AND operations in constraints (#7753). [Kornel Uriasz, Antmicro Ltd.]
+* Support NBAs in initial blocks (#7754). [Igor Zaworski, Antmicro Ltd.]
+* Support assertion control system tasks in classes and interfaces (#7761). [Yilou Wang]
+* Support cover sequence statement (#7764). [Yilou Wang]
+* Support unpacked struct stream (#7767). [Nick Brereton]
+* Support $assertcontrol control_type from lock to kill (#7788). [Yilou Wang]
+* Support unbounded always [m:$] and strong s_always liveness (#7798). [Yilou Wang]
+* Support method calls on a sub-interface via a virtual interface (#7800). [Yilou Wang]
+* Support global $assertcontrol (#7807). [Artur Bieniek, Antmicro Ltd.]
+* Support VPI access to unpacked struct members (#7823). [Nick Brereton]
+* Support variable-length intersect in SVA sequences (#7835). [Yilou Wang]
+* Support dynamic loading of VPI extensions (#7727). [Matthew Ballance]
+* Optimize DFG cycle breaking to do less work (#7210). [Geza Lore, Testorrent USA, Inc.]
+* Optimize emitting to_string() for compiler speedup (#7468). [Jakub Michalski, Antmicro Ltd.]
+* Optimize additional DFG peephole cases (#7553). [Varun Koyyalagunta, Testorrent USA, Inc.]
+* Optimize forced signal handling (#7554 partial) (#7572) (#7594) (#7596). [Krzysztof Bieganski, Artur Bieniek, Antmicro Ltd.]
+* Optimize primitive runtime functions. [Geza Lore, Testorrent USA, Inc.]
+* Optimize if branches with same trailing statements (#7674). [Geza Lore, Testorrent USA, Inc.]
+* Optimize wide conditional expansion in V3Premit (#7691). [Geza Lore, Testorrent USA, Inc.]
+* Optimize VL_ONEHOT. [Geza Lore, Testorrent USA, Inc.]
+* Optimize formatting functions (#7701) (#7702) (#7703). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DPI import argument passing (#7704). [Geza Lore, Testorrent USA, Inc.]
+* Optimize runtime assertOn() checks (#7707). [Geza Lore, Testorrent USA, Inc.]
+* Optimize $countones and $onehot in DFG. [Geza Lore, Testorrent USA, Inc.]
+* Optimize procedural loop unrolling. [Geza Lore, Testorrent USA, Inc.]
+* Optimize V3Gate inlining heuristic (#7716). [Geza Lore, Testorrent USA, Inc.]
+* Optimize reset in DFG (#7737). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG with relaxed live variable analysis (#7739). [Geza Lore, Testorrent USA, Inc.]
+* Optimize conditional patterns sharing common MBSs/LSBs in DfgPeephole (#7760). [Geza Lore, Testorrent USA, Inc.]
+* Optimize bit select removal earlier in DFG (#7762). [Geza Lore, Testorrent USA, Inc.]
+* Optimize away proven redundant case statement assertions (#7771). [Geza Lore, Testorrent USA, Inc.]
+* Optimize table lookups in DFG (#7772). [Geza Lore, Testorrent USA, Inc.]
+* Optimize input combinational logic by change detection (#7784). [Geza Lore, Testorrent USA, Inc.]
+* Optimize decoder case statements into lookup tables (#7795). [Geza Lore, Testorrent USA, Inc.]
+* Optimize wide decoder case statements into decoder expressions (#7804). [Geza Lore, Testorrent USA, Inc.]
+* Optimize statically known oversize shifts (#7806). [Geza Lore, Testorrent USA, Inc.]
+* Optimize generated function inlining (#7811). [Geza Lore, Testorrent USA, Inc.]
+* Optimize bit-scan loops into most-set-bit or $countones (#7822). [Thomas Santerre]
+* Optimize additional expression patterns (#7824). [Geza Lore, Testorrent USA, Inc.]
+* Optimize module inlining heuristic (#7837). [Geza Lore, Testorrent USA, Inc.]
+* Fix `$bits` on unpacked structs (#4521) (#7796). [Nick Brereton]
+* Fix TSP variable ordering for mtasks (#5342) (#7610). [Muzaffer Kal]
+* Fix inlining static initializer in V3Gate (#5381) (#7503). [Andrew Nolte] [Geza Lore, Testorrent USA, Inc.]
+* Fix timed nested fork block with disable (#6720) (#7743). [Marco Bartoli]
+* Fix segmentation fault when using --trace with --lib-create (#7299) (#7518). [anonkey]
+* Fix cross-hierarchy tristate drivers of interface nets (#7339) (#7801). [Yilou Wang]
+* Fix destructive event state before dynamic waits (#7340). [Nick Brereton]
+* Fix ALWCOMBORDER on variable ordering (#7350) (#7608). [Cookie]
+* Fix false MULTIDRIVEN warning on always_ff variables (#7351) (#7621) (#7672).
+* Fix array pattern concatenation (#7401) (#7402). [Greg Davill]
+* Fix fairness in `std::semaphore` (#7435) (#7605). [Krzysztof Bieganski, Antmicro Ltd.]
+* Fix generic interface port forwarded to a nested instance (#7454) (#7457). [Yilou Wang]
+* Fix internal error on multi-cycle SVA under default clocking (#7472) (#7506). [Yilou Wang]
+* Fix internal error instead of missing prototype error (#7485). [Alex Solomatnikov]
+* Fix mailbox#(packed_struct) type mismatch with parameterized class (#7494) (#7495). [Nikolai Kumar]
+* Fix std::randomize internal error on static member of different class (#7498) (#7499). [Alex Solomatnikov]
+* Fix assert under assert error (#7500) (#7513). [Nikolai Kumar]
+* Fix std::unique_ptr with incomplete type for clang (#7501) (#7526).
+* Fix virtual interface method call inlining and IMPURE suppression (#7505). [Nikolay Puzanov]
+* Fix expression coverage in loops (#7511). [Todd Strader]
+* Fix $bits on local struct with chained-interface (#7515) (#7517).
+* Fix array indexing side effects in compound assignments (#7519) (#7540) (#7544). [Kamil Danecki, Antmicro Ltd.]
+* Fix class::localparam during elaboration (#7524) (#7534).
+* Fix dearray variable scope error (#7530) (#7602).
+* Fix nested parameterized class typedef chain (#7538). [Michael Rogenmoser]
+* Fix events in observed region (#7546). [Todd Strader]
+* Fix regression rejecting boolean `!x` inside sequence expressions (#7549) (#7551). [Yilou Wang]
+* Fix exponential expansion in V3Gate (#7550). [Geza Lore, Testorrent USA, Inc.]
+* Fix internal error on consecutive repetition with N > 256 (#7552) (#7603). [Yilou Wang]
+* Fix inherited rand array with .size + foreach constraint (#7558) (#7650). [Yilou Wang]
+* Fix biased bit distribution under value < (1 << N) constraints (#7563) (#7684). [Yilou Wang]
+* Fix HIERPARAM lint checking (#7570) (#7690). [em2machine]
+* Fix display of %m in non-first argument (#7574).
+* Fix floating point compile warning on min/max delays.
+* Fix force of unpacked arrays (#7579) (#7580). [Zubin Jain]
+* Fix property argument retaining type of the previous variable (#7582). [Jakub Michalski]
+* Fix NBA to whole arrays (#7583) (#7575). [Geza Lore, Testorrent USA, Inc.]
+* Fix wrong false assert for property local variables with cycle-delayed consequents (#7587) (#7651). [Yilou Wang]
+* Fix interface instance name collision (#7591) (#7593). [Stuart Morris]
+* Fix process comparison compile error with `--public-flat-rw` (#7592).
+* Fix CPU pinning when no 'core id' present (#7599). [Geza Lore, Testorrent USA, Inc.]
+* Fix access to parameters via class::localparam (#7609) (#7671). [em2machine]
+* Fix clocking-block sample of unpacked array (#7612) (#7613). [Nikolai Kumar]
+* Fix type parameters order (#7615) (#7653) (#7693). [Kamil Danecki, Antmicro Ltd.]
+* Fix unique_index method on assoc arrays with values differing from the keys (#7616). [Pawel Klopotek]
+* Fix wide equality comparison in unpacked structs (#7618). [Geza Lore, Testorrent USA, Inc.]
+* Fix force determinism (#7620) (#7637). [Artur Bieniek, Antmicro Ltd.]
+* Fix reference counting for modport task references (#7628). [Nick Brereton]
+* Fix internal error when handling typedefs containing parameterized class type members (#7635) (#7661). [em2machine]
+* Fix forceable signal with a procedural continuous assign (#7638) (#7639). [Zubin Jain]
+* Fix scheduling of virtual interface method writes (#7641). [Artur Bieniek, Antmicro Ltd.]
+* Fix implicit conversions of VlWide (#7642). [Geza Lore, Testorrent USA, Inc.]
+* Fix CASEINCOMPLETE to not warn on `unique0 case` (#7647).
+* Fix hierarchical coverage counts for duplicate no-inline module instances (#7649). [Yogish Sekhar]
+* Fix dropped iff guard on clocking inside task (#7658) (#7659). [Nikolai Kumar]
+* Fix runtime speed summary report. [Geza Lore, Testorrent USA, Inc.]
+* Fix reserved keywords reaching emitter (#7666). [Pawel Kojma, Antmicro Ltd.]
+* Fix width of unsized literal in property expression (#7668). [Artur Bieniek, Antmicro Ltd.]
+* Fix loss of events due to bit shift (#7670). [Artur Bieniek, Antmicro Ltd.]
+* Fix parameter read through locally-declared interface instance (#7679). [Nick Brereton]
+* Fix skipping nulls in $sscanf (#7689).
+* Fix bounds checks in expressions with read/write references (#7694). [Ryszard Rozak, Antmicro Ltd.]
+* Fix (const) ref default task argument handling (#7698). [Nick Brereton]
+* Fix `ref` argument type check for packed arrays with differing range directions (#7700). [Nick Brereton]
+* Fix ignoring not-found modules with encoded names (#7706). [Igor Zaworski, Antmicro Ltd.]
+* Fix MULTIDRIVEN in generates (#7709). [Todd Strader]
+* Fix parameter pollution when using class parameters (#7711) (#7763). [em2machine]
+* Fix Makefile action to not write to ${srcdir} (#7715). [Larry Doolittle]
+* Fix splitting functions containing fork logic (#7717). [Mateusz Gancarz, Antmicro Ltd.]
+* Fix optimizations of assignments with timing controls (#7718). [Ryszard Rozak, Antmicro Ltd.]
+* Fix s_eventually on interface (#7731) (#7733). [Marco Bartoli]
+* Fix parameter values in coverage bins widths (#7732) (#7734). [Marco Bartoli]
+* Fix configure fall back on dynamic malloc libraries (#7736). [Geza Lore, Testorrent USA, Inc.]
+* Fix crash on overlapping priority case. [Geza Lore, Testorrent USA, Inc.]
+* Fix s_eventually in parameterized interfaces (#7741). [Nick Brereton]
+* Fix dpi export pointers (#7742) (#7751). [Yilin Li]
+* Fix force on unpacked bit select (#7744) (#7745). [Nikolai Kumar]
+* Fix `$` as unsupported coverpoint-bin range bounds (#7750) (#7825). [Matthew Ballance]
+* Fix FSM detect unchecked casts and variable redeclaration (#7758). [Adam Kostrzewski, Antmicro Ltd.]
+* Fix no-scope internal error on virtual interface method calls (#7759). [Yilou Wang]
+* Fix `case (_) inside` with x wildcards (#7766). [Geza Lore, Testorrent USA, Inc.]
+* Fix not failing assertion when RHS of a range window rejects once (#7773). [Artur Bieniek, Antmicro Ltd.]
+* Fix $fflush and autoflush with --threads (#7782).
+* Fix out-of-bounds read value for 2-state types (#7785). [Jakub Michalski]
+* Fix `cover property` of an implication counting vacuous matches (#7789). [Yilou Wang]
+* Fix randomization of dynamic arrays of objects (#7790). [Ryszard Rozak, Antmicro Ltd.]
+* Fix randomize() with skipping derived pre/post_randomize (#7799). [Yilou Wang]
+* Fix skewed dist operator for arrays (#7802). [Jakub Wasilewski, Antmicro Ltd.]
+* Fix assertion when loop unrolling failed (#7810). [Geza Lore, Testorrent USA, Inc.]
+* Fix CASEINCOMPLETE for all uncovered enum items (#7815) (#7817). [Saksham]
+* Fix split optimization nested-class crash (#7826). [Igor Zaworski, Antmicro Ltd.]
+* Fix class/var named identically to an enclosing-scope type (#7827) (#7828). [Tom Jackson]
+* Fix performance on large package-scoped structs (#7830). [Wolfgang Mayerwieser]
+* Fix unclocked concurrent assertion misreported as unsupported  (#7831). [Yilou Wang]
+* Fix insertion of expression coverage statement (#7832). [Ryszard Rozak, Antmicro Ltd.]
+* Fix lifetime of expression coverage variable (#7834). [Ryszard Rozak, Antmicro Ltd.]
+* Fix disable iff ignored when its condition is held continuously true (#7841). [Yilou Wang]
+* Fix constant pool cache after dead scope removal (#7845). [Nick Brereton]
+* Fix covergroups without --coverage (#7848) (#7849). [Joshua Leahy]
+* Fix class scope '::' reference through an inherited type parameter (#7844). [Sergey Chusov]
+
+
+Verilator 5.048 2026-04-26
+==========================
+
+**Important:**
+
+* Displaying Verilator generated FST files will require an updated version
+  of Surfer (built from 'main', or the future numbered release 0.7.0).
+  No GTKWave update is necessary (#7255).
+* Support jemalloc as the default allocator on Linux (#7250). [Yangyu Chen]
+  For better performance, `apt install libjemalloc-dev` or equivalent before running ./configure.
+
+**Other:**
+
+* Add VPI callback support to `--main` (#7145).
+* Add `--func-recursion-depth` option (#7175) (#7179).
+* Add `+verilator+solver+file` for debugging constraint solver (#7242).
+* Add `--coverage-fsm` for experimental FSM state and arc coverage (#7412). [Yogish Sekhar]
+* Add printed summary to verilator_coverage (#7438) (#7462). [Yogish Sekhar]
+* Deprecate `--structs-packed` (#7222).
+* Remove DFG extract optimization pass (#7394). [Geza Lore, Testorrent USA, Inc.]
+* Remove multi-threaded FST tracing (#7443). [Geza Lore, Testorrent USA, Inc.]
+* Improve assignment-compatibility type check (#2843) (#5666) (#7052). [Pawel Kojma, Antmicro Ltd.]
+* Improve error message when variable used as data type (#7318). [Ryszard Rozak, Antmicro Ltd.]
+* Improve E_UNSUPPORTED warning messages (#7329). [Eunseo Song]
+* Improve NFA-based multi-cycle SVA evaluation engine (#7430). [Yilou Wang]
+* Change array tracing to dump left index to right index (#7205). [Geza Lore, Testorrent USA, Inc.]
+* Change `--converge-limit` default to 10000 (#7209).
+* Support inout inside SV interface (#3466) (#7134) (#7708) (#7710). [Nick Brereton]
+* Support `##0` cycle delays (#4263) (#7298). [Yilou Wang]
+* Support multidimensional arrays of interfaces (#6230) (#7451). [em2machine]
+* Support array reduction methods with 'with' clause in constraints (#6455) (#6999). [Rahul Behl]
+* Support constraint imperfect distributions (#6811) (#7168). [Yilou Wang]
+* Support disable task by name (#6853) (#7136). [Nick Brereton]
+* Support procedural concurrent assertion simple cases (#6944).
+* Support force assignments to array elements of real type (#7048). [Ryszard Rozak, Antmicro Ltd.]
+* Support VPI array indexing in signal names (#7097) (#7187) (#7214) (#7289). [Christian Hecken, Heidelberg University]
+* Support soft constraint solving (#7124) (#7166). [Yilou Wang]
+* Support constraints on fixed-size array of class object members (#7170) (#7183). [Yilou Wang]
+* Support Z non-blocking assignment (#7192) (#496) (#7197). [Nick Brereton]
+* Support constraint `with` item.index array reduction (#7198). [Rahul Behl]
+* Support constant expressions without parentheses in `PATHPULSE$` (#7199). [Pawel Kojma, Antmicro Ltd.]
+* Support $sformat with runtime format string (#7212).
+* Support dist and solve...before inside foreach constraints (#7245) (#7253). [Yilou Wang]
+* Support array and struct info metadata in FST traces (#7255). [Geza Lore, Testorrent USA, Inc.]
+* Support dynamic array .size in inline randomize() with constraints (#7258) (#7266). [Yilou Wang]
+* Support defparam with more than one dot (#7262). [Artur Bieniek, Antmicro Ltd.]
+* Support modport export/import task prototypes and out-of-block definitions (#7277). [Yilou Wang]
+* Support very wide $display arguments (#7280). [Jakub Michalski]
+* Support named sequence declarations and instances in assertions  (#7283). [Yilou Wang]
+* Support `##`, `##[*]`, `##[+]`, `##[M:N]` cycle delays in assertions (#7284) (#7312) (#7377). [Yilou Wang]
+* Support boolean and/or in sequence expressions (#7285). [Yilou Wang]
+* Support property-local variables and sequence match items (#7286). [Yilou Wang]
+* Support 'until' and `until_with` property (#7290 partial) (#7399) (#7436). [Ryszard Rozak, Antmicro Ltd.]
+* Support implication operator with constraint_set (#7300) (#7448). [Yilou Wang]
+* Support array map() method (#7307) (#7316) (#7344). [Wei-Lun Chiu]
+* Support MacOS address sanitizer memory limit (#7308). [Marco Bartoli]
+* Support SVA goto repetition `[->N]` in concurrent assertions (#7310). [Yilou Wang]
+* Support consecutive repetition `[\*N]` in SVA properties (#7311). [Yilou Wang]
+* Support rise/fall delays (#7368). [Artur Bieniek, Antmicro Ltd.]
+* Support sequence intersect operator (#7374). [Yilou Wang]
+* Support sequence 'throughout' operator (#7378). [Yilou Wang]
+* Support sequence consecutive repetition `[*N:M]`, `[+]`, and `[*]` (#7379). [Yilou Wang]
+* Support sequence `first_match` operator (#7392). [Yilou Wang]
+* Support nonconsecutive repetition [=N] in sequence expressions (#7397). [Yilou Wang]
+* Support per-process RNG for process::srandom() and object seeding (#7408) (#7415) (#7408). [Yilou Wang]
+* Support 2**n expressions in constraint randomization (#7422). [Yilou Wang]
+* Support IEEE-compliant force/release handling (#7391). [Artur Bieniek, Antmicro Ltd.]
+* Support sequence 'within' operator (#7461). [Yilou Wang]
+* Optimize trace code for faster compiles on repeated types (#6707) (#6832). [Todd Strader]
+* Optimize impure expressions and calls with new V3LiftExpr pass (#7141) (#7164). [Geza Lore, Testorrent USA, Inc.]
+* Optimize size of trace declaration object code (#7150). [Szymon Gizler, Antmicro Ltd.]
+* Optimize function call return value temporaries (#7152). [Geza Lore, Testorrent USA, Inc.]
+* Optimize conditional merging across some impure statements (#7159). [Geza Lore, Testorrent USA, Inc.]
+* Optimize reuse of existing associative terms in DfgPeephole. [Geza Lore, Testorrent USA, Inc.]
+* Optimize duplicate vertices and multiplexers in DfgPeephole (#7305). [Geza Lore, Testorrent USA, Inc.]
+* Optimize commutative vertex operands in DFG for better combining. [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG peephole until a fixed point (#7309). [Geza Lore, Testorrent USA, Inc.]
+* Optimize comparisons with identical operands and $countones in DFG. [Geza Lore, Testorrent USA, Inc.]
+* Optimize more patterns in DfgPeephole (#7332). [Geza Lore, Testorrent USA, Inc.]
+* Optimize read references in DFG (#7354). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DFG only once, after scoping (#7362). [Geza Lore, Testorrent USA, Inc.]
+* Optimize more DFG peephole patterns (#7423) (#7452). [Geza Lore, Testorrent USA, Inc.]
+* Optimize DfgBreakCycles IndependentBits analysis ordering (#7446). [Geza Lore, Testorrent USA, Inc.]
+* Optimize select patterns in DfgPeephole. [Geza Lore, Testorrent USA, Inc.]
+* Optimize temporary insertion in DfgPeephole. [Geza Lore, Testorrent USA, Inc.]
+* Optimize arithmetic right shift (>>>) in DfgBreakCycles (#7447). [Geza Lore, Testorrent USA, Inc.]
+* Optimize temporary insertion in DFG (#7459). [Geza Lore, Testorrent USA, Inc.]
+* Optimize mix of Concat/Extend assignments (#7479). [Geza Lore, Testorrent USA, Inc.]
+* Fix recursive default assignment for sub-arrays (#4589) (#7202). [Julian Carrier]
+* Fix tracing virtual interface member written from classes (#5044) (#7465). [Nikolay Puzanov]
+* Fix virtual interface member trigger convergence (#5116) (#7323). [Yilou Wang]
+* Fix shift width mismatch in constraint solver SMT emission (#5420) (#7265). [Yilou Wang]
+* Fix returning wrong type from static function in parameterized class (#5479) (#7387) (#7411) (#7418) (#7445) (#7450). [em2machine]
+* Fix randomize size+element queue constraints (#5582) (#7225). [Rahul Behl, Testorrent USA, Inc.]
+* Fix null assignment to virtual interfaces (#5974) (#5990). [Maxim Fonarev]
+* Fix typedef scope resolution for parameterized class aliases (#5977) (#7319). [Nick Brereton]
+* Fix lambda coroutines (#6106) (#7135). [Nick Brereton]
+* Fix super constructor calls with local variables (#6214) (#6933). [Igor Zaworski, Antmicro Ltd.]
+* Fix parameter default comparison when value contains type cast (#6281) (#7369) (#6281). [Yilou Wang]
+* Fix `local::` false error in randomize() with on parameterized class (#6680) (#7293). [Yilou Wang]
+* Fix false recursive definition error (#6769) (#7118). [Alex Zhou]
+* Fix port assignment to large arrays (#6904).
+* Fix interface localparam dependencies and arbitrary nesting (#6936) (#7128) (#7188) (#7190). [em2machine]
+* Fix parameterized class typedef as interface type parameter (#7000) (#7006). [Leela Pakanati]
+* Fix errant integer promotion (#7012). [Todd Strader]
+* Fix randc solver hang with wide variables (#7068) (#7248). [Yilou Wang]
+* Fix coroutine trace setters (#7078 repair) (#7296). [Igor Zaworski, Antmicro Ltd.]
+* Fix vpi_put_value not updating forced read value (#7092) (#7395) (#7092). [Christian Hecken, Heidelberg University]
+* Fix scheduling non-determinism (#7120) (#7162) (#7165). [Geza Lore, Testorrent USA, Inc.]
+* Fix parameters inside std::randomize `with` clause  (#7140). [Kamil Danecki, Antmicro Ltd.]
+* Fix forcing unpacked variables (#7149). [Ryszard Rozak, Antmicro Ltd.]
+* Fix wide conditional short circuiting (#7155).
+* Fix eliminating assignments to DPI-read variables (#7158). [Geza Lore, Testorrent USA, Inc.]
+* Fix std::randomize() in static function with static class members (#7167) (#7169). [Yilou Wang]
+* Fix resolving default/non-default type parameters (#7171) (#7346) (#7380) (#7385) (#7398) (#7406) (#7398). [em2machine]
+* Fix recursive constant function in $unit scope (#7173) (#7174).
+* Fix class extend references between queues (#7195).
+* Fix library/hier_block tracing when top name is empty (#7200). [Geza Lore, Testorrent USA, Inc.]
+* Fix virtual interface select from sub-interface instance (#7203) (#7370) (#7203). [Yilou Wang]
+* Fix VPI force of bit-selected signals (#7211) (#7301). [Christian Hecken]
+* Fix `$finish` to immediately stop executing code from non-final blocks (#7213 partial) (#7390).
+* Fix wrong $bits() for parameterized interface struct typedefs (#7218) (#7219). [em2machine]
+* Fix `dist` operator inside constraint if blocks (#7221) (#7224). [Rahul Behl, Testorrent USA, Inc.]
+* Fix array reduction in constraints crashing with class inheritance (#7226) (#7263). [Yilou Wang]
+* Fix soft cross-object constraint priority inversion (#7228) (#7233). [Yilou Wang]
+* Fix internal error when derived class calls this.randomize() with inherited rand members (#7229) (#7234). [Yilou Wang]
+* Fix enum range constraints missing for rand variables in sub-objects (#7230) (#7235). [Yilou Wang]
+* Fix vpi_put_value release on non-continuous signal (#7231) (#7241). [Christian Hecken]
+* Fix functions in generate block resulting in 'Broken link in node' (#7236) (#7367). [em2machine]
+* Fix tracing of typedefed 1D packed arrays with --trace-structs (#7237). [Geza Lore, Testorrent USA, Inc.]
+* Fix rand variable used as array index in constraint evaluated as constant (#7238) (#7247). [Yilou Wang]
+* Fix --hierarchical dropping arguments in -f/-F files (#7240). [Clara Sparks]
+* Fix `final` asserts and $stop (#7249). [Artur Bieniek, Antmicro Ltd.]
+* Fix MacOS clang PCH compile error with -o flag (#7251) (#7327). [Eunseo Song]
+* Fix vpi_put_value with vpiIntVal on VlWide data (#7256). [Christian Hecken]
+* Fix streaming with descending unpacked arrays and unpacked-to-queue (#7287). [Yilou Wang]
+* Fix MacOs lexer compile error (#7314) (#7315). [Tracy Narine]
+* Fix linking shared library with its dependencies (#7320). [Artur Bieniek, Antmicro Ltd.]
+* Fix modport selection of virtual interface handle (#7321). [Yilou Wang]
+* Fix false ASSIGNIN on interface input ports driven from outside (#7322). [Yilou Wang]
+* Fix static initialization order for packages with class hierarchies (#7324). [Yilou Wang]
+* Fix sensitivity of signals to unrelated interface members (#7336). [Artur Bieniek, Antmicro Ltd.]
+* Fix `disable iff` imply-delay statement linking (#7337). [Nick Brereton]
+* Fix lost `$stop` on implied assertion `$error` failures.
+* Fix wait() hang when interface uses process calls and VIF function (#7342). [Yilou Wang]
+* Fix error on illegal nand/nor binary operators (#7353).
+* Fix simple array assignment unrolling in slice optimization (#7359). [Geza Lore, Testorrent USA, Inc.]
+* Fix missing temporary for DfgSplicePacked (#7361). [Geza Lore, Testorrent USA, Inc.]
+* Fix virtual interface function calls binding to wrong instance (#7363). [Yilou Wang]
+* Fix false ASSIGNIN on interface input port connections (#7365). [Yilou Wang]
+* Fix string `inside` queue (#7373).
+* Fix subclass with rand_mode(0) getting randomized (#7376) (#7383). [Yilou Wang]
+* Fix VPI access to Verilog `force`-ed signals (#7381). [Christian Hecken, Heidelberg University]
+* Fix sampling of hierarchical references (#7386). [Ryszard Rozak, Antmicro Ltd.]
+* Fix virtual class inheritance false error (#7403) (#7405). [Nikolay Puzanov]
+* Fix CMake compiler coroutine flags (#7404). [Shogo Yamazaki]
+* Fix delete inside foreach skipping elements (#7407) (#7410)
+* Fix std::randomize in parameterized-derived class (#7409) (#7416). [Yilou Wang]
+* Fix virtual interface implied comparison with null (#7421). [Alex Solomatnikov]
+* Fix uvm_hdl_release_and_read to release value and check success (#7425). [Christian Hecken, Heidelberg University]
+* Fix inline constraint on array-indexed randomize target (#7431) (#7434). [Yilou Wang]
+* Fix modification of members of object with const handle (#7433). [Kamil Danecki, Antmicro Ltd.]
+* Fix `dist` under implication in constraints (#7440) (#7442). [Alex Solomatnikov] [Yilou Wang]
+* Fix std::randomize `inside` corrupting class-member queue operand (#7449) (#7456). [Yilou Wang]
+* Fix module parameters not re-evaluated upon instantiation (#7463) (#7477). [em2machine]
+* Fix function-in-constraint internal error on bare port return (#7473) (#7480). [Yilou Wang]
+* Fix access to static variable inside function (#7474) (#7475). [Alex Zhou]
+* Fix multiple inclusion of verilated_std.sv (#7478). [Larry Doolittle]
+* Fix std::randomize inside {typedef array} internal error (#7481). [Yilou Wang]
+* Fix module parameters not re-evaluated upon instantiation (#7463) (#7477). [em2machine]
+* Fix infinite recursion with VERILATOR_BIN (#7496) (#7497).
+* Add error on mixed declaration initialization with continuous assignment (#7352). [Zhi QU]
+
 Verilator 5.046 2026-02-28
 ==========================
 
@@ -31,7 +406,7 @@ Verilator 5.046 2026-02-28
 * Support solve..before constraints (#5647) (#7123). [Yilou Wang]
 * Support structure initial values (#6130).
 * Support proper automatic/static initialization, and remove STATICVAR warning (#6405) (#7086).
-* Support vpi_put/vpi_get forcing of signals (#5933) (#6704). [Christian Hecken]
+* Support vpi_put/vpi_get forcing of signals (#5933) (#6704). [Christian Hecken, Heidelberg University]
 * Support detailed failure info for constraint violations (#6617) (#6883). [Yilou Wang]
 * Support `unique` constraints (on 1D static arrays) (#6810) (#6878). [Srinivasan Venkataramanan]
 * Support complex expressions as std::randomize arguments (#6860). [Jakub Wasilewski, Antmicro Ltd.]
@@ -94,7 +469,7 @@ Verilator 5.046 2026-02-28
 * Fix `foreach` with mid-index empty commas (#6910).
 * Fix internal error when fork under always expression (#6911).
 * Fix error when calling non-static method (#6916). [Artur Bieniek, Antmicro Ltd.]
-* Fix memory leak in vpi_put_value and vpi_get_value (#6917). [Christian Hecken]
+* Fix memory leak in vpi_put_value and vpi_get_value (#6917). [Christian Hecken, Heidelberg University]
 * Fix interface internal type reference (#6920) (#6966). [Todd Strader]
 * Fix segfault after assignment pattern XOR error (#6928) (#6931). [emmettifelts]
 * Fix delayed initial assignment (#6929). [Todd Strader]
@@ -169,7 +544,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.]
@@ -513,7 +888,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]
@@ -2169,7 +2544,6 @@ Verilator 4.108 2021-01-10
 * Fix to ignore coverage on real ports (#2741) (#2745). [Paul Wright]
 
 
-
 Verilator 4.106 2020-12-02
 ==========================
 
@@ -2576,7 +2950,6 @@ Verilator 4.018 2019-08-29
 * Fix internal error on gate optimization of assign. (#1475) [Oyvind Harboe]
 
 
-
 Verilator 4.016 2019-06-16
 ==========================
 
@@ -5027,7 +5400,6 @@ Verilator 3.270 2004-10-15
 * Fix numeric fault when dividing by zero.
 
 
-
 Verilator 3.260 2004-10-07
 ==========================
 

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

@@ -260,7 +260,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 +292,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 +310,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 +355,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
@@ -398,9 +397,12 @@ CPPCHECK_RUNTIME_CPP = $(wildcard $(srcdir)/include/*.cpp)
 CPPCHECK_VLC_CPP = $(wildcard $(srcdir)/src/Vlc*.cpp)
 CPPCHECK_EXAMPLES_CPP = $(wildcard $(srcdir)/examples/*/*.cpp)
 CHECK_CPP = $(CPPCHECK_VERILATOR_CPP) $(CPPCHECK_RUNTIME_CPP) $(CPPCHECK_VLC_CPP) $(CPPCHECK_EXAMPLES_CPP)
-CHECK_H = $(wildcard \
+CHECK_H = $(filter-out \
+  $(srcdir)/src/config_package.h \
+  $(srcdir)/src/config_rev.h, \
+  $(wildcard \
   $(srcdir)/include/*.h \
-  $(srcdir)/src/*.h )
+  $(srcdir)/src/*.h ))
 CHECK_YL = $(wildcard \
   $(srcdir)/src/*.y \
   $(srcdir)/src/*.l )
@@ -414,7 +416,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
@@ -441,7 +443,9 @@ cppcheck:
 CLANGTIDY = clang-tidy
 CLANGTIDY_FLAGS = -config='' \
   -header-filter='.*' \
-  -checks='-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
 
 CLANGTIDY_DEP = $(subst .cpp,.cpp.tidy,$(CHECK_CPP))
 CLANGTIDY_DEFS = -DVL_DEBUG=1 -DVL_CPPCHECK=1
@@ -491,6 +495,11 @@ MAKE_FILES = \
   src/Makefile*.in \
   test_regress/Makefile* \
 
+# Markdown
+MD_FILES = \
+  *.md \
+  */*.md \
+
 # Perl programs
 PERL_PROGRAMS = \
   bin/redirect \
@@ -517,6 +526,7 @@ PY_PROGRAMS = \
   nodist/lint_py_test_filter \
   nodist/log_changes \
   nodist/uvm_pkg_packer \
+  nodist/verilator_bisect \
   nodist/verilator_saif_diff \
   src/.gdbinit.py \
   src/astgen \
@@ -530,11 +540,19 @@ PY_PROGRAMS = \
 # 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 \
@@ -547,7 +565,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
@@ -577,13 +595,20 @@ MBAKE = mbake
 MBAKE_FLAGS = format --config ./.bake.toml
 
 format-exec:
-	-chmod a+x test_regress/t/*.py
+	-chmod a+x test_regress/t/t_*.py
 	-chmod a-x test_regress/t/*.v
 
 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
 
@@ -591,6 +616,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 =
 
@@ -678,7 +710,7 @@ FASTCOV_OPT += --dump-statistic
 FASTCOV_OPT += --exclude-glob
 FASTCOV_OPT += '/usr/*'
 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*'

README.rst

@@ -1,58 +1,63 @@
-.. 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| 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
+
 .. |badge8| image:: https://img.shields.io/github/actions/workflow/status/verilator/verilator/rtlmeter.yml?branch=master&event=schedule&label=benchmarks
    :target: https://verilator.github.io/verilator-rtlmeter-results
 
-
 Welcome to Verilator
 ====================
 
 .. list-table::
 
-   * - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
-        * Accepts Verilog or SystemVerilog
-        * Performs lint code-quality checks
-        * Compiles into multithreaded C++, or SystemC
-        * Creates JSON to front-end your own tools
+   - - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
+          - Accepts Verilog or SystemVerilog
+          - Performs lint code-quality checks
+          - Compiles into multithreaded C++, or SystemC
+          - Creates JSON to front-end your own tools
      - |Logo|
-   * - |verilator multithreaded performance|
+   - - |verilator multithreaded performance|
      - **Fast**
-        * Outperforms many closed-source commercial simulators
-        * Single- and multithreaded output models
-   * - **Widely Used**
-        * Wide industry and academic deployment
-        * Out-of-the-box support from Arm and RISC-V vendor IP
-        * Over 700 contributors
+          - Outperforms many closed-source commercial simulators
+          - Single- and multithreaded output models
+   - - **Widely Used**
+          - Wide industry and academic deployment
+          - Out-of-the-box support from Arm and RISC-V vendor IP
+          - Over 700 contributors
      - |verilator usage|
-   * - |verilator community|
+   - - |verilator community|
      - **Community Driven & Openly Licensed**
-        * Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
-        * Open, and free as in both speech and beer
-        * More simulation for your verification budget
-   * - **Commercial Support Available**
-        * Commercial support contracts
-        * Design support contracts
-        * Enhancement contracts
+          - Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
+          - Open, and free as in both speech and beer
+          - More simulation for your verification budget
+   - - **Commercial Support Available**
+          - Commercial support contracts
+          - Design support contracts
+          - Enhancement contracts
      - |verilator support|
 
-
 What Verilator Does
 ===================
 
@@ -77,7 +82,6 @@ SDF annotation, or mixed-signal simulation. However, if you are looking for
 a path to migrate SystemVerilog to C++/SystemC, or want high-speed
 simulation, Verilator is the tool for you.
 
-
 Performance
 ===========
 
@@ -96,7 +100,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 +118,6 @@ For more information:
 
 - `Verilator issues <https://verilator.org/issues>`_
 
-
 Support
 =======
 
@@ -132,7 +134,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 +150,6 @@ Related Projects
 - `Surfer <https://surfer-project.org/>`_ - Web or offline waveform viewer
   for Verilator traces.
 
-
 Open License
 ============
 
@@ -161,10 +161,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",
@@ -15,6 +15,7 @@ path = [
     ".style.yapf",
     "CITATION.cff",
     "CPPLINT.cfg",
+    "ci/docker/buildenv/wavetools.conf",
     "docs/CONTRIBUTORS",
     "docs/spelling.txt",
     "docs/verilated.dox",

bin/verilator

@@ -27,6 +27,21 @@ use vars qw($Debug @Opt_Verilator_Sw);
 autoflush STDOUT 1;
 autoflush STDERR 1;
 
+# Guard against unbounded recursive re-entry. Hierarchical / --build flows
+# legitimately re-enter the wrapper a few levels deep (wrapper -> verilator_bin
+# -> make -> wrapper -> ...); a misconfigured VERILATOR_BIN, VERILATOR_GDB or
+# VERILATOR_VALGRIND that points back at this wrapper, however, recurses
+# without bound and exhausts the OS PID table. Use VERILATOR_RUNNING as a
+# depth counter and cap it well above any real nesting.
+my $verilator_running_max = 16;
+my $verilator_running_depth = ($ENV{VERILATOR_RUNNING} || 0) + 1;
+if ($verilator_running_depth > $verilator_running_max) {
+    die "%Error: verilator: re-entered $verilator_running_depth levels deep"
+        . " via \$VERILATOR_RUNNING; check that VERILATOR_BIN, VERILATOR_GDB"
+        . " and VERILATOR_VALGRIND do not resolve back to this wrapper script.\n";
+}
+$ENV{VERILATOR_RUNNING} = $verilator_running_depth;
+
 $Debug = 0;
 my $opt_aslr;
 my $opt_gdb;
@@ -86,9 +101,15 @@ if (defined $ENV{VERILATOR_ROOT}) {
     $ENV{VERILATOR_ROOT} = $verilator_root;
 }
 
-if ($opt_gdbbt && !gdb_works()) {
-    warn "-Info: --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
-    $opt_gdbbt = 0;
+my $lldb_selected = 0;
+if (($opt_gdb || $opt_gdbbt) && !gdb_works()) {
+    if (lldb_works()) {
+        $lldb_selected = 1;
+    } else {
+        warn "-Info: --gdb or --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
+        $opt_gdbbt = 0;
+        $opt_gdb = 0;
+    }
 }
 
 # Determine runtime flags and run
@@ -98,22 +119,35 @@ if ($opt_gdbbt && !gdb_works()) {
 # then see exactly the contents of @Opt_Verilator_Sw.
 my @quoted_sw = map { sh_escape($_) } @Opt_Verilator_Sw;
 if ($opt_gdb) {
-    # Generic GDB interactive
-    run (ulimit_stack_unlimited()
-         . aslr(0)
-         . ($ENV{VERILATOR_GDB} || "gdb")
-         . " " . verilator_bin()
-         # Note, uncomment to set breakpoints before running:
-         #  ." -ex 'break main'"
-
-         # Note, we must use double-quotes ("run <switches>")
-         # and not single ('run <switches>') below. Bash swallows
-         # escapes as you would expect in a double-quoted string.
-         # That's not true for a single-quoted string, where \'
-         # actually terminates the string -- not what we want!
-         . " -ex \"run " . join(' ', @quoted_sw) . "\""
-         . " -ex 'set width 0'"
-         . " -ex 'bt'");
+    # Note, we must use double-quotes ("run <switches>")
+    # and not single ('run <switches>') below. Bash swallows
+    # escapes as you would expect in a double-quoted string.
+    # That's not true for a single-quoted string, where \'
+    # actually terminates the string -- not what we want!
+    if ($lldb_selected) {
+        # Generic lldb interactive
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "lldb")
+             . " " . verilator_bin()
+             # Note, uncomment to set breakpoints before running:
+             #  . " -o 'b main'"
+             . " -o 'b exit'"  # Need break to keep process active for bt
+             . " -o \"run " . join(' ', @quoted_sw) . "\""
+             . " -o 'settings set term-width 1024'"
+             . " -o 'bt'");
+    } else {
+        # Generic GDB interactive
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "gdb")
+             . " " . verilator_bin()
+             # Note, uncomment to set breakpoints before running:
+             #  . " -ex 'break main'"
+             . " -ex \"run " . join(' ', @quoted_sw) . "\""
+             . " -ex 'set width 0'"
+             . " -ex 'bt'");
+    }
 } elsif ($opt_rr) {
     # Record with rr
     run (ulimit_stack_unlimited()
@@ -121,15 +155,27 @@ if ($opt_gdb) {
          . "rr record " . verilator_bin()
          . " " . join(' ', @quoted_sw));
 } elsif ($opt_gdbbt && $Debug) {
-    # Run under GDB to get gdbbt
-    run (ulimit_stack_unlimited()
-         . aslr(0)
-         . "gdb"
-         . " " . verilator_bin()
-         . " --batch --quiet --return-child-result"
-         . " -ex \"run " . join(' ', @quoted_sw)."\""
-         . " -ex 'set width 0'"
-         . " -ex 'bt' -ex 'quit'");
+    # Run under debugger to get gdbbt
+    if ($lldb_selected) {
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "lldb")
+             . " " . verilator_bin()
+             . " -o 'b exit'"  # Need break to keep process active for bt
+             . " --batch --source-quietly"
+             . " -o \"run " . join(' ', @quoted_sw)."\""
+             . " -o 'settings set term-width 1024'"
+             . " -o 'bt' -o 'quit'");
+    } else {
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "gdb")
+             . " " . verilator_bin()
+             . " --batch --quiet --return-child-result"
+             . " -ex \"run " . join(' ', @quoted_sw)."\""
+             . " -ex 'set width 0'"
+             . " -ex 'bt' -ex 'quit'");
+    }
 } elsif ($opt_valgrind) {
     # Run under valgrind
     my $valgrind_bin = ($ENV{VERILATOR_VALGRIND} || "valgrind --error-exitcode=1 --max-stackframe=2815880"
@@ -149,7 +195,7 @@ if ($opt_gdb) {
         . verilator_bin()
         . " " . join(' ', @quoted_sw));
 } else {
-    # Normal, non gdb
+    # Normal, non-gdb
     run(ulimit_stack_unlimited() . aslr(1) . verilator_bin() . " " . join(' ', @quoted_sw));
 }
 
@@ -185,9 +231,9 @@ sub verilator_bin {
 
 sub gdb_works {
     $! = undef;  # Cleanup -x
-    system("gdb /bin/echo"
+    system("gdb /bin/sh"
            . " --batch-silent --quiet --return-child-result"
-           . " -ex 'run -n'"  # `echo -n`
+           . " -ex 'run -c exit'"  # `/bin/sh -c exit
            . " -ex 'set width 0'"
            . " -ex 'bt'"
            . " -ex 'quit'");
@@ -195,6 +241,18 @@ sub gdb_works {
     return $status == 0;
 }
 
+sub lldb_works {
+    $! = undef;  # Cleanup -x
+    # macOS system integrity stops attach to system binaries like /bin/sh
+    system("lldb --version"
+           . " --batch --source-quietly"
+           . " -o 'settings set term-width 1024'"
+           . " -o 'bt'"
+           . " -o 'quit'");
+    my $status = $?;
+    return $status == 0;
+}
+
 sub aslr {
     my $want_on = shift;
     $want_on = $opt_aslr if defined $opt_aslr;
@@ -213,14 +271,22 @@ sub ulimit_stack_unlimited {
     # AddressSanitizer doesn't work with 'ulimit -s unlimted'
     if (`${\(verilator_bin())} --get-supported DEV_ASAN` eq "1\n") {
         # Use host 'physical memory / #cores / 8' instead
-        open(my $fh, "<", "/proc/meminfo") || die "Can't read host memory for asan";
-        while (<$fh>) {
-            if (m/MemTotal:\s+(\d+)\s+kB/) {
-                $limit = int(int($1)/`nproc`/8);
-                last;
+        if ($^O eq "darwin") {
+            my $membytes = `sysctl -n hw.memsize`;
+            chomp $membytes;
+            my $ncpu = `sysctl -n hw.ncpu`;
+            chomp $ncpu;
+            $limit = int(int($membytes / 1024) / $ncpu / 8);
+        } else {
+            open(my $fh, "<", "/proc/meminfo") || die "Can't read host memory for asan";
+            while (<$fh>) {
+                if (m/MemTotal:\s+(\d+)\s+kB/) {
+                    $limit = int(int($1)/`nproc`/8);
+                    last;
+                }
             }
+            close($fh);
         }
-        close($fh);
     }
     system("ulimit -s $limit 2>/dev/null");
     my $status = $?;
@@ -334,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
@@ -345,12 +412,15 @@ detailed descriptions of these arguments.
      -CFLAGS <flags>            C++ compiler arguments for makefile
     --compiler <compiler-name>  Tune for specified C++ compiler
     --compiler-include          Include additional header in the precompiled one
+    --constraint-array-limit <size>   Maximum array size for constraint array reduction
     --converge-limit <loops>    Tune convergence settle time
     --coverage                  Enable all coverage
     --coverage-expr             Enable expression coverage
     --coverage-expr-max <value>     Maximum permutations allowed for an expression
+    --coverage-fsm              Enable FSM state/arc coverage
     --coverage-line             Enable line coverage
     --coverage-max-width <width>   Maximum array depth for coverage
+    --coverage-per-instance     Enable per-instance coverage counters
     --coverage-toggle           Enable toggle coverage
     --coverage-underscore       Enable coverage of _signals
     --coverage-user             Enable SVL user coverage
@@ -368,8 +438,10 @@ detailed descriptions of these arguments.
     --diagnostics-sarif-output <filename>  Set SARIF diagnostics output file
     --dpi-hdr-only              Only produce the DPI header file
     --dump-<srcfile>            Enable dumping everything in source file
+    --dump-ast-patterns         Enable dumping Ast pattern statistics
     --dump-defines              Show preprocessor defines with -E
     --dump-dfg                  Enable dumping DfgGraphs to .dot files
+    --dump-dfg-patterns         Enable dumping Dfg pattern statistics
     --dump-graph                Enable dumping V3Graphs to .dot files
     --dump-inputs               Enable dumping preprocessed input files
     --dump-tree                 Enable dumping Ast .tree files
@@ -390,6 +462,9 @@ 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
      -fno-<optimization>        Disable internal optimization stage
@@ -496,7 +571,6 @@ detailed descriptions of these arguments.
     --no-std-package            Prevent parsing standard package
     --no-std-waiver             Prevent parsing standard lint waivers
     --no-stop-fail              Do not call $stop when assertion fails
-    --structs-packed            Convert all unpacked structures to packed structures
      -sv                        Enable SystemVerilog parsing
      +systemverilogext+<ext>    Synonym for +1800-2023ext+<ext>
     --threads <threads>         Enable multithreading
@@ -517,7 +591,6 @@ detailed descriptions of these arguments.
     --trace-params              Enable tracing of parameters
     --trace-saif                Enable SAIF file creation
     --trace-structs             Enable tracing structure names
-    --trace-threads <threads>   Enable FST waveform creation on separate threads
     --no-trace-top              Do not emit traces for signals in the top module generated by verilator
     --trace-underscore          Enable tracing of _signals
     --trace-vcd                 Enable VCD waveform creation
@@ -568,6 +641,7 @@ description of these arguments.
      +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
@@ -576,8 +650,10 @@ description of these arguments.
      +verilator+quiet                      Minimize additional printing
      +verilator+rand+reset+<value>         Set random reset technique
      +verilator+seed+<value>               Set random seed
+     +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

@@ -52,7 +52,7 @@ if (! GetOptions (
     pod2usage(-exitstatus => 2, -verbose => 0);
 }
 
-# Normal, non gdb
+# Normal, non-gdb
 run(verilator_coverage_bin()
     . " " . join(' ', @Opt_Verilator_Sw));
 
@@ -157,6 +157,10 @@ verilator_coverage - Verilator coverage analyzer
 
     verilator_coverage --annotate <obj>
 
+    verilator_coverage --report summary,hier <datafiles>...
+
+    verilator_coverage --report hier <datafiles>...
+
     verilator_coverage  -write merged.dat <datafiles>...
 
     verilator_coverage  -write-info merged.info <datafiles>...
@@ -175,7 +179,10 @@ L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
     --annotate-points             Annotates info from each coverage point.
     --filter-type <regex>         Keep only records of given coverage type.
     --help                        Displays this message and version and exits.
+    --include-reset-arcs          Include reset arcs in FSM arc summaries.
+    --levels <depth>              Limit displayed hierarchy report depth.
     --rank                        Compute relative importance of tests.
+    --report <kind>[,<kind>...]   Generate reports: summary, hier, or hierarchy.
     --unlink                      With --write, unlink all inputs
     --version                     Displays program version and exits.
     --write <filename>            Write aggregate coverage results.

ci/ci-install.bash

@@ -30,7 +30,7 @@ elif [ "$CI_OS_NAME" = "osx" ]; then
 elif [ "$CI_OS_NAME" = "freebsd" ]; then
   MAKE=gmake
 else
-  fatal "Unknown os: '$CI_OS_NAME'"
+  fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
 fi
 
 if [ "$CI_OS_NAME" = "linux" ]; then
@@ -40,12 +40,32 @@ if [ "$CI_OS_NAME" = "linux" ]; then
   echo "path-exclude /usr/share/info/*" | sudo tee -a /etc/dpkg/dpkg.cfg.d/01_nodoc
 fi
 
-install-vcddiff() {
-  TMP_DIR="$(mktemp -d)"
-  git clone https://github.com/veripool/vcddiff "$TMP_DIR"
-  git -C "${TMP_DIR}" checkout 4db0d84a27e8f148b127e916fc71d650837955c5
-  "$MAKE" -C "${TMP_DIR}"
-  sudo cp "${TMP_DIR}/vcddiff" /usr/local/bin
+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
+    _platform="linux-x86_64"
+  elif [ "$CI_OS_NAME" = "osx" ]; 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"
+    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
+  sudo cp "${_tmpdir}/${_archive}/wavediff" /usr/local/bin/wavediff
+  rm -rf "${_tmpdir}"
 }
 
 if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
@@ -56,20 +76,22 @@ if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
   if [ "$CI_OS_NAME" = "linux" ]; then
     sudo apt-get update ||
     sudo apt-get update
-    sudo apt-get install ccache help2man libfl-dev ||
-    sudo apt-get install ccache help2man libfl-dev
+    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 libgoogle-perftools-dev ||
-      sudo apt-get install libgoogle-perftools-dev
+      sudo apt-get install --yes libjemalloc-dev ||
+      sudo apt-get install --yes libjemalloc-dev
     fi
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-20.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]]; then
-      sudo apt-get install libsystemc libsystemc-dev ||
-      sudo apt-get install libsystemc libsystemc-dev
+    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
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]]; then
-      sudo apt-get install bear mold ||
-      sudo apt-get install bear mold
+    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 ||
@@ -79,7 +101,7 @@ if [ "$CI_BUILD_STAGE_NAME" = "build" ]; then
   elif [ "$CI_OS_NAME" = "freebsd" ]; then
     sudo pkg install -y autoconf bison ccache gmake perl5
   else
-    fatal "Unknown os: '$CI_OS_NAME'"
+    fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
   fi
 
   if [ -n "$CCACHE_DIR" ]; then
@@ -94,16 +116,18 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
     sudo apt-get update ||
     sudo apt-get update
     # libfl-dev needed for internal coverage's test runs
-    sudo apt-get install gdb gtkwave lcov libfl-dev ccache jq z3 ||
-    sudo apt-get install gdb gtkwave lcov libfl-dev ccache jq z3
+    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" ]]; then
-      sudo apt-get install python3-clang mold ||
-      sudo apt-get install python3-clang mold
+    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
     fi
-    if [[ "$CI_RUNS_ON" =~ "ubuntu-20.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-22.04" ]] || [[ "$CI_RUNS_ON" =~ "ubuntu-24.04" ]]; then
-      sudo apt-get install libsystemc-dev ||
-      sudo apt-get install libsystemc-dev
+    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
@@ -113,14 +137,14 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
     # fst2vcd fails with "Could not open '<input file>', exiting."
     sudo pkg install -y ccache gmake perl5 python3 jq z3
   else
-    fatal "Unknown os: '$CI_OS_NAME'"
+    fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
   fi
   # Common installs
-  install-vcddiff
+  install-wavediff
   # Workaround -fsanitize=address crash
   sudo sysctl -w vm.mmap_rnd_bits=28
 else
   ##############################################################################
   # Unknown build stage
-  fatal "Unknown build stage: '$CI_BUILD_STAGE_NAME'"
+  fatal "Unknown CI_BUILD_STAGE_NAME: '$CI_BUILD_STAGE_NAME'"
 fi

ci/ci-pages-notify.bash

@@ -4,7 +4,7 @@
 # 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)
@@ -13,7 +13,7 @@ readonly REPO_URL=$(gh repo view --json url --jq .url)
 ARTIFACTS_ROOT=artifacts
 mkdir -p ${ARTIFACTS_ROOT}
 
-for RUN_ID in ${COVERAGE_PR_RUN_IDS//,/ }; do
+for RUN_ID in ${PR_RUN_IDS//,/ }; do
   echo "@@@ Processing run ${RUN_ID}"
 
   # Create workflow artifacts directory
@@ -21,7 +21,7 @@ for RUN_ID in ${COVERAGE_PR_RUN_IDS//,/ }; do
   mkdir -p ${ARTIFACTS_DIR}
 
   # Download artifact of this run, if exists
-  gh run download ${RUN_ID} --name coverage-pr-notification --dir ${ARTIFACTS_DIR} || true
+  gh run download ${RUN_ID} --name pr-notification --dir ${ARTIFACTS_DIR} || true
   ls -lsha ${ARTIFACTS_DIR}
 
   # Move on if no notification is required
@@ -35,7 +35,7 @@ for RUN_ID in ${COVERAGE_PR_RUN_IDS//,/ }; do
   gh pr comment $(cat ${ARTIFACTS_DIR}/pr-number.txt) --body-file ${ARTIFACTS_DIR}/body.txt
 
   # Get the artifact ID
-  ARTIFACT_ID=$(gh api "repos/{owner}/{repo}/actions/runs/${RUN_ID}/artifacts" --jq '.artifacts[] | select(.name == "coverage-pr-notification") | .id')
+  ARTIFACT_ID=$(gh api "repos/{owner}/{repo}/actions/runs/${RUN_ID}/artifacts" --jq '.artifacts[] | select(.name == "pr-notification") | .id')
 
   # Delete it, so we only notify once
   gh api --method DELETE "repos/{owner}/{repo}/actions/artifacts/${ARTIFACT_ID}"

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
@@ -42,7 +44,7 @@ compile_coverage_reports() {
   jq "." completedRuns.json
 
   # Create artifacts root directory
-  local ARTIFACTS_ROOT=artifacts
+  local ARTIFACTS_ROOT=artifacts-coverage
   mkdir -p ${ARTIFACTS_ROOT}
 
   # Create coverage reports root directory
@@ -53,9 +55,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"
@@ -72,13 +71,7 @@ compile_coverage_reports() {
       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}
@@ -148,7 +141,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 +149,136 @@ 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
+  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
+
+  # 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
+      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
+      [[ $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} || true
+      ls -lsha ${ARTIFACTS_DIR}
+
+      # Move on if no RTLMeter report is available
+      if [ ! -d ${ARTIFACTS_DIR}/report ]; then
+        echo "No RTLMeter report found"
+        continue
+      fi
+      echo "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,210 @@
+#!/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),
+        ("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),
+        ("NVDLA:*",                              28),
+        ("OpenPiton:1x1:*",                      5),
+        ("OpenPiton:2x2:*",                      6),
+        ("OpenPiton:4x4:*",                      8),
+        ("OpenTitan:*",                          10),
+        ("Servant:qerv:*",                       17),
+        ("Servant:serv:*",                       15),
+        ("VeeR-EH1:asic:*",                      6),
+        ("VeeR-EH1:default:*",                   8),
+        ("VeeR-EH1:hiperf:*",                    5),
+        ("VeeR-EH2:asic:*",                      9),
+        ("VeeR-EH2:default:*",                   8),
+        ("VeeR-EH2:hiperf:*",                    7),
+        ("VeeR-EL2:asic:*",                      4),
+        ("VeeR-EL2:default:*",                   5),
+        ("VeeR-EL2:hiperf:*",                    5),
+        ("Vortex:mini:*",                        3),
+        ("Vortex:sane:*",                        5),
+        ("XiangShan:default-chisel3:* !*:linux", 21),
+        ("XiangShan:default-chisel6:* !*:linux", 19),
+        ("XiangShan:mini-chisel3:* !*:linux",    8),
+        ("XiangShan:mini-chisel6:* !*:linux",    8),
+        ("XuanTie-C906:*",                       3),
+        ("XuanTie-C910:*",                       7),
+        ("XuanTie-E902:*",                       7),
+        ("XuanTie-E906:*",                       7),
+    ],
+    "gcc-hier": [
+        ("BlackParrot:1x1:*",    4),
+        ("BlackParrot:2x2:*",    16),
+        ("BlackParrot:4x4:*",    25),
+        ("NVDLA:*",              25),
+        ("OpenPiton:16x16:dhry", 16),
+        ("OpenPiton:1x1:*",      4),
+        ("OpenPiton:2x2:*",      4),
+        ("OpenPiton:4x4:*",      4),
+        ("OpenPiton:8x8:*",      6),
+        ("XuanTie-C910:*",       7),
+    ],
+}
+# fmt: on
+
+# Cases to run for PR jobs
+# fmt: off
+CASES_PR = {
+    "gcc": [
+        ("BlackParrot:1x1:*",                    5),
+        ("BlackParrot:4x4:*",                    25),
+        ("Caliptra:default:*",                   19),
+        ("NVDLA:*",                              29),
+        ("OpenPiton:1x1:*",                      4),
+        ("OpenPiton:4x4:*",                      10),
+        ("OpenTitan:*",                          16),
+        ("Servant:qerv:*",                       2),
+        ("Servant:serv:*",                       2),
+        ("VeeR-EH1:asic:*",                      4),
+        ("VeeR-EH1:default:*",                   6),
+        ("VeeR-EH1:hiperf:*",                    5),
+        ("VeeR-EH2:asic:*",                      13),
+        ("VeeR-EH2:default:*",                   6),
+        ("VeeR-EH2:hiperf:*",                    12),
+        ("VeeR-EL2:asic:*",                      4),
+        ("VeeR-EL2:default:*",                   4),
+        ("VeeR-EL2:hiperf:*",                    4),
+        ("Vortex:mini:*",                        3),
+        ("Vortex:sane:*",                        6),
+        ("XiangShan:default-chisel3:* !*:linux", 31),
+        ("XiangShan:default-chisel6:* !*:linux", 28),
+        ("XiangShan:mini-chisel3:* !*:linux",    13),
+        ("XiangShan:mini-chisel6:* !*:linux",    15),
+        ("XuanTie-C906:*",                       5),
+        ("XuanTie-C910:*",                       9),
+        ("XuanTie-E902:*",                       5),
+        ("XuanTie-E906:*",                       6),
+    ],
+    "clang": [
+        ("BlackParrot:1x1:*",                    5),
+        ("BlackParrot:4x4:*",                    12),
+        ("Caliptra:default:*",                   16),
+        ("NVDLA:*",                              28),
+        ("OpenPiton:1x1:*",                      5),
+        ("OpenPiton:4x4:*",                      8),
+        ("OpenTitan:*",                          10),
+        ("Servant:qerv:*",                       17),
+        ("Servant:serv:*",                       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,163 @@
+#!/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
+
+# Create notification comment content
+NOTIFICATION=$TMP_DIR/notification.txt
+cat > $NOTIFICATION <<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}](https://${PAGES_OWNER}.github.io/${PAGES_NAME}/rtlmeter-reports/${RUN_ID}/index.html)
+NOTIFICATION_TEMPLATE
+
+# 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

@@ -29,7 +29,7 @@ elif [ "$CI_OS_NAME" = "freebsd" ]; then
   export MAKE=gmake
   NPROC=$(sysctl -n hw.ncpu)
 else
-  fatal "Unknown os: '$CI_OS_NAME'"
+  fatal "Unknown CI_OS_NAME: '$CI_OS_NAME'"
 fi
 NPROC=$(expr $NPROC '+' 1)
 
@@ -192,7 +192,7 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
       "$MAKE" -C "$TEST_REGRESS" SCENARIOS="--vltmt" DRIVER_HASHSET=--hashset=9/10
       ;;
     *)
-      fatal "Unknown test: $TESTS"
+      fatal "Unknown TESTS: $TESTS"
       ;;
   esac
 
@@ -204,5 +204,5 @@ elif [ "$CI_BUILD_STAGE_NAME" = "test" ]; then
 else
   ##############################################################################
   # Unknown build stage
-  fatal "Unknown build stage: '$CI_BUILD_STAGE_NAME'"
+  fatal "Unknown CI_BUILD_STAGE_NAME: '$CI_BUILD_STAGE_NAME'"
 fi

ci/docker/buildenv/Dockerfile

@@ -37,7 +37,7 @@ RUN apt-get update \
                         libfl2 \
                         libfl-dev \
                         libclang-rt-18-dev \
-                        libgoogle-perftools-dev \
+                        libjemalloc-dev \
                         libsystemc \
                         libsystemc-dev \
                         numactl \
@@ -53,10 +53,14 @@ RUN apt-get update \
 
 WORKDIR /tmp
 
-RUN git clone https://github.com/veripool/vcddiff.git && \
-    make -C vcddiff && \
-    cp -p vcddiff/vcddiff /usr/local/bin/vcddiff && \
-    rm -rf vcddiff
+COPY wavetools.conf /tmp/wavetools.conf
+ARG WGET_EXTRA_ARGS=
+RUN . /tmp/wavetools.conf && \
+    wget -q ${WGET_EXTRA_ARGS} -O /tmp/wavetools.tar.gz \
+    "https://github.com/hudson-trading/wavetools/releases/download/${WAVETOOLS_VERSION}/wavetools-${WAVETOOLS_VERSION}-linux-x86_64.tar.gz" && \
+    tar -xzf /tmp/wavetools.tar.gz -C /tmp && \
+    cp -p /tmp/wavetools-${WAVETOOLS_VERSION}-linux-x86_64/wavediff /usr/local/bin/wavediff && \
+    rm -rf /tmp/wavetools.tar.gz /tmp/wavetools-* /tmp/wavetools.conf
 
 COPY build.sh /tmp/build.sh
 

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/buildenv/wavetools.conf

@@ -0,0 +1 @@
+WAVETOOLS_VERSION=v0.1.2

ci/docker/run/Dockerfile

@@ -22,7 +22,7 @@ RUN apt-get update \
                         help2man \
                         libfl2 \
                         libfl-dev \
-                        libgoogle-perftools-dev \
+                        libjemalloc-dev \
                         numactl \
                         perl \
                         perl-doc \

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.046 2026-02-28],
+AC_INIT([Verilator],[5.050 2026-07-01],
         [https://verilator.org],
         [verilator],[https://verilator.org])
 
@@ -64,8 +64,8 @@ AC_ARG_ENABLE([dev-asan],
               [AS_HELP_STRING([--enable-dev-asan],
                               [Enable compiling Verilator with ASAN
                                AddressSanitizer for memory error detection.
-                               This disables tcmalloc.  Does not affect
-                               Verilated models using ASAN.])],
+                               This disables tcmalloc and jemalloc.  Does not
+                               affect Verilated models using ASAN.])],
               [case "${enableval}" in
                 yes) CFG_WITH_DEV_ASAN=yes ;;
                 no)  CFG_WITH_DEV_ASAN=no ;;
@@ -93,6 +93,27 @@ else
   AC_MSG_RESULT($CFG_WITH_TCMALLOC)
 fi
 
+# Flag to enable linking Verilator with jemalloc if available
+AC_MSG_CHECKING(whether to use jemalloc)
+AC_ARG_ENABLE([jemalloc],
+              [AS_HELP_STRING([--enable-jemalloc],
+                              [Use libjemalloc for faster dynamic memory
+                               management in Verilator binary. Preferred over
+                               tcmalloc when both are available
+                               @<:@default=check@:>@])],
+              [case "${enableval}" in
+                yes) CFG_WITH_JEMALLOC=yes ;;
+                no)  CFG_WITH_JEMALLOC=no ;;
+                *)   AC_MSG_ERROR([bad value '${enableval}' for --enable-jemalloc]) ;;
+               esac],
+              [CFG_WITH_JEMALLOC=check;])
+if test "$CFG_WITH_DEV_ASAN" = "yes"; then
+  CFG_WITH_JEMALLOC=no
+  AC_MSG_RESULT("disabled by --enable-dev-asan")
+else
+  AC_MSG_RESULT($CFG_WITH_JEMALLOC)
+fi
+
 # Flag to enable code coverage build with gcov
 AC_MSG_CHECKING(whether to build for gcov code coverage collection)
 AC_ARG_ENABLE([dev-gcov],
@@ -400,6 +421,15 @@ 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
   _MY_CXX_CHECK_OPT(CXX,--coverage)
@@ -473,6 +503,7 @@ fi
 AC_SUBST(HAVE_DEV_ASAN)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Qunused-arguments)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-shadow)
+_MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-unnecessary-virtual-specifier)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Wno-unused-parameter)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-Xclang -fno-pch-timestamp)
 _MY_CXX_CHECK_OPT(CFG_CXXFLAGS_SRC,-faligned-new)
@@ -532,6 +563,7 @@ m4_foreach([cflag],[
         [-Wno-tautological-bitwise-compare],
         [-Wno-tautological-compare],
         [-Wno-uninitialized],
+        [-Wno-unnecessary-virtual-specifier],
         [-Wno-unused-but-set-parameter],
         [-Wno-unused-but-set-variable],
         [-Wno-unused-parameter],
@@ -557,6 +589,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)
@@ -566,9 +626,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"
-else
-  LTCMALLOC=-ltcmalloc_minimal
 fi
 AC_SUBST(CFG_LDFLAGS_SRC)
 AC_SUBST(CFG_LDFLAGS_VERILATED)
@@ -584,23 +641,56 @@ _MY_LDLIBS_CHECK_OPT(CFG_LIBS, -latomic)
 _MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lbcrypt)
 _MY_LDLIBS_CHECK_OPT(CFG_LIBS, -lpsapi)
 
-# Check if tcmalloc is available based on --enable-tcmalloc
-_MY_LDLIBS_CHECK_IFELSE(
-  $LTCMALLOC,
-  [if test "$CFG_WITH_TCMALLOC" != "no"; then
-    CFG_LIBS="$LTCMALLOC $CFG_LIBS";
-    # If using tcmalloc, add some extra options to make the compiler not assume
-    # it is using 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)
+# 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
+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])
+  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)
+
+# Test for tcmalloc
+CFG_HAVE_TCMALLOC=no
+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,10 +1,15 @@
 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.
 
 404allen404
 Adam Bagley
+Adam Kostrzewski
 Adrian Sampson
 Adrien Le Masle
 أحمد المحمودي (Ahmed El-Mahmoudy)
@@ -21,6 +26,7 @@ Andrei Kostovski
 Andrew Miloradovsky
 Andrew Nolte
 Andrew Voznytsa
+anonkey
 Anthony Donlon
 Anthony Moore
 Arkadiusz Kozdra
@@ -29,6 +35,7 @@ Artur Bieniek
 AUDIY
 Aylon Chaim Porat
 Bartłomiej Chmiel
+Benjamin Collier
 Brian Li
 Cameron Kirk
 Cameron Waite
@@ -41,6 +48,7 @@ Chuxuan Wang
 Chykon
 Congcong Cai
 Conor McCullough
+Cookie
 Dan Ruelas-Petrisko
 Daniel Bates
 Danny Oler
@@ -58,8 +66,10 @@ Drew Ranck
 Drew Taussig
 Driss Hafdi
 Edgar E. Iglesias
+Eric Mejdrich
 Eric Müller
 Eric Rippey
+Eunseo Song
 Ethan Sifferman
 Eyck Jentzsch
 Fabian Keßler-Schulz
@@ -86,6 +96,7 @@ Gökçe Aydos
 Han Qi
 Harald Heckmann
 Hennadii Chernyshchyk
+hjsanjana
 Howard Su
 Huang Rui
 Huanghuang Zhou
@@ -98,7 +109,9 @@ Iru Cai
 Ivan Vnučec
 Iztok Jeras
 Jake Merdich
+Jakub Michalski
 Jakub Wasilewski
+jalcim
 James Bailey
 James Hanlon
 James Hutchinson
@@ -133,6 +146,8 @@ Jose Loyola
 Josep Sans
 Joseph Nwabueze
 Josh Redford
+Joshua Leahy
+Julian Carrier
 Julian Daube
 Julie Schwartz
 Julien Margetts
@@ -145,6 +160,7 @@ Kefa Chen
 Keith Colbert
 Kevin Kiningham
 Kevin Nygaard
+Kornel Uriasz
 Kritik Bhimani
 Krzysztof Bieganski
 Krzysztof Boronski
@@ -155,14 +171,18 @@ Krzysztof Sychla
 Kuba Ober
 Lan Zongwei
 Larry Doolittle
+Laurent CHARRIER
 Leela Pakanati
 Liam Braun
 Luca Colagrande
+Lucas Amaral
 Ludwig Rogiers
 Lukasz Dalek
+M2kar
 Maarten De Braekeleer
 Maciej Sobkowski
 Marcel Chang
+Marco Bartoli
 Marco Widmer
 Mariusz Glebocki
 Markus Krause
@@ -174,11 +194,14 @@ Mateusz Gancarz
 Matt Stroud
 Matthew Ballance
 Max Wipfli
+Maxim Fonarev
 Michael Bedford Taylor
 Michael Bikovitsky
 Michael Killough
+Michael Rogenmoser
 Michal Czyz
 Michaël Lefebvre
+Miguel Perez Andrade
 Mike Popoloski
 Miodrag Milanović
 Mladen Slijepcevic
@@ -191,6 +214,8 @@ Nathan Graybeal
 Nathan Kohagen
 Nathan Myers
 Nick Brereton
+Nikolai Kumar
+Nikolay Puzanov
 Nolan Poe
 Oleh Maksymenko
 Patrick Stewart
@@ -198,6 +223,7 @@ Paul Bowen-Huggett
 Paul Swirhun
 Paul Wright
 Pawel Jewstafjew
+Pawel Klopotek
 Pawel Kojma
 Pawel Sagan
 Pengcheng Xu
@@ -214,6 +240,7 @@ Piotr Binkowski
 Qingyao Sun
 Quentin Corradi
 Rafal Kapuscik
+Rahul Behl
 Rasfunk
 Raynard Qiao
 Ricardo Barbedo
@@ -222,35 +249,45 @@ Risto Pejašinović
 Robert Balas
 Robin Heinemann
 Rodrigo Batista de Moraes
+Rowan Goemans
 Rupert Swarbrick
 Ryan Ziegler
 Ryszard Rozak
+Saksham Gupta
 Samuel Riedel
 Sean Cross
 Sebastien Van Cauwenberghe
+Secturion
+Sergey Chusov
 Sergey Fedorov
 Sergi Granell
 Seth Pellegrino
+Shogo Yamazaki
 Shou-Li Hsu
 Srinivasan Venkataramanan
 Stefan Wallentowitz
 Stephen Henry
 Steven Hugg
+Stuart Morris
 Szymon Gizler
 Sören Tempel
 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
 Toru Niina
+Tracy Narine
 Trung Nguyen
 Tudor Timi
 Tymoteusz Blazejczyk
@@ -267,6 +304,7 @@ Vito Gamberini
 Wei-Lun Chiu
 William D. Jones
 Wilson Snyder
+Wolfgang Mayerwieser
 Xi Zhang
 Yan Xu
 Yangyu Chen
@@ -291,3 +329,9 @@ em2machine
 emmettifelts
 Àlex Torregrosa
 Ícaro Lima
+Yogish Sekhar
+24bit-xjkp
+Zubin Jain
+Muzaffer Kal
+Yilin Li
+Shashvat Prabhu

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_ASSIGNEQEXPR_faulty.rst

@@ -1,8 +1,11 @@
 .. comment: generated by t_lint_assigneqexpr_bad
 .. code-block:: sv
    :linenos:
+   :emphasize-lines: 3,5
 
-       output logic c_o,
-       output logic d_o
-   );
-     assign c_o = (a_i != 0) ? 1 : 0;
+     assign d_o =  // Note = not == below
+         (
+         e_o = 1  // <--- Warning: ASSIGNEQEXPR
+         ) ? 1 : (
+         e_o = 0  // <--- Warning: ASSIGNEQEXPR
+         ) ? b_i : 0;

docs/gen/ex_DIDNOTCONVERGE_msg.rst

@@ -2,4 +2,4 @@
 .. code-block::
 
    -V{t#,#}         'stl' region trigger index 0 is active: @([hybrid] a)
-   %Error-DIDNOTCONVERGE: t/t_lint_didnotconverge_bad.v:7: Settle region did not converge after '--converge-limit' of 100 tries
+   %Error-DIDNOTCONVERGE: t/t_lint_didnotconverge_bad.v:7: 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 100 tries
+   %Error-DIDNOTCONVERGE: t/t_lint_didnotconverge_bad.v:7: 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_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_PINMISSING_faulty.rst

@@ -4,8 +4,8 @@
    :emphasize-lines: 2
 
    module t;
-      sub sub();  // <--- Warning
-   endmodule
-   module sub
-     (output port);
+     sub sub ();  // <--- Warning
    endmodule
+   module sub (
+       output port
+   );

docs/gen/ex_PINMISSING_msg.rst

@@ -1,4 +1,4 @@
 .. comment: generated by t_lint_pinmissing_bad
 .. code-block::
 
-   %Warning-PINMISSING: example.v:1:8 Instance has missing pin: 'port'
+   %Warning-PINMISSING: example.v:1:7 Instance has missing pin: 'port'

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/conf.py

@@ -44,7 +44,7 @@ def setup(app):
 # -- Project information
 
 project = 'Verilator'
-copyright = '2024 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
+copyright = '2026 by Wilson Snyder, under LGPL-3.0 or Artistic-2.0'
 author = 'Wilson Snyder'
 
 # The master toctree document.

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,13 +29,13 @@ The generated model class file manages all internal state required by the
 model, and exposes the following interface that allows interaction with the
 model:
 
-* Top level IO ports are exposed as references to the appropriate internal
+- Top level IO ports are exposed as references to the appropriate internal
   equivalents.
 
-* Public top level module instances are exposed as pointers to allow access
+- Public top level module instances are exposed as pointers to allow access
   to ``/* verilator public */`` items.
 
-* The root of the design hierarchy (as in SystemVerilog ``$root``) is
+- The root of the design hierarchy (as in SystemVerilog ``$root``) is
   exposed via the ``rootp`` member pointer to allow access to model
   internals, including ``/* verilator public_flat */`` items.
 
@@ -58,22 +59,22 @@ This means that user code that accesses internal signals in the model
 (likely including ``/* verilator public_flat */`` signals, as they are
 often inlined into the root scope) will need to be updated as follows:
 
-* No change required for accessing top level IO signals. These are directly
+- No change required for accessing top level IO signals. These are directly
   accessible in the model class via references.
 
-* No change required for accessing ``/* verilator public */`` items. These
+- No change required for accessing ``/* verilator public */`` items. These
   are directly accessible via sub-module pointers in the model class.
 
-* Accessing any other internal members, including
-  ``/* verilator public_flat */`` items requires the following changes:
+- Accessing any other internal members, including ``/* verilator
+  public_flat */`` items requires the following changes:
 
-  * Additionally include :file:`{prefix}___024root.h`. This header defines
+  - Additionally include :file:`{prefix}___024root.h`. This header defines
     type of the ``rootp`` pointer within the model class. Note the
     ``__024`` substring is the Verilator escape sequence for the ``$``
     character, i.e.: ``rootp`` points to the Verilated SystemVerilog
     ``$root`` scope.
 
-  * Replace ``modelp->internal->member`` references with
+  - Replace ``modelp->internal->member`` references with
     ``modelp->rootp->internal->member`` references, which contain one
     additional indirection via the ``rootp`` pointer.
 
@@ -178,13 +179,13 @@ DPI Example
 In the SYSTEMC example above, if you wanted to import C++ functions into
 Verilog, put in our.v:
 
-.. code-block::
+.. code-block:: sv
 
    import "DPI-C" function int add (input int a, input int b);
 
    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:
@@ -212,7 +213,7 @@ function name for the import, but note it must be escaped.
 
 .. code-block:: sv
 
-   export "DPI-C" function integer \$myRand;
+   import "DPI-C" function integer \$myRand;
 
    initial $display("myRand=%d", $myRand());
 
@@ -502,9 +503,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
@@ -7,10 +8,10 @@ Copyright
 
 The latest version of Verilator is available from https://verilator.org.
 
-Copyright 2003-2026 by Wilson Snyder. Verilator is free software; you
-can redistribute it and/or modify the Verilator internals under the terms
-of either the GNU Lesser General Public License Version 3 or the Perl
-Artistic License Version 2.0.
+Copyright 2003-2026 by Wilson Snyder. Verilator is free software; you can
+redistribute it and/or modify the Verilator internals under the terms of
+either the GNU Lesser General Public License Version 3 or the Perl Artistic
+License Version 2.0.
 
 All Verilog and C++/SystemC code quoted within this documentation file is
 released as Creative Commons Public Domain (CC0). Many example files and

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
 ============
@@ -16,3 +17,16 @@ C++14 compiler support
    (Although this date has expired, this change is currently on hold until
    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
+   no sooner than January 2027.

docs/guide/environment.rst

@@ -1,7 +1,8 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+..
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
-.. _Environment:
+.. _environment:
 
 Environment
 ===========
@@ -89,7 +90,8 @@ associated programs.
 .. option:: VERILATOR_GDB
 
    If set, the command to run when using the :vlopt:`--gdb` option, such as
-   "ddd". If not specified, it will use "gdb".
+   "ddd". If not specified, it will use "gdb" if available, otherwise
+   "lldb" if available.
 
 .. option:: VERILATOR_NUMA_STRATEGY
 

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:
 
@@ -48,6 +49,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
@@ -113,8 +119,17 @@ Options:
 .. 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>
+
+   If specified, when the randomization solver is used, open the given
+   filename for writing, and log all random solver commands and responses
+   to it.
 
 .. option:: +verilator+V
 
@@ -124,6 +139,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,15 @@ 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>
+
+   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
@@ -262,15 +272,27 @@ Summary:
    limitation that allow only one precompiled header per compilation.
    Use this instead of ::vlopt:`-CFLAGS` with `-include <header-path>`.
 
+.. option:: --constraint-array-limit <size>
+
+   Specifies the maximum array size for which array reduction methods
+   (sum, product, and, or, xor) in constraint expressions will be
+   expanded. Arrays larger than this limit will have their reduction
+   constraints ignored with a `CONSTRAINTIGN` warning. This prevents
+   excessive code generation for very large arrays.
+
+   Defaults to 64. Setting to 0 disables all array reduction constraint
+   expansion.
+
 .. option:: --converge-limit <loops>
 
    Rarely needed. Specifies the maximum number of runtime iterations before
-   creating a model failed to converge error. Defaults to 100.
+   creating a model failed to converge error. Defaults to 10000.
 
 .. option:: --coverage
 
    Enables all forms of coverage, an alias for :vlopt:`--coverage-line`
-   :vlopt:`--coverage-toggle` :vlopt:`--coverage-expr` :vlopt:`--coverage-user`.
+   :vlopt:`--coverage-toggle` :vlopt:`--coverage-expr` :vlopt:`--coverage-fsm`
+   :vlopt:`--coverage-user`.
 
 .. option:: --coverage-expr
 
@@ -282,6 +304,10 @@ Summary:
    covered for a given expression. Defaults to 32. Increasing may slow
    coverage simulations and make analyzing the results unwieldy.
 
+.. option:: --coverage-fsm
+
+   Enables native FSM state and arc coverage. See :ref:`FSM Coverage`.
+
 .. option:: --coverage-line
 
    Enables basic block line coverage analysis. See :ref:`Line Coverage`.
@@ -292,6 +318,20 @@ Summary:
    toggle coverage. Defaults to 256, as covering large vectors may greatly
    slow coverage simulations.
 
+.. option:: --coverage-per-instance
+
+   For Verilator-inserted coverage, preserve generated coverage counters and
+   ``.dat`` records per hierarchy instance. This option must be specified when
+   Verilating the model, together with one or more coverage instrumentation
+   options, for example :vlopt:`--coverage`, :vlopt:`--coverage-line`,
+   :vlopt:`--coverage-toggle`, :vlopt:`--coverage-expr`,
+   :vlopt:`--coverage-fsm`, or :vlopt:`--coverage-user`. It may increase
+   generated model size, counter memory, coverage write time, and ``.dat`` file
+   size.
+
+   This does not affect SystemVerilog ``cover``, which uses the IEEE-specified
+   coverage option ``per_instance``.
+
 .. option:: --coverage-toggle
 
    Enables adding signal toggle coverage. See :ref:`Toggle Coverage`.
@@ -304,8 +344,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>
 
@@ -451,6 +491,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
@@ -467,6 +511,10 @@ Summary:
    Rarely needed. Enable dumping DfgGraph .dot debug files with dumping
    level 3.
 
+.. option:: --dump-dfg-patterns
+
+   Rarely needed. Enable dumping DfgGraph pattern statistics.
+
 .. option:: --dump-graph
 
    Rarely needed. Enable dumping V3Graph .dot debug files with dumping
@@ -614,8 +662,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
@@ -638,9 +706,12 @@ Summary:
 
 .. option:: -fno-dfg
 
-   Rarely needed. Disable all use of the DFG-based combinational logic
-   optimizer. Alias for :vlopt:`-fno-dfg-pre-inline`,
-   :vlopt:`-fno-dfg-post-inline` and :vlopt:`-fno-dfg-scoped`.
+   Rarely needed. Disable the DFG-based combinational logic optimizer.
+
+   In versions before 5.048:
+
+   Alias for :vlopt:`-fno-dfg-pre-inline`, :vlopt:`-fno-dfg-post-inline` and
+   :vlopt:`-fno-dfg-scoped`.
 
 .. option:: -fno-dfg-break-cycles
 
@@ -656,11 +727,15 @@ Summary:
 
 .. option:: -fno-dfg-post-inline
 
-   Rarely needed. Do not apply the DFG optimizer after inlining.
+   Deprecated and has no effect (ignored).
+
+   In versions before 5.048: Do not apply the DFG optimizer after inlining.
 
 .. option:: -fno-dfg-pre-inline
 
-   Rarely needed. Do not apply the DFG optimizer before inlining.
+   Deprecated and has no effect (ignored).
+
+   In versions before 5.048: Do not apply the DFG optimizer before inlining.
 
 .. option:: -fno-dfg-push-down-sels
 
@@ -668,7 +743,10 @@ Summary:
 
 .. option:: -fno-dfg-scoped
 
-   Rarely needed. Do not apply the DFG optimizer across module scopes.
+   Deprecated; use :vlopt:`-fno-dfg` instead.
+
+   In versions before 5.048: Do not apply the DFG optimizer across module
+   scopes.
 
 .. option:: -fno-expand
 
@@ -684,16 +762,47 @@ 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
+
 .. option:: -fno-localize
 
 .. option:: -fno-merge-cond
@@ -726,11 +835,27 @@ 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
    optimization to avoid excessive memory usage.
 
+.. option:: --func-recursion-depth <value>
+
+   Specifies the maximum depth of recursive constant function evaluation.
+   When a recursive function exceeds this depth during constant folding,
+   Verilator gives up and treats the expression as non-constant.
+
+   Defaults to 1000.
+
 .. option:: -future0 <option>
 
    Rarely needed. Suppress an unknown Verilator option for an option that
@@ -873,27 +998,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>
 
@@ -1661,6 +1780,8 @@ Summary:
 
 .. option:: --structs-packed
 
+   Deprecated; discontinue use of this option.
+
    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
@@ -1792,7 +1913,7 @@ Summary:
 .. option:: --trace-fst
 
    Enable FST waveform tracing in the model. This overrides
-   :vlopt:`--trace`. See also :vlopt:`--trace-threads` option.
+   :vlopt:`--trace`.
 
 .. option:: --trace-max-array <depth>
 
@@ -1826,6 +1947,10 @@ Summary:
 
 .. option:: --trace-threads <threads>
 
+   Deprecated and has no effect.
+
+   In versions before 5.048:
+
    Enable waveform tracing using separate threads. This is typically faster
    in simulation runtime but uses more total compute. This option only
    applies to :vlopt:`--trace-fst`. FST tracing can utilize at most

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 ...
@@ -129,13 +134,31 @@ verilator_coverage Arguments
 .. option:: --filter-type <regex>
 
    Skips records of coverage types that matches with <regex>
-   Possible values are `toggle`, `line`, `branch`, `expr`, `user` and
-   a wildcard with `\*` or `?`. The default value is `\*`.
+   Possible values are `toggle`, `line`, `branch`, `expr`, `covergroup`,
+   `user`, `fsm_state`, `fsm_arc` and a wildcard with `\*` or `?`. The
+   default value is `\*`.
+
+   The `covergroup` type represents SystemVerilog functional coverage
+   including covergroups, coverpoints, bins, and cross coverage as defined
+   in IEEE 1800-2023 Section 19.
 
 .. option:: --help
 
    Displays a help summary, the program version, and exits.
 
+.. option:: --include-reset-arcs
+
+   Includes FSM reset arcs in the printed summaries and annotated output.
+   By default, reset arcs are tracked but summarized separately from the
+   non-reset FSM arcs.
+
+.. option:: --levels <depth>
+
+   With :option:`--report hierarchy`, limits displayed hierarchy depth.
+   Deeper descendants still roll-up into the visible parent totals. A depth
+   of 0 shows the top-level hierarchy roll-up. If negative or omitted, all
+   depths are shown.
+
 .. option:: --rank
 
    Prints an experimental report listing the relative importance of each
@@ -148,6 +171,18 @@ verilator_coverage Arguments
    contribute to overall coverage if all tests are run in the order of
    highest to the lowest rank.
 
+.. option:: --report <kind>[,<kind>...]
+
+   Generates a human-consumable report. Supported report kinds are
+   ``summary``, ``hier``, and ``hierarchy``. Multiple report kinds may be
+   comma-separated, for example ``summary,hier``. With no explicit
+   :option:`--report`, the legacy flat summary is printed. ``summary`` is
+   equivalent to the flat type summary. ``hier`` and ``hierarchy`` build a
+   deterministic hierarchy roll-up from ``hier`` fields. Collapsed wildcard
+   hierarchy can be reported, but it is not precise per-instance coverage.
+   If no hierarchy fields are present, a warning is printed and the flat
+   summary is shown instead.
+
 .. option:: --unlink
 
    With :option:`--write`, unlink all input files after the output has been

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
@@ -341,6 +342,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,16 +17,16 @@ Linux).
 Quick Install
 =============
 
-1. Install Python for your platform from https://www.python.org/downloads/.
-2. Install CMake for your platform from https://cmake.org/download/ or
+#. Install Python for your platform from https://www.python.org/downloads/.
+#. Install CMake for your platform from https://cmake.org/download/ or
    build it from source.
-3. If the compiler of your choice is MSVC, then install
+#. If the compiler of your choice is MSVC, then install
    https://visualstudio.microsoft.com/downloads/. If the compiler of your
    choice is Clang, then install https://releases.llvm.org/download.html or
    build it from source.
-4. For flex and bison use https://github.com/lexxmark/winflexbison to build
+#. For flex and bison use https://github.com/lexxmark/winflexbison to build
    and install.
-5. For build on Windows using MSVC set environment variable WIN_FLEX_BISON
+#. For build on Windows using MSVC set environment variable WIN_FLEX_BISON
    to install directory. For build on Windows/Linux/OS-X using ninja set
    the environment variable FLEX_INCLUDE to the directory containing
    FlexLexer.h and ensure that flex/bison is available within the PATH.
@@ -40,7 +41,8 @@ To build using MSVC:
 .. code-block:: bash
 
    cd verilator  # directory containing source files of verilator
-   mkdir build
+   mkdir -p build
+   cd build
    cmake .. -DCMAKE_BUILD_TYPE=Release --install-prefix $PWD/../install
    cmake --build . --config Release
    cmake --install . --prefix $PWD/../install
@@ -50,7 +52,8 @@ To build using ninja:
 .. code-block:: bash
 
    cd verilator
-   mkdir build
+   mkdir -p build
+   cd build
    cmake -G Ninja .. -DCMAKE_BUILD_TYPE=Release --install-prefix $PWD/../install -DCMAKE_MAKE_PROGRAM=<path to ninja binary> -DBISON_EXECUTABLE=<path to bison> -DFLEX_EXECUTABLE=<path to flex>
    <path to ninja binary> #execute ninja
    cmake --install . --prefix $PWD/../install
@@ -71,7 +74,7 @@ Example
 
    cd verilator/examples
    cd cmake_hello_c
-   mkdir build
+   mkdir -p build
    cd build
    cmake ..  # cmake -G Ninja ..
    cmake --build . --config Release # ninja

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:
 
@@ -61,10 +62,10 @@ In brief, to install from git:
 
    # Prerequisites:
    #sudo apt-get install git help2man perl python3 make autoconf g++ flex bison ccache
-   #sudo apt-get install libgoogle-perftools-dev numactl perl-doc
+   #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:
 
@@ -144,7 +145,7 @@ installed for good performance:
 
    sudo apt-get install ccache  # If present at build, needed for run
    sudo apt-get install mold  # If present at build, needed for run
-   sudo apt-get install libgoogle-perftools-dev numactl
+   sudo apt-get install libjemalloc-dev numactl
 
 To build Verilator you will need to install these packages; these do not
 need to be present to run Verilator:
@@ -170,6 +171,9 @@ once, after ``configure``:
 
 .. code-block:: bash
 
+   # Install dependencies
+   sudo apt install python3-pip
+
    # Create Python virutal environment in .venv:
    make venv
 
@@ -381,12 +385,10 @@ the files:
 
    make install
 
-
 .. Docker Build Environment
 
 .. include:: ../../ci/docker/buildenv/README.rst
 
-
 .. Docker Run Environment
 
 .. include:: ../../ci/docker/run/README.rst

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:
 
@@ -184,7 +185,9 @@ Verilator supports adding code to the Verilated model to support
 SystemVerilog code coverage. With :vlopt:`--coverage`, Verilator enables
 all forms of coverage:
 
-- :ref:`User Coverage`
+- :ref:`Property Coverage`
+- :ref:`Covergroup Coverage`
+- :ref:`FSM Coverage`
 - :ref:`Line Coverage`
 - :ref:`Toggle Coverage`
 
@@ -192,22 +195,124 @@ When a model with coverage is executed, it will create a coverage file for
 collection and later analysis, see :ref:`Coverage Collection`.
 
 
-.. _user coverage:
+.. _property coverage:
 
-Functional Coverage
--------------------
+Property Coverage
+-----------------
 
 With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
-translate functional coverage points the user has inserted manually in
-SystemVerilog code through into the Verilated model.
+translate property coverage points the user has inserted manually in
+SystemVerilog code into the Verilated model.
 
-For example, the following SystemVerilog statement will add a coverage
-point under the coverage name "DefaultClock":
+For simple coverage points, use the ``cover property`` construct:
 
 .. code-block:: sv
 
    DefaultClock: cover property (@(posedge clk) cyc==3);
 
+This adds a coverage point that tracks whether the condition has been
+observed.
+
+.. _covergroup coverage:
+
+Covergroup Coverage
+-------------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
+translate covergroup coverage points the user has inserted manually in
+SystemVerilog code into the Verilated model. Verilator supports coverpoints
+with value and transition bins, and cross points.
+
+
+.. _fsm coverage:
+
+FSM Coverage
+------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-fsm`, Verilator can
+instrument a conservative subset of FSMs and report both state coverage
+(`fsm_state`) and transition coverage (`fsm_arc`).
+
+This feature is currently experimental and might change in subsequent
+releases. In particular, the native FSM coverage extraction heuristics,
+:vlopt:`--coverage-fsm`, and the Verilator-specific FSM metacomments below
+should be treated as subject to change while the interface settles.
+
+FSM extraction is intentionally narrow. The current implementation targets
+clocked state machines that can be recovered directly from the RTL. It
+recognizes scalar enum, parameter, localparam, and selected literal state
+encodings in these common forms:
+
+- Single-process FSMs, whose state dispatch is written as ``case (state)``
+  or as a top-level ``if`` / ``else if`` chain comparing the same state
+  variable against known state values
+- Two-process and three-block FSMs, where a clocked state register is
+  paired with a combinational next-state block using the same supported
+  ``case`` or top-level ``if`` / ``else if`` dispatch forms
+
+Scalar state encodings may be wider than 32 bits. This allows sparse state
+encodings, such as high-Hamming-distance enum or localparam values, to be
+preserved in the detected FSM model. Verilator uses the declared enum item
+name, parameter name, or localparam name as the reported state label where
+possible.
+
+Simple input guards are supported when they appear inside a recognized
+state branch, or as a top-level conjunction containing exactly one state
+comparison, such as ``(state_q == IDLE) && ready``. Directly traceable
+pre-decoded state aliases, such as ``assign idle_state = (state_q ==
+IDLE)``, may also be used in these guarded predicates.
+
+Verilator does not claim broad support for arbitrary predicate
+decomposition, one-hot inference, helper-function next-state recovery,
+deeply nested control recovery, or cross-module state alias tracing.
+
+The following metacomments may be attached to the state variable to steer
+the extracted coverage model:
+
+- ``/*verilator fsm_state*/`` forces the variable to be treated as FSM
+  state.
+- ``/*verilator fsm_reset_arc*/`` marks reset transitions as user-visible
+  reset arcs instead of defaulting to a hidden reset-only summary.
+- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch arcs that
+  would otherwise be skipped by the conservative extractor.
+
+State registers may also be wrapped by a transparent instance, for example
+a project flop wrapper or primitive. Such wrappers must be described
+explicitly with a VLT command file action before Verilator will use their
+data, state, clock, or reset connections for FSM extraction:
+
+.. code-block:: sv
+
+   `verilator_config
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i"
+
+The same command may be placed in a separate ``.vlt`` file:
+
+.. code-block:: sv
+
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i"
+
+Optional reset metadata may also be supplied:
+
+.. code-block:: sv
+
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i" \
+      -reset "rst_ni" -reset_value "ResetValue"
+
+Reset arcs are emitted only when the configured reset port has an inferable
+edge in the wrapper and the configured reset value parameter is statically
+resolvable. If reset metadata is incomplete, Verilator warns and may still
+emit FSM state and transition coverage, but reset arcs are omitted.
+
+Reset transitions are included in the collected data either way. By
+default, :command:`verilator_coverage` summarizes reset-only arcs rather
+than printing them alongside non-reset arcs. Use
+:option:`verilator_coverage --include-reset-arcs` to include those arcs in
+the printed summary and annotated output.
+
+Annotated output produced by :command:`verilator_coverage --annotate` will
+label FSM points with `fsm_state` and `fsm_arc`, and synthetic fallback
+transitions with `SYNTHETIC DEFAULT ARC`.
 
 .. _line coverage:
 
@@ -328,11 +433,11 @@ coverage point insertions into the model and collect the coverage data.
 
 To get the coverage data from the model, write the coverage with either:
 
-1. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump
+#. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump
    coverage when the test completes to the filename specified with
    :vlopt:`+verilator+coverage+file+\<filename\>`.
 
-2. In the user wrapper code, typically at the end once a test passes, call
+#. In the user wrapper code, typically at the end once a test passes, call
    ``Verilated::threadContextp()->coveragep()->write`` with an argument of
    the filename for the coverage data file to write coverage data to
    (typically "logs/coverage.dat").
@@ -397,12 +502,12 @@ how execution time is distributed in a verilated model.
 
 With the :vlopt:`--prof-exec` option, Verilator will:
 
-* Add code to the Verilated model to record execution flow.
+- Add code to the Verilated model to record execution flow.
 
-* Add code to save profiling data in non-human-friendly form to the file
+- Add code to save profiling data in non-human-friendly form to the file
   specified with :vlopt:`+verilator+prof+exec+file+\<filename\>`.
 
-* In multithreaded models, add code to record each macro-task's start and
+- In multithreaded models, add code to record each macro-task's start and
   end time across several calls to eval. (What is a macro-task? See the
   Verilator internals document (:file:`docs/internals.rst` in the
   distribution.)
@@ -502,8 +607,8 @@ There are two forms of profile-guided optimizations. Unfortunately, for
 best results, they must each be performed from the highest level code to
 the lowest, which means performing them separately and in this order:
 
-* :ref:`Thread PGO`
-* :ref:`Compiler PGO`
+- :ref:`Thread PGO`
+- :ref:`Compiler PGO`
 
 Other forms of PGO may be supported in the future, such as clock and reset
 toggle rate PGO, branch prediction PGO, statement execution time PGO, or
@@ -569,7 +674,7 @@ multithreaded models.
 Please see the appropriate compiler documentation to use PGO with GCC or
 Clang. The process in GCC 10 was as follows:
 
-1. Compile the Verilated model with the compiler's "-fprofile-generate"
+#. Compile the Verilated model with the compiler's "-fprofile-generate"
    flag:
 
    .. code-block:: bash
@@ -580,10 +685,10 @@ Clang. The process in GCC 10 was as follows:
    Or, if calling make yourself, add -fprofile-generate appropriately to
    your Makefile.
 
-2. Run your simulation. This will create \*.gcda file(s) in the same
+#. Run your simulation. This will create \*.gcda file(s) in the same
    directory as the source files.
 
-3. Recompile the model with -fprofile-use. The compiler will read the
+#. Recompile the model with -fprofile-use. The compiler will read the
    \*.gcda file(s).
 
    For GCC:

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.
 
 
@@ -262,23 +263,6 @@ construction is parallelized using the same number of threads as specified
 with :vlopt:`--threads`, and is executed on the same thread pool as the
 model.
 
-The :vlopt:`--trace-threads` options can be used with :vlopt:`--trace-fst`
-to offload FST tracing using multiple threads. If :vlopt:`--trace-threads`
-is given without :vlopt:`--threads`, then :vlopt:`--trace-threads` will
-imply :vlopt:`--threads 1 <--threads>`, i.e., the support libraries will be
-thread safe.
-
-With :vlopt:`--trace-threads 0 <--trace-threads>`, trace dumps are produced
-on the main thread. This again gives the highest single-thread performance.
-
-With :vlopt:`--trace-threads {N} <--trace-threads>`, where N is at least 1,
-up to N additional threads will be created and managed by the trace files
-(e.g., VerilatedFstC), to offload construction of the trace dump. The main
-thread will be released to proceed with execution as soon as possible,
-though some main thread blocking is still necessary while capturing the
-trace. FST tracing can utilize up to 2 offload threads, so there is no use
-of setting :vlopt:`--trace-threads` higher than 2 at the moment.
-
 When running a multithreaded model, the default Linux task scheduler often
 works against the model by assuming short-lived threads and thus it often
 schedules threads using multiple hyperthreads within the same physical
@@ -286,15 +270,14 @@ core. If there is no affinity already set, on Linux only, Verilator
 attempts to set thread-to-processor affinity in a reasonable way.
 
 Some newer Linux kernels handle thread assignment well. If running
-Verilator on such a system, automatic thread affinity may not be
-beneficial and may even reduce performance. In this case, environment
-variable :vlopt:`VERILATOR_NUMA_STRATEGY` may be set to ``none`` to
-disable automatic thread affinity. For more information, refer to
+Verilator on such a system, automatic thread affinity may not be beneficial
+and may even reduce performance. In this case, environment variable
+:vlopt:`VERILATOR_NUMA_STRATEGY` may be set to ``none`` to disable
+automatic thread affinity. For more information, refer to
 :ref:`Environment`.
 
 For best performance, use the :command:`numactl` program to (when the
-threading count fits) select unique physical cores on the same socket. The
-same applies for :vlopt:`--trace-threads` as well.
+threading count fits) select unique physical cores on the same socket.
 
 As an example, if a model was Verilated with :vlopt:`--threads 4
 <--threads>`, we consult:
@@ -521,7 +504,10 @@ include directories and link to the SystemC libraries.
 
 .. describe:: TRACE_THREADS
 
-   Optional. Enable multithreaded FST trace; see :vlopt:`--trace-threads`.
+   Deprecated and has no effect.
+
+   In versions before 5.048: Optional. Enable multithreaded FST trace; see
+   :vlopt:`--trace-threads`.
 
 .. describe:: TRACE_VCD
 

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
@@ -306,7 +307,7 @@ List Of Warnings
         else
           array[address] <= data;
 
-   While this is supported in typical synthesizeable code (including the
+   While this is supported in typical synthesizable code (including the
    example above), some complicated cases are not supported. Namely:
 
    1. If the above loop is inside a suspendable process or fork statement.
@@ -382,6 +383,9 @@ List Of Warnings
    non-enumerated values (IEEE 1800-2023 12.5.3). Verilator checks that
    illegal values are not hit, unless :vlopt:`--no-assert-case` was used.
 
+   Unique0 case statements will never cause this warning. (Although unique0
+   should be avoided in synthesizable code as may result in latch behavior.)
+
    Ignoring this warning will only suppress the lint check; it will
    simulate correctly.
 
@@ -521,6 +525,48 @@ List Of Warnings
    Suppressing this error will suppress the error message check; it will
    simulate as if the ``const`` as not present.
 
+.. option:: CONTASSINIT
+
+   Error that a continuous assignment is setting a variable with an initial
+   value. Use either the initial value or the continuous assignment, but not
+   both.
+
+   For example:
+
+   .. code-block:: sv
+      :emphasize-lines: 2,4
+
+      module t;
+        logic b = 1'b0;
+        logic a;
+        assign b = a; //<--- Error
+      endmodule
+
+   Results in:
+
+   .. code-block::
+
+      %Error-CONTASSINIT: example.sv:4:10: Continuous assignment to variable with initial value: 'b'
+                                                  : ... note: In instance 't'
+                                                  : ... Location of variable initialization
+          2 |   logic b = 1'b0;
+            |         ^
+                            example.sv:4:10: ... Location of continuous assignment
+          4 |   assign b = a;
+            |          ^
+      %Error: Exiting due to 1 error(s)
+
+   The following is legal because the driven variable does not have a declaration
+   initializer:
+
+   .. code-block:: sv
+
+      module t;
+        logic b;
+        logic a = 1'b0;
+        assign b = a;
+      endmodule
+
 
 .. option:: CONTASSREG
 
@@ -837,6 +883,34 @@ List Of Warnings
    with a newline."
 
 
+.. option:: FINALDLY
+
+   Error issued when a non-blocking assignment `<=` is used in a
+   `final` block.
+
+   This error can be disabled. If disabled, the assignment will be
+   executed as a `=` blocking assignment.
+
+   Faulty example:
+
+   .. include:: ../../docs/gen/ex_FINALDLY_faulty.rst
+
+   Results in:
+
+   .. include:: ../../docs/gen/ex_FINALDLY_msg.rst
+
+.. option:: FSMMULTI
+
+   Warns that the same always block contains multiple enum-typed case
+   statements that look like FSM candidates for native FSM coverage when
+   :vlopt:`--coverage-fsm` or :vlopt:`--coverage` is enabled.
+
+   Verilator's FSM coverage instruments only the first such candidate in
+   source order. Split the FSMs into separate always blocks, or explicitly
+   annotate the intended state variables and restructure the RTL for full
+   coverage of such multiple state machines.
+
+
 .. option:: FUNCTIMECTL
 
    Error that a function contains a time-controlling statement or call of a
@@ -856,6 +930,11 @@ List Of Warnings
    pass.
 
 
+.. option:: FUTURE
+
+   Warns that a feature is under development and not yet supported.
+
+
 .. option:: GENCLK
 
    Historical, never issued since version 5.000.
@@ -939,6 +1018,13 @@ List Of Warnings
    port list, since these are references to interfaces/modports declared at a higher level and are
    already specialized. These types of accesses do not require waiving HIERPARAM.
 
+.. option:: IEEEMAYDEPRECATE
+
+   This feature is not yet deprecated, but may be in a future version of the IEEE standard.
+   This warning is to alert users that they may want to avoid using this feature, as it
+   may be removed in a future version of the IEEE standard, and thus may not be supported
+   in future versions of Verilator.
+
 .. option:: IFDEPTH
 
    Warns that if/if else statements have exceeded the depth specified with
@@ -1109,11 +1195,14 @@ List Of Warnings
 
 .. option:: INITIALDLY
 
-   .. TODO better example
+   Historical, never issued since version 5.050.
 
    Warns that the code has a delayed assignment inside of an ``initial`` or
    ``final`` block. If this message is suppressed, Verilator will convert
-   this to a non-delayed assignment. See also :option:`COMBDLY`.
+   this to a non-delayed assignment. With :vlopt:`--timing`, delayed
+   assignments in ``initial`` blocks that also contain a `#` delay
+   control, or `@` even control statement are scheduled as
+   non-blocking assignments. See also :option:`COMBDLY`.
 
    Ignoring this warning may make Verilator simulations differ from other
    simulators.
@@ -1342,9 +1431,11 @@ List Of Warnings
 
 .. option:: MULTIDRIVEN
 
-   Warns that the specified signal comes from multiple ``always``
-   blocks, each with different clocking. This warning does not look at
-   individual bits (see the example below).
+   Warns that the specified signal has multiple procedural drivers.
+
+   One case is when the signal comes from multiple ``always`` blocks,
+   each with different clocking. This warning does not look at individual
+   bits (see the example below).
 
    This is considered bad style, as the consumer of a given signal may be
    unaware of the inconsistent clocking, causing clock domain crossing
@@ -1358,8 +1449,28 @@ 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
+
+   Ignoring this warning may hide clock domain crossing, timing, or
+   portability bugs. It may also cause longer simulation runtimes due to
    reduced optimizations.
 
 
@@ -1487,6 +1598,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
@@ -1519,7 +1649,12 @@ List Of Warnings
    ANSI-style `#(...)` declarations. IEEE 1800-2023 6.20.1 requires this
    error, but some simulators accept this syntax.
 
-   Faulty example:
+   Also issued with ANSI format where a parameter without default is
+   present in the top-level module, and as such Verilator cannot know how
+   to process that module. For such cases suggest adding a default so the
+   module can lint cleanly.
+
+   Faulty non-ANSI example:
 
    .. include:: ../../docs/gen/ex_PARAMNODEFAULT_faulty.rst
 
@@ -1529,8 +1664,8 @@ List Of Warnings
 
    To fix the issue, move to an ANSI-style declaration.
 
-   Suppressing this error will only suppress the IEEE-required check; it
-   will simulate correctly.
+   For the non-ANSI case, suppressing this error will only suppress the
+   IEEE-required check; it will simulate correctly.
 
 
 .. option:: PINCONNECTEMPTY
@@ -1702,12 +1837,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.
 
@@ -1850,8 +1991,12 @@ List Of Warnings
 
       and #(1,2,3) AND (out, a, b);
 
-   Warns that rising, falling, and turn-off delays are currently unsupported.
-   The first (rising) delay is used for all cases.
+   Warns that the third (turn-off) delay is currently unsupported and is
+   ignored. Rising and falling delays are supported.
+
+   In versions before 5.048, warned that rising, falling, and turn-off
+   delays were unsupported. The first (rising) delay was used for all
+   cases.
 
 
 .. option:: SELRANGE
@@ -2238,11 +2383,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.
@@ -2592,11 +2732,11 @@ List Of Warnings
    Since version 5.046:
 
    Issued if neither :vlopt:`--sched-zero-delay`, nor
-   :vlopt:`--sched-zero-delay` is used on the command line, and the input does
-   not contain a compile time known ``#0`` delay, but does contain a
-   ``#(expressin)`` where the delay value cannot be determined at compile time.
-   Passing :vlopt:`--no-sched-zero-delay` can improve runtime performance if
-   variable delays are all known to be non-zero at runtime.
+   :vlopt:`--sched-zero-delay` is used on the command line, and the input
+   does not contain a compile time known ``#0`` delay, but does contain a
+   ``#(expression)`` where the delay value cannot be determined at compile
+   time. Passing :vlopt:`--no-sched-zero-delay` can improve runtime
+   performance if variable delays are all known to be non-zero at runtime.
 
    Also issued if :vlopt:`--no-sched-zero-delay` is used on the command line,
    but the input contains a compile time known ``#0`` delay. This is safe to

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``.
 
 
@@ -594,16 +594,15 @@ object.
 This class manages processes that await events (triggers). There is one
 such object per each trigger awaited by coroutines. Coroutines ``co_await``
 this object's ``trigger`` function. They are stored in three stages -
-`awaiting`, `fired` and `toResume`. First, they land in the `awaiting` stage, and
-cannot be resumed. The ``ready`` function moves all coroutines from the
-`awaiting` stage into the `fired` stage. The ``moveToResumeQueue`` function moves
-`fired` coroutines into `toResume`. Finally, function `resume` resumes
-all coroutines from the `toResume` stage.
+`awaiting`, `fired` and `toResume`. First, they land in the `awaiting`
+stage, and cannot be resumed. The ``ready`` function moves all coroutines
+from the `awaiting` stage into the `fired` stage. The ``moveToResumeQueue``
+function moves `fired` coroutines into `toResume`. Finally, function
+`resume` resumes all coroutines from the `toResume` stage.
 
-This split is done to avoid self-triggering, triggering coroutines
-multiple times and triggering coroutines in the same iteration
-they were suspended. See the `Scheduling with timing` section
-for details on how this is used.
+This split is done to avoid self-triggering, triggering coroutines multiple
+times and triggering coroutines in the same iteration they were suspended.
+See the `Scheduling with timing` section for details on how this is used.
 
 ``VlDynamicTriggerScheduler``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -667,23 +666,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.
 
@@ -721,35 +720,36 @@ in that process. When ordering code using ``V3Order``, these triggers are
 provided as external domains of these variables. This ensures that the
 necessary combinational logic is triggered after a coroutine resumption.
 
-Every call to a `VlTriggerScheduler`'s `trigger()` method is preempt by
-a call to a proper `__VbeforeTrig` function which evaluates all the necessary
-triggers so, the information about order of suspension/resumption is not lost.
-The triggers necessary to evaluate are ones dependent on the same events
-as the `trigger()` - e.g.: if `triggers()` awaits for event `a` or `b`, then
-every trigger that depends on any of those shall be evaluated. If they wouldn't
-be evaluated and next coroutine after resumption would fire the event `a` then
-it is impossible to get to know whether await or fire on event `a` was called
-first - which is necessary to know.
+Every call to a `VlTriggerScheduler`'s `trigger()` method is preempt by a
+call to a proper `__VbeforeTrig` function which evaluates all the necessary
+triggers so, the information about order of suspension/resumption is not
+lost. The triggers necessary to evaluate are ones dependent on the same
+events as the `trigger()` - e.g.: if `triggers()` awaits for event `a` or
+`b`, then every trigger that depends on any of those shall be evaluated. If
+they wouldn't be evaluated and next coroutine after resumption would fire
+the event `a` then it is impossible to get to know whether await or fire on
+event `a` was called first - which is necessary to know.
 
 There are two functions for managing timing logic called by ``_eval()``:
 
-* ``_timing_ready()``, which commits all coroutines whose triggers were
-  not set in the current iteration,
-* ``_timing_resume()``, which calls `resume()` on all trigger and delay
+- ``_timing_ready()``, which commits all coroutines whose triggers were not
+  set in the current iteration,
+- ``_timing_resume()``, which calls `resume()` on all trigger and delay
   schedulers whose triggers were set in the current iteration.
 
 Thanks to this separation a coroutine:
-* awaiting a trigger cannot be suspended and resumed in the same iteration
+
+- awaiting a trigger cannot be suspended and resumed in the same iteration
   (``test_regress/t/t_timing_eval_act.v``) - which is necessary to make
-  Verilator more predictable; this is the reason for introduction of 3rd stage
-  in `VlTriggerScheduler` and thanks to this it is guaranteed that downstream
-  logic will be evaluated before resumption (assuming that the coroutine wasn't
-  already triggered in previous iteration);
-* cannot be resumed before it is suspended -
+  Verilator more predictable; this is the reason for introduction of 3rd
+  stage in `VlTriggerScheduler` and thanks to this it is guaranteed that
+  downstream logic will be evaluated before resumption (assuming that the
+  coroutine wasn't already triggered in previous iteration);
+- cannot be resumed before it is suspended -
   ``test_regress/t/t_event_control_double_excessive.v``;
-* firing cannot cannot be lost
-  (``test_regress/t/t_event_control_double_lost.v``) - which is possible when
-  triggers are not evaluated right before awaiting.
+- firing cannot cannot be lost
+  (``test_regress/t/t_event_control_double_lost.v``) - which is possible
+  when triggers are not evaluated right before awaiting.
 
 All coroutines are committed and resumed in the 'act' eval loop. With
 timing features enabled, the ``_eval()`` function takes this form:
@@ -937,13 +937,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.
@@ -1298,15 +1300,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 +1395,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 +1405,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 +1436,7 @@ There are three ways data is passed between visitor functions.
    so it's ok to call fairly often. For example, it's commonly called on
    every module.
 
-3. Parameters can be passed between the visitors in close to the "normal"
+#. Parameters can be passed between the visitors in close to the "normal"
    function caller to callee way. This is the second ``vup`` parameter of
    type ``AstNUser`` that is ignored on most of the visitor functions.
    V3Width does this, but it proved messier than the above and is
@@ -1568,8 +1570,8 @@ For all tests to pass, you must install the following packages:
 
 - SystemC to compile the SystemC outputs, see https://systemc.org
 
-- vcddiff to find differences in VCD outputs. See the readme at
-  https://github.com/veripool/vcddiff
+- wavediff to find differences in waveform outputs. See the readme at
+  https://github.com/hudson-trading/wavetools
 
 - Cmake for build paths that use it.
 
@@ -1701,7 +1703,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 +1752,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
 -------
 
@@ -1843,33 +1870,25 @@ algorithmic stage. An example:
 The following summarizes the above example dump, with more detail on each
 field in the section below.
 
-+---------------+--------------------------------------------------------+
-| ``1:2:``      | The hierarchy of the ``VAR`` is the ``op2p``           |
-|               | pointer under the ``MODULE``, which in turn is the     |
-|               | ``op1p`` pointer under the ``NETLIST``.                |
-+---------------+--------------------------------------------------------+
-| ``VAR``       | The AstNodeType (e.g. ``AstVar``).                     |
-+---------------+--------------------------------------------------------+
-| ``0x91a780``  | Address of this node.                                  |
-+---------------+--------------------------------------------------------+
-| ``<e74>``     | The 74th edit to the netlist was the last              |
-|               | modification to this node.                             |
-+---------------+--------------------------------------------------------+
-| ``{a22ah}``   | This node is related to the source filename            |
-|               | "a", where "a" is the first file read, "z" the 26th,   |
-|               | and "aa" the 27th. Then line 22 in that file, then     |
-|               | column 8 (aa=0, az=25, ba=26, ...).                    |
-+---------------+--------------------------------------------------------+
-| ``@dt=0x...`` | The address of the data type this node references.     |
-+---------------+--------------------------------------------------------+
-| ``w32``       | The data-type width() is 32 bits.                      |
-+---------------+--------------------------------------------------------+
-| ``out_wide``  | The name() of the node, in this case, the name of the  |
-|               | variable.                                              |
-+---------------+--------------------------------------------------------+
-| ``[O]``       | Flags which vary with the type of node, in this        |
-|               | case of a VAR, it means the variable is an output.     |
-+---------------+--------------------------------------------------------+
+============= =============================================================
+``1:2:``      The hierarchy of the ``VAR`` is the ``op2p`` pointer under
+              the ``MODULE``, which in turn is the ``op1p`` pointer under
+              the ``NETLIST``.
+``VAR``       The AstNodeType (e.g. ``AstVar``).
+``0x91a780``  Address of this node.
+``<e74>``     The 74th edit to the netlist was the last modification to
+              this node.
+``{a22ah}``   This node is related to the source filename "a", where "a" is
+              the first file read, "z" the 26th, and "aa" the 27th. Then
+              line 22 in that file, then column 8 (aa=0, az=25, ba=26,
+              ...).
+``@dt=0x...`` The address of the data type this node references.
+``w32``       The data-type width() is 32 bits.
+``out_wide``  The name() of the node, in this case, the name of the
+              variable.
+``[O]``       Flags which vary with the type of node, in this case of a
+              VAR, it means the variable is an output.
+============= =============================================================
 
 In more detail, the following fields are dumped common to all nodes. They
 are produced by the ``AstNode::dump()`` method:
@@ -2107,19 +2126,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.
@@ -2141,31 +2160,109 @@ backtrace. You will typically see a frame sequence something like:
    visit()
    ...
 
+Bisecting bad transformations
+-----------------------------
+
+If a bad transformation in the internals of Verilator causes a failure only
+at runtime, it can be found fairly automatically by only applying the
+transform a limited number of times, then performing a bisection search
+over the limit to pinpoint the exact transformation that introduces the
+failure.
+
+To facilitate this an instance of the ``V3DebugBisect`` class can be used
+in conjunction with the ``verilator_bisect`` script.
+
+In the offending algorithm, create a static instance of ``V3DebugBisect``:
+
+::
+
+   static V3DebugBisect s_debugBisect{"TransformName"};
+
+Call the ``stop`` method before applying a transformation, and do not
+proceed if it returns ``false``. Then use ``verilator_bisect`` to search an
+interval of values. You need to provide an arbitrary discriminator command,
+this should run Verilator, then any necessary checks (e.g.: simulation) to
+detect that the failure is still present. It should exit with a non-zero
+status if the failure is still present. The discriminator command can
+otherwise be arbitrarily complex, the actual search limit is passed via
+environment variables. E.g.:
+
+::
+
+   bin/verilator_bisect DfgPeephole 0 1000 test_regress/t/t_myothertest.py
+
+An additional command can be run before the discriminator command. E.g.
+this will run RTLMeter, but first removes its working directory so the
+models are recompiled on every step:
+
+::
+
+   bin/verilator_bisect --pre "rm -rf work-bisect" DfgPeephole 0 10000000 \
+     rtlmeter run --cases "..." --workRoot=work-bisect
+
+When the bisection ends, the first value that makes the discriminator
+command fail is printed, which identifies the exact offending application
+of the transform.
+
+Debugging Non-Deterministic Results
+-----------------------------------
+
+The Verilator binary should be deterministic, producing the same Verilated
+C++ and stdout when run multiple times with the same inputs. A common
+source of non-determinism is (mis-)use of pointers in container
+comparisons, causing arbitrary changes im memory layout to make container
+comparisons differ, and in turn creating differences in Ast layout, and
+ultimately different C++ code.
+
+To debug this, compile Verilator with the `VL_ALLOC_RANDOM_CHECKS` define,
+then Verilator may be run with a seed e.g. `-debug-alloc-random 22` and
+`-debug-alloc-random 33` which will randomly change the memory allocation
+order. If multiple seeds are run, `verilator_difftree` may then be used to
+see where netlists start to differ. Once the Ast difference is determined,
+the debugging tips above can then further isolate the C++ code causing a
+specific node to be created or changed.
+
+The typical fix is to add a comparison operator to the problematic
+container, e.g. compare using `AstNodeComparator` or by `name()`.
+
+The following script is an example of this debugging:
+
+.. code-block:: bash
+
+   # Before this: ./configure CXX="g++ -DVL_ALLOC_RANDOM_CHECKS" && make -j
+   # Example script for finding nondeterminism
+   cd $VERILATOR_ROOT
+   set -e
+   t=t_split_var_0  # Test name
+   test_regress/t/$t.py --debug --debug-alloc-random 33 --dumpi-tree 9 --obj-suffix .33
+   test_regress/t/$t.py --debug --debug-alloc-random 66 --dumpi-tree 9 --obj-suffix .66
+   bin/verilator_difftree test_regress/obj_vlt/$t{.33,.66} | grep -v CFILE | grep -v "^ " | grep -v /tmp | grep -v @@
+
 
 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
@@ -2208,9 +2305,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
 ===========
@@ -2654,6 +2748,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
 ============
 
@@ -2662,6 +2805,7 @@ the terms of either the GNU Lesser General Public License Version 3 or the
 Perl Artistic License Version 2.0.
 
 SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+
 SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. |Logo| image:: https://www.veripool.org/img/verilator_256_200_min.png

docs/security.rst

@@ -1,6 +1,7 @@
-.. for github, vim: syntax=reStructuredText
-.. SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
-.. SPDX-License-Identifier: CC0-1.0
+..
+   for github, vim: syntax=reStructuredText
+   SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
+   SPDX-License-Identifier: CC0-1.0
 
 Security Policy
 ===============

docs/spelling.txt

@@ -180,6 +180,7 @@ Guo
 Gustafsson
 Güzel
 Hameed
+Hamming
 Hammoud
 Hao
 Haojin
@@ -333,6 +334,7 @@ Muhlestein
 Multithreaded
 Multithreading
 Mykyta
+NFA
 NOUNOPTFLAT
 NaN
 Nalbantis
@@ -428,6 +430,7 @@ Sasselli
 Sauter
 Scharrer
 Schless
+Secturion
 Seitz
 Shahid
 Shahrestani
@@ -578,6 +581,7 @@ Yujia
 Yurii
 Zaruba
 Zhang
+Zhi
 abirkmanis
 accessor
 accessors
@@ -589,6 +593,7 @@ al
 ala
 alejandro
 algrobman
+allocator
 andit
 ar
 architected
@@ -665,6 +670,7 @@ concatenatable
 concats
 conf
 config
+consequents
 const
 constexpr
 constification
@@ -678,6 +684,8 @@ countones
 cout
 covergroup
 covergroups
+coverpoint
+coverpoints
 cpp
 cppstyle
 cpu
@@ -696,6 +704,7 @@ datafiles
 david
 ddd
 de
+dearray
 deassign
 debugi
 defenv
@@ -810,6 +819,7 @@ fs
 fscanf
 fseek
 fsiegle
+fsm
 fst
 fstrict
 ftell
@@ -834,8 +844,10 @@ glibc
 gmake
 gmon
 gotFinish
+goto
 gprof
 gtkwave
+hdl
 hdr
 hdzhangdoc
 hh
@@ -850,6 +862,7 @@ hx
 hyperthreading
 hyperthreads
 icecream
+ico
 idmap
 ifdef
 ifdefed
@@ -859,6 +872,7 @@ impot
 incdir
 includer
 incrementing
+inferable
 inferfaces
 informationals
 inhibitSim
@@ -878,6 +892,7 @@ iostream
 ish
 isunbounded
 isunknown
+jemalloc
 jobserver
 json
 jwoutersymatra
@@ -891,7 +906,9 @@ len
 libc
 libext
 libgoogle
+libjemalloc
 liblist
+liblz
 libsystemc
 libtcmalloc
 libverilated
@@ -901,6 +918,8 @@ linters
 linux
 liu
 livelock
+liveness
+lldb
 ln
 loc
 localparam
@@ -908,6 +927,7 @@ localparams
 localtime
 logicals
 longint
+lookups
 lossy
 lsb
 lubc
@@ -917,6 +937,7 @@ lxt
 macromodule
 makefile
 makefiles
+malloc
 manpages
 metacomment
 metacomments
@@ -979,6 +1000,7 @@ onehot
 ooo
 oprofile
 ortegon
+output
 oversized
 oversubscription
 parallelized
@@ -1067,12 +1089,14 @@ recrem
 recurse
 recurses
 redeclaring
+reentrant
 regs
 reloop
 replaceShiftOp
 reproducibility
 resetall
 respecified
+reusability
 rodata
 rolloverSize
 rr
@@ -1103,6 +1127,7 @@ specparam
 splitme
 spp
 sqrt
+srand
 srandom
 src
 srcdir
@@ -1146,6 +1171,7 @@ sys
 systemc
 taskify
 tcmalloc
+tcmalloc
 tenghtt
 testbench
 threadsafe
@@ -1182,6 +1208,7 @@ typename
 uint
 un
 unbased
+unclocked
 uncomment
 undef
 undefineall
@@ -1197,6 +1224,7 @@ unnamedblk
 unopt
 unoptflat
 unoptimizable
+unparenthesized
 unroller
 unsatisfiable
 unsized
@@ -1206,6 +1234,7 @@ upcasting
 urandom
 uselib
 utimes
+uvm
 uwire
 uwires
 valgrind
@@ -1239,6 +1268,7 @@ vpiConstType
 vpiDefName
 vpiInertialDelay
 vpiInstance
+vpiIntVal
 vpiLeftRange
 vpiModule
 vpiSigned
@@ -1251,6 +1281,7 @@ vpm
 vpp
 warmup
 wavealloca
+wavediff
 waveforms
 whitespace
 widthed

include/AGENTS.md

@@ -0,0 +1,60 @@
+<!-- DESCRIPTION: Verilator: include/ guidelines for AI coding agents
+     SPDX-FileCopyrightText: 2026-2026 Wilson Snyder
+     SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0 -->
+
+# include/ -- Verilator runtime library
+
+Covers the C++ runtime under `include/` (`verilated.h/.cpp`, `verilated_*.h/.cpp`)
+that every generated model links against. Read the repository-root
+[AGENTS.md](../AGENTS.md) first. The rules here differ from `src/`: this code
+ships to users, runs every simulation cycle, and must stay portable and fast.
+
+______________________________________________________________________
+
+# Orientation
+
+- **This is the runtime, not the compiler.** The passes in `src/` *emit* C++ that
+  calls into this library; this code then *runs* during simulation. Optimize it
+  for execution speed and portability, not for compile-time clarity.
+- **Key files:** `verilated.h` (core model API), `verilated_types.h` (data
+  types), `verilated_random.cpp` (constrained-random runtime), `verilated_cov.*`
+  (coverage), `verilated_threads.*` (MT runtime), `verilated_timing.*`
+  (`--timing` runtime), `verilated_vcd_c.*`/`verilated_fst_c.*` (tracing).
+- A runtime-only fix lives entirely here and does not rebuild `verilator_bin`.
+
+______________________________________________________________________
+
+# Before you open a PR
+
+- **C++14 baseline.** The runtime must build under `--no-timing` with C++14; C++20
+  features are allowed only in `--timing` code paths.
+- **Public API naming and docs.** Prefix public classes and types with
+  `Verilated`/`Vl` to avoid collisions with user code, and document the API with
+  `///` comments -- they feed doc generation.
+- **No exceptions in runtime code** -- use error returns or assertions; exceptions
+  add overhead on every path.
+- **Use fixed-width model types** (`CData`/`SData`/`IData`/`QData`/`VlWide`), never
+  `size_t`, for model data. Process wide data word-by-word (`VL_ZERO_W`,
+  `VL_MEMCPY_W`), never bit-by-bit or byte-by-byte.
+- **Do all string parsing at verilation time** -- never parse strings during
+  simulation; emit structured data or compile-time hints instead.
+- **Keep per-cycle code lean.** Do not add vtables to high-frequency objects
+  (8 bytes per instance); guard optional features behind
+  `hasClasses()`/`hasEvents()`-style checks; functions called per cycle must avoid
+  mutexes -- use atomics or lockless designs.
+- **Emit no runtime loops** the compiler could have expanded at verilation time;
+  prefer a single runtime call.
+- **Thread safety.** Annotate with the hierarchy `VL_PURE` > `VL_MT_SAFE` >
+  `VL_MT_STABLE`; annotations must match the implementation. Annotate
+  mutex-protected members with `VL_GUARDED_BY` and document acquisition ordering.
+  Prefer has-a over is-a: a guarded class wrapping the unguarded internal one, with
+  the guarded version as the default public API.
+- **Keep runtime and compiler headers separate** -- never include `verilated.h`
+  into the compiler in `src/`.
+
+## File-specific rules
+
+| File | Rule |
+|---|---|
+| `verilated_random.cpp` | Emit only portable SMT-LIB 2.6 -- no solver-specific or MaxSMT extensions; the generated solver text is the model's runtime constraint interface |
+| `verilated_cov.cpp` | Coverage runtime is shared by all models -- keep per-point overhead minimal and the on-disk format stable for `verilator_coverage` |

include/fstcpp/.clang-format

@@ -0,0 +1,22 @@
+---
+Language: Cpp
+BasedOnStyle: Google
+
+AccessModifierOffset: -4
+AlignAfterOpenBracket: BlockIndent
+AlignEscapedNewlines: Left
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortFunctionsOnASingleLine: Inline
+BinPackArguments: false
+BinPackParameters: false
+BreakBeforeBraces: Attach
+ColumnLimit: 100
+ContinuationIndentWidth: 4
+DerivePointerAlignment: false
+IncludeBlocks: Preserve
+IndentCaseLabels: false
+IndentPPDirectives: AfterHash
+IndentWidth: 4
+PointerAlignment: Right
+TabWidth: 4
+UseTab: ForContinuationAndIndentation

include/fstcpp/fstcpp.h

@@ -0,0 +1,260 @@
+// SPDX-FileCopyrightText: 2025-2026 Yu-Sheng Lin <[email protected]>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+#pragma once
+// direct include
+// C system headers
+// C++ standard library headers
+#include <cstddef>
+#include <cstdint>
+#include <cstring>
+#include <string>
+// Other libraries' .h files.
+// Your project's .h files.
+#if defined(MSC_VER_) || defined(FORCE_MSC_VER_)
+#	define USE_GCC_INTRINSIC 0
+// Note: we do not support MSVC intrinsic for now
+#	define USE_MSVC_INTRINSIC 0
+#elif defined(__GNUC__) || defined(__clang__)
+#	define USE_GCC_INTRINSIC 1
+#	define USE_MSVC_INTRINSIC 0
+#else
+#	define USE_GCC_INTRINSIC 0
+#	define USE_MSVC_INTRINSIC 0
+#endif
+
+// Remove these when we upgrade to C++20
+#pragma GCC diagnostic ignored "-Wpragmas"
+#pragma GCC diagnostic ignored "-Wc++17-attribute-extensions"
+#pragma GCC diagnostic ignored "-Wc++20-attribute-extensions"
+
+namespace fst {
+
+typedef uint32_t Handle;
+typedef uint32_t EnumHandle;
+struct string_view_pair {
+	const char *m_data = nullptr;
+	size_t m_size = 0;
+
+	// implicit conversion from const char*, std::string, std::string_view
+	string_view_pair(const char *data)
+		: m_data{data}, m_size{data == nullptr ? 0 : std::strlen(data)} {}
+	string_view_pair(const char *data, size_t size) : m_data{data}, m_size{size} {}
+	string_view_pair(const std::string &s) : m_data{s.c_str()}, m_size{s.size()} {}
+#if __cplusplus >= 201703L
+	string_view_pair(std::string_view s) : m_data{s.data()}, m_size{s.size()} {}
+#endif
+};
+
+[[maybe_unused]]
+static inline string_view_pair make_string_view_pair(const char *data) {
+	if (!data) {
+		return {nullptr, 0};
+	}
+	return {data, std::strlen(data)};
+}
+
+[[maybe_unused]]
+static inline string_view_pair make_string_view_pair(const char *data, std::size_t size) {
+	return {data, size};
+}
+
+enum class WriterPackType : uint8_t {
+	ZLIB = 0,    // not supported
+	FASTLZ = 1,  // not supported
+	LZ4 = 2,
+	// usually for testing, you should use eLz4
+	// This will turn off compression for geometry/hierarchy/wave data
+	NO_COMPRESSION = 3,
+};
+
+enum class FileType : uint8_t {
+	VERILOG = 0,
+	VHDL,
+	VERILOG_VHDL,
+};
+
+enum class EncodingType : uint8_t {
+	BINARY = 0,   // 1 bit per bit to represent 0,1
+	VERILOG = 1,  // 2 bits per bit to represent X,Z
+	VHDL = 2,     // 4 bits per bit to represent H,U,W,L,-,?
+};
+
+[[maybe_unused]]
+static inline constexpr unsigned bitPerEncodedBit(EncodingType type) {
+	return 1 << static_cast<uint8_t>(type);
+}
+
+[[maybe_unused]]
+static const char* kEncodedBitToCharTable = (
+	"01" // Binary
+	"xzhu" // Verilog
+	"wl-?    " // Vhdl (padded with ' ')
+);
+
+struct Hierarchy {
+	enum class ScopeType : uint8_t {
+		VCD_MODULE = 0,
+		VCD_TASK = 1,
+		VCD_FUNCTION = 2,
+		VCD_BEGIN = 3,
+		VCD_FORK = 4,
+		VCD_GENERATE = 5,
+		VCD_STRUCT = 6,
+		VCD_UNION = 7,
+		VCD_CLASS = 8,
+		VCD_INTERFACE = 9,
+		VCD_PACKAGE = 10,
+		VCD_PROGRAM = 11,
+		VHDL_ARCHITECTURE = 12,
+		VHDL_PROCEDURE = 13,
+		VHDL_FUNCTION = 14,
+		VHDL_RECORD = 15,
+		VHDL_PROCESS = 16,
+		VHDL_BLOCK = 17,
+		VHDL_FORGENERATE = 18,
+		VHDL_IFGENERATE = 19,
+		VHDL_GENERATE = 20,
+		VHDL_PACKAGE = 21,
+		SV_ARRAY = 22,
+	};
+
+	enum class ScopeControlType : uint8_t {
+		GEN_ATTR_BEGIN = 252,
+		GEN_ATTR_END = 253,
+		VCD_SCOPE = 254,
+		VCD_UPSCOPE = 255,
+	};
+
+	enum class VarType : uint8_t {
+		VCD_EVENT = 0,
+		VCD_INTEGER = 1,
+		VCD_PARAMETER = 2,
+		VCD_REAL = 3,
+		VCD_REAL_PARAMETER = 4,
+		VCD_REG = 5,
+		VCD_SUPPLY0 = 6,
+		VCD_SUPPLY1 = 7,
+		VCD_TIME = 8,
+		VCD_TRI = 9,
+		VCD_TRIAND = 10,
+		VCD_TRIOR = 11,
+		VCD_TRIREG = 12,
+		VCD_TRI0 = 13,
+		VCD_TRI1 = 14,
+		VCD_WAND = 15,
+		VCD_WIRE = 16,
+		VCD_WOR = 17,
+		VCD_PORT = 18,
+		VCD_SPARRAY = 19,
+		VCD_REALTIME = 20,
+		GEN_STRING = 21,
+		SV_BIT = 22,
+		SV_LOGIC = 23,
+		SV_INT = 24,
+		SV_SHORTINT = 25,
+		SV_LONGINT = 26,
+		SV_BYTE = 27,
+		SV_ENUM = 28,
+		SV_SHORTREAL = 29,
+	};
+
+	enum class VarDirection : uint8_t {
+		MIN = 0,
+
+		IMPLICIT = 0,
+		INPUT = 1,
+		OUTPUT = 2,
+		INOUT = 3,
+		BUFFER = 4,
+		LINKAGE = 5,
+
+		MAX = 5,
+	};
+
+	enum class AttrType : uint8_t {
+		MIN = 0,
+		MISC = 0,
+		ARRAY = 1,
+		ENUM = 2,
+		PACK = 3,
+		MAX = 3,
+	};
+
+	enum class AttrSubType : uint8_t {
+		// For AttrType::eMisc
+		MISC_MIN = 0,
+		MISC_COMMENT = 0,
+		MISC_ENVVAR = 1,
+		MISC_SUPVAR = 2,
+		MISC_PATHNAME = 3,
+		MISC_SOURCESTEM = 4,
+		MISC_SOURCEISTEM = 5,
+		MISC_VALUELIST = 6,
+		MISC_ENUMTABLE = 7,
+		MISC_UNKNOWN = 8,
+		MISC_MAX = 8,
+
+		// For AttrType::eArray
+		ARRAY_MIN = 0,
+		ARRAY_NONE = 0,
+		ARRAY_UNPACKED = 1,
+		ARRAY_PACKED = 2,
+		ARRAY_SPARSE = 3,
+		ARRAY_MAX = 3,
+
+		// For AttrType::eEnum
+		ENUM_MIN = 0,
+		ENUM_SV_INTEGER = 0,
+		ENUM_SV_BIT = 1,
+		ENUM_SV_LOGIC = 2,
+		ENUM_SV_INT = 3,
+		ENUM_SV_SHORTINT = 4,
+		ENUM_SV_LONGINT = 5,
+		ENUM_SV_BYTE = 6,
+		ENUM_SV_UNSIGNED_INTEGER = 7,
+		ENUM_SV_UNSIGNED_BIT = 8,
+		ENUM_SV_UNSIGNED_LOGIC = 9,
+		ENUM_SV_UNSIGNED_INT = 10,
+		ENUM_SV_UNSIGNED_SHORTINT = 11,
+		ENUM_SV_UNSIGNED_LONGINT = 12,
+		ENUM_SV_UNSIGNED_BYTE = 13,
+		ENUM_REG = 14,
+		ENUM_TIME = 15,
+		ENUM_MAX = 15,
+
+		// For AttrType::ePack
+		PACK_MIN = 0,
+		PACK_NONE = 0,
+		PACK_UNPACKED = 1,
+		PACK_PACKED = 2,
+		PACK_SPARSE = 3,
+		PACK_MAX = 3,
+	};
+
+	enum class SupplementalVarType : uint8_t {};
+
+	enum class SupplementalDataType : uint8_t {};
+};
+
+struct Header {
+	uint64_t m_start_time{uint64_t(-1)};
+	uint64_t m_end_time{0};
+	int64_t m_timezero{0};
+	// Match the original fstapi.c. Just for information, not used in FST.
+	uint64_t m_writer_memory_use{1ull << 27};
+	uint64_t m_num_scopes{0};
+	uint64_t m_num_vars{0};     // #CreateVar calls, including aliases
+	uint64_t m_num_handles{0};  // #unique handles, excluding aliases, shall be <= m_num_vars
+	uint64_t m_num_value_change_data_blocks{0};
+	char m_writer[128]{};
+	char m_date[26]{};
+	FileType m_filetype{FileType::VERILOG};
+	int8_t m_timescale{-9};
+};
+
+static constexpr uint64_t kInvalidTime = uint64_t(-1);
+
+}  // namespace fst

include/fstcpp/fstcpp_assertion.h

@@ -0,0 +1,119 @@
+// SPDX-FileCopyrightText: 2025 Yu-Sheng Lin <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+#pragma once
+// direct include
+// C system headers
+// C++ standard library headers
+#include <cstdlib>
+#include <iostream>
+#include <sstream>
+// Other libraries' .h files.
+// Your project's .h files.
+
+#define FST_CHECK(a)                    \
+	if (!(a)) [[unlikely]] {            \
+		std::ostringstream oss;         \
+		oss << "FST_CHECK failed: " #a; \
+		const auto e = oss.str();       \
+		std::cerr << e << std::endl;    \
+		std::abort();                   \
+	}
+
+#define FST_CHECK_EQ(a, b)                           \
+	if ((a) != (b)) [[unlikely]] {                   \
+		std::ostringstream oss;                      \
+		oss << "FST_CHECK_EQ failed: " #a " != " #b; \
+		oss << " (" << (a) << " vs. " << (b) << ")"; \
+		const auto e = oss.str();                    \
+		std::cerr << e << std::endl;                 \
+		std::abort();                                \
+	}
+
+#define FST_CHECK_NE(a, b)                           \
+	if ((a) == (b)) [[unlikely]] {                   \
+		std::ostringstream oss;                      \
+		oss << "FST_CHECK_NE failed: " #a " == " #b; \
+		oss << " (" << (a) << " vs. " << (b) << ")"; \
+		const auto e = oss.str();                    \
+		std::cerr << e << std::endl;                 \
+		std::abort();                                \
+	}
+
+#define FST_CHECK_GT(a, b)                           \
+	if ((a) <= (b)) [[unlikely]] {                   \
+		std::ostringstream oss;                      \
+		oss << "FST_CHECK_GT failed: " #a " <= " #b; \
+		oss << " (" << (a) << " vs. " << (b) << ")"; \
+		const auto e = oss.str();                    \
+		std::cerr << e << std::endl;                 \
+		std::abort();                                \
+	}
+
+#define FST_CHECK_GE(a, b)                           \
+	if ((a) < (b)) [[unlikely]] {                    \
+		std::ostringstream oss;                      \
+		oss << "FST_CHECK_GE failed: " #a " < " #b;  \
+		oss << " (" << (a) << " vs. " << (b) << ")"; \
+		const auto e = oss.str();                    \
+		std::cerr << e << std::endl;                 \
+		std::abort();                                \
+	}
+
+#define FST_CHECK_LT(a, b)                           \
+	if ((a) >= (b)) [[unlikely]] {                   \
+		std::ostringstream oss;                      \
+		oss << "FST_CHECK_LT failed: " #a " >= " #b; \
+		oss << " (" << (a) << " vs. " << (b) << ")"; \
+		const auto e = oss.str();                    \
+		std::cerr << e << std::endl;                 \
+		std::abort();                                \
+	}
+
+#define FST_CHECK_LE(a, b)                           \
+	if ((a) > (b)) [[unlikely]] {                    \
+		std::ostringstream oss;                      \
+		oss << "FST_CHECK_LE failed: " #a " > " #b;  \
+		oss << " (" << (a) << " vs. " << (b) << ")"; \
+		const auto e = oss.str();                    \
+		std::cerr << e << std::endl;                 \
+		std::abort();                                \
+	}
+
+#define FST_FAIL_STRING(s)              \
+	do {                                \
+		std::cerr << (s) << std::endl;  \
+		std::abort();                   \
+	} while (0)
+
+// We turn on all DCHECKs to CHECKs temporarily for better safety.
+#if 1
+#	define FST_DCHECK(a) FST_CHECK(a)
+#	define FST_DCHECK_EQ(a, b) FST_CHECK_EQ(a, b)
+#	define FST_DCHECK_NE(a, b) FST_CHECK_NE(a, b)
+#	define FST_DCHECK_GT(a, b) FST_CHECK_GT(a, b)
+#	define FST_DCHECK_GE(a, b) FST_CHECK_GE(a, b)
+#	define FST_DCHECK_LT(a, b) FST_CHECK_LT(a, b)
+#	define FST_DCHECK_LE(a, b) FST_CHECK_LE(a, b)
+#else
+#	define FST_DCHECK(a)
+#	define FST_DCHECK_EQ(a, b)
+#	define FST_DCHECK_NE(a, b)
+#	define FST_DCHECK_GT(a, b)
+#	define FST_DCHECK_GE(a, b)
+#	define FST_DCHECK_LT(a, b)
+#	define FST_DCHECK_LE(a, b)
+#endif
+
+// Compatibility layer for unreachable code hint
+#if defined(__cplusplus) && __cplusplus >= 202302L
+#	include <utility>
+#	define FST_UNREACHABLE std::unreachable()
+#elif USE_GCC_INTRINSIC
+#	define FST_UNREACHABLE __builtin_unreachable()
+// TODO: implement MSVC version
+// #elif USE_MSVC_INTRINSIC
+#else
+#	define FST_UNREACHABLE std::abort()
+#endif

include/fstcpp/fstcpp_file.h

@@ -0,0 +1,83 @@
+// SPDX-FileCopyrightText: 2025-2026 Yu-Sheng Lin <[email protected]>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+#pragma once
+// direct include
+// C system headers
+// C++ standard library headers
+#include <cstdint>
+// Other libraries' .h files.
+// Your project's .h files.
+
+namespace fst {
+
+// Original block types from fstapi.h
+// FST_BL_HDR = 0,
+// FST_BL_VCDATA = 1,
+// FST_BL_BLACKOUT = 2,
+// FST_BL_GEOM = 3,
+// FST_BL_HIER = 4,
+// FST_BL_VCDATA_DYN_ALIAS = 5,
+// FST_BL_HIER_LZ4 = 6,
+// FST_BL_HIER_LZ4DUO = 7,
+// FST_BL_VCDATA_DYN_ALIAS2 = 8,
+// FST_BL_ZWRAPPER = 254,
+// FST_BL_SKIP = 255
+enum class BlockType : uint8_t {
+	HEADER = 0,
+	WAVE_DATA_VERSION1 = 1,  // not implemented
+	BLACKOUT = 2,
+	GEOMETRY = 3,
+	HIERARCHY_GZ_COMPRESSED = 4,  // not implemented
+	WAVE_DATA_VERSION2 = 5,       // not implemented
+	HIERARCHY_LZ4_COMPRESSED = 6,
+	HIERARCHY_LZ4_COMPRESSED_TWICE = 7,  // not implemented
+	WAVE_DATA_VERSION3 = 8,
+
+	ZWRAPPER = 254,  // not implemented
+	SKIP = 255       // not implemented
+};
+
+constexpr unsigned kSharedBlockHeaderSize = 1 /* BlockType */ + 8 /* size (u64) */;
+
+struct HeaderInfo {
+	struct Size {
+		static constexpr unsigned start_time = 0;
+		static constexpr unsigned end_time = 8;
+		static constexpr unsigned real_endianness = 8;
+		static constexpr unsigned writer_memory_use = 8;
+		static constexpr unsigned num_scopes = 8;
+		static constexpr unsigned num_vars = 8;
+		static constexpr unsigned num_handles = 8;
+		static constexpr unsigned num_wave_data_blocks = 8;
+		static constexpr unsigned timescale = 1;
+		static constexpr unsigned writer = 128;
+		static constexpr unsigned date = 26;
+		static constexpr unsigned reserved = 93;
+		static constexpr unsigned filetype = 1;
+		static constexpr unsigned timezero = 8;
+	};
+	struct Offset {
+		static constexpr unsigned start_time = 0;
+		static constexpr unsigned end_time = start_time + Size::end_time;
+		static constexpr unsigned real_endianness = end_time + Size::real_endianness;
+		static constexpr unsigned writer_memory_use = real_endianness + Size::writer_memory_use;
+		static constexpr unsigned num_scopes = writer_memory_use + Size::num_scopes;
+		static constexpr unsigned num_vars = num_scopes + Size::num_vars;
+		static constexpr unsigned num_handles = num_vars + Size::num_vars;
+		static constexpr unsigned num_wave_data_blocks = num_handles + Size::num_handles;
+		static constexpr unsigned timescale = num_wave_data_blocks + Size::num_wave_data_blocks;
+		static constexpr unsigned writer = timescale + Size::timescale;
+		static constexpr unsigned date = writer + Size::writer;
+		static constexpr unsigned reserved = date + Size::date;
+		static constexpr unsigned filetype = reserved + Size::reserved;
+		static constexpr unsigned timezero = filetype + Size::filetype;
+	};
+	static constexpr unsigned total_size = Offset::timezero + Size::timezero;
+	static constexpr double kEndianessMagicIdentifier = 2.7182818284590452354;
+	static_assert(total_size == 321, "Total size of HeaderInfo must be 321 bytes");
+};
+
+}  // namespace fst

include/fstcpp/fstcpp_stream_write_helper.h

@@ -0,0 +1,388 @@
+// SPDX-FileCopyrightText: 2025-2026 Yu-Sheng Lin <[email protected]>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+#pragma once
+// direct include
+// C system headers
+// C++ standard library headers
+#if defined(__cplusplus) && __cplusplus >= 202302L
+#	include <bit>
+#endif
+#include <cstdint>
+#include <cstring>
+#include <vector>
+// Other libraries' .h files.
+// Your project's .h files.
+#include "fstcpp/fstcpp.h"
+#include "fstcpp/fstcpp_file.h"
+
+namespace fst {
+
+namespace platform {
+
+// For C++14
+// Can remove once C++23 is required
+#if defined(__BYTE_ORDER__) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
+// clang-format off
+template <typename U> U to_big_endian(U u) { return u; }
+#else
+#if defined(__cplusplus) && __cplusplus >= 202302L
+template <typename U, size_t S>
+U to_big_endian(U u, std::integral_constant<size_t, S>) {
+	return std::byteswap(u);
+}
+#elif USE_GCC_INTRINSIC
+template<typename U> U to_big_endian(U u, std::integral_constant<size_t, 1>) { return u; }
+template<typename U> U to_big_endian(U u, std::integral_constant<size_t, 2>) { return __builtin_bswap16(u); }
+template<typename U> U to_big_endian(U u, std::integral_constant<size_t, 4>) { return __builtin_bswap32(u); }
+template<typename U> U to_big_endian(U u, std::integral_constant<size_t, 8>) { return __builtin_bswap64(u); }
+// TODO: implement MSVC version
+// #elif USE_MSVC_INTRINSIC
+#else
+template <typename U, size_t S>
+U to_big_endian(U u, std::integral_constant<size_t, S>) {
+	U ret{0};
+	for (size_t i = 0; i < S; ++i) {
+		ret = (ret << 8) | (u & 0xff);
+		u >>= 8;
+	}
+	return ret;
+}
+#endif
+// clang-format on
+template <typename U>
+U to_big_endian(U u) {
+	return platform::to_big_endian(u, std::integral_constant<size_t, sizeof(U)>());
+}
+#endif
+
+}  // namespace platform
+
+struct StreamWriteHelper {
+	std::ostream *m_os{nullptr};
+
+	StreamWriteHelper(std::ostream &os_) : m_os{&os_} {}
+	StreamWriteHelper(std::ostream *os_) : m_os{os_} {}
+
+	// Write the entire uint, big-endian
+	// We do not provide little-endian version since FST only uses big-endian
+	template <typename U>
+	StreamWriteHelper &writeUInt(U u) {
+		u = platform::to_big_endian(u);
+		m_os->write(reinterpret_cast<const char *>(&u), sizeof(u));
+		return *this;
+	}
+
+	// Write the uint, big-endian, left-aligned but only (bitwidth+7)/8 bytes
+	// This is a very special case for value changes
+	// For example, if the value is 10-bits (e.g. logic [9:0] in Verilog),
+	// then the first byte will be [9-:8], then {[1:0], 6'b0}.
+	template <typename U>
+	StreamWriteHelper &writeUIntPartialForValueChange(U u, size_t bitwidth) {
+		// Shift left to align the MSB to the MSB of the uint
+		u <<= sizeof(u) * 8 - bitwidth;
+		// Write the first (bitwidth+7)/8 bytes
+		u = platform::to_big_endian(u);
+		m_os->write(reinterpret_cast<const char *>(&u), (bitwidth + 7) / 8);
+		return *this;
+	}
+
+	StreamWriteHelper &writeLEB128(uint64_t v) {
+		// Just reuse the logic from fstapi.c, is there a better way?
+		uint64_t nxt{0};
+		unsigned char buf[10]{}; /* ceil(64/7) = 10 */
+		unsigned char *pnt{buf};
+		int len{0};
+		while ((nxt = v >> 7)) {
+			*(pnt++) = ((unsigned char)v) | 0x80;
+			v = nxt;
+		}
+		*(pnt++) = (unsigned char)v;
+		len = static_cast<int>(pnt - buf);
+		m_os->write(reinterpret_cast<const char *>(buf), len);
+		return *this;
+	}
+
+	StreamWriteHelper &writeLEB128Signed(int64_t v) {
+		// Just reuse the logic from fstapi.c, is there a better way?
+		unsigned char buf[15]{}; /* ceil(64/7) = 10 + sign byte padded way up */
+		unsigned char byt{0};
+		unsigned char *pnt{buf};
+		int more{1};
+		int len{0};
+		do {
+			byt = static_cast<unsigned char>(v | 0x80);
+			v >>= 7;
+
+			if (((!v) && (!(byt & 0x40))) || ((v == -1) && (byt & 0x40))) {
+				more = 0;
+				byt &= 0x7f;
+			}
+
+			*(pnt++) = byt;
+		} while (more);
+		len = static_cast<int>(pnt - buf);
+		m_os->write(reinterpret_cast<const char *>(buf), len);
+		return *this;
+	}
+
+	template <typename F>
+	StreamWriteHelper &writeFloat(F f) {
+		// Always write in native endianness
+		m_os->write(reinterpret_cast<const char *>(&f), sizeof(f));
+		return *this;
+	}
+
+	StreamWriteHelper &writeBlockHeader(fst::BlockType block_type, uint64_t block_length) {
+		return (
+			this  //
+				->writeUInt(static_cast<uint8_t>(block_type))
+				.writeUInt(
+					block_length + 8
+				)  // The 8 is required by FST, which is the size of this uint64_t
+		);
+	}
+
+	// Write the string, non-null-terminated
+	StreamWriteHelper &writeString(const fst::string_view_pair str) {
+		m_os->write(str.m_data, str.m_size);
+		return *this;
+	}
+
+	// Write the string, null-terminated
+	StreamWriteHelper &writeString0(const fst::string_view_pair str) {
+		m_os->write(str.m_data, str.m_size).put('\0');
+		return *this;
+	}
+	StreamWriteHelper &writeString(const std::string &str) {
+		return writeString0(fst::make_string_view_pair(str.c_str(), str.size()));
+	}
+	StreamWriteHelper &writeString(const char *str) {
+		return writeString0(fst::make_string_view_pair(str));
+	}
+
+	StreamWriteHelper &write(const char *ptr, size_t size) {
+		m_os->write(ptr, size);
+		return *this;
+	}
+
+	StreamWriteHelper &write(const uint8_t *ptr, size_t size) {
+		m_os->write(reinterpret_cast<const char *>(ptr), size);
+		return *this;
+	}
+
+	StreamWriteHelper &seek(std::streamoff pos, std::ios_base::seekdir dir) {
+		m_os->seekp(pos, dir);
+		return *this;
+	}
+
+	StreamWriteHelper &fill(char fill_char, size_t size) {
+		if (size > 32) {
+			// optimize large fills
+			constexpr unsigned s_kChunkSize = 16;
+			char buf[s_kChunkSize]{};
+			std::memset(buf, fill_char, s_kChunkSize);
+			for (size_t i{0}; i < size / s_kChunkSize; ++i) {
+				m_os->write(buf, s_kChunkSize);
+			}
+			size %= s_kChunkSize;
+		}
+		for (size_t i{0}; i < size; ++i) {
+			m_os->put(fill_char);
+		}
+		return *this;
+	}
+
+	// Handy functions for writing variable length data, you can
+	// cascade multiple write() calls after RecordOffset(), then
+	// call DiffOffset() to get the total number of bytes written.
+
+	// (1)
+	// std::streamoff diff;
+	// h
+	// .beginOffset(diff)
+	// .write(...)
+	// ... do other stuff ...
+	// .endOffset(&diff); <-- diff will be set to the number of bytes written
+	// (2)
+	// std::streamoff pos, diff;
+	// h
+	// .beginOffset(pos)
+	// .write(...)
+	// ... do other stuff ...
+	// .endOffset(&diff, pos); <-- diff will be set to the number of bytes written
+
+	// The API uses pointer on purpose to prevent you pass (pos, diff) as arguments
+	// to endOffset(), which is a common mistake.
+
+	StreamWriteHelper &beginOffset(std::streamoff &pos) {
+		pos = m_os->tellp();
+		return *this;
+	}
+
+	StreamWriteHelper &endOffset(std::streamoff *diff) {
+		// diff shall store previous position before calling this function
+		*diff = m_os->tellp() - *diff;
+		return *this;
+	}
+
+	StreamWriteHelper &endOffset(std::streamoff *diff, std::streamoff pos) {
+		*diff = m_os->tellp() - pos;
+		return *this;
+	}
+};
+
+struct StreamVectorWriteHelper {
+	std::vector<uint8_t> &m_vec;
+
+	StreamVectorWriteHelper(std::vector<uint8_t> &vec_) : m_vec{vec_} {}
+
+	template <typename T>
+	StreamVectorWriteHelper &write(T u) {
+		const size_t s = sizeof(u);
+		m_vec.resize(m_vec.size() + s);
+		std::memcpy(m_vec.data() + m_vec.size() - s, &u, s);
+		return *this;
+	}
+
+	template <typename T>
+	StreamVectorWriteHelper &fill(T u, size_t count) {
+		const size_t s = sizeof(u) * count;
+		m_vec.resize(m_vec.size() + s);
+		for (size_t i{0}; i < count; ++i) {
+			std::memcpy(m_vec.data() + m_vec.size() - s + i * sizeof(u), &u, sizeof(u));
+		}
+		return *this;
+	}
+
+	template <typename T>
+	StreamVectorWriteHelper &write(T *u, size_t size) {
+		const size_t s = sizeof(u) * size;
+		m_vec.resize(m_vec.size() + s);
+		std::memcpy(m_vec.data() + m_vec.size() - s, u, s);
+		return *this;
+	}
+
+	template <typename E>
+	StreamVectorWriteHelper &writeU8Enum(E e) {
+		m_vec.push_back(static_cast<uint8_t>(e));
+		return *this;
+	}
+
+	// Write the entire uint, big-endian
+	// We do not provide little-endian version since FST only uses big-endian
+	template <typename U>
+	StreamVectorWriteHelper &writeUIntBE(U u) {
+		u = platform::to_big_endian(u);
+		const size_t s = sizeof(u);
+		m_vec.resize(m_vec.size() + s);
+		std::memcpy(m_vec.data() + m_vec.size() - s, &u, s);
+		return *this;
+	}
+
+	// Write the uint, big-endian, left-aligned but only (bitwidth+7)/8 bytes
+	// This is a very special case for value changes
+	// For example, if the value is 10-bits (e.g. logic [9:0] in Verilog),
+	// then the first byte will be [9-:8], then {[1:0], 6'b0}.
+	template <typename U>
+	StreamVectorWriteHelper &writeUIntPartialForValueChange(U u, size_t bitwidth) {
+		// Shift left to align the MSB to the MSB of the uint
+		u <<= sizeof(u) * 8 - bitwidth;
+		// Write the first (bitwidth+7)/8 bytes
+		u = platform::to_big_endian(u);
+		const size_t s = (bitwidth + 7) / 8;
+		m_vec.resize(m_vec.size() + s);
+		std::memcpy(m_vec.data() + m_vec.size() - s, &u, s);
+		return *this;
+	}
+
+	StreamVectorWriteHelper &writeLEB128(uint64_t v) {
+		// Just reuse the logic from fstapi.c, is there a better way?
+		uint64_t nxt{0};
+		unsigned char buf[10]{}; /* ceil(64/7) = 10 */
+		unsigned char *pnt{buf};
+		int len{0};
+		while ((nxt = v >> 7)) {
+			*(pnt++) = ((unsigned char)v) | 0x80;
+			v = nxt;
+		}
+		*(pnt++) = (unsigned char)v;
+		len = static_cast<int>(pnt - buf);
+
+		const size_t cur = m_vec.size();
+		m_vec.resize(cur + len);
+		std::memcpy(m_vec.data() + cur, buf, len);
+		return *this;
+	}
+
+	StreamVectorWriteHelper &writeLEB128Signed(int64_t v) {
+		// Just reuse the logic from fstapi.c, is there a better way?
+		unsigned char buf[15]{}; /* ceil(64/7) = 10 + sign byte padded way up */
+		unsigned char byt{0};
+		unsigned char *pnt{buf};
+		int more{1};
+		int len{0};
+		do {
+			byt = static_cast<unsigned char>(v | 0x80);
+			v >>= 7;
+
+			if (((!v) && (!(byt & 0x40))) || ((v == -1) && (byt & 0x40))) {
+				more = 0;
+				byt &= 0x7f;
+			}
+
+			*(pnt++) = byt;
+		} while (more);
+		len = static_cast<int>(pnt - buf);
+
+		const size_t cur = m_vec.size();
+		m_vec.resize(cur + len);
+		std::memcpy(m_vec.data() + cur, buf, len);
+		return *this;
+	}
+
+	StreamVectorWriteHelper &writeBlockHeader(fst::BlockType block_type, uint64_t block_length) {
+		return (
+			this  //
+				->writeUIntBE(static_cast<uint8_t>(block_type))
+				.writeUIntBE(
+					block_length + 8
+				)  // The 8 is required by FST, which is the size of this uint64_t
+		);
+	}
+
+	// Write the string, non-null-terminated
+	StreamVectorWriteHelper &writeString(const fst::string_view_pair str) {
+		if (str.m_size != 0) {
+			const size_t len = str.m_size;
+			const size_t cur = m_vec.size();
+			m_vec.resize(cur + len);
+			std::memcpy(m_vec.data() + cur, str.m_data, len);
+		}
+		return *this;
+	}
+
+	// Write the string, null-terminated
+	StreamVectorWriteHelper &writeString0(const fst::string_view_pair str) {
+		if (str.m_size != 0) {
+			const size_t len = str.m_size;
+			const size_t cur = m_vec.size();
+			m_vec.resize(cur + len + 1);
+			std::memcpy(m_vec.data() + cur, str.m_data, len);
+			m_vec[cur + len] = '\0';
+		} else {
+			m_vec.push_back('\0');
+		}
+		return *this;
+	}
+	StreamVectorWriteHelper &writeString(const std::string &str) {
+		return writeString0(fst::make_string_view_pair(str.c_str(), str.size()));
+	}
+	StreamVectorWriteHelper &writeString(const char *str) {
+		return writeString0(fst::make_string_view_pair(str));
+	}
+};
+
+}  // namespace fst

include/fstcpp/fstcpp_variable_info.cpp

@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: 2026 Yu-Sheng Lin <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+// direct include
+#include "fstcpp/fstcpp_variable_info.h"
+// C system headers
+// C++ standard library headers
+#include <algorithm>
+// Other libraries' .h files.
+// Your project's .h files.
+
+namespace fst {
+
+// I don't know why I need to define them here, but StackOverflow says it
+constexpr uint64_t VariableInfo::kCapacityBaseShift;
+constexpr uint64_t VariableInfo::kCapacityBase;
+
+void VariableInfo::reallocate(uint64_t new_size) {
+	// Allocate new memory
+	const uint32_t new_capacity_log2{
+		std::max(
+			static_cast<uint32_t>(platform::clog2(new_size)),
+			static_cast<uint32_t>(kCapacityBaseShift)
+		) -
+		static_cast<uint32_t>(kCapacityBaseShift)
+	};
+	uint8_t *new_data{new uint8_t[kCapacityBase << new_capacity_log2]};
+	// Copy old data to new memory
+	if (m_data != nullptr) {
+		const uint64_t old_size{size()};
+		std::copy_n(m_data, old_size, new_data);
+		delete[] m_data;
+	}
+	m_data = new_data;
+	capacity_log2(new_capacity_log2);
+}
+
+}  // namespace fst

include/fstcpp/fstcpp_variable_info.h

@@ -0,0 +1,830 @@
+// SPDX-FileCopyrightText: 2025-2026 Yu-Sheng Lin <[email protected]>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+#pragma once
+// direct include
+#include "fstcpp/fstcpp.h"
+// C system headers
+// C++ standard library headers
+#if defined(__cplusplus) && __cplusplus >= 202002L
+#	include <bit>
+#endif
+#include <algorithm>
+#include <cstdint>
+#include <limits>
+#include <vector>
+// Other libraries' .h files.
+// Your project's .h files.
+#include "fstcpp/fstcpp_assertion.h"
+#include "fstcpp/fstcpp_stream_write_helper.h"
+
+namespace fst {
+
+namespace platform {
+
+// Can be replaced with std::bit_width when C++20 is available
+inline uint64_t clog2(uint64_t x) {
+	if (x <= 1) return 0;
+#if defined(__cplusplus) && __cplusplus >= 202002L
+	return std::bit_width(x - 1);
+#elif USE_GCC_INTRINSIC
+	return 64 - __builtin_clzll(x - 1);
+// TODO: implement MSVC version
+// #elif USE_MSVC_INTRINSIC
+#else
+	uint64_t r = 0;
+	x -= 1;
+	auto CheckAndShift = [&](uint64_t shift) {
+		if (x >> shift) {
+			r += shift;
+			x >>= shift;
+		}
+	};
+	CheckAndShift(32);
+	CheckAndShift(16);
+	CheckAndShift(8);
+	CheckAndShift(4);
+	CheckAndShift(2);
+	CheckAndShift(1);
+	r += x;
+	return r;
+#endif
+}
+
+inline constexpr uint32_t gen_mask_safe(unsigned width) {
+	// works even when width == 32
+	return ((uint32_t(1) << (width - 1)) << 1) - 1;
+}
+
+inline uint32_t read_field(const uint32_t src, unsigned width, unsigned offset) {
+	const uint32_t mask = gen_mask_safe(width);
+	return (src >> offset) & mask;
+}
+
+inline void write_field(uint32_t &dst, const uint32_t src, unsigned width, unsigned offset) {
+	const uint32_t mask = gen_mask_safe(width) << offset;
+	dst = (dst & ~mask) | ((src << offset) & mask);
+}
+
+}  // namespace platform
+
+class VariableInfo final {
+public:
+	static constexpr uint32_t kMaxSupportedBitwidth = 0x7fffff;
+
+private:
+	static constexpr uint64_t kCapacityBaseShift = 5;
+	static constexpr uint64_t kCapacityBase = 1 << kCapacityBaseShift;
+
+	// To maximize cache efficiency, we compact the data members into 16 bytes.
+	// We make use of bitfields to store multiple pieces of information in a single integer.
+	// But standard does not guarantee the layout of bitfields (the `int x : N;` syntax),
+	// so we use helper functions to access bitfields.
+
+	// begin of data members
+	// 1. 8B pointer (assume 64-bit architecture), its size can be:
+	//   - 0 if m_data is nullptr
+	//   - `kCapacityBase * pow(2, m_capacity_log2)` if m_data is not nullptr
+	//   - If we want more bits, we can use the `kCapacityBaseShift` LSB for other purposes.
+	uint8_t *m_data{nullptr};
+	// 2. 4B size. The same as vector.size(), but we only need 32b.
+	uint32_t m_size{0};
+	// 3. 4B misc. Highly compacted information for max cache efficiency.
+	//    - 6b capacity_log2
+	//    - 2b last_encoding_type
+	//    - 23b bitwidth
+	//    - 1b is_real
+	uint32_t m_misc{0};
+	// end of data members
+
+	// Note: optimization possibility (not implemented)
+	//    - real is always 64-bit double, so we can use 24 bits to encode
+	//      is_real and bitwidth together, and bitwidth = (1<<24-1) is a special
+	//      value to indicate that the variable is a real.
+	//    - Currently bitwidth is whatever you pass to Writer::createVar.
+	//    - Not implemented since nobody needs 16M-bit over 8M-bit bitwidth IMO.
+	static constexpr uint32_t kIsRealWidth = 1;
+	static constexpr uint32_t kBitwidthWidth = 23;
+	static constexpr uint32_t kLastEncodingTypeWidth = 2;
+	static constexpr uint32_t kCapacityLog2Width = 6;
+
+	static constexpr uint32_t kIsRealOffset = 0;
+	static constexpr uint32_t kBitwidthOffset = kIsRealOffset + kIsRealWidth;
+	static constexpr uint32_t kLastEncodingTypeOffset = kBitwidthOffset + kBitwidthWidth;
+	static constexpr uint32_t kCapacityLog2Offset =
+		kLastEncodingTypeOffset + kLastEncodingTypeWidth;
+
+	void capacity_log2(uint32_t capacity_log2_) {
+		platform::write_field(m_misc, capacity_log2_, kCapacityLog2Width, kCapacityLog2Offset);
+	}
+	uint32_t capacity() const {
+		if (m_data == nullptr) {
+			return 0;
+		}
+		return kCapacityBase << platform::read_field(
+				   m_misc, kCapacityLog2Width, kCapacityLog2Offset
+			   );
+	}
+
+	bool need_reallocate(uint64_t new_size) const { return capacity() < new_size; }
+	// This function is cold, so we don't inline it
+	void reallocate(uint64_t new_size);
+
+	void size(uint64_t s) { m_size = static_cast<uint32_t>(s); }
+
+public:
+	uint64_t size() const { return m_size; }
+	uint32_t bitwidth() const {
+		return platform::read_field(m_misc, kBitwidthWidth, kBitwidthOffset);
+	}
+	bool is_real() const { return bool(platform::read_field(m_misc, kIsRealWidth, kIsRealOffset)); }
+	void last_written_encode_type(EncodingType encoding_) {
+		platform::write_field(
+			m_misc,
+			static_cast<uint32_t>(encoding_),
+			kLastEncodingTypeWidth,
+			kLastEncodingTypeOffset
+		);
+	}
+	EncodingType last_written_encode_type() const {
+		return static_cast<EncodingType>(
+			platform::read_field(m_misc, kLastEncodingTypeWidth, kLastEncodingTypeOffset)
+		);
+	}
+	uint64_t last_written_bytes() const;
+
+	template <typename Callable, typename... Args>
+	auto dispatchHelper(Callable &&callable, Args &&...args) const;
+
+	VariableInfo(uint32_t bitwidth_, bool is_real_ = false);
+	~VariableInfo() {
+		if (data_ptr() != nullptr) {
+			// don't delete data directly for better abstraction
+			// we might use the LSB of data in the future as LSB is
+			// always aligned to kCapacityBase
+			delete[] data_ptr();
+		}
+	}
+	VariableInfo(VariableInfo &&rhs) {
+		m_data = rhs.m_data;
+		rhs.m_data = nullptr;
+		m_misc = rhs.m_misc;
+		m_size = rhs.m_size;
+	}
+
+	uint32_t emitValueChange(uint64_t current_time_index, const uint64_t val);
+	uint32_t emitValueChange(
+		uint64_t current_time_index, const uint32_t *val, EncodingType encoding
+	);
+	uint32_t emitValueChange(
+		uint64_t current_time_index, const uint64_t *val, EncodingType encoding
+	);
+
+	void keepOnlyTheLatestValue() {
+		const uint64_t last_written_bytes_ = last_written_bytes();
+		uint8_t *data_ptr_ = data_ptr();
+		std::copy_n(data_ptr_ + size() - last_written_bytes_, last_written_bytes_, data_ptr_);
+		size(last_written_bytes_);
+	}
+	void dumpInitialBits(std::vector<uint8_t> &buf) const;
+	void dumpValueChanges(std::vector<uint8_t> &buf) const;
+
+	// We only need to make this class compatible with vector
+	// delete copy constructor and assignment operator
+	VariableInfo(const VariableInfo &) = delete;
+	VariableInfo &operator=(const VariableInfo &) = delete;
+	VariableInfo &operator=(VariableInfo &&) = delete;
+
+	void resize(size_t new_size) {
+		if (need_reallocate(new_size)) {
+			reallocate(new_size);
+		}
+		size(new_size);
+	}
+	void add_size(size_t added_size) { resize(size() + added_size); }
+	uint8_t *data_ptr() { return m_data; }
+};
+static_assert(
+	sizeof(VariableInfo) != 12,
+	"We don't support 32-bit architecture, comment out the assertions and take the risk"
+);
+static_assert(sizeof(VariableInfo) == 16, "VariableInfo should be small");
+
+namespace detail {
+
+constexpr size_t kEmitTimeIndexAndEncodingSize = sizeof(uint64_t) + sizeof(fst::EncodingType);
+
+// EmitReaderHelper and EmitWriterHelper are very optimized for emit functions
+// User must ensure the pointer points to the valid memory region
+struct EmitReaderHelper {
+	const uint8_t *ptr;
+	EmitReaderHelper(const uint8_t *ptr_) : ptr(ptr_) {}
+
+	std::pair<uint64_t, fst::EncodingType> readTimeIndexAndEncoding() {
+		const auto time_index = read<uint64_t>();
+		const auto encoding = read<fst::EncodingType>();
+		return std::make_pair(time_index, encoding);
+	}
+
+	template <typename T>
+	T read() {
+		const size_t s = sizeof(T);
+		T u;
+		std::memcpy(&u, ptr, s);
+		ptr += s;
+		return u;
+	}
+
+	void skip(size_t count) { ptr += count; }
+
+	template <typename T>
+	T peek(size_t i = 0) {
+		const size_t s = sizeof(T);
+		T u;
+		std::memcpy(&u, ptr + i * s, s);
+		return u;
+	}
+};
+
+struct EmitWriterHelper {
+	uint8_t *ptr;
+
+	EmitWriterHelper(uint8_t *ptr_) : ptr(ptr_) {}
+
+	EmitWriterHelper &writeTimeIndexAndEncoding(uint64_t time_index, fst::EncodingType encoding) {
+		write(time_index);
+		write(encoding);
+		return *this;
+	}
+
+	template <typename T>
+	EmitWriterHelper &write(T u) {
+		const size_t s = sizeof(u);
+		std::memcpy(ptr, &u, s);
+		ptr += s;
+		return *this;
+	}
+
+	template <typename T>
+	EmitWriterHelper &fill(T u, size_t count) {
+		for (size_t i = 0; i < count; ++i) {
+			std::memcpy(ptr, &u, sizeof(u));
+			ptr += sizeof(u);
+		}
+		return *this;
+	}
+
+	template <typename T>
+	EmitWriterHelper &write(T *u, size_t size) {
+		for (size_t i = 0; i < size; ++i) {
+			std::memcpy(ptr, u + i, sizeof(T));
+			ptr += sizeof(T);
+		}
+		return *this;
+	}
+};
+
+class VariableInfoDouble {
+	VariableInfo &info;
+
+public:
+	VariableInfoDouble(VariableInfo &info_) : info(info_) {}
+
+public:
+	inline size_t computeBytesNeeded(EncodingType encoding) const {
+		(void)encoding;
+		return kEmitTimeIndexAndEncodingSize + sizeof(double);
+	}
+
+	inline EmitWriterHelper emitValueChangeCommonPart(
+		uint64_t current_time_index, EncodingType encoding
+	) {
+		if (current_time_index + 1 == 0) {
+			info.resize(0);
+		}
+		// For Double, value is always 8 bytes (sizeof(double) or uint64_t)
+		const size_t added_size = computeBytesNeeded(encoding);
+		const size_t old_size = info.size();
+		info.add_size(added_size);
+
+		EmitWriterHelper wh(info.data_ptr() + old_size);
+		wh.writeTimeIndexAndEncoding(current_time_index, encoding);
+		return wh;
+	}
+
+public:
+	void construct() {
+		const size_t needed = computeBytesNeeded(EncodingType::BINARY);
+		info.resize(needed);
+		EmitWriterHelper wh(info.data_ptr());
+		const double nan_val = std::numeric_limits<double>::quiet_NaN();
+		uint64_t nan_val_u64;
+		std::memcpy(&nan_val_u64, &nan_val, sizeof(nan_val_u64));
+		wh.writeTimeIndexAndEncoding(0, EncodingType::BINARY).write<uint64_t>(nan_val_u64);
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint64_t val) {
+		auto wh = emitValueChangeCommonPart(current_time_index, EncodingType::BINARY);
+		// Note, do not use write<double> here since the uint64_t is
+		// already bit_cast'ed from double
+		wh.write<uint64_t>(val);
+	}
+
+	// Double variables should not use these array-based emitValueChange overloads.
+	// We implement them to satisfy the VairableInfo::dispatchHelper template instantiation.
+	void emitValueChange(uint64_t, const uint32_t *, EncodingType) {
+		FST_FAIL_STRING("emitValueChange(uint32_t*) not supported for Double");
+	}
+	void emitValueChange(uint64_t, const uint64_t *, EncodingType) {
+		FST_FAIL_STRING("emitValueChange(uint64_t*) not supported for Double");
+	}
+
+	void dumpInitialBits(std::vector<uint8_t> &buf) const {
+		FST_DCHECK_GT(info.size(), kEmitTimeIndexAndEncodingSize);
+		EmitReaderHelper rh(info.data_ptr());
+		StreamVectorWriteHelper wh(buf);
+		(void)rh.readTimeIndexAndEncoding();
+		auto v = rh.read<double>();
+		wh.write<double>(v);
+	}
+
+	void dumpValueChanges(std::vector<uint8_t> &buf) const {
+		StreamVectorWriteHelper wh(buf);
+		EmitReaderHelper rh(info.data_ptr());
+		const uint8_t *tail = info.data_ptr() + info.size();
+
+		bool first = true;
+		uint64_t prev_time_index = 0;
+
+		while (true) {
+			if (rh.ptr == tail) break;
+			FST_CHECK_GT(tail, rh.ptr);
+			const auto time_index = rh.read<uint64_t>();
+			const auto enc = rh.read<EncodingType>();
+			const auto num_byte = sizeof(double);
+			if (first) {
+				// Note: [0] is initial value, which is already dumped in dumpInitialBits()
+				first = false;
+			} else {
+				FST_CHECK(enc == EncodingType::BINARY);
+				const uint64_t delta_time_index = time_index - prev_time_index;
+				prev_time_index = time_index;
+				// Double shall be treated as non-binary
+				const bool has_non_binary = true;
+				wh  //
+					.writeLEB128((delta_time_index << 1) | has_non_binary)
+					.write<double>(rh.peek<double>());
+			}
+			rh.skip(num_byte);
+		}
+	}
+};
+
+template <typename T>
+class VariableInfoScalarInt {
+	VariableInfo &info;
+
+public:
+	VariableInfoScalarInt(VariableInfo &info_) : info(info_) {}
+
+public:
+	size_t computeBytesNeeded(EncodingType encoding) const {
+		return kEmitTimeIndexAndEncodingSize + sizeof(T) * bitPerEncodedBit(encoding);
+	}
+
+	// The returning address points to the first byte of the value
+	EmitWriterHelper emitValueChangeCommonPart(uint64_t current_time_index, EncodingType encoding) {
+		if (current_time_index + 1 == 0) {
+			// This is the first value change, we need to remove everything
+			// and then add the new value
+			info.resize(0);
+		}
+		const size_t added_size = computeBytesNeeded(encoding);
+		const size_t old_size = info.size();
+		info.add_size(added_size);
+		EmitWriterHelper wh(info.data_ptr() + old_size);
+		wh.writeTimeIndexAndEncoding(current_time_index, encoding);
+		return wh;
+	}
+
+public:
+	void construct() {
+		info.resize(computeBytesNeeded(EncodingType::VERILOG));
+		EmitWriterHelper wh(info.data_ptr());
+		wh.writeTimeIndexAndEncoding(0, EncodingType::VERILOG).write(T(0)).write(T(-1));
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint64_t val) {
+		auto wh = emitValueChangeCommonPart(current_time_index, EncodingType::BINARY);
+		wh.template write<T>(val);
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint32_t *val, EncodingType encoding) {
+		auto wh = emitValueChangeCommonPart(current_time_index, encoding);
+		for (unsigned i = 0; i < bitPerEncodedBit(encoding); ++i) {
+			// C++17: replace this with if constexpr
+			if (sizeof(T) == 8) {
+				uint64_t v = val[1];  // high bits
+				v <<= 32;
+				v |= val[0];  // low bits
+				wh.template write<uint64_t>(v);
+				val += 2;
+			} else {
+				wh.template write<T>(val[0]);
+				val += 1;
+			}
+		}
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint64_t *val, EncodingType encoding) {
+		auto wh = emitValueChangeCommonPart(current_time_index, encoding);
+		for (unsigned i = 0; i < bitPerEncodedBit(encoding); ++i) {
+			wh.template write<T>(val[i]);
+		}
+	}
+
+	void dumpInitialBits(std::vector<uint8_t> &buf) const {
+		// FST requires initial bits present
+		FST_DCHECK_GT(info.size(), kEmitTimeIndexAndEncodingSize);
+		EmitReaderHelper rh(info.data_ptr());
+		const auto time_index_enc = rh.readTimeIndexAndEncoding();
+		const auto enc = time_index_enc.second;
+		const auto bitwidth = info.bitwidth();
+
+		switch (enc) {
+		case EncodingType::BINARY: {
+			auto v0 = rh.read<T>();
+			for (unsigned i = bitwidth; i-- > 0;) {
+				const char c = ((v0 >> i) & T(1)) ? '1' : '0';
+				buf.push_back(c);
+			}
+			break;
+		}
+
+		case EncodingType::VERILOG: {
+			auto v0 = rh.read<T>();
+			auto v1 = rh.read<T>();
+			for (unsigned i = bitwidth; i-- > 0;) {
+				const T b1 = ((v1 >> i) & T(1));
+				const T b0 = ((v0 >> i) & T(1));
+				const char c = kEncodedBitToCharTable[(b1 << 1) | b0];
+				buf.push_back(c);
+			}
+			break;
+		}
+		// Not supporting VHDL now
+		// LCOV_EXCL_START
+		default:
+		case EncodingType::VHDL: {
+			auto v0 = rh.read<T>();
+			auto v1 = rh.read<T>();
+			auto v2 = rh.read<T>();
+			for (unsigned i = bitwidth; i-- > 0;) {
+				const T b2 = ((v2 >> i) & T(1));
+				const T b1 = ((v1 >> i) & T(1));
+				const T b0 = ((v0 >> i) & T(1));
+				const char c = kEncodedBitToCharTable[(b2 << 2) | (b1 << 1) | b0];
+				buf.push_back(c);
+			}
+			break;
+		}
+		}
+		// LCOV_EXCL_STOP
+	}
+
+	void dumpValueChanges(std::vector<uint8_t> &buf) const {
+		StreamVectorWriteHelper h(buf);
+		EmitReaderHelper rh(info.data_ptr());
+		const uint8_t *tail = info.data_ptr() + info.size();
+		const auto bitwidth = info.bitwidth();
+		bool first = true;
+		uint64_t prev_time_index = 0;
+		if (bitwidth == 1) {
+			while (true) {
+				if (rh.ptr == tail) {
+					break;
+				}
+				FST_DCHECK_GT(tail, rh.ptr);
+				const auto time_index = rh.read<uint64_t>();
+				const auto enc = rh.read<EncodingType>();
+				const auto num_element = bitPerEncodedBit(enc);
+				const auto num_byte = num_element * sizeof(T);
+				if (first) {
+					// Note: [0] is initial value, which is already dumped in dumpInitialBits()
+					first = false;
+				} else {
+					unsigned val = 0;
+					for (unsigned i = 0; i < num_element; ++i) {
+						val |= rh.peek<T>(i);
+					}
+					uint64_t delta_time_index = time_index - prev_time_index;
+					prev_time_index = time_index;
+					switch (val) {
+						// clang-format off
+					case 0: delta_time_index = (delta_time_index<<2) | (0<<1) | 0; break; // '0'
+					case 1: delta_time_index = (delta_time_index<<2) | (1<<1) | 0; break; // '1'
+					case 2: delta_time_index = (delta_time_index<<4) | (0<<1) | 1; break; // 'X'
+					case 3: delta_time_index = (delta_time_index<<4) | (1<<1) | 1; break; // 'Z'
+					// Not supporting VHDL now
+					// LCOV_EXCL_START
+					case 4: delta_time_index = (delta_time_index<<4) | (2<<1) | 1; break; // 'H'
+					case 5: delta_time_index = (delta_time_index<<4) | (3<<1) | 1; break; // 'U'
+					case 6: delta_time_index = (delta_time_index<<4) | (4<<1) | 1; break; // 'W'
+					case 7: delta_time_index = (delta_time_index<<4) | (5<<1) | 1; break; // 'L'
+					case 8: delta_time_index = (delta_time_index<<4) | (6<<1) | 1; break; // '-'
+					case 9: delta_time_index = (delta_time_index<<4) | (7<<1) | 1; break; // '?'
+					default: break;
+					// LCOV_EXCL_STOP
+						// clang-format on
+					}
+					h.writeLEB128(delta_time_index);
+				}
+				rh.skip(num_byte);
+			}
+		} else {
+			while (true) {
+				if (rh.ptr == tail) {
+					break;
+				}
+				FST_CHECK_GT(tail, rh.ptr);
+				const auto time_index = rh.read<uint64_t>();
+				const auto enc = rh.read<EncodingType>();
+				const auto num_element = bitPerEncodedBit(enc);
+				const auto num_byte = num_element * sizeof(T);
+				if (first) {
+					first = false;
+				} else {
+					FST_CHECK(enc == EncodingType::BINARY);  // TODO
+					const bool has_non_binary = enc != EncodingType::BINARY;
+					const uint64_t delta_time_index = time_index - prev_time_index;
+					prev_time_index = time_index;
+					h  //
+						.writeLEB128((delta_time_index << 1) | has_non_binary)
+						.writeUIntPartialForValueChange(rh.peek<T>(), bitwidth);
+				}
+				rh.skip(num_byte);
+			}
+		}
+	}
+};
+
+class VariableInfoLongInt {
+	VariableInfo &info;
+	unsigned num_words() const { return (info.bitwidth() + 63) / 64; }
+
+public:
+	VariableInfoLongInt(VariableInfo &info_) : info(info_) {}
+
+public:
+	size_t computeBytesNeeded(EncodingType encoding) const {
+		return (
+			kEmitTimeIndexAndEncodingSize +
+			num_words() * sizeof(uint64_t) * bitPerEncodedBit(encoding)
+		);
+	}
+
+	EmitWriterHelper emitValueChangeCommonPart(uint64_t current_time_index, EncodingType encoding) {
+		if (current_time_index + 1 == 0) {
+			info.resize(0);
+		}
+		const size_t added_size = computeBytesNeeded(encoding);
+		const size_t old_size = info.size();
+		info.add_size(added_size);
+
+		EmitWriterHelper wh(info.data_ptr() + old_size);
+		wh.writeTimeIndexAndEncoding(current_time_index, encoding);
+		return wh;
+	}
+
+public:
+	void construct() {
+		const size_t nw = num_words();
+		info.resize(computeBytesNeeded(EncodingType::VERILOG));
+		EmitWriterHelper wh(info.data_ptr());
+		wh  //
+			.writeTimeIndexAndEncoding(0, EncodingType::VERILOG)
+			.fill(uint64_t(0), nw)
+			.fill(uint64_t(-1), nw);
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint64_t val) {
+		const unsigned nw = num_words();
+		auto wh = emitValueChangeCommonPart(current_time_index, EncodingType::BINARY);
+		wh.write(val).fill(uint64_t(0), nw - 1);
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint32_t *val, EncodingType encoding) {
+		const unsigned nw32 = (info.bitwidth() + 31) / 32;
+		const unsigned bpb = bitPerEncodedBit(encoding);
+
+		auto wh = emitValueChangeCommonPart(current_time_index, encoding);
+
+		for (unsigned i = 0; i < bpb; ++i) {
+			for (unsigned j = 0; j < nw32 / 2; ++j) {
+				uint64_t v = val[1];  // high bits
+				v <<= 32;
+				v |= val[0];  // low bits
+				wh.write(v);
+				val += 2;
+			}
+			if (nw32 % 2 != 0) {
+				uint64_t v = val[0];
+				wh.write(v);
+				val += 1;
+			}
+		}
+	}
+
+	void emitValueChange(uint64_t current_time_index, const uint64_t *val, EncodingType encoding) {
+		const unsigned nw_encoded = num_words() * bitPerEncodedBit(encoding);
+		auto wh = emitValueChangeCommonPart(current_time_index, encoding);
+		wh.write(val, nw_encoded);
+	}
+
+	void dumpInitialBits(std::vector<uint8_t> &buf) const {
+		FST_DCHECK_GT(info.size(), kEmitTimeIndexAndEncodingSize);
+		EmitReaderHelper rh(info.data_ptr());
+		const auto time_index_enc = rh.readTimeIndexAndEncoding();
+		const auto enc = time_index_enc.second;
+		const unsigned nw = num_words();
+		switch (enc) {
+		case EncodingType::BINARY: {
+			for (unsigned word_index = nw; word_index-- > 0;) {
+				const uint64_t v0 = rh.peek<uint64_t>(word_index);
+				const unsigned num_bit =
+					(word_index * 64 + 64 > info.bitwidth()) ? (info.bitwidth() % 64) : 64;
+				for (unsigned bit_index = num_bit; bit_index-- > 0;) {
+					const char c = ((v0 >> bit_index) & uint64_t(1)) ? '1' : '0';
+					buf.push_back(c);
+				}
+			}
+			break;
+		}
+		case EncodingType::VERILOG: {
+			for (unsigned word_index = nw; word_index-- > 0;) {
+				const uint64_t v0 = rh.peek<uint64_t>(nw * 0 + word_index);
+				const uint64_t v1 = rh.peek<uint64_t>(nw * 1 + word_index);
+				const unsigned num_bit =
+					(word_index * 64 + 64 > info.bitwidth()) ? (info.bitwidth() % 64) : 64;
+				for (unsigned bit_index = num_bit; bit_index-- > 0;) {
+					const bool b0 = ((v0 >> bit_index) & uint64_t(1));
+					const bool b1 = ((v1 >> bit_index) & uint64_t(1));
+					const char c = kEncodedBitToCharTable[(b1 << 1) | b0];
+					buf.push_back(c);
+				}
+			}
+			break;
+		}
+		default:
+		case EncodingType::VHDL: {
+			// Not supporting VHDL now
+			// LCOV_EXCL_START
+			for (unsigned word_index = nw; word_index-- > 0;) {
+				const uint64_t v0 = rh.peek<uint64_t>(nw * 0 + word_index);
+				const uint64_t v1 = rh.peek<uint64_t>(nw * 1 + word_index);
+				const uint64_t v2 = rh.peek<uint64_t>(nw * 2 + word_index);
+				const unsigned num_bit =
+					(word_index * 64 + 64 > info.bitwidth()) ? (info.bitwidth() % 64) : 64;
+				for (unsigned bit_index = num_bit; bit_index-- > 0;) {
+					const bool b0 = ((v0 >> bit_index) & uint64_t(1));
+					const bool b1 = ((v1 >> bit_index) & uint64_t(1));
+					const bool b2 = ((v2 >> bit_index) & uint64_t(1));
+					const char c = kEncodedBitToCharTable[(b2 << 2) | (b1 << 1) | b0];
+					buf.push_back(c);
+				}
+			}
+			break;
+			// LCOV_EXCL_STOP
+		}
+			rh.skip(sizeof(uint64_t) * nw * bitPerEncodedBit(enc));
+		}
+	}
+
+	void dumpValueChanges(std::vector<uint8_t> &buf) const {
+		StreamVectorWriteHelper h(buf);
+		EmitReaderHelper rh(info.data_ptr());
+		const uint8_t *tail = info.data_ptr() + info.size();
+		const unsigned nw = num_words();
+		const unsigned bitwidth = info.bitwidth();  // Local copy for lambda capture/usage if needed
+
+		bool first = true;
+		uint64_t prev_time_index = 0;
+
+		while (true) {
+			if (rh.ptr == tail) break;
+			FST_DCHECK_GT(tail, rh.ptr);
+			const auto time_index = rh.read<uint64_t>();
+			const auto enc = rh.read<EncodingType>();
+			const auto num_element = bitPerEncodedBit(enc);
+			const auto num_byte = num_element * nw * sizeof(uint64_t);
+			if (first) {
+				// Note: [0] is initial value, which is already dumped in dumpInitialBits()
+				first = false;
+			} else {
+				FST_CHECK(enc == EncodingType::BINARY);  // TODO
+				const bool has_non_binary = enc != EncodingType::BINARY;
+				const uint64_t delta_time_index = time_index - prev_time_index;
+				prev_time_index = time_index;
+				h.writeLEB128((delta_time_index << 1) | has_non_binary);
+				if (bitwidth % 64 != 0) {
+					const unsigned remaining = bitwidth % 64;
+					uint64_t hi64 = rh.peek<uint64_t>(nw - 1);
+					// write from nw-1 to 1
+					for (unsigned j = nw - 1; j > 0; --j) {
+						uint64_t lo64 = rh.peek<uint64_t>(j - 1);
+						h.writeUIntBE((hi64 << (64 - remaining)) | (lo64 >> remaining));
+						hi64 = lo64;
+					}
+					// write 0
+					h.writeUIntPartialForValueChange(hi64, remaining);
+				} else {
+					// write from nw-1 to 0
+					for (unsigned j = nw; j-- > 0;) {
+						h.writeUIntBE(rh.peek<uint64_t>(j));
+					}
+				}
+			}
+			rh.skip(num_byte);
+		}
+	}
+};
+
+}  // namespace detail
+
+template <typename Callable, typename... Args>
+auto VariableInfo::dispatchHelper(Callable &&callable, Args &&...args) const {
+	const uint32_t bitwidth = this->bitwidth();
+	const bool is_real = this->is_real();
+	if (!is_real) {
+		// Decision: the branch miss is too expensive for large design, so we only use 3 types of
+		// int
+		if (bitwidth <= 8) {
+			return callable(
+				detail::VariableInfoScalarInt<uint8_t>(const_cast<VariableInfo &>(*this)),
+				std::forward<Args>(args)...
+			);
+		} else if (bitwidth <= 64) {
+			return callable(
+				detail::VariableInfoScalarInt<uint64_t>(const_cast<VariableInfo &>(*this)),
+				std::forward<Args>(args)...
+			);
+		} else {
+			return callable(
+				detail::VariableInfoLongInt(const_cast<VariableInfo &>(*this)),
+				std::forward<Args>(args)...
+			);
+		}
+	}
+	return callable(
+		detail::VariableInfoDouble(const_cast<VariableInfo &>(*this)), std::forward<Args>(args)...
+	);
+}
+
+inline VariableInfo::VariableInfo(uint32_t bitwidth_, bool is_real_) {
+	platform::write_field(m_misc, bitwidth_, kBitwidthWidth, kBitwidthOffset);
+	platform::write_field(m_misc, is_real_, kIsRealWidth, kIsRealOffset);
+	dispatchHelper([](auto obj) { obj.construct(); });
+	last_written_encode_type(EncodingType::BINARY);
+}
+
+inline uint32_t VariableInfo::emitValueChange(uint64_t current_time_index, const uint64_t val) {
+	const uint64_t old_size = size();
+	dispatchHelper([=](auto obj) { obj.emitValueChange(current_time_index, val); });
+	last_written_encode_type(EncodingType::BINARY);
+	return static_cast<uint32_t>(size() - old_size);
+}
+
+inline uint32_t VariableInfo::emitValueChange(
+	uint64_t current_time_index, const uint32_t *val, EncodingType encoding
+) {
+	const uint64_t old_size = size();
+	dispatchHelper([=](auto obj) { obj.emitValueChange(current_time_index, val, encoding); });
+	last_written_encode_type(encoding);
+	return static_cast<uint32_t>(size() - old_size);
+}
+
+inline uint32_t VariableInfo::emitValueChange(
+	uint64_t current_time_index, const uint64_t *val, EncodingType encoding
+) {
+	const uint64_t old_size = size();
+	dispatchHelper([=](auto obj) { obj.emitValueChange(current_time_index, val, encoding); });
+	last_written_encode_type(encoding);
+	return static_cast<uint32_t>(size() - old_size);
+}
+
+inline void VariableInfo::dumpInitialBits(std::vector<uint8_t> &buf) const {
+	dispatchHelper([&](auto obj) { obj.dumpInitialBits(buf); });
+}
+
+inline void VariableInfo::dumpValueChanges(std::vector<uint8_t> &buf) const {
+	dispatchHelper([&](auto obj) { obj.dumpValueChanges(buf); });
+}
+
+inline uint64_t VariableInfo::last_written_bytes() const {
+	const EncodingType encoding = last_written_encode_type();
+	return dispatchHelper([encoding](auto obj) { return obj.computeBytesNeeded(encoding); });
+}
+
+}  // namespace fst

include/fstcpp/fstcpp_writer.cpp

@@ -0,0 +1,887 @@
+// SPDX-FileCopyrightText: 2025-2026 Yu-Sheng Lin <[email protected]>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+// direct include
+#include "fstcpp/fstcpp_writer.h"
+// C system headers
+// C++ standard library headers
+#include <cstdio>
+#include <cstring>
+#include <numeric>
+#include <string>
+#include <unordered_map>
+#include <utility>
+#include <vector>
+// Other libraries' .h files.
+#include <lz4.h>
+#include <zlib.h>
+// Your project's .h files.
+#include "fstcpp/fstcpp.h"
+#include "fstcpp/fstcpp_assertion.h"
+#include "fstcpp/fstcpp_stream_write_helper.h"
+#include "fstcpp/fstcpp_variable_info.h"
+
+// AT(vec, x) is used to access vector at index x, and it will throw exception if out of bound
+// in debug mode, but in release mode, it will not throw exception
+// Usually you should only need AT(vec, x) only at very hot code path.
+#ifndef NDEBUG
+#	define AT(vec, x) (vec.at(x))
+#else
+#	define AT(vec, x) (vec[x])
+#endif
+
+namespace fst {
+
+namespace detail {
+
+void BlackoutData::emitDumpActive(uint64_t current_timestamp, bool enable) {
+	StreamVectorWriteHelper h(m_buffer);
+	h.writeUIntBE<uint8_t>(enable).writeLEB128(current_timestamp - m_previous_timestamp);
+	++m_count;
+}
+
+ValueChangeData::ValueChangeData() {
+	m_variable_infos.reserve(1024);
+}
+
+ValueChangeData::~ValueChangeData() = default;
+
+void ValueChangeData::keepOnlyTheLatestValue() {
+	for (VariableInfo &v : m_variable_infos) {
+		v.keepOnlyTheLatestValue();
+	}
+	FST_CHECK(!m_timestamps.empty());
+	m_timestamps.front() = m_timestamps.back();
+	m_timestamps.resize(1);
+}
+
+}  // namespace detail
+
+void Writer::open(const string_view_pair name) {
+	FST_CHECK(!m_main_fst_file_.is_open());
+	m_main_fst_file_.open(std::string(name.m_data, name.m_size), std::ios::binary);
+	// reserve space for header, we will write it at Close(), append geometry and hierarchy at the
+	// end wave data will be flushed in between
+	m_main_fst_file_.seekp(kSharedBlockHeaderSize + HeaderInfo::total_size, std::ios_base::beg);
+}
+
+void Writer::close() {
+	if (!m_main_fst_file_.is_open()) return;
+	// Finalize header fields
+	if (m_header_.m_date[0] == '\0') {
+		// date is not set yet, set to the current date
+		setDate();
+	}
+	if (m_header_.m_start_time == kInvalidTime) {
+		m_header_.m_start_time = 0;
+	}
+	flushValueChangeData_(m_value_change_data_, m_main_fst_file_);
+	appendGeometry_(m_main_fst_file_);
+	appendHierarchy_(m_main_fst_file_);
+	appendBlackout_(m_main_fst_file_);
+	// Note: write header seek to 0, so we need to do
+	// this after all append operations
+	writeHeader_(m_header_, m_main_fst_file_);
+	m_main_fst_file_.close();
+}
+
+/////////////////////////////////////////
+// Hierarchy / variable API
+/////////////////////////////////////////
+void Writer::setScope(
+	Hierarchy::ScopeType scopetype,
+	const string_view_pair scopename,
+	const string_view_pair scopecomp
+) {
+	FST_CHECK(!m_hierarchy_finalized_);
+	StreamVectorWriteHelper h(m_hierarchy_buffer_);
+	h  //
+		.writeU8Enum(Hierarchy::ScopeControlType::VCD_SCOPE)
+		.writeU8Enum(scopetype)
+		.writeString0(scopename)
+		.writeString0(scopecomp);
+	++m_header_.m_num_scopes;
+}
+
+void Writer::upscope() {
+	FST_CHECK(!m_hierarchy_finalized_);
+	// TODO: shall we inline it?
+	StreamVectorWriteHelper h(m_hierarchy_buffer_);
+	h.writeU8Enum(Hierarchy::ScopeControlType::VCD_UPSCOPE);
+}
+
+Handle Writer::createVar(
+	Hierarchy::VarType vartype,
+	Hierarchy::VarDirection vardir,
+	uint32_t bitwidth,
+	const string_view_pair name,
+	Handle alias_handle
+) {
+	FST_CHECK(!m_hierarchy_finalized_);
+	FST_CHECK_LE(bitwidth, VariableInfo::kMaxSupportedBitwidth);
+	// write hierarchy entry: type, direction, name, length, alias
+	StreamVectorWriteHelper h(m_hierarchy_buffer_);
+
+	// determine real/string handling like original C implementation
+	bool is_real{false};
+	switch (vartype) {
+	case Hierarchy::VarType::VCD_REAL:
+	case Hierarchy::VarType::VCD_REAL_PARAMETER:
+	case Hierarchy::VarType::VCD_REALTIME:
+	case Hierarchy::VarType::SV_SHORTREAL:
+		is_real = true;
+		bitwidth = 8;  // recast to double size
+		break;
+	case Hierarchy::VarType::GEN_STRING:
+		bitwidth = 0;
+		break;
+	default:
+		break;
+	}
+	if (alias_handle > m_header_.m_num_handles) {
+		// sanitize
+		alias_handle = 0;
+	}
+	const bool is_alias{alias_handle != 0};
+	// This counter is incremented whether alias || non-alias
+	++m_header_.m_num_vars;
+	if (!is_alias) {
+		// This counter is incremented only for non-alias variables
+		++m_header_.m_num_handles;
+		alias_handle = static_cast<uint32_t>(m_header_.m_num_handles);
+	}
+
+	h  //
+		.writeU8Enum(vartype)
+		.writeU8Enum(vardir)
+		.writeString0(name)
+		.writeLEB128(bitwidth)
+		.writeLEB128(is_alias ? alias_handle : 0);
+
+	// If alias_handle == 0, we must allocate geom/valpos/curval entries and create a new handle
+	if (!is_alias) {
+		StreamVectorWriteHelper g(m_geometry_buffer_);
+		// I don't know why the original C implementation encode bitwidth again
+		const uint32_t geom_len{(bitwidth == 0 ? uint32_t(-1) : is_real ? uint32_t(0) : bitwidth)};
+		g.writeLEB128(geom_len);
+		m_value_change_data_.m_variable_infos.emplace_back(bitwidth, is_real);
+	}
+
+	return alias_handle;
+}
+
+// TODO
+// LCOV_EXCL_START
+// Handle Writer::createVar2(
+// 	Hierarchy::VarType vartype,
+// 	Hierarchy::VarDirection vardir,
+// 	uint32_t bitwidth,
+// 	const string_view_pair name,
+// 	Handle alias_handle,
+// 	const string_view_pair type,
+// 	Hierarchy::SupplementalVarType svt,
+// 	Hierarchy::SupplementalDataType sdt
+// ) {
+// 	FST_CHECK(!m_hierarchy_finalized_);
+// 	(void)vartype;
+// 	(void)vardir;
+// 	(void)bitwidth;
+// 	(void)name;
+// 	(void)alias_handle;
+// 	(void)type;
+// 	(void)svt;
+// 	(void)sdt;
+// 	FST_FAIL_STRING("TODO");
+// 	return 0;
+// }
+// LCOV_EXCL_STOP
+
+/////////////////////////////////////////
+// Waveform API
+/////////////////////////////////////////
+void Writer::emitTimeChange(uint64_t tim) {
+	finalizeHierarchy_();
+
+	if (m_value_change_data_usage_ > m_value_change_data_flush_threshold_ || m_flush_pending_) {
+		flushValueChangeData_(m_value_change_data_, m_main_fst_file_);
+	}
+
+	// Update header
+	m_header_.m_start_time = std::min(m_header_.m_start_time, tim);
+	m_header_.m_end_time = tim;
+
+	if (m_value_change_data_.m_timestamps.empty() ||
+		m_value_change_data_.m_timestamps.back() != tim) {
+		m_value_change_data_.m_timestamps.push_back(tim);
+	}
+}
+
+// TODO
+// void Writer::emitDumpActive(bool enable) {
+// 	// TODO: this API is not fully understood, need to check
+// 	FST_CHECK(!m_value_change_data_.m_timestamps.empty());
+// 	m_blackout_data_.emitDumpActive(m_value_change_data_.m_timestamps.back(), enable);
+// }
+
+template <typename... T>
+void Writer::emitValueChangeHelper_(Handle handle, T &&...val) {
+	// Let data prefetch go first
+	VariableInfo &var_info = AT(m_value_change_data_.m_variable_infos, handle - 1);
+#if defined(__GNUC__) || defined(__clang__)
+	__builtin_prefetch(var_info.data_ptr() + var_info.size() - 1, 1, 0);
+#endif
+
+	finalizeHierarchy_();
+
+	// Original implementation: virtual, but vtable is too costly, we switch to if-else static
+	// dispatch
+	m_value_change_data_usage_ += var_info.emitValueChange(
+		m_value_change_data_.m_timestamps.size() - 1, std::forward<T>(val)...
+	);
+}
+
+void Writer::emitValueChange(Handle handle, const uint32_t *val, EncodingType encoding) {
+	emitValueChangeHelper_(handle, val, encoding);
+}
+
+void Writer::emitValueChange(Handle handle, const uint64_t *val, EncodingType encoding) {
+	emitValueChangeHelper_(handle, val, encoding);
+}
+
+void Writer::emitValueChange(Handle handle, uint64_t val) {
+	emitValueChangeHelper_(handle, val);
+}
+
+void Writer::emitValueChange(Handle handle, const char *val) {
+	finalizeHierarchy_();
+	VariableInfo &var_info = AT(m_value_change_data_.m_variable_infos, handle - 1);
+
+	// For double handles, const char* is interpreted as a double* (8B)
+	// This double shall be written out as raw IEEE 754 double
+	// So we just reinterpret_cast it to uint64_t and emit it
+	if (var_info.is_real()) {
+		emitValueChange(handle, *reinterpret_cast<const uint64_t *>(val));
+		return;
+	}
+
+	// For normal integer handles, const char* is "01xz..." (1B per bit)
+	const uint32_t bitwidth{var_info.bitwidth()};
+	FST_DCHECK_NE(bitwidth, 0);
+
+	val += bitwidth;
+	const unsigned num_words{(bitwidth + 63) / 64};
+	m_packed_value_buffer_.assign(num_words, 0);
+	for (unsigned i = 0; i < num_words; ++i) {
+		const char *start{val - std::min((i + 1) * 64, bitwidth)};
+		const char *end{val - 64 * i};
+		m_packed_value_buffer_[i] = 0;
+		for (const char *p = start; p < end; ++p) {
+			// No checking for invalid characters, follow original C implementation
+			m_packed_value_buffer_[i] <<= 1;
+			m_packed_value_buffer_[i] |= static_cast<uint64_t>(*p - '0');
+		}
+	}
+
+	if (bitwidth <= 64) {
+		emitValueChange(handle, m_packed_value_buffer_.front());
+	} else {
+		emitValueChange(handle, m_packed_value_buffer_.data(), EncodingType::BINARY);
+	}
+}
+
+/////////////////////////////////////////
+// File flushing functions
+/////////////////////////////////////////
+void Writer::writeHeader_(const Header &header, std::ostream &os) {
+	StreamWriteHelper h(os);
+	static char kDefaultWriterName[sizeof(header.m_writer)] = "fstcppWriter";
+	const char *writer_name = header.m_writer[0] == '\0' ? kDefaultWriterName : header.m_writer;
+
+	// Actual write
+	h  //
+		.seek(std::streamoff(0), std::ios_base::beg)
+		.writeBlockHeader(BlockType::HEADER, HeaderInfo::total_size)
+		.writeUInt(header.m_start_time)
+		.writeUInt(header.m_end_time)
+		.writeFloat(HeaderInfo::kEndianessMagicIdentifier)
+		.writeUInt(header.m_writer_memory_use)
+		.writeUInt(header.m_num_scopes)
+		.writeUInt(header.m_num_vars)
+		.writeUInt(header.m_num_handles)
+		.writeUInt(header.m_num_value_change_data_blocks)
+		.writeUInt(header.m_timescale)
+		.write(writer_name, sizeof(header.m_writer))
+		.write(header.m_date, sizeof(header.m_date))
+		.fill('\0', HeaderInfo::Size::reserved)
+		.writeUInt(static_cast<uint8_t>(header.m_filetype))
+		.writeUInt(header.m_timezero);
+
+	FST_DCHECK_EQ(os.tellp(), HeaderInfo::total_size + kSharedBlockHeaderSize);
+}
+
+namespace {  // compression helpers
+
+// These API pass compressed_data to avoid frequent reallocations
+void compressUsingLz4(
+	const std::vector<uint8_t> &uncompressed_data, std::vector<uint8_t> &compressed_data
+) {
+	const int uncompressed_size = uncompressed_data.size();
+	const int compressed_bound = LZ4_compressBound(uncompressed_size);
+	compressed_data.resize(compressed_bound);
+	const int compressed_size = LZ4_compress_default(
+		reinterpret_cast<const char *>(uncompressed_data.data()),
+		reinterpret_cast<char *>(compressed_data.data()),
+		uncompressed_size,
+		compressed_bound
+	);
+	compressed_data.resize(compressed_size);
+}
+
+void compressUsingZlib(
+	const std::vector<uint8_t> &uncompressed_data, std::vector<uint8_t> &compressed_data, int level
+) {
+	// compress using zlib
+	const uLong uncompressed_size = uncompressed_data.size();
+	uLongf compressed_bound = compressBound(uncompressed_size);
+	compressed_data.resize(compressed_bound);
+	const auto z_status = compress2(
+		reinterpret_cast<Bytef *>(compressed_data.data()),
+		&compressed_bound,
+		reinterpret_cast<const Bytef *>(uncompressed_data.data()),
+		uncompressed_size,
+		level
+	);
+	FST_CHECK_EQ(z_status, Z_OK);
+	compressed_data.resize(compressed_bound);
+}
+
+std::pair<const uint8_t *, size_t> selectSmaller(
+	const std::vector<uint8_t> &compressed_data, const std::vector<uint8_t> &uncompressed_data
+) {
+	std::pair<const uint8_t *, size_t> ret;
+	if (compressed_data.size() < uncompressed_data.size()) {
+		ret.first = compressed_data.data();
+		ret.second = compressed_data.size();
+	} else {
+		ret.first = uncompressed_data.data();
+		ret.second = uncompressed_data.size();
+	}
+	return ret;
+}
+
+}  // namespace
+
+// AppendHierarchy_ and AppendGeometry_ shares a very similar structure
+// But they are slightly different in the original C implementation...
+void Writer::appendGeometry_(std::ostream &os) {
+	if (m_geometry_buffer_.empty()) {
+		// skip the geometry block if there is no data
+		return;
+	}
+	std::vector<uint8_t> geometry_buffer_compressed_{};
+	compressUsingZlib(m_geometry_buffer_, geometry_buffer_compressed_, 9);
+	// TODO: Replace with structured binding in C++17
+	const std::pair<const uint8_t *, size_t> selected_pair =
+		selectSmaller(geometry_buffer_compressed_, m_geometry_buffer_);
+	const uint8_t *selected_data = selected_pair.first;
+	const size_t selected_size = selected_pair.second;
+
+	StreamWriteHelper h(os);
+	h  //
+		.seek(0, std::ios_base::end)
+		// 16 is for the uncompressed_size and header_.num_handles
+		.writeBlockHeader(BlockType::GEOMETRY, selected_size + 16)
+		.writeUInt<uint64_t>(m_geometry_buffer_.size())
+		// I don't know why the original C implementation write num_handles again here
+		// but we have to follow it
+		.writeUInt(m_header_.m_num_handles)
+		.write(selected_data, selected_size);
+}
+
+void Writer::appendHierarchy_(std::ostream &os) {
+	if (m_hierarchy_buffer_.empty()) {
+		// skip the hierarchy block if there is no data
+		return;
+	}
+
+	// compress hierarchy_buffer_ using LZ4.
+	const int compressed_bound{LZ4_compressBound(m_hierarchy_buffer_.size())};
+	std::vector<uint8_t> hierarchy_buffer_compressed_(compressed_bound);
+	const int compressed_size{LZ4_compress_default(
+		reinterpret_cast<const char *>(m_hierarchy_buffer_.data()),
+		reinterpret_cast<char *>(hierarchy_buffer_compressed_.data()),
+		m_hierarchy_buffer_.size(),
+		compressed_bound
+	)};
+
+	StreamWriteHelper h(os);
+	h  //
+		.seek(0, std::ios_base::end)
+		// +16 is for the uncompressed_size
+		.writeBlockHeader(BlockType::HIERARCHY_LZ4_COMPRESSED, compressed_size + 8)
+		.writeUInt<uint64_t>(m_hierarchy_buffer_.size())
+		.write(hierarchy_buffer_compressed_.data(), compressed_size);
+}
+
+void Writer::appendBlackout_(std::ostream &os) {
+	if (m_blackout_data_.m_count == 0) {
+		// skip the blackout block if there is no data
+		return;
+	}
+	const std::vector<uint8_t> &blackout_data = m_blackout_data_.m_buffer;
+	const std::streampos begin_of_blackout_block = os.tellp();
+	StreamWriteHelper h(os);
+	h  //
+	   // skip the block header
+		.seek(kSharedBlockHeaderSize, std::ios_base::cur)
+		// Note: we cannot know the size beforehand since this length is LEB128 encoded
+		.writeLEB128(blackout_data.size())
+		.write(blackout_data.data(), blackout_data.size());
+
+	const std::streamoff size_of_blackout_block = os.tellp() - begin_of_blackout_block;
+	h  //
+	   // go back to the beginning of the block
+		.seek(begin_of_blackout_block, std::ios_base::beg)
+		// and write the block header
+		.writeBlockHeader(
+			BlockType::BLACKOUT,
+			static_cast<uint64_t>(size_of_blackout_block - kSharedBlockHeaderSize)
+		);
+}
+
+void detail::ValueChangeData::writeInitialBits(std::vector<uint8_t> &os) const {
+	// Build vc_bits_data by concatenating each variable's initial bits as documented.
+	// We will not compress for now; just generate the raw bytes and print summary to stdout.
+	for (size_t i{0}; i < m_variable_infos.size(); ++i) {
+		const VariableInfo &vref = m_variable_infos[i];
+		vref.dumpInitialBits(os);
+	}
+}
+
+std::vector<std::vector<uint8_t>> detail::ValueChangeData::computeWaveData() const {
+	const size_t N{m_variable_infos.size()};
+	std::vector<std::vector<uint8_t>> data(N);
+	for (size_t i{0}; i < N; ++i) {
+		m_variable_infos[i].dumpValueChanges(data[i]);
+	}
+	return data;
+}
+
+std::vector<int64_t> detail::ValueChangeData::uniquifyWaveData(
+	std::vector<std::vector<uint8_t>> &data
+) {
+	// After this function, positions[i] is:
+	//  - = 0: If data[i] is unique (first occurrence)
+	//  - < 0: If data[i] is a duplicate, encoded as -(original_index + 1)
+	std::vector<int64_t> positions(data.size(), 0);
+	struct MyHash {
+		size_t operator()(const std::vector<uint8_t> *vec) const {
+			size_t seed = 0;
+			for (auto v : *vec) {
+				seed ^= v + 0x9e3779b9 + (seed << 6) + (seed >> 2);
+			}
+			return seed;
+		}
+	};
+	struct MyEqual {
+		bool operator()(const std::vector<uint8_t> *a, const std::vector<uint8_t> *b) const {
+			return *a == *b;
+		}
+	};
+	std::unordered_map<const std::vector<uint8_t> *, int64_t, MyHash, MyEqual> data_map;
+	for (size_t i = 0; i < data.size(); ++i) {
+		if (data[i].empty()) {
+			continue;
+		}
+		// insert vec->i to data_map if not exists
+		auto p = data_map.emplace(&data[i], static_cast<int64_t>(i));
+		auto it = p.first;
+		const bool inserted{p.second};
+
+		if (!inserted) {
+			// duplicated wave data found
+			positions[i] = -(it->second + 1);
+			// clear data to save memory
+			data[i].clear();
+		}
+	}
+	return positions;
+}
+
+uint64_t detail::ValueChangeData::encodePositionsAndwriteUniqueWaveData(
+	std::ostream &os,
+	const std::vector<std::vector<uint8_t>> &data,
+	std::vector<int64_t> &positions,
+	WriterPackType pack_type
+) {
+	// After this function, positions[i] is:
+	//  - = 0: If variable i has no wave data
+	//  - < 0: The negative value from flushValueChangeData_ValueChanges_UniquifyWaveData_,
+	//  unchanged
+	//  - > 0: The size (in bytes) of the wave data block for *previous* variable,
+	//         the previous block size of the first block is 1 (required by FST spec).
+	StreamWriteHelper h(os);
+	int64_t previous_size = 1;
+	uint64_t written_count = 0;
+	std::vector<uint8_t> compressed_data;
+	for (size_t i = 0; i < positions.size(); ++i) {
+		if (positions[i] < 0) {
+			// duplicate (negative index), do nothing
+		} else if (data[i].empty()) {
+			// no change (empty data), positions[i] remains 0
+		} else {
+			// try to compress
+			const uint8_t *selected_data;
+			size_t selected_size;
+			if (pack_type == WriterPackType::NO_COMPRESSION || data[i].size() <= 32) {
+				selected_data = data[i].data();
+				selected_size = data[i].size();
+			} else {
+				compressUsingLz4(data[i], compressed_data);
+				const std::pair<const uint8_t *, size_t> selected_pair =
+					selectSmaller(compressed_data, data[i]);
+				selected_data = selected_pair.first;
+				selected_size = selected_pair.second;
+			}
+			const bool is_compressed = selected_data != data[i].data();
+
+			// non-empty unique data, write it
+			written_count++;
+			std::streamoff bytes_written;
+			h  //
+				.beginOffset(bytes_written)
+				// FST spec: 0 means no compression, >0 for the size of the original data
+				.writeLEB128(is_compressed ? data[i].size() : 0)
+				.write(selected_data, selected_size)
+				.endOffset(&bytes_written);
+			positions[i] = previous_size;
+			previous_size = bytes_written;
+		}
+	}
+	return written_count;
+}
+
+void detail::ValueChangeData::writeEncodedPositions(
+	const std::vector<int64_t> &encoded_positions, std::ostream &os
+) {
+	// Encode positions with the specified run/varint rules into a varint buffer.
+	StreamWriteHelper h(os);
+
+	size_t i = 0;
+	const size_t n = encoded_positions.size();
+
+	// arbitrary positive value for prev_negative
+	// so that first negative is always != prev_negative
+	int64_t prev_negative = 1;
+
+	// Please refer to the comments in
+	// flushValueChangeData_ValueChanges_EncodePositionsAndwriteWaveData_() for the encoding rules
+	// of positions.
+	while (i < n) {
+		if (encoded_positions[i] == 0) {
+			// zero: handle zero run-length
+			size_t run = 0;
+			while (i < n && encoded_positions[i] == 0) {
+				++run;
+				++i;
+			}
+			// encode as signed (run << 1) | 0 and write as signed LEB128
+			h.writeLEB128(run << 1);
+		} else {
+			// non-zero
+			int64_t value_to_encode = 0;
+			int64_t cur = encoded_positions[i];
+			if (cur < 0) {
+				if (cur == prev_negative) {
+					value_to_encode = 0;
+				} else {
+					value_to_encode = cur;
+					prev_negative = cur;
+				}
+			} else {
+				value_to_encode = cur;
+			}
+
+			// encode as signed (value << 1) | 1 and write as signed LEB128
+			h.writeLEB128Signed((value_to_encode << 1) | 1);
+
+			++i;
+		}
+	}
+}
+
+void detail::ValueChangeData::writeTimestamps(std::vector<uint8_t> &os) const {
+	// Build LEB128-encoded delta stream (first delta is timestamp[0] - 0)
+	StreamVectorWriteHelper h(os);
+	uint64_t prev{0};
+	for (size_t i{0}; i < m_timestamps.size(); ++i) {
+		const uint64_t cur{m_timestamps[i]};
+		const uint64_t delta{cur - prev};
+		h.writeLEB128(delta);
+		prev = cur;
+	}
+}
+
+void Writer::flushValueChangeDataConstPart_(
+	const detail::ValueChangeData &vcd, std::ostream &os, WriterPackType pack_type
+) {
+	// 0. setup
+	StreamWriteHelper h(os);
+
+	// 1. write Block Header & Global Fields (start/end/mem_req placeholder)
+	// FST_BL_VCDATA_DYN_ALIAS2 (8) maps to WaveDataVersion3 in fst_file.h
+	// The positions we cannot fill in yet
+	const auto p_tmp1 = [&]() {
+		std::streamoff start_pos, memory_usage_pos;
+		h                            //
+			.beginOffset(start_pos)  // record start position
+			.writeBlockHeader(BlockType::WAVE_DATA_VERSION3, 0 /* Length placeholder 0 */)
+			.writeUInt(vcd.m_timestamps.front())
+			.writeUInt(vcd.m_timestamps.back())
+			.beginOffset(memory_usage_pos)  // record memory usage position
+			.writeUInt<uint64_t>(0);        // placeholder for memory usage
+		return std::make_pair(start_pos, memory_usage_pos);
+	}();
+	const std::streamoff start_pos{p_tmp1.first};
+	const std::streamoff memory_usage_pos{p_tmp1.second};
+
+	// 2. Bits Section
+	{
+		std::vector<uint8_t> bits_data;
+		vcd.writeInitialBits(bits_data);
+		std::vector<uint8_t> bits_data_compressed;
+		const uint8_t *selected_data;
+		size_t selected_size;
+		if (pack_type == WriterPackType::NO_COMPRESSION || bits_data.size() < 32) {
+			selected_data = bits_data.data();
+			selected_size = bits_data.size();
+		} else {
+			compressUsingZlib(bits_data, bits_data_compressed, 4);
+			const std::pair<const uint8_t *, size_t> selected_pair =
+				selectSmaller(bits_data_compressed, bits_data);
+			selected_data = selected_pair.first;
+			selected_size = selected_pair.second;
+		}
+
+		h                                              //
+			.writeLEB128(bits_data.size())             // uncompressed length
+			.writeLEB128(selected_size)                // compressed length
+			.writeLEB128(vcd.m_variable_infos.size())  // bits count
+			.write(selected_data, selected_size);
+	}
+
+	// 3. Waves Section
+	// Note: We need positions for the next section
+	const auto p_tmp2 = [&, pack_type]() {
+		std::vector<std::vector<uint8_t>> wave_data{vcd.computeWaveData()};
+		const size_t memory_usage{std::accumulate(
+			wave_data.begin(),
+			wave_data.end(),
+			size_t(0),
+			[](size_t a, const std::vector<uint8_t> &b) { return a + b.size(); }
+		)};
+		std::vector<int64_t> positions{vcd.uniquifyWaveData(wave_data)};
+		h
+			// Note: this is not a typo, I expect we shall write count here.
+			// but the spec indeed write vcd.variable_infos.size(),
+			// which is repeated 1 times in header block, 2 times in valuechange block
+			.writeLEB128(vcd.m_variable_infos.size())
+			.writeUInt(uint8_t('4'));
+		const uint64_t count{detail::ValueChangeData::encodePositionsAndwriteUniqueWaveData(
+			os, wave_data, positions, pack_type
+		)};
+		(void)count;
+		return std::make_pair(positions, memory_usage);
+	}();
+	const std::vector<int64_t> positions{p_tmp2.first};
+	const size_t memory_usage{p_tmp2.second};
+
+	// 4. Position Section
+	{
+		const std::streampos pos_begin{os.tellp()};
+		vcd.writeEncodedPositions(positions, os);
+		const uint64_t pos_size{static_cast<uint64_t>(os.tellp() - pos_begin)};
+		h.writeUInt(pos_size);  // Length comes AFTER data for positions
+	}
+
+	// 5. Time Section
+	{
+		std::vector<uint8_t> time_data;
+		vcd.writeTimestamps(time_data);
+		std::vector<uint8_t> time_data_compressed;
+		const uint8_t *selected_data;
+		size_t selected_size;
+		if (pack_type == WriterPackType::NO_COMPRESSION) {
+			selected_data = time_data.data();
+			selected_size = time_data.size();
+		} else {
+			compressUsingZlib(time_data, time_data_compressed, 9);
+			const std::pair<const uint8_t *, size_t> selected_pair =
+				selectSmaller(time_data_compressed, time_data);
+			selected_data = selected_pair.first;
+			selected_size = selected_pair.second;
+		}
+		h                                                   //
+			.write(selected_data, selected_size)            // time data
+			.writeUInt(time_data.size())                    // uncompressed len
+			.writeUInt(selected_size)                       // compressed len
+			.writeUInt(uint64_t(vcd.m_timestamps.size()));  // count
+	}
+
+	// 6. Patch Block Length and Memory Required
+	std::streamoff end_pos{0};
+	h  //
+		.beginOffset(end_pos)
+		// Patch Block Length (after 1 byte Type)
+		.seek(start_pos + std::streamoff(1), std::ios_base::beg)
+		.writeUInt<uint64_t>(static_cast<uint64_t>(end_pos - start_pos - 1))
+		// Patch Memory Required
+		.seek(memory_usage_pos, std::ios_base::beg)
+		.writeUInt<uint64_t>(static_cast<uint64_t>(memory_usage))
+		// Restore position to end
+		.seek(end_pos, std::ios_base::beg);
+}
+
+namespace {  // Helper functions for createEnumTable
+
+void appendEscToString(const string_view_pair in, std::string &out) {
+	for (size_t i{0}; i < in.m_size; ++i) {
+		const char c{in.m_data[i]};
+		switch (c) {
+			// clang-format off
+		case '\a': { out += "\\a"; break; }
+		case '\b': { out += "\\b"; break; }
+		case '\f': { out += "\\f"; break; }
+		case '\n': { out += "\\n"; break; }
+		case '\r': { out += "\\r"; break; }
+		case '\t': { out += "\\t"; break; }
+		case '\v': { out += "\\v"; break; }
+		case '\'': { out += "\\'"; break; }
+		case '\"': { out += "\\\""; break; }
+		case '\\': { out += "\\\\"; break; }
+		case '?': { out += "\\?"; break; }
+		// clang-format on
+		default: {
+			if (c > ' ' && c <= '~') {
+				out += c;
+			} else {
+				unsigned char val = static_cast<unsigned char>(c);
+				out += '\\';
+				out += (val / 64) + '0';
+				val &= 63;
+				out += (val / 8) + '0';
+				val &= 7;
+				out += val + '0';
+			}
+			break;
+		}
+		}
+	}
+}
+
+}  // namespace
+
+void Writer::setAttrBegin(
+	Hierarchy::AttrType attrtype,
+	Hierarchy::AttrSubType subtype,
+	const string_view_pair attrname,
+	uint64_t arg
+) {
+	FST_CHECK(!m_hierarchy_finalized_);
+
+	StreamVectorWriteHelper h(m_hierarchy_buffer_);
+
+	if (attrtype > Hierarchy::AttrType::MAX) {
+		attrtype = Hierarchy::AttrType::MISC;
+		subtype = Hierarchy::AttrSubType::MISC_UNKNOWN;
+	}
+
+	switch (attrtype) {
+		// clang-format off
+	case Hierarchy::AttrType::ARRAY:
+		if (
+			subtype < Hierarchy::AttrSubType::ARRAY_NONE ||
+			subtype > Hierarchy::AttrSubType::ARRAY_SPARSE
+		) {
+			subtype = Hierarchy::AttrSubType::ARRAY_NONE;
+		}
+		break;
+	case Hierarchy::AttrType::ENUM:
+		if (
+			subtype < Hierarchy::AttrSubType::ENUM_SV_INTEGER ||
+			subtype > Hierarchy::AttrSubType::ENUM_TIME
+		) {
+			subtype = Hierarchy::AttrSubType::ENUM_SV_INTEGER;
+		}
+		break;
+	case Hierarchy::AttrType::PACK:
+		if (
+			subtype < Hierarchy::AttrSubType::PACK_NONE ||
+			subtype > Hierarchy::AttrSubType::PACK_SPARSE
+		) {
+			subtype = Hierarchy::AttrSubType::PACK_NONE;
+		}
+		break;
+	// clang-format on
+	case Hierarchy::AttrType::MISC:
+	default:
+		break;
+	}
+
+	h  //
+		.writeU8Enum(Hierarchy::ScopeControlType::GEN_ATTR_BEGIN)
+		.writeU8Enum(attrtype)
+		.writeU8Enum(subtype)
+		.writeString0(attrname)
+		.writeLEB128(arg);
+}
+
+EnumHandle Writer::createEnumTable(
+	const string_view_pair name,
+	uint32_t min_valbits,
+	const std::vector<std::pair<string_view_pair, string_view_pair>> &literal_val_arr
+) {
+	EnumHandle handle{0};
+
+	if (name.m_size == 0 || literal_val_arr.empty()) {
+		return handle;
+	}
+
+	std::string attr_str;
+	attr_str.reserve(256);
+	attr_str.append(name.m_data, name.m_size);
+	attr_str += ' ';
+	attr_str += std::to_string(literal_val_arr.size());
+	attr_str += ' ';
+
+	for (const auto &p : literal_val_arr) {
+		const string_view_pair literal{p.first};
+		// literal
+		appendEscToString(literal, attr_str);
+		attr_str += ' ';
+	}
+	for (const auto &p : literal_val_arr) {
+		const string_view_pair val{p.second};
+		// val (with padding)
+		if (min_valbits > 0 && val.m_size < min_valbits) {
+			attr_str.insert(attr_str.end(), min_valbits - val.m_size, '0');
+		}
+		appendEscToString(val, attr_str);
+		attr_str += ' ';
+	}
+	attr_str.pop_back();  // remove last space
+
+	handle = ++m_enum_count_;
+	setAttrBegin(
+		Hierarchy::AttrType::MISC,
+		Hierarchy::AttrSubType::MISC_ENUMTABLE,
+		make_string_view_pair(attr_str.c_str(), attr_str.size()),
+		handle
+	);
+
+	return handle;
+}
+
+}  // namespace fst

include/fstcpp/fstcpp_writer.h

@@ -0,0 +1,269 @@
+// SPDX-FileCopyrightText: 2025-2026 Yu-Sheng Lin <[email protected]>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <[email protected]>
+// SPDX-License-Identifier: MIT
+// Project: libfstwriter
+// Website: https://github.com/gtkwave/libfstwriter
+#pragma once
+// direct include
+#include "fstcpp/fstcpp.h"
+// C system headers
+// C++ standard library headers
+#include <algorithm>
+#include <cstdint>
+#include <ctime>
+#include <fstream>
+#include <vector>
+#if __cplusplus >= 201703L
+#	include <string_view>
+#endif
+// Other libraries' .h files.
+// Your project's .h files.
+#include "fstcpp/fstcpp_assertion.h"
+#include "fstcpp/fstcpp_variable_info.h"
+
+namespace fst {
+
+class Writer;
+
+namespace detail {
+
+// We define BlackoutData here for better code inlining, no forward declaration
+// Blackout is not implemented yet
+struct BlackoutData {
+	std::vector<uint8_t> m_buffer{};
+	uint64_t m_previous_timestamp{0};
+	uint64_t m_count{0};
+
+	void emitDumpActive(uint64_t current_timestamp, bool enable);
+};
+
+// We define ValueChangeData here for better code inlining, no forward declaration
+struct ValueChangeData {
+	std::vector<VariableInfo> m_variable_infos{};
+	std::vector<uint64_t> m_timestamps{};
+
+	ValueChangeData();
+	~ValueChangeData();
+
+	void writeInitialBits(std::vector<uint8_t> &os) const;
+	std::vector<std::vector<uint8_t>> computeWaveData() const;
+	static std::vector<int64_t> uniquifyWaveData(std::vector<std::vector<uint8_t>> &data);
+	static uint64_t encodePositionsAndwriteUniqueWaveData(
+		std::ostream &os,
+		const std::vector<std::vector<uint8_t>> &unique_data,
+		std::vector<int64_t> &positions,
+		WriterPackType pack_type
+	);
+	static void writeEncodedPositions(
+		const std::vector<int64_t> &encoded_positions, std::ostream &os
+	);
+	void writeTimestamps(std::vector<uint8_t> &os) const;
+	void keepOnlyTheLatestValue();
+};
+
+}  // namespace detail
+
+class Writer {
+	friend class WriterTest;
+
+private:
+	// File/memory buffers
+	// 1. For hierarchy and geometry, we do not keep the data structure, instead we just
+	//    serialize them into buffers, and compress+write them at the end of file.
+	// 2. For header, we keep the data structure in memory since it is quite small
+	// 3. For wave data, we keep a complicated data structure in memory,
+	//    and flush them to file when necessary
+	// 4. For blackout data, it is not implemented yet
+	std::ofstream m_main_fst_file_{};
+	std::vector<uint8_t> m_hierarchy_buffer_{};
+	std::vector<uint8_t> m_geometry_buffer_{};
+	// Temporary buffer for packing bit strings into words
+	// Only used in emitValueChange(Handle, const char*)
+	std::vector<uint64_t> m_packed_value_buffer_{};
+	Header m_header_{};
+	detail::BlackoutData m_blackout_data_{};  // Not implemented yet
+	detail::ValueChangeData m_value_change_data_{};
+	bool m_hierarchy_finalized_{false};
+	WriterPackType m_pack_type_{WriterPackType::LZ4};
+	uint64_t m_value_change_data_usage_{0};  // Note: this value is just an estimation
+	uint64_t m_value_change_data_flush_threshold_{128 << 20};  // 128MB
+	uint32_t m_enum_count_{0};
+	bool m_flush_pending_{false};
+
+public:
+	Writer() {}
+	Writer(const string_view_pair name) {
+		if (name.m_size != 0) open(name);
+	}
+	~Writer() { close(); }
+
+	Writer(const Writer &) = delete;
+	Writer(Writer &&) = delete;
+	Writer &operator=(const Writer &) = delete;
+	Writer &operator=(Writer &&) = delete;
+
+	// File control
+	void open(const string_view_pair name);
+	void close();
+
+	//////////////////////////////
+	// Header manipulation API
+	//////////////////////////////
+	const Header &getHeader() const { return m_header_; }
+	void setTimecale(int8_t timescale) { m_header_.m_timescale = timescale; }
+	void setWriter(const string_view_pair writer) {
+		const size_t len = std::min(writer.m_size, sizeof(m_header_.m_writer));
+		std::copy_n(writer.m_data, len, m_header_.m_writer);
+		if (len != sizeof(m_header_.m_writer)) {
+			m_header_.m_writer[len] = '\0';
+		}
+	}
+	void setDate(const string_view_pair date_str) {
+		const size_t len = date_str.m_size;
+		FST_CHECK_EQ(len, sizeof(m_header_.m_date) - 1);
+		std::copy_n(date_str.m_data, len, m_header_.m_date);
+		m_header_.m_date[len] = '\0';
+	}
+	void setDate(const std::tm *d) { setDate(make_string_view_pair(std::asctime(d))); }
+	void setDate() {
+		// set date to now
+		std::time_t t{std::time(nullptr)};
+		setDate(std::localtime(&t));
+	}
+	void setTimezero(int64_t timezero) { m_header_.m_timezero = timezero; }
+
+	//////////////////////////////
+	// Change scope API
+	//////////////////////////////
+	void setScope(
+		Hierarchy::ScopeType scopetype,
+		const string_view_pair scopename,
+		const string_view_pair scopecomp
+	);
+	void upscope();
+
+	//////////////////////////////
+	// Attribute / Misc API
+	//////////////////////////////
+	void setAttrBegin(
+		Hierarchy::AttrType attrtype,
+		Hierarchy::AttrSubType subtype,
+		const string_view_pair attrname,
+		uint64_t arg
+	);
+	void setAttrEnd() {
+		m_hierarchy_buffer_.push_back(
+			static_cast<uint8_t>(Hierarchy::ScopeControlType::GEN_ATTR_END)
+		);
+	}
+	EnumHandle createEnumTable(
+		const string_view_pair name,
+		uint32_t min_valbits,
+		const std::vector<std::pair<string_view_pair, string_view_pair>> &literal_val_arr
+	);
+	template <typename T1, typename T2>
+	EnumHandle createEnumTable(
+		const char *name,
+		uint32_t min_valbits,
+		const std::vector<std::pair<T1, T2>> &literal_val_arr
+	) {
+		std::vector<std::pair<string_view_pair, string_view_pair>> arr{};
+		arr.reserve(literal_val_arr.size());
+		for (const auto &p : literal_val_arr) {
+			arr.emplace_back(make_string_view_pair(p.first), make_string_view_pair(p.second));
+		}
+		return createEnumTable(make_string_view_pair(name), min_valbits, arr);
+	}
+	void emitEnumTableRef(EnumHandle handle) {
+		setAttrBegin(
+			Hierarchy::AttrType::MISC,
+			Hierarchy::AttrSubType::MISC_ENUMTABLE,
+			make_string_view_pair(nullptr, 0),
+			handle
+		);
+	}
+	void setWriterPackType(WriterPackType pack_type) {
+		FST_CHECK(pack_type != WriterPackType::ZLIB && pack_type != WriterPackType::FASTLZ);
+		m_pack_type_ = pack_type;
+	}
+
+	//////////////////////////////
+	// Create variable API
+	//////////////////////////////
+	Handle createVar(
+		Hierarchy::VarType vartype,
+		Hierarchy::VarDirection vardir,
+		uint32_t bitwidth,
+		const string_view_pair name,
+		uint32_t alias_handle
+	);
+	// TODO
+	// Handle createVar2(
+	// 	Hierarchy::VarType vartype,
+	// 	Hierarchy::VarDirection vardir,
+	// 	uint32_t bitwidth,
+	// 	const string_view_pair name,
+	// 	uint32_t alias_handle,
+	// 	const string_view_pair type,
+	// 	Hierarchy::SupplementalVarType svt,
+	// 	Hierarchy::SupplementalDataType sdt
+	// );
+
+	//////////////////////////////
+	// Waveform API
+	//////////////////////////////
+	void emitTimeChange(uint64_t tim);
+	// TODO
+	// void emitDumpActive(bool enable);
+	void emitValueChange(
+		Handle handle, const uint32_t *val, EncodingType encoding = EncodingType::BINARY
+	);
+	void emitValueChange(
+		Handle handle, const uint64_t *val, EncodingType encoding = EncodingType::BINARY
+	);
+	// Pass by value for small integers
+	void emitValueChange(Handle handle, uint64_t val);
+	// Add support for C-string value changes (e.g. fst string values)
+	// Note: This function is mainly for GtkWave compatibility.
+	// It is very dirty and inefficient, users should avoid using it.
+	// - For double handles, const char* is interpreted as a double* (8B)
+	// - For normal integer handles, const char* is "01xz..." (1B per bit)
+	// We only ensure that this function works where Verilator use it.
+	void emitValueChange(Handle handle, const char *val);
+
+	// Flush value change data
+	void flushValueChangeData() { m_flush_pending_ = true; }
+
+private:
+	// internal helpers
+	static void writeHeader_(const Header &header, std::ostream &os);
+	void appendGeometry_(std::ostream &os);
+	void appendHierarchy_(std::ostream &os);
+	void appendBlackout_(std::ostream &os);  // Not implemented yet
+	// This function is used to flush value change data to file, and keep only the latest value in
+	// memory Just want to separate the const part from the non-const part for code clarity
+	static void flushValueChangeDataConstPart_(
+		const detail::ValueChangeData &vcd, std::ostream &os, WriterPackType pack_type
+	);
+	void flushValueChangeData_(detail::ValueChangeData &vcd, std::ostream &os) {
+		if (vcd.m_timestamps.empty()) {
+			return;
+		}
+		flushValueChangeDataConstPart_(vcd, os, m_pack_type_);
+		vcd.keepOnlyTheLatestValue();
+		++m_header_.m_num_value_change_data_blocks;
+		m_value_change_data_usage_ = 0;
+		m_flush_pending_ = false;
+	}
+	void finalizeHierarchy_() {
+		if (m_hierarchy_finalized_) return;
+		m_hierarchy_finalized_ = true;
+		// Original FST code comments: as a default, use 128MB and increment when
+		// every 1M signals are defined.
+		m_value_change_data_flush_threshold_ = (((m_header_.m_num_handles - 1) >> 20) + 1) << 27;
+	}
+	template <typename... T>
+	void emitValueChangeHelper_(Handle handle, T &&...val);
+};
+
+}  // namespace fst

include/gtkwave/fastlz.c

@@ -1,549 +0,0 @@
-/*
-  FastLZ - lightning-fast lossless compression library
-
-  Copyright (C) 2007 Ariya Hidayat ([email protected])
-  Copyright (C) 2006 Ariya Hidayat ([email protected])
-  Copyright (C) 2005 Ariya Hidayat ([email protected])
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in
-  all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-  THE SOFTWARE.
-
-  SPDX-License-Identifier: MIT
-*/
-
-#include "fastlz.h"
-
-#if !defined(FASTLZ__COMPRESSOR) && !defined(FASTLZ_DECOMPRESSOR)
-
-/*
- * Always check for bound when decompressing.
- * Generally it is best to leave it defined.
- */
-#define FASTLZ_SAFE
-
-
-/*
- * Give hints to the compiler for branch prediction optimization.
- */
-#if defined(__GNUC__) && (__GNUC__ > 2)
-#define FASTLZ_EXPECT_CONDITIONAL(c)    (__builtin_expect((c), 1))
-#define FASTLZ_UNEXPECT_CONDITIONAL(c)  (__builtin_expect((c), 0))
-#else
-#define FASTLZ_EXPECT_CONDITIONAL(c)    (c)
-#define FASTLZ_UNEXPECT_CONDITIONAL(c)  (c)
-#endif
-
-/*
- * Use inlined functions for supported systems.
- */
-#if defined(__GNUC__) || defined(__DMC__) || defined(__POCC__) || defined(__WATCOMC__) || defined(__SUNPRO_C)
-#define FASTLZ_INLINE inline
-#elif defined(__BORLANDC__) || defined(_MSC_VER) || defined(__LCC__)
-#define FASTLZ_INLINE __inline
-#else
-#define FASTLZ_INLINE
-#endif
-
-/*
- * Prevent accessing more than 8-bit at once, except on x86 architectures.
- */
-#if !defined(FASTLZ_STRICT_ALIGN)
-#define FASTLZ_STRICT_ALIGN
-#if defined(__i386__) || defined(__386)  /* GNU C, Sun Studio */
-#undef FASTLZ_STRICT_ALIGN
-#elif defined(__i486__) || defined(__i586__) || defined(__i686__) || defined(__amd64) /* GNU C */
-#undef FASTLZ_STRICT_ALIGN
-#elif defined(_M_IX86) /* Intel, MSVC */
-#undef FASTLZ_STRICT_ALIGN
-#elif defined(__386)
-#undef FASTLZ_STRICT_ALIGN
-#elif defined(_X86_) /* MinGW */
-#undef FASTLZ_STRICT_ALIGN
-#elif defined(__I86__) /* Digital Mars */
-#undef FASTLZ_STRICT_ALIGN
-#endif
-#endif
-
-/* prototypes */
-int fastlz_compress(const void* input, int length, void* output);
-int fastlz_compress_level(int level, const void* input, int length, void* output);
-int fastlz_decompress(const void* input, int length, void* output, int maxout);
-
-#define MAX_COPY       32
-#define MAX_LEN       264  /* 256 + 8 */
-#define MAX_DISTANCE 8192
-
-#if !defined(FASTLZ_STRICT_ALIGN)
-#define FASTLZ_READU16(p) *((const flzuint16*)(p))
-#else
-#define FASTLZ_READU16(p) ((p)[0] | (p)[1]<<8)
-#endif
-
-#define HASH_LOG  13
-#define HASH_SIZE (1<< HASH_LOG)
-#define HASH_MASK  (HASH_SIZE-1)
-#define HASH_FUNCTION(v,p) { v = FASTLZ_READU16(p); v ^= FASTLZ_READU16(p+1)^(v>>(16-HASH_LOG));v &= HASH_MASK; }
-
-#undef FASTLZ_LEVEL
-#define FASTLZ_LEVEL 1
-
-#undef FASTLZ_COMPRESSOR
-#undef FASTLZ_DECOMPRESSOR
-#define FASTLZ_COMPRESSOR fastlz1_compress
-#define FASTLZ_DECOMPRESSOR fastlz1_decompress
-static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output);
-static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout);
-#include "fastlz.c"
-
-#undef FASTLZ_LEVEL
-#define FASTLZ_LEVEL 2
-
-#undef MAX_DISTANCE
-#define MAX_DISTANCE 8191
-#define MAX_FARDISTANCE (65535+MAX_DISTANCE-1)
-
-#undef FASTLZ_COMPRESSOR
-#undef FASTLZ_DECOMPRESSOR
-#define FASTLZ_COMPRESSOR fastlz2_compress
-#define FASTLZ_DECOMPRESSOR fastlz2_decompress
-static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output);
-static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout);
-#include "fastlz.c"
-
-int fastlz_compress(const void* input, int length, void* output)
-{
-  /* for short block, choose fastlz1 */
-  if(length < 65536)
-    return fastlz1_compress(input, length, output);
-
-  /* else... */
-  return fastlz2_compress(input, length, output);
-}
-
-int fastlz_decompress(const void* input, int length, void* output, int maxout)
-{
-  /* magic identifier for compression level */
-  int level = ((*(const flzuint8*)input) >> 5) + 1;
-
-  if(level == 1)
-    return fastlz1_decompress(input, length, output, maxout);
-  if(level == 2)
-    return fastlz2_decompress(input, length, output, maxout);
-
-  /* unknown level, trigger error */
-  return 0;
-}
-
-int fastlz_compress_level(int level, const void* input, int length, void* output)
-{
-  if(level == 1)
-    return fastlz1_compress(input, length, output);
-  if(level == 2)
-    return fastlz2_compress(input, length, output);
-
-  return 0;
-}
-
-#else /* !defined(FASTLZ_COMPRESSOR) && !defined(FASTLZ_DECOMPRESSOR) */
-
-static FASTLZ_INLINE int FASTLZ_COMPRESSOR(const void* input, int length, void* output)
-{
-  const flzuint8* ip = (const flzuint8*) input;
-  const flzuint8* ip_bound = ip + length - 2;
-  const flzuint8* ip_limit = ip + length - 12;
-  flzuint8* op = (flzuint8*) output;
-
-  const flzuint8* htab[HASH_SIZE];
-  const flzuint8** hslot;
-  flzuint32 hval;
-
-  flzuint32 copy;
-
-  /* sanity check */
-  if(FASTLZ_UNEXPECT_CONDITIONAL(length < 4))
-  {
-    if(length)
-    {
-      /* create literal copy only */
-      *op++ = length-1;
-      ip_bound++;
-      while(ip <= ip_bound)
-        *op++ = *ip++;
-      return length+1;
-    }
-    else
-      return 0;
-  }
-
-  /* initializes hash table */
-  for (hslot = htab; hslot < htab + HASH_SIZE; hslot++)
-    *hslot = ip;
-
-  /* we start with literal copy */
-  copy = 2;
-  *op++ = MAX_COPY-1;
-  *op++ = *ip++;
-  *op++ = *ip++;
-
-  /* main loop */
-  while(FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit))
-  {
-    const flzuint8* ref;
-    flzuint32 distance;
-
-    /* minimum match length */
-    flzuint32 len = 3;
-
-    /* comparison starting-point */
-    const flzuint8* anchor = ip;
-
-    /* check for a run */
-#if FASTLZ_LEVEL==2
-    if(ip[0] == ip[-1] && FASTLZ_READU16(ip-1)==FASTLZ_READU16(ip+1))
-    {
-      distance = 1;
-      /* ip += 3; */ /* scan-build, never used */
-      ref = anchor - 1 + 3;
-      goto match;
-    }
-#endif
-
-    /* find potential match */
-    HASH_FUNCTION(hval,ip);
-    hslot = htab + hval;
-    ref = htab[hval];
-
-    /* calculate distance to the match */
-    distance = anchor - ref;
-
-    /* update hash table */
-    *hslot = anchor;
-
-    /* is this a match? check the first 3 bytes */
-    if(distance==0 ||
-#if FASTLZ_LEVEL==1
-    (distance >= MAX_DISTANCE) ||
-#else
-    (distance >= MAX_FARDISTANCE) ||
-#endif
-    *ref++ != *ip++ || *ref++!=*ip++ || *ref++!=*ip++)
-      goto literal;
-
-#if FASTLZ_LEVEL==2
-    /* far, needs at least 5-byte match */
-    if(distance >= MAX_DISTANCE)
-    {
-      if(*ip++ != *ref++ || *ip++!= *ref++)
-        goto literal;
-      len += 2;
-    }
-
-    match:
-#endif
-
-    /* last matched byte */
-    ip = anchor + len;
-
-    /* distance is biased */
-    distance--;
-
-    if(!distance)
-    {
-      /* zero distance means a run */
-      flzuint8 x = ip[-1];
-      while(ip < ip_bound)
-        if(*ref++ != x) break; else ip++;
-    }
-    else
-    for(;;)
-    {
-      /* safe because the outer check against ip limit */
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      if(*ref++ != *ip++) break;
-      while(ip < ip_bound)
-        if(*ref++ != *ip++) break;
-      break;
-    }
-
-    /* if we have copied something, adjust the copy count */
-    if(copy)
-      /* copy is biased, '0' means 1 byte copy */
-      *(op-copy-1) = copy-1;
-    else
-      /* back, to overwrite the copy count */
-      op--;
-
-    /* reset literal counter */
-    copy = 0;
-
-    /* length is biased, '1' means a match of 3 bytes */
-    ip -= 3;
-    len = ip - anchor;
-
-    /* encode the match */
-#if FASTLZ_LEVEL==2
-    if(distance < MAX_DISTANCE)
-    {
-      if(len < 7)
-      {
-        *op++ = (len << 5) + (distance >> 8);
-        *op++ = (distance & 255);
-      }
-      else
-      {
-        *op++ = (7 << 5) + (distance >> 8);
-        for(len-=7; len >= 255; len-= 255)
-          *op++ = 255;
-        *op++ = len;
-        *op++ = (distance & 255);
-      }
-    }
-    else
-    {
-      /* far away, but not yet in the another galaxy... */
-      if(len < 7)
-      {
-        distance -= MAX_DISTANCE;
-        *op++ = (len << 5) + 31;
-        *op++ = 255;
-        *op++ = distance >> 8;
-        *op++ = distance & 255;
-      }
-      else
-      {
-        distance -= MAX_DISTANCE;
-        *op++ = (7 << 5) + 31;
-        for(len-=7; len >= 255; len-= 255)
-          *op++ = 255;
-        *op++ = len;
-        *op++ = 255;
-        *op++ = distance >> 8;
-        *op++ = distance & 255;
-      }
-    }
-#else
-
-    if(FASTLZ_UNEXPECT_CONDITIONAL(len > MAX_LEN-2))
-      while(len > MAX_LEN-2)
-      {
-        *op++ = (7 << 5) + (distance >> 8);
-        *op++ = MAX_LEN - 2 - 7 -2;
-        *op++ = (distance & 255);
-        len -= MAX_LEN-2;
-      }
-
-    if(len < 7)
-    {
-      *op++ = (len << 5) + (distance >> 8);
-      *op++ = (distance & 255);
-    }
-    else
-    {
-      *op++ = (7 << 5) + (distance >> 8);
-      *op++ = len - 7;
-      *op++ = (distance & 255);
-    }
-#endif
-
-    /* update the hash at match boundary */
-    HASH_FUNCTION(hval,ip);
-    htab[hval] = ip++;
-    HASH_FUNCTION(hval,ip);
-    htab[hval] = ip++;
-
-    /* assuming literal copy */
-    *op++ = MAX_COPY-1;
-
-    continue;
-
-    literal:
-      *op++ = *anchor++;
-      ip = anchor;
-      copy++;
-      if(FASTLZ_UNEXPECT_CONDITIONAL(copy == MAX_COPY))
-      {
-        copy = 0;
-        *op++ = MAX_COPY-1;
-      }
-  }
-
-  /* left-over as literal copy */
-  ip_bound++;
-  while(ip <= ip_bound)
-  {
-    *op++ = *ip++;
-    copy++;
-    if(copy == MAX_COPY)
-    {
-      copy = 0;
-      *op++ = MAX_COPY-1;
-    }
-  }
-
-  /* if we have copied something, adjust the copy length */
-  if(copy)
-    *(op-copy-1) = copy-1;
-  else
-    op--;
-
-#if FASTLZ_LEVEL==2
-  /* marker for fastlz2 */
-  *(flzuint8*)output |= (1 << 5);
-#endif
-
-  return op - (flzuint8*)output;
-}
-
-static FASTLZ_INLINE int FASTLZ_DECOMPRESSOR(const void* input, int length, void* output, int maxout)
-{
-  const flzuint8* ip = (const flzuint8*) input;
-  const flzuint8* ip_limit  = ip + length;
-  flzuint8* op = (flzuint8*) output;
-  flzuint8* op_limit = op + maxout;
-  flzuint32 ctrl = (*ip++) & 31;
-  int loop = 1;
-
-  do
-  {
-    const flzuint8* ref = op;
-    flzuint32 len = ctrl >> 5;
-    flzuint32 ofs = (ctrl & 31) << 8;
-
-    if(ctrl >= 32)
-    {
-#if FASTLZ_LEVEL==2
-      flzuint8 code;
-#endif
-      len--;
-      ref -= ofs;
-      if (len == 7-1)
-#if FASTLZ_LEVEL==1
-        len += *ip++;
-      ref -= *ip++;
-#else
-        do
-        {
-          code = *ip++;
-          len += code;
-        } while (code==255);
-      code = *ip++;
-      ref -= code;
-
-      /* match from 16-bit distance */
-      if(FASTLZ_UNEXPECT_CONDITIONAL(code==255))
-      if(FASTLZ_EXPECT_CONDITIONAL(ofs==(31 << 8)))
-      {
-        ofs = (*ip++) << 8;
-        ofs += *ip++;
-        ref = op - ofs - MAX_DISTANCE;
-      }
-#endif
-
-#ifdef FASTLZ_SAFE
-      if (FASTLZ_UNEXPECT_CONDITIONAL(op + len + 3 > op_limit))
-        return 0;
-
-      if (FASTLZ_UNEXPECT_CONDITIONAL(ref-1 < (flzuint8 *)output))
-        return 0;
-#endif
-
-      if(FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit))
-        ctrl = *ip++;
-      else
-        loop = 0;
-
-      if(ref == op)
-      {
-        /* optimize copy for a run */
-        flzuint8 b = ref[-1];
-        *op++ = b;
-        *op++ = b;
-        *op++ = b;
-        for(; len; --len)
-          *op++ = b;
-      }
-      else
-      {
-#if !defined(FASTLZ_STRICT_ALIGN)
-        const flzuint16* p;
-        flzuint16* q;
-#endif
-        /* copy from reference */
-        ref--;
-        *op++ = *ref++;
-        *op++ = *ref++;
-        *op++ = *ref++;
-
-#if !defined(FASTLZ_STRICT_ALIGN)
-        /* copy a byte, so that now it's word aligned */
-        if(len & 1)
-        {
-          *op++ = *ref++;
-          len--;
-        }
-
-        /* copy 16-bit at once */
-        q = (flzuint16*) op;
-        op += len;
-        p = (const flzuint16*) ref;
-        for(len>>=1; len > 4; len-=4)
-        {
-          *q++ = *p++;
-          *q++ = *p++;
-          *q++ = *p++;
-          *q++ = *p++;
-        }
-        for(; len; --len)
-          *q++ = *p++;
-#else
-        for(; len; --len)
-          *op++ = *ref++;
-#endif
-      }
-    }
-    else
-    {
-      ctrl++;
-#ifdef FASTLZ_SAFE
-      if (FASTLZ_UNEXPECT_CONDITIONAL(op + ctrl > op_limit))
-        return 0;
-      if (FASTLZ_UNEXPECT_CONDITIONAL(ip + ctrl > ip_limit))
-        return 0;
-#endif
-
-      *op++ = *ip++;
-      for(--ctrl; ctrl; ctrl--)
-        *op++ = *ip++;
-
-      loop = FASTLZ_EXPECT_CONDITIONAL(ip < ip_limit);
-      if(loop)
-        ctrl = *ip++;
-    }
-  }
-  while(FASTLZ_EXPECT_CONDITIONAL(loop));
-
-  return op - (flzuint8*)output;
-}
-
-#endif /* !defined(FASTLZ_COMPRESSOR) && !defined(FASTLZ_DECOMPRESSOR) */

include/gtkwave/fastlz.h

@@ -1,109 +0,0 @@
-/*
-  FastLZ - lightning-fast lossless compression library
-
-  Copyright (C) 2007 Ariya Hidayat ([email protected])
-  Copyright (C) 2006 Ariya Hidayat ([email protected])
-  Copyright (C) 2005 Ariya Hidayat ([email protected])
-
-  Permission is hereby granted, free of charge, to any person obtaining a copy
-  of this software and associated documentation files (the "Software"), to deal
-  in the Software without restriction, including without limitation the rights
-  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-  copies of the Software, and to permit persons to whom the Software is
-  furnished to do so, subject to the following conditions:
-
-  The above copyright notice and this permission notice shall be included in
-  all copies or substantial portions of the Software.
-
-  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-  THE SOFTWARE.
-
-  SPDX-License-Identifier: MIT
-*/
-
-#ifndef FASTLZ_H
-#define FASTLZ_H
-
-#include <inttypes.h>
-
-#define flzuint8 uint8_t
-#define flzuint16 uint16_t
-#define flzuint32 uint32_t
-
-
-#define FASTLZ_VERSION 0x000100
-
-#define FASTLZ_VERSION_MAJOR     0
-#define FASTLZ_VERSION_MINOR     0
-#define FASTLZ_VERSION_REVISION  0
-
-#define FASTLZ_VERSION_STRING "0.1.0"
-
-#if defined (__cplusplus)
-extern "C" {
-#endif
-
-/**
-  Compress a block of data in the input buffer and returns the size of
-  compressed block. The size of input buffer is specified by length. The
-  minimum input buffer size is 16.
-
-  The output buffer must be at least 5% larger than the input buffer
-  and can not be smaller than 66 bytes.
-
-  If the input is not compressible, the return value might be larger than
-  length (input buffer size).
-
-  The input buffer and the output buffer can not overlap.
-*/
-
-int fastlz_compress(const void* input, int length, void* output);
-
-/**
-  Decompress a block of compressed data and returns the size of the
-  decompressed block. If error occurs, e.g. the compressed data is
-  corrupted or the output buffer is not large enough, then 0 (zero)
-  will be returned instead.
-
-  The input buffer and the output buffer can not overlap.
-
-  Decompression is memory safe and guaranteed not to write the output buffer
-  more than what is specified in maxout.
- */
-
-int fastlz_decompress(const void* input, int length, void* output, int maxout);
-
-/**
-  Compress a block of data in the input buffer and returns the size of
-  compressed block. The size of input buffer is specified by length. The
-  minimum input buffer size is 16.
-
-  The output buffer must be at least 5% larger than the input buffer
-  and can not be smaller than 66 bytes.
-
-  If the input is not compressible, the return value might be larger than
-  length (input buffer size).
-
-  The input buffer and the output buffer can not overlap.
-
-  Compression level can be specified in parameter level. At the moment,
-  only level 1 and level 2 are supported.
-  Level 1 is the fastest compression and generally useful for short data.
-  Level 2 is slightly slower but it gives better compression ratio.
-
-  Note that the compressed data, regardless of the level, can always be
-  decompressed using the function fastlz_decompress above.
-*/
-
-int fastlz_compress_level(int level, const void* input, int length, void* output);
-
-#if defined (__cplusplus)
-}
-#endif
-
-#endif /* FASTLZ_H */