cocotbext-sva 0.1.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 (40) hide show
  1. cocotbext_sva-0.1.0/LICENSE +21 -0
  2. cocotbext_sva-0.1.0/PKG-INFO +146 -0
  3. cocotbext_sva-0.1.0/README.md +116 -0
  4. cocotbext_sva-0.1.0/pyproject.toml +44 -0
  5. cocotbext_sva-0.1.0/setup.cfg +4 -0
  6. cocotbext_sva-0.1.0/src/cocotbext/sva/__init__.py +28 -0
  7. cocotbext_sva-0.1.0/src/cocotbext/sva/_access.py +131 -0
  8. cocotbext_sva-0.1.0/src/cocotbext/sva/_api.py +2312 -0
  9. cocotbext_sva-0.1.0/src/cocotbext/sva/_ast.py +264 -0
  10. cocotbext_sva-0.1.0/src/cocotbext/sva/_compile.py +662 -0
  11. cocotbext_sva-0.1.0/src/cocotbext/sva/_engine.py +1000 -0
  12. cocotbext_sva-0.1.0/src/cocotbext/sva/_errors.py +27 -0
  13. cocotbext_sva-0.1.0/src/cocotbext/sva/_expr.py +625 -0
  14. cocotbext_sva-0.1.0/src/cocotbext/sva/_lexer.py +106 -0
  15. cocotbext_sva-0.1.0/src/cocotbext/sva/_multiclock.py +528 -0
  16. cocotbext_sva-0.1.0/src/cocotbext/sva/_nfa.py +385 -0
  17. cocotbext_sva-0.1.0/src/cocotbext/sva/_offline.py +670 -0
  18. cocotbext_sva-0.1.0/src/cocotbext/sva/_parser.py +632 -0
  19. cocotbext_sva-0.1.0/src/cocotbext/sva/_probe.py +283 -0
  20. cocotbext_sva-0.1.0/src/cocotbext/sva/_prop.py +1005 -0
  21. cocotbext_sva-0.1.0/src/cocotbext/sva/_symenv.py +318 -0
  22. cocotbext_sva-0.1.0/src/cocotbext/sva/_trace.py +288 -0
  23. cocotbext_sva-0.1.0/src/cocotbext_sva.egg-info/PKG-INFO +146 -0
  24. cocotbext_sva-0.1.0/src/cocotbext_sva.egg-info/SOURCES.txt +38 -0
  25. cocotbext_sva-0.1.0/src/cocotbext_sva.egg-info/dependency_links.txt +1 -0
  26. cocotbext_sva-0.1.0/src/cocotbext_sva.egg-info/requires.txt +4 -0
  27. cocotbext_sva-0.1.0/src/cocotbext_sva.egg-info/top_level.txt +1 -0
  28. cocotbext_sva-0.1.0/tests/test_corpus.py +150 -0
  29. cocotbext_sva-0.1.0/tests/test_corpus_mc.py +101 -0
  30. cocotbext_sva-0.1.0/tests/test_engine.py +114 -0
  31. cocotbext_sva-0.1.0/tests/test_expr.py +81 -0
  32. cocotbext_sva-0.1.0/tests/test_fuzz.py +271 -0
  33. cocotbext_sva-0.1.0/tests/test_kernel.py +165 -0
  34. cocotbext_sva-0.1.0/tests/test_logging.py +18 -0
  35. cocotbext_sva-0.1.0/tests/test_multiclock.py +254 -0
  36. cocotbext_sva-0.1.0/tests/test_offline.py +403 -0
  37. cocotbext_sva-0.1.0/tests/test_parser.py +99 -0
  38. cocotbext_sva-0.1.0/tests/test_probe_gen.py +88 -0
  39. cocotbext_sva-0.1.0/tests/test_symenv.py +154 -0
  40. cocotbext_sva-0.1.0/tests/test_triggered.py +128 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 David Pavlović
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,146 @@
1
+ Metadata-Version: 2.4
2
+ Name: cocotbext-sva
3
+ Version: 0.1.0
4
+ Summary: SystemVerilog-style immediate and concurrent assertions for cocotb
5
+ Author: David Pavlović
6
+ License-Expression: MIT
7
+ Project-URL: Documentation, https://cocotbext-sva.readthedocs.io
8
+ Project-URL: Repository, https://github.com/dpavlo55/cocotbext-sva
9
+ Project-URL: Issues, https://github.com/dpavlo55/cocotbext-sva/issues
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Framework :: cocotb
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
22
+ Classifier: Topic :: Software Development :: Testing
23
+ Requires-Python: >=3.10
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Requires-Dist: cocotb<3,>=2.0
27
+ Provides-Extra: fast
28
+ Requires-Dist: cocotbext-sva-kernel; extra == "fast"
29
+ Dynamic: license-file
30
+
31
+ <p align="center">
32
+ <picture>
33
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dpavlo55/cocotbext-sva/main/docs/_static/logo-dark.svg">
34
+ <img alt="cocotbext-sva" src="https://raw.githubusercontent.com/dpavlo55/cocotbext-sva/main/docs/_static/logo.svg" width="480">
35
+ </picture>
36
+ </p>
37
+
38
+ <p align="center">
39
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/"><img alt="Documentation" src="https://img.shields.io/readthedocs/cocotbext-sva?logo=readthedocs&logoColor=white&label=docs"></a>
40
+ <a href="https://github.com/dpavlo55/cocotbext-sva/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/dpavlo55/cocotbext-sva/ci.yml?branch=main&logo=github&label=CI"></a>
41
+ <a href="https://github.com/dpavlo55/cocotbext-sva/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
42
+ <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white">
43
+ <img alt="cocotb 2.x" src="https://img.shields.io/badge/cocotb-2.x-blue">
44
+ </p>
45
+
46
+ <p align="center">
47
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/getting-started.html"><img alt="Getting started" src="https://img.shields.io/badge/%F0%9F%9A%80-Getting%20started-7c6fd6"></a>
48
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/guide/index.html"><img alt="User guide" src="https://img.shields.io/badge/%F0%9F%93%96-User%20guide-7c6fd6"></a>
49
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/api.html"><img alt="API reference" src="https://img.shields.io/badge/%F0%9F%A7%A9-API%20reference-7c6fd6"></a>
50
+ </p>
51
+
52
+ > **Note:** this package was implemented with [Claude Code](https://claude.com/claude-code),
53
+ > and its results were validated against a commercial SVA simulator.
54
+
55
+ SystemVerilog-style **immediate and concurrent (temporal) assertions** for
56
+ [cocotb](https://www.cocotb.org) testbenches, written in SVA syntax. Works
57
+ with VHDL and Verilog designs.
58
+
59
+ Status: alpha (0.1.0, the first release). Requires cocotb 2.x and Python 3.10+.
60
+
61
+ ```python
62
+ import cocotb
63
+ from cocotb.clock import Clock
64
+ from cocotbext.sva import Assertions, checked, posedge
65
+
66
+ @cocotb.test()
67
+ @checked # collect failures, fail the test at its end
68
+ async def test_handshake(dut):
69
+ Clock(dut.clk, 10, unit="ns").start()
70
+ a = Assertions(dut, clock=posedge(dut.clk), disable_iff="!rst_n", name="hs")
71
+ a.assert_property("req |-> ##[1:3] ack", name="req_gets_ack")
72
+ a.assert_property("(req, t = tag) |-> ##[1:8] (rsp && rsp_tag == t)", name="tag_returns")
73
+ a.cover_property("req ##1 req ##1 req", name="three_reqs")
74
+ ... # drive the design
75
+ ```
76
+
77
+ A failure is logged at the time it happens, with the attempt's start time and
78
+ the sampled values:
79
+
80
+ ```
81
+ 150.00ns ERROR sva.hs.req_gets_ack FAILED attempt started 120 ns
82
+ req |-> ##[1:3] ack
83
+ sampled: req=0 ack=0
84
+ ```
85
+
86
+ ## Features
87
+
88
+ - **The SVA property language:** sequences, implications, local variables,
89
+ `$past` and the other sampled-value functions, `always` / `eventually` /
90
+ `until`, `disable iff`, `accept_on`, `cover`, `expect`, immediate
91
+ assertions ([full list](https://cocotbext-sva.readthedocs.io/en/latest/guide/supported-sva.html)).
92
+ - **Several clocks:** clocks generated or derived in the HDL (exact SVA
93
+ sampling), and multi-clock properties (`req |=> @(posedge clk_b) ack_b`).
94
+ - **Reuse:** parameterised properties, named sequences, checkers bound to
95
+ several instances.
96
+ - **Speed:** all attempts of an assertion are merged and evaluated together;
97
+ an optional compiled kernel makes a busy assertion cost about 0.05 µs per
98
+ cycle; idle clocks are not followed at all.
99
+ - **`Probe`:** an optional generated HDL module that samples the signals
100
+ inside the simulator and buffers them, for the lowest overhead.
101
+ - **Offline checking:** the same assertions on a VCD or FST dump after the
102
+ simulation (`TraceSampler`).
103
+
104
+ ## Install
105
+
106
+ ```bash
107
+ pip install cocotbext-sva # pure Python
108
+ pip install cocotbext-sva[fast] # with the compiled kernel (same results, faster)
109
+ ```
110
+
111
+ ## Validation
112
+
113
+ - Tested on nvc, GHDL, Icarus Verilog and Verilator, and on a commercial
114
+ simulator (VHDL and SystemVerilog).
115
+ - Results checked against a golden corpus of about 1,200 cases recorded from
116
+ a commercial SVA implementation, and fuzzed against a reference
117
+ interpreter of the IEEE 1800 formal semantics. Where the commercial tool
118
+ and the standard disagree, the package follows the standard; the cases are
119
+ listed in the [notes](https://cocotbext-sva.readthedocs.io/en/latest/notes.html).
120
+
121
+ ## Documentation
122
+
123
+ The full documentation is at **https://cocotbext-sva.readthedocs.io**:
124
+
125
+ - [Getting started](https://cocotbext-sva.readthedocs.io/en/latest/getting-started.html):
126
+ a first test with assertions, in five minutes.
127
+ - [User guide](https://cocotbext-sva.readthedocs.io/en/latest/guide/index.html): writing assertions,
128
+ clocks and sampling, `Probe`, offline checking, semantics notes, speed.
129
+ - [API reference](https://cocotbext-sva.readthedocs.io/en/latest/api.html): every class and function.
130
+ - [Notes](https://cocotbext-sva.readthedocs.io/en/latest/notes.html): differences from the
131
+ reference implementation, simulator-specific behaviour, measurements.
132
+ - [Design](https://cocotbext-sva.readthedocs.io/en/latest/design.html): architecture.
133
+ [Releasing](https://cocotbext-sva.readthedocs.io/en/latest/release.html).
134
+
135
+ ## Development
136
+
137
+ ```bash
138
+ pip install -r requirements.txt
139
+ nox -s kernel # build and install the compiled kernel (needs Rust)
140
+ nox -s tests # unit tests, fuzzing, golden corpus (no simulator)
141
+ nox -s simtests # end-to-end tests on every simulator found
142
+ ```
143
+
144
+ CI runs on GitHub Actions (`.github/workflows`).
145
+
146
+ License: MIT (see `LICENSE`).
@@ -0,0 +1,116 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dpavlo55/cocotbext-sva/main/docs/_static/logo-dark.svg">
4
+ <img alt="cocotbext-sva" src="https://raw.githubusercontent.com/dpavlo55/cocotbext-sva/main/docs/_static/logo.svg" width="480">
5
+ </picture>
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/"><img alt="Documentation" src="https://img.shields.io/readthedocs/cocotbext-sva?logo=readthedocs&logoColor=white&label=docs"></a>
10
+ <a href="https://github.com/dpavlo55/cocotbext-sva/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/dpavlo55/cocotbext-sva/ci.yml?branch=main&logo=github&label=CI"></a>
11
+ <a href="https://github.com/dpavlo55/cocotbext-sva/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
12
+ <img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white">
13
+ <img alt="cocotb 2.x" src="https://img.shields.io/badge/cocotb-2.x-blue">
14
+ </p>
15
+
16
+ <p align="center">
17
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/getting-started.html"><img alt="Getting started" src="https://img.shields.io/badge/%F0%9F%9A%80-Getting%20started-7c6fd6"></a>
18
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/guide/index.html"><img alt="User guide" src="https://img.shields.io/badge/%F0%9F%93%96-User%20guide-7c6fd6"></a>
19
+ <a href="https://cocotbext-sva.readthedocs.io/en/latest/api.html"><img alt="API reference" src="https://img.shields.io/badge/%F0%9F%A7%A9-API%20reference-7c6fd6"></a>
20
+ </p>
21
+
22
+ > **Note:** this package was implemented with [Claude Code](https://claude.com/claude-code),
23
+ > and its results were validated against a commercial SVA simulator.
24
+
25
+ SystemVerilog-style **immediate and concurrent (temporal) assertions** for
26
+ [cocotb](https://www.cocotb.org) testbenches, written in SVA syntax. Works
27
+ with VHDL and Verilog designs.
28
+
29
+ Status: alpha (0.1.0, the first release). Requires cocotb 2.x and Python 3.10+.
30
+
31
+ ```python
32
+ import cocotb
33
+ from cocotb.clock import Clock
34
+ from cocotbext.sva import Assertions, checked, posedge
35
+
36
+ @cocotb.test()
37
+ @checked # collect failures, fail the test at its end
38
+ async def test_handshake(dut):
39
+ Clock(dut.clk, 10, unit="ns").start()
40
+ a = Assertions(dut, clock=posedge(dut.clk), disable_iff="!rst_n", name="hs")
41
+ a.assert_property("req |-> ##[1:3] ack", name="req_gets_ack")
42
+ a.assert_property("(req, t = tag) |-> ##[1:8] (rsp && rsp_tag == t)", name="tag_returns")
43
+ a.cover_property("req ##1 req ##1 req", name="three_reqs")
44
+ ... # drive the design
45
+ ```
46
+
47
+ A failure is logged at the time it happens, with the attempt's start time and
48
+ the sampled values:
49
+
50
+ ```
51
+ 150.00ns ERROR sva.hs.req_gets_ack FAILED attempt started 120 ns
52
+ req |-> ##[1:3] ack
53
+ sampled: req=0 ack=0
54
+ ```
55
+
56
+ ## Features
57
+
58
+ - **The SVA property language:** sequences, implications, local variables,
59
+ `$past` and the other sampled-value functions, `always` / `eventually` /
60
+ `until`, `disable iff`, `accept_on`, `cover`, `expect`, immediate
61
+ assertions ([full list](https://cocotbext-sva.readthedocs.io/en/latest/guide/supported-sva.html)).
62
+ - **Several clocks:** clocks generated or derived in the HDL (exact SVA
63
+ sampling), and multi-clock properties (`req |=> @(posedge clk_b) ack_b`).
64
+ - **Reuse:** parameterised properties, named sequences, checkers bound to
65
+ several instances.
66
+ - **Speed:** all attempts of an assertion are merged and evaluated together;
67
+ an optional compiled kernel makes a busy assertion cost about 0.05 µs per
68
+ cycle; idle clocks are not followed at all.
69
+ - **`Probe`:** an optional generated HDL module that samples the signals
70
+ inside the simulator and buffers them, for the lowest overhead.
71
+ - **Offline checking:** the same assertions on a VCD or FST dump after the
72
+ simulation (`TraceSampler`).
73
+
74
+ ## Install
75
+
76
+ ```bash
77
+ pip install cocotbext-sva # pure Python
78
+ pip install cocotbext-sva[fast] # with the compiled kernel (same results, faster)
79
+ ```
80
+
81
+ ## Validation
82
+
83
+ - Tested on nvc, GHDL, Icarus Verilog and Verilator, and on a commercial
84
+ simulator (VHDL and SystemVerilog).
85
+ - Results checked against a golden corpus of about 1,200 cases recorded from
86
+ a commercial SVA implementation, and fuzzed against a reference
87
+ interpreter of the IEEE 1800 formal semantics. Where the commercial tool
88
+ and the standard disagree, the package follows the standard; the cases are
89
+ listed in the [notes](https://cocotbext-sva.readthedocs.io/en/latest/notes.html).
90
+
91
+ ## Documentation
92
+
93
+ The full documentation is at **https://cocotbext-sva.readthedocs.io**:
94
+
95
+ - [Getting started](https://cocotbext-sva.readthedocs.io/en/latest/getting-started.html):
96
+ a first test with assertions, in five minutes.
97
+ - [User guide](https://cocotbext-sva.readthedocs.io/en/latest/guide/index.html): writing assertions,
98
+ clocks and sampling, `Probe`, offline checking, semantics notes, speed.
99
+ - [API reference](https://cocotbext-sva.readthedocs.io/en/latest/api.html): every class and function.
100
+ - [Notes](https://cocotbext-sva.readthedocs.io/en/latest/notes.html): differences from the
101
+ reference implementation, simulator-specific behaviour, measurements.
102
+ - [Design](https://cocotbext-sva.readthedocs.io/en/latest/design.html): architecture.
103
+ [Releasing](https://cocotbext-sva.readthedocs.io/en/latest/release.html).
104
+
105
+ ## Development
106
+
107
+ ```bash
108
+ pip install -r requirements.txt
109
+ nox -s kernel # build and install the compiled kernel (needs Rust)
110
+ nox -s tests # unit tests, fuzzing, golden corpus (no simulator)
111
+ nox -s simtests # end-to-end tests on every simulator found
112
+ ```
113
+
114
+ CI runs on GitHub Actions (`.github/workflows`).
115
+
116
+ License: MIT (see `LICENSE`).
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"] # (SPDX license expression, PEP 639)
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "cocotbext-sva"
7
+ version = "0.1.0"
8
+ description = "SystemVerilog-style immediate and concurrent assertions for cocotb"
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "David Pavlović" }]
13
+ requires-python = ">=3.10"
14
+ dependencies = ["cocotb>=2.0,<3"]
15
+ classifiers = [
16
+ "Development Status :: 3 - Alpha",
17
+ "Framework :: cocotb",
18
+ "Intended Audience :: Developers",
19
+ "Intended Audience :: Science/Research",
20
+ "Operating System :: OS Independent",
21
+ "Programming Language :: Python :: 3",
22
+ "Programming Language :: Python :: 3 :: Only",
23
+ "Programming Language :: Python :: 3.10",
24
+ "Programming Language :: Python :: 3.11",
25
+ "Programming Language :: Python :: 3.12",
26
+ "Programming Language :: Python :: 3.13",
27
+ "Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)",
28
+ "Topic :: Software Development :: Testing",
29
+ ]
30
+
31
+ [project.urls]
32
+ Documentation = "https://cocotbext-sva.readthedocs.io"
33
+ Repository = "https://github.com/dpavlo55/cocotbext-sva"
34
+ Issues = "https://github.com/dpavlo55/cocotbext-sva/issues"
35
+
36
+ [project.optional-dependencies]
37
+ fast = ["cocotbext-sva-kernel"] # optional compiled kernel (kernel/)
38
+
39
+ [tool.setuptools.packages.find]
40
+ where = ["src"]
41
+ include = ["cocotbext.*"]
42
+
43
+ [tool.pytest.ini_options]
44
+ testpaths = ["tests"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,28 @@
1
+ """SystemVerilog-style immediate and concurrent assertions for cocotb.
2
+
3
+ from cocotbext.sva import Assertions, checked, posedge
4
+
5
+ @cocotb.test()
6
+ @checked
7
+ async def test_handshake(dut):
8
+ a = Assertions(dut, clock=posedge(dut.clk), disable_iff="!rst_n")
9
+ a.assert_property("req |-> ##[1:3] ack", name="req_gets_ack")
10
+ ...
11
+ """
12
+ from ._api import (AssertionHandle, Assertions, BoundProperty, Checker, ClockingEvent, Failure,
13
+ Property, Sequence, checked, edge, negedge, posedge)
14
+ from ._errors import SvaError, SvaNameError, SvaSyntaxError, SvaUnsupportedError
15
+ from ._offline import OfflineFailure, OfflineResult, TraceSampler
16
+ from ._probe import Probe
17
+
18
+ __all__ = [
19
+ "Assertions", "AssertionHandle", "BoundProperty", "Checker", "ClockingEvent", "Failure",
20
+ "Property", "Sequence", "checked", "edge", "negedge", "posedge",
21
+ "SvaError", "SvaNameError", "SvaSyntaxError", "SvaUnsupportedError",
22
+ "TraceSampler", "OfflineResult", "OfflineFailure", "Probe",
23
+ ]
24
+ try: # the version of the installed distribution: set in pyproject.toml only
25
+ from importlib.metadata import version as _version
26
+ __version__ = _version("cocotbext-sva")
27
+ except Exception: # not installed (e.g. src/ on sys.path)
28
+ __version__ = "0+unknown"
@@ -0,0 +1,131 @@
1
+ """Fast signal readers chosen per handle.
2
+
3
+ The public `handle.value` builds Logic/LogicArray objects (5-10x the cost of a
4
+ raw GPI read for narrow signals). This module is the only place that uses the
5
+ private low-level handle (`handle._handle`); if it is unavailable the public
6
+ API is used instead.
7
+
8
+ Reader choice (from phase 0 / reader calibration on nvc, GHDL, Icarus,
9
+ Verilator and a commercial simulator):
10
+
11
+ * Logic scalars / vectors through VPI (Verilog simulators, and GHDL for VHDL):
12
+ `get_signed()` returns 0/1. GPI long is correct up to 32 bits, but may be
13
+ sign-extended (signed objects, 32-bit values): mask to the width.
14
+ * Logic scalars / vectors through VHPI or FLI (VHDL in nvc, commercial
15
+ simulators): `get_signed()` returns -1 and GPI long is wrong (enum
16
+ positions, 0, or an error value). Use the binary string.
17
+ * Wider than 32 bits: binary string.
18
+ * Integer / enum objects: GPI long (32-bit), masked.
19
+
20
+ Unknown bits (X, Z, U, W, -) read as 0, H as 1, L as 0. X masks are read
21
+ separately from the binary string, only for $isunknown / $countbits.
22
+ """
23
+ from __future__ import annotations
24
+
25
+ from dataclasses import dataclass
26
+
27
+ _TO_BIN = str.maketrans({"H": "1", "h": "1", "L": "0", "l": "0", "X": "0", "x": "0", "Z": "0",
28
+ "z": "0", "U": "0", "u": "0", "W": "0", "w": "0", "-": "0"})
29
+ _TO_XMASK = str.maketrans({"0": "0", "1": "0", "H": "0", "h": "0", "L": "0", "l": "0",
30
+ "X": "1", "x": "1", "Z": "1", "z": "1", "U": "1", "u": "1",
31
+ "W": "1", "w": "1", "-": "1"})
32
+
33
+
34
+ @dataclass
35
+ class SignalInfo:
36
+ reader: object # () -> int
37
+ width: int
38
+ signed: bool
39
+ left: int | None # declared range, None for scalars
40
+ right: int | None
41
+ vpi: bool # accessed through VPI (long reads valid)
42
+ label: str
43
+
44
+
45
+ def _binstr_to_int(get):
46
+ def read():
47
+ s = get()
48
+ try:
49
+ return int(s, 2)
50
+ except ValueError:
51
+ return int(s.translate(_TO_BIN), 2) if s else 0
52
+ return read
53
+
54
+
55
+ def _bit_reader(get):
56
+ def read():
57
+ c = get()
58
+ return 1 if c == "1" or c == "H" or c == "h" else 0
59
+ return read
60
+
61
+
62
+ def signal_info(handle, label: str = "") -> SignalInfo:
63
+ """Inspect a cocotb value handle and choose the fastest correct reader."""
64
+ from cocotb.handle import EnumObject, IntegerObject, LogicArrayObject, LogicObject, RealObject
65
+
66
+ label = label or getattr(handle, "_path", "") or str(handle)
67
+ ll = getattr(handle, "_handle", None)
68
+ if isinstance(handle, RealObject):
69
+ from ._errors import SvaUnsupportedError
70
+ raise SvaUnsupportedError(f"real-valued signal '{label}' is not supported in assertions")
71
+ if ll is None: # no low-level handle: public API fallback
72
+ return _public_info(handle, label)
73
+
74
+ signed_flag = ll.get_signed()
75
+ if isinstance(handle, (IntegerObject, EnumObject)):
76
+ get = ll.get_signal_val_long
77
+ width = 32
78
+ m = (1 << width) - 1
79
+ return SignalInfo(lambda: get() & m, width, isinstance(handle, IntegerObject) and signed_flag != 0,
80
+ None, None, True, label)
81
+
82
+ is_scalar = isinstance(handle, LogicObject)
83
+ width = 1 if is_scalar else len(handle)
84
+ left = right = None
85
+ if not is_scalar:
86
+ try:
87
+ left, right, _ = ll.get_range()
88
+ except Exception:
89
+ left, right = width - 1, 0
90
+ vpi = signed_flag in (0, 1)
91
+ signed = signed_flag == 1
92
+ if vpi and width <= 32:
93
+ get = ll.get_signal_val_long
94
+ m = (1 << width) - 1
95
+ reader = lambda: get() & m # noqa: E731
96
+ elif is_scalar:
97
+ reader = _bit_reader(ll.get_signal_val_binstr)
98
+ else:
99
+ reader = _binstr_to_int(ll.get_signal_val_binstr)
100
+ return SignalInfo(reader, width, signed, left, right, vpi, label)
101
+
102
+
103
+ def x_reader(handle):
104
+ """() -> X mask of the handle (bits that are X/Z/U/W/-)."""
105
+ ll = getattr(handle, "_handle", None)
106
+ if ll is None:
107
+ return lambda: int(str(handle.value).translate(_TO_XMASK) or "0", 2)
108
+ get = ll.get_signal_val_binstr
109
+
110
+ def read():
111
+ s = get()
112
+ if not s or s.isdigit() and set(s) <= {"0", "1"}:
113
+ return 0
114
+ try:
115
+ return int(s.translate(_TO_XMASK), 2)
116
+ except ValueError:
117
+ return 0
118
+ return read
119
+
120
+
121
+ def _public_info(handle, label):
122
+ v = handle.value
123
+ width = len(v) if hasattr(v, "__len__") else 32
124
+
125
+ def read():
126
+ val = handle.value
127
+ try:
128
+ return int(val)
129
+ except (ValueError, TypeError):
130
+ return int(str(val).translate(_TO_BIN) or "0", 2)
131
+ return SignalInfo(read, width, False, None, None, False, label)