.TH "vGPU Migration" 3 "24 Apr 2019" "Version 1.1" "NVML" \" -*- nroff -*-
.ad l
.nh
.SH NAME
vGPU Migration \- 
.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBnvmlVgpuVersion_t\fP"
.br
.ti -1c
.RI "struct \fBnvmlVgpuMetadata_t\fP"
.br
.ti -1c
.RI "struct \fBnvmlVgpuPgpuMetadata_t\fP"
.br
.ti -1c
.RI "struct \fBnvmlVgpuPgpuCompatibility_t\fP"
.br
.in -1c
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBnvmlVgpuVmCompatibility_t\fP { \fBNVML_VGPU_VM_COMPATIBILITY_NONE\fP =  0x0, \fBNVML_VGPU_VM_COMPATIBILITY_COLD\fP =  0x1, \fBNVML_VGPU_VM_COMPATIBILITY_HIBERNATE\fP =  0x2, \fBNVML_VGPU_VM_COMPATIBILITY_SLEEP\fP =  0x4, \fBNVML_VGPU_VM_COMPATIBILITY_LIVE\fP =  0x8 }"
.br
.ti -1c
.RI "enum \fBnvmlVgpuPgpuCompatibilityLimitCode_t\fP { \fBNVML_VGPU_COMPATIBILITY_LIMIT_NONE\fP =  0x0, \fBNVML_VGPU_COMPATIBILITY_LIMIT_HOST_DRIVER\fP =  0x1, \fBNVML_VGPU_COMPATIBILITY_LIMIT_GUEST_DRIVER\fP =  0x2, \fBNVML_VGPU_COMPATIBILITY_LIMIT_GPU\fP =  0x4, \fBNVML_VGPU_COMPATIBILITY_LIMIT_OTHER\fP =  0x80000000 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBnvmlReturn_t\fP DECLDIR \fBnvmlVgpuInstanceGetMetadata\fP (nvmlVgpuInstance_t vgpuInstance, \fBnvmlVgpuMetadata_t\fP *vgpuMetadata, unsigned int *bufferSize)"
.br
.ti -1c
.RI "\fBnvmlReturn_t\fP DECLDIR \fBnvmlDeviceGetVgpuMetadata\fP (nvmlDevice_t device, \fBnvmlVgpuPgpuMetadata_t\fP *pgpuMetadata, unsigned int *bufferSize)"
.br
.ti -1c
.RI "\fBnvmlReturn_t\fP DECLDIR \fBnvmlGetVgpuCompatibility\fP (\fBnvmlVgpuMetadata_t\fP *vgpuMetadata, \fBnvmlVgpuPgpuMetadata_t\fP *pgpuMetadata, \fBnvmlVgpuPgpuCompatibility_t\fP *compatibilityInfo)"
.br
.ti -1c
.RI "\fBnvmlReturn_t\fP DECLDIR \fBnvmlGetVgpuVersion\fP (\fBnvmlVgpuVersion_t\fP *supported, \fBnvmlVgpuVersion_t\fP *current)"
.br
.ti -1c
.RI "\fBnvmlReturn_t\fP DECLDIR \fBnvmlSetVgpuVersion\fP (\fBnvmlVgpuVersion_t\fP *vgpuVersion)"
.br
.in -1c
.SH "Detailed Description"
.PP 
This chapter describes NVML operations that are associated with vGPU Migration. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBnvmlVgpuPgpuCompatibilityLimitCode_t\fP"
.PP
vGPU-pGPU compatibility limit codes 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fINVML_VGPU_COMPATIBILITY_LIMIT_NONE \fP\fP
Compatibility is not limited. 
.TP
\fB\fINVML_VGPU_COMPATIBILITY_LIMIT_HOST_DRIVER \fP\fP
ompatibility is limited by host driver version. 
.TP
\fB\fINVML_VGPU_COMPATIBILITY_LIMIT_GUEST_DRIVER \fP\fP
Compatibility is limited by guest driver version. 
.TP
\fB\fINVML_VGPU_COMPATIBILITY_LIMIT_GPU \fP\fP
Compatibility is limited by GPU hardware. 
.TP
\fB\fINVML_VGPU_COMPATIBILITY_LIMIT_OTHER \fP\fP
Compatibility is limited by an undefined factor. 
.SS "enum \fBnvmlVgpuVmCompatibility_t\fP"
.PP
vGPU VM compatibility codes 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fINVML_VGPU_VM_COMPATIBILITY_NONE \fP\fP
vGPU is not runnable 
.TP
\fB\fINVML_VGPU_VM_COMPATIBILITY_COLD \fP\fP
vGPU is runnable from a cold / powered-off state (ACPI S5) 
.TP
\fB\fINVML_VGPU_VM_COMPATIBILITY_HIBERNATE \fP\fP
vGPU is runnable from a hibernated state (ACPI S4) 
.TP
\fB\fINVML_VGPU_VM_COMPATIBILITY_SLEEP \fP\fP
vGPU is runnable from a sleeped state (ACPI S3) 
.TP
\fB\fINVML_VGPU_VM_COMPATIBILITY_LIVE \fP\fP
vGPU is runnable from a live/paused (ACPI S0) 
.SH "Function Documentation"
.PP 
.SS "\fBnvmlReturn_t\fP DECLDIR nvmlDeviceGetVgpuMetadata (nvmlDevice_t device, \fBnvmlVgpuPgpuMetadata_t\fP * pgpuMetadata, unsigned int * bufferSize)"
.PP
Returns a vGPU metadata structure for the physical GPU indicated by \fIdevice\fP. 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.
.PP
The caller passes in a buffer via \fIpgpuMetadata\fP, with the size of the buffer in \fIbufferSize\fP. If the \fIpgpuMetadata\fP structure is too large to fit in the supplied buffer, the function returns NVML_ERROR_INSUFFICIENT_SIZE with the size needed in \fIbufferSize\fP.
.PP
\fBParameters:\fP
.RS 4
\fIdevice\fP The identifier of the target device 
.br
\fIpgpuMetadata\fP Pointer to caller-supplied buffer into which \fIpgpuMetadata\fP is written 
.br
\fIbufferSize\fP Pointer to size of \fIpgpuMetadata\fP buffer
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
\fBNVML_SUCCESS\fP GPU metadata structure was successfully returned
.IP "\(bu" 2
\fBNVML_ERROR_INSUFFICIENT_SIZE\fP pgpuMetadata buffer is too small, required size is returned in \fIbufferSize\fP 
.IP "\(bu" 2
\fBNVML_ERROR_INVALID_ARGUMENT\fP if \fIbufferSize\fP is NULL or \fIdevice\fP is invalid; if \fIpgpuMetadata\fP is NULL and the value of \fIbufferSize\fP is not 0.
.IP "\(bu" 2
\fBNVML_ERROR_NOT_SUPPORTED\fP vGPU is not supported by the system
.IP "\(bu" 2
\fBNVML_ERROR_UNKNOWN\fP on any unexpected error 
.PP
.RE
.PP

