NVML API Reference Guide (PDF) - v535 (older) - Last updated January 31, 2024 - Send Feedback

4.15. Device Queries

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_v2(), nvmlDeviceGetHandleBySerial(), nvmlDeviceGetHandleByPciBusId_v2(). or nvmlDeviceGetHandleByUUID().

Modules

 

Functions

nvmlReturn_t nvmlDeviceGetAPIRestriction ( nvmlDevice_t device, nvmlRestrictedAPI_t apiType, nvmlEnableState_t* isRestricted )
nvmlReturn_t nvmlDeviceGetAdaptiveClockInfoStatus ( nvmlDevice_t device, unsigned int* adaptiveClockStatus )
nvmlReturn_t nvmlDeviceGetApplicationsClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
nvmlReturn_t nvmlDeviceGetArchitecture ( nvmlDevice_t device, nvmlDeviceArchitecture_t* arch )
nvmlReturn_t nvmlDeviceGetAttributes_v2 ( nvmlDevice_t device, nvmlDeviceAttributes_t* attributes )
nvmlReturn_t nvmlDeviceGetAutoBoostedClocksEnabled ( nvmlDevice_t device, nvmlEnableState_t* isEnabled, nvmlEnableState_t* defaultIsEnabled )
nvmlReturn_t nvmlDeviceGetBAR1MemoryInfo ( nvmlDevice_t device, nvmlBAR1Memory_t* bar1Memory )
nvmlReturn_t nvmlDeviceGetBoardId ( nvmlDevice_t device, unsigned int* boardId )
nvmlReturn_t nvmlDeviceGetBoardPartNumber ( nvmlDevice_t device, char* partNumber, unsigned int  length )
nvmlReturn_t nvmlDeviceGetBrand ( nvmlDevice_t device, nvmlBrandType_t* type )
nvmlReturn_t nvmlDeviceGetBridgeChipInfo ( nvmlDevice_t device, nvmlBridgeChipHierarchy_t* bridgeHierarchy )
nvmlReturn_t nvmlDeviceGetBusType ( nvmlDevice_t device, nvmlBusType_t* type )
nvmlReturn_t nvmlDeviceGetClock ( nvmlDevice_t device, nvmlClockType_t clockType, nvmlClockId_t clockId, unsigned int* clockMHz )
nvmlReturn_t nvmlDeviceGetClockInfo ( nvmlDevice_t device, nvmlClockType_t type, unsigned int* clock )
nvmlReturn_t nvmlDeviceGetComputeMode ( nvmlDevice_t device, nvmlComputeMode_t* mode )
nvmlReturn_t nvmlDeviceGetComputeRunningProcesses_v3 ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
nvmlReturn_t nvmlDeviceGetConfComputeGpuAttestationReport ( nvmlDevice_t device, nvmlConfComputeGpuAttestationReport_t* gpuAtstReport )
nvmlReturn_t nvmlDeviceGetConfComputeGpuCertificate ( nvmlDevice_t device, nvmlConfComputeGpuCertificate_t* gpuCert )
nvmlReturn_t nvmlDeviceGetConfComputeMemSizeInfo ( nvmlDevice_t device, nvmlConfComputeMemSizeInfo_t* memInfo )
nvmlReturn_t nvmlDeviceGetConfComputeProtectedMemoryUsage ( nvmlDevice_t device, nvmlMemory_t* memory )
nvmlReturn_t nvmlDeviceGetCount_v2 ( unsigned int* deviceCount )
nvmlReturn_t nvmlDeviceGetCudaComputeCapability ( nvmlDevice_t device, int* major, int* minor )
nvmlReturn_t nvmlDeviceGetCurrPcieLinkGeneration ( nvmlDevice_t device, unsigned int* currLinkGen )
nvmlReturn_t nvmlDeviceGetCurrPcieLinkWidth ( nvmlDevice_t device, unsigned int* currLinkWidth )
nvmlReturn_t nvmlDeviceGetCurrentClocksEventReasons ( nvmlDevice_t device, unsigned long long* clocksEventReasons )
nvmlReturn_t nvmlDeviceGetCurrentClocksThrottleReasons ( nvmlDevice_t device, unsigned long long* clocksThrottleReasons )
nvmlReturn_t nvmlDeviceGetDecoderUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
nvmlReturn_t nvmlDeviceGetDefaultApplicationsClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
nvmlReturn_t nvmlDeviceGetDefaultEccMode ( nvmlDevice_t device, nvmlEnableState_t* defaultMode )
nvmlReturn_t nvmlDeviceGetDetailedEccErrors ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, nvmlEccErrorCounts_t* eccCounts )
nvmlReturn_t nvmlDeviceGetDisplayActive ( nvmlDevice_t device, nvmlEnableState_t* isActive )
nvmlReturn_t nvmlDeviceGetDisplayMode ( nvmlDevice_t device, nvmlEnableState_t* display )
nvmlReturn_t nvmlDeviceGetDriverModel ( nvmlDevice_t device, nvmlDriverModel_t* current, nvmlDriverModel_t* pending )
nvmlReturn_t nvmlDeviceGetDynamicPstatesInfo ( nvmlDevice_t device, nvmlGpuDynamicPstatesInfo_t* pDynamicPstatesInfo )
nvmlReturn_t nvmlDeviceGetEccMode ( nvmlDevice_t device, nvmlEnableState_t* current, nvmlEnableState_t* pending )
nvmlReturn_t nvmlDeviceGetEncoderCapacity ( nvmlDevice_t device, nvmlEncoderType_t encoderQueryType, unsigned int* encoderCapacity )
nvmlReturn_t nvmlDeviceGetEncoderSessions ( nvmlDevice_t device, unsigned int* sessionCount, nvmlEncoderSessionInfo_t* sessionInfos )
nvmlReturn_t nvmlDeviceGetEncoderStats ( nvmlDevice_t device, unsigned int* sessionCount, unsigned int* averageFps, unsigned int* averageLatency )
nvmlReturn_t nvmlDeviceGetEncoderUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
nvmlReturn_t nvmlDeviceGetEnforcedPowerLimit ( nvmlDevice_t device, unsigned int* limit )
nvmlReturn_t nvmlDeviceGetFBCSessions ( nvmlDevice_t device, unsigned int* sessionCount, nvmlFBCSessionInfo_t* sessionInfo )
nvmlReturn_t nvmlDeviceGetFBCStats ( nvmlDevice_t device, nvmlFBCStats_t* fbcStats )
nvmlReturn_t nvmlDeviceGetFanControlPolicy_v2 ( nvmlDevice_t device, unsigned int  fan, nvmlFanControlPolicy_t* policy )
nvmlReturn_t nvmlDeviceGetFanSpeed ( nvmlDevice_t device, unsigned int* speed )
nvmlReturn_t nvmlDeviceGetFanSpeed_v2 ( nvmlDevice_t device, unsigned int  fan, unsigned int* speed )
nvmlReturn_t nvmlDeviceGetGpcClkMinMaxVfOffset ( nvmlDevice_t device, int* minOffset, int* maxOffset )
nvmlReturn_t nvmlDeviceGetGpcClkVfOffset ( nvmlDevice_t device, int* offset )
nvmlReturn_t nvmlDeviceGetGpuFabricInfo ( nvmlDevice_t device, nvmlGpuFabricInfo_t* gpuFabricInfo )
nvmlReturn_t nvmlDeviceGetGpuMaxPcieLinkGeneration ( nvmlDevice_t device, unsigned int* maxLinkGenDevice )
nvmlReturn_t nvmlDeviceGetGpuOperationMode ( nvmlDevice_t device, nvmlGpuOperationMode_t* current, nvmlGpuOperationMode_t* pending )
nvmlReturn_t nvmlDeviceGetGraphicsRunningProcesses_v3 ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
nvmlReturn_t nvmlDeviceGetHandleByIndex_v2 ( unsigned int  index, nvmlDevice_t* device )
nvmlReturn_t nvmlDeviceGetHandleByPciBusId_v2 ( const char* pciBusId, nvmlDevice_t* device )
nvmlReturn_t nvmlDeviceGetHandleBySerial ( const char* serial, nvmlDevice_t* device )
nvmlReturn_t nvmlDeviceGetHandleByUUID ( const char* uuid, nvmlDevice_t* device )
nvmlReturn_t nvmlDeviceGetIndex ( nvmlDevice_t device, unsigned int* index )
nvmlReturn_t nvmlDeviceGetInforomConfigurationChecksum ( nvmlDevice_t device, unsigned int* checksum )
nvmlReturn_t nvmlDeviceGetInforomImageVersion ( nvmlDevice_t device, char* version, unsigned int  length )
nvmlReturn_t nvmlDeviceGetInforomVersion ( nvmlDevice_t device, nvmlInforomObject_t object, char* version, unsigned int  length )
nvmlReturn_t nvmlDeviceGetIrqNum ( nvmlDevice_t device, unsigned int* irqNum )
nvmlReturn_t nvmlDeviceGetJpgUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
nvmlReturn_t nvmlDeviceGetMPSComputeRunningProcesses_v3 ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
nvmlReturn_t nvmlDeviceGetMaxClockInfo ( nvmlDevice_t device, nvmlClockType_t type, unsigned int* clock )
nvmlReturn_t nvmlDeviceGetMaxCustomerBoostClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
nvmlReturn_t nvmlDeviceGetMaxPcieLinkGeneration ( nvmlDevice_t device, unsigned int* maxLinkGen )
nvmlReturn_t nvmlDeviceGetMaxPcieLinkWidth ( nvmlDevice_t device, unsigned int* maxLinkWidth )
nvmlReturn_t nvmlDeviceGetMemClkMinMaxVfOffset ( nvmlDevice_t device, int* minOffset, int* maxOffset )
nvmlReturn_t nvmlDeviceGetMemClkVfOffset ( nvmlDevice_t device, int* offset )
nvmlReturn_t nvmlDeviceGetMemoryBusWidth ( nvmlDevice_t device, unsigned int* busWidth )
nvmlReturn_t nvmlDeviceGetMemoryErrorCounter ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, nvmlMemoryLocation_t locationType, unsigned long long* count )
nvmlReturn_t nvmlDeviceGetMemoryInfo ( nvmlDevice_t device, nvmlMemory_t* memory )
nvmlReturn_t nvmlDeviceGetMinMaxClockOfPState ( nvmlDevice_t device, nvmlClockType_t type, nvmlPstates_t pstate, unsigned int* minClockMHz, unsigned int* maxClockMHz )
nvmlReturn_t nvmlDeviceGetMinMaxFanSpeed ( nvmlDevice_t device, unsigned int* minSpeed, unsigned int* maxSpeed )
nvmlReturn_t nvmlDeviceGetMinorNumber ( nvmlDevice_t device, unsigned int* minorNumber )
nvmlReturn_t nvmlDeviceGetMultiGpuBoard ( nvmlDevice_t device, unsigned int* multiGpuBool )
nvmlReturn_t nvmlDeviceGetName ( nvmlDevice_t device, char* name, unsigned int  length )
nvmlReturn_t nvmlDeviceGetNumFans ( nvmlDevice_t device, unsigned int* numFans )
nvmlReturn_t nvmlDeviceGetNumGpuCores ( nvmlDevice_t device, unsigned int* numCores )
nvmlReturn_t nvmlDeviceGetOfaUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
nvmlReturn_t nvmlDeviceGetP2PStatus ( nvmlDevice_t device1, nvmlDevice_t device2, nvmlGpuP2PCapsIndex_t p2pIndex, nvmlGpuP2PStatus_t* p2pStatus )
nvmlReturn_t nvmlDeviceGetPciInfo_v3 ( nvmlDevice_t device, nvmlPciInfo_t* pci )
nvmlReturn_t nvmlDeviceGetPcieLinkMaxSpeed ( nvmlDevice_t device, unsigned int* maxSpeed )
nvmlReturn_t nvmlDeviceGetPcieReplayCounter ( nvmlDevice_t device, unsigned int* value )
nvmlReturn_t nvmlDeviceGetPcieSpeed ( nvmlDevice_t device, unsigned int* pcieSpeed )
nvmlReturn_t nvmlDeviceGetPcieThroughput ( nvmlDevice_t device, nvmlPcieUtilCounter_t counter, unsigned int* value )
nvmlReturn_t nvmlDeviceGetPerformanceState ( nvmlDevice_t device, nvmlPstates_t* pState )
nvmlReturn_t nvmlDeviceGetPersistenceMode ( nvmlDevice_t device, nvmlEnableState_t* mode )
nvmlReturn_t nvmlDeviceGetPowerManagementDefaultLimit ( nvmlDevice_t device, unsigned int* defaultLimit )
nvmlReturn_t nvmlDeviceGetPowerManagementLimit ( nvmlDevice_t device, unsigned int* limit )
nvmlReturn_t nvmlDeviceGetPowerManagementLimitConstraints ( nvmlDevice_t device, unsigned int* minLimit, unsigned int* maxLimit )
nvmlReturn_t nvmlDeviceGetPowerManagementMode ( nvmlDevice_t device, nvmlEnableState_t* mode )
nvmlReturn_t nvmlDeviceGetPowerSource ( nvmlDevice_t device, nvmlPowerSource_t* powerSource )
nvmlReturn_t nvmlDeviceGetPowerState ( nvmlDevice_t device, nvmlPstates_t* pState )
nvmlReturn_t nvmlDeviceGetPowerUsage ( nvmlDevice_t device, unsigned int* power )
nvmlReturn_t nvmlDeviceGetRemappedRows ( nvmlDevice_t device, unsigned int* corrRows, unsigned int* uncRows, unsigned int* isPending, unsigned int* failureOccurred )
nvmlReturn_t nvmlDeviceGetRetiredPages ( nvmlDevice_t device, nvmlPageRetirementCause_t cause, unsigned int* pageCount, unsigned long long* addresses )
nvmlReturn_t nvmlDeviceGetRetiredPagesPendingStatus ( nvmlDevice_t device, nvmlEnableState_t* isPending )
nvmlReturn_t nvmlDeviceGetRetiredPages_v2 ( nvmlDevice_t device, nvmlPageRetirementCause_t cause, unsigned int* pageCount, unsigned long long* addresses, unsigned long long* timestamps )
nvmlReturn_t nvmlDeviceGetRowRemapperHistogram ( nvmlDevice_t device, nvmlRowRemapperHistogramValues_t* values )
nvmlReturn_t nvmlDeviceGetRunningProcessDetailList ( nvmlDevice_t device, nvmlProcessDetailList_t* plist )
nvmlReturn_t nvmlDeviceGetSamples ( nvmlDevice_t device, nvmlSamplingType_t type, unsigned long long lastSeenTimeStamp, nvmlValueType_t* sampleValType, unsigned int* sampleCount, nvmlSample_t* samples )
nvmlReturn_t nvmlDeviceGetSerial ( nvmlDevice_t device, char* serial, unsigned int  length )
nvmlReturn_t nvmlDeviceGetSupportedClocksEventReasons ( nvmlDevice_t device, unsigned long long* supportedClocksEventReasons )
nvmlReturn_t nvmlDeviceGetSupportedClocksThrottleReasons ( nvmlDevice_t device, unsigned long long* supportedClocksThrottleReasons )
nvmlReturn_t nvmlDeviceGetSupportedGraphicsClocks ( nvmlDevice_t device, unsigned int  memoryClockMHz, unsigned int* count, unsigned int* clocksMHz )
nvmlReturn_t nvmlDeviceGetSupportedMemoryClocks ( nvmlDevice_t device, unsigned int* count, unsigned int* clocksMHz )
nvmlReturn_t nvmlDeviceGetSupportedPerformanceStates ( nvmlDevice_t device, nvmlPstates_t* pstates, unsigned int  size )
nvmlReturn_t nvmlDeviceGetTargetFanSpeed ( nvmlDevice_t device, unsigned int  fan, unsigned int* targetSpeed )
nvmlReturn_t nvmlDeviceGetTemperature ( nvmlDevice_t device, nvmlTemperatureSensors_t sensorType, unsigned int* temp )
nvmlReturn_t nvmlDeviceGetTemperatureThreshold ( nvmlDevice_t device, nvmlTemperatureThresholds_t thresholdType, unsigned int* temp )
nvmlReturn_t nvmlDeviceGetThermalSettings ( nvmlDevice_t device, unsigned int  sensorIndex, nvmlGpuThermalSettings_t* pThermalSettings )
nvmlReturn_t nvmlDeviceGetTopologyCommonAncestor ( nvmlDevice_t device1, nvmlDevice_t device2, nvmlGpuTopologyLevel_t* pathInfo )
nvmlReturn_t nvmlDeviceGetTopologyNearestGpus ( nvmlDevice_t device, nvmlGpuTopologyLevel_t level, unsigned int* count, nvmlDevice_t* deviceArray )
nvmlReturn_t nvmlDeviceGetTotalEccErrors ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, unsigned long long* eccCounts )
nvmlReturn_t nvmlDeviceGetTotalEnergyConsumption ( nvmlDevice_t device, unsigned long long* energy )
nvmlReturn_t nvmlDeviceGetUUID ( nvmlDevice_t device, char* uuid, unsigned int  length )
nvmlReturn_t nvmlDeviceGetUtilizationRates ( nvmlDevice_t device, nvmlUtilization_t* utilization )
nvmlReturn_t nvmlDeviceGetVbiosVersion ( nvmlDevice_t device, char* version, unsigned int  length )
nvmlReturn_t nvmlDeviceGetViolationStatus ( nvmlDevice_t device, nvmlPerfPolicyType_t perfPolicyType, nvmlViolationTime_t* violTime )
nvmlReturn_t nvmlDeviceOnSameBoard ( nvmlDevice_t device1, nvmlDevice_t device2, int* onSameBoard )
nvmlReturn_t nvmlDeviceResetApplicationsClocks ( nvmlDevice_t device )
nvmlReturn_t nvmlDeviceSetAutoBoostedClocksEnabled ( nvmlDevice_t device, nvmlEnableState_t enabled )
nvmlReturn_t nvmlDeviceSetDefaultAutoBoostedClocksEnabled ( nvmlDevice_t device, nvmlEnableState_t enabled, unsigned int  flags )
nvmlReturn_t nvmlDeviceSetDefaultFanSpeed_v2 ( nvmlDevice_t device, unsigned int  fan )
nvmlReturn_t nvmlDeviceSetFanControlPolicy ( nvmlDevice_t device, unsigned int  fan, nvmlFanControlPolicy_t policy )
nvmlReturn_t nvmlDeviceSetTemperatureThreshold ( nvmlDevice_t device, nvmlTemperatureThresholds_t thresholdType, int* temp )
nvmlReturn_t nvmlDeviceValidateInforom ( nvmlDevice_t device )
nvmlReturn_t nvmlSystemGetConfComputeCapabilities ( nvmlConfComputeSystemCaps_t* capabilities )
nvmlReturn_t nvmlSystemGetConfComputeGpusReadyState ( unsigned int* isAcceptingWork )
nvmlReturn_t nvmlSystemGetConfComputeState ( nvmlConfComputeSystemState_t* state )
nvmlReturn_t nvmlSystemGetTopologyGpuSet ( unsigned int  cpuNumber, unsigned int* count, nvmlDevice_t* deviceArray )
nvmlReturn_t nvmlVgpuInstanceGetMdevUUID ( nvmlVgpuInstance_t vgpuInstance, char* mdevUuid, unsigned int  size )

