System Queries

This chapter describes the queries that NVML can perform against the local system.

These queries are not device-specific.

Macros

NVML_CUDA_DRIVER_VERSION_MAJOR

Macros for converting the CUDA driver version number to Major and Minor version numbers.

NVML_CUDA_DRIVER_VERSION_MINOR

Macro to extract the minor version number from the CUDA driver version.

nvmlSystemDriverBranchInfo_v1

Version macro for nvmlSystemDriverBranchInfo_v1_t .

Functions

nvmlReturn_t nvmlSystemGetCPER_v1(nvmlGetCPER_v1_t *cper)

Retrieves Common Platform Error Record (CPER) data.

nvmlReturn_t nvmlSystemGetCudaDriverVersion(int *cudaDriverVersion)

Retrieves the version of the CUDA driver.

nvmlReturn_t nvmlSystemGetCudaDriverVersion_v2(int *cudaDriverVersion)

Retrieves the version of the CUDA driver from the shared library.

nvmlReturn_t nvmlSystemGetDriverBranch(nvmlSystemDriverBranchInfo_t *branchInfo, unsigned int length)

Retrieves the driver branch of the NVIDIA driver installed on the system.

nvmlReturn_t nvmlSystemGetDriverVersion(char *version, unsigned int length)

Retrieves the version of the system's graphics driver.

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

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

nvmlReturn_t nvmlSystemGetNVMLVersion(char *version, unsigned int length)

Retrieves the version of the NVML library.

nvmlReturn_t nvmlSystemGetProcessName(unsigned int pid, char *name, unsigned int length)

Gets name of the process with provided process id.

nvmlReturn_t nvmlSystemGetTopologyGpuSet(unsigned int cpuNumber, unsigned int *count, nvmlDevice_t *deviceArray)

Retrieve the set of GPUs that have a CPU affinity with the given CPU number For all products.

Structs

nvmlSystemDriverBranchInfo_v1_t

Structure to store Driver branch information.

Typedefs

nvmlSystemDriverBranchInfo_t

Macros

NVML_CUDA_DRIVER_VERSION_MAJOR(v)

Macros for converting the CUDA driver version number to Major and Minor version numbers.

Macro to extract the major version number from the CUDA driver version.

NVML_CUDA_DRIVER_VERSION_MINOR(v)

Macro to extract the minor version number from the CUDA driver version.

nvmlSystemDriverBranchInfo_v1

Version macro for nvmlSystemDriverBranchInfo_v1_t.

Functions

nvmlReturn_t nvmlSystemGetCPER_v1(nvmlGetCPER_v1_t *cper)

Retrieves Common Platform Error Record (CPER) data.

Records are returned in a caller-supplied buffer. Iteration is driven by the cursor (nvmlCPERCursor_v1_t) struct: pass the same cursor on every call in a sequence; the implementation updates cursor.handle. Do not modify cursor between calls. To change cursor.cperTypeMask or cursor.uuid, set cursor.handle to NVML_CPER_CURSOR_HANDLE_INIT and call again (new iteration).

For a size query, call with buffer NULL and bufferSize 0; the function returns NVML_ERROR_INSUFFICIENT_SIZE and sets bufferSize when records exist, or NVML_SUCCESS with bufferSize set to 0 when there are no CPER records. Use bufferSize == 0 on return as the indicator for “no records” or “no more records”.

This API requires root privileges. Records are available from initialization.

Parameters:

cper – Pointer to an nvmlGetCPER_v1_t. On entry set cursor.cperTypeMask, cursor.uuid (empty string for all), cursor.handle (to NVML_CPER_CURSOR_HANDLE_INIT for first call), buffer (or NULL), bufferSize. On return cursor.handle and bufferSize are updated.

Returns:

• NVML_SUCCESS Buffer has been populated with CPER data, or bufferSize is 0 (no/more records).

• NVML_ERROR_UNINITIALIZED The library has not been successfully initialized.

• NVML_ERROR_INVALID_ARGUMENT cper is NULL, or buffer is NULL while bufferSize is non-zero.

• NVML_ERROR_NOT_SUPPORTED The feature is not supported on this system.

• NVML_ERROR_INSUFFICIENT_SIZE Buffer too small; bufferSize set to required size.

• NVML_ERROR_NO_PERMISSION Insufficient privileges.

• NVML_ERROR_UNKNOWN An unexpected error occurred.

nvmlReturn_t nvmlSystemGetCudaDriverVersion(int *cudaDriverVersion)

Retrieves the version of the CUDA driver.

For all products.

The CUDA driver version returned will be retreived from the currently installed version of CUDA. If the cuda library is not found, this function will return a known supported version number.

Parameters:

cudaDriverVersion – Reference in which to return the version identifier

Returns:

• NVML_SUCCESS if cudaDriverVersion has been set

• NVML_ERROR_INVALID_ARGUMENT if cudaDriverVersion is NULL

nvmlReturn_t nvmlSystemGetCudaDriverVersion_v2(

int *cudaDriverVersion,

)

Retrieves the version of the CUDA driver from the shared library.

For all products.

