powerd++(8)

NAME
powerd++ - CPU clock speed daemon

SYNOPSIS
powerd++ -h
powerd++ [-vf] [-a mode] [-b mode] [-n mode] [-m freq] [-M freq] [-F freq:freq] [-A freq:freq] [-B freq:freq] [-H temp:temp] [-p ival] [-s cnt] [-P file]

DESCRIPTION
The powerd++ daemon monitors the system load and adjusts the CPU clock speed accordingly. It is a drop-in replacement for powerd(8) and supports two modes of operation, a load feedback control loop or fixed frequency operation.

  ARGUMENTS
The following argument types can be given:

mode
    The mode is either a load target or a fixed freq. The powerd(8) modes are interpreted as follows:
    maximum, max
        Use the highest clock frequency.
    minimum, min
        Use the lowest clock frequency.
    adaptive, adp
        A target load of 0.5 (50%).
    hiadaptive, hadp
        A target load of 0.375 (37.5%).

    If a scalar number is given, it is interpreted as a load.

load
    A load is either a fraction in the range [0.0, 1.0] or a percentage in the range [0%, 100%].

freq
    A clock frequency consists of a number and a frequency unit.
        Hz, KHz, MHz, GHz, THz
    The unit is not case sensitive, if omitted MHz are assumed for compatibility with powerd(8).

temp
    A temperature consisting of a number and a temperature unit. Supported units are:
        C, K, F, R
    These units stand for deg. Celsius, Kelvin, deg. Fahrenheit and deg. Rankine. A value without a unit is treated as deg. Celsius.

ival
    A time interval can be given in seconds or milliseconds.
        s, ms
    An interval without a unit is treated as milliseconds.

cnt A positive integer.

file
    A file name.

  OPTIONS
The following options are supported:

-h, --help
    Show usage and exit

-v, --verbose
    Be verbose and produce initial diagnostics on stderr.

-f, --foreground
    Stay in foreground, produce an event log on stdout.

-a, --ac mode
    Mode to use while the AC power line is connected (default hadp).

-b, --batt mode
    Mode to use while battery powered (default adp).

-n, --unknown mode
    Mode to use while the power line state is unknown (default hadp).

-m, --min freq
    The lowest CPU clock frequency to use (default 0Hz).

-M, --max freq
    The highest CPU clock frequency to use (default 1THz).

--min-ac freq
    The lowest CPU clock frequency to use on AC power.

--max-ac freq
    The highest CPU clock frequency to use on AC power.

--min-batt freq
    The lowest CPU clock frequency to use on battery power.

--max-batt freq
    The highest CPU clock frequency to use on battery power.

-F, --freq-range freq:freq
    A pair of frequency values representing the minimum and maximum CPU clock frequency.

-A, --freq-range-ac freq:freq
    A pair of frequency values representing the minimum and maximum CPU clock frequency on AC power.

-B, --freq-range-batt freq:freq
    A pair of frequency values representing the minimum and maximum CPU clock frequency on battery power.

-H, --hitemp-range temp:temp
    Set the high to critical temperature range, enables temperature based throttling.

-p, --poll ival
    The polling interval that is used to take load samples and update the CPU clock (default 0.5s).

-s, --samples cnt
    The number of load samples to use to calculate the current load. The default is 4.

-P, --pid file
    Use an alternative pidfile, the default is /var/run/powerd.pid. The default ensures that powerd(8) and powerd++ are not run simultaneously.

-i, -r load
    Legacy arguments from powerd(8) not applicable to powerd++ and thus ignored.

SERVICE
The powerd++ daemon can be run as an rc(8) service. Add the following line to rc.conf(5):
    powerdxx_enable="YES"
Command line arguments can be set via powerdxx_flags.

TOOLS
The loadrec(1) and loadplay(1) tools offer the possibility to record system loads and replay them.

IMPLEMENTATION NOTES
This section describes the operation of powerd++.

Both powerd(8) and powerd++ have in common, that they work by polling kern.cp_times via sysctl(3), which is an array of the accumulated loads of every core. By subtracting the last cp_times sample the loads over the polling interval can be determined. This information is used to set a new CPU clock frequency by updating dev.cpu.0.freq.

  Initialisation
