NVML API Reference Guide (PDF) - vR470 (older) - Last updated July 29, 2021 - Send Feedback

2.23. vGPU Management

This chapter describes APIs supporting NVIDIA vGPU.

Functions

nvmlReturn_t nvmlDeviceGetActiveVgpus ( nvmlDevice_t device, unsigned int* vgpuCount, nvmlVgpuInstance_t* vgpuInstances )
nvmlReturn_t nvmlDeviceGetCreatableVgpus ( nvmlDevice_t device, unsigned int* vgpuCount, nvmlVgpuTypeId_t* vgpuTypeIds )
nvmlReturn_t nvmlDeviceGetSupportedVgpus ( nvmlDevice_t device, unsigned int* vgpuCount, nvmlVgpuTypeId_t* vgpuTypeIds )
nvmlReturn_t nvmlVgpuInstanceGetEccMode ( nvmlVgpuInstance_t vgpuInstance, nvmlEnableState_t* eccMode )
nvmlReturn_t nvmlVgpuInstanceGetEncoderCapacity ( nvmlVgpuInstance_t vgpuInstance, unsigned int* encoderCapacity )
nvmlReturn_t nvmlVgpuInstanceGetEncoderSessions ( nvmlVgpuInstance_t vgpuInstance, unsigned int* sessionCount, nvmlEncoderSessionInfo_t* sessionInfo )
nvmlReturn_t nvmlVgpuInstanceGetEncoderStats ( nvmlVgpuInstance_t vgpuInstance, unsigned int* sessionCount, unsigned int* averageFps, unsigned int* averageLatency )
nvmlReturn_t nvmlVgpuInstanceGetFBCSessions ( nvmlVgpuInstance_t vgpuInstance, unsigned int* sessionCount, nvmlFBCSessionInfo_t* sessionInfo )
nvmlReturn_t nvmlVgpuInstanceGetFBCStats ( nvmlVgpuInstance_t vgpuInstance, nvmlFBCStats_t* fbcStats )
nvmlReturn_t nvmlVgpuInstanceGetFbUsage ( nvmlVgpuInstance_t vgpuInstance, unsigned long long* fbUsage )
nvmlReturn_t nvmlVgpuInstanceGetFrameRateLimit ( nvmlVgpuInstance_t vgpuInstance, unsigned int* frameRateLimit )
nvmlReturn_t nvmlVgpuInstanceGetGpuInstanceId ( nvmlVgpuInstance_t vgpuInstance, unsigned int* gpuInstanceId )
nvmlReturn_t nvmlVgpuInstanceGetLicenseStatus ( nvmlVgpuInstance_t vgpuInstance, unsigned int* licensed )
nvmlReturn_t nvmlVgpuInstanceGetType ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuTypeId_t* vgpuTypeId )
nvmlReturn_t nvmlVgpuInstanceGetUUID ( nvmlVgpuInstance_t vgpuInstance, char* uuid, unsigned int  size )
nvmlReturn_t nvmlVgpuInstanceGetVmDriverVersion ( nvmlVgpuInstance_t vgpuInstance, char* version, unsigned int  length )
nvmlReturn_t nvmlVgpuInstanceGetVmID ( nvmlVgpuInstance_t vgpuInstance, char* vmId, unsigned int  size, nvmlVgpuVmIdType_t* vmIdType )
nvmlReturn_t nvmlVgpuInstanceSetEncoderCapacity ( nvmlVgpuInstance_t vgpuInstance, unsigned int  encoderCapacity )
nvmlReturn_t nvmlVgpuTypeGetClass ( nvmlVgpuTypeId_t vgpuTypeId, char* vgpuTypeClass, unsigned int* size )
nvmlReturn_t nvmlVgpuTypeGetDeviceID ( nvmlVgpuTypeId_t vgpuTypeId, unsigned long long* deviceID, unsigned long long* subsystemID )
nvmlReturn_t nvmlVgpuTypeGetFrameRateLimit ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* frameRateLimit )
nvmlReturn_t nvmlVgpuTypeGetFramebufferSize ( nvmlVgpuTypeId_t vgpuTypeId, unsigned long long* fbSize )
nvmlReturn_t nvmlVgpuTypeGetGpuInstanceProfileId ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* gpuInstanceProfileId )
nvmlReturn_t nvmlVgpuTypeGetLicense ( nvmlVgpuTypeId_t vgpuTypeId, char* vgpuTypeLicenseString, unsigned int  size )
nvmlReturn_t nvmlVgpuTypeGetMaxInstances ( nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId, unsigned int* vgpuInstanceCount )
nvmlReturn_t nvmlVgpuTypeGetMaxInstancesPerVm ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* vgpuInstanceCountPerVm )
nvmlReturn_t nvmlVgpuTypeGetName ( nvmlVgpuTypeId_t vgpuTypeId, char* vgpuTypeName, unsigned int* size )
nvmlReturn_t nvmlVgpuTypeGetNumDisplayHeads ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* numDisplayHeads )
nvmlReturn_t nvmlVgpuTypeGetResolution ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int  displayIndex, unsigned int* xdim, unsigned int* ydim )