Functions

nvmlReturn_t nvmlDeviceGetAPIRestriction ( nvmlDevice_t device, nvmlRestrictedAPI_t apiType, nvmlEnableState_t* isRestricted )
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

Description

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.

See also:

nvmlRestrictedAPI_t

nvmlReturn_t nvmlDeviceGetAdaptiveClockInfoStatus ( nvmlDevice_t device, unsigned int* adaptiveClockStatus )
Parameters
device
The identifier of the target device
adaptiveClockStatus
The current adaptive clocking status, either NVML_ADAPTIVE_CLOCKING_INFO_STATUS_DISABLED or NVML_ADAPTIVE_CLOCKING_INFO_STATUS_ENABLED
Returns

Description

Gets the device's Adaptive Clock status

nvmlReturn_t nvmlDeviceGetApplicationsClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
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

Description

Retrieves the current setting of a clock that applications will use unless an overspec situation occurs. Can be changed using nvmlDeviceSetApplicationsClocks.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetArchitecture ( nvmlDevice_t device, nvmlDeviceArchitecture_t* arch )
Parameters
device
The identifier of the target device
arch
Reference where architecture is returned, if call successful. Set to NVML_DEVICE_ARCH_* upon success
Returns

Description

Get architecture for device

nvmlReturn_t nvmlDeviceGetAttributes_v2 ( nvmlDevice_t device, nvmlDeviceAttributes_t* attributes )
Parameters
device
NVML device handle
attributes
Device attributes
Returns

