svtb 0.1.0__tar.gz

svtb-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Correll
+
+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.

svtb-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: svtb
+Version: 0.1.0
+Summary: Self-checking SystemVerilog testbench generator: the subset of fault's Tester and magma's port-declaration API that svreal's and msdsl's tests use, for Python versions neither package installs on
+Author: Justin Correll
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/correlljm/svtb
+Project-URL: Repository, https://github.com/correlljm/svtb
+Project-URL: Issues, https://github.com/correlljm/svtb/issues
+Project-URL: Changelog, https://github.com/correlljm/svtb/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: svtb/fault/LICENSE.txt
+License-File: svtb/magma/LICENSE.txt
+Dynamic: license-file
+
+# svtb
+
+A self-checking SystemVerilog testbench generator: the subset of
+[fault](https://github.com/leonardt/fault)'s `Tester` and [magma](https://github.com/phanrahan/magma)'s
+port-declaration API that svreal's and msdsl's historical test suites use. Neither fault nor magma installs
+on Python 3.14; this is a from-scratch implementation written to the same calling convention, so existing
+test files do not change.
+
+`svtb.fault.Tester` records `poke`, `eval`, `step`, `expect` and `get_value` calls and generates a
+self-checking SystemVerilog testbench, run on iverilog, Verilator, Xcelium, Incisive, Vivado or VCS. The
+commands for Xcelium, Incisive, Vivado and VCS follow fault 3.0.43's `SystemVerilogTarget`.
+
+`svtb.magma` declares a DUT's name and port list only; no circuit construction or compilation.
+
+## Installation
+
+```shell
+pip install svtb
+```
+
+or, in a consuming package's `pyproject.toml`, as a dev dependency:
+
+```toml
+[dependency-groups]
+dev = ["svtb", "pytest"]
+```
+
+Then point `tests/conftest.py`'s import path at the installed package instead of a local directory:
+
+```python
+import svtb
+sys.path.insert(0, str(Path(svtb.__file__).parent))
+```
+
+This makes `import fault` and `import magma as m` resolve to `svtb`'s subpackages as top-level modules,
+exactly as they would from a local `tests/support/` directory.
+
+## Licensing
+
+- `fault` is BSD-3-Clause, Copyright 2018 Leonard Truong; see `svtb/fault/LICENSE.txt`.
+- `magma` is MIT, Copyright (C) 2016 Stanford University; see `svtb/magma/LICENSE.txt`.
+- svtb itself is MIT; see `LICENSE`.
+
+## Running the tests
+
+```shell
+uv sync
+uv run pytest -q tests
+```
+
+`tests/test_tester.py` checks the generator on each simulator; `tests/fake_sim.py` stands in for Xcelium,
+Incisive, Vivado and VCS, since only iverilog and Verilator have run here.

svtb-0.1.0/README.md

@@ -0,0 +1,52 @@
+# svtb
+
+A self-checking SystemVerilog testbench generator: the subset of
+[fault](https://github.com/leonardt/fault)'s `Tester` and [magma](https://github.com/phanrahan/magma)'s
+port-declaration API that svreal's and msdsl's historical test suites use. Neither fault nor magma installs
+on Python 3.14; this is a from-scratch implementation written to the same calling convention, so existing
+test files do not change.
+
+`svtb.fault.Tester` records `poke`, `eval`, `step`, `expect` and `get_value` calls and generates a
+self-checking SystemVerilog testbench, run on iverilog, Verilator, Xcelium, Incisive, Vivado or VCS. The
+commands for Xcelium, Incisive, Vivado and VCS follow fault 3.0.43's `SystemVerilogTarget`.
+
+`svtb.magma` declares a DUT's name and port list only; no circuit construction or compilation.
+
+## Installation
+
+```shell
+pip install svtb
+```
+
+or, in a consuming package's `pyproject.toml`, as a dev dependency:
+
+```toml
+[dependency-groups]
+dev = ["svtb", "pytest"]
+```
+
+Then point `tests/conftest.py`'s import path at the installed package instead of a local directory:
+
+```python
+import svtb
+sys.path.insert(0, str(Path(svtb.__file__).parent))
+```
+
+This makes `import fault` and `import magma as m` resolve to `svtb`'s subpackages as top-level modules,
+exactly as they would from a local `tests/support/` directory.
+
+## Licensing
+
+- `fault` is BSD-3-Clause, Copyright 2018 Leonard Truong; see `svtb/fault/LICENSE.txt`.
+- `magma` is MIT, Copyright (C) 2016 Stanford University; see `svtb/magma/LICENSE.txt`.
+- svtb itself is MIT; see `LICENSE`.
+
+## Running the tests
+
+```shell
+uv sync
+uv run pytest -q tests
+```
+
+`tests/test_tester.py` checks the generator on each simulator; `tests/fake_sim.py` stands in for Xcelium,
+Incisive, Vivado and VCS, since only iverilog and Verilator have run here.

svtb-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "svtb"
+version = "0.1.0"
+description = "Self-checking SystemVerilog testbench generator: the subset of fault's Tester and magma's port-declaration API that svreal's and msdsl's tests use, for Python versions neither package installs on"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "svtb/fault/LICENSE.txt", "svtb/magma/LICENSE.txt"]
+authors = [{ name = "Justin Correll" }]
+requires-python = ">=3.14"
+dependencies = []
+classifiers = [
+    "Development Status :: 3 - Alpha",
+]
+
+[project.urls]
+Homepage = "https://github.com/correlljm/svtb"
+Repository = "https://github.com/correlljm/svtb"
+Issues = "https://github.com/correlljm/svtb/issues"
+Changelog = "https://github.com/correlljm/svtb/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+include = ["svtb*"]
+
+[tool.setuptools.package-data]
+svtb = ["fault/LICENSE.txt", "magma/LICENSE.txt"]
+
+[dependency-groups]
+dev = ["pytest", "numpy"]

svtb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

svtb-0.1.0/svtb/__init__.py

@@ -0,0 +1,8 @@
+"""svtb: a self-checking SystemVerilog testbench generator.
+
+Implements the subset of fault's (https://github.com/leonardt/fault) Tester and magma's
+(https://github.com/phanrahan/magma) port-declaration API that svreal's and msdsl's historical test suites
+use. Neither fault nor magma installs on Python 3.14; this is a from-scratch implementation, not a
+compatibility patch, written to the same calling convention so existing test files do not change. See
+README.md.
+"""

svtb-0.1.0/svtb/fault/LICENSE.txt

@@ -0,0 +1,26 @@
+Copyright 2018 Leonard Truong
+
+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.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+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.

svtb-0.1.0/svtb/fault/__init__.py

@@ -0,0 +1,12 @@
+"""Subset of the fault testbench API (https://github.com/leonardt/fault, BSD-3-Clause, see LICENSE.txt),
+as svreal's and msdsl's tests use it."""
+
+from magma import PortType
+
+from . import subprocess_run
+from .tester import GetValue, Tester
+
+RealIn = PortType("real", direction="in")
+RealOut = PortType("real", direction="out")
+
+__all__ = ["GetValue", "RealIn", "RealOut", "Tester", "subprocess_run"]

svtb-0.1.0/svtb/fault/subprocess_run.py

@@ -0,0 +1,65 @@
+"""subprocess.run wrapper with fault's semantics: optional live display, error-string scan,
+return-code check. Raises AssertionError on failure."""
+
+from __future__ import annotations
+
+import re
+import shlex
+import subprocess
+
+
+def _error_detected(text: str, err_str) -> bool:
+    if isinstance(err_str, str):
+        return err_str in text
+    if isinstance(err_str, list):
+        return any(elem in text for elem in err_str)
+    if isinstance(err_str, re.Pattern):
+        return err_str.search(text) is not None
+    raise TypeError(f"Invalid err_str: {err_str!r}")
+
+
+def subprocess_run(
+    args,
+    cwd=None,
+    env=None,
+    disp_type: str = "on_error",
+    err_str=None,
+    chk_ret_code: bool = True,
+    shell: bool = False,
+    use_fault_cfg: bool = True,
+) -> subprocess.CompletedProcess:
+    if disp_type not in ("on_error", "realtime"):
+        raise ValueError(f"Invalid disp_type: {disp_type!r}")
+    args = [str(arg) for arg in args]
+    cmd_str = " ".join(shlex.quote(arg) for arg in args)
+    if disp_type == "realtime":
+        print(f"Running command: {cmd_str}", flush=True)
+
+    result = subprocess.run(
+        cmd_str if shell else args,
+        cwd=cwd,
+        env=env,
+        shell=shell,
+        capture_output=True,
+        text=True,
+    )
+    if disp_type == "realtime":
+        print(result.stdout, end="", flush=True)
+        print(result.stderr, end="", flush=True)
+
+    errors = []
+    if chk_ret_code and result.returncode:
+        errors.append(f"Got return code {result.returncode}.")
+    if err_str is not None:
+        if _error_detected(result.stdout, err_str):
+            errors.append(f'Found error pattern "{err_str}" in STDOUT.')
+        if _error_detected(result.stderr, err_str):
+            errors.append(f'Found error pattern "{err_str}" in STDERR.')
+
+    if errors:
+        if disp_type == "on_error":
+            print(f"Running command: {cmd_str}")
+            print(result.stdout, end="")
+            print(result.stderr, end="")
+        raise AssertionError(" ".join(errors))
+    return result

svtb-0.1.0/svtb/fault/tester.py

@@ -0,0 +1,432 @@
+"""fault.Tester subset: record poke/expect/step/... actions, emit a SystemVerilog testbench,
+run it under iverilog, Verilator, Xcelium (xrun), Incisive (irun), Vivado (xsim) or VCS.
+
+The commands for Xcelium, Incisive, Vivado and VCS follow fault 3.0.43's SystemVerilogTarget
+(BSD-3-Clause, see LICENSE.txt), with two changes: the Cadence Tcl runs to $finish rather than for
+num_cycles, and every one of them also fails on the testbench's own expect message, which fault
+did not check for Cadence.
+
+Timing mirrors fault's SystemVerilogTarget: poke is a nonblocking assign, eval is #1, step
+toggles the clock after #clock_step_delay, delay(t) is #(t*1s), and a failed expect raises
+$error, which is detected by scanning simulator output.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from magma import Port
+
+from .subprocess_run import subprocess_run
+
+# Printed as the testbench's last action so a simulation that stops early cannot pass.
+_DONE_TOKEN = "__FAULTSHIM_DONE__"
+_GET_VALUE_FILE = "get_value_file.txt"
+_SIMULATORS = ("iverilog", "verilator", "xcelium", "ncsim", "vivado", "vcs")
+# Start of the $error message a failed expect prints; see _render_expect.
+_EXPECT_FAILED = "Failed on action="
+
+
+def _plus_defines(defines: dict | None) -> list[str]:
+    """`+define+NAME` or `+define+NAME=value`, as fault's def_args writes them for Cadence and VCS."""
+    return [f"+define+{k}" if v is None else f"+define+{k}={v}" for k, v in (defines or {}).items()]
+
+
+def _vivado_tcl(srcs: list[Path], incs: list[Path], defines: dict, top_module: str) -> str:
+    """fault's write_vivado_tcl: a project with the sources as SystemVerilog, run to $finish."""
+    files = " ".join(f"{{{src}}}" for src in srcs)
+    cmds = ["create_project -force {project} {project}", f"add_files [list {files}]"]
+    cmds += [f"set_property file_type SystemVerilog [get_files [list {files}]]"]
+    if incs:
+        dirs = " ".join(f"{{{d}}}" for d in incs)
+        cmds += [f"set_property include_dirs [list {dirs}] [get_fileset sim_1]"]
+    if defines:
+        defs = " ".join(f"{{{k}}}" if v is None else f"{{{k}={v}}}" for k, v in defines.items())
+        cmds += [f"set_property -name verilog_define -value [list {defs}] -objects [get_fileset sim_1]"]
+    cmds += [f"set_property -name top -value {{{top_module}}} -objects [get_fileset sim_1]"]
+    cmds += ["set_property -name xsim.simulate.runtime -value -all -objects [get_fileset sim_1]"]
+    cmds += ["launch_simulation"]
+    return "\n".join(cmds)
+
+
+@dataclass
+class GetValue:
+    port: Port
+    value: float | int | None = None
+
+    @property
+    def is_real(self) -> bool:
+        return self.port.type_.kind == "real"
+
+    def update_from_line(self, line: str) -> None:
+        self.value = float(line) if self.is_real else int(line)
+
+
+@dataclass
+class _Action:
+    kind: str
+    args: tuple = ()
+    kwargs: dict = field(default_factory=dict)
+
+
+def _sv_real(value) -> str:
+    # float() first: NumPy 2 scalars repr as "np.float64(...)", which is not SV.
+    return repr(float(value))
+
+
+def _sv_value(port: Port, value) -> str:
+    type_ = port.type_
+    if type_.kind == "real":
+        return _sv_real(value)
+    width = type_.width
+    return f"{width}'d{int(value) & ((1 << width) - 1)}"
+
+
+def _sv_string(text: str) -> str:
+    return text.replace('"', '\\"').replace("\n", "\\n")
+
+
+class Tester:
+    def __init__(
+        self,
+        circuit,
+        clock: Port | None = None,
+        reset: Port | None = None,
+        poke_delay_default: float | None = None,
+        expect_strict_default: bool = True,
+    ) -> None:
+        self._circuit = circuit
+        self.clock = clock
+        self.reset = reset
+        self.poke_delay_default = poke_delay_default
+        self.expect_strict_default = expect_strict_default
+        self.debug_mode = False
+        self.actions: list[_Action] = []
+        if clock is not None:
+            self.poke(clock, 0)
+
+    @property
+    def circuit(self):
+        return self._circuit
+
+    # ---- actions ---------------------------------------------------------------------------
+
+    def poke(self, port: Port, value, delay: float | None = None) -> None:
+        if delay is None:
+            delay = self.poke_delay_default
+        self.actions.append(_Action("poke", (port, value), {"delay": delay}))
+
+    def expect(
+        self,
+        port: Port,
+        value,
+        strict: bool | None = None,
+        caller=None,
+        abs_tol: float | None = None,
+        rel_tol: float | None = None,
+        above: float | None = None,
+        below: float | None = None,
+        msg=None,
+    ) -> None:
+        if strict is None:
+            strict = self.expect_strict_default
+        if abs_tol is not None or rel_tol is not None:
+            if above is not None or below is not None:
+                raise ValueError("Cannot provide both abs_tol/rel_tol and above/below.")
+            abs_tol = abs_tol or 0
+            rel_tol = rel_tol or 0
+            if abs_tol < 0 or rel_tol < 0:
+                raise ValueError("rel_tol and abs_tol must be non-negative.")
+            above = value - rel_tol * abs(value) - abs_tol
+            below = value + rel_tol * abs(value) + abs_tol
+        if msg is not None and not isinstance(msg, (str, tuple)):
+            raise ValueError("expect msg must be a str or a (format_str, *args) tuple")
+        self.actions.append(
+            _Action(
+                "expect",
+                (port, value),
+                {"strict": strict, "above": above, "below": below, "msg": msg},
+            )
+        )
+
+    def eval(self) -> None:
+        self.actions.append(_Action("eval"))
+
+    def delay(self, time: float) -> None:
+        self.actions.append(_Action("delay", (time,)))
+
+    def step(self, steps: int = 1) -> None:
+        if self.clock is None:
+            raise RuntimeError("Stepping tester without a clock")
+        self.actions.append(_Action("step", (int(steps),)))
+
+    def print(self, format_str: str, *args) -> None:
+        self.actions.append(_Action("print", (format_str, *args)))
+
+    def get_value(self, port: Port) -> GetValue:
+        result = GetValue(port)
+        self.actions.append(_Action("get_value", (result,)))
+        return result
+
+    def zero_inputs(self) -> None:
+        for name, type_ in self._circuit.IO.ports.items():
+            if type_.is_input():
+                self.poke(getattr(self._circuit, name), 0)
+
+    # ---- code generation -------------------------------------------------------------------
+
+    def _render_action(self, i: int, action: _Action, clock_step_delay: float) -> list[str]:
+        kind, args, kw = action.kind, action.args, action.kwargs
+        if kind == "poke":
+            port, value = args
+            lines = [f"{port.name} <= {_sv_value(port, value)};"]
+            if kw["delay"] is not None:
+                lines.append(f"#({kw['delay']}*1s);")
+            return lines
+        if kind == "eval":
+            return ["#1;"]
+        if kind == "delay":
+            return [f"#({args[0]}*1s);"]
+        if kind == "step":
+            return [f"#{clock_step_delay} {self.clock.name} ^= 1;" for _ in range(args[0])]
+        if kind == "print":
+            fmt, *ports = args
+            items = [f'"{_sv_string(fmt)}"'] + [
+                p.name if isinstance(p, Port) else str(p) for p in ports
+            ]
+            return [f"$write({', '.join(items)});"]
+        if kind == "get_value":
+            (result,) = args
+            fmt = "%0f" if result.is_real else "%0d"
+            return [f'$fwrite(__get_value_fd, "{fmt}\\n", {result.port.name});']
+        if kind == "expect":
+            return self._render_expect(i, *args, **kw)
+        raise AssertionError(f"unknown action {kind}")
+
+    @staticmethod
+    def _render_expect(i: int, port: Port, value, strict, above, below, msg) -> list[str]:
+        name = port.name
+        if above is not None and below is not None:
+            lo, hi = _sv_real(above), _sv_real(below)
+            cond = f"(({lo} <= {name}) && ({name} <= {hi}))"
+            err_msg, err_args = "Expected %0f to %0f, got %0f", [lo, hi, name]
+        elif above is not None:
+            lo = _sv_real(above)
+            cond = f"({lo} <= {name})"
+            err_msg, err_args = "Expected above %0f, got %0f", [lo, name]
+        elif below is not None:
+            hi = _sv_real(below)
+            cond = f"({name} <= {hi})"
+            err_msg, err_args = "Expected below %0f, got %0f", [hi, name]
+        else:
+            sv_value = _sv_value(port, value)
+            is_real = port.type_.kind == "real"
+            # SV forbids === on reals; fault emitted it anyway, which failed to compile.
+            cond = f"({name} {'===' if strict and not is_real else '=='} {sv_value})"
+            fmt = "%0f" if is_real else "%x"
+            err_msg, err_args = f"Expected {fmt}, got {fmt}", [sv_value, name]
+        if isinstance(msg, str):
+            err_msg += "\\n" + _sv_string(msg)
+        elif isinstance(msg, tuple):
+            err_msg += "\\n" + _sv_string(msg[0])
+            err_args += [p.name if isinstance(p, Port) else str(p) for p in msg[1:]]
+        body = ", ".join([f'"Failed on action={i} checking port {name}.  {err_msg}."', *err_args])
+        return [f"if (!{cond}) begin", f"    $error({body});", "end"]
+
+    def _render_testbench(
+        self,
+        top_module: str,
+        timescale: str,
+        clock_step_delay: float,
+        parameters: dict,
+        dump_waveforms: bool,
+        get_value_path: Path,
+    ) -> str:
+        decls, conns = [], []
+        for name, type_ in self._circuit.IO.ports.items():
+            if type_.kind == "real":
+                sv_type = "real"
+            else:
+                sv_type = "reg" if type_.is_input() else "wire"
+                if type_.kind == "bits":
+                    sv_type += f" [{type_.width - 1}:0]"
+            decls.append(f"    {sv_type} {name};")
+            conns.append(f".{name}({name})")
+
+        body = []
+        if dump_waveforms:
+            body += ['$dumpfile("waveforms.vcd");', "$dumpvars(0, dut);"]
+        uses_get_value = any(a.kind == "get_value" for a in self.actions)
+        if uses_get_value:
+            body.append(f'__get_value_fd = $fopen("{get_value_path}", "w");')
+        for i, action in enumerate(self.actions):
+            body += self._render_action(i, action, clock_step_delay)
+        if uses_get_value:
+            body.append("$fclose(__get_value_fd);")
+        body += ["#20;", f'$display("{_DONE_TOKEN}");', "$finish;"]
+
+        params = ", ".join(f".{k}({v})" for k, v in parameters.items())
+        param_str = f"#({params}) " if params else ""
+        lines = [
+            f"`timescale {timescale}",
+            f"module {top_module};",
+            *decls,
+            "    integer __get_value_fd;" if uses_get_value else "",
+            f"    {self._circuit.name} {param_str}dut ({', '.join(conns)});",
+            "    initial begin",
+            *[f"        {line}" for line in body],
+            "    end",
+            "endmodule",
+            "",
+        ]
+        return "\n".join(lines)
+
+    # ---- compile and run -------------------------------------------------------------------
+
+    def compile_and_run(self, target: str = "system-verilog", tmp_dir: bool = False, **kwargs):
+        if tmp_dir:
+            with tempfile.TemporaryDirectory(dir=".") as directory:
+                kwargs["directory"] = directory
+                self._compile_and_run(target, **kwargs)
+        else:
+            self._compile_and_run(target, **kwargs)
+
+    def _compile_and_run(
+        self,
+        target: str,
+        simulator: str | None = None,
+        directory="build/",
+        ext_srcs=None,
+        include_verilog_libraries=None,
+        ext_model_file=None,
+        ext_libs=None,
+        inc_dirs=None,
+        include_directories=None,
+        defines=None,
+        flags=None,
+        parameters=None,
+        timescale: str = "1ns/1ns",
+        clock_step_delay: float = 5,
+        num_cycles=None,  # accepted for API compatibility; SV runs to $finish
+        dump_waveforms: bool = False,
+        disp_type: str = "on_error",
+        ext_test_bench: bool = False,
+        top_module: str | None = None,
+    ) -> None:
+        if target == "verilator":
+            simulator = "verilator"
+        elif target != "system-verilog":
+            raise NotImplementedError(f"svtb supports only system-verilog, not {target!r}")
+        if simulator not in _SIMULATORS:
+            raise NotImplementedError(f"svtb supports {_SIMULATORS}, not {simulator!r}")
+
+        directory = Path(directory).resolve()
+        directory.mkdir(parents=True, exist_ok=True)
+        srcs = [Path(s).resolve() for s in (include_verilog_libraries or []) + (ext_srcs or [])]
+        if isinstance(ext_model_file, (str, Path)):
+            srcs.append(Path(ext_model_file).resolve())
+        elif not (ext_model_file or ext_test_bench):
+            raise NotImplementedError("svtb cannot compile magma circuits; pass ext_model_file")
+        incs = [Path(d).resolve() for d in (inc_dirs or []) + (include_directories or [])]
+        lib_dirs = list(dict.fromkeys(Path(lib).resolve().parent for lib in ext_libs or []))
+        def_args = [
+            f"-D{k}" if v is None else f"-D{k}={v}" for k, v in (defines or {}).items()
+        ]
+
+        get_value_path = directory / _GET_VALUE_FILE
+        if ext_test_bench:
+            top_module = top_module or self._circuit.name
+        else:
+            top_module = top_module or f"{self._circuit.name}_tb"
+            tb_file = directory / f"{self._circuit.name}_tb.sv"
+            tb_file.write_text(
+                self._render_testbench(
+                    top_module,
+                    timescale,
+                    clock_step_delay,
+                    parameters or {},
+                    dump_waveforms,
+                    get_value_path,
+                )
+            )
+            srcs = [tb_file, *srcs]
+
+        bin_name = f"{self._circuit.name}_tb"
+        if simulator == "iverilog":
+            compile_cmd = ["iverilog", *(flags or []), f"-o{bin_name}"]
+            if lib_dirs:
+                compile_cmd += ["-Y.v", "-Y.sv", *[f"-y{d}" for d in lib_dirs]]
+            compile_cmd += [f"-I{d}" for d in incs] + def_args
+            compile_cmd += ["-g2012", "-s", top_module, *srcs]
+            compile_err = ["syntax error", "I give up."]
+            run_cmd = ["vvp", "-N", bin_name]
+            run_err = ["ERROR", "FATAL"]
+        elif simulator == "verilator":
+            compile_cmd = ["verilator", "--binary", "--timing", "-Wno-fatal"]
+            compile_cmd += ["--timescale", timescale, *(flags or [])]
+            compile_cmd += [f"-y{d}" for d in lib_dirs]
+            compile_cmd += [f"-I{d}" for d in incs] + def_args
+            compile_cmd += ["--top-module", top_module, "-o", bin_name, *srcs]
+            compile_err = None
+            run_cmd = [str(directory / "obj_dir" / bin_name)]
+            run_err = ["%Error", "ERROR", "FATAL"]
+        elif simulator in ("xcelium", "ncsim"):
+            # one command compiles and runs; fault's cadence_cmd and write_cadence_tcl
+            tcl = directory / f"{self._circuit.name}_cmd.tcl"
+            tcl.write_text("run\nassertion -summary -final\nquit")
+            compile_cmd = None
+            run_cmd = ["xrun" if simulator == "xcelium" else "irun", *(flags or [])]
+            run_cmd += ["-top", top_module, "-timescale", timescale, "-input", tcl, *srcs]
+            for lib in ext_libs or []:
+                run_cmd += ["-v", Path(lib).resolve()]
+            for d in incs:
+                run_cmd += ["-incdir", d]
+            run_cmd += _plus_defines(defines)
+            if dump_waveforms:
+                run_cmd += ["-access", "r"]
+            run_cmd += ["-notimingchecks"]
+            run_err = [_EXPECT_FAILED]
+        elif simulator == "vivado":
+            # a batch-mode project that compiles and runs; fault's write_vivado_tcl and vivado_cmd
+            tcl = directory / f"{self._circuit.name}_cmd.tcl"
+            tcl.write_text(
+                _vivado_tcl(srcs + [Path(lib).resolve() for lib in ext_libs or []], incs,
+                            defines or {}, top_module)
+            )
+            compile_cmd = None
+            run_cmd = ["vivado", *(flags or []), "-mode", "batch", "-source", tcl]
+            run_cmd += ["-nolog", "-nojournal"]
+            run_err = ["CRITICAL WARNING", "ERROR", "Fatal", "Error", _EXPECT_FAILED]
+        else:
+            # compile to ./simv, then run it; fault's vcs_cmd
+            compile_cmd = ["vcs", *(flags or []), f"-timescale={timescale}", *srcs]
+            for lib in ext_libs or []:
+                compile_cmd += ["-v", Path(lib).resolve()]
+            compile_cmd += [f"+incdir+{d}" for d in incs] + _plus_defines(defines)
+            compile_cmd += ["-sverilog", "-full64", "+v2k", "-LDFLAGS", "-Wl,--no-as-needed"]
+            if dump_waveforms:
+                compile_cmd += ["-debug_pp"]
+            compile_cmd += ["-top", top_module]
+            compile_err = None
+            run_cmd = ["./simv"]
+            run_err = ["Error", "Fatal", _EXPECT_FAILED]
+
+        if compile_cmd is not None:
+            subprocess_run(compile_cmd, cwd=directory, err_str=compile_err, disp_type=disp_type)
+        result = subprocess_run(run_cmd, cwd=directory, err_str=run_err, disp_type=disp_type)
+        if not ext_test_bench and _DONE_TOKEN not in result.stdout:
+            print(result.stdout)
+            raise AssertionError("Testbench did not reach its final action.")
+
+
+        get_values = [a.args[0] for a in self.actions if a.kind == "get_value"]
+        if get_values:
+            lines = get_value_path.read_text().splitlines()
+            if len(lines) != len(get_values):
+                raise AssertionError(
+                    f"Expected {len(get_values)} get_value results, found {len(lines)}."
+                )
+            for line, result_ in zip(lines, get_values):
+                result_.update_from_line(line)

svtb-0.1.0/svtb/magma/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (C) 2016 Stanford University.
+All rights reserved.
+
+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.

svtb-0.1.0/svtb/magma/__init__.py

@@ -0,0 +1,80 @@
+"""Port-declaration subset of magma (https://github.com/phanrahan/magma, MIT, see LICENSE.txt), as svreal's
+and msdsl's tests use it.
+
+Only declares a DUT's name and port list; no circuit construction or compilation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class PortType:
+    kind: str  # 'bit', 'bits', 'clock' or 'real'
+    width: int = 1
+    signed: bool = False
+    direction: str | None = None  # 'in', 'out' or None
+
+    def is_input(self) -> bool:
+        return self.direction == "in"
+
+    def is_output(self) -> bool:
+        return self.direction == "out"
+
+
+class _VectorFactory:
+    def __init__(self, signed: bool) -> None:
+        self._signed = signed
+
+    def __getitem__(self, width: int) -> PortType:
+        return PortType("bits", int(width), self._signed)
+
+
+def In(type_: PortType) -> PortType:  # noqa: N802 (magma API name)
+    return replace(type_, direction="in")
+
+
+def Out(type_: PortType) -> PortType:  # noqa: N802 (magma API name)
+    return replace(type_, direction="out")
+
+
+Bit = PortType("bit")
+BitIn = In(Bit)
+BitOut = Out(Bit)
+Clock = PortType("clock")
+ClockIn = In(Clock)
+Bits = _VectorFactory(signed=False)
+UInt = _VectorFactory(signed=False)
+SInt = _VectorFactory(signed=True)
+
+
+@dataclass(frozen=True)
+class Port:
+    name: str
+    type_: PortType
+
+    def __str__(self) -> str:
+        return self.name
+
+
+class IO:
+    def __init__(self, **ports: PortType) -> None:
+        self.ports = dict(ports)
+
+
+class _CircuitMeta(type):
+    def __init__(cls, name, bases, namespace):
+        super().__init__(name, bases, namespace)
+        io = namespace.get("io")
+        if io is None:
+            return
+        if "name" not in namespace:
+            cls.name = name
+        cls.IO = io
+        for port_name, type_ in io.ports.items():
+            setattr(cls, port_name, Port(port_name, type_))
+
+
+class Circuit(metaclass=_CircuitMeta):
+    pass

svtb-0.1.0/svtb.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: svtb
+Version: 0.1.0
+Summary: Self-checking SystemVerilog testbench generator: the subset of fault's Tester and magma's port-declaration API that svreal's and msdsl's tests use, for Python versions neither package installs on
+Author: Justin Correll
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/correlljm/svtb
+Project-URL: Repository, https://github.com/correlljm/svtb
+Project-URL: Issues, https://github.com/correlljm/svtb/issues
+Project-URL: Changelog, https://github.com/correlljm/svtb/blob/main/CHANGELOG.md
+Classifier: Development Status :: 3 - Alpha
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: svtb/fault/LICENSE.txt
+License-File: svtb/magma/LICENSE.txt
+Dynamic: license-file
+
+# svtb
+
+A self-checking SystemVerilog testbench generator: the subset of
+[fault](https://github.com/leonardt/fault)'s `Tester` and [magma](https://github.com/phanrahan/magma)'s
+port-declaration API that svreal's and msdsl's historical test suites use. Neither fault nor magma installs
+on Python 3.14; this is a from-scratch implementation written to the same calling convention, so existing
+test files do not change.
+
+`svtb.fault.Tester` records `poke`, `eval`, `step`, `expect` and `get_value` calls and generates a
+self-checking SystemVerilog testbench, run on iverilog, Verilator, Xcelium, Incisive, Vivado or VCS. The
+commands for Xcelium, Incisive, Vivado and VCS follow fault 3.0.43's `SystemVerilogTarget`.
+
+`svtb.magma` declares a DUT's name and port list only; no circuit construction or compilation.
+
+## Installation
+
+```shell
+pip install svtb
+```
+
+or, in a consuming package's `pyproject.toml`, as a dev dependency:
+
+```toml
+[dependency-groups]
+dev = ["svtb", "pytest"]
+```
+
+Then point `tests/conftest.py`'s import path at the installed package instead of a local directory:
+
+```python
+import svtb
+sys.path.insert(0, str(Path(svtb.__file__).parent))
+```
+
+This makes `import fault` and `import magma as m` resolve to `svtb`'s subpackages as top-level modules,
+exactly as they would from a local `tests/support/` directory.
+
+## Licensing
+
+- `fault` is BSD-3-Clause, Copyright 2018 Leonard Truong; see `svtb/fault/LICENSE.txt`.
+- `magma` is MIT, Copyright (C) 2016 Stanford University; see `svtb/magma/LICENSE.txt`.
+- svtb itself is MIT; see `LICENSE`.
+
+## Running the tests
+
+```shell
+uv sync
+uv run pytest -q tests
+```
+
+`tests/test_tester.py` checks the generator on each simulator; `tests/fake_sim.py` stands in for Xcelium,
+Incisive, Vivado and VCS, since only iverilog and Verilator have run here.

svtb-0.1.0/svtb.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+svtb/__init__.py
+svtb.egg-info/PKG-INFO
+svtb.egg-info/SOURCES.txt
+svtb.egg-info/dependency_links.txt
+svtb.egg-info/top_level.txt
+svtb/fault/LICENSE.txt
+svtb/fault/__init__.py
+svtb/fault/subprocess_run.py
+svtb/fault/tester.py
+svtb/magma/LICENSE.txt
+svtb/magma/__init__.py
+tests/test_tester.py

svtb-0.1.0/svtb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

svtb-0.1.0/svtb.egg-info/top_level.txt

@@ -0,0 +1 @@
+svtb

svtb-0.1.0/tests/test_tester.py

@@ -0,0 +1,191 @@
+import json
+import os
+from pathlib import Path
+from shutil import which
+
+import numpy as np
+import pytest
+
+import fault
+import magma as m
+
+DUT_FILE = Path(__file__).resolve().parent / "dut.sv"
+FAKE_SIM = Path(__file__).resolve().parent / "fake_sim.py"
+# simulator name -> the executable fake_sim.py stands in for
+FAKES = {"xcelium": "xrun", "ncsim": "irun", "vivado": "vivado", "vcs": "vcs"}
+REAL = [s for s in ("iverilog", "verilator") if which(s)]
+
+
+@pytest.fixture(params=REAL + [f"fake-{s}" for s in FAKES])
+def simulator(request, tmp_path_factory, monkeypatch):
+    """A real simulator, or a commercial one, stood in for by fake_sim.py on PATH."""
+    name = request.param
+    if not name.startswith("fake-"):
+        return name
+    bindir = tmp_path_factory.mktemp("fakebin")
+    for exe in FAKES.values():
+        (bindir / exe).symlink_to(FAKE_SIM)
+    monkeypatch.setenv("PATH", f"{bindir}{os.pathsep}{os.environ['PATH']}")
+    return name.removeprefix("fake-")
+
+
+class dut(m.Circuit):  # noqa: N801 (mirrors legacy test style)
+    name = "dut"
+    io = m.IO(
+        a=fault.RealIn,
+        y=fault.RealOut,
+        d=m.In(m.Bits[8]),
+        q_comb=m.Out(m.Bits[8]),
+        q_reg=m.Out(m.Bits[8]),
+        clk=m.ClockIn,
+        early_finish=m.BitIn,
+    )
+
+
+def make_tester():
+    t = fault.Tester(dut, dut.clk)
+    t.zero_inputs()
+    t.eval()
+    return t
+
+
+def run(t, simulator, tmp_path, **kwargs):
+    t.compile_and_run(
+        target="system-verilog",
+        simulator=simulator,
+        ext_srcs=[DUT_FILE],
+        ext_model_file=True,
+        directory=tmp_path,
+        **kwargs,
+    )
+
+
+def test_correct_expects_pass(simulator, tmp_path):
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.poke(dut.d, 41)
+    t.eval()
+    t.expect(dut.y, 2.5, abs_tol=1e-9)
+    t.expect(dut.q_comb, 42)
+    t.expect(dut.q_reg, 0)
+    t.step(2)
+    t.expect(dut.q_reg, 41)
+    t.poke(dut.d, 255)
+    t.eval()
+    t.expect(dut.q_comb, 0)  # 8-bit wrap
+    y = t.get_value(dut.y)
+    q = t.get_value(dut.q_reg)
+    t.print("q_reg=%0d\n", dut.q_reg)
+    run(t, simulator, tmp_path)
+    assert y.value == pytest.approx(2.5)
+    assert q.value == 41
+
+
+def test_numpy_scalar_values(simulator, tmp_path):
+    t = make_tester()
+    t.poke(dut.a, np.float64(1.25))
+    t.eval()
+    t.expect(dut.y, np.float64(2.5), abs_tol=np.float64(1e-9))
+    t.expect(dut.y, np.float64(2.5))
+    run(t, simulator, tmp_path)
+
+
+def test_wrong_real_expect_fails(simulator, tmp_path, capsys):
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.eval()
+    t.expect(dut.y, 2.6, abs_tol=0.05)
+    with pytest.raises(AssertionError):
+        run(t, simulator, tmp_path)
+    assert "Failed on action=" in capsys.readouterr().out
+
+
+def test_wrong_digital_expect_fails(simulator, tmp_path, capsys):
+    t = make_tester()
+    t.poke(dut.d, 41)
+    t.eval()
+    t.expect(dut.q_comb, 41)
+    with pytest.raises(AssertionError):
+        run(t, simulator, tmp_path)
+    assert "Failed on action=" in capsys.readouterr().out
+
+
+def test_above_only_expect_passes(simulator, tmp_path):
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.eval()
+    t.expect(dut.y, None, above=2.0)  # y = 2.5
+    run(t, simulator, tmp_path)
+
+
+def test_above_only_expect_fails(simulator, tmp_path, capsys):
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.eval()
+    t.expect(dut.y, None, above=3.0)  # y = 2.5, not above 3.0
+    with pytest.raises(AssertionError):
+        run(t, simulator, tmp_path)
+    assert "Failed on action=" in capsys.readouterr().out
+
+
+def test_below_only_expect_passes(simulator, tmp_path):
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.eval()
+    t.expect(dut.y, None, below=3.0)  # y = 2.5
+    run(t, simulator, tmp_path)
+
+
+def test_below_only_expect_fails(simulator, tmp_path, capsys):
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.eval()
+    t.expect(dut.y, None, below=2.0)  # y = 2.5, not below 2.0
+    with pytest.raises(AssertionError):
+        run(t, simulator, tmp_path)
+    assert "Failed on action=" in capsys.readouterr().out
+
+
+def test_early_finish_fails(simulator, tmp_path):
+    t = make_tester()
+    t.poke(dut.early_finish, 1)
+    t.eval()
+    t.expect(dut.q_comb, 1)
+    with pytest.raises(AssertionError, match="did not reach"):
+        run(t, simulator, tmp_path)
+
+
+@pytest.mark.parametrize("simulator", [f"fake-{s}" for s in FAKES], indirect=True)
+def test_commands_follow_fault(simulator, tmp_path):
+    """The command line and Tcl each tool receives, as fault 3.0.43's SystemVerilogTarget writes them."""
+    t = make_tester()
+    t.poke(dut.a, 1.25)
+    t.eval()
+    t.expect(dut.y, 2.5, abs_tol=1e-9)
+    inc = tmp_path / "inc"
+    inc.mkdir()
+    run(t, simulator, tmp_path, inc_dirs=[inc], defines={"FOO": None, "BAR": 2})
+    argv = json.loads((tmp_path / "fake_sim.json").read_text())["argv"]
+    tb, tcl = str(tmp_path / "dut_tb.sv"), str(tmp_path / "dut_cmd.tcl")
+    srcs = [tb, str(DUT_FILE)]
+    if simulator in ("xcelium", "ncsim"):
+        assert argv == ["-top", "dut_tb", "-timescale", "1ns/1ns", "-input", tcl, *srcs,
+                        "-incdir", str(inc), "+define+FOO", "+define+BAR=2", "-notimingchecks"]
+        assert Path(tcl).read_text() == "run\nassertion -summary -final\nquit"
+    elif simulator == "vivado":
+        assert argv == ["-mode", "batch", "-source", tcl, "-nolog", "-nojournal"]
+        files = f"{{{tb}}} {{{DUT_FILE}}}"
+        assert Path(tcl).read_text().splitlines() == [
+            "create_project -force {project} {project}",
+            f"add_files [list {files}]",
+            f"set_property file_type SystemVerilog [get_files [list {files}]]",
+            f"set_property include_dirs [list {{{inc}}}] [get_fileset sim_1]",
+            "set_property -name verilog_define -value [list {FOO} {BAR=2}] -objects [get_fileset sim_1]",
+            "set_property -name top -value {dut_tb} -objects [get_fileset sim_1]",
+            "set_property -name xsim.simulate.runtime -value -all -objects [get_fileset sim_1]",
+            "launch_simulation",
+        ]
+    else:
+        assert argv == ["-timescale=1ns/1ns", *srcs, f"+incdir+{inc}", "+define+FOO", "+define+BAR=2",
+                        "-sverilog", "-full64", "+v2k", "-LDFLAGS", "-Wl,--no-as-needed",
+                        "-top", "dut_tb"]