1.. SPDX-License-Identifier: GPL-2.0 2.. include:: <isonum.txt> 3 4======================== 5CPU Idle Time Management 6======================== 7 8:Copyright: |copy| 2019 Intel Corporation 9 10:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> 11 12 13CPU Idle Time Management Subsystem 14================================== 15 16Every time one of the logical CPUs in the system (the entities that appear to 17fetch and execute instructions: hardware threads, if present, or processor 18cores) is idle after an interrupt or equivalent wakeup event, which means that 19there are no tasks to run on it except for the special "idle" task associated 20with it, there is an opportunity to save energy for the processor that it 21belongs to. That can be done by making the idle logical CPU stop fetching 22instructions from memory and putting some of the processor's functional units 23depended on by it into an idle state in which they will draw less power. 24 25However, there may be multiple different idle states that can be used in such a 26situation in principle, so it may be necessary to find the most suitable one 27(from the kernel perspective) and ask the processor to use (or "enter") that 28particular idle state. That is the role of the CPU idle time management 29subsystem in the kernel, called ``CPUIdle``. 30 31The design of ``CPUIdle`` is modular and based on the code duplication avoidance 32principle, so the generic code that in principle need not depend on the hardware 33or platform design details in it is separate from the code that interacts with 34the hardware. It generally is divided into three categories of functional 35units: *governors* responsible for selecting idle states to ask the processor 36to enter, *drivers* that pass the governors' decisions on to the hardware and 37the *core* providing a common framework for them. 38 39 40CPU Idle Time Governors 41======================= 42 43A CPU idle time (``CPUIdle``) governor is a bundle of policy code invoked when 44one of the logical CPUs in the system turns out to be idle. Its role is to 45select an idle state to ask the processor to enter in order to save some energy. 46 47``CPUIdle`` governors are generic and each of them can be used on any hardware 48platform that the Linux kernel can run on. For this reason, data structures 49operated on by them cannot depend on any hardware architecture or platform 50design details as well. 51 52The governor itself is represented by a struct cpuidle_governor object 53containing four callback pointers, :c:member:`enable`, :c:member:`disable`, 54:c:member:`select`, :c:member:`reflect`, a :c:member:`rating` field described 55below, and a name (string) used for identifying it. 56 57For the governor to be available at all, that object needs to be registered 58with the ``CPUIdle`` core by calling :c:func:`cpuidle_register_governor()` with 59a pointer to it passed as the argument. If successful, that causes the core to 60add the governor to the global list of available governors and, if it is the 61only one in the list (that is, the list was empty before) or the value of its 62:c:member:`rating` field is greater than the value of that field for the 63governor currently in use, or the name of the new governor was passed to the 64kernel as the value of the ``cpuidle.governor=`` command line parameter, the new 65governor will be used from that point on (there can be only one ``CPUIdle`` 66governor in use at a time). Also, user space can choose the ``CPUIdle`` 67governor to use at run time via ``sysfs``. 68 69Once registered, ``CPUIdle`` governors cannot be unregistered, so it is not 70practical to put them into loadable kernel modules. 71 72The interface between ``CPUIdle`` governors and the core consists of four 73callbacks: 74 75:c:member:`enable` 76 :: 77 78 int (*enable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); 79 80 The role of this callback is to prepare the governor for handling the 81 (logical) CPU represented by the struct cpuidle_device object pointed 82 to by the ``dev`` argument. The struct cpuidle_driver object pointed 83 to by the ``drv`` argument represents the ``CPUIdle`` driver to be used 84 with that CPU (among other things, it should contain the list of 85 struct cpuidle_state objects representing idle states that the 86 processor holding the given CPU can be asked to enter). 87 88 It may fail, in which case it is expected to return a negative error 89 code, and that causes the kernel to run the architecture-specific 90 default code for idle CPUs on the CPU in question instead of ``CPUIdle`` 91 until the ``->enable()`` governor callback is invoked for that CPU 92 again. 93 94:c:member:`disable` 95 :: 96 97 void (*disable) (struct cpuidle_driver *drv, struct cpuidle_device *dev); 98 99 Called to make the governor stop handling the (logical) CPU represented 100 by the struct cpuidle_device object pointed to by the ``dev`` 101 argument. 102 103 It is expected to reverse any changes made by the ``->enable()`` 104 callback when it was last invoked for the target CPU, free all memory 105 allocated by that callback and so on. 106 107:c:member:`select` 108 :: 109 110 int (*select) (struct cpuidle_driver *drv, struct cpuidle_device *dev, 111 bool *stop_tick); 112 113 Called to select an idle state for the processor holding the (logical) 114 CPU represented by the struct cpuidle_device object pointed to by the 115 ``dev`` argument. 116 117 The list of idle states to take into consideration is represented by the 118 :c:member:`states` array of struct cpuidle_state objects held by the 119 struct cpuidle_driver object pointed to by the ``drv`` argument (which 120 represents the ``CPUIdle`` driver to be used with the CPU at hand). The 121 value returned by this callback is interpreted as an index into that 122 array (unless it is a negative error code). 123 124 The ``stop_tick`` argument is used to indicate whether or not to stop 125 the scheduler tick before asking the processor to enter the selected 126 idle state. When the ``bool`` variable pointed to by it (which is set 127 to ``true`` before invoking this callback) is cleared to ``false``, the 128 processor will be asked to enter the selected idle state without 129 stopping the scheduler tick on the given CPU (if the tick has been 130 stopped on that CPU already, however, it will not be restarted before 131 asking the processor to enter the idle state). 132 133 This callback is mandatory (i.e. the :c:member:`select` callback pointer 134 in struct cpuidle_governor must not be ``NULL`` for the registration 135 of the governor to succeed). 136 137:c:member:`reflect` 138 :: 139 140 void (*reflect) (struct cpuidle_device *dev, int index); 141 142 Called to allow the governor to evaluate the accuracy of the idle state 143 selection made by the ``->select()`` callback (when it was invoked last 144 time) and possibly use the result of that to improve the accuracy of 145 idle state selections in the future. 146 147In addition, ``CPUIdle`` governors are required to take power management 148quality of service (PM QoS) constraints on the processor wakeup latency into 149account when selecting idle states. In order to obtain the current effective 150PM QoS wakeup latency constraint for a given CPU, a ``CPUIdle`` governor is 151expected to pass the number of the CPU to 152:c:func:`cpuidle_governor_latency_req()`. Then, the governor's ``->select()`` 153callback must not return the index of an indle state whose 154:c:member:`exit_latency` value is greater than the number returned by that 155function. 156 157 158CPU Idle Time Management Drivers 159================================ 160 161CPU idle time management (``CPUIdle``) drivers provide an interface between the 162other parts of ``CPUIdle`` and the hardware. 163 164First of all, a ``CPUIdle`` driver has to populate the :c:member:`states` array 165of struct cpuidle_state objects included in the struct cpuidle_driver object 166representing it. Going forward this array will represent the list of available 167idle states that the processor hardware can be asked to enter shared by all of 168the logical CPUs handled by the given driver. 169 170The entries in the :c:member:`states` array are expected to be sorted by the 171value of the :c:member:`target_residency` field in struct cpuidle_state in 172the ascending order (that is, index 0 should correspond to the idle state with 173the minimum value of :c:member:`target_residency`). [Since the 174:c:member:`target_residency` value is expected to reflect the "depth" of the 175idle state represented by the struct cpuidle_state object holding it, this 176sorting order should be the same as the ascending sorting order by the idle 177state "depth".] 178 179Three fields in struct cpuidle_state are used by the existing ``CPUIdle`` 180governors for computations related to idle state selection: 181 182:c:member:`target_residency` 183 Minimum time to spend in this idle state including the time needed to 184 enter it (which may be substantial) to save more energy than could 185 be saved by staying in a shallower idle state for the same amount of 186 time, in microseconds. 187 188:c:member:`exit_latency` 189 Maximum time it will take a CPU asking the processor to enter this idle 190 state to start executing the first instruction after a wakeup from it, 191 in microseconds. 192 193:c:member:`flags` 194 Flags representing idle state properties. Currently, governors only use 195 the ``CPUIDLE_FLAG_POLLING`` flag which is set if the given object 196 does not represent a real idle state, but an interface to a software 197 "loop" that can be used in order to avoid asking the processor to enter 198 any idle state at all. [There are other flags used by the ``CPUIdle`` 199 core in special situations.] 200 201The :c:member:`enter` callback pointer in struct cpuidle_state, which must not 202be ``NULL``, points to the routine to execute in order to ask the processor to 203enter this particular idle state: 204 205:: 206 207 void (*enter) (struct cpuidle_device *dev, struct cpuidle_driver *drv, 208 int index); 209 210The first two arguments of it point to the struct cpuidle_device object 211representing the logical CPU running this callback and the 212struct cpuidle_driver object representing the driver itself, respectively, 213and the last one is an index of the struct cpuidle_state entry in the driver's 214:c:member:`states` array representing the idle state to ask the processor to 215enter. 216 217The analogous ``->enter_s2idle()`` callback in struct cpuidle_state is used 218only for implementing the suspend-to-idle system-wide power management feature. 219The difference between in and ``->enter()`` is that it must not re-enable 220interrupts at any point (even temporarily) or attempt to change the states of 221clock event devices, which the ``->enter()`` callback may do sometimes. 222 223Once the :c:member:`states` array has been populated, the number of valid 224entries in it has to be stored in the :c:member:`state_count` field of the 225struct cpuidle_driver object representing the driver. Moreover, if any 226entries in the :c:member:`states` array represent "coupled" idle states (that 227is, idle states that can only be asked for if multiple related logical CPUs are 228idle), the :c:member:`safe_state_index` field in struct cpuidle_driver needs 229to be the index of an idle state that is not "coupled" (that is, one that can be 230asked for if only one logical CPU is idle). 231 232In addition to that, if the given ``CPUIdle`` driver is only going to handle a 233subset of logical CPUs in the system, the :c:member:`cpumask` field in its 234struct cpuidle_driver object must point to the set (mask) of CPUs that will be 235handled by it. 236 237A ``CPUIdle`` driver can only be used after it has been registered. If there 238are no "coupled" idle state entries in the driver's :c:member:`states` array, 239that can be accomplished by passing the driver's struct cpuidle_driver object 240to :c:func:`cpuidle_register_driver()`. Otherwise, :c:func:`cpuidle_register()` 241should be used for this purpose. 242 243However, it also is necessary to register struct cpuidle_device objects for 244all of the logical CPUs to be handled by the given ``CPUIdle`` driver with the 245help of :c:func:`cpuidle_register_device()` after the driver has been registered 246and :c:func:`cpuidle_register_driver()`, unlike :c:func:`cpuidle_register()`, 247does not do that automatically. For this reason, the drivers that use 248:c:func:`cpuidle_register_driver()` to register themselves must also take care 249of registering the struct cpuidle_device objects as needed, so it is generally 250recommended to use :c:func:`cpuidle_register()` for ``CPUIdle`` driver 251registration in all cases. 252 253The registration of a struct cpuidle_device object causes the ``CPUIdle`` 254``sysfs`` interface to be created and the governor's ``->enable()`` callback to 255be invoked for the logical CPU represented by it, so it must take place after 256registering the driver that will handle the CPU in question. 257 258``CPUIdle`` drivers and struct cpuidle_device objects can be unregistered 259when they are not necessary any more which allows some resources associated with 260them to be released. Due to dependencies between them, all of the 261struct cpuidle_device objects representing CPUs handled by the given 262``CPUIdle`` driver must be unregistered, with the help of 263:c:func:`cpuidle_unregister_device()`, before calling 264:c:func:`cpuidle_unregister_driver()` to unregister the driver. Alternatively, 265:c:func:`cpuidle_unregister()` can be called to unregister a ``CPUIdle`` driver 266along with all of the struct cpuidle_device objects representing CPUs handled 267by it. 268 269``CPUIdle`` drivers can respond to runtime system configuration changes that 270lead to modifications of the list of available processor idle states (which can 271happen, for example, when the system's power source is switched from AC to 272battery or the other way around). Upon a notification of such a change, 273a ``CPUIdle`` driver is expected to call :c:func:`cpuidle_pause_and_lock()` to 274turn ``CPUIdle`` off temporarily and then :c:func:`cpuidle_disable_device()` for 275all of the struct cpuidle_device objects representing CPUs affected by that 276change. Next, it can update its :c:member:`states` array in accordance with 277the new configuration of the system, call :c:func:`cpuidle_enable_device()` for 278all of the relevant struct cpuidle_device objects and invoke 279:c:func:`cpuidle_resume_and_unlock()` to allow ``CPUIdle`` to be used again. 280