Is this page helpful?

vGPU Management#

This chapter describes APIs supporting NVIDIA vGPU.

Functions#

nvmlReturn_t nvmlDeviceGetActiveVgpus(nvmlDevice_t device, unsigned int *vgpuCount, nvmlVgpuInstance_t *vgpuInstances)

Retrieve the active vGPU instances on a device.

nvmlReturn_t nvmlDeviceGetCreatableVgpus(nvmlDevice_t device, unsigned int *vgpuCount, nvmlVgpuTypeId_t *vgpuTypeIds)

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

nvmlReturn_t nvmlDeviceGetSupportedVgpus(nvmlDevice_t device, unsigned int *vgpuCount, nvmlVgpuTypeId_t *vgpuTypeIds)

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

nvmlReturn_t nvmlDeviceGetVgpuCapabilities(nvmlDevice_t device, nvmlDeviceVgpuCapability_t capability, unsigned int *capResult)

Retrieve the requested vGPU capability for GPU.

nvmlReturn_t nvmlDeviceGetVgpuSchedulerLog_v2(nvmlDevice_t device, nvmlVgpuSchedulerLogInfo_v2_t *pSchedulerLogInfo)

Returns the vGPU Software scheduler logs for the device.

nvmlReturn_t nvmlDeviceGetVgpuSchedulerState_v2(nvmlDevice_t device, nvmlVgpuSchedulerStateInfo_v2_t *pSchedulerStateInfo)

Returns the vGPU scheduler state.

nvmlReturn_t nvmlDeviceSetVgpuSchedulerState_v2(nvmlDevice_t device, nvmlVgpuSchedulerState_v2_t *pSchedulerState)

Sets the vGPU scheduler state.

nvmlReturn_t nvmlGetVgpuDriverCapabilities(nvmlVgpuDriverCapability_t capability, unsigned int *capResult)

Retrieve the requested vGPU driver capability.

nvmlReturn_t nvmlGpuInstanceGetActiveVgpus(nvmlGpuInstance_t gpuInstance, nvmlActiveVgpuInstanceInfo_t *pVgpuInstanceInfo)

Retrieve the active vGPU instances within a GPU instance.

nvmlReturn_t nvmlGpuInstanceGetCreatableVgpus(nvmlGpuInstance_t gpuInstance, nvmlVgpuTypeIdInfo_t *pVgpus)

Query the currently creatable vGPU types on a specific GPU Instance.

nvmlReturn_t nvmlGpuInstanceGetVgpuHeterogeneousMode(nvmlGpuInstance_t gpuInstance, nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode)

Get the vGPU heterogeneous mode for the GPU instance.

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerLog(nvmlGpuInstance_t gpuInstance, nvmlVgpuSchedulerLogInfo_t *pSchedulerLogInfo)

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerLog_v2(nvmlGpuInstance_t gpuInstance, nvmlVgpuSchedulerLogInfo_v2_t *pSchedulerLogInfo)

Returns the vGPU scheduler logs for the given GPU instance.

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerState(nvmlGpuInstance_t gpuInstance, nvmlVgpuSchedulerStateInfo_t *pSchedulerStateInfo)

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerState_v2(nvmlGpuInstance_t gpuInstance, nvmlVgpuSchedulerStateInfo_v2_t *pSchedulerStateInfo)

Returns the vGPU scheduler state for the given GPU instance.

nvmlReturn_t nvmlGpuInstanceGetVgpuTypeCreatablePlacements(nvmlGpuInstance_t gpuInstance, nvmlVgpuCreatablePlacementInfo_t *pCreatablePlacementInfo)

Query the creatable vGPU placement ID of the vGPU type within a GPU instance.

nvmlReturn_t nvmlGpuInstanceSetVgpuHeterogeneousMode(nvmlGpuInstance_t gpuInstance, const nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode)

Enable or disable vGPU heterogeneous mode for the GPU instance.

nvmlReturn_t nvmlGpuInstanceSetVgpuSchedulerState(nvmlGpuInstance_t gpuInstance, nvmlVgpuSchedulerState_t *pScheduler)

