Initial commit: Open-IOV vGPU-IO complete stack

- Firmware decompilation: GSP 570.144W (28.5MB ELF, RV64IMAC), 132 decompiled C files
- Kernel modules: nvidia.ko (34MB, OpenRM), open-iov-vfio.ko (2.8MB, VFIO mdev), gsp-vgpu.ko (1.8MB, guest driver)
- Userspace: libiov.so/libvgpu.so (76KB), example_vgpu (28KB), rpc_emulator.c
- PCI config space emulation (256B with PM, MSI, MSI-X, PCIe caps)
- 12 RPC types fully mapped from firmware decompilation
- BAR trap, WPR, scheduling, notification, migration emulation
- Helper scripts: load_vgpu_stack, create_mdev, launch_qemu_vgpu, test_vgpu_stack, setup_guest_driver, unload_vgpu_stack
- Architecture documentation
- Wiki: 10 technical documents
- Git LFS for large binaries (.ko, .bin, .iso, .img, .o, ghidra repos)
- nvidia-open-gpu-kernel-modules as submodule

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