NVML API Reference Guide (PDF) - vR331 (older) - Last updated March 14, 2014 - Send Feedback

4.10. 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(), nvmlDeviceGetHandleBySerial(), nvmlDeviceGetHandleByPciBusId(). or nvmlDeviceGetHandleByUUID().

Functions

nvmlReturn_t nvmlDeviceGetAPIRestriction ( nvmlDevice_t device, nvmlRestrictedAPI_t apiType, nvmlEnableState_t* isRestricted )
nvmlReturn_t nvmlDeviceGetApplicationsClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
nvmlReturn_t nvmlDeviceGetBAR1MemoryInfo ( nvmlDevice_t device, nvmlBAR1Memory_t* bar1Memory )
nvmlReturn_t nvmlDeviceGetBridgeChipInfo ( nvmlDevice_t device, nvmlBridgeChipHierarchy_t* bridgeHierarchy )
nvmlReturn_t nvmlDeviceGetClockInfo ( nvmlDevice_t device, nvmlClockType_t type, unsigned int* clock )
nvmlReturn_t nvmlDeviceGetComputeMode ( nvmlDevice_t device, nvmlComputeMode_t* mode )
nvmlReturn_t nvmlDeviceGetComputeRunningProcesses ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
nvmlReturn_t nvmlDeviceGetCount ( unsigned int* deviceCount )
nvmlReturn_t nvmlDeviceGetCurrPcieLinkGeneration ( nvmlDevice_t device, unsigned int* currLinkGen )
nvmlReturn_t nvmlDeviceGetCurrPcieLinkWidth ( nvmlDevice_t device, unsigned int* currLinkWidth )
nvmlReturn_t nvmlDeviceGetCurrentClocksThrottleReasons ( nvmlDevice_t device, unsigned long long* clocksThrottleReasons )
nvmlReturn_t nvmlDeviceGetDefaultApplicationsClock ( nvmlDevice_t device, nvmlClockType_t clockType, unsigned int* clockMHz )
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 nvmlDeviceGetEccMode ( nvmlDevice_t device, nvmlEnableState_t* current, nvmlEnableState_t* pending )
nvmlReturn_t nvmlDeviceGetEnforcedPowerLimit ( nvmlDevice_t device, unsigned int* limit )
nvmlReturn_t nvmlDeviceGetFanSpeed ( nvmlDevice_t device, unsigned int* speed )
nvmlReturn_t nvmlDeviceGetGpuOperationMode ( nvmlDevice_t device, nvmlGpuOperationMode_t* current, nvmlGpuOperationMode_t* pending )
nvmlReturn_t nvmlDeviceGetHandleByIndex ( unsigned int  index, nvmlDevice_t* device )
nvmlReturn_t nvmlDeviceGetHandleByPciBusId ( 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 nvmlDeviceGetMaxClockInfo ( nvmlDevice_t device, nvmlClockType_t type, unsigned int* clock )
nvmlReturn_t nvmlDeviceGetMaxPcieLinkGeneration ( nvmlDevice_t device, unsigned int* maxLinkGen )
nvmlReturn_t nvmlDeviceGetMaxPcieLinkWidth ( nvmlDevice_t device, unsigned int* maxLinkWidth )
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 nvmlDeviceGetMinorNumber ( nvmlDevice_t device, unsigned int* minorNumber )
nvmlReturn_t nvmlDeviceGetName ( nvmlDevice_t device, char* name, unsigned int  length )
nvmlReturn_t nvmlDeviceGetPciInfo ( nvmlDevice_t device, nvmlPciInfo_t* pci )
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 nvmlDeviceGetPowerState ( nvmlDevice_t device, nvmlPstates_t* pState )
nvmlReturn_t nvmlDeviceGetPowerUsage ( nvmlDevice_t device, unsigned int* power )
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 nvmlDeviceGetSerial ( nvmlDevice_t device, char* serial, unsigned int  length )
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 nvmlDeviceGetTemperature ( nvmlDevice_t device, nvmlTemperatureSensors_t sensorType, unsigned int* temp )
nvmlReturn_t nvmlDeviceGetTotalEccErrors ( nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, unsigned long long* eccCounts )
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 nvmlDeviceOnSameBoard ( nvmlDevice_t device1, nvmlDevice_t device2, int* onSameBoard )
nvmlReturn_t nvmlDeviceResetApplicationsClocks ( nvmlDevice_t device )
nvmlReturn_t nvmlDeviceValidateInforom ( nvmlDevice_t device )

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 nvmlDeviceGetAPIRestriction to change current permissions.

For Tesla and Quadro &tm products from the Kepler+ family.

See also:

nvmlRestrictedAPI_t

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 Tesla products from the Kepler family.

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

For Tesla and Quadro &tm products from the Kepler+ family.

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 multi-GPU products

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 Tesla and Quadro products from the Fermi and Kepler families.

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 CUDA-capable products.

See nvmlComputeMode_t for details on allowed compute modes.

See also:

nvmlDeviceSetComputeMode()

nvmlReturn_t nvmlDeviceGetComputeRunningProcesses ( nvmlDevice_t device, unsigned int* infoCount, nvmlProcessInfo_t* infos )
Parameters
device
The identifier of the target device
infoCount
Reference in which to provide the infos array size, and to return the number of returned elements
infos
Reference in which to return the process information
Returns

Description

Get information about processes with a compute context on a device

For Tesla and Quadro products from the Fermi and Kepler families.

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.

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.

See also:

nvmlSystemGetProcessName

nvmlReturn_t nvmlDeviceGetCount ( 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 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 Tesla and Quadro products from the Fermi and Kepler families.

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 Tesla and Quadro products from the Fermi and Kepler families.

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

Description

Retrieves current clocks throttling reasons.

For Tesla products from Kepler family.

Note:

More than one bit can be enabled at the same time. Multiple reasons can be affecting clocks at once.

See also:

NvmlClocksThrottleReasons

nvmlDeviceGetSupportedClocksThrottleReasons

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 Tesla products from the Kepler family.

See also:

nvmlDeviceGetApplicationsClock

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 Tesla and Quadro products from the Fermi and Kepler families. 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 Tesla and Quadro products from the Fermi and Kepler families.

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 Tesla and Quadro products from the Fermi and Kepler families.

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 Tesla and Quadro products from the Fermi and Kepler families. 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 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 Tesla and Quadro products from the Fermi and Kepler families. 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 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

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 percent of the maximum, i.e. full speed is 100%.

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. Not supported on Quadro and Tesla C-class products.

See also:

nvmlGpuOperationMode_t

nvmlDeviceSetGpuOperationMode

nvmlReturn_t nvmlDeviceGetHandleByIndex ( 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(). For example, if accessibleDevices is 2 the valid indices are 0 and 1, corresponding to GPU 0 and GPU 1.

The order in which NVML enumerates devices has no guarantees of consistency between reboots. For that reason it is recommended that devices be looked up by their PCI ids or UUID. See nvmlDeviceGetHandleByUUID() and nvmlDeviceGetHandleByPciBusId().

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

Starting from NVML 5, this API causes NVML to initialize the target GPU NVML may initialize additional GPUs if:

  • The target GPU is an SLI slave

Note: New nvmlDeviceGetCount_v2 (default in NVML 5.319) returns count of all devices in the system even if nvmlDeviceGetHandleByIndex_v2 returns NVML_ERROR_NO_PERMISSION for such device. Update your code to handle this error, or use NVML 4.304 or older nvml header file. For backward binary compatibility reasons _v1 version of the API is still present in the shared library. Old _v1 version of nvmlDeviceGetCount doesn't count devices that NVML has no permission to talk to.

This means that nvmlDeviceGetHandleByIndex_v2 and _v1 can return different devices for the same index. If you don't touch macros that map old (_v1) versions to _v2 versions at the top of the file you don't need to worry about that.

See also:

nvmlDeviceGetIndex

nvmlDeviceGetCount

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

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

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
device
Reference in which to return the 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(). For example, if accessibleDevices is 2 the valid indices are 0 and 1, corresponding to GPU 0 and GPU 1.

The order in which NVML enumerates devices has no guarantees of consistency between reboots. For that reason it is recommended that devices be looked up by their PCI ids or GPU UUID. See nvmlDeviceGetHandleByPciBusId() and nvmlDeviceGetHandleByUUID().

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

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 Tesla and Quadro products from the Fermi and Kepler families.

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 Tesla and Quadro products from the Kepler family.

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 Tesla and Quadro products from the Fermi and Kepler families.

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 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 Tesla and Quadro products from the Fermi and Kepler families.

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 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 Tesla and Quadro products from the Fermi and Kepler families.

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 Tesla and Quadro products from the Fermi and Kepler families.

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 Tesla and Quadro products from the Fermi family. 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.

For all Tesla and Quadro products from the Kepler family.

Requires ECC Mode to be enabled.

See nvmlMemoryErrorType_t for a description of available memory error types. See nvmlEccCounterType_t for a description of available counter types. See nvmlMemoryLocation_t for a description of available counter locations.

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 and total memory available on the device, in bytes.

For all products.

Enabling ECC reduces the amount of total available memory, due to the extra required parity bits. Under WDDM most device memory is allocated and managed on startup by Windows.

Under Linux and Windows TCC, the reported amount of used memory is equal to the sum of memory allocated by all active channels on the device.

See nvmlMemory_t for details on available memory info.

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 the GPUs. Supported only for Linux

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

nvmlReturn_t nvmlDeviceGetPciInfo ( 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 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 Tesla and Quadro products from the Fermi and Kepler families.

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 CUDA-capable 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 Tesla and Quadro products from the Kepler family.

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 "GF11x" Tesla and Quadro products from the Fermi family.

  • Requires NVML_INFOROM_POWER version 3.0 or higher.

For Tesla and Quadro products from the Kepler family.

  • Does not require NVML_INFOROM_POWER object.

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 Tesla and Quadro products from the Kepler family.

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

Retrieves the power management mode associated with this device.

For "GF11x" Tesla and Quadro products from the Fermi family.

  • Requires NVML_INFOROM_POWER version 3.0 or higher.

For Tesla and Quadro products from the Kepler family.

  • 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 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 Tesla and Quadro products from the Fermi and Kepler families.

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 "GF11x" Tesla and Quadro products from the Fermi family.

  • Requires NVML_INFOROM_POWER version 3.0 or higher.

For Tesla and Quadro products from the Kepler family.

  • Does not require NVML_INFOROM_POWER object.

On Fermi and Kepler GPUs the reading is accurate to within +/- 5% of current power draw.

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

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 Tesla K20 products

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 Tesla K20 products

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 Tesla and Quadro products from the Fermi and Kepler families.

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 nvmlDeviceGetSupportedClocksThrottleReasons ( nvmlDevice_t device, unsigned long long* supportedClocksThrottleReasons )
Parameters
device
The identifier of the target device
supportedClocksThrottleReasons
Reference in which to return bitmask of supported clocks throttle reasons
Returns

Description

Retrieves bitmask of supported clocks throttle reasons that can be returned by nvmlDeviceGetCurrentClocksThrottleReasons

For all devices

See also:

NvmlClocksThrottleReasons

nvmlDeviceGetCurrentClocksThrottleReasons

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 Tesla products and Quadro products from the Kepler family.

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 Tesla products from the Kepler family.

See also:

nvmlDeviceSetApplicationsClocks

nvmlDeviceGetSupportedGraphicsClocks

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 discrete and S-class products.

See nvmlTemperatureSensors_t for details on available temperature sensors.

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 Tesla and Quadro products from the Fermi and Kepler families. 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 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 CUDA capable GPUs.

The UUID is a globally unique identifier. It is the only available identifier for pre-Fermi-architecture products. It does NOT correspond to any identifier printed on the board. It will not exceed 80 characters in length (including the NULL terminator). See nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.

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 Tesla and Quadro products from the Fermi and Kepler families.

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.

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

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.

See also:

nvmlDeviceGetApplicationsClock

nvmlDeviceSetApplicationsClocks

For Tesla products from the Kepler family.

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 Tesla and Quadro products from the Fermi and Kepler families.


NVML API Reference Guide (PDF) - vR331 (older) - Last updated March 14, 2014 - Send Feedback