uc-xcomm 1.1.0__tar.gz

uc_xcomm-1.1.0/.clang-format

@@ -0,0 +1,73 @@
+Language: Cpp
+BasedOnStyle: LLVM
+AccessModifierOffset: -4
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: true
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands: true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: true
+AllowShortCaseLabelsOnASingleLine: true
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: true
+BinPackParameters: true
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterClass: true
+  AfterControlStatement: false
+  AfterEnum: false
+  AfterFunction: true
+  AfterNamespace: false
+  AfterStruct: false
+  AfterUnion: false
+  AfterExternBlock: false
+  BeforeCatch: false
+  BeforeElse: false
+  IndentBraces: false
+  SplitEmptyFunction: false
+  SplitEmptyRecord: false
+  SplitEmptyNamespace: false
+BreakBeforeBinaryOperators: NonAssignment
+BreakBeforeTernaryOperators: false
+BreakConstructorInitializers: AfterColon
+BreakStringLiterals: false
+ColumnLimit: 80
+CompactNamespaces: true
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+FixNamespaceComments: true
+IndentCaseLabels: false
+IndentPPDirectives: None
+IndentWidth: 4
+IndentWrappedFunctionNames: false
+KeepEmptyLinesAtTheStartOfBlocks: false
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: Inner
+PointerAlignment: Right
+ReflowComments: true
+SortIncludes: false
+SortUsingDeclarations: false
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 1
+SpacesInAngles: false
+SpacesInCStyleCastParentheses: false
+SpacesInContainerLiterals: true
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard: Auto
+TabWidth: 4
+UseTab: Never

uc_xcomm-1.1.0/.github/README.md

