Device Queries

This page describes that queries that NVML can perform against each device. More...


Functions

nvmlReturn_t DECLDIR nvmlDeviceGetCount (unsigned int *deviceCount)
 Retrieve the number of compute devices in the system.
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByIndex (unsigned int index, nvmlDevice_t *device)
 Acquire the handle for a particular device, based on its index.
nvmlReturn_t DECLDIR nvmlDeviceGetHandleBySerial (char *serial, nvmlDevice_t *device)
 Acquire the handle for a particular device, based on its board serial number.
nvmlReturn_t DECLDIR nvmlDeviceGetHandleByPciBusId (char *pciBusId, nvmlDevice_t *device)
 Acquire the handle for a particular device, based on its PCI bus id.
nvmlReturn_t DECLDIR nvmlDeviceGetName (nvmlDevice_t device, char *name, unsigned int length)
 Retrieve the name of this device.
nvmlReturn_t DECLDIR nvmlDeviceGetSerial (nvmlDevice_t device, char *serial, unsigned int length)
 Retrieve the globally unique serial number associated with this device.
nvmlReturn_t DECLDIR nvmlDeviceGetUUID (nvmlDevice_t device, char *uuid, unsigned int length)
 Retrieve the UUID associated with this device.
nvmlReturn_t DECLDIR nvmlDeviceGetInforomVersion (nvmlDevice_t device, nvmlInforomObject_t object, char *version, unsigned int length)
 Retrieve the version info for the device's inforom.
nvmlReturn_t DECLDIR nvmlDeviceGetDisplayMode (nvmlDevice_t device, nvmlEnableState_t *display)
 Retrieve the display mode for the this device.
nvmlReturn_t DECLDIR nvmlDeviceGetPersistenceMode (nvmlDevice_t device, nvmlEnableState_t *mode)
 Retrieve the persistence mode associated with this device.
nvmlReturn_t DECLDIR nvmlDeviceGetPciInfo (nvmlDevice_t device, nvmlPciInfo_t *pci)
 Retrieve the PCI attributes of this device.
nvmlReturn_t DECLDIR nvmlDeviceGetClockInfo (nvmlDevice_t device, nvmlClockType_t type, unsigned int *clock)
 Retrieve the current clock speeds for the device, in Mhz.
nvmlReturn_t DECLDIR nvmlDeviceGetFanSpeed (nvmlDevice_t device, unsigned int *speed)
 Retrieve the current operating speed of the device's fan.
nvmlReturn_t DECLDIR nvmlDeviceGetTemperature (nvmlDevice_t device, nvmlTemperatureSensors_t sensorType, unsigned int *temp)
 Retrieve the current temperature readings for the device, in degrees F.
nvmlReturn_t DECLDIR nvmlDeviceGetPowerState (nvmlDevice_t device, nvmlPstates_t *pState)
 Retrieve the current power state for the device.
nvmlReturn_t DECLDIR nvmlDeviceGetPowerCappingMode (nvmlDevice_t device, nvmlEnableState_t *mode)
 Retrieve the power capping mode associated with this device.
nvmlReturn_t DECLDIR nvmlDeviceGetPowerUsage (nvmlDevice_t device, unsigned int *power)
 Retrieve the power usage reading for the device, in milliwatts.
nvmlReturn_t DECLDIR nvmlDeviceGetMemoryInfo (nvmlDevice_t device, nvmlMemory_t *memory)
 Retrieve the amount of used, free and total memory available on the device, in bytes.
nvmlReturn_t DECLDIR nvmlDeviceGetComputeMode (nvmlDevice_t device, nvmlComputeMode_t *mode)
 Retrieve the current compute mode for the device.
nvmlReturn_t DECLDIR nvmlDeviceGetEccMode (nvmlDevice_t device, nvmlEnableState_t *current, nvmlEnableState_t *pending)
 Retrieve the current and pending ECC modes for the device.
nvmlReturn_t DECLDIR nvmlDeviceGetTotalEccErrors (nvmlDevice_t device, nvmlEccBitType_t bitType, nvmlEccCounterType_t counterType, unsigned long long *eccCounts)
 Retrieve the total ECC error counts for the device.
nvmlReturn_t DECLDIR nvmlDeviceGetDetailedEccErrors (nvmlDevice_t device, nvmlEccBitType_t bitType, nvmlEccCounterType_t counterType, nvmlEccErrorCounts_t *eccCounts)
 Retrieve the detailed ECC error counts for the device.
nvmlReturn_t DECLDIR nvmlDeviceGetUtilizationRates (nvmlDevice_t device, nvmlUtilization_t *utilization)
 Retrieve the current utilization rates for the device's major subsystems.
nvmlReturn_t DECLDIR nvmlDeviceGetDriverModel (nvmlDevice_t device, nvmlDriverModel_t *current, nvmlDriverModel_t *pending)
 Retrieve the current and pending driver model for the device.


Detailed Description

This page 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() or nvmlDeviceGetHandleByPciBusId().


Function Documentation

nvmlReturn_t DECLDIR nvmlDeviceGetClockInfo ( nvmlDevice_t  device,
nvmlClockType_t  type,
unsigned int *  clock 
)

Retrieve the current clock speeds for the device, in Mhz.

See nvmlClockType_t for details on available clock information.

Parameters:
device The identifer of the target device
type Identify which clock domain to query
clock Reference in which to return the clock speed
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetComputeMode ( nvmlDevice_t  device,
nvmlComputeMode_t mode 
)

Retrieve the current compute mode for the device.

See nvmlComputeMode_t for details on allowed compute modes.

Parameters:
device The identifer of the target device
mode Reference in which to return the current compute mode
Returns:
See also:
nvmlDeviceSetComputeMode()

nvmlReturn_t DECLDIR nvmlDeviceGetCount ( unsigned int *  deviceCount  ) 

Retrieve the number of compute devices in the system.

A compute device is a single GPU.

On some platforms not all devices may be accessible due to permission restrictions. In these cases the device count will reflect only the GPUs that NVML has access to.

Parameters:
deviceCount Reference in which to return the number of accessible devices
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetDetailedEccErrors ( nvmlDevice_t  device,
nvmlEccBitType_t  bitType,
nvmlEccCounterType_t  counterType,
nvmlEccErrorCounts_t eccCounts 
)

Retrieve the detailed ECC error counts for the device.

For Fermi-class products only.

Detailed errors provide separate ECC counts for specific parts of the memory system.

See nvmlEccBitType_t for a description of available bit types.
See nvmlEccCounterType_t for a description of available counter types.
See nvmlEccErrorCounts_t for a description of provided detailed ECC counts.

Parameters:
device The identifer of the target device
bitType Flag that specifies the bit-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:
See also:
nvmlDeviceClearEccErrorCounts()

nvmlReturn_t DECLDIR nvmlDeviceGetDisplayMode ( nvmlDevice_t  device,
nvmlEnableState_t display 
)

Retrieve the display mode for the this device.

This method indicates whether a physical display is currently connected to the device.

See nvmlEnableState_t for details on allowed modes.

Parameters:
device The identifer of the target device
display Reference in which to return the display mode
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetDriverModel ( nvmlDevice_t  device,
nvmlDriverModel_t current,
nvmlDriverModel_t pending 
)

Retrieve the current and pending driver model for the device.

Windows-only.

On Windows platforms the device driver can run in either WDDM or WDM (TCC) mode. If a display is attached to the device it must run in WDDM mode. TCC mode is preferred if a display is not attached.

See nvmlDriverModel_t for details on available driver models.

Parameters:
device The identifer 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:
See also:
nvmlDeviceSetDriverModel()

nvmlReturn_t DECLDIR nvmlDeviceGetEccMode ( nvmlDevice_t  device,
nvmlEnableState_t current,
nvmlEnableState_t pending 
)

Retrieve the current and pending ECC modes for the device.

For Fermi-class products only.

Changing ECC modes requires a reboot. The "pending" ECC mode refers to the target mode following the next reboot.

See nvmlEnableState_t for details on allowed modes.

Parameters:
device The identifer 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:
See also:
nvmlDeviceSetEccMode()

nvmlReturn_t DECLDIR nvmlDeviceGetFanSpeed ( nvmlDevice_t  device,
unsigned int *  speed 
)

Retrieve the current operating speed of the device's fan.

The fan speed is expressed as a percent of the maximum, i.e. full speed is 100%.

Fan speeds are generally not available through NVML for M and X class parts, since these parts are cooled through system fans.

Parameters:
device The identifer of the target device
speed Reference in which to return the fan speed percentage
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetHandleByIndex ( unsigned int  index,
nvmlDevice_t *  device 
)

Acquire the handle for a particular device, based on its index.

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 guarentees of consistency between reboots. For that reason it is recommended that devices be looked by by their PCI ids or board serial numbers. See nvmlDeviceGetHandleBySerial() and nvmlDeviceGetHandleByPciBusId().

Parameters:
index The index of the target gpu, >= 0 and < accessibleDevices
device Reference in which to return the device handle
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetHandleByPciBusId ( char *  pciBusId,
nvmlDevice_t *  device 
)

Acquire the handle for a particular device, based on its PCI bus id.

This number corresponds to the value nvmlPciInfo_t -> busId returned by nvmlDeviceGetPciInfo().

Parameters:
pciBusId The PCI bus id of the target gpu
device Reference in which to return the device handle
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetHandleBySerial ( char *  serial,
nvmlDevice_t *  device 
)

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

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

For Fermi-class products only.

Parameters:
serial The board serial number of the target gpu
device Reference in which to return the device handle
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetInforomVersion ( nvmlDevice_t  device,
nvmlInforomObject_t  object,
char *  version,
unsigned int  length 
)

Retrieve the version info for the device's inforom.

For Fermi-class products only.

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. This method retrieves this version info.

See nvmlInforomObject_t for details on the available inforom objects.

Parameters:
device The identifer 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:

nvmlReturn_t DECLDIR nvmlDeviceGetMemoryInfo ( nvmlDevice_t  device,
nvmlMemory_t memory 
)

Retrieve the amount of used, free and total memory available on the device, in bytes.

Enabling ECC reduces the amount of total available memory, due to the extra required parity bits.

The reported amount of used memory is equal to the sum of memory allocated by all active channels on the device.

See nvmlMemory_t for details on available memory info.

Parameters:
device The identifer of the target device
memory Reference in which to return the memory information
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetName ( nvmlDevice_t  device,
char *  name,
unsigned int  length 
)

Retrieve the name of this device.

The name is an alphanumeric string that denotes a particular product, e.g. Tesla C2070. It will not exceed 50 characters in length (including the null terminator).

Parameters:
device The identifer 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:

nvmlReturn_t DECLDIR nvmlDeviceGetPciInfo ( nvmlDevice_t  device,
nvmlPciInfo_t pci 
)

Retrieve the PCI attributes of this device.

See nvmlPciInfo_t for details on the available PCI info.

Parameters:
device The identifer of the target device
pci Reference in which to return the pci info
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetPersistenceMode ( nvmlDevice_t  device,
nvmlEnableState_t mode 
)

Retrieve the persistence mode associated with this device.

Linux Only.

When driver persistence mode is enabled the driver software state is not torn down when the last client disconnects. By default this feature is disabled.

See nvmlEnableState_t for details on allowed modes.

Parameters:
device The identifer of the target device
mode Reference in which to return the current driver persistence mode
Returns:
See also:
nvmlDeviceSetPersistenceMode()

nvmlReturn_t DECLDIR nvmlDeviceGetPowerCappingMode ( nvmlDevice_t  device,
nvmlEnableState_t mode 
)

Retrieve the power capping mode associated with this device.

For "GF11x" Fermi-class products only.

This flag indicates whether any power capping algorithm is currently active on the device. An enabled state does not necessarily mean the device is being actively throttled -- only that that the driver will do so if the appropriate conditions are met.

See nvmlEnableState_t for details on allowed modes.

Parameters:
device The identifer of the target device
mode Reference in which to return the current power capping mode
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetPowerState ( nvmlDevice_t  device,
nvmlPstates_t pState 
)

Retrieve the current power state for the device.

See nvmlPstates_t for details on allowed power states.

Parameters:
device The identifer of the target device
pState Reference in which to return the power state reading
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetPowerUsage ( nvmlDevice_t  device,
unsigned int *  power 
)

Retrieve the power usage reading for the device, in milliwatts.

For Fermi-class products only.

Parameters:
device The identifer of the target device
power Reference in which to return the power usage information
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetSerial ( nvmlDevice_t  device,
char *  serial,
unsigned int  length 
)

Retrieve the globally unique serial number associated with this device.

For Fermi-class products only.

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.

Parameters:
device The identifer 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:

nvmlReturn_t DECLDIR nvmlDeviceGetTemperature ( nvmlDevice_t  device,
nvmlTemperatureSensors_t  sensorType,
unsigned int *  temp 
)

Retrieve the current temperature readings for the device, in degrees F.

See nvmlTemperatureSensors_t for details on available temperature sensors.

Parameters:
device The identifer of the target device
sensorType Flag that indicates which sensor reading to retrieve
temp Reference in which to return the temperature reading
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetTotalEccErrors ( nvmlDevice_t  device,
nvmlEccBitType_t  bitType,
nvmlEccCounterType_t  counterType,
unsigned long long *  eccCounts 
)

Retrieve the total ECC error counts for the device.

For Fermi-class products only.

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 nvmlEccBitType_t for a description of available bit types.
See nvmlEccCounterType_t for a description of available counter types.

Parameters:
device The identifer of the target device
bitType Flag that specifies the bit-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:
See also:
nvmlDeviceClearEccErrorCounts()

nvmlReturn_t DECLDIR nvmlDeviceGetUtilizationRates ( nvmlDevice_t  device,
nvmlUtilization_t utilization 
)

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

See nvmlUtilization_t for details on available utilization rates.

Parameters:
device The identifer of the target device
utilization Reference in which to return the utilization information
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetUUID ( nvmlDevice_t  device,
char *  uuid,
unsigned int  length 
)

Retrieve the UUID associated with this device.

It is an alphanumeric string.

The UUID is a globally unique identifier. It is the only available identifier for pre-Fermi products. It does NOT correspond to the serial number tag typically attached to each board.

Parameters:
device The identifer 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:


Generated on Tue Feb 8 09:10:21 2011