msr_rapl.h File Reference

#include <stdint.h>
#include <stdio.h>
#include <sys/time.h>
#include "master.h"

Include dependency graph for msr_rapl.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rapl_units
	Structure containing units for energy, time, and power across all RAPL power domains. More...
struct	rapl_data
	Structure containing data from energy, time, and power measurements of various RAPL power domains. More...
struct	rapl_limit
	Structure containing power limit data for a given RAPL power domain. More...
struct	rapl_power_info
	Structure containing power range info for RAPL usage for various RAPL power domains. More...

Macros
#define	MF_06_37   (0x407)
#define	MF_06_4A   (0x407)
#define	MF_06_5A   (0x407)
#define	MF_06_4D   (0x20003)
#define	MF_06_4C   (0x607)
#define	MF_06_2A   (0xFE17)
#define	MF_06_2D   (0x7FF)
#define	MF_06_3A   (0xFE17)
#define	MF_06_3E   (0x6007F7)
#define	MF_06_3C   (0x1CEE17)
#define	MF_06_45   (0x1CFE17)
#define	MF_06_46   (0x1CFE17)
#define	MF_06_3F   (0x1C01FF)
#define	MF_06_3D   (0x1CFE17)
#define	MF_06_47   (0x1CFE17)
#define	MF_06_4F   (0x1CFE17)
#define	MF_06_56   (0x1CFE17)
#define	MF_06_4E   (0x1EFE17)
#define	MF_06_5E   (0x1EFE17)
#define	MF_06_57   (0x507FF)
#define	POWER_UNIT   (0x1L)
#define	PKG_POWER_LIMIT   (0x2L)
#define	PKG_ENERGY_STATUS   (0x4L)
#define	PKG_PERF_STATUS   (0x8L)
#define	PKG_POWER_INFO   (0x10L)
#define	DRAM_POWER_LIMIT   (0x20L)
#define	DRAM_ENERGY_STATUS   (0x40L)
#define	DRAM_PERF_STATUS   (0x80L)
#define	DRAM_POWER_INFO   (0x100L)
#define	PP0_POWER_LIMIT   (0x200L)
#define	PP0_ENERGY_STATUS   (0x400L)
#define	PP0_POLICY   (0x800L)
#define	PP0_PERF_STATUS   (0x1000L)
#define	PP1_POWER_LIMIT   (0x2000L)
#define	PP1_ENERGY_STATUS   (0x4000L)
#define	PP1_POLICY   (0x8000L)
#define	TURBO_ACTIVATION_RATIO   (0x10000L)
#define	TURBO_RATIO_LIMIT   (0x200000L)
#define	TURBO_RATIO_LIMIT1   (0x400000L)
#define	UINT_MAX   4294967295U
#define	STD_ENERGY_UNIT   65536.0

Enumerations
enum	libmsr_unit_conversions_e {   BITS_TO_WATTS,   WATTS_TO_BITS,   BITS_TO_JOULES,   JOULES_TO_BITS,   BITS_TO_SECONDS_STD,   SECONDS_TO_BITS_STD,   BITS_TO_SECONDS_HASWELL,   SECONDS_TO_BITS_HASWELL,   BITS_TO_JOULES_DRAM }
	Enum encompassing unit conversion types. More...

Functions
int	rapl_storage (struct rapl_data **data, uint64_t **flags)
	Store the RAPL data and flags on the heap.
int	print_available_rapl (void)
	Print available RAPL registers based on platform-dependent flags.
int	rapl_init (struct rapl_data **rapl, uint64_t **rapl_flags)
	Initialize storage for Running Average Power Limit (RAPL) data and flags.
int	set_pkg_rapl_limit (const unsigned socket, struct rapl_limit *limit1, struct rapl_limit *limit2)
	Determine the steps necessary to set the user-supplied package-level power limit(s).
int	set_dram_rapl_limit (const unsigned socket, struct rapl_limit *limit)
	Determine the steps necessary to set the user-supplied DRAM limit.
int	set_pp_rapl_limit (const unsigned socket, struct rapl_limit *limit0, struct rapl_limit *limit1)
	Determine the steps necessary to set the user-supplied power plane limit.
int	get_rapl_power_info (const unsigned socket, struct rapl_power_info *info)
	Get power info data for all RAPL power domains.