The returned CUDA driver version by calling cuDriverGetVersion()

Parameters:

cudaDriverVersion – Reference in which to return the version identifier

Returns:

• NVML_SUCCESS if cudaDriverVersion has been set

• NVML_ERROR_INVALID_ARGUMENT if cudaDriverVersion is NULL

• NVML_ERROR_LIBRARY_NOT_FOUND if libcuda.so.1 or libcuda.dll is not found

• NVML_ERROR_FUNCTION_NOT_FOUND if cuDriverGetVersion() is not found in the shared library

nvmlReturn_t nvmlSystemGetDriverBranch(

nvmlSystemDriverBranchInfo_t *branchInfo,

unsigned int length,

)

Retrieves the driver branch of the NVIDIA driver installed on the system.

For all products.

The branch identifier is an alphanumeric string. It will not exceed 80 characters in length (including the NULL terminator). See nvmlConstants::NVML_SYSTEM_DRIVER_VERSION_BUFFER_SIZE.

Parameters:

• branchInfo – Pointer to the driver branch information structure nvmlSystemDriverBranchInfo_t

• length – The maximum allowed length of the driver branch string

Returns:

• NVML_SUCCESS successful completion

• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized

• NVML_ERROR_INVALID_ARGUMENT if branchInfo is NULL

• NVML_ERROR_INSUFFICIENT_SIZE if length is too small

• NVML_ERROR_UNKNOWN on any unexpected error

nvmlReturn_t nvmlSystemGetDriverVersion(

char *version,

unsigned int length,

)

Retrieves the version of the system’s graphics driver.

For all products.

The version identifier is an alphanumeric string. It will not exceed 80 characters in length (including the NULL terminator). See nvmlConstants::NVML_SYSTEM_DRIVER_VERSION_BUFFER_SIZE.

Parameters:

• version – Reference in which to return the version identifier

• 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 version is NULL

• NVML_ERROR_INSUFFICIENT_SIZE if length is too small

nvmlReturn_t nvmlSystemGetHicVersion(

unsigned int *hwbcCount,

nvmlHwbcEntry_t *hwbcEntries,

)

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

For S-class products.

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

Parameters:

• hwbcCount – Size of hwbcEntries array

• hwbcEntries – Array holding information about hwbc

Returns:

• NVML_SUCCESS if hwbcCount and hwbcEntries have been populated

• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized

• NVML_ERROR_INVALID_ARGUMENT if either hwbcCount or hwbcEntries is NULL

• NVML_ERROR_INSUFFICIENT_SIZE if hwbcCount indicates that the hwbcEntries array is too small

nvmlReturn_t nvmlSystemGetNVMLVersion(

char *version,

unsigned int length,

)

Retrieves the version of the NVML library.

For all products.

The version identifier is an alphanumeric string. It will not exceed 80 characters in length (including the NULL terminator). See nvmlConstants::NVML_SYSTEM_NVML_VERSION_BUFFER_SIZE.

Parameters:

• version – Reference in which to return the version identifier

• length – The maximum allowed length of the string returned in version

Returns:

• NVML_SUCCESS if version has been set

• NVML_ERROR_INVALID_ARGUMENT if version is NULL

• NVML_ERROR_INSUFFICIENT_SIZE if length is too small

nvmlReturn_t nvmlSystemGetProcessName(

unsigned int pid,

char *name,

unsigned int length,

)

Gets name of the process with provided process id.

For all products.

Returned process name is cropped to provided length. name string is encoded in ANSI.

Parameters:

• pid – The identifier of the process

• name – Reference in which to return the process name

• length – The maximum allowed length of the string returned in name

Returns:

• NVML_SUCCESS if name has been set

• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized

• NVML_ERROR_INVALID_ARGUMENT if name is NULL or length is 0.

• NVML_ERROR_NOT_FOUND if process doesn’t exists

• NVML_ERROR_NO_PERMISSION if the user doesn’t have permission to perform this operation

• NVML_ERROR_UNKNOWN on any unexpected error

nvmlReturn_t nvmlSystemGetTopologyGpuSet(

unsigned int cpuNumber,

unsigned int *count,

nvmlDevice_t *deviceArray,

)

Retrieve the set of GPUs that have a CPU affinity with the given CPU number For all products.

Supported on Linux only.

Parameters:

• cpuNumber – The CPU number

• count – When zero, is set to the number of matching GPUs such that deviceArray can be malloc’d. When non-zero, deviceArray will be filled with count number of device handles.

• deviceArray – An array of device handles for GPUs found with affinity to cpuNumber

Returns:

• NVML_SUCCESS if deviceArray or count (if initially zero) has been set

• NVML_ERROR_INVALID_ARGUMENT if cpuNumber, or count is invalid, or deviceArray is NULL with a non-zero count

• NVML_ERROR_NOT_SUPPORTED if the device or OS does not support this feature

• NVML_ERROR_UNKNOWN an error has occurred in underlying topology discovery

Typedefs

typedef nvmlSystemDriverBranchInfo_v1_t nvmlSystemDriverBranchInfo_t