Commit | Line | Data |
---|---|---|
fc7db767 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
fc1860d6 | 2 | .. include:: <isonum.txt> |
fc7db767 | 3 | |
f77af637 FV |
4 | .. _driverapi_pm_devices: |
5 | ||
2728b2d2 RW |
6 | ============================== |
7 | Device Power Management Basics | |
8 | ============================== | |
d6f9cda1 | 9 | |
fc1860d6 RW |
10 | :Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. |
11 | :Copyright: |copy| 2010 Alan Stern <stern@rowland.harvard.edu> | |
12 | :Copyright: |copy| 2016 Intel Corporation | |
13 | ||
14 | :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> | |
2728b2d2 | 15 | |
624f6ec8 | 16 | |
4fc08400 | 17 | Most of the code in Linux is device drivers, so most of the Linux power |
d6f9cda1 AS |
18 | management (PM) code is also driver-specific. Most drivers will do very |
19 | little; others, especially for platforms with small batteries (like cell | |
20 | phones), will do a lot. | |
4fc08400 DB |
21 | |
22 | This writeup gives an overview of how drivers interact with system-wide | |
23 | power management goals, emphasizing the models and interfaces that are | |
24 | shared by everything that hooks up to the driver model core. Read it as | |
25 | background for the domain-specific work you'd do with any specific driver. | |
26 | ||
27 | ||
28 | Two Models for Device Power Management | |
29 | ====================================== | |
2728b2d2 | 30 | |
4fc08400 DB |
31 | Drivers will use one or both of these models to put devices into low-power |
32 | states: | |
33 | ||
34 | System Sleep model: | |
2728b2d2 | 35 | |
d6f9cda1 AS |
36 | Drivers can enter low-power states as part of entering system-wide |
37 | low-power states like "suspend" (also known as "suspend-to-RAM"), or | |
38 | (mostly for systems with disks) "hibernation" (also known as | |
39 | "suspend-to-disk"). | |
4fc08400 DB |
40 | |
41 | This is something that device, bus, and class drivers collaborate on | |
42 | by implementing various role-specific suspend and resume methods to | |
43 | cleanly power down hardware and software subsystems, then reactivate | |
44 | them without loss of data. | |
45 | ||
46 | Some drivers can manage hardware wakeup events, which make the system | |
d6f9cda1 | 47 | leave the low-power state. This feature may be enabled or disabled |
2728b2d2 RW |
48 | using the relevant :file:`/sys/devices/.../power/wakeup` file (for |
49 | Ethernet drivers the ioctl interface used by ethtool may also be used | |
50 | for this purpose); enabling it may cost some power usage, but let the | |
51 | whole system enter low-power states more often. | |
4fc08400 DB |
52 | |
53 | Runtime Power Management model: | |
2728b2d2 | 54 | |
d6f9cda1 | 55 | Devices may also be put into low-power states while the system is |
624f6ec8 RW |
56 | running, independently of other power management activity in principle. |
57 | However, devices are not generally independent of each other (for | |
d6f9cda1 AS |
58 | example, a parent device cannot be suspended unless all of its child |
59 | devices have been suspended). Moreover, depending on the bus type the | |
624f6ec8 | 60 | device is on, it may be necessary to carry out some bus-specific |
d6f9cda1 AS |
61 | operations on the device for this purpose. Devices put into low power |
62 | states at run time may require special handling during system-wide power | |
63 | transitions (suspend or hibernation). | |
624f6ec8 RW |
64 | |
65 | For these reasons not only the device driver itself, but also the | |
d6f9cda1 AS |
66 | appropriate subsystem (bus type, device type or device class) driver and |
67 | the PM core are involved in runtime power management. As in the system | |
68 | sleep power management case, they need to collaborate by implementing | |
69 | various role-specific suspend and resume methods, so that the hardware | |
70 | is cleanly powered down and reactivated without data or service loss. | |
71 | ||
72 | There's not a lot to be said about those low-power states except that they are | |
73 | very system-specific, and often device-specific. Also, that if enough devices | |
74 | have been put into low-power states (at runtime), the effect may be very similar | |
75 | to entering some system-wide low-power state (system sleep) ... and that | |
76 | synergies exist, so that several drivers using runtime PM might put the system | |
77 | into a state where even deeper power saving options are available. | |
78 | ||
79 | Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except | |
80 | for wakeup events), no more data read or written, and requests from upstream | |
81 | drivers are no longer accepted. A given bus or platform may have different | |
82 | requirements though. | |
4fc08400 DB |
83 | |
84 | Examples of hardware wakeup events include an alarm from a real time clock, | |
85 | network wake-on-LAN packets, keyboard or mouse activity, and media insertion | |
86 | or removal (for PCMCIA, MMC/SD, USB, and so on). | |
87 | ||
4fc08400 DB |
88 | Interfaces for Entering System Sleep States |
89 | =========================================== | |
2728b2d2 | 90 | |
d6f9cda1 AS |
91 | There are programming interfaces provided for subsystems (bus type, device type, |
92 | device class) and device drivers to allow them to participate in the power | |
93 | management of devices they are concerned with. These interfaces cover both | |
94 | system sleep and runtime power management. | |
624f6ec8 RW |
95 | |
96 | ||
97 | Device Power Management Operations | |
98 | ---------------------------------- | |
2728b2d2 | 99 | |
624f6ec8 RW |
100 | Device power management operations, at the subsystem level as well as at the |
101 | device driver level, are implemented by defining and populating objects of type | |
6624d64d | 102 | struct dev_pm_ops defined in :file:`include/linux/pm.h`. The roles of the |
e3941cd9 RW |
103 | methods included in it will be explained in what follows. For now, it should be |
104 | sufficient to remember that the last three methods are specific to runtime power | |
105 | management while the remaining ones are used during system-wide power | |
106 | transitions. | |
4fc08400 | 107 | |
d6f9cda1 AS |
108 | There also is a deprecated "old" or "legacy" interface for power management |
109 | operations available at least for some subsystems. This approach does not use | |
6624d64d | 110 | struct dev_pm_ops objects and it is suitable only for implementing system |
e3941cd9 RW |
111 | sleep power management methods in a limited way. Therefore it is not described |
112 | in this document, so please refer directly to the source code for more | |
2728b2d2 | 113 | information about it. |
624f6ec8 RW |
114 | |
115 | ||
116 | Subsystem-Level Methods | |
117 | ----------------------- | |
2728b2d2 RW |
118 | |
119 | The core methods to suspend and resume devices reside in | |
6624d64d MCC |
120 | struct dev_pm_ops pointed to by the :c:member:`ops` member of |
121 | struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type, | |
122 | struct device_type and struct class. They are mostly of interest to the | |
e3941cd9 RW |
123 | people writing infrastructure for platforms and buses, like PCI or USB, or |
124 | device type and device class drivers. They also are relevant to the writers of | |
125 | device drivers whose subsystems (PM domains, device types, device classes and | |
126 | bus types) don't provide all power management methods. | |
1da177e4 | 127 | |
d6f9cda1 AS |
128 | Bus drivers implement these methods as appropriate for the hardware and the |
129 | drivers using it; PCI works differently from USB, and so on. Not many people | |
130 | write subsystem-level drivers; most driver code is a "device driver" that builds | |
131 | on top of bus-specific framework code. | |
4fc08400 DB |
132 | |
133 | For more information on these driver calls, see the description later; | |
134 | they are called in phases for every device, respecting the parent-child | |
624f6ec8 | 135 | sequencing in the driver model tree. |
4fc08400 DB |
136 | |
137 | ||
2728b2d2 RW |
138 | :file:`/sys/devices/.../power/wakeup` files |
139 | ------------------------------------------- | |
140 | ||
fafba48d RW |
141 | All device objects in the driver model contain fields that control the handling |
142 | of system wakeup events (hardware signals that can force the system out of a | |
143 | sleep state). These fields are initialized by bus or device driver code using | |
2728b2d2 RW |
144 | :c:func:`device_set_wakeup_capable()` and :c:func:`device_set_wakeup_enable()`, |
145 | defined in :file:`include/linux/pm_wakeup.h`. | |
146 | ||
147 | The :c:member:`power.can_wakeup` flag just records whether the device (and its | |
148 | driver) can physically support wakeup events. The | |
149 | :c:func:`device_set_wakeup_capable()` routine affects this flag. The | |
150 | :c:member:`power.wakeup` field is a pointer to an object of type | |
6624d64d | 151 | struct wakeup_source used for controlling whether or not the device should use |
e3941cd9 RW |
152 | its system wakeup mechanism and for notifying the PM core of system wakeup |
153 | events signaled by the device. This object is only present for wakeup-capable | |
154 | devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created | |
155 | (or removed) by :c:func:`device_set_wakeup_capable()`. | |
d6f9cda1 AS |
156 | |
157 | Whether or not a device is capable of issuing wakeup events is a hardware | |
158 | matter, and the kernel is responsible for keeping track of it. By contrast, | |
159 | whether or not a wakeup-capable device should issue wakeup events is a policy | |
160 | decision, and it is managed by user space through a sysfs attribute: the | |
2728b2d2 RW |
161 | :file:`power/wakeup` file. User space can write the "enabled" or "disabled" |
162 | strings to it to indicate whether or not, respectively, the device is supposed | |
163 | to signal system wakeup. This file is only present if the | |
164 | :c:member:`power.wakeup` object exists for the given device and is created (or | |
165 | removed) along with that object, by :c:func:`device_set_wakeup_capable()`. | |
166 | Reads from the file will return the corresponding string. | |
167 | ||
168 | The initial value in the :file:`power/wakeup` file is "disabled" for the | |
169 | majority of devices; the major exceptions are power buttons, keyboards, and | |
170 | Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool. | |
171 | It should also default to "enabled" for devices that don't generate wakeup | |
172 | requests on their own but merely forward wakeup requests from one bus to another | |
173 | (like PCI Express ports). | |
174 | ||
175 | The :c:func:`device_may_wakeup()` routine returns true only if the | |
176 | :c:member:`power.wakeup` object exists and the corresponding :file:`power/wakeup` | |
177 | file contains the "enabled" string. This information is used by subsystems, | |
178 | like the PCI bus type code, to see whether or not to enable the devices' wakeup | |
179 | mechanisms. If device wakeup mechanisms are enabled or disabled directly by | |
180 | drivers, they also should use :c:func:`device_may_wakeup()` to decide what to do | |
181 | during a system sleep transition. Device drivers, however, are not expected to | |
182 | call :c:func:`device_set_wakeup_enable()` directly in any case. | |
fafba48d RW |
183 | |
184 | It ought to be noted that system wakeup is conceptually different from "remote | |
185 | wakeup" used by runtime power management, although it may be supported by the | |
186 | same physical mechanism. Remote wakeup is a feature allowing devices in | |
187 | low-power states to trigger specific interrupts to signal conditions in which | |
188 | they should be put into the full-power state. Those interrupts may or may not | |
189 | be used to signal system wakeup events, depending on the hardware design. On | |
190 | some systems it is impossible to trigger them from system sleep states. In any | |
191 | case, remote wakeup should always be enabled for runtime power management for | |
192 | all devices and drivers that support it. | |
624f6ec8 | 193 | |
2728b2d2 RW |
194 | |
195 | :file:`/sys/devices/.../power/control` files | |
196 | -------------------------------------------- | |
197 | ||
d6f9cda1 | 198 | Each device in the driver model has a flag to control whether it is subject to |
2728b2d2 RW |
199 | runtime power management. This flag, :c:member:`runtime_auto`, is initialized |
200 | by the bus type (or generally subsystem) code using :c:func:`pm_runtime_allow()` | |
201 | or :c:func:`pm_runtime_forbid()`; the default is to allow runtime power | |
202 | management. | |
d6f9cda1 AS |
203 | |
204 | The setting can be adjusted by user space by writing either "on" or "auto" to | |
2728b2d2 RW |
205 | the device's :file:`power/control` sysfs file. Writing "auto" calls |
206 | :c:func:`pm_runtime_allow()`, setting the flag and allowing the device to be | |
207 | runtime power-managed by its driver. Writing "on" calls | |
208 | :c:func:`pm_runtime_forbid()`, clearing the flag, returning the device to full | |
209 | power if it was in a low-power state, and preventing the | |
d6f9cda1 | 210 | device from being runtime power-managed. User space can check the current value |
2728b2d2 | 211 | of the :c:member:`runtime_auto` flag by reading that file. |
624f6ec8 | 212 | |
2728b2d2 RW |
213 | The device's :c:member:`runtime_auto` flag has no effect on the handling of |
214 | system-wide power transitions. In particular, the device can (and in the | |
215 | majority of cases should and will) be put into a low-power state during a | |
216 | system-wide transition to a sleep state even though its :c:member:`runtime_auto` | |
217 | flag is clear. | |
624f6ec8 | 218 | |
d6f9cda1 | 219 | For more information about the runtime power management framework, refer to |
559a66b8 | 220 | Documentation/power/runtime_pm.rst. |
4fc08400 DB |
221 | |
222 | ||
d6f9cda1 AS |
223 | Calling Drivers to Enter and Leave System Sleep States |
224 | ====================================================== | |
2728b2d2 | 225 | |
d6f9cda1 AS |
226 | When the system goes into a sleep state, each device's driver is asked to |
227 | suspend the device by putting it into a state compatible with the target | |
4fc08400 DB |
228 | system state. That's usually some version of "off", but the details are |
229 | system-specific. Also, wakeup-enabled devices will usually stay partly | |
230 | functional in order to wake the system. | |
231 | ||
d6f9cda1 AS |
232 | When the system leaves that low-power state, the device's driver is asked to |
233 | resume it by returning it to full power. The suspend and resume operations | |
234 | always go together, and both are multi-phase operations. | |
4fc08400 | 235 | |
d6f9cda1 AS |
236 | For simple drivers, suspend might quiesce the device using class code |
237 | and then turn its hardware as "off" as possible during suspend_noirq. The | |
4fc08400 DB |
238 | matching resume calls would then completely reinitialize the hardware |
239 | before reactivating its class I/O queues. | |
240 | ||
624f6ec8 RW |
241 | More power-aware drivers might prepare the devices for triggering system wakeup |
242 | events. | |
4fc08400 DB |
243 | |
244 | ||
245 | Call Sequence Guarantees | |
246 | ------------------------ | |
2728b2d2 | 247 | |
624f6ec8 | 248 | To ensure that bridges and similar links needing to talk to a device are |
2728b2d2 | 249 | available when the device is suspended or resumed, the device hierarchy is |
4fc08400 DB |
250 | walked in a bottom-up order to suspend devices. A top-down order is |
251 | used to resume those devices. | |
252 | ||
2728b2d2 | 253 | The ordering of the device hierarchy is defined by the order in which devices |
4fc08400 DB |
254 | get registered: a child can never be registered, probed or resumed before |
255 | its parent; and can't be removed or suspended after that parent. | |
256 | ||
2728b2d2 RW |
257 | The policy is that the device hierarchy should match hardware bus topology. |
258 | [Or at least the control bus, for devices which use multiple busses.] | |
58aca232 | 259 | In particular, this means that a device registration may fail if the parent of |
624f6ec8 | 260 | the device is suspending (i.e. has been chosen by the PM core as the next |
58aca232 RW |
261 | device to suspend) or has already suspended, as well as after all of the other |
262 | devices have been suspended. Device drivers must be prepared to cope with such | |
263 | situations. | |
4fc08400 DB |
264 | |
265 | ||
d6f9cda1 AS |
266 | System Power Management Phases |
267 | ------------------------------ | |
2728b2d2 | 268 | |
d6f9cda1 | 269 | Suspending or resuming the system is done in several phases. Different phases |
2728b2d2 RW |
270 | are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM") |
271 | sleep states and the hibernation state ("suspend-to-disk"). Each phase involves | |
272 | executing callbacks for every device before the next phase begins. Not all | |
273 | buses or classes support all these callbacks and not all drivers use all the | |
274 | callbacks. The various phases always run after tasks have been frozen and | |
7e95d913 | 275 | before they are unfrozen. Furthermore, the ``*_noirq`` phases run at a time |
2728b2d2 RW |
276 | when IRQ handlers have been disabled (except for those marked with the |
277 | IRQF_NO_SUSPEND flag). | |
624f6ec8 | 278 | |
35cd133c | 279 | All phases use PM domain, bus, type, class or driver callbacks (that is, methods |
2728b2d2 RW |
280 | defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``, |
281 | ``dev->class->pm`` or ``dev->driver->pm``). These callbacks are regarded by the | |
282 | PM core as mutually exclusive. Moreover, PM domain callbacks always take | |
283 | precedence over all of the other callbacks and, for example, type callbacks take | |
284 | precedence over bus, class and driver callbacks. To be precise, the following | |
285 | rules are used to determine which callback to execute in the given phase: | |
5841eb64 | 286 | |
2728b2d2 RW |
287 | 1. If ``dev->pm_domain`` is present, the PM core will choose the callback |
288 | provided by ``dev->pm_domain->ops`` for execution. | |
5841eb64 | 289 | |
2728b2d2 RW |
290 | 2. Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the |
291 | callback provided by ``dev->type->pm`` will be chosen for execution. | |
5841eb64 | 292 | |
2728b2d2 RW |
293 | 3. Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present, |
294 | the callback provided by ``dev->class->pm`` will be chosen for | |
295 | execution. | |
5841eb64 | 296 | |
2728b2d2 RW |
297 | 4. Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the |
298 | callback provided by ``dev->bus->pm`` will be chosen for execution. | |
5841eb64 RW |
299 | |
300 | This allows PM domains and device types to override callbacks provided by bus | |
301 | types or device classes if necessary. | |
4fc08400 | 302 | |
35cd133c | 303 | The PM domain, type, class and bus callbacks may in turn invoke device- or |
2728b2d2 | 304 | driver-specific methods stored in ``dev->driver->pm``, but they don't have to do |
35cd133c RW |
305 | that. |
306 | ||
307 | If the subsystem callback chosen for execution is not present, the PM core will | |
2728b2d2 RW |
308 | execute the corresponding method from the ``dev->driver->pm`` set instead if |
309 | there is one. | |
4fc08400 | 310 | |
4fc08400 | 311 | |
d6f9cda1 AS |
312 | Entering System Suspend |
313 | ----------------------- | |
d6f9cda1 | 314 | |
2728b2d2 RW |
315 | When the system goes into the freeze, standby or memory sleep state, |
316 | the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``. | |
d6f9cda1 | 317 | |
2728b2d2 RW |
318 | 1. The ``prepare`` phase is meant to prevent races by preventing new |
319 | devices from being registered; the PM core would never know that all the | |
d6f9cda1 | 320 | children of a device had been suspended if new children could be |
2728b2d2 RW |
321 | registered at will. [By contrast, from the PM core's perspective, |
322 | devices may be unregistered at any time.] Unlike the other | |
323 | suspend-related phases, during the ``prepare`` phase the device | |
324 | hierarchy is traversed top-down. | |
d6f9cda1 | 325 | |
2728b2d2 | 326 | After the ``->prepare`` callback method returns, no new children may be |
91e7c75b | 327 | registered below the device. The method may also prepare the device or |
fa8ce723 | 328 | driver in some way for the upcoming system power transition, but it |
104dc5e2 RW |
329 | should not put the device into a low-power state. Moreover, if the |
330 | device supports runtime power management, the ``->prepare`` callback | |
331 | method must not update its state in case it is necessary to resume it | |
332 | from runtime suspend later on. | |
d6f9cda1 | 333 | |
f71495f3 RW |
334 | For devices supporting runtime power management, the return value of the |
335 | prepare callback can be used to indicate to the PM core that it may | |
336 | safely leave the device in runtime suspend (if runtime-suspended | |
337 | already), provided that all of the device's descendants are also left in | |
338 | runtime suspend. Namely, if the prepare callback returns a positive | |
339 | number and that happens for all of the descendants of the device too, | |
340 | and all of them (including the device itself) are runtime-suspended, the | |
2728b2d2 RW |
341 | PM core will skip the ``suspend``, ``suspend_late`` and |
342 | ``suspend_noirq`` phases as well as all of the corresponding phases of | |
343 | the subsequent device resume for all of these devices. In that case, | |
598cc930 | 344 | the ``->complete`` callback will be the next one invoked after the |
2728b2d2 RW |
345 | ``->prepare`` callback and is entirely responsible for putting the |
346 | device into a consistent state as appropriate. | |
f71495f3 | 347 | |
019d8817 AS |
348 | Note that this direct-complete procedure applies even if the device is |
349 | disabled for runtime PM; only the runtime-PM status matters. It follows | |
350 | that if a device has system-sleep callbacks but does not support runtime | |
351 | PM, then its prepare callback must never return a positive value. This | |
2728b2d2 | 352 | is because all such devices are initially set to runtime-suspended with |
019d8817 AS |
353 | runtime PM disabled. |
354 | ||
08810a41 | 355 | This feature also can be controlled by device drivers by using the |
e0751556 RW |
356 | ``DPM_FLAG_NO_DIRECT_COMPLETE`` and ``DPM_FLAG_SMART_PREPARE`` driver |
357 | power management flags. [Typically, they are set at the time the driver | |
358 | is probed against the device in question by passing them to the | |
08810a41 RW |
359 | :c:func:`dev_pm_set_driver_flags` helper function.] If the first of |
360 | these flags is set, the PM core will not apply the direct-complete | |
361 | procedure described above to the given device and, consequenty, to any | |
362 | of its ancestors. The second flag, when set, informs the middle layer | |
363 | code (bus types, device types, PM domains, classes) that it should take | |
364 | the return value of the ``->prepare`` callback provided by the driver | |
365 | into account and it may only return a positive value from its own | |
366 | ``->prepare`` callback if the driver's one also has returned a positive | |
367 | value. | |
368 | ||
2728b2d2 RW |
369 | 2. The ``->suspend`` methods should quiesce the device to stop it from |
370 | performing I/O. They also may save the device registers and put it into | |
371 | the appropriate low-power state, depending on the bus type the device is | |
372 | on, and they may enable wakeup events. | |
d6f9cda1 | 373 | |
104dc5e2 RW |
374 | However, for devices supporting runtime power management, the |
375 | ``->suspend`` methods provided by subsystems (bus types and PM domains | |
376 | in particular) must follow an additional rule regarding what can be done | |
377 | to the devices before their drivers' ``->suspend`` methods are called. | |
598cc930 AS |
378 | Namely, they may resume the devices from runtime suspend by |
379 | calling :c:func:`pm_runtime_resume` for them, if that is necessary, but | |
104dc5e2 RW |
380 | they must not update the state of the devices in any other way at that |
381 | time (in case the drivers need to resume the devices from runtime | |
598cc930 AS |
382 | suspend in their ``->suspend`` methods). In fact, the PM core prevents |
383 | subsystems or drivers from putting devices into runtime suspend at | |
384 | these times by calling :c:func:`pm_runtime_get_noresume` before issuing | |
385 | the ``->prepare`` callback (and calling :c:func:`pm_runtime_put` after | |
386 | issuing the ``->complete`` callback). | |
104dc5e2 | 387 | |
2728b2d2 | 388 | 3. For a number of devices it is convenient to split suspend into the |
cf579dfb | 389 | "quiesce device" and "save device state" phases, in which cases |
2728b2d2 RW |
390 | ``suspend_late`` is meant to do the latter. It is always executed after |
391 | runtime power management has been disabled for the device in question. | |
cf579dfb | 392 | |
2728b2d2 | 393 | 4. The ``suspend_noirq`` phase occurs after IRQ handlers have been disabled, |
d6f9cda1 | 394 | which means that the driver's interrupt handler will not be called while |
2728b2d2 RW |
395 | the callback method is running. The ``->suspend_noirq`` methods should |
396 | save the values of the device's registers that weren't saved previously | |
397 | and finally put the device into the appropriate low-power state. | |
624f6ec8 RW |
398 | |
399 | The majority of subsystems and device drivers need not implement this | |
d6f9cda1 AS |
400 | callback. However, bus types allowing devices to share interrupt |
401 | vectors, like PCI, generally need it; otherwise a driver might encounter | |
402 | an error during the suspend phase by fielding a shared interrupt | |
403 | generated by some other device after its own device had been set to low | |
404 | power. | |
405 | ||
406 | At the end of these phases, drivers should have stopped all I/O transactions | |
407 | (DMA, IRQs), saved enough state that they can re-initialize or restore previous | |
408 | state (as needed by the hardware), and placed the device into a low-power state. | |
409 | On many platforms they will gate off one or more clock sources; sometimes they | |
2728b2d2 RW |
410 | will also switch off power supplies or reduce voltages. [Drivers supporting |
411 | runtime PM may already have performed some or all of these steps.] | |
624f6ec8 | 412 | |
2f27ed75 | 413 | If :c:func:`device_may_wakeup()` returns ``true``, the device should be |
2728b2d2 RW |
414 | prepared for generating hardware wakeup signals to trigger a system wakeup event |
415 | when the system is in the sleep state. For example, :c:func:`enable_irq_wake()` | |
416 | might identify GPIO signals hooked up to a switch or other external hardware, | |
417 | and :c:func:`pci_enable_wake()` does something similar for the PCI PME signal. | |
624f6ec8 | 418 | |
d6f9cda1 | 419 | If any of these callbacks returns an error, the system won't enter the desired |
2728b2d2 | 420 | low-power state. Instead, the PM core will unwind its actions by resuming all |
d6f9cda1 | 421 | the devices that were suspended. |
4fc08400 DB |
422 | |
423 | ||
d6f9cda1 AS |
424 | Leaving System Suspend |
425 | ---------------------- | |
4fc08400 | 426 | |
2728b2d2 RW |
427 | When resuming from freeze, standby or memory sleep, the phases are: |
428 | ``resume_noirq``, ``resume_early``, ``resume``, ``complete``. | |
429 | ||
430 | 1. The ``->resume_noirq`` callback methods should perform any actions | |
431 | needed before the driver's interrupt handlers are invoked. This | |
432 | generally means undoing the actions of the ``suspend_noirq`` phase. If | |
433 | the bus type permits devices to share interrupt vectors, like PCI, the | |
434 | method should bring the device and its driver into a state in which the | |
435 | driver can recognize if the device is the source of incoming interrupts, | |
436 | if any, and handle them correctly. | |
437 | ||
438 | For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device | |
439 | into the full-power state (D0 in the PCI terminology) and restores the | |
d6f9cda1 | 440 | standard configuration registers of the device. Then it calls the |
2728b2d2 | 441 | device driver's ``->pm.resume_noirq()`` method to perform device-specific |
d6f9cda1 | 442 | actions. |
4fc08400 | 443 | |
2728b2d2 RW |
444 | 2. The ``->resume_early`` methods should prepare devices for the execution |
445 | of the resume methods. This generally involves undoing the actions of | |
446 | the preceding ``suspend_late`` phase. | |
cf579dfb | 447 | |
2728b2d2 | 448 | 3. The ``->resume`` methods should bring the device back to its operating |
d6f9cda1 | 449 | state, so that it can perform normal I/O. This generally involves |
2728b2d2 RW |
450 | undoing the actions of the ``suspend`` phase. |
451 | ||
452 | 4. The ``complete`` phase should undo the actions of the ``prepare`` phase. | |
453 | For this reason, unlike the other resume-related phases, during the | |
454 | ``complete`` phase the device hierarchy is traversed bottom-up. | |
455 | ||
456 | Note, however, that new children may be registered below the device as | |
457 | soon as the ``->resume`` callbacks occur; it's not necessary to wait | |
598cc930 | 458 | until the ``complete`` phase runs. |
2728b2d2 RW |
459 | |
460 | Moreover, if the preceding ``->prepare`` callback returned a positive | |
461 | number, the device may have been left in runtime suspend throughout the | |
598cc930 AS |
462 | whole system suspend and resume (its ``->suspend``, ``->suspend_late``, |
463 | ``->suspend_noirq``, ``->resume_noirq``, | |
464 | ``->resume_early``, and ``->resume`` callbacks may have been | |
465 | skipped). In that case, the ``->complete`` callback is entirely | |
2728b2d2 RW |
466 | responsible for putting the device into a consistent state after system |
467 | suspend if necessary. [For example, it may need to queue up a runtime | |
468 | resume request for the device for this purpose.] To check if that is | |
469 | the case, the ``->complete`` callback can consult the device's | |
598cc930 AS |
470 | ``power.direct_complete`` flag. If that flag is set when the |
471 | ``->complete`` callback is being run then the direct-complete mechanism | |
472 | was used, and special actions may be required to make the device work | |
473 | correctly afterward. | |
f71495f3 | 474 | |
d6f9cda1 AS |
475 | At the end of these phases, drivers should be as functional as they were before |
476 | suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are | |
f71495f3 | 477 | gated on. |
4fc08400 DB |
478 | |
479 | However, the details here may again be platform-specific. For example, | |
480 | some systems support multiple "run" states, and the mode in effect at | |
624f6ec8 | 481 | the end of resume might not be the one which preceded suspension. |
4fc08400 DB |
482 | That means availability of certain clocks or power supplies changed, |
483 | which could easily affect how a driver works. | |
484 | ||
2728b2d2 | 485 | Drivers need to be able to handle hardware which has been reset since all of the |
4fc08400 DB |
486 | suspend methods were called, for example by complete reinitialization. |
487 | This may be the hardest part, and the one most protected by NDA'd documents | |
488 | and chip errata. It's simplest if the hardware state hasn't changed since | |
2728b2d2 RW |
489 | the suspend was carried out, but that can only be guaranteed if the target |
490 | system sleep entered was suspend-to-idle. For the other system sleep states | |
491 | that may not be the case (and usually isn't for ACPI-defined system sleep | |
492 | states, like S3). | |
4fc08400 DB |
493 | |
494 | Drivers must also be prepared to notice that the device has been removed | |
d6f9cda1 | 495 | while the system was powered down, whenever that's physically possible. |
4fc08400 DB |
496 | PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses |
497 | where common Linux platforms will see such removal. Details of how drivers | |
498 | will notice and handle such removals are currently bus-specific, and often | |
499 | involve a separate thread. | |
1da177e4 | 500 | |
d6f9cda1 AS |
501 | These callbacks may return an error value, but the PM core will ignore such |
502 | errors since there's nothing it can do about them other than printing them in | |
503 | the system log. | |
1da177e4 | 504 | |
d6f9cda1 AS |
505 | |
506 | Entering Hibernation | |
507 | -------------------- | |
d6f9cda1 | 508 | |
2728b2d2 RW |
509 | Hibernating the system is more complicated than putting it into sleep states, |
510 | because it involves creating and saving a system image. Therefore there are | |
511 | more phases for hibernation, with a different set of callbacks. These phases | |
512 | always run after tasks have been frozen and enough memory has been freed. | |
d6f9cda1 | 513 | |
2728b2d2 RW |
514 | The general procedure for hibernation is to quiesce all devices ("freeze"), |
515 | create an image of the system memory while everything is stable, reactivate all | |
516 | devices ("thaw"), write the image to permanent storage, and finally shut down | |
517 | the system ("power off"). The phases used to accomplish this are: ``prepare``, | |
518 | ``freeze``, ``freeze_late``, ``freeze_noirq``, ``thaw_noirq``, ``thaw_early``, | |
519 | ``thaw``, ``complete``, ``prepare``, ``poweroff``, ``poweroff_late``, | |
520 | ``poweroff_noirq``. | |
d6f9cda1 | 521 | |
2728b2d2 RW |
522 | 1. The ``prepare`` phase is discussed in the "Entering System Suspend" |
523 | section above. | |
d6f9cda1 | 524 | |
2728b2d2 RW |
525 | 2. The ``->freeze`` methods should quiesce the device so that it doesn't |
526 | generate IRQs or DMA, and they may need to save the values of device | |
527 | registers. However the device does not have to be put in a low-power | |
528 | state, and to save time it's best not to do so. Also, the device should | |
529 | not be prepared to generate wakeup events. | |
d6f9cda1 | 530 | |
2728b2d2 RW |
531 | 3. The ``freeze_late`` phase is analogous to the ``suspend_late`` phase |
532 | described earlier, except that the device should not be put into a | |
533 | low-power state and should not be allowed to generate wakeup events. | |
cf579dfb | 534 | |
2728b2d2 RW |
535 | 4. The ``freeze_noirq`` phase is analogous to the ``suspend_noirq`` phase |
536 | discussed earlier, except again that the device should not be put into | |
537 | a low-power state and should not be allowed to generate wakeup events. | |
d6f9cda1 AS |
538 | |
539 | At this point the system image is created. All devices should be inactive and | |
540 | the contents of memory should remain undisturbed while this happens, so that the | |
541 | image forms an atomic snapshot of the system state. | |
542 | ||
2728b2d2 RW |
543 | 5. The ``thaw_noirq`` phase is analogous to the ``resume_noirq`` phase |
544 | discussed earlier. The main difference is that its methods can assume | |
545 | the device is in the same state as at the end of the ``freeze_noirq`` | |
546 | phase. | |
d6f9cda1 | 547 | |
2728b2d2 RW |
548 | 6. The ``thaw_early`` phase is analogous to the ``resume_early`` phase |
549 | described above. Its methods should undo the actions of the preceding | |
550 | ``freeze_late``, if necessary. | |
cf579dfb | 551 | |
2728b2d2 RW |
552 | 7. The ``thaw`` phase is analogous to the ``resume`` phase discussed |
553 | earlier. Its methods should bring the device back to an operating | |
554 | state, so that it can be used for saving the image if necessary. | |
d6f9cda1 | 555 | |
2728b2d2 RW |
556 | 8. The ``complete`` phase is discussed in the "Leaving System Suspend" |
557 | section above. | |
d6f9cda1 AS |
558 | |
559 | At this point the system image is saved, and the devices then need to be | |
560 | prepared for the upcoming system shutdown. This is much like suspending them | |
2728b2d2 | 561 | before putting the system into the suspend-to-idle, shallow or deep sleep state, |
dc5aeae4 | 562 | and the phases are similar. |
d6f9cda1 | 563 | |
2728b2d2 | 564 | 9. The ``prepare`` phase is discussed above. |
cf579dfb | 565 | |
2728b2d2 | 566 | 10. The ``poweroff`` phase is analogous to the ``suspend`` phase. |
d6f9cda1 | 567 | |
2728b2d2 | 568 | 11. The ``poweroff_late`` phase is analogous to the ``suspend_late`` phase. |
d6f9cda1 | 569 | |
2728b2d2 | 570 | 12. The ``poweroff_noirq`` phase is analogous to the ``suspend_noirq`` phase. |
d6f9cda1 | 571 | |
2728b2d2 RW |
572 | The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks |
573 | should do essentially the same things as the ``->suspend``, ``->suspend_late`` | |
598cc930 | 574 | and ``->suspend_noirq`` callbacks, respectively. A notable difference is |
2728b2d2 RW |
575 | that they need not store the device register values, because the registers |
576 | should already have been stored during the ``freeze``, ``freeze_late`` or | |
598cc930 AS |
577 | ``freeze_noirq`` phases. Also, on many machines the firmware will power-down |
578 | the entire system, so it is not necessary for the callback to put the device in | |
579 | a low-power state. | |
d6f9cda1 AS |
580 | |
581 | ||
582 | Leaving Hibernation | |
583 | ------------------- | |
2728b2d2 | 584 | |
624f6ec8 RW |
585 | Resuming from hibernation is, again, more complicated than resuming from a sleep |
586 | state in which the contents of main memory are preserved, because it requires | |
587 | a system image to be loaded into memory and the pre-hibernation memory contents | |
588 | to be restored before control can be passed back to the image kernel. | |
589 | ||
2728b2d2 | 590 | Although in principle the image might be loaded into memory and the |
d6f9cda1 AS |
591 | pre-hibernation memory contents restored by the boot loader, in practice this |
592 | can't be done because boot loaders aren't smart enough and there is no | |
593 | established protocol for passing the necessary information. So instead, the | |
2728b2d2 RW |
594 | boot loader loads a fresh instance of the kernel, called "the restore kernel", |
595 | into memory and passes control to it in the usual way. Then the restore kernel | |
596 | reads the system image, restores the pre-hibernation memory contents, and passes | |
597 | control to the image kernel. Thus two different kernel instances are involved | |
598 | in resuming from hibernation. In fact, the restore kernel may be completely | |
599 | different from the image kernel: a different configuration and even a different | |
600 | version. This has important consequences for device drivers and their | |
601 | subsystems. | |
602 | ||
603 | To be able to load the system image into memory, the restore kernel needs to | |
d6f9cda1 AS |
604 | include at least a subset of device drivers allowing it to access the storage |
605 | medium containing the image, although it doesn't need to include all of the | |
606 | drivers present in the image kernel. After the image has been loaded, the | |
607 | devices managed by the boot kernel need to be prepared for passing control back | |
608 | to the image kernel. This is very similar to the initial steps involved in | |
2728b2d2 RW |
609 | creating a system image, and it is accomplished in the same way, using |
610 | ``prepare``, ``freeze``, and ``freeze_noirq`` phases. However, the devices | |
611 | affected by these phases are only those having drivers in the restore kernel; | |
612 | other devices will still be in whatever state the boot loader left them. | |
624f6ec8 | 613 | |
2728b2d2 | 614 | Should the restoration of the pre-hibernation memory contents fail, the restore |
d6f9cda1 | 615 | kernel would go through the "thawing" procedure described above, using the |
2728b2d2 RW |
616 | ``thaw_noirq``, ``thaw_early``, ``thaw``, and ``complete`` phases, and then |
617 | continue running normally. This happens only rarely. Most often the | |
618 | pre-hibernation memory contents are restored successfully and control is passed | |
619 | to the image kernel, which then becomes responsible for bringing the system back | |
620 | to the working state. | |
624f6ec8 | 621 | |
d6f9cda1 | 622 | To achieve this, the image kernel must restore the devices' pre-hibernation |
2728b2d2 RW |
623 | functionality. The operation is much like waking up from a sleep state (with |
624 | the memory contents preserved), although it involves different phases: | |
625 | ``restore_noirq``, ``restore_early``, ``restore``, ``complete``. | |
624f6ec8 | 626 | |
2728b2d2 | 627 | 1. The ``restore_noirq`` phase is analogous to the ``resume_noirq`` phase. |
624f6ec8 | 628 | |
2728b2d2 | 629 | 2. The ``restore_early`` phase is analogous to the ``resume_early`` phase. |
624f6ec8 | 630 | |
2728b2d2 | 631 | 3. The ``restore`` phase is analogous to the ``resume`` phase. |
cf579dfb | 632 | |
2728b2d2 | 633 | 4. The ``complete`` phase is discussed above. |
624f6ec8 | 634 | |
2728b2d2 RW |
635 | The main difference from ``resume[_early|_noirq]`` is that |
636 | ``restore[_early|_noirq]`` must assume the device has been accessed and | |
637 | reconfigured by the boot loader or the restore kernel. Consequently, the state | |
638 | of the device may be different from the state remembered from the ``freeze``, | |
639 | ``freeze_late`` and ``freeze_noirq`` phases. The device may even need to be | |
640 | reset and completely re-initialized. In many cases this difference doesn't | |
641 | matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]`` | |
642 | method pointers can be set to the same routines. Nevertheless, different | |
643 | callback pointers are used in case there is a situation where it actually does | |
644 | matter. | |
624f6ec8 | 645 | |
1da177e4 | 646 | |
2728b2d2 RW |
647 | Power Management Notifiers |
648 | ========================== | |
1da177e4 | 649 | |
2728b2d2 RW |
650 | There are some operations that cannot be carried out by the power management |
651 | callbacks discussed above, because the callbacks occur too late or too early. | |
652 | To handle these cases, subsystems and device drivers may register power | |
653 | management notifiers that are called before tasks are frozen and after they have | |
654 | been thawed. Generally speaking, the PM notifiers are suitable for performing | |
655 | actions that either require user space to be available, or at least won't | |
656 | interfere with user space. | |
7538e3db | 657 | |
559a66b8 | 658 | For details refer to Documentation/driver-api/pm/notifiers.rst. |
ca9c6890 | 659 | |
7538e3db | 660 | |
2728b2d2 RW |
661 | Device Low-Power (suspend) States |
662 | ================================= | |
7538e3db | 663 | |
d6f9cda1 | 664 | Device low-power states aren't standard. One device might only handle |
8d2c7941 | 665 | "on" and "off", while another might support a dozen different versions of |
d6f9cda1 AS |
666 | "on" (how many engines are active?), plus a state that gets back to "on" |
667 | faster than from a full "off". | |
668 | ||
2728b2d2 RW |
669 | Some buses define rules about what different suspend states mean. PCI |
670 | gives one example: after the suspend sequence completes, a non-legacy | |
d6f9cda1 AS |
671 | PCI device may not perform DMA or issue IRQs, and any wakeup events it |
672 | issues would be issued through the PME# bus signal. Plus, there are | |
673 | several PCI-standard device states, some of which are optional. | |
674 | ||
675 | In contrast, integrated system-on-chip processors often use IRQs as the | |
2728b2d2 RW |
676 | wakeup event sources (so drivers would call :c:func:`enable_irq_wake`) and |
677 | might be able to treat DMA completion as a wakeup event (sometimes DMA can stay | |
d6f9cda1 AS |
678 | active too, it'd only be the CPU and some peripherals that sleep). |
679 | ||
680 | Some details here may be platform-specific. Systems may have devices that | |
681 | can be fully active in certain sleep states, such as an LCD display that's | |
682 | refreshed using DMA while most of the system is sleeping lightly ... and | |
683 | its frame buffer might even be updated by a DSP or other non-Linux CPU while | |
684 | the Linux control processor stays idle. | |
685 | ||
686 | Moreover, the specific actions taken may depend on the target system state. | |
687 | One target system state might allow a given device to be very operational; | |
688 | another might require a hard shut down with re-initialization on resume. | |
689 | And two different target systems might use the same device in different | |
690 | ways; the aforementioned LCD might be active in one product's "standby", | |
691 | but a different product using the same SOC might work differently. | |
692 | ||
693 | ||
2728b2d2 RW |
694 | Device Power Management Domains |
695 | =============================== | |
696 | ||
697 | Sometimes devices share reference clocks or other power resources. In those | |
698 | cases it generally is not possible to put devices into low-power states | |
699 | individually. Instead, a set of devices sharing a power resource can be put | |
700 | into a low-power state together at the same time by turning off the shared | |
701 | power resource. Of course, they also need to be put into the full-power state | |
702 | together, by turning the shared power resource on. A set of devices with this | |
703 | property is often referred to as a power domain. A power domain may also be | |
704 | nested inside another power domain. The nested domain is referred to as the | |
705 | sub-domain of the parent domain. | |
624f6ec8 | 706 | |
2728b2d2 | 707 | Support for power domains is provided through the :c:member:`pm_domain` field of |
6624d64d MCC |
708 | struct device. This field is a pointer to an object of type |
709 | struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set | |
e3941cd9 RW |
710 | of power management callbacks analogous to the subsystem-level and device driver |
711 | callbacks that are executed for the given device during all power transitions, | |
712 | instead of the respective subsystem-level callbacks. Specifically, if a | |
713 | device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback | |
714 | from the object pointed to by it will be executed instead of its subsystem's | |
715 | (e.g. bus type's) ``->suspend()`` callback and analogously for all of the | |
716 | remaining callbacks. In other words, power management domain callbacks, if | |
717 | defined for the given device, always take precedence over the callbacks provided | |
718 | by the device's subsystem (e.g. bus type). | |
2728b2d2 RW |
719 | |
720 | The support for device power management domains is only relevant to platforms | |
721 | needing to use the same device driver power management callbacks in many | |
722 | different power domain configurations and wanting to avoid incorporating the | |
723 | support for power domains into subsystem-level callbacks, for example by | |
724 | modifying the platform bus type. Other platforms need not implement it or take | |
725 | it into account in any way. | |
726 | ||
727 | Devices may be defined as IRQ-safe which indicates to the PM core that their | |
728 | runtime PM callbacks may be invoked with disabled interrupts (see | |
559a66b8 | 729 | Documentation/power/runtime_pm.rst for more information). If an |
2728b2d2 RW |
730 | IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be |
731 | disallowed, unless the domain itself is defined as IRQ-safe. However, it | |
732 | makes sense to define a PM domain as IRQ-safe only if all the devices in it | |
733 | are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime | |
734 | PM of the parent is only allowed if the parent itself is IRQ-safe too with the | |
735 | additional restriction that all child domains of an IRQ-safe parent must also | |
736 | be IRQ-safe. | |
624f6ec8 RW |
737 | |
738 | ||
4fc08400 DB |
739 | Runtime Power Management |
740 | ======================== | |
2728b2d2 | 741 | |
4fc08400 DB |
742 | Many devices are able to dynamically power down while the system is still |
743 | running. This feature is useful for devices that are not being used, and | |
744 | can offer significant power savings on a running system. These devices | |
745 | often support a range of runtime power states, which might use names such | |
746 | as "off", "sleep", "idle", "active", and so on. Those states will in some | |
d6f9cda1 | 747 | cases (like PCI) be partially constrained by the bus the device uses, and will |
4fc08400 DB |
748 | usually include hardware states that are also used in system sleep states. |
749 | ||
d6f9cda1 AS |
750 | A system-wide power transition can be started while some devices are in low |
751 | power states due to runtime power management. The system sleep PM callbacks | |
752 | should recognize such situations and react to them appropriately, but the | |
753 | necessary actions are subsystem-specific. | |
754 | ||
755 | In some cases the decision may be made at the subsystem level while in other | |
756 | cases the device driver may be left to decide. In some cases it may be | |
757 | desirable to leave a suspended device in that state during a system-wide power | |
758 | transition, but in other cases the device must be put back into the full-power | |
759 | state temporarily, for example so that its system wakeup capability can be | |
760 | disabled. This all depends on the hardware and the design of the subsystem and | |
761 | device driver in question. | |
762 | ||
104dc5e2 RW |
763 | If it is necessary to resume a device from runtime suspend during a system-wide |
764 | transition into a sleep state, that can be done by calling | |
598cc930 AS |
765 | :c:func:`pm_runtime_resume` from the ``->suspend`` callback (or the ``->freeze`` |
766 | or ``->poweroff`` callback for transitions related to hibernation) of either the | |
767 | device's driver or its subsystem (for example, a bus type or a PM domain). | |
768 | However, subsystems must not otherwise change the runtime status of devices | |
104dc5e2 RW |
769 | from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before* |
770 | invoking device drivers' ``->suspend`` callbacks (or equivalent). | |
771 | ||
2fff3f73 RW |
772 | .. _smart_suspend_flag: |
773 | ||
774 | The ``DPM_FLAG_SMART_SUSPEND`` Driver Flag | |
775 | ------------------------------------------ | |
776 | ||
0eab11c9 RW |
777 | Some bus types and PM domains have a policy to resume all devices from runtime |
778 | suspend upfront in their ``->suspend`` callbacks, but that may not be really | |
598cc930 AS |
779 | necessary if the device's driver can cope with runtime-suspended devices. |
780 | The driver can indicate this by setting ``DPM_FLAG_SMART_SUSPEND`` in | |
781 | :c:member:`power.driver_flags` at probe time, with the assistance of the | |
2fff3f73 RW |
782 | :c:func:`dev_pm_set_driver_flags` helper routine. |
783 | ||
598cc930 | 784 | Setting that flag causes the PM core and middle-layer code |
0eab11c9 RW |
785 | (bus types, PM domains etc.) to skip the ``->suspend_late`` and |
786 | ``->suspend_noirq`` callbacks provided by the driver if the device remains in | |
598cc930 AS |
787 | runtime suspend throughout those phases of the system-wide suspend (and |
788 | similarly for the "freeze" and "poweroff" parts of system hibernation). | |
789 | [Otherwise the same driver | |
2fff3f73 RW |
790 | callback might be executed twice in a row for the same device, which would not |
791 | be valid in general.] If the middle-layer system-wide PM callbacks are present | |
598cc930 AS |
792 | for the device then they are responsible for skipping these driver callbacks; |
793 | if not then the PM core skips them. The subsystem callback routines can | |
794 | determine whether they need to skip the driver callbacks by testing the return | |
795 | value from the :c:func:`dev_pm_skip_suspend` helper function. | |
2fff3f73 | 796 | |
598cc930 AS |
797 | In addition, with ``DPM_FLAG_SMART_SUSPEND`` set, the driver's ``->thaw_noirq`` |
798 | and ``->thaw_early`` callbacks are skipped in hibernation if the device remained | |
799 | in runtime suspend throughout the preceding "freeze" transition. Again, if the | |
800 | middle-layer callbacks are present for the device, they are responsible for | |
801 | doing this, otherwise the PM core takes care of it. | |
2fff3f73 RW |
802 | |
803 | ||
804 | The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag | |
805 | -------------------------------------------- | |
0eab11c9 | 806 | |
455716e9 | 807 | During system-wide resume from a sleep state it's easiest to put devices into |
559a66b8 | 808 | the full-power state, as explained in Documentation/power/runtime_pm.rst. |
0d4b54c6 | 809 | [Refer to that document for more information regarding this particular issue as |
2728b2d2 | 810 | well as for information on the device runtime power management framework in |
2fff3f73 RW |
811 | general.] However, it often is desirable to leave devices in suspend after |
812 | system transitions to the working state, especially if those devices had been in | |
0d4b54c6 | 813 | runtime suspend before the preceding system-wide suspend (or analogous) |
2fff3f73 RW |
814 | transition. |
815 | ||
816 | To that end, device drivers can use the ``DPM_FLAG_MAY_SKIP_RESUME`` flag to | |
817 | indicate to the PM core and middle-layer code that they allow their "noirq" and | |
818 | "early" resume callbacks to be skipped if the device can be left in suspend | |
819 | after system-wide PM transitions to the working state. Whether or not that is | |
820 | the case generally depends on the state of the device before the given system | |
821 | suspend-resume cycle and on the type of the system transition under way. | |
598cc930 AS |
822 | In particular, the "thaw" and "restore" transitions related to hibernation are |
823 | not affected by ``DPM_FLAG_MAY_SKIP_RESUME`` at all. [All callbacks are | |
824 | issued during the "restore" transition regardless of the flag settings, | |
825 | and whether or not any driver callbacks | |
826 | are skipped during the "thaw" transition depends whether or not the | |
827 | ``DPM_FLAG_SMART_SUSPEND`` flag is set (see `above <smart_suspend_flag_>`_). | |
828 | In addition, a device is not allowed to remain in runtime suspend if any of its | |
829 | children will be returned to full power.] | |
2fff3f73 RW |
830 | |
831 | The ``DPM_FLAG_MAY_SKIP_RESUME`` flag is taken into account in combination with | |
832 | the :c:member:`power.may_skip_resume` status bit set by the PM core during the | |
833 | "suspend" phase of suspend-type transitions. If the driver or the middle layer | |
834 | has a reason to prevent the driver's "noirq" and "early" resume callbacks from | |
598cc930 | 835 | being skipped during the subsequent system resume transition, it should |
2fff3f73 RW |
836 | clear :c:member:`power.may_skip_resume` in its ``->suspend``, ``->suspend_late`` |
837 | or ``->suspend_noirq`` callback. [Note that the drivers setting | |
838 | ``DPM_FLAG_SMART_SUSPEND`` need to clear :c:member:`power.may_skip_resume` in | |
839 | their ``->suspend`` callback in case the other two are skipped.] | |
840 | ||
841 | Setting the :c:member:`power.may_skip_resume` status bit along with the | |
842 | ``DPM_FLAG_MAY_SKIP_RESUME`` flag is necessary, but generally not sufficient, | |
843 | for the driver's "noirq" and "early" resume callbacks to be skipped. Whether or | |
844 | not they should be skipped can be determined by evaluating the | |
845 | :c:func:`dev_pm_skip_resume` helper function. | |
846 | ||
847 | If that function returns ``true``, the driver's "noirq" and "early" resume | |
848 | callbacks should be skipped and the device's runtime PM status will be set to | |
849 | "suspended" by the PM core. Otherwise, if the device was runtime-suspended | |
598cc930 AS |
850 | during the preceding system-wide suspend transition and its |
851 | ``DPM_FLAG_SMART_SUSPEND`` is set, its runtime PM status will be set to | |
2fff3f73 RW |
852 | "active" by the PM core. [Hence, the drivers that do not set |
853 | ``DPM_FLAG_SMART_SUSPEND`` should not expect the runtime PM status of their | |
854 | devices to be changed from "suspended" to "active" by the PM core during | |
855 | system-wide resume-type transitions.] | |
856 | ||
857 | If the ``DPM_FLAG_MAY_SKIP_RESUME`` flag is not set for a device, but | |
858 | ``DPM_FLAG_SMART_SUSPEND`` is set and the driver's "late" and "noirq" suspend | |
859 | callbacks are skipped, its system-wide "noirq" and "early" resume callbacks, if | |
860 | present, are invoked as usual and the device's runtime PM status is set to | |
861 | "active" by the PM core before enabling runtime PM for it. In that case, the | |
862 | driver must be prepared to cope with the invocation of its system-wide resume | |
863 | callbacks back-to-back with its ``->runtime_suspend`` one (without the | |
864 | intervening ``->runtime_resume`` and system-wide suspend callbacks) and the | |
865 | final state of the device must reflect the "active" runtime PM status in that | |
866 | case. [Note that this is not a problem at all if the driver's | |
867 | ``->suspend_late`` callback pointer points to the same function as its | |
868 | ``->runtime_suspend`` one and its ``->resume_early`` callback pointer points to | |
869 | the same function as the ``->runtime_resume`` one, while none of the other | |
870 | system-wide suspend-resume callbacks of the driver are present, for example.] | |
871 | ||
872 | Likewise, if ``DPM_FLAG_MAY_SKIP_RESUME`` is set for a device, its driver's | |
873 | system-wide "noirq" and "early" resume callbacks may be skipped while its "late" | |
874 | and "noirq" suspend callbacks may have been executed (in principle, regardless | |
875 | of whether or not ``DPM_FLAG_SMART_SUSPEND`` is set). In that case, the driver | |
876 | needs to be able to cope with the invocation of its ``->runtime_resume`` | |
877 | callback back-to-back with its "late" and "noirq" suspend ones. [For instance, | |
878 | that is not a concern if the driver sets both ``DPM_FLAG_SMART_SUSPEND`` and | |
879 | ``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same pair of suspend/resume callback | |
880 | functions for runtime PM and system-wide suspend/resume.] |