int	set_pp_rapl_policies (const unsigned socket, uint64_t *pp0, uint64_t *pp1)
	Determine the steps necessary to set the user-supplied power plane policy.
int	get_pp_rapl_policies (const unsigned socket, uint64_t *pp0, uint64_t *pp1)
	Get RAPL policies for the power plane domains.
int	get_pkg_rapl_limit (const unsigned socket, struct rapl_limit *limit1, struct rapl_limit *limit2)
	Get RAPL power limit for the package domain.
int	get_dram_rapl_limit (const unsigned socket, struct rapl_limit *limit)
	Get RAPL power limit for the DRAM domain.
int	get_pp_rapl_limit (const unsigned socket, struct rapl_limit *limit0, struct rapl_limit *limit1)
	Get RAPL power limit for the power plane domains.
void	dump_rapl_limit (struct rapl_limit *L, FILE *writedest)
	Print out RAPL power limit.
int	dump_rapl_data_terse_label (FILE *writedest)
	Print the label for the abbreviated RAPL data print out.
int	dump_rapl_data_terse (FILE *writedest)
	Print abbreviated RAPL data.
int	dump_rapl_data (FILE *writedest)
	Print out a specified RAPL data item.
int	dump_rapl_power_info (FILE *writedest)
	Print out only RAPL power data.
int	poll_rapl_data (void)
	Read the current RAPL data and calculate the deltas from the previous call to this function.
int	delta_rapl_data (void)
	Check how much the RAPL data has changed overtime to derive time-based values, such as power.
int	read_rapl_data (void)
	Read all available RAPL data for a given socket.
void	get_rapl_power_unit (struct rapl_units *ru)
	Get units for RAPL power data.
void	dump_rapl_power_unit (FILE *writedest)
	Print out RAPL power units (power, energy, time).

Macro Definition Documentation

#define DRAM_ENERGY_STATUS   (0x40L)

#define DRAM_PERF_STATUS   (0x80L)

#define DRAM_POWER_INFO   (0x100L)

#define DRAM_POWER_LIMIT   (0x20L)

#define MF_06_2A   (0xFE17)

#define MF_06_2D   (0x7FF)

#define MF_06_37   (0x407)

#define MF_06_3A   (0xFE17)

#define MF_06_3C   (0x1CEE17)

#define MF_06_3D   (0x1CFE17)

#define MF_06_3E   (0x6007F7)

#define MF_06_3F   (0x1C01FF)

#define MF_06_45   (0x1CFE17)

#define MF_06_46   (0x1CFE17)

#define MF_06_47   (0x1CFE17)

#define MF_06_4A   (0x407)

#define MF_06_4C   (0x607)

#define MF_06_4D   (0x20003)

#define MF_06_4E   (0x1EFE17)

#define MF_06_4F   (0x1CFE17)

#define MF_06_56   (0x1CFE17)

#define MF_06_57   (0x507FF)

#define MF_06_5A   (0x407)

#define MF_06_5E   (0x1EFE17)

#define PKG_ENERGY_STATUS   (0x4L)

#define PKG_PERF_STATUS   (0x8L)

#define PKG_POWER_INFO   (0x10L)

#define PKG_POWER_LIMIT   (0x2L)

#define POWER_UNIT   (0x1L)

#define PP0_ENERGY_STATUS   (0x400L)

#define PP0_PERF_STATUS   (0x1000L)

#define PP0_POLICY   (0x800L)

#define PP0_POWER_LIMIT   (0x200L)

#define PP1_ENERGY_STATUS   (0x4000L)

#define PP1_POLICY   (0x8000L)

#define PP1_POWER_LIMIT   (0x2000L)

#define STD_ENERGY_UNIT   65536.0

#define TURBO_ACTIVATION_RATIO   (0x10000L)

#define TURBO_RATIO_LIMIT   (0x200000L)

#define TURBO_RATIO_LIMIT1   (0x400000L)

#define UINT_MAX   4294967295U

Enumeration Type Documentation

enum libmsr_unit_conversions_e

Enum encompassing unit conversion types.

Enumerator:

