|
|
Modules
For Pascal or newer fully supported devices.
nvmlReturn_t
nvmlDeviceFreezeNvLinkUtilizationCounter
(nvmlDevice_t device, unsigned int link, unsigned int
counter, nvmlEnableState_t freeze)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
counter
Specifies the counter that should be frozen (0 or 1).
freeze
NVML_FEATURE_ENABLED = freeze the receive and transmit counters
NVML_FEATURE_DISABLED = unfreeze the receive and transmit counters
Returns
‣ NVML_SUCCESS if counters were successfully frozen or unfrozen
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, link, counter, or freeze is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Deprecated: Freezing NVLINK utilization counters is no longer supported.
Freeze the NVLINK utilization counters Both the receive and transmit counters are
operated on by this function
For Pascal or newer fully supported devices.
262
Modules
nvmlReturn_t nvmlDeviceResetNvLinkUtilizationCounter
(nvmlDevice_t device, unsigned int link, unsigned int
counter)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be reset
counter
Specifies the counter that should be reset (0 or 1)
Returns
‣ NVML_SUCCESS if counters were successfully reset
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, link, or counter is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Deprecated: Resetting NVLINK utilization counters is no longer supported.
Reset the NVLINK utilization counters Both the receive and transmit counters are
operated on by this function
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetNvLinkRemoteDeviceType
(nvmlDevice_t device, unsigned int link,
nvmlIntNvLinkDeviceType_t *pNvLinkDeviceType)
Parameters
device
The device handle of the target GPU
link
The NVLink link index on the target GPU
pNvLinkDeviceType
Pointer in which the output remote device type is returned
263
Modules
Returns
‣ NVML_SUCCESS if pNvLinkDeviceType has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_NOT_SUPPORTED if NVLink is not supported
‣ NVML_ERROR_INVALID_ARGUMENT if device or link is invalid, or
pNvLinkDeviceType 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
Get the NVLink device type of the remote device connected over the given link.
nvmlReturn_t
nvmlDeviceSetNvLinkDeviceLowPowerThreshold
(nvmlDevice_t device, nvmlNvLinkPowerThres_t *info)
Parameters
device
The identifier of the target device
info
Reference to nvmlNvLinkPowerThres_t struct input parameters
Returns
‣ NVML_SUCCESS if the Threshold is successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or Threshold is not
within range
‣ NVML_ERROR_NOT_READY if an internal driver setting prevents the threshold
from being used
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
Description
Set NvLink Low Power Threshold for device.
For Hopper or newer fully supported devices.
264
Modules
nvmlReturn_t nvmlSystemSetNvlinkBwMode (unsigned
int nvlinkBwMode)
Parameters
nvlinkBwMode
nvlink bandwidth mode
Returns
‣ NVML_SUCCESS on success
‣ NVML_ERROR_INVALID_ARGUMENT if an invalid argument is provided
‣ NVML_ERROR_IN_USE if P2P object exists
‣ NVML_ERROR_NOT_SUPPORTED if GPU is not Hopper or newer architecture.
‣ NVML_ERROR_NO_PERMISSION if not root user
Description
Set the global nvlink bandwith mode
nvmlReturn_t nvmlSystemGetNvlinkBwMode (unsigned
int *nvlinkBwMode)
Parameters
nvlinkBwMode
reference of nvlink bandwidth mode
Returns
‣ NVML_SUCCESS on success
‣ NVML_ERROR_INVALID_ARGUMENT if an invalid pointer is provided
‣ NVML_ERROR_NOT_SUPPORTED if GPU is not Hopper or newer architecture.
‣ NVML_ERROR_NO_PERMISSION if not root user
Description
Get the global nvlink bandwith mode
265
Modules
nvmlReturn_t nvmlDeviceGetNvlinkSupportedBwModes
(nvmlDevice_t device, nvmlNvlinkSupportedBwModes_t
*supportedBwMode)
Parameters
device
The identifier of the target device
supportedBwMode
Reference to nvmlNvlinkSupportedBwModes_t
Returns
‣ NVML_SUCCESS if the query was successful
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or supportedBwMode
is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this feature is not supported by the device
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH if the version specified is
not supported
Description
Get the supported NvLink Reduced Bandwidth Modes of the device
BLACKWELL_OR_NEWER%
nvmlReturn_t nvmlDeviceGetNvlinkBwMode
(nvmlDevice_t device, nvmlNvlinkGetBwMode_t
*getBwMode)
Parameters
device
The identifier of the target device
getBwMode
Reference to nvmlNvlinkGetBwMode_t
Returns
‣ NVML_SUCCESS if the query was successful
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or getBwMode is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this feature is not supported by the device
266
Modules
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH if the version specified is
not supported
Description
Get the NvLink Reduced Bandwidth Mode for the device
BLACKWELL_OR_NEWER%
nvmlReturn_t nvmlDeviceSetNvlinkBwMode
(nvmlDevice_t device, nvmlNvlinkSetBwMode_t
*setBwMode)
Parameters
device
The identifier of the target device
setBwMode
Reference to nvmlNvlinkSetBwMode_t
Returns
‣ NVML_SUCCESS if the Bandwidth mode was successfully set
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or setBwMode is NULL
‣ NVML_ERROR_NO_PERMISSION if user does not have permission to change
Bandwidth mode
‣ NVML_ERROR_NOT_SUPPORTED if this feature is not supported by the device
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH if the version specified is
not supported
Description
Set the NvLink Reduced Bandwidth Mode for the device
BLACKWELL_OR_NEWER%
4.20. Event Handling Methods
This chapter describes methods that NVML can perform against each device to register
and wait for some event to occur.
267
Modules
struct nvmlEventData_t
Event Types
typedef struct nvmlEventSet_st *nvmlEventSet_t
Handle to an event set
nvmlReturn_t nvmlEventSetCreate (nvmlEventSet_t
*set)
Parameters
set
Reference in which to return the event handle
Returns
‣ NVML_SUCCESS if the event has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if set is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Create an empty set of events. Event set should be freed by nvmlEventSetFree
For Fermi or newer fully supported devices.
See also:
nvmlEventSetFree
nvmlReturn_t nvmlDeviceRegisterEvents (nvmlDevice_t
device, unsigned long long eventTypes, nvmlEventSet_t
set)
Parameters
device
The identifier of the target device
eventTypes
Bitmask of Event Types to record
268
Modules
set
Set to which add new event types
Returns
‣ NVML_SUCCESS if the event has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if eventTypes is invalid or set is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the platform does not support this feature or
some of requested event types
‣ 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
Starts recording of events on a specified devices and add the events to specified
nvmlEventSet_t
For Fermi or newer fully supported devices. ECC events are available only
on ECC-enabled devices (see nvmlDeviceGetTotalEccErrors) Power capping
events are available only on Power Management enabled devices (see
nvmlDeviceGetPowerManagementMode)
For Linux only.
This call starts recording of events on specific device. All events that occurred
before this call are not recorded. Checking if some event occurred can be done with
nvmlEventSetWait_v2
If function reports NVML_ERROR_UNKNOWN, event set is in undefined state and
should be freed. If function reports NVML_ERROR_NOT_SUPPORTED, event set can
still be used. None of the requested eventTypes are registered in that case.
See also:
Event Types
nvmlDeviceGetSupportedEventTypes
nvmlEventSetWait
nvmlEventSetFree
269
Modules
nvmlReturn_t nvmlDeviceGetSupportedEventTypes
(nvmlDevice_t device, unsigned long long *eventTypes)
Parameters
device
The identifier of the target device
eventTypes
Reference in which to return bitmask of supported events
Returns
‣ NVML_SUCCESS if the eventTypes has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if eventType 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
Returns information about events supported on device
For Fermi or newer fully supported devices.
Events are not supported on Windows. So this function returns an empty mask in
eventTypes on Windows.
See also:
Event Types
nvmlDeviceRegisterEvents
nvmlReturn_t nvmlEventSetWait_v2 (nvmlEventSet_t
set, nvmlEventData_t *data, unsigned int timeoutms)
Parameters
set
Reference to set of events to wait on
data
Reference in which to return event data
timeoutms
Maximum amount of wait time in milliseconds for registered event
270
Modules
Returns
‣ NVML_SUCCESS if the data has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if data is NULL
‣ NVML_ERROR_TIMEOUT if no event arrived in specified timeout or interrupt
arrived
‣ NVML_ERROR_GPU_IS_LOST if a GPU has fallen off the bus or is otherwise
inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Waits on events and delivers events
For Fermi or newer fully supported devices.
If some events are ready to be delivered at the time of the call, function returns
immediately. If there are no events ready to be delivered, function sleeps till event
arrives but not longer than specified timeout. This function in certain conditions can
return before specified timeout passes (e.g. when interrupt arrives)
On Windows, in case of Xid error, the function returns the most recent Xid error type
seen by the system. If there are multiple Xid errors generated before nvmlEventSetWait
is invoked then the last seen Xid error type is returned for all Xid error events.
On Linux, every Xid error event would return the associated event data and other
information if applicable.
In MIG mode, if device handle is provided, the API reports all the events for the
available instances, only if the caller has appropriate privileges. In absence of required
privileges, only the events which affect all the instances (i.e. whole device) are reported.
This API does not currently support per-instance event reporting using MIG device
handles.
See also:
Event Types
nvmlDeviceRegisterEvents
nvmlReturn_t nvmlEventSetFree (nvmlEventSet_t set)
Parameters
set
Reference to events to be released
271
Modules
Returns
‣ NVML_SUCCESS if the event has been successfully released
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Releases events in the set
For Fermi or newer fully supported devices.
See also:
nvmlDeviceRegisterEvents
nvmlReturn_t nvmlSystemEventSetFree
(nvmlSystemEventSetFreeRequest_t *request)
Returns
‣ NVML_SUCCESS if the event has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if request is NULL
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH for unsupported version
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Releases system event set
For Fermi or newer fully supported devices.
See also:
nvmlDeviceRegisterEvents
nvmlReturn_t nvmlSystemRegisterEvents
(nvmlSystemRegisterEventRequest_t *request)
Parameters
request
Reference to the struct nvmlSystemRegisterEventRequest_t
272
Modules
Returns
‣ NVML_SUCCESS if the event has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if request is NULL
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH for unsupported version
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Starts recording of events on system and add the events to specified
nvmlSystemEventSet_t
For Linux only.
This call starts recording of events on specific device. All events that occurred
before this call are not recorded. Checking if some event occurred can be done with
nvmlSystemEventSetWait
If function reports NVML_ERROR_UNKNOWN, event set is in undefined state and
should be freed. If function reports NVML_ERROR_NOT_SUPPORTED, event set can
still be used. None of the requested eventTypes are registered in that case.
See also:
nvmlSystemEventType
nvmlSystemEventSetWait
nvmlEventSetFree
nvmlReturn_t nvmlSystemEventSetWait
(nvmlSystemEventSetWaitRequest_t *request)
Parameters
request
Reference in which to nvmlSystemEventSetWaitRequest_t
Returns
‣ NVML_SUCCESS if the event has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if request is NULL
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH for unsupported version
‣ NVML_ERROR_TIMEOUT if no event notification after timeoutms
‣ NVML_ERROR_UNKNOWN on any unexpected error
273
Modules
Description
Waits on system events and delivers events
For Fermi or newer fully supported devices.
If some events are ready to be delivered at the time of the call, function returns
immediately. If there are no events ready to be delivered, function sleeps till event
arrives but not longer than specified timeout. This function in certain conditions can
return before specified timeout passes (e.g. when interrupt arrives)
if the return request->numEvent equals to request->dataSize, there might be outstanding
event, it is recommended to call nvmlSystemEventSetWait again to query all the events.
See also:
nvmlSystemEventType
nvmlSystemRegisterEvents
4.20.1. Event Types
Event Handling Methods
Event Types which user can be notified about. See description of particular functions for
details.
See nvmlDeviceRegisterEvents and nvmlDeviceGetSupportedEventTypes to check
which devices support each event.
Types can be combined with bitwise or operator '|' when passed to
nvmlDeviceRegisterEvents
#define nvmlEventTypeNone 0x0000000000000000LL
Mask with no events.
#define nvmlEventTypeSingleBitEccError 0x0000000000000001LL
Event about single bit ECC errors.
A corrected texture memory error is not an ECC error, so it does not generate a single
bit event
274
Modules
#define nvmlEventTypeDoubleBitEccError 0x0000000000000002LL
Event about double bit ECC errors.
An uncorrected texture memory error is not an ECC error, so it does not generate a
double bit event
#define nvmlEventTypePState 0x0000000000000004LL
Event about PState changes.
On Fermi architecture PState changes are also an indicator that GPU is throttling
down due to no work being executed on the GPU, power capping or thermal capping.
In a typical situation, Fermi-based GPU should stay in P0 for the duration of the
execution of the compute process.
#define nvmlEventTypeXidCriticalError 0x0000000000000008LL
Event that Xid critical error occurred.
#define nvmlEventTypeClock 0x0000000000000010LL
Event about clock changes.
Kepler only
#define nvmlEventTypePowerSourceChange 0x0000000000000080LL
Event about AC/Battery power source changes.
#define nvmlEventMigConfigChange 0x0000000000000100LL
Event about MIG configuration changes.
#define nvmlEventTypeSingleBitEccErrorStorm
0x0000000000000200LL
Event about single bit ECC error storm.
#define nvmlEventTypeDramRetirementEvent
0x0000000000000400LL
Event about DRAM retirement event.
275
Modules
#define nvmlEventTypeDramRetirementFailure
0x0000000000000800LL
Event about DRAM retirement failure.
#define nvmlEventTypeNonFatalPoisonError 0x0000000000001000LL
Event for Non Fatal Poison.
#define nvmlEventTypeFatalPoisonError 0x0000000000002000LL
Event for Fatal Poison.
#define nvmlEventTypeGpuUnavailableError 0x0000000000004000LL
Event for GPU Unavailable.
#define nvmlEventTypeGpuRecoveryAction 0x0000000000008000LL
Event for GPU Recovery Action.
#define nvmlEventTypeAll (nvmlEventTypeNone
\ | nvmlEventTypeSingleBitEccError \ |
nvmlEventTypeDoubleBitEccError \ | nvmlEventTypePState \
| nvmlEventTypeClock \ | nvmlEventTypeXidCriticalError \ |
nvmlEventTypePowerSourceChange \ | nvmlEventMigConfigChange
\ | nvmlEventTypeSingleBitEccErrorStorm
\ | nvmlEventTypeDramRetirementEvent
\ | nvmlEventTypeDramRetirementFailure
\ | nvmlEventTypeNonFatalPoisonError
\ | nvmlEventTypeFatalPoisonError \ |
nvmlEventTypeGpuUnavailableError \ |
nvmlEventTypeGpuRecoveryAction)
Mask of all events.
4.21. Drain states
This chapter describes methods that NVML can perform against each device to control
their drain state and recognition by NVML and NVIDIA kernel driver. These methods
can be used with out-of-band tools to power on/off GPUs, enable robust reset scenarios,
etc.
276
Modules
nvmlReturn_t nvmlDeviceModifyDrainState
(nvmlPciInfo_t *pciInfo, nvmlEnableState_t newState)
Parameters
pciInfo
The PCI address of the GPU drain state to be modified
newState
The drain state that should be entered, see nvmlEnableState_t
Returns
‣ NVML_SUCCESS if counters were successfully reset
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if nvmlIndex or newState is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_NO_PERMISSION if the calling process has insufficient
permissions to perform operation
‣ NVML_ERROR_IN_USE if the device has persistence mode turned on
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Modify the drain state of a GPU. This method forces a GPU to no longer accept new
incoming requests. Any new NVML process will no longer see this GPU. Persistence
mode for this GPU must be turned off before this call is made. Must be called as
administrator. For Linux only.
For Pascal or newer fully supported devices. Some Kepler devices supported.
nvmlReturn_t nvmlDeviceQueryDrainState
(nvmlPciInfo_t *pciInfo, nvmlEnableState_t
*currentState)
Parameters
pciInfo
The PCI address of the GPU drain state to be queried
currentState
The current drain state for this GPU, see nvmlEnableState_t
277
Modules
Returns
‣ NVML_SUCCESS if counters were successfully reset
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if nvmlIndex or currentState is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Query the drain state of a GPU. This method is used to check if a GPU is in a currently
draining state. For Linux only.
For Pascal or newer fully supported devices. Some Kepler devices supported.
nvmlReturn_t nvmlDeviceRemoveGpu_v2 (nvmlPciInfo_t
*pciInfo, nvmlDetachGpuState_t gpuState,
nvmlPcieLinkState_t linkState)
Parameters
pciInfo
The PCI address of the GPU to be removed
gpuState
Whether the GPU is to be removed, from the OS see nvmlDetachGpuState_t
linkState
Requested upstream PCIe link state, see nvmlPcieLinkState_t
Returns
‣ NVML_SUCCESS if counters were successfully reset
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if nvmlIndex is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_IN_USE if the device is still in use and cannot be removed
Description
This method will remove the specified GPU from the view of both NVML and the
NVIDIA kernel driver as long as no other processes are attached. If other processes are
attached, this call will return NVML_ERROR_IN_USE and the GPU will be returned
to its original "draining" state. Note: the only situation where a process can still be
attached after nvmlDeviceModifyDrainState() is called to initiate the draining state is
if that process was using, and is still using, a GPU before the call was made. Also note,
278
Modules
persistence mode counts as an attachment to the GPU thus it must be disabled prior to
this call.
For long-running NVML processes please note that this will change the enumeration of
current GPUs. For example, if there are four GPUs present and GPU1 is removed, the
new enumeration will be 0-2. Also, device handles after the removed GPU will not be
valid and must be re-established. Must be run as administrator. For Linux only.
For Pascal or newer fully supported devices. Some Kepler devices supported.
nvmlReturn_t nvmlDeviceDiscoverGpus (nvmlPciInfo_t
*pciInfo)
Parameters
pciInfo
The PCI tree to be searched. Only the domain, bus, and device fields are used in this
call.
Returns
‣ NVML_SUCCESS if counters were successfully reset
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if pciInfo is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the operating system does not support this
feature
‣ NVML_ERROR_OPERATING_SYSTEM if the operating system is denying this
feature
‣ NVML_ERROR_NO_PERMISSION if the calling process has insufficient
permissions to perform operation
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Request the OS and the NVIDIA kernel driver to rediscover a portion of the PCI
subsystem looking for GPUs that were previously removed. The portion of the PCI
tree can be narrowed by specifying a domain, bus, and device. If all are zeroes then the
entire PCI tree will be searched. Please note that for long-running NVML processes the
enumeration will change based on how many GPUs are discovered and where they are
inserted in bus order.
In addition, all newly discovered GPUs will be initialized and their ECC scrubbed which
may take several seconds per GPU. Also, all device handles are no longer guaranteed to
be valid post discovery.
279
Modules
Must be run as administrator. For Linux only.
For Pascal or newer fully supported devices. Some Kepler devices supported.
4.22. Field Value Queries
This chapter describes NVML operations that are associated with retrieving Field Values
from NVML
nvmlReturn_t nvmlDeviceGetFieldValues (nvmlDevice_t
device, int valuesCount, nvmlFieldValue_t *values)
Parameters
device
The device handle of the GPU to request field values for
valuesCount
Number of entries in values that should be retrieved
values
Array of valuesCount structures to hold field values. Each value's fieldId must be
populated prior to this call
Returns
‣ NVML_SUCCESS if any values in values were populated. Note that you must check
the nvmlReturn field of each value for each individual status
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or values is NULL
Description
Request values for a list of fields for a device. This API allows multiple fields to be
queried at once. If any of the underlying fieldIds are populated by the same driver call,
the results for those field IDs will be populated from a single call rather than making a
driver call for each fieldId.
280
Modules
nvmlReturn_t nvmlDeviceClearFieldValues
(nvmlDevice_t device, int valuesCount,
nvmlFieldValue_t *values)
Parameters
device
The device handle of the GPU to request field values for
valuesCount
Number of entries in values that should be cleared
values
Array of valuesCount structures to hold field values. Each value's fieldId must be
populated prior to this call
Returns
‣ NVML_SUCCESS if any values in values were cleared. Note that you must check the
nvmlReturn field of each value for each individual status
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or values is NULL
Description
Clear values for a list of fields for a device. This API allows multiple fields to be cleared
at once.
4.23. vGPU APIs
This chapter describes operations that are associated with NVIDIA vGPU Software
products.
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_?
281
Modules
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 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.
282
Modules
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 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
283
Modules
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 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
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 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
284
Modules
‣ 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 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.
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
285
Modules
‣ 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
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
286
Modules
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
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 MIG is enabled or device or vgpuTypeId isn't
supported
‣ NVML_ERROR_NO_PERMISSION If user doesn't have permission to perform the
operation
287
Modules
‣ 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 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
288
Modules
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 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
289
Modules
‣ 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 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.
290
Modules
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.
4.24. vGPU Management
This chapter describes APIs supporting NVIDIA vGPU.
nvmlReturn_t nvmlGetVgpuDriverCapabilities
(nvmlVgpuDriverCapability_t capability, unsigned int
*capResult)
Parameters
capability
Specifies the nvmlVgpuDriverCapability_t to be queried
capResult
A boolean for the queried capability indicating that feature is supported
Returns
‣ NVML_SUCCESS successful completion
291
Modules
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if capability is invalid, or capResult is
NULL
‣ NVML_ERROR_NOT_SUPPORTED the API is not supported in current state or
devices not in vGPU mode
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
nvmlReturn_t nvmlDeviceGetVgpuCapabilities
(nvmlDevice_t device, nvmlDeviceVgpuCapability_t
capability, unsigned int *capResult)
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
‣ 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 capResult is NULL
‣ 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
Retrieve the requested vGPU capability for GPU.
292
Modules
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.
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_INSUFFICIENT_SIZE vgpuTypeIds buffer is too small, array
element count is returned in vgpuCount
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuCount is NULL or device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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.
293
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_INSUFFICIENT_SIZE vgpuTypeIds buffer is too small, array
element count is returned in vgpuCount
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuCount is NULL
‣ NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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.
294
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or
vgpuTypeClass is NULL
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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
295
Modules
Returns
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or name is NULL
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 nvmlVgpuTypeGetGpuInstanceProfileId
(nvmlVgpuTypeId_t vgpuTypeId, unsigned int
*gpuInstanceProfileId)
Parameters
vgpuTypeId
Handle to vGPU type
gpuInstanceProfileId
GPU Instance Profile ID
Returns
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_NOT_SUPPORTED if device is not in vGPU Host virtualization
mode
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or
gpuInstanceProfileId is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
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.
296
Modules
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
Subsystem ID and subsystem vendor ID of the device contained in single 32 bit 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 deviceId or
subsystemID are NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve the device ID of a 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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
297
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or fbSize is
NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve the vGPU framebuffer size in bytes.
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or
numDisplayHeads is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
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
298
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or xdim or ydim
are NULL, or displayIndex is out of range.
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve vGPU display head's maximum supported resolution.
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or
vgpuTypeLicenseString is NULL
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
299
Modules
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 nvmlVgpuTypeGetFrameRateLimit
(nvmlVgpuTypeId_t vgpuTypeId, unsigned int
*frameRateLimit)
Parameters
vgpuTypeId
Handle to vGPU type
frameRateLimit
Reference to return the frame rate limit value
Returns
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_NOT_SUPPORTED if frame rate limiter is turned off for the vGPU
type
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or
frameRateLimit is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve the static frame rate limit value of the vGPU type
For Kepler or newer fully supported devices.
300
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid or is not
supported on target device, or vgpuInstanceCount is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
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
301
Modules
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
vgpuInstanceCountPerVm is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve the maximum number of vGPU instances supported per VM for given vGPU
type
For Kepler or newer fully supported devices.
nvmlReturn_t nvmlVgpuTypeGetBAR1Info
(nvmlVgpuTypeId_t vgpuTypeId,
nvmlVgpuTypeBar1Info_t *bar1Info)
Parameters
vgpuTypeId
Handle to vGPU type
bar1Info
Pointer to the vGPU type BAR1 information structure nvmlVgpuTypeBar1Info_t
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 bar1Info is
NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve the BAR1 info for given vGPU type.
For Maxwell or newer fully supported devices.
302
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or vgpuCount is NULL
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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.
303
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vmId or vmIdType is NULL, or
vgpuInstance is 0
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
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.
304
Modules
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or uuid is NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
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
305
Modules
version
Caller-supplied buffer to return driver version string
length
Size of version buffer
Returns
‣ NVML_SUCCESS if version has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_INSUFFICIENT_SIZE if length is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 nvmlVgpuInstanceGetFbUsage
(nvmlVgpuInstance_t vgpuInstance, unsigned long long
*fbUsage)
Parameters
vgpuInstance
The identifier of the target instance
fbUsage
Pointer to framebuffer usage in bytes
Returns
‣ NVML_SUCCESS successful completion
306
Modules
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or fbUsage is NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 nvmlVgpuInstanceGetLicenseStatus
(nvmlVgpuInstance_t vgpuInstance, unsigned int
*licensed)
Parameters
vgpuInstance
Identifier of the target vGPU instance
licensed
Reference to return the licensing status
Returns
‣ NVML_SUCCESS if licensed has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or licensed is NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
307
Modules
nvmlReturn_t nvmlVgpuInstanceGetType
(nvmlVgpuInstance_t vgpuInstance, nvmlVgpuTypeId_t
*vgpuTypeId)
Parameters
vgpuInstance
Identifier of the target vGPU instance
vgpuTypeId
Reference to return the vgpuTypeId
Returns
‣ NVML_SUCCESS if vgpuTypeId has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or vgpuTypeId is
NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 nvmlVgpuInstanceGetFrameRateLimit
(nvmlVgpuInstance_t vgpuInstance, unsigned int
*frameRateLimit)
Parameters
vgpuInstance
Identifier of the target vGPU instance
frameRateLimit
Reference to return the frame rate limit
Returns
‣ NVML_SUCCESS if frameRateLimit has been set
308
Modules
‣ NVML_ERROR_NOT_SUPPORTED if frame rate limiter is turned off for the vGPU
type
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or frameRateLimit is
NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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
‣ NVML_SUCCESS if the vgpuInstance's ECC mode has been successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or mode is NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_NOT_SUPPORTED if the vGPU doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieve the current ECC mode of vGPU instance.
309
Modules
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
‣ NVML_SUCCESS if encoderCapacity has been retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or encoderQueryType
is invalid
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 nvmlVgpuInstanceSetEncoderCapacity
(nvmlVgpuInstance_t vgpuInstance, unsigned int
encoderCapacity)
Parameters
vgpuInstance
Identifier of the target vGPU instance
encoderCapacity
Unsigned int for the encoder capacity value
Returns
‣ NVML_SUCCESS if encoderCapacity has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
310
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or encoderCapacity is
out of range of 0-100.
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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
‣ NVML_SUCCESS if sessionCount, averageFps and averageLatency is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if sessionCount , or averageFps or
averageLatency is NULL or vgpuInstance is 0.
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the current encoder statistics of a vGPU Instance
For Maxwell or newer fully supported devices.
311
Modules
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
‣ NVML_SUCCESS if sessionInfo is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INSUFFICIENT_SIZE if sessionCount is too small, array element
count is returned in sessionCount
‣ NVML_ERROR_INVALID_ARGUMENT if sessionCount is NULL, or vgpuInstance
is 0.
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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.
312
Modules
nvmlReturn_t nvmlVgpuInstanceGetFBCStats
(nvmlVgpuInstance_t vgpuInstance, nvmlFBCStats_t
*fbcStats)
Parameters
vgpuInstance
Identifier of the target vGPU instance
fbcStats
Reference to nvmlFBCStats_t structure containing NvFBC stats
Returns
‣ NVML_SUCCESS if fbcStats is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or fbcStats is NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the active frame buffer capture sessions 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
‣ NVML_SUCCESS if sessionInfo is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
313
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or sessionCount is
NULL.
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_INSUFFICIENT_SIZE if sessionCount is too small, array element
count is returned in sessionCount
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 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.
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 nvmlVgpuInstanceGetGpuInstanceId
(nvmlVgpuInstance_t vgpuInstance, unsigned int
*gpuInstanceId)
Parameters
vgpuInstance
Identifier of the target vGPU instance
gpuInstanceId
GPU Instance ID
Returns
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
314
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or gpuInstanceId is
NULL.
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
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 nvmlVgpuInstanceGetGpuPciId
(nvmlVgpuInstance_t vgpuInstance, char *vgpuPciId,
unsigned int *length)
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
‣ NVML_SUCCESS if vGPU PCI Id is sucessfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or vgpuPciId is NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_DRIVER_NOT_LOADED if NVIDIA driver is not running on the
vGPU instance
‣ NVML_ERROR_INSUFFICIENT_SIZE if length is too small, length is set to required
length
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the PCI Id of the given vGPU Instance i.e. the PCI Id of the GPU as seen inside
the VM.
315
Modules
The vGPU PCI id is returned as "00000000:00:00.0" if NVIDIA driver is not installed on
the vGPU instance.
nvmlReturn_t nvmlVgpuTypeGetCapabilities
(nvmlVgpuTypeId_t vgpuTypeId, nvmlVgpuCapability_t
capability, unsigned int *capResult)
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
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or capability is
invalid, or capResult is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
nvmlReturn_t nvmlVgpuInstanceGetMdevUUID
(nvmlVgpuInstance_t vgpuInstance, char *mdevUuid,
unsigned int size)
Parameters
vgpuInstance
Identifier of the target vGPU instance
316
Modules
mdevUuid
Pointer to caller-supplied buffer to hold MDEV UUID
size
Size of buffer in bytes
Returns
‣ NVML_SUCCESS successful completion
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_NOT_SUPPORTED on any hypervisor other than KVM
‣ NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or mdevUuid is
NULL
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_INSUFFICIENT_SIZE if size is too small
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
nvmlReturn_t nvmlGpuInstanceGetCreatableVgpus
(nvmlGpuInstance_t gpuInstance, nvmlVgpuTypeIdInfo_t
*pVgpus)
Parameters
gpuInstance
The GPU instance handle
pVgpus
Pointer to the caller-provided structure of nvmlVgpuTypeIdInfo_t
Returns
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
317
Modules
‣ NVML_ERROR_INVALID_ARGUMENT If gpuInstance is NULL or invalid, or
pVgpus is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
‣ NVML_ERROR_INSUFFICIENT_SIZE If pVgpus->vgpuTypeIds buffer is small
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pVgpus is
invalid
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
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.
nvmlReturn_t
nvmlVgpuTypeGetMaxInstancesPerGpuInstance
(nvmlVgpuTypeMaxInstance_t *pMaxInstance)
Parameters
pMaxInstance
Pointer to the caller-provided structure of nvmlVgpuTypeMaxInstance_t
Returns
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If pMaxInstance is NULL or
pMaxInstance->vgpuTypeId is invalid
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
or non-MIG vGPU type
318
Modules
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pMaxInstance is invalid
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Retrieve the maximum number of vGPU instances per GPU instance for given vGPU
type
nvmlReturn_t nvmlGpuInstanceGetActiveVgpus
(nvmlGpuInstance_t gpuInstance,
nvmlActiveVgpuInstanceInfo_t *pVgpuInstanceInfo)
Parameters
gpuInstance
The GPU instance handle
pVgpuInstanceInfo
Pointer to the vGPU instance information structure nvmlActiveVgpuInstanceInfo_t
Returns
‣ NVML_SUCCESS Successful completion
‣ NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If gpuInstance is NULL or invalid, or
pVgpuInstanceInfo is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_INSUFFICIENT_SIZE pVgpuInstanceInfo->vgpuTypeIds buffer is
too small, array element count is returned in pVgpuInstanceInfo->vgpuCount
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pVgpuInstanceInfo is invalid
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
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
319
Modules
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.
nvmlReturn_t nvmlGpuInstanceSetVgpuSchedulerState
(nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerState_t *pScheduler)
Parameters
gpuInstance
The GPU instance handle
pScheduler
Pointer to the caller-provided structure of nvmlVgpuSchedulerState_t
Returns
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_INVALID_ARGUMENT If gpuInstance is NULL or invalid, or
pScheduler is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_RESET_REQUIRED If setting the state failed with fatal error, reboot
is required
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
or if any vGPU instance exists
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of pScheduler
is invalid
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Set vGPU scheduler state for the given GPU instance
GB20X_OR_NEWER%
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.
320
Modules
nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerState
(nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerStateInfo_t *pSchedulerStateInfo)
Parameters
gpuInstance
The GPU instance handle
pSchedulerStateInfo
Reference in which pSchedulerStateInfo is returned
Returns
‣ NVML_SUCCESS vGPU scheduler state is successfully obtained
‣ NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If gpuInstance is NULL or invalid, or
pSchedulerStateInfo is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pSchedulerStateInfo is invalid
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
GB20X_OR_NEWER%
nvmlReturn_t nvmlGpuInstanceGetVgpuSchedulerLog
(nvmlGpuInstance_t gpuInstance,
nvmlVgpuSchedulerLogInfo_t *pSchedulerLogInfo)
Parameters
gpuInstance
The GPU instance handle
pSchedulerLogInfo
Reference in which pSchedulerLogInfo is written
Returns
‣ NVML_SUCCESS vGPU scheduler logs are successfully obtained
321
Modules
‣ NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If gpuInstance is NULL or invalid, or
pSchedulerLogInfo is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pSchedulerLogInfo is invalid
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
GB20X_OR_NEWER%
nvmlReturn_t
nvmlGpuInstanceGetVgpuTypeCreatablePlacements
(nvmlGpuInstance_t gpuInstance,
nvmlVgpuCreatablePlacementInfo_t
*pCreatablePlacementInfo)
Parameters
gpuInstance
The GPU instance handle
pCreatablePlacementInfo
Pointer to the list of vGPU creatable placement structure
nvmlVgpuCreatablePlacementInfo_t
Returns
‣ NVML_SUCCESS Successful completion
‣ NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If gpuInstance is NULL or invalid, or
pCreatablePlacementInfo is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_INSUFFICIENT_SIZE If the buffer is small, element count is
returned in pCreatablePlacementInfo->count
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pCreatablePlacementInfo is invalid
322
Modules
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
or vGPU heterogeneous mode is not enabled
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Query the creatable vGPU placement ID of the vGPU type within a GPU instance.
GB20X_OR_NEWER%
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.
nvmlReturn_t
nvmlGpuInstanceGetVgpuHeterogeneousMode
(nvmlGpuInstance_t gpuInstance,
nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode)
Parameters
gpuInstance
The GPU instance handle
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 gpuInstance is NULL or invalid, or
pHeterogeneousMode is NULL or GPU Instance Id is invalid
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
or not in MIG mode
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pHeterogeneousMode is invalid
323
Modules
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
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.
GB20X_OR_NEWER%
nvmlReturn_t
nvmlGpuInstanceSetVgpuHeterogeneousMode
(nvmlGpuInstance_t gpuInstance, const
nvmlVgpuHeterogeneousMode_t *pHeterogeneousMode)
Parameters
gpuInstance
The GPU instance handle
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 gpuInstance is NULL or invalid, or
pHeterogeneousMode is NULL or pHeterogeneousMode->mode is invalid or GPU
Instance Id is invalid
‣ NVML_ERROR_IN_USE If the gpuInstance is in use
‣ NVML_ERROR_NOT_SUPPORTED If not on a vGPU host or an unsupported GPU
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
pHeterogeneousMode is invalid
‣ NVML_ERROR_UNKNOWN On any unexpected error
324
Modules
Description
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.
GB20X_OR_NEWER%
4.25. vGPU Migration
This chapter describes operations that are associated with vGPU Migration.
struct nvmlVgpuVersion_t
struct nvmlVgpuMetadata_t
struct nvmlVgpuPgpuMetadata_t
struct nvmlVgpuPgpuCompatibility_t
enum nvmlVgpuVmCompatibility_t
vGPU VM compatibility codes
Values
NVML_VGPU_VM_COMPATIBILITY_NONE = 0x0
vGPU is not runnable
NVML_VGPU_VM_COMPATIBILITY_COLD = 0x1
vGPU is runnable from a cold / powered-off state (ACPI S5)
NVML_VGPU_VM_COMPATIBILITY_HIBERNATE = 0x2
vGPU is runnable from a hibernated state (ACPI S4)
325
Modules
NVML_VGPU_VM_COMPATIBILITY_SLEEP = 0x4
vGPU is runnable from a sleeped state (ACPI S3)
NVML_VGPU_VM_COMPATIBILITY_LIVE = 0x8
vGPU is runnable from a live/paused (ACPI S0)
enum nvmlVgpuPgpuCompatibilityLimitCode_t
vGPU-pGPU compatibility limit codes
Values
NVML_VGPU_COMPATIBILITY_LIMIT_NONE = 0x0
Compatibility is not limited.
NVML_VGPU_COMPATIBILITY_LIMIT_HOST_DRIVER = 0x1
ompatibility is limited by host driver version.
NVML_VGPU_COMPATIBILITY_LIMIT_GUEST_DRIVER = 0x2
Compatibility is limited by guest driver version.
NVML_VGPU_COMPATIBILITY_LIMIT_GPU = 0x4
Compatibility is limited by GPU hardware.
NVML_VGPU_COMPATIBILITY_LIMIT_OTHER = 0x80000000
Compatibility is limited by an undefined factor.
nvmlReturn_t nvmlVgpuInstanceGetMetadata
(nvmlVgpuInstance_t vgpuInstance,
nvmlVgpuMetadata_t *vgpuMetadata, unsigned int
*bufferSize)
Parameters
vgpuInstance
vGPU instance handle
vgpuMetadata
Pointer to caller-supplied buffer into which vGPU metadata is written
bufferSize
Size of vgpuMetadata buffer
Returns
‣ NVML_SUCCESS vGPU metadata structure was successfully returned
‣ NVML_ERROR_INSUFFICIENT_SIZE vgpuMetadata buffer is too small, required
size is returned in bufferSize
‣ NVML_ERROR_INVALID_ARGUMENT if bufferSize is NULL or vgpuInstance is 0;
if vgpuMetadata is NULL and the value of bufferSize is not 0.
326
Modules
‣ NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU
instance on the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
nvmlVgpuInstanceGetMetadata() 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
nvmlVgpuGuestInfoState_t field.
The VMM may choose to read and save the vGPU's VM info as persistent metadata
associated with the VM, and provide it to Virtual GPU Manager when creating a vGPU
for subsequent instances of the VM.
The caller passes in a buffer via vgpuMetadata, with the size of the buffer in bufferSize.
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 bufferSize.
nvmlReturn_t nvmlDeviceGetVgpuMetadata
(nvmlDevice_t device, nvmlVgpuPgpuMetadata_t
*pgpuMetadata, unsigned int *bufferSize)
Parameters
device
The identifier of the target device
pgpuMetadata
Pointer to caller-supplied buffer into which pgpuMetadata is written
bufferSize
Pointer to size of pgpuMetadata buffer
Returns
‣ NVML_SUCCESS GPU metadata structure was successfully returned
‣ NVML_ERROR_INSUFFICIENT_SIZE pgpuMetadata buffer is too small, required
size is returned in bufferSize
‣ NVML_ERROR_INVALID_ARGUMENT if bufferSize is NULL or device is invalid;
if pgpuMetadata is NULL and the value of bufferSize is not 0.
327
Modules
‣ NVML_ERROR_NOT_SUPPORTED vGPU is not supported by the system
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Returns a vGPU metadata structure for the physical GPU indicated by device. 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.
The caller passes in a buffer via pgpuMetadata, with the size of the buffer in bufferSize.
If the pgpuMetadata structure is too large to fit in the supplied buffer, the function
returns NVML_ERROR_INSUFFICIENT_SIZE with the size needed in bufferSize.
nvmlReturn_t nvmlGetVgpuCompatibility
(nvmlVgpuMetadata_t *vgpuMetadata,
nvmlVgpuPgpuMetadata_t *pgpuMetadata,
nvmlVgpuPgpuCompatibility_t *compatibilityInfo)
Parameters
vgpuMetadata
Pointer to caller-supplied vGPU metadata structure
pgpuMetadata
Pointer to caller-supplied GPU metadata structure
compatibilityInfo
Pointer to caller-supplied buffer to hold compatibility info
Returns
‣ NVML_SUCCESS vGPU metadata structure was successfully returned
‣ NVML_ERROR_INVALID_ARGUMENT If vgpuMetadata or pgpuMetadata or
bufferSize are NULL
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Takes a vGPU instance metadata structure read from nvmlVgpuInstanceGetMetadata(),
and a vGPU metadata structure for a physical GPU read from
nvmlDeviceGetVgpuMetadata(), and returns compatibility information of the vGPU
instance and the physical GPU.
The caller passes in a buffer via compatibilityInfo, into which a compatibility
information structure is written. The structure defines the states in which the vGPU /
328
Modules
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 compatability. (see
nvmlVgpuPgpuCompatibilityLimitCode_t for details).
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.
nvmlReturn_t nvmlDeviceGetPgpuMetadataString
(nvmlDevice_t device, char *pgpuMetadata, unsigned int
*bufferSize)
Parameters
device
The identifier of the target device
pgpuMetadata
Pointer to caller-supplied buffer into which pgpuMetadata is written
bufferSize
Pointer to size of pgpuMetadata buffer
Returns
‣ NVML_SUCCESS GPU metadata structure was successfully returned
‣ NVML_ERROR_INSUFFICIENT_SIZE pgpuMetadata buffer is too small, required
size is returned in bufferSize
‣ NVML_ERROR_INVALID_ARGUMENT If bufferSize is NULL or device is invalid;
if pgpuMetadata is NULL and the value of bufferSize is not 0.
‣ NVML_ERROR_NOT_SUPPORTED If vGPU is not supported by the system
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Returns the properties of the physical GPU indicated by the device in an ascii-encoded
string format.
The caller passes in a buffer via pgpuMetadata, with the size of the buffer in
bufferSize. If the string is too large to fit in the supplied buffer, the function returns
NVML_ERROR_INSUFFICIENT_SIZE with the size needed in bufferSize.
329
Modules
nvmlReturn_t nvmlDeviceGetVgpuSchedulerLog
(nvmlDevice_t device, nvmlVgpuSchedulerLog_t
*pSchedulerLog)
Parameters
device
The identifier of the target device
pSchedulerLog
Reference in which pSchedulerLog is written
Returns
‣ NVML_SUCCESS vGPU scheduler logs were successfully obtained
‣ NVML_ERROR_INVALID_ARGUMENT If pSchedulerLog is NULL or device is
invalid
‣ NVML_ERROR_NOT_SUPPORTED If MIG is enabled or device not in vGPU host
mode
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Returns the vGPU Software scheduler logs. pSchedulerLog 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.
nvmlReturn_t nvmlDeviceGetVgpuSchedulerState
(nvmlDevice_t device, nvmlVgpuSchedulerGetState_t
*pSchedulerState)
Parameters
device
The identifier of the target device
pSchedulerState
Reference in which pSchedulerState is returned
330
Modules
Returns
‣ NVML_SUCCESS vGPU scheduler state is successfully obtained
‣ NVML_ERROR_INVALID_ARGUMENT If pSchedulerState is NULL or device is
invalid
‣ NVML_ERROR_NOT_SUPPORTED If MIG is enabled or device not in vGPU host
mode
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Returns the vGPU scheduler state. The information returned in
nvmlVgpuSchedulerGetState_t is not relevant if the BEST EFFORT policy is set.
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetVgpuSchedulerCapabilities
(nvmlDevice_t device, nvmlVgpuSchedulerCapabilities_t
*pCapabilities)
Parameters
device
The identifier of the target device
pCapabilities
Reference in which pCapabilities is written
Returns
‣ NVML_SUCCESS vGPU scheduler capabilities were successfully obtained
‣ NVML_ERROR_INVALID_ARGUMENT If pCapabilities is NULL or device is
invalid
‣ NVML_ERROR_NOT_SUPPORTED The API is not supported in current state or
device not in vGPU host mode
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Returns the vGPU scheduler capabilities. The list of supported vGPU
schedulers returned in nvmlVgpuSchedulerCapabilities_t is from the
NVML_VGPU_SCHEDULER_POLICY_*. This list enumerates the supported
scheduler policies if the engine is Graphics type. The other values in
nvmlVgpuSchedulerCapabilities_t are also applicable if the engine is Graphics type.
For other engine types, it is BEST EFFORT policy. If ARR is supported and enabled,
scheduling frequency and averaging factor are applicable else timeSlice is applicable.
331
Modules
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceSetVgpuSchedulerState
(nvmlDevice_t device, nvmlVgpuSchedulerSetState_t
*pSchedulerState)
Parameters
device
The identifier of the target device
pSchedulerState
vGPU pSchedulerState to set
Returns
‣ NVML_SUCCESS vGPU scheduler state has been successfully set
‣ NVML_ERROR_INVALID_ARGUMENT If pSchedulerState is NULL or device is
invalid
‣ NVML_ERROR_RESET_REQUIRED If setting pSchedulerState failed with fatal
error, reboot is required to overcome from this error.
‣ NVML_ERROR_NOT_SUPPORTED If MIG is enabled or device not in vGPU host
mode or if any vGPU instance currently exists on the device
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
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. In
nvmlVgpuSchedulerSetState_t, IFF enableARRMode is enabled then provide
avgFactorForARR and frequency as input. If enableARRMode is disabled then provide
timeslice as input.
332
Modules
nvmlReturn_t nvmlGetVgpuVersion (nvmlVgpuVersion_t
*supported, nvmlVgpuVersion_t *current)
Parameters
supported
Pointer to the structure in which the preset range of vGPU versions supported by the
NVIDIA vGPU Manager is written
current
Pointer to the structure in which the range of supported vGPU versions set by an
administrator is written
Returns
‣ NVML_SUCCESS The vGPU version range structures were successfully obtained.
‣ NVML_ERROR_NOT_SUPPORTED The API is not supported.
‣ NVML_ERROR_INVALID_ARGUMENT The supported parameter or the current
parameter is NULL.
‣ NVML_ERROR_UNKNOWN An error occurred while the data was being fetched.
Description
Query the ranges of supported vGPU versions.
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 nvmlSetVgpuVersion, both ranges are the same.
The caller passes pointers to the following nvmlVgpuVersion_t structures, into which
the NVIDIA vGPU Manager writes the ranges: 1. supported structure that represents
the preset range of vGPU versions supported by the NVIDIA vGPU Manager. 2. current
structure that represents the range of supported vGPU versions set by an administrator.
By default, this range is the same as the preset range.
nvmlReturn_t nvmlSetVgpuVersion (nvmlVgpuVersion_t
*vgpuVersion)
Parameters
vgpuVersion
Pointer to a caller-supplied range of supported vGPU versions.
333
Modules
Returns
‣ NVML_SUCCESS The preset range of supported vGPU versions was successfully
overridden.
‣ NVML_ERROR_NOT_SUPPORTED The API is not supported.
‣ NVML_ERROR_IN_USE The range was not overridden because a VM is running on
the host.
‣ NVML_ERROR_INVALID_ARGUMENT The vgpuVersion parameter specifies
a range that is outside the range supported by the NVIDIA vGPU Manager or if
vgpuVersion is NULL.
Description
Override the preset range of vGPU versions supported by the NVIDIA vGPU Manager
with a range set by an administrator.
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 nvmlGetVgpuVersion for details of how to query the preset range of
versions supported.
This function takes a pointer to vGPU version range structure nvmlVgpuVersion_t
as input to override the preset vGPU version range that the NVIDIA vGPU Manager
supports.
After host system reboot or driver reload, the range of supported versions reverts to the
range that is preset for the NVIDIA vGPU Manager.
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.
4.26. vGPU Utilization and Accounting
This chapter describes operations that are associated with vGPU Utilization and
Accounting.
334
Modules
nvmlReturn_t nvmlDeviceGetVgpuUtilization
(nvmlDevice_t device, unsigned long long
lastSeenTimeStamp, nvmlValueType_t *sampleValType,
unsigned int *vgpuInstanceSamplesCount,
nvmlVgpuInstanceUtilizationSample_t
*utilizationSamples)
Parameters
device
The identifier for the target device
lastSeenTimeStamp
Return only samples with timestamp greater than lastSeenTimeStamp.
sampleValType
Pointer to caller-supplied buffer to hold the type of returned sample values
vgpuInstanceSamplesCount
Pointer to caller-supplied array size, and returns number of vGPU instances
utilizationSamples
Pointer to caller-supplied buffer in which vGPU utilization samples are returned
Returns
‣ NVML_SUCCESS if utilization samples are successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid,
vgpuInstanceSamplesCount or sampleValType is NULL, or a sample count of 0 is
passed with a non-NULL utilizationSamples
‣ NVML_ERROR_INSUFFICIENT_SIZE if supplied vgpuInstanceSamplesCount is
too small to return samples for all vGPU instances currently executing on the device
‣ NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_FOUND if sample entries are not found
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves current utilization for vGPUs on a physical GPU (device).
For Kepler or newer fully supported devices.
335
Modules
Reads recent utilization of GPU SM (3D/Compute), framebuffer, video encoder, and
video decoder for vGPU instances running on a device. Utilization values are returned
as an array of utilization sample structures in the caller-supplied buffer pointed at by
utilizationSamples. One utilization sample structure is returned per vGPU instance, and
includes the CPU timestamp at which the samples were recorded. Individual utilization
values are returned as "unsigned int" values in nvmlValue_t unions. The function sets
the caller-supplied sampleValType to NVML_VALUE_TYPE_UNSIGNED_INT to
indicate the returned value type.
To read utilization values, first determine the size of buffer required to hold the samples
by invoking the function with utilizationSamples set to NULL. The function will
return NVML_ERROR_INSUFFICIENT_SIZE, with the current vGPU instance count
in vgpuInstanceSamplesCount, or NVML_SUCCESS if the current vGPU instance
count is zero. The caller should allocate a buffer of size vgpuInstanceSamplesCount
* sizeof(nvmlVgpuInstanceUtilizationSample_t). Invoke the function again with the
allocated buffer passed in utilizationSamples, and vgpuInstanceSamplesCount set to the
number of entries the buffer is sized for.
On successful return, the function updates vgpuInstanceSampleCount with the number
of vGPU utilization sample structures that were actually written. This may differ from a
previously read value as vGPU instances are created or destroyed.
lastSeenTimeStamp represents the CPU timestamp in microseconds at which utilization
samples were last read. Set it to 0 to read utilization based on all the samples maintained
by the driver's internal sample buffer. Set lastSeenTimeStamp to a timeStamp retrieved
from a previous query to read utilization since the previous query.
nvmlReturn_t
nvmlDeviceGetVgpuInstancesUtilizationInfo
(nvmlDevice_t device,
nvmlVgpuInstancesUtilizationInfo_t *vgpuUtilInfo)
Parameters
device
The identifier for the target device
vgpuUtilInfo
Pointer to the caller-provided structure of nvmlVgpuInstancesUtilizationInfo_t
Returns
‣ NVML_SUCCESS If utilization samples are successfully retrieved
‣ NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
336
|
||
|
|
|