coaxi 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. coaxi-1.0.0/.github/workflows/release.yml +141 -0
  2. coaxi-1.0.0/.gitignore +15 -0
  3. coaxi-1.0.0/.python-version +1 -0
  4. coaxi-1.0.0/AGENTS.md +193 -0
  5. coaxi-1.0.0/ARCHITECTURE.md +401 -0
  6. coaxi-1.0.0/AXI_STREAM_REVIEW.md +144 -0
  7. coaxi-1.0.0/LICENSE.txt +121 -0
  8. coaxi-1.0.0/PKG-INFO +640 -0
  9. coaxi-1.0.0/README.md +630 -0
  10. coaxi-1.0.0/RELEASING.md +120 -0
  11. coaxi-1.0.0/examples/stream_loopback.py +63 -0
  12. coaxi-1.0.0/pyproject.toml +58 -0
  13. coaxi-1.0.0/src/coaxi/__init__.py +36 -0
  14. coaxi-1.0.0/src/coaxi/_binding.py +192 -0
  15. coaxi-1.0.0/src/coaxi/_payload.py +142 -0
  16. coaxi-1.0.0/src/coaxi/_sideband.py +118 -0
  17. coaxi-1.0.0/src/coaxi/_stream.py +826 -0
  18. coaxi-1.0.0/src/coaxi/py.typed +0 -0
  19. coaxi-1.0.0/tests/__init__.py +5 -0
  20. coaxi-1.0.0/tests/audit_cases.py +316 -0
  21. coaxi-1.0.0/tests/check_release.py +46 -0
  22. coaxi-1.0.0/tests/frame_cases.py +773 -0
  23. coaxi-1.0.0/tests/full_rate_cases.py +458 -0
  24. coaxi-1.0.0/tests/handle_cases.py +200 -0
  25. coaxi-1.0.0/tests/hdl/stream_dut.vhd +100 -0
  26. coaxi-1.0.0/tests/omission_cases.py +535 -0
  27. coaxi-1.0.0/tests/reliability_cases.py +446 -0
  28. coaxi-1.0.0/tests/reliability_worker.py +72 -0
  29. coaxi-1.0.0/tests/reset_pin_cases.py +618 -0
  30. coaxi-1.0.0/tests/run_coverage.py +45 -0
  31. coaxi-1.0.0/tests/run_reliability.py +215 -0
  32. coaxi-1.0.0/tests/sideband_cases.py +526 -0
  33. coaxi-1.0.0/tests/stream_cases.py +632 -0
  34. coaxi-1.0.0/tests/test_distribution.py +256 -0
  35. coaxi-1.0.0/tests/test_release.py +109 -0
  36. coaxi-1.0.0/tests/test_reliability_harness.py +96 -0
  37. coaxi-1.0.0/tests/test_simulation.py +68 -0
  38. coaxi-1.0.0/tests/test_typing.py +98 -0
  39. coaxi-1.0.0/tests/test_validation.py +18 -0
  40. coaxi-1.0.0/tests/test_values.py +27 -0
  41. coaxi-1.0.0/uv.lock +264 -0
