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

## 4.9. Unit Queries

This chapter describes that queries that NVML can perform against each unit. For S-class systems only. In each case the device is identified with an nvmlUnit_t handle. This handle is obtained by calling nvmlUnitGetHandleByIndex().

### Functions

nvmlReturn_t nvmlSystemGetHicVersion ( unsigned int* hwbcCount, nvmlHwbcEntry_t* hwbcEntries )
nvmlReturn_t nvmlUnitGetCount ( unsigned int* unitCount )
nvmlReturn_t nvmlUnitGetDevices ( nvmlUnit_t unit, unsigned int* deviceCount, nvmlDevice_t* devices )
nvmlReturn_t nvmlUnitGetFanSpeedInfo ( nvmlUnit_t unit, nvmlUnitFanSpeeds_t* fanSpeeds )
nvmlReturn_t nvmlUnitGetHandleByIndex ( unsigned int index, nvmlUnit_t* unit )
nvmlReturn_t nvmlUnitGetLedState ( nvmlUnit_t unit, nvmlLedState_t* state )
nvmlReturn_t nvmlUnitGetPsuInfo ( nvmlUnit_t unit, nvmlPSUInfo_t* psu )
nvmlReturn_t nvmlUnitGetTemperature ( nvmlUnit_t unit, unsigned int type, unsigned int* temp )
nvmlReturn_t nvmlUnitGetUnitInfo ( nvmlUnit_t unit, nvmlUnitInfo_t* info )

### Functions

nvmlReturn_t nvmlSystemGetHicVersion ( unsigned int* hwbcCount, nvmlHwbcEntry_t* hwbcEntries )

  ###### Parameters

  `hwbcCount`
    Size of hwbcEntries array
  `hwbcEntries`
    Array holding information about hwbc

  ###### Returns

  - NVML_SUCCESS if hwbcCount and hwbcEntries have been populated
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if either hwbcCount or hwbcEntries is NULL
  - NVML_ERROR_INSUFFICIENT_SIZE if hwbcCount indicates that the hwbcEntries array is too small

  ###### Description

  Retrieves the IDs and firmware versions for any Host Interface Cards (HICs) in the system.

  For S-class products.

  The hwbcCount argument is expected to be set to the size of the input hwbcEntries array. The HIC must be connected to an S-class system for it to be reported by this function.

nvmlReturn_t nvmlUnitGetCount ( unsigned int* unitCount )

  ###### Parameters

  `unitCount`
    Reference in which to return the number of units

  ###### Returns

  - NVML_SUCCESS if unitCount has been set
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if unitCount is NULL
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

  Retrieves the number of units in the system.

  For S-class products.

nvmlReturn_t nvmlUnitGetDevices ( nvmlUnit_t unit, unsigned int* deviceCount, nvmlDevice_t* devices )

  ###### Parameters

  `unit`
    The identifier of the target unit
  `deviceCount`
    Reference in which to provide the devices array size, and to return the number of attached GPU devices
  `devices`
    Reference in which to return the references to the attached GPU devices

  ###### Returns

  - NVML_SUCCESS if deviceCount and devices have been populated
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INSUFFICIENT_SIZE if deviceCount indicates that the devices array is too small
  - NVML_ERROR_INVALID_ARGUMENT if unit is invalid, either of deviceCount or devices is NULL
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

  Retrieves the set of GPU devices that are attached to the specified unit.

  For S-class products.

  The deviceCount argument is expected to be set to the size of the input devices array.

nvmlReturn_t nvmlUnitGetFanSpeedInfo ( nvmlUnit_t unit, nvmlUnitFanSpeeds_t* fanSpeeds )

  ###### Parameters

  `unit`
    The identifier of the target unit
  `fanSpeeds`
    Reference in which to return the fan speed information

  ###### Returns

  - NVML_SUCCESS if fanSpeeds has been populated
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if unit is invalid or fanSpeeds is NULL
  - NVML_ERROR_NOT_SUPPORTED if this is not an S-class product
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

  Retrieves the fan speed readings for the unit.

  For S-class products.

  See nvmlUnitFanSpeeds_t for details on available fan speed info.

nvmlReturn_t nvmlUnitGetHandleByIndex ( unsigned int index, nvmlUnit_t* unit )

  ###### Parameters

  `index`
    The index of the target unit, >= 0 and < unitCount
  `unit`
    Reference in which to return the unit handle

  ###### Returns

  - NVML_SUCCESS if unit has been set
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if index is invalid or unit is NULL
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

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

  For S-class products.

  Valid indices are derived from the unitCount returned by nvmlUnitGetCount(). For example, if unitCount is 2 the valid indices are 0 and 1, corresponding to UNIT 0 and UNIT 1.

  The order in which NVML enumerates units has no guarantees of consistency between reboots.

nvmlReturn_t nvmlUnitGetLedState ( nvmlUnit_t unit, nvmlLedState_t* state )

  ###### Parameters

  `unit`
    The identifier of the target unit
  `state`
    Reference in which to return the current LED state

  ###### Returns

  - NVML_SUCCESS if state has been set
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if unit is invalid or state is NULL
  - NVML_ERROR_NOT_SUPPORTED if this is not an S-class product
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

  Retrieves the LED state associated with this unit.

  For S-class products.

  See nvmlLedState_t for details on allowed states.

  See also:

  nvmlUnitSetLedState()

nvmlReturn_t nvmlUnitGetPsuInfo ( nvmlUnit_t unit, nvmlPSUInfo_t* psu )

  ###### Parameters

  `unit`
    The identifier of the target unit
  `psu`
    Reference in which to return the PSU information

  ###### Returns

  - NVML_SUCCESS if psu has been populated
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if unit is invalid or psu is NULL
  - NVML_ERROR_NOT_SUPPORTED if this is not an S-class product
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

  Retrieves the PSU stats for the unit.

  For S-class products.

  See nvmlPSUInfo_t for details on available PSU info.

nvmlReturn_t nvmlUnitGetTemperature ( nvmlUnit_t unit, unsigned int type, unsigned int* temp )

  ###### Parameters

  `unit`
    The identifier of the target unit
  `type`
    The type of reading to take
  `temp`
    Reference in which to return the intake temperature

  ###### Returns

  - NVML_SUCCESS if temp has been populated
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if unit or type is invalid or temp is NULL
  - NVML_ERROR_NOT_SUPPORTED if this is not an S-class product
  - NVML_ERROR_UNKNOWN on any unexpected error

  ###### Description

  Retrieves the temperature readings for the unit, in degrees C.

  For S-class products.

  Depending on the product, readings may be available for intake (type=0), exhaust (type=1) and board (type=2).

nvmlReturn_t nvmlUnitGetUnitInfo ( nvmlUnit_t unit, nvmlUnitInfo_t* info )

  ###### Parameters

  `unit`
    The identifier of the target unit
  `info`
    Reference in which to return the unit information

  ###### Returns

  - NVML_SUCCESS if info has been populated
  - NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
  - NVML_ERROR_INVALID_ARGUMENT if unit is invalid or info is NULL

  ###### Description

  Retrieves the static information associated with a unit.

  For S-class products.

  See nvmlUnitInfo_t for details on available unit info.

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