Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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> |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 12 | some additions and corrections by Nico Golde <nico@ngolde.de> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 29 | 2.4 Ondemand |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 30 | 2.5 Conservative |
Mike Chan | 277f751 | 2010-06-22 11:26:45 -0700 | [diff] [blame] | 31 | 2.6 Interactive |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 32 | |
| 33 | 3. The Governor Interface in the CPUfreq Core |
| 34 | |
| 35 | |
| 36 | |
| 37 | 1. What Is A CPUFreq Governor? |
| 38 | ============================== |
| 39 | |
Prarit Bhargava | 1df1b36 | 2015-06-01 09:36:04 -0400 | [diff] [blame] | 40 | Most cpufreq drivers (except the intel_pstate and longrun) or even most |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 41 | cpu frequency scaling algorithms only offer the CPU to be set to one |
| 42 | frequency. In order to offer dynamic frequency scaling, the cpufreq |
| 43 | core must be able to tell these drivers of a "target frequency". So |
Viresh Kumar | 9c0ebcf | 2013-10-25 19:45:48 +0530 | [diff] [blame] | 44 | these specific drivers will be transformed to offer a "->target/target_index" |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 45 | call instead of the existing "->setpolicy" call. For "longrun", all |
| 46 | stays the same, though. |
| 47 | |
| 48 | How to decide what frequency within the CPUfreq policy should be used? |
| 49 | That's done using "cpufreq governors". Two are already in this patch |
| 50 | -- they're the already existing "powersave" and "performance" which |
| 51 | set the frequency statically to the lowest or highest frequency, |
| 52 | respectively. At least two more such governors will be ready for |
| 53 | addition in the near future, but likely many more as there are various |
| 54 | different theories and models about dynamic frequency scaling |
| 55 | around. Using such a generic interface as cpufreq offers to scaling |
| 56 | governors, these can be tested extensively, and the best one can be |
| 57 | selected for each specific use. |
| 58 | |
| 59 | Basically, it's the following flow graph: |
| 60 | |
Matt LaPlante | 2fe0ae7 | 2006-10-03 22:50:39 +0200 | [diff] [blame] | 61 | CPU can be set to switch independently | CPU can only be set |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 62 | within specific "limits" | to specific frequencies |
| 63 | |
| 64 | "CPUfreq policy" |
| 65 | consists of frequency limits (policy->{min,max}) |
| 66 | and CPUfreq governor to be used |
| 67 | / \ |
| 68 | / \ |
| 69 | / the cpufreq governor decides |
| 70 | / (dynamically or statically) |
| 71 | / what target_freq to set within |
| 72 | / the limits of policy->{min,max} |
| 73 | / \ |
| 74 | / \ |
Viresh Kumar | 9c0ebcf | 2013-10-25 19:45:48 +0530 | [diff] [blame] | 75 | Using the ->setpolicy call, Using the ->target/target_index call, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 76 | the limits and the the frequency closest |
| 77 | "policy" is set. to target_freq is set. |
| 78 | It is assured that it |
| 79 | is within policy->{min,max} |
| 80 | |
| 81 | |
| 82 | 2. Governors In the Linux Kernel |
| 83 | ================================ |
| 84 | |
| 85 | 2.1 Performance |
| 86 | --------------- |
| 87 | |
| 88 | The CPUfreq governor "performance" sets the CPU statically to the |
| 89 | highest frequency within the borders of scaling_min_freq and |
| 90 | scaling_max_freq. |
| 91 | |
| 92 | |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 93 | 2.2 Powersave |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 94 | ------------- |
| 95 | |
| 96 | The CPUfreq governor "powersave" sets the CPU statically to the |
| 97 | lowest frequency within the borders of scaling_min_freq and |
| 98 | scaling_max_freq. |
| 99 | |
| 100 | |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 101 | 2.3 Userspace |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 102 | ------------- |
| 103 | |
| 104 | The CPUfreq governor "userspace" allows the user, or any userspace |
| 105 | program running with UID "root", to set the CPU to a specific frequency |
| 106 | by making a sysfs file "scaling_setspeed" available in the CPU-device |
| 107 | directory. |
| 108 | |
| 109 | |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 110 | 2.4 Ondemand |
| 111 | ------------ |
| 112 | |
Matt LaPlante | a2ffd27 | 2006-10-03 22:49:15 +0200 | [diff] [blame] | 113 | The CPUfreq governor "ondemand" sets the CPU depending on the |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 114 | current usage. To do this the CPU must have the capability to |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 115 | switch the frequency very quickly. There are a number of sysfs file |
| 116 | accessible parameters: |
| 117 | |
| 118 | sampling_rate: measured in uS (10^-6 seconds), this is how often you |
| 119 | want the kernel to look at the CPU usage and to make decisions on |
| 120 | what to do about the frequency. Typically this is set to values of |
Thomas Renninger | 112124a | 2009-02-04 11:55:12 +0100 | [diff] [blame] | 121 | around '10000' or more. It's default value is (cmp. with users-guide.txt): |
| 122 | transition_latency * 1000 |
Thomas Renninger | 112124a | 2009-02-04 11:55:12 +0100 | [diff] [blame] | 123 | Be aware that transition latency is in ns and sampling_rate is in us, so you |
| 124 | get the same sysfs value by default. |
| 125 | Sampling rate should always get adjusted considering the transition latency |
| 126 | To set the sampling rate 750 times as high as the transition latency |
| 127 | in the bash (as said, 1000 is default), do: |
| 128 | echo `$(($(cat cpuinfo_transition_latency) * 750 / 1000)) \ |
| 129 | >ondemand/sampling_rate |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 130 | |
Paul Bolle | e7cbb5b | 2011-11-08 10:16:03 +0100 | [diff] [blame] | 131 | sampling_rate_min: |
Thomas Renninger | 4f4d1ad | 2009-04-22 13:48:31 +0200 | [diff] [blame] | 132 | The sampling rate is limited by the HW transition latency: |
| 133 | transition_latency * 100 |
| 134 | Or by kernel restrictions: |
Frederic Weisbecker | 3451d02 | 2011-08-10 23:21:01 +0200 | [diff] [blame] | 135 | If CONFIG_NO_HZ_COMMON is set, the limit is 10ms fixed. |
| 136 | If CONFIG_NO_HZ_COMMON is not set or nohz=off boot parameter is used, the |
Thomas Renninger | 4f4d1ad | 2009-04-22 13:48:31 +0200 | [diff] [blame] | 137 | limits depend on the CONFIG_HZ option: |
| 138 | HZ=1000: min=20000us (20ms) |
| 139 | HZ=250: min=80000us (80ms) |
| 140 | HZ=100: min=200000us (200ms) |
| 141 | The highest value of kernel and HW latency restrictions is shown and |
| 142 | used as the minimum sampling rate. |
| 143 | |
Matt LaPlante | d919588 | 2008-07-25 19:45:33 -0700 | [diff] [blame] | 144 | up_threshold: defines what the average CPU usage between the samplings |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 145 | of 'sampling_rate' needs to be for the kernel to make a decision on |
| 146 | whether it should increase the frequency. For example when it is set |
Mike Frysinger | 292e004 | 2009-12-09 06:56:40 -0500 | [diff] [blame] | 147 | to its default value of '95' it means that between the checking |
| 148 | intervals the CPU needs to be on average more than 95% in use to then |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 149 | decide that the CPU frequency needs to be increased. |
| 150 | |
Matt LaPlante | 992caac | 2006-10-03 22:52:05 +0200 | [diff] [blame] | 151 | ignore_nice_load: this parameter takes a value of '0' or '1'. When |
| 152 | set to '0' (its default), all processes are counted towards the |
| 153 | 'cpu utilisation' value. When set to '1', the processes that are |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 154 | run with a 'nice' value will not count (and thus be ignored) in the |
Matt LaPlante | 992caac | 2006-10-03 22:52:05 +0200 | [diff] [blame] | 155 | overall usage calculation. This is useful if you are running a CPU |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 156 | intensive calculation on your laptop that you do not care how long it |
| 157 | takes to complete as you can 'nice' it and prevent it from taking part |
| 158 | in the deciding process of whether to increase your CPU frequency. |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 159 | |
Vishwanath BS | 5b95364 | 2011-01-25 20:12:41 +0530 | [diff] [blame] | 160 | sampling_down_factor: this parameter controls the rate at which the |
| 161 | kernel makes a decision on when to decrease the frequency while running |
| 162 | at top speed. When set to 1 (the default) decisions to reevaluate load |
| 163 | are made at the same interval regardless of current clock speed. But |
| 164 | when set to greater than 1 (e.g. 100) it acts as a multiplier for the |
| 165 | scheduling interval for reevaluating load when the CPU is at its top |
| 166 | speed due to high load. This improves performance by reducing the overhead |
| 167 | of load evaluation and helping the CPU stay at its top speed when truly |
| 168 | busy, rather than shifting back and forth in speed. This tunable has no |
| 169 | effect on behavior at lower speeds/lower CPU loads. |
| 170 | |
Jacob Shin | 9c5320c | 2013-04-04 16:19:04 +0000 | [diff] [blame] | 171 | powersave_bias: this parameter takes a value between 0 to 1000. It |
| 172 | defines the percentage (times 10) value of the target frequency that |
| 173 | will be shaved off of the target. For example, when set to 100 -- 10%, |
| 174 | when ondemand governor would have targeted 1000 MHz, it will target |
| 175 | 1000 MHz - (10% of 1000 MHz) = 900 MHz instead. This is set to 0 |
| 176 | (disabled) by default. |
| 177 | When AMD frequency sensitivity powersave bias driver -- |
| 178 | drivers/cpufreq/amd_freq_sensitivity.c is loaded, this parameter |
| 179 | defines the workload frequency sensitivity threshold in which a lower |
| 180 | frequency is chosen instead of ondemand governor's original target. |
| 181 | The frequency sensitivity is a hardware reported (on AMD Family 16h |
| 182 | Processors and above) value between 0 to 100% that tells software how |
| 183 | the performance of the workload running on a CPU will change when |
| 184 | frequency changes. A workload with sensitivity of 0% (memory/IO-bound) |
| 185 | will not perform any better on higher core frequency, whereas a |
| 186 | workload with sensitivity of 100% (CPU-bound) will perform better |
| 187 | higher the frequency. When the driver is loaded, this is set to 400 |
| 188 | by default -- for CPUs running workloads with sensitivity value below |
| 189 | 40%, a lower frequency is chosen. Unloading the driver or writing 0 |
| 190 | will disable this feature. |
| 191 | |
Nico Golde | 594dd2c | 2005-06-25 14:58:33 -0700 | [diff] [blame] | 192 | |
Alexander Clouter | 537208c | 2005-12-01 01:09:23 -0800 | [diff] [blame] | 193 | 2.5 Conservative |
| 194 | ---------------- |
| 195 | |
| 196 | The CPUfreq governor "conservative", much like the "ondemand" |
| 197 | governor, sets the CPU depending on the current usage. It differs in |
| 198 | behaviour in that it gracefully increases and decreases the CPU speed |
| 199 | rather than jumping to max speed the moment there is any load on the |
| 200 | CPU. This behaviour more suitable in a battery powered environment. |
| 201 | The governor is tweaked in the same manner as the "ondemand" governor |
| 202 | through sysfs with the addition of: |
| 203 | |
| 204 | freq_step: this describes what percentage steps the cpu freq should be |
| 205 | increased and decreased smoothly by. By default the cpu frequency will |
| 206 | increase in 5% chunks of your maximum cpu frequency. You can change this |
| 207 | value to anywhere between 0 and 100 where '0' will effectively lock your |
| 208 | CPU at a speed regardless of its load whilst '100' will, in theory, make |
| 209 | it behave identically to the "ondemand" governor. |
| 210 | |
| 211 | down_threshold: same as the 'up_threshold' found for the "ondemand" |
| 212 | governor but for the opposite direction. For example when set to its |
| 213 | default value of '20' it means that if the CPU usage needs to be below |
| 214 | 20% between samples to have the frequency decreased. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 215 | |
Stratos Karafotis | 7af1c05 | 2013-03-05 22:06:29 +0000 | [diff] [blame] | 216 | sampling_down_factor: similar functionality as in "ondemand" governor. |
| 217 | But in "conservative", it controls the rate at which the kernel makes |
| 218 | a decision on when to decrease the frequency while running in any |
| 219 | speed. Load for frequency increase is still evaluated every |
| 220 | sampling rate. |
| 221 | |
Mike Chan | 277f751 | 2010-06-22 11:26:45 -0700 | [diff] [blame] | 222 | 2.6 Interactive |
| 223 | --------------- |
| 224 | |
| 225 | The CPUfreq governor "interactive" is designed for latency-sensitive, |
| 226 | interactive workloads. This governor sets the CPU speed depending on |
| 227 | usage, similar to "ondemand" and "conservative" governors. However, |
| 228 | the governor is more aggressive about scaling the CPU speed up in |
| 229 | response to CPU-intensive activity. |
| 230 | |
| 231 | Sampling the CPU load every X ms can lead to under-powering the CPU |
| 232 | for X ms, leading to dropped frames, stuttering UI, etc. Instead of |
| 233 | sampling the cpu at a specified rate, the interactive governor will |
| 234 | check whether to scale the cpu frequency up soon after coming out of |
| 235 | idle. When the cpu comes out of idle, a timer is configured to fire |
| 236 | within 1-2 ticks. If the cpu is very busy between exiting idle and |
| 237 | when the timer fires then we assume the cpu is underpowered and ramp |
| 238 | to MAX speed. |
| 239 | |
| 240 | If the cpu was not sufficiently busy to immediately ramp to MAX speed, |
| 241 | then governor evaluates the cpu load since the last speed adjustment, |
| 242 | choosing the highest value between that longer-term load or the |
| 243 | short-term load since idle exit to determine the cpu speed to ramp to. |
| 244 | |
| 245 | The tuneable values for this governor are: |
| 246 | |
| 247 | min_sample_time: The minimum amount of time to spend at the current |
| 248 | frequency before ramping down. This is to ensure that the governor has |
| 249 | seen enough historic cpu load data to determine the appropriate |
| 250 | workload. Default is 80000 uS. |
| 251 | |
Todd Poynor | d343fba | 2012-04-17 17:39:34 -0700 | [diff] [blame] | 252 | hispeed_freq: An intermediate "hi speed" at which to initially ramp |
| 253 | when CPU load hits the value specified in go_hispeed_load. If load |
| 254 | stays high for the amount of time specified in above_hispeed_delay, |
| 255 | then speed may be bumped higher. Default is maximum speed. |
| 256 | |
| 257 | go_hispeed_load: The CPU load at which to ramp to the intermediate "hi |
| 258 | speed". Default is 85%. |
| 259 | |
| 260 | above_hispeed_delay: Once speed is set to hispeed_freq, wait for this |
| 261 | long before bumping speed higher in response to continued high load. |
| 262 | Default is 20000 uS. |
Mike Chan | 277f751 | 2010-06-22 11:26:45 -0700 | [diff] [blame] | 263 | |
| 264 | timer_rate: Sample rate for reevaluating cpu load when the system is |
Todd Poynor | d343fba | 2012-04-17 17:39:34 -0700 | [diff] [blame] | 265 | not idle. Default is 20000 uS. |
| 266 | |
Todd Poynor | 103efca | 2012-04-02 17:17:14 -0700 | [diff] [blame] | 267 | input_boost: If non-zero, boost speed of all CPUs to hispeed_freq on |
| 268 | touchscreen activity. Default is 0. |
| 269 | |
Todd Poynor | 8273eaf | 2012-05-03 00:16:55 -0700 | [diff] [blame^] | 270 | boost: If non-zero, immediately boost speed of all CPUs to at least |
| 271 | hispeed_freq until zero is written to this attribute. If zero, allow |
| 272 | CPU speeds to drop below hispeed_freq according to load as usual. |
| 273 | |
| 274 | boostpulse: Immediately boost speed of all CPUs to hispeed_freq for |
| 275 | min_sample_time, after which speeds are allowed to drop below |
| 276 | hispeed_freq according to load as usual. |
Todd Poynor | 853cd31 | 2012-04-23 20:42:41 -0700 | [diff] [blame] | 277 | |
Mike Chan | 277f751 | 2010-06-22 11:26:45 -0700 | [diff] [blame] | 278 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 279 | 3. The Governor Interface in the CPUfreq Core |
| 280 | ============================================= |
| 281 | |
| 282 | A new governor must register itself with the CPUfreq core using |
| 283 | "cpufreq_register_governor". The struct cpufreq_governor, which has to |
| 284 | be passed to that function, must contain the following values: |
| 285 | |
| 286 | governor->name - A unique name for this governor |
| 287 | governor->governor - The governor callback function |
| 288 | governor->owner - .THIS_MODULE for the governor module (if |
| 289 | appropriate) |
| 290 | |
| 291 | The governor->governor callback is called with the current (or to-be-set) |
| 292 | cpufreq_policy struct for that CPU, and an unsigned int event. The |
| 293 | following events are currently defined: |
| 294 | |
| 295 | CPUFREQ_GOV_START: This governor shall start its duty for the CPU |
| 296 | policy->cpu |
| 297 | CPUFREQ_GOV_STOP: This governor shall end its duty for the CPU |
| 298 | policy->cpu |
| 299 | CPUFREQ_GOV_LIMITS: The limits for CPU policy->cpu have changed to |
| 300 | policy->min and policy->max. |
| 301 | |
| 302 | If you need other "events" externally of your driver, _only_ use the |
| 303 | cpufreq_governor_l(unsigned int cpu, unsigned int event) call to the |
| 304 | CPUfreq core to ensure proper locking. |
| 305 | |
| 306 | |
| 307 | The CPUfreq governor may call the CPU processor driver using one of |
| 308 | these two functions: |
| 309 | |
| 310 | int cpufreq_driver_target(struct cpufreq_policy *policy, |
| 311 | unsigned int target_freq, |
| 312 | unsigned int relation); |
| 313 | |
| 314 | int __cpufreq_driver_target(struct cpufreq_policy *policy, |
| 315 | unsigned int target_freq, |
| 316 | unsigned int relation); |
| 317 | |
| 318 | target_freq must be within policy->min and policy->max, of course. |
| 319 | What's the difference between these two functions? When your governor |
| 320 | still is in a direct code path of a call to governor->governor, the |
| 321 | per-CPU cpufreq lock is still held in the cpufreq core, and there's |
| 322 | no need to lock it again (in fact, this would cause a deadlock). So |
| 323 | use __cpufreq_driver_target only in these cases. In all other cases |
| 324 | (for example, when there's a "daemonized" function that wakes up |
| 325 | every second), use cpufreq_driver_target to lock the cpufreq per-CPU |
| 326 | lock before the command is passed to the cpufreq processor driver. |
| 327 | |