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.

sysctl

The name of a sysctl(3), may consists of the characters [0-9A-Za-z%._-]. Characters preceded by ‘%’ are considered formatting fields. Allowed formatting fields are specific to a particular sysctl. Unexpected formatting fields are rejected. In order to produce a literal ‘%’, ‘%%’ should be used.

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.

-N, --idle-nice

Treat nice time as idle.

This option exists for powerd(8) compatibility, but note that most heavy workloads such as compiling software mostly consist of nice time. Users considering this flag may be better served with running at a fixed low frequency:

powerd++ -b min

-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.

-t, --temperature sysctl

Set the temperature source sysctl name. May contain a single ‘%d’ to insert the core ID.

-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.

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.