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

vunit_python_bridge/native/fli.c

@@ -0,0 +1,98 @@
+/*
+ * 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
+ *
+ * FLI front end of the bridge, compiled into the library only for
+ * Questa/ModelSim. Every entry point of bridge.h gets an fli_ prefixed
+ * foreign subprogram that converts the FLI parameters and delegates, so that
+ * the bridge itself, the generated VHDL and python_ffi_pkg_bridge.vhd are the
+ * same for all simulators.
+ *
+ * Parameter and return type mapping, from the tables of "Matching VHDL
+ * Parameters with C Parameters" and "Matching VHDL Return Types with C Return
+ * Types" in the Questa Foreign Language Interface Manual:
+ *   - A VHDL integer IN parameter of class constant is passed by value as int.
+ *   - An array parameter, IN or OUT, is passed as an mtiVariableIdT handle.
+ *     mti_GetArrayVarValue(id, NULL) returns a pointer to the storage of the
+ *     variable itself, which is both read and written in place. The element
+ *     type decides what it points to: char for string (an enumeration with at
+ *     most 256 values), mtiInt32T for integer_vector and double for
+ *     real_vector, which is exactly the ABI of bridge.h.
+ *   - A function returning integer returns int, one returning real returns
+ *     the mtiRealT union, assigned with MTI_ASSIGN_TO_REAL.
+ * Arrays are not null terminated and the handles are only valid during the
+ * call, neither of which matters here: every chunk carries its length and
+ * nothing is kept after the call returns.
+ */
+
+#include "bridge.h"
+
+#include "mti.h"
+
+/* ------------------------------------------------------------------------ */
+/* Scalars only: passed by value and returned as int                         */
+/* ------------------------------------------------------------------------ */
+
+VPY_EXPORT int fli_vpy_setup(void) { return (int)vpy_setup(); }
+
+VPY_EXPORT int fli_vpy_cleanup(void) { return (int)vpy_cleanup(); }
+
+VPY_EXPORT int fli_vpy_buffer_clear(void) { return (int)vpy_buffer_clear(); }
+
+VPY_EXPORT int fli_vpy_begin(void) { return (int)vpy_begin(); }
+
+VPY_EXPORT int fli_vpy_execute(int is_file) { return (int)vpy_execute((int32_t)is_file); }
+
+VPY_EXPORT int fli_vpy_eval(int kind, int width) { return (int)vpy_eval((int32_t)kind, (int32_t)width); }
+
+VPY_EXPORT int fli_vpy_push_array(int length, int width, int height, int depth, int bit_width, int is_signed) {
+  return (int)vpy_push_array((int32_t)length, (int32_t)width, (int32_t)height, (int32_t)depth, (int32_t)bit_width,
+                             (int32_t)is_signed);
+}
+
+VPY_EXPORT int fli_vpy_stage(void) { return (int)vpy_stage(); }
+
+VPY_EXPORT int fli_vpy_result_integer(void) { return (int)vpy_result_integer(); }
+
+VPY_EXPORT int fli_vpy_result_meta(int index) { return (int)vpy_result_meta((int32_t)index); }
+
+VPY_EXPORT int fli_vpy_error_length(void) { return (int)vpy_error_length(); }
+
+/* A VHDL function returning real returns the mtiRealT union, not a double. */
+VPY_EXPORT mtiRealT fli_vpy_result_real(void) {
+  mtiRealT result;
+
+  MTI_ASSIGN_TO_REAL(result, vpy_result_real());
+  return result;
+}
+
+/* ------------------------------------------------------------------------ */
+/* Chunks: constrained arrays passed as mtiVariableIdT                       */
+/* ------------------------------------------------------------------------ */
+
+VPY_EXPORT int fli_vpy_buffer_append(mtiVariableIdT chunk, int length) {
+  return (int)vpy_buffer_append((const char *)mti_GetArrayVarValue(chunk, NULL), (int32_t)length);
+}
+
+VPY_EXPORT int fli_vpy_array_write(mtiVariableIdT chunk, int length) {
+  return (int)vpy_array_write((const int32_t *)mti_GetArrayVarValue(chunk, NULL), (int32_t)length);
+}
+
+VPY_EXPORT void fli_vpy_result_read_string(mtiVariableIdT chunk, int offset, int length) {
+  vpy_result_read_string((char *)mti_GetArrayVarValue(chunk, NULL), (int32_t)offset, (int32_t)length);
+}
+
+VPY_EXPORT void fli_vpy_result_read_integers(mtiVariableIdT chunk, int offset, int length) {
+  vpy_result_read_integers((int32_t *)mti_GetArrayVarValue(chunk, NULL), (int32_t)offset, (int32_t)length);
+}
+
+VPY_EXPORT void fli_vpy_result_read_reals(mtiVariableIdT chunk, int offset, int length) {
+  vpy_result_read_reals((double *)mti_GetArrayVarValue(chunk, NULL), (int32_t)offset, (int32_t)length);
+}
+
+VPY_EXPORT void fli_vpy_error_read(mtiVariableIdT chunk, int offset, int length) {
+  vpy_error_read((char *)mti_GetArrayVarValue(chunk, NULL), (int32_t)offset, (int32_t)length);
+}

