NVAPI Reference Documentation
NVIDIA
Release 550
Wed Mar 20 2024

Data Structures | Macros | Typedefs | Enumerations | Functions
GPU Performance State Interface

Data Structures

struct  NV_GPU_PERF_PSTATES20_PARAM_DELTA
 
struct  NV_GPU_PSTATE20_CLOCK_ENTRY_V1
 
struct  NV_GPU_PSTATE20_BASE_VOLTAGE_ENTRY_V1
 
struct  NV_GPU_PERF_PSTATES20_INFO_V1
 
struct  _NV_GPU_PERF_PSTATES20_INFO_V2
 
struct  NV_GPU_PERF_PSTATES_INFO_V1
 
struct  NV_GPU_PERF_PSTATES_INFO_V2
 
struct  NV_GPU_DYNAMIC_PSTATES_INFO_EX
 

Macros

#define NVAPI_MAX_GPU_PSTATE20_PSTATES   16
 
#define NVAPI_MAX_GPU_PSTATE20_CLOCKS   8
 
#define NVAPI_MAX_GPU_PSTATE20_BASE_VOLTAGES   4
 
#define NV_GPU_PERF_PSTATES20_INFO_VER1   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES20_INFO_V1,1)
 
#define NV_GPU_PERF_PSTATES20_INFO_VER2   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES20_INFO_V2,2)
 
#define NV_GPU_PERF_PSTATES20_INFO_VER3   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES20_INFO_V2,3)
 
#define NV_GPU_PERF_PSTATES20_INFO_VER   NV_GPU_PERF_PSTATES20_INFO_VER3
 
#define NVAPI_MAX_GPU_UTILIZATIONS   8
 
#define NV_GPU_DYNAMIC_PSTATES_INFO_EX_VER   MAKE_NVAPI_VERSION(NV_GPU_DYNAMIC_PSTATES_INFO_EX,1)
 

Typedefs

typedef enum _NV_GPU_PERF_PSTATE_ID NV_GPU_PERF_PSTATE_ID
 
typedef struct _NV_GPU_PERF_PSTATES20_INFO_V2 NV_GPU_PERF_PSTATES20_INFO_V2
 
typedef NV_GPU_PERF_PSTATES20_INFO_V2 NV_GPU_PERF_PSTATES20_INFO
 
typedef NV_GPU_PERF_PSTATES_INFO_V2 NV_GPU_PERF_PSTATES_INFO
 

Enumerations

enum  _NV_GPU_PERF_PSTATE_ID {
  NVAPI_GPU_PERF_PSTATE_P0 = 0 , NVAPI_GPU_PERF_PSTATE_P1 , NVAPI_GPU_PERF_PSTATE_P2 , NVAPI_GPU_PERF_PSTATE_P3 ,
  NVAPI_GPU_PERF_PSTATE_P4 , NVAPI_GPU_PERF_PSTATE_P5 , NVAPI_GPU_PERF_PSTATE_P6 , NVAPI_GPU_PERF_PSTATE_P7 ,
  NVAPI_GPU_PERF_PSTATE_P8 , NVAPI_GPU_PERF_PSTATE_P9 , NVAPI_GPU_PERF_PSTATE_P10 , NVAPI_GPU_PERF_PSTATE_P11 ,
  NVAPI_GPU_PERF_PSTATE_P12 , NVAPI_GPU_PERF_PSTATE_P13 , NVAPI_GPU_PERF_PSTATE_P14 , NVAPI_GPU_PERF_PSTATE_P15 ,
  NVAPI_GPU_PERF_PSTATE_UNDEFINED = NVAPI_MAX_GPU_PERF_PSTATES , NVAPI_GPU_PERF_PSTATE_ALL
}
 
enum  NV_GPU_PERF_PSTATE20_CLOCK_TYPE_ID { NVAPI_GPU_PERF_PSTATE20_CLOCK_TYPE_SINGLE = 0 , NVAPI_GPU_PERF_PSTATE20_CLOCK_TYPE_RANGE }
 

