From 68cdd7728a7cc6715bbbff7decfe2b11c3bdf558 Mon Sep 17 00:00:00 2001 From: Open-IOV Date: Wed, 23 Sep 2026 05:44:08 -0400 Subject: Open-IOV: initial public release Open-IOV virtualizes NVIDIA GPUs so that unmodified guest drivers run with real GPU functionality - CUDA first, 3D and video to follow - on unmodified hosts, without a proprietary vGPU license and without patching any driver, firmware or hypervisor. Core principle: emulate the interface, pass through the work. kernel/ open-iov-vfio.ko - host VFIO mdev driver: virtual GPU device (PCI config space, BAR shadows, MSI-X), GSP boot emulation, GSP-RM message-queue/RPC emulation, memory model (GPU-VA to guest-PA discovery) and the semaphore-completion service that advances guest UVM progress. userspace/ libiov.so management API and examples. tools/ guest diagnostics, firmware analysis wrappers, RM probes. scripts/ stack manager, VM harness, build/load/test automation. config/ hardware/version profiles (the portability surface). docs/ documentation tree - start at docs/README.md. wiki/ long-form firmware and protocol deep dives. Status: initialization works end to end for a stock 570.144 Linux guest on Turing (TU104): driver probe, nvidia-smi, the full GSP-RM control battery, object creation and the early CUDA/UVM start-up path. GPU work forwarding - the step that makes CUDA kernels execute on real hardware - is the active work item; see docs/04-implementation/01-known-knowns-and-unknowns.md. License: BSD-3-Clause for the project; GPL-2.0 for kernel modules that link GPL-only kernel interfaces. See LICENSE and docs/09-reference/legal-and-licensing.md. --- userspace/include/libvgpu.h | 238 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 238 insertions(+) create mode 100644 userspace/include/libvgpu.h (limited to 'userspace/include/libvgpu.h') diff --git a/userspace/include/libvgpu.h b/userspace/include/libvgpu.h new file mode 100644 index 0000000..7f6505b --- /dev/null +++ b/userspace/include/libvgpu.h @@ -0,0 +1,238 @@ +/* + * GSP vGPU-IO Userspace Library (libvgpu) + * Simple C API for VF management and GPU operations + */ + +#ifndef _LIBVGPU_H_ +#define _LIBVGPU_H_ + +#include +#include +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/* Error codes */ +typedef enum { + VGPU_OK = 0, + VGPU_ERR_INVALID_ARG = -1, + VGPU_ERR_NO_DEVICE = -2, + VGPU_ERR_NO_MEMORY = -3, + VGPU_ERR_BUSY = -4, + VGPU_ERR_TIMEOUT = -5, + VGPU_ERR_PERMISSION = -6, + VGPU_ERR_NOT_SUPPORTED = -7, + VGPU_ERR_INTERNAL = -8, +} vgpu_error_t; + +/* Memory types */ +typedef enum { + VGPU_MEM_VRAM = 0, + VGPU_MEM_SYSMEM = 1, + VGPU_MEM_UNCACHED = 2, +} vgpu_mem_type_t; + +/* Pin flags */ +#define VGPU_PIN_READ (1 << 0) +#define VGPU_PIN_WRITE (1 << 1) +#define VGPU_PIN_LONGTERM (1 << 2) + +/* WPR flags */ +#define VGPU_WPR_WRITE (1 << 0) +#define VGPU_WPR_READ (1 << 1) +#define VGPU_WPR_EXECUTE (1 << 2) + +/* Migration phases */ +typedef enum { + VGPU_MIG_QUERY = 0, + VGPU_MIG_PREPARE = 1, + VGPU_MIG_TRANSFER = 2, + VGPU_MIG_COMMIT = 3, + VGPU_MIG_CLEANUP = 4, +} vgpu_mig_phase_t; + +/* Migration flags */ +#define VGPU_MIG_LIVE (1 << 0) +#define VGPU_MIG_POSTCOPY (1 << 1) +#define VGPU_MIG_AUTO_COMMIT (1 << 2) +#define VGPU_MIG_VERIFY (1 << 3) + +/* VF Configuration */ +typedef struct { + uint32_t id; + uint64_t bar1_offset; + uint64_t bar1_size; + uint64_t pt_base; + uint64_t pt_size; + uint64_t cmd_base; + uint64_t cmd_size; + uint32_t max_memory_mb; + uint32_t num_engines; +} vgpu_vf_config_t; + +/* VF Handle */ +typedef struct vgpu_vf *vgpu_vf_t; + +/* Device Handle */ +typedef struct vgpu_device *vgpu_device_t; + +/* Allocation Handle */ +typedef uint64_t vgpu_handle_t; + +/* ============================================================ + * Device Management + * ============================================================ */ + +/* Open GSP device */ +vgpu_error_t vgpu_open(const char *device_path, vgpu_device_t *device); + +/* Close GSP device */ +void vgpu_close(vgpu_device_t device); + +/* Get device info */ +vgpu_error_t vgpu_get_info(vgpu_device_t device, char *buf, size_t len); + +/* ============================================================ + * VF Management + * ============================================================ */ + +/* Create VF */ +vgpu_error_t vgpu_vf_create(vgpu_device_t device, const vgpu_vf_config_t *config, vgpu_vf_t *vf); + +/* Destroy VF */ +vgpu_error_t vgpu_vf_destroy(vgpu_vf_t vf); + +/* Get VF info */ +vgpu_error_t vgpu_vf_get_info(vgpu_vf_t vf, char *buf, size_t len); + +/* ============================================================ + * Memory Management + * ============================================================ */ + +/* Allocate GPU memory */ +vgpu_error_t vgpu_mem_alloc(vgpu_vf_t vf, uint64_t size, vgpu_mem_type_t type, + uint64_t alignment, uint64_t va_hint, + uint32_t flags, vgpu_handle_t *handle, uint64_t *va); + +/* Free GPU memory */ +vgpu_error_t vgpu_mem_free(vgpu_vf_t vf, vgpu_handle_t handle); + +/* Map memory to VF address space */ +vgpu_error_t vgpu_mem_map(vgpu_vf_t vf, vgpu_handle_t handle, uint64_t gpu_va, + uint64_t size, uint32_t prot, uint32_t flags, + uint64_t offset, uint64_t *mapped_va); + +/* Unmap memory */ +vgpu_error_t vgpu_mem_unmap(vgpu_vf_t vf, vgpu_handle_t handle, uint64_t gpu_va, uint64_t size); + +/* Pin pages for DMA */ +vgpu_error_t vgpu_mem_pin(vgpu_vf_t vf, vgpu_handle_t handle, uint64_t offset, + uint64_t size, uint32_t flags, uint64_t *dma_addr); + +/* Unpin pages */ +vgpu_error_t vgpu_mem_unpin(vgpu_vf_t vf, vgpu_handle_t handle, uint64_t offset, uint64_t size); + +/* ============================================================ + * BAR Emulation + * ============================================================ */ + +/* Configure BAR1 aperture */ +vgpu_error_t vgpu_bar_config(vgpu_vf_t vf, uint64_t offset, uint64_t size); + +/* Enable/disable ForceBarAccess */ +vgpu_error_t vgpu_bar_force_access(vgpu_vf_t vf, bool enable); + +/* Save BAR state for migration */ +vgpu_error_t vgpu_bar_save(vgpu_vf_t vf, void *buf, size_t *size); + +/* Restore BAR state after migration */ +vgpu_error_t vgpu_bar_restore(vgpu_vf_t vf, const void *buf, size_t size); + +/* ============================================================ + * WPR (Write/Read Protect Region) + * ============================================================ */ + +/* Protect memory region (write) */ +vgpu_error_t vgpu_wpr_protect_write(vgpu_vf_t vf, uint64_t base, uint64_t size); + +/* Protect memory region (read) */ +vgpu_error_t vgpu_wpr_protect_read(vgpu_vf_t vf, uint64_t base, uint64_t size); + +/* Unprotect memory region */ +vgpu_error_t vgpu_wpr_unprotect(vgpu_vf_t vf, uint64_t base); + +/* Set WPR timeout */ +vgpu_error_t vgpu_wpr_set_timeout(vgpu_vf_t vf, uint64_t timeout_ns); + +/* Register WPR callback */ +typedef void (*vgpu_wpr_callback_t)(vgpu_vf_t vf, uint64_t addr, uint32_t type, void *ctx); +vgpu_error_t vgpu_wpr_register_callback(vgpu_vf_t vf, uint32_t event_type, + vgpu_wpr_callback_t cb, void *ctx); + +/* ============================================================ + * Scheduling + * ============================================================ */ + +/* Schedule work on VF */ +vgpu_error_t vgpu_schedule(vgpu_vf_t vf, uint64_t work_handle, uint64_t callback, + uint64_t arg, uint32_t priority, uint32_t flags); + +/* Yield VF timeslice */ +vgpu_error_t vgpu_yield(vgpu_vf_t vf); + +/* ============================================================ + * Migration + * ============================================================ */ + +/* Start live migration */ +vgpu_error_t vgpu_migrate_start(vgpu_vf_t vf, uint64_t dst_vf, uint32_t flags); + +/* Check migration status */ +vgpu_error_t vgpu_migrate_status(vgpu_vf_t vf, vgpu_mig_phase_t *phase, uint64_t *progress); + +/* Cancel migration */ +vgpu_error_t vgpu_migrate_cancel(vgpu_vf_t vf); + +/* ============================================================ + * Error Handling + * ============================================================ */ + +/* Get error string */ +const char *vgpu_strerror(vgpu_error_t err); + +/* ============================================================ + * Event Handling (async) + * ============================================================ */ + +/* Event types */ +typedef enum { + VGPU_EVENT_WPR_WRITE_COMPLETE = 0, + VGPU_EVENT_WPR_READ_COMPLETE = 1, + VGPU_EVENT_WPR_WRITE_TIMEOUT = 2, + VGPU_EVENT_WPR_READ_TIMEOUT = 3, + VGPU_EVENT_MIGRATION_PROGRESS = 4, + VGPU_EVENT_MIGRATION_COMPLETE = 5, + VGPU_EVENT_VF_ERROR = 6, +} vgpu_event_type_t; + +/* Event callback */ +typedef void (*vgpu_event_callback_t)(vgpu_vf_t vf, vgpu_event_type_t type, + void *data, size_t size, void *ctx); + +/* Register event callback */ +vgpu_error_t vgpu_register_event_callback(vgpu_vf_t vf, vgpu_event_type_t type, + vgpu_event_callback_t cb, void *ctx); + +/* Unregister event callback */ +vgpu_error_t vgpu_unregister_event_callback(vgpu_vf_t vf, vgpu_event_type_t type); + +/* Process pending events (call periodically) */ +vgpu_error_t vgpu_process_events(vgpu_device_t device, int timeout_ms); + +#ifdef __cplusplus +} +#endif + +#endif /* _LIBVGPU_H_ */ \ No newline at end of file -- cgit v1.2.3