nvmlReturn_t nvmlGpuInstanceSetVgpuSchedulerState_v2(nvmlGpuInstance_t gpuInstance, nvmlVgpuSchedulerState_v2_t *pSchedulerState)

Set vGPU scheduler state for the given GPU instance.

nvmlReturn_t nvmlVgpuInstanceGetEccMode(nvmlVgpuInstance_t vgpuInstance, nvmlEnableState_t *eccMode)

Retrieve the current ECC mode of vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetEncoderCapacity(nvmlVgpuInstance_t vgpuInstance, unsigned int *encoderCapacity)

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

nvmlReturn_t nvmlVgpuInstanceGetEncoderSessions(nvmlVgpuInstance_t vgpuInstance, unsigned int *sessionCount, nvmlEncoderSessionInfo_t *sessionInfo)

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

nvmlReturn_t nvmlVgpuInstanceGetEncoderStats(nvmlVgpuInstance_t vgpuInstance, unsigned int *sessionCount, unsigned int *averageFps, unsigned int *averageLatency)

Retrieves the current encoder statistics of a vGPU Instance.

nvmlReturn_t nvmlVgpuInstanceGetFBCSessions(nvmlVgpuInstance_t vgpuInstance, unsigned int *sessionCount, nvmlFBCSessionInfo_t *sessionInfo)

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

nvmlReturn_t nvmlVgpuInstanceGetFBCStats(nvmlVgpuInstance_t vgpuInstance, nvmlFBCStats_t *fbcStats)

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

nvmlReturn_t nvmlVgpuInstanceGetFbUsage(nvmlVgpuInstance_t vgpuInstance, unsigned long long *fbUsage)

Retrieve the framebuffer usage in bytes.

nvmlReturn_t nvmlVgpuInstanceGetFrameRateLimit(nvmlVgpuInstance_t vgpuInstance, unsigned int *frameRateLimit)

Retrieve the frame rate limit set for the vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetGpuInstanceId(nvmlVgpuInstance_t vgpuInstance, unsigned int *gpuInstanceId)

Retrieve the GPU Instance ID for the given vGPU Instance.

nvmlReturn_t nvmlVgpuInstanceGetGpuPciId(nvmlVgpuInstance_t vgpuInstance, char *vgpuPciId, unsigned int *length)

Retrieves the PCI Id of the given vGPU Instance i.e.

nvmlReturn_t nvmlVgpuInstanceGetLicenseStatus(nvmlVgpuInstance_t vgpuInstance, unsigned int *licensed)

nvmlReturn_t nvmlVgpuInstanceGetMdevUUID(nvmlVgpuInstance_t vgpuInstance, char *mdevUuid, unsigned int size)

Retrieve the MDEV UUID of a vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetType(nvmlVgpuInstance_t vgpuInstance, nvmlVgpuTypeId_t *vgpuTypeId)

Retrieve the vGPU type of a vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetUUID(nvmlVgpuInstance_t vgpuInstance, char *uuid, unsigned int size)

Retrieve the UUID of a vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetVmDriverVersion(nvmlVgpuInstance_t vgpuInstance, char *version, unsigned int length)

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

nvmlReturn_t nvmlVgpuInstanceGetVmID(nvmlVgpuInstance_t vgpuInstance, char *vmId, unsigned int size, nvmlVgpuVmIdType_t *vmIdType)

Retrieve the VM ID associated with a vGPU instance.

nvmlReturn_t nvmlVgpuInstanceSetEncoderCapacity(nvmlVgpuInstance_t vgpuInstance, unsigned int encoderCapacity)

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

nvmlReturn_t nvmlVgpuTypeGetBAR1Info(nvmlVgpuTypeId_t vgpuTypeId, nvmlVgpuTypeBar1Info_t *bar1Info)

Retrieve the BAR1 info for given vGPU type.

nvmlReturn_t nvmlVgpuTypeGetCapabilities(nvmlVgpuTypeId_t vgpuTypeId, nvmlVgpuCapability_t capability, unsigned int *capResult)

Retrieve the requested capability for a given vGPU type.

