|
|
Modules
Description
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.
‣ 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.
‣ On MIG-enabled GPUs, querying device utilization rates is not currently
supported.
nvmlReturn_t nvmlDeviceGetEncoderUtilization
(nvmlDevice_t device, unsigned int *utilization,
unsigned int *samplingPeriodUs)
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
‣ NVML_SUCCESS if utilization has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or
samplingPeriodUs is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the current utilization and sampling size in microseconds for the Encoder
For Kepler or newer fully supported devices.
187
Modules
On MIG-enabled GPUs, querying encoder utilization is not currently supported.
nvmlReturn_t nvmlDeviceGetEncoderCapacity
(nvmlDevice_t device, nvmlEncoderType_t
encoderQueryType, unsigned int *encoderCapacity)
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
‣ NVML_SUCCESS if encoderCapacity is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if encoderCapacity is NULL, or device or
encoderQueryType are invalid
‣ NVML_ERROR_NOT_SUPPORTED if device does not support the encoder
specified in encodeQueryType
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
188
Modules
nvmlReturn_t nvmlDeviceGetEncoderStats
(nvmlDevice_t device, unsigned int *sessionCount,
unsigned int *averageFps, unsigned int *averageLatency)
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
‣ NVML_SUCCESS if sessionCount, averageFps and averageLatency is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if sessionCount, or device or averageFps,
or averageLatency is NULL
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the current encoder statistics for a given device.
For Maxwell or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetEncoderSessions
(nvmlDevice_t device, unsigned int *sessionCount,
nvmlEncoderSessionInfo_t *sessionInfos)
Parameters
device
The identifier of the target device
sessionCount
Reference to caller supplied array size, and returns the number of sessions.
189
Modules
sessionInfos
Reference in which to return the session information
Returns
‣ NVML_SUCCESS if sessionInfos is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INSUFFICIENT_SIZE if sessionCount is too small, array element
count is returned in sessionCount
‣ NVML_ERROR_INVALID_ARGUMENT if sessionCount is NULL.
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
nvmlReturn_t nvmlDeviceGetDecoderUtilization
(nvmlDevice_t device, unsigned int *utilization,
unsigned int *samplingPeriodUs)
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
190
Modules
Returns
‣ NVML_SUCCESS if utilization has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or
samplingPeriodUs is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the current utilization and sampling size in microseconds for the Decoder
For Kepler or newer fully supported devices.
On MIG-enabled GPUs, querying decoder utilization is not currently supported.
nvmlReturn_t nvmlDeviceGetJpgUtilization
(nvmlDevice_t device, unsigned int *utilization,
unsigned int *samplingPeriodUs)
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
‣ NVML_SUCCESS if utilization has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or
samplingPeriodUs is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
191
Modules
Description
Retrieves the current utilization and sampling size in microseconds for the JPG
TURING_OR_NEWER%
On MIG-enabled GPUs, querying decoder utilization is not currently supported.
nvmlReturn_t nvmlDeviceGetOfaUtilization
(nvmlDevice_t device, unsigned int *utilization,
unsigned int *samplingPeriodUs)
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
‣ NVML_SUCCESS if utilization has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or
samplingPeriodUs is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the current utilization and sampling size in microseconds for the OFA (Optical
Flow Accelerator)
TURING_OR_NEWER%
On MIG-enabled GPUs, querying decoder utilization is not currently supported.
192
Modules
nvmlReturn_t nvmlDeviceGetFBCStats (nvmlDevice_t
device, nvmlFBCStats_t *fbcStats)
Parameters
device
The identifier of the target device
fbcStats
Reference to nvmlFBCStats_t structure containing NvFBC stats
Returns
‣ NVML_SUCCESS if fbcStats is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if fbcStats is NULL
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the active frame buffer capture sessions statistics for a given device.
For Maxwell or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetFBCSessions
(nvmlDevice_t device, unsigned int *sessionCount,
nvmlFBCSessionInfo_t *sessionInfo)
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
‣ NVML_SUCCESS if sessionInfo is fetched
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
193
Modules
‣ NVML_ERROR_INSUFFICIENT_SIZE if sessionCount is too small, array element
count is returned in sessionCount
‣ NVML_ERROR_INVALID_ARGUMENT if sessionCount is NULL.
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
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.
nvmlReturn_t nvmlDeviceGetDriverModel_v2
(nvmlDevice_t device, nvmlDriverModel_t *current,
nvmlDriverModel_t *pending)
Parameters
device
The identifier of the target device
current
Reference in which to return the current driver model
pending
Reference in which to return the pending driver model
Returns
‣ NVML_SUCCESS if either current and/or pending have been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
194
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or both current and
pending are NULL
‣ NVML_ERROR_NOT_SUPPORTED if the platform is not windows
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
See nvmlDriverModel_t for details on available driver models.
See also:
nvmlDeviceSetDriverModel_v2()
nvmlReturn_t nvmlDeviceGetVbiosVersion (nvmlDevice_t
device, char *version, unsigned int length)
Parameters
device
The identifier of the target device
version
Reference to which to return the VBIOS version
length
The maximum allowed length of the string returned in version
Returns
‣ NVML_SUCCESS if version has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or version is NULL
‣ NVML_ERROR_INSUFFICIENT_SIZE if length is too small
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
195
Modules
Description
Get VBIOS version of the device.
For all products.
The VBIOS version may change from time to time. It will not
exceed 32 characters in length (including the NULL terminator). See
nvmlConstants::NVML_DEVICE_VBIOS_VERSION_BUFFER_SIZE.
nvmlReturn_t nvmlDeviceGetBridgeChipInfo
(nvmlDevice_t device, nvmlBridgeChipHierarchy_t
*bridgeHierarchy)
Parameters
device
The identifier of the target device
bridgeHierarchy
Reference to the returned bridge chip Hierarchy
Returns
‣ NVML_SUCCESS if bridge chip exists
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or bridgeInfo is NULL
‣ NVML_ERROR_NOT_SUPPORTED if bridge chip not supported on the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Get Bridge Chip Information for all the bridge chips on the board.
For all fully supported products. Only applicable to multi-GPU products.
nvmlReturn_t
nvmlDeviceGetComputeRunningProcesses_v3
196
Modules
(nvmlDevice_t device, unsigned int *infoCount,
nvmlProcessInfo_t *infos)
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
‣ NVML_SUCCESS if infoCount and infos have been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INSUFFICIENT_SIZE if infoCount indicates that the infos array is
too small infoCount will contain minimal amount of space necessary for the call to
complete
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, either of infoCount or
infos is NULL
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
197
Modules
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.
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.
See also:
nvmlSystemGetProcessName
nvmlReturn_t
nvmlDeviceGetGraphicsRunningProcesses_v3
(nvmlDevice_t device, unsigned int *infoCount,
nvmlProcessInfo_t *infos)
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
‣ NVML_SUCCESS if infoCount and infos have been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INSUFFICIENT_SIZE if infoCount indicates that the infos array is
too small infoCount will contain minimal amount of space necessary for the call to
complete
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, either of infoCount or
infos is NULL
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by device
198
Modules
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
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.
See also:
nvmlSystemGetProcessName
nvmlReturn_t
nvmlDeviceGetMPSComputeRunningProcesses_v3
(nvmlDevice_t device, unsigned int *infoCount,
nvmlProcessInfo_t *infos)
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
199
Modules
Returns
‣ NVML_SUCCESS if infoCount and infos have been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INSUFFICIENT_SIZE if infoCount indicates that the infos array is
too small infoCount will contain minimal amount of space necessary for the call to
complete
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, either of infoCount or
infos is NULL
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
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.
See also:
nvmlSystemGetProcessName
200
Modules
nvmlReturn_t nvmlDeviceGetRunningProcessDetailList
(nvmlDevice_t device, nvmlProcessDetailList_t *plist)
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
‣ NVML_SUCCESS if plist->numprocArrayEntries and plist->procArray have been
populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INSUFFICIENT_SIZE if plist->numprocArrayEntries indicates that
the plist->procArray is too small plist->numprocArrayEntries will contain minimal
amount of space necessary for the call to complete
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, plist is NULL, plist-
>version is invalid, plist->mode is invalid,
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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).
201
Modules
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.
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.
nvmlReturn_t nvmlDeviceOnSameBoard (nvmlDevice_t
device1, nvmlDevice_t device2, int *onSameBoard)
Parameters
device1
The first GPU device
device2
The second GPU device
onSameBoard
Reference in which to return the status. Non-zero indicates that the GPUs are on the
same board.
Returns
‣ NVML_SUCCESS if onSameBoard has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if dev1 or dev2 are invalid or
onSameBoard is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this check is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the either GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Check if the GPU devices are on the same physical board.
For all fully supported products.
202
Modules
nvmlReturn_t nvmlDeviceGetAPIRestriction
(nvmlDevice_t device, nvmlRestrictedAPI_t apiType,
nvmlEnableState_t *isRestricted)
Parameters
device
The identifier of the target device
apiType
Target API type for this operation
isRestricted
Reference in which to return the current restriction NVML_FEATURE_ENABLED
indicates that the API is root-only NVML_FEATURE_DISABLED indicates that the
API is accessible to all users
Returns
‣ NVML_SUCCESS if isRestricted has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, apiType incorrect or
isRestricted is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
or the device does not support the feature that is being queried (E.G. Enabling/
disabling Auto Boosted clocks is not supported by the device)
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the root/admin permissions on the target API. See nvmlRestrictedAPI_t for
the list of supported APIs. If an API is restricted only root users can call that API. See
nvmlDeviceSetAPIRestriction to change current permissions.
For all fully supported products.
See also:
nvmlRestrictedAPI_t
nvmlReturn_t nvmlDeviceGetSamples (nvmlDevice_t
device, nvmlSamplingType_t type, unsigned long long
203
Modules
lastSeenTimeStamp, nvmlValueType_t *sampleValType,
unsigned int *sampleCount, nvmlSample_t *samples)
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
‣ NVML_SUCCESS if samples are successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, samplesCount is
NULL or reference to sampleCount is 0 for non null samples
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_NOT_FOUND if sample entries are not found
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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
204
Modules
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.
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.
nvmlReturn_t nvmlDeviceGetBAR1MemoryInfo
(nvmlDevice_t device, nvmlBAR1Memory_t
*bar1Memory)
Parameters
device
The identifier of the target device
bar1Memory
Reference in which BAR1 memory information is returned.
Returns
‣ NVML_SUCCESS if BAR1 memory is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, bar1Memory is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Gets Total, Available and Used size of BAR1 memory.
205
Modules
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).
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.
For Kepler or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetViolationStatus
(nvmlDevice_t device, nvmlPerfPolicyType_t
perfPolicyType, nvmlViolationTime_t *violTime)
Parameters
device
The identifier of the target device
perfPolicyType
Represents Performance policy which can trigger GPU throttling
violTime
Reference to which violation time related information is returned
Returns
‣ NVML_SUCCESS if violation time is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, perfPolicyType is
invalid, or violTime is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
Description
Gets the duration of time during which the device was throttled (lower than requested
clocks) due to power or thermal constraints.
The method is important to users who are tying to understand if their GPUs throttle at
any point during their applications. The difference in violation times at two different
reference times gives the indication of GPU throttling event.
Violation for thermal capping is not supported at this time.
For Kepler or newer fully supported devices.
206
Modules
nvmlReturn_t nvmlDeviceGetIrqNum (nvmlDevice_t
device, unsigned int *irqNum)
Parameters
device
The identifier of the target device
irqNum
The interrupt number associated with the specified device
Returns
‣ NVML_SUCCESS if irq number is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or irqNum is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
Description
Gets the device's interrupt number
nvmlReturn_t nvmlDeviceGetNumGpuCores
(nvmlDevice_t device, unsigned int *numCores)
Parameters
device
The identifier of the target device
numCores
The number of cores for the specified device
Returns
‣ NVML_SUCCESS if GPU core count is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or numCores is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
207
Modules
Description
Gets the device's core count
nvmlReturn_t nvmlDeviceGetPowerSource
(nvmlDevice_t device, nvmlPowerSource_t
*powerSource)
Parameters
device
The identifier of the target device
powerSource
The power source of the device
Returns
‣ NVML_SUCCESS if the current power source was successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or powerSource is
NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
Description
Gets the devices power source
nvmlReturn_t nvmlDeviceGetMemoryBusWidth
(nvmlDevice_t device, unsigned int *busWidth)
Parameters
device
The identifier of the target device
busWidth
The devices's memory bus width
Returns
‣ NVML_SUCCESS if the memory bus width is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
208
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or busWidth is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
Description
Gets the device's memory bus width
nvmlReturn_t nvmlDeviceGetPcieLinkMaxSpeed
(nvmlDevice_t device, unsigned int *maxSpeed)
Parameters
device
The identifier of the target device
maxSpeed
The devices's PCIE Max Link speed in MBPS
Returns
‣ NVML_SUCCESS if PCIe Max Link Speed is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or maxSpeed is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
Description
Gets the device's PCIE Max Link speed in MBPS
nvmlReturn_t nvmlDeviceGetPcieSpeed (nvmlDevice_t
device, unsigned int *pcieSpeed)
Parameters
device
The identifier of the target device
pcieSpeed
The devices's PCIe Max Link speed in Mbps
209
Modules
Returns
‣ NVML_SUCCESS if pcieSpeed has been retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or pcieSpeed is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support PCIe speed
getting
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Gets the device's PCIe Link speed in Mbps
nvmlReturn_t nvmlDeviceGetAdaptiveClockInfoStatus
(nvmlDevice_t device, unsigned int
*adaptiveClockStatus)
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
‣ NVML_SUCCESS if the current adaptive clocking status is successfully retrieved
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, or adaptiveClockStatus
is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
Description
Gets the device's Adaptive Clock status
210
Modules
nvmlReturn_t nvmlDeviceGetBusType (nvmlDevice_t
device, nvmlBusType_t *type)
Parameters
device
The identifier of the target device
type
The PCI Bus type
Description
Get the type of the GPU Bus (PCIe, PCI, ...)
return
‣ NVML_SUCCESS if the bus type is successfully retreived
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or type is NULL
‣ NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t nvmlDeviceGetGpuFabricInfo
(nvmlDevice_t device, nvmlGpuFabricInfo_t
*gpuFabricInfo)
Parameters
device
The identifier of the target device
gpuFabricInfo
Information about GPU fabric state
Returns
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_NOT_SUPPORTED If device doesn't support gpu fabric
Description
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.
211
Modules
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.
nvmlReturn_t nvmlDeviceGetGpuFabricInfoV
(nvmlDevice_t device, nvmlGpuFabricInfoV_t
*gpuFabricInfo)
Parameters
device
The identifier of the target device
gpuFabricInfo
Information about GPU fabric state
Returns
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_NOT_SUPPORTED If device doesn't support gpu fabric
Description
Versioned wrapper around nvmlDeviceGetGpuFabricInfo that accepts a versioned
nvmlGpuFabricInfo_v2_t or later output structure.
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);
For Hopper or newer fully supported devices.
nvmlReturn_t nvmlSystemGetConfComputeCapabilities
(nvmlConfComputeSystemCaps_t *capabilities)
Parameters
capabilities
System CC capabilities
212
Modules
Returns
‣ NVML_SUCCESS if capabilities were successfully queried
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if capabilities is invalid
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
Description
Get Conf Computing System capabilities.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t nvmlSystemGetConfComputeState
(nvmlConfComputeSystemState_t *state)
Parameters
state
System CC State
Returns
‣ NVML_SUCCESS if state were successfully queried
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if state is invalid
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
Description
Get Conf Computing System State.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t nvmlDeviceGetConfComputeMemSizeInfo
(nvmlDevice_t device, nvmlConfComputeMemSizeInfo_t
*memInfo)
Parameters
device
Device handle
memInfo
Protected/Unprotected Memory sizes
213
Modules
Returns
‣ NVML_SUCCESS if memInfo were successfully queried
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if memInfo or device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
Description
Get Conf Computing Protected and Unprotected Memory Sizes.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t
nvmlSystemGetConfComputeGpusReadyState (unsigned
int *isAcceptingWork)
Parameters
isAcceptingWork
Returns GPU current work accepting state,
NVML_CC_ACCEPTING_CLIENT_REQUESTS_TRUE or
NVML_CC_ACCEPTING_CLIENT_REQUESTS_FALSE
Description
Get Conf Computing GPUs ready state.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
return
‣ NVML_SUCCESS if current GPUs ready state were successfully queried
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if isAcceptingWork is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
nvmlReturn_t
nvmlDeviceGetConfComputeProtectedMemoryUsage
(nvmlDevice_t device, nvmlMemory_t *memory)
Parameters
device
The identifier of the target device
214
Modules
memory
Reference in which to return the memory information
Returns
‣ NVML_SUCCESS if memory has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or memory is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Get Conf Computing protected memory usage.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t
nvmlDeviceGetConfComputeGpuCertificate
(nvmlDevice_t device,
nvmlConfComputeGpuCertificate_t *gpuCert)
Parameters
device
The identifier of the target device
gpuCert
Reference in which to return the gpu certificate information
Returns
‣ NVML_SUCCESS if gpu certificate info has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or memory is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Get Conf Computing GPU certificate details.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
215
Modules
nvmlReturn_t
nvmlDeviceGetConfComputeGpuAttestationReport
(nvmlDevice_t device,
nvmlConfComputeGpuAttestationReport_t
*gpuAtstReport)
Parameters
device
The identifier of the target device
gpuAtstReport
Reference in which to return the gpu attestation report
Returns
‣ NVML_SUCCESS if gpu attestation report has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or memory is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Get Conf Computing GPU attestation report.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t
nvmlSystemGetConfComputeKeyRotationThresholdInfo
(nvmlConfComputeGetKeyRotationThresholdInfo_t
*pKeyRotationThrInfo)
Parameters
pKeyRotationThrInfo
Reference in which to return the key rotation threshold data
Returns
‣ NVML_SUCCESS if gpu key rotation threshold info has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
216
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or memory is NULL
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Get Conf Computing key rotation threshold detail.
For Hopper or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t
nvmlDeviceSetConfComputeUnprotectedMemSize
(nvmlDevice_t device, unsigned long long sizeKiB)
Parameters
device
Device Handle
sizeKiB
Unprotected Memory size to be set in KiB
Returns
‣ NVML_SUCCESS if sizeKiB successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
Description
Set Conf Computing Unprotected Memory Size.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t
nvmlSystemSetConfComputeGpusReadyState (unsigned
int isAcceptingWork)
Parameters
isAcceptingWork
GPU accepting new work, NVML_CC_ACCEPTING_CLIENT_REQUESTS_TRUE or
NVML_CC_ACCEPTING_CLIENT_REQUESTS_FALSE
217
Modules
Description
Set Conf Computing GPUs ready state.
For Ampere or newer fully supported devices. Supported on Linux, Windows TCC.
return
‣ NVML_SUCCESS if current GPUs ready state is successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if isAcceptingWork is invalid
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
nvmlReturn_t
nvmlSystemSetConfComputeKeyRotationThresholdInfo
(nvmlConfComputeSetKeyRotationThresholdInfo_t
*pKeyRotationThrInfo)
Parameters
pKeyRotationThrInfo
Reference to the key rotation threshold data
Returns
‣ NVML_SUCCESS if key rotation threashold max attacker advantage has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or memory is NULL
‣ NVML_ERROR_INVALID_STATE if confidential compute GPU ready state is
enabled
‣ NVML_ERROR_NOT_SUPPORTED if this query is not supported by the device
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
218
Modules
nvmlReturn_t nvmlSystemGetConfComputeSettings
(nvmlSystemConfComputeSettings_t *settings)
Parameters
settings
System CC settings
Returns
‣ NVML_SUCCESS If the query is success
‣ NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If device is invalid or counters is NULL
‣ NVML_ERROR_NOT_SUPPORTED If the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST If the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the provided version is
invalid/unsupported
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Get Conf Computing System Settings.
For Hopper or newer fully supported devices. Supported on Linux, Windows TCC.
nvmlReturn_t nvmlDeviceGetGspFirmwareVersion
(nvmlDevice_t device, char *version)
Parameters
device
Device handle
version
The retrieved GSP firmware version
Returns
‣ NVML_SUCCESS if GSP firmware version is sucessfully retrieved
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or GSP version pointer
is NULL
‣ NVML_ERROR_NOT_SUPPORTED if GSP firmware is not enabled for GPU
‣ NVML_ERROR_UNKNOWN on any unexpected error
219
Modules
Description
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.
nvmlReturn_t nvmlDeviceGetGspFirmwareMode
(nvmlDevice_t device, unsigned int *isEnabled, unsigned
int *defaultMode)
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
‣ NVML_SUCCESS if GSP firmware mode is sucessfully retrieved
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or any of isEnabled or
defaultMode is NULL
‣ NVML_ERROR_NOT_SUPPORTED if GSP firmware is not enabled for GPU
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
220
Modules
nvmlReturn_t nvmlDeviceGetSramEccErrorStatus
(nvmlDevice_t device, nvmlEccSramErrorStatus_t
*status)
Parameters
device
The identifier of the target device
status
Returns SRAM ECC error status
Returns
‣ NVML_SUCCESS If limit has been set
‣ NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If device is invalid or counters is NULL
‣ NVML_ERROR_NOT_SUPPORTED If the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST If the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
nvmlEccSramErrorStatus_t is invalid
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
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.
nvmlReturn_t nvmlDeviceGetRetiredPages
(nvmlDevice_t device, nvmlPageRetirementCause_t
cause, unsigned int *pageCount, unsigned long long
*addresses)
Parameters
device
The identifier of the target device
cause
Filter page addresses by cause of retirement
221
Modules
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
‣ NVML_SUCCESS if pageCount was populated and addresses was filled
‣ NVML_ERROR_INSUFFICIENT_SIZE if pageCount indicates the buffer is not large
enough to store all the matching page addresses. pageCount is set to the needed
size.
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, pageCount is NULL,
cause is invalid, or addresses is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Returns the list of retired pages by source, including pages that are pending retirement
The address information provided from this API is the hardware address of the page
that was retired. Note that this does not match the virtual address used in CUDA, but
will match the address information in Xid 63
For Kepler or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetRetiredPages_v2
(nvmlDevice_t device, nvmlPageRetirementCause_t
cause, unsigned int *pageCount, unsigned long long
*addresses, unsigned long long *timestamps)
Parameters
device
The identifier of the target device
cause
Filter page addresses by cause of retirement
222
Modules
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
‣ NVML_SUCCESS if pageCount was populated and addresses was filled
‣ NVML_ERROR_INSUFFICIENT_SIZE if pageCount indicates the buffer is not large
enough to store all the matching page addresses. pageCount is set to the needed
size.
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, pageCount is NULL,
cause is invalid, or addresses is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Returns the list of retired pages by source, including pages that are pending retirement
The address information provided from this API is the hardware address of the page
that was retired. Note that this does not match the virtual address used in CUDA, but
will match the address information in Xid 63
nvmlDeviceGetRetiredPages_v2 adds an additional timestamps parameter to return
the time of each page's retirement.
For Kepler or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetRetiredPagesPendingStatus
(nvmlDevice_t device, nvmlEnableState_t *isPending)
Parameters
device
The identifier of the target device
223
Modules
isPending
Reference in which to return the pending status
Returns
‣ NVML_SUCCESS if isPending was populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or isPending is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Check if any pages are pending retirement and need a reboot to fully retire.
For Kepler or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetRemappedRows
(nvmlDevice_t device, unsigned int *corrRows, unsigned
int *uncRows, unsigned int *isPending, unsigned int
*failureOccurred)
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
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_INVALID_ARGUMENT If corrRows, uncRows, isPending or
failureOccurred is invalid
224
Modules
‣ NVML_ERROR_NOT_SUPPORTED If MIG is enabled or if the device doesn't
support this feature
‣ NVML_ERROR_UNKNOWN Unexpected error
Description
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.
On MIG-enabled GPUs with active instances, querying the number of remapped rows is
not supported
For Ampere or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetRowRemapperHistogram
(nvmlDevice_t device,
nvmlRowRemapperHistogramValues_t *values)
Parameters
device
Device handle
values
Histogram values
Returns
‣ NVML_SUCCESS On success
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Get the row remapper histogram. Returns the remap availability for each bank on the
GPU.
225
Modules
nvmlReturn_t nvmlDeviceGetArchitecture
(nvmlDevice_t device, nvmlDeviceArchitecture_t *arch)
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
‣ NVML_SUCCESS Upon success
‣ NVML_ERROR_UNINITIALIZED If library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT If device or arch (output refererence) are
invalid
Description
Get architecture for device
nvmlReturn_t nvmlDeviceGetClkMonStatus
(nvmlDevice_t device, nvmlClkMonStatus_t *status)
Parameters
device
The identifier of the target device
status
Reference in which to return the clkmon fault status
Returns
‣ NVML_SUCCESS if status has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or status is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
226
Modules
Description
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()
nvmlReturn_t nvmlDeviceGetProcessUtilization
(nvmlDevice_t device, nvmlProcessUtilizationSample_t
*utilization, unsigned int *processSamplesCount,
unsigned long long lastSeenTimeStamp)
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
‣ NVML_SUCCESS if utilization has been populated
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, utilization is NULL, or
samplingPeriodUs is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_NOT_FOUND if sample entries are not found
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the current utilization and process ID
227
Modules
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.
On MIG-enabled GPUs, querying process utilization is not currently supported.
nvmlReturn_t nvmlDeviceGetProcessesUtilizationInfo
(nvmlDevice_t device, nvmlProcessesUtilizationInfo_t
*procesesUtilInfo)
Parameters
device
The identifier of the target device
procesesUtilInfo
Pointer to the caller-provided structure of nvmlProcessesUtilizationInfo_t.
Returns
‣ NVML_SUCCESS If procesesUtilInfo->procUtilArray has been populated
‣ NVML_ERROR_UNINITIALIZED If the library has not been successfully initialized
228
Modules
‣ NVML_ERROR_INVALID_ARGUMENT If device is invalid, or procesesUtilInfo is
NULL
‣ NVML_ERROR_NOT_SUPPORTED If the device does not support this feature
‣ NVML_ERROR_NOT_FOUND If sample entries are not found
‣ NVML_ERROR_GPU_IS_LOST If the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
procesesUtilInfo is invalid
‣ NVML_ERROR_INSUFFICIENT_SIZE If procesesUtilInfo->procUtilArray is
NULL, or the buffer size of procesesUtilInfo->procUtilArray is too small. The
caller should check the minimul array size from the returned procesesUtilInfo-
>processSamplesCount, and call the function again with a buffer no smaller than
procesesUtilInfo->processSamplesCount * sizeof(nvmlProcessUtilizationInfo_t)
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
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.
229
Modules
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.
On MIG-enabled GPUs, querying process utilization is not currently supported.
nvmlReturn_t nvmlDeviceGetPlatformInfo
(nvmlDevice_t device, nvmlPlatformInfo_t
*platformInfo)
Parameters
device
The identifier of the target device
platformInfo
Pointer to the caller-provided structure of nvmlPlatformInfo_t.
Returns
‣ NVML_SUCCESS If platformInfo has been retrieved
‣ NVML_ERROR_INVALID_ARGUMENT If device is invalid or platformInfo is
NULL
‣ NVML_ERROR_NOT_SUPPORTED If the device does not support this feature
‣ NVML_ERROR_MEMORY if system memory is insufficient
‣ NVML_ERROR_ARGUMENT_VERSION_MISMATCH If the version of
nvmlPlatformInfo_t is invalid
‣ NVML_ERROR_UNKNOWN On any unexpected error
Description
Get platform information of this device.
BLACKWELL_OR_NEWER%
See nvmlPlatformInfo_v2_t for more information on the struct.
4.16.1. CPU and Memory Affinity
Device Queries
This chapter describes NVML operations that are associated with CPU and memory
affinity.
230
Modules
nvmlReturn_t nvmlDeviceGetMemoryAffinity (nvmlDevice_t
device, unsigned int nodeSetSize, unsignedlong *nodeSet,
nvmlAffinityScope_t scope)
Parameters
device
The identifier of the target device
nodeSetSize
The size of the nodeSet array that is safe to access
nodeSet
Array reference in which to return a bitmask of NODEs, 64 NODEs per unsigned
long on 64-bit machines, 32 on 32-bit machines
scope
Scope that change the default behavior
Returns
‣ NVML_SUCCESS if NUMA node Affinity has been filled
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, nodeSetSize == 0,
nodeSet is NULL or scope is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves an array of unsigned ints (sized to nodeSetSize) of bitmasks with the ideal
memory affinity within node or socket for the device. For example, if NUMA node 0, 1
are ideal within the socket for the device and nodeSetSize == 1, result[0] = 0x3
If requested scope is not applicable to the target topology, the API will fall back to
reporting the memory affinity for the immediate non-I/O ancestor of the device.
For Kepler or newer fully supported devices. Supported on Linux only.
231
Modules
nvmlReturn_t nvmlDeviceGetCpuAffinityWithinScope (nvmlDevice_t
device, unsigned int cpuSetSize, unsignedlong *cpuSet,
nvmlAffinityScope_t scope)
Parameters
device
The identifier of the target device
cpuSetSize
The size of the cpuSet array that is safe to access
cpuSet
Array reference in which to return a bitmask of CPUs, 64 CPUs per unsigned long on
64-bit machines, 32 on 32-bit machines
scope
Scope that change the default behavior
Returns
‣ NVML_SUCCESS if cpuAffinity has been filled
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, cpuSetSize == 0, cpuSet
is NULL or sope is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves an array of unsigned ints (sized to cpuSetSize) of bitmasks with the ideal CPU
affinity within node or socket for the device. For example, if processors 0, 1, 32, and 33
are ideal for the device and cpuSetSize == 2, result[0] = 0x3, result[1] = 0x3
If requested scope is not applicable to the target topology, the API will fall back to
reporting the CPU affinity for the immediate non-I/O ancestor of the device.
For Kepler or newer fully supported devices. Supported on Linux only.
232
Modules
nvmlReturn_t nvmlDeviceGetCpuAffinity (nvmlDevice_t device,
unsigned int cpuSetSize, unsignedlong *cpuSet)
Parameters
device
The identifier of the target device
cpuSetSize
The size of the cpuSet array that is safe to access
cpuSet
Array reference in which to return a bitmask of CPUs, 64 CPUs per unsigned long on
64-bit machines, 32 on 32-bit machines
Returns
‣ NVML_SUCCESS if cpuAffinity has been filled
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, cpuSetSize == 0, or
cpuSet is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves an array of unsigned ints (sized to cpuSetSize) of bitmasks with the ideal
CPU affinity for the device For example, if processors 0, 1, 32, and 33 are ideal for the
device and cpuSetSize == 2, result[0] = 0x3, result[1] = 0x3 This is equivalent to calling
nvmlDeviceGetCpuAffinityWithinScope with NVML_AFFINITY_SCOPE_NODE.
For Kepler or newer fully supported devices. Supported on Linux only.
nvmlReturn_t nvmlDeviceSetCpuAffinity (nvmlDevice_t device)
Parameters
device
The identifier of the target device
Returns
‣ NVML_SUCCESS if the calling process has been successfully bound
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
233
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Sets the ideal affinity for the calling thread and device using the guidelines given in
nvmlDeviceGetCpuAffinity(). Note, this is a change as of version 8.0. Older versions
set the affinity for a calling process and all children. Currently supports up to 1024
processors.
For Kepler or newer fully supported devices. Supported on Linux only.
nvmlReturn_t nvmlDeviceClearCpuAffinity (nvmlDevice_t device)
Parameters
device
The identifier of the target device
Returns
‣ NVML_SUCCESS if the calling process has been successfully unbound
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Clear all affinity bindings for the calling thread. Note, this is a change as of version 8.0 as
older versions cleared the affinity for a calling process and all children.
For Kepler or newer fully supported devices. Supported on Linux only.
nvmlReturn_t nvmlDeviceGetNumaNodeId (nvmlDevice_t device,
unsigned int *node)
Parameters
device
The device handle
node
NUMA node ID of the device
234
Modules
Returns
‣ NVML_SUCCESS if the NUMA node is retrieved successfully
‣ NVML_ERROR_NOT_SUPPORTED if request is not supported on the current
platform
‣ NVML_ERROR_INVALID_ARGUMENT if device node is invalid
Description
Get the NUMA node of the given GPU device. This only applies to platforms where the
GPUs are NUMA nodes.
#define NVML_AFFINITY_SCOPE_NODE 0
Scope of NUMA node for affinity queries.
#define NVML_AFFINITY_SCOPE_SOCKET 1
Scope of processor socket for affinity queries.
4.17. Unit Commands
This chapter describes NVML operations that change the state of the unit. For S-class
products. Each of these requires root/admin access. Non-admin users will see an
NVML_ERROR_NO_PERMISSION error code when invoking any of these methods.
nvmlReturn_t nvmlUnitSetLedState (nvmlUnit_t unit,
nvmlLedColor_t color)
Parameters
unit
The identifier of the target unit
color
The target LED color
Returns
‣ NVML_SUCCESS if the LED color has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if unit or color is invalid
‣ NVML_ERROR_NOT_SUPPORTED if this is not an S-class product
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
235
Modules
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set the LED state for the unit. The LED can be either green (0) or amber (1).
For S-class products. Requires root/admin permissions.
This operation takes effect immediately.
Current S-Class products don't provide unique LEDs for each unit. As such, both
front and back LEDs will be toggled in unison regardless of which unit is specified
with this command.
See nvmlLedColor_t for available colors.
See also:
nvmlUnitGetLedState()
4.18. Device Commands
This chapter describes NVML operations that change the state of the device.
Each of these requires root/admin access. Non-admin users will see an
NVML_ERROR_NO_PERMISSION error code when invoking any of these methods.
nvmlReturn_t nvmlDeviceSetPersistenceMode
(nvmlDevice_t device, nvmlEnableState_t mode)
Parameters
device
The identifier of the target device
mode
The target persistence mode
Returns
‣ NVML_SUCCESS if the persistence mode was set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or mode is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
236
Modules
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set the persistence mode for the device.
For all products. For Linux only. Requires root/admin permissions.
The persistence mode determines whether the GPU driver software is torn down after
the last client exits.
This operation takes effect immediately. It is not persistent across reboots. After each
reboot the persistence mode is reset to "Disabled".
See nvmlEnableState_t for available modes.
After calling this API with mode set to NVML_FEATURE_DISABLED on a device that
has its own NUMA memory, the given device handle will no longer be valid, and to
continue to interact with this device, a new handle should be obtained from one of the
nvmlDeviceGetHandleBy*() APIs. This limitation is currently only applicable to devices
that have a coherent NVLink connection to system memory.
See also:
nvmlDeviceGetPersistenceMode()
nvmlReturn_t nvmlDeviceSetComputeMode
(nvmlDevice_t device, nvmlComputeMode_t mode)
Parameters
device
The identifier of the target device
mode
The target compute mode
Returns
‣ NVML_SUCCESS if the compute mode was set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or mode is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
237
Modules
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set the compute mode for the device.
For all products. Requires root/admin permissions.
The compute mode determines whether a GPU can be used for compute operations and
whether it can be shared across contexts.
This operation takes effect immediately. Under Linux it is not persistent across reboots
and always resets to "Default". Under windows it is persistent.
Under windows compute mode may only be set to DEFAULT when running in WDDM
On MIG-enabled GPUs, compute mode would be set to DEFAULT and changing it is not
supported.
See nvmlComputeMode_t for details on available compute modes.
See also:
nvmlDeviceGetComputeMode()
nvmlReturn_t nvmlDeviceSetEccMode (nvmlDevice_t
device, nvmlEnableState_t ecc)
Parameters
device
The identifier of the target device
ecc
The target ECC mode
Returns
‣ NVML_SUCCESS if the ECC mode was set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or ecc is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
238
Modules
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set the ECC mode for the device.
For Kepler or newer fully supported devices. Only applicable to devices with ECC.
Requires NVML_INFOROM_ECC version 1.0 or higher. Requires root/admin
permissions.
The ECC mode determines whether the GPU enables its ECC support.
This operation takes effect after the next reboot.
See nvmlEnableState_t for details on available modes.
See also:
nvmlDeviceGetEccMode()
nvmlReturn_t nvmlDeviceClearEccErrorCounts
(nvmlDevice_t device, nvmlEccCounterType_t
counterType)
Parameters
device
The identifier of the target device
counterType
Flag that indicates which type of errors should be cleared.
Returns
‣ NVML_SUCCESS if the error counts were cleared
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or counterType is
invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
239
Modules
Description
Clear the ECC error and other memory error counts for the device.
For Kepler or newer fully supported devices. Only applicable to devices with ECC.
Requires NVML_INFOROM_ECC version 2.0 or higher to clear aggregate location-based
ECC counts. Requires NVML_INFOROM_ECC version 1.0 or higher to clear all other
ECC counts. Requires root/admin permissions. Requires ECC Mode to be enabled.
Sets all of the specified ECC counters to 0, including both detailed and total counts.
This operation takes effect immediately.
See nvmlMemoryErrorType_t for details on available counter types.
See also:
‣ nvmlDeviceGetDetailedEccErrors()
‣ nvmlDeviceGetTotalEccErrors()
nvmlReturn_t nvmlDeviceSetDriverModel (nvmlDevice_t
device, nvmlDriverModel_t driverModel, unsigned int
flags)
Parameters
device
The identifier of the target device
driverModel
The target driver model
flags
Flags that change the default behavior
Returns
‣ NVML_SUCCESS if the driver model has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or driverModel is
invalid
‣ NVML_ERROR_NOT_SUPPORTED if the platform is not windows or the device
does not support this feature
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
240
Modules
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set the driver model for the device.
For Fermi or newer fully supported devices. For windows only. Requires root/admin
permissions.
On Windows platforms the device driver can run in either WDDM or WDM (TCC)
mode. If a display is attached to the device it must run in WDDM mode.
It is possible to force the change to WDM (TCC) while the display is still attached with a
force flag (nvmlFlagForce). This should only be done if the host is subsequently powered
down and the display is detached from the device before the next reboot.
This operation takes effect after the next reboot.
Windows driver model may only be set to WDDM when running in DEFAULT compute
mode.
Change driver model to WDDM is not supported when GPU doesn't support graphics
acceleration or will not support it after reboot. See nvmlDeviceSetGpuOperationMode.
See nvmlDriverModel_t for details on available driver models. See nvmlFlagDefault and
nvmlFlagForce
See also:
nvmlDeviceGetDriverModel()
nvmlReturn_t nvmlDeviceSetGpuLockedClocks
(nvmlDevice_t device, unsigned int minGpuClockMHz,
unsigned int maxGpuClockMHz)
Parameters
device
The identifier of the target device
minGpuClockMHz
Requested minimum gpu clock in MHz
maxGpuClockMHz
Requested maximum gpu clock in MHz
Returns
‣ NVML_SUCCESS if new settings were successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
241
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or minGpuClockMHz
and maxGpuClockMHz is not a valid clock combination
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set clocks that device will lock to.
Sets the clocks that the device will be running at to the value in the range of
minGpuClockMHz to maxGpuClockMHz. Setting this will supersede application
clock values and take effect regardless if a cuda app is running. See /ref
nvmlDeviceSetApplicationsClocks
Can be used as a setting to request constant performance.
This can be called with a pair of integer clock frequencies in MHz, or a pair of /ref
nvmlClockLimitId_t values. See the table below for valid combinations of these values.
minGpuClock | maxGpuClock | Effect ------------+-------------
+-------------------------------------------------- tdp | tdp | Lock clock to TDP unlimited |
tdp | Upper bound is TDP but clock may drift below this tdp | unlimited | Lower
bound is TDP but clock may boost above this unlimited | unlimited | Unlocked (==
nvmlDeviceResetGpuLockedClocks)
If one arg takes one of these values, the other must be one of these values as well. Mixed
numeric and symbolic calls return NVML_ERROR_INVALID_ARGUMENT.
Requires root/admin permissions.
After system reboot or driver reload applications clocks go back to their default value.
See nvmlDeviceResetGpuLockedClocks.
For Volta or newer fully supported devices.
nvmlReturn_t nvmlDeviceResetGpuLockedClocks
(nvmlDevice_t device)
Parameters
device
The identifier of the target device
242
Modules
Returns
‣ NVML_SUCCESS if new settings were successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Resets the gpu clock to the default value
This is the gpu clock that will be used after system reboot or driver reload.
Default values are idle clocks, but the current values can be changed using
nvmlDeviceSetApplicationsClocks.
See also:
nvmlDeviceSetGpuLockedClocks
For Volta or newer fully supported devices.
nvmlReturn_t nvmlDeviceSetMemoryLockedClocks
(nvmlDevice_t device, unsigned int minMemClockMHz,
unsigned int maxMemClockMHz)
Parameters
device
The identifier of the target device
minMemClockMHz
Requested minimum memory clock in MHz
maxMemClockMHz
Requested maximum memory clock in MHz
Returns
‣ NVML_SUCCESS if new settings were successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or minGpuClockMHz
and maxGpuClockMHz is not a valid clock combination
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
243
Modules
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set memory clocks that device will lock to.
Sets the device's memory clocks to the value in the range of minMemClockMHz to
maxMemClockMHz. Setting this will supersede application clock values and take effect
regardless of whether a cuda app is running. See /ref nvmlDeviceSetApplicationsClocks
Can be used as a setting to request constant performance.
Requires root/admin permissions.
After system reboot or driver reload applications clocks go back to their default value.
See nvmlDeviceResetMemoryLockedClocks.
For Ampere or newer fully supported devices.
nvmlReturn_t nvmlDeviceResetMemoryLockedClocks
(nvmlDevice_t device)
Parameters
device
The identifier of the target device
Returns
‣ NVML_SUCCESS if new settings were successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Resets the memory clock to the default value
This is the memory clock that will be used after system reboot or driver reload.
Default values are idle clocks, but the current values can be changed using
nvmlDeviceSetApplicationsClocks.
244
Modules
See also:
nvmlDeviceSetMemoryLockedClocks
For Ampere or newer fully supported devices.
nvmlReturn_t nvmlDeviceSetApplicationsClocks
(nvmlDevice_t device, unsigned int memClockMHz,
unsigned int graphicsClockMHz)
Parameters
device
The identifier of the target device
memClockMHz
Requested memory clock in MHz
graphicsClockMHz
Requested graphics clock in MHz
Returns
‣ NVML_SUCCESS if new settings were successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or memClockMHz and
graphicsClockMHz is not a valid clock combination
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Set clocks that applications will lock to.
Sets the clocks that compute and graphics applications will be running at. e.g. CUDA
driver requests these clocks during context creation which means this property defines
clocks at which CUDA applications will be running unless some overspec event occurs
(e.g. over power, over thermal or external HW brake).
Can be used as a setting to request constant performance.
On Pascal and newer hardware, this will automatically disable automatic boosting of
clocks.
245
Modules
On K80 and newer Kepler and Maxwell GPUs, users desiring fixed performance
should also call nvmlDeviceSetAutoBoostedClocksEnabled to prevent clocks from
automatically boosting above the clock value being set.
For Kepler or newer non-GeForce fully supported devices and Maxwell or newer
GeForce devices. Requires root/admin permissions.
See nvmlDeviceGetSupportedMemoryClocks and
nvmlDeviceGetSupportedGraphicsClocks for details on how to list available clocks
combinations.
After system reboot or driver reload applications clocks go back to their default value.
See nvmlDeviceResetApplicationsClocks.
nvmlReturn_t nvmlDeviceResetApplicationsClocks
(nvmlDevice_t device)
Parameters
device
The identifier of the target device
Returns
‣ NVML_SUCCESS if new settings were successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Resets the application clock to the default value
This is the applications clock that will be used after system reboot or driver
reload. Default value is constant, but the current value an be changed using
nvmlDeviceSetApplicationsClocks.
On Pascal and newer hardware, if clocks were previously locked with
nvmlDeviceSetApplicationsClocks, this call will unlock clocks. This returns clocks their
default behavior ofautomatically boosting above base clocks as thermal limits allow.
See also:
nvmlDeviceGetApplicationsClock
246
Modules
nvmlDeviceSetApplicationsClocks
For Fermi or newer non-GeForce fully supported devices and Maxwell or newer
GeForce devices.
nvmlReturn_t nvmlDeviceSetAutoBoostedClocksEnabled
(nvmlDevice_t device, nvmlEnableState_t enabled)
Parameters
device
The identifier of the target device
enabled
What state to try to set Auto Boosted clocks of the target device to
Returns
‣ NVML_SUCCESS If the Auto Boosted clocks were successfully set to the state
specified by enabled
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support Auto Boosted
clocks
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Try to set the current state of Auto Boosted clocks on a device.
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. Auto Boosted
clocks should be disabled if fixed clock rates are desired.
Non-root users may use this API by default but can be restricted by
root from using this API by calling nvmlDeviceSetAPIRestriction with
apiType=NVML_RESTRICTED_API_SET_AUTO_BOOSTED_CLOCKS. Note:
Persistence Mode is required to modify current Auto Boost settings, therefore, it must be
enabled.
On Pascal and newer hardware, Auto Boosted clocks are controlled through application
clocks. Use nvmlDeviceSetApplicationsClocks and nvmlDeviceResetApplicationsClocks
to control Auto Boost behavior.
247
Modules
nvmlReturn_t
nvmlDeviceSetDefaultAutoBoostedClocksEnabled
(nvmlDevice_t device, nvmlEnableState_t enabled,
unsigned int flags)
Parameters
device
The identifier of the target device
enabled
What state to try to set default Auto Boosted clocks of the target device to
flags
Flags that change the default behavior. Currently Unused.
Returns
‣ NVML_SUCCESS If the Auto Boosted clock's default state was successfully set to
the state specified by enabled
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_NO_PERMISSION If the calling user does not have permission to
change Auto Boosted clock's default state.
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support Auto Boosted
clocks
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Try to set the default state of Auto Boosted clocks on a device. This is the default state
that Auto Boosted clocks will return to when no compute running processes (e.g. CUDA
application which have an active context) are running
For Kepler or newer non-GeForce fully supported devices and Maxwell or newer
GeForce devices. Requires root/admin permissions.
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. Auto Boosted
clocks should be disabled if fixed clock rates are desired.
On Pascal and newer hardware, Auto Boosted clocks are controlled through application
clocks. Use nvmlDeviceSetApplicationsClocks and nvmlDeviceResetApplicationsClocks
to control Auto Boost behavior.
248
Modules
nvmlReturn_t nvmlDeviceSetDefaultFanSpeed_v2
(nvmlDevice_t device, unsigned int fan)
Parameters
device
The identifier of the target device
fan
The index of the fan, starting at zero
Description
Sets the speed of the fan control policy to default.
For all cuda-capable discrete products with fans
return NVML_SUCCESS if speed has been adjusted
NVML_ERROR_UNINITIALIZED if the library has not been successfully
initialized NVML_ERROR_INVALID_ARGUMENT if device is invalid
NVML_ERROR_NOT_SUPPORTED if the device does not support this (doesn't have
fans) NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t nvmlDeviceSetFanControlPolicy
(nvmlDevice_t device, unsigned int fan,
nvmlFanControlPolicy_t policy)
Description
Sets current fan control policy.
For Maxwell or newer fully supported devices.
Requires privileged user.
For all cuda-capable discrete products with fans
device The identifier of the target device policy The fan control policy to set
return NVML_SUCCESS if policy has been set NVML_ERROR_UNINITIALIZED if the
library has not been successfully initialized NVML_ERROR_INVALID_ARGUMENT
if device is invalid or policy is null or the fan given doesn't reference a fan that
exists. NVML_ERROR_NOT_SUPPORTED if the device is older than Maxwell
NVML_ERROR_UNKNOWN on any unexpected error
249
Modules
nvmlReturn_t nvmlDeviceSetTemperatureThreshold
(nvmlDevice_t device, nvmlTemperatureThresholds_t
thresholdType, int *temp)
Parameters
device
The identifier of the target device
thresholdType
The type of threshold value to be set
temp
Reference which hold the value to be set
Returns
‣ NVML_SUCCESS if temp has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid, thresholdType is
invalid or temp is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not have a temperature
sensor or is unsupported
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Sets the temperature threshold for the GPU with the specified threshold type in degrees
C.
For Maxwell or newer fully supported devices.
See nvmlTemperatureThresholds_t for details on available temperature thresholds.
nvmlReturn_t nvmlDeviceSetPowerManagementLimit
(nvmlDevice_t device, unsigned int limit)
Parameters
device
The identifier of the target device
limit
Power management limit in milliwatts to set
250
Modules
Returns
‣ NVML_SUCCESS if limit has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or defaultLimit is out of
range
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
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.
Limit is not persistent across reboots or driver unloads. Enable persistent mode to
prevent driver from unloading when no application is using the device.
See also:
nvmlDeviceGetPowerManagementLimitConstraints
nvmlDeviceGetPowerManagementDefaultLimit
nvmlReturn_t nvmlDeviceSetGpuOperationMode
(nvmlDevice_t device, nvmlGpuOperationMode_t mode)
Parameters
device
The identifier of the target device
mode
Target GOM
Returns
‣ NVML_SUCCESS if mode has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or mode incorrect
251
Modules
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support GOM or specific
mode
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Sets new GOM. See nvmlGpuOperationMode_t for details.
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. Requires root/
admin permissions.
Changing GOMs requires a reboot. The reboot requirement might be removed in the
future.
Compute only GOMs don't support graphics acceleration. Under windows switching
to these GOMs when pending driver model is WDDM is not supported. See
nvmlDeviceSetDriverModel.
See also:
nvmlGpuOperationMode_t
nvmlDeviceGetGpuOperationMode
nvmlReturn_t nvmlDeviceSetAPIRestriction
(nvmlDevice_t device, nvmlRestrictedAPI_t apiType,
nvmlEnableState_t isRestricted)
Parameters
device
The identifier of the target device
apiType
Target API type for this operation
isRestricted
The target restriction
Returns
‣ NVML_SUCCESS if isRestricted has been set
252
Modules
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or apiType incorrect
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support changing API
restrictions or the device does not support the feature that api restrictions are being
set for (E.G. Enabling/disabling auto boosted clocks is not supported by the device)
‣ NVML_ERROR_NO_PERMISSION if the user doesn't have permission to perform
this operation
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Changes the root/admin restructions on certain APIs. See nvmlRestrictedAPI_t for the
list of supported APIs. This method can be used by a root/admin user to give non-root/
admin access to certain otherwise-restricted APIs. The new setting lasts for the lifetime
of the NVIDIA driver; it is not persistent. See nvmlDeviceGetAPIRestriction to query the
current restriction settings.
For Kepler or newer fully supported devices. Requires root/admin permissions.
See also:
nvmlRestrictedAPI_t
nvmlReturn_t nvmlDeviceSetFanSpeed_v2
(nvmlDevice_t device, unsigned int fan, unsigned int
speed)
Description
Sets the speed of a specified fan.
WARNING: This function changes the fan control policy to manual. It means that YOU
have to monitor the temperature and adjust the fan speed accordingly. If you set the
fan speed too low you can burn your GPU! Use nvmlDeviceSetDefaultFanSpeed_v2 to
restore default control policy.
For all cuda-capable discrete products with fans that are Maxwell or Newer.
device The identifier of the target device fan The index of the fan, starting at zero speed
The target speed of the fan [0-100] in % of max speed
return NVML_SUCCESS if the fan speed has been set
NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
NVML_ERROR_INVALID_ARGUMENT if the device is not valid, or the speed
253
Modules
is outside acceptable ranges, or if the fan index doesn't reference an actual
fan. NVML_ERROR_NOT_SUPPORTED if the device is older than Maxwell.
NVML_ERROR_UNKNOWN if there was an unexpected error.
nvmlReturn_t nvmlDeviceSetGpcClkVfOffset
(nvmlDevice_t device, int offset)
Parameters
device
The identifier of the target device
offset
The GPCCLK VF offset value to set
Returns
‣ NVML_SUCCESS if offset has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or offset is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Deprecated: Will be deprecated in a future release. Use nvmlDeviceSetClockOffsets
instead. It works on Maxwell onwards GPU architectures.
Set the GPCCLK VF offset value
nvmlReturn_t nvmlDeviceSetMemClkVfOffset
(nvmlDevice_t device, int offset)
Parameters
device
The identifier of the target device
offset
The MemClk VF offset value to set
Returns
‣ NVML_SUCCESS if offset has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
254
Modules
‣ NVML_ERROR_INVALID_ARGUMENT if device is invalid or offset is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device does not support this feature
‣ NVML_ERROR_GPU_IS_LOST if the target GPU has fallen off the bus or is
otherwise inaccessible
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Deprecated: Will be deprecated in a future release. Use nvmlDeviceSetClockOffsets
instead. It works on Maxwell onwards GPU architectures.
Set the MemClk (Memory Clock) VF offset value. It requires elevated privileges.
4.19. NvLink Methods
This chapter describes methods that NVML can perform on NVLINK enabled devices.
nvmlReturn_t nvmlDeviceGetNvLinkState (nvmlDevice_t
device, unsigned int link, nvmlEnableState_t *isActive)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
isActive
nvmlEnableState_t where NVML_FEATURE_ENABLED indicates that the link is
active and NVML_FEATURE_DISABLED indicates it is inactive
Returns
‣ NVML_SUCCESS if isActive has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device or link is invalid or isActive is
NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the state of the device's NvLink for the link specified
For Pascal or newer fully supported devices.
255
Modules
nvmlReturn_t nvmlDeviceGetNvLinkVersion
(nvmlDevice_t device, unsigned int link, unsigned int
*version)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
version
Requested NvLink version from nvmlNvlinkVersion_t
Returns
‣ NVML_SUCCESS if version has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device or link is invalid or version is
NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the version of the device's NvLink for the link specified
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetNvLinkCapability
(nvmlDevice_t device, unsigned int link,
nvmlNvLinkCapability_t capability, unsigned int
*capResult)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
capability
Specifies the nvmlNvLinkCapability_t to be queried
256
Modules
capResult
A boolean for the queried capability indicating that feature is available
Returns
‣ NVML_SUCCESS if capResult has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, link, or capability is invalid or
capResult is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the requested capability from the device's NvLink for the link specified Please
refer to the nvmlNvLinkCapability_t structure for the specific caps that can be queried
The return value should be treated as a boolean.
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetNvLinkRemotePciInfo_v2
(nvmlDevice_t device, unsigned int link, nvmlPciInfo_t
*pci)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
pci
nvmlPciInfo_t of the remote node for the specified link
Returns
‣ NVML_SUCCESS if pci has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device or link is invalid or pci is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
257
Modules
Description
Retrieves the PCI information for the remote node on a NvLink link Note:
pciSubSystemId is not filled in this function and is indeterminate
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetNvLinkErrorCounter
(nvmlDevice_t device, unsigned int link,
nvmlNvLinkErrorCounter_t counter, unsigned long long
*counterValue)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
counter
Specifies the NvLink counter to be queried
counterValue
Returned counter value
Returns
‣ NVML_SUCCESS if counter has been set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, link, or counter is invalid or
counterValue is NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Retrieves the specified error counter value Please refer to nvmlNvLinkErrorCounter_t
for error counters that are available
For Pascal or newer fully supported devices.
258
Modules
nvmlReturn_t nvmlDeviceResetNvLinkErrorCounters
(nvmlDevice_t device, unsigned int link)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
Returns
‣ NVML_SUCCESS if the reset is successful
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device or link is invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Resets all error counters to zero Please refer to nvmlNvLinkErrorCounter_t for the list of
error counters that are reset
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceSetNvLinkUtilizationControl
(nvmlDevice_t device, unsigned int link, unsigned
int counter, nvmlNvLinkUtilizationControl_t *control,
unsigned int reset)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
counter
Specifies the counter that should be set (0 or 1).
control
A reference to the nvmlNvLinkUtilizationControl_t to set
reset
Resets the counters on set if non-zero
259
Modules
Returns
‣ NVML_SUCCESS if the control has been set successfully
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, counter, link, or control is
invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Deprecated: Setting utilization counter control is no longer supported.
Set the NVLINK utilization counter control information for the specified counter, 0 or 1.
Please refer to nvmlNvLinkUtilizationControl_t for the structure definition. Performs a
reset of the counters if the reset parameter is non-zero.
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetNvLinkUtilizationControl
(nvmlDevice_t device, unsigned int link, unsigned int
counter, nvmlNvLinkUtilizationControl_t *control)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
counter
Specifies the counter that should be set (0 or 1).
control
A reference to the nvmlNvLinkUtilizationControl_t to place information
Returns
‣ NVML_SUCCESS if the control has been set successfully
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, counter, link, or control is
invalid
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
260
Modules
Description
Deprecated: Getting utilization counter control is no longer supported.
Get the NVLINK utilization counter control information for the specified counter, 0 or 1.
Please refer to nvmlNvLinkUtilizationControl_t for the structure definition
For Pascal or newer fully supported devices.
nvmlReturn_t nvmlDeviceGetNvLinkUtilizationCounter
(nvmlDevice_t device, unsigned int link, unsigned int
counter, unsigned long long *rxcounter, unsigned long
long *txcounter)
Parameters
device
The identifier of the target device
link
Specifies the NvLink link to be queried
counter
Specifies the counter that should be read (0 or 1).
rxcounter
Receive counter return value
txcounter
Transmit counter return value
Returns
‣ NVML_SUCCESS if rxcounter and txcounter have been successfully set
‣ NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
‣ NVML_ERROR_INVALID_ARGUMENT if device, counter, or link is invalid or
rxcounter or txcounter are NULL
‣ NVML_ERROR_NOT_SUPPORTED if the device doesn't support this feature
‣ NVML_ERROR_UNKNOWN on any unexpected error
Description
Deprecated: Use nvmlDeviceGetFieldValues with
NVML_FI_DEV_NVLINK_THROUGHPUT_* as field values instead.
Retrieve the NVLINK utilization counter based on the current control for a specified
counter. In general it is good practice to use nvmlDeviceSetNvLinkUtilizationControl
before reading the utilization counters as they have no default state
261
|
||
|
|
|