Functions

nvmlReturn_t nvmlDeviceGetActiveVgpus ( nvmlDevice_t device, unsigned int* vgpuCount, nvmlVgpuInstance_t* vgpuInstances )
Parameters
device
The identifier of the target device
vgpuCount
Pointer which passes in the array size as well as get back the number of types
vgpuInstances
Pointer to array in which to return list of vGPU instances
Returns

Description

Retrieve the active vGPU instances on a device.

An array of active vGPU instances is returned in the caller-supplied buffer pointed at by vgpuInstances. The array elememt count is passed in vgpuCount, and vgpuCount is used to return the number of vGPU instances written to the buffer.

If the supplied buffer is not large enough to accomodate the vGPU instance array, the function returns NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlVgpuInstance_t array required in vgpuCount. To query the number of active vGPU instances, call this function with *vgpuCount = 0. The code will return NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if no vGPU Types are supported.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetCreatableVgpus ( nvmlDevice_t device, unsigned int* vgpuCount, nvmlVgpuTypeId_t* vgpuTypeIds )
Parameters
device
The identifier of the target device
vgpuCount
Pointer to caller-supplied array size, and returns number of vGPU types
vgpuTypeIds
Pointer to caller-supplied array in which to return list of vGPU types
Returns

Description

Retrieve the currently creatable vGPU types on a physical GPU (device).

An array of creatable vGPU types for the physical GPU indicated by device is returned in the caller-supplied buffer pointed at by vgpuTypeIds. The element count of nvmlVgpuTypeId_t array is passed in vgpuCount, and vgpuCount is used to return the number of vGPU types written to the buffer.

The creatable vGPU types for a device may differ over time, as there may be restrictions on what type of vGPU types can concurrently run on a device. For example, if only one vGPU type is allowed at a time on a device, then the creatable list will be restricted to whatever vGPU type is already running on the device.

If the supplied buffer is not large enough to accomodate the vGPU type array, the function returns NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlVgpuTypeId_t array required in vgpuCount. To query the number of vGPU types createable for the GPU, call this function with *vgpuCount = 0. The code will return NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if no vGPU types are creatable.

nvmlReturn_t nvmlDeviceGetSupportedVgpus ( nvmlDevice_t device, unsigned int* vgpuCount, nvmlVgpuTypeId_t* vgpuTypeIds )
Parameters
device
The identifier of the target device
vgpuCount
Pointer to caller-supplied array size, and returns number of vGPU types
vgpuTypeIds
Pointer to caller-supplied array in which to return list of vGPU types
Returns

Description

Retrieve the supported vGPU types on a physical GPU (device).

An array of supported vGPU types for the physical GPU indicated by device is returned in the caller-supplied buffer pointed at by vgpuTypeIds. The element count of nvmlVgpuTypeId_t array is passed in vgpuCount, and vgpuCount is used to return the number of vGPU types written to the buffer.

If the supplied buffer is not large enough to accomodate the vGPU type array, the function returns NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlVgpuTypeId_t array required in vgpuCount. To query the number of vGPU types supported for the GPU, call this function with *vgpuCount = 0. The code will return NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if no vGPU types are supported.

nvmlReturn_t nvmlVgpuInstanceGetEccMode ( nvmlVgpuInstance_t vgpuInstance, nvmlEnableState_t* eccMode )
Parameters
vgpuInstance
The identifier of the target vGPU instance
eccMode
Reference in which to return the current ECC mode
Returns

Description

Retrieve the current ECC mode of vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetEncoderCapacity ( nvmlVgpuInstance_t vgpuInstance, unsigned int* encoderCapacity )
Parameters
vgpuInstance
Identifier of the target vGPU instance
encoderCapacity
Reference to an unsigned int for the encoder capacity
Returns

Description

Retrieve the encoder capacity of a vGPU instance, as a percentage of maximum encoder capacity with valid values in the range 0-100.

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetEncoderSessions ( nvmlVgpuInstance_t vgpuInstance, unsigned int* sessionCount, nvmlEncoderSessionInfo_t* sessionInfo )
Parameters
vgpuInstance
Identifier of the target vGPU instance
sessionCount
Reference to caller supplied array size, and returns the number of sessions.
sessionInfo
Reference to caller supplied array in which the list of session information us returned.
Returns

Description

Retrieves information about all active encoder sessions on a vGPU Instance.

An array of active encoder sessions is returned in the caller-supplied buffer pointed at by sessionInfo. The array element count is passed in sessionCount, and sessionCount is used to return the number of sessions written to the buffer.

If the supplied buffer is not large enough to accomodate the active session array, the function returns NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlEncoderSessionInfo_t array required in sessionCount. To query the number of active encoder sessions, call this function with *sessionCount = 0. The code will return NVML_SUCCESS with number of active encoder sessions updated in *sessionCount.

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetEncoderStats ( nvmlVgpuInstance_t vgpuInstance, unsigned int* sessionCount, unsigned int* averageFps, unsigned int* averageLatency )
Parameters
vgpuInstance
Identifier of the target vGPU instance
sessionCount
Reference to an unsigned int for count of active encoder sessions
averageFps
Reference to an unsigned int for trailing average FPS of all active sessions
averageLatency
Reference to an unsigned int for encode latency in microseconds
Returns

Description

Retrieves the current encoder statistics of a vGPU Instance

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetFBCSessions ( nvmlVgpuInstance_t vgpuInstance, unsigned int* sessionCount, nvmlFBCSessionInfo_t* sessionInfo )
Parameters
vgpuInstance
Identifier of the target vGPU instance
sessionCount
Reference to caller supplied array size, and returns the number of sessions.
sessionInfo
Reference in which to return the session information
Returns

Description

Retrieves information about active frame buffer capture sessions on a vGPU Instance.

An array of active FBC sessions is returned in the caller-supplied buffer pointed at by sessionInfo. The array element count is passed in sessionCount, and sessionCount is used to return the number of sessions written to the buffer.

If the supplied buffer is not large enough to accomodate the active session array, the function returns NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlFBCSessionInfo_t array required in sessionCount. To query the number of active FBC sessions, call this function with *sessionCount = 0. The code will return NVML_SUCCESS with number of active FBC sessions updated in *sessionCount.

For Maxwell or newer fully supported devices.

Note:

hResolution, vResolution, averageFPS and averageLatency data for a FBC session returned in sessionInfo may be zero if there are no new frames captured since the session started.

nvmlReturn_t nvmlVgpuInstanceGetFBCStats ( nvmlVgpuInstance_t vgpuInstance, nvmlFBCStats_t* fbcStats )
Parameters
vgpuInstance
Identifier of the target vGPU instance
fbcStats
Reference to nvmlFBCStats_t structure contianing NvFBC stats
Returns

Description

Retrieves the active frame buffer capture sessions statistics of a vGPU Instance

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetFbUsage ( nvmlVgpuInstance_t vgpuInstance, unsigned long long* fbUsage )
Parameters
vgpuInstance
The identifier of the target instance
fbUsage
Pointer to framebuffer usage in bytes
Returns

Description

Retrieve the framebuffer usage in bytes.

Framebuffer usage is the amont of vGPU framebuffer memory that is currently in use by the VM.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetFrameRateLimit ( nvmlVgpuInstance_t vgpuInstance, unsigned int* frameRateLimit )
Parameters
vgpuInstance
Identifier of the target vGPU instance
frameRateLimit
Reference to return the frame rate limit
Returns

Description

Retrieve the frame rate limit set for the vGPU instance.

Returns the value of the frame rate limit set for the vGPU instance

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetGpuInstanceId ( nvmlVgpuInstance_t vgpuInstance, unsigned int* gpuInstanceId )
Parameters
vgpuInstance
Identifier of the target vGPU instance
gpuInstanceId
GPU Instance ID
Returns

Description

Retrieve the GPU Instance ID for the given vGPU Instance. The API will return a valid GPU Instance ID for MIG backed vGPU Instance, else INVALID_GPU_INSTANCE_ID is returned.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetLicenseStatus ( nvmlVgpuInstance_t vgpuInstance, unsigned int* licensed )
Parameters
vgpuInstance
Identifier of the target vGPU instance
licensed
Reference to return the licensing status
Returns

Description

Retrieve the current licensing state of the vGPU instance.

If the vGPU is currently licensed, licensed is set to 1, otherwise it is set to 0.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetType ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuTypeId_t* vgpuTypeId )
Parameters
vgpuInstance
Identifier of the target vGPU instance
vgpuTypeId
Reference to return the vgpuTypeId
Returns

Description

Retrieve the vGPU type of a vGPU instance.

Returns the vGPU type ID of vgpu assigned to the vGPU instance.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetUUID ( nvmlVgpuInstance_t vgpuInstance, char* uuid, unsigned int  size )
Parameters
vgpuInstance
Identifier of the target vGPU instance
uuid
Pointer to caller-supplied buffer to hold vGPU UUID
size
Size of buffer in bytes
Returns

Description

Retrieve the UUID of a vGPU instance.

The UUID is a globally unique identifier associated with the vGPU, and is returned as a 5-part hexadecimal string, not exceeding 80 characters in length (including the NULL terminator). See nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetVmDriverVersion ( nvmlVgpuInstance_t vgpuInstance, char* version, unsigned int  length )
Parameters
vgpuInstance
Identifier of the target vGPU instance
version
Caller-supplied buffer to return driver version string
length
Size of version buffer
Returns

Description

Retrieve the NVIDIA driver version installed in the VM associated with a vGPU.

The version is returned as an alphanumeric string in the caller-supplied buffer version. The length of the version string will not exceed 80 characters in length (including the NUL terminator). See nvmlConstants::NVML_SYSTEM_DRIVER_VERSION_BUFFER_SIZE.

nvmlVgpuInstanceGetVmDriverVersion() may be called at any time for a vGPU instance. The guest VM driver version is returned as "Not Available" if no NVIDIA driver is installed in the VM, or the VM has not yet booted to the point where the NVIDIA driver is loaded and initialized.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetVmID ( nvmlVgpuInstance_t vgpuInstance, char* vmId, unsigned int  size, nvmlVgpuVmIdType_t* vmIdType )
Parameters
vgpuInstance
Identifier of the target vGPU instance
vmId
Pointer to caller-supplied buffer to hold VM ID
size
Size of buffer in bytes
vmIdType
Pointer to hold VM ID type
Returns

Description

Retrieve the VM ID associated with a vGPU instance.

The VM ID is returned as a string, not exceeding 80 characters in length (including the NUL terminator). See nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.

The format of the VM ID varies by platform, and is indicated by the type identifier returned in vmIdType.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceSetEncoderCapacity ( nvmlVgpuInstance_t vgpuInstance, unsigned int  encoderCapacity )
Parameters
vgpuInstance
Identifier of the target vGPU instance
encoderCapacity
Unsigned int for the encoder capacity value
Returns

Description

Set the encoder capacity of a vGPU instance, as a percentage of maximum encoder capacity with valid values in the range 0-100.

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetClass ( nvmlVgpuTypeId_t vgpuTypeId, char* vgpuTypeClass, unsigned int* size )
Parameters
vgpuTypeId
Handle to vGPU type
vgpuTypeClass
Pointer to string array to return class in
size
Size of string
Returns

Description

Retrieve the class of a vGPU type. It will not exceed 64 characters in length (including the NUL terminator). See nvmlConstants::NVML_DEVICE_NAME_BUFFER_SIZE.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetDeviceID ( nvmlVgpuTypeId_t vgpuTypeId, unsigned long long* deviceID, unsigned long long* subsystemID )
Parameters
vgpuTypeId
Handle to vGPU type
deviceID
Device ID and vendor ID of the device contained in single 32 bit value
subsystemID
Subsytem ID and subsytem vendor ID of the device contained in single 32 bit value
Returns

