Documentation/cpu-freq/governors.txt

   1      CPU frequency and voltage scaling code in the Linux(TM) kernel
   2
   3
   4                          L i n u x    C P U F r e q
   5
   6                       C P U F r e q   G o v e r n o r s
   7
   8                    - information for users and developers -
   9
  10
  11                     Dominik Brodowski  <linux@brodo.de>
  12             some additions and corrections by Nico Golde <nico@ngolde.de>
  13
  14
  15
  16    Clock scaling allows you to change the clock speed of the CPUs on the
  17     fly. This is a nice method to save battery power, because the lower
  18             the clock speed, the less power the CPU consumes.
  19
  20
  21 Contents:
  22 ---------
  23 1.   What is a CPUFreq Governor?
  24
  25 2.   Governors In the Linux Kernel
  26 2.1  Performance
  27 2.2  Powersave
  28 2.3  Userspace
  29 2.4  Ondemand
  30 2.5  Conservative
  31
  32 3.   The Governor Interface in the CPUfreq Core
  33
  34
  35
  36 1. What Is A CPUFreq Governor?
  37 ==============================
  38
  39 Most cpufreq drivers (except the intel_pstate and longrun) or even most
  40 cpu frequency scaling algorithms only offer the CPU to be set to one
  41 frequency. In order to offer dynamic frequency scaling, the cpufreq
  42 core must be able to tell these drivers of a "target frequency". So
  43 these specific drivers will be transformed to offer a "->target/target_index"
  44 call instead of the existing "->setpolicy" call. For "longrun", all
  45 stays the same, though.
  46
  47 How to decide what frequency within the CPUfreq policy should be used?
  48 That's done using "cpufreq governors". Two are already in this patch
  49 -- they're the already existing "powersave" and "performance" which
  50 set the frequency statically to the lowest or highest frequency,
  51 respectively. At least two more such governors will be ready for
  52 addition in the near future, but likely many more as there are various
  53 different theories and models about dynamic frequency scaling
  54 around. Using such a generic interface as cpufreq offers to scaling
  55 governors, these can be tested extensively, and the best one can be
  56 selected for each specific use.
  57
  58 Basically, it's the following flow graph:
  59
  60 CPU can be set to switch independently   |         CPU can only be set
  61       within specific "limits"           |       to specific frequencies
  62
  63                                  "CPUfreq policy"
  64                 consists of frequency limits (policy->{min,max})
  65                      and CPUfreq governor to be used
  66                          /                    \
  67                         /                      \
  68                        /                       the cpufreq governor decides
  69                       /                        (dynamically or statically)
  70                      /                         what target_freq to set within
  71                     /                          the limits of policy->{min,max}
  72                    /                                \
  73                   /                                  \
  74         Using the ->setpolicy call,              Using the ->target/target_index call,
  75             the limits and the                    the frequency closest
  76              "policy" is set.                     to target_freq is set.
  77                                                   It is assured that it
  78                                                   is within policy->{min,max}
  79
  80
  81 2. Governors In the Linux Kernel
  82 ================================
  83
  84 2.1 Performance
  85 ---------------
  86
  87 The CPUfreq governor "performance" sets the CPU statically to the
  88 highest frequency within the borders of scaling_min_freq and
  89 scaling_max_freq.
  90
  91
  92 2.2 Powersave
  93 -------------
  94
  95 The CPUfreq governor "powersave" sets the CPU statically to the
  96 lowest frequency within the borders of scaling_min_freq and
  97 scaling_max_freq.
  98
  99
 100 2.3 Userspace
 101 -------------
 102
 103 The CPUfreq governor "userspace" allows the user, or any userspace
 104 program running with UID "root", to set the CPU to a specific frequency
 105 by making a sysfs file "scaling_setspeed" available in the CPU-device
 106 directory.
 107
 108
 109 2.4 Ondemand
 110 ------------
 111
 112 The CPUfreq governor "ondemand" sets the CPU depending on the
 113 current usage. To do this the CPU must have the capability to
 114 switch the frequency very quickly.
 115
 116 Sysfs files:
 117
 118 * sampling_rate:
 119
 120   Measured in uS (10^-6 seconds), this is how often you want the kernel
 121   to look at the CPU usage and to make decisions on what to do about the
 122   frequency.  Typically this is set to values of around '10000' or more.
 123   It's default value is (cmp. with users-guide.txt): transition_latency
 124   * 1000.  Be aware that transition latency is in ns and sampling_rate
 125   is in us, so you get the same sysfs value by default.  Sampling rate
 126   should always get adjusted considering the transition latency to set
 127   the sampling rate 750 times as high as the transition latency in the
 128   bash (as said, 1000 is default), do:
 129
 130   $ echo `$(($(cat cpuinfo_transition_latency) * 750 / 1000)) > ondemand/sampling_rate
 131
 132 * sampling_rate_min:
 133
 134   The sampling rate is limited by the HW transition latency:
 135   transition_latency * 100
 136
 137   Or by kernel restrictions:
 138   - If CONFIG_NO_HZ_COMMON is set, the limit is 10ms fixed.
 139   - If CONFIG_NO_HZ_COMMON is not set or nohz=off boot parameter is
 140     used, the limits depend on the CONFIG_HZ option:
 141     HZ=1000: min=20000us  (20ms)
 142     HZ=250:  min=80000us  (80ms)
 143     HZ=100:  min=200000us (200ms)
 144
 145   The highest value of kernel and HW latency restrictions is shown and
 146   used as the minimum sampling rate.
 147
 148 * up_threshold:
 149
 150   This defines what the average CPU usage between the samplings of
 151   'sampling_rate' needs to be for the kernel to make a decision on
 152   whether it should increase the frequency.  For example when it is set
 153   to its default value of '95' it means that between the checking
 154   intervals the CPU needs to be on average more than 95% in use to then
 155   decide that the CPU frequency needs to be increased.
 156
 157 * ignore_nice_load:
 158
 159   This parameter takes a value of '0' or '1'. When set to '0' (its
 160   default), all processes are counted towards the 'cpu utilisation'
 161   value.  When set to '1', the processes that are run with a 'nice'
 162   value will not count (and thus be ignored) in the overall usage
 163   calculation.  This is useful if you are running a CPU intensive
 164   calculation on your laptop that you do not care how long it takes to
 165   complete as you can 'nice' it and prevent it from taking part in the
 166   deciding process of whether to increase your CPU frequency.
 167
 168 * sampling_down_factor:
 169
 170   This parameter controls the rate at which the kernel makes a decision
 171   on when to decrease the frequency while running at top speed. When set
 172   to 1 (the default) decisions to reevaluate load are made at the same
 173   interval regardless of current clock speed. But when set to greater
 174   than 1 (e.g. 100) it acts as a multiplier for the scheduling interval
 175   for reevaluating load when the CPU is at its top speed due to high
 176   load. This improves performance by reducing the overhead of load
 177   evaluation and helping the CPU stay at its top speed when truly busy,
 178   rather than shifting back and forth in speed. This tunable has no
 179   effect on behavior at lower speeds/lower CPU loads.
 180
 181 * powersave_bias:
 182
 183   This parameter takes a value between 0 to 1000. It defines the
 184   percentage (times 10) value of the target frequency that will be
 185   shaved off of the target. For example, when set to 100 -- 10%, when
 186   ondemand governor would have targeted 1000 MHz, it will target
 187   1000 MHz - (10% of 1000 MHz) = 900 MHz instead. This is set to 0
 188   (disabled) by default.
 189
 190   When AMD frequency sensitivity powersave bias driver --
 191   drivers/cpufreq/amd_freq_sensitivity.c is loaded, this parameter
 192   defines the workload frequency sensitivity threshold in which a lower
 193   frequency is chosen instead of ondemand governor's original target.
 194   The frequency sensitivity is a hardware reported (on AMD Family 16h
 195   Processors and above) value between 0 to 100% that tells software how
 196   the performance of the workload running on a CPU will change when
 197   frequency changes. A workload with sensitivity of 0% (memory/IO-bound)
 198   will not perform any better on higher core frequency, whereas a
 199   workload with sensitivity of 100% (CPU-bound) will perform better
 200   higher the frequency. When the driver is loaded, this is set to 400 by
 201   default -- for CPUs running workloads with sensitivity value below
 202   40%, a lower frequency is chosen. Unloading the driver or writing 0
 203   will disable this feature.
 204
 205
 206 2.5 Conservative
 207 ----------------
 208
 209 The CPUfreq governor "conservative", much like the "ondemand"
 210 governor, sets the CPU depending on the current usage.  It differs in
 211 behaviour in that it gracefully increases and decreases the CPU speed
 212 rather than jumping to max speed the moment there is any load on the
 213 CPU.  This behaviour more suitable in a battery powered environment.
 214 The governor is tweaked in the same manner as the "ondemand" governor
 215 through sysfs with the addition of:
 216
 217 * freq_step:
 218
 219   This describes what percentage steps the cpu freq should be increased
 220   and decreased smoothly by.  By default the cpu frequency will increase
 221   in 5% chunks of your maximum cpu frequency.  You can change this value
 222   to anywhere between 0 and 100 where '0' will effectively lock your CPU
 223   at a speed regardless of its load whilst '100' will, in theory, make
 224   it behave identically to the "ondemand" governor.
 225
 226 * down_threshold:
 227
 228   Same as the 'up_threshold' found for the "ondemand" governor but for
 229   the opposite direction.  For example when set to its default value of
 230   '20' it means that if the CPU usage needs to be below 20% between
 231   samples to have the frequency decreased.
 232
 233 * sampling_down_factor:
 234
 235   Similar functionality as in "ondemand" governor.  But in
 236   "conservative", it controls the rate at which the kernel makes a
 237   decision on when to decrease the frequency while running in any speed.
 238   Load for frequency increase is still evaluated every sampling rate.
 239
 240 3. The Governor Interface in the CPUfreq Core
 241 =============================================
 242
 243 A new governor must register itself with the CPUfreq core using
 244 "cpufreq_register_governor". The struct cpufreq_governor, which has to
 245 be passed to that function, must contain the following values:
 246
 247 governor->name -            A unique name for this governor
 248 governor->governor -        The governor callback function
 249 governor->owner -           .THIS_MODULE for the governor module (if
 250                             appropriate)
 251
 252 The governor->governor callback is called with the current (or to-be-set)
 253 cpufreq_policy struct for that CPU, and an unsigned int event. The
 254 following events are currently defined:
 255
 256 CPUFREQ_GOV_START:   This governor shall start its duty for the CPU
 257                      policy->cpu
 258 CPUFREQ_GOV_STOP:    This governor shall end its duty for the CPU
 259                      policy->cpu
 260 CPUFREQ_GOV_LIMITS:  The limits for CPU policy->cpu have changed to
 261                      policy->min and policy->max.
 262
 263 If you need other "events" externally of your driver, _only_ use the
 264 cpufreq_governor_l(unsigned int cpu, unsigned int event) call to the
 265 CPUfreq core to ensure proper locking.
 266
 267
 268 The CPUfreq governor may call the CPU processor driver using one of
 269 these two functions:
 270
 271 int cpufreq_driver_target(struct cpufreq_policy *policy,
 272                                  unsigned int target_freq,
 273                                  unsigned int relation);
 274
 275 int __cpufreq_driver_target(struct cpufreq_policy *policy,
 276                                    unsigned int target_freq,
 277                                    unsigned int relation);
 278
 279 target_freq must be within policy->min and policy->max, of course.
 280 What's the difference between these two functions? When your governor
 281 still is in a direct code path of a call to governor->governor, the
 282 per-CPU cpufreq lock is still held in the cpufreq core, and there's
 283 no need to lock it again (in fact, this would cause a deadlock). So
 284 use __cpufreq_driver_target only in these cases. In all other cases
 285 (for example, when there's a "daemonized" function that wakes up
 286 every second), use cpufreq_driver_target to lock the cpufreq per-CPU
 287 lock before the command is passed to the cpufreq processor driver.
 288