Using the Intel® Power Gadget API on Mac OS X*
Mac OS X For Intel. Building a computer with Intel's technology shouldn't prove too difficult for Apple's engineers, but one of the most important factors in the transition to Intel-based Macs will be, as Jobs himself put it, 'making Mac OS X sing on Intel processors'. Mac OS X 10.6 Snow Leopard. Mac OS X 10.5 Leopard. Get it for PowerPC or 32bit Intel. Mac OS X 10.4 Tiger. Mac OS X 10.4.7 or later is required. Get it for PowerPC or Intel. Mac OS X 10.3 Panther. QuickTime 6.5.2 or later is required. Get it for PowerPC.
Intel® Power Gadget for Mac* is a GUI application that provides real-time data on processor frequency and estimated processor power, and can log frequency, power, energy, and temperature data over time. Intel® Power Gadget also provides a C Application Programming Interface (API) for accessing this power and frequency data in your program. Intel® Power Gadget is also available for Windows* and Linux*. Intel® Power Gadget and the API are only supported on 2nd generation and later Intel® Core processors, because previous processors do not support the necessary power Model Specific Registers (MSRs).
Intro to the Intel® Power Gadget API
The Intel® Power Gadget API is a framework (IntelPowerGadget .framework) that provides a C interface for reading current estimated processor power, current processor frequency, base frequency, thermal design power (TDP), current temperature, maximum temperature, timestamps, and elapsed time. It also provides logging functionality.
What You Need
To use the API you’ll need the Intel® Power Gadget for Mac* driver and framework. These are included in the Intel® Power Gadget installer, or as a standalone API installer. The driver is installed to /System/Library/Extensions/EnergyDriver.kext, and the framework is installed to /Library/Frameworks/IntelPowerGadget.framework.
To link with the Intel® Power Gadget API you simply need to include–framework IntelPowerGadget in your link command.
Using the Intel® Power Gadget API
To begin you must initialize the library by calling IntelEnergyLibInitialize.
The most common use of the Intel® Power Gadget API is to read samples with ReadSample. The API supports sampling of specific Model Specific Registers (MSRs). Meta data on the sampled MSRs can be queried with GetNumMsrs, GetMsrName, and GetMsrFunc. GetNumMsrs returns the number of sampled MSRs; MSRs are given an ID from 0 to n-1, where n is the number returned by GetNumMsrs. The MSR ID is used to get data for a specific MSR with functions GetPowerData, GetMsrName, and GetMsrFunc.
Calling GetPowerData for each sampled MSR will provide you with the relevant data from that MSR. An MSR’s function (from GetMsrFunc) determines the amount and meaning of data returned from GetPowerData. MSRs with function 0 (frequency) return 1 result, which represents the frequency in megahertz. MSRs with function 1 (power) return 3 results, which represent the average power in watts, cumulative energy in Joules, and cumulative energy in milliwatt-hours. MSRs with function 2 (temperature) return 1 result, which represents the temperature in degrees Celsius. The Intel® Power Gadget API currently supports sampling with the following MSRs: processor frequency, estimated processor power, and package temperature. The currently supported MSR functions are: frequency (0), power (1), temperature (2).
Intel Mac Os X 10_15_4
ReadSample also reads the system time and Time Stamp Counter (TSC) at the time the sample is read. These values are available via GetSysTime and GetRDTSC; the time interval between samples is available (in seconds) via GetTimeInterval. Note that you must call ReadSample prior to calling GetPowerData, GetRDTSC, and GetTimeInterval, and that you must call 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.
The Intel® Power Gadget API also supports reading generic MSRs with ReadMSR, which returns the raw data from the MSR. However, note that specifying an invalid MSR address can crash your system and could potentially corrupt it. There is no method to determine if an MSR address is valid. The API supports reading common individual MSRs without having to specify the MSR address or read an entire sample; the supported functions are: GetIAFrequency, GetMaxTemperature, GetTemperature, and GetTDP.
The sample data from ReadSample can be logged to a file. Logging can be enabled at any time by calling StartLog, and subsequently disabled by calling StopLog. Note that the logged data isn’t written until StopLog is called. Both StartLog and StopLog cause an internal call to ReadSample.
Sampling Considerations
The frequency at which you read samples may have an impact on the accuracy of data. The instantaneous processor frequency can change significantly from moment to moment. Frequency data may be more meaningful if you sample often and average the frequency samples over time. The processor power is calculated by taking the difference between two samples, thus a shorter interval between samples will result in more fine-grained power data. However, the frequency at which you read samples may also impact the performance of the system. Using a very short frequency (e.g. less than 20 milliseconds) may result in significant overhead, and may also increase the power consumption of the system, both of which may reduce the usefulness of the data. The Intel® Power Gadget application uses a default sampling frequency of 50 milliseconds, and updates the GUI with averaged frequency and power data every second.
Example
Download the Xcode project for this example application here.
API Reference
Initializes the library and connects to the driver.
Returns the number of CPU packages on the system.
Returns the number of supported MSRs for bulk reading and logging.
Returns in szName the name of the MSR specified by iMsr. Note that the Windows version uses wchar_t.
Returns in pFuncID the function of the MSR specified by iMsrCurrently supported functions are: 0 = frequency, 1 = power, 2 = temperature.
Reads the MSR specified by address on the package specified by iNode, and returns the value in value. Warning: Specifying an invalid MSR address can crash your system and could potentially corrupt it. There is no method to determine if an MSR address is valid.
Reads the processor frequency MSR on the package specified by iNode, and returns the frequency in MHz in freqInMHz.
Reads the package power info MSR on the package specified by iNode, and returns the TDP in watts in TDP.
Reads the temperature target MSR on the package specified by iNode, and returns the maximum temperature in degrees Celsius in degreeC.
Reads the temperature MSR on the package specified by iNode, and returns the current temperature in degrees Celsius in degreeC.
Reads sample data from the driver for all the supported MSRs. Note that two calls to ReadSample are necessary to calculate power data, as power data is calculated using the difference between two samples.
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
Returns in pTSC the processors time stamp counter as of the last call to ReadSample. Note that this function does not execute the rdtsc instruction directly, but instead returns the TSC from when the last sample was read.
Intel Mac Os X 10_14_5
Returns in pOffset the time in seconds that has elapsed between the two most recent calls to ReadSample.
Returns in pBaseFrequency the advertised processor frequency for the package specified by iNode.
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. Frequency MSRs (function 0) return 1 result, which represents the frequency in megahertz. Power MSRs (function 1) return 3 results, which represent the average power in watts, cumulative energy in Joules, and cumulative energy in milliwatt-hours. Temperature MSRs (function 2) return 1 result, which represents the temperature in degrees Celsius.
Starts saving the data collected by ReadSample. When StopLog is called, this data will be written to the file specified by szFileName. Note that the Windows version uses wchar_t. StartLog will cause an initial call to ReadSample.
Intel For Mac Os X 10.10
Stops saving data and writes all saved data to the file specified by the call to StartLog. StopLog will cause a final call to ReadSample.