Description

Get attributes (engine counts etc.) for the given NVML device handle.

Note:

This API currently only supports MIG device handles.

For Ampere or newer fully supported devices. Supported on Linux only.

nvmlReturn_t nvmlDeviceGetAutoBoostedClocksEnabled ( nvmlDevice_t device, nvmlEnableState_t* isEnabled, nvmlEnableState_t* defaultIsEnabled )
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

Description

Retrieve the current state of Auto Boosted clocks on a device and store it in isEnabled

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

nvmlReturn_t nvmlDeviceGetBAR1MemoryInfo ( nvmlDevice_t device, nvmlBAR1Memory_t* bar1Memory )
Parameters
device
The identifier of the target device
bar1Memory
Reference in which BAR1 memory information is returned.
Returns

Description

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

Note:

In MIG mode, if device handle is provided, the API returns aggregate information, only if the caller has appropriate privileges. Per-instance information can be queried by using specific MIG device handles.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetBoardId ( nvmlDevice_t device, unsigned int* boardId )
Parameters
device
The identifier of the target device
boardId
Reference in which to return the device's board ID
Returns

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetBoardPartNumber ( nvmlDevice_t device, char* partNumber, unsigned int  length )
Parameters
device
Identifier of the target device
partNumber
Reference to the buffer to return
length
Length of the buffer reference
Returns

Description

Retrieves the the device board part number which is programmed into the board's InfoROM

For all products.

nvmlReturn_t nvmlDeviceGetBrand ( nvmlDevice_t device, nvmlBrandType_t* type )
Parameters
device
The identifier of the target device
type
Reference in which to return the product brand type
Returns

Description

Retrieves the brand of this device.

For all products.

The type is a member of nvmlBrandType_t defined above.

nvmlReturn_t nvmlDeviceGetBridgeChipInfo ( nvmlDevice_t device, nvmlBridgeChipHierarchy_t* bridgeHierarchy )
Parameters
device
The identifier of the target device
bridgeHierarchy
Reference to the returned bridge chip Hierarchy
Returns

Description

Get Bridge Chip Information for all the bridge chips on the board.

For all fully supported products. Only applicable to multi-GPU products.

nvmlReturn_t nvmlDeviceGetBusType ( nvmlDevice_t device, nvmlBusType_t* type )
Parameters
device
The identifier of the target device
type
The PCI Bus type
Description

Get the type of the GPU Bus (PCIe, PCI, ...)

return

nvmlReturn_t nvmlDeviceGetClock ( nvmlDevice_t device, nvmlClockType_t clockType, nvmlClockId_t clockId, unsigned int* clockMHz )
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

Description

Retrieves the clock speed for the clock specified by the clock type and clock ID.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetClockInfo ( nvmlDevice_t device, nvmlClockType_t type, unsigned int* clock )
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

Description

Retrieves the current clock speeds for the device.

For Fermi or newer fully supported devices.

See nvmlClockType_t for details on available clock information.

nvmlReturn_t nvmlDeviceGetComputeMode ( nvmlDevice_t device, nvmlComputeMode_t* mode )
Parameters
device
The identifier of the target device
mode
Reference in which to return the current compute mode
Returns

Description

Retrieves the current compute mode for the device.

For all products.

See nvmlComputeMode_t for details on allowed compute modes.

See also:

nvmlDeviceSetComputeMode()

nvmlReturn_t nvmlDeviceGetComputeRunningProcesses_v3 ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
Parameters
device
The device handle or MIG device handle
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

Description

Get information about processes with a compute context on a device

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

Note:

In MIG mode, if device handle is provided, the API returns aggregate information, only if the caller has appropriate privileges. Per-instance information can be queried by using specific MIG device handles. Querying per-instance information using MIG device handles is not supported if the device is in vGPU Host virtualization mode.

See also:

nvmlSystemGetProcessName

nvmlReturn_t nvmlDeviceGetConfComputeGpuAttestationReport ( nvmlDevice_t device, nvmlConfComputeGpuAttestationReport_t* gpuAtstReport )
Parameters
device
The identifier of the target device
gpuAtstReport
Reference in which to return the gpu attestation report
Returns

Description

Get Conf Computing Gpu attestation report.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

