Merge branch 'pm-sleep'
[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.  Moreover, if the
332         device supports runtime power management, the ``->prepare`` callback
333         method must not update its state in case it is necessary to resume it
334         from runtime suspend later on.
335
336         For devices supporting runtime power management, the return value of the
337         prepare callback can be used to indicate to the PM core that it may
338         safely leave the device in runtime suspend (if runtime-suspended
339         already), provided that all of the device's descendants are also left in
340         runtime suspend.  Namely, if the prepare callback returns a positive
341         number and that happens for all of the descendants of the device too,
342         and all of them (including the device itself) are runtime-suspended, the
343         PM core will skip the ``suspend``, ``suspend_late`` and
344         ``suspend_noirq`` phases as well as all of the corresponding phases of
345         the subsequent device resume for all of these devices.  In that case,
346         the ``->complete`` callback will be invoked directly after the
347         ``->prepare`` callback and is entirely responsible for putting the
348         device into a consistent state as appropriate.
349
350         Note that this direct-complete procedure applies even if the device is
351         disabled for runtime PM; only the runtime-PM status matters.  It follows
352         that if a device has system-sleep callbacks but does not support runtime
353         PM, then its prepare callback must never return a positive value.  This
354         is because all such devices are initially set to runtime-suspended with
355         runtime PM disabled.
356
357     2.  The ``->suspend`` methods should quiesce the device to stop it from
358         performing I/O.  They also may save the device registers and put it into
359         the appropriate low-power state, depending on the bus type the device is
360         on, and they may enable wakeup events.
361
362         However, for devices supporting runtime power management, the
363         ``->suspend`` methods provided by subsystems (bus types and PM domains
364         in particular) must follow an additional rule regarding what can be done
365         to the devices before their drivers' ``->suspend`` methods are called.
366         Namely, they can only resume the devices from runtime suspend by
367         calling :c:func:`pm_runtime_resume` for them, if that is necessary, and
368         they must not update the state of the devices in any other way at that
369         time (in case the drivers need to resume the devices from runtime
370         suspend in their ``->suspend`` methods).
371
372     3.  For a number of devices it is convenient to split suspend into the
373         "quiesce device" and "save device state" phases, in which cases
374         ``suspend_late`` is meant to do the latter.  It is always executed after
375         runtime power management has been disabled for the device in question.
376
377     4.  The ``suspend_noirq`` phase occurs after IRQ handlers have been disabled,
378         which means that the driver's interrupt handler will not be called while
379         the callback method is running.  The ``->suspend_noirq`` methods should
380         save the values of the device's registers that weren't saved previously
381         and finally put the device into the appropriate low-power state.
382
383         The majority of subsystems and device drivers need not implement this
384         callback.  However, bus types allowing devices to share interrupt
385         vectors, like PCI, generally need it; otherwise a driver might encounter
386         an error during the suspend phase by fielding a shared interrupt
387         generated by some other device after its own device had been set to low
388         power.
389
390 At the end of these phases, drivers should have stopped all I/O transactions
391 (DMA, IRQs), saved enough state that they can re-initialize or restore previous
392 state (as needed by the hardware), and placed the device into a low-power state.
393 On many platforms they will gate off one or more clock sources; sometimes they
394 will also switch off power supplies or reduce voltages.  [Drivers supporting
395 runtime PM may already have performed some or all of these steps.]
396
397 If :c:func:`device_may_wakeup(dev)` returns ``true``, the device should be
398 prepared for generating hardware wakeup signals to trigger a system wakeup event
399 when the system is in the sleep state.  For example, :c:func:`enable_irq_wake()`
400 might identify GPIO signals hooked up to a switch or other external hardware,
401 and :c:func:`pci_enable_wake()` does something similar for the PCI PME signal.
402
403 If any of these callbacks returns an error, the system won't enter the desired
404 low-power state.  Instead, the PM core will unwind its actions by resuming all
405 the devices that were suspended.
406
407
408 Leaving System Suspend
409 ----------------------
410
411 When resuming from freeze, standby or memory sleep, the phases are:
412 ``resume_noirq``, ``resume_early``, ``resume``, ``complete``.
413
414     1.  The ``->resume_noirq`` callback methods should perform any actions
415         needed before the driver's interrupt handlers are invoked.  This
416         generally means undoing the actions of the ``suspend_noirq`` phase.  If
417         the bus type permits devices to share interrupt vectors, like PCI, the
418         method should bring the device and its driver into a state in which the
419         driver can recognize if the device is the source of incoming interrupts,
420         if any, and handle them correctly.
421
422         For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device
423         into the full-power state (D0 in the PCI terminology) and restores the
424         standard configuration registers of the device.  Then it calls the
425         device driver's ``->pm.resume_noirq()`` method to perform device-specific
426         actions.
427
428     2.  The ``->resume_early`` methods should prepare devices for the execution
429         of the resume methods.  This generally involves undoing the actions of
430         the preceding ``suspend_late`` phase.
431
432     3.  The ``->resume`` methods should bring the device back to its operating
433         state, so that it can perform normal I/O.  This generally involves
434         undoing the actions of the ``suspend`` phase.
435
436     4.  The ``complete`` phase should undo the actions of the ``prepare`` phase.
437         For this reason, unlike the other resume-related phases, during the
438         ``complete`` phase the device hierarchy is traversed bottom-up.
439
440         Note, however, that new children may be registered below the device as
441         soon as the ``->resume`` callbacks occur; it's not necessary to wait
442         until the ``complete`` phase with that.
443
444         Moreover, if the preceding ``->prepare`` callback returned a positive
445         number, the device may have been left in runtime suspend throughout the
446         whole system suspend and resume (the ``suspend``, ``suspend_late``,
447         ``suspend_noirq`` phases of system suspend and the ``resume_noirq``,
448         ``resume_early``, ``resume`` phases of system resume may have been
449         skipped for it).  In that case, the ``->complete`` callback is entirely
450         responsible for putting the device into a consistent state after system
451         suspend if necessary.  [For example, it may need to queue up a runtime
452         resume request for the device for this purpose.]  To check if that is
453         the case, the ``->complete`` callback can consult the device's
454         ``power.direct_complete`` flag.  Namely, if that flag is set when the
455         ``->complete`` callback is being run, it has been called directly after
456         the preceding ``->prepare`` and special actions may be required
457         to make the device work correctly afterward.
458
459 At the end of these phases, drivers should be as functional as they were before
460 suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are
461 gated on.
462
463 However, the details here may again be platform-specific.  For example,
464 some systems support multiple "run" states, and the mode in effect at
465 the end of resume might not be the one which preceded suspension.
466 That means availability of certain clocks or power supplies changed,
467 which could easily affect how a driver works.
468
469 Drivers need to be able to handle hardware which has been reset since all of the
470 suspend methods were called, for example by complete reinitialization.
471 This may be the hardest part, and the one most protected by NDA'd documents
472 and chip errata.  It's simplest if the hardware state hasn't changed since
473 the suspend was carried out, but that can only be guaranteed if the target
474 system sleep entered was suspend-to-idle.  For the other system sleep states
475 that may not be the case (and usually isn't for ACPI-defined system sleep
476 states, like S3).
477
478 Drivers must also be prepared to notice that the device has been removed
479 while the system was powered down, whenever that's physically possible.
480 PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
481 where common Linux platforms will see such removal.  Details of how drivers
482 will notice and handle such removals are currently bus-specific, and often
483 involve a separate thread.
484
485 These callbacks may return an error value, but the PM core will ignore such
486 errors since there's nothing it can do about them other than printing them in
487 the system log.
488
489
490 Entering Hibernation
491 --------------------
492
493 Hibernating the system is more complicated than putting it into sleep states,
494 because it involves creating and saving a system image.  Therefore there are
495 more phases for hibernation, with a different set of callbacks.  These phases
496 always run after tasks have been frozen and enough memory has been freed.
497
498 The general procedure for hibernation is to quiesce all devices ("freeze"),
499 create an image of the system memory while everything is stable, reactivate all
500 devices ("thaw"), write the image to permanent storage, and finally shut down
501 the system ("power off").  The phases used to accomplish this are: ``prepare``,
502 ``freeze``, ``freeze_late``, ``freeze_noirq``, ``thaw_noirq``, ``thaw_early``,
503 ``thaw``, ``complete``, ``prepare``, ``poweroff``, ``poweroff_late``,
504 ``poweroff_noirq``.
505
506     1.  The ``prepare`` phase is discussed in the "Entering System Suspend"
507         section above.
508
509     2.  The ``->freeze`` methods should quiesce the device so that it doesn't
510         generate IRQs or DMA, and they may need to save the values of device
511         registers.  However the device does not have to be put in a low-power
512         state, and to save time it's best not to do so.  Also, the device should
513         not be prepared to generate wakeup events.
514
515     3.  The ``freeze_late`` phase is analogous to the ``suspend_late`` phase
516         described earlier, except that the device should not be put into a
517         low-power state and should not be allowed to generate wakeup events.
518
519     4.  The ``freeze_noirq`` phase is analogous to the ``suspend_noirq`` phase
520         discussed earlier, except again that the device should not be put into
521         a low-power state and should not be allowed to generate wakeup events.
522
523 At this point the system image is created.  All devices should be inactive and
524 the contents of memory should remain undisturbed while this happens, so that the
525 image forms an atomic snapshot of the system state.
526
527     5.  The ``thaw_noirq`` phase is analogous to the ``resume_noirq`` phase
528         discussed earlier.  The main difference is that its methods can assume
529         the device is in the same state as at the end of the ``freeze_noirq``
530         phase.
531
532     6.  The ``thaw_early`` phase is analogous to the ``resume_early`` phase
533         described above.  Its methods should undo the actions of the preceding
534         ``freeze_late``, if necessary.
535
536     7.  The ``thaw`` phase is analogous to the ``resume`` phase discussed
537         earlier.  Its methods should bring the device back to an operating
538         state, so that it can be used for saving the image if necessary.
539
540     8.  The ``complete`` phase is discussed in the "Leaving System Suspend"
541         section above.
542
543 At this point the system image is saved, and the devices then need to be
544 prepared for the upcoming system shutdown.  This is much like suspending them
545 before putting the system into the suspend-to-idle, shallow or deep sleep state,
546 and the phases are similar.
547
548     9.  The ``prepare`` phase is discussed above.
549
550     10. The ``poweroff`` phase is analogous to the ``suspend`` phase.
551
552     11. The ``poweroff_late`` phase is analogous to the ``suspend_late`` phase.
553
554     12. The ``poweroff_noirq`` phase is analogous to the ``suspend_noirq`` phase.
555
556 The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
557 should do essentially the same things as the ``->suspend``, ``->suspend_late``
558 and ``->suspend_noirq`` callbacks, respectively.  The only notable difference is
559 that they need not store the device register values, because the registers
560 should already have been stored during the ``freeze``, ``freeze_late`` or
561 ``freeze_noirq`` phases.
562
563
564 Leaving Hibernation
565 -------------------
566
567 Resuming from hibernation is, again, more complicated than resuming from a sleep
568 state in which the contents of main memory are preserved, because it requires
569 a system image to be loaded into memory and the pre-hibernation memory contents
570 to be restored before control can be passed back to the image kernel.
571
572 Although in principle the image might be loaded into memory and the
573 pre-hibernation memory contents restored by the boot loader, in practice this
574 can't be done because boot loaders aren't smart enough and there is no
575 established protocol for passing the necessary information.  So instead, the
576 boot loader loads a fresh instance of the kernel, called "the restore kernel",
577 into memory and passes control to it in the usual way.  Then the restore kernel
578 reads the system image, restores the pre-hibernation memory contents, and passes
579 control to the image kernel.  Thus two different kernel instances are involved
580 in resuming from hibernation.  In fact, the restore kernel may be completely
581 different from the image kernel: a different configuration and even a different
582 version.  This has important consequences for device drivers and their
583 subsystems.
584
585 To be able to load the system image into memory, the restore kernel needs to
586 include at least a subset of device drivers allowing it to access the storage
587 medium containing the image, although it doesn't need to include all of the
588 drivers present in the image kernel.  After the image has been loaded, the
589 devices managed by the boot kernel need to be prepared for passing control back
590 to the image kernel.  This is very similar to the initial steps involved in
591 creating a system image, and it is accomplished in the same way, using
592 ``prepare``, ``freeze``, and ``freeze_noirq`` phases.  However, the devices
593 affected by these phases are only those having drivers in the restore kernel;
594 other devices will still be in whatever state the boot loader left them.
595
596 Should the restoration of the pre-hibernation memory contents fail, the restore
597 kernel would go through the "thawing" procedure described above, using the
598 ``thaw_noirq``, ``thaw_early``, ``thaw``, and ``complete`` phases, and then
599 continue running normally.  This happens only rarely.  Most often the
600 pre-hibernation memory contents are restored successfully and control is passed
601 to the image kernel, which then becomes responsible for bringing the system back
602 to the working state.
603
604 To achieve this, the image kernel must restore the devices' pre-hibernation
605 functionality.  The operation is much like waking up from a sleep state (with
606 the memory contents preserved), although it involves different phases:
607 ``restore_noirq``, ``restore_early``, ``restore``, ``complete``.
608
609     1.  The ``restore_noirq`` phase is analogous to the ``resume_noirq`` phase.
610
611     2.  The ``restore_early`` phase is analogous to the ``resume_early`` phase.
612
613     3.  The ``restore`` phase is analogous to the ``resume`` phase.
614
615     4.  The ``complete`` phase is discussed above.
616
617 The main difference from ``resume[_early|_noirq]`` is that
618 ``restore[_early|_noirq]`` must assume the device has been accessed and
619 reconfigured by the boot loader or the restore kernel.  Consequently, the state
620 of the device may be different from the state remembered from the ``freeze``,
621 ``freeze_late`` and ``freeze_noirq`` phases.  The device may even need to be
622 reset and completely re-initialized.  In many cases this difference doesn't
623 matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]``
624 method pointers can be set to the same routines.  Nevertheless, different
625 callback pointers are used in case there is a situation where it actually does
626 matter.
627
628
629 Power Management Notifiers
630 ==========================
631
632 There are some operations that cannot be carried out by the power management
633 callbacks discussed above, because the callbacks occur too late or too early.
634 To handle these cases, subsystems and device drivers may register power
635 management notifiers that are called before tasks are frozen and after they have
636 been thawed.  Generally speaking, the PM notifiers are suitable for performing
637 actions that either require user space to be available, or at least won't
638 interfere with user space.
639
640 For details refer to :doc:`notifiers`.
641
642
643 Device Low-Power (suspend) States
644 =================================
645
646 Device low-power states aren't standard.  One device might only handle
647 "on" and "off", while another might support a dozen different versions of
648 "on" (how many engines are active?), plus a state that gets back to "on"
649 faster than from a full "off".
650
651 Some buses define rules about what different suspend states mean.  PCI
652 gives one example: after the suspend sequence completes, a non-legacy
653 PCI device may not perform DMA or issue IRQs, and any wakeup events it
654 issues would be issued through the PME# bus signal.  Plus, there are
655 several PCI-standard device states, some of which are optional.
656
657 In contrast, integrated system-on-chip processors often use IRQs as the
658 wakeup event sources (so drivers would call :c:func:`enable_irq_wake`) and
659 might be able to treat DMA completion as a wakeup event (sometimes DMA can stay
660 active too, it'd only be the CPU and some peripherals that sleep).
661
662 Some details here may be platform-specific.  Systems may have devices that
663 can be fully active in certain sleep states, such as an LCD display that's
664 refreshed using DMA while most of the system is sleeping lightly ... and
665 its frame buffer might even be updated by a DSP or other non-Linux CPU while
666 the Linux control processor stays idle.
667
668 Moreover, the specific actions taken may depend on the target system state.
669 One target system state might allow a given device to be very operational;
670 another might require a hard shut down with re-initialization on resume.
671 And two different target systems might use the same device in different
672 ways; the aforementioned LCD might be active in one product's "standby",
673 but a different product using the same SOC might work differently.
674
675
676 Device Power Management Domains
677 ===============================
678
679 Sometimes devices share reference clocks or other power resources.  In those
680 cases it generally is not possible to put devices into low-power states
681 individually.  Instead, a set of devices sharing a power resource can be put
682 into a low-power state together at the same time by turning off the shared
683 power resource.  Of course, they also need to be put into the full-power state
684 together, by turning the shared power resource on.  A set of devices with this
685 property is often referred to as a power domain. A power domain may also be
686 nested inside another power domain. The nested domain is referred to as the
687 sub-domain of the parent domain.
688
689 Support for power domains is provided through the :c:member:`pm_domain` field of
690 |struct device|.  This field is a pointer to an object of type
691 |struct dev_pm_domain|, defined in :file:`include/linux/pm.h`, providing a set
692 of power management callbacks analogous to the subsystem-level and device driver
693 callbacks that are executed for the given device during all power transitions,
694 instead of the respective subsystem-level callbacks.  Specifically, if a
695 device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
696 from the object pointed to by it will be executed instead of its subsystem's
697 (e.g. bus type's) ``->suspend()`` callback and analogously for all of the
698 remaining callbacks.  In other words, power management domain callbacks, if
699 defined for the given device, always take precedence over the callbacks provided
700 by the device's subsystem (e.g. bus type).
701
702 The support for device power management domains is only relevant to platforms
703 needing to use the same device driver power management callbacks in many
704 different power domain configurations and wanting to avoid incorporating the
705 support for power domains into subsystem-level callbacks, for example by
706 modifying the platform bus type.  Other platforms need not implement it or take
707 it into account in any way.
708
709 Devices may be defined as IRQ-safe which indicates to the PM core that their
710 runtime PM callbacks may be invoked with disabled interrupts (see
711 :file:`Documentation/power/runtime_pm.txt` for more information).  If an
712 IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
713 disallowed, unless the domain itself is defined as IRQ-safe. However, it
714 makes sense to define a PM domain as IRQ-safe only if all the devices in it
715 are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime
716 PM of the parent is only allowed if the parent itself is IRQ-safe too with the
717 additional restriction that all child domains of an IRQ-safe parent must also
718 be IRQ-safe.
719
720
721 Runtime Power Management
722 ========================
723
724 Many devices are able to dynamically power down while the system is still
725 running. This feature is useful for devices that are not being used, and
726 can offer significant power savings on a running system.  These devices
727 often support a range of runtime power states, which might use names such
728 as "off", "sleep", "idle", "active", and so on.  Those states will in some
729 cases (like PCI) be partially constrained by the bus the device uses, and will
730 usually include hardware states that are also used in system sleep states.
731
732 A system-wide power transition can be started while some devices are in low
733 power states due to runtime power management.  The system sleep PM callbacks
734 should recognize such situations and react to them appropriately, but the
735 necessary actions are subsystem-specific.
736
737 In some cases the decision may be made at the subsystem level while in other
738 cases the device driver may be left to decide.  In some cases it may be
739 desirable to leave a suspended device in that state during a system-wide power
740 transition, but in other cases the device must be put back into the full-power
741 state temporarily, for example so that its system wakeup capability can be
742 disabled.  This all depends on the hardware and the design of the subsystem and
743 device driver in question.
744
745 If it is necessary to resume a device from runtime suspend during a system-wide
746 transition into a sleep state, that can be done by calling
747 :c:func:`pm_runtime_resume` for it from the ``->suspend`` callback (or its
748 couterpart for transitions related to hibernation) of either the device's driver
749 or a subsystem responsible for it (for example, a bus type or a PM domain).
750 That is guaranteed to work by the requirement that subsystems must not change
751 the state of devices (possibly except for resuming them from runtime suspend)
752 from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
753 invoking device drivers' ``->suspend`` callbacks (or equivalent).
754
755 During system-wide resume from a sleep state it's easiest to put devices into
756 the full-power state, as explained in :file:`Documentation/power/runtime_pm.txt`.
757 Refer to that document for more information regarding this particular issue as
758 well as for information on the device runtime power management framework in
759 general.