nvmlReturn_t nvmlVgpuTypeGetClass(nvmlVgpuTypeId_t vgpuTypeId, char *vgpuTypeClass, unsigned int *size)

Retrieve the class of a vGPU type.

nvmlReturn_t nvmlVgpuTypeGetDeviceID(nvmlVgpuTypeId_t vgpuTypeId, unsigned long long *deviceID, unsigned long long *subsystemID)

Retrieve the device ID of a vGPU type.

nvmlReturn_t nvmlVgpuTypeGetFrameRateLimit(nvmlVgpuTypeId_t vgpuTypeId, unsigned int *frameRateLimit)

Retrieve the static frame rate limit value of the vGPU type.

nvmlReturn_t nvmlVgpuTypeGetFramebufferSize(nvmlVgpuTypeId_t vgpuTypeId, unsigned long long *fbSize)

Retrieve the vGPU framebuffer size in bytes.

nvmlReturn_t nvmlVgpuTypeGetGpuInstanceProfileId(nvmlVgpuTypeId_t vgpuTypeId, unsigned int *gpuInstanceProfileId)

Retrieve the GPU Instance Profile ID for the given vGPU type ID.

nvmlReturn_t nvmlVgpuTypeGetLicense(nvmlVgpuTypeId_t vgpuTypeId, char *vgpuTypeLicenseString, unsigned int size)

Retrieve license requirements for a vGPU type.

nvmlReturn_t nvmlVgpuTypeGetMaxInstances(nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId, unsigned int *vgpuInstanceCount)

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

nvmlReturn_t nvmlVgpuTypeGetMaxInstancesPerGpuInstance(nvmlVgpuTypeMaxInstance_t *pMaxInstance)

Retrieve the maximum number of vGPU instances per GPU instance for given vGPU type.

nvmlReturn_t nvmlVgpuTypeGetMaxInstancesPerVm(nvmlVgpuTypeId_t vgpuTypeId, unsigned int *vgpuInstanceCountPerVm)

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

nvmlReturn_t nvmlVgpuTypeGetName(nvmlVgpuTypeId_t vgpuTypeId, char *vgpuTypeName, unsigned int *size)

Retrieve the vGPU type name.

nvmlReturn_t nvmlVgpuTypeGetNumDisplayHeads(nvmlVgpuTypeId_t vgpuTypeId, unsigned int *numDisplayHeads)

Retrieve count of vGPU's supported display heads.

nvmlReturn_t nvmlVgpuTypeGetResolution(nvmlVgpuTypeId_t vgpuTypeId, unsigned int displayIndex, unsigned int *xdim, unsigned int *ydim)

Retrieve vGPU display head's maximum supported resolution.

Functions#

nvmlReturn_t nvmlDeviceGetActiveVgpus(
nvmlDevice_t device,
unsigned int *vgpuCount,
nvmlVgpuInstance_t *vgpuInstances,
)#

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 element 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 accommodate 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.

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:

nvmlReturn_t nvmlDeviceGetCreatableVgpus(
nvmlDevice_t device,
unsigned int *vgpuCount,
nvmlVgpuTypeId_t *vgpuTypeIds,
)#

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 accommodate 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 that can be created 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.

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:

nvmlReturn_t nvmlDeviceGetSupportedVgpus(
nvmlDevice_t device,
unsigned int *vgpuCount,
nvmlVgpuTypeId_t *vgpuTypeIds,
)#

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 accommodate 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.

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:

nvmlReturn_t nvmlDeviceGetVgpuCapabilities(
nvmlDevice_t device,
nvmlDeviceVgpuCapability_t capability,
unsigned int *capResult,
)#

Retrieve the requested vGPU capability for GPU.

Refer to the nvmlDeviceVgpuCapability_t structure for the specific capabilities that can be queried. The return value in capResult reports a non-zero value indicating that the capability is supported, and also reports the capability’s data based on the queried capability.

For Maxwell or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • capability – Specifies the nvmlDeviceVgpuCapability_t to be queried

  • capResult – Specifies that the queried capability is supported, and also returns capability’s data

Returns:

nvmlReturn_t nvmlDeviceGetVgpuSchedulerLog_v2(
nvmlDevice_t device,
nvmlVgpuSchedulerLogInfo_v2_t *pSchedulerLogInfo,
)#

Returns the vGPU Software scheduler logs for the device.

pSchedulerLogInfo points to a caller-allocated structure to contain the logs. The number of elements returned will never exceed NVML_SCHEDULER_SW_MAX_LOG_ENTRIES.

To get the entire logs, call the function atleast 5 times a second.

For Pascal or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • pSchedulerLogInfo – Reference in which pSchedulerLogInfo is written

Returns:

nvmlReturn_t nvmlDeviceGetVgpuSchedulerState_v2(
nvmlDevice_t device,
nvmlVgpuSchedulerStateInfo_v2_t *pSchedulerStateInfo,
)#

Returns the vGPU scheduler state.

The information returned in nvmlVgpuSchedulerStateInfo_v2_t is not relevant if the BEST EFFORT policy is set.

For Pascal or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • pSchedulerStateInfo – Reference in which pSchedulerStateInfo is returned

Returns:

nvmlReturn_t nvmlDeviceSetVgpuSchedulerState_v2(
nvmlDevice_t device,
nvmlVgpuSchedulerState_v2_t *pSchedulerState,
)#

Sets the vGPU scheduler state.

For Pascal or newer fully supported devices.

The scheduler state change won’t persist across module load/unload. Scheduler state and params will be allowed to set only when no VM is running.

Parameters:

  • device – The identifier of the target device

  • pSchedulerState – vGPU pSchedulerState to set

Returns:

nvmlReturn_t nvmlGetVgpuDriverCapabilities(
nvmlVgpuDriverCapability_t capability,
unsigned int *capResult,
)#

Retrieve the requested vGPU driver capability.

Refer to the nvmlVgpuDriverCapability_t structure for the specific capabilities that can be queried. The return value in capResult should be treated as a boolean, with a non-zero value indicating that the capability is supported.

For Maxwell or newer fully supported devices.

Parameters:

  • capability – Specifies the nvmlVgpuDriverCapability_t to be queried

  • capResult – A boolean for the queried capability indicating that feature is supported

Returns:

nvmlReturn_t nvmlGpuInstanceGetActiveVgpus(
nvmlGpuInstance_t gpuInstance,
nvmlActiveVgpuInstanceInfo_t *pVgpuInstanceInfo,
)#

Retrieve the active vGPU instances within a GPU instance.

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

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

Parameters:

  • gpuInstance – The GPU instance handle

  • pVgpuInstanceInfo – Pointer to the vGPU instance information structure nvmlActiveVgpuInstanceInfo_t

Returns:

nvmlReturn_t nvmlGpuInstanceGetCreatableVgpus(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuTypeIdInfo_t *pVgpus,
)#

Query the currently creatable vGPU types on a specific GPU Instance.

The function returns an array of vGPU types that can be created for a specified GPU instance. This array is stored in a caller-supplied buffer, with the buffer’s element count passed through pVgpus->vgpuCount. The number of vGPU types written to the buffer is indicated by pVgpus->vgpuCount. If the buffer is too small to hold the vGPU type array, the function returns NVML_ERROR_INSUFFICIENT_SIZE and updates pVgpus->vgpuCount with the required element count.

To determine the creatable vGPUs for a GPU Instance, invoke this function with pVgpus->vgpuCount set to 0 and pVgpus->vgpuTypeIds as NULL. This will result in NVML_ERROR_INSUFFICIENT_SIZE being returned, along with the count value in pVgpus->vgpuCount.

The creatable vGPU types may differ over time, as there may be restrictions on what type of vGPUs can concurrently run on the device.

Parameters:

  • gpuInstance – The GPU instance handle

  • pVgpus – Pointer to the caller-provided structure of nvmlVgpuTypeIdInfo_t

Returns:

nvmlReturn_t nvmlGpuInstanceGetVgpuHeterogeneousMode(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode,
)#

Get the vGPU heterogeneous mode for the GPU instance.

When in heterogeneous mode, a vGPU can concurrently host timesliced vGPUs with differing framebuffer sizes.

