Using the Intel® Power Gadget 3.0 API on Windows*

ID 777779
Updated 1/7/2014
Version Latest
Public

author-image

By

Authors:  Seung-Woo Kim, Joseph Jin-Sung Lee, Vardhan Dugar, Jun De Vega

1.Introduction

1.1 About Intel® Power Gadget for Windows

Intel® Power Gadget for Windows is an application which presents real-time data about a 2nd generation or later Intel® Core processor regarding current estimated processor power, package power limit, current processor frequency, base frequency, GT frequency, current temperature, maximum temperature, proc hot (when package temperature exceeds max temperature) timestamps and elapsed time. The data is obtained from the Model Specific Registers (MSRs) and energy counters that are available only in 2nd Generation Intel® Core™ or later processors.  The PROCHOT feature is available only in 3rd Generation Intel® Core™ processors or later.

The supported MSRs are correlated with three MSR functions as described in Table 1. This data can be viewed on a Graphical User Interface (GUI) and/or logged for a required duration of time.

MSR Function

Data

Returns

0

Frequency

Frequency of sample (in MHz)

1

Power

Average Power (in Watts),
Cumulative Energy (in Joules),
Cumulative Energy (in milliWatt-Hours)

2

Temperature

Temperature (in Deg. Celsius)
Proc Hot (‘0’ if false and ‘1’ if true)

3

Package Power Limit

Package Power Limit (in Watts)

 Table 1: MSR functions 

Developers may use this data to create their own application by exploiting the Dynamic-Link Library (DLL) used by the Intel® Power Gadget. The DLL serves as a C++ Application Programming Interface (API). For more details on the API, please refer to subsequent sections.

1.2 Setup

  1. Download the appropriate Intel® Power Gadget installation package on your system.
  2. Run setup.exe as an administrator. Accept the UAC, if one appears.
  3. Follow the installer prompt instructions to complete installation. Microsoft .Net Framework 4 will automatically be downloaded from the Microsoft website if not yet installed in your system. Microsoft Visual C++ 2010 SP1 Redistributable Package will also automatically get installed if not yet installed.

 

For more information on system requirements and installation, please visit Intel® Power Gadget page

2.Developers’ Tools

The installer sets two environment variables on installation:

  • IPG_Ver: Contains version of Intel® Power Gadget being installed.
  • IPG_Dir: Contains directory in which the DLLs (EnergyLib64.dll used for 64-bit applications and EnergyLib32.dll used for 32-bit applications) were installed.

Developers may utilize the DLL for their 32-bit or 64-bit applications. Sample code called “PowerLog3.0-source.zip” to use Intel®     Power Gadget’s DLL is available for download at the bottom of this page

3.API of Intel® Power Gadget

3.1 Concept of Sampling

For a good understanding of the API, it is essential to be familiar with the concept of sampling. Data is acquired from specific MSRs at a fixed sampling frequency. Higher the frequency, greater will be the accuracy of the data but poorer will be the performance of the system. Although the Intel® Power Gadget API can be used with a sampling frequency ranging from 1 to 1000 milliseconds, the optimal sampling frequency of 100 milliseconds is the default selection on the GUI and is recommended for application developers.

3.2 Overview

As the primary API, developers may use Intel® Power Gadget’s EnergyLib32.dll for 32-bit applications or EnergyLib64.dll for 64-bit applications. This library must be initialized at the start of the program by calling IntelEnergyLibInitialize(). Here, the loading of the driver takes place.

The ReadSample()function is used to read samples. ReadSample() obtains the number of sampled MSRs from GetNumMsrs(). MSRs are given an ID from 0 to n-1, where n is the number returned by GetNumMsrs(). The MSR ID is used to acquire data for a specific MSR using GetMsrName(),GetMsrFunc() and GetPowerData() functions. GetPowerData() is called for each sampled MSR and provides the relevant data from that MSR. An MSR’s function, which the API obtains from GetMsrFunc(), determines the amount and meaning of data returned from GetPowerData() as described in Table 1.  Since GT frequency is not obtained from MSRs, another function called GetGTFrequency() will provide this data. One can check if Intel® graphics is available with the help of IsGTAvailable() function before attempting to obtain GT related data.

ReadSample() also reads the system time via GetSysTime()at the time the sample was read. The time interval (in seconds) between samples is available via GetTimeInterval().

