Merge from master for release.

.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@v7
+        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@v8
+        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@v6
+        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@v8
+        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@v8
+        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@v7
+        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@v7
+        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@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
         with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
           private-key: ${{ secrets.VERILATOR_CI_KEY }}
           owner: verilator
           repositories: verilator

.github/workflows/docker.yml

@@ -39,7 +39,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
       - name: Extract context variables
         run: |
@@ -54,7 +54,7 @@ jobs:
 
       - name: Docker meta
         id: docker_meta
-        uses: docker/metadata-action@v6
+        uses: docker/metadata-action@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@v4
+        uses: docker/setup-qemu-action@06116385d9baf250c9f4dcb4858b16962ea869c3  # v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v4
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4
         with:
           buildkitd-flags: --debug
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v4
+        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@v7
+        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/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@v5
+        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@v5
+        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@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
         with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
           private-key: ${{ secrets.VERILATOR_CI_KEY }}
           permission-actions: write
           permission-pull-requests: write
       - name: Comment on PR
         env:
           GH_TOKEN: ${{ steps.generate-token.outputs.token }}
-          COVERAGE_PR_RUN_IDS: ${{ needs.build.outputs.coverage-pr-run-ids }}
+          PR_RUN_IDS: ${{ needs.build.outputs.pr-run-ids }}
-        run: bash -x ./ci/ci-pages-notify.bash
+        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@v7
+        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: |
@@ -40,16 +50,20 @@ jobs:
           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 }}
+          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 }}
+          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@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
-          path: verilator-rtlmeter.tar.gz
+          path: ${{ steps.create-archive.outputs.archive }}
-          name: verilator-rtlmeter-${{ inputs.runs-on }}-${{ inputs.cc }}
+          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.
@@ -63,26 +72,8 @@ jobs:
           sudo apt install ccache mold libfl-dev libjemalloc-dev libsystemc-dev || \
           sudo apt install ccache mold libfl-dev libjemalloc-dev libsystemc-dev
 
-      - name: Download Verilator installation archive
-        uses: actions/download-artifact@v8
-        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 }}
-
       - 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
+      - name: Upload results - new
-        uses: actions/upload-artifact@v7
+        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@v8
+        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,7 +99,7 @@ jobs:
 
       - name: Upload code coverage data
         if: ${{ inputs.dev-gcov }}
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: ${{ github.workspace }}/repo/obj_coverage/verilator-${{ inputs.suite }}.info
           name: code-coverage-${{ inputs.suite }}

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