On successful return, the function returns pHeterogeneousMode->mode with the current vGPU heterogeneous mode. pHeterogeneousMode->version is the version number of the structure nvmlVgpuHeterogeneousMode_t, the caller should set the correct version number to retrieve the vGPU heterogeneous mode. pHeterogeneousMode->mode can either be NVML_FEATURE_ENABLED or NVML_FEATURE_DISABLED.

For Blackwell &tm GB20x; or newer fully supported devices.

Parameters:

  • gpuInstance – The GPU instance handle

  • pHeterogeneousMode – Pointer to the caller-provided structure of nvmlVgpuHeterogeneousMode_t

Returns:

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerLog(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerLogInfo_t *pSchedulerLogInfo,
)#

Deprecated:

Will be deprecated in a future release. Use nvmlGpuInstanceGetVgpuSchedulerLog_v2 instead

Returns the vGPU scheduler logs for the given GPU instance. pSchedulerLogInfo points to a caller-allocated structure to contain the logs. The number of elements returned will never exceed NVML_SCHEDULER_SW_MAX_LOG_ENTRIES.

To get the entire logs, call the function atleast 5 times a second.

For Blackwell &tm GB20x; or newer fully supported devices.

Parameters:

  • gpuInstance – The GPU instance handle

  • pSchedulerLogInfo – Reference in which pSchedulerLogInfo is written

Returns:

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerLog_v2(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerLogInfo_v2_t *pSchedulerLogInfo,
)#

Returns the vGPU scheduler logs for the given GPU instance.

pSchedulerLogInfo points to a caller-allocated structure to contain the logs. The number of elements returned will never exceed NVML_SCHEDULER_SW_MAX_LOG_ENTRIES.

To get the entire logs, call the function atleast 5 times a second.

For Blackwell &tm GB20x; or newer fully supported devices.

Parameters:

  • gpuInstance – The GPU instance handle

  • pSchedulerLogInfo – Reference in which pSchedulerLogInfo is written

Returns:

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerState(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerStateInfo_t *pSchedulerStateInfo,
)#

Deprecated:

Will be deprecated in a future release. Use nvmlGpuInstanceGetVgpuSchedulerState_v2 instead

Returns the vGPU scheduler state for the given GPU instance. The information returned in nvmlVgpuSchedulerStateInfo_t is not relevant if the BEST EFFORT policy is set.

For Blackwell &tm GB20x; or newer fully supported devices.

Parameters:

  • gpuInstance – The GPU instance handle

  • pSchedulerStateInfo – Reference in which pSchedulerStateInfo is returned

Returns:

nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerState_v2(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerStateInfo_v2_t *pSchedulerStateInfo,
)#

Returns the vGPU scheduler state for the given GPU instance.

The information returned in nvmlVgpuSchedulerStateInfo_v2_t is not relevant if the BEST EFFORT policy is set.

For Blackwell &tm GB20x; or newer fully supported devices.

Parameters:

  • gpuInstance – The GPU instance handle

  • pSchedulerStateInfo – Reference in which pSchedulerStateInfo is returned

Returns:

nvmlReturn_t nvmlGpuInstanceGetVgpuTypeCreatablePlacements(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuCreatablePlacementInfo_t *pCreatablePlacementInfo,
)#

Query the creatable vGPU placement ID of the vGPU type within a GPU instance.

For Blackwell &tm GB20x; or newer fully supported devices.

An array of creatable vGPU placement IDs for the vGPU type ID indicated by pCreatablePlacementInfo->vgpuTypeId is returned in the caller-supplied buffer of pCreatablePlacementInfo->placementIds. Memory needed for the placementIds array should be allocated based on maximum instances of a vGPU type per GPU instance which can be queried via nvmlVgpuTypeGetMaxInstancesPerGpuInstance(). If the provided count by the caller is insufficient, the function will return NVML_ERROR_INSUFFICIENT_SIZE along with the number of required entries in pCreatablePlacementInfo->count. The caller should then reallocate a buffer with the size of pCreatablePlacementInfo->count * sizeof(pCreatablePlacementInfo->placementIds) and invoke the function again. The creatable vGPU placement IDs may differ over time, as there may be restrictions on what type of vGPU the vGPU instance is running.

