Is this page helpful?

vGPU APIs#

This chapter describes operations that are associated with NVIDIA vGPU Software products.

Functions#

nvmlReturn_t nvmlDeviceGetGridLicensableFeatures_v4(nvmlDevice_t device, nvmlGridLicensableFeatures_t *pGridLicensableFeatures)

Retrieve the vGPU Software licensable features.

nvmlReturn_t nvmlDeviceGetHostVgpuMode(nvmlDevice_t device, nvmlHostVgpuMode_t *pHostVgpuMode)

Queries if SR-IOV host operation is supported on a vGPU supported device.

nvmlReturn_t nvmlDeviceGetVgpuHeterogeneousMode(nvmlDevice_t device, nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode)

Get the vGPU heterogeneous mode for the device.

nvmlReturn_t nvmlDeviceGetVgpuTypeCreatablePlacements(nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId, nvmlVgpuPlacementList_t *pPlacementList)

Query the creatable vGPU placement ID of the vGPU type.

nvmlReturn_t nvmlDeviceGetVgpuTypeSupportedPlacements(nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId, nvmlVgpuPlacementList_t *pPlacementList)

Query the supported vGPU placement ID of the vGPU type.

nvmlReturn_t nvmlDeviceGetVirtualizationMode(nvmlDevice_t device, nvmlGpuVirtualizationMode_t *pVirtualMode)

This method is used to get the virtualization mode corresponding to the GPU.

nvmlReturn_t nvmlDeviceSetVgpuCapabilities(nvmlDevice_t device, nvmlDeviceVgpuCapability_t capability, nvmlEnableState_t state)

Set the desirable vGPU capability of a device.

nvmlReturn_t nvmlDeviceSetVgpuHeterogeneousMode(nvmlDevice_t device, const nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode)

Enable or disable vGPU heterogeneous mode for the device.

nvmlReturn_t nvmlDeviceSetVirtualizationMode(nvmlDevice_t device, nvmlGpuVirtualizationMode_t virtualMode)

This method is used to set the virtualization mode corresponding to the GPU.

nvmlReturn_t nvmlDeviceVgpuForceGspUnload(nvmlDevice_t device)

Executes a forced GSP unload operation on a device.

nvmlReturn_t nvmlVgpuInstanceGetPlacementId(nvmlVgpuInstance_t vgpuInstance, nvmlVgpuPlacementId_t *pPlacement)

Query the placement ID of active vGPU instance.

nvmlReturn_t nvmlVgpuInstanceGetRuntimeStateSize(nvmlVgpuInstance_t vgpuInstance, nvmlVgpuRuntimeState_t *pState)

Retrieve the currently used runtime state size of the vGPU instance.

nvmlReturn_t nvmlVgpuTypeGetFbReservation(nvmlVgpuTypeId_t vgpuTypeId, unsigned long long *fbReservation)

Retrieve the static framebuffer reservation of the vGPU type in bytes.

nvmlReturn_t nvmlVgpuTypeGetGspHeapSize(nvmlVgpuTypeId_t vgpuTypeId, unsigned long long *gspHeapSize)

Retrieve the static GSP heap size of the vGPU type in bytes.

Functions#

nvmlReturn_t nvmlDeviceGetGridLicensableFeatures_v4(
nvmlDevice_t device,
nvmlGridLicensableFeatures_t *pGridLicensableFeatures,
)#

Retrieve the vGPU Software licensable features.

Identifies whether the system supports vGPU Software Licensing. If it does, return the list of licensable feature(s) and their current license status.

Parameters:

  • device – Identifier of the target device

  • pGridLicensableFeatures – Pointer to structure in which vGPU software licensable features are returned

Returns:

nvmlReturn_t nvmlDeviceGetHostVgpuMode(
nvmlDevice_t device,
nvmlHostVgpuMode_t *pHostVgpuMode,
)#

Queries if SR-IOV host operation is supported on a vGPU supported device.

Checks whether SR-IOV host capability is supported by the device and the driver, and indicates device is in SR-IOV mode if both of these conditions are true.

Parameters:

  • device – The identifier of the target device

  • pHostVgpuMode – Reference in which to return the current vGPU mode

Returns:

nvmlReturn_t nvmlDeviceGetVgpuHeterogeneousMode(
nvmlDevice_t device,
nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode,
)#

Get the vGPU heterogeneous mode for the device.

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.

Parameters:

  • device – The identifier of the target device

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

Returns:

nvmlReturn_t nvmlDeviceGetVgpuTypeCreatablePlacements(
nvmlDevice_t device,
nvmlVgpuTypeId_t vgpuTypeId,
nvmlVgpuPlacementList_t *pPlacementList,
)#

Query the creatable vGPU placement ID of the vGPU type.

