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

vunit_python_bridge/__init__.py

@@ -12,52 +12,58 @@ 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).
 
 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``.
+
+``set_relative_file_base(directory)``, called in the run script before ``add_package``, sets the
+directory that ``base_path`` of ``python_pkg`` returns, for VHDL to join file names to. The
+environment variable ``VUNIT_PYTHON_BRIDGE_FILE_BASE`` sets it too, and takes precedence.
 """
 
 from pathlib import Path
 
+from .file_base import add_file_base_package
+
+# Public: run scripts use them
+from .file_base import FILE_BASE_VARIABLE as FILE_BASE_VARIABLE
+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.
+# Riviera-PRO through VHPI.
 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"
+SUPPORTED_SIMULATORS = "NVC, GHDL, Questa/ModelSim or Riviera-PRO"
 
 
 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 . import simulator_hooks
 
     simulator_name = context.simulator_name
@@ -73,11 +79,7 @@ def setup(context):
             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
+    add_file_base_package(context)
 
     bridge = setup_bridge(
         context.output_path,

vunit_python_bridge/bridge.py

@@ -16,10 +16,12 @@ from pathlib import Path
 from typing import List, NamedTuple, Optional
 
 from .native_library import (
+    LIBRARY_DIR_VARIABLE,
     PACKAGE_PATH,
     PythonBridgeError,
     check_python_build,
     check_windows_64bit_simulator,
+    library_directory,
     prepare_library,
     windows_python_dll,
 )
@@ -29,10 +31,10 @@ 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.
+# The simulators the bridge serves, reaching it through VHPIDIRECT, the FLI and VHPI.
 FLI_SIMULATORS = ("modelsim",)
-BRIDGE_SIMULATORS = ("nvc", "ghdl") + FLI_SIMULATORS
+VHPI_SIMULATORS = ("rivierapro",)
+BRIDGE_SIMULATORS = ("nvc", "ghdl") + FLI_SIMULATORS + VHPI_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
@@ -51,6 +53,7 @@ class PythonBridge(NamedTuple):
     """
 
     library_file: Path
+    config_file: Path
     vhdl_files: List[Path]
 
 
