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

vunit_python_bridge/__init__.py

@@ -0,0 +1,92 @@
+# 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
+
+
+"""
+The VUnit package making Python callable from VHDL.
+
+``vu.add_package("vunit-python-bridge", allow_setup=True)`` compiles
+``python_pkg``/``python_context`` into the ``python_bridge`` library and sets up the foreign
+language interface implementing them for the selected simulator:
+
+* NVC, GHDL (VHPIDIRECT) and Questa/ModelSim (FLI) are served by the VUnit Python bridge, a
+  small C library (native/*.c) embedding CPython in the simulator process.
+* Riviera-PRO/Active-HDL are served by a VHPI application built with the simulator's own
+  compiler driver.
+
+Modules:
+
+* bridge: setup of the bridge, its configuration and its generated VHDL.
+* native_library: compiles and caches the library on Linux and macOS, selects the prebuilt
+  DLL on Windows.
+* foreign_application: builds the VHPI application.
+* simulator_hooks: makes NVC and GHDL find the library.
+* runtime: runs inside the simulator's embedded interpreter.
+"""
+
+from pathlib import Path
+
+VHDL_PATH = Path(__file__).parent.resolve() / "hdl" / "src"
+
+# The foreign language interface implementing the package for a simulator. VUnit says which
+# simulator was selected, the package says how it is served: NVC and GHDL both go through
+# VHPIDIRECT but bind the library differently, Questa/ModelSim goes through the FLI and
+# Riviera-PRO/Active-HDL through a VHPI application of their own.
+FOREIGN_LANGUAGE_INTERFACES = {
+    "nvc": "VHPIDIRECT_NVC",
+    "ghdl": "VHPIDIRECT_GHDL",
+    "modelsim": "FLI",
+    "rivierapro": "VHPI",
+    "activehdl": "VHPI",
+}
+
+# The simulators of the table, named as a user knows them
+SUPPORTED_SIMULATORS = "NVC, GHDL, Questa/ModelSim, Riviera-PRO or Active-HDL"
+
+
+def setup(context):
+    """
+    Complete the addition of the package.
+
+    ``vunit_pkg.toml`` lists the sources both variants of the package share, this adds the
+    foreign language interface of the selected simulator: the VHPI application for
+    Riviera-PRO/Active-HDL, the VUnit Python bridge for everyone else.
+    """
+    # pylint: disable=import-outside-toplevel
+    from .bridge import setup as setup_bridge
+    from .foreign_application import setup_vhpi_application
+    from . import simulator_hooks
+
+    simulator_name = context.simulator_name
+    if simulator_name is None:
+        raise RuntimeError(
+            f"The vunit-python-bridge package requires {SUPPORTED_SIMULATORS} but no simulator was found"
+        )
+
+    interface = FOREIGN_LANGUAGE_INTERFACES.get(simulator_name)
+    if interface is None:
+        raise RuntimeError(
+            f"The vunit-python-bridge package requires {SUPPORTED_SIMULATORS}, "
+            f"it has no foreign language interface for {simulator_name}"
+        )
+
+    if interface == "VHPI":
+        # Riviera-PRO/Active-HDL, the simulators served by the VHPI application
+        context.add_source_files(context.library.name, [VHDL_PATH / "python_pkg_vhpi.vhd"])
+        setup_vhpi_application(context.output_path, simulator_name, context.simulator_prefix)
+        return
+
+    bridge = setup_bridge(
+        context.output_path,
+        context.run_script_path,
+        simulator_name,
+        context.simulator_prefix,
+        context.simulator_backend,
+    )
+
+    context.add_source_files(context.library.name, list(bridge.vhdl_files))
+
+    simulator_hooks.register(context, bridge)

vunit_python_bridge/bridge.py