nvmlReturn_t nvmlDeviceGetConfComputeGpuCertificate ( nvmlDevice_t device, nvmlConfComputeGpuCertificate_t* gpuCert )
Parameters
device
The identifier of the target device
gpuCert
Reference in which to return the gpu certificate information
Returns

Description

Get Conf Computing Gpu certificate details.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

nvmlReturn_t nvmlDeviceGetConfComputeMemSizeInfo ( nvmlDevice_t device, nvmlConfComputeMemSizeInfo_t* memInfo )
Parameters
device
Device handle
memInfo
Protected/Unprotected Memory sizes
Returns

Description

Get Conf Computing Protected and Unprotected Memory Sizes.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

nvmlReturn_t nvmlDeviceGetConfComputeProtectedMemoryUsage ( nvmlDevice_t device, nvmlMemory_t* memory )
Parameters
device
The identifier of the target device
memory
Reference in which to return the memory information
Returns

Description

Get Conf Computing protected memory usage.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

nvmlReturn_t nvmlDeviceGetCount_v2 ( unsigned int* deviceCount )
Parameters
deviceCount
Reference in which to return the number of accessible devices
Returns

Description

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.

nvmlReturn_t nvmlDeviceGetCudaComputeCapability ( nvmlDevice_t device, int* major, int* minor )
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

Description

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

nvmlReturn_t nvmlDeviceGetCurrPcieLinkGeneration ( nvmlDevice_t device, unsigned int* currLinkGen )
Parameters
device
The identifier of the target device
currLinkGen
Reference in which to return the current PCIe link generation
Returns

Description

Retrieves the current PCIe link generation

For Fermi or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetCurrPcieLinkWidth ( nvmlDevice_t device, unsigned int* currLinkWidth )
Parameters
device
The identifier of the target device
currLinkWidth
Reference in which to return the current PCIe link generation
Returns

Description

Retrieves the current PCIe link width

For Fermi or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetCurrentClocksEventReasons ( nvmlDevice_t device, unsigned long long* clocksEventReasons )
Parameters
device
The identifier of the target device
clocksEventReasons
Reference in which to return bitmask of active clocks event reasons
Returns

Description

Retrieves current clocks event 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.

See also:

NvmlClocksEventReasons

nvmlDeviceGetSupportedClocksEventReasons

nvmlReturn_t nvmlDeviceGetCurrentClocksThrottleReasons ( nvmlDevice_t device, unsigned long long* clocksThrottleReasons )
nvmlReturn_t nvmlDeviceGetDecoderUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
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

Description

Retrieves the current utilization and sampling size in microseconds for the Decoder

For Kepler or newer fully supported devices.

Note:

On MIG-enabled GPUs, querying decoder utilization is not currently supported.

nvmlReturn_t nvmlDeviceGetDefaultApplicationsClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
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

Description

Retrieves the default applications clock that GPU boots with or defaults to after nvmlDeviceResetApplicationsClocks call.

For Kepler or newer fully supported devices.

See also:

nvmlDeviceGetApplicationsClock

nvmlReturn_t nvmlDeviceGetDefaultEccMode ( nvmlDevice_t device, nvmlEnableState_t* defaultMode )
Parameters
device
The identifier of the target device
defaultMode
Reference in which to return the default ECC mode
Returns

Description

Retrieves the default ECC modes for the device.

For Fermi or newer fully supported devices. Only applicable to devices with ECC. Requires NVML_INFOROM_ECC version 1.0 or higher.

See nvmlEnableState_t for details on allowed modes.

See also:

nvmlDeviceSetEccMode()

nvmlReturn_t nvmlDeviceGetDetailedEccErrors ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, nvmlEccErrorCounts_t* eccCounts )
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

Deprecated

This API supports only a fixed set of ECC error locations On different GPU architectures different locations are supported See nvmlDeviceGetMemoryErrorCounter

Description

Retrieves the detailed ECC error counts for the device.

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

See also:

nvmlDeviceClearEccErrorCounts()

nvmlReturn_t nvmlDeviceGetDisplayActive ( nvmlDevice_t device, nvmlEnableState_t* isActive )
Parameters
device
The identifier of the target device
isActive
Reference in which to return the display active state
Returns

Description

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.

nvmlReturn_t nvmlDeviceGetDisplayMode ( nvmlDevice_t device, nvmlEnableState_t* display )
Parameters
device
The identifier of the target device
display
Reference in which to return the display mode
Returns

Description

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.

nvmlReturn_t nvmlDeviceGetDriverModel ( nvmlDevice_t device, nvmlDriverModel_t* current, nvmlDriverModel_t* pending )
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

Description

Retrieves the current and pending driver model for the device.

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

See also:

nvmlDeviceSetDriverModel()

nvmlReturn_t nvmlDeviceGetDynamicPstatesInfo ( nvmlDevice_t device, nvmlGpuDynamicPstatesInfo_t* pDynamicPstatesInfo )
Parameters
device
pDynamicPstatesInfo
Returns

Description

Retrieve performance monitor samples from the associated subdevice.

nvmlReturn_t nvmlDeviceGetEccMode ( nvmlDevice_t device, nvmlEnableState_t* current, nvmlEnableState_t* pending )
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

Description

Retrieves the current and pending ECC modes for the device.

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

See also:

nvmlDeviceSetEccMode()

nvmlReturn_t nvmlDeviceGetEncoderCapacity ( nvmlDevice_t device, nvmlEncoderType_t encoderQueryType, unsigned int* encoderCapacity )
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

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetEncoderSessions ( nvmlDevice_t device, unsigned int* sessionCount, nvmlEncoderSessionInfo_t* sessionInfos )
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

Description

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 element count is passed in sessionCount, and sessionCount is used to return the number of sessions written to the buffer.

If the supplied buffer is not large enough to accommodate the active session array, the function returns NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlEncoderSessionInfo_t array required in sessionCount. To query the number of active encoder sessions, call this function with *sessionCount = 0. The code will return NVML_SUCCESS with number of active encoder sessions updated in *sessionCount.

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetEncoderStats ( nvmlDevice_t device, unsigned int* sessionCount, unsigned int* averageFps, unsigned int* averageLatency )
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

Description

Retrieves the current encoder statistics for a given device.

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetEncoderUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
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

Description

Retrieves the current utilization and sampling size in microseconds for the Encoder

For Kepler or newer fully supported devices.

Note:

On MIG-enabled GPUs, querying encoder utilization is not currently supported.

nvmlReturn_t nvmlDeviceGetEnforcedPowerLimit ( nvmlDevice_t device, unsigned int* limit )
Parameters
device
The device to communicate with
limit
Reference in which to return the power management limit in milliwatts
Returns

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetFBCSessions ( nvmlDevice_t device, unsigned int* sessionCount, nvmlFBCSessionInfo_t* sessionInfo )
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

Description

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

nvmlReturn_t nvmlDeviceGetFBCStats ( nvmlDevice_t device, nvmlFBCStats_t* fbcStats )
Parameters
device
The identifier of the target device
fbcStats
Reference to nvmlFBCStats_t structure containing NvFBC stats
Returns

Description

Retrieves the active frame buffer capture sessions statistics for a given device.

For Maxwell or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetFanControlPolicy_v2 ( nvmlDevice_t device, unsigned int  fan, nvmlFanControlPolicy_t* policy )
Description

Gets current fan control policy.

For Maxwell or newer fully supported devices.

For all cuda-capable discrete products with fans

device The identifier of the target device policy Reference in which to return the fan control policy

return NVML_SUCCESS if policy has been populated NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized NVML_ERROR_INVALID_ARGUMENT if device is invalid or policy is null or the fan given doesn't reference a fan that exists. NVML_ERROR_NOT_SUPPORTED if the device is older than Maxwell NVML_ERROR_UNKNOWN on any unexpected error

nvmlReturn_t nvmlDeviceGetFanSpeed ( nvmlDevice_t device, unsigned int* speed )
Parameters
device
The identifier of the target device
speed
Reference in which to return the fan speed percentage
Returns

Description

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 percentage of the product's maximum noise tolerance fan speed. This value may exceed 100% in certain cases.

nvmlReturn_t nvmlDeviceGetFanSpeed_v2 ( nvmlDevice_t device, unsigned int  fan, unsigned int* speed )
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

Description

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 product's maximum noise tolerance fan speed. This value may exceed 100% in certain cases.

