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 21Contents: 22--------- 231. What is a CPUFreq Governor? 24 252. Governors In the Linux Kernel 262.1 Performance 272.2 Powersave 282.3 Userspace 292.4 Ondemand 302.5 Conservative 312.6 Interactive 32 333. The Governor Interface in the CPUfreq Core 34 35 36 371. What Is A CPUFreq Governor? 38============================== 39 40Most cpufreq drivers (in fact, all except one, longrun) or even most 41cpu frequency scaling algorithms only offer the CPU to be set to one 42frequency. In order to offer dynamic frequency scaling, the cpufreq 43core must be able to tell these drivers of a "target frequency". So 44these specific drivers will be transformed to offer a "->target" 45call instead of the existing "->setpolicy" call. For "longrun", all 46stays the same, though. 47 48How to decide what frequency within the CPUfreq policy should be used? 49That's done using "cpufreq governors". Two are already in this patch 50-- they're the already existing "powersave" and "performance" which 51set the frequency statically to the lowest or highest frequency, 52respectively. At least two more such governors will be ready for 53addition in the near future, but likely many more as there are various 54different theories and models about dynamic frequency scaling 55around. Using such a generic interface as cpufreq offers to scaling 56governors, these can be tested extensively, and the best one can be 57selected for each specific use. 58 59Basically, it's the following flow graph: 60 61CPU can be set to switch independently | CPU can only be set 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 / \ 75 Using the ->setpolicy call, Using the ->target call, 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 822. Governors In the Linux Kernel 83================================ 84 852.1 Performance 86--------------- 87 88The CPUfreq governor "performance" sets the CPU statically to the 89highest frequency within the borders of scaling_min_freq and 90scaling_max_freq. 91 92 932.2 Powersave 94------------- 95 96The CPUfreq governor "powersave" sets the CPU statically to the 97lowest frequency within the borders of scaling_min_freq and 98scaling_max_freq. 99 100 1012.3 Userspace 102------------- 103 104The CPUfreq governor "userspace" allows the user, or any userspace 105program running with UID "root", to set the CPU to a specific frequency 106by making a sysfs file "scaling_setspeed" available in the CPU-device 107directory. 108 109 1102.4 Ondemand 111------------ 112 113The CPUfreq governor "ondemand" sets the CPU depending on the 114current usage. To do this the CPU must have the capability to 115switch the frequency very quickly. There are a number of sysfs file 116accessible parameters: 117 118sampling_rate: measured in uS (10^-6 seconds), this is how often you 119want the kernel to look at the CPU usage and to make decisions on 120what to do about the frequency. Typically this is set to values of 121around '10000' or more. It's default value is (cmp. with users-guide.txt): 122transition_latency * 1000 123Be aware that transition latency is in ns and sampling_rate is in us, so you 124get the same sysfs value by default. 125Sampling rate should always get adjusted considering the transition latency 126To set the sampling rate 750 times as high as the transition latency 127in the bash (as said, 1000 is default), do: 128echo `$(($(cat cpuinfo_transition_latency) * 750 / 1000)) \ 129 >ondemand/sampling_rate 130 131sampling_rate_min: 132The sampling rate is limited by the HW transition latency: 133transition_latency * 100 134Or by kernel restrictions: 135If CONFIG_NO_HZ is set, the limit is 10ms fixed. 136If CONFIG_NO_HZ is not set or nohz=off boot parameter is used, the 137limits depend on the CONFIG_HZ option: 138HZ=1000: min=20000us (20ms) 139HZ=250: min=80000us (80ms) 140HZ=100: min=200000us (200ms) 141The highest value of kernel and HW latency restrictions is shown and 142used as the minimum sampling rate. 143 144up_threshold: defines what the average CPU usage between the samplings 145of 'sampling_rate' needs to be for the kernel to make a decision on 146whether it should increase the frequency. For example when it is set 147to its default value of '95' it means that between the checking 148intervals the CPU needs to be on average more than 95% in use to then 149decide that the CPU frequency needs to be increased. 150 151ignore_nice_load: this parameter takes a value of '0' or '1'. When 152set to '0' (its default), all processes are counted towards the 153'cpu utilisation' value. When set to '1', the processes that are 154run with a 'nice' value will not count (and thus be ignored) in the 155overall usage calculation. This is useful if you are running a CPU 156intensive calculation on your laptop that you do not care how long it 157takes to complete as you can 'nice' it and prevent it from taking part 158in the deciding process of whether to increase your CPU frequency. 159 160sampling_down_factor: this parameter controls the rate at which the 161kernel makes a decision on when to decrease the frequency while running 162at top speed. When set to 1 (the default) decisions to reevaluate load 163are made at the same interval regardless of current clock speed. But 164when set to greater than 1 (e.g. 100) it acts as a multiplier for the 165scheduling interval for reevaluating load when the CPU is at its top 166speed due to high load. This improves performance by reducing the overhead 167of load evaluation and helping the CPU stay at its top speed when truly 168busy, rather than shifting back and forth in speed. This tunable has no 169effect on behavior at lower speeds/lower CPU loads. 170 171 1722.5 Conservative 173---------------- 174 175The CPUfreq governor "conservative", much like the "ondemand" 176governor, sets the CPU depending on the current usage. It differs in 177behaviour in that it gracefully increases and decreases the CPU speed 178rather than jumping to max speed the moment there is any load on the 179CPU. This behaviour more suitable in a battery powered environment. 180The governor is tweaked in the same manner as the "ondemand" governor 181through sysfs with the addition of: 182 183freq_step: this describes what percentage steps the cpu freq should be 184increased and decreased smoothly by. By default the cpu frequency will 185increase in 5% chunks of your maximum cpu frequency. You can change this 186value to anywhere between 0 and 100 where '0' will effectively lock your 187CPU at a speed regardless of its load whilst '100' will, in theory, make 188it behave identically to the "ondemand" governor. 189 190down_threshold: same as the 'up_threshold' found for the "ondemand" 191governor but for the opposite direction. For example when set to its 192default value of '20' it means that if the CPU usage needs to be below 19320% between samples to have the frequency decreased. 194 195 1962.6 Interactive 197--------------- 198 199The CPUfreq governor "interactive" is designed for latency-sensitive, 200interactive workloads. This governor sets the CPU speed depending on 201usage, similar to "ondemand" and "conservative" governors, but with a 202different set of configurable behaviors. 203 204The tuneable values for this governor are: 205 206target_loads: CPU load values used to adjust speed to influence the 207current CPU load toward that value. In general, the lower the target 208load, the more often the governor will raise CPU speeds to bring load 209below the target. The format is a single target load, optionally 210followed by pairs of CPU speeds and CPU loads to target at or above 211those speeds. Colons can be used between the speeds and associated 212target loads for readability. For example: 213 214 85 1000000:90 1700000:99 215 216targets CPU load 85% below speed 1GHz, 90% at or above 1GHz, until 2171.7GHz and above, at which load 99% is targeted. If speeds are 218specified these must appear in ascending order. Higher target load 219values are typically specified for higher speeds, that is, target load 220values also usually appear in an ascending order. The default is 221target load 90% for all speeds. 222 223min_sample_time: The minimum amount of time to spend at the current 224frequency before ramping down. Default is 80000 uS. 225 226hispeed_freq: An intermediate "hi speed" at which to initially ramp 227when CPU load hits the value specified in go_hispeed_load. If load 228stays high for the amount of time specified in above_hispeed_delay, 229then speed may be bumped higher. Default is the maximum speed 230allowed by the policy at governor initialization time. 231 232go_hispeed_load: The CPU load at which to ramp to hispeed_freq. 233Default is 99%. 234 235above_hispeed_delay: When speed is at or above hispeed_freq, wait for 236this long before raising speed in response to continued high load. 237The format is a single delay value, optionally followed by pairs of 238CPU speeds and the delay to use at or above those speeds. Colons can 239be used between the speeds and associated delays for readability. For 240example: 241 242 80000 1300000:200000 1500000:40000 243 244uses delay 80000 uS until CPU speed 1.3 GHz, at which speed delay 245200000 uS is used until speed 1.5 GHz, at which speed (and above) 246delay 40000 uS is used. If speeds are specified these must appear in 247ascending order. Default is 20000 uS. 248 249timer_rate: Sample rate for reevaluating CPU load when the CPU is not 250idle. A deferrable timer is used, such that the CPU will not be woken 251from idle to service this timer until something else needs to run. 252(The maximum time to allow deferring this timer when not running at 253minimum speed is configurable via timer_slack.) Default is 20000 uS. 254 255timer_slack: Maximum additional time to defer handling the governor 256sampling timer beyond timer_rate when running at speeds above the 257minimum. For platforms that consume additional power at idle when 258CPUs are running at speeds greater than minimum, this places an upper 259bound on how long the timer will be deferred prior to re-evaluating 260load and dropping speed. For example, if timer_rate is 20000uS and 261timer_slack is 10000uS then timers will be deferred for up to 30msec 262when not at lowest speed. A value of -1 means defer timers 263indefinitely at all speeds. Default is 80000 uS. 264 265boost: If non-zero, immediately boost speed of all CPUs to at least 266hispeed_freq until zero is written to this attribute. If zero, allow 267CPU speeds to drop below hispeed_freq according to load as usual. 268Default is zero. 269 270boostpulse: On each write, immediately boost speed of all CPUs to 271hispeed_freq for at least the period of time specified by 272boostpulse_duration, after which speeds are allowed to drop below 273hispeed_freq according to load as usual. 274 275boostpulse_duration: Length of time to hold CPU speed at hispeed_freq 276on a write to boostpulse, before allowing speed to drop according to 277load as usual. Default is 80000 uS. 278 279 2803. The Governor Interface in the CPUfreq Core 281============================================= 282 283A new governor must register itself with the CPUfreq core using 284"cpufreq_register_governor". The struct cpufreq_governor, which has to 285be passed to that function, must contain the following values: 286 287governor->name - A unique name for this governor 288governor->governor - The governor callback function 289governor->owner - .THIS_MODULE for the governor module (if 290 appropriate) 291 292The governor->governor callback is called with the current (or to-be-set) 293cpufreq_policy struct for that CPU, and an unsigned int event. The 294following events are currently defined: 295 296CPUFREQ_GOV_START: This governor shall start its duty for the CPU 297 policy->cpu 298CPUFREQ_GOV_STOP: This governor shall end its duty for the CPU 299 policy->cpu 300CPUFREQ_GOV_LIMITS: The limits for CPU policy->cpu have changed to 301 policy->min and policy->max. 302 303If you need other "events" externally of your driver, _only_ use the 304cpufreq_governor_l(unsigned int cpu, unsigned int event) call to the 305CPUfreq core to ensure proper locking. 306 307 308The CPUfreq governor may call the CPU processor driver using one of 309these two functions: 310 311int cpufreq_driver_target(struct cpufreq_policy *policy, 312 unsigned int target_freq, 313 unsigned int relation); 314 315int __cpufreq_driver_target(struct cpufreq_policy *policy, 316 unsigned int target_freq, 317 unsigned int relation); 318 319target_freq must be within policy->min and policy->max, of course. 320What's the difference between these two functions? When your governor 321still is in a direct code path of a call to governor->governor, the 322per-CPU cpufreq lock is still held in the cpufreq core, and there's 323no need to lock it again (in fact, this would cause a deadlock). So 324use __cpufreq_driver_target only in these cases. In all other cases 325(for example, when there's a "daemonized" function that wakes up 326every second), use cpufreq_driver_target to lock the cpufreq per-CPU 327lock before the command is passed to the cpufreq processor driver. 328 329