gorapl

README

goRAPL

A dead-simple, low-level API for accessing the Intel RAPL API.

Install

gorapl uses modules for dependency management. This means you'll need at least go 1.11. With that in mind:

$ go get github.com/fearful-symmetry/gorapl

This is a rather experimental library that's early on in it's life, so it isn't very useful yet! It has a lot of shortcomings, and a lot of things that needs to do, but can't. Most notably, it can only handle systems with one CPU socket. TODOs and progress is being tracked on the issues page.

Usage & caveats

Unless you're using something like msr-safe, gorapl requres root to access the underlying msr device at /dev/cpu/$CPU/msr.

If that device doesn't exist, you might need to load the kernel module:

$ sudo modprobe msr

Not all Intel CPUs support RAPL. The feature was introduced in Sandy Bridge, and available domains vary by processor. A quick way to check:

$ sudo rdmsr -a 0x611 #rdmsr is part of the msr-tools package on most linuxes

#You can check to see if the kernel picked up an RAPL domains too:

$ dmesg | grep rapl

Now that' you're ready to go, using gorapl is easy:

    h, err := NewRAPL(0)
    if err != nil {
        // ...
    }

	dat, err := h.ReadPowerLimit(DRAM)
	if err != nil {
		//
	}
	fmt.Printf("Current RAPL power limit settings: %#v\n", dat)

Documentation

Index

• Constants
• Variables
• type PowerLimitSetting
• type RAPLDomain
• type RAPLHandler
  • func NewRAPL(cpu int) (RAPLHandler, error)
  • func (h RAPLHandler) ReadEnergyStatus(domain RAPLDomain) (float64, error)
  • func (h RAPLHandler) ReadPerfStatus(domain RAPLDomain) (float64, error)
  • func (h RAPLHandler) ReadPolicy(domain RAPLDomain) (uint64, error)
  • func (h RAPLHandler) ReadPowerInfo(domain RAPLDomain) (RAPLPowerInfo, error)
  • func (h RAPLHandler) ReadPowerLimit(domain RAPLDomain) (RAPLPowerLimit, error)
  • func (h RAPLHandler) ReadPowerUnit() (RAPLPowerUnit, error)
• type RAPLPowerInfo
• type RAPLPowerLimit
• type RAPLPowerUnit

Constants

const MSRPowerUnit int64 = 0x606

MSRPowerUnit specifies the MSR for the MSR_RAPL_POWER_UNIT register

Variables

var DRAM = RAPLDomain{0x2, "DRAM", domainMSRs{0x618, 0x619, 0x0, 0x61b, 0x61c}}

DRAM is the RAPL domain for the DRAM

var PP0 = RAPLDomain{0x4, "PP0", domainMSRs{0x638, 0x639, 0x63a, 0x63a, 0x0}}

PP0 is the RAPL domain for the processor core

var PP1 = RAPLDomain{0x8, "PP1", domainMSRs{0x640, 0x641, 0x642, 0x0, 0x0}}

PP1 is platform-dependant, although it usually refers to some uncore power plane

var Package = RAPLDomain{0x1, "Package", domainMSRs{0x610, 0x611, 0x0, 0x613, 0x614}}

Package is the RAPL domain for the CPU package

Types

type PowerLimitSetting

type PowerLimitSetting struct {
	//Sets the average power usage limits in Watts
	PowerLimit float64
	//Enables or disables the power limit
	EnableLimit bool
	//If enabled, this allows RAPL to turn down the processor frequency below what the OS has requested
	ClampingLimit bool
	//The time window,in seconds, over which the RAPL limit will be measured
	TimeWindowLimit float64
}

PowerLimitSetting specifies a power limit for a given time window

type RAPLDomain

type RAPLDomain struct {
	// contains filtered or unexported fields
}

RAPLDomain is a string type that covers the various RAPL domains

type RAPLHandler

type RAPLHandler struct {
	// contains filtered or unexported fields
}

RAPLHandler manages a stateful connection to the RAPL system.

func NewRAPL

func NewRAPL(cpu int) (RAPLHandler, error)

NewRAPL returns a new RAPL handler

func (RAPLHandler) ReadEnergyStatus

func (h RAPLHandler) ReadEnergyStatus(domain RAPLDomain) (float64, error)

ReadEnergyStatus returns the MSR_[DOMAIN]_ENERGY_STATUS MSR This MSR is a single 32 bit field that reports the energy usage for the domain. Updated ~1ms. Every domain has this MSR. This is a cumulative register

func (RAPLHandler) ReadPerfStatus

func (h RAPLHandler) ReadPerfStatus(domain RAPLDomain) (float64, error)

ReadPerfStatus returns the MSR_[DOMAIN]_PERF_STATUS msr. This is a single value. The value is the amount of time that the domain has been throttled due to RAPL limits. This is not available on PP1.

func (RAPLHandler) ReadPolicy

func (h RAPLHandler) ReadPolicy(domain RAPLDomain) (uint64, error)

ReadPolicy returns the MSR_[DOMAIN]_POLICY msr. This constists of a single value. The value is a priority that balances energy between the core and uncore devices. It's only available on the PP0/PP1 domains.

func (RAPLHandler) ReadPowerInfo

func (h RAPLHandler) ReadPowerInfo(domain RAPLDomain) (RAPLPowerInfo, error)

ReadPowerInfo returns the MSR_[DOMAIN]_POWER_INFO MSR. This MSR is not available on PP0/PP1

func (RAPLHandler) ReadPowerLimit

func (h RAPLHandler) ReadPowerLimit(domain RAPLDomain) (RAPLPowerLimit, error)

ReadPowerLimit returns the MSR_[DOMAIN]_POWER_LIMIT MSR This MSR defines power limits for the given domain. Every domain has this MSR

func (RAPLHandler) ReadPowerUnit

func (h RAPLHandler) ReadPowerUnit() (RAPLPowerUnit, error)

ReadPowerUnit returns the MSR_RAPL_POWER_UNIT MSR This has no associated domain

type RAPLPowerInfo

type RAPLPowerInfo struct {
	ThermalSpecPower float64
	MinPower         float64
	MaxPower         float64
	MaxTimeWindow    float64
}

RAPLPowerInfo contains the data from the MSR_[DOMAIN]_POWER_INFO MSR

type RAPLPowerLimit

type RAPLPowerLimit struct {
	Limit1 PowerLimitSetting
	Limit2 PowerLimitSetting
	Lock   bool
}

RAPLPowerLimit contains the data in the MSR_[DOMAIN]_POWER_LIMIT MSR This MSR containers two power limits. From the SDM: "Two power limits can be specified, corresponding to time windows of different sizes" "Each power limit provides independent clamping control that would permit the processor cores to go below OS-requested state to meet the power limits."

type RAPLPowerUnit

type RAPLPowerUnit struct {
	//PowerUnits is a multiplier for power related information in watts
	PowerUnits float64
	//EnergyStatusUnits is a multiplier for energy related information in joules
	EnergyStatusUnits float64
	//TimeUnits is a multiplier for time related information in seconds
	TimeUnits float64
}

RAPLPowerUnit contains the data in the MSR_RAPL_POWER_UNIT MSR