uc-toffee 2.0.0__tar.gz

uc_toffee-2.0.0/.github/native-dependencies.json

@@ -0,0 +1,9 @@
+{
+  "xcomm": {
+    "repository": "XS-MLVP/xcomm",
+    "ref": "69e993d4fc0c8786819d2beae50a2197ea4ab124",
+    "package_version": "1.1.0",
+    "native_abi": 3,
+    "coverage_protocol": 5
+  }
+}

uc_toffee-2.0.0/.github/workflows/ci.yml

@@ -0,0 +1,175 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      ref:
+        type: string
+        default: ""
+      expected-version:
+        type: string
+        default: ""
+      artifact-name:
+        type: string
+        default: toffee-dist
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.sha }}
+      - name: Read native dependency pin
+        id: native
+        run: |
+          python - <<'PY'
+          import json, os, re
+          pin = json.load(open('.github/native-dependencies.json'))['xcomm']
+          assert re.fullmatch(r'[0-9a-f]{40}', pin['ref'])
+          with open(os.environ['GITHUB_OUTPUT'], 'a') as output:
+              for key in ('repository', 'ref', 'package_version', 'native_abi', 'coverage_protocol'):
+                  print(f'{key}={pin[key]}', file=output)
+          PY
+      - uses: actions/checkout@v4
+        with:
+          repository: ${{ steps.native.outputs.repository }}
+          ref: ${{ steps.native.outputs.ref }}
+          fetch-depth: 0
+          path: _deps/xcomm
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install build and report tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends build-essential cmake ninja-build lcov verilator
+          python -m pip install 'build>=1,<2'
+      - name: Build pinned native backend
+        # This wheel is reused by another runner during isolated installation.
+        run: python -m build --wheel ./_deps/xcomm --outdir native-wheel -Ccmake.define.XSPCOMM_NATIVE=OFF
+        env:
+          BUILD_XSPCOMM_SWIG: python
+          XSPCOMM_BUILD_WHEEL: "1"
+          CMAKE_BUILD_PARALLEL_LEVEL: "2"
+          SETUPTOOLS_SCM_PRETEND_VERSION_FOR_UC_XCOMM: ${{ steps.native.outputs.package_version }}
+      - name: Install Toffee with the pinned dependency
+        run: |
+          python -m pip install native-wheel/*.whl '.[test]'
+          python -m pip check
+      - uses: actions/upload-artifact@v4
+        if: matrix.python-version == '3.12'
+        with:
+          name: ${{ inputs.artifact-name || 'toffee-dist' }}-native-cp312
+          path: native-wheel/*.whl
+          if-no-files-found: error
+      - name: Require the tested package, native ABI and coverage protocol
+        env:
+          EXPECTED_PACKAGE_VERSION: ${{ steps.native.outputs.package_version }}
+          EXPECTED_NATIVE_ABI: ${{ steps.native.outputs.native_abi }}
+          EXPECTED_COVERAGE_PROTOCOL: ${{ steps.native.outputs.coverage_protocol }}
+        run: |
+          python - <<'PY'
+          from importlib.metadata import version
+          import os, xspcomm
+          assert version('uc-xcomm') == os.environ['EXPECTED_PACKAGE_VERSION']
+          assert xspcomm.version() == os.environ['EXPECTED_PACKAGE_VERSION']
+          assert xspcomm.abi_version() == int(os.environ['EXPECTED_NATIVE_ABI'])
+          assert xspcomm.XTriggerEngine.CoverageVersion() == int(os.environ['EXPECTED_COVERAGE_PROTOCOL'])
+          for method in ('AcquireClock', 'ReleaseClock', 'CollectExpressions', 'ExprNewBits', 'ExprNewBool', 'ExprEvalBits'):
+              assert hasattr(xspcomm.XTriggerEngine, method), method
+          PY
+      - run: python -m pytest -q --require-xspcomm
+      - name: Run documented command-line examples
+        run: |
+          python examples/getting_started/check_native.py
+          python -m pytest -q examples/getting_started/native_lab.py
+          python examples/triggers/basic_execution.py
+          python examples/coverage/functional_coverage.py
+          python examples/triggers/subscription.py
+          python examples/transactions/scoreboard.py
+          python -m examples.transactions.reference_model
+          python -m examples.transactions.reference_model --backend native
+          python examples/transactions/pipeline.py
+          python examples/transactions/pipeline.py --backend native
+          python -m examples.coverage.trigger_bins --engine xcomm --strategy native
+
+  docs:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install 'mkdocs>=1.6'
+      - run: mkdocs build --strict
+
+  package:
+    needs: [test, docs]
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: python -m pip install 'build>=1,<2' 'twine>=6,<7'
+      - name: Build and validate distributions
+        env:
+          EXPECTED_VERSION: ${{ inputs.expected-version }}
+        run: |
+          python -m build
+          python -m twine check --strict dist/*.whl dist/*.tar.gz
+          python scripts/release/verify_dist.py --expected-version "$EXPECTED_VERSION"
+      - name: Rebuild from the source distribution without Git metadata
+        run: |
+          mkdir -p "$RUNNER_TEMP/sdist-source" "$RUNNER_TEMP/sdist-wheel"
+          tar -xf dist/uc_toffee-*.tar.gz -C "$RUNNER_TEMP/sdist-source"
+          source_dir=("$RUNNER_TEMP"/sdist-source/uc_toffee-*)
+          python -m build --wheel "${source_dir[0]}" --outdir "$RUNNER_TEMP/sdist-wheel"
+          original=(dist/*.whl)
+          rebuilt=("$RUNNER_TEMP"/sdist-wheel/*.whl)
+          test "$(basename "${original[0]}")" = "$(basename "${rebuilt[0]}")"
+      - uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name || 'toffee-dist' }}-native-cp312
+          path: native-wheel
+      - name: Install the wheel in an isolated environment
+        run: |
+          python -m venv "$RUNNER_TEMP/wheel-test"
+          "$RUNNER_TEMP/wheel-test/bin/python" -m pip install --no-index --find-links=native-wheel dist/*.whl
+          "$RUNNER_TEMP/wheel-test/bin/python" -m pip check
+          "$RUNNER_TEMP/wheel-test/bin/python" -I -c 'from importlib.metadata import version; from importlib.resources import files; import toffee; assert files("toffee").joinpath("templates/unified_coverage.html").is_file(); print(version("uc-toffee"), toffee.__file__)'
+      - name: Record exact tested build provenance
+        env:
+          EXPECTED_VERSION: ${{ inputs.expected-version }}
+        run: python scripts/release/verify_dist.py --expected-version "$EXPECTED_VERSION" --manifest --verify-manifest
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact-name || 'toffee-dist' }}
+          path: dist/*
+          if-no-files-found: error

uc_toffee-2.0.0/.github/workflows/release.yml

@@ -0,0 +1,126 @@
+name: Tagged release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+  repository_dispatch:
+    types: [version-tagged]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing merged-PR release tag (vX.Y.Z) to verify and publish"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  pull-requests: read
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: toffee-release-${{ github.event.client_payload.tag || inputs.tag || github.ref_name }}
+  queue: max
+  cancel-in-progress: false
+
+jobs:
+  resolve:
+    runs-on: ubuntu-24.04
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+      version: ${{ steps.version.outputs.version }}
+      sha: ${{ steps.version.outputs.sha }}
+    env:
+      TAG: ${{ github.event.client_payload.tag || inputs.tag || github.ref_name }}
+    steps:
+      - name: Check tag syntax before checkout
+        run: '[[ "$TAG" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$ ]]'
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ env.TAG }}
+      - name: Verify tag and merge provenance
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+          EXPECTED_SHA: ${{ github.event.client_payload.sha }}
+        run: |
+          git fetch origin main:refs/remotes/origin/main --tags
+          sha="$(git rev-parse HEAD)"
+          test "$sha" = "$(git rev-parse "refs/tags/${TAG}^{commit}")"
+          if [[ -n "$EXPECTED_SHA" ]]; then
+            test "$sha" = "$EXPECTED_SHA"
+          fi
+          python scripts/release/version_policy.py verify
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+          echo "sha=$sha" >> "$GITHUB_OUTPUT"
+
+  checks:
+    needs: resolve
+    uses: ./.github/workflows/ci.yml
+    with:
+      ref: ${{ needs.resolve.outputs.sha }}
+      expected-version: ${{ needs.resolve.outputs.version }}
+      artifact-name: release-dist-${{ needs.resolve.outputs.tag }}
+
+  publish:
+    needs: [resolve, checks]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.resolve.outputs.sha }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist-${{ needs.resolve.outputs.tag }}
+          path: release-assets
+      - name: Recheck tag and exact tested distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ needs.resolve.outputs.tag }}
+          VERSION: ${{ needs.resolve.outputs.version }}
+        run: |
+          git fetch origin main:refs/remotes/origin/main --tags
+          test "$(git rev-parse HEAD)" = "$(git rev-parse "refs/tags/${TAG}^{commit}")"
+          python scripts/release/version_policy.py verify
+          python scripts/release/verify_dist.py --dist release-assets --expected-version "$VERSION" --verify-manifest --existing-tag "$TAG"
+      - name: Publish the verified CI bundle
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.resolve.outputs.tag }}
+          generate_release_notes: true
+          files: release-assets/*
+          fail_on_unmatched_files: true
+          overwrite_files: false
+
+  pypi:
+    needs: [resolve, publish]
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uc-toffee
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dist-${{ needs.resolve.outputs.tag }}
+          path: verified-assets
+      - name: Select the verified Python distributions
+        run: |
+          mkdir dist
+          cp verified-assets/*.whl verified-assets/*.tar.gz dist/
+      - name: Publish with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

uc_toffee-2.0.0/.github/workflows/version.yml

@@ -0,0 +1,103 @@
+name: Version policy
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, reopened, synchronize, ready_for_review, labeled, unlabeled]
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version bump for a merged main PR (including retry)"
+        required: true
+        type: choice
+        options: [patch, minor, major]
+      commit:
+        description: "Optional full merged commit SHA for recovery; empty uses the selected main commit"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  release-label:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - run: python scripts/release/version_policy.py label --json "$GITHUB_EVENT_PATH"
+
+  resolve:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      bump: ${{ steps.pr.outputs.bump }}
+      commit: ${{ steps.pr.outputs.commit }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Resolve merged PR version bump
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+          MANUAL_BUMP: ${{ inputs.bump }}
+          TARGET_COMMIT: ${{ inputs.commit || github.sha }}
+        run: |
+          [[ "$TARGET_COMMIT" =~ ^[0-9a-f]{40}$ ]]
+          if [[ "$GITHUB_EVENT_NAME" == workflow_dispatch ]]; then
+            bump="$MANUAL_BUMP"
+          else
+            gh api "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_SHA}/pulls" > "$RUNNER_TEMP/associated-prs.json"
+            bump="$(python scripts/release/version_policy.py resolve --json "$RUNNER_TEMP/associated-prs.json" --commit "$GITHUB_SHA")"
+          fi
+          echo "bump=$bump" >> "$GITHUB_OUTPUT"
+          echo "commit=$TARGET_COMMIT" >> "$GITHUB_OUTPUT"
+
+  tag:
+    needs: resolve
+    if: needs.resolve.outputs.bump != ''
+    runs-on: ubuntu-24.04
+    concurrency:
+      group: toffee-version-tag
+      queue: max
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.resolve.outputs.commit }}
+      - name: Verify merge result and create or reuse its tag
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BUMP: ${{ needs.resolve.outputs.bump }}
+        run: |
+          git fetch origin main:refs/remotes/origin/main --tags
+          python scripts/release/version_policy.py verify
+          tag="$(python scripts/release/version_policy.py next --bump "$BUMP")"
+          if ! git rev-parse --verify "refs/tags/$tag" >/dev/null 2>&1; then
+            git config user.name 'github-actions[bot]'
+            git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+            git tag -a "$tag" -m "Toffee ${tag#v}"
+            git push origin "refs/tags/$tag"
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+      - name: Dispatch tagged verification and release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+          TARGET_COMMIT: ${{ needs.resolve.outputs.commit }}
+        run: |
+          python -c 'import json, os; print(json.dumps({"event_type": "version-tagged", "client_payload": {"tag": os.environ["TAG"], "sha": os.environ["TARGET_COMMIT"]}}))' |
+            gh api -X POST "repos/${GITHUB_REPOSITORY}/dispatches" --input -

uc_toffee-2.0.0/.gitignore

@@ -0,0 +1,63 @@
+# Python bytecode, environments and tool caches.
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.nox/
+
+# Python packaging and documentation builds.
+build/
+dist/
+site/
+*.egg-info/
+.eggs/
+*.egg
+*.whl
+
+# Native simulator builds and waveforms.
+obj_dir/
+*.o
+*.a
+*.so
+*.so.*
+*.dylib
+*.vcd
+*.fst
+
+# Python and native coverage data.
+.coverage
+.coverage.*
+htmlcov/
+/coverage.xml
+/coverage.json
+/coverage.dat
+/*_coverage.dat
+/*-coverage.dat
+*.gcda
+*.gcno
+
+# Runtime artifacts and generated reports stay local.
+/output/
+
+# Local copies of dependencies and release artifacts used by CI.
+/_deps/
+/release-assets/
+
+# Legacy generated evidence saved alongside authored verification records.
+# Keep notes, probes, fixtures and formal verification plans visible to Git.
+/design/verification/*-measurements-*.json
+/design/verification/*-results-*.json
+/design/verification/feature-docs-regression-*.json
+/design/verification/rtl-internal-observation-inventory-*.json
+/design/verification/rtl-property-evidence-*/
+
+# Editor backups and operating-system metadata.
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db

