driver-api/pm/cpuidle.rst

16 Every time one of the logical CPUs in the system (the entities that appear to
18 cores) is idle after an interrupt or equivalent wakeup event, which means that
20 with it, there is an opportunity to save energy for the processor that it
21 belongs to.  That can be done by making the idle logical CPU stop fetching
25 However, there may be multiple different idle states that can be used in such a
27 (from the kernel perspective) and ask the processor to use (or "enter") that
28 particular idle state.  That is the role of the CPU idle time management
32 principle, so the generic code that in principle need not depend on the hardware
33 or platform design details in it is separate from the code that interacts with
36 to enter, *drivers* that pass the governors' decisions on to the hardware and
48 platform that the Linux kernel can run on.  For this reason, data structures
57 For the governor to be available at all, that object needs to be registered
59 a pointer to it passed as the argument.  If successful, that causes the core to
61 only 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
65 governor will be used from that point on (there can be only one ``CPUIdle``
84 	with that CPU (among other things, it should contain the list of
85 	struct cpuidle_state objects representing idle states that the
89 	code, and that causes the kernel to run the architecture-specific
91 	until the ``->enable()`` governor callback is invoked for that CPU
105 	allocated by that callback and so on.
121 	value returned by this callback is interpreted as an index into that
130 	stopped on that CPU already, however, it will not be restarted before
144 	time) and possibly use the result of that to improve the accuracy of
154 :c:member:`exit_latency` value is greater than the number returned by that
167 idle states that the processor hardware can be asked to enter shared by all of
172 the ascending order (that is, index 0 should correspond to the idle state with
197 	"loop" that can be used in order to avoid asking the processor to enter
219 The difference between in and ``->enter()`` is that it must not re-enable
226 entries in the :c:member:`states` array represent "coupled" idle states (that
227 is, idle states that can only be asked for if multiple related logical CPUs are
229 to be the index of an idle state that is not "coupled" (that is, one that can be
232 In addition to that, if the given ``CPUIdle`` driver is only going to handle a
234 struct cpuidle_driver object must point to the set (mask) of CPUs that will be
239 that can be accomplished by passing the driver's struct cpuidle_driver object
247 does not do that automatically.  For this reason, the drivers that use
256 registering the driver that will handle the CPU in question.
269 ``CPUIdle`` drivers can respond to runtime system configuration changes that
275 all of the struct cpuidle_device objects representing CPUs affected by that