vGPU Management(3)

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 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 accomodate 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 accomodate 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 accomodate 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 retrived

    •   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 elememt 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 accomodate 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 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 accomodate 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 contianing 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

    •   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 Subsytem ID and subsytem 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 device 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 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.