An array of creatable vGPU placement IDs for the vGPU type ID indicated by vgpuTypeId is returned in the caller-supplied buffer of pPlacementList->placementIds. Memory needed for the placementIds array should be allocated based on maximum instances of a vGPU type which can be queried via nvmlVgpuTypeGetMaxInstances(). 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 pPlacementList->count. The caller should then reallocate a buffer with the size of pPlacementList->count * sizeof(pPlacementList->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:

  • device – The identifier of the target device

  • vgpuTypeId – Handle to vGPU type. The vGPU type ID

  • pPlacementList – Pointer to the list of vGPU placement structure nvmlVgpuPlacementList_t

Returns:

nvmlReturn_t nvmlDeviceGetVgpuTypeSupportedPlacements(
nvmlDevice_t device,
nvmlVgpuTypeId_t vgpuTypeId,
nvmlVgpuPlacementList_t *pPlacementList,
)#

Query the supported vGPU placement ID of the vGPU type.

The function returns an array of supported vGPU placement IDs for the specified vGPU type ID in the buffer provided by the caller at pPlacementList->placementIds. The required memory for the placementIds array must be allocated based on the maximum number of vGPU type instances, which is retrievable through nvmlVgpuTypeGetMaxInstances(). 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 pPlacementList->count. The caller should then reallocate a buffer with the size of pPlacementList->count * sizeof(pPlacementList->placementIds) and invoke the function again.

To obtain a list of homogeneous placement IDs, the caller needs to set pPlacementList->mode to NVML_VGPU_PGPU_HOMOGENEOUS_MODE. For heterogeneous placement IDs, pPlacementList->mode should be set to NVML_VGPU_PGPU_HETEROGENEOUS_MODE. By default, a list of heterogeneous placement IDs is returned.

Parameters:

  • device – Identifier of the target device

  • vgpuTypeId – Handle to vGPU type. The vGPU type ID

  • pPlacementList – Pointer to the vGPU placement structure nvmlVgpuPlacementList_t

Returns:

nvmlReturn_t nvmlDeviceGetVirtualizationMode(
nvmlDevice_t device,
nvmlGpuVirtualizationMode_t *pVirtualMode,
)#

This method is used to get the virtualization mode corresponding to the GPU.

For Kepler or newer fully supported devices.

Parameters:

  • device – Identifier of the target device

  • pVirtualMode – Reference to virtualization mode. One of NVML_GPU_VIRTUALIZATION_?

Returns:

nvmlReturn_t nvmlDeviceSetVgpuCapabilities(
nvmlDevice_t device,
nvmlDeviceVgpuCapability_t capability,
nvmlEnableState_t state,
)#

Set the desirable vGPU capability of a device.

Refer to the nvmlDeviceVgpuCapability_t structure for the specific capabilities that can be set. See nvmlEnableState_t for available state.

Parameters:

  • device – The identifier of the target device

  • capability – Specifies the nvmlDeviceVgpuCapability_t to be set

  • state – The target capability mode

Returns:

nvmlReturn_t nvmlDeviceSetVgpuHeterogeneousMode(
nvmlDevice_t device,
const nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode,
)#

Enable or disable vGPU heterogeneous mode for the device.

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 on the device. The caller of this API is expected to shutdown the vGPU VMs and retry setting the mode. On KVM platform, setting heterogeneous mode is allowed, if no MDEV device is created on the device, else will fail with same error NVML_ERROR_IN_USE. 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:

  • device – Identifier of the target device

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

Returns:

nvmlReturn_t nvmlDeviceSetVirtualizationMode(
nvmlDevice_t device,
nvmlGpuVirtualizationMode_t virtualMode,
)#

This method is used to set the virtualization mode corresponding to the GPU.

For Kepler or newer fully supported devices.

Parameters:

  • device – Identifier of the target device

  • virtualMode – virtualization mode. One of NVML_GPU_VIRTUALIZATION_?

Returns:

nvmlReturn_t nvmlDeviceVgpuForceGspUnload(nvmlDevice_t device)#

Executes a forced GSP unload operation on a device.

For Ada or newer fully supported devices. Forces the unload of the GSP firmware on a device currently operating in vGPU mode. This operation forcibly removes the GSP from the targeted GPU and terminates all GSP operations.

Note

This is a disruptive operation that will impact any active vGPU instances and should only be used when absolutely necessary, such as during error recovery or maintenance operations.

Warning

This operation may result in a temporary loss of GPU functionality and should be used with caution.

Parameters:

device – The identifier of the target device

Returns:

nvmlReturn_t nvmlVgpuInstanceGetPlacementId(
nvmlVgpuInstance_t vgpuInstance,
nvmlVgpuPlacementId_t *pPlacement,
)#

Query the placement ID of active vGPU instance.

When in vGPU heterogeneous mode, this function returns a valid placement ID as pPlacement->placementId else NVML_INVALID_VGPU_PLACEMENT_ID is returned. pPlacement->version is the version number of the structure nvmlVgpuPlacementId_t, the caller should set the correct version number to get placement id of the vGPU instance vgpuInstance.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • pPlacement – Pointer to vGPU placement ID structure nvmlVgpuPlacementId_t

Returns:

nvmlReturn_t nvmlVgpuInstanceGetRuntimeStateSize(
nvmlVgpuInstance_t vgpuInstance,
nvmlVgpuRuntimeState_t *pState,
)#

Retrieve the currently used runtime state size of the vGPU instance.

This size represents the maximum in-memory data size utilized by a vGPU instance during standard operation. This measurement is exclusive of frame buffer (FB) data size assigned to the vGPU instance.

For Maxwell or newer fully supported devices.

Parameters:

  • vgpuInstance – Identifier of the target vGPU instance

  • pState – Pointer to the vGPU runtime state’s structure nvmlVgpuRuntimeState_t

Returns:

nvmlReturn_t nvmlVgpuTypeGetFbReservation(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned long long *fbReservation,
)#

Retrieve the static framebuffer reservation of the vGPU type in bytes.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • fbReservation – Reference to return the framebuffer reservation

Returns:

nvmlReturn_t nvmlVgpuTypeGetGspHeapSize(
nvmlVgpuTypeId_t vgpuTypeId,
unsigned long long *gspHeapSize,
)#

Retrieve the static GSP heap size of the vGPU type in bytes.

Parameters:

  • vgpuTypeId – Handle to vGPU type

  • gspHeapSize – Reference to return the GSP heap size value

Returns: