Is this page helpful?

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

Macros#

nvmlTemperature_v1

Version macro for nvmlTemperature_v1_t .

Functions#

nvmlReturn_t nvmlDeviceGetAPIRestriction(nvmlDevice_t device, nvmlRestrictedAPI_t apiType, nvmlEnableState_t *isRestricted)

Retrieves the root/admin permissions on the target API.

nvmlReturn_t nvmlDeviceGetAdaptiveClockInfoStatus(nvmlDevice_t device, unsigned int *adaptiveClockStatus)

Gets the device's Adaptive Clock status.

nvmlReturn_t nvmlDeviceGetAdaptiveTgpModeInfo_v1(nvmlDevice_t device, nvmlAdaptiveTgpModeInfo_v1_t *info)

Retrieves Adaptive TGP Mode state and telemetry for a GPU.

nvmlReturn_t nvmlDeviceGetApplicationsClock(nvmlDevice_t device, nvmlClockType_t clockType, unsigned int *clockMHz)

nvmlReturn_t nvmlDeviceGetArchitecture(nvmlDevice_t device, nvmlDeviceArchitecture_t *arch)

Get architecture for device.

nvmlReturn_t nvmlDeviceGetAttributes_v2(nvmlDevice_t device, nvmlDeviceAttributes_t *attributes)

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

nvmlReturn_t nvmlDeviceGetAutoBoostedClocksEnabled(nvmlDevice_t device, nvmlEnableState_t *isEnabled, nvmlEnableState_t *defaultIsEnabled)

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

nvmlReturn_t nvmlDeviceGetBAR1MemoryInfo(nvmlDevice_t device, nvmlBAR1Memory_t *bar1Memory)

Gets Total, Available and Used size of BAR1 memory.

nvmlReturn_t nvmlDeviceGetBBXTimeData_v1(nvmlDevice_t device, nvmlBBXTimeData_v1_t *timeData)

Retrieves the cumulative number of seconds the GPU has had the driver loaded.

nvmlReturn_t nvmlDeviceGetBankRemapperStatus_v1(nvmlDevice_t device, nvmlEccBankRemapperStatus_v1_t *pBankRemapperStatus)

Get bank remapper status.

nvmlReturn_t nvmlDeviceGetBoardId(nvmlDevice_t device, unsigned int *boardId)

Retrieves the device boardId from 0-N.

nvmlReturn_t nvmlDeviceGetBoardPartNumber(nvmlDevice_t device, char *partNumber, unsigned int length)

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

nvmlReturn_t nvmlDeviceGetBrand(nvmlDevice_t device, nvmlBrandType_t *type)

Retrieves the brand of this device.

nvmlReturn_t nvmlDeviceGetBridgeChipInfo(nvmlDevice_t device, nvmlBridgeChipHierarchy_t *bridgeHierarchy)

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

nvmlReturn_t nvmlDeviceGetBusType(nvmlDevice_t device, nvmlBusType_t *type)

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

nvmlReturn_t nvmlDeviceGetC2cModeInfoV(nvmlDevice_t device, nvmlC2cModeInfo_v1_t *c2cModeInfo)

Retrieves the Device's C2C Mode information.

nvmlReturn_t nvmlDeviceGetClkMonStatus(nvmlDevice_t device, nvmlClkMonStatus_t *status)

Retrieves the frequency monitor fault status for the device.

nvmlReturn_t nvmlDeviceGetClock(nvmlDevice_t device, nvmlClockType_t clockType, nvmlClockId_t clockId, unsigned int *clockMHz)

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

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

Retrieves the current clock speeds for the device.

nvmlReturn_t nvmlDeviceGetClockOffsets(nvmlDevice_t device, nvmlClockOffset_t *info)

Retrieve min, max and current clock offset of some clock domain for a given PState.

nvmlReturn_t nvmlDeviceGetComputeMode(nvmlDevice_t device, nvmlComputeMode_t *mode)

Retrieves the current compute mode for the device or MIG device.

nvmlReturn_t nvmlDeviceGetComputeRunningProcesses_v3(nvmlDevice_t device, unsigned int *infoCount, nvmlProcessInfo_t *infos)

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

nvmlReturn_t nvmlDeviceGetConfComputeGpuAttestationReport(nvmlDevice_t device, nvmlConfComputeGpuAttestationReport_t *gpuAtstReport)

Get Conf Computing GPU attestation report.

nvmlReturn_t nvmlDeviceGetConfComputeGpuCertificate(nvmlDevice_t device, nvmlConfComputeGpuCertificate_t *gpuCert)

Get Conf Computing GPU certificate details.

nvmlReturn_t nvmlDeviceGetConfComputeMemSizeInfo(nvmlDevice_t device, nvmlConfComputeMemSizeInfo_t *memInfo)

Get Conf Computing Protected and Unprotected Memory Sizes.

nvmlReturn_t nvmlDeviceGetConfComputeProtectedMemoryUsage(nvmlDevice_t device, nvmlMemory_t *memory)

Get Conf Computing protected memory usage.

nvmlReturn_t nvmlDeviceGetCoolerInfo(nvmlDevice_t device, nvmlCoolerInfo_t *coolerInfo)

Retrieves the cooler's information.

nvmlReturn_t nvmlDeviceGetCount_v2(unsigned int *deviceCount)

Retrieves the number of compute devices in the system.

nvmlReturn_t nvmlDeviceGetCudaComputeCapability(nvmlDevice_t device, int *major, int *minor)

Retrieves the CUDA compute capability of the device.

nvmlReturn_t nvmlDeviceGetCurrPcieLinkGeneration(nvmlDevice_t device, unsigned int *currLinkGen)

Retrieves the current PCIe link generation.

nvmlReturn_t nvmlDeviceGetCurrPcieLinkWidth(nvmlDevice_t device, unsigned int *currLinkWidth)

Retrieves the current PCIe link width.

nvmlReturn_t nvmlDeviceGetCurrentClockFreqs(nvmlDevice_t device, nvmlDeviceCurrentClockFreqs_t *currentClockFreqs)

Retrieves a string with the associated current GPU Clock and Memory Clock values.

nvmlReturn_t nvmlDeviceGetCurrentClocksEventReasons(nvmlDevice_t device, unsigned long long *clocksEventReasons)

Retrieves current clocks event reasons.

nvmlReturn_t nvmlDeviceGetCurrentClocksThrottleReasons(nvmlDevice_t device, unsigned long long *clocksThrottleReasons)

nvmlReturn_t nvmlDeviceGetDecoderUtilization(nvmlDevice_t device, unsigned int *utilization, unsigned int *samplingPeriodUs)

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

nvmlReturn_t nvmlDeviceGetDefaultApplicationsClock(nvmlDevice_t device, nvmlClockType_t clockType, unsigned int *clockMHz)

nvmlReturn_t nvmlDeviceGetDefaultEccMode(nvmlDevice_t device, nvmlEnableState_t *defaultMode)

Retrieves the default ECC modes for the device.

nvmlReturn_t nvmlDeviceGetDetailedEccErrors(nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, nvmlEccErrorCounts_t *eccCounts)

Retrieves the detailed ECC error counts for the device.

nvmlReturn_t nvmlDeviceGetDisplayActive(nvmlDevice_t device, nvmlEnableState_t *isActive)

Retrieves the display active state for the device.

nvmlReturn_t nvmlDeviceGetDisplayMode(nvmlDevice_t device, nvmlEnableState_t *display)

Retrieves the display mode for the device.

nvmlReturn_t nvmlDeviceGetDramEncryptionMode(nvmlDevice_t device, nvmlDramEncryptionInfo_t *current, nvmlDramEncryptionInfo_t *pending)

Retrieves the current and pending DRAM Encryption modes for the device.

nvmlReturn_t nvmlDeviceGetDriverModel_v2(nvmlDevice_t device, nvmlDriverModel_t *current, nvmlDriverModel_t *pending)

Retrieves the current and pending driver model for the device.

nvmlReturn_t nvmlDeviceGetDynamicPstatesInfo(nvmlDevice_t device, nvmlGpuDynamicPstatesInfo_t *pDynamicPstatesInfo)

Retrieve performance monitor samples from the associated subdevice.

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

Retrieves the current and pending ECC modes for the device.

nvmlReturn_t nvmlDeviceGetEncoderCapacity(nvmlDevice_t device, nvmlEncoderType_t encoderQueryType, unsigned int *encoderCapacity)

Retrieves the current capacity of the device's encoder, as a percentage of maximum encoder capacity with valid values in the range 0-100.

nvmlReturn_t nvmlDeviceGetEncoderSessions(nvmlDevice_t device, unsigned int *sessionCount, nvmlEncoderSessionInfo_t *sessionInfos)

Retrieves information about active encoder sessions on a target device.

nvmlReturn_t nvmlDeviceGetEncoderStats(nvmlDevice_t device, unsigned int *sessionCount, unsigned int *averageFps, unsigned int *averageLatency)

Retrieves the current encoder statistics for a given device.

nvmlReturn_t nvmlDeviceGetEncoderUtilization(nvmlDevice_t device, unsigned int *utilization, unsigned int *samplingPeriodUs)

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

nvmlReturn_t nvmlDeviceGetEnforcedPowerLimit(nvmlDevice_t device, unsigned int *limit)

Get the effective power limit that the driver enforces after taking into account all limiters.

nvmlReturn_t nvmlDeviceGetFBCSessions(nvmlDevice_t device, unsigned int *sessionCount, nvmlFBCSessionInfo_t *sessionInfo)

Retrieves information about active frame buffer capture sessions on a target device.

nvmlReturn_t nvmlDeviceGetFBCStats(nvmlDevice_t device, nvmlFBCStats_t *fbcStats)

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

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

Gets current fan control policy.

nvmlReturn_t nvmlDeviceGetFanSpeed(nvmlDevice_t device, unsigned int *speed)

Retrieves the intended operating speed of the device's fan.

nvmlReturn_t nvmlDeviceGetFanSpeedRPM(nvmlDevice_t device, nvmlFanSpeedInfo_t *fanSpeed)

Retrieves the intended operating speed in rotations per minute (RPM) of the device's specified fan.

nvmlReturn_t nvmlDeviceGetFanSpeed_v2(nvmlDevice_t device, unsigned int fan, unsigned int *speed)

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

nvmlReturn_t nvmlDeviceGetGpcClkMinMaxVfOffset(nvmlDevice_t device, int *minOffset, int *maxOffset)

Retrieve the GPCCLK min max VF offset value.

nvmlReturn_t nvmlDeviceGetGpcClkVfOffset(nvmlDevice_t device, int *offset)

Retrieve the GPCCLK VF offset value.

nvmlReturn_t nvmlDeviceGetGpuFabricInfo(nvmlDevice_t device, nvmlGpuFabricInfo_t *gpuFabricInfo)

nvmlReturn_t nvmlDeviceGetGpuFabricInfoV(nvmlDevice_t device, nvmlGpuFabricInfoV_t *gpuFabricInfo)

Versioned wrapper around nvmlDeviceGetGpuFabricInfo that accepts a versioned nvmlGpuFabricInfo_v2_t or later output structure.

nvmlReturn_t nvmlDeviceGetGpuFabricInfo_v4(nvmlDevice_t device, nvmlGpuFabricInfo_v4_t *gpuFabricInfo)

Retrieves GPU fabric information including per-type clique assignments.

nvmlReturn_t nvmlDeviceGetGpuMaxPcieLinkGeneration(nvmlDevice_t device, unsigned int *maxLinkGenDevice)

Retrieves the maximum PCIe link generation supported by this device.

nvmlReturn_t nvmlDeviceGetGpuOperationMode(nvmlDevice_t device, nvmlGpuOperationMode_t *current, nvmlGpuOperationMode_t *pending)

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

nvmlReturn_t nvmlDeviceGetGraphicsRunningProcesses_v3(nvmlDevice_t device, unsigned int *infoCount, nvmlProcessInfo_t *infos)

Get information about processes with a graphics context on a device.

nvmlReturn_t nvmlDeviceGetGspFirmwareMode(nvmlDevice_t device, unsigned int *isEnabled, unsigned int *defaultMode)

Retrieve GSP firmware mode.

nvmlReturn_t nvmlDeviceGetGspFirmwareVersion(nvmlDevice_t device, char *version)

Retrieve GSP firmware version.

nvmlReturn_t nvmlDeviceGetHandleByIndex_v2(unsigned int index, nvmlDevice_t *device)

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

nvmlReturn_t nvmlDeviceGetHandleByPciBusId_v2(const char *pciBusId, nvmlDevice_t *device)

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

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

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

nvmlReturn_t nvmlDeviceGetHandleByUUID(const char *uuid, nvmlDevice_t *device)

Acquire the handle for a particular device, based on its globally unique immutable UUID (in ASCII format) associated with each device.

nvmlReturn_t nvmlDeviceGetHandleByUUIDV(const nvmlUUID_t *uuid, nvmlDevice_t *device)

Acquire the handle for a particular device, based on its globally unique immutable UUID (in either ASCII or binary format) associated with each device.

nvmlReturn_t nvmlDeviceGetHostname_v1(nvmlDevice_t device, nvmlHostname_v1_t *hostname)

Get the hostname for the device.

nvmlReturn_t nvmlDeviceGetIndex(nvmlDevice_t device, unsigned int *index)

Retrieves the NVML index of this device.

nvmlReturn_t nvmlDeviceGetInforomConfigurationChecksum(nvmlDevice_t device, unsigned int *checksum)

Retrieves the checksum of the configuration stored in the device's infoROM.

nvmlReturn_t nvmlDeviceGetInforomImageVersion(nvmlDevice_t device, char *version, unsigned int length)

Retrieves the global infoROM image version.

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

Retrieves the version information for the device's infoROM object.

nvmlReturn_t nvmlDeviceGetIrqNum(nvmlDevice_t device, unsigned int *irqNum)

Gets the device's interrupt number.

nvmlReturn_t nvmlDeviceGetJpgUtilization(nvmlDevice_t device, unsigned int *utilization, unsigned int *samplingPeriodUs)

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

nvmlReturn_t nvmlDeviceGetLastBBXFlushTime(nvmlDevice_t device, unsigned long long *timestamp, unsigned long *durationUs)

Retrieves the timestamp and the duration of the last flush of the BBX (blackbox) infoROM object during the current run.

nvmlReturn_t nvmlDeviceGetMPSComputeRunningProcesses_v3(nvmlDevice_t device, unsigned int *infoCount, nvmlProcessInfo_t *infos)

Get information about processes with a Multi-Process Service (MPS) compute context on a device.

nvmlReturn_t nvmlDeviceGetMarginTemperature(nvmlDevice_t device, nvmlMarginTemperature_t *marginTempInfo)

Retrieves the thermal margin temperature (distance to nearest slowdown threshold).

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

Retrieves the maximum clock speeds for the device.

nvmlReturn_t nvmlDeviceGetMaxCustomerBoostClock(nvmlDevice_t device, nvmlClockType_t clockType, unsigned int *clockMHz)

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

nvmlReturn_t nvmlDeviceGetMaxPcieLinkGeneration(nvmlDevice_t device, unsigned int *maxLinkGen)

Retrieves the maximum PCIe link generation possible with this device and system.

nvmlReturn_t nvmlDeviceGetMaxPcieLinkWidth(nvmlDevice_t device, unsigned int *maxLinkWidth)

Retrieves the maximum PCIe link width possible with this device and system.

nvmlReturn_t nvmlDeviceGetMemClkMinMaxVfOffset(nvmlDevice_t device, int *minOffset, int *maxOffset)

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

nvmlReturn_t nvmlDeviceGetMemClkVfOffset(nvmlDevice_t device, int *offset)

Retrieve the MemClk (Memory Clock) VF offset value.

nvmlReturn_t nvmlDeviceGetMemoryBusWidth(nvmlDevice_t device, unsigned int *busWidth)

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)

Retrieves the requested memory error counter for the device.

nvmlReturn_t nvmlDeviceGetMemoryInfo(nvmlDevice_t device, nvmlMemory_t *memory)

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

nvmlReturn_t nvmlDeviceGetMemoryInfo_v2(nvmlDevice_t device, nvmlMemory_v2_t *memory)

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

nvmlReturn_t nvmlDeviceGetMemoryLimits_v1(nvmlDevice_t device, nvmlGetMemoryLimits_v1_t *limits)

Get the memory limits of the device for the cgroup partition.

nvmlReturn_t nvmlDeviceGetMinMaxClockOfPState(nvmlDevice_t device, nvmlClockType_t type, nvmlPstates_t pstate, unsigned int *minClockMHz, unsigned int *maxClockMHz)

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)

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

nvmlReturn_t nvmlDeviceGetMinorNumber(nvmlDevice_t device, unsigned int *minorNumber)

Retrieves minor number for the device.

nvmlReturn_t nvmlDeviceGetModuleId(nvmlDevice_t device, unsigned int *moduleId)

Get a unique identifier for the device module on the baseboard.

nvmlReturn_t nvmlDeviceGetMultiGpuBoard(nvmlDevice_t device, unsigned int *multiGpuBool)

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.

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

Retrieves the name of this device.

nvmlReturn_t nvmlDeviceGetNumFans(nvmlDevice_t device, unsigned int *numFans)

Retrieves the number of fans on the device.

nvmlReturn_t nvmlDeviceGetNumGpuCores(nvmlDevice_t device, unsigned int *numCores)

Gets the device's core count.

nvmlReturn_t nvmlDeviceGetOfaUtilization(nvmlDevice_t device, unsigned int *utilization, unsigned int *samplingPeriodUs)

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

nvmlReturn_t nvmlDeviceGetP2PStatus(nvmlDevice_t device1, nvmlDevice_t device2, nvmlGpuP2PCapsIndex_t p2pIndex, nvmlGpuP2PStatus_t *p2pStatus)

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

nvmlReturn_t nvmlDeviceGetPciInfoExt(nvmlDevice_t device, nvmlPciInfoExt_t *pci)

Retrieves PCI attributes of this device.

nvmlReturn_t nvmlDeviceGetPciInfo_v3(nvmlDevice_t device, nvmlPciInfo_t *pci)

Retrieves the PCI attributes of this device.

nvmlReturn_t nvmlDeviceGetPcieLinkMaxSpeed(nvmlDevice_t device, unsigned int *maxSpeed)

Gets the device's PCIE Max Link speed in MBPS.

nvmlReturn_t nvmlDeviceGetPcieReplayCounter(nvmlDevice_t device, unsigned int *value)

Retrieve the PCIe replay counter.

nvmlReturn_t nvmlDeviceGetPcieSpeed(nvmlDevice_t device, unsigned int *pcieSpeed)

Gets the device's PCIe Link speed in Mbps.

nvmlReturn_t nvmlDeviceGetPcieThroughput(nvmlDevice_t device, nvmlPcieUtilCounter_t counter, unsigned int *value)

Retrieve PCIe utilization information.

nvmlReturn_t nvmlDeviceGetPdi(nvmlDevice_t device, nvmlPdi_t *pdi)

Retrieves the Per Device Identifier (PDI) associated with this device.

nvmlReturn_t nvmlDeviceGetPerformanceModes(nvmlDevice_t device, nvmlDevicePerfModes_t *perfModes)

Retrieves a performance mode string with all the performance modes defined for this device along with their associated GPU Clock and Memory Clock values.

nvmlReturn_t nvmlDeviceGetPerformanceState(nvmlDevice_t device, nvmlPstates_t *pState)

Retrieves the current performance state for the device.

nvmlReturn_t nvmlDeviceGetPersistenceMode(nvmlDevice_t device, nvmlEnableState_t *mode)

Retrieves the persistence mode associated with this device.

nvmlReturn_t nvmlDeviceGetPlatformInfo(nvmlDevice_t device, nvmlPlatformInfo_t *platformInfo)

Get platform information of this device.

nvmlReturn_t nvmlDeviceGetPowerManagementDefaultLimit(nvmlDevice_t device, unsigned int *defaultLimit)

Retrieves default power management limit on this device, in milliwatts.

nvmlReturn_t nvmlDeviceGetPowerManagementLimit(nvmlDevice_t device, unsigned int *limit)

Retrieves the power management limit associated with this device.

nvmlReturn_t nvmlDeviceGetPowerManagementLimitConstraints(nvmlDevice_t device, unsigned int *minLimit, unsigned int *maxLimit)

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

nvmlReturn_t nvmlDeviceGetPowerManagementMode(nvmlDevice_t device, nvmlEnableState_t *mode)

nvmlReturn_t nvmlDeviceGetPowerMizerMode_v1(nvmlDevice_t device, nvmlDevicePowerMizerModes_v1_t *powerMizerMode)

Retrieves current power mizer mode on this device.

nvmlReturn_t nvmlDeviceGetPowerSource(nvmlDevice_t device, nvmlPowerSource_t *powerSource)

Gets the devices power source.

nvmlReturn_t nvmlDeviceGetPowerState(nvmlDevice_t device, nvmlPstates_t *pState)

nvmlReturn_t nvmlDeviceGetPowerUsage(nvmlDevice_t device, unsigned int *power)

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

nvmlReturn_t nvmlDeviceGetProcessUtilization(nvmlDevice_t device, nvmlProcessUtilizationSample_t *utilization, unsigned int *processSamplesCount, unsigned long long lastSeenTimeStamp)

Retrieves the current utilization and process ID.

nvmlReturn_t nvmlDeviceGetProcessesUtilizationInfo(nvmlDevice_t device, nvmlProcessesUtilizationInfo_t *procesesUtilInfo)

Retrieves the recent utilization and process ID for all running processes.

nvmlReturn_t nvmlDeviceGetRemappedRows(nvmlDevice_t device, unsigned int *corrRows, unsigned int *uncRows, unsigned int *isPending, unsigned int *failureOccurred)

Get number of remapped rows.

nvmlReturn_t nvmlDeviceGetRemappedRows_v2(nvmlDevice_t device, nvmlRemappedRowsInfo_v2_t *info)

Get the status of row remapper.

nvmlReturn_t nvmlDeviceGetRetiredPages(nvmlDevice_t device, nvmlPageRetirementCause_t cause, unsigned int *pageCount, unsigned long long *addresses)

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.

nvmlReturn_t nvmlDeviceGetRetiredPagesPendingStatus(nvmlDevice_t device, nvmlEnableState_t *isPending)

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

nvmlReturn_t nvmlDeviceGetRetiredPages_v2(nvmlDevice_t device, nvmlPageRetirementCause_t cause, unsigned int *pageCount, unsigned long long *addresses, unsigned long long *timestamps)

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.

nvmlReturn_t nvmlDeviceGetRowRemapperHistogram(nvmlDevice_t device, nvmlRowRemapperHistogramValues_t *values)

Get the row remapper histogram.

nvmlReturn_t nvmlDeviceGetRunningProcessDetailList(nvmlDevice_t device, nvmlProcessDetailList_t *plist)

Get information about running processes on a device for input context.

nvmlReturn_t nvmlDeviceGetSamples(nvmlDevice_t device, nvmlSamplingType_t type, unsigned long long lastSeenTimeStamp, nvmlValueType_t *sampleValType, unsigned int *sampleCount, nvmlSample_t *samples)

Gets recent samples for the GPU.

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

Retrieves the globally unique board serial number associated with this device's board.

nvmlReturn_t nvmlDeviceGetSramEccErrorStatus(nvmlDevice_t device, nvmlEccSramErrorStatus_t *status)

Get SRAM ECC error status of this device.

nvmlReturn_t nvmlDeviceGetSramUniqueUncorrectedEccErrorCounts(nvmlDevice_t device, nvmlEccSramUniqueUncorrectedErrorCounts_t *errorCounts)

Retrieves the counts of SRAM unique uncorrected ECC errors.

nvmlReturn_t nvmlDeviceGetSupportedClocksEventReasons(nvmlDevice_t device, unsigned long long *supportedClocksEventReasons)

Retrieves bitmask of supported clocks event reasons that can be returned by 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)

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

nvmlReturn_t nvmlDeviceGetSupportedMemoryClocks(nvmlDevice_t device, unsigned int *count, unsigned int *clocksMHz)

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

nvmlReturn_t nvmlDeviceGetSupportedPerformanceStates(nvmlDevice_t device, nvmlPstates_t *pstates, unsigned int size)

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

nvmlReturn_t nvmlDeviceGetTargetFanSpeed(nvmlDevice_t device, unsigned int fan, unsigned int *targetSpeed)

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

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

nvmlReturn_t nvmlDeviceGetTemperatureThreshold(nvmlDevice_t device, nvmlTemperatureThresholds_t thresholdType, unsigned int *temp)

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

nvmlReturn_t nvmlDeviceGetTemperatureV(nvmlDevice_t device, nvmlTemperature_t *temperature)

Retrieves the current temperature readings (in degrees C) for the given device.

nvmlReturn_t nvmlDeviceGetThermalSettings(nvmlDevice_t device, unsigned int sensorIndex, nvmlGpuThermalSettings_t *pThermalSettings)

Used to execute a list of thermal system instructions.

nvmlReturn_t nvmlDeviceGetTopologyCommonAncestor(nvmlDevice_t device1, nvmlDevice_t device2, nvmlGpuTopologyLevel_t *pathInfo)

Retrieve the common ancestor for two devices For all products.

nvmlReturn_t nvmlDeviceGetTopologyNearestGpus(nvmlDevice_t device, nvmlGpuTopologyLevel_t level, unsigned int *count, nvmlDevice_t *deviceArray)

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

nvmlReturn_t nvmlDeviceGetTotalEccErrors(nvmlDevice_t device, nvmlMemoryErrorType_t errorType, nvmlEccCounterType_t counterType, unsigned long long *eccCounts)

Retrieves the total ECC error counts for the device.

nvmlReturn_t nvmlDeviceGetTotalEnergyConsumption(nvmlDevice_t device, unsigned long long *energy)

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

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

Retrieves the globally unique immutable UUID associated with this device, as a 5 part hexadecimal string, that augments the immutable, board serial identifier.

nvmlReturn_t nvmlDeviceGetUtilizationRates(nvmlDevice_t device, nvmlUtilization_t *utilization)

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

nvmlReturn_t nvmlDeviceGetVbiosVersion(nvmlDevice_t device, char *version, unsigned int length)

Get VBIOS version of the device.

nvmlReturn_t nvmlDeviceGetViolationStatus(nvmlDevice_t device, nvmlPerfPolicyType_t perfPolicyType, nvmlViolationTime_t *violTime)

nvmlReturn_t nvmlDeviceOnSameBoard(nvmlDevice_t device1, nvmlDevice_t device2, int *onSameBoard)

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

nvmlReturn_t nvmlDevicePerfMetricsGetSamples_v1(nvmlDevice_t device, nvmlPerfMetricsSamples_v1_t *samples)

Get Performance Metric samples.

nvmlReturn_t nvmlDeviceSetAdaptiveTgpMode_v1(nvmlDevice_t device, nvmlEnableState_t mode)

Request to enable or disable Adaptive TGP Mode for a GPU.

nvmlReturn_t nvmlDeviceSetClockOffsets(nvmlDevice_t device, nvmlClockOffset_t *info)

Control current clock offset of some clock domain for a given PState.

nvmlReturn_t nvmlDeviceSetConfComputeUnprotectedMemSize(nvmlDevice_t device, unsigned long long sizeKiB)

Set Conf Computing Unprotected Memory Size.

nvmlReturn_t nvmlDeviceSetDramEncryptionMode(nvmlDevice_t device, const nvmlDramEncryptionInfo_t *dramEncryption)

Set the DRAM Encryption mode for the device.

nvmlReturn_t nvmlDeviceSetHostname_v1(nvmlDevice_t device, nvmlHostname_v1_t *hostname)

Set the hostname for the device.

nvmlReturn_t nvmlDeviceSetMemoryLimits_v1(nvmlDevice_t device, nvmlSetMemoryLimits_v1_t *limits)

Set the memory limits of the device for the cgroup partition.

nvmlReturn_t nvmlDeviceSetPowerManagementLimit_v2(nvmlDevice_t device, nvmlPowerValue_v2_t *powerValue)

Set new power limit of this device.

nvmlReturn_t nvmlDeviceSetPowerMizerMode_v1(nvmlDevice_t device, nvmlDevicePowerMizerModes_v1_t *powerMizerMode)

Sets the new power mizer mode.

nvmlReturn_t nvmlDeviceValidateInforom(nvmlDevice_t device)

Reads the infoROM from the flash and verifies the checksums.

nvmlReturn_t nvmlSystemGetConfComputeCapabilities(nvmlConfComputeSystemCaps_t *capabilities)

Get Conf Computing System capabilities.

nvmlReturn_t nvmlSystemGetConfComputeGpusReadyState(unsigned int *isAcceptingWork)

Get Conf Computing GPUs ready state.

nvmlReturn_t nvmlSystemGetConfComputeKeyRotationThresholdInfo(nvmlConfComputeGetKeyRotationThresholdInfo_t *pKeyRotationThrInfo)

Get Conf Computing key rotation threshold detail.

nvmlReturn_t nvmlSystemGetConfComputeSettings(nvmlSystemConfComputeSettings_t *settings)

Get Conf Computing System Settings.

nvmlReturn_t nvmlSystemGetConfComputeState(nvmlConfComputeSystemState_t *state)

Get Conf Computing System State.

nvmlReturn_t nvmlSystemSetConfComputeGpusReadyState(unsigned int isAcceptingWork)

Set Conf Computing GPUs ready state.

nvmlReturn_t nvmlSystemSetConfComputeKeyRotationThresholdInfo(nvmlConfComputeSetKeyRotationThresholdInfo_t *pKeyRotationThrInfo)

Set Conf Computing key rotation threshold.

Groups#

CPU and Memory Affinity

This chapter describes NVML operations that are associated with CPU and memory affinity.

Structs#

nvmlEccBankRemapperHistogram_v1_t

Structure to store bank remapper histogram.

nvmlEccBankRemapperStatus_v1_t

Structure to store bank remapper status.

nvmlTemperature_v1_t

Structure used to encapsulate temperature info.

Typedefs#

nvmlTemperature_t

Macros#

nvmlTemperature_v1#

Version macro for nvmlTemperature_v1_t.

Functions#

nvmlReturn_t nvmlDeviceGetAPIRestriction(
nvmlDevice_t device,
nvmlRestrictedAPI_t apiType,
nvmlEnableState_t *isRestricted,
)#

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

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:

nvmlReturn_t nvmlDeviceGetAdaptiveClockInfoStatus(
nvmlDevice_t device,
unsigned int *adaptiveClockStatus,
)#

Gets the device’s Adaptive Clock status.

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:

nvmlReturn_t nvmlDeviceGetAdaptiveTgpModeInfo_v1(
nvmlDevice_t device,
nvmlAdaptiveTgpModeInfo_v1_t *info,
)#

Retrieves Adaptive TGP Mode state and telemetry for a GPU.

RUBIN_OR_NEWER%

Populates info with the in-band request, out-of-band enablement status, out-of-band override status, arbitrated enablement state, and adjusted base power limit. The adjusted base power is valid only when feature is enabled. See nvmlAdaptiveTgpModeInfo_v1_t for field details.

See also

nvmlDeviceSetAdaptiveTgpMode_v1()

Parameters:

  • device – The identifier of the target device

  • info – Reference in which to return the Adaptive TGP Mode information

Returns:

nvmlReturn_t nvmlDeviceGetApplicationsClock(
nvmlDevice_t device,
nvmlClockType_t clockType,
unsigned int *clockMHz,
)#

Deprecated:

Applications clocks are deprecated and will be removed in CUDA 14.0.

nvmlReturn_t nvmlDeviceGetArchitecture(
nvmlDevice_t device,
nvmlDeviceArchitecture_t *arch,
)#

Get architecture for device.

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:

nvmlReturn_t nvmlDeviceGetAttributes_v2(
nvmlDevice_t device,
nvmlDeviceAttributes_t *attributes,
)#

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

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

Note

This API currently only supports MIG device handles.

Parameters:

  • device – NVML device handle

  • attributes – Device attributes

Returns:

nvmlReturn_t nvmlDeviceGetAutoBoostedClocksEnabled(
nvmlDevice_t device,
nvmlEnableState_t *isEnabled,
nvmlEnableState_t *defaultIsEnabled,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetBAR1MemoryInfo(
nvmlDevice_t device,
nvmlBAR1Memory_t *bar1Memory,
)#

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

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.

Parameters:

  • device – The identifier of the target device

  • bar1Memory – Reference in which BAR1 memory information is returned.

Returns:

nvmlReturn_t nvmlDeviceGetBBXTimeData_v1(
nvmlDevice_t device,
nvmlBBXTimeData_v1_t *timeData,
)#

Retrieves the cumulative number of seconds the GPU has had the driver loaded.

For all products with an inforom.

Parameters:

  • device – The identifier of the target device

  • timeData – Reference in which to return the cumulative number of seconds the GPU has had the driver loaded

Returns:

nvmlReturn_t nvmlDeviceGetBankRemapperStatus_v1(
nvmlDevice_t device,
nvmlEccBankRemapperStatus_v1_t *pBankRemapperStatus,
)#

Get bank remapper status.

RUBIN_OR_NEWER%

Parameters:

  • device – The identifier of the target device

  • pBankRemapperStatus – Reference to nvmlEccBankRemapperStatus_t

Returns:

nvmlReturn_t nvmlDeviceGetBoardId(
nvmlDevice_t device,
unsigned int *boardId,
)#

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.

Parameters:

  • device – The identifier of the target device

  • boardId – Reference in which to return the device’s board ID

Returns:

nvmlReturn_t nvmlDeviceGetBoardPartNumber(
nvmlDevice_t device,
char *partNumber,
unsigned int length,
)#

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

For all products.

Parameters:

  • device – Identifier of the target device

  • partNumber – Reference to the buffer to return

  • length – Length of the buffer reference

Returns:

nvmlReturn_t nvmlDeviceGetBrand(
nvmlDevice_t device,
nvmlBrandType_t *type,
)#

Retrieves the brand of this device.

For all products.

The type is a member of nvmlBrandType_t defined above.

Parameters:

  • device – The identifier of the target device

  • type – Reference in which to return the product brand type

Returns:

nvmlReturn_t nvmlDeviceGetBridgeChipInfo(
nvmlDevice_t device,
nvmlBridgeChipHierarchy_t *bridgeHierarchy,
)#

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

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

Parameters:

  • device – The identifier of the target device

  • bridgeHierarchy – Reference to the returned bridge chip Hierarchy

Returns:

nvmlReturn_t nvmlDeviceGetBusType(
nvmlDevice_t device,
nvmlBusType_t *type,
)#

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

return

Parameters:

  • device – The identifier of the target device

  • type – The PCI Bus type

nvmlReturn_t nvmlDeviceGetC2cModeInfoV(
nvmlDevice_t device,
nvmlC2cModeInfo_v1_t *c2cModeInfo,
)#

Retrieves the Device’s C2C Mode information.

Parameters:

  • device – The identifier of the target device

  • c2cModeInfo – Output struct containing the device’s C2C Mode info

Returns:

nvmlReturn_t nvmlDeviceGetClkMonStatus(
nvmlDevice_t device,
nvmlClkMonStatus_t *status,
)#

Retrieves the frequency monitor fault status for the device.

For Ampere or newer fully supported devices. Requires root user.

See nvmlClkMonStatus_t for details on decoding the status output.

See also

nvmlDeviceGetClkMonStatus()

Parameters:

  • device – The identifier of the target device

  • status – Reference in which to return the clkmon fault status

Returns:

nvmlReturn_t nvmlDeviceGetClock(
nvmlDevice_t device,
nvmlClockType_t clockType,
nvmlClockId_t clockId,
unsigned int *clockMHz,
)#

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

For Kepler or newer fully supported devices.

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:

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

Retrieves the current clock speeds for the device.

For Fermi or newer fully supported devices.

See nvmlClockType_t for details on available clock information.

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:

nvmlReturn_t nvmlDeviceGetClockOffsets(
nvmlDevice_t device,
nvmlClockOffset_t *info,
)#

Retrieve min, max and current clock offset of some clock domain for a given PState.

For Maxwell or newer fully supported devices.

Note: nvmlDeviceGetGpcClkVfOffset, nvmlDeviceGetMemClkVfOffset, nvmlDeviceGetGpcClkMinMaxVfOffset and nvmlDeviceGetMemClkMinMaxVfOffset will be deprecated in a future release. Use nvmlDeviceGetClockOffsets instead.

Parameters:

  • device – The identifier of the target device

  • info – Structure specifying the clock type (input) and the pstate (input) retrieved clock offset value (output), min clock offset (output) and max clock offset (output)

Returns:

nvmlReturn_t nvmlDeviceGetComputeMode(
nvmlDevice_t device,
nvmlComputeMode_t *mode,
)#

Retrieves the current compute mode for the device or MIG device.

For all products.

See nvmlComputeMode_t for details on allowed compute modes.

See also

nvmlDeviceSetComputeMode()

Note

If MIG is enabled on a GPU, device must be MIG device handle.

Parameters:

  • device – The identifier of the target device handle or MIG device handle

  • mode – Reference in which to return the current compute mode

Returns:

nvmlReturn_t nvmlDeviceGetComputeRunningProcesses_v3(
nvmlDevice_t device,
unsigned int *infoCount,
nvmlProcessInfo_t *infos,
)#

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.

See also

nvmlSystemGetProcessName

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.

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:

nvmlReturn_t nvmlDeviceGetConfComputeGpuAttestationReport(
nvmlDevice_t device,
nvmlConfComputeGpuAttestationReport_t *gpuAtstReport,
)#

Get Conf Computing GPU attestation report.

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

Parameters:

  • device – The identifier of the target device

  • gpuAtstReport – Reference in which to return the gpu attestation report

Returns:

nvmlReturn_t nvmlDeviceGetConfComputeGpuCertificate(
nvmlDevice_t device,
nvmlConfComputeGpuCertificate_t *gpuCert,
)#

Get Conf Computing GPU certificate details.

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

Parameters:

  • device – The identifier of the target device

  • gpuCert – Reference in which to return the gpu certificate information

Returns:

nvmlReturn_t nvmlDeviceGetConfComputeMemSizeInfo(
nvmlDevice_t device,
nvmlConfComputeMemSizeInfo_t *memInfo,
)#

Get Conf Computing Protected and Unprotected Memory Sizes.

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

Parameters:

  • device – Device handle

  • memInfo – Protected/Unprotected Memory sizes

Returns:

nvmlReturn_t nvmlDeviceGetConfComputeProtectedMemoryUsage(
nvmlDevice_t device,
nvmlMemory_t *memory,
)#

Get Conf Computing protected memory usage.

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

Parameters:

  • device – The identifier of the target device

  • memory – Reference in which to return the memory information

Returns:

nvmlReturn_t nvmlDeviceGetCoolerInfo(
nvmlDevice_t device,
nvmlCoolerInfo_t *coolerInfo,
)#

Retrieves the cooler’s information.

Returns a cooler’s control signal characteristics. The possible types are restricted, Variable and Toggle. See nvmlCoolerControl_t for details on available signal types. Returns objects that cooler cools. Targets may be GPU, Memory, Power Supply or All of these. See nvmlCoolerTarget_t for details on available targets.

For Maxwell or newer fully supported devices.

For all discrete products with dedicated fans.

Parameters:

  • device – [in] The identifier of the target device

  • coolerInfo – [out] Structure specifying the cooler’s control signal characteristics (out) and the target that cooler cools (out)

Returns:

nvmlReturn_t nvmlDeviceGetCount_v2(unsigned int *deviceCount)#

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.

Parameters:

deviceCount – Reference in which to return the number of accessible devices

Returns:

nvmlReturn_t nvmlDeviceGetCudaComputeCapability(
nvmlDevice_t device,
int *major,
int *minor,
)#

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

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:

nvmlReturn_t nvmlDeviceGetCurrPcieLinkGeneration(
nvmlDevice_t device,
unsigned int *currLinkGen,
)#

Retrieves the current PCIe link generation.

For Fermi or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • currLinkGen – Reference in which to return the current PCIe link generation

Returns:

nvmlReturn_t nvmlDeviceGetCurrPcieLinkWidth(
nvmlDevice_t device,
unsigned int *currLinkWidth,
)#

Retrieves the current PCIe link width.

For Fermi or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • currLinkWidth – Reference in which to return the current PCIe link generation

Returns:

nvmlReturn_t nvmlDeviceGetCurrentClockFreqs(
nvmlDevice_t device,
nvmlDeviceCurrentClockFreqs_t *currentClockFreqs,
)#

Retrieves a string with the associated current GPU Clock and Memory Clock values.

Not all tokens will be reported on all GPUs, and additional tokens may be added in the future.

Note: These clock values take into account the offset set by clients through /ref nvmlDeviceSetClockOffsets.

Clock values are returned as a comma-separated list of “token=value” pairs. Valid tokens:

Token Value “perf” unsigned int - the Performance level “nvclock” unsigned int - the GPU clocks (in MHz) for the perf level “nvclockmin” unsigned int - the GPU clocks min (in MHz) for the perf level “nvclockmax” unsigned int - the GPU clocks max (in MHz) for the perf level “nvclockeditable” unsigned int - if the GPU clock domain is editable for the perf level “memclock” unsigned int - the memory clocks (in MHz) for the perf level “memclockmin” unsigned int - the memory clocks min (in MHz) for the perf level “memclockmax” unsigned int - the memory clocks max (in MHz) for the perf level “memclockeditable” unsigned int - if the memory clock domain is editable for the perf level “memtransferrate” unsigned int - the memory transfer rate (in MHz) for the perf level “memtransferratemin” unsigned int - the memory transfer rate min (in MHz) for the perf level “memtransferratemax” unsigned int - the memory transfer rate max (in MHz) for the perf level “memtransferrateeditable” unsigned int - if the memory transfer rate is editable for the perf level

Example:

nvclock=324, nvclockmin=324, nvclockmax=324, nvclockeditable=0, memclock=324, memclockmin=324, memclockmax=324, memclockeditable=0, memtransferrate=648, memtransferratemin=648, memtransferratemax=648, memtransferrateeditable=0 ;

Parameters:

  • device – The identifier of the target device

  • currentClockFreqs – Reference in which to return the performance level string

Returns:

nvmlReturn_t nvmlDeviceGetCurrentClocksEventReasons(
nvmlDevice_t device,
unsigned long long *clocksEventReasons,
)#

Retrieves current clocks event reasons.

For all fully supported products.

See also

NvmlClocksEventReasons

See also

nvmlDeviceGetSupportedClocksEventReasons

Note

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

Parameters:

  • device – The identifier of the target device

  • clocksEventReasons – Reference in which to return bitmask of active clocks event reasons

Returns:

nvmlReturn_t nvmlDeviceGetCurrentClocksThrottleReasons(
nvmlDevice_t device,
unsigned long long *clocksThrottleReasons,
)#

Deprecated:

Use nvmlDeviceGetCurrentClocksEventReasons instead

nvmlReturn_t nvmlDeviceGetDecoderUtilization(
nvmlDevice_t device,
unsigned int *utilization,
unsigned int *samplingPeriodUs,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetDefaultApplicationsClock(
nvmlDevice_t device,
nvmlClockType_t clockType,
unsigned int *clockMHz,
)#

Deprecated:

Applications clocks are deprecated and will be removed in CUDA 14.0.

nvmlReturn_t nvmlDeviceGetDefaultEccMode(
nvmlDevice_t device,
nvmlEnableState_t *defaultMode,
)#

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

Parameters:

  • device – The identifier of the target device

  • defaultMode – Reference in which to return the default ECC mode

Returns:

nvmlReturn_t nvmlDeviceGetDetailedEccErrors(
nvmlDevice_t device,
nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType,
nvmlEccErrorCounts_t *eccCounts,
)#

Retrieves the detailed ECC error counts for the device.

Deprecated:

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

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

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:

nvmlReturn_t nvmlDeviceGetDisplayActive(
nvmlDevice_t device,
nvmlEnableState_t *isActive,
)#

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.

Parameters:

  • device – The identifier of the target device

  • isActive – Reference in which to return the display active state

Returns:

nvmlReturn_t nvmlDeviceGetDisplayMode(
nvmlDevice_t device,
nvmlEnableState_t *display,
)#

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.

Parameters:

  • device – The identifier of the target device

  • display – Reference in which to return the display mode

Returns:

nvmlReturn_t nvmlDeviceGetDramEncryptionMode(
nvmlDevice_t device,
nvmlDramEncryptionInfo_t *current,
nvmlDramEncryptionInfo_t *pending,
)#

Retrieves the current and pending DRAM Encryption modes for the device.

For Blackwell or newer fully supported devices. Only applicable to devices that support DRAM Encryption Requires NVML_INFOROM_DEN version 1.0 or higher.

Changing DRAM Encryption modes requires a reboot. The “pending” DRAM Encryption mode refers to the target mode following the next reboot.

See nvmlEnableState_t for details on allowed modes.

See also

nvmlDeviceSetDramEncryptionMode()

Parameters:

  • device – The identifier of the target device

  • current – Reference in which to return the current DRAM Encryption mode

  • pending – Reference in which to return the pending DRAM Encryption mode

Returns:

nvmlReturn_t nvmlDeviceGetDriverModel_v2(
nvmlDevice_t device,
nvmlDriverModel_t *current,
nvmlDriverModel_t *pending,
)#

Retrieves the current and pending driver model for the device.

For Kepler or newer fully supported devices. For windows only.

On Windows platforms the device driver can run in either WDDM, MCDM or WDM (TCC) modes. If a display is attached to the device it must run in WDDM mode. MCDM mode is preferred if a display is not attached. TCC mode is deprecated. Driver-model availability is architecture-specific; attempting to set an unsupported driver model returns NVML_ERROR_NOT_SUPPORTED.

See nvmlDriverModel_t for details on available driver models.

See also

nvmlDeviceSetDriverModel_v2()

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:

nvmlReturn_t nvmlDeviceGetDynamicPstatesInfo(
nvmlDevice_t device,
nvmlGpuDynamicPstatesInfo_t *pDynamicPstatesInfo,
)#

Retrieve performance monitor samples from the associated subdevice.

Parameters:

  • device –

  • pDynamicPstatesInfo –

Returns:

nvmlReturn_t nvmlDeviceGetEccMode(
nvmlDevice_t device,
nvmlEnableState_t *current,
nvmlEnableState_t *pending,
)#

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

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:

nvmlReturn_t nvmlDeviceGetEncoderCapacity(
nvmlDevice_t device,
nvmlEncoderType_t encoderQueryType,
unsigned int *encoderCapacity,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetEncoderSessions(
nvmlDevice_t device,
unsigned int *sessionCount,
nvmlEncoderSessionInfo_t *sessionInfos,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetEncoderStats(
nvmlDevice_t device,
unsigned int *sessionCount,
unsigned int *averageFps,
unsigned int *averageLatency,
)#

Retrieves the current encoder statistics for a given device.

For Maxwell or newer fully supported devices.

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:

nvmlReturn_t nvmlDeviceGetEncoderUtilization(
nvmlDevice_t device,
unsigned int *utilization,
unsigned int *samplingPeriodUs,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetEnforcedPowerLimit(
nvmlDevice_t device,
unsigned int *limit,
)#

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.

Parameters:

  • device – The device to communicate with

  • limit – Reference in which to return the power management limit in milliwatts

Returns:

nvmlReturn_t nvmlDeviceGetFBCSessions(
nvmlDevice_t device,
unsigned int *sessionCount,
nvmlFBCSessionInfo_t *sessionInfo,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetFBCStats(
nvmlDevice_t device,
nvmlFBCStats_t *fbcStats,
)#

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

For Maxwell or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • fbcStats – Reference to nvmlFBCStats_t structure containing NvFBC stats

Returns:

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

Gets current fan control policy.

For Maxwell or newer fully supported devices.

For all cuda-capable discrete products with fans

Parameters:

  • device – The identifier of the target device

  • fan – The index of the target fan, zero indexed.

  • policy – Reference in which to return the fan control policy

Returns:

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

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.

Parameters:

  • device – The identifier of the target device

  • speed – Reference in which to return the fan speed percentage

Returns:

nvmlReturn_t nvmlDeviceGetFanSpeedRPM(
nvmlDevice_t device,
nvmlFanSpeedInfo_t *fanSpeed,
)#

Retrieves the intended operating speed in rotations per minute (RPM) of the device’s specified fan.

For Maxwell or newer fully supported devices.

For all discrete products with dedicated fans.

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.

Parameters:

  • device – The identifier of the target device

  • fanSpeed – Structure specifying the index of the target fan (input) and retrieved fan speed value (output)

Returns:

nvmlReturn_t nvmlDeviceGetFanSpeed_v2(
nvmlDevice_t device,
unsigned int fan,
unsigned int *speed,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetGpcClkMinMaxVfOffset(
nvmlDevice_t device,
int *minOffset,
int *maxOffset,
)#

Retrieve the GPCCLK min max VF offset value.

Parameters:

  • device – [in] The identifier of the target device

  • minOffset – [out] The retrieved GPCCLK VF min offset value

  • maxOffset – [out] The retrieved GPCCLK VF max offset value

Returns:

nvmlReturn_t nvmlDeviceGetGpcClkVfOffset(
nvmlDevice_t device,
int *offset,
)#

Retrieve the GPCCLK VF offset value.

Parameters:

  • device – [in] The identifier of the target device

  • offset – [out] The retrieved GPCCLK VF offset value

Returns:

nvmlReturn_t nvmlDeviceGetGpuFabricInfo(
nvmlDevice_t device,
nvmlGpuFabricInfo_t *gpuFabricInfo,
)#

Deprecated:

Will be deprecated in a future release. Use nvmlDeviceGetGpuFabricInfoV instead

Get fabric information associated with the device.

For Hopper or newer fully supported devices.

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.

Parameters:

  • device – The identifier of the target device

  • gpuFabricInfo – Information about GPU fabric state

Returns:

nvmlReturn_t nvmlDeviceGetGpuFabricInfoV(
nvmlDevice_t device,
nvmlGpuFabricInfoV_t *gpuFabricInfo,
)#

Versioned wrapper around nvmlDeviceGetGpuFabricInfo that accepts a versioned nvmlGpuFabricInfo_v2_t or later output structure.

For Hopper or newer fully supported devices.

Note

The caller must set the nvmlGpuFabricInfoV_t::version field to the appropriate version prior to calling this function. For example: 

nvmlGpuFabricInfoV_t fabricInfo =
    { .version = nvmlGpuFabricInfo_v2 };
nvmlReturn_t result = nvmlDeviceGetGpuFabricInfoV(device,&fabricInfo);

Parameters:

  • device – The identifier of the target device

  • gpuFabricInfo – Information about GPU fabric state

Returns:

nvmlReturn_t nvmlDeviceGetGpuFabricInfo_v4(
nvmlDevice_t device,
nvmlGpuFabricInfo_v4_t *gpuFabricInfo,
)#

Retrieves GPU fabric information including per-type clique assignments.

Returns fabric clique data via nvmlGpuFabricInfo_v4_t. Each entry in the cliques array is a (type, id) pair representing a single clique assignment. The number of valid entries is given by numCliques. Entries are sorted by ascending type (NVML_GPU_FABRIC_CLIQUE_TYPE_*), then by ascending clique id within each type.

On Hopper systems, the driver reports Unicast Pointer and Multicast Pointer cliques. On Blackwell and Rubin, Unicast Logical Endpoint and Multicast Logical Endpoint are additionally reported.

nvmlGpuFabricInfo_v4_t fabricInfo = {0};
nvmlReturn_t result = nvmlDeviceGetGpuFabricInfo_v4(device, &fabricInfo);

For Hopper or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • gpuFabricInfo – Information about GPU fabric state including per-type cliques

Returns:

nvmlReturn_t nvmlDeviceGetGpuMaxPcieLinkGeneration(
nvmlDevice_t device,
unsigned int *maxLinkGenDevice,
)#

Retrieves the maximum PCIe link generation supported by this device.

For Fermi or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • maxLinkGenDevice – Reference in which to return the max PCIe link generation

Returns:

nvmlReturn_t nvmlDeviceGetGpuOperationMode(
nvmlDevice_t device,
nvmlGpuOperationMode_t *current,
nvmlGpuOperationMode_t *pending,
)#

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

See also

nvmlDeviceSetGpuOperationMode

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:

nvmlReturn_t nvmlDeviceGetGraphicsRunningProcesses_v3(
nvmlDevice_t device,
unsigned int *infoCount,
nvmlProcessInfo_t *infos,
)#

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.

See also

nvmlSystemGetProcessName

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.

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:

nvmlReturn_t nvmlDeviceGetGspFirmwareMode(
nvmlDevice_t device,
unsigned int *isEnabled,
unsigned int *defaultMode,
)#

Retrieve GSP firmware mode.

The caller passes in integer pointers. GSP firmware enablement and default mode information is returned with corresponding parameters. The return value in isEnabled and defaultMode should be treated as boolean.

Parameters:

  • device – Device handle

  • isEnabled – Pointer to specify if GSP firmware is enabled

  • defaultMode – Pointer to specify if GSP firmware is supported by default on device

Returns:

nvmlReturn_t nvmlDeviceGetGspFirmwareVersion(
nvmlDevice_t device,
char *version,
)#

Retrieve GSP firmware version.

The caller passes in buffer via version and corresponding GSP firmware numbered version is returned with the same parameter in string format.

Parameters:

  • device – Device handle

  • version – The retrieved GSP firmware version

Returns:

nvmlReturn_t nvmlDeviceGetHandleByIndex_v2(
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_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

See also

nvmlDeviceGetCount

Parameters:

  • index – The index of the target GPU, >= 0 and < accessibleDevices

  • device – Reference in which to return the device handle

Returns:

nvmlReturn_t nvmlDeviceGetHandleByPciBusId_v2(
const char *pciBusId,
nvmlDevice_t *device,
)#

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.

Parameters:

  • pciBusId – The PCI bus id of the target GPU Accept the following formats (all numbers in hexadecimal): domain:bus:device.function in format x:x:x.x domain:bus:device in format x:x:x bus:device.function in format x:x.x

  • device – Reference in which to return the device handle

Returns:

nvmlReturn_t nvmlDeviceGetHandleBySerial(
const char *serial,
nvmlDevice_t *device,
)#

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

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.

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

See also

nvmlDeviceGetHandleByUUID

Parameters:

  • serial – The board serial number of the target GPU

  • device – Reference in which to return the device handle

Returns:

nvmlReturn_t nvmlDeviceGetHandleByUUID(
const char *uuid,
nvmlDevice_t *device,
)#

Acquire the handle for a particular device, based on its globally unique immutable UUID (in ASCII format) 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

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:

nvmlReturn_t nvmlDeviceGetHandleByUUIDV(
const nvmlUUID_t *uuid,
nvmlDevice_t *device,
)#

Acquire the handle for a particular device, based on its globally unique immutable UUID (in either ASCII or binary format) associated with each device.

See nvmlUUID_v1_t for more information on the UUID struct. The caller must set the appropriate version prior to calling this API.

For all products.

This API causes NVML to initialize the target GPU NVML may initialize additional GPUs as it searches for the target GPU

Parameters:

  • uuid – [in] The UUID of the target GPU or MIG instance

  • device – [out] Reference in which to return the device handle or MIG device handle

Returns:

nvmlReturn_t nvmlDeviceGetHostname_v1(
nvmlDevice_t device,
nvmlHostname_v1_t *hostname,
)#

Get the hostname for the device.

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

Retrieves the hostname string for the GPU device that was set using nvmlDeviceSetHostname_v1().

See also

nvmlDeviceSetHostname_v1()

Parameters:

  • device – The identifier of the target device

  • hostname – Reference to the caller-provided nvmlHostname_v1_t struct to return the hostname

Returns:

nvmlReturn_t nvmlDeviceGetIndex(
nvmlDevice_t device,
unsigned int *index,
)#

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

See also

nvmlDeviceGetCount()

Parameters:

  • device – The identifier of the target device

  • index – Reference in which to return the NVML index of the device

Returns:

nvmlReturn_t nvmlDeviceGetInforomConfigurationChecksum(
nvmlDevice_t device,
unsigned int *checksum,
)#

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)

Parameters:

  • device – The identifier of the target device

  • checksum – Reference in which to return the infoROM configuration checksum

Returns:

nvmlReturn_t nvmlDeviceGetInforomImageVersion(
nvmlDevice_t device,
char *version,
unsigned int length,
)#

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

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:

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

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

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:

nvmlReturn_t nvmlDeviceGetIrqNum(
nvmlDevice_t device,
unsigned int *irqNum,
)#

Gets the device’s interrupt number.

Parameters:

  • device – The identifier of the target device

  • irqNum – The interrupt number associated with the specified device

Returns:

nvmlReturn_t nvmlDeviceGetJpgUtilization(
nvmlDevice_t device,
unsigned int *utilization,
unsigned int *samplingPeriodUs,
)#

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

For Turing or newer fully supported devices.

Note

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

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:

nvmlReturn_t nvmlDeviceGetLastBBXFlushTime(
nvmlDevice_t device,
unsigned long long *timestamp,
unsigned long *durationUs,
)#

Retrieves the timestamp and the duration of the last flush of the BBX (blackbox) infoROM object during the current run.

For all products with an inforom.

See also

nvmlDeviceGetInforomVersion

Parameters:

  • device – The identifier of the target device

  • timestamp – The start timestamp of the last BBX Flush

  • durationUs – The duration (us) of the last BBX Flush

Returns:

nvmlReturn_t nvmlDeviceGetMPSComputeRunningProcesses_v3(
nvmlDevice_t device,
unsigned int *infoCount,
nvmlProcessInfo_t *infos,
)#

Get information about processes with a Multi-Process Service (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.

See also

nvmlSystemGetProcessName

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.

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:

nvmlReturn_t nvmlDeviceGetMarginTemperature(
nvmlDevice_t device,
nvmlMarginTemperature_t *marginTempInfo,
)#

Retrieves the thermal margin temperature (distance to nearest slowdown threshold).

Parameters:

  • device – [in] The identifier of the target device

  • marginTempInfo – [inout] Versioned structure in which to return the temperature reading

Returns:

nvmlReturn_t nvmlDeviceGetMaxClockInfo(
nvmlDevice_t device,
nvmlClockType_t type,
unsigned int *clock,
)#

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

Current P0 clocks (reported by nvmlDeviceGetClockInfo) can differ from max clocks by a few MHz.

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:

nvmlReturn_t nvmlDeviceGetMaxCustomerBoostClock(
nvmlDevice_t device,
nvmlClockType_t clockType,
unsigned int *clockMHz,
)#

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

For Pascal or newer fully supported devices.

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:

nvmlReturn_t nvmlDeviceGetMaxPcieLinkGeneration(
nvmlDevice_t device,
unsigned int *maxLinkGen,
)#

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.

Parameters:

  • device – The identifier of the target device

  • maxLinkGen – Reference in which to return the max PCIe link generation

Returns:

nvmlReturn_t nvmlDeviceGetMaxPcieLinkWidth(
nvmlDevice_t device,
unsigned int *maxLinkWidth,
)#

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.

Parameters:

  • device – The identifier of the target device

  • maxLinkWidth – Reference in which to return the max PCIe link generation

Returns:

nvmlReturn_t nvmlDeviceGetMemClkMinMaxVfOffset(
nvmlDevice_t device,
int *minOffset,
int *maxOffset,
)#

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

Parameters:

  • device – [in] The identifier of the target device

  • minOffset – [out] The retrieved MemClk VF min offset value

  • maxOffset – [out] The retrieved MemClk VF max offset value

Returns:

nvmlReturn_t nvmlDeviceGetMemClkVfOffset(
nvmlDevice_t device,
int *offset,
)#

Retrieve the MemClk (Memory Clock) VF offset value.

Parameters:

  • device – [in] The identifier of the target device

  • offset – [out] The retrieved MemClk VF offset value

Returns:

nvmlReturn_t nvmlDeviceGetMemoryBusWidth(
nvmlDevice_t device,
unsigned int *busWidth,
)#

Gets the device’s memory bus width.

Parameters:

  • device – The identifier of the target device

  • busWidth – The devices’s memory bus width

Returns:

nvmlReturn_t nvmlDeviceGetMemoryErrorCounter(
nvmlDevice_t device,
nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType,
nvmlMemoryLocation_t locationType,
unsigned long long *count,
)#

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.

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.

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.

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:

nvmlReturn_t nvmlDeviceGetMemoryInfo(
nvmlDevice_t device,
nvmlMemory_t *memory,
)#

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.

Note

nvmlDeviceGetMemoryInfo_v2 adds additional memory information.

Note

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.

Note

On certain SOC platforms, the integrated GPU (iGPU) does not use a dedicated framebuffer but instead shares memory with the system. As a result, NVML_ERROR_NOT_SUPPORTED will be returned in this case.

Parameters:

  • device – The identifier of the target device

  • memory – Reference in which to return the memory information

Returns:

nvmlReturn_t nvmlDeviceGetMemoryInfo_v2(
nvmlDevice_t device,
nvmlMemory_v2_t *memory,
)#

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

nvmlDeviceGetMemoryInfo_v2 accounts separately for reserved memory and includes it in the used memory amount.

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.

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.

Note

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.

Note

On certain SOC platforms, the integrated GPU (iGPU) does not use a dedicated framebuffer but instead shares memory with the system. As a result, NVML_ERROR_NOT_SUPPORTED will be returned in this case.

Parameters:

  • device – The identifier of the target device

  • memory – Reference in which to return the memory information

Returns:

nvmlReturn_t nvmlDeviceGetMemoryLimits_v1(
nvmlDevice_t device,
nvmlGetMemoryLimits_v1_t *limits,
)#

Get the memory limits of the device for the cgroup partition.

This method will get the current memory limits of the device for the specified cgroup partition, as well as the current memory used against the limits.

For all products. For Linux only.

Note

MIG handles are not supported

Parameters:
Returns:

nvmlReturn_t nvmlDeviceGetMinMaxClockOfPState(
nvmlDevice_t device,
nvmlClockType_t type,
nvmlPstates_t pstate,
unsigned int *minClockMHz,
unsigned int *maxClockMHz,
)#

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

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:

nvmlReturn_t nvmlDeviceGetMinMaxFanSpeed(
nvmlDevice_t device,
unsigned int *minSpeed,
unsigned int *maxSpeed,
)#

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

For all cuda-capable discrete products with fans

Parameters:

  • device – The identifier of the target device

  • minSpeed – The minimum speed allowed to set

  • maxSpeed – The maximum speed allowed to set

Returns:

nvmlReturn_t nvmlDeviceGetMinorNumber(
nvmlDevice_t device,
unsigned int *minorNumber,
)#

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

Parameters:

  • device – The identifier of the target device

  • minorNumber – Reference in which to return the minor number for the device

Returns:

nvmlReturn_t nvmlDeviceGetModuleId(
nvmlDevice_t device,
unsigned int *moduleId,
)#

Get a unique identifier for the device module on the baseboard.

This API retrieves a unique identifier for each GPU module that exists on a given baseboard. For non-baseboard products, this ID would always be 0.

Parameters:

  • device – The identifier of the target device

  • moduleId – Unique identifier for the GPU module

Returns:

nvmlReturn_t nvmlDeviceGetMultiGpuBoard(
nvmlDevice_t device,
unsigned int *multiGpuBool,
)#

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.

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:

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

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.

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:

nvmlReturn_t nvmlDeviceGetNumFans(
nvmlDevice_t device,
unsigned int *numFans,
)#

Retrieves the number of fans on the device.

For all discrete products with dedicated fans.

Parameters:

  • device – The identifier of the target device

  • numFans – The number of fans

Returns:

nvmlReturn_t nvmlDeviceGetNumGpuCores(
nvmlDevice_t device,
unsigned int *numCores,
)#

Gets the device’s core count.

Note

On MIG-enabled GPUs, querying the device’s core count is currently not supported using this API. Please use nvmlDeviceGetGpuInstanceProfileInfo to fetch the MIG device’s core count.

Parameters:

  • device – The identifier of the target device

  • numCores – The number of cores for the specified device

Returns:

nvmlReturn_t nvmlDeviceGetOfaUtilization(
nvmlDevice_t device,
unsigned int *utilization,
unsigned int *samplingPeriodUs,
)#

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

For Turing or newer fully supported devices.

Note

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

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:

nvmlReturn_t nvmlDeviceGetP2PStatus(
nvmlDevice_t device1,
nvmlDevice_t device2,
nvmlGpuP2PCapsIndex_t p2pIndex,
nvmlGpuP2PStatus_t *p2pStatus,
)#

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

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:

nvmlReturn_t nvmlDeviceGetPciInfoExt(
nvmlDevice_t device,
nvmlPciInfoExt_t *pci,
)#

Retrieves PCI attributes of this device.

For all products.

See nvmlPciInfoExt_v1_t for details on the available PCI info.

Parameters:

  • device – The identifier of the target device

  • pci – Reference in which to return the PCI info

Returns:

nvmlReturn_t nvmlDeviceGetPciInfo_v3(
nvmlDevice_t device,
nvmlPciInfo_t *pci,
)#

Retrieves the PCI attributes of this device.

For all products.

See nvmlPciInfo_t for details on the available PCI info.

Parameters:

  • device – The identifier of the target device

  • pci – Reference in which to return the PCI info

Returns:

nvmlReturn_t nvmlDeviceGetPcieLinkMaxSpeed(
nvmlDevice_t device,
unsigned int *maxSpeed,
)#

Gets the device’s PCIE Max Link speed in MBPS.

Parameters:

  • device – The identifier of the target device

  • maxSpeed – The devices’s PCIE Max Link speed in MBPS

Returns:

nvmlReturn_t nvmlDeviceGetPcieReplayCounter(
nvmlDevice_t device,
unsigned int *value,
)#

Retrieve the PCIe replay counter.

For Kepler or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • value – Reference in which to return the counter’s value

Returns:

nvmlReturn_t nvmlDeviceGetPcieSpeed(
nvmlDevice_t device,
unsigned int *pcieSpeed,
)#

Gets the device’s PCIe Link speed in Mbps.

Parameters:

  • device – The identifier of the target device

  • pcieSpeed – The devices’s PCIe Max Link speed in Mbps

Returns:

nvmlReturn_t nvmlDeviceGetPcieThroughput(
nvmlDevice_t device,
nvmlPcieUtilCounter_t counter,
unsigned int *value,
)#

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

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:

nvmlReturn_t nvmlDeviceGetPdi(nvmlDevice_t device, nvmlPdi_t *pdi)#

Retrieves the Per Device Identifier (PDI) associated with this device.

For Pascal or newer fully supported devices.

See nvmlPdi_v1_t for more information on the struct.

Parameters:

  • device – [in] The identifier of the target device

  • pdi – [out] Reference to the caller-provided structure to return the GPU PDI

Returns:

nvmlReturn_t nvmlDeviceGetPerformanceModes(
nvmlDevice_t device,
nvmlDevicePerfModes_t *perfModes,
)#

Retrieves a performance mode string with all the performance modes defined for this device along with their associated GPU Clock and Memory Clock values.

Not all tokens will be reported on all GPUs, and additional tokens may be added in the future. For backwards compatibility we still provide nvclock and memclock; those are the same as nvclockmin and memclockmin.

Note: These clock values take into account the offset set by clients through /ref nvmlDeviceSetClockOffsets.

Maximum available Pstate (P15) shows the minimum performance level (0) and vice versa.

Each performance modes are returned as a comma-separated list of “token=value” pairs. Each set of performance mode tokens are separated by a “;”. Valid tokens:

Token Value “perf” unsigned int - the Performance level “nvclock” unsigned int - the GPU clocks (in MHz) for the perf level “nvclockmin” unsigned int - the GPU clocks min (in MHz) for the perf level “nvclockmax” unsigned int - the GPU clocks max (in MHz) for the perf level “nvclockeditable” unsigned int - if the GPU clock domain is editable for the perf level “memclock” unsigned int - the memory clocks (in MHz) for the perf level “memclockmin” unsigned int - the memory clocks min (in MHz) for the perf level “memclockmax” unsigned int - the memory clocks max (in MHz) for the perf level “memclockeditable” unsigned int - if the memory clock domain is editable for the perf level “memtransferrate” unsigned int - the memory transfer rate (in MHz) for the perf level “memtransferratemin” unsigned int - the memory transfer rate min (in MHz) for the perf level “memtransferratemax” unsigned int - the memory transfer rate max (in MHz) for the perf level “memtransferrateeditable” unsigned int - if the memory transfer rate is editable for the perf level

Example:

perf=0, nvclock=324, nvclockmin=324, nvclockmax=324, nvclockeditable=0, memclock=324, memclockmin=324, memclockmax=324, memclockeditable=0, memtransferrate=648, memtransferratemin=648, memtransferratemax=648, memtransferrateeditable=0 ; perf=1, nvclock=324, nvclockmin=324, nvclockmax=640, nvclockeditable=0, memclock=810, memclockmin=810, memclockmax=810, memclockeditable=0, memtransferrate=1620, memtransferrate=1620, memtransferrate=1620, memtransferrateeditable=0 ;

Parameters:

  • device – The identifier of the target device

  • perfModes – Reference in which to return the performance level string

Returns:

nvmlReturn_t nvmlDeviceGetPerformanceState(
nvmlDevice_t device,
nvmlPstates_t *pState,
)#

Retrieves the current performance state for the device.

For Fermi or newer fully supported devices.

See nvmlPstates_t for details on allowed performance states.

Parameters:

  • device – The identifier of the target device

  • pState – Reference in which to return the performance state reading

Returns:

nvmlReturn_t nvmlDeviceGetPersistenceMode(
nvmlDevice_t device,
nvmlEnableState_t *mode,
)#

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

Parameters:

  • device – The identifier of the target device

  • mode – Reference in which to return the current driver persistence mode

Returns:

nvmlReturn_t nvmlDeviceGetPlatformInfo(
nvmlDevice_t device,
nvmlPlatformInfo_t *platformInfo,
)#

Get platform information of this device.

For Blackwell or newer fully supported devices.

See nvmlPlatformInfo_v2_t for more information on the struct.

Parameters:

  • device – The identifier of the target device

  • platformInfo – Pointer to the caller-provided structure of nvmlPlatformInfo_t.

Returns:

nvmlReturn_t nvmlDeviceGetPowerManagementDefaultLimit(
nvmlDevice_t device,
unsigned int *defaultLimit,
)#

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.

Parameters:

  • device – The identifier of the target device

  • defaultLimit – Reference in which to return the default power management limit in milliwatts

Returns:

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

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.

Parameters:

  • device – The identifier of the target device

  • limit – Reference in which to return the power management limit in milliwatts

Returns:

nvmlReturn_t nvmlDeviceGetPowerManagementLimitConstraints(
nvmlDevice_t device,
unsigned int *minLimit,
unsigned int *maxLimit,
)#

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

For Kepler or newer fully supported devices.

See also

nvmlDeviceSetPowerManagementLimit

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:

nvmlReturn_t nvmlDeviceGetPowerManagementMode(
nvmlDevice_t device,
nvmlEnableState_t *mode,
)#

Deprecated:

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 &#8212; 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 identifier of the target device

  • mode – Reference in which to return the current power management mode

Returns:

nvmlReturn_t nvmlDeviceGetPowerMizerMode_v1(
nvmlDevice_t device,
nvmlDevicePowerMizerModes_v1_t *powerMizerMode,
)#

Retrieves current power mizer mode on this device.

PowerMizerMode provides a hint to the driver as to how to manage the performance of the GPU.

For Maxwell or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • powerMizerMode – Reference in which to return the power mizer mode

Returns:

nvmlReturn_t nvmlDeviceGetPowerSource(
nvmlDevice_t device,
nvmlPowerSource_t *powerSource,
)#

Gets the devices power source.

Parameters:

  • device – The identifier of the target device

  • powerSource – The power source of the device

Returns:

nvmlReturn_t nvmlDeviceGetPowerState(
nvmlDevice_t device,
nvmlPstates_t *pState,
)#

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.

Parameters:

  • device – The identifier of the target device

  • pState – Reference in which to return the performance state reading

Returns:

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

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.

Parameters:

  • device – The identifier of the target device

  • power – Reference in which to return the power usage information

Returns:

nvmlReturn_t nvmlDeviceGetProcessUtilization(
nvmlDevice_t device,
nvmlProcessUtilizationSample_t *utilization,
unsigned int *processSamplesCount,
unsigned long long lastSeenTimeStamp,
)#

Retrieves the current utilization and process ID.

For Maxwell or newer fully supported devices.

Reads recent utilization of GPU SM (3D/Compute), framebuffer, video encoder, and video decoder for processes running. Utilization values are returned as an array of utilization sample structures in the caller-supplied buffer pointed at by utilization. One utilization sample structure is returned per process running, that had some non-zero utilization during the last sample period. It includes the CPU timestamp at which the samples were recorded. Individual utilization values are returned as “unsigned int” values. If no valid sample entries are found since the lastSeenTimeStamp, NVML_ERROR_NOT_FOUND is returned.

To read utilization values, first determine the size of buffer required to hold the samples by invoking the function with utilization set to NULL. The caller should allocate a buffer of size processSamplesCount * sizeof(nvmlProcessUtilizationSample_t). Invoke the function again with the allocated buffer passed in utilization, and processSamplesCount set to the number of entries the buffer is sized for.

On successful return, the function updates processSamplesCount with the number of process utilization sample structures that were actually written. This may differ from a previously read value as instances are created or destroyed.

lastSeenTimeStamp represents the CPU timestamp in microseconds at which utilization samples were last read. Set it to 0 to read utilization based on all the samples maintained by the driver’s internal sample buffer. Set lastSeenTimeStamp to a timeStamp retrieved from a previous query to read utilization since the previous query.

Note

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

Parameters:

  • device – The identifier of the target device

  • utilization – Pointer to caller-supplied buffer in which guest process utilization samples are returned

  • processSamplesCount – Pointer to caller-supplied array size, and returns number of processes running

  • lastSeenTimeStamp – Return only samples with timestamp greater than lastSeenTimeStamp.

Returns:

nvmlReturn_t nvmlDeviceGetProcessesUtilizationInfo(
nvmlDevice_t device,
nvmlProcessesUtilizationInfo_t *procesesUtilInfo,
)#

Retrieves the recent utilization and process ID for all running processes.

For Maxwell or newer fully supported devices.

Reads recent utilization of GPU SM (3D/Compute), framebuffer, video encoder, and video decoder, jpeg decoder, OFA (Optical Flow Accelerator) for all running processes. Utilization values are returned as an array of utilization sample structures in the caller-supplied buffer pointed at by procesesUtilInfo->procUtilArray. One utilization sample structure is returned per process running, that had some non-zero utilization during the last sample period. It includes the CPU timestamp at which the samples were recorded. Individual utilization values are returned as “unsigned int” values.

The caller should allocate a buffer of size processSamplesCount * sizeof(nvmlProcessUtilizationInfo_t). If the buffer is too small, the API will return NVML_ERROR_INSUFFICIENT_SIZE, with the recommended minimal buffer size at procesesUtilInfo->processSamplesCount. The caller should invoke the function again with the allocated buffer passed in procesesUtilInfo->procUtilArray, and procesesUtilInfo->processSamplesCount set to the number no less than the recommended value by the previous API return.

On successful return, the function updates procesesUtilInfo->processSamplesCount with the number of process utilization info structures that were actually written. This may differ from a previously read value as instances are created or destroyed.

procesesUtilInfo->lastSeenTimeStamp represents the CPU timestamp in microseconds at which utilization samples were last read. Set it to 0 to read utilization based on all the samples maintained by the driver’s internal sample buffer. Set procesesUtilInfo->lastSeenTimeStamp to a timeStamp retrieved from a previous query to read utilization since the previous query.

procesesUtilInfo->version is the version number of the structure nvmlProcessesUtilizationInfo_t, the caller should set the correct version number to retrieve the specific version of processes utilization information.

Note

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

Parameters:

  • device – The identifier of the target device

  • procesesUtilInfo – Pointer to the caller-provided structure of nvmlProcessesUtilizationInfo_t.

Returns:

nvmlReturn_t nvmlDeviceGetRemappedRows(
nvmlDevice_t device,
unsigned int *corrRows,
unsigned int *uncRows,
unsigned int *isPending,
unsigned int *failureOccurred,
)#

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.

For Ampere or newer fully supported devices.

Note

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

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:

nvmlReturn_t nvmlDeviceGetRemappedRows_v2(
nvmlDevice_t device,
nvmlRemappedRowsInfo_v2_t *info,
)#

Get the status of row remapper.

For Ampere or newer fully supported devices.

Note

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

Parameters:

  • device – The identifier of the target device

  • info – Reference for nvmlRemappedRowsInfo_v2_t

Returns:

nvmlReturn_t nvmlDeviceGetRetiredPages(
nvmlDevice_t device,
nvmlPageRetirementCause_t cause,
unsigned int *pageCount,
unsigned long long *addresses,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetRetiredPagesPendingStatus(
nvmlDevice_t device,
nvmlEnableState_t *isPending,
)#

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

For Kepler or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • isPending – Reference in which to return the pending status

Returns:

nvmlReturn_t nvmlDeviceGetRetiredPages_v2(
nvmlDevice_t device,
nvmlPageRetirementCause_t cause,
unsigned int *pageCount,
unsigned long long *addresses,
unsigned long long *timestamps,
)#

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.

Note

nvmlDeviceGetRetiredPages_v2 adds an additional timestamps parameter to return the time of each page’s retirement. This is supported for Pascal and newer architecture.

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:

nvmlReturn_t nvmlDeviceGetRowRemapperHistogram(
nvmlDevice_t device,
nvmlRowRemapperHistogramValues_t *values,
)#

Get the row remapper histogram.

Returns the remap availability for each bank on the GPU.

Parameters:

  • device – Device handle

  • values – Histogram values

Returns:

nvmlReturn_t nvmlDeviceGetRunningProcessDetailList(
nvmlDevice_t device,
nvmlProcessDetailList_t *plist,
)#

Get information about running processes on a device for input context.

For Hopper or newer fully supported devices.

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.

Parameters:

  • device – The device handle or MIG device handle

  • plist – Reference in which to process detail list plist->version The api version plist->mode The process mode plist->procArray Reference in which to return the process information plist->numProcArrayEntries Proc array size of returned entries

Returns:

nvmlReturn_t nvmlDeviceGetSamples(
nvmlDevice_t device,
nvmlSamplingType_t type,
unsigned long long lastSeenTimeStamp,
nvmlValueType_t *sampleValType,
unsigned int *sampleCount,
nvmlSample_t *samples,
)#

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.

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:

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

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.

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:

nvmlReturn_t nvmlDeviceGetSramEccErrorStatus(
nvmlDevice_t device,
nvmlEccSramErrorStatus_t *status,
)#

Get SRAM ECC error status of this device.

For Ampere or newer fully supported devices. Requires root/admin permissions.

See nvmlEccSramErrorStatus_v1_t for more information on the struct.

Parameters:

  • device – The identifier of the target device

  • status – Returns SRAM ECC error status

Returns:

nvmlReturn_t nvmlDeviceGetSramUniqueUncorrectedEccErrorCounts(
nvmlDevice_t device,
nvmlEccSramUniqueUncorrectedErrorCounts_t *errorCounts,
)#

Retrieves the counts of SRAM unique uncorrected ECC errors.

For Blackwell or newer fully supported devices.

Reads SRAM unique uncorrected ECC error counts. The total number of unique errors is returned by errorCounts->entryCount. Error counts are returned as an array of in the caller-supplied buffer pointed at by errorCounts->entries. Each error count entry holds the location/address of the unique error, the error count and whether the error is parity or not.

To read SRAM unique uncorrected ECC error counts, first determine the size of buffer required to hold the error counts by invoking the function with errorCounts->entries set to NULL. The required array size is returned in errorCounts->entryCount

. The caller should allocate a buffer of size “errorCounts->entryCount *

sizeof(nvmlEccSramUniqueUncorrectedErrorCounts_t)”. Invoke the function again with the allocated buffer passed in

errorCounts->entries. This time errorCounts->entryCount will be taken as the entry array size that caller allocates for errorCounts->entries.

On successful return of the second query, the function updates errorCounts->entries with all unique errors. This may fail if errorCounts->entryCount is smaller than the actual number of unique errors. This can happen in cases like new errors occur since the previous query of errorCounts->entryCount. No matter the query succeeds or not, the latest number of unique errors will be returned in errorCounts->entryCount.

Note

The query is only supported when ECC mode is enabled.

Parameters:

  • device – The identifier of the target device

  • errorCounts – Pointer to caller-supplied array which returns the unique error count entries

Returns:

nvmlReturn_t nvmlDeviceGetSupportedClocksEventReasons(
nvmlDevice_t device,
unsigned long long *supportedClocksEventReasons,
)#

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

See also

nvmlDeviceGetCurrentClocksEventReasons

Parameters:

  • device – The identifier of the target device

  • supportedClocksEventReasons – Reference in which to return bitmask of supported clocks event reasons

Returns:

nvmlReturn_t nvmlDeviceGetSupportedClocksThrottleReasons(
nvmlDevice_t device,
unsigned long long *supportedClocksThrottleReasons,
)#

Deprecated:

Use nvmlDeviceGetSupportedClocksEventReasons instead

nvmlReturn_t nvmlDeviceGetSupportedGraphicsClocks(
nvmlDevice_t device,
unsigned int memoryClockMHz,
unsigned int *count,
unsigned int *clocksMHz,
)#

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

For Kepler or newer fully supported devices.

See also

nvmlDeviceSetGpuLockedClocks

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:

nvmlReturn_t nvmlDeviceGetSupportedMemoryClocks(
nvmlDevice_t device,
unsigned int *count,
unsigned int *clocksMHz,
)#

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

For Kepler or newer fully supported devices.

See also

nvmlDeviceSetMemoryLockedClocks

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:

nvmlReturn_t nvmlDeviceGetSupportedPerformanceStates(
nvmlDevice_t device,
nvmlPstates_t *pstates,
unsigned int size,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetTargetFanSpeed(
nvmlDevice_t device,
unsigned int fan,
unsigned int *targetSpeed,
)#

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.

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:

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

Deprecated:

Use nvmlDeviceGetTemperatureV instead

nvmlReturn_t nvmlDeviceGetTemperatureThreshold(
nvmlDevice_t device,
nvmlTemperatureThresholds_t thresholdType,
unsigned int *temp,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetTemperatureV(
nvmlDevice_t device,
nvmlTemperature_t *temperature,
)#

Retrieves the current temperature readings (in degrees C) for the given device.

For all products.

Parameters:

  • device – [in] Target device identifier.

  • temperature – [inout] Structure specifying the sensor type (input) and retrieved temperature value (output).

Returns:

nvmlReturn_t nvmlDeviceGetThermalSettings(
nvmlDevice_t device,
unsigned int sensorIndex,
nvmlGpuThermalSettings_t *pThermalSettings,
)#

Used to execute a list of thermal system instructions.

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:

nvmlReturn_t nvmlDeviceGetTopologyCommonAncestor(
nvmlDevice_t device1,
nvmlDevice_t device2,
nvmlGpuTopologyLevel_t *pathInfo,
)#

Retrieve the common ancestor for two devices For all products.

Supported on Linux only.

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:

nvmlReturn_t nvmlDeviceGetTopologyNearestGpus(
nvmlDevice_t device,
nvmlGpuTopologyLevel_t level,
unsigned int *count,
nvmlDevice_t *deviceArray,
)#

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

Supported on Linux only.

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:

nvmlReturn_t nvmlDeviceGetTotalEccErrors(
nvmlDevice_t device,
nvmlMemoryErrorType_t errorType,
nvmlEccCounterType_t counterType,
unsigned long long *eccCounts,
)#

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

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:

nvmlReturn_t nvmlDeviceGetTotalEnergyConsumption(
nvmlDevice_t device,
unsigned long long *energy,
)#

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

For Volta or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • energy – Reference in which to return the energy consumption information

Returns:

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

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.

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:

nvmlReturn_t nvmlDeviceGetUtilizationRates(
nvmlDevice_t device,
nvmlUtilization_t *utilization,
)#

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.

Note

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

Parameters:

  • device – The identifier of the target device

  • utilization – Reference in which to return the utilization information

Returns:

nvmlReturn_t nvmlDeviceGetVbiosVersion(
nvmlDevice_t device,
char *version,
unsigned int length,
)#

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.

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:

nvmlReturn_t nvmlDeviceGetViolationStatus(
nvmlDevice_t device,
nvmlPerfPolicyType_t perfPolicyType,
nvmlViolationTime_t *violTime,
)#

Deprecated:

Use nvmlDeviceGetFieldValues to query this data. This API will be removed in CUDA 14.0.

Translations are as follows:

NVML_PERF_POLICY_POWER -> NVML_FI_DEV_CLOCKS_EVENT_REASON_SW_POWER_CAP NVML_PERF_POLICY_THERMAL -> NVML_FI_DEV_CLOCKS_EVENT_REASON_SW_THERM_SLOWDOWN NVML_PERF_POLICY_SYNC_BOOST -> NVML_FI_DEV_CLOCKS_EVENT_REASON_SYNC_BOOST NVML_PERF_POLICY_BOARD_LIMIT -> NVML_FI_DEV_PERF_POLICY_BOARD_LIMIT NVML_PERF_POLICY_LOW_UTILIZATION -> NVML_FI_DEV_PERF_POLICY_LOW_UTILIZATION NVML_PERF_POLICY_RELIABILITY -> NVML_FI_DEV_PERF_POLICY_RELIABILITY NVML_PERF_POLICY_TOTAL_APP_CLOCKS -> DEPRECATED, Do not use NVML_PERF_POLICY_TOTAL_BASE_CLOCKS -> NVML_FI_DEV_PERF_POLICY_TOTAL_BASE_CLOCKS

nvmlReturn_t nvmlDeviceOnSameBoard(
nvmlDevice_t device1,
nvmlDevice_t device2,
int *onSameBoard,
)#

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

For all fully supported products.

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:

nvmlReturn_t nvmlDevicePerfMetricsGetSamples_v1(
nvmlDevice_t device,
nvmlPerfMetricsSamples_v1_t *samples,
)#

Get Performance Metric samples.

See nvmlPerfMetricsSamples_v1_t for more information on the struct.

Parameters:
Returns:

nvmlReturn_t nvmlDeviceSetAdaptiveTgpMode_v1(
nvmlDevice_t device,
nvmlEnableState_t mode,
)#

Request to enable or disable Adaptive TGP Mode for a GPU.

RUBIN_OR_NEWER% Requires root/admin privileges.

Adaptive TGP Mode assigns tailored power budgets to two binned GPU parts within the same module, reducing node-to-node and rack-to-rack performance variation. An out-of-band administrator policy may override the in-band request; use nvmlDeviceGetAdaptiveTgpModeInfo_v1 to query the arbitrated state.

See also

nvmlDeviceGetAdaptiveTgpModeInfo_v1()

Parameters:

  • device – The identifier of the target device

  • mode – NVML_FEATURE_ENABLED or NVML_FEATURE_DISABLED

Returns:

nvmlReturn_t nvmlDeviceSetClockOffsets(
nvmlDevice_t device,
nvmlClockOffset_t *info,
)#

Control current clock offset of some clock domain for a given PState.

For Maxwell or newer fully supported devices.

Requires privileged user.

Parameters:

  • device – The identifier of the target device

  • info – Structure specifying the clock type (input), the pstate (input) and clock offset value (input)

Returns:

nvmlReturn_t nvmlDeviceSetConfComputeUnprotectedMemSize(
nvmlDevice_t device,
unsigned long long sizeKiB,
)#

Set Conf Computing Unprotected Memory Size.

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

Parameters:

  • device – Device Handle

  • sizeKiB – Unprotected Memory size to be set in KiB

Returns:

nvmlReturn_t nvmlDeviceSetDramEncryptionMode(
nvmlDevice_t device,
const nvmlDramEncryptionInfo_t *dramEncryption,
)#

Set the DRAM Encryption mode for the device.

For Kepler or newer fully supported devices. Only applicable to devices that support DRAM Encryption. Requires NVML_INFOROM_DEN version 1.0 or higher. Requires root/admin permissions.

The DRAM Encryption mode determines whether the GPU enables its DRAM Encryption support.

This operation takes effect after the next reboot.

See nvmlEnableState_t for details on available modes.

See also

nvmlDeviceGetDramEncryptionMode()

Parameters:

  • device – The identifier of the target device

  • dramEncryption – The target DRAM Encryption mode

Returns:

nvmlReturn_t nvmlDeviceSetHostname_v1(
nvmlDevice_t device,
nvmlHostname_v1_t *hostname,
)#

Set the hostname for the device.

For Blackwell or newer fully supported devices. Requires root/admin permissions. Supported on Linux only.

Sets a hostname string for the GPU device. This operation takes effect immediately.

The hostname is not stored persistently across GPU resets or driver reloads.

See also

nvmlDeviceGetHostname_v1()

Parameters:

  • device – The identifier of the target device

  • hostname – Reference to the caller-provided nvmlHostname_v1_t struct containing the hostname

Returns:

nvmlReturn_t nvmlDeviceSetMemoryLimits_v1(
nvmlDevice_t device,
nvmlSetMemoryLimits_v1_t *limits,
)#

Set the memory limits of the device for the cgroup partition.

This method will set the memory limits of the device for the specified cgroup partition. The limits will indicate the amount of memory that can be allocated for the device for use of an application in that cgroup.

For all products. For Linux only. Requires root/admin permissions.

Note

MIG handles are not supported

Parameters:

  • device – [in] The identifier of the target device

  • limits – [in] A pointer to nvmlSetMemoryLimits_v1_t where the limits can be set

Returns:

nvmlReturn_t nvmlDeviceSetPowerManagementLimit_v2(
nvmlDevice_t device,
nvmlPowerValue_v2_t *powerValue,
)#

Set new power limit of this device.

For Kepler or newer fully supported devices. Requires root/admin permissions.

See nvmlDeviceGetPowerManagementLimitConstraints to check the allowed ranges of values.

See nvmlPowerValue_v2_t for more information on the struct.

This API replaces nvmlDeviceSetPowerManagementLimit. It can be used as a drop-in replacement for the older version.

See also

NVML_FI_DEV_POWER_AVERAGE

See also

NVML_FI_DEV_POWER_INSTANT

See also

NVML_FI_DEV_POWER_MIN_LIMIT

See also

NVML_FI_DEV_POWER_MAX_LIMIT

See also

NVML_FI_DEV_POWER_CURRENT_LIMIT

Note

Limit is not persistent across reboots or driver unloads. Enable persistent mode to prevent driver from unloading when no application is using the device.

Parameters:

  • device – The identifier of the target device

  • powerValue – Power management limit in milliwatts to set

Returns:

nvmlReturn_t nvmlDeviceSetPowerMizerMode_v1(
nvmlDevice_t device,
nvmlDevicePowerMizerModes_v1_t *powerMizerMode,
)#

Sets the new power mizer mode.

For Maxwell or newer fully supported devices.

Parameters:

  • device – The identifier of the target device

  • powerMizerMode – Reference in which to set the power mizer mode.

Returns:

nvmlReturn_t nvmlDeviceValidateInforom(nvmlDevice_t device)#

Reads the infoROM from the flash and verifies the checksums.

For all products with an inforom.

Parameters:

device – The identifier of the target device

Returns:

nvmlReturn_t nvmlSystemGetConfComputeCapabilities(
nvmlConfComputeSystemCaps_t *capabilities,
)#

Get Conf Computing System capabilities.

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

Parameters:

capabilities – System CC capabilities

Returns:

nvmlReturn_t nvmlSystemGetConfComputeGpusReadyState(
unsigned int *isAcceptingWork,
)#

Get Conf Computing GPUs ready state.

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

return

Parameters:

isAcceptingWork – Returns GPU current work accepting state, NVML_CC_ACCEPTING_CLIENT_REQUESTS_TRUE or NVML_CC_ACCEPTING_CLIENT_REQUESTS_FALSE

nvmlReturn_t nvmlSystemGetConfComputeKeyRotationThresholdInfo(
nvmlConfComputeGetKeyRotationThresholdInfo_t *pKeyRotationThrInfo,
)#

Get Conf Computing key rotation threshold detail.

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

Parameters:

pKeyRotationThrInfo – Reference in which to return the key rotation threshold data

Returns:

nvmlReturn_t nvmlSystemGetConfComputeSettings(
nvmlSystemConfComputeSettings_t *settings,
)#

Get Conf Computing System Settings.

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

Parameters:

settings – System CC settings

Returns:

nvmlReturn_t nvmlSystemGetConfComputeState(
nvmlConfComputeSystemState_t *state,
)#

Get Conf Computing System State.

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

Parameters:

state – System CC State

Returns:

nvmlReturn_t nvmlSystemSetConfComputeGpusReadyState(
unsigned int isAcceptingWork,
)#

Set Conf Computing GPUs ready state.

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

return

Parameters:

isAcceptingWork – GPU accepting new work, NVML_CC_ACCEPTING_CLIENT_REQUESTS_TRUE or NVML_CC_ACCEPTING_CLIENT_REQUESTS_FALSE

nvmlReturn_t nvmlSystemSetConfComputeKeyRotationThresholdInfo(
nvmlConfComputeSetKeyRotationThresholdInfo_t *pKeyRotationThrInfo,
)#

Set Conf Computing key rotation threshold.

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

This function is to set the confidential compute key rotation threshold parameters. pKeyRotationThrInfo->maxAttackerAdvantage should be in the range from NVML_CC_KEY_ROTATION_THRESHOLD_ATTACKER_ADVANTAGE_MIN to NVML_CC_KEY_ROTATION_THRESHOLD_ATTACKER_ADVANTAGE_MAX. Default value is 60.

Parameters:

pKeyRotationThrInfo – Reference to the key rotation threshold data

Returns:

Typedefs#

typedef nvmlTemperature_v1_t nvmlTemperature_t#
On this page