Description

Retrieve the device ID of a vGPU type.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetFrameRateLimit ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* frameRateLimit )
Parameters
vgpuTypeId
Handle to vGPU type
frameRateLimit
Reference to return the frame rate limit value
Returns

Description

Retrieve the static frame rate limit value of the vGPU type

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetFramebufferSize ( nvmlVgpuTypeId_t vgpuTypeId, unsigned long long* fbSize )
Parameters
vgpuTypeId
Handle to vGPU type
fbSize
Pointer to framebuffer size in bytes
Returns

Description

Retrieve the vGPU framebuffer size in bytes.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetGpuInstanceProfileId ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* gpuInstanceProfileId )
Parameters
vgpuTypeId
Handle to vGPU type
gpuInstanceProfileId
GPU Instance Profile ID
Returns

Description

Retrieve the GPU Instance Profile ID for the given vGPU type ID. The API will return a valid GPU Instance Profile ID for the MIG capable vGPU types, else INVALID_GPU_INSTANCE_PROFILE_ID is returned.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetLicense ( nvmlVgpuTypeId_t vgpuTypeId, char* vgpuTypeLicenseString, unsigned int  size )
Parameters
vgpuTypeId
Handle to vGPU type
vgpuTypeLicenseString
Pointer to buffer to return license info
size
Size of vgpuTypeLicenseString buffer
Returns

Description

Retrieve license requirements for a vGPU type

The license type and version required to run the specified vGPU type is returned as an alphanumeric string, in the form "<license name>,<version>", for example "GRID-Virtual-PC,2.0". If a vGPU is runnable with* more than one type of license, the licenses are delimited by a semicolon, for example "GRID-Virtual-PC,2.0;GRID-Virtual-WS,2.0;GRID-Virtual-WS-Ext,2.0".

The total length of the returned string will not exceed 128 characters, including the NUL terminator. See nvmlVgpuConstants::NVML_GRID_LICENSE_BUFFER_SIZE.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetMaxInstances ( nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId, unsigned int* vgpuInstanceCount )
Parameters
device
The identifier of the target device
vgpuTypeId
Handle to vGPU type
vgpuInstanceCount
Pointer to get the max number of vGPU instances that can be created on a deicve for given vgpuTypeId
Returns

Description

Retrieve the maximum number of vGPU instances creatable on a device for given vGPU type

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetMaxInstancesPerVm ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* vgpuInstanceCountPerVm )
Parameters
vgpuTypeId
Handle to vGPU type
vgpuInstanceCountPerVm
Pointer to get the max number of vGPU instances supported per VM for given vgpuTypeId
Returns

Description

Retrieve the maximum number of vGPU instances supported per VM for given vGPU type

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetName ( nvmlVgpuTypeId_t vgpuTypeId, char* vgpuTypeName, unsigned int* size )
Parameters
vgpuTypeId
Handle to vGPU type
vgpuTypeName
Pointer to buffer to return name
size
Size of buffer
Returns

Description

Retrieve the vGPU type name.

The name is an alphanumeric string that denotes a particular vGPU, e.g. GRID M60-2Q. It will not exceed 64 characters in length (including the NUL terminator). See nvmlConstants::NVML_DEVICE_NAME_BUFFER_SIZE.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetNumDisplayHeads ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int* numDisplayHeads )
Parameters
vgpuTypeId
Handle to vGPU type
numDisplayHeads
Pointer to number of display heads
Returns

Description

Retrieve count of vGPU's supported display heads.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuTypeGetResolution ( nvmlVgpuTypeId_t vgpuTypeId, unsigned int  displayIndex, unsigned int* xdim, unsigned int* ydim )
Parameters
vgpuTypeId
Handle to vGPU type
displayIndex
Zero-based index of display head
xdim
Pointer to maximum number of pixels in X dimension
ydim
Pointer to maximum number of pixels in Y dimension
Returns

Description

Retrieve vGPU display head's maximum supported resolution.

For Kepler or newer fully supported devices.


NVML API Reference Guide (PDF) - vR470 (older) - Last updated July 29, 2021 - Send Feedback