.SS "\fBnvmlReturn_t\fP DECLDIR nvmlGetVgpuCompatibility (\fBnvmlVgpuMetadata_t\fP * vgpuMetadata, \fBnvmlVgpuPgpuMetadata_t\fP * pgpuMetadata, \fBnvmlVgpuPgpuCompatibility_t\fP * compatibilityInfo)"
.PP
Takes a vGPU instance metadata structure read from \fBnvmlVgpuInstanceGetMetadata()\fP, and a vGPU metadata structure for a physical GPU read from \fBnvmlDeviceGetVgpuMetadata()\fP, and returns compatibility information of the vGPU instance and the physical GPU.
.PP
The caller passes in a buffer via \fIcompatibilityInfo\fP, 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 \fBnvmlVgpuPgpuCompatibilityLimitCode_t\fP for details).
.PP
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.
.PP
\fBParameters:\fP
.RS 4
\fIvgpuMetadata\fP Pointer to caller-supplied vGPU metadata structure 
.br
\fIpgpuMetadata\fP Pointer to caller-supplied GPU metadata structure 
.br
\fIcompatibilityInfo\fP Pointer to caller-supplied buffer to hold compatibility info
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
\fBNVML_SUCCESS\fP vGPU metadata structure was successfully returned
.IP "\(bu" 2
\fBNVML_ERROR_INVALID_ARGUMENT\fP if \fIvgpuMetadata\fP or \fIpgpuMetadata\fP or \fIbufferSize\fP are NULL
.IP "\(bu" 2
\fBNVML_ERROR_UNKNOWN\fP on any unexpected error 
.PP
.RE
.PP

.SS "\fBnvmlReturn_t\fP DECLDIR nvmlGetVgpuVersion (\fBnvmlVgpuVersion_t\fP * supported, \fBnvmlVgpuVersion_t\fP * current)"
.PP
Query the ranges of supported vGPU versions.
.PP
This function gets the linear range of supported vGPU versions that is preset for the NVIDIA vGPU Manager and the range set by an administrator. If the preset range has not been overridden by \fBnvmlSetVgpuVersion\fP, both ranges are the same.
.PP
The caller passes pointers to the following \fBnvmlVgpuVersion_t\fP structures, into which the NVIDIA vGPU Manager writes the ranges: 1. \fIsupported\fP structure that represents the preset range of vGPU versions supported by the NVIDIA vGPU Manager. 2. \fIcurrent\fP structure that represents the range of supported vGPU versions set by an administrator. By default, this range is the same as the preset range.
.PP
\fBParameters:\fP
.RS 4
\fIsupported\fP Pointer to the structure in which the preset range of vGPU versions supported by the NVIDIA vGPU Manager is written 
.br
\fIcurrent\fP Pointer to the structure in which the range of supported vGPU versions set by an administrator is written
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
\fBNVML_SUCCESS\fP The vGPU version range structures were successfully obtained.
.IP "\(bu" 2
\fBNVML_ERROR_NOT_SUPPORTED\fP The API is not supported.
.IP "\(bu" 2
\fBNVML_ERROR_INVALID_ARGUMENT\fP The \fIsupported\fP parameter or the \fIcurrent\fP parameter is NULL.
.IP "\(bu" 2
\fBNVML_ERROR_UNKNOWN\fP An error occurred while the data was being fetched. 
.PP
.RE
.PP

