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