BITS_TO_WATTS	Decode raw bits into Watts.
WATTS_TO_BITS	Encode Watt value to raw bits.
BITS_TO_JOULES	Decode raw bits into Joules.
JOULES_TO_BITS	Encode Joule value to raw bits.
BITS_TO_SECONDS_STD	Decode raw bits to seconds (for Sandy Bridge and Ivy Bridge).
SECONDS_TO_BITS_STD	Encode seconds value to raw bits (for Sandy Bridge and Ivy Bridge).
BITS_TO_SECONDS_HASWELL	Decode raw bits to seconds (for Haswell).
SECONDS_TO_BITS_HASWELL	Encode seconds value to raw bits (for Haswell).
BITS_TO_JOULES_DRAM	Decode raw bits to Joules for DRAM.

Function Documentation

int delta_rapl_data

(

void

)

Check how much the RAPL data has changed overtime to derive time-based values, such as power.

Returns

0 if successful, else -1 if rapl_storage() fails.

int dump_rapl_data

(

FILE *

writedest

)

Print out a specified RAPL data item.

Parameters

[in]

writedest

File stream where output will be written to.

Returns

0 if successful, else -1 if rapl_storage() fails.

int dump_rapl_data_terse

(

FILE *

writedest

)

Print abbreviated RAPL data.

Parameters

[in]

writedest

File stream where output will be written to.

Returns

0 if successful, else -1 if rapl_storage() fails.

int dump_rapl_data_terse_label

(

FILE *

writedest

)

Print the label for the abbreviated RAPL data print out.

Parameters

[in]

writedest

File stream where output will be written to.

Returns

0 if successful, else -1 if rapl_storage() fails.

void dump_rapl_limit	(	struct rapl_limit *	L,
		FILE *	writedest
	)

Print out RAPL power limit.

Parameters

[in]	L	RAPL power limit for a given domain.
[in]	writedest	File stream where output will be written to.

int dump_rapl_power_info

(

FILE *

writedest

)

Print out only RAPL power data.

Parameters

[in]

writedest

File stream where output will be written to.

Returns

0 if successful, else -1 if rapl_storage() fails.

void dump_rapl_power_unit

(

FILE *

writedest

)

Print out RAPL power units (power, energy, time).

Parameters

[in]

writedest

File stream where output will be written to.

Returns

0 if successful, else -1 if rapl_storage() fails.

int get_dram_rapl_limit	(	const unsigned	socket,
		struct rapl_limit *	limit
	)

Get RAPL power limit for the DRAM domain.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds. If the bit vector is zero, read the msr value into the bit vector and translate into watts and seconds.

Parameters

[in]	socket	Identifier of socket to read
[out]	limit	Data for DRAM domain RAPL power limit.

Returns

0 if successful, else -1 if rapl_storage() fails.

int get_pkg_rapl_limit	(	const unsigned	socket,
		struct rapl_limit *	limit1,
		struct rapl_limit *	limit2
	)

Get RAPL power limit for the package domain.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds. If the bit vector is zero, read the msr value into the bit vector and translate into watts and seconds.

Parameters

[in]	socket	Identifier of socket to read
[out]	limit1	Data for package domain RAPL power limit 1 (lower).
[out]	limit2	Data for package domain RAPL power limit 2 (upper).

Returns

0 if successful, else -1 if rapl_storage() fails.

int get_pp_rapl_limit	(	const unsigned	socket,
		struct rapl_limit *	limit0,
		struct rapl_limit *	limit1
	)

Get RAPL power limit for the power plane domains.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds. If the bit vector is zero, read the msr value into the bit vector and translate into watts and seconds.

Parameters

[in]	socket	Identifier of socket to read
[out]	limit0	Data for PP0 domain RAPL power limit.
[out]	limit1	Data for PP1 domain RAPL power limit.

Returns

0 if successful, else -1 if rapl_storage() fails.

int get_pp_rapl_policies	(	const unsigned	socket,
		uint64_t *	pp0,
		uint64_t *	pp1
	)

Get RAPL policies for the power plane domains.

Parameters

[in]	socket	Unique socket/package identifier.
[out]	pp0	Raw 64-bit value stored in MSR_PP0_POLICY.
[out]	pp1	Raw 64-bit value stored in MSR_PP1_POLICY.

Returns

0 if successful, else -1 if rapl_storage() fails.

int get_rapl_power_info	(	const unsigned	socket,
		struct rapl_power_info *	info
	)

Get power info data for all RAPL power domains.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds. If the bit vector is zero, read the msr value into the bit vector and translate into watts and seconds.

Parameters