After parsing command line arguments powerd++ assigns a clock frequency controller to every core. I.e. cores are grouped by a common dev.cpu.%d.freq handle that controls the clock for all of them. Due to limitations of cpufreq(4) dev.cpu.0.freq is the controlling handle for all cores, even across multiple CPUs. However powerd++ is not built with that assumption and per CPU, core or thread controls will work as soon as the hardware and kernel support them.

In the next initialisation stage the available frequencies for every core group are determined to set appropriate lower and upper boundaries. This is a purely cosmetic measure and used to avoid unnecessary frequency updates. The controlling algorithm does not require this information, so failure to do so will only be reported (non-fatally) in verbose mode.

Unless the -H option is given, the initialisation checks for a critical temperature source. If one is found temperature throttling is implicitly turned on, causing throttling to start 10 deg. Celsius below the critical temperature.

So far the sysctl(3) dev.cpu.%d.coretemp.tjmax is the only supported critical temperature source.

  Detaching From the Terminal
After the initialisation phase powerd++ prepares to detach from the terminal. The first step is to acquire a lock on the pidfile. Afterwards all the frequencies are read and written as a last opportunity to fail. After detaching from the terminal the pidfile is written and the daemon goes into frequency controlling operation until killed by a signal.

  Load Control Loop
The original powerd(8) uses a hysteresis to control the CPU frequency. I.e. it determines the load over all cores since taking the last sample (the summary load during the last polling interval) and uses a lower and an upper load boundary to decide whether it should update the frequency or not.

powerd++ has some core differences. It can take more than two samples (four by default), this makes it more robust against small spikes in load, while retaining much of its ability to quickly react to sudden surges in load. Changing the number of samples does not change the runtime cost of running powerd++.

Instead of taking the sum of all loads, the highest load within the core group is used to decide the next frequency target. Like with powerd(8) this means, that high load on a single core will cause an increase in the clock frequency. Unlike powerd(8) it also means that moderate load over all cores allows a decrease of the clock frequency.

The powerd++ daemon steers the clock frequency to match a load target, e.g. if there was a 25% load at 2 GHz and the load target was 50%, the frequency would be set to 1 GHz.

  Temperature Based Throttling
If temperature based throttling is active and the temperature is above the high temperature boundary (the critical temperature minus 10 deg. Celsius by default), the core clock is limited to a value below the permitted maximum. The limit depends on the remaining distance to the critical temperature.

Thermal throttling ignores user-defined frequency limits, i.e. when using -F, -B, -A or -m to prevent the clock from going unreasonably low, sufficient thermal load may cause powerd++ to select a clock frequency below the user provided minimum.

  Termination and Signals
The signals HUP and TERM cause an orderly shutdown of powerd++. An orderly shutdown means the pidfile is removed and the clock frequencies are restored to their original values.

FILES

/var/run/powerd.pid
    Common pidfile with powerd(8).

/usr/local/etc/rc.d/powerdxx
    Service file, enable in rc.conf(5).

EXAMPLES
Run in foreground, minimum clock frequency 800 MHz:
    powerd++ -fm800

Report configuration before detaching into the background:
    powerd++ -v

Target 75% load on battery power and run at 2.4 GHz on AC power:
    powerd++ -b .75 -a 2.4ghz

Target 25% load on AC power:
    powerd++ -a 25%

Use the same load sampling powerd(8) does:
    powerd++ -s1 -p.25s

Limit CPU clock frequencies to a range from 800 MHz to 1.8 GHz:
    powerd++ -F800:1.8ghz

DIAGNOSTICS
The powerd++ daemon exits 0 on receiving an INT or TERM signal, and >0 if an error occurs.

COMPATIBILITY
So far powerd++ requires ACPI to detect the current power line state.

SEE ALSO
cpufreq(4), powerd(8), loadrec(1), loadplay(1)

AUTHORS
Implementation and manual by Dominic Fandrey <kami@freebsd.org>