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