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:

• P0/P1 - Maximum 3D performance
• P2/P3 - Balanced 3D performance-power
• P8 - Basic HD video playback
• P10 - DVD playback
• P12 - Minimum idle power consumption

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

typedef enum _NV_GPU_PERF_PSTATE_ID NV_GPU_PERF_PSTATE_ID

NV_GPU_PERF_PSTATES20_INFO

typedef NV_GPU_PERF_PSTATES20_INFO_V2 NV_GPU_PERF_PSTATES20_INFO

NV_GPU_PERF_PSTATES20_INFO_V2

typedef struct _NV_GPU_PERF_PSTATES20_INFO_V2 NV_GPU_PERF_PSTATES20_INFO_V2

Used in NvAPI_GPU_GetPstates20() interface call.

NV_GPU_PERF_PSTATES_INFO

typedef NV_GPU_PERF_PSTATES_INFO_V2 NV_GPU_PERF_PSTATES_INFO

Enumeration Type Documentation

_NV_GPU_PERF_PSTATE_ID

enum _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

enum 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. This is the same as NvAPI_GPU_GetPstatesInfo(), but supports an input flag for various options.

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:

• 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]	hPhysicalGPU	GPU selection.
[out]	pPerfPstatesInfo	P-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_OK	Completed request
NVAPI_ERROR	Miscellaneous error occurred
NVAPI_HANDLE_INVALIDATED	Handle passed has been invalidated (see user guide)
NVAPI_EXPECTED_PHYSICAL_GPU_HANDLE	Handle passed is not a physical GPU handle
NVAPI_INCOMPATIBLE_STRUCT_VERSION	The 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 7 and higher

Since

Release: 165

TCC_SUPPORTED

Parameters

[in]	hPhysicalGPU	GPU selection
[out]	pCurrentPstate	The ID of the current P-State of the GPU - see NV_GPU_PERF_PSTATES.

Return values

NVAPI_OK	Completed request
NVAPI_ERROR	Miscellaneous error occurred.
NVAPI_HANDLE_INVALIDATED	Handle passed has been invalidated (see user guide).
NVAPI_EXPECTED_PHYSICAL_GPU_HANDLE	Handle passed is not a physical GPU handle.
NVAPI_NOT_SUPPORTED	P-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 7 and higher

TCC_SUPPORTED

Since

Release: 185

Return values

NVAPI_OK
NVAPI_ERROR
NVAPI_INVALID_ARGUMENT	pDynamicPstatesInfo is NULL
NVAPI_HANDLE_INVALIDATED
NVAPI_EXPECTED_PHYSICAL_GPU_HANDLE
NVAPI_INCOMPATIBLE_STRUCT_VERSION	The 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 7 and higher

Parameters

[in]	hPhysicalGPU	GPU selection
[out]	pPstatesInfo	P-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.