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

vunit_python_bridge/native/arguments.c

@@ -0,0 +1,191 @@
+/*
+ * 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
+ *
+ * Data transferred from VHDL: a byte buffer for strings (Python source code,
+ * expressions, file and session names) and the integer_array_t value being
+ * pushed, which is staged in the runtime and then referred to from the Python
+ * source text VHDL builds.
+ */
+
+#include "bridge.h"
+
+#include <stdlib.h>
+#include <string.h>
+
+/* Raw byte buffer used to transfer strings from VHDL, owned. */
+static char *g_buffer = NULL;
+static size_t g_buffer_length = 0;
+static size_t g_buffer_capacity = 0;
+
+/* Strong references, only touched with the GIL held. */
+static PyObject *g_array = NULL;   /* NumPy array of the integer_array_t being pushed */
+static PyObject *g_pending = NULL; /* bytearray backing it */
+
+/* View into g_pending. It is owned by us and never resized while referenced
+ * (NumPy holds a buffer export on it), so the pointer stays valid. */
+static char *g_pending_data = NULL;
+static size_t g_pending_size = 0;
+static size_t g_pending_position = 0;
+
+/* New reference to the transfer buffer as a str. */
+PyObject *vpy_buffer_as_str(void) {
+  return PyUnicode_DecodeUTF8(g_buffer == NULL ? "" : g_buffer, (Py_ssize_t)g_buffer_length, "surrogateescape");
+}
+
+void vpy_clear_arguments(void) {
+  Py_CLEAR(g_array);
+  Py_CLEAR(g_pending);
+  g_pending_data = NULL;
+  g_pending_size = 0;
+  g_pending_position = 0;
+}
+
+/* ------------------------------------------------------------------------ */
+/* Entry points                                                              */
+/* ------------------------------------------------------------------------ */
+
+VPY_EXPORT int32_t vpy_buffer_clear(void) {
+  g_buffer_length = 0;
+  return VPY_OK;
+}
+
+VPY_EXPORT int32_t vpy_buffer_append(const char *chunk, int32_t length) {
+  size_t required;
+
+  if (length <= 0) {
+    return VPY_OK;
+  }
+  required = g_buffer_length + (size_t)length;
+  if (required > g_buffer_capacity) {
+    size_t capacity = g_buffer_capacity == 0 ? 4096 : g_buffer_capacity;
+    char *buffer;
+
+    while (capacity < required) {
+      capacity *= 2;
+    }
+    buffer = (char *)realloc(g_buffer, capacity);
+    if (buffer == NULL) {
+      vpy_set_error("Out of memory while transferring a string to Python");
+      return VPY_ERROR;
+    }
+    g_buffer = buffer;
+    g_buffer_capacity = capacity;
+  }
+  memcpy(g_buffer + g_buffer_length, chunk, (size_t)length);
+  g_buffer_length = required;
+  return VPY_OK;
+}
+
+/*
+ * Push an integer_array_t value. Allocates the Python-owned storage that the
+ * element values are subsequently written to with vpy_array_write. The value
+ * is made available to Python source code by vpy_stage.
+ */
+VPY_EXPORT int32_t vpy_push_array(int32_t length, int32_t width, int32_t height, int32_t depth, int32_t bit_width,
+                                  int32_t is_signed) {
+  PyGILState_STATE gil;
+  size_t size = length > 0 ? (size_t)length * sizeof(int32_t) : 0;
+  PyObject *storage = NULL;
+  int status = VPY_ERROR;
+
+  if (vpy_initialize() != VPY_OK || vpy_enter(&gil) != VPY_OK) {
+    return VPY_ERROR;
+  }
+  vpy_clear_arguments();
+  if (length < 0) {
+    vpy_set_error("Internal error: negative array length");
+    goto done;
+  }
+
+  storage = PyByteArray_FromStringAndSize(NULL, (Py_ssize_t)size);
+  if (storage == NULL) {
+    vpy_set_error_from_python();
+    goto done;
+  }
+  if (size > 0) {
+    memset(PyByteArray_AsString(storage), 0, size);
+  }
+
+  g_array = PyObject_CallMethod(vpy_runtime(), "make_array", "Oiiiiii", storage, (int)length, (int)width, (int)height,
+                                (int)depth, (int)bit_width, (int)(is_signed != 0));
+  if (g_array == NULL) {
+    vpy_set_error_from_python();
+    goto done;
+  }
+
+  /* The array keeps the storage alive; we keep our own reference too so the
+   * cached data pointer is valid until the next vpy_clear_arguments(). */
+  g_pending = storage;
+  storage = NULL;
+  g_pending_data = PyByteArray_AsString(g_pending);
+  g_pending_size = size;
+  g_pending_position = 0;
+  status = VPY_OK;
+
+done:
+  Py_XDECREF(storage);
+  PyGILState_Release(gil);
+  return status;
+}
+
+VPY_EXPORT int32_t vpy_array_write(const int32_t *chunk, int32_t length) {
+  size_t bytes;
+
+  if (length <= 0) {
+    return VPY_OK;
+  }
+  bytes = (size_t)length * sizeof(int32_t);
+  if (g_pending_data == NULL || g_pending_position + bytes > g_pending_size) {
+    vpy_set_error("Internal error: array data written out of bounds");
+    return VPY_ERROR;
+  }
+  memcpy(g_pending_data + g_pending_position, chunk, bytes);
+  g_pending_position += bytes;
+  return VPY_OK;
+}
+
+/*
+ * Stage the pushed array in the runtime. Python source code built by VHDL
+ * refers to it as __vunit__.staged(<id>).
+ *
+ * Returns the id (>= 1) or -1 on failure, with the error text set.
+ */
+VPY_EXPORT int32_t vpy_stage(void) {
+  PyGILState_STATE gil;
+  PyObject *id;
+  long value;
+  int32_t result = -1;
+
+  if (vpy_initialize() != VPY_OK || vpy_enter(&gil) != VPY_OK) {
+    return -1;
+  }
+  if (g_array == NULL) {
+    vpy_set_error("Internal error: no value pushed before vpy_stage");
+    goto done;
+  }
+  id = PyObject_CallMethod(vpy_runtime(), "stage_value", "O", g_array);
+  if (id == NULL) {
+    vpy_set_error_from_python();
+    goto done;
+  }
+  value = PyLong_AsLong(id);
+  Py_DECREF(id);
+  if (PyErr_Occurred()) {
+    vpy_set_error_from_python();
+    goto done;
+  }
+  if (value < 1 || value > INT32_MAX) {
+    vpy_set_error("Internal error: invalid staged value id");
+    goto done;
+  }
+  result = (int32_t)value;
+
+done:
+  vpy_clear_arguments();
+  PyGILState_Release(gil);
+  return result;
+}