nvmlReturn_t nvmlDeviceGetGpcClkMinMaxVfOffset ( nvmlDevice_t device, int* minOffset, int* maxOffset )
Parameters
device
The identifier of the target device
minOffset
The retrieved GPCCLK VF min offset value
maxOffset
The retrieved GPCCLK VF max offset value
Returns

Description

Retrieve the GPCCLK min max VF offset value.

nvmlReturn_t nvmlDeviceGetGpcClkVfOffset ( nvmlDevice_t device, int* offset )
Parameters
device
The identifier of the target device
offset
The retrieved GPCCLK VF offset value
Returns

Description

Retrieve the GPCCLK VF offset value

nvmlReturn_t nvmlDeviceGetGpuFabricInfo ( nvmlDevice_t device, nvmlGpuFabricInfo_t* gpuFabricInfo )
Parameters
device
The identifier of the target device
gpuFabricInfo
Information about GPU fabric state
Returns

Description

Get fabric information associated with the device.

HOPPER_OR_NEWER%

On Hopper + NVSwitch systems, GPU is registered with the NVIDIA Fabric Manager Upon successful registration, the GPU is added to the NVLink fabric to enable peer-to-peer communication. This API reports the current state of the GPU in the NVLink fabric along with other useful information.

nvmlReturn_t nvmlDeviceGetGpuMaxPcieLinkGeneration ( nvmlDevice_t device, unsigned int* maxLinkGenDevice )
Parameters
device
The identifier of the target device
maxLinkGenDevice
Reference in which to return the max PCIe link generation
Returns

Description

Retrieves the maximum PCIe link generation supported by this device

For Fermi or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetGpuOperationMode ( nvmlDevice_t device, nvmlGpuOperationMode_t* current, nvmlGpuOperationMode_t* pending )
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

Description

Retrieves the current GOM and pending GOM (the one that GPU will switch to after reboot).

For GK110 M-class and X-class Tesla 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 and Tesla C-class products.

See also:

nvmlGpuOperationMode_t

nvmlDeviceSetGpuOperationMode

nvmlReturn_t nvmlDeviceGetGraphicsRunningProcesses_v3 ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
Parameters
device
The device handle or MIG device handle
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

Description

Get information about processes with a graphics context on a device

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

Note:

In MIG mode, if device handle is provided, the API returns aggregate information, only if the caller has appropriate privileges. Per-instance information can be queried by using specific MIG device handles. Querying per-instance information using MIG device handles is not supported if the device is in vGPU Host virtualization mode.

See also:

nvmlSystemGetProcessName

nvmlReturn_t nvmlDeviceGetHandleByIndex_v2 ( unsigned int  index, nvmlDevice_t* device )
Parameters
index
The index of the target GPU, >= 0 and < accessibleDevices
device
Reference in which to return the device handle
Returns

Description

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_v2(). 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_v2().

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.

See also:

nvmlDeviceGetIndex

nvmlDeviceGetCount

nvmlReturn_t nvmlDeviceGetHandleByPciBusId_v2 ( const char* pciBusId, nvmlDevice_t* device )
Parameters
pciBusId
The PCI bus id of the target GPU
device
Reference in which to return the device handle
Returns

Description

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_v3().

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.

nvmlReturn_t nvmlDeviceGetHandleBySerial ( const char* serial, nvmlDevice_t* device )
Parameters
serial
The board serial number of the target GPU
device
Reference in which to return the device handle
Returns

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.

Description

Acquire the handle for a particular device, based on its board serial number.

For Fermi or newer fully supported devices.

This number corresponds to the value printed directly on the board, and to the value returned by nvmlDeviceGetSerial().

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

See also:

nvmlDeviceGetSerial

nvmlDeviceGetHandleByUUID

nvmlReturn_t nvmlDeviceGetHandleByUUID ( const char* uuid, nvmlDevice_t* device )
Parameters
uuid
The UUID of the target GPU or MIG instance
device
Reference in which to return the device handle or MIG device handle
Returns

Description

Acquire the handle for a particular device, based on its globally unique immutable UUID associated with each device.

For all products.

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

See also:

nvmlDeviceGetUUID

nvmlReturn_t nvmlDeviceGetIndex ( nvmlDevice_t device, unsigned int* index )
Parameters
device
The identifier of the target device
index
Reference in which to return the NVML index of the device
Returns

Description

Retrieves the NVML index of this device.

For all products.

Valid indices are derived from the accessibleDevices count returned by nvmlDeviceGetCount_v2(). 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_v2() and nvmlDeviceGetHandleByUUID().

When used with MIG device handles this API returns indices that can be passed to nvmlDeviceGetMigDeviceHandleByIndex to retrieve an identical handle. MIG device indices are unique within a device.

Note: The NVML index may not correlate with other APIs, such as the CUDA device index.

See also:

nvmlDeviceGetHandleByIndex()

nvmlDeviceGetCount()

nvmlReturn_t nvmlDeviceGetInforomConfigurationChecksum ( nvmlDevice_t device, unsigned int* checksum )
Parameters
device
The identifier of the target device
checksum
Reference in which to return the infoROM configuration checksum
Returns

Description

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)

nvmlReturn_t nvmlDeviceGetInforomImageVersion ( nvmlDevice_t device, char* version, unsigned int  length )
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

Description

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.

See also:

nvmlDeviceGetInforomVersion

nvmlReturn_t nvmlDeviceGetInforomVersion ( nvmlDevice_t device, nvmlInforomObject_t object, char* version, unsigned int  length )
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

Description

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.

See also:

nvmlDeviceGetInforomImageVersion

nvmlReturn_t nvmlDeviceGetIrqNum ( nvmlDevice_t device, unsigned int* irqNum )
Parameters
device
The identifier of the target device
irqNum
The interrupt number associated with the specified device
Returns

Description

Gets the device's interrupt number

nvmlReturn_t nvmlDeviceGetJpgUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
Parameters
device
The identifier of the target device
utilization
Reference to an unsigned int for jpg utilization info
samplingPeriodUs
Reference to an unsigned int for the sampling period in US
Returns

Description

Retrieves the current utilization and sampling size in microseconds for the JPG

TURING_OR_NEWER%

Note:

On MIG-enabled GPUs, querying decoder utilization is not currently supported.

nvmlReturn_t nvmlDeviceGetMPSComputeRunningProcesses_v3 ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
Parameters
device
The device handle or MIG device handle
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

Description

Get information about processes with a MPS compute context on a device

For Volta or newer fully supported devices.

This function returns information only about compute running processes (e.g. CUDA application which have active context) utilizing MPS. 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.

Note:

In MIG mode, if device handle is provided, the API returns aggregate information, only if the caller has appropriate privileges. Per-instance information can be queried by using specific MIG device handles. Querying per-instance information using MIG device handles is not supported if the device is in vGPU Host virtualization mode.

See also:

nvmlSystemGetProcessName

nvmlReturn_t nvmlDeviceGetMaxClockInfo ( nvmlDevice_t device, nvmlClockType_t type, unsigned int* clock )
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

Description

Retrieves the maximum clock speeds for the device.

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

nvmlReturn_t nvmlDeviceGetMaxCustomerBoostClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
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

Description

Retrieves the customer defined maximum boost clock speed specified by the given clock type.

For Pascal or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetMaxPcieLinkGeneration ( nvmlDevice_t device, unsigned int* maxLinkGen )
Parameters
device
The identifier of the target device
maxLinkGen
Reference in which to return the max PCIe link generation
Returns

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetMaxPcieLinkWidth ( nvmlDevice_t device, unsigned int* maxLinkWidth )
Parameters
device
The identifier of the target device
maxLinkWidth
Reference in which to return the max PCIe link generation
Returns

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetMemClkMinMaxVfOffset ( nvmlDevice_t device, int* minOffset, int* maxOffset )
Parameters
device
The identifier of the target device
minOffset
The retrieved MemClk VF min offset value
maxOffset
The retrieved MemClk VF max offset value
Returns

Description

Retrieve the MemClk (Memory Clock) min max VF offset value.

nvmlReturn_t nvmlDeviceGetMemClkVfOffset ( nvmlDevice_t device, int* offset )
Parameters
device
The identifier of the target device
offset
The retrieved MemClk VF offset value
Returns

Description

Retrieve the MemClk (Memory Clock) VF offset value.

nvmlReturn_t nvmlDeviceGetMemoryBusWidth ( nvmlDevice_t device, unsigned int* busWidth )
Parameters
device
The identifier of the target device
busWidth
The devices's memory bus width
Returns

