Functions

nvmlReturn_t nvmlDeviceGetGridLicensableFeatures_v4 ( nvmlDevice_t device, nvmlGridLicensableFeatures_t* pGridLicensableFeatures )

Parameters

device

Identifier of the target device

pGridLicensableFeatures

Pointer to structure in which vGPU software licensable features are returned

Returns

• NVML_SUCCESS if licensable features are successfully retrieved
• NVML_ERROR_INVALID_ARGUMENT if pGridLicensableFeatures is NULL
• NVML_ERROR_UNKNOWN on any unexpected error

Description

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.

nvmlReturn_t nvmlDeviceGetHostVgpuMode ( nvmlDevice_t device, nvmlHostVgpuMode_t* pHostVgpuMode )

Parameters

device

The identifier of the target device

pHostVgpuMode

Reference in which to return the current vGPU mode

Returns

• NVML_SUCCESS if device's vGPU mode has been successfully retrieved
• NVML_ERROR_INVALID_ARGUMENT if device handle is 0 or pVgpuMode is NULL
• NVML_ERROR_NOT_SUPPORTED if device doesn't support this feature.
• NVML_ERROR_UNKNOWN if any unexpected error occurred

Description

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.

nvmlReturn_t nvmlDeviceGetVgpuHeterogeneousMode ( nvmlDevice_t device, nvmlVgpuHeterogeneousMode_t* pHeterogeneousMode )

Parameters

device

The identifier of the target device

pHeterogeneousMode

Pointer to the caller-provided structure of nvmlVgpuHeterogeneousMode_t

Returns

• NVML_SUCCESS Upon success
• NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If device is invalid or pHeterogeneousMode is NULL
• NVML_ERROR_NOT_SUPPORTED If device doesn't support this feature
• NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pHeterogeneousMode is invalid
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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.

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

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

• NVML_SUCCESS Upon success
• NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If device or vgpuTypeId is invalid or pPlacementList is NULL
• NVML_ERROR_NOT_SUPPORTED If device or vgpuTypeId isn't supported
• NVML_ERROR_NO_PERMISSION If user doesn't have permission to perform the operation
• NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pPlacementList is invalid
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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.

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

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

• NVML_SUCCESS Upon success
• NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If device or vgpuTypeId is invalid or pPlacementList is NULL
• NVML_ERROR_NOT_SUPPORTED If device or vgpuTypeId isn't supported
• NVML_ERROR_NO_PERMISSION If user doesn't have permission to perform the operation
• NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pPlacementList is invalid
• NVML_ERROR_INSUFFICIENT_SIZE If the buffer is small, element count is returned in pPlacementList->count
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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.

nvmlReturn_t nvmlDeviceGetVirtualizationMode ( nvmlDevice_t device, nvmlGpuVirtualizationMode_t* pVirtualMode )

Parameters

device

Identifier of the target device

pVirtualMode

Reference to virtualization mode. One of NVML_GPU_VIRTUALIZATION_?

Returns

• NVML_SUCCESS if pVirtualMode is fetched
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or pVirtualMode is NULL
• NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is otherwise inaccessible
• NVML_ERROR_UNKNOWN on any unexpected error

Description

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

For Kepler or newer fully supported devices.

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

Parameters

device

The identifier of the target device

capability

Specifies the nvmlDeviceVgpuCapability_t to be set

state

The target capability mode

Returns

• NVML_SUCCESS Successful completion
• NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If device is invalid, or capability is invalid, or state is invalid
• NVML_ERROR_NOT_SUPPORTED The API is not supported in current state, or device not in vGPU mode
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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.

nvmlReturn_t nvmlDeviceSetVgpuHeterogeneousMode ( nvmlDevice_t device, const nvmlVgpuHeterogeneousMode_t* pHeterogeneousMode )

Parameters

device

Identifier of the target device

pHeterogeneousMode

Pointer to the caller-provided structure of nvmlVgpuHeterogeneousMode_t

Returns

• NVML_SUCCESS Upon success
• NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If device or pHeterogeneousMode is NULL or pHeterogeneousMode->mode is invalid
• NVML_ERROR_IN_USE If the device is in use
• NVML_ERROR_NO_PERMISSION If user doesn't have permission to perform the operation
• NVML_ERROR_NOT_SUPPORTED If MIG is enabled or device doesn't support this feature
• NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pHeterogeneousMode is invalid
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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

nvmlReturn_t nvmlDeviceSetVirtualizationMode ( nvmlDevice_t device, nvmlGpuVirtualizationMode_t virtualMode )

Parameters

device

Identifier of the target device

virtualMode

virtualization mode. One of NVML_GPU_VIRTUALIZATION_?

Returns

• NVML_SUCCESS if virtualMode is set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or virtualMode is NULL
• NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is otherwise inaccessible
• NVML_ERROR_NOT_SUPPORTED if setting of virtualization mode is not supported.
• NVML_ERROR_NO_PERMISSION if setting of virtualization mode is not allowed for this client.

Description

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

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlVgpuInstanceGetPlacementId ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuPlacementId_t* pPlacement )

Parameters

vgpuInstance

Identifier of the target vGPU instance

pPlacement

Pointer to vGPU placement ID structure nvmlVgpuPlacementId_t

Returns

• NVML_SUCCESS If information is successfully retrieved
• NVML_ERROR_NOT_FOUND If vgpuInstance does not match a valid active vGPU instance
• NVML_ERROR_INVALID_ARGUMENT If vgpuInstance is invalid or pPlacement is NULL
• NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pPlacement is invalid
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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.

nvmlReturn_t nvmlVgpuInstanceGetRuntimeStateSize ( nvmlVgpuInstance_t vgpuInstance, nvmlVgpuRuntimeState_t* pState )

Parameters

vgpuInstance

Identifier of the target vGPU instance

pState

Pointer to the vGPU runtime state's structure nvmlVgpuRuntimeState_t

Returns

• NVML_SUCCESS If information is successfully retrieved
• NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If vgpuInstance is invalid, or pState is NULL
• NVML_ERROR_NOT_FOUND If vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pState is invalid
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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.

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

Parameters

vgpuTypeId

Handle to vGPU type

fbReservation

Reference to return the framebuffer reservation

Returns

• NVML_SUCCESS Successful completion
• NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If vgpuTypeId is invalid, or fbReservation is NULL
• NVML_ERROR_UNKNOWN On any unexpected error

Description

Retrieve the static framebuffer reservation of the vGPU type in bytes

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

Parameters

vgpuTypeId

Handle to vGPU type

gspHeapSize

Reference to return the GSP heap size value

Returns

• NVML_SUCCESS Successful completion
• NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT If vgpuTypeId is invalid, or gspHeapSize is NULL
• NVML_ERROR_UNKNOWN On any unexpected error

Description

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