vunit_python_bridge/native/bridge.h

@@ -0,0 +1,117 @@
+/*
+ * 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
+ *
+ * Internal header of the native bridge between VHDL and an embedded CPython
+ * interpreter. The bridge is a private implementation detail of
+ * python_ffi_pkg: VHDL builds Python source text and the bridge executes or
+ * evaluates it. VHDL reaches the entry points below through VHPIDIRECT on NVC
+ * and GHDL and through the FLI front end in fli.c on Questa/ModelSim.
+ *
+ * Modules:
+ *   error.c        error text reported to VHDL
+ *   config.c       configuration file written by VUnit next to the library
+ *   interpreter.c  starting the interpreter and loading ../runtime.py
+ *   arguments.c    strings and integer_array_t values transferred from VHDL
+ *   operations.c   setup, exec, eval and results transferred back to VHDL
+ *   fli.c          Questa/ModelSim front end, only built for that simulator
+ *
+ * ABI rules, chosen to be identical for NVC and GHDL on all platforms, and
+ * translated to the FLI parameter passing conventions by fli.c:
+ *   - VHDL integer <-> int32_t, VHDL real <-> double.
+ *   - Booleans are passed as integers (0/1), never as VHDL boolean.
+ *   - Strings and integer vectors only cross the boundary as *constrained*
+ *     chunks (plain pointers) with explicit offsets/lengths. Unconstrained
+ *     arrays (fat pointers) are simulator specific and are never used.
+ *   - Every operation that can fail returns a status (VPY_OK or VPY_ERROR).
+ *     The error text is retrieved with vpy_error_length/vpy_error_read.
+ *
+ * Python objects are only touched with the GIL held. Python data symbols
+ * (e.g. Py_None) must not be used: the Windows DLL delay-loads the Python
+ * DLL, which only supports functions.
+ */
+
+#ifndef VUNIT_PYTHON_BRIDGE_H
+#define VUNIT_PYTHON_BRIDGE_H
+
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef Py_GIL_DISABLED
+#error "VHDL Python support does not work with free-threaded CPython builds"
+#endif
+
+#ifdef _WIN32
+#define VPY_EXPORT __declspec(dllexport)
+#else
+#define VPY_EXPORT __attribute__((visibility("default")))
+#endif
+
+#define VPY_OK 0
+#define VPY_ERROR 1
+
+/*
+ * Entry points called from VHDL (declared in python_bridge_pkg.vhd.in,
+ * directly for VHPIDIRECT and through the fli_ prefixed wrappers of fli.c for
+ * the FLI). Strings cross the boundary through a buffer; integer_array_t
+ * values are pushed and staged, everything else is Python source text built
+ * by VHDL.
+ */
+VPY_EXPORT int32_t vpy_setup(void);
+VPY_EXPORT int32_t vpy_cleanup(void);
+VPY_EXPORT int32_t vpy_buffer_clear(void);
+VPY_EXPORT int32_t vpy_buffer_append(const char *chunk, int32_t length);
+VPY_EXPORT int32_t vpy_begin(void);
+VPY_EXPORT int32_t vpy_execute(int32_t is_file);
+VPY_EXPORT int32_t vpy_eval(int32_t kind, int32_t width);
+VPY_EXPORT int32_t 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 int32_t vpy_array_write(const int32_t *chunk, int32_t length);
+VPY_EXPORT int32_t vpy_stage(void);
+VPY_EXPORT int32_t vpy_result_integer(void);
+VPY_EXPORT double vpy_result_real(void);
+VPY_EXPORT int32_t vpy_result_meta(int32_t index);
+VPY_EXPORT void vpy_result_read_string(char *chunk, int32_t offset, int32_t length);
+VPY_EXPORT void vpy_result_read_integers(int32_t *chunk, int32_t offset, int32_t length);
+VPY_EXPORT void vpy_result_read_reals(double *chunk, int32_t offset, int32_t length);
+VPY_EXPORT int32_t vpy_error_length(void);
+VPY_EXPORT void vpy_error_read(char *chunk, int32_t offset, int32_t length);
+
+/* Internal functions shared between the modules */
+
+/* error.c */
+void vpy_set_error(const char *text);
+void vpy_set_error_bytes(const char *text, size_t length);
+void vpy_set_error2(const char *prefix, const char *detail);
+void vpy_set_error_from_python(void); /* GIL held */
+int vpy_has_error(void);
+
+/* config.c */
+typedef struct {
+  char *executable;     /* sys.executable of the Python running VUnit */
+  char *prefix;         /* its sys.prefix, verified by the runtime */
+  char *runtime;        /* path of runtime.py */
+  char *run_script_dir; /* directory of the run script, put on sys.path */
+  char *python_dll;     /* Windows only: path of the Python DLL */
+} vpy_config_t;
+
+int vpy_read_config(vpy_config_t *config);
+
+/* interpreter.c */
+int vpy_initialize(void);
+int vpy_is_initialized(void);
+PyObject *vpy_runtime(void); /* borrowed, NULL before initialization */
+int vpy_enter(PyGILState_STATE *gil);
+int vpy_finish_call(PyObject *ret); /* GIL held, steals ret */
+
+/* arguments.c (GIL held) */
+PyObject *vpy_buffer_as_str(void);
+void vpy_clear_arguments(void);
+
+#endif

vunit_python_bridge/native/config.c

@@ -0,0 +1,201 @@
+/*
+ * 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
+ *
+ * Configuration file written by VUnit next to the bridge library. It tells
+ * the bridge which Python to embed, where the runtime is and the base
+ * directory of relative Python file names.
+ */
+
+#include "bridge.h"
+
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#ifdef _WIN32
+#include <windows.h>
+#define DIRECTORY_SEPARATOR '\\'
+#else
+#include <dlfcn.h>
+#define DIRECTORY_SEPARATOR '/'
+#endif
+
+#define CONFIG_FILE_NAME "vunit_python_bridge.cfg"
+
+/* Return a malloc'ed UTF-8 path of the directory containing this library. */
+static char *get_library_directory(void) {
+  char *path;
+  char *separator;
+#ifdef _WIN32
+  static wchar_t wpath[32768]; /* static: keep it off the simulator stack */
+  HMODULE module = NULL;
+  DWORD length;
+  int utf8_length;
+
+  if (!GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS | GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT,
+                          (LPCWSTR)(void *)&get_library_directory, &module)) {
+    return NULL;
+  }
+  length = GetModuleFileNameW(module, wpath, (DWORD)(sizeof(wpath) / sizeof(wpath[0])));
+  if (length == 0 || length >= sizeof(wpath) / sizeof(wpath[0])) {
+    return NULL;
+  }
+  utf8_length = WideCharToMultiByte(CP_UTF8, 0, wpath, (int)length, NULL, 0, NULL, NULL);
+  if (utf8_length <= 0) {
+    return NULL;
+  }
+  path = (char *)malloc((size_t)utf8_length + 1);
+  if (path == NULL) {
+    return NULL;
+  }
+  WideCharToMultiByte(CP_UTF8, 0, wpath, (int)length, path, utf8_length, NULL, NULL);
+  path[utf8_length] = '\0';
+  separator = strrchr(path, '\\');
+  if (separator == NULL) {
+    separator = strrchr(path, '/');
+  }
+#else
+  Dl_info info;
+
+  if (dladdr((void *)&get_library_directory, &info) == 0 || info.dli_fname == NULL) {
+    return NULL;
+  }
+  path = strdup(info.dli_fname);
+  if (path == NULL) {
+    return NULL;
+  }
+  separator = strrchr(path, '/');
+#endif
+  if (separator == NULL) {
+    free(path);
+    return NULL;
+  }
+  *separator = '\0';
+  return path;
+}
+
+static FILE *open_utf8_path(const char *path) {
+#ifdef _WIN32
+  int length = MultiByteToWideChar(CP_UTF8, 0, path, -1, NULL, 0);
+  wchar_t *wpath;
+  FILE *file;
+
+  if (length <= 0) {
+    return NULL;
+  }
+  wpath = (wchar_t *)malloc(sizeof(wchar_t) * (size_t)length);
+  if (wpath == NULL) {
+    return NULL;
+  }
+  MultiByteToWideChar(CP_UTF8, 0, path, -1, wpath, length);
+  file = _wfopen(wpath, L"rb");
+  free(wpath);
+  return file;
+#else
+  return fopen(path, "rb");
+#endif
+}
+
+/* The configuration file next to this library, opened for reading. */
+static FILE *open_config_file(void) {
+  char *directory = get_library_directory();
+  size_t directory_length;
+  char *path;
+  FILE *file;
+
+  if (directory == NULL) {
+    vpy_set_error("Failed to determine the location of the Python bridge library");
+    return NULL;
+  }
+  directory_length = strlen(directory);
+  path = (char *)malloc(directory_length + 1 + sizeof(CONFIG_FILE_NAME));
+  if (path == NULL) {
+    free(directory);
+    vpy_set_error("Out of memory");
+    return NULL;
+  }
+  memcpy(path, directory, directory_length);
+  path[directory_length] = DIRECTORY_SEPARATOR;
+  memcpy(path + directory_length + 1, CONFIG_FILE_NAME, sizeof(CONFIG_FILE_NAME));
+  free(directory);
+
+  file = open_utf8_path(path);
+  if (file == NULL) {
+    vpy_set_error2("Failed to open the Python bridge configuration file ", path);
+  }
+  free(path);
+  return file;
+}
+
+/* The field of config for a key, NULL for unknown keys. */
+static char **config_field(vpy_config_t *config, const char *key) {
+  static const struct {
+    const char *key;
+    size_t offset;
+  } fields[] = {{"executable", offsetof(vpy_config_t, executable)},
+                {"prefix", offsetof(vpy_config_t, prefix)},
+                {"runtime", offsetof(vpy_config_t, runtime)},
+                {"run_script_dir", offsetof(vpy_config_t, run_script_dir)},
+                {"python_dll", offsetof(vpy_config_t, python_dll)}};
+  size_t index;
+
+  for (index = 0; index < sizeof(fields) / sizeof(fields[0]); index++) {
+    if (strcmp(key, fields[index].key) == 0) {
+      return (char **)((char *)config + fields[index].offset);
+    }
+  }
+  return NULL;
+}
+
+/*
+ * Read the "key=value" lines (UTF-8) of the configuration file into config,
+ * whose fields must be NULL or malloc'ed. Returns VPY_ERROR with the error
+ * text set on failure.
+ */
+int vpy_read_config(vpy_config_t *config) {
+  FILE *file = open_config_file();
+  char line[8192];
+
+  if (file == NULL) {
+    return VPY_ERROR;
+  }
+
+  while (fgets(line, (int)sizeof(line), file) != NULL) {
+    size_t length = strlen(line);
+    char *separator;
+    char **field;
+
+    while (length > 0 && (line[length - 1] == '\n' || line[length - 1] == '\r')) {
+      line[--length] = '\0';
+    }
+    separator = strchr(line, '=');
+    if (separator == NULL) {
+      continue;
+    }
+    *separator = '\0';
+    field = config_field(config, line);
+    if (field != NULL) {
+      free(*field);
+      *field = strdup(separator + 1);
+    }
+  }
+  fclose(file);
+
+  if (config->executable == NULL || config->prefix == NULL || config->runtime == NULL ||
+      config->run_script_dir == NULL) {
+    vpy_set_error("Incomplete Python bridge configuration file");
+    return VPY_ERROR;
+  }
+#ifdef _WIN32
+  if (config->python_dll == NULL) {
+    vpy_set_error("The Python bridge configuration file lacks the Python DLL path");
+    return VPY_ERROR;
+  }
+#endif
+  return VPY_OK;
+}

vunit_python_bridge/native/error.c

@@ -0,0 +1,120 @@
+/*
+ * 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
+ *
+ * Error text of the last failed operation, reported to VHDL.
+ */
+
+#include "bridge.h"
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+/* UTF-8, owned. Sticky when initialization failed. */
+static char *g_error = NULL;
+static size_t g_error_length = 0;
+
+void vpy_set_error_bytes(const char *text, size_t length) {
+  char *copy = (char *)malloc(length + 1);
+
+  free(g_error);
+  g_error = NULL;
+  g_error_length = 0;
+  if (copy == NULL) {
+    return;
+  }
+  memcpy(copy, text, length);
+  copy[length] = '\0';
+  g_error = copy;
+  g_error_length = length;
+}
+
+void vpy_set_error(const char *text) { vpy_set_error_bytes(text, strlen(text)); }
+
+/* prefix may be the current error text, it is copied before being replaced. */
+void vpy_set_error2(const char *prefix, const char *detail) {
+  char text[4096];
+  int length = snprintf(text, sizeof(text), "%s%s", prefix, detail == NULL ? "" : detail);
+
+  vpy_set_error_bytes(text, length < 0 ? 0 : (length < (int)sizeof(text) ? (size_t)length : sizeof(text) - 1));
+}
+
+int vpy_has_error(void) { return g_error != NULL; }
+
+/* New reference to the raised exception, which is cleared. NULL if none. */
+static PyObject *take_exception(void) {
+#if PY_VERSION_HEX >= 0x030C0000
+  return PyErr_GetRaisedException();
+#else
+  PyObject *type, *value, *traceback;
+
+  PyErr_Fetch(&type, &value, &traceback);
+  PyErr_NormalizeException(&type, &value, &traceback);
+  if (value != NULL && traceback != NULL) {
+    PyException_SetTraceback(value, traceback);
+  }
+  Py_XDECREF(type);
+  Py_XDECREF(traceback);
+  return value;
+#endif
+}
+
+/*
+ * Convert the currently raised Python exception into the error text and clear
+ * it. Formatting is delegated to the runtime, which hides bridge-internal
+ * traceback frames; plain str() and a fixed text are the fallbacks.
+ */
+void vpy_set_error_from_python(void) {
+  PyObject *exc = take_exception();
+  PyObject *text = NULL;
+
+  if (exc == NULL) {
+    vpy_set_error("Unknown Python error (no exception set)");
+    return;
+  }
+
+  if (vpy_runtime() != NULL) {
+    text = PyObject_CallMethod(vpy_runtime(), "format_exception", "O", exc);
+    if (text == NULL) {
+      PyErr_Clear();
+    }
+  }
+  if (text == NULL) {
+    text = PyObject_Str(exc);
+    if (text == NULL) {
+      PyErr_Clear();
+    }
+  }
+
+  if (text != NULL && PyUnicode_Check(text)) {
+    Py_ssize_t length;
+    const char *utf8 = PyUnicode_AsUTF8AndSize(text, &length);
+
+    if (utf8 != NULL) {
+      vpy_set_error_bytes(utf8, (size_t)length);
+    } else {
+      PyErr_Clear();
+      vpy_set_error("Python error (message could not be encoded)");
+    }
+  } else {
+    vpy_set_error("Python error (message could not be formatted)");
+  }
+
+  Py_XDECREF(text);
+  Py_DECREF(exc);
+}
+
+VPY_EXPORT int32_t vpy_error_length(void) {
+  return g_error_length > INT32_MAX ? INT32_MAX : (int32_t)g_error_length;
+}
+
+VPY_EXPORT void vpy_error_read(char *chunk, int32_t offset, int32_t length) {
+  if (g_error == NULL || offset < 0 || length <= 0 || (size_t)offset + (size_t)length > g_error_length) {
+    return;
+  }
+  memcpy(chunk, g_error + offset, (size_t)length);
+}