.SS "\fBnvmlReturn_t\fP DECLDIR nvmlSetVgpuVersion (\fBnvmlVgpuVersion_t\fP * vgpuVersion)"
.PP
Override the preset range of vGPU versions supported by the NVIDIA vGPU Manager with a range set by an administrator.
.PP
This function configures the NVIDIA vGPU Manager with a range of supported vGPU versions set by an administrator. This range must be a subset of the preset range that the NVIDIA vGPU Manager supports. The custom range set by an administrator takes precedence over the preset range and is advertised to the guest VM for negotiating the vGPU version. See \fBnvmlGetVgpuVersion\fP for details of how to query the preset range of versions supported.
.PP
This function takes a pointer to vGPU version range structure \fBnvmlVgpuVersion_t\fP as input to override the preset vGPU version range that the NVIDIA vGPU Manager supports.
.PP
After host system reboot or driver reload, the range of supported versions reverts to the range that is preset for the NVIDIA vGPU Manager.
.PP
\fBNote:\fP
.RS 4
1. The range set by the administrator must be a subset of the preset range that the NVIDIA vGPU Manager supports. Otherwise, an error is returned. 2. If the range of supported guest driver versions does not overlap the range set by the administrator, the guest driver fails to load. 3. If the range of supported guest driver versions overlaps the range set by the administrator, the guest driver will load with a negotiated vGPU version that is the maximum value in the overlapping range. 4. No VMs must be running on the host when this function is called. If a VM is running on the host, the call to this function fails.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIvgpuVersion\fP Pointer to a caller-supplied range of supported vGPU versions.
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
\fBNVML_SUCCESS\fP The preset range of supported vGPU versions was successfully overridden.
.IP "\(bu" 2
\fBNVML_ERROR_NOT_SUPPORTED\fP The API is not supported.
.IP "\(bu" 2
\fBNVML_ERROR_IN_USE\fP The range was not overridden because a VM is running on the host.
.IP "\(bu" 2
\fBNVML_ERROR_INVALID_ARGUMENT\fP The \fIvgpuVersion\fP parameter specifies a range that is outside the range supported by the NVIDIA vGPU Manager or if \fIvgpuVersion\fP is NULL. 
.PP
.RE
.PP

.SS "\fBnvmlReturn_t\fP DECLDIR nvmlVgpuInstanceGetMetadata (nvmlVgpuInstance_t vgpuInstance, \fBnvmlVgpuMetadata_t\fP * vgpuMetadata, unsigned int * bufferSize)"
.PP
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.
.PP
\fBnvmlVgpuInstanceGetMetadata()\fP 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 \fBnvmlVgpuGuestInfoState_t\fP field.
.PP
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.
.PP
The caller passes in a buffer via \fIvgpuMetadata\fP, with the size of the buffer in \fIbufferSize\fP. 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 \fIbufferSize\fP.
.PP
\fBParameters:\fP
.RS 4
\fIvgpuInstance\fP vGPU instance handle 
.br
\fIvgpuMetadata\fP Pointer to caller-supplied buffer into which vGPU metadata is written 
.br
\fIbufferSize\fP Size of vgpuMetadata buffer
.RE
.PP
\fBReturns:\fP
.RS 4
.IP "\(bu" 2
\fBNVML_SUCCESS\fP vGPU metadata structure was successfully returned
.IP "\(bu" 2
\fBNVML_ERROR_INSUFFICIENT_SIZE\fP vgpuMetadata buffer is too small, required size is returned in \fIbufferSize\fP 
.IP "\(bu" 2
\fBNVML_ERROR_INVALID_ARGUMENT\fP if \fIbufferSize\fP is NULL or \fIvgpuInstance\fP is 0; if \fIvgpuMetadata\fP is NULL and the value of \fIbufferSize\fP is not 0.
.IP "\(bu" 2
\fBNVML_ERROR_NOT_FOUND\fP if \fIvgpuInstance\fP does not match a valid active vGPU instance on the system
.IP "\(bu" 2
\fBNVML_ERROR_UNKNOWN\fP on any unexpected error 
.PP
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for NVML from the source code.