vunit-python-bridge 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

vunit_python_bridge/__init__.py

@@ -12,18 +12,17 @@ The VUnit package making Python callable from VHDL.
 ``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.
+the VUnit Python bridge, a small C library (native/*.c) embedding CPython in the simulator
+process, called through VHPIDIRECT (NVC, GHDL), the FLI (Questa/ModelSim) or VHPI
+(Riviera-PRO). A simulator provided by a VUnit package names its interface itself, see
+bridge.bridge_simulators.
 
 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.
+* simulator_hooks: makes the simulators find the library and its configuration.
 * runtime: runs inside the simulator's embedded interpreter.
 * file_base: the base directory of ``base_path``, ``set_relative_file_base``.
 
@@ -42,64 +41,39 @@ from .file_base import set_relative_file_base as set_relative_file_base
 
 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.
+    ``vunit_pkg.toml`` lists the sources of the package, this adds the bridge for the
+    foreign language interface of the selected simulator.
     """
     # pylint: disable=import-outside-toplevel
-    from .bridge import setup as setup_bridge
-    from .foreign_application import setup_vhpi_application
+    from .bridge import bridge_simulators, select_simulator, setup as setup_bridge
     from . import simulator_hooks
 
     simulator_name = context.simulator_name
+    simulators = bridge_simulators(simulator_name)
     if simulator_name is None:
         raise RuntimeError(
-            f"The vunit-python-bridge package requires {SUPPORTED_SIMULATORS} but no simulator was found"
+            f"The vunit-python-bridge package requires {', '.join(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}"
-        )
+    # Before anything is built, so a simulator the bridge cannot serve fails first
+    interface = select_simulator(simulators, simulator_name).interface
 
     add_file_base_package(context)
 
-    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,
+        interface,
     )
 
     context.add_source_files(context.library.name, list(bridge.vhdl_files))
 
-    simulator_hooks.register(context, bridge)
+    simulator_hooks.register(context, bridge, simulators)

vunit_python_bridge/bridge.py

@@ -13,7 +13,9 @@ import os
 import re
 import sys
 from pathlib import Path
-from typing import List, NamedTuple, Optional
+from typing import Callable, Dict, List, NamedTuple, Optional
+
+from vunit.sim_if.factory import SIMULATOR_FACTORY
 
 from .native_library import (
     LIBRARY_DIR_VARIABLE,
@@ -31,10 +33,20 @@ 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
+# The foreign language interface of each built-in VUnit simulator. VHPIDIRECT names the library
+# by file name and the simulator hooks make the simulator load it, which GHDL does in its own way.
+BUILTIN_SIMULATORS = {
+    "nvc": "VHPIDIRECT",
+    "ghdl": "VHPIDIRECT_GHDL",
+    "modelsim": "FLI",
+    "rivierapro": "VHPI",
+}
+
+# What the interface class of a simulator from a VUnit package defines instead, see
+# docs/simulator_packages.rst
+INTERFACE_ATTRIBUTE = "foreign_language_interface"
+HOOKS_ATTRIBUTE = "native_library_hooks"
+PACKAGE_INTERFACES = ("VHPIDIRECT", "FLI", "VHPI")
 
 # 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
@@ -47,6 +59,16 @@ FOREIGN_PATTERN = re.compile(r"\{foreign:(\w+)\}")
 SUBPROGRAM_PATTERN = re.compile(r"^  (impure function|procedure) (\w+)(\([^)]*\))?( return \w+)?;", re.MULTILINE)
 
 
+class BridgeSimulator(NamedTuple):
+    """
+    How the bridge serves a simulator: its foreign language interface and, for a simulator from a
+    VUnit package, the native_library_hooks that make it load the library (None for a built-in one).
+    """
+
+    interface: str
+    native_library_hooks: Optional[Callable]
+
+
 class PythonBridge(NamedTuple):
     """
     A prepared bridge: the native library and the generated VHDL.
@@ -63,6 +85,7 @@ def setup(
     simulator_name: Optional[str] = None,
     simulator_prefix: Optional[str] = None,
     simulator_backend: Optional[str] = None,
+    interface: Optional[str] = None,
 ) -> PythonBridge:
     """
     Prepare the Python bridge for a project. Called by the package setup function.
@@ -73,25 +96,27 @@ def setup(
     :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.
+    :param interface: The foreign language interface, see bridge_simulators. None takes it from
+                      there by simulator name.
     :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}"
-        )
+    if interface is None and simulator_name is not None:
+        interface = select_simulator(bridge_simulators(simulator_name), simulator_name).interface
 
     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:
+    is_fli = interface == "FLI"
+    is_vhpi = interface == "VHPI"
+    if (is_fli or is_vhpi) 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"
+            f"The {'FLI' if is_fli else 'VHPI'} 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(Path(simulator_prefix) if is_fli else None)
+    front_end = "fli" if is_fli else "vhpi" if is_vhpi else None
+    library_file = _prepare_library(Path(simulator_prefix) if front_end else None, front_end)
     run_script_dir = str(Path.cwd() if run_script_path is None else Path(run_script_path).resolve().parent)
     # The configuration belongs to the project, the library may be shared. The simulator
     # hooks tell the library where the configuration is.
@@ -99,13 +124,16 @@ def setup(
     _write_if_changed(config_file, _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}}"
-    )
+    # and the library, by absolute path since Questa accepts it, for the FLI; the library by
+    # absolute path without its suffix, which Riviera-PRO adds, and the entry point registered
+    # by native/vhpi.c for VHPI; the VHPIDIRECT library token and the entry point itself for
+    # VHPIDIRECT.
+    if is_fli:
+        foreign = f"fli_{{entry_point}} {library_file!s}"
+    elif is_vhpi:
+        foreign = f"VHPI {_vhpi_library_token(library_file)} {{entry_point}}"
+    else:
+        foreign = f"VHPIDIRECT {_vhpidirect_token(interface, simulator_backend, library_file)} {{entry_point}}"
     bridge_package = root / "vhdl" / "python_bridge_pkg.vhd"
     _write_if_changed(bridge_package, _render_bridge_package(foreign))
 
@@ -119,14 +147,75 @@ def setup(
     )
 
 
-def _prepare_library(fli_prefix: Optional[Path]) -> Path:
+def bridge_simulators(selected: Optional[str] = None) -> Dict[str, BridgeSimulator]:
+    """
+    The simulators the bridge serves, by name: the built-in ones and every simulator VUnit knows,
+    from a simulator package, whose interface class defines foreign_language_interface and
+    native_library_hooks. The simulator packages are added to VUnit before the bridge. Only the
+    attributes of the selected simulator are checked, a class defining just one of them is
+    otherwise not a simulator the bridge serves.
+    """
+    simulators = {name: BridgeSimulator(interface, None) for name, interface in BUILTIN_SIMULATORS.items()}
+    for simulator_class in SIMULATOR_FACTORY.supported_simulators():
+        interface = getattr(simulator_class, INTERFACE_ATTRIBUTE, None)
+        hooks = getattr(simulator_class, HOOKS_ATTRIBUTE, None)
+        if interface is None and hooks is None:
+            continue
+        if simulator_class.name == selected:
+            _check_attributes(simulator_class.name, interface, hooks)
+        elif interface is None or hooks is None:
+            continue
+        simulators[simulator_class.name] = BridgeSimulator(interface, hooks)
+    return simulators
+
+
+def select_simulator(simulators: Dict[str, BridgeSimulator], name: str) -> BridgeSimulator:
+    """
+    The simulator of the given name from bridge_simulators.
+    """
+    if name not in simulators:
+        raise PythonBridgeError(
+            f"The vunit-python-bridge package requires {', '.join(simulators)}, or a simulator whose interface "
+            f"class says how it loads a native library, which {name} does not. Its simulator interface class must "
+            f"define {INTERFACE_ATTRIBUTE} ({', '.join(map(repr, PACKAGE_INTERFACES))}) and "
+            f"{HOOKS_ATTRIBUTE}(library_file), see 'Simulator packages' in the vunit-python-bridge documentation."
+        )
+    return simulators[name]
+
+
+def _check_attributes(name: str, interface, hooks) -> None:
+    """
+    Check the attributes a simulator interface class defines to be served by the bridge.
+    """
+    for defined, missing, value in (
+        (INTERFACE_ATTRIBUTE, HOOKS_ATTRIBUTE, hooks),
+        (HOOKS_ATTRIBUTE, INTERFACE_ATTRIBUTE, interface),
+    ):
+        if value is None:
+            raise PythonBridgeError(
+                f"The {name} simulator interface defines {defined} but not {missing}, "
+                "the vunit-python-bridge package needs both. Define it in the simulator interface class."
+            )
+    if interface not in PACKAGE_INTERFACES:
+        raise PythonBridgeError(
+            f"{INTERFACE_ATTRIBUTE} of the {name} simulator interface is {interface!r}, "
+            f"the vunit-python-bridge package knows {', '.join(map(repr, PACKAGE_INTERFACES))}"
+        )
+    if not callable(hooks):
+        raise PythonBridgeError(
+            f"{HOOKS_ATTRIBUTE} of the {name} simulator interface is not callable, it must be a static or "
+            "class method taking the library file"
+        )
+
+
+def _prepare_library(simulator_prefix: Optional[Path], front_end: Optional[str]) -> Path:
     """
     Prepare the library in the library directory, failing with a pointer to the variable
     selecting another one when it cannot be written, e.g. a read-only home directory.
     """
     directory = library_directory()
     try:
-        return prepare_library(directory, fli_prefix)
+        return prepare_library(directory, simulator_prefix, front_end)
     except OSError as exc:
         source = f"set by {LIBRARY_DIR_VARIABLE}" if os.environ.get(LIBRARY_DIR_VARIABLE) else "the default"
         raise PythonBridgeError(
@@ -135,16 +224,30 @@ def _prepare_library(fli_prefix: Optional[Path]) -> Path:
         ) from exc
 
 
-def _vhpidirect_token(simulator_name, simulator_backend: Optional[str], library_file: Path) -> str:
+def _vhpidirect_token(interface: Optional[str], 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:
+    if interface == "VHPIDIRECT_GHDL" and simulator_backend in GHDL_LINKING_BACKENDS:
         return "-lvunit_python_bridge"
     return library_file.name
 
 
+def _vhpi_library_token(library_file: Path) -> str:
+    """
+    The library of the VHPI attributes: its path without the suffix the simulator adds. The
+    attribute separates its parts by spaces, so the path cannot have any.
+    """
+    token = str(library_file.with_suffix(""))
+    if any(character.isspace() for character in token):
+        raise PythonBridgeError(
+            f"The Python bridge library for VHPI is in {library_file.parent!s}, whose path has a space, which the "
+            f"VHPI foreign attribute cannot name. Set {LIBRARY_DIR_VARIABLE} to a directory without spaces."
+        )
+    return token
+
+
 def _render_bridge_package(foreign: str) -> str:
     """
     The generated python_bridge_pkg.vhd: the declarations of the template with the foreign

vunit_python_bridge/hdl/src/python_context.vhd

@@ -10,4 +10,5 @@ context python_context is
   library python_bridge;
   use python_bridge.python_pkg.all;
   use python_bridge.python_ffi_pkg.all;
+  use python_bridge.python_object_pkg.all;
 end context;

vunit_python_bridge/hdl/src/python_ffi_pkg_bridge.vhd

@@ -4,24 +4,18 @@
 --
 -- Copyright (c) 2014-2026, Lars Asplund lars.anders.asplund@gmail.com
 --
--- The foreign language interface of the Python package for NVC and GHDL,
--- implemented with the VUnit Python bridge (src/vunit_python_bridge). It provides
--- the same subprograms as the FLI and VHPI variants but over the private
--- python_bridge_pkg, which the setup function of the package generates.
---
--- Deviations from the other variants:
---   * The subprograms are impure since they call impure foreign subprograms.
---   * Errors are reported as failures on the logger of the session they were
---     performed in rather than aborting the simulation directly, which makes
---     them observable from VHDL.
---   * Sessions other than the default one are supported.
+-- The foreign language interface of the Python package for every simulator,
+-- implemented with the VUnit Python bridge (src/vunit_python_bridge) over the
+-- private python_bridge_pkg, which the setup function of the package generates.
+-- The subprograms are impure since they call impure foreign subprograms. Errors
+-- are reported as failures on the logger of the session they were performed in,
+-- which makes them observable from VHDL.
 --
 -- The p_ prefixed declarations are the private primitives the bridge
--- operations of python_pkg are built on. They are not part of the API. The FLI and VHPI
--- variants of this package declare the same primitives and implement them by
--- reporting a failure.
+-- operations of python_pkg are built on. They are not part of the API.
 
 library vunit_lib;
+use vunit_lib.dict_pkg.all;
 use vunit_lib.id_pkg.all;
 use vunit_lib.integer_array_pkg.all;
 use vunit_lib.integer_vector_ptr_pkg.all;
@@ -111,6 +105,9 @@ package python_ffi_pkg is
   -----------------------------------------------------------------------------
   -- Private, the primitives the bridge operations of python_pkg are built on
   -----------------------------------------------------------------------------
+  -- Whether new_session has made a session with the identity
+  impure function p_has_session(id : id_t) return boolean;
+
   -- Result kinds, must match src/vunit_python_bridge/runtime.py
   constant p_kind_integer : integer := 0;
   constant p_kind_real : integer := 1;
@@ -172,6 +169,7 @@ package python_ffi_pkg is
 
   -- The result of the last evaluation
   impure function p_result_integer return integer;
+  impure function p_result_real return real;
   impure function p_result_string return string;
   impure function p_result_integer_vector return integer_vector;
   impure function p_result_real_vector return real_vector;
@@ -192,11 +190,20 @@ package body python_ffi_pkg is
     return new_session(get_id(name, parent => p_python_id));
   end;
 
+  -- The full names of the identities new_session has made sessions with
+  constant p_session_ids : dict_t := new_dict;
+
   impure function new_session(id : id_t) return python_session_t is
   begin
+    set_string(p_session_ids, full_name(id), "");
     return (p_data => new_integer_vector_ptr(1, value => to_integer(id)));
   end;
 
+  impure function p_has_session(id : id_t) return boolean is
+  begin
+    return has_key(p_session_ids, full_name(id));
+  end;
+
   impure function get_id(session : python_session_t) return id_t is
   begin
     return to_id(get(session.p_data, 0));
@@ -338,6 +345,11 @@ package body python_ffi_pkg is
     return vpy_result_integer;
   end;
 
+  impure function p_result_real return real is
+  begin
+    return vpy_result_real;
+  end;
+
   impure function p_result_string return string is
     constant len : natural := vpy_result_meta(0);
     variable result : string(1 to len);