Functions

 __nvapi_deprecated_function ("Do not use this function - it is deprecated in release 304. Instead, use NvAPI_GPU_GetPstates20.") NVAPI_INTERFACE NvAPI_GPU_GetPstatesInfoEx(NvPhysicalGpuHandle hPhysicalGpu
 
NVAPI_INTERFACE NvAPI_GPU_GetPstates20 (__in NvPhysicalGpuHandle hPhysicalGpu, __inout NV_GPU_PERF_PSTATES20_INFO *pPstatesInfo)
 
NVAPI_INTERFACE NvAPI_GPU_GetCurrentPstate (NvPhysicalGpuHandle hPhysicalGpu, NV_GPU_PERF_PSTATE_ID *pCurrentPstate)
 
NVAPI_INTERFACE NvAPI_GPU_GetDynamicPstatesInfoEx (NvPhysicalGpuHandle hPhysicalGpu, NV_GPU_DYNAMIC_PSTATES_INFO_EX *pDynamicPstatesInfoEx)
 
#define NV_GPU_PERF_PSTATES_INFO_VER1   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES_INFO_V1,1)
 
#define NV_GPU_PERF_PSTATES_INFO_VER2   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES_INFO_V2,2)
 
#define NV_GPU_PERF_PSTATES_INFO_VER3   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES_INFO_V2,3)
 
#define NV_GPU_PERF_PSTATES_INFO_VER   NV_GPU_PERF_PSTATES_INFO_VER3
 

Detailed Description

The GPU performance state APIs are used to get and set various performance levels on a per-GPU basis. P-States are GPU active/executing performance capability and power consumption states.

P-States range from P0 to P15, with P0 being the highest performance/power state, and P15 being the lowest performance/power state. Each P-State maps to a performance level. Not all P-States are available on a given system. The definition of each P-States are currently as follows:

Macro Definition Documentation

◆ NV_GPU_DYNAMIC_PSTATES_INFO_EX_VER

#define NV_GPU_DYNAMIC_PSTATES_INFO_EX_VER   MAKE_NVAPI_VERSION(NV_GPU_DYNAMIC_PSTATES_INFO_EX,1)

Macro for constructing the version field of NV_GPU_DYNAMIC_PSTATES_INFO_EX

◆ NV_GPU_PERF_PSTATES20_INFO_VER

#define NV_GPU_PERF_PSTATES20_INFO_VER   NV_GPU_PERF_PSTATES20_INFO_VER3

Macro for constructing the version field of NV_GPU_PERF_PSTATES20_INFO.

◆ NV_GPU_PERF_PSTATES20_INFO_VER1

#define NV_GPU_PERF_PSTATES20_INFO_VER1   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES20_INFO_V1,1)

Macro for constructing the version field of NV_GPU_PERF_PSTATES20_INFO_V1.

◆ NV_GPU_PERF_PSTATES20_INFO_VER2

#define NV_GPU_PERF_PSTATES20_INFO_VER2   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES20_INFO_V2,2)

Macro for constructing the version field of NV_GPU_PERF_PSTATES20_INFO_V2.

◆ NV_GPU_PERF_PSTATES20_INFO_VER3

#define NV_GPU_PERF_PSTATES20_INFO_VER3   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES20_INFO_V2,3)

Macro for constructing the version field of NV_GPU_PERF_PSTATES20_INFO_V2.

◆ NV_GPU_PERF_PSTATES_INFO_VER

#define NV_GPU_PERF_PSTATES_INFO_VER   NV_GPU_PERF_PSTATES_INFO_VER3

Macro for constructing the version field of NV_GPU_PERF_PSTATES_INFO.

◆ NV_GPU_PERF_PSTATES_INFO_VER1

#define NV_GPU_PERF_PSTATES_INFO_VER1   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES_INFO_V1,1)

Macro for constructing the version field of NV_GPU_PERF_PSTATES_INFO_V1.

◆ NV_GPU_PERF_PSTATES_INFO_VER2

#define NV_GPU_PERF_PSTATES_INFO_VER2   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES_INFO_V2,2)

Macro for constructing the version field of NV_GPU_PERF_PSTATES_INFO_V2.

◆ NV_GPU_PERF_PSTATES_INFO_VER3

#define NV_GPU_PERF_PSTATES_INFO_VER3   MAKE_NVAPI_VERSION(NV_GPU_PERF_PSTATES_INFO_V2,3)

Macro for constructing the version field of NV_GPU_PERF_PSTATES_INFO_V2.

◆ NVAPI_MAX_GPU_PSTATE20_BASE_VOLTAGES

#define NVAPI_MAX_GPU_PSTATE20_BASE_VOLTAGES   4

◆ NVAPI_MAX_GPU_PSTATE20_CLOCKS

#define NVAPI_MAX_GPU_PSTATE20_CLOCKS   8

◆ NVAPI_MAX_GPU_PSTATE20_PSTATES

#define NVAPI_MAX_GPU_PSTATE20_PSTATES   16

◆ NVAPI_MAX_GPU_UTILIZATIONS

#define NVAPI_MAX_GPU_UTILIZATIONS   8

Typedef Documentation

◆ NV_GPU_PERF_PSTATE_ID

◆ NV_GPU_PERF_PSTATES20_INFO

◆ NV_GPU_PERF_PSTATES20_INFO_V2

Used in NvAPI_GPU_GetPstates20() interface call.

◆ NV_GPU_PERF_PSTATES_INFO

Enumeration Type Documentation

◆ _NV_GPU_PERF_PSTATE_ID

Enumerator
NVAPI_GPU_PERF_PSTATE_P0 
NVAPI_GPU_PERF_PSTATE_P1 
NVAPI_GPU_PERF_PSTATE_P2 
NVAPI_GPU_PERF_PSTATE_P3 
NVAPI_GPU_PERF_PSTATE_P4 
NVAPI_GPU_PERF_PSTATE_P5 
NVAPI_GPU_PERF_PSTATE_P6 
NVAPI_GPU_PERF_PSTATE_P7 
NVAPI_GPU_PERF_PSTATE_P8 
NVAPI_GPU_PERF_PSTATE_P9 
NVAPI_GPU_PERF_PSTATE_P10 
NVAPI_GPU_PERF_PSTATE_P11 
NVAPI_GPU_PERF_PSTATE_P12 
NVAPI_GPU_PERF_PSTATE_P13 
NVAPI_GPU_PERF_PSTATE_P14 
NVAPI_GPU_PERF_PSTATE_P15 
NVAPI_GPU_PERF_PSTATE_UNDEFINED 
NVAPI_GPU_PERF_PSTATE_ALL 

◆ NV_GPU_PERF_PSTATE20_CLOCK_TYPE_ID

Used to identify clock type.

Enumerator
NVAPI_GPU_PERF_PSTATE20_CLOCK_TYPE_SINGLE 

Clock domains that use single frequency value within given pstate.

NVAPI_GPU_PERF_PSTATE20_CLOCK_TYPE_RANGE 

Clock domains that allow range of frequency values within given pstate.

Function Documentation

◆ __nvapi_deprecated_function()

__nvapi_deprecated_function ( "Do not use this function - it is deprecated in release 304.  Instead,
use NvAPI_GPU_GetPstates20."   
)

DESCRIPTION: This API retrieves all performance states (P-States) information.

             P-States are GPU active/executing performance capability and power consumption states.

             P-States ranges from P0 to P15, with P0 being the highest performance/power state, and
             P15 being the lowest performance/power state. Each P-State, if available, maps to a
             performance level. Not all P-States are available on a given system. The definitions
             of each P-State are currently as follows: \n
             - P0/P1 - Maximum 3D performance
             - P2/P3 - Balanced 3D performance-power
             - P8 - Basic HD video playback
             - P10 - DVD playback
             - P12 - Minimum idle power consumption
Parameters
[in]hPhysicalGPUGPU selection.
[out]pPerfPstatesInfoP-States information retrieved, as detailed below:
  • flags is reserved for future use.
  • numPstates is the number of available P-States
  • numClocks is the number of clock domains supported by each P-State
  • pstates has valid index range from 0 to numPstates - 1
  • pstates[i].pstateId is the ID of the P-State, containing the following info:
    • pstates[i].flags containing the following info:
      • bit 0 indicates if the PCIE limit is GEN1 or GEN2
      • bit 1 indicates if the Pstate is overclocked or not
      • bit 2 indicates if the Pstate is overclockable or not
    • pstates[i].clocks has valid index range from 0 to numClocks -1
    • pstates[i].clocks[j].domainId is the public ID of the clock domain, containing the following info:
      • pstates[i].clocks[j].flags containing the following info: bit 0 indicates if the clock domain is overclockable or not
      • pstates[i].clocks[j].freq is the clock frequency in kHz
    • pstates[i].voltages has a valid index range from 0 to numVoltages - 1
    • pstates[i].voltages[j].domainId is the ID of the voltage domain, containing the following info:
      • pstates[i].voltages[j].flags is reserved for future use.
      • pstates[i].voltages[j].mvolt is the voltage in mV inputFlags(IN) - This can be used to select various options:
    • if bit 0 is set, pPerfPstatesInfo would contain the default settings instead of the current, possibily overclocked settings.
    • if bit 1 is set, pPerfPstatesInfo would contain the maximum clock frequencies instead of the nominal frequencies.
    • if bit 2 is set, pPerfPstatesInfo would contain the minimum clock frequencies instead of the nominal frequencies.
    • all other bits must be set to 0.
Return values
NVAPI_OKCompleted request
NVAPI_ERRORMiscellaneous error occurred
NVAPI_HANDLE_INVALIDATEDHandle passed has been invalidated (see user guide)
NVAPI_EXPECTED_PHYSICAL_GPU_HANDLEHandle passed is not a physical GPU handle
NVAPI_INCOMPATIBLE_STRUCT_VERSIONThe version of the NV_GPU_PERF_PSTATES struct is not supported

◆ NvAPI_GPU_GetCurrentPstate()

NVAPI_INTERFACE NvAPI_GPU_GetCurrentPstate ( NvPhysicalGpuHandle  hPhysicalGpu,
NV_GPU_PERF_PSTATE_ID pCurrentPstate 
)

DESCRIPTION: This function retrieves the current performance state (P-State).

SUPPORTED OS: Windows 10 and higher

Since
Release: 165

TCC_SUPPORTED

Parameters
[in]hPhysicalGPUGPU selection
[out]pCurrentPstateThe ID of the current P-State of the GPU - see NV_GPU_PERF_PSTATES.
Return values
NVAPI_OKCompleted request
NVAPI_ERRORMiscellaneous error occurred.
NVAPI_HANDLE_INVALIDATEDHandle passed has been invalidated (see user guide).
NVAPI_EXPECTED_PHYSICAL_GPU_HANDLEHandle passed is not a physical GPU handle.
NVAPI_NOT_SUPPORTEDP-States is not supported on this setup.

◆ NvAPI_GPU_GetDynamicPstatesInfoEx()

NVAPI_INTERFACE NvAPI_GPU_GetDynamicPstatesInfoEx ( NvPhysicalGpuHandle  hPhysicalGpu,
NV_GPU_DYNAMIC_PSTATES_INFO_EX pDynamicPstatesInfoEx 
)

DESCRIPTION: This API retrieves the NV_GPU_DYNAMIC_PSTATES_INFO_EX structure for the specified physical GPU. Each domain's info is indexed in the array. For example:

  • pDynamicPstatesInfo->utilization[NVAPI_GPU_UTILIZATION_DOMAIN_GPU] holds the info for the GPU domain. There are currently 4 domains for which GPU utilization and dynamic P-State thresholds can be retrieved: graphic engine (GPU), frame buffer (FB), video engine (VID), and bus interface (BUS).

SUPPORTED OS: Windows 10 and higher

TCC_SUPPORTED

Since
Release: 185
Return values
NVAPI_OK
NVAPI_ERROR
NVAPI_INVALID_ARGUMENTpDynamicPstatesInfo is NULL
NVAPI_HANDLE_INVALIDATED
NVAPI_EXPECTED_PHYSICAL_GPU_HANDLE
NVAPI_INCOMPATIBLE_STRUCT_VERSIONThe version of the INFO struct is not supported

◆ NvAPI_GPU_GetPstates20()

NVAPI_INTERFACE NvAPI_GPU_GetPstates20 ( __in NvPhysicalGpuHandle  hPhysicalGpu,
__inout NV_GPU_PERF_PSTATES20_INFO pPstatesInfo 
)

DESCRIPTION: This API retrieves all performance states (P-States) 2.0 information.

            P-States are GPU active/executing performance capability states.
            They range from P0 to P15, with P0 being the highest performance state,
            and P15 being the lowest performance state. Each P-State, if available,
            maps to a performance level. Not all P-States are available on a given system.
            The definition of each P-States are currently as follow:
            - P0/P1 - Maximum 3D performance
            - P2/P3 - Balanced 3D performance-power
            - P8 - Basic HD video playback
            - P10 - DVD playback
            - P12 - Minimum idle power consumption

TCC_SUPPORTED

Since
Release: 295

SUPPORTED OS: Windows 10 and higher

Parameters
[in]hPhysicalGPUGPU selection
[out]pPstatesInfoP-States information retrieved, as documented in declaration above
Returns
This API can return any of the error codes enumerated in NvAPI_Status. If there are return error codes with specific meaning for this API, they are listed below.

NVIDIA
Copyright (c) 2007–2024 NVIDIA Corporation. All rights reserved.

NVIDIA