From 00e54c13c7c9030c4d5f7151467f2d85a3730e29 Mon Sep 17 00:00:00 2001 From: Arthur Hanson Rasmusson Date: Sun, 13 Sep 2026 18:36:21 -0400 Subject: 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 --- 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