/* * 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_ */