vunit-python-bridge 0.1.0__py3-none-any.whl

vunit_python_bridge/simulator_hooks.py

@@ -0,0 +1,141 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com
+
+
+"""
+Simulator hooks making the simulator load the bridge library and its dependencies.
+
+They are registered with the package context by the setup function of the package, one set
+per simulator, and are only called for the project they were registered for.
+
+Questa needs no help finding the library itself: the FLI attributes of the generated
+python_bridge_pkg.vhd name it by absolute path.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .bridge import GHDL_LINKING_BACKENDS, PythonBridge
+
+# The vsim flag keeping the runtime libraries Questa bundles out of the dynamic library
+# search path, and the help category listing every vsim flag.
+NO_AUTO_LD_LIBRARY_PATH = "-noautoldlibpath"
+VSIM_HELP_ARGUMENTS = ("-help", "all")
+
+
+def register(context, bridge: PythonBridge) -> None:
+    """
+    Register the hooks of every simulator the bridge serves with the package context.
+    """
+    context.register_simulator_hooks("nvc", run_flags=_nvc_run_flags(bridge))
+    context.register_simulator_hooks(
+        "ghdl",
+        elab_flags=_ghdl_elab_flags(bridge),
+        run_env=_ghdl_run_env(bridge),
+    )
+    context.register_simulator_hooks("modelsim", process_flags=_modelsim_process_flags())
+
+
+def _nvc_run_flags(bridge: PythonBridge):
+    """
+    NVC run (-r) flags loading the bridge.
+    """
+
+    def hook(simulator_interface) -> List[str]:  # pylint: disable=unused-argument
+        return [f"--load={bridge.library_file!s}"]
+
+    return hook
+
+
+def _ghdl_elab_flags(bridge: PythonBridge):
+    """
+    GHDL elaboration flags. Only the backends linking the design ahead of time need them,
+    the others load the bridge at run time and are served by the run environment.
+    """
+
+    def hook(simulator_interface) -> List[str]:
+        if simulator_interface.backend not in GHDL_LINKING_BACKENDS:
+            return []
+        return [f"-Wl,-L{bridge.library_file.parent!s}"]
+
+    return hook
+
+
+def _ghdl_run_env(bridge: PythonBridge):
+    """
+    Add the bridge directory to the dynamic library search path of a GHDL simulation.
+    """
+
+    def hook(simulator_interface, env: Dict[str, str]) -> Dict[str, str]:  # pylint: disable=unused-argument
+        variable = {"win32": "PATH", "darwin": "DYLD_LIBRARY_PATH"}.get(sys.platform, "LD_LIBRARY_PATH")
+        env = dict(env)
+        env[variable] = os.pathsep.join(
+            item for item in (str(bridge.library_file.parent), env.get(variable, "")) if item
+        )
+        return env
+
+    return hook
+
+
+def _modelsim_process_flags():
+    """
+    Flags for the vsim process VUnit starts for a Questa/ModelSim simulation.
+
+    Questa/ModelSim puts the directory of the C++ runtime it bundles first in
+    LD_LIBRARY_PATH. That runtime is regularly older than the one the Python extension
+    modules of the environment (NumPy, used for integer_array_t values) were built
+    against, and they then fail to load in the embedded interpreter. -noautoldlibpath
+    turns that off, leaving the C++ runtime of the system to be found as usual.
+
+    The flag is set up when the process starts, so it is only honoured on the command line
+    of the vsim process itself, not on the vsim command of the do-file VUnit generates.
+
+    Only relevant on Linux, where LD_LIBRARY_PATH decides this, and only given to a vsim
+    that knows the flag.
+    """
+    known: Dict[Optional[str], bool] = {}
+
+    def hook(simulator_interface) -> List[str]:
+        if not sys.platform.startswith("linux"):
+            return []
+
+        prefix = simulator_interface.prefix
+        if prefix not in known:
+            known[prefix] = _vsim_knows_flag(prefix, simulator_interface)
+        if not known[prefix]:
+            return []
+
+        return [NO_AUTO_LD_LIBRARY_PATH]
+
+    return hook
+
+
+def _vsim_knows_flag(prefix: Optional[str], simulator_interface) -> bool:
+    """
+    Whether the vsim of an installation lists -noautoldlibpath among its options.
+
+    Asking vsim rather than assuming keeps a version without the flag from failing to
+    start at all. An installation that cannot be asked is taken to know it, since the
+    flag is what makes the bridge usable there.
+    """
+    if prefix is None:
+        return True
+
+    try:
+        output = subprocess.run(
+            [str(Path(prefix) / "vsim"), *VSIM_HELP_ARGUMENTS],
+            check=True,
+            capture_output=True,
+            text=True,
+            env=simulator_interface.get_env(),
+        ).stdout
+    except (OSError, subprocess.SubprocessError):
+        return True
+
+    return NO_AUTO_LD_LIBRARY_PATH in output.split()

vunit_python_bridge/vunit_pkg.toml

@@ -0,0 +1,17 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this file,
+# You can obtain one at http://mozilla.org/MPL/2.0/.
+#
+# Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com
+
+[package]
+# The VUnit adding packages and simulator hooks, VUnit/vunit#1221
+requires-vunit = ">=5.0.0.dev12"
+requires-vhdl = ">=2008"
+library = "python_bridge"
+setup = "vunit_python_bridge:setup"
+
+# The foreign language interface implementing python_ffi_pkg is selected by the
+# setup function since the choice depends on the simulator.
+[[package.sources]]
+include = ["hdl/src/python_context.vhd", "hdl/src/python_pkg.vhd"]

vunit_python_bridge-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: vunit-python-bridge
+Version: 0.1.0
+Summary: A VUnit package making Python callable from VHDL.
+Author-email: Lars Asplund <lars.anders.asplund@gmail.com>
+License-Expression: MPL-2.0
+Project-URL: homepage, https://github.com/VUnit/vunit-python-bridge
+Keywords: vunit,vunitpkg,verification,vhdl,fpga,asic,python,vhpi,vhpidirect,fli
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: vunit_hdl>=5.0.0.dev12
+Dynamic: license-file
+
+# vunit-python-bridge
+
+A VUnit package making Python callable from VHDL.
+
+## Overview
+
+vunit-python-bridge embeds a Python interpreter in the simulator process so that a VHDL testbench
+can execute Python code and call Python functions — a NumPy reference model, a constraint solver, a
+plot of what the design just produced — without leaving the simulation. The VHDL API,
+`python_pkg`/`python_context`, is compiled into the `python_bridge` library and is implemented for
+the selected simulator by a foreign language interface the package builds itself: a small C library
+called through VHPIDIRECT (NVC, GHDL) or the FLI (Questa/ModelSim), or a VHPI application built with
+the simulator's own compiler driver (Riviera-PRO/Active-HDL). Values cross the interface with their
+VHDL types: `integer`, `real`, `string`, `boolean`, `std_ulogic`, `unsigned`/`signed`, the vector
+types, and `integer_array_t` as a NumPy array.
+
+## Installation
+
+```bash
+pip install vunit-python-bridge
+```
+
+## Basic Example
+
+The run script adds the package after the VUnit builtins:
+
+```python
+from vunit import VUnit
+
+vu = VUnit.from_argv()
+vu.add_vhdl_builtins()
+vu.add_package("vunit-python-bridge", allow_setup=True)
+
+lib = vu.add_library("lib")
+lib.add_source_files("*.vhd")
+
+vu.main()
+```
+
+`allow_setup=True` is required because, when added, the package builds its native library and
+registers simulator options as part of its setup function, which VUnit only runs when the project
+allows it.
+
+The testbench gets the API from the `python_context` context of the `python_bridge` library:
+
+```vhdl
+library vunit_lib;
+context vunit_lib.vunit_context;
+
+library python_bridge;
+context python_bridge.python_context;
+
+...
+
+exec("import numpy as np");
+exec("def gain(x): return [2 * v for v in x]");
+
+check_equal(eval_integer("int(np.sum([1, 2, 3]))"), 6);
+check_equal(eval_string("'-'.join(['a', 'b'])"), string'("a-b"));
+check(call_integer_vector("gain", arg(integer_vector'(1, 2))) = integer_vector'(2, 4));
+```
+
+## Supported Simulators
+
+| Simulator | Interface | Status |
+| --- | --- | --- |
+| NVC | VHPIDIRECT | Tested on Linux, macOS and Windows |
+| GHDL (mcode, llvm-jit, llvm, gcc) | VHPIDIRECT | Tested on Linux, macOS and Windows |
+| Questa/ModelSim | FLI | Tested manually on Linux; the Windows build is untested |
+| Riviera-PRO, Active-HDL | VHPI | Untested; a subset of the API, see the documentation |
+
+## Requirements
+
+- VUnit 5.0.0.dev12 or later (`vunit_hdl` on PyPI), which pip installs with the package.
+- VHDL-2008 or later.
+- CPython 3.10 or later, standard (GIL) build, with a shared `libpython` (`--enable-shared`), which
+  is what distribution Pythons, `actions/setup-python`, `uv` and `pyenv` provide by default.
+- Linux and macOS: a C compiler (`cc`, `gcc` or `clang`, or `CC`) and the Python development headers
+  (for example the `python3-dev` package). The bridge library is compiled on first use and cached
+  under the VUnit output path.
+- Windows: a 64-bit CPython from python.org (or compatible). The package ships prebuilt DLLs
+  for NVC and GHDL. Questa builds its FLI library, and NVC and GHDL their library when the DLLs
+  are missing, with a MinGW-w64 gcc: `CC`, the one bundled with the simulator, or `gcc` on `PATH`.
+
+The simulator runs Python in the same environment as VUnit itself, including an active virtual
+environment and its installed packages.
+
+## Documentation
+
+The user guide is in [docs/user_guide.rst](docs/user_guide.rst): sessions, `exec`, `eval`, `call`
+and its argument forms, `exec_file`, `import_run_script`, the type mapping, `integer_array_t` and
+NumPy, error reporting, and how the bridge works. A complete example covering all three simulator
+families is in [examples/embedded_python](examples/embedded_python).
+
+## License
+
+Mozilla Public License, v. 2.0, like VUnit. See [LICENSE](LICENSE).

vunit_python_bridge-0.1.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+vunit_python_bridge/__init__.py,sha256=wCafoKlOFCqPNqweq_KnnFvaH5vzK5yP4_DtWe8lZD0,3567
+vunit_python_bridge/bridge.py,sha256=zrSRD6DdkS3OInFnCKTn68Bsgde3zPH1tgAdIxq3Aqk,6973
+vunit_python_bridge/foreign_application.py,sha256=hrEjGmvwmOmSS2fEZfkxd7U5RL1n4e06g_HmqEM4_jg,4103
+vunit_python_bridge/native_library.py,sha256=J648lPhKAB7g10A_Huf5OIK3mIqoJIKB9nn_Mx1bkZ0,19336
+vunit_python_bridge/runtime.py,sha256=oMH6ruA2aGnYrallcf6PNzswZYCg4Y7RsVD81eqgysk,24041
+vunit_python_bridge/simulator_hooks.py,sha256=1GPcsWN16n3RHAx9UhqEA9pkmXrNRbUjNNPUiUhDOV4,4875
+vunit_python_bridge/vunit_pkg.toml,sha256=sFyO6kIgOIk-p0-5Y1_4DHnopDmjGRXZAnuy1W6RFwQ,696
+vunit_python_bridge/bin/vunit_python_bridge-cp310-win_amd64.dll,sha256=EHaeICd6cOy9uPIPrIjHxt1tZbOnyLJH-5Ky3bWtdMg,25600
+vunit_python_bridge/bin/vunit_python_bridge-cp311-win_amd64.dll,sha256=9hY0qQDgrENjjhg3WRj4iL9BOPmiv-_513f1uYEhMuY,25600
+vunit_python_bridge/bin/vunit_python_bridge-cp312-win_amd64.dll,sha256=nsyzWNzFfFeNiMUHzMadI0TXMUlSyQgp1KI_NjqXseE,25600
+vunit_python_bridge/bin/vunit_python_bridge-cp313-win_amd64.dll,sha256=w1jKZ2ccI0JL_CX9S9ek5x6A_3E9Pxt5eh1G37Ju3o8,25600
+vunit_python_bridge/bin/vunit_python_bridge-cp314-win_amd64.dll,sha256=Pe7NHoPeH1J8vdtUftaP6WOeBQ3mHVi0QiFDEt_whE8,25600
+vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in,sha256=0Nqy9w2S5PuJVEYhgoiyUi9I3n_kz12iXmCYHA8eEBM,4811
+vunit_python_bridge/hdl/src/python_context.vhd,sha256=zOJoo6Wu2vrzS3TF_pY36O_a6h8iRC5f3SAKwhiKeAw,479
+vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd,sha256=EBhhxB4dWxbI4bE3sQjcaVygiOiyrmXKHC6tjcnTmtI,19284
+vunit_python_bridge/hdl/src/python_pkg.vhd,sha256=5XvCeEOnZVDPLizVdjWTpS09oioHXq5e0c7v1AaaslI,40950
+vunit_python_bridge/hdl/src/python_pkg_vhpi.vhd,sha256=leTiWcaMW24_WdaFWE8FvWhJzQbcfcL2KvSQEUG47fQ,10304
+vunit_python_bridge/hdl/tools/generate_python_pkg.py,sha256=PifvodL_EgkaTR_AaA-tYvu6e29oNq-F8PFuoOoz-CE,13017
+vunit_python_bridge/hdl/tools/python_pkg.vhd.in,sha256=fHS5gWEorAlsrNrF7iMUQWsVlzkBbIXhOYQgLujbHSI,28528
+vunit_python_bridge/native/arguments.c,sha256=Bov0RZYtUehCuf3nHyxjMX4XUU2DtQ1IqqiyrO8UYQc,5774
+vunit_python_bridge/native/bridge.h,sha256=uUYU3mk6wUC-M-HdXqjsaM5_NijbCVjxFR-kxOjI3B0,4886
+vunit_python_bridge/native/config.c,sha256=_nftjKmM-qYirEx6PJAij5a6Ax6y6NyfAfl4tpMzXpk,5659
+vunit_python_bridge/native/error.c,sha256=ImotvdMLhJQQ-znUJoltJraBuMTB13GUfA1p6LtZplE,3366
+vunit_python_bridge/native/fli.c,sha256=Half7fS8BA9X3n1jjpRAsUOoNDWEqhUT4WVfn_d-WFY,4613
+vunit_python_bridge/native/interpreter.c,sha256=Ey6S6NZdCGs32G43jnOnAoS04RhSwJZoGGFGlaG0CBw,8222
+vunit_python_bridge/native/operations.c,sha256=8hDC4iHcYOcy9Ijh564OKEx80eoJ7GDnlbPJX4hII1g,7271
+vunit_python_bridge/native/vhpi/python_pkg.c,sha256=7HzcF2upH47PHdkVZw_gWKvmrbpg5jtQI3jPwgqDHCk,3761
+vunit_python_bridge/native/vhpi/python_pkg.h,sha256=_xg-efdoRZbSn0pOlt_YexPqv2-TQOn5o8AvalJ7tjg,1210
+vunit_python_bridge/native/vhpi/python_pkg_vhpi.c,sha256=jkDpH9QioH2LJE9b3FTeCZxijXNjYTG-_WGVpgh6inQ,11474
+vunit_python_bridge-0.1.0.dist-info/licenses/LICENSE,sha256=Pz2eACSxkhsGfW9_iN60pgy-enjnbGTj8df8O3ebnQQ,16726
+vunit_python_bridge-0.1.0.dist-info/METADATA,sha256=6xxfUs7i9vvLXswfJPp80c9z1vuyUmG_ykNWaTQrA-k,4563
+vunit_python_bridge-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+vunit_python_bridge-0.1.0.dist-info/top_level.txt,sha256=abj4noIVQMKaPr2m8kPPxH6RSYadeXKc0Ho2uilmlEg,20
+vunit_python_bridge-0.1.0.dist-info/RECORD,,

vunit_python_bridge-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+