Documentation/driver-api/pm/cpuidle.rst

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