Description

Gets the device's memory bus width

nvmlReturn_t nvmlDeviceGetMemoryErrorCounter ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, nvmlMemoryLocation_t locationType, unsigned long long* count )
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

Description

Retrieves the requested memory error counter for the device.

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

Note:

On MIG-enabled GPUs, per instance information can be queried using specific MIG device handles. Per instance information is currently only supported for non-DRAM uncorrectable volatile errors. Querying volatile errors using device handles is currently not supported.

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.

nvmlReturn_t nvmlDeviceGetMemoryInfo ( nvmlDevice_t device, nvmlMemory_t* memory )
Parameters
device
The identifier of the target device
memory
Reference in which to return the memory information
Returns

Description

Retrieves the amount of used, free, reserved and total memory available on the device, in bytes. The reserved amount is supported on version 2 only.

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_v2_t for details on available memory info.

Note:
  • In MIG mode, if device handle is provided, the API returns aggregate information, only if the caller has appropriate privileges. Per-instance information can be queried by using specific MIG device handles.

  • nvmlDeviceGetMemoryInfo_v2 adds additional memory information.

  • On systems where GPUs are NUMA nodes, the accuracy of FB memory utilization provided by this API depends on the memory accounting of the operating system. This is because FB memory is managed by the operating system instead of the NVIDIA GPU driver. Typically, pages allocated from FB memory are not released even after the process terminates to enhance performance. In scenarios where the operating system is under memory pressure, it may resort to utilizing FB memory. Such actions can result in discrepancies in the accuracy of memory reporting.

nvmlReturn_t nvmlDeviceGetMinMaxClockOfPState ( nvmlDevice_t device, nvmlClockType_t type, nvmlPstates_t pstate, unsigned int* minClockMHz, unsigned int* maxClockMHz )
Parameters
device
The identifier of the target device
type
Clock domain
pstate
PState to query
minClockMHz
Reference in which to return min clock frequency
maxClockMHz
Reference in which to return max clock frequency
Returns

Description

Retrieve min and max clocks of some clock domain for a given PState

nvmlReturn_t nvmlDeviceGetMinMaxFanSpeed ( nvmlDevice_t device, unsigned int* minSpeed, unsigned int* maxSpeed )
Parameters
device
The identifier of the target device
minSpeed
The minimum speed allowed to set
maxSpeed
The maximum speed allowed to set
Description

Retrieves the min and max fan speed that user can set for the GPU fan.

For all cuda-capable discrete products with fans