@@ -1,48 +0,0 @@
----
-# DESCRIPTION: Github actions config
-# This name is key to badges in README.rst, so we use the name build
-# SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
-
-name: RTLMeter PR results
-
-on:
-  workflow_run:
-    workflows: [RTLMeter]
-    types: [completed]
-
-jobs:
-  publish:
-    name: Publish
-    runs-on: ubuntu-latest
-    if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' }}
-    permissions:
-      actions: read
-      pull-requests: write
-    steps:
-      - name: Download report
-        uses: actions/download-artifact@v8
-        with:
-          name: rtlmeter-pr-results
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Download PR number
-        uses: actions/download-artifact@v8
-        with:
-          name: pr-number
-          run-id: ${{ github.event.workflow_run.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-      # Use the Verilator CI app to post the comment
-      - name: Generate access token
-        id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
-        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

@@ -40,175 +40,229 @@ jobs:
       (github.event_name == 'workflow_dispatch') ||
       (github.event_name == 'push')
     runs-on: ubuntu-24.04
+    outputs:
+      old-sha: ${{ steps.start.outputs.old-sha }}
+      cases: ${{ steps.cases.outputs.cases }}
     steps:
-      - name: Startup
+      - name: Checkout
-        run: echo
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
 
-  build-gcc:
+      - name: Startup
-    name: Build GCC
+        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:
+  build-clang-new:
-    name: Build Clang
+    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
+      fail-fast: ${{ github.event_name == 'pull_request' }}
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      max-parallel: 7
       matrix:
-        cases:
+        cases: ${{ fromJSON(needs.start.outputs.cases)['gcc'] }}
-          - "BlackParrot:1x1:*"
-          - "BlackParrot:4x4:*"
-          - "Caliptra:default:*"
-          - "NVDLA:*"
-          - "OpenPiton:1x1:*"
-          - "OpenPiton:4x4:*"
-          - "OpenTitan:*"
-          - "VeeR-EH1:asic*"
-          - "VeeR-EH1:default*"
-          - "VeeR-EH1:hiperf*"
-          - "VeeR-EH2:asic*"
-          - "VeeR-EH2:default*"
-          - "VeeR-EH2:hiperf*"
-          - "VeeR-EL2:asic*"
-          - "VeeR-EL2:default*"
-          - "VeeR-EL2:hiperf*"
-          - "Vortex:mini:*"
-          - "Vortex:sane:*"
-          - "XiangShan:default-chisel3:* !*:linux"
-          - "XiangShan:default-chisel6:* !*:linux"
-          - "XiangShan:mini-chisel3:* !*:linux"
-          - "XiangShan:mini-chisel6:* !*:linux"
-          - "XuanTie-E902:*"
-          - "XuanTie-E906:*"
-          - "XuanTie-C906:*"
-          - "XuanTie-C910:*"
 
   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
+      fail-fast: ${{ github.event_name == 'pull_request' }}
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      max-parallel: 7
       matrix:
-        cases:
+        cases: ${{ fromJSON(needs.start.outputs.cases)['clang'] }}
-          - "BlackParrot:1x1:*"
-          - "BlackParrot:4x4:*"
-          - "Caliptra:default:*"
-          - "NVDLA:*"
-          - "OpenPiton:1x1:*"
-          - "OpenPiton:4x4:*"
-          - "OpenTitan:*"
-          - "VeeR-EH1:asic*"
-          - "VeeR-EH1:default*"
-          - "VeeR-EH1:hiperf*"
-          - "VeeR-EH2:asic*"
-          - "VeeR-EH2:default*"
-          - "VeeR-EH2:hiperf*"
-          - "VeeR-EL2:asic*"
-          - "VeeR-EL2:default*"
-          - "VeeR-EL2:hiperf*"
-          - "Vortex:mini:*"
-          - "Vortex:sane:*"
-          - "XiangShan:default-chisel3:* !*:linux"
-          - "XiangShan:default-chisel6:* !*:linux"
-          - "XiangShan:mini-chisel3:* !*:linux"
-          - "XiangShan:mini-chisel6:* !*:linux"
-          - "XuanTie-E902:*"
-          - "XuanTie-E906:*"
-          - "XuanTie-C906:*"
-          - "XuanTie-C910:*"
 
   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
+      fail-fast: ${{ github.event_name == 'pull_request' }}
-      max-parallel: ${{ github.event == 'schedule' && 2 || 7 }}
+      max-parallel: 6
       matrix:
-        cases:
+        cases: ${{ fromJSON(needs.start.outputs.cases)['gcc-hier'] }}
-          - "BlackParrot:1x1:* !-hier"
-          - "BlackParrot:4x4:* !-hier"
-          - "NVDLA:* !-hier"
-          - "OpenPiton:1x1:* !-hier"
-          - "OpenPiton:4x4:* !-hier"
-          - "OpenPiton:8x8:* !-hier"
-          - "OpenPiton:16x16:dhry !-hier"
-          - "XuanTie-C910:* !-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.
+    # Skip if cancelled.
-    # That is: do not run if all skipped, or the workflow was cancelled.
+    # On PRs, run if something succeeded and nothing failed.
-    if: ${{ (contains(needs.*.result, 'success') || contains(needs.*.result, 'failure')) && !cancelled() }}
+    # 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:
+    outputs:
-      fail-fast: false
+      # The run tags, derived from the 'run-*' dependency job names
-      matrix:
+      run-tags: ${{ steps.tags.outputs.tags }}
-        tag: [gcc, clang, gcc-hier]
+    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@v8
+        run: |
-        with:
+          for tag in ${{ steps.tags.outputs.tags }}; do
-          pattern: rtlmeter-${{ matrix.tag }}-results-*
+            mkdir artifacts all-results-$tag
-          path: all-results-${{ matrix.tag }}
+            gh run download ${{ github.run_id }} --pattern "rtlmeter-$tag-results-*" --dir artifacts
-          merge-multiple: true
+            mv $(find artifacts -name "*.json") all-results-$tag/
+            rm -rf artifacts
+          done
       - name: Combine results
         working-directory: rtlmeter
         run: |
-          ./rtlmeter collate ../all-results-${{ matrix.tag }}/*.json > ../all-results-${{ matrix.tag }}.json
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            ./rtlmeter collate ../all-results-$tag/*.json > ../all-results-$tag.json
+          done
       - name: Upload combined results
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
-          path: all-results-${{ matrix.tag }}.json
+          path: all-results-*.json
-          name: all-results-${{ matrix.tag }}
+          name: all-results
+          overwrite: true
+          retention-days: 30
+
+      # The reference (old) results only exist for pull requests, where the
+      # 'build-*-old' jobs run and the run jobs produce '*-reference-*' artifacts.
+      - name: Download reference results
+        if: ${{ github.event_name == 'pull_request' }}
+        run: |
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            mkdir artifacts all-reference-$tag
+            gh run download ${{ github.run_id }} --pattern "rtlmeter-$tag-reference-*" --dir artifacts
+            mv $(find artifacts -name "*.json") all-reference-$tag/
+            rm -rf artifacts
+          done
+      - name: Combine reference results
+        if: ${{ github.event_name == 'pull_request' }}
+        working-directory: rtlmeter
+        run: |
+          for tag in ${{ steps.tags.outputs.tags }}; do
+            ./rtlmeter collate ../all-reference-$tag/*.json > ../all-reference-$tag.json
+          done
+      - name: Upload reference results
+        if: ${{ github.event_name == 'pull_request' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
+        with:
+          path: all-reference-*.json
+          name: all-reference
           overwrite: true
           retention-days: 30
 
@@ -224,28 +278,27 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - name: Download combined results
-        uses: actions/download-artifact@v8
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8
         with:
-          pattern: all-results-*
+          name: all-results
           path: results
-          merge-multiple: true
       - name: Upload published results
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
           path: results/*.json
           name: published-results
       # Pushing to verilator/verilator-rtlmeter-results requires elevated permissions
       - name: Generate access token
         id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
         with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
           private-key: ${{ secrets.VERILATOR_CI_KEY }}
           owner: verilator
           repositories: verilator-rtlmeter-results
           permission-contents: write
       - name: Checkout verilator-rtlmeter-results
-        uses: actions/checkout@v6
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
           repository: "verilator/verilator-rtlmeter-results"
           token: ${{ steps.generate-token.outputs.token }}
@@ -272,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@v8
+      - name: Checkout Verilator
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7
         with:
-          pattern: all-results-*
+          path: verilator
-          path: all-results
+
-          merge-multiple: true
-      - name: Get scheduled run info
-        id: scheduled-info
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          ID=$(gh run --repo ${{ github.repository }} list --workflow RTLMeter --event schedule --status success --limit 1 --json databaseId --jq ".[0].databaseId")
-          echo "id=$ID" >> $GITHUB_OUTPUT
-          URL=$(gh run --repo ${{ github.repository }} view $ID --json url --jq ".url")
-          echo "url=$URL" >> $GITHUB_OUTPUT
-          NUM=$(gh run --repo ${{ github.repository }} view $ID --json number --jq ".number")
-          echo "num=$NUM" >> $GITHUB_OUTPUT
-          DATE=$(gh run --repo ${{ github.repository }} view $ID --json createdAt --jq ".createdAt")
-          echo "date=$DATE" >> $GITHUB_OUTPUT
-      - name: Download scheduled run results
-        uses: actions/download-artifact@v8
-        with:
-          name: published-results
-          path: nightly-results
-          run-id: ${{ steps.scheduled-info.outputs.id }}
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-      - name: Compare results
-        working-directory: rtlmeter
-        run: |
-          for tag in gcc clang gcc-hier; do
-            ADATA=../nightly-results/all-results-${tag}.json
-            BDATA=../all-results/all-results-${tag}.json
-            touch ../verilate-${tag}.txt
-            touch ../execute-${tag}.txt
-            touch ../cppbuild-${tag}.txt
-            if [[ ! -e $ADATA ]]; then
-              continue
-            fi
-            ./rtlmeter compare --cases '* !Example:* !*:hello' --steps "verilate" --metrics "elapsed memory"              $ADATA $BDATA > ../verilate-${tag}.txt
-            cat ../verilate-${tag}.txt
-            ./rtlmeter compare --cases '* !Example:* !*:hello' --steps "execute"  --metrics "speed memory elapsed"        $ADATA $BDATA > ../execute-${tag}.txt
-            cat ../execute-${tag}.txt
-            ./rtlmeter compare --cases '* !Example:* !*:hello' --steps "cppbuild" --metrics "elapsed memory cpu codeSize" $ADATA $BDATA > ../cppbuild-${tag}.txt
-            cat ../cppbuild-${tag}.txt
-          done
       - name: Create report
+        id: report
+        working-directory: verilator
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          set -x
+          ln -s ../rtlmeter rtlmeter
-          NUM=$(gh run --repo ${{ github.repository }} view ${{ github.run_id }} --json number --jq ".number")
+          gh repo set-default ${{ github.repository }}
-          URL=$(gh run --repo ${{ github.repository }} view ${{ github.run_id }} --json url    --jq ".url")
+          # Create run report - save status to fail job if the script did
-          echo -n "Performance metrics for PR workflow [#$NUM]($URL) (B) compared to scheduled run" > report.txt
+          STATUS=0
-          echo -n " [#${{ steps.scheduled-info.outputs.num }}](${{ steps.scheduled-info.outputs.url }}) (A)" >> report.txt
+          ci/ci-rtlmeter-report.bash ${{ github.run_id }} ${{ github.sha }} ${{ needs.combine-results.outputs.run-tags }} || STATUS=$?
-          echo    " from ${{ steps.scheduled-info.outputs.date }}" >> report.txt
+          echo "status=$STATUS" >> "$GITHUB_OUTPUT"
-          for tag in gcc clang gcc-hier; do
+          # Create the report artifact
-            echo "" >> report.txt
+          mkdir ../report-artifact
-            if [[ $tag == "gcc" ]]; then
+          mv rtlmeter-report/report ../report-artifact/
-              echo "<details open>" >> report.txt
+          echo ${{ github.event.number }} > ../report-artifact/pr-number.txt
-            else
+          # Create the notification artifact
-              echo "<details>" >> report.txt
+          mkdir ../notification-artifact
-            fi
+          mv rtlmeter-report/notification.txt ../notification-artifact/body.txt
-            echo -n "<summary><strong><em>" >> report.txt
+          echo ${{ github.event.number }} > ../notification-artifact/pr-number.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
       - name: Upload report
-        uses: actions/upload-artifact@v7
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
         with:
-          path: report.txt
+          path: report-artifact
-          name: rtlmeter-pr-results
+          name: rtlmeter-report
-      - name: Save PR number
+
-        run: echo ${{ github.event.number }} > pr-number.txt
+      - name: Upload notification
-      - name: Upload PR number
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7
-        uses: actions/upload-artifact@v7
         with:
-          path: pr-number.txt
+          path: notification-artifact
-          name: pr-number
+          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)
@@ -394,9 +392,9 @@ jobs:
       # Creating issues requires elevated privilege
       - name: Generate access token
         id: generate-token
-        uses: actions/create-github-app-token@v3.1.1
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1  # v3.2.0
         with:
-          app-id: ${{ vars.VERILATOR_CI_ID }}
+          client-id: ${{ vars.VERILATOR_CI_ID }}
           private-key: ${{ secrets.VERILATOR_CI_KEY }}
           owner: verilator
           repositories: verilator

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.048
+    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,206 @@ 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
 ==========================
 
@@ -35,7 +237,7 @@ Verilator 5.048 2026-04-26
 * Improve NFA-based multi-cycle SVA evaluation engine (#7430). [Yilou Wang]
 * Change array tracing to dump left index to right index (#7205). [Geza Lore, Testorrent USA, Inc.]
 * Change `--converge-limit` default to 10000 (#7209).
-* Support inout inside SV interface (#3466) (#7134). [Nick Brereton]
+* Support inout inside SV interface (#3466) (#7134) (#7708) (#7710). [Nick Brereton]
 * Support `##0` cycle delays (#4263) (#7298). [Yilou Wang]
 * Support multidimensional arrays of interfaces (#6230) (#7451). [em2machine]
 * Support array reduction methods with 'with' clause in constraints (#6455) (#6999). [Rahul Behl]
@@ -179,7 +381,7 @@ Verilator 5.048 2026-04-26
 * Fix std::randomize inside {typedef array} internal error (#7481). [Yilou Wang]
 * Fix module parameters not re-evaluated upon instantiation (#7463) (#7477). [em2machine]
 * Fix infinite recursion with VERILATOR_BIN (#7496) (#7497).
-
+* Add error on mixed declaration initialization with continuous assignment (#7352). [Zhi QU]
 
 Verilator 5.046 2026-02-28
 ==========================
@@ -342,7 +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.]
@@ -686,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]
@@ -2342,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
 ==========================
 
@@ -2749,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
 ==========================
 
@@ -5200,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
+	REDIR_SCRATCH=$$(mktemp redir_XXXXXX); \
-	perl -p -i -e 'use File::Spec;' \
+	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.tmp"
+	        -e 's/RELPATH.*/"$$path";/g' -- "${srcdir}/bin/redirect" > $$REDIR_SCRATCH; \
-	cd $(srcdir)/bin; \
 	for p in $(VL_INST_PUBLIC_SCRIPT_FILES) $(VL_INST_PUBLIC_BIN_FILES) ; do \
-		$(INSTALL_PROGRAM) redirect.tmp $(DESTDIR)$(pkgdatadir)/bin/$$p; \
+		$(INSTALL_PROGRAM) $$REDIR_SCRATCH $(DESTDIR)$(pkgdatadir)/bin/$$p; \
-	done
+	done; \
-	rm ${srcdir}/bin/redirect.tmp
+	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
@@ -417,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
@@ -444,7 +443,7 @@ cppcheck:
 CLANGTIDY = clang-tidy
 CLANGTIDY_FLAGS = -config='' \
   -header-filter='.*' \
-  -checks='*,-abseil-*,-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-init-variables,-cppcoreguidelines-avoid-goto,-modernize-avoid-c-arrays,-readability-magic-numbers,-readability-simplify-boolean-expr,-cppcoreguidelines-macro-usage' \
+  -checks='*,-abseil-*,-fuchsia-*,-cppcoreguidelines-avoid-c-arrays,-cppcoreguidelines-avoid-do-while,-cppcoreguidelines-init-variables,-cppcoreguidelines-avoid-goto,-modernize-avoid-c-arrays,-readability-magic-numbers,-readability-simplify-boolean-expr,-cppcoreguidelines-macro-usage' \
 
 # Good checks: -checks='-*,bugprone-assignment-in-if-condition,google-build-using-namespace,google-readability-casting,modernize-use-default-member-init,modernize-use-emplace,modernize-use-equals-default,modernize-use-equals-delete,modernize-use-nullptr,performance-faster-string-find,readability-isolate-declaration,readability-redundant-control-flow,readability-redundant-member-init,readability-redundant-string-cstr,readability-uppercase-literal-suffix
 
@@ -496,6 +495,11 @@ MAKE_FILES = \
   src/Makefile*.in \
   test_regress/Makefile* \
 
+# Markdown
+MD_FILES = \
+  *.md \
+  */*.md \
+
 # Perl programs
 PERL_PROGRAMS = \
   bin/redirect \
@@ -536,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 \
@@ -553,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
@@ -590,6 +602,13 @@ format-make mbake:
 	$(MBAKE) --version
 	$(MBAKE) $(MBAKE_FLAGS) $(MAKE_FILES)
 
+MDFORMAT = mdformat
+MDFORMAT_FLAGS =
+
+format-md:
+	$(MDFORMAT) --version
+	$(MDFORMAT) $(MDFORMAT_FLAGS) $(MD_FILES)
+
 YAPF = yapf
 YAPF_FLAGS = -i --parallel
 
@@ -597,6 +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 =
 
@@ -684,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
+   Github doesn't render images unless absolute URL
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   Do not know of a conditional tag, "only: github" nor "github display" works
-.. 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
 
 |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.**
+   - - **Welcome to Verilator, the fastest Verilog/SystemVerilog simulator.**
-        * Accepts Verilog or SystemVerilog
+          - Accepts Verilog or SystemVerilog
-        * Performs lint code-quality checks
+          - Performs lint code-quality checks
-        * Compiles into multithreaded C++, or SystemC
+          - Compiles into multithreaded C++, or SystemC
-        * Creates JSON to front-end your own tools
+          - Creates JSON to front-end your own tools
      - |Logo|
-   * - |verilator multithreaded performance|
+   - - |verilator multithreaded performance|
      - **Fast**
-        * Outperforms many closed-source commercial simulators
+          - Outperforms many closed-source commercial simulators
-        * Single- and multithreaded output models
+          - Single- and multithreaded output models
-   * - **Widely Used**
+   - - **Widely Used**
-        * Wide industry and academic deployment
+          - Wide industry and academic deployment
-        * Out-of-the-box support from Arm and RISC-V vendor IP
+          - Out-of-the-box support from Arm and RISC-V vendor IP
-        * Over 700 contributors
+          - Over 700 contributors
      - |verilator usage|
-   * - |verilator community|
+   - - |verilator community|
      - **Community Driven & Openly Licensed**
-        * Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
+          - Guided by the `CHIPS Alliance`_ and `Linux Foundation`_
-        * Open, and free as in both speech and beer
+          - Open, and free as in both speech and beer
-        * More simulation for your verification budget
+          - More simulation for your verification budget
-   * - **Commercial Support Available**
+   - - **Commercial Support Available**
-        * Commercial support contracts
+          - Commercial support contracts
-        * Design support contracts
+          - Design support contracts
-        * Enhancement 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",

bin/verilator

@@ -101,9 +101,15 @@ if (defined $ENV{VERILATOR_ROOT}) {
     $ENV{VERILATOR_ROOT} = $verilator_root;
 }
 
-if ($opt_gdbbt && !gdb_works()) {
+my $lldb_selected = 0;
-    warn "-Info: --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
+if (($opt_gdb || $opt_gdbbt) && !gdb_works()) {
+    if (lldb_works()) {
+        $lldb_selected = 1;
+    } else {
+        warn "-Info: --gdb or --gdbbt ignored: gdb doesn't seem to be working\n" if $Debug;
         $opt_gdbbt = 0;
+        $opt_gdb = 0;
+    }
 }
 
 # Determine runtime flags and run
@@ -113,22 +119,35 @@ if ($opt_gdbbt && !gdb_works()) {
 # then see exactly the contents of @Opt_Verilator_Sw.
 my @quoted_sw = map { sh_escape($_) } @Opt_Verilator_Sw;
 if ($opt_gdb) {
+    # 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 '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'");
+    }
 } elsif ($opt_rr) {
     # Record with rr
     run (ulimit_stack_unlimited()
@@ -136,15 +155,27 @@ if ($opt_gdb) {
          . "rr record " . verilator_bin()
          . " " . join(' ', @quoted_sw));
 } elsif ($opt_gdbbt && $Debug) {
-    # Run under GDB to get gdbbt
+    # Run under debugger to get gdbbt
+    if ($lldb_selected) {
         run (ulimit_stack_unlimited()
              . aslr(0)
-         . "gdb"
+             . ($ENV{VERILATOR_GDB} || "lldb")
+             . " " . verilator_bin()
+             . " -o 'b exit'"  # Need break to keep process active for bt
+             . " --batch --source-quietly"
+             . " -o \"run " . join(' ', @quoted_sw)."\""
+             . " -o 'settings set term-width 1024'"
+             . " -o 'bt' -o 'quit'");
+    } else {
+        run (ulimit_stack_unlimited()
+             . aslr(0)
+             . ($ENV{VERILATOR_GDB} || "gdb")
              . " " . verilator_bin()
              . " --batch --quiet --return-child-result"
              . " -ex \"run " . join(' ', @quoted_sw)."\""
              . " -ex 'set width 0'"
              . " -ex 'bt' -ex 'quit'");
+    }
 } elsif ($opt_valgrind) {
     # Run under valgrind
     my $valgrind_bin = ($ENV{VERILATOR_VALGRIND} || "valgrind --error-exitcode=1 --max-stackframe=2815880"
@@ -200,9 +231,9 @@ sub verilator_bin {
 
 sub gdb_works {
     $! = undef;  # Cleanup -x
-    system("gdb /bin/echo"
+    system("gdb /bin/sh"
            . " --batch-silent --quiet --return-child-result"
-           . " -ex 'run -n'"  # `echo -n`
+           . " -ex 'run -c exit'"  # `/bin/sh -c exit
            . " -ex 'set width 0'"
            . " -ex 'bt'"
            . " -ex 'quit'");
@@ -210,6 +241,18 @@ sub gdb_works {
     return $status == 0;
 }
 
+sub lldb_works {
+    $! = undef;  # Cleanup -x
+    # macOS system integrity stops attach to system binaries like /bin/sh
+    system("lldb --version"
+           . " --batch --source-quietly"
+           . " -o 'settings set term-width 1024'"
+           . " -o 'bt'"
+           . " -o 'quit'");
+    my $status = $?;
+    return $status == 0;
+}
+
 sub aslr {
     my $want_on = shift;
     $want_on = $opt_aslr if defined $opt_aslr;
@@ -357,6 +400,7 @@ detailed descriptions of these arguments.
     --no-aslr                   Disable address space layout randomization
     --no-assert                 Disable all assertions
     --no-assert-case            Disable unique/unique0/priority-case assertions
+    --assert-unroll-limit <iter> Max SVA assertion repetition before erroring
     --autoflush                 Flush streams after all $displays
     --bbox-sys                  Blackbox unknown $system calls
     --bbox-unsup                Blackbox unsupported language features
@@ -376,6 +420,7 @@ detailed descriptions of these arguments.
     --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
@@ -393,6 +438,7 @@ detailed descriptions of these arguments.
     --diagnostics-sarif-output <filename>  Set SARIF diagnostics output file
     --dpi-hdr-only              Only produce the DPI header file
     --dump-<srcfile>            Enable dumping everything in source file
+    --dump-ast-patterns         Enable dumping Ast pattern statistics
     --dump-defines              Show preprocessor defines with -E
     --dump-dfg                  Enable dumping DfgGraphs to .dot files
     --dump-dfg-patterns         Enable dumping Dfg pattern statistics
@@ -416,6 +462,8 @@ detailed descriptions of these arguments.
      -f <file>                  Parse arguments from a file
      -FI <file>                 Force include of a file
     --flatten                   Force inlining of all modules, tasks and functions
+    --fourstate                 Enable fourstate logic
+    --no-fourstate              Disable fourstate logic
     --func-recursion-depth <value>  Maximum recursive constant function depth
     --future0 <option>          Ignore an option for compatibility
     --future1 <option>          Ignore an option with argument for compatibility
@@ -593,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
@@ -604,6 +653,7 @@ description of these arguments.
      +verilator+solver+file+<filename>     Set random solver log filename
      +verilator+V                          Show verbose version and config
      +verilator+version                    Show version and exit
+     +verilator+vpi+<library>[:<bootstrap>]  Load VPI shared library
      +verilator+wno+unsatconstr+<value>    Disable constraint warnings
 
 

bin/verilator_coverage

@@ -157,6 +157,10 @@ verilator_coverage - Verilator coverage analyzer
 
     verilator_coverage --annotate <obj>
 
+    verilator_coverage --report summary,hier <datafiles>...
+
+    verilator_coverage --report hier <datafiles>...
+
     verilator_coverage  -write merged.dat <datafiles>...
 
     verilator_coverage  -write-info merged.info <datafiles>...
@@ -176,7 +180,9 @@ L<https://verilator.org/guide/latest/exe_verilator_coverage.html>.
     --filter-type <regex>         Keep only records of given coverage type.
     --help                        Displays this message and version and exits.
     --include-reset-arcs          Include reset arcs in FSM arc summaries.
+    --levels <depth>              Limit displayed hierarchy report depth.
     --rank                        Compute relative importance of tests.
+    --report <kind>[,<kind>...]   Generate reports: summary, hier, or hierarchy.
     --unlink                      With --write, unlink all inputs
     --version                     Displays program version and exits.
     --write <filename>            Write aggregate coverage results.

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
+# Currently this hosts code coverage reports, and PR RTLMeter detailed reports.
-# add any other contents to the page in parallel here.
 
 # 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
+      [[ $EVENT != "pull_request" ]] || PR_RUN_IDS="$PR_RUN_IDS $RUN_ID"
-        if [[ -z "$PR_RUN_IDS" ]]; then
-          PR_RUN_IDS="$RUN_ID"
-        else
-          PR_RUN_IDS="$PR_RUN_IDS,$RUN_ID"
-        fi
-      fi
 
       # 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
+# Populates ${PAGES_ROOT}/rtlmeter-reports
-  echo "coverage-pr-run-ids=${PR_RUN_IDS}" >> $GITHUB_OUTPUT
+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/docker/buildenv/README.rst

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

ci/docker/run/README.rst

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

configure.ac

@@ -12,7 +12,7 @@
 # Then 'make maintainer-dist'
 #AC_INIT([Verilator],[#.### YYYY-MM-DD])
 #AC_INIT([Verilator],[#.### devel])
-AC_INIT([Verilator],[5.048 2026-04-26],
+AC_INIT([Verilator],[5.050 2026-07-01],
         [https://verilator.org],
         [verilator],[https://verilator.org])
 
@@ -421,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)
@@ -580,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)
@@ -589,11 +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"
-  LJEMALLOC="-Wl,--whole-archive -l:libjemalloc.a -Wl,--no-whole-archive"
-else
-  LTCMALLOC=-ltcmalloc_minimal
-  LJEMALLOC=-ljemalloc
 fi
 AC_SUBST(CFG_LDFLAGS_SRC)
 AC_SUBST(CFG_LDFLAGS_VERILATED)
@@ -609,51 +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 jemalloc is available based on --enable-jemalloc
+# Figure out which malloc library to use:
-# jemalloc is preferred over tcmalloc when both are available
+# - Prefer jemalloc over tcmalloc (it's faster)
+# - If partial static link enabled, prefer static libraries,
+#   but fall back on dynamic if static is not available
+
+# Test for jemalloc
 CFG_HAVE_JEMALLOC=no
-_MY_LDLIBS_CHECK_IFELSE(
+if test "$CFG_WITH_JEMALLOC" != "no"; then
-  $LJEMALLOC,
+  if test "$CFG_ENABLE_PARTIAL_STATIC" = "yes"; then
-  [if test "$CFG_WITH_JEMALLOC" != "no"; then
+    _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -Xlinker --whole-archive -l:libjemalloc.a -Xlinker --no-whole-archive)
-    CFG_LIBS="$LJEMALLOC $CFG_LIBS";
+  fi
-    CFG_HAVE_JEMALLOC=yes;
+  _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -ljemalloc)
-    # If using jemalloc, add some extra options to make the compiler not assume
+  if test "$CFG_LIBS_MALLOC" != ""; then
-    # it is using its own versions of the standard library functions
+    CFG_HAVE_JEMALLOC=yes
-    _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)
     AC_DEFINE([HAVE_JEMALLOC],[1],[Defined if have jemalloc])
-   fi],
+  elif test "$CFG_WITH_JEMALLOC" = "yes"; then
-  [if test "$CFG_WITH_JEMALLOC" = "yes"; then
+    AC_MSG_ERROR([--enable-jemalloc was given but jemalloc is not available])
-    AC_MSG_ERROR([--enable-jemalloc was given but test for ${LJEMALLOC} failed])
+  fi
-   fi])
+fi
 AC_SUBST(HAVE_JEMALLOC)
 
-# Check if tcmalloc is available based on --enable-tcmalloc
+# Test for tcmalloc
-# Only use tcmalloc if jemalloc was not found/enabled
-if test "$CFG_HAVE_JEMALLOC" = "yes"; then
-  AC_MSG_NOTICE([jemalloc found, skipping tcmalloc check])
-else
 CFG_HAVE_TCMALLOC=no
-_MY_LDLIBS_CHECK_IFELSE(
+if test "$CFG_HAVE_JEMALLOC" = "yes"; then
-  $LTCMALLOC,
+  AC_MSG_NOTICE([jemalloc found, skipping check for tcmalloc])
-  [if test "$CFG_WITH_TCMALLOC" != "no"; then
+elif test "$CFG_WITH_TCMALLOC" != "no"; then
-    CFG_LIBS="$LTCMALLOC $CFG_LIBS";
+  if test "$CFG_ENABLE_PARTIAL_STATIC" = "yes"; then
-    CFG_HAVE_TCMALLOC=yes;
+    _MY_LDLIBS_CHECK_SET(CFG_LIBS_MALLOC, -Xlinker --whole-archive -l:libtcmalloc_minimal.a -Xlinker --no-whole-archive)
-    # If using tcmalloc, add some extra options to make the compiler not assume
+  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])
+  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)
-    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])
 fi
-AC_SUBST(HAVE_TCMALLOC)
+
+# 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
+Our contributors and participants pledge to make participation in our
-  project and our community a positive experience for everyone. We follow
+project and our community a positive experience for everyone. We follow the
-  the `Contributor Covenant version 1.4
+`Contributor Covenant version 1.4
-  <https://www.contributor-covenant.org/version/1/4/code-of-conduct/>`__.
+<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
@@ -88,6 +96,7 @@ Gökçe Aydos
 Han Qi
 Harald Heckmann
 Hennadii Chernyshchyk
+hjsanjana
 Howard Su
 Huang Rui
 Huanghuang Zhou
@@ -137,6 +146,7 @@ Jose Loyola
 Josep Sans
 Joseph Nwabueze
 Josh Redford
+Joshua Leahy
 Julian Carrier
 Julian Daube
 Julie Schwartz
@@ -150,6 +160,7 @@ Kefa Chen
 Keith Colbert
 Kevin Kiningham
 Kevin Nygaard
+Kornel Uriasz
 Kritik Bhimani
 Krzysztof Bieganski
 Krzysztof Boronski
@@ -160,9 +171,11 @@ Krzysztof Sychla
 Kuba Ober
 Lan Zongwei
 Larry Doolittle
+Laurent CHARRIER
 Leela Pakanati
 Liam Braun
 Luca Colagrande
+Lucas Amaral
 Ludwig Rogiers
 Lukasz Dalek
 M2kar
@@ -185,8 +198,10 @@ 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
@@ -199,6 +214,7 @@ Nathan Graybeal
 Nathan Kohagen
 Nathan Myers
 Nick Brereton
+Nikolai Kumar
 Nikolay Puzanov
 Nolan Poe
 Oleh Maksymenko
@@ -207,6 +223,7 @@ Paul Bowen-Huggett
 Paul Swirhun
 Paul Wright
 Pawel Jewstafjew
+Pawel Klopotek
 Pawel Kojma
 Pawel Sagan
 Pengcheng Xu
@@ -236,9 +253,12 @@ 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
@@ -248,17 +268,21 @@ 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
@@ -280,6 +304,7 @@ Vito Gamberini
 Wei-Lun Chiu
 William D. Jones
 Wilson Snyder
+Wolfgang Mayerwieser
 Xi Zhang
 Yan Xu
 Yangyu Chen
@@ -305,3 +330,8 @@ 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_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/guide/changes.rst

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

docs/guide/connecting.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _connecting:
 
@@ -28,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
+- Accessing any other internal members, including ``/* verilator
-  ``/* verilator public_flat */`` items requires the following changes:
+  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
+Ltd., Hicamp Systems, Intel Corporation, Marvell Inc., Mindspeed
-Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems Inc., Nauticus
+Technologies Inc., MicroTune Inc., picoChip Designs Ltd., Sun Microsystems
-Networks Inc., SiCortex Inc, Shunyao CAD, Tenstorrent USA, Inc. and Western
+Inc., Nauticus Networks Inc., SiCortex Inc, Shunyao CAD, Tenstorrent USA,
-Digital Inc.
+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,
+Pham, Wesley Piard, Maciej Piechotka, David Pierce, Cody Piersall, T.
-T. Platz, Michael Platzer, Dominic Plunkett, Nolan Poe, Tuomas Poikela,
+Platz, Michael Platzer, Dominic Plunkett, Nolan Poe, Tuomas Poikela, George
-George Polack, David Poole, Michael Popoloski, Roman Popov, Aylon Chaim
+Polack, David Poole, Michael Popoloski, Roman Popov, Aylon Chaim Porat,
-Porat, Oron Port, Rich Porter, Rick Porter, Stefan Post, Niranjan Prabhu,
+Oron Port, Rich Porter, Rick Porter, Stefan Post, Niranjan Prabhu, Damien
-Damien Pretet, Harald Pretl, Bill Pringlemeir, Usha Priyadharshini, Mark
+Pretet, Harald Pretl, Bill Pringlemeir, Usha Priyadharshini, Mark Jackson
-Jackson Pulver, Prateek Puri, Nikolay Puzanov, Han Qi, Jiacheng Qian,
+Pulver, Prateek Puri, Nikolay Puzanov, Han Qi, Jiacheng Qian, Marshal Qiao,
-Marshal Qiao, Raynard Qiao, Yujia Qiao, Jasen Qin, Frank Qiu, Nandu Raj,
+Raynard Qiao, Yujia Qiao, Jasen Qin, Frank Qiu, Nandu Raj, Kamil Rakoczy,
-Kamil Rakoczy, Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh
+Danilo Ramos, Drew Ranck, Chris Randall, Anton Rapp, Josh Redford, Odd
-Redford, Odd Magne Reitan, Frédéric Requin, Wajahat Riaz, Dustin Richmond,
+Magne Reitan, Frédéric Requin, Wajahat Riaz, Dustin Richmond, Samuel
-Samuel Riedel, Alberto Del Rio, Eric Rippey, Narcis Rodas, Oleg Rodionov,
+Riedel, Alberto Del Rio, Eric Rippey, Narcis Rodas, Oleg Rodionov, Ludwig
-Ludwig Rogiers, Paul Rolfe, Michail Rontionov, Arjen Roodselaar, Arthur
+Rogiers, Paul Rolfe, Michail Rontionov, Arjen Roodselaar, Arthur Rosa,
-Rosa, Tobias Rosenkranz, Yernagula Roshit, Diego Roux, Ryszard Rozak, Dan
+Tobias Rosenkranz, Yernagula Roshit, Diego Roux, Ryszard Rozak, Dan
 Ruelas-Petrisko, Luca Rufer, Huang Rui, Graham Rushton, Jan Egil Ruud,
 Denis Rystsov, Pawel Sagan, Robert Sammelson, Adrian Sampson, John
 Sanguinetti, Josep Sans, Dave Sargeant, Luca Sasselli, Philippe Sauter,

docs/guide/control.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _verilator control files:
 
@@ -100,6 +101,27 @@ The grammar of control commands is as follows:
 
    Same as :option:`/*verilator&32;forceable*/` metacomment.
 
+.. option:: fsm_register_wrapper -module "<modulename>" -d "<port>" -q "<port>" -clock "<port>" [-reset "<port>"] [-reset_value "<param>"]
+
+   Declares that the specified module is a transparent FSM state-register
+   wrapper for FSM coverage extraction. One declaration applies to all
+   instances of that module.
+
+   The ``-d`` option names the wrapper input port carrying next-state data.
+   The ``-q`` option names the wrapper output port carrying registered state.
+   The ``-clock`` option names the wrapper clock port.
+
+   Verilator does not infer wrapper semantics from module or port naming
+   conventions. A wrapper module must be declared with this option before
+   Verilator will use instances of it to extract FSM state and transition
+   coverage.
+
+   The ``-reset`` and ``-reset_value`` options are optional. Reset arcs are
+   emitted only when both the reset polarity can be inferred from the
+   wrapper's event control and ``-reset_value`` names a static parameter value.
+   If reset metadata is incomplete, Verilator may still emit FSM state and
+   transition coverage without reset arcs.
+
 .. option:: full_case -file "<filename>" -lines <lineno>
 
    Same as ``//synthesis full_case``. When these synthesis directives
@@ -166,6 +188,10 @@ The grammar of control commands is as follows:
 
 .. option:: isolate_assignments -module "<modulename>" [-task "<taskname>"] -var "<signame>"
 
+   Deprecated and has no effect (ignored).
+
+   In versions before 5.050:
+
    Used to indicate that the assignments to this signal in any blocks
    should be isolated into new blocks. Same as
    :option:`/*verilator&32;isolate_assignments*/` metacomment.

docs/guide/copyright.rst

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

docs/guide/deprecations.rst

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

docs/guide/environment.rst

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

docs/guide/example_binary.rst

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

docs/guide/example_cc.rst

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

docs/guide/example_common_install.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 First you need Verilator installed, see :ref:`Installation`. In brief, if
 you installed Verilator using the package manager of your operating system,

docs/guide/example_dist.rst

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

docs/guide/example_sc.rst

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

docs/guide/examples.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _examples:
 
@@ -9,10 +10,10 @@ Examples
 
 This section covers the following examples:
 
-* :ref:`Example Create-Binary Execution`
+- :ref:`Example Create-Binary Execution`
-* :ref:`Example C++ Execution`
+- :ref:`Example C++ Execution`
-* :ref:`Example SystemC Execution`
+- :ref:`Example SystemC Execution`
-* :ref:`Examples in the Distribution`
+- :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,11 @@ 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
+   simulation runtime random seed value. If not specified, the seed
-   value from the system random number generator.
+   defaults to 1. If specified as 0, a non-zero seed is generated at
+   startup; the picked value is exposed through ``$get_initial_random_seed``
+   so the run can be reproduced later by passing
+   ``+verilator+seed+<that_value>``.
 
 .. option:: +verilator+solver+file+<filename>
 
@@ -130,6 +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
@@ -308,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`.
@@ -320,8 +344,8 @@ Summary:
 
 .. option:: --coverage-user
 
-   Enables adding user-inserted functional coverage. See :ref:`User
+   Enables adding user-inserted functional covergroup coverage. See
-   Coverage`.
+   :ref:`Covergroup Coverage`.
 
 .. option:: -D<var>=<value>
 
@@ -467,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
@@ -634,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
@@ -714,12 +762,41 @@ Summary:
    this is not recommended as may cause additional warnings and ordering
    issues.
 
+.. option:: -fno-ico-change-detect
+
+   Rarely needed. Disable input change detection in the input combinational
+   ('ico') region. With change detection enabled (the default, unless
+   :vlopt:`--vpi` is passed), the input combinational logic is evaluated only
+   when a top level input has actually changed, rather than unconditionally on
+   the first scheduling iteration.
+
+   The change detection logic assumes a top level input only ever changes
+   externally between evaluations. The optimization is automatically disabled
+   for top level input signals that are written within the design. Accesses via
+   the VPI cannot be analyzed at compile time, therefore :vlopt:`--vpi`
+   disables this optimization for all inputs; it may be turned back on by
+   explicitly passing :vlopt:`-fico-change-detect <-fno-ico-change-detect>`.
+
 .. option:: -fno-inline
 
+   Rarely needed. Disable module inlining.
+
+.. option:: -fno-inline-cfuncs
+
+   Rarely needed. Disable inlining of small generated C++ functions into their
+   callers.
+
+   This optimization is automatically disabled when :vlopt:`--prof-cfuncs` is
+   used.
+
 .. option:: -fno-inline-funcs
 
+   Rarely needed. Disable inlining of SystemVerilog functions and tasks.
+
 .. option:: -fno-inline-funcs-eager
 
+   Rarely needed. Disable eager inlining of SystemVerilog functions and tasks.
+
 .. option:: -fno-life
 
 .. option:: -fno-life-post
@@ -758,6 +835,14 @@ Summary:
    automatically. Variables explicitly annotated with
    :option:`/*verilator&32;split_var*/` are still split.
 
+.. option:: --fourstate
+
+   Enables four-state logic support. Experimental, for developer use only.
+
+.. option:: --no-fourstate
+
+   Disables four-state logic support which is the default. Exists for forward compatibility.
+
 .. option:: --fslice-element-limit
 
    Rarely needed. Set the maximum array size (number of elements) for slice
@@ -913,27 +998,21 @@ Summary:
 
 .. option:: --inline-cfuncs <value>
 
-   Inline small C++ function (internal AstCFunc) calls directly into their
+   Tune the inlining of small generated C++ function. Functions no bigger than
-   callers when the function has at most <value> nodes. This reduces
+   <value> nodes will be inlined if possible. The default is 20.
-   function call overhead when :vlopt:`--output-split-cfuncs` places
-   functions in separate compilation units that the C++ compiler cannot
-   inline.
 
-   Set to 0 to disable this optimization. The default is 20.
+   See also :vlopt:`--inline-cfuncs-product` and :vlopt:`-fno-inline-cfuncs`.
-
-   This optimization is automatically disabled when :vlopt:`--prof-cfuncs`
-   or :vlopt:`--trace` is used.
 
 .. option:: --inline-cfuncs-product <value>
 
-   Tune the inlining of C++ function (internal AstCFunc) calls for larger
+   Tune the inlining of small generated C++ function. If a function's node
-   functions. When a function is too large to always inline (exceeds
+   count multiplied by the number of calls is not bigger than <value>, the
-   :vlopt:`--inline-cfuncs` threshold), it may still be inlined if the
+   function will be inlined if possible.
-   function size multiplied by the number of call sites is at most <value>.
 
-   This allows functions that are called only once or twice to be inlined
+   This allows functions that are called only once or twice to be inlined even
-   even if they exceed the small function threshold. Set to 0 to only inline
+   if they exceed the small function threshold. The default is 200.
-   functions below the :vlopt:`--inline-cfuncs` threshold. The default is 200.
+
+   See also :vlopt:`--inline-cfuncs` and :vlopt:`-fno-inline-cfuncs`.
 
 .. option:: --inline-mult <value>
 

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

docs/guide/exe_verilator_gantt.rst

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

docs/guide/exe_verilator_profcfunc.rst

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

docs/guide/executables.rst

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

docs/guide/extensions.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 ===================
 Language Extensions
@@ -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
+   - - *{prefix}*\ __hier.dir
-     - Directory to store .dot, .vpp, .tree of top module (from --hierarchical)
+     - 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
+   - - coverage.dat
-     - Code coverage output, and default input filename for :command:`verilator_coverage`
+     - Code coverage output, and default input filename for
-   * - gmon.out
+       :command:`verilator_coverage`
-     - GCC/clang code profiler output, often fed into :command:`verilator_profcfunc`
+   - - gmon.out
-   * - profile.vlt
+     - 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/.
+#. Install Python for your platform from https://www.python.org/downloads/.
-2. Install CMake for your platform from https://cmake.org/download/ or
+#. 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.

docs/guide/install.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 .. _installation:
 
@@ -64,7 +65,7 @@ In brief, to install from git:
    #sudo apt-get install libgoogle-perftools-dev libjemalloc-dev numactl perl-doc
    #sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
    #sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
-   #sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)
+   #sudo apt-get install zlibc zlib1g zlib1g-dev liblz4 liblz4-dev  # Ubuntu only (ignore if gives error)
 
    git clone https://github.com/verilator/verilator   # Only first time
 
@@ -116,7 +117,7 @@ To build or run Verilator, you need these standard packages:
    sudo apt-get install libgz  # Non-Ubuntu (ignore if gives error)
    sudo apt-get install libfl2  # Ubuntu only (ignore if gives error)
    sudo apt-get install libfl-dev  # Ubuntu only (ignore if gives error)
-   sudo apt-get install zlibc zlib1g zlib1g-dev  # Ubuntu only (ignore if gives error)
+   sudo apt-get install zlibc zlib1g zlib1g-dev liblz4 liblz4-dev  # Ubuntu only (ignore if gives error)
 
 For SystemC:
 
@@ -170,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,
+- delay statements,
-* event control statements not only at the top of a process,
+- event control statements not only at the top of a process,
-* intra-assignment timing controls,
+- intra-assignment timing controls,
-* net delays,
+- net delays,
-* ``wait`` statements,
+- ``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
+- delay statements - they are ignored (as they are in synthesis), though
-  do issue a :option:`STMTDLY` warning,
+  they do issue a :option:`STMTDLY` warning,
-* intra-assignment timing controls - they are ignored, though they do issue
+- intra-assignment timing controls - they are ignored, though they do issue
   an :option:`ASSIGNDLY` warning,
-* net delays - they are ignored,
+- net delays - they are ignored,
-* event controls at the top of the procedure,
+- event controls at the top of the procedure,
 
 Forks cause this error as well, except:
 
-* forks with no statements,
+- forks with no statements,
-* ``fork..join`` or ``fork..join_any`` with one statement,
+- ``fork..join`` or ``fork..join_any`` with one statement,
-* forks with :vlopt:`--bbox-unsup`.
+- 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,
+- forks with no statements,
-* ``fork..join`` or ``fork..join_any`` with one statement,
+- ``fork..join`` or ``fork..join_any`` with one statement,
-* forks with :vlopt:`--bbox-unsup`.
+- 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
+Verilator partially supports assertions and assertion-driven functional
-only converts assertions to simple ``if (...) error`` statements, and
+coverage.
-coverage statements to increment the line counters described in the
-coverage section.
 
-Verilator does not support SEREs yet. All assertion and coverage statements
+Coverage
-must be simple expressions that complete in one cycle.
+--------
+
+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
+.. [#] SystemVerilog is defined by the `Institute of Electrical and Electronics
-   Electronics Engineers (IEEE) Standard for SystemVerilog - Unified
+   Engineers (IEEE) Standard for SystemVerilog - Unified Hardware Design,
-   Hardware Design, Specification, and Verification Language`, Standard
+   Specification, and Verification Language`, Standard 1800, released in
-   1800, released in 2005, 2009, 2012, 2017, and 2023. The Verilator
+   2005, 2009, 2012, 2017, and 2023. The Verilator documentation uses the
-   documentation uses the shorthand e.g., "IEEE 1800-2023", to refer to
+   shorthand e.g., "IEEE 1800-2023", to refer to the, e.g., 2023 version of
-   the, e.g., 2023 version of this standard.
+   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,8 @@ Verilator supports adding code to the Verilated model to support
 SystemVerilog code coverage. With :vlopt:`--coverage`, Verilator enables
 all forms of coverage:
 
-- :ref:`User Coverage`
+- :ref:`Property Coverage`
+- :ref:`Covergroup Coverage`
 - :ref:`FSM Coverage`
 - :ref:`Line Coverage`
 - :ref:`Toggle Coverage`
@@ -193,30 +195,43 @@ When a model with coverage is executed, it will create a coverage file for
 collection and later analysis, see :ref:`Coverage Collection`.
 
 
-.. _user coverage:
+.. _property coverage:
 
-Functional Coverage
+Property Coverage
--------------------
+-----------------
 
 With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
-translate functional coverage points the user has inserted manually in
+translate property coverage points the user has inserted manually in
-SystemVerilog code through into the Verilated model.
+SystemVerilog code into the Verilated model.
 
-For example, the following SystemVerilog statement will add a coverage
+For simple coverage points, use the ``cover property`` construct:
-point under the coverage name "DefaultClock":
 
 .. code-block:: sv
 
    DefaultClock: cover property (@(posedge clk) cyc==3);
 
+This adds a coverage point that tracks whether the condition has been
+observed.
+
+.. _covergroup coverage:
+
+Covergroup Coverage
+-------------------
+
+With :vlopt:`--coverage` or :vlopt:`--coverage-user`, Verilator will
+translate covergroup coverage points the user has inserted manually in
+SystemVerilog code into the Verilated model. Verilator supports coverpoints
+with value and transition bins, and cross points.
+
+
 .. _fsm coverage:
 
 FSM Coverage
 ------------
 
 With :vlopt:`--coverage` or :vlopt:`--coverage-fsm`, Verilator can
-instrument a conservative subset of single-process FSMs and report both
+instrument a conservative subset of FSMs and report both state coverage
-state coverage (`fsm_state`) and transition coverage (`fsm_arc`).
+(`fsm_state`) and transition coverage (`fsm_arc`).
 
 This feature is currently experimental and might change in subsequent
 releases. In particular, the native FSM coverage extraction heuristics,
@@ -224,21 +239,70 @@ releases. In particular, the native FSM coverage extraction heuristics,
 should be treated as subject to change while the interface settles.
 
 FSM extraction is intentionally narrow. The current implementation targets
-clocked, enum-driven state machines that can be recovered directly from the
+clocked state machines that can be recovered directly from the RTL. It
-RTL. It does not claim broad support for two-process FSMs, one-hot
+recognizes scalar enum, parameter, localparam, and selected literal state
-inference, helper-function next-state recovery, or deeply nested control
+encodings in these common forms:
-recovery.
+
+- 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
+- ``/*verilator fsm_state*/`` forces the variable to be treated as FSM
-  FSM state.
+  state.
-- ``/*verilator fsm_reset_arc*/`` marks reset transitions as
+- ``/*verilator fsm_reset_arc*/`` marks reset transitions as user-visible
-  user-visible reset arcs instead of defaulting to a hidden reset-only
+  reset arcs instead of defaulting to a hidden reset-only summary.
-  summary.
+- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch arcs that
-- ``/*verilator fsm_arc_include_cond*/`` keeps conditional branch
+  would otherwise be skipped by the conservative extractor.
-  arcs that would otherwise be skipped by the conservative extractor.
+
+State registers may also be wrapped by a transparent instance, for example
+a project flop wrapper or primitive. Such wrappers must be described
+explicitly with a VLT command file action before Verilator will use their
+data, state, clock, or reset connections for FSM extraction:
+
+.. code-block:: sv
+
+   `verilator_config
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i"
+
+The same command may be placed in a separate ``.vlt`` file:
+
+.. code-block:: sv
+
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i"
+
+Optional reset metadata may also be supplied:
+
+.. code-block:: sv
+
+   fsm_register_wrapper -module "my_fsm_flop" -d "state_i" -q "state_o" -clock "clk_i" \
+      -reset "rst_ni" -reset_value "ResetValue"
+
+Reset arcs are emitted only when the configured reset port has an inferable
+edge in the wrapper and the configured reset value parameter is statically
+resolvable. If reset metadata is incomplete, Verilator warns and may still
+emit FSM state and transition coverage, but reset arcs are omitted.
 
 Reset transitions are included in the collected data either way. By
 default, :command:`verilator_coverage` summarizes reset-only arcs rather
@@ -250,7 +314,6 @@ Annotated output produced by :command:`verilator_coverage --annotate` will
 label FSM points with `fsm_state` and `fsm_arc`, and synthetic fallback
 transitions with `SYNTHETIC DEFAULT ARC`.
 
-
 .. _line coverage:
 
 Line Coverage
@@ -370,11 +433,11 @@ coverage point insertions into the model and collect the coverage data.
 
 To get the coverage data from the model, write the coverage with either:
 
-1. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump
+#. Using :vlopt:`--binary` or :vlopt:`--main`, and Verilator will dump
    coverage when the test completes to the filename specified with
    :vlopt:`+verilator+coverage+file+\<filename\>`.
 
-2. In the user wrapper code, typically at the end once a test passes, call
+#. In the user wrapper code, typically at the end once a test passes, call
    ``Verilated::threadContextp()->coveragep()->write`` with an argument of
    the filename for the coverage data file to write coverage data to
    (typically "logs/coverage.dat").
@@ -439,12 +502,12 @@ how execution time is distributed in a verilated model.
 
 With the :vlopt:`--prof-exec` option, Verilator will:
 
-* Add code to the Verilated model to record execution flow.
+- Add code to the Verilated model to record execution flow.
 
-* Add code to save profiling data in non-human-friendly form to the file
+- Add code to save profiling data in non-human-friendly form to the file
   specified with :vlopt:`+verilator+prof+exec+file+\<filename\>`.
 
-* In multithreaded models, add code to record each macro-task's start and
+- In multithreaded models, add code to record each macro-task's start and
   end time across several calls to eval. (What is a macro-task? See the
   Verilator internals document (:file:`docs/internals.rst` in the
   distribution.)
@@ -544,8 +607,8 @@ There are two forms of profile-guided optimizations. Unfortunately, for
 best results, they must each be performed from the highest level code to
 the lowest, which means performing them separately and in this order:
 
-* :ref:`Thread PGO`
+- :ref:`Thread PGO`
-* :ref:`Compiler PGO`
+- :ref:`Compiler PGO`
 
 Other forms of PGO may be supported in the future, such as clock and reset
 toggle rate PGO, branch prediction PGO, statement execution time PGO, or
@@ -611,7 +674,7 @@ multithreaded models.
 Please see the appropriate compiler documentation to use PGO with GCC or
 Clang. The process in GCC 10 was as follows:
 
-1. Compile the Verilated model with the compiler's "-fprofile-generate"
+#. Compile the Verilated model with the compiler's "-fprofile-generate"
    flag:
 
    .. code-block:: bash
@@ -622,10 +685,10 @@ Clang. The process in GCC 10 was as follows:
    Or, if calling make yourself, add -fprofile-generate appropriately to
    your Makefile.
 
-2. Run your simulation. This will create \*.gcda file(s) in the same
+#. Run your simulation. This will create \*.gcda file(s) in the same
    directory as the source files.
 
-3. Recompile the model with -fprofile-use. The compiler will read the
+#. Recompile the model with -fprofile-use. The compiler will read the
    \*.gcda file(s).
 
    For GCC:

docs/guide/verilating.rst

@@ -1,5 +1,6 @@
-.. SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+..
-.. SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+   SPDX-FileCopyrightText: 2003-2026 Wilson Snyder
+   SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
 
 **********
 Verilating
@@ -7,21 +8,21 @@ Verilating
 
 Verilator may be used in five major ways:
 
-* With the :vlopt:`--binary` option, Verilator will translate the design
+- With the :vlopt:`--binary` option, Verilator will translate the design
   into an executable, via generating C++ and compiling it. See
   :ref:`Binary, C++ and SystemC Generation`.
 
-* With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate
+- With the :vlopt:`--cc` or :vlopt:`--sc` options, Verilator will translate
   the design into C++ or SystemC code, respectively. See :ref:`Binary, C++
   and SystemC Generation`.
 
-* With the :vlopt:`--lint-only` option, Verilator will lint the design to
+- With the :vlopt:`--lint-only` option, Verilator will lint the design to
   check for warnings but will not typically create any output files.
 
-* With the :vlopt:`--json-only` option, Verilator will create JSON output
+- With the :vlopt:`--json-only` option, Verilator will create JSON output
   that may be used to feed into other user-designed tools.
 
-* With the :vlopt:`-E` option, Verilator will preprocess the code according
+- With the :vlopt:`-E` option, Verilator will preprocess the code according
   to IEEE preprocessing rules and write the output to standard out. This is
   useful to feed other tools and to debug how "\`define" statements are
   expanded.
@@ -127,9 +128,9 @@ Usage
 Users need to mark one or more moderate-size modules as hierarchy block(s).
 There are two ways to mark a module:
 
-* Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code.
+- Write :option:`/*verilator&32;hier_block*/` metacomment in HDL code.
 
-* Add a :option:`hier_block` line in the :ref:`Verilator Control Files`.
+- Add a :option:`hier_block` line in the :ref:`Verilator Control Files`.
 
 Then pass the :vlopt:`--hierarchical` option to Verilator.
 
@@ -145,28 +146,28 @@ Limitations
 
 Hierarchy blocks have some limitations, including:
 
-* Internals of the hierarchy block cannot be accessed using dot (.) from
+- Internals of the hierarchy block cannot be accessed using dot (.) from
   the upper module(s) or other hierarchy blocks, except that ports of a
   hierarchy block instance can be accessed from the directly enclosing
   nested hierarchy block, or from the top level non-hierarchical portions
   of the design if not a nested hierarchy block.
 
-* Modport cannot be used at the hierarchical block boundary.
+- Modport cannot be used at the hierarchical block boundary.
 
-* The simulation speed is likely not as fast as flat Verilation, in which
+- The simulation speed is likely not as fast as flat Verilation, in which
   all modules are globally scheduled.
 
-* Generated clocks may not work correctly if generated in the hierarchical
+- Generated clocks may not work correctly if generated in the hierarchical
   model and passed into another hierarchical model or the top module.
 
-* Delays are not allowed in hierarchy blocks.
+- Delays are not allowed in hierarchy blocks.
 
 But, the following usage is supported:
 
-* Nested hierarchy blocks. A hierarchy block may instantiate other
+- Nested hierarchy blocks. A hierarchy block may instantiate other
   hierarchy blocks.
 
-* Parameterized hierarchy block. Parameters of a hierarchy block can be
+- Parameterized hierarchy block. Parameters of a hierarchy block can be
   overridden using ``#(.param_name(value))`` construct.
 
 

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 reads a variable before assigning it
-
+   later in the same block. Because statements in a procedural block execute
-   Warns that an ``always_comb`` block has a variable that is set after it
+   in source order, the read observes the variable's previous value for that
-   is used. This may cause simulation-synthesis mismatches, as not all
+   activation. This can imply latch/state-like behavior and is not purely
-   simulators allow this ordering.
+   combinational.
 
    .. code-block:: sv
 
       always_comb begin
-        a = b;
+        y = a + tmp;  // Reads the previous value of tmp
-        b = 1;
+        tmp = b;
       end
 
-   Ignoring this warning will only suppress the lint check; it will
+   If the new value of ``tmp`` is intended, assign ``tmp`` before reading it.
-   simulate correctly.
+   Suppressing this warning may make results vary between simulators.
 
 
 .. option:: ALWNEVER
@@ -382,6 +383,9 @@ List Of Warnings
    non-enumerated values (IEEE 1800-2023 12.5.3). Verilator checks that
    illegal values are not hit, unless :vlopt:`--no-assert-case` was used.
 
+   Unique0 case statements will never cause this warning. (Although unique0
+   should be avoided in synthesizable code as may result in latch behavior.)
+
    Ignoring this warning will only suppress the lint check; it will
    simulate correctly.
 
@@ -521,6 +525,48 @@ List Of Warnings
    Suppressing this error will suppress the error message check; it will
    simulate as if the ``const`` as not present.
 
+.. option:: CONTASSINIT
+
+   Error that a continuous assignment is setting a variable with an initial
+   value. Use either the initial value or the continuous assignment, but not
+   both.
+
+   For example:
+
+   .. code-block:: sv
+      :emphasize-lines: 2,4
+
+      module t;
+        logic b = 1'b0;
+        logic a;
+        assign b = a; //<--- Error
+      endmodule
+
+   Results in:
+
+   .. code-block::
+
+      %Error-CONTASSINIT: example.sv:4:10: Continuous assignment to variable with initial value: 'b'
+                                                  : ... note: In instance 't'
+                                                  : ... Location of variable initialization
+          2 |   logic b = 1'b0;
+            |         ^
+                            example.sv:4:10: ... Location of continuous assignment
+          4 |   assign b = a;
+            |          ^
+      %Error: Exiting due to 1 error(s)
+
+   The following is legal because the driven variable does not have a declaration
+   initializer:
+
+   .. code-block:: sv
+
+      module t;
+        logic b;
+        logic a = 1'b0;
+        assign b = a;
+      endmodule
+
 
 .. option:: CONTASSREG
 
@@ -837,6 +883,22 @@ List Of Warnings
    with a newline."
 
 
+.. option:: FINALDLY
+
+   Error issued when a non-blocking assignment `<=` is used in a
+   `final` block.
+
+   This error can be disabled. If disabled, the assignment will be
+   executed as a `=` blocking assignment.
+
+   Faulty example:
+
+   .. include:: ../../docs/gen/ex_FINALDLY_faulty.rst
+
+   Results in:
+
+   .. include:: ../../docs/gen/ex_FINALDLY_msg.rst
+
 .. option:: FSMMULTI
 
    Warns that the same always block contains multiple enum-typed case
@@ -956,6 +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
@@ -1126,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.
@@ -1359,9 +1431,11 @@ List Of Warnings
 
 .. option:: MULTIDRIVEN
 
-   Warns that the specified signal comes from multiple ``always``
+   Warns that the specified signal has multiple procedural drivers.
-   blocks, each with different clocking. This warning does not look at
+
-   individual bits (see the example below).
+   One case is when the signal comes from multiple ``always`` blocks,
+   each with different clocking. This warning does not look at individual
+   bits (see the example below).
 
    This is considered bad style, as the consumer of a given signal may be
    unaware of the inconsistent clocking, causing clock domain crossing
@@ -1375,8 +1449,28 @@ List Of Warnings
 
    .. include:: ../../docs/gen/ex_MULTIDRIVEN_msg.rst
 
-   Ignoring this warning will only slow simulations; it will simulate
+   Another case is when a variable written in an ``always_comb`` or
-   correctly. It may, however, cause longer simulation runtimes due to
+   ``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.
 
 
@@ -1504,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
@@ -1724,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.
 
@@ -2264,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.

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``.
 
 
@@ -666,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.
 
@@ -732,24 +732,24 @@ 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
+- ``_timing_ready()``, which commits all coroutines whose triggers were not
-  not set in the current iteration,
+  set in the current iteration,
-* ``_timing_resume()``, which calls `resume()` on all trigger and delay
+- ``_timing_resume()``, which calls `resume()` on all trigger and delay
   schedulers whose triggers were set in the current iteration.
 
 Thanks to this separation a coroutine:
 
-* awaiting a trigger cannot be suspended and resumed in the same iteration
+- awaiting a trigger cannot be suspended and resumed in the same iteration
   (``test_regress/t/t_timing_eval_act.v``) - which is necessary to make
   Verilator more predictable; this is the reason for introduction of 3rd
   stage in `VlTriggerScheduler` and thanks to this it is guaranteed that
   downstream logic will be evaluated before resumption (assuming that the
   coroutine wasn't already triggered in previous iteration);
-* cannot be resumed before it is suspended -
+- cannot be resumed before it is suspended -
   ``test_regress/t/t_event_control_double_excessive.v``;
-* firing cannot cannot be lost
+- firing cannot cannot be lost
-  (``test_regress/t/t_event_control_double_lost.v``) - which is possible when
+  (``test_regress/t/t_event_control_double_lost.v``) - which is possible
-  triggers are not evaluated right before awaiting.
+  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
+variable. The variables in a given module have a set of footprints. We
-order those footprints to minimize the distance between them (distance is
+group variables with identical non-empty footprints, emit those groups in
-the number of macro-tasks that are different across any two footprints) and
+deterministic footprint-key order, then emit variables with no footprint
-then emit all variables into the struct in ordered-footprint order.
+information last.
 
-The footprint ordering is literally the traveling salesman problem, and we
+The first emitted variable in each footprint group is aligned to a
-use a TSP-approximation algorithm to get close to an optimal sort.
+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
@@ -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
 -------
 
@@ -2099,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.
@@ -2177,30 +2204,65 @@ When the bisection ends, the first value that makes the discriminator
 command fail is printed, which identifies the exact offending application
 of the transform.
 
+Debugging Non-Deterministic Results
+-----------------------------------
+
+The Verilator binary should be deterministic, producing the same Verilated
+C++ and stdout when run multiple times with the same inputs. A common
+source of non-determinism is (mis-)use of pointers in container
+comparisons, causing arbitrary changes im memory layout to make container
+comparisons differ, and in turn creating differences in Ast layout, and
+ultimately different C++ code.
+
+To debug this, compile Verilator with the `VL_ALLOC_RANDOM_CHECKS` define,
+then Verilator may be run with a seed e.g. `-debug-alloc-random 22` and
+`-debug-alloc-random 33` which will randomly change the memory allocation
+order. If multiple seeds are run, `verilator_difftree` may then be used to
+see where netlists start to differ. Once the Ast difference is determined,
+the debugging tips above can then further isolate the C++ code causing a
+specific node to be created or changed.
+
+The typical fix is to add a comparison operator to the problematic
+container, e.g. compare using `AstNodeComparator` or by `name()`.
+
+The following script is an example of this debugging:
+
+.. code-block:: bash
+
+   # Before this: ./configure CXX="g++ -DVL_ALLOC_RANDOM_CHECKS" && make -j
+   # Example script for finding nondeterminism
+   cd $VERILATOR_ROOT
+   set -e
+   t=t_split_var_0  # Test name
+   test_regress/t/$t.py --debug --debug-alloc-random 33 --dumpi-tree 9 --obj-suffix .33
+   test_regress/t/$t.py --debug --debug-alloc-random 66 --dumpi-tree 9 --obj-suffix .66
+   bin/verilator_difftree test_regress/obj_vlt/$t{.33,.66} | grep -v CFILE | grep -v "^ " | grep -v /tmp | grep -v @@
+
+
 Adding a New Feature
 ====================
 
 Generally, what would you do to add a new feature?
 
-1. File an issue (if there isn't already) so others know what you're
+#. File an issue (if there isn't already) so others know what you're
    working on.
 
-2. Make a testcase in the test_regress/t/t_EXAMPLE format, see `Testing`.
+#. Make a testcase in the test_regress/t/t_EXAMPLE format, see `Testing`.
 
-3. If grammar changes are needed, look at the IEEE 1800-2023 Appendix A, as
+#. If grammar changes are needed, look at the IEEE 1800-2023 Appendix A, as
    src/verilog.y generally follows the same rule layout.
 
-4. If a new Ast type is needed, add it to the appropriate V3AstNode*.h.
+#. If a new Ast type is needed, add it to the appropriate V3AstNode*.h.
    Follow the convention described above about the AstNode type hierarchy.
    Ordering of definitions is enforced by ``astgen``.
 
-5. Now you can run ``test_regress/t/t_<newtestcase>.py --debug`` and it'll
+#. Now you can run ``test_regress/t/t_<newtestcase>.py --debug`` and it'll
    probably fail, but you'll see a
    ``test_regress/obj_dir/t_<newtestcase>/*.tree`` file which you can
    examine to see if the parsing worked. See also the sections above on
    debugging.
 
-6. Modify the later visitor functions to process the new feature as needed.
+#. Modify the later visitor functions to process the new feature as needed.
 
 
 Adding a New Pass
@@ -2243,9 +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
 ===========
@@ -2689,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
 ============
 

docs/security.rst

@@ -1,6 +1,7 @@
-.. for github, vim: syntax=reStructuredText
+..
-.. SPDX-FileCopyrightText: 2025-2026 Wilson Snyder
+   for github, vim: syntax=reStructuredText
-.. SPDX-License-Identifier: CC0-1.0
+   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
@@ -429,6 +430,7 @@ Sasselli
 Sauter
 Scharrer
 Schless
+Secturion
 Seitz
 Shahid
 Shahrestani
@@ -579,6 +581,7 @@ Yujia
 Yurii
 Zaruba
 Zhang
+Zhi
 abirkmanis
 accessor
 accessors
@@ -667,6 +670,7 @@ concatenatable
 concats
 conf
 config
+consequents
 const
 constexpr
 constification
@@ -680,6 +684,8 @@ countones
 cout
 covergroup
 covergroups
+coverpoint
+coverpoints
 cpp
 cppstyle
 cpu
@@ -698,6 +704,7 @@ datafiles
 david
 ddd
 de
+dearray
 deassign
 debugi
 defenv
@@ -855,6 +862,7 @@ hx
 hyperthreading
 hyperthreads
 icecream
+ico
 idmap
 ifdef
 ifdefed
@@ -864,6 +872,7 @@ impot
 incdir
 includer
 incrementing
+inferable
 inferfaces
 informationals
 inhibitSim
@@ -899,6 +908,7 @@ libext
 libgoogle
 libjemalloc
 liblist
+liblz
 libsystemc
 libtcmalloc
 libverilated
@@ -908,6 +918,8 @@ linters
 linux
 liu
 livelock
+liveness
+lldb
 ln
 loc
 localparam
@@ -915,6 +927,7 @@ localparams
 localtime
 logicals
 longint
+lookups
 lossy
 lsb
 lubc
@@ -1114,6 +1127,7 @@ specparam
 splitme
 spp
 sqrt
+srand
 srandom
 src
 srcdir
@@ -1194,6 +1208,7 @@ typename
 uint
 un
 unbased
+unclocked
 uncomment
 undef
 undefineall
@@ -1209,6 +1224,7 @@ unnamedblk
 unopt
 unoptflat
 unoptimizable
+unparenthesized
 unroller
 unsatisfiable
 unsized

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 <johnjohnlys@gmail.com>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <lc85301@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <lc85301@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <lc85301@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <lc85301@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <lc85301@gmail.com>
+// 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 <johnjohnlys@gmail.com>
+// SPDX-FileCopyrightText: 2025-2026 Yoda Lee <lc85301@gmail.com>
+// 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 (ariya@kde.org)
-  Copyright (C) 2006 Ariya Hidayat (ariya@kde.org)
-  Copyright (C) 2005 Ariya Hidayat (ariya@kde.org)
-
-  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 (ariya@kde.org)
-  Copyright (C) 2006 Ariya Hidayat (ariya@kde.org)
-  Copyright (C) 2005 Ariya Hidayat (ariya@kde.org)
-
-  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 */

include/gtkwave/fst_config.h

@@ -1,12 +0,0 @@
-// This file specifically for FST usage
-// Originally generated from config.h.in by configure.
-// SPDX-FileCopyrightText: 2018-2026 Wilson Snyder
-// SPDX-License-Identifier: CC0-1.0
-
-/* Define to 1 if you have <alloca.h> and it should be used (not on Ultrix). */
-#if !defined(__MINGW32__) && !defined(__FreeBSD__)
-# define HAVE_ALLOCA_H 1
-#endif
-
-/* Define to 1 if fseeko (and presumably ftello) exists and is declared. */
-#define HAVE_FSEEKO 1

include/gtkwave/fst_win_unistd.h

@@ -1,52 +0,0 @@
-/*
- * Copyright (c) 2009-2018 Tony Bybell.
- *
- * 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 WIN_UNISTD_H
-#define WIN_UNISTD_H
-
-#include <stdlib.h>
-#ifdef _WIN64
-#include <io.h>
-#else
-#include <sys/io.h>
-#endif
-
-#include <process.h>
-
-#define ftruncate _chsize_s
-#define unlink _unlink
-#define fileno _fileno
-#define lseek _lseeki64
-
-#ifdef _WIN64
-#define ssize_t __int64
-#define SSIZE_MAX 9223372036854775807i64
-#else
-#define ssize_t long
-#define SSIZE_MAX 2147483647L
-#endif
-
-#include "stdint.h"
-
-#endif //WIN_UNISTD_H

include/gtkwave/fstapi.h

@@ -1,548 +0,0 @@
-/*
- * Copyright (c) 2009-2026 Tony Bybell.
- *
- * 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 FST_API_H
-#define FST_API_H
-
-#ifdef __cplusplus
-extern "C"
-{
-#endif
-
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include <ctype.h>
-#include <zlib.h>
-#include <inttypes.h>
-#if defined(_MSC_VER)
-#include "fst_win_unistd.h"
-#else
-#include <unistd.h>
-#endif
-#include <time.h>
-
-typedef uint32_t fstHandle;
-typedef uint32_t fstEnumHandle;
-
-enum fstWriterPackType
-{
-    FST_WR_PT_ZLIB = 0,
-    FST_WR_PT_FASTLZ = 1,
-    FST_WR_PT_LZ4 = 2
-};
-
-enum fstFileType
-{
-    FST_FT_MIN = 0,
-
-    FST_FT_VERILOG = 0,
-    FST_FT_VHDL = 1,
-    FST_FT_VERILOG_VHDL = 2,
-
-    FST_FT_MAX = 2
-};
-
-enum fstBlockType
-{
-    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, /* indicates that whole trace is gz wrapped */
-    FST_BL_SKIP = 255 /* used while block is being written */
-};
-
-enum fstScopeType
-{
-    FST_ST_MIN = 0,
-
-    FST_ST_VCD_MODULE = 0,
-    FST_ST_VCD_TASK = 1,
-    FST_ST_VCD_FUNCTION = 2,
-    FST_ST_VCD_BEGIN = 3,
-    FST_ST_VCD_FORK = 4,
-    FST_ST_VCD_GENERATE = 5,
-    FST_ST_VCD_STRUCT = 6,
-    FST_ST_VCD_UNION = 7,
-    FST_ST_VCD_CLASS = 8,
-    FST_ST_VCD_INTERFACE = 9,
-    FST_ST_VCD_PACKAGE = 10,
-    FST_ST_VCD_PROGRAM = 11,
-
-    FST_ST_VHDL_ARCHITECTURE = 12,
-    FST_ST_VHDL_PROCEDURE = 13,
-    FST_ST_VHDL_FUNCTION = 14,
-    FST_ST_VHDL_RECORD = 15,
-    FST_ST_VHDL_PROCESS = 16,
-    FST_ST_VHDL_BLOCK = 17,
-    FST_ST_VHDL_FOR_GENERATE = 18,
-    FST_ST_VHDL_IF_GENERATE = 19,
-    FST_ST_VHDL_GENERATE = 20,
-    FST_ST_VHDL_PACKAGE = 21,
-
-    FST_ST_SV_ARRAY = 22,
-    FST_ST_MAX = 22,
-
-    FST_ST_GEN_ATTRBEGIN = 252,
-    FST_ST_GEN_ATTREND = 253,
-
-    FST_ST_VCD_SCOPE = 254,
-    FST_ST_VCD_UPSCOPE = 255
-};
-
-enum fstVarType
-{
-    FST_VT_MIN = 0, /* start of vartypes */
-
-    FST_VT_VCD_EVENT = 0,
-    FST_VT_VCD_INTEGER = 1,
-    FST_VT_VCD_PARAMETER = 2,
-    FST_VT_VCD_REAL = 3,
-    FST_VT_VCD_REAL_PARAMETER = 4,
-    FST_VT_VCD_REG = 5,
-    FST_VT_VCD_SUPPLY0 = 6,
-    FST_VT_VCD_SUPPLY1 = 7,
-    FST_VT_VCD_TIME = 8,
-    FST_VT_VCD_TRI = 9,
-    FST_VT_VCD_TRIAND = 10,
-    FST_VT_VCD_TRIOR = 11,
-    FST_VT_VCD_TRIREG = 12,
-    FST_VT_VCD_TRI0 = 13,
-    FST_VT_VCD_TRI1 = 14,
-    FST_VT_VCD_WAND = 15,
-    FST_VT_VCD_WIRE = 16,
-    FST_VT_VCD_WOR = 17,
-    FST_VT_VCD_PORT = 18,
-    FST_VT_VCD_SPARRAY = 19, /* used to define the rownum (index) port for a sparse array */
-    FST_VT_VCD_REALTIME = 20,
-
-    FST_VT_GEN_STRING = 21, /* generic string type   (max len is defined dynamically via
-                                fstWriterEmitVariableLengthValueChange) */
-
-    FST_VT_SV_BIT = 22,
-    FST_VT_SV_LOGIC = 23,
-    FST_VT_SV_INT = 24, /* declare as size = 32 */
-    FST_VT_SV_SHORTINT = 25, /* declare as size = 16 */
-    FST_VT_SV_LONGINT = 26, /* declare as size = 64 */
-    FST_VT_SV_BYTE = 27, /* declare as size = 8  */
-    FST_VT_SV_ENUM = 28, /* declare as appropriate type range */
-    FST_VT_SV_SHORTREAL = 29, /* declare and emit same as FST_VT_VCD_REAL (needs to be emitted
-                                    as double, not a float) */
-
-    FST_VT_MAX = 29 /* end of vartypes */
-};
-
-enum fstVarDir
-{
-    FST_VD_MIN = 0,
-
-    FST_VD_IMPLICIT = 0,
-    FST_VD_INPUT = 1,
-    FST_VD_OUTPUT = 2,
-    FST_VD_INOUT = 3,
-    FST_VD_BUFFER = 4,
-    FST_VD_LINKAGE = 5,
-
-    FST_VD_MAX = 5
-};
-
-enum fstHierType
-{
-    FST_HT_MIN = 0,
-
-    FST_HT_SCOPE = 0,
-    FST_HT_UPSCOPE = 1,
-    FST_HT_VAR = 2,
-    FST_HT_ATTRBEGIN = 3,
-    FST_HT_ATTREND = 4,
-
-    /* FST_HT_TREEBEGIN and FST_HT_TREEEND are not yet used by FST but are currently used when
-        fstHier bridges other formats */
-    FST_HT_TREEBEGIN = 5,
-    FST_HT_TREEEND = 6,
-
-    FST_HT_MAX = 6
-};
-
-enum fstAttrType
-{
-    FST_AT_MIN = 0,
-
-    FST_AT_MISC = 0, /* self-contained: does not need matching FST_HT_ATTREND */
-    FST_AT_ARRAY = 1,
-    FST_AT_ENUM = 2,
-    FST_AT_PACK = 3,
-
-    FST_AT_MAX = 3
-};
-
-enum fstMiscType
-{
-    FST_MT_MIN = 0,
-
-    FST_MT_COMMENT = 0, /* use fstWriterSetComment() to emit */
-    FST_MT_ENVVAR = 1, /* use fstWriterSetEnvVar() to emit */
-    FST_MT_SUPVAR = 2, /* use fstWriterCreateVar2() to emit */
-    FST_MT_PATHNAME = 3, /* reserved for fstWriterSetSourceStem() string -> number management */
-    FST_MT_SOURCESTEM = 4, /* use fstWriterSetSourceStem() to emit */
-    FST_MT_SOURCEISTEM = 5, /* use fstWriterSetSourceInstantiationStem() to emit */
-    FST_MT_VALUELIST =
-        6, /* use fstWriterSetValueList() to emit, followed by fstWriterCreateVar*() */
-    FST_MT_ENUMTABLE =
-        7, /* use fstWriterCreateEnumTable() and fstWriterEmitEnumTableRef() to emit */
-    FST_MT_UNKNOWN = 8,
-
-    FST_MT_MAX = 8
-};
-
-enum fstArrayType
-{
-    FST_AR_MIN = 0,
-
-    FST_AR_NONE = 0,
-    FST_AR_UNPACKED = 1,
-    FST_AR_PACKED = 2,
-    FST_AR_SPARSE = 3,
-
-    FST_AR_MAX = 3
-};
-
-enum fstEnumValueType
-{
-    FST_EV_SV_INTEGER = 0,
-    FST_EV_SV_BIT = 1,
-    FST_EV_SV_LOGIC = 2,
-    FST_EV_SV_INT = 3,
-    FST_EV_SV_SHORTINT = 4,
-    FST_EV_SV_LONGINT = 5,
-    FST_EV_SV_BYTE = 6,
-    FST_EV_SV_UNSIGNED_INTEGER = 7,
-    FST_EV_SV_UNSIGNED_BIT = 8,
-    FST_EV_SV_UNSIGNED_LOGIC = 9,
-    FST_EV_SV_UNSIGNED_INT = 10,
-    FST_EV_SV_UNSIGNED_SHORTINT = 11,
-    FST_EV_SV_UNSIGNED_LONGINT = 12,
-    FST_EV_SV_UNSIGNED_BYTE = 13,
-
-    FST_EV_REG = 14,
-    FST_EV_TIME = 15,
-
-    FST_EV_MAX = 15
-};
-
-enum fstPackType
-{
-    FST_PT_NONE = 0,
-    FST_PT_UNPACKED = 1,
-    FST_PT_PACKED = 2,
-    FST_PT_TAGGED_PACKED = 3,
-
-    FST_PT_MAX = 3
-};
-
-enum fstSupplementalVarType
-{
-    FST_SVT_MIN = 0,
-
-    FST_SVT_NONE = 0,
-
-    FST_SVT_VHDL_SIGNAL = 1,
-    FST_SVT_VHDL_VARIABLE = 2,
-    FST_SVT_VHDL_CONSTANT = 3,
-    FST_SVT_VHDL_FILE = 4,
-    FST_SVT_VHDL_MEMORY = 5,
-
-    FST_SVT_MAX = 5
-};
-
-enum fstSupplementalDataType
-{
-    FST_SDT_MIN = 0,
-
-    FST_SDT_NONE = 0,
-
-    FST_SDT_VHDL_BOOLEAN = 1,
-    FST_SDT_VHDL_BIT = 2,
-    FST_SDT_VHDL_BIT_VECTOR = 3,
-    FST_SDT_VHDL_STD_ULOGIC = 4,
-    FST_SDT_VHDL_STD_ULOGIC_VECTOR = 5,
-    FST_SDT_VHDL_STD_LOGIC = 6,
-    FST_SDT_VHDL_STD_LOGIC_VECTOR = 7,
-    FST_SDT_VHDL_UNSIGNED = 8,
-    FST_SDT_VHDL_SIGNED = 9,
-    FST_SDT_VHDL_INTEGER = 10,
-    FST_SDT_VHDL_REAL = 11,
-    FST_SDT_VHDL_NATURAL = 12,
-    FST_SDT_VHDL_POSITIVE = 13,
-    FST_SDT_VHDL_TIME = 14,
-    FST_SDT_VHDL_CHARACTER = 15,
-    FST_SDT_VHDL_STRING = 16,
-
-    FST_SDT_MAX = 16,
-
-    FST_SDT_SVT_SHIFT_COUNT = 10, /* FST_SVT_* is ORed in by fstWriterCreateVar2() to the left
-                                        after shifting FST_SDT_SVT_SHIFT_COUNT */
-    FST_SDT_ABS_MAX = ((1 << (FST_SDT_SVT_SHIFT_COUNT)) - 1)
-};
-
-struct fstHier
-{
-    unsigned char htyp;
-
-    union
-    {
-        /* if htyp == FST_HT_SCOPE */
-        struct fstHierScope
-        {
-            unsigned char typ; /* FST_ST_MIN ... FST_ST_MAX */
-            const char *name;
-            const char *component;
-            uint32_t name_length; /* strlen(u.scope.name) */
-            uint32_t component_length; /* strlen(u.scope.component) */
-        } scope;
-
-        /* if htyp == FST_HT_VAR */
-        struct fstHierVar
-        {
-            unsigned char typ; /* FST_VT_MIN ... FST_VT_MAX */
-            unsigned char direction; /* FST_VD_MIN ... FST_VD_MAX */
-            unsigned char svt_workspace; /* zeroed out by FST reader, for client code use */
-            unsigned char sdt_workspace; /* zeroed out by FST reader, for client code use */
-            unsigned int sxt_workspace; /* zeroed out by FST reader, for client code use */
-            const char *name;
-            uint32_t length;
-            fstHandle handle;
-            uint32_t name_length; /* strlen(u.var.name) */
-            unsigned is_alias : 1;
-        } var;
-
-        /* if htyp == FST_HT_ATTRBEGIN */
-        struct fstHierAttr
-        {
-            unsigned char typ; /* FST_AT_MIN ... FST_AT_MAX */
-            unsigned char
-                subtype; /* from fstMiscType, fstArrayType, fstEnumValueType, fstPackType */
-            const char *name;
-            uint64_t arg; /* number of array elements, struct members, or some other payload
-                                (possibly ignored) */
-            uint64_t arg_from_name; /* for when name is overloaded as a variable-length integer
-                                        (FST_AT_MISC + FST_MT_SOURCESTEM) */
-            uint32_t name_length; /* strlen(u.attr.name) */
-        } attr;
-    } u;
-};
-
-struct fstETab
-{
-    char *name;
-    uint32_t elem_count;
-    char **literal_arr;
-    char **val_arr;
-};
-
-/*
- * writer functions
- */
-
-typedef struct fstWriterContext fstWriterContext;
-
-void fstWriterClose(fstWriterContext *ctx);
-fstWriterContext *fstWriterCreate(const char *nam, int use_compressed_hier);
-fstEnumHandle fstWriterCreateEnumTable(fstWriterContext *ctx,
-                                        const char *name,
-                                        uint32_t elem_count,
-                                        unsigned int min_valbits,
-                                        const char **literal_arr,
-                                        const char **val_arr);
-/* used for Verilog/SV */
-fstHandle fstWriterCreateVar(fstWriterContext *ctx,
-                                enum fstVarType vt,
-                                enum fstVarDir vd,
-                                uint32_t len,
-                                const char *nam,
-                                fstHandle aliasHandle);
-/* future expansion for VHDL and other languages.  The variable type, data type, etc map onto
-    the current Verilog/SV one.  The "type" string is optional for a more verbose or custom
-    description */
-fstHandle fstWriterCreateVar2(fstWriterContext *ctx,
-                                enum fstVarType vt,
-                                enum fstVarDir vd,
-                                uint32_t len,
-                                const char *nam,
-                                fstHandle aliasHandle,
-                                const char *type,
-                                enum fstSupplementalVarType svt,
-                                enum fstSupplementalDataType sdt);
-void fstWriterEmitDumpActive(fstWriterContext *ctx, int enable);
-void fstWriterEmitEnumTableRef(fstWriterContext *ctx, fstEnumHandle handle);
-void fstWriterEmitValueChange(fstWriterContext *ctx, fstHandle handle, const void *val);
-void fstWriterEmitValueChange32(fstWriterContext *ctx,
-                                fstHandle handle,
-                                uint32_t bits,
-                                uint32_t val);
-void fstWriterEmitValueChange64(fstWriterContext *ctx,
-                                fstHandle handle,
-                                uint32_t bits,
-                                uint64_t val);
-void fstWriterEmitValueChangeVec32(fstWriterContext *ctx,
-                                    fstHandle handle,
-                                    uint32_t bits,
-                                    const uint32_t *val);
-void fstWriterEmitValueChangeVec64(fstWriterContext *ctx,
-                                    fstHandle handle,
-                                    uint32_t bits,
-                                    const uint64_t *val);
-void fstWriterEmitVariableLengthValueChange(fstWriterContext *ctx,
-                                            fstHandle handle,
-                                            const void *val,
-                                            uint32_t len);
-void fstWriterEmitTimeChange(fstWriterContext *ctx, uint64_t tim);
-void fstWriterFlushContext(fstWriterContext *ctx);
-int fstWriterGetDumpSizeLimitReached(fstWriterContext *ctx);
-int fstWriterGetFseekFailed(fstWriterContext *ctx);
-int fstWriterGetFlushContextPending(fstWriterContext *ctx);
-void fstWriterSetAttrBegin(fstWriterContext *ctx,
-                            enum fstAttrType attrtype,
-                            int subtype,
-                            const char *attrname,
-                            uint64_t arg);
-void fstWriterSetAttrEnd(fstWriterContext *ctx);
-void fstWriterSetComment(fstWriterContext *ctx, const char *comm);
-void fstWriterSetDate(fstWriterContext *ctx, const char *dat);
-void fstWriterSetDumpSizeLimit(fstWriterContext *ctx, uint64_t numbytes);
-void fstWriterSetEnvVar(fstWriterContext *ctx, const char *envvar);
-void fstWriterSetFileType(fstWriterContext *ctx, enum fstFileType filetype);
-void fstWriterSetPackType(fstWriterContext *ctx, enum fstWriterPackType typ);
-void fstWriterSetParallelMode(fstWriterContext *ctx, int enable);
-void fstWriterSetRepackOnClose(fstWriterContext *ctx,
-                                int enable); /* type = 0 (none), 1 (libz) */
-void fstWriterSetScope(fstWriterContext *ctx,
-                        enum fstScopeType scopetype,
-                        const char *scopename,
-                        const char *scopecomp);
-void fstWriterSetSourceInstantiationStem(fstWriterContext *ctx,
-                                            const char *path,
-                                            unsigned int line,
-                                            unsigned int use_realpath);
-void fstWriterSetSourceStem(fstWriterContext *ctx,
-                            const char *path,
-                            unsigned int line,
-                            unsigned int use_realpath);
-void fstWriterSetTimescale(fstWriterContext *ctx, int ts);
-void fstWriterSetTimescaleFromString(fstWriterContext *ctx, const char *s);
-void fstWriterSetTimezero(fstWriterContext *ctx, int64_t tim);
-void fstWriterSetUpscope(fstWriterContext *ctx);
-void fstWriterSetValueList(fstWriterContext *ctx, const char *vl);
-void fstWriterSetVersion(fstWriterContext *ctx, const char *vers);
-
-/*
- * reader functions
- */
-
-typedef struct fstReaderContext fstReaderContext;
-
-void fstReaderClose(fstReaderContext *ctx);
-void fstReaderClrFacProcessMask(fstReaderContext *ctx, fstHandle facidx);
-void fstReaderClrFacProcessMaskAll(fstReaderContext *ctx);
-uint64_t fstReaderGetAliasCount(fstReaderContext *ctx);
-const char *fstReaderGetCurrentFlatScope(fstReaderContext *ctx);
-void *fstReaderGetCurrentScopeUserInfo(fstReaderContext *ctx);
-int fstReaderGetCurrentScopeLen(fstReaderContext *ctx);
-const char *fstReaderGetDateString(fstReaderContext *ctx);
-int fstReaderGetDoubleEndianMatchState(fstReaderContext *ctx);
-uint64_t fstReaderGetDumpActivityChangeTime(fstReaderContext *ctx, uint32_t idx);
-unsigned char fstReaderGetDumpActivityChangeValue(fstReaderContext *ctx, uint32_t idx);
-uint64_t fstReaderGetEndTime(fstReaderContext *ctx);
-int fstReaderGetFacProcessMask(fstReaderContext *ctx, fstHandle facidx);
-int fstReaderGetFileType(fstReaderContext *ctx);
-int fstReaderGetFseekFailed(fstReaderContext *ctx);
-fstHandle fstReaderGetMaxHandle(fstReaderContext *ctx);
-uint64_t fstReaderGetMemoryUsedByWriter(fstReaderContext *ctx);
-uint32_t fstReaderGetNumberDumpActivityChanges(fstReaderContext *ctx);
-uint64_t fstReaderGetScopeCount(fstReaderContext *ctx);
-uint64_t fstReaderGetStartTime(fstReaderContext *ctx);
-signed char fstReaderGetTimescale(fstReaderContext *ctx);
-int64_t fstReaderGetTimezero(fstReaderContext *ctx);
-uint64_t fstReaderGetValueChangeSectionCount(fstReaderContext *ctx);
-char *fstReaderGetValueFromHandleAtTime(fstReaderContext *ctx,
-                                        uint64_t tim,
-                                        fstHandle facidx,
-                                        char *buf);
-uint64_t fstReaderGetVarCount(fstReaderContext *ctx);
-const char *fstReaderGetVersionString(fstReaderContext *ctx);
-struct fstHier *fstReaderIterateHier(fstReaderContext *ctx);
-int fstReaderIterateHierRewind(fstReaderContext *ctx);
-int fstReaderIterBlocks(fstReaderContext *ctx,
-                        void (*value_change_callback)(void *user_callback_data_pointer,
-                                                      uint64_t time,
-                                                      fstHandle facidx,
-                                                      const unsigned char *value),
-                        void *user_callback_data_pointer,
-                        FILE *vcdhandle);
-int fstReaderIterBlocks2(fstReaderContext *ctx,
-                         void (*value_change_callback)(void *user_callback_data_pointer,
-                                                       uint64_t time,
-                                                       fstHandle facidx,
-                                                       const unsigned char *value),
-                         void (*value_change_callback_varlen)(void *user_callback_data_pointer,
-                                                              uint64_t time,
-                                                              fstHandle facidx,
-                                                              const unsigned char *value,
-                                                              uint32_t len),
-                         void *user_callback_data_pointer,
-                         FILE *vcdhandle);
-void fstReaderIterBlocksSetNativeDoublesOnCallback(fstReaderContext *ctx, int enable);
-fstReaderContext *fstReaderOpen(const char *nam);
-fstReaderContext *fstReaderOpenForUtilitiesOnly(void);
-const char *fstReaderPopScope(fstReaderContext *ctx);
-int fstReaderProcessHier(fstReaderContext *ctx, FILE *vcdhandle);
-const char *fstReaderPushScope(fstReaderContext *ctx, const char *nam, void *user_info);
-void fstReaderResetScope(fstReaderContext *ctx);
-void fstReaderSetFacProcessMask(fstReaderContext *ctx, fstHandle facidx);
-void fstReaderSetFacProcessMaskAll(fstReaderContext *ctx);
-void fstReaderSetLimitTimeRange(fstReaderContext *ctx, uint64_t start_time, uint64_t end_time);
-void fstReaderSetUnlimitedTimeRange(fstReaderContext *ctx);
-void fstReaderSetVcdExtensions(fstReaderContext *ctx, int enable);
-
-/*
- * utility functions
- */
-int fstUtilityBinToEscConvertedLen(const unsigned char *s, int len); /* used for mallocs for fstUtilityBinToEsc() */
-int fstUtilityBinToEsc(unsigned char *d, const unsigned char *s, int len);
-int fstUtilityEscToBin(unsigned char *d, unsigned char *s, int len);
-struct fstETab *fstUtilityExtractEnumTableFromString(const char *s);
-void fstUtilityFreeEnumTable(struct fstETab *etab); /* must use to free fstETab properly */
-
-#ifdef __cplusplus
-}
-#endif
-
-#endif

include/gtkwave/lz4.h

@@ -1,868 +0,0 @@
-/*
- *  LZ4 - Fast LZ compression algorithm
- *  Header File
- *  Copyright (C) 2011-2023, Yann Collet.
-
-   BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php)
-
-   Redistribution and use in source and binary forms, with or without
-   modification, are permitted provided that the following conditions are
-   met:
-
-       * Redistributions of source code must retain the above copyright
-   notice, this list of conditions and the following disclaimer.
-       * 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
-   OWNER 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.
-
-   You can contact the author at :
-    - LZ4 homepage : http://www.lz4.org
-    - LZ4 source repository : https://github.com/lz4/lz4
-*/
-#if defined (__cplusplus)
-extern "C" {
-#endif
-
-#ifndef LZ4_H_2983827168210
-#define LZ4_H_2983827168210
-
-/* --- Dependency --- */
-#include <stddef.h>   /* size_t */
-
-
-/**
-  Introduction
-
-  LZ4 is lossless compression algorithm, providing compression speed >500 MB/s per core,
-  scalable with multi-cores CPU. It features an extremely fast decoder, with speed in
-  multiple GB/s per core, typically reaching RAM speed limits on multi-core systems.
-
-  The LZ4 compression library provides in-memory compression and decompression functions.
-  It gives full buffer control to user.
-  Compression can be done in:
-    - a single step (described as Simple Functions)
-    - a single step, reusing a context (described in Advanced Functions)
-    - unbounded multiple steps (described as Streaming compression)
-
-  lz4.h generates and decodes LZ4-compressed blocks (doc/lz4_Block_format.md).
-  Decompressing such a compressed block requires additional metadata.
-  Exact metadata depends on exact decompression function.
-  For the typical case of LZ4_decompress_safe(),
-  metadata includes block's compressed size, and maximum bound of decompressed size.
-  Each application is free to encode and pass such metadata in whichever way it wants.
-
-  lz4.h only handle blocks, it can not generate Frames.
-
-  Blocks are different from Frames (doc/lz4_Frame_format.md).
-  Frames bundle both blocks and metadata in a specified manner.
-  Embedding metadata is required for compressed data to be self-contained and portable.
-  Frame format is delivered through a companion API, declared in lz4frame.h.
-  The `lz4` CLI can only manage frames.
-*/
-
-/*^***************************************************************
-*  Export parameters
-*****************************************************************/
-/*
-*  LZ4_DLL_EXPORT :
-*  Enable exporting of functions when building a Windows DLL
-*  LZ4LIB_VISIBILITY :
-*  Control library symbols visibility.
-*/
-#ifndef LZ4LIB_VISIBILITY
-#  if defined(__GNUC__) && (__GNUC__ >= 4)
-#    define LZ4LIB_VISIBILITY __attribute__ ((visibility ("default")))
-#  else
-#    define LZ4LIB_VISIBILITY
-#  endif
-#endif
-#if defined(LZ4_DLL_EXPORT) && (LZ4_DLL_EXPORT==1)
-#  define LZ4LIB_API __declspec(dllexport) LZ4LIB_VISIBILITY
-#elif defined(LZ4_DLL_IMPORT) && (LZ4_DLL_IMPORT==1)
-#  define LZ4LIB_API __declspec(dllimport) LZ4LIB_VISIBILITY /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/
-#else
-#  define LZ4LIB_API LZ4LIB_VISIBILITY
-#endif
-
-/*! LZ4_FREESTANDING :
- *  When this macro is set to 1, it enables "freestanding mode" that is
- *  suitable for typical freestanding environment which doesn't support
- *  standard C library.
- *
- *  - LZ4_FREESTANDING is a compile-time switch.
- *  - It requires the following macros to be defined:
- *    LZ4_memcpy, LZ4_memmove, LZ4_memset.
- *  - It only enables LZ4/HC functions which don't use heap.
- *    All LZ4F_* functions are not supported.
- *  - See tests/freestanding.c to check its basic setup.
- */
-#if defined(LZ4_FREESTANDING) && (LZ4_FREESTANDING == 1)
-#  define LZ4_HEAPMODE 0
-#  define LZ4HC_HEAPMODE 0
-#  define LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION 1
-#  if !defined(LZ4_memcpy)
-#    error "LZ4_FREESTANDING requires macro 'LZ4_memcpy'."
-#  endif
-#  if !defined(LZ4_memset)
-#    error "LZ4_FREESTANDING requires macro 'LZ4_memset'."
-#  endif
-#  if !defined(LZ4_memmove)
-#    error "LZ4_FREESTANDING requires macro 'LZ4_memmove'."
-#  endif
-#elif ! defined(LZ4_FREESTANDING)
-#  define LZ4_FREESTANDING 0
-#endif
-
-
-/*------   Version   ------*/
-#define LZ4_VERSION_MAJOR    1    /* for breaking interface changes  */
-#define LZ4_VERSION_MINOR    9    /* for new (non-breaking) interface capabilities */
-#define LZ4_VERSION_RELEASE  5    /* for tweaks, bug-fixes, or development */
-
-#define LZ4_VERSION_NUMBER (LZ4_VERSION_MAJOR *100*100 + LZ4_VERSION_MINOR *100 + LZ4_VERSION_RELEASE)
-
-#define LZ4_LIB_VERSION LZ4_VERSION_MAJOR.LZ4_VERSION_MINOR.LZ4_VERSION_RELEASE
-#define LZ4_QUOTE(str) #str
-#define LZ4_EXPAND_AND_QUOTE(str) LZ4_QUOTE(str)
-#define LZ4_VERSION_STRING LZ4_EXPAND_AND_QUOTE(LZ4_LIB_VERSION)  /* requires v1.7.3+ */
-
-LZ4LIB_API int LZ4_versionNumber (void);  /**< library version number; useful to check dll version; requires v1.3.0+ */
-LZ4LIB_API const char* LZ4_versionString (void);   /**< library version string; useful to check dll version; requires v1.7.5+ */
-
-
-/*-************************************
-*  Tuning memory usage
-**************************************/
-/*!
- * LZ4_MEMORY_USAGE :
- * Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB)
- * Increasing memory usage improves compression ratio, generally at the cost of speed.
- * Reduced memory usage may improve speed at the cost of ratio, thanks to better cache locality.
- * Default value is 14, for 16KB, which nicely fits into most L1 caches.
- */
-#ifndef LZ4_MEMORY_USAGE
-# define LZ4_MEMORY_USAGE LZ4_MEMORY_USAGE_DEFAULT
-#endif
-
-#define LZ4_MEMORY_USAGE_MIN 10
-#define LZ4_MEMORY_USAGE_DEFAULT 14
-#define LZ4_MEMORY_USAGE_MAX 20
-
-#if (LZ4_MEMORY_USAGE < LZ4_MEMORY_USAGE_MIN)
-#  error "LZ4_MEMORY_USAGE is too small !"
-#endif
-
-#if (LZ4_MEMORY_USAGE > LZ4_MEMORY_USAGE_MAX)
-#  error "LZ4_MEMORY_USAGE is too large !"
-#endif
-
-/*-************************************
-*  Simple Functions
-**************************************/
-/*! LZ4_compress_default() :
- *  Compresses 'srcSize' bytes from buffer 'src'
- *  into already allocated 'dst' buffer of size 'dstCapacity'.
- *  Compression is guaranteed to succeed if 'dstCapacity' >= LZ4_compressBound(srcSize).
- *  It also runs faster, so it's a recommended setting.
- *  If the function cannot compress 'src' into a more limited 'dst' budget,
- *  compression stops *immediately*, and the function result is zero.
- *  In which case, 'dst' content is undefined (invalid).
- *      srcSize : max supported value is LZ4_MAX_INPUT_SIZE.
- *      dstCapacity : size of buffer 'dst' (which must be already allocated)
- *     @return  : the number of bytes written into buffer 'dst' (necessarily <= dstCapacity)
- *                or 0 if compression fails
- * Note : This function is protected against buffer overflow scenarios (never writes outside 'dst' buffer, nor read outside 'source' buffer).
- */
-LZ4LIB_API int LZ4_compress_default(const char* src, char* dst, int srcSize, int dstCapacity);
-
-/*! LZ4_decompress_safe() :
- * @compressedSize : is the exact complete size of the compressed block.
- * @dstCapacity : is the size of destination buffer (which must be already allocated),
- *                presumed an upper bound of decompressed size.
- * @return : the number of bytes decompressed into destination buffer (necessarily <= dstCapacity)
- *           If destination buffer is not large enough, decoding will stop and output an error code (negative value).
- *           If the source stream is detected malformed, the function will stop decoding and return a negative result.
- * Note 1 : This function is protected against malicious data packets :
- *          it will never writes outside 'dst' buffer, nor read outside 'source' buffer,
- *          even if the compressed block is maliciously modified to order the decoder to do these actions.
- *          In such case, the decoder stops immediately, and considers the compressed block malformed.
- * Note 2 : compressedSize and dstCapacity must be provided to the function, the compressed block does not contain them.
- *          The implementation is free to send / store / derive this information in whichever way is most beneficial.
- *          If there is a need for a different format which bundles together both compressed data and its metadata, consider looking at lz4frame.h instead.
- */
-LZ4LIB_API int LZ4_decompress_safe (const char* src, char* dst, int compressedSize, int dstCapacity);
-
-
-/*-************************************
-*  Advanced Functions
-**************************************/
-#define LZ4_MAX_INPUT_SIZE        0x7E000000   /* 2 113 929 216 bytes */
-#define LZ4_COMPRESSBOUND(isize)  ((unsigned)(isize) > (unsigned)LZ4_MAX_INPUT_SIZE ? 0 : (isize) + ((isize)/255) + 16)
-
-/*! LZ4_compressBound() :
-    Provides the maximum size that LZ4 compression may output in a "worst case" scenario (input data not compressible)
-    This function is primarily useful for memory allocation purposes (destination buffer size).
-    Macro LZ4_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example).
-    Note that LZ4_compress_default() compresses faster when dstCapacity is >= LZ4_compressBound(srcSize)
-        inputSize  : max supported value is LZ4_MAX_INPUT_SIZE
-        return : maximum output size in a "worst case" scenario
-              or 0, if input size is incorrect (too large or negative)
-*/
-LZ4LIB_API int LZ4_compressBound(int inputSize);
-
-/*! LZ4_compress_fast() :
-    Same as LZ4_compress_default(), but allows selection of "acceleration" factor.
-    The larger the acceleration value, the faster the algorithm, but also the lesser the compression.
-    It's a trade-off. It can be fine tuned, with each successive value providing roughly +~3% to speed.
-    An acceleration value of "1" is the same as regular LZ4_compress_default()
-    Values <= 0 will be replaced by LZ4_ACCELERATION_DEFAULT (currently == 1, see lz4.c).
-    Values > LZ4_ACCELERATION_MAX will be replaced by LZ4_ACCELERATION_MAX (currently == 65537, see lz4.c).
-*/
-LZ4LIB_API int LZ4_compress_fast (const char* src, char* dst, int srcSize, int dstCapacity, int acceleration);
-
-
-/*! LZ4_compress_fast_extState() :
- *  Same as LZ4_compress_fast(), using an externally allocated memory space for its state.
- *  Use LZ4_sizeofState() to know how much memory must be allocated,
- *  and allocate it on 8-bytes boundaries (using `malloc()` typically).
- *  Then, provide this buffer as `void* state` to compression function.
- */
-LZ4LIB_API int LZ4_sizeofState(void);
-LZ4LIB_API int LZ4_compress_fast_extState (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration);
-
-/*! LZ4_compress_destSize() :
- *  Reverse the logic : compresses as much data as possible from 'src' buffer
- *  into already allocated buffer 'dst', of size >= 'dstCapacity'.
- *  This function either compresses the entire 'src' content into 'dst' if it's large enough,
- *  or fill 'dst' buffer completely with as much data as possible from 'src'.
- *  note: acceleration parameter is fixed to "default".
- *
- * *srcSizePtr : in+out parameter. Initially contains size of input.
- *               Will be modified to indicate how many bytes where read from 'src' to fill 'dst'.
- *               New value is necessarily <= input value.
- * @return : Nb bytes written into 'dst' (necessarily <= dstCapacity)
- *           or 0 if compression fails.
- *
- * Note : from v1.8.2 to v1.9.1, this function had a bug (fixed in v1.9.2+):
- *        the produced compressed content could, in specific circumstances,
- *        require to be decompressed into a destination buffer larger
- *        by at least 1 byte than the content to decompress.
- *        If an application uses `LZ4_compress_destSize()`,
- *        it's highly recommended to update liblz4 to v1.9.2 or better.
- *        If this can't be done or ensured,
- *        the receiving decompression function should provide
- *        a dstCapacity which is > decompressedSize, by at least 1 byte.
- *        See https://github.com/lz4/lz4/issues/859 for details
- */
-LZ4LIB_API int LZ4_compress_destSize(const char* src, char* dst, int* srcSizePtr, int targetDstSize);
-
-/*! LZ4_decompress_safe_partial() :
- *  Decompress an LZ4 compressed block, of size 'srcSize' at position 'src',
- *  into destination buffer 'dst' of size 'dstCapacity'.
- *  Up to 'targetOutputSize' bytes will be decoded.
- *  The function stops decoding on reaching this objective.
- *  This can be useful to boost performance
- *  whenever only the beginning of a block is required.
- *
- * @return : the number of bytes decoded in `dst` (necessarily <= targetOutputSize)
- *           If source stream is detected malformed, function returns a negative result.
- *
- *  Note 1 : @return can be < targetOutputSize, if compressed block contains less data.
- *
- *  Note 2 : targetOutputSize must be <= dstCapacity
- *
- *  Note 3 : this function effectively stops decoding on reaching targetOutputSize,
- *           so dstCapacity is kind of redundant.
- *           This is because in older versions of this function,
- *           decoding operation would still write complete sequences.
- *           Therefore, there was no guarantee that it would stop writing at exactly targetOutputSize,
- *           it could write more bytes, though only up to dstCapacity.
- *           Some "margin" used to be required for this operation to work properly.
- *           Thankfully, this is no longer necessary.
- *           The function nonetheless keeps the same signature, in an effort to preserve API compatibility.
- *
- *  Note 4 : If srcSize is the exact size of the block,
- *           then targetOutputSize can be any value,
- *           including larger than the block's decompressed size.
- *           The function will, at most, generate block's decompressed size.
- *
- *  Note 5 : If srcSize is _larger_ than block's compressed size,
- *           then targetOutputSize **MUST** be <= block's decompressed size.
- *           Otherwise, *silent corruption will occur*.
- */
-LZ4LIB_API int LZ4_decompress_safe_partial (const char* src, char* dst, int srcSize, int targetOutputSize, int dstCapacity);
-
-
-/*-*********************************************
-*  Streaming Compression Functions
-***********************************************/
-typedef union LZ4_stream_u LZ4_stream_t;  /* incomplete type (defined later) */
-
-/*!
- Note about RC_INVOKED
-
- - RC_INVOKED is predefined symbol of rc.exe (the resource compiler which is part of MSVC/Visual Studio).
-   https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros
-
- - Since rc.exe is a legacy compiler, it truncates long symbol (> 30 chars)
-   and reports warning "RC4011: identifier truncated".
-
- - To eliminate the warning, we surround long preprocessor symbol with
-   "#if !defined(RC_INVOKED) ... #endif" block that means
-   "skip this block when rc.exe is trying to read it".
-*/
-#if !defined(RC_INVOKED) /* https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros */
-#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION)
-LZ4LIB_API LZ4_stream_t* LZ4_createStream(void);
-LZ4LIB_API int           LZ4_freeStream (LZ4_stream_t* streamPtr);
-#endif /* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */
-#endif
-
-/*! LZ4_resetStream_fast() : v1.9.0+
- *  Use this to prepare an LZ4_stream_t for a new chain of dependent blocks
- *  (e.g., LZ4_compress_fast_continue()).
- *
- *  An LZ4_stream_t must be initialized once before usage.
- *  This is automatically done when created by LZ4_createStream().
- *  However, should the LZ4_stream_t be simply declared on stack (for example),
- *  it's necessary to initialize it first, using LZ4_initStream().
- *
- *  After init, start any new stream with LZ4_resetStream_fast().
- *  A same LZ4_stream_t can be re-used multiple times consecutively
- *  and compress multiple streams,
- *  provided that it starts each new stream with LZ4_resetStream_fast().
- *
- *  LZ4_resetStream_fast() is much faster than LZ4_initStream(),
- *  but is not compatible with memory regions containing garbage data.
- *
- *  Note: it's only useful to call LZ4_resetStream_fast()
- *        in the context of streaming compression.
- *        The *extState* functions perform their own resets.
- *        Invoking LZ4_resetStream_fast() before is redundant, and even counterproductive.
- */
-LZ4LIB_API void LZ4_resetStream_fast (LZ4_stream_t* streamPtr);
-
-/*! LZ4_loadDict() :
- *  Use this function to reference a static dictionary into LZ4_stream_t.
- *  The dictionary must remain available during compression.
- *  LZ4_loadDict() triggers a reset, so any previous data will be forgotten.
- *  The same dictionary will have to be loaded on decompression side for successful decoding.
- *  Dictionary are useful for better compression of small data (KB range).
- *  While LZ4 itself accepts any input as dictionary, dictionary efficiency is also a topic.
- *  When in doubt, employ the Zstandard's Dictionary Builder.
- *  Loading a size of 0 is allowed, and is the same as reset.
- * @return : loaded dictionary size, in bytes (note: only the last 64 KB are loaded)
- */
-LZ4LIB_API int LZ4_loadDict (LZ4_stream_t* streamPtr, const char* dictionary, int dictSize);
-
-/*! LZ4_compress_fast_continue() :
- *  Compress 'src' content using data from previously compressed blocks, for better compression ratio.
- * 'dst' buffer must be already allocated.
- *  If dstCapacity >= LZ4_compressBound(srcSize), compression is guaranteed to succeed, and runs faster.
- *
- * @return : size of compressed block
- *           or 0 if there is an error (typically, cannot fit into 'dst').
- *
- *  Note 1 : Each invocation to LZ4_compress_fast_continue() generates a new block.
- *           Each block has precise boundaries.
- *           Each block must be decompressed separately, calling LZ4_decompress_*() with relevant metadata.
- *           It's not possible to append blocks together and expect a single invocation of LZ4_decompress_*() to decompress them together.
- *
- *  Note 2 : The previous 64KB of source data is __assumed__ to remain present, unmodified, at same address in memory !
- *
- *  Note 3 : When input is structured as a double-buffer, each buffer can have any size, including < 64 KB.
- *           Make sure that buffers are separated, by at least one byte.
- *           This construction ensures that each block only depends on previous block.
- *
- *  Note 4 : If input buffer is a ring-buffer, it can have any size, including < 64 KB.
- *
- *  Note 5 : After an error, the stream status is undefined (invalid), it can only be reset or freed.
- */
-LZ4LIB_API int LZ4_compress_fast_continue (LZ4_stream_t* streamPtr, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration);
-
-/*! LZ4_saveDict() :
- *  If last 64KB data cannot be guaranteed to remain available at its current memory location,
- *  save it into a safer place (char* safeBuffer).
- *  This is schematically equivalent to a memcpy() followed by LZ4_loadDict(),
- *  but is much faster, because LZ4_saveDict() doesn't need to rebuild tables.
- * @return : saved dictionary size in bytes (necessarily <= maxDictSize), or 0 if error.
- */
-LZ4LIB_API int LZ4_saveDict (LZ4_stream_t* streamPtr, char* safeBuffer, int maxDictSize);
-
-
-/*-**********************************************
-*  Streaming Decompression Functions
-*  Bufferless synchronous API
-************************************************/
-typedef union LZ4_streamDecode_u LZ4_streamDecode_t;   /* tracking context */
-
-/*! LZ4_createStreamDecode() and LZ4_freeStreamDecode() :
- *  creation / destruction of streaming decompression tracking context.
- *  A tracking context can be re-used multiple times.
- */
-#if !defined(RC_INVOKED) /* https://docs.microsoft.com/en-us/windows/win32/menurc/predefined-macros */
-#if !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION)
-LZ4LIB_API LZ4_streamDecode_t* LZ4_createStreamDecode(void);
-LZ4LIB_API int                 LZ4_freeStreamDecode (LZ4_streamDecode_t* LZ4_stream);
-#endif /* !defined(LZ4_STATIC_LINKING_ONLY_DISABLE_MEMORY_ALLOCATION) */
-#endif
-
-/*! LZ4_setStreamDecode() :
- *  An LZ4_streamDecode_t context can be allocated once and re-used multiple times.
- *  Use this function to start decompression of a new stream of blocks.
- *  A dictionary can optionally be set. Use NULL or size 0 for a reset order.
- *  Dictionary is presumed stable : it must remain accessible and unmodified during next decompression.
- * @return : 1 if OK, 0 if error
- */
-LZ4LIB_API int LZ4_setStreamDecode (LZ4_streamDecode_t* LZ4_streamDecode, const char* dictionary, int dictSize);
-
-/*! LZ4_decoderRingBufferSize() : v1.8.2+
- *  Note : in a ring buffer scenario (optional),
- *  blocks are presumed decompressed next to each other
- *  up to the moment there is not enough remaining space for next block (remainingSize < maxBlockSize),
- *  at which stage it resumes from beginning of ring buffer.
- *  When setting such a ring buffer for streaming decompression,
- *  provides the minimum size of this ring buffer
- *  to be compatible with any source respecting maxBlockSize condition.
- * @return : minimum ring buffer size,
- *           or 0 if there is an error (invalid maxBlockSize).
- */
-LZ4LIB_API int LZ4_decoderRingBufferSize(int maxBlockSize);
-#define LZ4_DECODER_RING_BUFFER_SIZE(maxBlockSize) (65536 + 14 + (maxBlockSize))  /* for static allocation; maxBlockSize presumed valid */
-
-/*! LZ4_decompress_safe_continue() :
- *  This decoding function allows decompression of consecutive blocks in "streaming" mode.
- *  The difference with the usual independent blocks is that
- *  new blocks are allowed to find references into former blocks.
- *  A block is an unsplittable entity, and must be presented entirely to the decompression function.
- *  LZ4_decompress_safe_continue() only accepts one block at a time.
- *  It's modeled after `LZ4_decompress_safe()` and behaves similarly.
- *
- * @LZ4_streamDecode : decompression state, tracking the position in memory of past data
- * @compressedSize : exact complete size of one compressed block.
- * @dstCapacity : size of destination buffer (which must be already allocated),
- *                must be an upper bound of decompressed size.
- * @return : number of bytes decompressed into destination buffer (necessarily <= dstCapacity)
- *           If destination buffer is not large enough, decoding will stop and output an error code (negative value).
- *           If the source stream is detected malformed, the function will stop decoding and return a negative result.
- *
- *  The last 64KB of previously decoded data *must* remain available and unmodified
- *  at the memory position where they were previously decoded.
- *  If less than 64KB of data has been decoded, all the data must be present.
- *
- *  Special : if decompression side sets a ring buffer, it must respect one of the following conditions :
- *  - Decompression buffer size is _at least_ LZ4_decoderRingBufferSize(maxBlockSize).
- *    maxBlockSize is the maximum size of any single block. It can have any value > 16 bytes.
- *    In which case, encoding and decoding buffers do not need to be synchronized.
- *    Actually, data can be produced by any source compliant with LZ4 format specification, and respecting maxBlockSize.
- *  - Synchronized mode :
- *    Decompression buffer size is _exactly_ the same as compression buffer size,
- *    and follows exactly same update rule (block boundaries at same positions),
- *    and decoding function is provided with exact decompressed size of each block (exception for last block of the stream),
- *    _then_ decoding & encoding ring buffer can have any size, including small ones ( < 64 KB).
- *  - Decompression buffer is larger than encoding buffer, by a minimum of maxBlockSize more bytes.
- *    In which case, encoding and decoding buffers do not need to be synchronized,
- *    and encoding ring buffer can have any size, including small ones ( < 64 KB).
- *
- *  Whenever these conditions are not possible,
- *  save the last 64KB of decoded data into a safe buffer where it can't be modified during decompression,
- *  then indicate where this data is saved using LZ4_setStreamDecode(), before decompressing next block.
-*/
-LZ4LIB_API int
-LZ4_decompress_safe_continue (LZ4_streamDecode_t* LZ4_streamDecode,
-                        const char* src, char* dst,
-                        int srcSize, int dstCapacity);
-
-
-/*! LZ4_decompress_safe_usingDict() :
- *  Works the same as
- *  a combination of LZ4_setStreamDecode() followed by LZ4_decompress_safe_continue()
- *  However, it's stateless: it doesn't need any LZ4_streamDecode_t state.
- *  Dictionary is presumed stable : it must remain accessible and unmodified during decompression.
- *  Performance tip : Decompression speed can be substantially increased
- *                    when dst == dictStart + dictSize.
- */
-LZ4LIB_API int
-LZ4_decompress_safe_usingDict(const char* src, char* dst,
-                              int srcSize, int dstCapacity,
-                              const char* dictStart, int dictSize);
-
-/*! LZ4_decompress_safe_partial_usingDict() :
- *  Behaves the same as LZ4_decompress_safe_partial()
- *  with the added ability to specify a memory segment for past data.
- *  Performance tip : Decompression speed can be substantially increased
- *                    when dst == dictStart + dictSize.
- */
-LZ4LIB_API int
-LZ4_decompress_safe_partial_usingDict(const char* src, char* dst,
-                                      int compressedSize,
-                                      int targetOutputSize, int maxOutputSize,
-                                      const char* dictStart, int dictSize);
-
-#endif /* LZ4_H_2983827168210 */
-
-
-/*^*************************************
- * !!!!!!   STATIC LINKING ONLY   !!!!!!
- ***************************************/
-
-/*-****************************************************************************
- * Experimental section
- *
- * Symbols declared in this section must be considered unstable. Their
- * signatures or semantics may change, or they may be removed altogether in the
- * future. They are therefore only safe to depend on when the caller is
- * statically linked against the library.
- *
- * To protect against unsafe usage, not only are the declarations guarded,
- * the definitions are hidden by default
- * when building LZ4 as a shared/dynamic library.
- *
- * In order to access these declarations,
- * define LZ4_STATIC_LINKING_ONLY in your application
- * before including LZ4's headers.
- *
- * In order to make their implementations accessible dynamically, you must
- * define LZ4_PUBLISH_STATIC_FUNCTIONS when building the LZ4 library.
- ******************************************************************************/
-
-#ifdef LZ4_STATIC_LINKING_ONLY
-
-#ifndef LZ4_STATIC_3504398509
-#define LZ4_STATIC_3504398509
-
-#ifdef LZ4_PUBLISH_STATIC_FUNCTIONS
-# define LZ4LIB_STATIC_API LZ4LIB_API
-#else
-# define LZ4LIB_STATIC_API
-#endif
-
-
-/*! LZ4_compress_fast_extState_fastReset() :
- *  A variant of LZ4_compress_fast_extState().
- *
- *  Using this variant avoids an expensive initialization step.
- *  It is only safe to call if the state buffer is known to be correctly initialized already
- *  (see above comment on LZ4_resetStream_fast() for a definition of "correctly initialized").
- *  From a high level, the difference is that
- *  this function initializes the provided state with a call to something like LZ4_resetStream_fast()
- *  while LZ4_compress_fast_extState() starts with a call to LZ4_resetStream().
- */
-LZ4LIB_STATIC_API int LZ4_compress_fast_extState_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int acceleration);
-
-/*! LZ4_compress_destSize_extState() :
- *  Same as LZ4_compress_destSize(), but using an externally allocated state.
- *  Also: exposes @acceleration
- */
-int LZ4_compress_destSize_extState(void* state, const char* src, char* dst, int* srcSizePtr, int targetDstSize, int acceleration);
-
-/*! LZ4_attach_dictionary() :
- *  This is an experimental API that allows
- *  efficient use of a static dictionary many times.
- *
- *  Rather than re-loading the dictionary buffer into a working context before
- *  each compression, or copying a pre-loaded dictionary's LZ4_stream_t into a
- *  working LZ4_stream_t, this function introduces a no-copy setup mechanism,
- *  in which the working stream references the dictionary stream in-place.
- *
- *  Several assumptions are made about the state of the dictionary stream.
- *  Currently, only streams which have been prepared by LZ4_loadDict() should
- *  be expected to work.
- *
- *  Alternatively, the provided dictionaryStream may be NULL,
- *  in which case any existing dictionary stream is unset.
- *
- *  If a dictionary is provided, it replaces any pre-existing stream history.
- *  The dictionary contents are the only history that can be referenced and
- *  logically immediately precede the data compressed in the first subsequent
- *  compression call.
- *
- *  The dictionary will only remain attached to the working stream through the
- *  first compression call, at the end of which it is cleared. The dictionary
- *  stream (and source buffer) must remain in-place / accessible / unchanged
- *  through the completion of the first compression call on the stream.
- */
-LZ4LIB_STATIC_API void
-LZ4_attach_dictionary(LZ4_stream_t* workingStream,
-                const LZ4_stream_t* dictionaryStream);
-
-
-/*! In-place compression and decompression
- *
- * It's possible to have input and output sharing the same buffer,
- * for highly constrained memory environments.
- * In both cases, it requires input to lay at the end of the buffer,
- * and decompression to start at beginning of the buffer.
- * Buffer size must feature some margin, hence be larger than final size.
- *
- * |<------------------------buffer--------------------------------->|
- *                             |<-----------compressed data--------->|
- * |<-----------decompressed size------------------>|
- *                                                  |<----margin---->|
- *
- * This technique is more useful for decompression,
- * since decompressed size is typically larger,
- * and margin is short.
- *
- * In-place decompression will work inside any buffer
- * which size is >= LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize).
- * This presumes that decompressedSize > compressedSize.
- * Otherwise, it means compression actually expanded data,
- * and it would be more efficient to store such data with a flag indicating it's not compressed.
- * This can happen when data is not compressible (already compressed, or encrypted).
- *
- * For in-place compression, margin is larger, as it must be able to cope with both
- * history preservation, requiring input data to remain unmodified up to LZ4_DISTANCE_MAX,
- * and data expansion, which can happen when input is not compressible.
- * As a consequence, buffer size requirements are much higher,
- * and memory savings offered by in-place compression are more limited.
- *
- * There are ways to limit this cost for compression :
- * - Reduce history size, by modifying LZ4_DISTANCE_MAX.
- *   Note that it is a compile-time constant, so all compressions will apply this limit.
- *   Lower values will reduce compression ratio, except when input_size < LZ4_DISTANCE_MAX,
- *   so it's a reasonable trick when inputs are known to be small.
- * - Require the compressor to deliver a "maximum compressed size".
- *   This is the `dstCapacity` parameter in `LZ4_compress*()`.
- *   When this size is < LZ4_COMPRESSBOUND(inputSize), then compression can fail,
- *   in which case, the return code will be 0 (zero).
- *   The caller must be ready for these cases to happen,
- *   and typically design a backup scheme to send data uncompressed.
- * The combination of both techniques can significantly reduce
- * the amount of margin required for in-place compression.
- *
- * In-place compression can work in any buffer
- * which size is >= (maxCompressedSize)
- * with maxCompressedSize == LZ4_COMPRESSBOUND(srcSize) for guaranteed compression success.
- * LZ4_COMPRESS_INPLACE_BUFFER_SIZE() depends on both maxCompressedSize and LZ4_DISTANCE_MAX,
- * so it's possible to reduce memory requirements by playing with them.
- */
-
-#define LZ4_DECOMPRESS_INPLACE_MARGIN(compressedSize)          (((compressedSize) >> 8) + 32)
-#define LZ4_DECOMPRESS_INPLACE_BUFFER_SIZE(decompressedSize)   ((decompressedSize) + LZ4_DECOMPRESS_INPLACE_MARGIN(decompressedSize))  /**< note: presumes that compressedSize < decompressedSize. note2: margin is overestimated a bit, since it could use compressedSize instead */
-
-#ifndef LZ4_DISTANCE_MAX   /* history window size; can be user-defined at compile time */
-#  define LZ4_DISTANCE_MAX 65535   /* set to maximum value by default */
-#endif
-
-#define LZ4_COMPRESS_INPLACE_MARGIN                           (LZ4_DISTANCE_MAX + 32)   /* LZ4_DISTANCE_MAX can be safely replaced by srcSize when it's smaller */
-#define LZ4_COMPRESS_INPLACE_BUFFER_SIZE(maxCompressedSize)   ((maxCompressedSize) + LZ4_COMPRESS_INPLACE_MARGIN)  /**< maxCompressedSize is generally LZ4_COMPRESSBOUND(inputSize), but can be set to any lower value, with the risk that compression can fail (return code 0(zero)) */
-
-#endif   /* LZ4_STATIC_3504398509 */
-#endif   /* LZ4_STATIC_LINKING_ONLY */
-
-
-
-#ifndef LZ4_H_98237428734687
-#define LZ4_H_98237428734687
-
-/*-************************************************************
- *  Private Definitions
- **************************************************************
- * Do not use these definitions directly.
- * They are only exposed to allow static allocation of `LZ4_stream_t` and `LZ4_streamDecode_t`.
- * Accessing members will expose user code to API and/or ABI break in future versions of the library.
- **************************************************************/
-#define LZ4_HASHLOG   (LZ4_MEMORY_USAGE-2)
-#define LZ4_HASHTABLESIZE (1 << LZ4_MEMORY_USAGE)
-#define LZ4_HASH_SIZE_U32 (1 << LZ4_HASHLOG)       /* required as macro for static allocation */
-
-#if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */)
-# include <stdint.h>
-  typedef  int8_t  LZ4_i8;
-  typedef uint8_t  LZ4_byte;
-  typedef uint16_t LZ4_u16;
-  typedef uint32_t LZ4_u32;
-#else
-  typedef   signed char  LZ4_i8;
-  typedef unsigned char  LZ4_byte;
-  typedef unsigned short LZ4_u16;
-  typedef unsigned int   LZ4_u32;
-#endif
-
-/*! LZ4_stream_t :
- *  Never ever use below internal definitions directly !
- *  These definitions are not API/ABI safe, and may change in future versions.
- *  If you need static allocation, declare or allocate an LZ4_stream_t object.
-**/
-
-typedef struct LZ4_stream_t_internal LZ4_stream_t_internal;
-struct LZ4_stream_t_internal {
-    LZ4_u32 hashTable[LZ4_HASH_SIZE_U32];
-    const LZ4_byte* dictionary;
-    const LZ4_stream_t_internal* dictCtx;
-    LZ4_u32 currentOffset;
-    LZ4_u32 tableType;
-    LZ4_u32 dictSize;
-    /* Implicit padding to ensure structure is aligned */
-};
-
-#define LZ4_STREAM_MINSIZE  ((1UL << (LZ4_MEMORY_USAGE)) + 32)  /* static size, for inter-version compatibility */
-union LZ4_stream_u {
-    char minStateSize[LZ4_STREAM_MINSIZE];
-    LZ4_stream_t_internal internal_donotuse;
-}; /* previously typedef'd to LZ4_stream_t */
-
-
-/*! LZ4_initStream() : v1.9.0+
- *  An LZ4_stream_t structure must be initialized at least once.
- *  This is automatically done when invoking LZ4_createStream(),
- *  but it's not when the structure is simply declared on stack (for example).
- *
- *  Use LZ4_initStream() to properly initialize a newly declared LZ4_stream_t.
- *  It can also initialize any arbitrary buffer of sufficient size,
- *  and will @return a pointer of proper type upon initialization.
- *
- *  Note : initialization fails if size and alignment conditions are not respected.
- *         In which case, the function will @return NULL.
- *  Note2: An LZ4_stream_t structure guarantees correct alignment and size.
- *  Note3: Before v1.9.0, use LZ4_resetStream() instead
-**/
-LZ4LIB_API LZ4_stream_t* LZ4_initStream (void* stateBuffer, size_t size);
-
-
-/*! LZ4_streamDecode_t :
- *  Never ever use below internal definitions directly !
- *  These definitions are not API/ABI safe, and may change in future versions.
- *  If you need static allocation, declare or allocate an LZ4_streamDecode_t object.
-**/
-typedef struct {
-    const LZ4_byte* externalDict;
-    const LZ4_byte* prefixEnd;
-    size_t extDictSize;
-    size_t prefixSize;
-} LZ4_streamDecode_t_internal;
-
-#define LZ4_STREAMDECODE_MINSIZE 32
-union LZ4_streamDecode_u {
-    char minStateSize[LZ4_STREAMDECODE_MINSIZE];
-    LZ4_streamDecode_t_internal internal_donotuse;
-} ;   /* previously typedef'd to LZ4_streamDecode_t */
-
-
-
-/*-************************************
-*  Obsolete Functions
-**************************************/
-
-/*! Deprecation warnings
- *
- *  Deprecated functions make the compiler generate a warning when invoked.
- *  This is meant to invite users to update their source code.
- *  Should deprecation warnings be a problem, it is generally possible to disable them,
- *  typically with -Wno-deprecated-declarations for gcc
- *  or _CRT_SECURE_NO_WARNINGS in Visual.
- *
- *  Another method is to define LZ4_DISABLE_DEPRECATE_WARNINGS
- *  before including the header file.
- */
-#ifdef LZ4_DISABLE_DEPRECATE_WARNINGS
-#  define LZ4_DEPRECATED(message)   /* disable deprecation warnings */
-#else
-#  if defined (__cplusplus) && (__cplusplus >= 201402) /* C++14 or greater */
-#    define LZ4_DEPRECATED(message) [[deprecated(message)]]
-#  elif defined(_MSC_VER)
-#    define LZ4_DEPRECATED(message) __declspec(deprecated(message))
-#  elif defined(__clang__) || (defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 45))
-#    define LZ4_DEPRECATED(message) __attribute__((deprecated(message)))
-#  elif defined(__GNUC__) && (__GNUC__ * 10 + __GNUC_MINOR__ >= 31)
-#    define LZ4_DEPRECATED(message) __attribute__((deprecated))
-#  else
-#    pragma message("WARNING: LZ4_DEPRECATED needs custom implementation for this compiler")
-#    define LZ4_DEPRECATED(message)   /* disabled */
-#  endif
-#endif /* LZ4_DISABLE_DEPRECATE_WARNINGS */
-
-/*! Obsolete compression functions (since v1.7.3) */
-LZ4_DEPRECATED("use LZ4_compress_default() instead")       LZ4LIB_API int LZ4_compress               (const char* src, char* dest, int srcSize);
-LZ4_DEPRECATED("use LZ4_compress_default() instead")       LZ4LIB_API int LZ4_compress_limitedOutput (const char* src, char* dest, int srcSize, int maxOutputSize);
-LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_withState               (void* state, const char* source, char* dest, int inputSize);
-LZ4_DEPRECATED("use LZ4_compress_fast_extState() instead") LZ4LIB_API int LZ4_compress_limitedOutput_withState (void* state, const char* source, char* dest, int inputSize, int maxOutputSize);
-LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_continue                (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize);
-LZ4_DEPRECATED("use LZ4_compress_fast_continue() instead") LZ4LIB_API int LZ4_compress_limitedOutput_continue  (LZ4_stream_t* LZ4_streamPtr, const char* source, char* dest, int inputSize, int maxOutputSize);
-
-/*! Obsolete decompression functions (since v1.8.0) */
-LZ4_DEPRECATED("use LZ4_decompress_fast() instead") LZ4LIB_API int LZ4_uncompress (const char* source, char* dest, int outputSize);
-LZ4_DEPRECATED("use LZ4_decompress_safe() instead") LZ4LIB_API int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize);
-
-/* Obsolete streaming functions (since v1.7.0)
- * degraded functionality; do not use!
- *
- * In order to perform streaming compression, these functions depended on data
- * that is no longer tracked in the state. They have been preserved as well as
- * possible: using them will still produce a correct output. However, they don't
- * actually retain any history between compression calls. The compression ratio
- * achieved will therefore be no better than compressing each chunk
- * independently.
- */
-LZ4_DEPRECATED("Use LZ4_createStream() instead") LZ4LIB_API void* LZ4_create (char* inputBuffer);
-LZ4_DEPRECATED("Use LZ4_createStream() instead") LZ4LIB_API int   LZ4_sizeofStreamState(void);
-LZ4_DEPRECATED("Use LZ4_resetStream() instead")  LZ4LIB_API int   LZ4_resetStreamState(void* state, char* inputBuffer);
-LZ4_DEPRECATED("Use LZ4_saveDict() instead")     LZ4LIB_API char* LZ4_slideInputBuffer (void* state);
-
-/*! Obsolete streaming decoding functions (since v1.7.0) */
-LZ4_DEPRECATED("use LZ4_decompress_safe_usingDict() instead") LZ4LIB_API int LZ4_decompress_safe_withPrefix64k (const char* src, char* dst, int compressedSize, int maxDstSize);
-LZ4_DEPRECATED("use LZ4_decompress_fast_usingDict() instead") LZ4LIB_API int LZ4_decompress_fast_withPrefix64k (const char* src, char* dst, int originalSize);
-
-/*! Obsolete LZ4_decompress_fast variants (since v1.9.0) :
- *  These functions used to be faster than LZ4_decompress_safe(),
- *  but this is no longer the case. They are now slower.
- *  This is because LZ4_decompress_fast() doesn't know the input size,
- *  and therefore must progress more cautiously into the input buffer to not read beyond the end of block.
- *  On top of that `LZ4_decompress_fast()` is not protected vs malformed or malicious inputs, making it a security liability.
- *  As a consequence, LZ4_decompress_fast() is strongly discouraged, and deprecated.
- *
- *  The last remaining LZ4_decompress_fast() specificity is that
- *  it can decompress a block without knowing its compressed size.
- *  Such functionality can be achieved in a more secure manner
- *  by employing LZ4_decompress_safe_partial().
- *
- *  Parameters:
- *  originalSize : is the uncompressed size to regenerate.
- *                 `dst` must be already allocated, its size must be >= 'originalSize' bytes.
- * @return : number of bytes read from source buffer (== compressed size).
- *           The function expects to finish at block's end exactly.
- *           If the source stream is detected malformed, the function stops decoding and returns a negative result.
- *  note : LZ4_decompress_fast*() requires originalSize. Thanks to this information, it never writes past the output buffer.
- *         However, since it doesn't know its 'src' size, it may read an unknown amount of input, past input buffer bounds.
- *         Also, since match offsets are not validated, match reads from 'src' may underflow too.
- *         These issues never happen if input (compressed) data is correct.
- *         But they may happen if input data is invalid (error or intentional tampering).
- *         As a consequence, use these functions in trusted environments with trusted data **only**.
- */
-LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_partial() instead")
-LZ4LIB_API int LZ4_decompress_fast (const char* src, char* dst, int originalSize);
-LZ4_DEPRECATED("This function is deprecated and unsafe. Consider migrating towards LZ4_decompress_safe_continue() instead. "
-               "Note that the contract will change (requires block's compressed size, instead of decompressed size)")
-LZ4LIB_API int LZ4_decompress_fast_continue (LZ4_streamDecode_t* LZ4_streamDecode, const char* src, char* dst, int originalSize);
-LZ4_DEPRECATED("This function is deprecated and unsafe. Consider using LZ4_decompress_safe_partial_usingDict() instead")
-LZ4LIB_API int LZ4_decompress_fast_usingDict (const char* src, char* dst, int originalSize, const char* dictStart, int dictSize);
-
-/*! LZ4_resetStream() :
- *  An LZ4_stream_t structure must be initialized at least once.
- *  This is done with LZ4_initStream(), or LZ4_resetStream().
- *  Consider switching to LZ4_initStream(),
- *  invoking LZ4_resetStream() will trigger deprecation warnings in the future.
- */
-LZ4LIB_API void LZ4_resetStream (LZ4_stream_t* streamPtr);
-
-
-#endif /* LZ4_H_98237428734687 */
-
-
-#if defined (__cplusplus)
-}
-#endif

include/verilated.cpp

@@ -58,7 +58,10 @@
 #include <algorithm>
 #include <cctype>
 #include <cerrno>
+#include <chrono>
 #include <cstdlib>
+#include <ctime>
+#include <fcntl.h>
 #include <iostream>
 #include <limits>
 #include <list>
@@ -71,6 +74,9 @@
 // clang-format off
 #if defined(_WIN32) || defined(__MINGW32__)
 # include <direct.h>  // mkdir
+# include <io.h>       // open, read, write, close
+# define STDOUT_FILENO _fileno(stdout)
+# define STDERR_FILENO _fileno(stderr)
 #endif
 #ifdef __GLIBC__
 # include <cxxabi.h>
@@ -80,8 +86,15 @@
 #if defined(__unix__) || (defined(__APPLE__) && defined(__MACH__))
 # include <sys/time.h>
 # include <sys/resource.h>
+# include <unistd.h>
 # define _VL_HAVE_GETRLIMIT
 #endif
+#if VM_VPI
+# include <cstring>
+# ifndef _WIN32
+#  include <dlfcn.h>  // dlopen
+# endif
+#endif
 
 #include "verilated_threads.h"
 // clang-format on
@@ -253,6 +266,58 @@ void VL_WARN_MT(const char* filename, int linenum, const char* hier, const char*
     }});
 }
 
+//===========================================================================
+// Runtime VPI shared library loading (--vpi)
+
+// Load one VPI shared library named by a +verilator+vpi+<lib>[:<bootstrap>] argument.
+// 'arg' is the payload after the prefix: either "<lib>" (invoke the library's
+// vlog_startup_routines array) or "<lib>:<bootstrap>" (invoke the named bootstrap).
+void Verilated::loadVpiLib(const std::string& arg) VL_MT_UNSAFE {
+#if VM_VPI
+    if (arg.empty()) return;
+#ifdef _WIN32
+    VL_FATAL_MT("", 0, "",
+                "+verilator+vpi+: runtime VPI library loading is not supported on"
+                " Windows; link the VPI code into the model instead");
+#else
+    using vlog_startup_t = void (*)();
+    // Split <lib>:<bootstrap> on the last ':'
+    const std::string::size_type colon_pos = arg.rfind(':');
+    const bool has_entry = (colon_pos != std::string::npos);
+    const std::string libpath = has_entry ? arg.substr(0, colon_pos) : arg;
+    const std::string entry_name = has_entry ? arg.substr(colon_pos + 1) : std::string{};
+    void* handle = dlopen(libpath.c_str(), RTLD_LAZY);
+    if (!handle)
+        // The library path is stable; the dlerror() text is platform-specific, so put it on
+        // a separate "- " line (test golden files strip "- " lines, keeping output portable).
+        VL_FATAL_MT(
+            "", 0, "",
+            (std::string{"Cannot load VPI library: "} + libpath + "\n- dlerror: " + dlerror())
+                .c_str());
+    if (has_entry) {
+        vlog_startup_t bsp = reinterpret_cast<vlog_startup_t>(dlsym(handle, entry_name.c_str()));
+        if (!bsp)
+            VL_FATAL_MT(
+                "", 0, "",
+                (std::string{"Cannot find VPI bootstrap '"} + entry_name + "' in: " + libpath)
+                    .c_str());
+        bsp();
+    } else {
+        vlog_startup_t* routinesp
+            = reinterpret_cast<vlog_startup_t*>(dlsym(handle, "vlog_startup_routines"));
+        if (!routinesp)
+            VL_FATAL_MT(
+                "", 0, "",
+                (std::string{"Cannot find 'vlog_startup_routines' in: "} + libpath).c_str());
+        for (int j = 0; routinesp[j]; ++j) routinesp[j]();
+    }
+#endif
+#else
+    // Never reached: the command-line handler only calls this when compiled with --vpi.
+    (void)arg;
+#endif
+}
+
 //===========================================================================
 // Debug prints
 
@@ -311,6 +376,12 @@ void VL_PRINTF_MT(const char* formatp, ...) VL_MT_SAFE {
     }});
 }
 
+void VL_FFLUSH_MT() VL_MT_SAFE {
+    VerilatedThreadMsgQueue::post(VerilatedMsg{[=]() {  //
+        Verilated::runFlushCallbacks();
+    }});
+}
+
 template <typename... snprintf_args_ts>
 static size_t _vl_snprintf_string(std::string& str, const char* format,
                                   snprintf_args_ts... args) VL_MT_SAFE {
@@ -812,7 +883,7 @@ double VL_ISTOR_D_W(int lbits, const WDataInP lwp) VL_MT_SAFE {
     if (!VL_SIGN_W(lbits, lwp)) return VL_ITOR_D_W(lbits, lwp);
     const int words = VL_WORDS_I(lbits);
     VL_DEBUG_IFDEF(assert(words <= VL_MULS_MAX_WORDS););
-    uint32_t pos[VL_MULS_MAX_WORDS + 1];  // Fixed size, as MSVC++ doesn't allow [words] here
+    VlWide<VL_MULS_MAX_WORDS + 1> pos;
     VL_NEGATE_W(words, pos, lwp);
     _vl_clean_inplace_w(lbits, pos);
     return -VL_ITOR_D_W(lbits, pos);
@@ -826,9 +897,12 @@ std::string VL_DECIMAL_NW(int width, const WDataInP lwp) VL_MT_SAFE {
     const int maxdecwidth = (width + 3) * 4 / 3;
     // Or (maxdecwidth+7)/8], but can't have more than 4 BCD bits per word
     std::vector<EData> bcd(VL_WORDS_I(maxdecwidth));
-    VL_ZERO_W(maxdecwidth, bcd.data());
+    WDataOutP bcdp = WDataOutP::external(bcd.data());
+    VL_ZERO_W(maxdecwidth, bcdp);
     std::vector<EData> tmp(VL_WORDS_I(maxdecwidth));
     std::vector<EData> tmp2(VL_WORDS_I(maxdecwidth));
+    WDataOutP tmpp = WDataOutP::external(tmp.data());
+    WDataOutP tmp2p = WDataOutP::external(tmp2.data());
     int from_bit = width - 1;
     // Skip all leading zeros
     for (; from_bit >= 0 && !(VL_BITRSHIFT_W(lwp, from_bit) & 1); --from_bit) {}
@@ -837,15 +911,15 @@ std::string VL_DECIMAL_NW(int width, const WDataInP lwp) VL_MT_SAFE {
         // Any digits >= 5 need an add 3 (via tmp)
         for (int nibble_bit = 0; nibble_bit < maxdecwidth; nibble_bit += 4) {
             if ((VL_BITRSHIFT_W(bcd, nibble_bit) & 0xf) >= 5) {
-                VL_ZERO_W(maxdecwidth, tmp2.data());
+                VL_ZERO_W(maxdecwidth, tmp2p);
                 tmp2[VL_BITWORD_E(nibble_bit)] |= VL_EUL(0x3) << VL_BITBIT_E(nibble_bit);
-                VL_ASSIGN_W(maxdecwidth, tmp.data(), bcd.data());
+                VL_ASSIGN_W(maxdecwidth, tmpp, bcdp);
-                VL_ADD_W(VL_WORDS_I(maxdecwidth), bcd.data(), tmp.data(), tmp2.data());
+                VL_ADD_W(VL_WORDS_I(maxdecwidth), bcdp, tmpp, tmp2p);
             }
         }
         // Shift; bcd = bcd << 1
-        VL_ASSIGN_W(maxdecwidth, tmp.data(), bcd.data());
+        VL_ASSIGN_W(maxdecwidth, tmpp, bcdp);
-        VL_SHIFTL_WWI(maxdecwidth, maxdecwidth, 32, bcd.data(), tmp.data(), 1);
+        VL_SHIFTL_WWI(maxdecwidth, maxdecwidth, 32, bcdp, tmpp, 1);
         // bcd[0] = lwp[from_bit]
         if (VL_BITISSET_W(lwp, from_bit)) bcd[0] |= 1;
     }
@@ -948,7 +1022,7 @@ void _vl_vsformat(std::string& output, const std::string& format, int argc,
                   va_list ap) VL_MT_SAFE {
     // Format a Verilog $write style format into the output list
     // The format must be pre-processed (and lower cased) by Verilator.
-    // Arguments are each {"VFormatAttr character, int width, arg-value (or WDataIn* if wide)"}
+    // Arguments are each {"VFormatAttr character, int width, arg-value (or EData* if wide)"}
     //
     // Uses a single buffer internally; presumes only one usage per printf.
     // Also assumes variables < 64 are not wide, this assumption is
@@ -988,7 +1062,7 @@ void _vl_vsformat(std::string& output, const std::string& format, int argc,
     bool widthSet = false;
     bool left = false;
     size_t width = 0;
-    output = "";
+    output.clear();
     output.reserve(format.length());
     for (std::string::const_iterator pos = format.cbegin(); pos != format.cend(); ++pos) {
         if (!inPct && pos[0] == '%') {
@@ -1078,9 +1152,10 @@ void _vl_vsformat(std::string& output, const std::string& format, int argc,
             // Similar code flow in V3Number::displayed
             int lbits = 0;
             void* thingp = nullptr;
+            const std::string* enump = nullptr;
             QData ld = 0;
             std::vector<EData> strwide;
-            WDataInP lwp = nullptr;
+            WDataInP lwp{nullptr};
             int lsb = 0;
             double real = 0.0;
             if (formatAttr == VL_VFORMATATTR_COMPLEX) {  // printed as string
@@ -1090,23 +1165,53 @@ void _vl_vsformat(std::string& output, const std::string& format, int argc,
                 real = va_arg(ap, double);
                 ld = VL_RTOIROUND_Q_D(real);
                 strwide.resize(2);
-                VL_SET_WQ(strwide, ld);
+                WDataOutP strwidep = WDataOutP::external(strwide.data());
-                lwp = strwide.data();
+                VL_SET_WQ(strwidep, ld);
+                lwp = strwidep;
                 lbits = 64;
                 // Not changint fmt == 'p' to fmt = 'g', as need fmts correct
             } else if (formatAttr == VL_VFORMATATTR_STRING) {
                 thingp = va_arg(ap, std::string*);
                 if (fmt != 'p' && fmt != 'x') fmt = 's';  // Override
+            } else if (formatAttr == VL_VFORMATATTR_ENUM) {
+                // Always <= VL_QUADSIZE; emit uses non-ENUM format for wider enums
+                lbits = va_arg(ap, int);
+                ld = VL_VA_ARG_Q_(ap, lbits);
+                strwide.resize(2);
+                WDataOutP strwidep = WDataOutP::external(strwide.data());
+                VL_SET_WQ(strwidep, ld);
+                lwp = strwidep;
+                lsb = lbits - 1;
+                ++argn;  // Enum value is followed by the generated name string argument
+                static_cast<void>(va_arg(ap, int));  // VL_VFORMATATTR_STRING
+                enump = va_arg(ap, std::string*);
+                if (enump && !enump->empty()) {
+                    formatAttr = (fmt == 'p') ? VL_VFORMATATTR_COMPLEX : VL_VFORMATATTR_STRING;
+                    thingp = const_cast<std::string*>(enump);
+                } else if (fmt == 'p' && widthSet && width == 0) {
+                    output += "'h";
+                    fmt = 'h';
+                    formatAttr = VL_VFORMATATTR_UNSIGNED;
+                } else {
+                    if (fmt == 'p') width = 0;
+                    widthSet = true;
+                    fmt = 'd';
+                    formatAttr = VL_VFORMATATTR_UNSIGNED;
+                }
+                if (widthSet && width == 0) {
+                    while (lsb && !VL_BITISSET_W(lwp, lsb)) --lsb;
+                }
             } else {  // Numeric
                 lbits = va_arg(ap, int);
                 if (lbits <= VL_QUADSIZE) {
                     ld = VL_VA_ARG_Q_(ap, lbits);
                     strwide.resize(2);
-                    VL_SET_WQ(strwide, ld);
+                    WDataOutP strwidep = WDataOutP::external(strwide.data());
-                    lwp = strwide.data();
+                    VL_SET_WQ(strwidep, ld);
+                    lwp = strwidep;
                 } else {
-                    lwp = va_arg(ap, WDataInP);
+                    lwp = WDataInP::external(va_arg(ap, EData*));
-                    ld = lwp[0];
+                    ld = VL_SET_QW(lwp);  // Low 64 bits, for %c/%t
                 }
                 if (fmt == 'p') {
                     if (widthSet && width == 0) {  // For %0p, IEEE our choice, use 'h%0h
@@ -1191,8 +1296,9 @@ void _vl_vsformat(std::string& output, const std::string& format, int argc,
                     } else {
                         if (VL_SIGN_E(lbits, lwp[VL_WORDS_I(lbits) - 1])) {
                             std::vector<EData> neg(VL_WORDS_I(lbits));
-                            VL_NEGATE_W(VL_WORDS_I(lbits), neg.data(), lwp);
+                            WDataOutP negp = WDataOutP::external(neg.data());
-                            append = "-"s + VL_DECIMAL_NW(lbits, neg.data());
+                            VL_NEGATE_W(VL_WORDS_I(lbits), negp, lwp);
+                            append = "-"s + VL_DECIMAL_NW(lbits, negp);
                         } else {
                             append = VL_DECIMAL_NW(lbits, lwp);
                         }
@@ -1259,9 +1365,10 @@ void _vl_vsformat(std::string& output, const std::string& format, int argc,
                     if (truncFront < 0) truncFront = 0;
                     lbits = chars * 8;
                     strwide.resize(VL_WORDS_I(lbits));
-                    lwp = strwide.data();
+                    WDataOutP strwidep = WDataOutP::external(strwide.data());
+                    lwp = strwidep;
                     lsb = lbits - 1;
-                    VL_NTOI_W(lbits, strwide.data(), *strp, truncFront);
+                    VL_NTOI_W(lbits, strwidep, *strp, truncFront);
                 }
 
                 if (widthSet || left) {
@@ -1382,7 +1489,7 @@ static void _vl_vsss_skipspace(FILE* fp, int& floc, const WDataInP fromp,
                                const std::string& fstr) VL_MT_SAFE {
     while (true) {
         const int c = _vl_vsss_peek(fp, floc, fromp, fstr);
-        if (c == EOF || !std::isspace(c)) return;
+        if (c == EOF || !(std::isspace(c) || c == '\0')) return;
         _vl_vsss_advance(fp, floc);
     }
 }
@@ -1399,7 +1506,6 @@ static void _vl_vsss_read_str(FILE* fp, int& floc, const WDataInP fromp, const s
         *cp++ = c;
         _vl_vsss_advance(fp, floc);
     }
-    // VL_DBG_MSGF(" _read got='"<<tmpp<<"'\n");
 }
 static char* _vl_vsss_read_bin(FILE* fp, int& floc, const WDataInP fromp, const std::string& fstr,
                                char* beginp, std::size_t n,
@@ -1456,7 +1562,7 @@ IData _vl_vsscanf(FILE* fp,  // If a fscanf
                   const std::string& format, int argc, va_list ap) VL_MT_SAFE {
     // Read a Verilog $sscanf/$fscanf style format into the output list
     // The format must be pre-processed (and lower cased) by Verilator
-    // Arguments are in "width, arg-value (or WDataIn* if wide)" form
+    // Arguments are in "width, arg-value (or EData* if wide)" form
     static thread_local std::string t_tmp;
     int floc = fbits - 1;
     IData got = 0;
@@ -1543,7 +1649,8 @@ IData _vl_vsscanf(FILE* fp,  // If a fscanf
 
                 VlWide<VL_WQ_WORDS_E> qowp;
                 VL_SET_WQ(qowp, 0ULL);
-                WDataOutP owp = (obits <= 64) ? qowp : static_cast<WDataOutP>(thingp);
+                WDataOutP owp = WDataOutP::external((obits <= 64) ? qowp.data()
+                                                                  : static_cast<EData*>(thingp));
 
                 for (int i = 0; i < VL_WORDS_I(obits); ++i) owp[i] = 0;
                 t_tmp.clear();
@@ -1646,7 +1753,7 @@ IData _vl_vsscanf(FILE* fp,  // If a fscanf
                 case 'u': {
                     // Read packed 2-value binary data
                     const int bytes = VL_BYTES_I(obits);
-                    char* const out = reinterpret_cast<char*>(owp);
+                    char* const out = reinterpret_cast<char*>(owp.datap());
                     if (!_vl_vsss_read_bin(fp, floc, fromp, fstr, out, bytes)) goto done;
                     const int last = bytes % 4;
                     if (last != 0
@@ -1656,7 +1763,7 @@ IData _vl_vsscanf(FILE* fp,  // If a fscanf
                 }
                 case 'z': {
                     // Read packed 4-value binary data
-                    char* out = reinterpret_cast<char*>(owp);
+                    char* out = reinterpret_cast<char*>(owp.datap());
                     int bytes = VL_BYTES_I(obits);
                     while (bytes > 0) {
                         const int abytes = std::min(4, bytes);
@@ -1798,7 +1905,7 @@ IData VL_FERROR_IN(IData, std::string& outputr) VL_MT_SAFE {
 IData VL_FERROR_IW(IData fpi, int obits, WDataOutP outwp) VL_MT_SAFE {
     std::string output;
     const IData ret = VL_FERROR_IN(fpi, output /*ref*/);
-    _vl_string_to_vint(obits, outwp, output.length(), output.c_str());
+    _vl_string_to_vint(obits, outwp.datap(), output.length(), output.c_str());
     return ret;
 }
 
@@ -1819,9 +1926,11 @@ void VL_FCLOSE_I(IData fdi) VL_MT_SAFE {
     Verilated::threadContextp()->impp()->fdClose(fdi);
 }
 
+//===========================================================================
+// String formatting functions taking const std::string& as format string
+
 void VL_SFORMAT_NX(int obits, CData& destr, const std::string& format, int argc, ...) VL_MT_SAFE {
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1832,7 +1941,6 @@ void VL_SFORMAT_NX(int obits, CData& destr, const std::string& format, int argc,
 
 void VL_SFORMAT_NX(int obits, SData& destr, const std::string& format, int argc, ...) VL_MT_SAFE {
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1843,7 +1951,6 @@ void VL_SFORMAT_NX(int obits, SData& destr, const std::string& format, int argc,
 
 void VL_SFORMAT_NX(int obits, IData& destr, const std::string& format, int argc, ...) VL_MT_SAFE {
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1854,7 +1961,6 @@ void VL_SFORMAT_NX(int obits, IData& destr, const std::string& format, int argc,
 
 void VL_SFORMAT_NX(int obits, QData& destr, const std::string& format, int argc, ...) VL_MT_SAFE {
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1863,9 +1969,8 @@ void VL_SFORMAT_NX(int obits, QData& destr, const std::string& format, int argc,
     _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
 }
 
-void VL_SFORMAT_NX(int obits, void* destp, const std::string& format, int argc, ...) VL_MT_SAFE {
+void VL_SFORMAT_NX(int obits, EData* destp, const std::string& format, int argc, ...) VL_MT_SAFE {
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1874,9 +1979,7 @@ void VL_SFORMAT_NX(int obits, void* destp, const std::string& format, int argc,
     _vl_string_to_vint(obits, destp, t_output.length(), t_output.c_str());
 }
 
-void VL_SFORMAT_NX(int obits_ignored, std::string& output, const std::string& format, int argc,
+void VL_SFORMAT_NX(std::string& output, const std::string& format, int argc, ...) VL_MT_SAFE {
-                   ...) VL_MT_SAFE {
-    (void)obits_ignored;  // So VL_SFORMAT_NNX function signatures all match
     std::string temp_output;
     va_list ap;
     va_start(ap, argc);
@@ -1886,19 +1989,17 @@ void VL_SFORMAT_NX(int obits_ignored, std::string& output, const std::string& fo
 }
 
 std::string VL_SFORMATF_N_NX(const std::string& format, int argc, ...) VL_MT_SAFE {
-    static thread_local std::string t_output;  // static only for speed
+    std::string output;
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
-    _vl_vsformat(t_output, format, argc, ap);
+    _vl_vsformat(output, format, argc, ap);
     va_end(ap);
 
-    return t_output;
+    return output;
 }
 
 void VL_WRITEF_NX(const std::string& format, int argc, ...) VL_MT_SAFE {
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1910,8 +2011,6 @@ void VL_WRITEF_NX(const std::string& format, int argc, ...) VL_MT_SAFE {
 void VL_FWRITEF_NX(IData fpi, const std::string& format, int argc, ...) VL_MT_SAFE {
     // While threadsafe, each thread can only access different file handles
     static thread_local std::string t_output;  // static only for speed
-    t_output = "";
-
     va_list ap;
     va_start(ap, argc);
     _vl_vsformat(t_output, format, argc, ap);
@@ -1920,14 +2019,108 @@ void VL_FWRITEF_NX(IData fpi, const std::string& format, int argc, ...) VL_MT_SA
     Verilated::threadContextp()->impp()->fdWrite(fpi, t_output);
 }
 
+//===========================================================================
+// String formatting functions taking const char* as format string
+
+void VL_SFORMAT_NX(int obits, CData& destr, const char* formatp, int argc, ...) VL_MT_SAFE {
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
+}
+
+void VL_SFORMAT_NX(int obits, SData& destr, const char* formatp, int argc, ...) VL_MT_SAFE {
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
+}
+
+void VL_SFORMAT_NX(int obits, IData& destr, const char* formatp, int argc, ...) VL_MT_SAFE {
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
+}
+
+void VL_SFORMAT_NX(int obits, QData& destr, const char* formatp, int argc, ...) VL_MT_SAFE {
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    _vl_string_to_vint(obits, &destr, t_output.length(), t_output.c_str());
+}
+
+void VL_SFORMAT_NX(int obits, EData* destp, const char* formatp, int argc, ...) VL_MT_SAFE {
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    _vl_string_to_vint(obits, destp, t_output.length(), t_output.c_str());
+}
+
+void VL_SFORMAT_NX(std::string& output, const char* formatp, int argc, ...) VL_MT_SAFE {
+    std::string temp_output;
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(temp_output, formatp, argc, ap);
+    va_end(ap);
+    output = temp_output;
+}
+
+std::string VL_SFORMATF_N_NX(const char* formatp, int argc, ...) VL_MT_SAFE {
+    std::string output;
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(output, formatp, argc, ap);
+    va_end(ap);
+
+    return output;
+}
+
+void VL_WRITEF_NX(const char* formatp, int argc, ...) VL_MT_SAFE {
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    VL_PRINTF_MT("%s", t_output.c_str());
+}
+
+void VL_FWRITEF_NX(IData fpi, const char* formatp, int argc, ...) VL_MT_SAFE {
+    // While threadsafe, each thread can only access different file handles
+    static thread_local std::string t_output;  // static only for speed
+    va_list ap;
+    va_start(ap, argc);
+    _vl_vsformat(t_output, formatp, argc, ap);
+    va_end(ap);
+
+    Verilated::threadContextp()->impp()->fdWrite(fpi, t_output);
+}
+
 IData VL_FSCANF_INX(IData fpi, const std::string& format, int argc, ...) VL_MT_SAFE {
     // While threadsafe, each thread can only access different file handles
     FILE* const fp = VL_CVT_I_FP(fpi);
     if (VL_UNLIKELY(!fp)) return ~0U;  // -1
 
+    WDataInP fromp{nullptr};
     va_list ap;
     va_start(ap, argc);
-    const IData got = _vl_vsscanf(fp, 0, nullptr, "", format, argc, ap);
+    const IData got = _vl_vsscanf(fp, 0, fromp, "", format, argc, ap);
     va_end(ap);
     return got;
 }
@@ -1962,10 +2155,11 @@ IData VL_SSCANF_IWNX(int lbits, const WDataInP lwp, const std::string& format, i
 }
 IData VL_SSCANF_INNX(int, const std::string& ld, const std::string& format, int argc,
                      ...) VL_MT_SAFE {
+    WDataInP fromp{nullptr};
     va_list ap;
     va_start(ap, argc);
     const IData got
-        = _vl_vsscanf(nullptr, static_cast<int>(ld.length() * 8), nullptr, ld, format, argc, ap);
+        = _vl_vsscanf(nullptr, static_cast<int>(ld.length() * 8), fromp, ld, format, argc, ap);
     va_end(ap);
     return got;
 }
@@ -2049,7 +2243,8 @@ IData VL_FREAD_I(int width, int array_lsb, int array_size, void* memp, IData fpi
             if (shift == start_shift) *datap = 0;
             *datap |= ((static_cast<QData>(c) << static_cast<QData>(shift)) & VL_MASK_Q(width));
         } else {
-            WDataOutP datap = &(reinterpret_cast<WDataOutP>(memp))[entry * VL_WORDS_I(width)];
+            const WDataOutP datap = WDataOutP::external(
+                &(reinterpret_cast<EData*>(memp))[entry * VL_WORDS_I(width)]);
             if (shift == start_shift) VL_ZERO_W(width, datap);
             datap[VL_BITWORD_E(shift)] |= (static_cast<EData>(c) << VL_BITBIT_E(shift));
         }
@@ -2144,7 +2339,13 @@ IData VL_SYSTEM_IW(int lhswords, const WDataInP lhsp) VL_MT_SAFE {
     return VL_SYSTEM_IN(lhs);
 }
 IData VL_SYSTEM_IN(const std::string& lhs) VL_MT_SAFE {
+    VerilatedContext* ctxp = Verilated::threadContextp();
+    const bool sending = ctxp->logOutputToFile();
+    // system() command may echo and read so restore default stdout and stderr if sending
+    if (sending) ctxp->logRestoreOutput();
     const int code = std::system(lhs.c_str());  // Yes, std::system() is threadsafe
+    // Log to file again if we were sending
+    if (sending) ctxp->logOutputToFile(true /* append */);
     return code >> 8;  // Want exit status
 }
 
@@ -2542,7 +2743,7 @@ void VlReadMem::setData(void* valuep, const std::string& rhs) {
             *datap = ((*datap << static_cast<QData>(shift)) + static_cast<QData>(value))
                      & VL_MASK_Q(m_bits);
         } else {
-            WDataOutP datap = reinterpret_cast<WDataOutP>(valuep);
+            const WDataOutP datap = WDataOutP::external(reinterpret_cast<EData*>(valuep));
             if (!innum) VL_ZERO_W(m_bits, datap);
             _vl_shiftl_inplace_w(m_bits, datap, static_cast<IData>(shift));
             datap[0] |= value;
@@ -2614,7 +2815,7 @@ void VlWriteMem::print(QData addr, bool addrstamp, const void* valuep) {
             fprintf(m_fp, "%s\n", formatBinary(32, lo));
         }
     } else {
-        const WDataInP datap = reinterpret_cast<WDataInP>(valuep);
+        const WDataInP datap = WDataInP::external(reinterpret_cast<const EData*>(valuep));
         // output as a sequence of VL_EDATASIZE'd words
         // from MSB to LSB. Mask off the MSB word which could
         // contain junk above the top of valid data.
@@ -2682,8 +2883,8 @@ void VL_READMEM_N(bool hex,  // Hex format, else binary
                     QData* const datap = &(reinterpret_cast<QData*>(memp))[entry];
                     rmem.setData(datap, value);
                 } else {
-                    WDataOutP datap
+                    EData* const datap
-                        = &(reinterpret_cast<WDataOutP>(memp))[entry * VL_WORDS_I(bits)];
+                        = &(reinterpret_cast<EData*>(memp))[entry * VL_WORDS_I(bits)];
                     rmem.setData(datap, value);
                 }
             }
@@ -2725,8 +2926,8 @@ void VL_WRITEMEM_N(bool hex,  // Hex format, else binary
             const QData* const datap = &(reinterpret_cast<const QData*>(memp))[row_offset];
             wmem.print(addr, false, datap);
         } else {
-            const WDataInP memDatap = reinterpret_cast<WDataInP>(memp);
+            const EData* const datap
-            const WDataInP datap = &memDatap[row_offset * VL_WORDS_I(bits)];
+                = &(reinterpret_cast<const EData*>(memp))[row_offset * VL_WORDS_I(bits)];
             wmem.print(addr, false, datap);
         }
     }
@@ -2854,6 +3055,9 @@ VerilatedContext::VerilatedContext()
     m_ns.m_profExecFilename = "profile_exec.dat";
     m_ns.m_profVltFilename = "profile.vlt";
     m_ns.m_solverProgram = VlOs::getenvStr("VERILATOR_SOLVER", VL_SOLVER_DEFAULT);
+    m_ns.m_logFD = -1;
+    m_ns.m_stdoutFD = -1;
+    m_ns.m_stderrFD = -1;
     m_fdps.resize(31);
     std::fill(m_fdps.begin(), m_fdps.end(), static_cast<FILE*>(nullptr));
     m_fdFreeMct.resize(30);
@@ -2865,6 +3069,7 @@ VerilatedContext::VerilatedContext()
 VerilatedContext::~VerilatedContext() {
     checkMagic(this);
     m_magic = 0x1;  // Arbitrary but 0x1 is what Verilator src uses for a deleted pointer
+    logRestoreOutput();
 }
 
 void VerilatedContext::checkMagic(const VerilatedContext* contextp) {
@@ -2887,40 +3092,97 @@ void VerilatedContext::assertOn(bool flag) VL_MT_SAFE {
 }
 bool VerilatedContext::assertOnGet(VerilatedAssertType_t type,
                                    VerilatedAssertDirectiveType_t directive) const VL_MT_SAFE {
-    // Check if selected directive type bit in the assertOn is enabled for assertion type.
+    return assertCtlGet(VerilatedAssertCtlQuery::ASSERT_CTL_ON, type, directive);
-    // Note: it is assumed that this is checked only for one type at the time.
+}
-
+uint32_t VerilatedContext::assertOnMask(VerilatedAssertType_t types,
-    // Flag unspecified assertion types as disabled.
+                                        VerilatedAssertDirectiveType_t directives) VL_PURE {
-    if (type == 0) return false;
+    // Place the directive bits at each selected assertion type's 3-bit group.
-
+    uint32_t mask = 0;
-    // Get index of 3-bit group guarding assertion type status.
+    for (int i = 0; i < std::numeric_limits<VerilatedAssertType_t>::digits; ++i) {
-    // Since the assertOnGet is generated __always__ for a single assert type, we assume that only
+        if (VL_BITISSET_I(types, i)) mask |= directives << (i * ASSERT_DIRECTIVE_TYPE_MASK_WIDTH);
-    // a single bit will be set. Thus, ceil log2 will work fine.
+    }
-    VL_DEBUG_IFDEF(assert((type & (type - 1)) == 0););
+    return mask;
-    const IData typeMaskPosition = VL_CLOG2_I(type);
-
-    // Check if directive type bit is enabled in corresponding assertion type bits.
-    return m_s.m_assertOn & (directive << (typeMaskPosition * ASSERT_DIRECTIVE_TYPE_MASK_WIDTH));
 }
 void VerilatedContext::assertOnSet(VerilatedAssertType_t types,
                                    VerilatedAssertDirectiveType_t directives) VL_MT_SAFE {
-    // For each assertion type, set directive bits.
+    m_s.m_assertOn |= assertOnMask(types, directives);
-
-    // Iterate through all positions of assertion type bits. If bit for this assertion type is set,
-    // set directive type bits mask at this group index.
-    for (int i = 0; i < std::numeric_limits<VerilatedAssertType_t>::digits; ++i) {
-        if (VL_BITISSET_I(types, i))
-            m_s.m_assertOn |= directives << (i * ASSERT_DIRECTIVE_TYPE_MASK_WIDTH);
-    }
 }
 void VerilatedContext::assertOnClear(VerilatedAssertType_t types,
                                      VerilatedAssertDirectiveType_t directives) VL_MT_SAFE {
-    // Iterate through all positions of assertion type bits. If bit for this assertion type is set,
+    m_s.m_assertOn &= ~assertOnMask(types, directives);
-    // clear directive type bits mask at this group index.
+}
-    for (int i = 0; i < std::numeric_limits<VerilatedAssertType_t>::digits; ++i) {
+void VerilatedContext::assertCtl(uint32_t controlType, VerilatedAssertType_t types,
-        if (VL_BITISSET_I(types, i))
+                                 VerilatedAssertDirectiveType_t directives) VL_MT_SAFE {
-            m_s.m_assertOn &= ~(directives << (i * ASSERT_DIRECTIVE_TYPE_MASK_WIDTH));
+    // IEEE 1800-2023 Table 20-5 control_type. Lock freezes the On/Off state of the
+    // selected bits until Unlock; On/Off/Kill leave locked bits unchanged.
+    const uint32_t mask = assertOnMask(types, directives);
+    const uint32_t lockedMask = mask & ~m_s.m_assertLock;
+    switch (controlType) {
+    case 1:  // Lock
+        m_s.m_assertLock |= mask;
+        break;
+    case 2:  // Unlock
+        m_s.m_assertLock &= ~mask;
+        break;
+    case 3:  // On
+        m_s.m_assertOn |= lockedMask;
+        break;
+    case 4:  // Off
+        m_s.m_assertOn &= ~lockedMask;
+        break;
+    case 5: {  // Kill
+        m_s.m_assertOn &= ~lockedMask;
+        for (int slot = 0; slot < static_cast<int>(ASSERT_CONTROL_SLOT_COUNT); ++slot) {
+            if (VL_BITISSET_I(lockedMask, slot)) { m_s.m_assertKill[slot]++; }
         }
+        break;
+    }
+    case 6:  // PassOn
+        m_s.m_assertPassOnVacuous |= lockedMask;
+        m_s.m_assertPassOnNonvacuous |= lockedMask;
+        break;
+    case 7:  // PassOff
+        m_s.m_assertPassOnVacuous &= ~lockedMask;
+        m_s.m_assertPassOnNonvacuous &= ~lockedMask;
+        break;
+    case 8:  // FailOn
+        m_s.m_assertFailOn |= lockedMask;
+        break;
+    case 9:  // FailOff
+        m_s.m_assertFailOn &= ~lockedMask;
+        break;
+    case 10:  // NonvacuousOn
+        m_s.m_assertPassOnNonvacuous |= lockedMask;
+        break;
+    case 11:  // VacuousOff
+        m_s.m_assertPassOnVacuous &= ~lockedMask;
+        break;
+    default:
+        VL_WARN_MT("", 0, "",
+                   ("Bad $assertcontrol control_type '" + std::to_string(controlType)
+                    + "' (IEEE 1800-2023 Table 20-5)")
+                       .c_str());
+    }
+}
+uint32_t
+VerilatedContext::assertCtlGet(VerilatedAssertCtlQuery query, VerilatedAssertType_t type,
+                               VerilatedAssertDirectiveType_t directive) const VL_MT_SAFE {
+    const uint32_t mask = assertOnMask(type, directive);
+    if (!mask) return 0;
+    switch (query) {  // LCOV_EXCL_BR_LINE
+    case VerilatedAssertCtlQuery::ASSERT_CTL_ON: return (m_s.m_assertOn & mask) != 0;
+    case VerilatedAssertCtlQuery::ASSERT_CTL_KILL:
+        assert(mask && (mask & (mask - 1)) == 0);
+        return m_s.m_assertKill[VL_CLOG2_I(mask)];
+    case VerilatedAssertCtlQuery::ASSERT_CTL_PASS_ON_VACUOUS:
+        return (m_s.m_assertPassOnVacuous & mask) != 0;
+    case VerilatedAssertCtlQuery::ASSERT_CTL_PASS_ON_NONVACUOUS:
+        return (m_s.m_assertPassOnNonvacuous & mask) != 0;
+    case VerilatedAssertCtlQuery::ASSERT_CTL_FAIL_ON: return (m_s.m_assertFailOn & mask) != 0;
+    default:  // LCOV_EXCL_START
+        VL_FATAL_MT("", 0, "", "Internal: Bad assertCtlGet query");
+        VL_UNREACHABLE;
+    }  // LCOV_EXCL_STOP
 }
 void VerilatedContext::calcUnusedSigs(bool flag) VL_MT_SAFE {
     const VerilatedLockGuard lock{m_mutex};
@@ -2934,6 +3196,52 @@ std::string VerilatedContext::coverageFilename() const VL_MT_SAFE {
     const VerilatedLockGuard lock{m_mutex};
     return m_ns.m_coverageFilename;
 }
+void VerilatedContext::logFilename(const std::string& flag) VL_MT_SAFE {
+    const VerilatedLockGuard lock{m_mutex};
+    assert(m_ns.m_logFD == -1);
+    m_ns.m_logFilename = flag;
+}
+std::string VerilatedContext::logFilename() const VL_MT_SAFE {
+    const VerilatedLockGuard lock{m_mutex};
+    return m_ns.m_logFilename;
+}
+bool VerilatedContext::logOutputToFile() const VL_MT_SAFE {
+    const VerilatedLockGuard lock{m_mutex};
+    return m_ns.m_logFD >= 0;
+}
+void VerilatedContext::logOutputToFile(bool append) VL_MT_SAFE {
+    int log_fd = ::open(m_ns.m_logFilename.c_str(),
+                        O_WRONLY | O_CREAT | (append ? O_APPEND : O_TRUNC), 0666);
+    std::string error_msg;
+    if (log_fd >= 0) {
+        const VerilatedLockGuard lock{m_mutex};
+        m_ns.m_logFD = log_fd;
+        // See https://man7.org/linux/man-pages/man2/dup.2.html
+        m_ns.m_stdoutFD = ::dup(STDOUT_FILENO);  // Save original fd
+        ::dup2(m_ns.m_logFD, STDOUT_FILENO);  // Replace STDOUT_FILENO with m_logFD
+        m_ns.m_stderrFD = ::dup(STDERR_FILENO);  // Save original fd
+        ::dup2(m_ns.m_logFD, STDERR_FILENO);  // Replace STDERR_FILENO with m_logFD
+    } else {
+        const VerilatedLockGuard lock{m_mutex};
+        m_ns.m_logFD = -1;
+        const std::string op_str = append ? "appended" : "created";
+        error_msg = "Logfile " + m_ns.m_logFilename + " cannot be " + op_str;
+    }
+    if (!error_msg.empty()) { VL_FATAL_MT("", 0, "", error_msg.c_str()); }
+}
+void VerilatedContext::logRestoreOutput() VL_MT_SAFE {
+    const VerilatedLockGuard lock{m_mutex};
+    if (m_ns.m_logFD >= 0) {
+        std::fflush(stdout);  // Flush logfile
+        std::fflush(stderr);
+        ::dup2(m_ns.m_stdoutFD, STDOUT_FILENO);  // Restore STDOUT_FILENO with saved m_stdoutFD
+        ::dup2(m_ns.m_stderrFD, STDERR_FILENO);  // Restore STDERR_FILENO with saved m_stderrFD
+        ::close(m_ns.m_logFD);  // Close logfile
+        m_ns.m_logFD = -1;
+        m_ns.m_stdoutFD = -1;
+        m_ns.m_stderrFD = -1;
+    }
+}
 void VerilatedContext::dumpfile(const std::string& flag) VL_MT_SAFE_EXCLUDES(m_timeDumpMutex) {
     const VerilatedLockGuard lock{m_timeDumpMutex};
     m_dumpfile = flag;
@@ -3223,6 +3531,27 @@ std::pair<int, char**> VerilatedContextImp::argc_argv() VL_MT_SAFE_EXCLUDES(m_ar
     return std::make_pair(s_argc, s_argvp);
 }
 
+// Derive a non-deterministic non-zero positive seed value from the system
+// clocks. Used to implement +verilator+seed+0, which means "pick a random
+// seed". Returning the actual picked value lets $get_initial_random_seed()
+// expose it so the user can reproduce the run later by passing
+// +verilator+seed+<that_value>.
+static uint64_t pickRandomSeed() VL_MT_SAFE {
+    using namespace std::chrono;
+    // Combine steady_clock and system_clock to get entropy even when one has
+    // low resolution (e.g. high_resolution_clock aliases system_clock on MSVC).
+    const uint64_t t1 = static_cast<uint64_t>(
+        duration_cast<microseconds>(steady_clock::now().time_since_epoch()).count());
+    const uint64_t t2 = static_cast<uint64_t>(
+        duration_cast<microseconds>(system_clock::now().time_since_epoch()).count());
+    // vl_splitmix64 avalanches bits so closely-spaced timestamps look unrelated.
+    uint64_t seed = vl_splitmix64(t1 ^ t2).second;
+    // Keep within [1, INT_MAX] so it round-trips through the int seed field.
+    seed &= 0x7fffffffULL;
+    if (seed == 0) seed = 1;
+    return seed;
+}
+
 void VerilatedContextImp::commandArgVl(const std::string& arg) {
     if (0 == std::strncmp(arg.c_str(), "+verilator+", std::strlen("+verilator+"))) {
         std::string str;
@@ -3242,6 +3571,9 @@ void VerilatedContextImp::commandArgVl(const std::string& arg) {
             VL_PRINTF_MT("For help, please see 'verilator --help'\n");
             VL_FATAL_MT("COMMAND_LINE", 0, "",
                         "Exiting due to command line argument (not an error)");
+        } else if (commandArgVlString(arg, "+verilator+log+file+", str)) {
+            logFilename(str);
+            logOutputToFile(false /* append */);
         } else if (arg == "+verilator+noassert") {
             assertOn(false);
         } else if (commandArgVlUint64(arg, "+verilator+prof+exec+start+", u64)) {
@@ -3260,9 +3592,26 @@ void VerilatedContextImp::commandArgVl(const std::string& arg) {
             solverLogFilename(str);
         } else if (commandArgVlUint64(arg, "+verilator+wno+unsatconstr+", u64, 0, 1)) {
             warnUnsatConstr(u64 == 0);  // wno means disable, so invert
-        } else if (commandArgVlUint64(arg, "+verilator+seed+", u64, 1,
+        } else if (commandArgVlUint64(arg, "+verilator+seed+", u64, 0,
                                       std::numeric_limits<int>::max())) {
+            // +verilator+seed+0 means "pick a random seed". Replace the
+            // user-supplied 0 with a non-deterministic non-zero value derived
+            // from the high-resolution clock and store that as the actual
+            // seed, so $get_initial_random_seed() returns the picked value
+            // and the run can be reproduced by passing +verilator+seed+<that_value>.
+            if (u64 == 0) u64 = pickRandomSeed();
             randSeed(static_cast<int>(u64));
+        } else if (commandArgVlString(arg, "+verilator+vpi+", str)) {
+            // With --vpi, load the requested shared library now.  Without --vpi there is
+            // no VPI runtime, so warn the argument is ignored.
+#if VM_VPI
+            Verilated::loadVpiLib(str);
+#else
+            VL_WARN_MT(
+                "COMMAND_LINE", 0, "",
+                ("+verilator+vpi+ ignored: simulation was not compiled with --vpi '" + arg + "'")
+                    .c_str());  // LCOV_EXCL_LINE  (gcov zeroes this wrapped continuation line)
+#endif
         } else if (arg == "+verilator+V") {
             VerilatedImp::versionDump();  // Someday more info too
             VL_FATAL_MT("COMMAND_LINE", 0, "",
@@ -3355,7 +3704,7 @@ void VerilatedContext::statsPrintSummary() VL_MT_UNSAFE {
     const double walltime = statWallTimeSinceStart();
     const double cputime = statCpuTimeSinceStart();
     const std::string simtimePerf
-        = vl_timescaled_double((cputime != 0.0) ? (simtimeInUnits / cputime) : 0, "%0.3f %s");
+        = vl_timescaled_double((walltime != 0.0) ? (simtimeInUnits / walltime) : 0, "%0.3f %s");
     VL_PRINTF("- Verilator: %s at %s; walltime %0.3f s; speed %s/s\n", endwhy.c_str(),
               simtime.c_str(), walltime, simtimePerf.c_str());
     uint64_t memPeak;
@@ -3676,6 +4025,7 @@ std::unique_ptr<VerilatedTraceConfig> VerilatedModel::traceConfig() const { retu
 
 // cppcheck-suppress unusedFunction  // Used by applications
 uint32_t VerilatedVarProps::entSize() const VL_MT_SAFE {
+    if (m_entSize) return m_entSize;
     uint32_t size = 1;
     switch (vltype()) {
     case VLVT_PTR: size = sizeof(void*); break;
@@ -3792,6 +4142,27 @@ VerilatedVar* VerilatedScope::varInsert(const char* namep, void* datap, bool isP
     return &(m_varsp->find(namep)->second);
 }
 
+VerilatedVar* VerilatedScope::varInsertSized(const char* namep, void* datap, bool isParam,
+                                             VerilatedVarType vltype, int vlflags, int udims,
+                                             uint32_t entSize...) VL_MT_UNSAFE {
+    if (!m_varsp) m_varsp = new VerilatedVarNameMap;
+    VerilatedVar var(namep, datap, vltype, static_cast<VerilatedVarFlags>(vlflags), udims, 0,
+                     isParam, entSize);
+
+    va_list ap;
+    va_start(ap, entSize);
+    for (int i = 0; i < udims; ++i) {
+        const int msb = va_arg(ap, int);
+        const int lsb = va_arg(ap, int);
+        var.m_unpacked[i].m_left = msb;
+        var.m_unpacked[i].m_right = lsb;
+    }
+    va_end(ap);
+
+    m_varsp->emplace(namep, std::move(var));
+    return &(m_varsp->find(namep)->second);
+}
+
 VerilatedVar*
 VerilatedScope::forceableVarInsert(const char* namep, void* datap, bool isParam,
                                    VerilatedVarType vltype, int vlflags, void* forceReadSignalData,
@@ -3819,8 +4190,10 @@ VerilatedScope::forceableVarInsert(const char* namep, void* datap, bool isParam,
 
     va_list ap;
     va_start(ap, pdims);
-    assert(udims == 0);  // Forcing unpacked arrays is unsupported (#4735) and should have been
+    for (int i = 0; i < udims; ++i) {
-                         // checked in V3Force already.
+        forceReadSignal.m_unpacked[i].m_left = va_arg(ap, int);
+        forceReadSignal.m_unpacked[i].m_right = va_arg(ap, int);
+    }
     for (int i = 0; i < pdims; ++i) {
         const int msb = va_arg(ap, int);
         const int lsb = va_arg(ap, int);
@@ -3838,8 +4211,10 @@ VerilatedScope::forceableVarInsert(const char* namep, void* datap, bool isParam,
     verilatedForceControlSignalsp = nullptr;
 
     va_start(ap, pdims);
-    assert(udims == 0);  // Forcing unpacked arrays is unsupported (#4735) and should have been
+    for (int i = 0; i < udims; ++i) {
-                         // checked in V3Force already.
+        var.m_unpacked[i].m_left = va_arg(ap, int);
+        var.m_unpacked[i].m_right = va_arg(ap, int);
+    }
     for (int i = 0; i < pdims; ++i) {
         const int msb = va_arg(ap, int);
         const int lsb = va_arg(ap, int);

include/verilated.h

@@ -120,8 +120,7 @@ using CData = uint8_t;    ///< Data representing 'bit' of 1-8 packed bits
 using SData = uint16_t;   ///< Data representing 'bit' of 9-16 packed bits
 using IData = uint32_t;   ///< Data representing 'bit' of 17-32 packed bits
 using QData = uint64_t;   ///< Data representing 'bit' of 33-64 packed bits
-using EData = uint32_t;   ///< Data representing one element of WData array
+using EData = uint32_t;   ///< Data representing one element of VlWide
-using WData = EData;        ///< Data representing >64 packed bits (used as pointer)
 //    F     = float;        // No typedef needed; Verilator uses float
 //    D     = double;       // No typedef needed; Verilator uses double
 //    N     = std::string;  // No typedef needed; Verilator uses string
@@ -129,9 +128,6 @@ using WData = EData;        ///< Data representing >64 packed bits (used as poin
 //    R     = VlQueue;
 // clang-format on
 
-using WDataInP = const WData*;  ///< 'bit' of >64 packed bits as array input to a function
-using WDataOutP = WData*;  ///< 'bit' of >64 packed bits as array output from a function
-
 enum VerilatedVarType : uint8_t {
     VLVT_UNKNOWN = 0,
     VLVT_PTR,  // Pointer to something
@@ -139,12 +135,14 @@ enum VerilatedVarType : uint8_t {
     VLVT_UINT16,  // AKA SData
     VLVT_UINT32,  // AKA IData
     VLVT_UINT64,  // AKA QData
-    VLVT_WDATA,  // AKA WData
+    VLVT_WDATA,  // AKA VlWide
     VLVT_STRING,  // C++ string
-    VLVT_REAL  // AKA double
+    VLVT_REAL,  // AKA double
+    VLVT_STRUCT,  // SystemVerilog unpacked struct
+    VLVT_UNION  // SystemVerilog unpacked union
 };
 
-enum VerilatedVarFlags {
+enum VerilatedVarFlags : uint32_t {
     VLVD_0 = 0,  // None
     VLVD_IN = 1,  // == vpiInput
     VLVD_OUT = 2,  // == vpiOutput
@@ -158,7 +156,8 @@ enum VerilatedVarFlags {
     VLVF_CONTINUOUSLY = (1 << 11),  // Is continously assigned
     VLVF_FORCEABLE = (1 << 12),  // Forceable
     VLVF_SIGNED = (1 << 13),  // Signed integer
-    VLVF_BITVAR = (1 << 14)  // Four state bit (vs two state logic)
+    VLVF_BITVAR = (1 << 14),  // Four state bit (vs two state logic)
+    VLVF_NET = (1 << 15)  // Net object
 };
 
 // IEEE 1800-2023 Table 20-6
@@ -179,6 +178,15 @@ enum class VerilatedAssertDirectiveType : uint8_t {
     DIRECTIVE_TYPE_COVER = (1 << 1),
     DIRECTIVE_TYPE_ASSUME = (1 << 2),
 };
+
+/// Runtime query selector for assertion-control state
+enum class VerilatedAssertCtlQuery : uint8_t {
+    ASSERT_CTL_ON,
+    ASSERT_CTL_KILL,
+    ASSERT_CTL_PASS_ON_VACUOUS,
+    ASSERT_CTL_PASS_ON_NONVACUOUS,
+    ASSERT_CTL_FAIL_ON,
+};
 using VerilatedAssertType_t = std::underlying_type<VerilatedAssertType>::type;
 using VerilatedAssertDirectiveType_t = std::underlying_type<VerilatedAssertDirectiveType>::type;
 
@@ -360,6 +368,10 @@ private:
     static constexpr size_t ASSERT_ON_WIDTH
         = ASSERT_DIRECTIVE_TYPE_MASK_WIDTH * std::numeric_limits<VerilatedAssertType_t>::digits
           + 1;
+    // Build the assertion-control bit mask for the given assertion x directive types.
+    static uint32_t assertOnMask(VerilatedAssertType_t types,
+                                 VerilatedAssertDirectiveType_t directives) VL_PURE;
+    static constexpr size_t ASSERT_CONTROL_SLOT_COUNT = ASSERT_ON_WIDTH - 1;
 
 protected:
     // TYPES
@@ -379,6 +391,16 @@ protected:
                                                     // for each VerilatedAssertType we store
                                                     // 3-bits, one for each directive type. Last
                                                     // bit guards internal directive types.
+        std::atomic<uint32_t> m_assertLock{0};  // Locked assertion bits (IEEE 1800-2023 20.11
+                                                // Lock/Unlock); same layout as m_assertOn. While
+                                                // a bit is locked, On/Off/Kill leave it unchanged.
+        std::atomic<uint32_t> m_assertPassOnVacuous{
+            std::numeric_limits<uint32_t>::max()};  // Enabled vacuous pass actions
+        std::atomic<uint32_t> m_assertPassOnNonvacuous{
+            std::numeric_limits<uint32_t>::max()};  // Enabled nonvacuous pass actions
+        std::atomic<uint32_t> m_assertFailOn{
+            std::numeric_limits<uint32_t>::max()};  // Enabled fail actions
+        std::array<std::atomic<uint32_t>, ASSERT_CONTROL_SLOT_COUNT> m_assertKill{};
         bool m_calcUnusedSigs = false;  // Waves file on, need all signals calculated
         bool m_fatalOnError = true;  // Fatal on $stop/non-fatal error
         bool m_fatalOnVpiError = true;  // Fatal on vpi error/unsupported
@@ -391,7 +413,7 @@ protected:
         int m_errorCount = 0;  // Number of errors
         int m_errorLimit = 1;  // Stop on error number
         int m_randReset = 0;  // Random reset: 0=all 0s, 1=all 1s, 2=random
-        int m_randSeed = 0;  // Random seed: 0=random
+        int m_randSeed = 1;  // Random seed (default 1; +verilator+seed+0 picks at parse time)
         static constexpr int UNITS_NONE = 99;  // Default based on precision
         int m_timeFormatUnits = UNITS_NONE;  // $timeformat units
         int m_timeFormatPrecision = 0;  // $timeformat number of decimal places
@@ -413,6 +435,7 @@ protected:
         uint32_t m_profExecWindow = 2;  // +prof+exec+window size
         // Slow path
         std::string m_coverageFilename;  // +coverage+file filename
+        std::string m_logFilename;  // +log+file filename
         std::string m_profExecFilename;  // +prof+exec+file filename
         std::string m_profVltFilename;  // +prof+vlt filename
         std::string m_solverLogFilename;  // SMT solver log filename
@@ -421,6 +444,9 @@ protected:
         VlOs::DeltaCpuTime m_cpuTimeStart{false};  // CPU time, starts when create first model
         VlOs::DeltaWallTime m_wallTimeStart{false};  // Wall time, starts when create first model
         std::vector<traceBaseModelCb_t> m_traceBaseModelCbs;  // Callbacks to traceRegisterModel
+        int m_stdoutFD;  // Duplicated stdout file descriptor
+        int m_stderrFD;  // Duplicated stderr file descriptor
+        int m_logFD;  // Log file descriptor
     } m_ns;
 
     mutable VerilatedMutex m_argMutex;  // Protect m_argVec, m_argVecLoaded
@@ -484,6 +510,13 @@ public:
     /// Clear enabled status for given assertion types
     void assertOnClear(VerilatedAssertType_t types,
                        VerilatedAssertDirectiveType_t directives) VL_MT_SAFE;
+    /// Apply assertion control for given control, assertion, and directive types
+    void assertCtl(uint32_t controlType, VerilatedAssertType_t types,
+                   VerilatedAssertDirectiveType_t directives) VL_MT_SAFE;
+    /// Get assertion-control runtime state. Boolean queries return 0/1, Kill returns
+    /// the generation count.
+    uint32_t assertCtlGet(VerilatedAssertCtlQuery query, VerilatedAssertType_t type,
+                          VerilatedAssertDirectiveType_t directive) const VL_MT_SAFE;
     /// Return if calculating of unused signals (for traces)
     bool calcUnusedSigs() const VL_MT_SAFE { return m_s.m_calcUnusedSigs; }
     /// Enable calculation of unused signals (for traces)
@@ -654,6 +687,13 @@ public:
     std::string coverageFilename() const VL_MT_SAFE;
     void coverageFilename(const std::string& flag) VL_MT_SAFE;
 
+    // Internal: logfile
+    std::string logFilename() const VL_MT_SAFE;
+    void logFilename(const std::string& flag) VL_MT_SAFE;
+    bool logOutputToFile() const VL_MT_SAFE;
+    void logOutputToFile(bool append) VL_MT_SAFE;
+    void logRestoreOutput() VL_MT_SAFE;
+
     // Internal: $dumpfile
     std::string dumpfile() const VL_MT_SAFE_EXCLUDES(m_timeDumpMutex);
     void dumpfile(const std::string& flag) VL_MT_SAFE_EXCLUDES(m_timeDumpMutex);
@@ -744,6 +784,9 @@ public:  // But internals only - called from verilated modules, VerilatedSyms
     void exportInsert(int finalize, const char* namep, void* cb) VL_MT_UNSAFE;
     VerilatedVar* varInsert(const char* namep, void* datap, bool isParam, VerilatedVarType vltype,
                             int vlflags, int udims, int pdims, ...) VL_MT_UNSAFE;
+    VerilatedVar* varInsertSized(const char* namep, void* datap, bool isParam,
+                                 VerilatedVarType vltype, int vlflags, int udims, uint32_t entSize,
+                                 ...) VL_MT_UNSAFE;
     VerilatedVar* forceableVarInsert(const char* namep, void* datap, bool isParam,
                                      VerilatedVarType vltype, int vlflags,
                                      void* forceReadSignalData, const char* forceReadSignalName,
@@ -993,6 +1036,9 @@ public:
     static void scTraceBeforeElaborationError() VL_ATTR_NORETURN VL_MT_SAFE;
     static void stackCheck(QData needSize) VL_MT_UNSAFE;
 
+    // Internal: Load a VPI shared library (+verilator+vpi+<lib>[:<bootstrap>])
+    static void loadVpiLib(const std::string& arg) VL_MT_UNSAFE;
+
     // Internal: Get and set DPI context
     static const VerilatedScope* dpiScope() VL_MT_SAFE { return t_s.t_dpiScopep; }
     static void dpiScope(const VerilatedScope* scopep) VL_MT_SAFE { t_s.t_dpiScopep = scopep; }

include/verilated.mk.in

@@ -52,6 +52,9 @@ CFG_GCH_IF_CLANG = @CFG_GCH_IF_CLANG@
 CFG_LDFLAGS_VERILATED = @CFG_LDFLAGS_VERILATED@
 # Linker libraries for multithreading
 CFG_LDLIBS_THREADS = @CFG_LDLIBS_THREADS@
+# Linker flags/libraries for runtime VPI library loading (+verilator+vpi+<lib>)
+CFG_LDFLAGS_DYNAMIC = @CFG_LDFLAGS_DYNAMIC@
+CFG_LDLIBS_DYNAMIC = @CFG_LDLIBS_DYNAMIC@
 
 ######################################################################
 # Programs
@@ -93,6 +96,7 @@ VK_CPPFLAGS_ALWAYS += \
   -DVM_TRACE_FST=$(VM_TRACE_FST) \
   -DVM_TRACE_VCD=$(VM_TRACE_VCD) \
   -DVM_TRACE_SAIF=$(VM_TRACE_SAIF) \
+  -DVM_VPI=$(VM_VPI) \
   $(CFG_CXXFLAGS_NO_UNUSED) \
 
 ifeq ($(CFG_WITH_CCWARN),yes)  # Local... Else don't burden users
@@ -205,6 +209,12 @@ VK_OBJS_SLOW = $(addsuffix .o, $(VM_SLOW))
 
 VK_USER_OBJS = $(addsuffix .o, $(VM_USER_CLASSES))
 
+ifneq ($(VM_TRACE_FST),0)
+ifneq ($(VM_TRACE_FST),)
+    LDLIBS += -llz4 -lz
+endif
+endif
+
 # Note VM_GLOBAL_FAST and VM_GLOBAL_SLOW holds the files required from the
 # run-time library. In practice everything is actually in VM_GLOBAL_FAST,
 # but keeping the distinction for compatibility for now.

include/verilated_cov_key.h

@@ -39,6 +39,7 @@ VLCOVGEN_ITEM("'name':'per_instance','short':'P',  'group':1, 'default':0,    'd
 VLCOVGEN_ITEM("'name':'thresh',      'short':'s',  'group':1, 'default':None, 'descr':'Number of hits to consider covered (aka at_least)'")
 VLCOVGEN_ITEM("'name':'type',        'short':'t',  'group':1, 'default':'',   'descr':'Type of coverage (block, line, fsm, etc)'")
 // Bin attributes
+VLCOVGEN_ITEM("'name':'cross_bins',   'short':'Cb', 'group':0, 'default':'',   'descr':'Comma-separated per-dimension bin names for cross coverage points'")
 VLCOVGEN_ITEM("'name':'comment',     'short':'o',  'group':0, 'default':'',   'descr':'Textual description for the item'")
 VLCOVGEN_ITEM("'name':'fsm_from',    'short':'Ff', 'group':0, 'default':'',   'descr':'FSM source state name for structured FSM coverage points'")
 VLCOVGEN_ITEM("'name':'fsm_tag',     'short':'Fg', 'group':0, 'default':'',   'descr':'FSM point tag such as reset, reset_include, or default'")
@@ -52,6 +53,7 @@ VLCOVGEN_ITEM("'name':'weight',      'short':'w',  'group':0, 'default':None, 'd
 // VLCOVGEN_CIK_AUTO_EDIT_BEGIN
 #define VL_CIK_COLUMN "n"
 #define VL_CIK_COMMENT "o"
+#define VL_CIK_CROSS_BINS "Cb"
 #define VL_CIK_FILENAME "f"
 #define VL_CIK_FSM_FROM "Ff"
 #define VL_CIK_FSM_TAG "Fg"
@@ -77,6 +79,7 @@ public:
         // VLCOVGEN_SHORT_AUTO_EDIT_BEGIN
         if (key == "column") return VL_CIK_COLUMN;
         if (key == "comment") return VL_CIK_COMMENT;
+        if (key == "cross_bins") return VL_CIK_CROSS_BINS;
         if (key == "filename") return VL_CIK_FILENAME;
         if (key == "fsm_from") return VL_CIK_FSM_FROM;
         if (key == "fsm_tag") return VL_CIK_FSM_TAG;

include/verilated_cov_model.h

@@ -0,0 +1,63 @@
+// -*- mode: C++; c-file-style: "cc-mode" -*-
+//=============================================================================
+//
+// Code available from: https://verilator.org
+//
+// This program is free software; you can redistribute it and/or modify it
+// under the terms of either the GNU Lesser General Public License Version 3
+// or the Perl Artistic License Version 2.0.
+// SPDX-FileCopyrightText: 2024-2026 Wilson Snyder
+// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+//
+//=============================================================================
+///
+/// \file
+/// \brief Verilated functional-coverage model interfaces
+///
+/// Defines interface classes to runtime covergroup coverage-collection classes.
+/// These are used to query coverage achievement at runtime, and (future)
+/// when writing coverage to the coverage database.
+///
+//=============================================================================
+
+#ifndef VERILATOR_VERILATED_COV_MODEL_H_
+#define VERILATOR_VERILATED_COV_MODEL_H_
+
+#include "verilatedos.h"
+
+#include <cstdint>
+#include <string>
+
+// Per-bin classification.  A bin's kind is which set it lives in (structural),
+// not a per-bin field.  Only Normal feeds coverage(); the rest are recorded.
+// Enumerators are 'KIND_'-prefixed because the bare LRM terms collide with
+// <windows.h> macros (e.g. IGNORE), which the preprocessor would expand.
+enum class VlCovBinKind : uint8_t {
+    KIND_NORMAL = 0,  // Base coverage-collecting bin
+    KIND_DEFAULT = 1,  // Bin declared with 'default' range (which is excluded per LRM)
+    KIND_IGNORE = 2,  // Ignore bin
+    KIND_ILLEGAL = 3  // Illegal bin
+};
+
+//=============================================================================
+// VlCoverpointIf
+/// Read-side view of a coverpoint.  The writer queries bins by index; the
+/// implementor computes names/kinds on demand.  Bounded bin count, so random
+/// access by index is the primary usage.
+
+class VlCoverpointIf VL_NOT_FINAL {
+public:
+    // CONSTRUCTORS
+    virtual ~VlCoverpointIf() = default;
+
+    // METHODS
+    // All bins, across every set; index range [0, binCount())
+    virtual int binCount() const = 0;
+    // Bin name in declaration order (e.g. "myBin" or "b[3]")
+    virtual std::string binName(int i) const = 0;
+    virtual VlCovBinKind binKind(int i) const = 0;
+    // Bins covered / effective total (Normal set only) for the coverage calc
+    virtual void coverageParts(double& covered, double& total) const = 0;
+};
+
+#endif  // Guard

include/verilated_covergroup.cpp

@@ -0,0 +1,83 @@
+// -*- mode: C++; c-file-style: "cc-mode" -*-
+//=============================================================================
+//
+// Code available from: https://verilator.org
+//
+// This program is free software; you can redistribute it and/or modify it
+// under the terms of either the GNU Lesser General Public License Version 3
+// or the Perl Artistic License Version 2.0.
+// SPDX-FileCopyrightText: 2024-2026 Wilson Snyder
+// SPDX-License-Identifier: LGPL-3.0-only OR Artistic-2.0
+//
+//=============================================================================
+///
+/// \file
+/// \brief Verilated functional-coverage collection runtime implementation
+///
+/// Linked when covergroups are present.  The coverage-database registration
+/// is compiled only with "verilator --coverage".
+///
+//=============================================================================
+
+#include "verilatedos.h"
+
+#include "verilated_covergroup.h"
+
+#if VM_COVERAGE
+#include "verilated_cov.h"
+#endif
+
+void VlCoverpoint::init(const char* hier, uint32_t atLeast, int nBins) {
+    m_hier = hier;
+    m_atLeast = atLeast;
+    m_total = nBins;
+    m_counts.assign(nBins, 0);
+}
+
+void VlCoverpoint::addNamer(VlCovBinKind set, int count, VlCovBinNaming naming, const char* name,
+                            const char* file, int line, int col) {
+    m_namers.emplace_back(set, count, m_nextBase, naming, name, file, line, col);
+    m_nextBase += count;
+    if (set == VlCovBinKind::KIND_NORMAL) m_normal += count;
+}
+
+const VlCovNamer& VlCoverpoint::namerFor(int i) const {
+    // Namers are appended in ascending, contiguous index order covering [0, m_total),
+    // and i is always a valid bin index, so the matching namer always exists.
+    for (const VlCovNamer& nm : m_namers) {
+        if (i < nm.base() + nm.count()) return nm;
+    }
+    VL_UNREACHABLE;
+}
+
+std::string VlCoverpoint::binName(int i) const {
+    const VlCovNamer& nm = namerFor(i);
+    std::string name = nm.name();
+    if (nm.naming() == VlCovBinNaming::Array) name += '[' + std::to_string(i - nm.base()) + ']';
+    return name;
+}
+
+#if VM_COVERAGE
+void VlCoverpoint::registerBins(VerilatedCovContext* covcontextp, const char* page) {
+    for (int i = 0; i < binCount(); ++i) {
+        const VlCovNamer& nm = namerFor(i);
+        const VlCovBinKind kind = binKind(i);
+        const std::string binp = binName(i);
+        const std::string full = m_hier + "." + binp;
+        const std::string lineStr = std::to_string(nm.line());
+        const std::string colStr = std::to_string(nm.col());
+        if (kind == VlCovBinKind::KIND_NORMAL) {
+            VL_COVER_INSERT(covcontextp, full.c_str(), &m_counts[i], "page", page, "filename",
+                            nm.file(), "lineno", lineStr.c_str(), "column", colStr.c_str(), "bin",
+                            binp.c_str());
+        } else {
+            const char* const binType = kind == VlCovBinKind::KIND_IGNORE    ? "ignore"
+                                        : kind == VlCovBinKind::KIND_ILLEGAL ? "illegal"
+                                                                             : "default";
+            VL_COVER_INSERT(covcontextp, full.c_str(), &m_counts[i], "page", page, "filename",
+                            nm.file(), "lineno", lineStr.c_str(), "column", colStr.c_str(), "bin",
+                            binp.c_str(), "bin_type", binType);
+        }
+    }
+}
+#endif  // VM_COVERAGE