Provided by: nvidia-cuda-dev_10.1.243-3_amd64 
NAME
Device Queries -
Functions
nvmlReturn_t DECLDIR nvmlDeviceGetCount (unsigned int *deviceCount)
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByIndex (unsigned int index, nvmlDevice_t *device)
nvmlReturn_t DECLDIR nvmlDeviceGetHandleBySerial (const char *serial, nvmlDevice_t *device)
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByUUID (const char *uuid, nvmlDevice_t *device)
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByPciBusId (const char *pciBusId, nvmlDevice_t *device)
nvmlReturn_t DECLDIR nvmlDeviceGetName (nvmlDevice_t device, char *name, unsigned int length)
nvmlReturn_t DECLDIR nvmlDeviceGetBrand (nvmlDevice_t device, nvmlBrandType_t *type)
nvmlReturn_t DECLDIR nvmlDeviceGetIndex (nvmlDevice_t device, unsigned int *index)
nvmlReturn_t DECLDIR nvmlDeviceGetSerial (nvmlDevice_t device, char *serial, unsigned int length)
nvmlReturn_t DECLDIR nvmlDeviceGetCpuAffinity (nvmlDevice_t device, unsigned int cpuSetSize, unsigned
long *cpuSet)
nvmlReturn_t DECLDIR nvmlDeviceSetCpuAffinity (nvmlDevice_t device)
nvmlReturn_t DECLDIR nvmlDeviceClearCpuAffinity (nvmlDevice_t device)
nvmlReturn_t DECLDIR nvmlDeviceGetTopologyCommonAncestor (nvmlDevice_t device1, nvmlDevice_t device2,
nvmlGpuTopologyLevel_t *pathInfo)
nvmlReturn_t DECLDIR nvmlDeviceGetTopologyNearestGpus (nvmlDevice_t device, nvmlGpuTopologyLevel_t level,
unsigned int *count, nvmlDevice_t *deviceArray)
nvmlReturn_t DECLDIR nvmlSystemGetTopologyGpuSet (unsigned int cpuNumber, unsigned int *count,
nvmlDevice_t *deviceArray)
nvmlReturn_t DECLDIR nvmlDeviceGetP2PStatus (nvmlDevice_t device1, nvmlDevice_t device2,
nvmlGpuP2PCapsIndex_t p2pIndex, nvmlGpuP2PStatus_t *p2pStatus)
nvmlReturn_t DECLDIR nvmlDeviceGetUUID (nvmlDevice_t device, char *uuid, unsigned int length)
nvmlReturn_t DECLDIR nvmlDeviceGetMinorNumber (nvmlDevice_t device, unsigned int *minorNumber)
nvmlReturn_t DECLDIR nvmlDeviceGetBoardPartNumber (nvmlDevice_t device, char *partNumber, unsigned int
length)
nvmlReturn_t DECLDIR nvmlDeviceGetInforomVersion (nvmlDevice_t device, nvmlInforomObject_t object, char
*version, unsigned int length)
nvmlReturn_t DECLDIR nvmlDeviceGetInforomImageVersion (nvmlDevice_t device, char *version, unsigned int
length)
nvmlReturn_t DECLDIR nvmlDeviceGetInforomConfigurationChecksum (nvmlDevice_t device, unsigned int
*checksum)
nvmlReturn_t DECLDIR nvmlDeviceValidateInforom (nvmlDevice_t device)
nvmlReturn_t DECLDIR nvmlDeviceGetDisplayMode (nvmlDevice_t device, nvmlEnableState_t *display)
nvmlReturn_t DECLDIR nvmlDeviceGetDisplayActive (nvmlDevice_t device, nvmlEnableState_t *isActive)
nvmlReturn_t DECLDIR nvmlDeviceGetPersistenceMode (nvmlDevice_t device, nvmlEnableState_t *mode)
nvmlReturn_t DECLDIR nvmlDeviceGetPciInfo (nvmlDevice_t device, nvmlPciInfo_t *pci)
nvmlReturn_t DECLDIR nvmlDeviceGetMaxPcieLinkGeneration (nvmlDevice_t device, unsigned int *maxLinkGen)
nvmlReturn_t DECLDIR nvmlDeviceGetMaxPcieLinkWidth (nvmlDevice_t device, unsigned int *maxLinkWidth)
nvmlReturn_t DECLDIR nvmlDeviceGetCurrPcieLinkGeneration (nvmlDevice_t device, unsigned int *currLinkGen)
nvmlReturn_t DECLDIR nvmlDeviceGetCurrPcieLinkWidth (nvmlDevice_t device, unsigned int *currLinkWidth)
nvmlReturn_t DECLDIR nvmlDeviceGetPcieThroughput (nvmlDevice_t device, nvmlPcieUtilCounter_t counter,
unsigned int *value)
nvmlReturn_t DECLDIR nvmlDeviceGetPcieReplayCounter (nvmlDevice_t device, unsigned int *value)
nvmlReturn_t DECLDIR nvmlDeviceGetClockInfo (nvmlDevice_t device, nvmlClockType_t type, unsigned int
*clock)
nvmlReturn_t DECLDIR nvmlDeviceGetMaxClockInfo (nvmlDevice_t device, nvmlClockType_t type, unsigned int
*clock)
nvmlReturn_t DECLDIR nvmlDeviceGetApplicationsClock (nvmlDevice_t device, nvmlClockType_t clockType,
unsigned int *clockMHz)
nvmlReturn_t DECLDIR nvmlDeviceGetDefaultApplicationsClock (nvmlDevice_t device, nvmlClockType_t
clockType, unsigned int *clockMHz)
nvmlReturn_t DECLDIR nvmlDeviceResetApplicationsClocks (nvmlDevice_t device)
nvmlReturn_t DECLDIR nvmlDeviceGetClock (nvmlDevice_t device, nvmlClockType_t clockType, nvmlClockId_t
clockId, unsigned int *clockMHz)
nvmlReturn_t DECLDIR nvmlDeviceGetMaxCustomerBoostClock (nvmlDevice_t device, nvmlClockType_t clockType,
unsigned int *clockMHz)
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedMemoryClocks (nvmlDevice_t device, unsigned int *count,
unsigned int *clocksMHz)
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedGraphicsClocks (nvmlDevice_t device, unsigned int
memoryClockMHz, unsigned int *count, unsigned int *clocksMHz)
nvmlReturn_t DECLDIR nvmlDeviceGetAutoBoostedClocksEnabled (nvmlDevice_t device, nvmlEnableState_t
*isEnabled, nvmlEnableState_t *defaultIsEnabled)
nvmlReturn_t DECLDIR nvmlDeviceSetAutoBoostedClocksEnabled (nvmlDevice_t device, nvmlEnableState_t
enabled)
nvmlReturn_t DECLDIR nvmlDeviceSetDefaultAutoBoostedClocksEnabled (nvmlDevice_t device, nvmlEnableState_t
enabled, unsigned int flags)
nvmlReturn_t DECLDIR nvmlDeviceGetFanSpeed (nvmlDevice_t device, unsigned int *speed)
nvmlReturn_t DECLDIR nvmlDeviceGetFanSpeed_v2 (nvmlDevice_t device, unsigned int fan, unsigned int
*speed)
nvmlReturn_t DECLDIR nvmlDeviceGetTemperature (nvmlDevice_t device, nvmlTemperatureSensors_t sensorType,
unsigned int *temp)
nvmlReturn_t DECLDIR nvmlDeviceGetTemperatureThreshold (nvmlDevice_t device, nvmlTemperatureThresholds_t
thresholdType, unsigned int *temp)
nvmlReturn_t DECLDIR nvmlDeviceGetPerformanceState (nvmlDevice_t device, nvmlPstates_t *pState)
nvmlReturn_t DECLDIR nvmlDeviceGetCurrentClocksThrottleReasons (nvmlDevice_t device, unsigned long long
*clocksThrottleReasons)
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedClocksThrottleReasons (nvmlDevice_t device, unsigned long long
*supportedClocksThrottleReasons)
nvmlReturn_t DECLDIR nvmlDeviceGetPowerState (nvmlDevice_t device, nvmlPstates_t *pState)
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementMode (nvmlDevice_t device, nvmlEnableState_t *mode)
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementLimit (nvmlDevice_t device, unsigned int *limit)
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementLimitConstraints (nvmlDevice_t device, unsigned int
*minLimit, unsigned int *maxLimit)
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementDefaultLimit (nvmlDevice_t device, unsigned int
*defaultLimit)
nvmlReturn_t DECLDIR nvmlDeviceGetPowerUsage (nvmlDevice_t device, unsigned int *power)
nvmlReturn_t DECLDIR nvmlDeviceGetTotalEnergyConsumption (nvmlDevice_t device, unsigned long long
*energy)
nvmlReturn_t DECLDIR nvmlDeviceGetEnforcedPowerLimit (nvmlDevice_t device, unsigned int *limit)
nvmlReturn_t DECLDIR nvmlDeviceGetGpuOperationMode (nvmlDevice_t device, nvmlGpuOperationMode_t *current,
nvmlGpuOperationMode_t *pending)
nvmlReturn_t DECLDIR nvmlDeviceGetMemoryInfo (nvmlDevice_t device, nvmlMemory_t *memory)
nvmlReturn_t DECLDIR nvmlDeviceGetComputeMode (nvmlDevice_t device, nvmlComputeMode_t *mode)
nvmlReturn_t DECLDIR nvmlDeviceGetCudaComputeCapability (nvmlDevice_t device, int *major, int *minor)
nvmlReturn_t DECLDIR nvmlDeviceGetEccMode (nvmlDevice_t device, nvmlEnableState_t *current,
nvmlEnableState_t *pending)
nvmlReturn_t DECLDIR nvmlDeviceGetBoardId (nvmlDevice_t device, unsigned int *boardId)
nvmlReturn_t DECLDIR nvmlDeviceGetMultiGpuBoard (nvmlDevice_t device, unsigned int *multiGpuBool)
nvmlReturn_t DECLDIR nvmlDeviceGetTotalEccErrors (nvmlDevice_t device, nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType, unsigned long long *eccCounts)
nvmlReturn_t DECLDIR nvmlDeviceGetDetailedEccErrors (nvmlDevice_t device, nvmlMemoryErrorType_t
errorType, nvmlEccCounterType_t counterType, nvmlEccErrorCounts_t *eccCounts)
nvmlReturn_t DECLDIR nvmlDeviceGetMemoryErrorCounter (nvmlDevice_t device, nvmlMemoryErrorType_t
errorType, nvmlEccCounterType_t counterType, nvmlMemoryLocation_t locationType, unsigned long long
*count)
nvmlReturn_t DECLDIR nvmlDeviceGetUtilizationRates (nvmlDevice_t device, nvmlUtilization_t *utilization)
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderUtilization (nvmlDevice_t device, unsigned int *utilization,
unsigned int *samplingPeriodUs)
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderCapacity (nvmlDevice_t device, nvmlEncoderType_t
encoderQueryType, unsigned int *encoderCapacity)
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderStats (nvmlDevice_t device, unsigned int *sessionCount, unsigned
int *averageFps, unsigned int *averageLatency)
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderSessions (nvmlDevice_t device, unsigned int *sessionCount,
nvmlEncoderSessionInfo_t *sessionInfos)
nvmlReturn_t DECLDIR nvmlDeviceGetDecoderUtilization (nvmlDevice_t device, unsigned int *utilization,
unsigned int *samplingPeriodUs)
nvmlReturn_t DECLDIR nvmlDeviceGetFBCStats (nvmlDevice_t device, nvmlFBCStats_t *fbcStats)
nvmlReturn_t DECLDIR nvmlDeviceGetFBCSessions (nvmlDevice_t device, unsigned int *sessionCount,
nvmlFBCSessionInfo_t *sessionInfo)
nvmlReturn_t DECLDIR nvmlDeviceGetDriverModel (nvmlDevice_t device, nvmlDriverModel_t *current,
nvmlDriverModel_t *pending)
nvmlReturn_t DECLDIR nvmlDeviceGetVbiosVersion (nvmlDevice_t device, char *version, unsigned int length)
nvmlReturn_t DECLDIR nvmlDeviceGetBridgeChipInfo (nvmlDevice_t device, nvmlBridgeChipHierarchy_t
*bridgeHierarchy)
nvmlReturn_t DECLDIR nvmlDeviceGetComputeRunningProcesses (nvmlDevice_t device, unsigned int *infoCount,
nvmlProcessInfo_t *infos)
nvmlReturn_t DECLDIR nvmlDeviceGetGraphicsRunningProcesses (nvmlDevice_t device, unsigned int *infoCount,
nvmlProcessInfo_t *infos)
nvmlReturn_t DECLDIR nvmlDeviceOnSameBoard (nvmlDevice_t device1, nvmlDevice_t device2, int *onSameBoard)
nvmlReturn_t DECLDIR nvmlDeviceGetAPIRestriction (nvmlDevice_t device, nvmlRestrictedAPI_t apiType,
nvmlEnableState_t *isRestricted)
nvmlReturn_t DECLDIR nvmlDeviceGetSamples (nvmlDevice_t device, nvmlSamplingType_t type, unsigned long
long lastSeenTimeStamp, nvmlValueType_t *sampleValType, unsigned int *sampleCount, nvmlSample_t
*samples)
nvmlReturn_t DECLDIR nvmlDeviceGetBAR1MemoryInfo (nvmlDevice_t device, nvmlBAR1Memory_t *bar1Memory)
nvmlReturn_t DECLDIR nvmlDeviceGetViolationStatus (nvmlDevice_t device, nvmlPerfPolicyType_t
perfPolicyType, nvmlViolationTime_t *violTime)
nvmlReturn_t DECLDIR nvmlDeviceGetRetiredPages (nvmlDevice_t device, nvmlPageRetirementCause_t cause,
unsigned int *pageCount, unsigned long long *addresses)
nvmlReturn_t DECLDIR nvmlDeviceGetRetiredPages_v2 (nvmlDevice_t device, nvmlPageRetirementCause_t cause,
unsigned int *pageCount, unsigned long long *addresses, unsigned long long *timestamps)
nvmlReturn_t DECLDIR nvmlDeviceGetRetiredPagesPendingStatus (nvmlDevice_t device, nvmlEnableState_t
*isPending)
Detailed Description
This chapter describes that queries that NVML can perform against each device. In each case the device is
identified with an nvmlDevice_t handle. This handle is obtained by calling one of
nvmlDeviceGetHandleByIndex(), nvmlDeviceGetHandleBySerial(), nvmlDeviceGetHandleByPciBusId(). or
nvmlDeviceGetHandleByUUID().
Function Documentation
nvmlReturn_t DECLDIR nvmlDeviceClearCpuAffinity (nvmlDevice_t device)
Clear all affinity bindings for the calling thread. Note, this is a change as of version 8.0 as older
versions cleared the affinity for a calling process and all children.
For Kepler (TM) or newer fully supported devices. Supported on Linux only.
Parameters:
device The identifier of the target device
Returns:
• NVML_SUCCESS if the calling process has been successfully unbound
• NVML_ERROR_INVALID_ARGUMENT if device is invalid
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetAPIRestriction (nvmlDevice_t device, nvmlRestrictedAPI_t apiType,
nvmlEnableState_t * isRestricted)
Retrieves the root/admin permissions on the target API. See nvmlRestrictedAPI_t for the list of supported
APIs. If an API is restricted only root users can call that API. See nvmlDeviceSetAPIRestriction to
change current permissions.
For all fully supported products.
Parameters:
device The identifier of the target device
apiType Target API type for this operation
isRestricted Reference in which to return the current restriction NVML_FEATURE_ENABLED indicates that
the API is root-only NVML_FEATURE_DISABLED indicates that the API is accessible to all users
Returns:
• NVML_SUCCESS if isRestricted has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, apiType incorrect or isRestricted is NULL
• NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device or the device does not
support the feature that is being queried (E.G. Enabling/disabling Auto Boosted clocks 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_UNKNOWN on any unexpected error
See also:
nvmlRestrictedAPI_t
nvmlReturn_t DECLDIR nvmlDeviceGetApplicationsClock (nvmlDevice_t device, nvmlClockType_t clockType, unsigned
int * clockMHz)
Retrieves the current setting of a clock that applications will use unless an overspec situation occurs.
Can be changed using nvmlDeviceSetApplicationsClocks.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
clockType Identify which clock domain to query
clockMHz Reference in which to return the clock in MHz
Returns:
• NVML_SUCCESS if clockMHz has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clockMHz is NULL or clockType is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetAutoBoostedClocksEnabled (nvmlDevice_t device, nvmlEnableState_t *
isEnabled, nvmlEnableState_t * defaultIsEnabled)
Retrieve the current state of Auto Boosted clocks on a device and store it in isEnabled
For Kepler (TM) or newer fully supported devices.
Auto Boosted clocks are enabled by default on some hardware, allowing the GPU to run at higher clock
rates to maximize performance as thermal limits allow.
On Pascal and newer hardware, Auto Aoosted clocks are controlled through application clocks. Use
nvmlDeviceSetApplicationsClocks and nvmlDeviceResetApplicationsClocks to control Auto Boost behavior.
Parameters:
device The identifier of the target device
isEnabled Where to store the current state of Auto Boosted clocks of the target device
defaultIsEnabled Where to store the default Auto Boosted clocks behavior of the target device that
the device will revert to when no applications are using the GPU
Returns:
• NVML_SUCCESS If isEnabled has been been set with the Auto Boosted clocks state of device
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or isEnabled is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support Auto Boosted clocks
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetBAR1MemoryInfo (nvmlDevice_t device, nvmlBAR1Memory_t * bar1Memory)
Gets Total, Available and Used size of BAR1 memory.
BAR1 is used to map the FB (device memory) so that it can be directly accessed by the CPU or by 3rd party
devices (peer-to-peer on the PCIE bus).
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
bar1Memory Reference in which BAR1 memory information is returned.
Returns:
• NVML_SUCCESS if BAR1 memory is successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, bar1Memory is NULL
• NVML_ERROR_NOT_SUPPORTED if this query 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_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetBoardId (nvmlDevice_t device, unsigned int * boardId)
Retrieves the device boardId from 0-N. Devices with the same boardId indicate GPUs connected to the same
PLX. Use in conjunction with nvmlDeviceGetMultiGpuBoard() to decide if they are on the same board as
well. The boardId returned is a unique ID for the current configuration. Uniqueness and ordering across
reboots and system configurations is not guaranteed (i.e. if a Tesla K40c returns 0x100 and the two GPUs
on a Tesla K10 in the same system returns 0x200 it is not guaranteed they will always return those values
but they will always be different from each other).
For Fermi (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
boardId Reference in which to return the device's board ID
Returns:
• NVML_SUCCESS if boardId has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or boardId is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetBoardPartNumber (nvmlDevice_t device, char * partNumber, unsigned int
length)
Retrieves the the device board part number which is programmed into the board's InfoROM
For all products.
Parameters:
device Identifier of the target device
partNumber Reference to the buffer to return
length Length of the buffer reference
Returns:
• NVML_SUCCESS if partNumber has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_NOT_SUPPORTED if the needed VBIOS fields have not been filled
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or serial 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
nvmlReturn_t DECLDIR nvmlDeviceGetBrand (nvmlDevice_t device, nvmlBrandType_t * type)
Retrieves the brand of this device.
For all products.
The type is a member of nvmlBrandType_t defined above.
Parameters:
device The identifier of the target device
type Reference in which to return the product brand type
Returns:
• NVML_SUCCESS if name has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or type 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
nvmlReturn_t DECLDIR nvmlDeviceGetBridgeChipInfo (nvmlDevice_t device, nvmlBridgeChipHierarchy_t *
bridgeHierarchy)
Get Bridge Chip Information for all the bridge chips on the board.
For all fully supported products. Only applicable to multi-GPU products.
Parameters:
device The identifier of the target device
bridgeHierarchy Reference to the returned bridge chip Hierarchy
Returns:
• NVML_SUCCESS if bridge chip exists
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or bridgeInfo is NULL
• NVML_ERROR_NOT_SUPPORTED if bridge chip not supported on the device
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetClock (nvmlDevice_t device, nvmlClockType_t clockType, nvmlClockId_t
clockId, unsigned int * clockMHz)
Retrieves the clock speed for the clock specified by the clock type and clock ID.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
clockType Identify which clock domain to query
clockId Identify which clock in the domain to query
clockMHz Reference in which to return the clock in MHz
Returns:
• NVML_SUCCESS if clockMHz has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clockMHz is NULL or clockType is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetClockInfo (nvmlDevice_t device, nvmlClockType_t type, unsigned int * clock)
Retrieves the current clock speeds for the device.
For Fermi (TM) or newer fully supported devices.
See nvmlClockType_t for details on available clock information.
Parameters:
device The identifier of the target device
type Identify which clock domain to query
clock Reference in which to return the clock speed in MHz
Returns:
• NVML_SUCCESS if clock has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clock is NULL
• NVML_ERROR_NOT_SUPPORTED if the device cannot report the specified clock
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetComputeMode (nvmlDevice_t device, nvmlComputeMode_t * mode)
Retrieves the current compute mode for the device.
For all products.
See nvmlComputeMode_t for details on allowed compute modes.
Parameters:
device The identifier of the target device
mode Reference in which to return the current compute mode
Returns:
• NVML_SUCCESS if mode has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or mode is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceSetComputeMode()
nvmlReturn_t DECLDIR nvmlDeviceGetComputeRunningProcesses (nvmlDevice_t device, unsigned int * infoCount,
nvmlProcessInfo_t * infos)
Get information about processes with a compute context on a device
For Fermi (TM) or newer fully supported devices.
This function returns information only about compute running processes (e.g. CUDA application which have
active context). Any graphics applications (e.g. using OpenGL, DirectX) won't be listed by this function.
To query the current number of running compute processes, call this function with *infoCount = 0. The
return code will be NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if none are running. For this call
infos is allowed to be NULL.
The usedGpuMemory field returned is all of the memory used by the application.
Keep in mind that information returned by this call is dynamic and the number of elements might change in
time. Allocate more space for infos table in case new compute processes are spawned.
Parameters:
device The identifier of the target device
infoCount Reference in which to provide the infos array size, and to return the number of returned
elements
infos Reference in which to return the process information
Returns:
• NVML_SUCCESS if infoCount and infos have been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INSUFFICIENT_SIZE if infoCount indicates that the infos array is too small infoCount
will contain minimal amount of space necessary for the call to complete
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, either of infoCount or infos 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
See also:
nvmlSystemGetProcessName
nvmlReturn_t DECLDIR nvmlDeviceGetCount (unsigned int * deviceCount)
Retrieves the number of compute devices in the system. A compute device is a single GPU.
For all products.
Note: New nvmlDeviceGetCount_v2 (default in NVML 5.319) returns count of all devices in the system even
if nvmlDeviceGetHandleByIndex_v2 returns NVML_ERROR_NO_PERMISSION for such device. Update your code to
handle this error, or use NVML 4.304 or older nvml header file. For backward binary compatibility reasons
_v1 version of the API is still present in the shared library. Old _v1 version of nvmlDeviceGetCount
doesn't count devices that NVML has no permission to talk to.
Parameters:
deviceCount Reference in which to return the number of accessible devices
Returns:
• NVML_SUCCESS if deviceCount has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if deviceCount is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetCpuAffinity (nvmlDevice_t device, unsigned int cpuSetSize, unsigned long *
cpuSet)
Retrieves an array of unsigned ints (sized to cpuSetSize) of bitmasks with the ideal CPU affinity for the
device For example, if processors 0, 1, 32, and 33 are ideal for the device and cpuSetSize == 2,
result[0] = 0x3, result[1] = 0x3
For Kepler (TM) or newer fully supported devices. Supported on Linux only.
Parameters:
device The identifier of the target device
cpuSetSize The size of the cpuSet array that is safe to access
cpuSet Array reference in which to return a bitmask of CPUs, 64 CPUs per unsigned long on 64-bit
machines, 32 on 32-bit machines
Returns:
• NVML_SUCCESS if cpuAffinity has been filled
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, cpuSetSize == 0, or cpuSet is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetCudaComputeCapability (nvmlDevice_t device, int * major, int * minor)
Retrieves the CUDA compute capability of the device.
For all products.
Returns the major and minor compute capability version numbers of the device. The major and minor
versions are equivalent to the CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MINOR and
CU_DEVICE_ATTRIBUTE_COMPUTE_CAPABILITY_MAJOR attributes that would be returned by CUDA's
cuDeviceGetAttribute().
Parameters:
device The identifier of the target device
major Reference in which to return the major CUDA compute capability
minor Reference in which to return the minor CUDA compute capability
Returns:
• NVML_SUCCESS if major and minor have been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or major or minor are 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
nvmlReturn_t DECLDIR nvmlDeviceGetCurrentClocksThrottleReasons (nvmlDevice_t device, unsigned long long *
clocksThrottleReasons)
Retrieves current clocks throttling reasons.
For all fully supported products.
Note:
More than one bit can be enabled at the same time. Multiple reasons can be affecting clocks at once.
Parameters:
device The identifier of the target device
clocksThrottleReasons Reference in which to return bitmask of active clocks throttle reasons
Returns:
• NVML_SUCCESS if clocksThrottleReasons has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clocksThrottleReasons is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
NvmlClocksThrottleReasons
nvmlDeviceGetSupportedClocksThrottleReasons
nvmlReturn_t DECLDIR nvmlDeviceGetCurrPcieLinkGeneration (nvmlDevice_t device, unsigned int * currLinkGen)
Retrieves the current PCIe link generation
For Fermi (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
currLinkGen Reference in which to return the current PCIe link generation
Returns:
• NVML_SUCCESS if currLinkGen has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or currLinkGen is null
• NVML_ERROR_NOT_SUPPORTED if PCIe link information is not available
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetCurrPcieLinkWidth (nvmlDevice_t device, unsigned int * currLinkWidth)
Retrieves the current PCIe link width
For Fermi (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
currLinkWidth Reference in which to return the current PCIe link generation
Returns:
• NVML_SUCCESS if currLinkWidth has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or currLinkWidth is null
• NVML_ERROR_NOT_SUPPORTED if PCIe link information is not available
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetDecoderUtilization (nvmlDevice_t device, unsigned int * utilization,
unsigned int * samplingPeriodUs)
Retrieves the current utilization and sampling size in microseconds for the Decoder
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
utilization Reference to an unsigned int for decoder utilization info
samplingPeriodUs Reference to an unsigned int for the sampling period in US
Returns:
• NVML_SUCCESS if utilization has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or samplingPeriodUs is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetDefaultApplicationsClock (nvmlDevice_t device, nvmlClockType_t clockType,
unsigned int * clockMHz)
Retrieves the default applications clock that GPU boots with or defaults to after
nvmlDeviceResetApplicationsClocks call.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
clockType Identify which clock domain to query
clockMHz Reference in which to return the default clock in MHz
Returns:
• NVML_SUCCESS if clockMHz has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clockMHz is NULL or clockType is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceGetApplicationsClock
nvmlReturn_t DECLDIR nvmlDeviceGetDetailedEccErrors (nvmlDevice_t device, nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType, nvmlEccErrorCounts_t * eccCounts)
Retrieves the detailed ECC error counts for the device.
Deprecated
This API supports only a fixed set of ECC error locations On different GPU architectures different
locations are supported See nvmlDeviceGetMemoryErrorCounter
For Fermi (TM) or newer fully supported devices. Only applicable to devices with ECC. Requires
NVML_INFOROM_ECC version 2.0 or higher to report aggregate location-based ECC counts. Requires
NVML_INFOROM_ECC version 1.0 or higher to report all other ECC counts. Requires ECC Mode to be enabled.
Detailed errors provide separate ECC counts for specific parts of the memory system.
Reports zero for unsupported ECC error counters when a subset of ECC error counters are supported.
See nvmlMemoryErrorType_t for a description of available bit types.
See nvmlEccCounterType_t for a description of available counter types.
See nvmlEccErrorCounts_t for a description of provided detailed ECC counts.
Parameters:
device The identifier of the target device
errorType Flag that specifies the type of the errors.
counterType Flag that specifies the counter-type of the errors.
eccCounts Reference in which to return the specified ECC errors
Returns:
• NVML_SUCCESS if eccCounts has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device, errorType or counterType is invalid, or eccCounts is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceClearEccErrorCounts()
nvmlReturn_t DECLDIR nvmlDeviceGetDisplayActive (nvmlDevice_t device, nvmlEnableState_t * isActive)
Retrieves the display active state for the device.
For all products.
This method indicates whether a display is initialized on the device. For example whether X Server is
attached to this device and has allocated memory for the screen.
Display can be active even when no monitor is physically attached.
See nvmlEnableState_t for details on allowed modes.
Parameters:
device The identifier of the target device
isActive Reference in which to return the display active state
Returns:
• NVML_SUCCESS if isActive has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or isActive is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetDisplayMode (nvmlDevice_t device, nvmlEnableState_t * display)
Retrieves the display mode for the device.
For all products.
This method indicates whether a physical display (e.g. monitor) is currently connected to any of the
device's connectors.
See nvmlEnableState_t for details on allowed modes.
Parameters:
device The identifier of the target device
display Reference in which to return the display mode
Returns:
• NVML_SUCCESS if display has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or display is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetDriverModel (nvmlDevice_t device, nvmlDriverModel_t * current,
nvmlDriverModel_t * pending)
Retrieves the current and pending driver model for the device.
For Fermi (TM) or newer fully supported devices. For windows only.
On Windows platforms the device driver can run in either WDDM or WDM (TCC) mode. If a display is attached
to the device it must run in WDDM mode. TCC mode is preferred if a display is not attached.
See nvmlDriverModel_t for details on available driver models.
Parameters:
device The identifier of the target device
current Reference in which to return the current driver model
pending Reference in which to return the pending driver model
Returns:
• NVML_SUCCESS if either current and/or pending have been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or both current and pending are NULL
• NVML_ERROR_NOT_SUPPORTED if the platform is not windows
• 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
See also:
nvmlDeviceSetDriverModel()
nvmlReturn_t DECLDIR nvmlDeviceGetEccMode (nvmlDevice_t device, nvmlEnableState_t * current,
nvmlEnableState_t * pending)
Retrieves the current and pending ECC modes for the device.
For Fermi (TM) or newer fully supported devices. Only applicable to devices with ECC. Requires
NVML_INFOROM_ECC version 1.0 or higher.
Changing ECC modes requires a reboot. The 'pending' ECC mode refers to the target mode following the next
reboot.
See nvmlEnableState_t for details on allowed modes.
Parameters:
device The identifier of the target device
current Reference in which to return the current ECC mode
pending Reference in which to return the pending ECC mode
Returns:
• NVML_SUCCESS if current and pending have been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or either current or pending is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceSetEccMode()
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderCapacity (nvmlDevice_t device, nvmlEncoderType_t encoderQueryType,
unsigned int * encoderCapacity)
Retrieves the current capacity of the device's encoder, as a percentage of maximum encoder capacity with
valid values in the range 0-100.
For Maxwell (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
encoderQueryType Type of encoder to query
encoderCapacity Reference to an unsigned int for the encoder capacity
Returns:
• NVML_SUCCESS if encoderCapacity is fetched
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if encoderCapacity is NULL, or device or encoderQueryType are invalid
• NVML_ERROR_NOT_SUPPORTED if device does not support the encoder specified in encodeQueryType
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderSessions (nvmlDevice_t device, unsigned int * sessionCount,
nvmlEncoderSessionInfo_t * sessionInfos)
Retrieves information about active encoder sessions on a target device.
An array of active encoder sessions is returned in the caller-supplied buffer pointed at by sessionInfos.
The array elememt 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 (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
sessionCount Reference to caller supplied array size, and returns the number of sessions.
sessionInfos Reference in which to return the session information
Returns:
• NVML_SUCCESS if sessionInfos 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.
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderStats (nvmlDevice_t device, unsigned int * sessionCount, unsigned
int * averageFps, unsigned int * averageLatency)
Retrieves the current encoder statistics for a given device.
For Maxwell (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
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 device or averageFps, or averageLatency 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
nvmlReturn_t DECLDIR nvmlDeviceGetEncoderUtilization (nvmlDevice_t device, unsigned int * utilization,
unsigned int * samplingPeriodUs)
Retrieves the current utilization and sampling size in microseconds for the Encoder
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
utilization Reference to an unsigned int for encoder utilization info
samplingPeriodUs Reference to an unsigned int for the sampling period in US
Returns:
• NVML_SUCCESS if utilization has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or samplingPeriodUs is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetEnforcedPowerLimit (nvmlDevice_t device, unsigned int * limit)
Get the effective power limit that the driver enforces after taking into account all limiters
Note: This can be different from the nvmlDeviceGetPowerManagementLimit if other limits are set elsewhere
This includes the out of band power limit interface
For Kepler (TM) or newer fully supported devices.
Parameters:
device The device to communicate with
limit Reference in which to return the power management limit in milliwatts
Returns:
• NVML_SUCCESS if limit has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or limit is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetFanSpeed (nvmlDevice_t device, unsigned int * speed)
Retrieves the intended operating speed of the device's fan.
Note: The reported speed is the intended fan speed. If the fan is physically blocked and unable to spin,
the output will not match the actual fan speed.
For all discrete products with dedicated fans.
The fan speed is expressed as a percent of the maximum, i.e. full speed is 100%.
Parameters:
device The identifier of the target device
speed Reference in which to return the fan speed percentage
Returns:
• NVML_SUCCESS if speed has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or speed is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not have a fan
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetFanSpeed_v2 (nvmlDevice_t device, unsigned int fan, unsigned int * speed)
Retrieves the intended operating speed of the device's specified fan.
Note: The reported speed is the intended fan speed. If the fan is physically blocked and unable to spin,
the output will not match the actual fan speed.
For all discrete products with dedicated fans.
The fan speed is expressed as a percentage of the maximum, i.e. full speed is 100%
Parameters:
device The identifier of the target device
fan The index of the target fan, zero indexed.
speed Reference in which to return the fan speed percentage
Returns:
• NVML_SUCCESS if speed has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, fan is not an acceptable index, or speed is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not have a fan or is newer than Maxwell
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetFBCSessions (nvmlDevice_t device, unsigned int * sessionCount,
nvmlFBCSessionInfo_t * sessionInfo)
Retrieves information about active frame buffer capture sessions on a target device.
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 (TM) or newer fully supported devices.
Note:
hResolution, vResolution, averageFPS and averageLatency data for a FBC session returned in
sessionInfo may be zero if there are no new frames captured since the session started.
Parameters:
device The identifier of the target device
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
• NVML_ERROR_INSUFFICIENT_SIZE if sessionCount is too small, array element count is returned in
sessionCount
• NVML_ERROR_INVALID_ARGUMENT if sessionCount 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
nvmlReturn_t DECLDIR nvmlDeviceGetFBCStats (nvmlDevice_t device, nvmlFBCStats_t * fbcStats)
Retrieves the active frame buffer capture sessions statistics for a given device.
For Maxwell (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
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 fbcStats 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
nvmlReturn_t DECLDIR nvmlDeviceGetGpuOperationMode (nvmlDevice_t device, nvmlGpuOperationMode_t * current,
nvmlGpuOperationMode_t * pending)
Retrieves the current GOM and pending GOM (the one that GPU will switch to after reboot).
For GK110 M-class and X-class Tesla (TM) products from the Kepler family. Modes NVML_GOM_LOW_DP and
NVML_GOM_ALL_ON are supported on fully supported GeForce products. Not supported on Quadro (R) and Tesla
(TM) C-class products.
Parameters:
device The identifier of the target device
current Reference in which to return the current GOM
pending Reference in which to return the pending GOM
Returns:
• NVML_SUCCESS if mode has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or current or pending is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlGpuOperationMode_t
nvmlDeviceSetGpuOperationMode
nvmlReturn_t DECLDIR nvmlDeviceGetGraphicsRunningProcesses (nvmlDevice_t device, unsigned int * infoCount,
nvmlProcessInfo_t * infos)
Get information about processes with a graphics context on a device
For Kepler (TM) or newer fully supported devices.
This function returns information only about graphics based processes (eg. applications using OpenGL,
DirectX)
To query the current number of running graphics processes, call this function with *infoCount = 0. The
return code will be NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if none are running. For this call
infos is allowed to be NULL.
The usedGpuMemory field returned is all of the memory used by the application.
Keep in mind that information returned by this call is dynamic and the number of elements might change in
time. Allocate more space for infos table in case new graphics processes are spawned.
Parameters:
device The identifier of the target device
infoCount Reference in which to provide the infos array size, and to return the number of returned
elements
infos Reference in which to return the process information
Returns:
• NVML_SUCCESS if infoCount and infos have been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INSUFFICIENT_SIZE if infoCount indicates that the infos array is too small infoCount
will contain minimal amount of space necessary for the call to complete
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, either of infoCount or infos 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
See also:
nvmlSystemGetProcessName
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByIndex (unsigned int index, nvmlDevice_t * device)
Acquire the handle for a particular device, based on its index.
For all products.
Valid indices are derived from the accessibleDevices count returned by nvmlDeviceGetCount(). For example,
if accessibleDevices is 2 the valid indices are 0 and 1, corresponding to GPU 0 and GPU 1.
The order in which NVML enumerates devices has no guarantees of consistency between reboots. For that
reason it is recommended that devices be looked up by their PCI ids or UUID. See
nvmlDeviceGetHandleByUUID() and nvmlDeviceGetHandleByPciBusId().
Note: The NVML index may not correlate with other APIs, such as the CUDA device index.
Starting from NVML 5, this API causes NVML to initialize the target GPU NVML may initialize additional
GPUs if:
• The target GPU is an SLI slave
Note: New nvmlDeviceGetCount_v2 (default in NVML 5.319) returns count of all devices in the system even
if nvmlDeviceGetHandleByIndex_v2 returns NVML_ERROR_NO_PERMISSION for such device. Update your code to
handle this error, or use NVML 4.304 or older nvml header file. For backward binary compatibility reasons
_v1 version of the API is still present in the shared library. Old _v1 version of nvmlDeviceGetCount
doesn't count devices that NVML has no permission to talk to.
This means that nvmlDeviceGetHandleByIndex_v2 and _v1 can return different devices for the same index. If
you don't touch macros that map old (_v1) versions to _v2 versions at the top of the file you don't need
to worry about that.
Parameters:
index The index of the target GPU, >= 0 and < accessibleDevices
device Reference in which to return the device handle
Returns:
• NVML_SUCCESS if device has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if index is invalid or device is NULL
• NVML_ERROR_INSUFFICIENT_POWER if any attached devices have improperly attached external power
cables
• NVML_ERROR_NO_PERMISSION if the user doesn't have permission to talk to this device
• NVML_ERROR_IRQ_ISSUE if NVIDIA kernel detected an interrupt issue with the attached GPUs
• 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
See also:
nvmlDeviceGetIndex
nvmlDeviceGetCount
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByPciBusId (const char * pciBusId, nvmlDevice_t * device)
Acquire the handle for a particular device, based on its PCI bus id.
For all products.
This value corresponds to the nvmlPciInfo_t::busId returned by nvmlDeviceGetPciInfo().
Starting from NVML 5, this API causes NVML to initialize the target GPU NVML may initialize additional
GPUs if:
• The target GPU is an SLI slave
Note:
NVML 4.304 and older version of nvmlDeviceGetHandleByPciBusId'_v1' returns NVML_ERROR_NOT_FOUND
instead of NVML_ERROR_NO_PERMISSION.
Parameters:
pciBusId The PCI bus id of the target GPU
device Reference in which to return the device handle
Returns:
• NVML_SUCCESS if device has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if pciBusId is invalid or device is NULL
• NVML_ERROR_NOT_FOUND if pciBusId does not match a valid device on the system
• NVML_ERROR_INSUFFICIENT_POWER if the attached device has improperly attached external power cables
• NVML_ERROR_NO_PERMISSION if the user doesn't have permission to talk to this device
• NVML_ERROR_IRQ_ISSUE if NVIDIA kernel detected an interrupt issue with the attached GPUs
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetHandleBySerial (const char * serial, nvmlDevice_t * device)
Acquire the handle for a particular device, based on its board serial number.
For Fermi (TM) or newer fully supported devices.
This number corresponds to the value printed directly on the board, and to the value returned by
nvmlDeviceGetSerial().
Deprecated
Since more than one GPU can exist on a single board this function is deprecated in favor of
nvmlDeviceGetHandleByUUID. For dual GPU boards this function will return NVML_ERROR_INVALID_ARGUMENT.
Starting from NVML 5, this API causes NVML to initialize the target GPU NVML may initialize additional
GPUs as it searches for the target GPU
Parameters:
serial The board serial number of the target GPU
device Reference in which to return the device handle
Returns:
• NVML_SUCCESS if device has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if serial is invalid, device is NULL or more than one device has the
same serial (dual GPU boards)
• NVML_ERROR_NOT_FOUND if serial does not match a valid device on the system
• NVML_ERROR_INSUFFICIENT_POWER if any attached devices have improperly attached external power
cables
• NVML_ERROR_IRQ_ISSUE if NVIDIA kernel detected an interrupt issue with the attached GPUs
• NVML_ERROR_GPU_IS_LOST if any GPU has fallen off the bus or is otherwise inaccessible
• NVML_ERROR_UNKNOWN on any unexpected error
See also:
nvmlDeviceGetSerial
nvmlDeviceGetHandleByUUID
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByUUID (const char * uuid, nvmlDevice_t * device)
Acquire the handle for a particular device, based on its globally unique immutable UUID associated with
each device.
For all products.
Parameters:
uuid The UUID of the target GPU
device Reference in which to return the device handle
Starting from NVML 5, this API causes NVML to initialize the target GPU NVML may initialize additional
GPUs as it searches for the target GPU
Returns:
• NVML_SUCCESS if device has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if uuid is invalid or device is null
• NVML_ERROR_NOT_FOUND if uuid does not match a valid device on the system
• NVML_ERROR_INSUFFICIENT_POWER if any attached devices have improperly attached external power
cables
• NVML_ERROR_IRQ_ISSUE if NVIDIA kernel detected an interrupt issue with the attached GPUs
• NVML_ERROR_GPU_IS_LOST if any GPU has fallen off the bus or is otherwise inaccessible
• NVML_ERROR_UNKNOWN on any unexpected error
See also:
nvmlDeviceGetUUID
nvmlReturn_t DECLDIR nvmlDeviceGetIndex (nvmlDevice_t device, unsigned int * index)
Retrieves the NVML index of this device.
For all products.
Valid indices are derived from the accessibleDevices count returned by nvmlDeviceGetCount(). For example,
if accessibleDevices is 2 the valid indices are 0 and 1, corresponding to GPU 0 and GPU 1.
The order in which NVML enumerates devices has no guarantees of consistency between reboots. For that
reason it is recommended that devices be looked up by their PCI ids or GPU UUID. See
nvmlDeviceGetHandleByPciBusId() and nvmlDeviceGetHandleByUUID().
Note: The NVML index may not correlate with other APIs, such as the CUDA device index.
Parameters:
device The identifier of the target device
index Reference in which to return the NVML index of the device
Returns:
• NVML_SUCCESS if index has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or index 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
See also:
nvmlDeviceGetHandleByIndex()
nvmlDeviceGetCount()
nvmlReturn_t DECLDIR nvmlDeviceGetInforomConfigurationChecksum (nvmlDevice_t device, unsigned int * checksum)
Retrieves the checksum of the configuration stored in the device's infoROM.
For all products with an inforom.
Can be used to make sure that two GPUs have the exact same configuration. Current checksum takes into
account configuration stored in PWR and ECC infoROM objects. Checksum can change between driver releases
or when user changes configuration (e.g. disable/enable ECC)
Parameters:
device The identifier of the target device
checksum Reference in which to return the infoROM configuration checksum
Returns:
• NVML_SUCCESS if checksum has been set
• NVML_ERROR_CORRUPTED_INFOROM if the device's checksum couldn't be retrieved due to infoROM
corruption
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if checksum is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetInforomImageVersion (nvmlDevice_t device, char * version, unsigned int
length)
Retrieves the global infoROM image version
For all products with an inforom.
Image version just like VBIOS version uniquely describes the exact version of the infoROM flashed on the
board in contrast to infoROM object version which is only an indicator of supported features. Version
string will not exceed 16 characters in length (including the NULL terminator). See
nvmlConstants::NVML_DEVICE_INFOROM_VERSION_BUFFER_SIZE.
Parameters:
device The identifier of the target device
version Reference in which to return the infoROM image version
length The maximum allowed length of the string returned in version
Returns:
• NVML_SUCCESS if version has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if version is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• NVML_ERROR_NOT_SUPPORTED if the device does not have an infoROM
• 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
See also:
nvmlDeviceGetInforomVersion
nvmlReturn_t DECLDIR nvmlDeviceGetInforomVersion (nvmlDevice_t device, nvmlInforomObject_t object, char *
version, unsigned int length)
Retrieves the version information for the device's infoROM object.
For all products with an inforom.
Fermi and higher parts have non-volatile on-board memory for persisting device info, such as aggregate
ECC counts. The version of the data structures in this memory may change from time to time. It will not
exceed 16 characters in length (including the NULL terminator). See
nvmlConstants::NVML_DEVICE_INFOROM_VERSION_BUFFER_SIZE.
See nvmlInforomObject_t for details on the available infoROM objects.
Parameters:
device The identifier of the target device
object The target infoROM object
version Reference in which to return the infoROM version
length The maximum allowed length of the string returned in version
Returns:
• NVML_SUCCESS if version has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if version is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• NVML_ERROR_NOT_SUPPORTED if the device does not have an infoROM
• 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
See also:
nvmlDeviceGetInforomImageVersion
nvmlReturn_t DECLDIR nvmlDeviceGetMaxClockInfo (nvmlDevice_t device, nvmlClockType_t type, unsigned int *
clock)
Retrieves the maximum clock speeds for the device.
For Fermi (TM) or newer fully supported devices.
See nvmlClockType_t for details on available clock information.
Note:
On GPUs from Fermi family current P0 clocks (reported by nvmlDeviceGetClockInfo) can differ from max
clocks by few MHz.
Parameters:
device The identifier of the target device
type Identify which clock domain to query
clock Reference in which to return the clock speed in MHz
Returns:
• NVML_SUCCESS if clock has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clock is NULL
• NVML_ERROR_NOT_SUPPORTED if the device cannot report the specified clock
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetMaxCustomerBoostClock (nvmlDevice_t device, nvmlClockType_t clockType,
unsigned int * clockMHz)
Retrieves the customer defined maximum boost clock speed specified by the given clock type.
For Pascal (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
clockType Identify which clock domain to query
clockMHz Reference in which to return the clock in MHz
Returns:
• NVML_SUCCESS if clockMHz has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clockMHz is NULL or clockType is invalid
• NVML_ERROR_NOT_SUPPORTED if the device or the clockType on this device does not support this
feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetMaxPcieLinkGeneration (nvmlDevice_t device, unsigned int * maxLinkGen)
Retrieves the maximum PCIe link generation possible with this device and system
I.E. for a generation 2 PCIe device attached to a generation 1 PCIe bus the max link generation this
function will report is generation 1.
For Fermi (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
maxLinkGen Reference in which to return the max PCIe link generation
Returns:
• NVML_SUCCESS if maxLinkGen has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or maxLinkGen is null
• NVML_ERROR_NOT_SUPPORTED if PCIe link information is not available
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetMaxPcieLinkWidth (nvmlDevice_t device, unsigned int * maxLinkWidth)
Retrieves the maximum PCIe link width possible with this device and system
I.E. for a device with a 16x PCIe bus width attached to a 8x PCIe system bus this function will report a
max link width of 8.
For Fermi (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
maxLinkWidth Reference in which to return the max PCIe link generation
Returns:
• NVML_SUCCESS if maxLinkWidth has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or maxLinkWidth is null
• NVML_ERROR_NOT_SUPPORTED if PCIe link information is not available
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetMemoryErrorCounter (nvmlDevice_t device, nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType, nvmlMemoryLocation_t locationType, unsigned long long * count)
Retrieves the requested memory error counter for the device.
For Fermi (TM) or newer fully supported devices. Requires NVML_INFOROM_ECC version 2.0 or higher to
report aggregate location-based memory error counts. Requires NVML_INFOROM_ECC version 1.0 or higher to
report all other memory error counts.
Only applicable to devices with ECC.
Requires ECC Mode to be enabled.
See nvmlMemoryErrorType_t for a description of available memory error types.
See nvmlEccCounterType_t for a description of available counter types.
See nvmlMemoryLocation_t for a description of available counter locations.
Parameters:
device The identifier of the target device
errorType Flag that specifies the type of error.
counterType Flag that specifies the counter-type of the errors.
locationType Specifies the location of the counter.
count Reference in which to return the ECC counter
Returns:
• NVML_SUCCESS if count has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device, bitTyp,e counterType or locationType is invalid, or count is
NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support ECC error reporting in the specified memory
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetMemoryInfo (nvmlDevice_t device, nvmlMemory_t * memory)
Retrieves the amount of used, free and total memory available on the device, in bytes.
For all products.
Enabling ECC reduces the amount of total available memory, due to the extra required parity bits. Under
WDDM most device memory is allocated and managed on startup by Windows.
Under Linux and Windows TCC, the reported amount of used memory is equal to the sum of memory allocated
by all active channels on the device.
See nvmlMemory_t for details on available memory info.
Parameters:
device The identifier of the target device
memory Reference in which to return the memory information
Returns:
• NVML_SUCCESS if memory has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or memory 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
nvmlReturn_t DECLDIR nvmlDeviceGetMinorNumber (nvmlDevice_t device, unsigned int * minorNumber)
Retrieves minor number for the device. The minor number for the device is such that the Nvidia device
node file for each GPU will have the form /dev/nvidia[minor number].
For all products. Supported only for Linux
Parameters:
device The identifier of the target device
minorNumber Reference in which to return the minor number for the device
Returns:
• NVML_SUCCESS if the minor number is successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or minorNumber is NULL
• NVML_ERROR_NOT_SUPPORTED if this query 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_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetMultiGpuBoard (nvmlDevice_t device, unsigned int * multiGpuBool)
Retrieves whether the device is on a Multi-GPU Board Devices that are on multi-GPU boards will set
multiGpuBool to a non-zero value.
For Fermi (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
multiGpuBool Reference in which to return a zero or non-zero value to indicate whether the device is
on a multi GPU board
Returns:
• NVML_SUCCESS if multiGpuBool has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or multiGpuBool is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetName (nvmlDevice_t device, char * name, unsigned int length)
Retrieves the name of this device.
For all products.
The name is an alphanumeric string that denotes a particular product, e.g. Tesla (TM) C2070. It will not
exceed 64 characters in length (including the NULL terminator). See
nvmlConstants::NVML_DEVICE_NAME_BUFFER_SIZE.
Parameters:
device The identifier of the target device
name Reference in which to return the product name
length The maximum allowed length of the string returned in name
Returns:
• NVML_SUCCESS if name has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or name is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetP2PStatus (nvmlDevice_t device1, nvmlDevice_t device2,
nvmlGpuP2PCapsIndex_t p2pIndex, nvmlGpuP2PStatus_t * p2pStatus)
Retrieve the status for a given p2p capability index between a given pair of GPU
Parameters:
device1 The first device
device2 The second device
p2pIndex p2p Capability Index being looked for between device1 and device2
p2pStatus Reference in which to return the status of the p2pIndex between device1 and device2
Returns:
• NVML_SUCCESS if p2pStatus has been populated
• NVML_ERROR_INVALID_ARGUMENT if device1 or device2 or p2pIndex is invalid or p2pStatus is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetPcieReplayCounter (nvmlDevice_t device, unsigned int * value)
Retrieve the PCIe replay counter.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
value Reference in which to return the counter's value
Returns:
• NVML_SUCCESS if value has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or value is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPcieThroughput (nvmlDevice_t device, nvmlPcieUtilCounter_t counter,
unsigned int * value)
Retrieve PCIe utilization information. This function is querying a byte counter over a 20ms interval and
thus is the PCIe throughput over that interval.
For Maxwell (TM) or newer fully supported devices.
This method is not supported in virtual machines running virtual GPU (vGPU).
Parameters:
device The identifier of the target device
counter The specific counter that should be queried nvmlPcieUtilCounter_t
value Reference in which to return throughput in KB/s
Returns:
• NVML_SUCCESS if value has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device or counter is invalid, or value is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPciInfo (nvmlDevice_t device, nvmlPciInfo_t * pci)
Retrieves the PCI attributes of this device.
For all products.
See nvmlPciInfo_t for details on the available PCI info.
Parameters:
device The identifier of the target device
pci Reference in which to return the PCI info
Returns:
• NVML_SUCCESS if pci has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or pci 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
nvmlReturn_t DECLDIR nvmlDeviceGetPerformanceState (nvmlDevice_t device, nvmlPstates_t * pState)
Retrieves the current performance state for the device.
For Fermi (TM) or newer fully supported devices.
See nvmlPstates_t for details on allowed performance states.
Parameters:
device The identifier of the target device
pState Reference in which to return the performance state reading
Returns:
• NVML_SUCCESS if pState has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or pState is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPersistenceMode (nvmlDevice_t device, nvmlEnableState_t * mode)
Retrieves the persistence mode associated with this device.
For all products. For Linux only.
When driver persistence mode is enabled the driver software state is not torn down when the last client
disconnects. By default this feature is disabled.
See nvmlEnableState_t for details on allowed modes.
Parameters:
device The identifier of the target device
mode Reference in which to return the current driver persistence mode
Returns:
• NVML_SUCCESS if mode has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or mode is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceSetPersistenceMode()
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementDefaultLimit (nvmlDevice_t device, unsigned int *
defaultLimit)
Retrieves default power management limit on this device, in milliwatts. Default power management limit is
a power management limit that the device boots with.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
defaultLimit Reference in which to return the default power management limit in milliwatts
Returns:
• NVML_SUCCESS if defaultLimit has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or defaultLimit is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementLimit (nvmlDevice_t device, unsigned int * limit)
Retrieves the power management limit associated with this device.
For Fermi (TM) or newer fully supported devices.
The power limit defines the upper boundary for the card's power draw. If the card's total power draw
reaches this limit the power management algorithm kicks in.
This reading is only available if power management mode is supported. See
nvmlDeviceGetPowerManagementMode.
Parameters:
device The identifier of the target device
limit Reference in which to return the power management limit in milliwatts
Returns:
• NVML_SUCCESS if limit has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or limit is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementLimitConstraints (nvmlDevice_t device, unsigned int *
minLimit, unsigned int * maxLimit)
Retrieves information about possible values of power management limits on this device.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
minLimit Reference in which to return the minimum power management limit in milliwatts
maxLimit Reference in which to return the maximum power management limit in milliwatts
Returns:
• NVML_SUCCESS if minLimit and maxLimit have been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or minLimit or maxLimit is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceSetPowerManagementLimit
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementMode (nvmlDevice_t device, nvmlEnableState_t * mode)
This API has been deprecated.
Retrieves the power management mode associated with this device.
For products from the Fermi family.
• Requires NVML_INFOROM_POWER version 3.0 or higher.
For from the Kepler or newer families.
• Does not require NVML_INFOROM_POWER object.
This flag indicates whether any power management algorithm is currently active on the device. An enabled
state does not necessarily mean the device is being actively throttled -- only that that the driver will
do so if the appropriate conditions are met.
See nvmlEnableState_t for details on allowed modes.
Parameters:
device The identifier of the target device
mode Reference in which to return the current power management mode
Returns:
• NVML_SUCCESS if mode has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or mode is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPowerState (nvmlDevice_t device, nvmlPstates_t * pState)
Deprecated: Use nvmlDeviceGetPerformanceState. This function exposes an incorrect generalization.
Retrieve the current performance state for the device.
For Fermi (TM) or newer fully supported devices.
See nvmlPstates_t for details on allowed performance states.
Parameters:
device The identifier of the target device
pState Reference in which to return the performance state reading
Returns:
• NVML_SUCCESS if pState has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or pState is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetPowerUsage (nvmlDevice_t device, unsigned int * power)
Retrieves power usage for this GPU in milliwatts and its associated circuitry (e.g. memory)
For Fermi (TM) or newer fully supported devices.
On Fermi and Kepler GPUs the reading is accurate to within +/- 5% of current power draw.
It is only available if power management mode is supported. See nvmlDeviceGetPowerManagementMode.
Parameters:
device The identifier of the target device
power Reference in which to return the power usage information
Returns:
• NVML_SUCCESS if power has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or power is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support power readings
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetRetiredPages (nvmlDevice_t device, nvmlPageRetirementCause_t cause,
unsigned int * pageCount, unsigned long long * addresses)
Returns the list of retired pages by source, including pages that are pending retirement The address
information provided from this API is the hardware address of the page that was retired. Note that this
does not match the virtual address used in CUDA, but will match the address information in XID 63
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
cause Filter page addresses by cause of retirement
pageCount Reference in which to provide the addresses buffer size, and to return the number of
retired pages that match cause Set to 0 to query the size without allocating an addresses buffer
addresses Buffer to write the page addresses into
Returns:
• NVML_SUCCESS if pageCount was populated and addresses was filled
• NVML_ERROR_INSUFFICIENT_SIZE if pageCount indicates the buffer is not large enough to store all the
matching page addresses. pageCount is set to the needed size.
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, pageCount is NULL, cause is invalid, or addresses
is NULL
• NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetRetiredPages_v2 (nvmlDevice_t device, nvmlPageRetirementCause_t cause,
unsigned int * pageCount, unsigned long long * addresses, unsigned long long * timestamps)
Returns the list of retired pages by source, including pages that are pending retirement The address
information provided from this API is the hardware address of the page that was retired. Note that this
does not match the virtual address used in CUDA, but will match the address information in XID 63
Note:
nvmlDeviceGetRetiredPages_v2 adds an additional timestamps parameter to return the time of each
page's retirement.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
cause Filter page addresses by cause of retirement
pageCount Reference in which to provide the addresses buffer size, and to return the number of
retired pages that match cause Set to 0 to query the size without allocating an addresses buffer
addresses Buffer to write the page addresses into
timestamps Buffer to write the timestamps of page retirement, additional for _v2
Returns:
• NVML_SUCCESS if pageCount was populated and addresses was filled
• NVML_ERROR_INSUFFICIENT_SIZE if pageCount indicates the buffer is not large enough to store all the
matching page addresses. pageCount is set to the needed size.
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, pageCount is NULL, cause is invalid, or addresses
is NULL
• NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetRetiredPagesPendingStatus (nvmlDevice_t device, nvmlEnableState_t *
isPending)
Check if any pages are pending retirement and need a reboot to fully retire.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
isPending Reference in which to return the pending status
Returns:
• NVML_SUCCESS if isPending was populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or isPending is NULL
• NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetSamples (nvmlDevice_t device, nvmlSamplingType_t type, unsigned long long
lastSeenTimeStamp, nvmlValueType_t * sampleValType, unsigned int * sampleCount, nvmlSample_t * samples)
Gets recent samples for the GPU.
For Kepler (TM) or newer fully supported devices.
Based on type, this method can be used to fetch the power, utilization or clock samples maintained in the
buffer by the driver.
Power, Utilization and Clock samples are returned as type 'unsigned int' for the union nvmlValue_t.
To get the size of samples that user needs to allocate, the method is invoked with samples set to NULL.
The returned samplesCount will provide the number of samples that can be queried. The user needs to
allocate the buffer with size as samplesCount * sizeof(nvmlSample_t).
lastSeenTimeStamp represents CPU timestamp in microseconds. Set it to 0 to fetch all the samples
maintained by the underlying buffer. Set lastSeenTimeStamp to one of the timeStamps retrieved from the
date of the previous query to get more recent samples.
This method fetches the number of entries which can be accommodated in the provided samples array, and
the reference samplesCount is updated to indicate how many samples were actually retrieved. The advantage
of using this method for samples in contrast to polling via existing methods is to get get higher
frequency data at lower polling cost.
Parameters:
device The identifier for the target device
type Type of sampling event
lastSeenTimeStamp Return only samples with timestamp greater than lastSeenTimeStamp.
sampleValType Output parameter to represent the type of sample value as described in nvmlSampleVal_t
sampleCount Reference to provide the number of elements which can be queried in samples array
samples Reference in which samples are returned
Returns:
• NVML_SUCCESS if samples are successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, samplesCount is NULL or reference to sampleCount
is 0 for non null samples
• NVML_ERROR_NOT_SUPPORTED if this query 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
nvmlReturn_t DECLDIR nvmlDeviceGetSerial (nvmlDevice_t device, char * serial, unsigned int length)
Retrieves the globally unique board serial number associated with this device's board.
For all products with an inforom.
The serial number is an alphanumeric string that will not exceed 30 characters (including the NULL
terminator). This number matches the serial number tag that is physically attached to the board. See
nvmlConstants::NVML_DEVICE_SERIAL_BUFFER_SIZE.
Parameters:
device The identifier of the target device
serial Reference in which to return the board/module serial number
length The maximum allowed length of the string returned in serial
Returns:
• NVML_SUCCESS if serial has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or serial is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedClocksThrottleReasons (nvmlDevice_t device, unsigned long long *
supportedClocksThrottleReasons)
Retrieves bitmask of supported clocks throttle reasons that can be returned by
nvmlDeviceGetCurrentClocksThrottleReasons
For all fully supported products.
This method is not supported in virtual machines running virtual GPU (vGPU).
Parameters:
device The identifier of the target device
supportedClocksThrottleReasons Reference in which to return bitmask of supported clocks throttle
reasons
Returns:
• NVML_SUCCESS if supportedClocksThrottleReasons has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or supportedClocksThrottleReasons 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
See also:
NvmlClocksThrottleReasons
nvmlDeviceGetCurrentClocksThrottleReasons
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedGraphicsClocks (nvmlDevice_t device, unsigned int memoryClockMHz,
unsigned int * count, unsigned int * clocksMHz)
Retrieves the list of possible graphics clocks that can be used as an argument for
nvmlDeviceSetApplicationsClocks.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
memoryClockMHz Memory clock for which to return possible graphics clocks
count Reference in which to provide the clocksMHz array size, and to return the number of elements
clocksMHz Reference in which to return the clocks in MHz
Returns:
• NVML_SUCCESS if count and clocksMHz have been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_NOT_FOUND if the specified memoryClockMHz is not a supported frequency
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or clock is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• NVML_ERROR_INSUFFICIENT_SIZE if count is too small
• 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
See also:
nvmlDeviceSetApplicationsClocks
nvmlDeviceGetSupportedMemoryClocks
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedMemoryClocks (nvmlDevice_t device, unsigned int * count, unsigned
int * clocksMHz)
Retrieves the list of possible memory clocks that can be used as an argument for
nvmlDeviceSetApplicationsClocks.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
count Reference in which to provide the clocksMHz array size, and to return the number of elements
clocksMHz Reference in which to return the clock in MHz
Returns:
• NVML_SUCCESS if count and clocksMHz have been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or count is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• NVML_ERROR_INSUFFICIENT_SIZE if count is too small (count is set to the number of required
elements)
• 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
See also:
nvmlDeviceSetApplicationsClocks
nvmlDeviceGetSupportedGraphicsClocks
nvmlReturn_t DECLDIR nvmlDeviceGetTemperature (nvmlDevice_t device, nvmlTemperatureSensors_t sensorType,
unsigned int * temp)
Retrieves the current temperature readings for the device, in degrees C.
For all products.
See nvmlTemperatureSensors_t for details on available temperature sensors.
Parameters:
device The identifier of the target device
sensorType Flag that indicates which sensor reading to retrieve
temp Reference in which to return the temperature reading
Returns:
• NVML_SUCCESS if temp has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, sensorType is invalid or temp is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not have the specified sensor
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetTemperatureThreshold (nvmlDevice_t device, nvmlTemperatureThresholds_t
thresholdType, unsigned int * temp)
Retrieves the temperature threshold for the GPU with the specified threshold type in degrees C.
For Kepler (TM) or newer fully supported devices.
See nvmlTemperatureThresholds_t for details on available temperature thresholds.
Parameters:
device The identifier of the target device
thresholdType The type of threshold value queried
temp Reference in which to return the temperature reading
Returns:
• NVML_SUCCESS if temp has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, thresholdType is invalid or temp is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not have a temperature sensor or is unsupported
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetTopologyCommonAncestor (nvmlDevice_t device1, nvmlDevice_t device2,
nvmlGpuTopologyLevel_t * pathInfo)
Retrieve the common ancestor for two devices For all products. Supported on Linux only.
Parameters:
device1 The identifier of the first device
device2 The identifier of the second device
pathInfo A nvmlGpuTopologyLevel_t that gives the path type
Returns:
• NVML_SUCCESS if pathInfo has been set
• NVML_ERROR_INVALID_ARGUMENT if device1, or device2 is invalid, or pathInfo is NULL
• NVML_ERROR_NOT_SUPPORTED if the device or OS does not support this feature
• NVML_ERROR_UNKNOWN an error has occurred in underlying topology discovery
nvmlReturn_t DECLDIR nvmlDeviceGetTopologyNearestGpus (nvmlDevice_t device, nvmlGpuTopologyLevel_t level,
unsigned int * count, nvmlDevice_t * deviceArray)
Retrieve the set of GPUs that are nearest to a given device at a specific interconnectivity level For all
products. Supported on Linux only.
Parameters:
device The identifier of the first device
level The nvmlGpuTopologyLevel_t level to search for other GPUs
count When zero, is set to the number of matching GPUs such that deviceArray can be malloc'd. When
non-zero, deviceArray will be filled with count number of device handles.
deviceArray An array of device handles for GPUs found at level
Returns:
• NVML_SUCCESS if deviceArray or count (if initially zero) has been set
• NVML_ERROR_INVALID_ARGUMENT if device, level, or count is invalid, or deviceArray is NULL with a
non-zero count
• NVML_ERROR_NOT_SUPPORTED if the device or OS does not support this feature
• NVML_ERROR_UNKNOWN an error has occurred in underlying topology discovery
nvmlReturn_t DECLDIR nvmlDeviceGetTotalEccErrors (nvmlDevice_t device, nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType, unsigned long long * eccCounts)
Retrieves the total ECC error counts for the device.
For Fermi (TM) or newer fully supported devices. Only applicable to devices with ECC. Requires
NVML_INFOROM_ECC version 1.0 or higher. Requires ECC Mode to be enabled.
The total error count is the sum of errors across each of the separate memory systems, i.e. the total set
of errors across the entire device.
See nvmlMemoryErrorType_t for a description of available error types.
See nvmlEccCounterType_t for a description of available counter types.
Parameters:
device The identifier of the target device
errorType Flag that specifies the type of the errors.
counterType Flag that specifies the counter-type of the errors.
eccCounts Reference in which to return the specified ECC errors
Returns:
• NVML_SUCCESS if eccCounts has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device, errorType or counterType is invalid, or eccCounts is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
See also:
nvmlDeviceClearEccErrorCounts()
nvmlReturn_t DECLDIR nvmlDeviceGetTotalEnergyConsumption (nvmlDevice_t device, unsigned long long * energy)
Retrieves total energy consumption for this GPU in millijoules (mJ) since the driver was last reloaded
For newer than Pascal (TM) fully supported devices.
Parameters:
device The identifier of the target device
energy Reference in which to return the energy consumption information
Returns:
• NVML_SUCCESS if energy has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or energy is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support energy readings
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetUtilizationRates (nvmlDevice_t device, nvmlUtilization_t * utilization)
Retrieves the current utilization rates for the device's major subsystems.
For Fermi (TM) or newer fully supported devices.
See nvmlUtilization_t for details on available utilization rates.
Note:
During driver initialization when ECC is enabled one can see high GPU and Memory Utilization
readings. This is caused by ECC Memory Scrubbing mechanism that is performed during driver
initialization.
Parameters:
device The identifier of the target device
utilization Reference in which to return the utilization information
Returns:
• NVML_SUCCESS if utilization has been populated
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid or utilization is NULL
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetUUID (nvmlDevice_t device, char * uuid, unsigned int length)
Retrieves the globally unique immutable UUID associated with this device, as a 5 part hexadecimal string,
that augments the immutable, board serial identifier.
For all products.
The UUID is a globally unique identifier. It is the only available identifier for pre-Fermi-architecture
products. It does NOT correspond to any identifier printed on the board. It will not exceed 80 characters
in length (including the NULL terminator). See nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.
Parameters:
device The identifier of the target device
uuid Reference in which to return the GPU UUID
length The maximum allowed length of the string returned in uuid
Returns:
• NVML_SUCCESS if uuid has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or uuid is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetVbiosVersion (nvmlDevice_t device, char * version, unsigned int length)
Get VBIOS version of the device.
For all products.
The VBIOS version may change from time to time. It will not exceed 32 characters in length (including the
NULL terminator). See nvmlConstants::NVML_DEVICE_VBIOS_VERSION_BUFFER_SIZE.
Parameters:
device The identifier of the target device
version Reference to which to return the VBIOS version
length The maximum allowed length of the string returned in version
Returns:
• NVML_SUCCESS if version has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or version is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• 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
nvmlReturn_t DECLDIR nvmlDeviceGetViolationStatus (nvmlDevice_t device, nvmlPerfPolicyType_t perfPolicyType,
nvmlViolationTime_t * violTime)
Gets the duration of time during which the device was throttled (lower than requested clocks) due to
power or thermal constraints.
The method is important to users who are tying to understand if their GPUs throttle at any point during
their applications. The difference in violation times at two different reference times gives the
indication of GPU throttling event.
Violation for thermal capping is not supported at this time.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
perfPolicyType Represents Performance policy which can trigger GPU throttling
violTime Reference to which violation time related information is returned
Returns:
• NVML_SUCCESS if violation time is successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, perfPolicyType is invalid, or violTime is NULL
• NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
• NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is otherwise inaccessible
nvmlReturn_t DECLDIR nvmlDeviceOnSameBoard (nvmlDevice_t device1, nvmlDevice_t device2, int * onSameBoard)
Check if the GPU devices are on the same physical board.
For all fully supported products.
Parameters:
device1 The first GPU device
device2 The second GPU device
onSameBoard Reference in which to return the status. Non-zero indicates that the GPUs are on the same
board.
Returns:
• NVML_SUCCESS if onSameBoard has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if dev1 or dev2 are invalid or onSameBoard is NULL
• NVML_ERROR_NOT_SUPPORTED if this check is not supported by the device
• NVML_ERROR_GPU_IS_LOST if the either GPU has fallen off the bus or is otherwise inaccessible
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceResetApplicationsClocks (nvmlDevice_t device)
Resets the application clock to the default value
This is the applications clock that will be used after system reboot or driver reload. Default value is
constant, but the current value an be changed using nvmlDeviceSetApplicationsClocks.
On Pascal and newer hardware, if clocks were previously locked with nvmlDeviceSetApplicationsClocks, this
call will unlock clocks. This returns clocks their default behavior ofautomatically boosting above base
clocks as thermal limits allow.
See also:
nvmlDeviceGetApplicationsClock
nvmlDeviceSetApplicationsClocks
For Fermi (TM) or newer non-GeForce fully supported devices and Maxwell or newer GeForce devices.
Parameters:
device The identifier of the target device
Returns:
• NVML_SUCCESS if new settings were successfully set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceSetAutoBoostedClocksEnabled (nvmlDevice_t device, nvmlEnableState_t enabled)
Try to set the current state of Auto Boosted clocks on a device.
For Kepler (TM) or newer fully supported devices.
Auto Boosted clocks are enabled by default on some hardware, allowing the GPU to run at higher clock
rates to maximize performance as thermal limits allow. Auto Boosted clocks should be disabled if fixed
clock rates are desired.
Non-root users may use this API by default but can be restricted by root from using this API by calling
nvmlDeviceSetAPIRestriction with apiType=NVML_RESTRICTED_API_SET_AUTO_BOOSTED_CLOCKS. Note: Persistence
Mode is required to modify current Auto Boost settings, therefore, it must be enabled.
On Pascal and newer hardware, Auto Boosted clocks are controlled through application clocks. Use
nvmlDeviceSetApplicationsClocks and nvmlDeviceResetApplicationsClocks to control Auto Boost behavior.
Parameters:
device The identifier of the target device
enabled What state to try to set Auto Boosted clocks of the target device to
Returns:
• NVML_SUCCESS If the Auto Boosted clocks were successfully set to the state specified by enabled
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support Auto Boosted clocks
• 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
nvmlReturn_t DECLDIR nvmlDeviceSetCpuAffinity (nvmlDevice_t device)
Sets the ideal affinity for the calling thread and device using the guidelines given in
nvmlDeviceGetCpuAffinity(). Note, this is a change as of version 8.0. Older versions set the affinity for
a calling process and all children. Currently supports up to 64 processors.
For Kepler (TM) or newer fully supported devices. Supported on Linux only.
Parameters:
device The identifier of the target device
Returns:
• NVML_SUCCESS if the calling process has been successfully bound
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlDeviceSetDefaultAutoBoostedClocksEnabled (nvmlDevice_t device, nvmlEnableState_t
enabled, unsigned int flags)
Try to set the default state of Auto Boosted clocks on a device. This is the default state that Auto
Boosted clocks will return to when no compute running processes (e.g. CUDA application which have an
active context) are running
For Kepler (TM) or newer non-GeForce fully supported devices and Maxwell or newer GeForce devices.
Requires root/admin permissions.
Auto Boosted clocks are enabled by default on some hardware, allowing the GPU to run at higher clock
rates to maximize performance as thermal limits allow. Auto Boosted clocks should be disabled if fixed
clock rates are desired.
On Pascal and newer hardware, Auto Boosted clocks are controlled through application clocks. Use
nvmlDeviceSetApplicationsClocks and nvmlDeviceResetApplicationsClocks to control Auto Boost behavior.
Parameters:
device The identifier of the target device
enabled What state to try to set default Auto Boosted clocks of the target device to
flags Flags that change the default behavior. Currently Unused.
Returns:
• NVML_SUCCESS If the Auto Boosted clock's default state was successfully set to the state specified
by enabled
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_NO_PERMISSION If the calling user does not have permission to change Auto Boosted
clock's default state.
• NVML_ERROR_INVALID_ARGUMENT if device is invalid
• NVML_ERROR_NOT_SUPPORTED if the device does not support Auto Boosted clocks
• 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
nvmlReturn_t DECLDIR nvmlDeviceValidateInforom (nvmlDevice_t device)
Reads the infoROM from the flash and verifies the checksums.
For all products with an inforom.
Parameters:
device The identifier of the target device
Returns:
• NVML_SUCCESS if infoROM is not corrupted
• NVML_ERROR_CORRUPTED_INFOROM if the device's infoROM is corrupted
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
• 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
nvmlReturn_t DECLDIR nvmlSystemGetTopologyGpuSet (unsigned int cpuNumber, unsigned int * count, nvmlDevice_t
* deviceArray)
Retrieve the set of GPUs that have a CPU affinity with the given CPU number For all products. Supported
on Linux only.
Parameters:
cpuNumber The CPU number
count When zero, is set to the number of matching GPUs such that deviceArray can be malloc'd. When
non-zero, deviceArray will be filled with count number of device handles.
deviceArray An array of device handles for GPUs found with affinity to cpuNumber
Returns:
• NVML_SUCCESS if deviceArray or count (if initially zero) has been set
• NVML_ERROR_INVALID_ARGUMENT if cpuNumber, or count is invalid, or deviceArray is NULL with a non-
zero count
• NVML_ERROR_NOT_SUPPORTED if the device or OS does not support this feature
• NVML_ERROR_UNKNOWN an error has occurred in underlying topology discovery
Author
Generated automatically by Doxygen for NVML from the source code.
Version 1.1 28 Jul 2019 Device Queries(3)