Parameters:

  • gpuInstance – The GPU instance handle

  • pCreatablePlacementInfo – Pointer to the list of vGPU creatable placement structure nvmlVgpuCreatablePlacementInfo_t

Returns:

nvmlReturn_t nvmlGpuInstanceSetVgpuHeterogeneousMode(
nvmlGpuInstance_t gpuInstance,
const nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode,
)#

Enable or disable vGPU heterogeneous mode for the GPU instance.

When in heterogeneous mode, a vGPU can concurrently host timesliced vGPUs with differing framebuffer sizes.

API would return an appropriate error code upon unsuccessful activation. For example, the heterogeneous mode set will fail with error NVML_ERROR_IN_USE if any vGPU instance is active within the GPU instance. The caller of this API is expected to shutdown the vGPU VMs and retry setting the mode. On successful return, the function updates the vGPU heterogeneous mode with the user provided pHeterogeneousMode->mode. pHeterogeneousMode->version is the version number of the structure nvmlVgpuHeterogeneousMode_t, the caller should set the correct version number to set the vGPU heterogeneous mode.

Parameters:

  • gpuInstance – The GPU instance handle

  • pHeterogeneousMode – Pointer to the caller-provided structure of nvmlVgpuHeterogeneousMode_t

Returns:

nvmlReturn_t nvmlGpuInstanceSetVgpuSchedulerState(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerState_t *pScheduler,
)#

Deprecated:

Will be deprecated in a future release. Use nvmlGpuInstanceSetVgpuSchedulerState_v2 instead

Set vGPU scheduler state for the given GPU instance

For Blackwell &tm GB20x; or newer fully supported devices.

Scheduler state and params will be allowed to set only when no VM is running within the GPU instance. In nvmlVgpuSchedulerState_t, IFF enableARRMode is enabled then provide the avgFactor and frequency as input. If enableARRMode is disabled then provide timeslice as input.

The scheduler state change won’t persist across module load/unload and GPU Instance creation/deletion.

Parameters:

  • gpuInstance – The GPU instance handle

  • pScheduler – Pointer to the caller-provided structure of nvmlVgpuSchedulerState_t

Returns:

nvmlReturn_t nvmlGpuInstanceSetVgpuSchedulerState_v2(
nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerState_v2_t *pSchedulerState,
)#

Set vGPU scheduler state for the given GPU instance.

For Blackwell &tm GB20x; or newer fully supported devices.

Scheduler state and params will be allowed to set only when no VM is running within the GPU instance.

The scheduler state change won’t persist across module load/unload and GPU Instance creation/deletion.

Parameters:
Returns:

nvmlReturn_t nvmlVgpuInstanceGetEccMode(
nvmlVgpuInstance_t vgpuInstance,
nvmlEnableState_t *eccMode,
)#

Retrieve the current ECC mode of vGPU instance.

Parameters:

  • vgpuInstance – The identifier of the target vGPU instance

  • eccMode – Reference in which to return the current ECC mode

Returns:

nvmlReturn_t nvmlVgpuInstanceGetEncoderCapacity(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *encoderCapacity,
)#

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • encoderCapacity – Reference to an unsigned int for the encoder capacity

Returns:

nvmlReturn_t nvmlVgpuInstanceGetEncoderSessions(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *sessionCount,
nvmlEncoderSessionInfo_t *sessionInfo,
)#

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 accommodate 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.

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:

nvmlReturn_t nvmlVgpuInstanceGetEncoderStats(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *sessionCount,
unsigned int *averageFps,
unsigned int *averageLatency,
)#

Retrieves the current encoder statistics of a vGPU Instance.

For Maxwell or newer fully supported devices.

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:

nvmlReturn_t nvmlVgpuInstanceGetFBCSessions(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *sessionCount,
nvmlFBCSessionInfo_t *sessionInfo,
)#

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 accommodate 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.

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:

nvmlReturn_t nvmlVgpuInstanceGetFBCStats(
nvmlVgpuInstance_t vgpuInstance,
nvmlFBCStats_t *fbcStats,
)#

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

