powerd++  0.4.1
Manual powerd++(8)
powerd++(8)             FreeBSD System Manager's Manual            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>
FreeBSD 12.0-STABLE               9 May, 2017              FreeBSD 12.0-STABLE