@@ -0,0 +1,29 @@
+# xcomm
+
+English | [中文](README.cn.md)
+
+xcomm is a C++20 library for hardware simulation, providing four-state signals, port collections, clocks, expressions, temporal events, and functional coverage. Install the Python distribution as `uc-xcomm` and import it as `xspcomm`; bindings are also available for Java, Scala, Go, Lua, and JavaScript.
+
+## Get started
+
+After [installation](docs/en/guides/installation.md), create and read a wide signal:
+
+```python
+import xspcomm as xs
+
+signal = xs.XData(128, xs.XData.InOut)
+signal.value = (1 << 96) + 3
+print(hex(signal.value))
+```
+
+The output is `0x1000000000000000000000003`. Continue with the [tutorial](docs/en/tutorials/first-simulation.md) to advance a clock and wait for an event.
+
+## Documentation
+
+[English documentation](docs/en/index.md) · [完整中文文档](docs/zh/index.md)
+
+- Use the library: [events and coverage](docs/en/guides/events-coverage.md), [typed expressions](docs/en/guides/typed-expressions.md).
+- Look up an interface: [API index](docs/en/reference/api-index.md), [language bindings](docs/en/reference/bindings.md), [migration](docs/en/reference/compatibility.md), [troubleshooting](docs/en/reference/troubleshooting.md).
+- Develop the library: [architecture](docs/en/explanation/architecture.md), [performance](docs/en/explanation/performance.md), [tests](docs/en/development/contributing.md), [documentation and Wiki](docs/en/development/documentation.md).
+
+Report issues and suggestions through [GitHub Issues](https://github.com/XS-MLVP/xcomm/issues). See [LICENSE](LICENSE) for licensing.

uc_xcomm-1.1.0/.github/workflows/build-python.yml

@@ -0,0 +1,89 @@
+name: Build Python distributions
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        type: string
+        default: ""
+      artifact-prefix:
+        type: string
+        default: xspcomm
+
+permissions:
+  contents: read
+
+jobs:
+  sdist:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install 'build>=1,<2' 'twine>=6,<7'
+      - run: python -m build --sdist
+      - run: python -m twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact-prefix }}-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  wheel:
+    needs: sdist
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: [cp311, cp312]
+        policy: [manylinux_2_17, manylinux_2_28]
+        include:
+          - policy: manylinux_2_17
+            image: quay.io/pypa/manylinux2014_x86_64@sha256:3a591c1109773dbd79f16c038588fd1867d9f2f708b360dab5715852c7f96ef0
+            ldflags: -static-libstdc++
+            prepare: python {project}/scripts/release/prepare_manylinux2014.py
+            sdk-flags: --static-libstdcxx
+          - policy: manylinux_2_28
+            image: quay.io/pypa/manylinux_2_28_x86_64@sha256:076b19ef6e698f28649fa817c49d14443201e01da85240e8e52f93e8daa49bff
+            ldflags: ""
+            prepare: ""
+            sdk-flags: ""
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python == 'cp311' && '3.11' || '3.12' }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: ${{ inputs.artifact-prefix }}-sdist
+          path: source
+      - run: python -m pip install 'cibuildwheel==3.4.1' 'twine>=6,<7'
+      - name: Build, audit and test wheel from sdist
+        env:
+          CIBW_MANYLINUX_X86_64_IMAGE: ${{ matrix.image }}
+          # CentOS 7's default libstdc++ ABI is 0. Use ABI 1 consistently with
+          # modern Picker/DUT compilers and bundle its runtime on GLIBC 2.17.
+          CIBW_ENVIRONMENT_LINUX: >-
+            CMAKE_BUILD_PARALLEL_LEVEL=4 CMAKE_GENERATOR="Unix Makefiles"
+            CXXFLAGS="-D_GLIBCXX_USE_CXX11_ABI=1" LDFLAGS="${{ matrix.ldflags }}"
+          CIBW_BEFORE_ALL_LINUX: ${{ matrix.prepare }}
+          CIBW_TEST_COMMAND: python {project}/scripts/release/check_wheel.py --cxx11-abi=1 ${{ matrix.sdk-flags }}
+          CIBW_REPAIR_WHEEL_COMMAND_LINUX: auditwheel repair --only-plat --plat ${{ matrix.policy }}_x86_64 -w {dest_dir} {wheel}
+        run: python -m cibuildwheel --only '${{ matrix.python }}-manylinux_x86_64' --output-dir wheelhouse source/*.tar.gz
+      - name: Check SDK with the host compiler
+        run: |
+          python -m pip install --no-index wheelhouse/*.whl
+          python -m pip check
+          python scripts/release/check_wheel.py
+      - run: python -m twine check --strict wheelhouse/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ inputs.artifact-prefix }}-${{ matrix.policy }}-${{ matrix.python }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error

uc_xcomm-1.1.0/.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Documentation
+
+on:
+  pull_request:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "README*"
+      - "CONTRIBUTING.md"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - "scripts/docs.py"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [master, "docs/**"]
+    paths:
+      - "docs/**"
+      - "README*"
+      - "CONTRIBUTING.md"
+      - "mkdocs.yml"
+      - "requirements-docs.txt"
+      - "scripts/docs.py"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: documentation-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+      - name: Install documentation tools
+        run: python -m pip install -r requirements-docs.txt
+      - name: Check translations, links and example syntax
+        run: python scripts/docs.py check
+      - name: Build documentation site
+        run: python -m mkdocs build --strict
+      - name: Export Wiki pages
+        run: python scripts/docs.py wiki --output build/wiki-export
+      - name: Upload documentation preview
+        uses: actions/upload-artifact@v4
+        with:
+          name: xcomm-documentation
+          if-no-files-found: error
+          path: |
+            build/docs-site
+            build/wiki-export

uc_xcomm-1.1.0/.github/workflows/python-wheel.yml

@@ -0,0 +1,48 @@
+name: Python wheel
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  distributions:
+    uses: ./.github/workflows/build-python.yml
+
+  source-install:
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install system build tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends build-essential cmake ninja-build
+      - run: python -m unittest discover -s tests/release -v
+      - run: python -m pip install 'build>=1,<2'
+      - run: python -m build --sdist
+      - name: Install sdist with default native optimization
+        env:
+          CMAKE_BUILD_PARALLEL_LEVEL: "4"
+        run: |
+          python -m venv /tmp/xspcomm-source-test
+          /tmp/xspcomm-source-test/bin/python -m pip install --no-cache-dir dist/*.tar.gz \
+            -Ccmake.define.BUILD_TESTING=ON \
+            -Ccmake.define.CMAKE_EXPORT_COMPILE_COMMANDS=ON \
+            -Cbuild-dir=/tmp/xspcomm-source-build
+          ctest --test-dir /tmp/xspcomm-source-build --output-on-failure
+          python scripts/release/check_build.py /tmp/xspcomm-source-build
+          /tmp/xspcomm-source-test/bin/python -m pip check
+          /tmp/xspcomm-source-test/bin/python scripts/release/check_wheel.py

uc_xcomm-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,109 @@
+name: Release Python distributions
+
+on:
+  repository_dispatch:
+    types: [version-tagged]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing version tag to publish (vX.Y.Z)"
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: xspcomm-release
+  queue: max
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      tag: ${{ steps.version.outputs.tag }}
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.client_payload.tag || inputs.tag }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Validate existing tag
+        id: version
+        env:
+          TAG: ${{ github.event.client_payload.tag || inputs.tag }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          test "$(git rev-parse HEAD)" = "$(git rev-parse "refs/tags/${TAG}^{commit}")"
+          git fetch origin master:refs/remotes/origin/master --tags
+          python scripts/release/tag_policy.py verify HEAD
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+  distributions:
+    needs: validate
+    uses: ./.github/workflows/build-python.yml
+    with:
+      ref: ${{ needs.validate.outputs.tag }}
+      artifact-prefix: xspcomm-release
+
+  github-release:
+    needs: [validate, distributions]
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.validate.outputs.tag }}
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: xspcomm-release-*
+          merge-multiple: true
+          path: dist
+      - run: python -m pip install 'packaging>=24' 'twine>=6,<7'
+      - name: Check complete release matrix
+        env:
+          VERSION: ${{ needs.validate.outputs.version }}
+        run: |
+          python scripts/release/check_distributions.py dist "$VERSION"
+          python -m twine check --strict dist/*
+      - uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ needs.validate.outputs.tag }}
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+          fail_on_unmatched_files: true
+          overwrite_files: false
+
+  pypi:
+    needs: github-release
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/uc-xcomm
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: xspcomm-release-*
+          merge-multiple: true
+          path: dist
+      - name: Publish to PyPI with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

uc_xcomm-1.1.0/.github/workflows/version.yml

@@ -0,0 +1,155 @@
+name: Version policy
+
+on:
+  pull_request:
+    branches: [master]
+    types: [opened, reopened, synchronize, ready_for_review, labeled, unlabeled]
+  push:
+    branches: [master]
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: "Version component to bump (recovery/manual tag)"
+        required: true
+        type: choice
+        options: [patch, minor, major]
+
+permissions:
+  contents: read
+
+jobs:
+  release-label:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require exactly one version label
+        env:
+          LABELS_JSON: ${{ toJSON(github.event.pull_request.labels.*.name) }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+
+          labels = json.loads(os.environ["LABELS_JSON"])
+          selected = sorted(set(labels) & {"release:patch", "release:minor", "release:major"})
+          if len(selected) != 1:
+              raise SystemExit(f"Expected exactly one release label; found: {selected}")
+          print(f"Version bump: {selected[0]}")
+          PY
+
+  resolve:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    outputs:
+      publish: ${{ steps.pr.outputs.publish }}
+      bump: ${{ steps.pr.outputs.bump }}
+    steps:
+      - name: Resolve merged PR release label
+        id: pr
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          if [[ "$GITHUB_EVENT_NAME" == workflow_dispatch ]]; then
+            echo 'publish=true' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          gh api "repos/${GITHUB_REPOSITORY}/commits/${GITHUB_SHA}/pulls" > /tmp/associated-prs.json
+          python - <<'PY'
+          import json
+          import os
+
+          with open("/tmp/associated-prs.json") as source:
+              prs = json.load(source)
+          merged = [pr for pr in prs if pr["merged_at"] and pr["base"]["ref"] == "master" and pr["merge_commit_sha"] == os.environ["GITHUB_SHA"]]
+          if not merged:
+              print("No merged PR for push; no version tag")
+              exit()
+          if len(merged) != 1:
+              raise SystemExit(f"Expected one merged PR for commit; found {len(merged)}")
+          labels = {label["name"] for label in merged[0]["labels"]}
+          selected = labels & {"release:patch", "release:minor", "release:major"}
+          if len(selected) != 1:
+              raise SystemExit(f"Expected exactly one release label; found {sorted(selected)}")
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              print("publish=true", file=output)
+              print(f"bump={selected.pop().split(':', 1)[1]}", file=output)
+          PY
+
+  tag:
+    needs: resolve
+    if: needs.resolve.outputs.publish == 'true' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-24.04
+    concurrency:
+      group: xspcomm-version-tag
+      queue: max
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.sha }}
+      - name: Calculate and push version tag
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+          MANUAL_BUMP: ${{ inputs.bump }}
+          PR_BUMP: ${{ needs.resolve.outputs.bump }}
+        run: |
+          set -euo pipefail
+          git fetch origin master:refs/remotes/origin/master --tags
+          python scripts/release/tag_policy.py verify HEAD
+          python - <<'PY'
+          import os
+          import re
+          import subprocess
+          import sys
+          import tomllib
+
+          bump = os.environ["PR_BUMP"] or os.environ["MANUAL_BUMP"]
+          if bump not in {"patch", "minor", "major"}:
+              raise SystemExit(f"Invalid bump: {bump}")
+          current_tag = subprocess.check_output(
+              [sys.executable, "scripts/release/tag_policy.py", "latest"], text=True
+          ).strip()
+          if current_tag:
+              current = tuple(map(int, re.fullmatch(r"v(\d+)\.(\d+)\.(\d+)", current_tag).groups()))
+              subprocess.run(["git", "merge-base", "--is-ancestor", current_tag, "HEAD"], check=True)
+          else:
+              with open("pyproject.toml", "rb") as config:
+                  fallback = tomllib.load(config)["tool"]["setuptools_scm"]["fallback_version"]
+              current = tuple(map(int, re.fullmatch(r"(\d+)\.(\d+)\.(\d+)\.dev0", fallback).groups()))
+          major, minor, patch = current
+          next_version = {
+              "patch": (major, minor, patch + 1),
+              "minor": (major, minor + 1, 0),
+              "major": (major + 1, 0, 0),
+          }[bump]
+          version = ".".join(map(str, next_version))
+          with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+              print(f"tag=v{version}", file=output)
+          print(f"Tag v{version} ({bump})")
+          PY
+          TAG="$(sed -n 's/^tag=//p' "$GITHUB_OUTPUT")"
+          if git rev-parse "refs/tags/${TAG}" >/dev/null 2>&1; then
+            echo "Tag ${TAG} already exists" >&2
+            exit 1
+          fi
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          git tag -a "$TAG" -m "xspcomm ${TAG#v}"
+          git push origin "refs/tags/${TAG}"
+      - name: Announce version tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          python -c 'import json, os; print(json.dumps({"event_type": "version-tagged", "client_payload": {"tag": os.environ["TAG"]}}))' |
+            gh api -X POST "repos/${GITHUB_REPOSITORY}/dispatches" --input -

uc_xcomm-1.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Prerequisites
+*.d
+build/
+.vscode/
+dist/
+*.pyc
+.pyodide-xbuildenv/
+node_modules/
+.bsp/
+.scala-build/
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+.metals
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+!swig/golang/go.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app

uc_xcomm-1.1.0/CMakeLists.txt

@@ -0,0 +1,37 @@
+cmake_minimum_required(VERSION 3.15)
+set(XSPCOMM_CMAKE_VERSION "0.1.0")
+if(DEFINED SKBUILD_PROJECT_VERSION)
+    set(XSPCOMM_CMAKE_VERSION "${SKBUILD_PROJECT_VERSION}")
+endif()
+project(xspcomm VERSION ${XSPCOMM_CMAKE_VERSION})
+if(DEFINED SKBUILD_PROJECT_VERSION_FULL)
+    set(XSPCOMM_PACKAGE_VERSION "${SKBUILD_PROJECT_VERSION_FULL}")
+else()
+    set(XSPCOMM_PACKAGE_VERSION "${PROJECT_VERSION}")
+endif()
+
+# Increment for incompatibility with master / published native ABIs.
+# Unreleased changes on this branch share one ABI transition.
+set(XSPCOMM_ABI_VERSION 3)
+
+list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
+
+include(xcomm)
+init_xspcomm()
+
+# Source headers must win over copies left in the build-tree install staging
+# directory.  Otherwise an incremental build can compile against yesterday's
+# public API before copy_xspcomm_include refreshes that directory.
+include_directories(BEFORE ${PROJECT_SOURCE_DIR}/include)
+
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/lib)
+set(XSPCOMM_HEADER_STAGE ${CMAKE_CURRENT_BINARY_DIR}/include)
+
+add_subdirectory(src)
+include(CTest)
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
+add_subdirectory(integrations/tlm)
+add_subdirectory(swig)