1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt>
3
4 .. |struct cpuidle_state| replace:: :c:type:`s
5 .. |cpufreq| replace:: :doc:`CPU Performance S
6
7 ========================
8 CPU Idle Time Management
9 ========================
10
11 :Copyright: |copy| 2018 Intel Corporation
12
13 :Author: Rafael J. Wysocki <rafael.j.wysocki@in
14
15
16 Concepts
17 ========
18
19 Modern processors are generally able to enter
20 a program is suspended and instructions belong
21 memory or executed. Those states are the *idl
22
23 Since part of the processor hardware is not us
24 generally allows power drawn by the processor
25 it is an opportunity to save energy.
26
27 CPU idle time management is an energy-efficien
28 the idle states of processors for this purpose
29
30 Logical CPUs
31 ------------
32
33 CPU idle time management operates on CPUs as s
34 is the part of the kernel responsible for the
35 work in the system). In its view, CPUs are *l
36 not be separate physical entities and may just
37 software as individual single-core processors.
38 entity which appears to be fetching instructio
39 (program) from memory and executing them, but
40 physically. Generally, three different cases
41
42 First, if the whole processor can only follow
43 program) at a time, it is a CPU. In that case
44 enter an idle state, that applies to the proce
45
46 Second, if the processor is multi-core, each c
47 least one program at a time. The cores need n
48 other (for example, they may share caches), bu
49 work physically in parallel with each other, s
50 one program, those programs run mostly indepen
51 time. The entire cores are CPUs in that case
52 enter an idle state, that applies to the core
53 place, but it also may apply to a larger unit
54 that the core belongs to (in fact, it may appl
55 units containing the core). Namely, if all of
56 except for one have been put into idle states
57 remaining core asks the processor to enter an
58 to put the whole larger unit into an idle stat
59 other cores in that unit.
60
61 Finally, each core in a multi-core processor m
62 program in the same time frame (that is, each
63 instructions from multiple locations in memory
64 frame, but not necessarily entirely in paralle
65 the cores present themselves to software as "b
66 multiple individual single-core "processors",
67 (or hyper-threads specifically on Intel hardwa
68 sequence of instructions. Then, the hardware
69 time management perspective and if the process
70 by one of them, the hardware thread (or CPU) t
71 nothing more happens, unless all of the other
72 core also have asked the processor to enter an
73 the core may be put into an idle state individ
74 it may be put into an idle state as a whole (i
75 larger unit are in idle states already).
76
77 Idle CPUs
78 ---------
79
80 Logical CPUs, simply referred to as "CPUs" in
81 *idle* by the Linux kernel when there are no t
82 special "idle" task.
83
84 Tasks are the CPU scheduler's representation o
85 sequence of instructions to execute, or code,
86 running that code, and some context informatio
87 processor every time the task's code is run by
88 distributes work by assigning tasks to run to
89
90 Tasks can be in various states. In particular
91 no specific conditions preventing their code f
92 there is a CPU available for that (for example
93 events to occur or similar). When a task beco
94 assigns it to one of the available CPUs to run
95 tasks assigned to it, the CPU will load the gi
96 code (from the instruction following the last
97 another CPU). [If there are multiple runnable
98 simultaneously, they will be subject to priori
99 to allow them to make some progress over time.
100
101 The special "idle" task becomes runnable if th
102 assigned to the given CPU and the CPU is then
103 in Linux idle CPUs run the code of the "idle"
104 code may cause the processor to be put into on
105 supported, in order to save energy, but if the
106 idle states, or there is not enough time to sp
107 next wakeup event, or there are strict latency
108 available idle states from being used, the CPU
109 useless instructions in a loop until it is ass
110
111
112 .. _idle-loop:
113
114 The Idle Loop
115 =============
116
117 The idle loop code takes two major steps in ev
118 calls into a code module referred to as the *g
119 idle time management subsystem called ``CPUIdl
120 the CPU to ask the hardware to enter. Second,
121 from the ``CPUIdle`` subsystem, called the *dr
122 processor hardware to enter the idle state sel
123
124 The role of the governor is to find an idle st
125 conditions at hand. For this purpose, idle st
126 asked to enter by logical CPUs are represented
127 the platform or the processor architecture and
128 (linear) array. That array has to be prepared
129 driver matching the platform the kernel is run
130 time. This allows ``CPUIdle`` governors to be
131 hardware and to work with any platforms that t
132
133 Each idle state present in that array is chara
134 taken into account by the governor, the *targe
135 *exit latency*. The target residency is the m
136 spend in the given state, including the time n
137 substantial), in order to save more energy tha
138 the shallower idle states instead. [The "dept
139 corresponds to the power drawn by the processo
140 latency, in turn, is the maximum time it will
141 hardware to enter an idle state to start execu
142 wakeup from that state. Note that in general
143 the time needed to enter the given state in ca
144 hardware is entering it and it must be entered
145 ordered manner.
146
147 There are two types of information that can in
148 First of all, the governor knows the time unti
149 time is known exactly, because the kernel prog
150 when they will trigger, and it is the maximum
151 CPU depends on can spend in an idle state, inc
152 and exit it. However, the CPU may be woken up
153 (in particular, before the closest timer trigg
154 when that may happen. The governor can only s
155 was idle after it has been woken up (that time
156 duration* from now on) and it can use that inf
157 time until the closest timer to estimate the i
158 governor uses that information depends on what
159 and that is the primary reason for having more
160 ``CPUIdle`` subsystem.
161
162 There are four ``CPUIdle`` governors available
163 ``ladder`` and ``haltpoll``. Which of them is
164 configuration of the kernel and in particular
165 tick can be `stopped by the idle loop <idle-cp
166 governors can be read from the :file:`availabl
167 can be changed at runtime. The name of the ``
168 used by the kernel can be read from the :file:
169 :file:`current_governor` file under :file:`/sy
170 in ``sysfs``.
171
172 Which ``CPUIdle`` driver is used, on the other
173 platform the kernel is running on, but there a
174 matching driver. For example, there are two d
175 majority of Intel platforms, ``intel_idle`` an
176 hardcoded idle states information and the othe
177 from the system's ACPI tables, respectively.
178 driver chosen at the system initialization tim
179 decision on which one of them to use has to be
180 the ``acpi_idle`` driver will be used if ``int
181 reason or if it does not recognize the process
182 driver currently used by the kernel can be rea
183 file under :file:`/sys/devices/system/cpu/cpui
184
185
186 .. _idle-cpus-and-tick:
187
188 Idle CPUs and The Scheduler Tick
189 ================================
190
191 The scheduler tick is a timer that triggers pe
192 the time sharing strategy of the CPU scheduler
193 multiple runnable tasks assigned to one CPU at
194 allow them to make reasonable progress in a gi
195 share the available CPU time. Namely, in roug
196 given a slice of the CPU time to run its code,
197 prioritization and so on and when that time sl
198 switched over to running (the code of) another
199 may not want to give the CPU away voluntarily,
200 is there to make the switch happen regardless.
201 tick, but it is the primary reason for using i
202
203 The scheduler tick is problematic from the CPU
204 because it triggers periodically and relativel
205 configuration, the length of the tick period i
206 Thus, if the tick is allowed to trigger on idl
207 for them to ask the hardware to enter idle sta
208 the tick period length. Moreover, in that cas
209 will never exceed the tick period length and t
210 exiting idle states due to the tick wakeups on
211
212 Fortunately, it is not really necessary to all
213 CPUs, because (by definition) they have no tas
214 "idle" one. In other words, from the CPU sche
215 of the CPU time on them is the idle loop. Sin
216 not be shared between multiple runnable tasks,
217 tick goes away if the given CPU is idle. Cons
218 the scheduler tick entirely on idle CPUs in pr
219 always be worth the effort.
220
221 Whether or not it makes sense to stop the sche
222 depends on what is expected by the governor.
223 (non-tick) timer due to trigger within the tic
224 would be a waste of time, even though the time
225 reprogrammed in that case. Second, if the gov
226 wakeup within the tick range, stopping the tic
227 be harmful. Namely, in that case the governor
228 the target residency within the time until the
229 going to be relatively shallow. The governor
230 state then, as that would contradict its own e
231 order. Now, if the wakeup really occurs short
232 waste of time and in this case the timer hardw
233 which is expensive. On the other hand, if the
234 does not occur any time soon, the hardware may
235 in the shallow idle state selected by the gove
236 energy. Hence, if the governor is expecting a
237 tick range, it is better to allow the tick tri
238 governor will select a relatively deep idle st
239 so that it does not wake up the CPU too early.
240
241 In any case, the governor knows what it is exp
242 or not to stop the scheduler tick belongs to i
243 stopped already (in one of the previous iterat
244 to leave it as is and the governor needs to ta
245
246 The kernel can be configured to disable stoppi
247 loop altogether. That can be done through the
248 (by unsetting the ``CONFIG_NO_HZ_IDLE`` config
249 ``nohz=off`` to it in the command line. In bo
250 scheduler tick is disabled, the governor's dec
251 ignored by the idle loop code and the tick is
252
253 The systems that run kernels configured to all
254 stopped on idle CPUs are referred to as *tickl
255 generally regarded as more energy-efficient th
256 which the tick cannot be stopped. If the give
257 the ``menu`` governor by default and if it is
258 ``CPUIdle`` governor on it will be ``ladder``.
259
260
261 .. _menu-gov:
262
263 The ``menu`` Governor
264 =====================
265
266 The ``menu`` governor is the default ``CPUIdle
267 It is quite complex, but the basic principle o
268 Namely, when invoked to select an idle state f
269 the CPU will ask the processor hardware to ent
270 idle duration and uses the predicted value for
271
272 It first obtains the time until the closest ti
273 that the scheduler tick will be stopped. That
274 length* in what follows, is the upper bound on
275 wakeup. It is used to determine the sleep len
276 to get the sleep length correction factor.
277
278 The ``menu`` governor maintains two arrays of
279 One of them is used when tasks previously runn
280 for some I/O operations to complete and the ot
281 the case. Each array contains several correct
282 to different sleep length ranges organized so
283 array is approximately 10 times wider than the
284
285 The correction factor for the given sleep leng
286 selecting the idle state for the CPU) is updat
287 up and the closer the sleep length is to the o
288 to 1 the correction factor becomes (it must fa
289 The sleep length is multiplied by the correcti
290 falls into to obtain the first approximation o
291
292 Next, the governor uses a simple pattern recog
293 idle duration prediction. Namely, it saves th
294 values and, when predicting the idle duration
295 and variance of them. If the variance is smal
296 milliseconds) or it is small relative to the a
297 that 6 times the standard deviation), the aver
298 interval" value. Otherwise, the longest of th
299 values is discarded and the computation is rep
300 Again, if the variance of them is small (in th
301 taken as the "typical interval" value and so o
302 interval" is determined or too many data point
303 the "typical interval" is assumed to equal "in
304 integer value). The "typical interval" comput
305 sleep length multiplied by the correction fact
306 taken as the predicted idle duration.
307
308 Then, the governor computes an extra latency l
309 workloads. It uses the observation that if th
310 idle state is comparable with the predicted id
311 in that state probably will be very short and
312 entering it will be relatively small, so likel
313 overhead related to entering that state and ex
314 shallower state is likely to be a better optio
315 of the extra latency limit is the predicted id
316 additionally is divided by a value depending o
317 previously ran on the given CPU and now they a
318 complete. The result of that division is comp
319 from the power management quality of service,
320 framework and the minimum of the two is taken
321 exit latency.
322
323 Now, the governor is ready to walk the list of
324 them. For this purpose, it compares the targe
325 the predicted idle duration and the exit laten
326 limit. It selects the state with the target r
327 idle duration, but still below it, and exit la
328 limit.
329
330 In the final step the governor may still need
331 if it has not decided to `stop the scheduler t
332 happens if the idle duration predicted by it i
333 the tick has not been stopped already (in a pr
334 loop). Then, the sleep length used in the pre
335 the real time until the closest timer event an
336 that time, the governor may need to select a s
337 target residency.
338
339
340 .. _teo-gov:
341
342 The Timer Events Oriented (TEO) Governor
343 ========================================
344
345 The timer events oriented (TEO) governor is an
346 for tickless systems. It follows the same bas
347 <menu-gov_>`_: it always tries to find the dee
348 given conditions. However, it applies a diffe
349
350 .. kernel-doc:: drivers/cpuidle/governors/teo.
351 :doc: teo-description
352
353 .. _idle-states-representation:
354
355 Representation of Idle States
356 =============================
357
358 For the CPU idle time management purposes all
359 supported by the processor have to be represen
360 |struct cpuidle_state| objects each allowing a
361 the processor hardware to enter an idle state
362 is a hierarchy of units in the processor, one
363 cover a combination of idle states supported b
364 the hierarchy. In that case, the `target resi
365 of it <idle-loop_>`_, must reflect the propert
366 deepest level (i.e. the idle state of the unit
367 units).
368
369 For example, take a processor with two cores i
370 a "module" and suppose that asking the hardwar
371 (say "X") at the "core" level by one core will
372 enter a specific idle state of its own (say "M
373 state "X" already. In other words, asking for
374 level gives the hardware a license to go as de
375 "module" level, but there is no guarantee that
376 asking for idle state "X" may just end up in t
377 Then, the target residency of the |struct cpui
378 idle state "X" must reflect the minimum time t
379 the module (including the time needed to enter
380 time the CPU needs to be idle to save any ener
381 that state. Analogously, the exit latency par
382 the exit time of idle state "MX" of the module
383 because that is the maximum delay between a wa
384 will start to execute the first new instructio
385 module will always be ready to execute instruc
386 becomes operational as a whole).
387
388 There are processors without direct coordinati
389 hierarchy of units inside them, however. In t
390 state at the "core" level does not automatical
391 example, in any way and the ``CPUIdle`` driver
392 handling of the hierarchy. Then, the definiti
393 entirely up to the driver, but still the physi
394 that the processor hardware finally goes into
395 used by the governor for idle state selection
396 latency of that idle state must not exceed the
397 idle state object selected by the governor).
398
399 In addition to the target residency and exit l
400 discussed above, the objects representing idle
401 parameters describing the idle state and a poi
402 order to ask the hardware to enter that state.
403 |struct cpuidle_state| object, there is a corr
404 :c:type:`struct cpuidle_state_usage <cpuidle_s
405 statistics of the given idle state. That info
406 via ``sysfs``.
407
408 For each CPU in the system, there is a :file:`
409 directory in ``sysfs``, where the number ``<N>
410 CPU at the initialization time. That director
411 called :file:`state0`, :file:`state1` and so o
412 objects defined for the given CPU minus one.
413 corresponds to one idle state object and the l
414 deeper the (effective) idle state represented
415 a number of files (attributes) representing th
416 object corresponding to it, as follows:
417
418 ``above``
419 Total number of times this idle state
420 observed idle duration was certainly t
421 residency.
422
423 ``below``
424 Total number of times this idle state
425 a deeper idle state would have been a
426 duration.
427
428 ``desc``
429 Description of the idle state.
430
431 ``disable``
432 Whether or not this idle state is disa
433
434 ``default_status``
435 The default status of this state, "ena
436
437 ``latency``
438 Exit latency of the idle state in micr
439
440 ``name``
441 Name of the idle state.
442
443 ``power``
444 Power drawn by hardware in this idle s
445 0 otherwise).
446
447 ``residency``
448 Target residency of the idle state in
449
450 ``time``
451 Total time spent in this idle state by
452 kernel) in microseconds.
453
454 ``usage``
455 Total number of times the hardware has
456 enter this idle state.
457
458 ``rejected``
459 Total number of times a request to ent
460 CPU was rejected.
461
462 The :file:`desc` and :file:`name` files both c
463 between them is that the name is expected to b
464 description may be longer and it may contain w
465 The other files listed above contain integer n
466
467 The :file:`disable` attribute is the only writ
468 given idle state is disabled for this particul
469 governor will never select it for this particu
470 driver will never ask the hardware to enter it
471 However, disabling an idle state for one CPU d
472 asked for by the other CPUs, so it must be dis
473 never be asked for by any of them. [Note that
474 governor is implemented, disabling an idle sta
475 selecting any idle states deeper than the disa
476
477 If the :file:`disable` attribute contains 0, t
478 this particular CPU, but it still may be disab
479 CPUs in the system at the same time. Writing
480 be disabled for this particular CPU and writin
481 take it into consideration for the given CPU a
482 unless that state was disabled globally in the
483 be used at all).
484
485 The :file:`power` attribute is not defined ver
486 objects representing combinations of idle stat
487 hierarchy of units in the processor, and it ge
488 state power numbers for complex hardware, so :
489 available) and if it contains a nonzero number
490 accurate and it should not be relied on for an
491
492 The number in the :file:`time` file generally
493 really spent by the given CPU in the given idl
494 the kernel and it may not cover the cases in w
495 this idle state and entered a shallower one in
496 enter any idle state at all). The kernel can
497 asking the hardware to enter an idle state and
498 and it cannot say what really happened in the
499 Moreover, if the idle state object in question
500 states at different levels of the hierarchy of
501 the kernel can never say how deep the hardware
502 particular case. For these reasons, the only
503 much time has been spent by the hardware in di
504 it is to use idle state residency counters in
505
506 Generally, an interrupt received when trying t
507 idle state entry request to be rejected, in wh
508 may return an error code to indicate that this
509 and :file:`rejected` files report the number o
510 was entered successfully or rejected, respecti
511
512 .. _cpu-pm-qos:
513
514 Power Management Quality of Service for CPUs
515 ============================================
516
517 The power management quality of service (PM Qo
518 allows kernel code and user space processes to
519 energy-efficiency features of the kernel to pr
520 below a required level.
521
522 CPU idle time management can be affected by PM
523 global CPU latency limit and through the resum
524 individual CPUs. Kernel code (e.g. device dri
525 the help of special internal interfaces provid
526 space can modify the former by opening the :fi
527 device file under :file:`/dev/` and writing a
528 signed 32-bit integer) to it. In turn, the re
529 can be modified from user space by writing a s
530 32-bit integer) to the :file:`power/pm_qos_res
531 :file:`/sys/devices/system/cpu/cpu<N>/` in ``s
532 ``<N>`` is allocated at the system initializat
533 will be rejected in both cases and, also in bo
534 number will be interpreted as a requested PM Q
535
536 The requested value is not automatically appli
537 as it may be less restrictive (greater in this
538 constraint previously requested by someone els
539 framework maintains a list of requests that ha
540 global CPU latency limit and for each individu
541 applies the effective (minimum in this particu
542 constraint.
543
544 In fact, opening the :file:`cpu_dma_latency` s
545 PM QoS request to be created and added to a gl
546 limit requests and the file descriptor coming
547 represents that request. If that file descrip
548 number written to it will be associated with t
549 it as a new requested limit value. Next, the
550 used to determine the new effective value of t
551 that effective value will be set as a new CPU
552 new limit value will only change the real limi
553 affected by it, which is the case if it is the
554 in the list.
555
556 The process holding a file descriptor obtained
557 :file:`cpu_dma_latency` special device file co
558 associated with that file descriptor, but it c
559 request only.
560
561 Closing the :file:`cpu_dma_latency` special de
562 file descriptor obtained while opening it, cau
563 with that file descriptor to be removed from t
564 latency limit requests and destroyed. If that
565 mechanism will be used again, to determine the
566 list and that value will become the new limit.
567
568 In turn, for each CPU there is one resume late
569 the :file:`power/pm_qos_resume_latency_us` fil
570 :file:`/sys/devices/system/cpu/cpu<N>/` in ``s
571 this single PM QoS request to be updated regar
572 process does that. In other words, this PM Qo
573 user space, so access to the file associated w
574 to avoid confusion. [Arguably, the only legit
575 practice is to pin a process to the CPU in que
576 ``sysfs`` interface to control the resume late
577 still only a request, however. It is an entry
578 determine the effective value to be set as the
579 CPU in question every time the list of request
580 (there may be other requests coming from kerne
581
582 CPU idle time governors are expected to regard
583 (effective) CPU latency limit and the effectiv
584 the given CPU as the upper limit for the exit
585 they are allowed to select for that CPU. They
586 states with exit latency beyond that limit.
587
588
589 Idle States Control Via Kernel Command Line
590 ===========================================
591
592 In addition to the ``sysfs`` interface allowin
593 `disabled for individual CPUs <idle-states-rep
594 command line parameters affecting CPU idle tim
595
596 The ``cpuidle.off=1`` kernel command line opti
597 CPU idle time management entirely. It does no
598 running on idle CPUs, but it prevents the CPU
599 from being invoked. If it is added to the ker
600 will ask the hardware to enter idle states on
601 support code that is expected to provide a def
602 That default mechanism usually is the least co
603 processors implementing the architecture (i.e.
604 however, so it is rather crude and not very en
605 it is not recommended for production use.
606
607 The ``cpuidle.governor=`` kernel command line
608 governor to use to be specified. It has to be
609 the name of an available governor (e.g. ``cpui
610 governor will be used instead of the default o
611 the ``menu`` governor to be used on the system
612 by default this way, for example.
613
614 The other kernel command line parameters contr
615 described below are only relevant for the *x86
616 to ``intel_idle`` affect Intel processors only
617
618 The *x86* architecture support code recognizes
619 options related to CPU idle time management: `
620 and ``idle=nomwait``. The first two of them d
621 ``intel_idle`` drivers altogether, which effec
622 ``CPUIdle`` subsystem to be disabled and makes
623 architecture support code to deal with idle CP
624 which of the two parameters is added to the ke
625 ``idle=halt`` case, the architecture support c
626 instruction of the CPUs (which, as a rule, sus
627 and causes the hardware to attempt to enter th
628 for this purpose, and if ``idle=poll`` is used
629 more or less "lightweight" sequence of instruc
630 that using ``idle=poll`` is somewhat drastic i
631 CPUs from saving almost any energy at all may
632 For example, on Intel hardware it effectively
633 P-states (see |cpufreq|) that require any numb
634 idle, so it very well may hurt single-thread c
635 energy-efficiency. Thus using it for performa
636 at all.]
637
638 The ``idle=nomwait`` option prevents the use o
639 the CPU to enter idle states. When this option
640 driver will use the ``HLT`` instruction instea
641 running Intel processors, this option disables
642 and forces the use of the ``acpi_idle`` driver
643 case, ``acpi_idle`` driver will function only
644 by it is in the system's ACPI tables.
645
646 In addition to the architecture-level kernel c
647 idle time management, there are parameters aff
648 drivers that can be passed to them via the ker
649 the ``intel_idle.max_cstate=<n>`` and ``proces
650 where ``<n>`` is an idle state index also used
651 state's directory in ``sysfs`` (see
652 `Representation of Idle States <idle-states-re
653 ``intel_idle`` and ``acpi_idle`` drivers, resp
654 idle states deeper than idle state ``<n>``. I
655 for any of those idle states or expose them to
656 the two drivers is different for ``<n>`` equal
657 ``intel_idle.max_cstate=0`` to the kernel comm
658 ``intel_idle`` driver and allows ``acpi_idle``
659 ``processor.max_cstate=0`` is equivalent to ``
660 Also, the ``acpi_idle`` driver is part of the
661 can be loaded separately and ``max_cstate=<n>`
662 parameter when it is loaded.]
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.