vunit_python_bridge/native/interpreter.c

@@ -0,0 +1,271 @@
+/*
+ * 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 embedded interpreter. It is initialized lazily on first use, in the
+ * Python environment that runs VUnit, and kept alive for the lifetime of the
+ * simulator process (it is never finalized).
+ */
+
+#include "bridge.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef _WIN32
+#include <windows.h>
+#else
+#include <dlfcn.h>
+#endif
+
+typedef enum { STATE_UNINITIALIZED, STATE_READY, STATE_FAILED } state_t;
+
+static state_t g_state = STATE_UNINITIALIZED;
+static vpy_config_t g_config;
+static PyObject *g_runtime = NULL; /* runtime.Runtime instance, strong reference */
+
+PyObject *vpy_runtime(void) { return g_runtime; }
+
+#ifdef _WIN32
+/* malloc'ed wide string of a UTF-8 string, NULL on failure. */
+static wchar_t *to_wide(const char *text) {
+  int length = MultiByteToWideChar(CP_UTF8, 0, text, -1, NULL, 0);
+  wchar_t *wide;
+
+  if (length <= 0) {
+    return NULL;
+  }
+  wide = (wchar_t *)malloc(sizeof(wchar_t) * (size_t)length);
+  if (wide != NULL) {
+    MultiByteToWideChar(CP_UTF8, 0, text, -1, wide, length);
+  }
+  return wide;
+}
+#endif
+
+/*
+ * Make the Python runtime library usable by extension modules.
+ *
+ * Windows: this library delay-loads pythonXY.dll. Load it by absolute path
+ * before the first Python API call so the delay-load helper finds it no
+ * matter how the simulator's DLL search path looks.
+ *
+ * POSIX: simulators dlopen() this library with RTLD_LOCAL, which makes
+ * libpython (our dependency) invisible to extension modules such as NumPy
+ * that expect the Python symbols to be globally available. Promote libpython
+ * to RTLD_GLOBAL.
+ */
+static int load_python_library(void) {
+#ifdef _WIN32
+  wchar_t *wpath = to_wide(g_config.python_dll);
+  HMODULE module;
+
+  if (wpath == NULL) {
+    vpy_set_error("Invalid Python DLL path in the Python bridge configuration");
+    return VPY_ERROR;
+  }
+  module = LoadLibraryExW(wpath, NULL, LOAD_WITH_ALTERED_SEARCH_PATH);
+  free(wpath);
+  if (module == NULL) {
+    char message[4096];
+
+    snprintf(message, sizeof(message), "Failed to load the Python DLL %s (Windows error %lu)", g_config.python_dll,
+             (unsigned long)GetLastError());
+    vpy_set_error(message);
+    return VPY_ERROR;
+  }
+  /* Intentionally never freed: the interpreter lives until process exit. */
+  return VPY_OK;
+#else
+  Dl_info info;
+
+  if (dladdr((void *)&Py_InitializeFromConfig, &info) != 0 && info.dli_fname != NULL) {
+    /* Intentionally never closed: the interpreter lives until process exit. */
+    if (dlopen(info.dli_fname, RTLD_NOW | RTLD_GLOBAL | RTLD_NOLOAD) == NULL) {
+      vpy_set_error2("Failed to make the Python library globally visible: ", dlerror());
+      return VPY_ERROR;
+    }
+  }
+  return VPY_OK;
+#endif
+}
+
+static int set_config_string(PyConfig *config, wchar_t **field, const char *value) {
+  PyStatus status;
+#ifdef _WIN32
+  wchar_t *wvalue = to_wide(value);
+
+  if (wvalue == NULL) {
+    vpy_set_error("Invalid path in the Python bridge configuration");
+    return VPY_ERROR;
+  }
+  status = PyConfig_SetString(config, field, wvalue);
+  free(wvalue);
+#else
+  status = PyConfig_SetBytesString(config, field, value);
+#endif
+  if (PyStatus_Exception(status)) {
+    vpy_set_error2("Failed to configure Python: ", status.err_msg);
+    return VPY_ERROR;
+  }
+  return VPY_OK;
+}
+
+/* Create the interpreter. On success this thread holds the GIL. */
+static int initialize_interpreter(void) {
+  PyConfig config;
+  PyStatus status;
+
+  PyConfig_InitPythonConfig(&config);
+  /* The simulator owns the process: no signal handlers, no argv parsing. */
+  config.install_signal_handlers = 0;
+  config.parse_argv = 0;
+
+  /* Make path configuration behave as if the interpreter that launched VUnit
+   * was started, which selects the same installation, virtual environment
+   * and site-packages. */
+  if (set_config_string(&config, &config.program_name, g_config.executable) != VPY_OK ||
+      set_config_string(&config, &config.executable, g_config.executable) != VPY_OK) {
+    PyConfig_Clear(&config);
+    return VPY_ERROR;
+  }
+
+  status = Py_InitializeFromConfig(&config);
+  PyConfig_Clear(&config);
+  if (PyStatus_Exception(status)) {
+    vpy_set_error2("Failed to initialize Python: ", status.err_msg != NULL ? status.err_msg : "unknown error");
+    return VPY_ERROR;
+  }
+  return VPY_OK;
+}
+
+/* Add a UTF-8 configuration string to a dict. GIL held. */
+static int set_item(PyObject *dict, const char *key, const char *value) {
+  PyObject *object = PyUnicode_DecodeUTF8(value, (Py_ssize_t)strlen(value), "surrogateescape");
+  int status;
+
+  if (object == NULL) {
+    return -1;
+  }
+  status = PyDict_SetItemString(dict, key, object);
+  Py_DECREF(object);
+  return status;
+}
+
+/* Load ../runtime.py and create the Runtime instance. GIL held. */
+static int create_runtime(void) {
+  static const char *bootstrap =
+      "import importlib.util, sys\n"
+      "_spec = importlib.util.spec_from_file_location('_vunit_python_runtime', runtime_path)\n"
+      "_module = importlib.util.module_from_spec(_spec)\n"
+      "sys.modules[_spec.name] = _module\n"
+      "_spec.loader.exec_module(_module)\n"
+      "runtime = _module.Runtime(run_script_dir=run_script_dir, prefix=prefix)\n";
+  PyObject *globals = PyDict_New();
+  PyObject *ret = NULL;
+  int status = VPY_ERROR;
+
+  if (globals == NULL || PyDict_SetItemString(globals, "__builtins__", PyEval_GetBuiltins()) < 0 ||
+      set_item(globals, "runtime_path", g_config.runtime) < 0 ||
+      set_item(globals, "run_script_dir", g_config.run_script_dir) < 0 ||
+      set_item(globals, "prefix", g_config.prefix) < 0) {
+    vpy_set_error_from_python();
+    goto done;
+  }
+
+  ret = PyRun_String(bootstrap, Py_file_input, globals, globals);
+  if (ret == NULL) {
+    vpy_set_error_from_python();
+    goto done;
+  }
+
+  g_runtime = PyDict_GetItemString(globals, "runtime"); /* borrowed */
+  if (g_runtime == NULL) {
+    vpy_set_error("Failed to create the Python bridge runtime");
+    goto done;
+  }
+  Py_INCREF(g_runtime);
+  status = VPY_OK;
+
+done:
+  Py_XDECREF(ret);
+  Py_XDECREF(globals);
+  return status;
+}
+
+/*
+ * Initialize on first use. Failure is sticky: the error text keeps the reason
+ * and every later operation fails with it.
+ */
+int vpy_initialize(void) {
+  int we_initialized;
+  PyGILState_STATE gil = PyGILState_UNLOCKED;
+  int status;
+
+  if (g_state != STATE_UNINITIALIZED) {
+    return g_state == STATE_READY ? VPY_OK : VPY_ERROR;
+  }
+  g_state = STATE_FAILED;
+
+  if (vpy_read_config(&g_config) != VPY_OK || load_python_library() != VPY_OK) {
+    return VPY_ERROR;
+  }
+
+  /* Reuse an interpreter embedded by someone else in this process. */
+  we_initialized = !Py_IsInitialized();
+  if (we_initialized) {
+    if (initialize_interpreter() != VPY_OK) {
+      return VPY_ERROR;
+    }
+  } else {
+    gil = PyGILState_Ensure();
+  }
+
+  status = create_runtime();
+
+  if (we_initialized) {
+    /* Release the GIL taken by initialization. Every entry point acquires it
+     * with PyGILState_Ensure, from whatever thread the simulator happens to
+     * call us on. The thread state is kept forever. */
+    PyEval_SaveThread();
+  } else {
+    PyGILState_Release(gil);
+  }
+
+  if (status == VPY_OK) {
+    g_state = STATE_READY;
+  }
+  return status;
+}
+
+/* Whether the interpreter and the runtime are ready to be used. */
+int vpy_is_initialized(void) { return g_state == STATE_READY; }
+
+/*
+ * Common start of the entry points that use Python after vpy_begin: fail if
+ * the bridge is not initialized, else take the GIL.
+ */
+int vpy_enter(PyGILState_STATE *gil) {
+  if (g_state != STATE_READY) {
+    if (!vpy_has_error()) {
+      vpy_set_error("Internal error: the Python bridge is not initialized");
+    }
+    return VPY_ERROR;
+  }
+  *gil = PyGILState_Ensure();
+  return VPY_OK;
+}
+
+/* Status of a Python call returning ret (a new reference or NULL), which is consumed. */
+int vpy_finish_call(PyObject *ret) {
+  if (ret == NULL) {
+    vpy_set_error_from_python();
+    return VPY_ERROR;
+  }
+  Py_DECREF(ret);
+  return VPY_OK;
+}

