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