@@ -0,0 +1,141 @@
1
+ # release.yml
2
+ # SPDX-License-Identifier: CC0-1.0
3
+ # This file was created by an AI model: openai/gpt-6.1-sol
4
+
5
+ name: Publish Python package
6
+ run-name: Publish ${{ github.ref_name }} to ${{ inputs.destination }}
7
+
8
+ on:
9
+ workflow_dispatch:
10
+ inputs:
11
+ destination:
12
+ description: Package index (use test-pypi for the rehearsal)
13
+ required: true
14
+ type: choice
15
+ default: test-pypi
16
+ options:
17
+ - test-pypi
18
+ - pypi
19
+
20
+ permissions: {}
21
+
22
+ concurrency:
23
+ group: release-${{ inputs.destination }}
24
+ cancel-in-progress: false
25
+
26
+ defaults:
27
+ run:
28
+ shell: bash
29
+
30
+ jobs:
31
+ validate-build:
32
+ name: Validate and build the tagged revision
33
+ runs-on: ubuntu-24.04
34
+ timeout-minutes: 20
35
+ permissions:
36
+ contents: read
37
+ outputs:
38
+ artifact-id: ${{ steps.distributions.outputs.artifact-id }}
39
+ steps:
40
+ - name: Check out the triggering commit
41
+ uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
42
+ with:
43
+ ref: ${{ github.sha }}
44
+ persist-credentials: false
45
+
46
+ - name: Require a matching version tag and known destination
47
+ env:
48
+ RELEASE_REF: ${{ github.ref }}
49
+ RELEASE_DESTINATION: ${{ inputs.destination }}
50
+ run: |
51
+ case "$RELEASE_DESTINATION" in
52
+ test-pypi|pypi) ;;
53
+ *) echo "Unknown publishing destination" >&2; exit 1 ;;
54
+ esac
55
+ python3 tests/check_release.py "$RELEASE_REF"
56
+
57
+ - name: Set up uv and Python
58
+ uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
59
+ with:
60
+ version: "0.13.7"
61
+ python-version: "3.13.5"
62
+ enable-cache: false
63
+
64
+ - name: Install checksum-pinned NVC
65
+ run: |
66
+ asset="nvc_1.21.1-1_amd64_ubuntu-24.04.deb"
67
+ package="$RUNNER_TEMP/$asset"
68
+ curl --fail --location --silent --show-error --retry 3 \
69
+ --proto '=https' --proto-redir '=https' \
70
+ --output "$package" \
71
+ "https://github.com/nickg/nvc/releases/download/r1.21.1/$asset"
72
+ printf '%s %s\n' \
73
+ 'a259847c86fe0e547c481b20686c62a97245a3d44d40d79b7f70ac7408e9bda6' \
74
+ "$package" | sha256sum --check --strict
75
+ sudo apt-get update
76
+ sudo apt-get install --yes --no-install-recommends "$package"
77
+ test "$(dpkg-query --show --showformat='${Version}' nvc)" = "1.21.1-1"
78
+ nvc --version
79
+
80
+ - name: Install locked development dependencies
81
+ run: uv sync --locked
82
+
83
+ - name: Check types
84
+ run: uv run --locked pyrefly check
85
+
86
+ - name: Check formatting
87
+ run: uv run --locked ruff format --check .
88
+
89
+ - name: Check lint
90
+ run: uv run --locked ruff check .
91
+
92
+ - name: Run Python and NVC tests
93
+ run: uv run --locked pytest -q
94
+
95
+ - name: Build and validate the release distributions
96
+ run: |
97
+ mkdir "$RUNNER_TEMP/release-dist"
98
+ uv build --no-sources --out-dir "$RUNNER_TEMP/release-dist"
99
+ uv run --locked python -m tests.test_distribution --dist "$RUNNER_TEMP/release-dist"
100
+ sha256sum "$RUNNER_TEMP/release-dist/"*.whl "$RUNNER_TEMP/release-dist/"*.tar.gz
101
+
102
+ - name: Save only the validated sdist and wheel
103
+ id: distributions
104
+ uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
105
+ with:
106
+ name: release-distributions-${{ github.run_id }}-${{ github.run_attempt }}
107
+ path: |
108
+ ${{ runner.temp }}/release-dist/*.whl
109
+ ${{ runner.temp }}/release-dist/*.tar.gz
110
+ if-no-files-found: error
111
+ retention-days: 7
112
+
113
+ publish:
114
+ name: Publish validated distributions
115
+ needs: validate-build
116
+ if: inputs.destination == 'pypi' || inputs.destination == 'test-pypi'
117
+ runs-on: ubuntu-24.04
118
+ timeout-minutes: 10
119
+ environment:
120
+ name: ${{ inputs.destination }}
121
+ url: ${{ inputs.destination == 'pypi' && 'https://pypi.org/p/coaxi' || 'https://test.pypi.org/p/coaxi' }}
122
+ permissions:
123
+ id-token: write
124
+ steps:
125
+ # No checkout, dependency installation or package execution in this job.
126
+ - name: Download this run's validated distributions
127
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
128
+ with:
129
+ artifact-ids: ${{ needs.validate-build.outputs.artifact-id }}
130
+ merge-multiple: true
131
+ path: dist/
132
+
133
+ - name: Publish with Trusted Publishing
134
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
135
+ with:
136
+ repository-url: ${{ inputs.destination == 'pypi' && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}
137
+ packages-dir: dist/
138
+ verify-metadata: true
139
+ attestations: true
140
+ print-hash: true
141
+ skip-existing: false
coaxi-1.0.0/.gitignore ADDED
@@ -0,0 +1,15 @@
1
+ # .gitignore
2
+ # SPDX-License-Identifier: CC0-1.0
3
+ # This file was created by an AI model: openai/gpt-6.1-sol
4
+
5
+ .venv/
6
+ __pycache__/
7
+ *.py[cod]
8
+ .ruff_cache/
9
+ .pytest_cache/
10
+ sim_build/
11
+ dist/
12
+ .coverage*
13
+ coverage.json
14
+ htmlcov/
15
+ reliability-results.json
@@ -0,0 +1 @@
1
+ 3.13
coaxi-1.0.0/AGENTS.md ADDED
@@ -0,0 +1,193 @@
1
+ # AGENTS.md
2
+ # SPDX-License-Identifier: CC0-1.0
3
+ # This file was created by an AI model: openai/gpt-6.1-sol
4
+
5
+ ## Project purpose
6
+
7
+ `coaxi` is a ground-up rewrite of `cocotbext-axi`. It provides helpers for
8
+ interacting with AXI4, AXI4-Lite, and AXI-Stream interfaces in cocotb testbenches.
9
+ The project and distribution name is `coaxi`; the Python package is `coaxi`,
10
+ located at `src/coaxi`. Use imports such as `from coaxi import AxiStreamBus`.
11
+ Do not use the former `cocotbext.axi` namespace or add a compatibility package.
12
+
13
+ The first implementation should make AXI-Stream work well, with a small, clear
14
+ foundation that can later support AXI4 and AXI4-Lite. Do not implement the other
15
+ protocols ahead of that goal or build abstractions solely for hypothetical needs.
16
+ The stream target is full AXI4-Stream, not AXI5-Stream wake-up/parity extensions.
17
+ Keep bare-bones usage clean: optional sideband support must not make callers
18
+ supply metadata objects or restate defaults for ordinary transfers.
19
+
20
+ Do not depend on `cocotb-bus` or `cocotbext-bus`. Keep signal binding simple and
21
+ within this library.
22
+
23
+ ## Decisions and clarification
24
+
25
+ Never assume the answer to an ambiguous project architecture choice or other
26
+ decision. If a decision is unclear, or it would otherwise be useful to consult
27
+ the user, always ask the user what to do and wait for their answer before
28
+ proceeding with that decision.
29
+
30
+ Explain the uncertainty briefly and, where useful, give the available options
31
+ and their trade-offs. Do not invent requirements or silently settle the choice.
32
+
33
+ ## Interface requirements
34
+
35
+ ### Signal names
36
+
37
+ - Do not require any HDL signal naming convention. Treat protocol roles such as
38
+ data, valid, ready, and last independently of the signals' actual names.
39
+ - Provide convenient defaults for standard AXI-Stream names such as
40
+ `foo_tvalid` and `foo_tready`, and for names such as `foo_valid` and `foo_ready`.
41
+ Prefix and `t`-prefix options are conveniences only.
42
+ - Let callers override every signal independently with an arbitrary HDL name
43
+ or an already-bound cocotb handle. This includes optional sidebands and any
44
+ clock or reset signals accepted by an API.
45
+ - Make overrides straightforward through per-signal arguments or a mapping.
46
+ Overriding one signal must not require restating the others, subclassing,
47
+ writing an adapter, or renaming signals in the DUT.
48
+ - Use explicit names exactly as supplied. Do not add prefixes or suffixes,
49
+ change case, or require a shared naming pattern. Accept HDL names supported
50
+ by cocotb even when they are not valid Python attribute names.
51
+ - Keep optional-signal selection explicit; naming defaults must not require
52
+ optional signals to exist.
53
+
54
+ ### Data types
55
+
56
+ - Support ordinary `std_logic_vector` payloads and custom HDL data types.
57
+ - A VHDL record such as `IQ_t`, containing two `signed(15 downto 0)` fields,
58
+ should be usable as naturally as a vector payload.
59
+ - Keep payload access and conversion separate from handshake and framing logic.
60
+ Do not require every payload to be flattened into an integer or byte sequence.
61
+ - Keep/strb require a defined byte-lane layout. Support byte-aligned logic vectors;
62
+ do not infer byte lanes or flatten custom records to provide these qualifiers.
63
+ Other sidebands remain independent of payload shape.
64
+
65
+ ### Transactions and framing
66
+
67
+ - Provide straightforward support for unframed streams without `tlast` and
68
+ framed streams with `tlast`.
69
+ - Keep the value of `tlast` available for individual transfers, even when using
70
+ higher-level frame helpers.
71
+ - Document which optional signals an operation needs. Do not silently assume
72
+ that every interface has every AXI-Stream sideband signal.
73
+ - Full-rate transfers are critical: sustain one accepted transfer per rising
74
+ clock edge with immediately consecutive calls when data and ready are
75
+ available. Verify cycle spacing and recovery from backpressure in tests.
76
+
77
+ ### Clocks
78
+
79
+ - Require every clock to contain only literal 0/1 values from before the first
80
+ endpoint initialisation onwards. Weak L/H and unresolved clock values are unsupported.
81
+ - Document this as a caller precondition. The current endpoints do not monitor
82
+ clocks for invalid values.
83
+
84
+ ### Meta-values and reset
85
+
86
+ - `initialise()` performs local initialisation/recovery and never drives the DUT
87
+ reset pin. Do not name a non-pin-driving endpoint operation `reset()`.
88
+ - Optional reset-pin monitoring supports configurable polarity, including
89
+ active-high. Do not infer polarity from names. Pin-only reset recovery must
90
+ preserve previously recorded faults/cancellation until explicit initialisation.
91
+
92
+ - Handle HDL meta-values such as `X` and `U` explicitly. Do not silently convert
93
+ them into ordinary data values.
94
+ - Drive meta-values only for a clear, documented protocol or testing reason.
95
+ - Reset must restore the library's driven signals and internal state to defined
96
+ values, clearing meta-values that the library introduced where appropriate.
97
+ - Make unsupported values or conversions produce clear errors.
98
+
99
+ ### Logging
100
+
101
+ Use DEBUG-level logging where useful for observing transfers, framing, reset,
102
+ and other bus activity. Avoid unconditional printing and routine transaction
103
+ messages at higher log levels.
104
+
105
+ ## Python and development tools
106
+
107
+ - Target Python 3.13 and use `uv` for dependency and environment management.
108
+ - Use a project-local, `uv`-managed `.venv` for Python work. Run tools through
109
+ `uv run` rather than relying on a globally activated environment.
110
+ - Avoid system-wide package installation. If sandbox restrictions prevent
111
+ environment creation, dependency installation, or tool execution, report the
112
+ limitation rather than working around those restrictions.
113
+ - Use modern Python practices and keep the design straightforward.
114
+ - Use cocotb 2.1.0 or later. Keep it as a runtime dependency in `pyproject.toml`.
115
+ - Keep `uv.lock` consistent with changes to declared dependencies. Avoid
116
+ unrelated dependency upgrades.
117
+ - Use Pyrefly for type checking with its default configuration. Do not add
118
+ Pyrefly overrides unless requested.
119
+ - Use Ruff for formatting and linting. Follow the settings in `pyproject.toml`:
120
+ a 120-character line length, tab indentation, double quotes, docstring code
121
+ formatting, and the supplied lint and import-sorting rules.
122
+ - Run `uv run pyrefly check`, `uv run ruff format --check .`, and
123
+ `uv run ruff check .`. Apply formatting with `uv run ruff format .`.
124
+ - Run `uv run pytest -q` for the Python and simulator tests. Add a regression
125
+ test for each bug fix where practical.
126
+
127
+ ## Public APIs and documentation
128
+
129
+ - Give every public function, method, class, and type a succinct, useful
130
+ docstring or equivalent documentation.
131
+ - Give all public function and method parameters and return values type
132
+ annotations. Annotate public attributes and other exposed types as appropriate.
133
+ - Choose self-describing parameter names. Still explain each parameter's meaning
134
+ in the function documentation, including units, defaults, or constraints where
135
+ relevant.
136
+ - Document behaviour that callers need to understand, especially reset,
137
+ handshake timing, framing, payload conversion, and meta-value handling.
138
+
139
+ ## Language and style
140
+
141
+ - Use British English in code, comments, documentation, and user-facing prose:
142
+ for example, `initialise`, `serialise`, and `colour`.
143
+ - Preserve spelling required by existing APIs, protocol names, identifiers, and
144
+ external tools.
145
+ - Write simple, direct English. Use technical terms when they have a precise,
146
+ useful meaning; avoid unnecessary jargon.
147
+ - Avoid stock assistant phrasing, rhetorical contrasts such as “not X but Y”,
148
+ and inflated claims.
149
+
150
+ ## Source headers and licence
151
+
152
+ The project licence is CC0-1.0. Start every new first-party source file with:
153
+
154
+ ```python
155
+ # <FILENAME>
156
+ # SPDX-License-Identifier: CC0-1.0
157
+ # This file was created by an AI model: openai/<MODEL-NAME>
158
+ ```
159
+
160
+ Replace `<FILENAME>` with the file's basename, without any directory components.
161
+ Replace `<MODEL-NAME>` with the exact name of the model creating the file, such
162
+ as `gpt-6.1-sol`. Use `openai/<MODEL-NAME>`, omitting routing or proxy components.
163
+ Do not use a generic assistant name or invent a model name.
164
+ Use the language's comment syntax where `#` is unsuitable, such as `--` for
165
+ VHDL, while retaining the same header text.
166
+
167
+ ## HDL and simulation
168
+
169
+ - Use `nvc` as the simulator. It is installed in the development environment.
170
+ - Write any required HDL DUTs in VHDL-2008.
171
+ - Test default naming styles, arbitrary unrelated signal names, individual
172
+ overrides mixed with defaults, and direct handle binding as signal binding
173
+ is implemented.
174
+ - Test framed and unframed transfers, custom data types, meta-values, reset
175
+ behaviour, and backpressure as the relevant features are implemented.
176
+ - Give simulation tests bounded simulation-time timeouts so stalled transfers
177
+ fail instead of hanging indefinitely.
178
+ - Record the seeds used by randomised tests so failures can be reproduced.
179
+
180
+ ## Architecture and commits
181
+
182
+ - Maintain `ARCHITECTURE.md` as an accurate description of the implemented
183
+ architecture, including the main components, their responsibilities, and
184
+ important design decisions.
185
+ - Before every commit, review the code changes against `ARCHITECTURE.md`.
186
+ Update it whenever needed so that all architectural effects of those changes
187
+ are reflected. Do not describe planned features as already implemented.
188
+ - Do not overwrite or revert unrelated changes, discard uncommitted work, or
189
+ rewrite Git history without the user's explicit permission.
190
+ - Commit work in self-contained, appropriately sized chunks. Keep unrelated
191
+ changes separate and use succinct, readable commit messages.
192
+ - Run the relevant tests, type checks, and formatting checks before committing.
193
+ State which checks ran and report any that could not run, with the reason.