Further, the API supports reading from common individual MSRs without having to specify the MSR address or read an entire sample via GetIAFrequency(), GetMaxTemperature(), GetTemperature() and GetTDP().It is recommended that Package Power Limit is used instead of TDP whenever possible, as it is a more accurate upper bound to the package power than TDP.

The sample data from ReadSample() can be logged to a file. Logging can be started at any time by calling StartLog(), and subsequently ended by calling StopLog().

For more information on the API, refer to the Function Reference section.

4.Function Reference

 

 

Function

Description

1

bool IntelEnergyLibInitialize();

Initializes the library and connects to the driver.

2

bool ReadSample();

Reads sample data from the driver for all the supported MSRs.

3

bool GetNumNodes(int *nNodes);

Returns the number of CPU packages on the system.

4

bool GetNumMsrs(int *nMsrs);

Returns the number of supported MSRs for bulk reading and logging.

5

bool GetMsrName(int iMsr, wchar_t *szName);

Returns in szName the name of the MSR specified by iMsr.

6

bool GetMsrFunc(int iMsr, int *pFuncID);

Returns in pFuncID the function of the MSR specified by MSR ID in iMsr. Refer Table 1: MSR Functions.

7

bool GetPowerData(int iNode, int iMSR, double *pResult, int *nResult);

Returns the data collected by the most recent call to ReadSample(). The returned data is for the data on the package specified by iNode, from the MSR specified by iMSR. The data is returned in pResult, and the number of double results returned in pResult is returned in nResult. Refer Table 1: MSR Functions.

8

bool IsGTAvailable();

Returns true if Intel® graphics is available and false if Intel® graphics is unavailable (i.e if it’s not present or disabled).

9

bool GetGTFrequency(int *freq);

Returns the current GT frequency in MHz. The data is returned in freq.

10

bool GetSysTime(void *pSysTime);

Returns the system time as of the last call to ReadSample(). The data returned in pSysTime is structured as follows: pSysTime[63:32] = time in seconds ; pSysTime[31:0] = time in nanoseconds

11

bool GetTimeInterval(double *pOffset);

Returns in pOffset the time (in seconds) that has elapsed between the two most recent calls to ReadSample().

12

bool GetIAFrequency(int iNode, int *freqInMHz);

Reads the processor frequency MSR on the package specified by iNode, and returns the frequency (in MHz) in freqInMHz.

13

bool GetTDP(int iNode, double *TDP);

Reads the package power info MSR on the package specified by iNode, and returns the TDP (in Watts) in TDP. It is recommended that Package Power Limit is used instead of TDP whenever possible, as it is a more accurate upper bound to the package power than TDP.

14

bool GetMaxTemperature(int iNode, int *degreeC);

Reads the temperature target MSR on the package specified by iNode, and returns the maximum temperature (in degrees Celsius) in degreeC.

15

bool GetTemperature(int iNode, int *degreeC);

Reads the temperature MSR on the package specified by iNode, and returns the current temperature (in degrees) Celsius in degreeC.

16

bool GetBaseFrequency(int iNode, double *pBaseFrequency);

Returns in pBaseFrequency the advertised processor frequency for the package specified by iNode.

17

bool StartLog(wchar_t *szFileName);

Starts saving the data collected by ReadSample() until StopLog() is called. Data will be written to the file specified by szFileName.

18

bool StopLog();

Stops saving data and writes all saved data to the file specified by the call to StartLog().

Table 2: Function Lookup
 

4.1 Notes of Caution

  1. The functions described in Table 2 return either true on success or false on failure.
  2. It is recommended to first verify if Intel® graphics is available via IsGTAvailable() before attempting to obtain GT frequency data via GetGTFrequency().
  3. The “PROCHOT” feature is available only in 3rd Generation Intel® Core™ processors or later.
  4. It is recommended that Package Power Limit is used instead of TDP whenever possible, as it is a more accurate upper bound to the package power than TDP.The ReadSample() function must be called twice before calling GetTimeInterval() and before getting power data (as opposed to frequency or temperature data) from GetPowerData(), as they are computed using the difference between two samples.
  5. When logging data, the data isn’t written into the log until StopLog() function is called. StartLog() will cause an initial call to ReadSample() and StopLog() causes the final call.
  6. The GetRDTSC() function has been deprecated from previous versions of the DLL.