NVML API Reference Guide (PDF) - vR418 (older) - Last updated August 14, 2019 - Send Feedback

4.28. vGPU Migration

This chapter describes NVML operations that are associated with vGPU Migration.

Classes

struct 
struct 
struct 
struct 

Enumerations

enum nvmlVgpuPgpuCompatibilityLimitCode_t
enum nvmlVgpuVmCompatibility_t

Functions

nvmlReturn_t nvmlDeviceGetVgpuMetadata ( nvmlDevice_t device, nvmlVgpuPgpuMetadata_t* pgpuMetadata, unsigned int* bufferSize )
nvmlReturn_t nvmlGetVgpuCompatibility ( nvmlVgpuMetadata_t* vgpuMetadata, nvmlVgpuPgpuMetadata_t* pgpuMetadata, nvmlVgpuPgpuCompatibility_t* compatibilityInfo )
nvmlReturn_t nvmlGetVgpuVersion ( nvmlVgpuVersion_t* supported, nvmlVgpuVersion_t* current )
nvmlReturn_t nvmlSetVgpuVersion ( nvmlVgpuVersion_t* vgpuVersion )
nvmlReturn_t nvmlVgpuInstanceGetMetadata ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuMetadata_t* vgpuMetadata, unsigned int* bufferSize )

Enumerations

enum nvmlVgpuPgpuCompatibilityLimitCode_t

vGPU-pGPU compatibility limit codes

Values
NVML_VGPU_COMPATIBILITY_LIMIT_NONE = 0x0
Compatibility is not limited.
NVML_VGPU_COMPATIBILITY_LIMIT_HOST_DRIVER = 0x1
ompatibility is limited by host driver version.
NVML_VGPU_COMPATIBILITY_LIMIT_GUEST_DRIVER = 0x2
Compatibility is limited by guest driver version.
NVML_VGPU_COMPATIBILITY_LIMIT_GPU = 0x4
Compatibility is limited by GPU hardware.
NVML_VGPU_COMPATIBILITY_LIMIT_OTHER = 0x80000000
Compatibility is limited by an undefined factor.
enum nvmlVgpuVmCompatibility_t

vGPU VM compatibility codes

Values
NVML_VGPU_VM_COMPATIBILITY_NONE = 0x0
vGPU is not runnable
NVML_VGPU_VM_COMPATIBILITY_COLD = 0x1
vGPU is runnable from a cold / powered-off state (ACPI S5)
NVML_VGPU_VM_COMPATIBILITY_HIBERNATE = 0x2
vGPU is runnable from a hibernated state (ACPI S4)
NVML_VGPU_VM_COMPATIBILITY_SLEEP = 0x4
vGPU is runnable from a sleeped state (ACPI S3)
NVML_VGPU_VM_COMPATIBILITY_LIVE = 0x8
vGPU is runnable from a live/paused (ACPI S0)

Functions

nvmlReturn_t nvmlDeviceGetVgpuMetadata ( nvmlDevice_t device, nvmlVgpuPgpuMetadata_t* pgpuMetadata, unsigned int* bufferSize )
Parameters
device
The identifier of the target device
pgpuMetadata
Pointer to caller-supplied buffer into which pgpuMetadata is written
bufferSize
Pointer to size of pgpuMetadata buffer
Returns

Description

Returns a vGPU metadata structure for the physical GPU indicated by device. The structure contains information about the GPU and the currently installed NVIDIA host driver version that's controlling it, together with an opaque data section containing internal state.

The caller passes in a buffer via pgpuMetadata, with the size of the buffer in bufferSize. If the pgpuMetadata structure is too large to fit in the supplied buffer, the function returns NVML_ERROR_INSUFFICIENT_SIZE with the size needed in bufferSize.

