Using the Intel® Power Gadget 3.0 API on Windows*

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 2^nd 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.

 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

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.