[in]	socket	Unique socket/package identifier.
[out]	info	Data for domain-specific power range info for RAPL usage.

Returns

0 if successful, else -1 if rapl_storage() fails.

void get_rapl_power_unit

(

struct rapl_units *

ru

)

Get units for RAPL power data.

Parameters

[out]

ru

Data for RAPL power units.

int poll_rapl_data

(

void

)

Read the current RAPL data and calculate the deltas from the previous call to this function.

If this function has not been called at least once, then the data will be initialized to zeros. NOTE: This is now what you use instead of read_rapl_data().

Returns

0 if successful, else -1 if rapl_storage() fails.

int print_available_rapl

(

void

)

Print available RAPL registers based on platform-dependent flags.

Returns

0 if successful, else -1 if rapl_storage() fails.

int rapl_init	(	struct rapl_data **	rapl,
		uint64_t **	rapl_flags
	)

Initialize storage for Running Average Power Limit (RAPL) data and flags.

Be sure to put this function before any other RAPL functions.

Parameters

[out]	rapl	Pointer to storage for energy, time, and power data measurements from a given RAPL power domain.
[out]	rapl_flags	Pointer to storage for flags indicating available on registers on platform.

Returns

Number of locked registers, else -1 if rapl_storage() fails.

int rapl_storage	(	struct rapl_data **	data,
		uint64_t **	flags
	)

Store the RAPL data and flags on the heap.

This data will be used by nearly all other RAPL APIs. A user can retrieve only RAPL data or only RAPL flags by passing a NULL argument.

Parameters

[out]	data	Pointer to measurements of energy, time, and power data from a given RAPL power domain.
[out]	flags	Pointer to RAPL flags indicating available registers on a given platform.

Returns

0 if successful, else -1 if setflags() fails.

int read_rapl_data

(

void

)

Read all available RAPL data for a given socket.

Returns

0 if successful, else -1 if rapl_storage() fails.

int set_dram_rapl_limit	(	const unsigned	socket,
		struct rapl_limit *	limit
	)

Determine the steps necessary to set the user-supplied DRAM limit.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds and write the bit vector to the msr. If the bit vector is zero, translate the watts and seconds to the appropriate bit vector and write the bit vector to the msr.

Parameters

[in]	socket	Unique socket/package identifier.
[out]	limit	RAPL power limit data for DRAM power domain.

Returns

0 if successful, else -1 if rapl_storage() fails, if calc_std_rapl_limit() fails, or if DRAM RAPL domain power limit is not supported on the platform.

int set_pkg_rapl_limit	(	const unsigned	socket,
		struct rapl_limit *	limit1,
		struct rapl_limit *	limit2
	)

Determine the steps necessary to set the user-supplied package-level power limit(s).

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds and write the bit vector to the msr. If the bit vector is zero, translate the watts and seconds to the appropriate bit vector and write the bit vector to the msr.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	limit1	Data for lower power limit 1.
[in]	limit2	Data for upper power limit 2.

Returns

0 if successful, else -1 if rapl_storage() fails or if package RAPL domain power limit is not supported on the platform.

int set_pp_rapl_limit	(	const unsigned	socket,
		struct rapl_limit *	limit0,
		struct rapl_limit *	limit1
	)

Determine the steps necessary to set the user-supplied power plane limit.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds and write the bit vector to the msr. If the bit vector is zero, translate the watts and seconds to the appropriate bit vector and write the bit vector to the msr.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	limit0	Data for PP0 power limit.
[in]	limit1	Data for PP1 power limit.

Returns

0 if successful, else -1 if rapl_storage() or calc_std_rapl_limit() fails.

int set_pp_rapl_policies	(	const unsigned	socket,
		uint64_t *	pp0,
		uint64_t *	pp1
	)

Determine the steps necessary to set the user-supplied power plane policy.

If a pointer is null, do nothing. If the bit vector is nonzero, translate the bit vector to watts and seconds and write the bit vector to the msr. If the bit vector is zero, translate the watts and seconds to the appropriate bit vector and write the bit vector to the msr.

Parameters

[in]	socket	Unique socket/package identifier.
[in]	pp0	Raw 64-bit value specifying desired policy for PP0.
[in]	pp1	Raw 64-bit value specifying desired policy for PP1.

Returns

0 if successful, else -1 if rapl_storage() fails.