nvmlReturn_t nvmlGetVgpuCompatibility ( nvmlVgpuMetadata_t* vgpuMetadata, nvmlVgpuPgpuMetadata_t* pgpuMetadata, nvmlVgpuPgpuCompatibility_t* compatibilityInfo )
Parameters
vgpuMetadata
Pointer to caller-supplied vGPU metadata structure
pgpuMetadata
Pointer to caller-supplied GPU metadata structure
compatibilityInfo
Pointer to caller-supplied buffer to hold compatibility info
Returns

Description

Takes a vGPU instance metadata structure read from nvmlVgpuInstanceGetMetadata(), and a vGPU metadata structure for a physical GPU read from nvmlDeviceGetVgpuMetadata(), and returns compatibility information of the vGPU instance and the physical GPU.

The caller passes in a buffer via compatibilityInfo, into which a compatibility information structure is written. The structure defines the states in which the vGPU / VM may be booted on the physical GPU. If the vGPU / VM compatibility with the physical GPU is limited, a limit code indicates the factor limiting compability. (see nvmlVgpuPgpuCompatibilityLimitCode_t for details).

Note: vGPU compatibility does not take into account dynamic capacity conditions that may limit a system's ability to boot a given vGPU or associated VM.

nvmlReturn_t nvmlGetVgpuVersion ( nvmlVgpuVersion_t* supported, nvmlVgpuVersion_t* current )
Parameters
supported
Pointer to caller-supplied structure into which the supported vGPU version range is returned
current
Pointer to caller-supplied structure into which the caller enforced supported vGPU version range is returned.
Returns

Description

Returns the following two version range structures nvmlVgpuVersion_t : 1. supported : structure representing the range of vGPU versions supported by the host; 2. current : structure representing the range of supported versions enforced by the caller via nvmlSetVgpuVersion().

The caller pass in the pointer to the structures, into which the compatible ranges are written.

Note:

: 1. The guest driver will fail to load if the version is below the range returned in the current structure. 2. If the guest driver is above the range, it will be downgraded to the current structure maximum version.

nvmlReturn_t nvmlSetVgpuVersion ( nvmlVgpuVersion_t* vgpuVersion )
Parameters
vgpuVersion
Pointer to caller-supplied vGPU supported version range.
Returns

Description

Takes a vGPU version range structure nvmlVgpuVersion_t and set the vGPU compatible version range to the one provided as input. The caller should call the nvmlGetVgpuVersion() to get the range of supported version by the host driver.

Note:

: 1. The guest driver will fail to load if the version is below the range set via vgpuVersion structure. 2. If the guest driver is above the range, it will be downgraded to the vgpuVersion structure maximum version. 3. This will result error if there are VMs already active on the host or the supported range being set is outside the range supported by host driver.

nvmlReturn_t nvmlVgpuInstanceGetMetadata ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuMetadata_t* vgpuMetadata, unsigned int* bufferSize )
Parameters
vgpuInstance
vGPU instance handle
vgpuMetadata
Pointer to caller-supplied buffer into which vGPU metadata is written
bufferSize
Size of vgpuMetadata buffer
Returns

Description

Returns vGPU metadata structure for a running vGPU. The structure contains information about the vGPU and its associated VM such as the currently installed NVIDIA guest driver version, together with host driver version and an opaque data section containing internal state.

nvmlVgpuInstanceGetMetadata() may be called at any time for a vGPU instance. Some fields in the returned structure are dependent on information obtained from the guest VM, which may not yet have reached a state where that information is available. The current state of these dependent fields is reflected in the info structure's nvmlVgpuGuestInfoState_t field.

The VMM may choose to read and save the vGPU's VM info as persistent metadata associated with the VM, and provide it to GRID Virtual GPU Manager when creating a vGPU for subsequent instances of the VM.

The caller passes in a buffer via vgpuMetadata, with the size of the buffer in bufferSize. If the vGPU Metadata structure is too large to fit in the supplied buffer, the function returns NVML_ERROR_INSUFFICIENT_SIZE with the size needed in bufferSize.


NVML API Reference Guide (PDF) - vR418 (older) - Last updated August 14, 2019 - Send Feedback