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