@@ -0,0 +1,171 @@
+# 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
+
+
+"""
+Setup of the Python bridge of a project: native library, configuration and generated VHDL.
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+from typing import List, NamedTuple, Optional
+
+from .native_library import (
+    PACKAGE_PATH,
+    PythonBridgeError,
+    check_python_build,
+    check_windows_64bit_simulator,
+    prepare_library,
+    windows_python_dll,
+)
+
+RUNTIME_SOURCE = PACKAGE_PATH / "runtime.py"
+VHDL_SOURCE_PATH = PACKAGE_PATH / "hdl" / "src"
+BRIDGE_PACKAGE_TEMPLATE = VHDL_SOURCE_PATH / "python_bridge_pkg.vhd.in"
+CONFIG_FILE_NAME = "vunit_python_bridge.cfg"
+
+# The simulators the bridge serves, reaching it through VHPIDIRECT and through the FLI.
+# The rest of the simulators of the package are served by the VHPI application.
+FLI_SIMULATORS = ("modelsim",)
+BRIDGE_SIMULATORS = ("nvc", "ghdl") + FLI_SIMULATORS
+
+# GHDL backends that link the design ahead of time. For these the library
+# token in the VHPIDIRECT attribute is passed to the linker instead of being
+# dlopen()ed at run time.
+GHDL_LINKING_BACKENDS = ("llvm", "gcc")
+
+# {foreign:<entry point>} placeholder of the bridge package template
+FOREIGN_PATTERN = re.compile(r"\{foreign:(\w+)\}")
+# The subprogram declarations of the template, whose bodies are generated
+SUBPROGRAM_PATTERN = re.compile(r"^  (impure function|procedure) (\w+)(\([^)]*\))?( return \w+)?;", re.MULTILINE)
+
+
+class PythonBridge(NamedTuple):
+    """
+    A prepared bridge: the native library and the generated VHDL.
+    """
+
+    library_file: Path
+    vhdl_files: List[Path]
+
+
+def setup(
+    output_path,
+    run_script_path: Optional[Path],
+    simulator_name: Optional[str] = None,
+    simulator_prefix: Optional[str] = None,
+    simulator_backend: Optional[str] = None,
+) -> PythonBridge:
+    """
+    Prepare the Python bridge for a project. Called by the package setup function.
+
+    :param run_script_path: The run script or None. The runtime puts its directory, or the current
+                            directory without a run script, first on sys.path, like python does.
+    :param simulator_name: The name of the selected simulator, None for no simulator.
+    :param simulator_prefix: The path its executables were found in.
+    :param simulator_backend: How the installation found there was built, which for GHDL
+                              is the code generator deciding how the library is bound.
+    :returns: The bridge. Its vhdl_files are to be added to the package library.
+    """
+    if simulator_name is not None and simulator_name not in BRIDGE_SIMULATORS:
+        raise PythonBridgeError(
+            f"The vunit-python-bridge package requires NVC, GHDL or Questa/ModelSim, "
+            f"it is not supported for {simulator_name}"
+        )
+
+    check_python_build()
+    check_windows_64bit_simulator(simulator_name, simulator_prefix)
+
+    is_fli = simulator_name in FLI_SIMULATORS
+    if is_fli and simulator_prefix is None:
+        raise PythonBridgeError(
+            f"The FLI variant of the bridge is built against the {simulator_name} installation, but it was not found"
+        )
+
+    root = Path(output_path) / "python_bridge"
+    library_file = prepare_library(root, Path(simulator_prefix) if is_fli else None)
+    run_script_dir = str(Path.cwd() if run_script_path is None else Path(run_script_path).resolve().parent)
+    _write_if_changed(library_file.parent / CONFIG_FILE_NAME, _config_text(run_script_dir))
+
+    # The foreign attribute string of an entry point: the name of its wrapper in native/fli.c
+    # and the library, by absolute path since Questa accepts it, for the FLI; the VHPIDIRECT
+    # library token and the entry point itself for NVC and GHDL.
+    foreign = (
+        f"fli_{{entry_point}} {library_file!s}"
+        if is_fli
+        else f"VHPIDIRECT {_vhpidirect_token(simulator_name, simulator_backend, library_file)} {{entry_point}}"
+    )
+    bridge_package = root / "vhdl" / "python_bridge_pkg.vhd"
+    _write_if_changed(bridge_package, _render_bridge_package(foreign))
+
+    return PythonBridge(
+        library_file,
+        [
+            bridge_package,
+            VHDL_SOURCE_PATH / "python_ffi_pkg_bridge.vhd",
+        ],
+    )
+
+
+def _vhpidirect_token(simulator_name, simulator_backend: Optional[str], library_file: Path) -> str:
+    """
+    The library token of the VHPIDIRECT attributes: the file name the simulator dlopen()s,
+    or the linker flag of the GHDL backends that link the design ahead of time.
+    """
+    if simulator_name == "ghdl" and simulator_backend in GHDL_LINKING_BACKENDS:
+        return "-lvunit_python_bridge"
+    return library_file.name
+
+
+def _render_bridge_package(foreign: str) -> str:
+    """
+    The generated python_bridge_pkg.vhd: the declarations of the template with the foreign
+    attribute of every subprogram, and a body reporting a failure for each of them since the
+    bodies are replaced by the foreign implementations and never executed.
+    """
+    template = BRIDGE_PACKAGE_TEMPLATE.read_text(encoding="utf-8")
+    declarations = FOREIGN_PATTERN.sub(lambda match: foreign.format(entry_point=match.group(1)), template)
+    stubs = []
+    for kind, name, parameters, result in SUBPROGRAM_PATTERN.findall(declarations):
+        stubs.append(f"  {kind} {name}{parameters}{result} is\n  begin")
+        stubs.append(f'    report "VUnit Python bridge: foreign subprogram {name} is not bound" severity failure;')
+        if result:
+            stubs.append(f"    return {'0.0' if result.endswith('real') else '1'};")
+        stubs.append("  end;\n")
+    return declarations + "\npackage body python_bridge_pkg is\n" + "\n".join(stubs) + "end package body;\n"
+
+
+def _config_text(run_script_dir: str) -> str:
+    """
+    Content of the configuration file read by the bridge library at run time.
+    """
+    lines = {
+        "executable": sys.executable,
+        "prefix": sys.prefix,
+        "runtime": str(RUNTIME_SOURCE),
+        "run_script_dir": run_script_dir,
+    }
+    if sys.platform == "win32":
+        lines["python_dll"] = windows_python_dll()
+    for key, value in lines.items():
+        if "\n" in value or "\r" in value:
+            raise PythonBridgeError(f"VHDL Python support cannot handle line breaks in the path {value!r}")
+    return "".join(f"{key}={value}\n" for key, value in lines.items())
+
+
+def _write_if_changed(path: Path, text: str) -> None:
+    """
+    Write a file unless it already has the given content, keeping timestamps stable.
+    """
+    data = text.encode("utf-8")
+    if path.is_file() and path.read_bytes() == data:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + f".{os.getpid()}.tmp")
+    tmp.write_bytes(data)
+    os.replace(tmp, path)

vunit_python_bridge/foreign_application.py

@@ -0,0 +1,90 @@
+# 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
+
+"""
+Building the foreign language application implementing ``python_pkg``/``python_context``
+for the simulators the VUnit Python bridge does not serve.
+
+``setup_vhpi_application`` is called by the setup function of the package for
+Riviera-PRO/Active-HDL (VHPI). The application is built under the output path on first use and
+rebuilt when its sources, the Python running VUnit or the simulator change.
+"""
+
+from pathlib import Path
+import os
+import sys
+import hashlib
+
+from .native_library import (
+    add_python_dll_to_path,
+    check_windows_64bit_simulator,
+    compile_library,
+    python_dev_paths,
+    windows_gcc,
+)
+
+SRC_PATH = Path(__file__).parent.resolve() / "native" / "vhpi"
+
+
+def setup_vhpi_application(output_path, simulator_name, simulator_prefix):
+    """
+    Build the VHPI application for Riviera-PRO/Active-HDL under the output path, unless the one
+    already there was built from the same sources for the same Python and simulator.
+
+    :param simulator_prefix: The path the executables of the simulator were found in, which is
+                             where its ccomp compiler driver is.
+    """
+    if simulator_prefix is None:
+        raise RuntimeError(f"The VHPI application is built with the ccomp of {simulator_name}, but it was not found")
+
+    check_windows_64bit_simulator(simulator_name, simulator_prefix)
+    target = Path(output_path) / simulator_name / "libraries" / "python.dll"
+    sources = [SRC_PATH / "python_pkg_vhpi.c", SRC_PATH / "python_pkg.c"]
+    simulator_prefix = Path(simulator_prefix).resolve()
+    fingerprint = _fingerprint(sources, simulator_prefix)
+    fingerprint_file = target.with_suffix(target.suffix + ".fingerprint")
+    if target.exists() and fingerprint_file.exists() and fingerprint_file.read_text(encoding="utf-8") == fingerprint:
+        return
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    fingerprint_file.unlink(missing_ok=True)
+    _build_vhpi(target, sources, simulator_prefix)
+    fingerprint_file.write_text(fingerprint, encoding="utf-8")
+
+
+def _fingerprint(sources, simulator_prefix):
+    """
+    Everything the built application depends on: the C sources and headers, the Python that is
+    embedded and the simulator whose headers and libraries are used.
+    """
+    digest = hashlib.sha256()
+    for path in sorted(sources) + sorted(SRC_PATH.glob("*.h")):
+        digest.update(path.name.encode("utf-8") + b"\0" + path.read_bytes() + b"\0")
+    for item in [sys.executable, sys.prefix, sys.version, sys.platform, str(simulator_prefix)]:
+        digest.update(item.encode("utf-8") + b"\0")
+    return digest.hexdigest()
+
+
+def _build_vhpi(target, sources, simulator_prefix):
+    """
+    Compile the VHPI application with the ccomp compiler driver of Riviera-PRO/Active-HDL.
+    """
+    python_include, python_libs = python_dev_paths()
+    ccomp = simulator_prefix / ("ccomp.exe" if sys.platform == "win32" else "ccomp")
+    env = None
+    if sys.platform == "win32":
+        add_python_dll_to_path()
+        # Riviera-PRO bundles a MinGW gcc under <installation>/mingw, other installations may not.
+        # ponytail: untested (no Aldec license), assumes ccomp finds gcc on PATH when none is bundled
+        gcc = windows_gcc(simulator_prefix)
+        if gcc is not None:
+            env = dict(os.environ, PATH=os.pathsep.join([str(Path(gcc[0]).parent), os.environ.get("PATH", "")]))
+    # One argument per item: subprocess quotes them, quotes added here would reach ccomp literally
+    args = [str(ccomp), "-vhpi", "-dbg", "-verbose", "-o", str(target)]
+    args += ["-l", f"python{sys.version_info[0]}{sys.version_info[1]}", "-l", "python3", "-l", "_tkinter"]
+    args += ["-I", str(python_include), "-I", str(SRC_PATH), "-L", str(python_libs)]
+    args += [str(path) for path in sources]
+    compile_library(args, target, target, env)

vunit_python_bridge/hdl/src/python_bridge_pkg.vhd.in

@@ -0,0 +1,91 @@
+-- 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
+--
+-- PRIVATE foreign subprograms of the VUnit Python bridge (src/vunit_python_bridge/native).
+--
+-- This file is a template. The setup function of the package substitutes every
+-- {foreign:<entry point>} placeholder with the foreign attribute string of the
+-- selected simulator -- "VHPIDIRECT <library> <entry point>" for NVC and GHDL,
+-- "fli_<entry point> <library>" for the FLI of Questa/ModelSim -- and adds the
+-- result to the python_bridge library, together with a generated package body
+-- whose subprograms are never executed. The public API is
+-- python_pkg/python_ffi_pkg, which is implemented on top of this package.
+--
+-- Only scalars and constrained arrays cross the foreign interface since their
+-- ABI is identical for NVC and GHDL on all platforms and is translated to the
+-- FLI parameter passing conventions by native/fli.c.
+
+package python_bridge_pkg is
+  constant chunk_length : positive := 1024;
+  subtype string_chunk_t is string(1 to chunk_length);
+  subtype integer_chunk_t is integer_vector(0 to chunk_length - 1);
+  subtype real_chunk_t is real_vector(0 to chunk_length - 1);
+
+  -- Start the interpreter. Idempotent.
+  impure function vpy_setup return integer;
+  attribute foreign of vpy_setup : function is "{foreign:vpy_setup}";
+
+  -- Flush Python's streams and drop the last result and the staged values.
+  -- The interpreter is not finalized: later operations keep working.
+  impure function vpy_cleanup return integer;
+  attribute foreign of vpy_cleanup : function is "{foreign:vpy_cleanup}";
+
+  impure function vpy_buffer_clear return integer;
+  attribute foreign of vpy_buffer_clear : function is "{foreign:vpy_buffer_clear}";
+
+  impure function vpy_buffer_append(chunk : string_chunk_t; length : integer) return integer;
+  attribute foreign of vpy_buffer_append : function is "{foreign:vpy_buffer_append}";
+
+  -- Start an operation in the session named by the buffer ("default" is __main__).
+  impure function vpy_begin return integer;
+  attribute foreign of vpy_begin : function is "{foreign:vpy_begin}";
+
+  -- Execute the buffer as Python source (is_file = 0) or as a file name (is_file = 1).
+  impure function vpy_execute(is_file : integer) return integer;
+  attribute foreign of vpy_execute : function is "{foreign:vpy_execute}";
+
+  -- Evaluate the buffer as a Python expression and convert the value to the
+  -- VHDL type given by kind. width is the length of a std_ulogic_vector,
+  -- signed or unsigned result, -1 when it is not known.
+  impure function vpy_eval(kind, width : integer) return integer;
+  attribute foreign of vpy_eval : function is "{foreign:vpy_eval}";
+
+  impure function vpy_push_array(length, width, height, depth, bit_width, is_signed : integer) return integer;
+  attribute foreign of vpy_push_array : function is "{foreign:vpy_push_array}";
+
+  impure function vpy_array_write(chunk : integer_chunk_t; length : integer) return integer;
+  attribute foreign of vpy_array_write : function is "{foreign:vpy_array_write}";
+
+  -- Stage the pushed array and return its id (>= 1), -1 on error. Python
+  -- source code refers to the value as __vunit__.staged(<id>).
+  impure function vpy_stage return integer;
+  attribute foreign of vpy_stage : function is "{foreign:vpy_stage}";
+
+  impure function vpy_result_integer return integer;
+  attribute foreign of vpy_result_integer : function is "{foreign:vpy_result_integer}";
+
+  impure function vpy_result_real return real;
+  attribute foreign of vpy_result_real : function is "{foreign:vpy_result_real}";
+
+  impure function vpy_result_meta(idx : integer) return integer;
+  attribute foreign of vpy_result_meta : function is "{foreign:vpy_result_meta}";
+
+  impure function vpy_error_length return integer;
+  attribute foreign of vpy_error_length : function is "{foreign:vpy_error_length}";
+
+  procedure vpy_result_read_string(chunk : out string_chunk_t; offset, length : integer);
+  attribute foreign of vpy_result_read_string : procedure is "{foreign:vpy_result_read_string}";
+
+  procedure vpy_result_read_integers(chunk : out integer_chunk_t; offset, length : integer);
+  attribute foreign of vpy_result_read_integers : procedure is "{foreign:vpy_result_read_integers}";
+
+  procedure vpy_result_read_reals(chunk : out real_chunk_t; offset, length : integer);
+  attribute foreign of vpy_result_read_reals : procedure is "{foreign:vpy_result_read_reals}";
+
+  procedure vpy_error_read(chunk : out string_chunk_t; offset, length : integer);
+  attribute foreign of vpy_error_read : procedure is "{foreign:vpy_error_read}";
+end package;
+

vunit_python_bridge/hdl/src/python_context.vhd

@@ -0,0 +1,13 @@
+-- This package provides a dictionary types and operations
+--
+-- 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
+
+context python_context is
+  library python_bridge;
+  use python_bridge.python_pkg.all;
+  use python_bridge.python_ffi_pkg.all;
+end context;