vunit_python_bridge/native/operations.c

@@ -0,0 +1,239 @@
+/*
+ * 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 operations: setup, cleanup, begin, exec, eval, and the conversion and
+ * transfer of the result back to VHDL.
+ */
+
+#include "bridge.h"
+
+#include <stdio.h>
+#include <string.h>
+
+#define NUM_META 8
+
+/* Result of the last evaluation, converted to a VHDL kind by vpy_eval. */
+static PyObject *g_result = NULL; /* bytes of a string/array result, strong reference */
+static const char *g_result_data = NULL; /* view into g_result, immutable */
+static size_t g_result_size = 0;
+static int32_t g_result_integer = 0;
+static double g_result_real = 0.0;
+static int32_t g_result_meta[NUM_META];
+
+/* Drop the result of the previous operation. GIL held. */
+static void clear_result(void) {
+  Py_CLEAR(g_result);
+  g_result_data = NULL;
+  g_result_size = 0;
+  g_result_integer = 0;
+  g_result_real = 0.0;
+  memset(g_result_meta, 0, sizeof(g_result_meta));
+}
+
+/* Keep the simulator's and Python's output in order. */
+static void flush_c_streams(void) {
+  fflush(stdout);
+  fflush(stderr);
+}
+
+/*
+ * Start the interpreter. Eager and idempotent. Optional: every operation
+ * starts the interpreter if it is not running, see vpy_begin.
+ */
+VPY_EXPORT int32_t vpy_setup(void) {
+  flush_c_streams();
+  return vpy_initialize();
+}
+
+/*
+ * Release what the simulation acquired: flush Python's streams and drop the
+ * last result and the staged values. The interpreter is NOT finalized and the
+ * session namespaces are kept, so later operations keep working. Optional:
+ * everything it releases is released by the simulator process ending, and
+ * every operation flushes on its own.
+ */
+VPY_EXPORT int32_t vpy_cleanup(void) {
+  PyGILState_STATE gil;
+  int status;
+
+  flush_c_streams();
+  if (!vpy_is_initialized()) {
+    /* Nothing was ever started, so there is nothing to release. */
+    return VPY_OK;
+  }
+  if (vpy_enter(&gil) != VPY_OK) {
+    return VPY_ERROR;
+  }
+  clear_result();
+  vpy_clear_arguments();
+  status = vpy_finish_call(PyObject_CallMethod(vpy_runtime(), "cleanup", NULL));
+  PyGILState_Release(gil);
+  return status;
+}
+
+/*
+ * Start a new operation in the session named by the buffer: initialize on
+ * first use, select the session and drop the previous result and values.
+ */
+VPY_EXPORT int32_t vpy_begin(void) {
+  PyGILState_STATE gil;
+  PyObject *session;
+  int status = VPY_ERROR;
+
+  if (vpy_initialize() != VPY_OK || vpy_enter(&gil) != VPY_OK) {
+    return VPY_ERROR;
+  }
+  clear_result();
+  vpy_clear_arguments();
+  session = vpy_buffer_as_str();
+  if (session == NULL) {
+    vpy_set_error_from_python();
+  } else {
+    status = vpy_finish_call(PyObject_CallMethod(vpy_runtime(), "select_session", "O", session));
+    Py_DECREF(session);
+  }
+  PyGILState_Release(gil);
+  return status;
+}
+
+/* Execute the buffer as Python source (is_file = 0) or as a file name (is_file = 1). */
+VPY_EXPORT int32_t vpy_execute(int32_t is_file) {
+  PyGILState_STATE gil;
+  PyObject *text;
+  int status = VPY_ERROR;
+
+  flush_c_streams();
+  if (vpy_enter(&gil) != VPY_OK) {
+    return VPY_ERROR;
+  }
+  text = vpy_buffer_as_str();
+  if (text == NULL) {
+    vpy_set_error_from_python();
+  } else {
+    status = vpy_finish_call(PyObject_CallMethod(vpy_runtime(), "execute", "Oi", text, (int)(is_file != 0)));
+    Py_DECREF(text);
+  }
+  PyGILState_Release(gil);
+  /* The runtime flushed Python's streams, flush what Python wrote through C */
+  flush_c_streams();
+  return status;
+}
+
+/*
+ * Store the conversion result (integer, real, bytes, meta tuple) returned by
+ * the runtime. Which fields are meaningful depends on the kind. GIL held.
+ */
+static int store_result(PyObject *converted) {
+  PyObject *data;
+  PyObject *meta;
+  Py_ssize_t index;
+
+  if (!PyTuple_Check(converted) || PyTuple_Size(converted) != 4) {
+    vpy_set_error("Internal error: unexpected result conversion format");
+    return VPY_ERROR;
+  }
+  data = PyTuple_GetItem(converted, 2); /* borrowed */
+  meta = PyTuple_GetItem(converted, 3); /* borrowed */
+  if (!PyBytes_Check(data) || !PyTuple_Check(meta)) {
+    vpy_set_error("Internal error: unexpected result conversion format");
+    return VPY_ERROR;
+  }
+
+  g_result_integer = (int32_t)PyLong_AsLong(PyTuple_GetItem(converted, 0));
+  g_result_real = PyFloat_AsDouble(PyTuple_GetItem(converted, 1));
+  for (index = 0; index < PyTuple_Size(meta) && index < NUM_META; index++) {
+    g_result_meta[index] = (int32_t)PyLong_AsLong(PyTuple_GetItem(meta, index));
+  }
+  if (PyErr_Occurred()) {
+    vpy_set_error_from_python();
+    return VPY_ERROR;
+  }
+
+  Py_INCREF(data);
+  g_result = data;
+  g_result_data = PyBytes_AsString(data);
+  g_result_size = (size_t)PyBytes_Size(data);
+  return VPY_OK;
+}
+
+/*
+ * Evaluate the buffer as a Python expression in the current session and
+ * convert the value to the requested VHDL kind and width.
+ */
+VPY_EXPORT int32_t vpy_eval(int32_t kind, int32_t width) {
+  PyGILState_STATE gil;
+  PyObject *text;
+  PyObject *converted;
+  int status = VPY_ERROR;
+
+  flush_c_streams();
+  if (vpy_enter(&gil) != VPY_OK) {
+    return VPY_ERROR;
+  }
+  clear_result();
+  text = vpy_buffer_as_str();
+  if (text == NULL) {
+    vpy_set_error_from_python();
+  } else {
+    converted = PyObject_CallMethod(vpy_runtime(), "evaluate", "Oii", text, (int)kind, (int)width);
+    Py_DECREF(text);
+    if (converted == NULL) {
+      vpy_set_error_from_python();
+    } else {
+      status = store_result(converted);
+      Py_DECREF(converted);
+    }
+  }
+  if (status != VPY_OK) {
+    clear_result();
+  }
+  PyGILState_Release(gil);
+  /* The runtime flushed Python's streams, flush what Python wrote through C */
+  flush_c_streams();
+  return status;
+}
+
+VPY_EXPORT int32_t vpy_result_integer(void) { return g_result_integer; }
+
+VPY_EXPORT double vpy_result_real(void) { return g_result_real; }
+
+VPY_EXPORT int32_t vpy_result_meta(int32_t index) {
+  if (index < 0 || index >= NUM_META) {
+    return 0;
+  }
+  return g_result_meta[index];
+}
+
+/* Copy length bytes of the string/bit-string result starting at offset. */
+VPY_EXPORT void vpy_result_read_string(char *chunk, int32_t offset, int32_t length) {
+  if (offset < 0 || length <= 0 || (size_t)offset + (size_t)length > g_result_size) {
+    return;
+  }
+  memcpy(chunk, g_result_data + offset, (size_t)length);
+}
+
+/* Copy length integers of an integer_array_t/integer_vector result starting at element offset. */
+VPY_EXPORT void vpy_result_read_integers(int32_t *chunk, int32_t offset, int32_t length) {
+  size_t start = (size_t)offset * sizeof(int32_t);
+  size_t bytes = (size_t)length * sizeof(int32_t);
+
+  if (offset < 0 || length <= 0 || start + bytes > g_result_size) {
+    return;
+  }
+  memcpy(chunk, g_result_data + start, bytes);
+}
+
+/* Copy length reals of a real_vector result starting at element offset. */
+VPY_EXPORT void vpy_result_read_reals(double *chunk, int32_t offset, int32_t length) {
+  size_t start = (size_t)offset * sizeof(double);
+  size_t bytes = (size_t)length * sizeof(double);
+
+  if (offset < 0 || length <= 0 || start + bytes > g_result_size) {
+    return;
+  }
+  memcpy(chunk, g_result_data + start, bytes);
+}