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, as a 5 part hexidecimal string.
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.
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 C.
nvmlReturn_t DECLDIR nvmlDeviceGetPowerState (nvmlDevice_t device, nvmlPstates_t *pState)
 Retrieve the current power state for the device.
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementMode (nvmlDevice_t device, nvmlEnableState_t *mode)
 Retrieve the power management mode associated with this device.
nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementLimit (nvmlDevice_t device, unsigned int *limit)
 Retrieve the power management limit associated with this device, in milliwatts.
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.

For Tesla products, and Quadro products from the Fermi family.

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 in MHz
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetComputeMode ( nvmlDevice_t  device,
nvmlComputeMode_t mode 
)

Retrieve the current compute mode for the device.

For Tesla products, and Quadro products from the Fermi family.

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.

For all products.

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

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

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.

For Tesla products, and Quadro products from the Fermi family.

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.

For Tesla products, and Quadro products from the Fermi family. For windows only.

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

See nvmlDriverModel_t for details on available driver models.

Parameters:
device The 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 Tesla and Quadro products from the Fermi family. Requires NVML_INFOROM_ECC version 1.0 or higher.

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

See nvmlEnableState_t for details on allowed modes.

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

For all discrete products with dedicated fans.

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

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

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 guarentees of consistency between reboots. For that reason it is recommended that devices be looked up 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.

For all products.

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.

For Tesla and Quadro products from the Fermi family.

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

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

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.

For all products.

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

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

See nvmlMemory_t for details on available memory info.

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

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

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.

For all products.

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.

For Tesla products, and Quadro products from the Fermi family. For Linux only.

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

See nvmlEnableState_t for details on allowed modes.

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

nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementLimit ( nvmlDevice_t  device,
unsigned int *  limit 
)

Retrieve the power management limit associated with this device, in milliwatts.

For "GF11x" Tesla and Quadro products from the Fermi family. Requires NVML_INFOROM_POWER version 3.0 or higher.

The power limit defines the upper boundary for the card's power draw. If the card's total power draw reaches this limit the power management algorithm kicks in.

This reading is only available if power management mode is supported. See nvmlDeviceGetPowerManagementMode.

Parameters:
device The identifer of the target device
limit Reference in which to return the power management limit
Returns:

nvmlReturn_t DECLDIR nvmlDeviceGetPowerManagementMode ( nvmlDevice_t  device,
nvmlEnableState_t mode 
)

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

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

See nvmlEnableState_t for details on allowed modes.

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

nvmlReturn_t DECLDIR nvmlDeviceGetPowerState ( nvmlDevice_t  device,
nvmlPstates_t pState 
)

Retrieve the current power state for the device.

For Tesla products, and Quadro products from the Fermi family.

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.

This is the power draw for the entire board, including GPU, memory, etc.

For "GF11x" Tesla and Quadro products from the Fermi family. Requires NVML_INFOROM_POWER version 3.0 or higher.

The reading is accurate to within a range of +/- 5 watts. It is only available if power management mode is supported. See nvmlDeviceGetPowerManagementMode.

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

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

For all discrete and S-class products.

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 Tesla and Quadro products from the Fermi family. Requires NVML_INFOROM_ECC version 1.0 or higher.

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.

For Tesla products, and Quadro products from the Fermi family.

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, as a 5 part hexidecimal string.

For Tesla products, and Quadro products from the Fermi family.

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.

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 Mar 15 21:18:02 2011