return NVML_SUCCESS if speed has been adjusted 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 (doesn't have fans) NVML_ERROR_UNKNOWN on any unexpected error

nvmlReturn_t nvmlDeviceGetMinorNumber ( nvmlDevice_t device, unsigned int* minorNumber )
Parameters
device
The identifier of the target device
minorNumber
Reference in which to return the minor number for the device
Returns

Description

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

nvmlReturn_t nvmlDeviceGetMultiGpuBoard ( nvmlDevice_t device, unsigned int* multiGpuBool )
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

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetName ( nvmlDevice_t device, char* name, unsigned int  length )
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

Description

Retrieves the name of this device.

For all products.

The name is an alphanumeric string that denotes a particular product, e.g. Tesla C2070. It will not exceed 96 characters in length (including the NULL terminator). See nvmlConstants::NVML_DEVICE_NAME_V2_BUFFER_SIZE.

When used with MIG device handles the API returns MIG device names which can be used to identify devices based on their attributes.

nvmlReturn_t nvmlDeviceGetNumFans ( nvmlDevice_t device, unsigned int* numFans )
Parameters
device
The identifier of the target device
numFans
The number of fans
Returns

Description

Retrieves the number of fans on the device.

For all discrete products with dedicated fans.

nvmlReturn_t nvmlDeviceGetNumGpuCores ( nvmlDevice_t device, unsigned int* numCores )
Parameters
device
The identifier of the target device
numCores
The number of cores for the specified device
Returns

Description

Gets the device's core count

nvmlReturn_t nvmlDeviceGetOfaUtilization ( nvmlDevice_t device, unsigned int* utilization, unsigned int* samplingPeriodUs )
Parameters
device
The identifier of the target device
utilization
Reference to an unsigned int for ofa utilization info
samplingPeriodUs
Reference to an unsigned int for the sampling period in US
Returns

Description

Retrieves the current utilization and sampling size in microseconds for the OFA (Optical Flow Accelerator)

TURING_OR_NEWER%

Note:

On MIG-enabled GPUs, querying decoder utilization is not currently supported.

nvmlReturn_t nvmlDeviceGetP2PStatus ( nvmlDevice_t device1, nvmlDevice_t device2, nvmlGpuP2PCapsIndex_t p2pIndex, nvmlGpuP2PStatus_t* p2pStatus )
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

Description

Retrieve the status for a given p2p capability index between a given pair of GPU

nvmlReturn_t nvmlDeviceGetPciInfo_v3 ( nvmlDevice_t device, nvmlPciInfo_t* pci )
Parameters
device
The identifier of the target device
pci
Reference in which to return the PCI info
Returns

Description

Retrieves the PCI attributes of this device.

For all products.

See nvmlPciInfo_t for details on the available PCI info.

nvmlReturn_t nvmlDeviceGetPcieLinkMaxSpeed ( nvmlDevice_t device, unsigned int* maxSpeed )
Parameters
device
The identifier of the target device
maxSpeed
The devices's PCIE Max Link speed in MBPS
Returns

Description

Gets the device's PCIE Max Link speed in MBPS

nvmlReturn_t nvmlDeviceGetPcieReplayCounter ( nvmlDevice_t device, unsigned int* value )
Parameters
device
The identifier of the target device
value
Reference in which to return the counter's value
Returns

Description

Retrieve the PCIe replay counter.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetPcieSpeed ( nvmlDevice_t device, unsigned int* pcieSpeed )
Parameters
device
The identifier of the target device
pcieSpeed
The devices's PCIe Max Link speed in Mbps
Returns

Description

Gets the device's PCIe Link speed in Mbps

nvmlReturn_t nvmlDeviceGetPcieThroughput ( nvmlDevice_t device, nvmlPcieUtilCounter_t counter, unsigned int* value )
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

Description

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 or newer fully supported devices.

This method is not supported in virtual machines running virtual GPU (vGPU).

nvmlReturn_t nvmlDeviceGetPerformanceState ( nvmlDevice_t device, nvmlPstates_t* pState )
Parameters
device
The identifier of the target device
pState
Reference in which to return the performance state reading
Returns

Description

Retrieves the current performance state for the device.

For Fermi or newer fully supported devices.

See nvmlPstates_t for details on allowed performance states.

nvmlReturn_t nvmlDeviceGetPersistenceMode ( nvmlDevice_t device, nvmlEnableState_t* mode )
Parameters
device
The identifier of the target device
mode
Reference in which to return the current driver persistence mode
Returns

Description

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.

See also:

nvmlDeviceSetPersistenceMode()

nvmlReturn_t nvmlDeviceGetPowerManagementDefaultLimit ( nvmlDevice_t device, unsigned int* defaultLimit )
Parameters
device
The identifier of the target device
defaultLimit
Reference in which to return the default power management limit in milliwatts
Returns

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetPowerManagementLimit ( nvmlDevice_t device, unsigned int* limit )
Parameters
device
The identifier of the target device
limit
Reference in which to return the power management limit in milliwatts
Returns

Description

Retrieves the power management limit associated with this device.

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

nvmlReturn_t nvmlDeviceGetPowerManagementLimitConstraints ( nvmlDevice_t device, unsigned int* minLimit, unsigned int* maxLimit )
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

Description

Retrieves information about possible values of power management limits on this device.

For Kepler or newer fully supported devices.

See also:

nvmlDeviceSetPowerManagementLimit

nvmlReturn_t nvmlDeviceGetPowerManagementMode ( nvmlDevice_t device, nvmlEnableState_t* mode )
Parameters
device
The identifier of the target device
mode
Reference in which to return the current power management mode
Returns

Description

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.

nvmlReturn_t nvmlDeviceGetPowerSource ( nvmlDevice_t device, nvmlPowerSource_t* powerSource )
Parameters
device
The identifier of the target device
powerSource
The power source of the device
Returns

Description

Gets the devices power source

nvmlReturn_t nvmlDeviceGetPowerState ( nvmlDevice_t device, nvmlPstates_t* pState )
Parameters
device
The identifier of the target device
pState
Reference in which to return the performance state reading
Returns

Description

Deprecated: Use nvmlDeviceGetPerformanceState. This function exposes an incorrect generalization.

Retrieve the current performance state for the device.

For Fermi or newer fully supported devices.

See nvmlPstates_t for details on allowed performance states.

nvmlReturn_t nvmlDeviceGetPowerUsage ( nvmlDevice_t device, unsigned int* power )
Parameters
device
The identifier of the target device
power
Reference in which to return the power usage information
Returns

Description

Retrieves power usage for this GPU in milliwatts and its associated circuitry (e.g. memory)

For Fermi or newer fully supported devices.

On Fermi and Kepler GPUs the reading is accurate to within +/- 5% of current power draw. On Ampere (except GA100) or newer GPUs, the API returns power averaged over 1 sec interval. On GA100 and older architectures, instantaneous power is returned.

See NVML_FI_DEV_POWER_AVERAGE and NVML_FI_DEV_POWER_INSTANT to query specific power values.

It is only available if power management mode is supported. See nvmlDeviceGetPowerManagementMode.

nvmlReturn_t nvmlDeviceGetRemappedRows ( nvmlDevice_t device, unsigned int* corrRows, unsigned int* uncRows, unsigned int* isPending, unsigned int* failureOccurred )
Parameters
device
The identifier of the target device
corrRows
Reference for number of rows remapped due to correctable errors
uncRows
Reference for number of rows remapped due to uncorrectable errors
isPending
Reference for whether or not remappings are pending
failureOccurred
Reference that is set when a remapping has failed in the past
Returns

Description

Get number of remapped rows. The number of rows reported will be based on the cause of the remapping. isPending indicates whether or not there are pending remappings. A reset will be required to actually remap the row. failureOccurred will be set if a row remapping ever failed in the past. A pending remapping won't affect future work on the GPU since error-containment and dynamic page blacklisting will take care of that.

Note:

On MIG-enabled GPUs with active instances, querying the number of remapped rows is not supported

For Ampere or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetRetiredPages ( nvmlDevice_t device, nvmlPageRetirementCause_t cause, unsigned int* pageCount, unsigned long long* addresses )
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

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetRetiredPagesPendingStatus ( nvmlDevice_t device, nvmlEnableState_t* isPending )
Parameters
device
The identifier of the target device
isPending
Reference in which to return the pending status
Returns

Description

Check if any pages are pending retirement and need a reboot to fully retire.

For Kepler or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetRetiredPages_v2 ( nvmlDevice_t device, nvmlPageRetirementCause_t cause, unsigned int* pageCount, unsigned long long* addresses, unsigned long long* timestamps )
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

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetRowRemapperHistogram ( nvmlDevice_t device, nvmlRowRemapperHistogramValues_t* values )
Parameters
device
Device handle
values
Histogram values
Returns

Description

Get the row remapper histogram. Returns the remap availability for each bank on the GPU.

nvmlReturn_t nvmlDeviceGetRunningProcessDetailList ( nvmlDevice_t device, nvmlProcessDetailList_t* plist )
Parameters
device
The device handle or MIG device handle
plist
Reference in which to process detail list
Returns

Description

Get information about running processes on a device for input context

HOPPER_OR_NEWER%

This function returns information only about running processes (e.g. CUDA application which have active context).

To determine the size of the plist->procArray array to allocate, call the function with plist->numProcArrayEntries set to zero and plist->procArray set to NULL. The return code will be either NVML_ERROR_INSUFFICIENT_SIZE (if there are valid processes of type plist->mode to report on, in which case the plist->numProcArrayEntries field will indicate the required number of entries in the array) or NVML_SUCCESS (if no processes of type plist->mode exist).

The usedGpuMemory field returned is all of the memory used by the application. The usedGpuCcProtectedMemory field returned is all of the protected 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 plist->procArray table in case new processes are spawned.

Note:

In MIG mode, if device handle is provided, the API returns aggregate information, only if the caller has appropriate privileges. Per-instance information can be queried by using specific MIG device handles. Querying per-instance information using MIG device handles is not supported if the device is in vGPU Host virtualization mode. Protected memory usage is currently not available in MIG mode and in windows.

nvmlReturn_t nvmlDeviceGetSamples ( nvmlDevice_t device, nvmlSamplingType_t type, unsigned long long lastSeenTimeStamp, nvmlValueType_t* sampleValType, unsigned int* sampleCount, nvmlSample_t* samples )
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

Description

Gets recent samples for the GPU.

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

Note:

On MIG-enabled GPUs, querying the following sample types, NVML_GPU_UTILIZATION_SAMPLES, NVML_MEMORY_UTILIZATION_SAMPLES NVML_ENC_UTILIZATION_SAMPLES and NVML_DEC_UTILIZATION_SAMPLES, is not currently supported.

nvmlReturn_t nvmlDeviceGetSerial ( nvmlDevice_t device, char* serial, unsigned int  length )
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

Description

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.

nvmlReturn_t nvmlDeviceGetSupportedClocksEventReasons ( nvmlDevice_t device, unsigned long long* supportedClocksEventReasons )
Parameters
device
The identifier of the target device
supportedClocksEventReasons
Reference in which to return bitmask of supported clocks event reasons
Returns

Description

Retrieves bitmask of supported clocks event reasons that can be returned by nvmlDeviceGetCurrentClocksEventReasons

For all fully supported products.

This method is not supported in virtual machines running virtual GPU (vGPU).

See also:

NvmlClocksEventReasons

nvmlDeviceGetCurrentClocksEventReasons

nvmlReturn_t nvmlDeviceGetSupportedClocksThrottleReasons ( nvmlDevice_t device, unsigned long long* supportedClocksThrottleReasons )
nvmlReturn_t nvmlDeviceGetSupportedGraphicsClocks ( nvmlDevice_t device, unsigned int  memoryClockMHz, unsigned int* count, unsigned int* clocksMHz )
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

Description

Retrieves the list of possible graphics clocks that can be used as an argument for nvmlDeviceSetApplicationsClocks.

For Kepler or newer fully supported devices.

See also:

nvmlDeviceSetApplicationsClocks

nvmlDeviceGetSupportedMemoryClocks

nvmlReturn_t nvmlDeviceGetSupportedMemoryClocks ( nvmlDevice_t device, unsigned int* count, unsigned int* clocksMHz )
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

Description

Retrieves the list of possible memory clocks that can be used as an argument for nvmlDeviceSetApplicationsClocks.

For Kepler or newer fully supported devices.

See also:

nvmlDeviceSetApplicationsClocks

nvmlDeviceGetSupportedGraphicsClocks

nvmlReturn_t nvmlDeviceGetSupportedPerformanceStates ( nvmlDevice_t device, nvmlPstates_t* pstates, unsigned int  size )
Parameters
device
The identifier of the target device
pstates
Container to return the list of performance states supported by device
size
Size of the supplied pstates array in bytes
Returns

Description

Get all supported Performance States (P-States) for the device.

The returned array would contain a contiguous list of valid P-States supported by the device. If the number of supported P-States is fewer than the size of the array supplied missing elements would contain NVML_PSTATE_UNKNOWN.

The number of elements in the returned list will never exceed NVML_MAX_GPU_PERF_PSTATES.

nvmlReturn_t nvmlDeviceGetTargetFanSpeed ( nvmlDevice_t device, unsigned int  fan, unsigned int* targetSpeed )
Parameters
device
The identifier of the target device
fan
The index of the target fan, zero indexed.
targetSpeed
Reference in which to return the fan speed percentage
Returns

Description

Retrieves the intended target speed of the device's specified fan.

Normally, the driver dynamically adjusts the fan based on the needs of the GPU. But when user set fan speed using nvmlDeviceSetFanSpeed_v2, the driver will attempt to make the fan achieve the setting in nvmlDeviceSetFanSpeed_v2. The actual current speed of the fan is reported in nvmlDeviceGetFanSpeed_v2.

For all discrete products with dedicated fans.

The fan speed is expressed as a percentage of the product's maximum noise tolerance fan speed. This value may exceed 100% in certain cases.

nvmlReturn_t nvmlDeviceGetTemperature ( nvmlDevice_t device, nvmlTemperatureSensors_t sensorType, unsigned int* temp )
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

Description

Retrieves the current temperature readings for the device, in degrees C.

For all products.

See nvmlTemperatureSensors_t for details on available temperature sensors.

nvmlReturn_t nvmlDeviceGetTemperatureThreshold ( nvmlDevice_t device, nvmlTemperatureThresholds_t thresholdType, unsigned int* temp )
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

Description

Retrieves the temperature threshold for the GPU with the specified threshold type in degrees C.

For Kepler or newer fully supported devices.

See nvmlTemperatureThresholds_t for details on available temperature thresholds.

Note: This API is no longer the preferred interface for retrieving the following temperature thresholds on Ada and later architectures: NVML_TEMPERATURE_THRESHOLD_SHUTDOWN, NVML_TEMPERATURE_THRESHOLD_SLOWDOWN, NVML_TEMPERATURE_THRESHOLD_MEM_MAX and NVML_TEMPERATURE_THRESHOLD_GPU_MAX.

Support for reading these temperature thresholds for Ada and later architectures would be removed from this API in future releases. Please use nvmlDeviceGetFieldValues with NVML_FI_DEV_TEMPERATURE_* fields to retrieve temperature thresholds on these architectures.

nvmlReturn_t nvmlDeviceGetThermalSettings ( nvmlDevice_t device, unsigned int  sensorIndex, nvmlGpuThermalSettings_t* pThermalSettings )
Parameters
device
The identifier of the target device
sensorIndex
The index of the thermal sensor
pThermalSettings
Reference in which to return the thermal sensor information
Returns

Description

Used to execute a list of thermal system instructions.

nvmlReturn_t nvmlDeviceGetTopologyCommonAncestor ( nvmlDevice_t device1, nvmlDevice_t device2, nvmlGpuTopologyLevel_t* pathInfo )
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

Description

Retrieve the common ancestor for two devices For all products. Supported on Linux only.

nvmlReturn_t nvmlDeviceGetTopologyNearestGpus ( nvmlDevice_t device, nvmlGpuTopologyLevel_t level, unsigned int* count, nvmlDevice_t* deviceArray )
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

Description

Retrieve the set of GPUs that are nearest to a given device at a specific interconnectivity level For all products. Supported on Linux only.

nvmlReturn_t nvmlDeviceGetTotalEccErrors ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, unsigned long long* eccCounts )
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

