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>`
9 ==============================
10 Device Power Management Basics
11 ==============================
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>
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.
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.
30 Two Models for Device Power Management
31 ======================================
33 Drivers will use one or both of these models to put devices into low-power
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
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.
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.
55 Runtime Power Management model:
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).
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.
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.
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
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).
90 Interfaces for Entering System Sleep States
91 ===========================================
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.
99 Device Power Management Operations
100 ----------------------------------
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
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.
118 Subsystem-Level Methods
119 -----------------------
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.
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.
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.
140 :file:`/sys/devices/.../power/wakeup` files
141 -------------------------------------------
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`.
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()`.
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.
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).
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.
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.
197 :file:`/sys/devices/.../power/control` files
198 --------------------------------------------
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
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.
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`
221 For more information about the runtime power management framework, refer to
222 :file:`Documentation/power/runtime_pm.txt`.
225 Calling Drivers to Enter and Leave System Sleep States
226 ======================================================
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.
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.
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.
243 More power-aware drivers might prepare the devices for triggering system wakeup
247 Call Sequence Guarantees
248 ------------------------
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.
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.
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
268 System Power Management Phases
269 ------------------------------
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).
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:
289 1. If ``dev->pm_domain`` is present, the PM core will choose the callback
290 provided by ``dev->pm_domain->ops`` for execution.
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.
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
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.
302 This allows PM domains and device types to override callbacks provided by bus
303 types or device classes if necessary.
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
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
314 Entering System Suspend
315 -----------------------
317 When the system goes into the freeze, standby or memory sleep state,
318 the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``.
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.
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.
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.
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
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.
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).
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.
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.
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
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.]
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.
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.
408 Leaving System Suspend
409 ----------------------
411 When resuming from freeze, standby or memory sleep, the phases are:
412 ``resume_noirq``, ``resume_early``, ``resume``, ``complete``.
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.
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
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.
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.
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.
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.
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.
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
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.
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
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.
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
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.
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``,
506 1. The ``prepare`` phase is discussed in the "Entering System Suspend"
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.
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.
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.
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.
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``
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.
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.
540 8. The ``complete`` phase is discussed in the "Leaving System Suspend"
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.
548 9. The ``prepare`` phase is discussed above.
550 10. The ``poweroff`` phase is analogous to the ``suspend`` phase.
552 11. The ``poweroff_late`` phase is analogous to the ``suspend_late`` phase.
554 12. The ``poweroff_noirq`` phase is analogous to the ``suspend_noirq`` phase.
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.
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.
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
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.
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.
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``.
609 1. The ``restore_noirq`` phase is analogous to the ``resume_noirq`` phase.
611 2. The ``restore_early`` phase is analogous to the ``resume_early`` phase.
613 3. The ``restore`` phase is analogous to the ``resume`` phase.
615 4. The ``complete`` phase is discussed above.
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
629 Power Management Notifiers
630 ==========================
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.
640 For details refer to :doc:`notifiers`.
643 Device Low-Power (suspend) States
644 =================================
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".
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.
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).
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.
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.
676 Device Power Management Domains
677 ===============================
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.
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).
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.
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
721 Runtime Power Management
722 ========================
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.
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.
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.
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).
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