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.

1 files changed, 238 insertions, 0 deletions

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 <stdint.h>
+#include <stddef.h>
+#include <stdbool.h>
+
+#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