Description

Retrieves the total ECC error counts for the device.

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

See also:

nvmlDeviceClearEccErrorCounts()

nvmlReturn_t nvmlDeviceGetTotalEnergyConsumption ( nvmlDevice_t device, unsigned long long* energy )
Parameters
device
The identifier of the target device
energy
Reference in which to return the energy consumption information
Returns

Description

Retrieves total energy consumption for this GPU in millijoules (mJ) since the driver was last reloaded

For Volta or newer fully supported devices.

nvmlReturn_t nvmlDeviceGetUUID ( nvmlDevice_t device, char* uuid, unsigned int  length )
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

Description

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 96 characters in length (including the NULL terminator). See nvmlConstants::NVML_DEVICE_UUID_V2_BUFFER_SIZE.

When used with MIG device handles the API returns globally unique UUIDs which can be used to identify MIG devices across both GPU and MIG devices. UUIDs are immutable for the lifetime of a MIG device.

nvmlReturn_t nvmlDeviceGetUtilizationRates ( nvmlDevice_t device, nvmlUtilization_t* utilization )
Parameters
device
The identifier of the target device
utilization
Reference in which to return the utilization information
Returns

Description

Retrieves the current utilization rates for the device's major subsystems.

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

  • On MIG-enabled GPUs, querying device utilization rates is not currently supported.

nvmlReturn_t nvmlDeviceGetVbiosVersion ( nvmlDevice_t device, char* version, unsigned int  length )
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

Description

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.

nvmlReturn_t nvmlDeviceGetViolationStatus ( nvmlDevice_t device, nvmlPerfPolicyType_t perfPolicyType, nvmlViolationTime_t* violTime )
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

Description

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 or newer fully supported devices.

nvmlReturn_t nvmlDeviceOnSameBoard ( nvmlDevice_t device1, nvmlDevice_t device2, int* onSameBoard )
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

Description

Check if the GPU devices are on the same physical board.

For all fully supported products.

nvmlReturn_t nvmlDeviceResetApplicationsClocks ( nvmlDevice_t device )
Parameters
device
The identifier of the target device
Returns

Description

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 or newer non-GeForce fully supported devices and Maxwell or newer GeForce devices.

nvmlReturn_t nvmlDeviceSetAutoBoostedClocksEnabled ( nvmlDevice_t device, nvmlEnableState_t enabled )
Parameters
device
The identifier of the target device
enabled
What state to try to set Auto Boosted clocks of the target device to
Returns

Description

Try to set the current state of Auto Boosted clocks on a device.

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

nvmlReturn_t nvmlDeviceSetDefaultAutoBoostedClocksEnabled ( nvmlDevice_t device, nvmlEnableState_t enabled, unsigned int  flags )
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

Description

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

nvmlReturn_t nvmlDeviceSetDefaultFanSpeed_v2 ( nvmlDevice_t device, unsigned int  fan )
Parameters
device
The identifier of the target device
fan
The index of the fan, starting at zero
Description

Sets the speed of the fan control policy to default.

For all cuda-capable discrete products with fans

return NVML_SUCCESS if speed has been adjusted 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 (doesn't have fans) NVML_ERROR_UNKNOWN on any unexpected error

nvmlReturn_t nvmlDeviceSetFanControlPolicy ( nvmlDevice_t device, unsigned int  fan, nvmlFanControlPolicy_t policy )
Description

Sets current fan control policy.

For Maxwell or newer fully supported devices.

Requires privileged user.

For all cuda-capable discrete products with fans

device The identifier of the target device policy The fan control policy to set

return NVML_SUCCESS if policy has been set NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized NVML_ERROR_INVALID_ARGUMENT if device is invalid or policy is null or the fan given doesn't reference a fan that exists. NVML_ERROR_NOT_SUPPORTED if the device is older than Maxwell NVML_ERROR_UNKNOWN on any unexpected error

nvmlReturn_t nvmlDeviceSetTemperatureThreshold ( nvmlDevice_t device, nvmlTemperatureThresholds_t thresholdType, int* temp )
Parameters
device
The identifier of the target device
thresholdType
The type of threshold value to be set
temp
Reference which hold the value to be set
Returns

Description

Sets the temperature threshold for the GPU with the specified threshold type in degrees C.

For Maxwell or newer fully supported devices.

See nvmlTemperatureThresholds_t for details on available temperature thresholds.

nvmlReturn_t nvmlDeviceValidateInforom ( nvmlDevice_t device )
Parameters
device
The identifier of the target device
Returns

Description

Reads the infoROM from the flash and verifies the checksums.

For all products with an inforom.

nvmlReturn_t nvmlSystemGetConfComputeCapabilities ( nvmlConfComputeSystemCaps_t* capabilities )
Parameters
capabilities
System CC capabilities
Returns

Description

Get Conf Computing System capabilities.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

nvmlReturn_t nvmlSystemGetConfComputeGpusReadyState ( unsigned int* isAcceptingWork )
Parameters
isAcceptingWork
Returns GPU current work accepting state, NVML_CC_ACCEPTING_CLIENT_REQUESTS_TRUE or NVML_CC_ACCEPTING_CLIENT_REQUESTS_FALSE
Description

Get Conf Computing GPUs ready state.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

return

nvmlReturn_t nvmlSystemGetConfComputeState ( nvmlConfComputeSystemState_t* state )
Parameters
state
System CC State
Returns

Description

Get Conf Computing System State.

For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.

nvmlReturn_t nvmlSystemGetTopologyGpuSet ( unsigned int  cpuNumber, unsigned int* count, nvmlDevice_t* deviceArray )
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

Description

Retrieve the set of GPUs that have a CPU affinity with the given CPU number For all products. Supported on Linux only.

nvmlReturn_t nvmlVgpuInstanceGetMdevUUID ( nvmlVgpuInstance_t vgpuInstance, char* mdevUuid, unsigned int  size )
Parameters
vgpuInstance
Identifier of the target vGPU instance
mdevUuid
Pointer to caller-supplied buffer to hold MDEV UUID
size
Size of buffer in bytes
Returns

Description

Retrieve the MDEV UUID of a vGPU instance.

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

For Maxwell or newer fully supported devices.

CPU and Memory Affinity


NVML API Reference Guide (PDF) - v535 (older) - Last updated January 31, 2024 - Send Feedback