Provided by: nvidia-cuda-dev_10.1.243-3_amd64 
NAME
vGPU Management -
Functions
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedVgpus (nvmlDevice_t device, unsigned int *vgpuCount,
nvmlVgpuTypeId_t *vgpuTypeIds)
nvmlReturn_t DECLDIR nvmlDeviceGetCreatableVgpus (nvmlDevice_t device, unsigned int *vgpuCount,
nvmlVgpuTypeId_t *vgpuTypeIds)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetClass (nvmlVgpuTypeId_t vgpuTypeId, char *vgpuTypeClass, unsigned int
*size)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetName (nvmlVgpuTypeId_t vgpuTypeId, char *vgpuTypeName, unsigned int
*size)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetDeviceID (nvmlVgpuTypeId_t vgpuTypeId, unsigned long long *deviceID,
unsigned long long *subsystemID)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetFramebufferSize (nvmlVgpuTypeId_t vgpuTypeId, unsigned long long
*fbSize)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetNumDisplayHeads (nvmlVgpuTypeId_t vgpuTypeId, unsigned int
*numDisplayHeads)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetResolution (nvmlVgpuTypeId_t vgpuTypeId, unsigned int displayIndex,
unsigned int *xdim, unsigned int *ydim)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetLicense (nvmlVgpuTypeId_t vgpuTypeId, char *vgpuTypeLicenseString,
unsigned int size)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetFrameRateLimit (nvmlVgpuTypeId_t vgpuTypeId, unsigned int
*frameRateLimit)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetMaxInstances (nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId,
unsigned int *vgpuInstanceCount)
nvmlReturn_t DECLDIR nvmlVgpuTypeGetMaxInstancesPerVm (nvmlVgpuTypeId_t vgpuTypeId, unsigned int
*vgpuInstanceCountPerVm)
nvmlReturn_t DECLDIR nvmlDeviceGetActiveVgpus (nvmlDevice_t device, unsigned int *vgpuCount,
nvmlVgpuInstance_t *vgpuInstances)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetVmID (nvmlVgpuInstance_t vgpuInstance, char *vmId, unsigned int
size, nvmlVgpuVmIdType_t *vmIdType)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetUUID (nvmlVgpuInstance_t vgpuInstance, char *uuid, unsigned int
size)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetVmDriverVersion (nvmlVgpuInstance_t vgpuInstance, char *version,
unsigned int length)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFbUsage (nvmlVgpuInstance_t vgpuInstance, unsigned long long
*fbUsage)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetLicenseStatus (nvmlVgpuInstance_t vgpuInstance, unsigned int
*licensed)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetType (nvmlVgpuInstance_t vgpuInstance, nvmlVgpuTypeId_t
*vgpuTypeId)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFrameRateLimit (nvmlVgpuInstance_t vgpuInstance, unsigned int
*frameRateLimit)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetEncoderCapacity (nvmlVgpuInstance_t vgpuInstance, unsigned int
*encoderCapacity)
nvmlReturn_t DECLDIR nvmlVgpuInstanceSetEncoderCapacity (nvmlVgpuInstance_t vgpuInstance, unsigned int
encoderCapacity)
nvmlReturn_t DECLDIR nvmlDeviceGetVgpuUtilization (nvmlDevice_t device, unsigned long long
lastSeenTimeStamp, nvmlValueType_t *sampleValType, unsigned int *vgpuInstanceSamplesCount,
nvmlVgpuInstanceUtilizationSample_t *utilizationSamples)
nvmlReturn_t DECLDIR nvmlDeviceGetVgpuProcessUtilization (nvmlDevice_t device, unsigned long long
lastSeenTimeStamp, unsigned int *vgpuProcessSamplesCount, nvmlVgpuProcessUtilizationSample_t
*utilizationSamples)
nvmlReturn_t DECLDIR nvmlDeviceGetGridLicensableFeatures (nvmlDevice_t device,
nvmlGridLicensableFeatures_t *pGridLicensableFeatures)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetEncoderStats (nvmlVgpuInstance_t vgpuInstance, unsigned int
*sessionCount, unsigned int *averageFps, unsigned int *averageLatency)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetEncoderSessions (nvmlVgpuInstance_t vgpuInstance, unsigned int
*sessionCount, nvmlEncoderSessionInfo_t *sessionInfo)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFBCStats (nvmlVgpuInstance_t vgpuInstance, nvmlFBCStats_t
*fbcStats)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFBCSessions (nvmlVgpuInstance_t vgpuInstance, unsigned int
*sessionCount, nvmlFBCSessionInfo_t *sessionInfo)
nvmlReturn_t DECLDIR nvmlDeviceGetProcessUtilization (nvmlDevice_t device, nvmlProcessUtilizationSample_t
*utilization, unsigned int *processSamplesCount, unsigned long long lastSeenTimeStamp)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetAccountingMode (nvmlVgpuInstance_t vgpuInstance,
nvmlEnableState_t *mode)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetAccountingPids (nvmlVgpuInstance_t vgpuInstance, unsigned int
*count, unsigned int *pids)
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetAccountingStats (nvmlVgpuInstance_t vgpuInstance, unsigned int
pid, nvmlAccountingStats_t *stats)
Detailed Description
Set of APIs supporting GRID vGPU
Function Documentation
nvmlReturn_t DECLDIR nvmlDeviceGetActiveVgpus (nvmlDevice_t device, unsigned int * vgpuCount,
nvmlVgpuInstance_t * vgpuInstances)
Retrieve the active vGPU instances on a device.
An array of active vGPU instances is returned in the caller-supplied buffer pointed at by vgpuInstances.
The array elememt count is passed in vgpuCount, and vgpuCount is used to return the number of vGPU
instances written to the buffer.
If the supplied buffer is not large enough to accommodate the vGPU instance array, the function returns
NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlVgpuInstance_t array required in vgpuCount.
To query the number of active vGPU instances, call this function with *vgpuCount = 0. The code will
return NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if no vGPU Types are supported.
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
vgpuCount Pointer which passes in the array size as well as get back the number of types
vgpuInstances Pointer to array in which to return list of vGPU instances
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, or vgpuCount is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if size is too small
• NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetCreatableVgpus (nvmlDevice_t device, unsigned int * vgpuCount,
nvmlVgpuTypeId_t * vgpuTypeIds)
Retrieve the currently creatable vGPU types on a physical GPU (device).
An array of creatable vGPU types for the physical GPU indicated by device is returned in the caller-
supplied buffer pointed at by vgpuTypeIds. The element count of nvmlVgpuTypeId_t array is passed in
vgpuCount, and vgpuCount is used to return the number of vGPU types written to the buffer.
The creatable vGPU types for a device may differ over time, as there may be restrictions on what type of
vGPU types can concurrently run on a device. For example, if only one vGPU type is allowed at a time on a
device, then the creatable list will be restricted to whatever vGPU type is already running on the
device.
If the supplied buffer is not large enough to accommodate the vGPU type array, the function returns
NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlVgpuTypeId_t array required in vgpuCount. To
query the number of vGPU types createable for the GPU, call this function with *vgpuCount = 0. The code
will return NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if no vGPU types are creatable.
Parameters:
device The identifier of the target device
vgpuCount Pointer to caller-supplied array size, and returns number of vGPU types
vgpuTypeIds Pointer to caller-supplied array in which to return list of vGPU types
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_INSUFFICIENT_SIZE vgpuTypeIds buffer is too small, array element count is returned in
vgpuCount
• NVML_ERROR_INVALID_ARGUMENT if vgpuCount is NULL
• NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
• NVML_ERROR_VGPU_ECC_NOT_SUPPORTED if ECC is enabled on the device
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetGridLicensableFeatures (nvmlDevice_t device, nvmlGridLicensableFeatures_t *
pGridLicensableFeatures)
Retrieve the GRID licensable features.
Identifies whether the system supports GRID Software Licensing. If it does, return the list of licensable
feature(s) and their current license status.
Parameters:
device Identifier of the target device
pGridLicensableFeatures Pointer to structure in which GRID licensable features are returned
Returns:
• NVML_SUCCESS if licensable features are successfully retrieved
• NVML_ERROR_INVALID_ARGUMENT if pGridLicensableFeatures is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetProcessUtilization (nvmlDevice_t device, nvmlProcessUtilizationSample_t *
utilization, unsigned int * processSamplesCount, unsigned long long lastSeenTimeStamp)
Retrieves the current utilization and process ID
For Maxwell (TM) 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.
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.
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_GPU_IS_LOST if the target GPU has fallen off the bus or is otherwise inaccessible
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetSupportedVgpus (nvmlDevice_t device, unsigned int * vgpuCount,
nvmlVgpuTypeId_t * vgpuTypeIds)
Retrieve the supported vGPU types on a physical GPU (device).
An array of supported vGPU types for the physical GPU indicated by device is returned in the caller-
supplied buffer pointed at by vgpuTypeIds. The element count of nvmlVgpuTypeId_t array is passed in
vgpuCount, and vgpuCount is used to return the number of vGPU types written to the buffer.
If the supplied buffer is not large enough to accommodate the vGPU type array, the function returns
NVML_ERROR_INSUFFICIENT_SIZE, with the element count of nvmlVgpuTypeId_t array required in vgpuCount. To
query the number of vGPU types supported for the GPU, call this function with *vgpuCount = 0. The code
will return NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if no vGPU types are supported.
Parameters:
device The identifier of the target device
vgpuCount Pointer to caller-supplied array size, and returns number of vGPU types
vgpuTypeIds Pointer to caller-supplied array in which to return list of vGPU types
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_INSUFFICIENT_SIZE vgpuTypeIds buffer is too small, array element count is returned in
vgpuCount
• NVML_ERROR_INVALID_ARGUMENT if vgpuCount is NULL or device is invalid
• NVML_ERROR_NOT_SUPPORTED if vGPU is not supported by the device
• NVML_ERROR_VGPU_ECC_NOT_SUPPORTED if ECC is enabled on the device
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlDeviceGetVgpuProcessUtilization (nvmlDevice_t device, unsigned long long
lastSeenTimeStamp, unsigned int * vgpuProcessSamplesCount, nvmlVgpuProcessUtilizationSample_t *
utilizationSamples)
Retrieves current utilization for processes running on vGPUs on a physical GPU (device).
For Maxwell (TM) or newer fully supported devices.
Reads recent utilization of GPU SM (3D/Compute), framebuffer, video encoder, and video decoder for
processes running on vGPU instances active on a device. Utilization values are returned as an array of
utilization sample structures in the caller-supplied buffer pointed at by utilizationSamples. One
utilization sample structure is returned per process running on vGPU instances, 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.
To read utilization values, first determine the size of buffer required to hold the samples by invoking
the function with utilizationSamples set to NULL. The function will return NVML_ERROR_INSUFFICIENT_SIZE,
with the current vGPU instance count in vgpuProcessSamplesCount. The caller should allocate a buffer of
size vgpuProcessSamplesCount * sizeof(nvmlVgpuProcessUtilizationSample_t). Invoke the function again with
the allocated buffer passed in utilizationSamples, and vgpuProcessSamplesCount set to the number of
entries the buffer is sized for.
On successful return, the function updates vgpuSubProcessSampleCount with the number of vGPU sub process
utilization sample structures that were actually written. This may differ from a previously read value
depending on the number of processes that are active in any given sample period.
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.
Parameters:
device The identifier for the target device
lastSeenTimeStamp Return only samples with timestamp greater than lastSeenTimeStamp.
vgpuProcessSamplesCount Pointer to caller-supplied array size, and returns number of processes
running on vGPU instances
utilizationSamples Pointer to caller-supplied buffer in which vGPU sub process utilization samples
are returned
Returns:
• NVML_SUCCESS if utilization samples are successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, vgpuProcessSamplesCount or a sample count of 0 is
passed with a non-NULL utilizationSamples
• NVML_ERROR_INSUFFICIENT_SIZE if supplied vgpuProcessSamplesCount is too small to return samples for
all vGPU instances currently executing on the device
• NVML_ERROR_NOT_SUPPORTED if vGPU 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
nvmlReturn_t DECLDIR nvmlDeviceGetVgpuUtilization (nvmlDevice_t device, unsigned long long lastSeenTimeStamp,
nvmlValueType_t * sampleValType, unsigned int * vgpuInstanceSamplesCount,
nvmlVgpuInstanceUtilizationSample_t * utilizationSamples)
Retrieves current utilization for vGPUs on a physical GPU (device).
For Kepler (TM) or newer fully supported devices.
Reads recent utilization of GPU SM (3D/Compute), framebuffer, video encoder, and video decoder for vGPU
instances running on a device. Utilization values are returned as an array of utilization sample
structures in the caller-supplied buffer pointed at by utilizationSamples. One utilization sample
structure is returned per vGPU instance, and includes the CPU timestamp at which the samples were
recorded. Individual utilization values are returned as 'unsigned int' values in nvmlValue_t unions. The
function sets the caller-supplied sampleValType to NVML_VALUE_TYPE_UNSIGNED_INT to indicate the returned
value type.
To read utilization values, first determine the size of buffer required to hold the samples by invoking
the function with utilizationSamples set to NULL. The function will return NVML_ERROR_INSUFFICIENT_SIZE,
with the current vGPU instance count in vgpuInstanceSamplesCount, or NVML_SUCCESS if the current vGPU
instance count is zero. The caller should allocate a buffer of size vgpuInstanceSamplesCount *
sizeof(nvmlVgpuInstanceUtilizationSample_t). Invoke the function again with the allocated buffer passed
in utilizationSamples, and vgpuInstanceSamplesCount set to the number of entries the buffer is sized for.
On successful return, the function updates vgpuInstanceSampleCount with the number of vGPU utilization
sample structures that were actually written. This may differ from a previously read value as vGPU
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.
Parameters:
device The identifier for the target device
lastSeenTimeStamp Return only samples with timestamp greater than lastSeenTimeStamp.
sampleValType Pointer to caller-supplied buffer to hold the type of returned sample values
vgpuInstanceSamplesCount Pointer to caller-supplied array size, and returns number of vGPU instances
utilizationSamples Pointer to caller-supplied buffer in which vGPU utilization samples are returned
Returns:
• NVML_SUCCESS if utilization samples are successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if device is invalid, vgpuInstanceSamplesCount or sampleValType is
NULL, or a sample count of 0 is passed with a non-NULL utilizationSamples
• NVML_ERROR_INSUFFICIENT_SIZE if supplied vgpuInstanceSamplesCount is too small to return samples
for all vGPU instances currently executing on the device
• NVML_ERROR_NOT_SUPPORTED if vGPU 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
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetAccountingMode (nvmlVgpuInstance_t vgpuInstance, nvmlEnableState_t *
mode)
Queries the state of per process accounting mode on vGPU.
For Maxwell (TM) or newer fully supported devices.
Parameters:
vgpuInstance The identifier of the target vGPU VM
mode Reference in which to return the current accounting mode
Returns:
• NVML_SUCCESS if the mode has been successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or mode is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_NOT_SUPPORTED if the vGPU doesn't support this feature
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetAccountingPids (nvmlVgpuInstance_t vgpuInstance, unsigned int *
count, unsigned int * pids)
Queries list of processes running on vGPU that can be queried for accounting stats. The list of processes
returned can be in running or terminated state.
For Maxwell (TM) or newer fully supported devices.
To just query the maximum number of processes that can be queried, call this function with *count = 0 and
pids=NULL. The return code will be NVML_ERROR_INSUFFICIENT_SIZE, or NVML_SUCCESS if list is empty.
For more details see nvmlVgpuInstanceGetAccountingStats.
Note:
In case of PID collision some processes might not be accessible before the circular buffer is full.
Parameters:
vgpuInstance The identifier of the target vGPU VM
count Reference in which to provide the pids array size, and to return the number of elements ready
to be queried
pids Reference in which to return list of process ids
Returns:
• NVML_SUCCESS if pids were successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or count is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_NOT_SUPPORTED if the vGPU doesn't support this feature or accounting mode is disabled
• NVML_ERROR_INSUFFICIENT_SIZE if count is too small (count is set to expected value)
• NVML_ERROR_UNKNOWN on any unexpected error
See also:
nvmlVgpuInstanceGetAccountingPids
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetAccountingStats (nvmlVgpuInstance_t vgpuInstance, unsigned int pid,
nvmlAccountingStats_t * stats)
Queries process's accounting stats.
For Maxwell (TM) or newer fully supported devices.
Accounting stats capture GPU utilization and other statistics across the lifetime of a process, and can
be queried during life time of the process or after its termination. The time field in
nvmlAccountingStats_t is reported as 0 during the lifetime of the process and updated to actual running
time after its termination. Accounting stats are kept in a circular buffer, newly created processes
overwrite information about old processes.
See nvmlAccountingStats_t for description of each returned metric. List of processes that can be queried
can be retrieved from nvmlVgpuInstanceGetAccountingPids.
Note:
Accounting Mode needs to be on. See nvmlVgpuInstanceGetAccountingMode.
Only compute and graphics applications stats can be queried. Monitoring applications stats can't be
queried since they don't contribute to GPU utilization.
In case of pid collision stats of only the latest process (that terminated last) will be reported
Parameters:
vgpuInstance The identifier of the target vGPU VM
pid Process Id of the target process to query stats for
stats Reference in which to return the process's accounting stats
Returns:
• NVML_SUCCESS if stats have been successfully retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or stats is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system or
stats is not found
• NVML_ERROR_NOT_SUPPORTED if the vGPU doesn't support this feature or accounting mode is disabled
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetEncoderCapacity (nvmlVgpuInstance_t vgpuInstance, unsigned int *
encoderCapacity)
Retrieve the encoder capacity of a vGPU instance, as a percentage of maximum encoder capacity with valid
values in the range 0-100.
For Maxwell (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
encoderCapacity Reference to an unsigned int for the encoder capacity
Returns:
• NVML_SUCCESS if encoderCapacity has been retrieved
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or encoderQueryType is invalid
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetEncoderSessions (nvmlVgpuInstance_t vgpuInstance, unsigned int *
sessionCount, nvmlEncoderSessionInfo_t * sessionInfo)
Retrieves information about all active encoder sessions on a vGPU Instance.
An array of active encoder 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 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 (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
sessionCount Reference to caller supplied array size, and returns the number of sessions.
sessionInfo Reference to caller supplied array in which the list of session information us returned.
Returns:
• NVML_SUCCESS if sessionInfo 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, or vgpuInstance is 0.
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetEncoderStats (nvmlVgpuInstance_t vgpuInstance, unsigned int *
sessionCount, unsigned int * averageFps, unsigned int * averageLatency)
Retrieves the current encoder statistics of a vGPU Instance
For Maxwell (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
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 averageFps or averageLatency is NULL or
vgpuInstance is 0.
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFBCSessions (nvmlVgpuInstance_t vgpuInstance, unsigned int *
sessionCount, nvmlFBCSessionInfo_t * sessionInfo)
Retrieves information about active frame buffer capture sessions on a vGPU Instance.
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 (TM) or newer fully supported devices.
Note:
hResolution, vResolution, averageFPS and averageLatency data for a FBC session returned in
sessionInfo may be zero if there are no new frames captured since the session started.
Parameters:
vgpuInstance Identifier of the target vGPU instance
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
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or sessionCount is NULL.
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_INSUFFICIENT_SIZE if sessionCount is too small, array element count is returned in
sessionCount
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFBCStats (nvmlVgpuInstance_t vgpuInstance, nvmlFBCStats_t * fbcStats)
Retrieves the active frame buffer capture sessions statistics of a vGPU Instance
For Maxwell (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
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 vgpuInstance is 0, or fbcStats is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFbUsage (nvmlVgpuInstance_t vgpuInstance, unsigned long long *
fbUsage)
Retrieve the framebuffer usage in bytes.
Framebuffer usage is the amont of vGPU framebuffer memory that is currently in use by the VM.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance The identifier of the target instance
fbUsage Pointer to framebuffer usage in bytes
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or fbUsage is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetFrameRateLimit (nvmlVgpuInstance_t vgpuInstance, unsigned int *
frameRateLimit)
Retrieve the frame rate limit set for the vGPU instance.
Returns the value of the frame rate limit set for the vGPU instance
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
frameRateLimit Reference to return the frame rate limit
Returns:
• NVML_SUCCESS if frameRateLimit has been set
• NVML_ERROR_NOT_SUPPORTED if frame rate limiter is turned off for the vGPU type
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or frameRateLimit is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetLicenseStatus (nvmlVgpuInstance_t vgpuInstance, unsigned int *
licensed)
Retrieve the current licensing state of the vGPU instance.
If the vGPU is currently licensed, licensed is set to 1, otherwise it is set to 0.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
licensed Reference to return the licensing status
Returns:
• NVML_SUCCESS if licensed has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or licensed is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetType (nvmlVgpuInstance_t vgpuInstance, nvmlVgpuTypeId_t * vgpuTypeId)
Retrieve the vGPU type of a vGPU instance.
Returns the vGPU type ID of vgpu assigned to the vGPU instance.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
vgpuTypeId Reference to return the vgpuTypeId
Returns:
• NVML_SUCCESS if vgpuTypeId has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or vgpuTypeId is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetUUID (nvmlVgpuInstance_t vgpuInstance, char * uuid, unsigned int
size)
Retrieve the UUID of a vGPU instance.
The UUID is a globally unique identifier associated with the vGPU, and is returned as a 5-part
hexadecimal string, not exceeding 80 characters in length (including the NULL terminator). See
nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
uuid Pointer to caller-supplied buffer to hold vGPU UUID
size Size of buffer in bytes
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or uuid is NULL
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_INSUFFICIENT_SIZE if size is too small
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetVmDriverVersion (nvmlVgpuInstance_t vgpuInstance, char * version,
unsigned int length)
Retrieve the NVIDIA driver version installed in the VM associated with a vGPU.
The version is returned as an alphanumeric string in the caller-supplied buffer version. The length of
the version string will not exceed 80 characters in length (including the NUL terminator). See
nvmlConstants::NVML_SYSTEM_DRIVER_VERSION_BUFFER_SIZE.
nvmlVgpuInstanceGetVmDriverVersion() may be called at any time for a vGPU instance. The guest VM driver
version is returned as 'Unknown' if no NVIDIA driver is installed in the VM, or the VM has not yet booted
to the point where the NVIDIA driver is loaded and initialized.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
version Caller-supplied buffer to return driver version string
length Size of version buffer
Returns:
• NVML_SUCCESS if version has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_INSUFFICIENT_SIZE if length is too small
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceGetVmID (nvmlVgpuInstance_t vgpuInstance, char * vmId, unsigned int
size, nvmlVgpuVmIdType_t * vmIdType)
Retrieve the VM ID associated with a vGPU instance.
The VM ID is returned as a string, not exceeding 80 characters in length (including the NUL terminator).
See nvmlConstants::NVML_DEVICE_UUID_BUFFER_SIZE.
The format of the VM ID varies by platform, and is indicated by the type identifier returned in vmIdType.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
vmId Pointer to caller-supplied buffer to hold VM ID
size Size of buffer in bytes
vmIdType Pointer to hold VM ID type
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vmId or vmIdType is NULL, or vgpuInstance is 0
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_INSUFFICIENT_SIZE if size is too small
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuInstanceSetEncoderCapacity (nvmlVgpuInstance_t vgpuInstance, unsigned int
encoderCapacity)
Set the encoder capacity of a vGPU instance, as a percentage of maximum encoder capacity with valid
values in the range 0-100.
For Maxwell (TM) or newer fully supported devices.
Parameters:
vgpuInstance Identifier of the target vGPU instance
encoderCapacity Unsigned int for the encoder capacity value
Returns:
• NVML_SUCCESS if encoderCapacity has been set
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuInstance is 0, or encoderCapacity is out of range of 0-100.
• NVML_ERROR_NOT_FOUND if vgpuInstance does not match a valid active vGPU instance on the system
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetClass (nvmlVgpuTypeId_t vgpuTypeId, char * vgpuTypeClass, unsigned int *
size)
Retrieve the class of a vGPU type. It will not exceed 64 characters in length (including the NUL
terminator). See nvmlConstants::NVML_DEVICE_NAME_BUFFER_SIZE.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
vgpuTypeClass Pointer to string array to return class in
size Size of string
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or vgpuTypeClass is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if size is too small
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetDeviceID (nvmlVgpuTypeId_t vgpuTypeId, unsigned long long * deviceID,
unsigned long long * subsystemID)
Retrieve the device ID of a vGPU type.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
deviceID Device ID and vendor ID of the device contained in single 32 bit value
subsystemID Subsystem ID and subsystem vendor ID of the device contained in single 32 bit value
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or deviceId or subsystemID are NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetFramebufferSize (nvmlVgpuTypeId_t vgpuTypeId, unsigned long long *
fbSize)
Retrieve the vGPU framebuffer size in bytes.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
fbSize Pointer to framebuffer size in bytes
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or fbSize is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetFrameRateLimit (nvmlVgpuTypeId_t vgpuTypeId, unsigned int *
frameRateLimit)
Retrieve the static frame rate limit value of the vGPU type
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
frameRateLimit Reference to return the frame rate limit value
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_NOT_SUPPORTED if frame rate limiter is turned off for the vGPU type
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or frameRateLimit is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetLicense (nvmlVgpuTypeId_t vgpuTypeId, char * vgpuTypeLicenseString,
unsigned int size)
Retrieve license requirements for a vGPU type
The license type and version required to run the specified vGPU type is returned as an alphanumeric
string, in the form '<license name>,<version>', for example 'GRID-Virtual-PC,2.0'. If a vGPU is runnable
with* more than one type of license, the licenses are delimited by a semicolon, for example 'GRID-
Virtual-PC,2.0;GRID-Virtual-WS,2.0;GRID-Virtual-WS-Ext,2.0'.
The total length of the returned string will not exceed 128 characters, including the NUL terminator. See
nvmlVgpuConstants::NVML_GRID_LICENSE_BUFFER_SIZE.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
vgpuTypeLicenseString Pointer to buffer to return license info
size Size of vgpuTypeLicenseString buffer
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or vgpuTypeLicenseString is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if size is too small
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetMaxInstances (nvmlDevice_t device, nvmlVgpuTypeId_t vgpuTypeId, unsigned
int * vgpuInstanceCount)
Retrieve the maximum number of vGPU instances creatable on a device for given vGPU type
For Kepler (TM) or newer fully supported devices.
Parameters:
device The identifier of the target device
vgpuTypeId Handle to vGPU type
vgpuInstanceCount Pointer to get the max number of vGPU instances that can be created on a deicve for
given vgpuTypeId
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid or is not supported on target device, or
vgpuInstanceCount is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetMaxInstancesPerVm (nvmlVgpuTypeId_t vgpuTypeId, unsigned int *
vgpuInstanceCountPerVm)
Retrieve the maximum number of vGPU instances supported per VM for given vGPU type
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
vgpuInstanceCountPerVm Pointer to get the max number of vGPU instances supported per VM for given
vgpuTypeId
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or vgpuInstanceCountPerVm is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetName (nvmlVgpuTypeId_t vgpuTypeId, char * vgpuTypeName, unsigned int *
size)
Retrieve the vGPU type name.
The name is an alphanumeric string that denotes a particular vGPU, e.g. GRID M60-2Q. It will not exceed
64 characters in length (including the NUL terminator). See nvmlConstants::NVML_DEVICE_NAME_BUFFER_SIZE.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
vgpuTypeName Pointer to buffer to return name
size Size of buffer
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or name is NULL
• NVML_ERROR_INSUFFICIENT_SIZE if size is too small
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetNumDisplayHeads (nvmlVgpuTypeId_t vgpuTypeId, unsigned int *
numDisplayHeads)
Retrieve count of vGPU's supported display heads.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
numDisplayHeads Pointer to number of display heads
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or numDisplayHeads is NULL
• NVML_ERROR_UNKNOWN on any unexpected error
nvmlReturn_t DECLDIR nvmlVgpuTypeGetResolution (nvmlVgpuTypeId_t vgpuTypeId, unsigned int displayIndex,
unsigned int * xdim, unsigned int * ydim)
Retrieve vGPU display head's maximum supported resolution.
For Kepler (TM) or newer fully supported devices.
Parameters:
vgpuTypeId Handle to vGPU type
displayIndex Zero-based index of display head
xdim Pointer to maximum number of pixels in X dimension
ydim Pointer to maximum number of pixels in Y dimension
Returns:
• NVML_SUCCESS successful completion
• NVML_ERROR_UNINITIALIZED if the library has not been successfully initialized
• NVML_ERROR_INVALID_ARGUMENT if vgpuTypeId is invalid, or xdim or ydim are NULL, or displayIndex is
out of range.
• NVML_ERROR_UNKNOWN on any unexpected error
Author
Generated automatically by Doxygen for NVML from the source code.
Version 1.1 28 Jul 2019 vGPU Management(3)