ADVISOR DETAILS

RECENT BLOG POSTS

Using the Intel® Power Gadget API on Windows*

Contributors: Seung-Woo Kim, 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, thermal design power (TDP), current processor frequency, base frequency, current temperature, maximum temperature, timestamps and elapsed time. The data is obtained from the Model Specific Registers (MSRs) that are available only in 2nd Generation Intel® Core™ or later processors.  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.

Table 1: MSR functions

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)

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

 

2. Developers’ Tools

The installer sets two environment variables on installation:

a.     IPG_Ver: Contains version of Intel® Power Gadget being installed.

b.    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 “PowerLog2.7-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 20 to 1000 milliseconds, the optimal sampling frequency of 50 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.  

ReadSample() also reads the system time via GetSysTime()  and Time Stamp Counter (TSC) via GetRDTSC() at the time the sample is 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().

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

Table 2: Function Lookup

 

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

9

bool GetRDTSC(unsigned __int64 *pTSC);

Returns in pTSC the processors time stamp counter as of the last call to ReadSample().

10

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.

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().

Notes of Caution

1.     The functions described in Table 2 return either true on success or false on failure.

2.     Prior to calling GetPowerData(), GetRDTSC(), and GetTimeInterval(), ReadSample() 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.

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

                                         

Read more >