uc_toffee-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# 参与 Toffee 开发
+
+Toffee 负责 Python API、仿真调度、验证组件和报告。
+原生时钟、信号和触发引擎由 xcomm 提供；真实 DUT 的环境代码放在
+`examples/integration/<dut>/`，不要混进框架实现。
+
+## 一项改动应包含什么
+
+新增或修改功能时，一并更新：
+
+1. `src/toffee/` 中的实现。
+2. 相应的用户文档；按下文的读者目的选择页面。
+3. 对应 `tests/` 分类中的回归。
+4. 面向用户的功能示例；影响高频路径时，还应有可重复的性能测试。
+
+文档说明当前能做什么、怎样使用。不要把试验过程、机器专用路径、分轮测试数字
+或未实现的接口原型放进用户手册。生成的报告、日志和测量结果写入 `output/`，不要提交。
+
+## 文档按读者目的组织
+
+文档采用 [Diátaxis](https://diataxis.fr/) 的四类划分：
+
+| 类型 | 位置 | 写作要求 |
+| --- | --- | --- |
+| 教程 | `docs/getting-started/` | 带读者完成可复现的练习，给出命令与预期结果；逐步引入概念，减少分支选择 |
+| 操作指南 | `docs/guides/` | 开头说明目标和前提，围绕实际任务给步骤、验证方法和常见失败处理 |
+| 参考 | `docs/reference/` | 准确列出签名、默认值、单位、返回值、异常与限制；与实现逐项核对 |
+| 原理说明 | `docs/explanation/` | 解释原因、边界和取舍，通过具体场景建立概念之间的联系 |
+
+一页主要解决一种阅读需求；需要其他类型的内容时链接过去，避免在操作步骤中展开长篇
+原理，或在教程中罗列所有参数。已有页面混合多种内容时逐步拆分，并尽量保留旧地址。
+例如，配置步骤留在 Execution 指南，默认值放在 Execution 参考，调度原因放在原理说明。
+
+新增页面须接入 `mkdocs.yml` 和相应目录入口。检查相对链接与页内锚点，
+运行 `python3 -m pytest -q tests/integration/test_documentation.py` 和 `mkdocs build --strict`。
+新增可运行示例时还要实际执行；已有覆盖模型片段由文档测试校验。
+
+## 提交前检查
+
+先准备 `uc-xcomm>=1.1,<2`，再安装开发依赖。开发跨仓库未发布修改时，
+按 `.github/native-dependencies.json` 检出 xcomm 的固定提交，再运行：
+
+```bash
+SETUPTOOLS_SCM_PRETEND_VERSION_FOR_UC_XCOMM=1.1.0 \
+  python3 -m pip install /path/to/xcomm
+```
+
+这里的版本覆盖仅用于本地和 CI 验证目标依赖范围，不发布该测试包。随后安装开发依赖：
+
+```bash
+python3 -m pip install -e '.[test,docs]'
+python3 -m pytest -q --require-xspcomm
+mkdocs build --strict
+```
+
+`--require-xspcomm` 会在原生依赖不满足时失败，避免把原生测试没运行当成通过。
+没有原生环境时，可先用 `python3 -m pytest -q` 检查纯 Python 部分，但这不代替完整回归。
+
+原生后端的提交、包版本、ABI 和协议版本以
+[依赖清单](.github/native-dependencies.json)为准。
+只编译了本地绑定而未安装时，可设置 `XCOMM_PYTHON=/path/to/xcomm/build/python`。
+测试也会查找同级 Picker 的 `build/dependence/xcomm/python`。
+
+需要从 xcomm 源码安装时，SWIG 须为 4.2 或更新版本，并打开两个构建选项：
+
+```bash
+BUILD_XSPCOMM_SWIG=python XSPCOMM_BUILD_WHEEL=1 \
+  python3 -m pip install /path/to/xcomm
+```
+
+不要只升级 Python 包而混用旧原生库。CI 会安装依赖清单固定的版本并运行原生测试。
+
+## 生命周期
+
+`Execution` 只清理本次执行注册的等待、采样和组件，不拥有 backend。
+创建 backend 的代码负责调用 `close()`；创建 DUT 的 fixture 负责初始化和释放 DUT。
+修改这类行为时，要同时测试正常退出、取消和异常退出。
+
+## 版本和发布
+
+版本号由 Git tag 和 setuptools-scm 生成，不在源码中另写一份。
+针对 main 的 PR 需选择一个版本标签：`release:patch`、`release:minor` 或 `release:major`。
+具体选择和发布失败后的处理见[版本与发布](docs/guides/versioning-and-releases.md)。
+
+发布检查包括原生回归、严格文档构建、源码包重建和隔离安装。
+验证通过后发布的是同一组已检查产物，不另行构建一份替代。