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