@@ -74,7 +77,7 @@ def setup(
     """
     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"The vunit-python-bridge package requires NVC, GHDL, Questa/ModelSim or Riviera-PRO, "
             f"it is not supported for {simulator_name}"
         )
 
@@ -82,29 +85,39 @@ def setup(
     check_windows_64bit_simulator(simulator_name, simulator_prefix)
 
     is_fli = simulator_name in FLI_SIMULATORS
-    if is_fli and simulator_prefix is None:
+    is_vhpi = simulator_name in VHPI_SIMULATORS
+    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(root, 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)
-    _write_if_changed(library_file.parent / CONFIG_FILE_NAME, _config_text(run_script_dir))
+    # The configuration belongs to the project, the library may be shared. The simulator
+    # hooks tell the library where the configuration is.
+    config_file = root / CONFIG_FILE_NAME
+    _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
+    # NVC and GHDL.
+    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(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,
+        config_file,
         [
             bridge_package,
             VHDL_SOURCE_PATH / "python_ffi_pkg_bridge.vhd",
@@ -112,6 +125,22 @@ def setup(
     )
 
 
+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, 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(
+            f"Cannot build the Python bridge library in {directory!s} ({source}): {exc}. "
+            f"Set {LIBRARY_DIR_VARIABLE} to a writable directory."
+        ) from exc
+
+
 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,
@@ -122,6 +151,20 @@ def _vhpidirect_token(simulator_name, simulator_backend: Optional[str], library_
     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/file_base.py

@@ -0,0 +1,128 @@
+# 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 base directory that ``base_path`` of ``python_pkg`` returns: set by ``set_relative_file_base``
+in the run script or by the environment variable ``VUNIT_PYTHON_BRIDGE_FILE_BASE``, and given to
+VHDL in a generated package.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+from .bridge import _write_if_changed
+
+# Name of the generated VHDL package holding the base directory, used by python_pkg (base_path)
+FILE_BASE_PACKAGE = "python_file_base_pkg"
+
+# The environment variable setting the directory of base_path when the run script cannot. It takes
+# precedence over set_relative_file_base so that whoever runs a shared run script can override it.
+FILE_BASE_VARIABLE = "VUNIT_PYTHON_BRIDGE_FILE_BASE"
+
+LOGGER = logging.getLogger(__name__)
+
+# The directory set by set_relative_file_base, None when unset, and whether setup has run, after
+# which the directory is in the generated package and can no longer be changed
+_relative_file_base = None
+_setup_done = False
+
+
+def set_relative_file_base(directory):
+    """
+    Set the directory that ``base_path`` of ``python_pkg`` returns, for VHDL to join file names to.
+
+    Call it in the run script before ``vu.add_package("vunit-python-bridge", ...)``. A relative
+    directory is taken from the current working directory at the time of the call.
+
+    :param directory: An existing directory, a ``str`` or a ``Path``.
+    """
+    global _relative_file_base  # pylint: disable=global-statement
+
+    if _setup_done:
+        raise RuntimeError(
+            'set_relative_file_base() must be called before vu.add_package("vunit-python-bridge", ...), '
+            "the package has already been set up"
+        )
+    path = Path(directory).resolve()
+    if not path.is_dir():
+        raise ValueError(f"The relative file base {str(directory)!r} is not an existing directory")
+    _relative_file_base = path
+
+
+def _vhdl_string_literal(text):
+    """
+    A VHDL expression of type string for the UTF-8 bytes of a text, in ASCII: printable characters
+    in a literal with its quotes doubled, other bytes as character'val(n).
+    """
+    parts = []
+    literal = ""
+    for byte in text.encode("utf-8"):
+        if 0x20 <= byte <= 0x7E:
+            literal += '""' if byte == ord('"') else chr(byte)
+        else:
+            if literal:
+                parts.append(f'"{literal}"')
+                literal = ""
+            parts.append(f"character'val({byte})")
+    if literal or not parts:
+        parts.append(f'"{literal}"')
+    if not parts[0].startswith('"'):
+        # A string expression rather than a lone character
+        parts.insert(0, '""')
+    return " & ".join(parts)
+
+
+def _file_base_package_text(directory):
+    """
+    Content of the generated python_file_base_pkg.vhd.
+    """
+    value = "" if directory is None else directory.as_posix()
+    return f"""\
+-- Generated by vunit_python_bridge.setup. Do not edit.
+--
+-- The directory set by the environment variable {FILE_BASE_VARIABLE} or by
+-- vunit_python_bridge.set_relative_file_base() in the run script, empty when neither is set.
+-- base_path of python_pkg returns it.
+package {FILE_BASE_PACKAGE} is
+  constant p_relative_file_base : string := {_vhdl_string_literal(value)};
+end package;
+"""
+
+
+def _file_base():
+    """
+    The directory of base_path: that of the environment variable if it is set and not empty,
+    otherwise that of set_relative_file_base, None when neither is set.
+    """
+    value = os.environ.get(FILE_BASE_VARIABLE, "")
+    if value == "":
+        return _relative_file_base
+
+    directory = Path(value).resolve()
+    if not directory.is_dir():
+        raise ValueError(f"The environment variable {FILE_BASE_VARIABLE}={value!r} is not an existing directory")
+    if _relative_file_base is not None and _relative_file_base != directory:
+        LOGGER.warning(
+            "The environment variable %s=%s takes precedence over set_relative_file_base(%r)",
+            FILE_BASE_VARIABLE,
+            value,
+            str(_relative_file_base),
+        )
+    return directory
+
+
+def add_file_base_package(context):
+    """
+    Generate python_file_base_pkg and add it to the library of the package.
+    """
+    global _setup_done  # pylint: disable=global-statement
+
+    path = Path(context.output_path) / "python_bridge" / "vhdl" / f"{FILE_BASE_PACKAGE}.vhd"
+    _write_if_changed(path, _file_base_package_text(_file_base()))
+    context.add_source_files(context.library.name, [path])
+    _setup_done = True
+

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,28 +4,24 @@
 --
 -- 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;
 use vunit_lib.logger_pkg.all;
+use vunit_lib.run_pkg.get_phase;
+use vunit_lib.run_types_pkg.all;
 use work.python_bridge_pkg.all;
 
 package python_ffi_pkg is
@@ -109,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;
@@ -121,6 +120,7 @@ package python_ffi_pkg is
   constant p_kind_integer_array : integer := 8;
   constant p_kind_integer_vector : integer := 9;
   constant p_kind_real_vector : integer := 10;
+  constant p_kind_dict : integer := 11;
 
   -- Names of the operations, used in the error messages
   impure function p_exec_operation(session : python_session_t := default_session) return string;
@@ -169,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;
@@ -189,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));
@@ -335,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);
@@ -412,6 +427,14 @@ package body python_ffi_pkg is
     variable offset, n : natural := 0;
     variable staged_id : integer;
   begin
+    if get_phase < test_runner_setup then
+      failure(
+        python_logger,
+        operation & " failed:" & LF &
+        "An integer_array_t argument cannot be made before test_runner_setup."
+      );
+      return -1;
+    end if;
     if not p_succeeded(
       vpy_push_array(len, width(arr), height(arr), depth(arr), bit_width(arr), boolean'pos(is_signed(arr))),
       operation