For Maxwell or newer fully supported devices.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • fbcStats – Reference to nvmlFBCStats_t structure containing NvFBC stats

Returns:

nvmlReturn_t nvmlVgpuInstanceGetFbUsage(
nvmlVgpuInstance_t vgpuInstance,
unsigned long long *fbUsage,
)#

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.

Parameters:

  • vgpuInstance – The identifier of the target instance

  • fbUsage – Pointer to framebuffer usage in bytes

Returns:

nvmlReturn_t nvmlVgpuInstanceGetFrameRateLimit(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *frameRateLimit,
)#

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • frameRateLimit – Reference to return the frame rate limit

Returns:

nvmlReturn_t nvmlVgpuInstanceGetGpuInstanceId(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *gpuInstanceId,
)#

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • gpuInstanceId – GPU Instance ID

Returns:

nvmlReturn_t nvmlVgpuInstanceGetGpuPciId(
nvmlVgpuInstance_t vgpuInstance,
char *vgpuPciId,
unsigned int *length,
)#

Retrieves the PCI Id of the given vGPU Instance i.e.

the PCI Id of the GPU as seen inside the VM.

The vGPU PCI id is returned as “00000000:00:00.0” if NVIDIA driver is not installed on the vGPU instance.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • vgpuPciId – Caller-supplied buffer to return vGPU PCI Id string

  • length – Size of the vgpuPciId buffer

Returns:

nvmlReturn_t nvmlVgpuInstanceGetLicenseStatus(
nvmlVgpuInstance_t vgpuInstance,
unsigned int *licensed,
)#

Deprecated:

Use nvmlVgpuInstanceGetLicenseInfo_v2.

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • licensed – Reference to return the licensing status

Returns:

nvmlReturn_t nvmlVgpuInstanceGetMdevUUID(
nvmlVgpuInstance_t vgpuInstance,
char *mdevUuid,
unsigned int size,
)#

Retrieve the MDEV UUID of a vGPU instance.

The MDEV UUID is a globally unique identifier of the mdev device assigned to the VM, and is returned as a 5-part hexadecimal string, not exceeding 80 characters in length (including the NULL terminator). MDEV UUID is displayed only on KVM platform. See nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.

For Maxwell or newer fully supported devices.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • mdevUuid – Pointer to caller-supplied buffer to hold MDEV UUID

  • size – Size of buffer in bytes

Returns:

nvmlReturn_t nvmlVgpuInstanceGetType(
nvmlVgpuInstance_t vgpuInstance,
nvmlVgpuTypeId_t *vgpuTypeId,
)#

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • vgpuTypeId – Reference to return the vgpuTypeId

Returns:

nvmlReturn_t nvmlVgpuInstanceGetUUID(
nvmlVgpuInstance_t vgpuInstance,
char *uuid,
unsigned int size,
)#

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.

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:

nvmlReturn_t nvmlVgpuInstanceGetVmDriverVersion(
nvmlVgpuInstance_t vgpuInstance,
char *version,
unsigned int length,
)#

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • version – Caller-supplied buffer to return driver version string

  • length – Size of version buffer

Returns:

nvmlReturn_t nvmlVgpuInstanceGetVmID(
nvmlVgpuInstance_t vgpuInstance,
char *vmId,
unsigned int size,
nvmlVgpuVmIdType_t *vmIdType,
)#

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.

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:

nvmlReturn_t nvmlVgpuInstanceSetEncoderCapacity(
nvmlVgpuInstance_t vgpuInstance,
unsigned int encoderCapacity,
)#

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.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • encoderCapacity – Unsigned int for the encoder capacity value

Returns:

nvmlReturn_t nvmlVgpuTypeGetBAR1Info(
nvmlVgpuTypeId_t vgpuTypeId,
nvmlVgpuTypeBar1Info_t *bar1Info,
)#

Retrieve the BAR1 info for given vGPU type.

For Maxwell or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • bar1Info – Pointer to the vGPU type BAR1 information structure nvmlVgpuTypeBar1Info_t

Returns:

nvmlReturn_t nvmlVgpuTypeGetCapabilities(
nvmlVgpuTypeId_t vgpuTypeId,
nvmlVgpuCapability_t capability,
unsigned int *capResult,
)#

Retrieve the requested capability for a given vGPU type.

Refer to the nvmlVgpuCapability_t structure for the specific capabilities that can be queried. The return value in capResult should be treated as a boolean, with a non-zero value indicating that the capability is supported.

For Maxwell or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • capability – Specifies the nvmlVgpuCapability_t to be queried

  • capResult – A boolean for the queried capability indicating that feature is supported

Returns:

nvmlReturn_t nvmlVgpuTypeGetClass(
nvmlVgpuTypeId_t vgpuTypeId,
char *vgpuTypeClass,
unsigned int *size,
)#

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.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • vgpuTypeClass – Pointer to string array to return class in

  • size – Size of string

Returns:

nvmlReturn_t nvmlVgpuTypeGetDeviceID(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned long long *deviceID,
unsigned long long *subsystemID,
)#

Retrieve the device ID of a vGPU type.

For Kepler or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • deviceID – Device ID and vendor ID of the device contained in single 32 bit value

  • subsystemID – Subsystem ID and subsystem vendor ID of the device contained in single 32 bit value

Returns:

nvmlReturn_t nvmlVgpuTypeGetFrameRateLimit(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned int *frameRateLimit,
)#

Retrieve the static frame rate limit value of the vGPU type.

For Kepler or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • frameRateLimit – Reference to return the frame rate limit value

Returns:

nvmlReturn_t nvmlVgpuTypeGetFramebufferSize(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned long long *fbSize,
)#

Retrieve the vGPU framebuffer size in bytes.

For Kepler or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • fbSize – Pointer to framebuffer size in bytes

Returns:

nvmlReturn_t nvmlVgpuTypeGetGpuInstanceProfileId(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned int *gpuInstanceProfileId,
)#

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.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • gpuInstanceProfileId – GPU Instance Profile ID

Returns:

nvmlReturn_t nvmlVgpuTypeGetLicense(
nvmlVgpuTypeId_t vgpuTypeId,
char *vgpuTypeLicenseString,
unsigned int size,
)#

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.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • vgpuTypeLicenseString – Pointer to buffer to return license info

  • size – Size of vgpuTypeLicenseString buffer

Returns:

nvmlReturn_t nvmlVgpuTypeGetMaxInstances(
nvmlDevice_t device,
nvmlVgpuTypeId_t vgpuTypeId,
unsigned int *vgpuInstanceCount,
)#

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

For Kepler or newer fully supported devices.

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:

nvmlReturn_t nvmlVgpuTypeGetMaxInstancesPerGpuInstance(
nvmlVgpuTypeMaxInstance_t *pMaxInstance,
)#

Retrieve the maximum number of vGPU instances per GPU instance for given vGPU type.

Parameters:

pMaxInstance – Pointer to the caller-provided structure of nvmlVgpuTypeMaxInstance_t

Returns:

nvmlReturn_t nvmlVgpuTypeGetMaxInstancesPerVm(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned int *vgpuInstanceCountPerVm,
)#

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

For Kepler or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • vgpuInstanceCountPerVm – Pointer to get the max number of vGPU instances supported per VM for given vgpuTypeId

Returns:

nvmlReturn_t nvmlVgpuTypeGetName(
nvmlVgpuTypeId_t vgpuTypeId,
char *vgpuTypeName,
unsigned int *size,
)#

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.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • vgpuTypeName – Pointer to buffer to return name

  • size – Size of buffer

Returns:

nvmlReturn_t nvmlVgpuTypeGetNumDisplayHeads(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned int *numDisplayHeads,
)#

Retrieve count of vGPU’s supported display heads.

For Kepler or newer fully supported devices.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • numDisplayHeads – Pointer to number of display heads

Returns:

nvmlReturn_t nvmlVgpuTypeGetResolution(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned int displayIndex,
unsigned int *xdim,
unsigned int *ydim,
)#

Retrieve vGPU display head’s maximum supported resolution.

For Kepler or newer fully supported devices.

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:

On this page