NVAPI Reference Documentation
NVIDIA
Release 361: January 27
2016
Data Structures | Defines | Typedefs | Enumerations | Functions
GPU Performance State Interface
GPU APIs

Data Structures

struct  NV_GPU_PERF_PSTATES_INFO_V1
struct  NV_GPU_PERF_PSTATES_INFO_V2
struct  NV_GPU_PERF_PSTATES20_PARAM_DELTA
 Used to describe both voltage and frequency deltas. More...
struct  NV_GPU_PSTATE20_CLOCK_ENTRY_V1
 Used to describe single clock entry. More...
struct  NV_GPU_PSTATE20_BASE_VOLTAGE_ENTRY_V1
 Used to describe single base voltage entry. More...
struct  NV_GPU_PERF_PSTATES20_INFO_V1
 Used in NvAPI_GPU_GetPstates20() interface call. More...
struct  _NV_GPU_PERF_PSTATES20_INFO_V2
 Used in NvAPI_GPU_GetPstates20() interface call. More...
struct  NV_GPU_DYNAMIC_PSTATES_INFO_EX

Defines

#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 NV_GPU_PERF_PSTATES_INFO_V2 NV_GPU_PERF_PSTATES_INFO
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

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:

Define Documentation

#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

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#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.

#define NVAPI_MAX_GPU_PSTATE20_BASE_VOLTAGES   4
#define NVAPI_MAX_GPU_PSTATE20_CLOCKS   8
#define NVAPI_MAX_GPU_PSTATE20_PSTATES   16
#define NVAPI_MAX_GPU_UTILIZATIONS   8

Typedef Documentation

typedef enum _NV_GPU_PERF_PSTATE_ID NV_GPU_PERF_PSTATE_ID
typedef NV_GPU_PERF_PSTATES20_INFO_V2 NV_GPU_PERF_PSTATES20_INFO
typedef struct _NV_GPU_PERF_PSTATES20_INFO_V2 NV_GPU_PERF_PSTATES20_INFO_V2

Used in NvAPI_GPU_GetPstates20() interface call.

typedef NV_GPU_PERF_PSTATES_INFO_V2 NV_GPU_PERF_PSTATES_INFO

Enumeration Type Documentation

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 
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 ( "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]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_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 XP 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_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 XP and higher

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_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 XP 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.

Copyright (c) 2007-2015 NVIDIA Corporation. All rights reserved.

NVIDIA