Lines Matching +full:loss +full:- +full:of +full:- +full:signal
1 .. SPDX-License-Identifier: GPL-2.0
10 :Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
17 Most of the code in Linux is device drivers, so most of the Linux power
18 management (PM) code is also driver-specific. Most drivers will do very
22 This writeup gives an overview of how drivers interact with system-wide
25 background for the domain-specific work you'd do with any specific driver.
31 Drivers will use one or both of these models to put devices into low-power
36 Drivers can enter low-power states as part of entering system-wide
37 low-power states like "suspend" (also known as "suspend-to-RAM"), or
39 "suspend-to-disk").
42 by implementing various role-specific suspend and resume methods to
44 them without loss of data.
47 leave the low-power state. This feature may be enabled or disabled
51 whole system enter low-power states more often.
55 Devices may also be put into low-power states while the system is
56 running, independently of other power management activity in principle.
57 However, devices are not generally independent of each other (for
58 example, a parent device cannot be suspended unless all of its child
60 device is on, it may be necessary to carry out some bus-specific
62 states at run time may require special handling during system-wide power
69 various role-specific suspend and resume methods, so that the hardware
70 is cleanly powered down and reactivated without data or service loss.
72 There's not a lot to be said about those low-power states except that they are
73 very system-specific, and often device-specific. Also, that if enough devices
74 have been put into low-power states (at runtime), the effect may be very similar
75 to entering some system-wide low-power state (system sleep) ... and that
84 Examples of hardware wakeup events include an alarm from a real time clock,
85 network wake-on-LAN packets, keyboard or mouse activity, and media insertion
93 management of devices they are concerned with. These interfaces cover both
98 ----------------------------------
101 device driver level, are implemented by defining and populating objects of type
102 struct dev_pm_ops defined in :file:`include/linux/pm.h`. The roles of the
105 management while the remaining ones are used during system-wide power
116 Subsystem-Level Methods
117 -----------------------
120 struct dev_pm_ops pointed to by the :c:member:`ops` member of
121 struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type,
122 struct device_type and struct class. They are mostly of interest to the
124 device type and device class drivers. They also are relevant to the writers of
130 write subsystem-level drivers; most driver code is a "device driver" that builds
131 on top of bus-specific framework code.
134 they are called in phases for every device, respecting the parent-child
139 -------------------------------------------
142 of system wakeup events (hardware signals that can force the system out of a
150 :c:member:`power.wakeup` field is a pointer to an object of type
152 its system wakeup mechanism and for notifying the PM core of system wakeup
153 events signaled by the device. This object is only present for wakeup-capable
157 Whether or not a device is capable of issuing wakeup events is a hardware
158 matter, and the kernel is responsible for keeping track of it. By contrast,
159 whether or not a wakeup-capable device should issue wakeup events is a policy
163 to signal system wakeup. This file is only present if the
169 majority of devices; the major exceptions are power buttons, keyboards, and
170 Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool.
187 low-power states to trigger specific interrupts to signal conditions in which
188 they should be put into the full-power state. Those interrupts may or may not
189 be used to signal system wakeup events, depending on the hardware design. On
196 --------------------------------------------
207 runtime power-managed by its driver. Writing "on" calls
209 power if it was in a low-power state, and preventing the
210 device from being runtime power-managed. User space can check the current value
211 of the :c:member:`runtime_auto` flag by reading that file.
213 The device's :c:member:`runtime_auto` flag has no effect on the handling of
214 system-wide power transitions. In particular, the device can (and in the
215 majority of cases should and will) be put into a low-power state during a
216 system-wide transition to a sleep state even though its :c:member:`runtime_auto`
228 system state. That's usually some version of "off", but the details are
229 system-specific. Also, wakeup-enabled devices will usually stay partly
232 When the system leaves that low-power state, the device's driver is asked to
234 always go together, and both are multi-phase operations.
241 More power-aware drivers might prepare the devices for triggering system wakeup
246 ------------------------
250 walked in a bottom-up order to suspend devices. A top-down order is
253 The ordering of the device hierarchy is defined by the order in which devices
259 In particular, this means that a device registration may fail if the parent of
261 device to suspend) or has already suspended, as well as after all of the other
267 ------------------------------
270 are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM")
271 sleep states and the hibernation state ("suspend-to-disk"). Each phase involves
280 defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``,
281 ``dev->class->pm`` or ``dev->driver->pm``). These callbacks are regarded by the
283 precedence over all of the other callbacks and, for example, type callbacks take
287 1. If ``dev->pm_domain`` is present, the PM core will choose the callback
288 provided by ``dev->pm_domain->ops`` for execution.
290 2. Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the
291 callback provided by ``dev->type->pm`` will be chosen for execution.
293 3. Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present,
294 the callback provided by ``dev->class->pm`` will be chosen for
297 4. Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the
298 callback provided by ``dev->bus->pm`` will be chosen for execution.
303 The PM domain, type, class and bus callbacks may in turn invoke device- or
304 driver-specific methods stored in ``dev->driver->pm``, but they don't have to do
308 execute the corresponding method from the ``dev->driver->pm`` set instead if
313 -----------------------
320 children of a device had been suspended if new children could be
323 suspend-related phases, during the ``prepare`` phase the device
324 hierarchy is traversed top-down.
326 After the ``->prepare`` callback method returns, no new children may be
329 should not put the device into a low-power state. Moreover, if the
330 device supports runtime power management, the ``->prepare`` callback
334 For devices supporting runtime power management, the return value of the
336 safely leave the device in runtime suspend (if runtime-suspended
337 already), provided that all of the device's descendants are also left in
339 number and that happens for all of the descendants of the device too,
340 and all of them (including the device itself) are runtime-suspended, the
342 ``suspend_noirq`` phases as well as all of the corresponding phases of
343 the subsequent device resume for all of these devices. In that case,
344 the ``->complete`` callback will be the next one invoked after the
345 ``->prepare`` callback and is entirely responsible for putting the
348 Note that this direct-complete procedure applies even if the device is
349 disabled for runtime PM; only the runtime-PM status matters. It follows
350 that if a device has system-sleep callbacks but does not support runtime
352 is because all such devices are initially set to runtime-suspended with
359 :c:func:`dev_pm_set_driver_flags` helper function.] If the first of
360 these flags is set, the PM core will not apply the direct-complete
362 of its ancestors. The second flag, when set, informs the middle layer
364 the return value of the ``->prepare`` callback provided by the driver
366 ``->prepare`` callback if the driver's one also has returned a positive
369 2. The ``->suspend`` methods should quiesce the device to stop it from
371 the appropriate low-power state, depending on the bus type the device is
375 ``->suspend`` methods provided by subsystems (bus types and PM domains
377 to the devices before their drivers' ``->suspend`` methods are called.
380 they must not update the state of the devices in any other way at that
382 suspend in their ``->suspend`` methods). In fact, the PM core prevents
385 the ``->prepare`` callback (and calling :c:func:`pm_runtime_put` after
386 issuing the ``->complete`` callback).
388 3. For a number of devices it is convenient to split suspend into the
395 the callback method is running. The ``->suspend_noirq`` methods should
396 save the values of the device's registers that weren't saved previously
397 and finally put the device into the appropriate low-power state.
399 The majority of subsystems and device drivers need not implement this
406 At the end of these phases, drivers should have stopped all I/O transactions
407 (DMA, IRQs), saved enough state that they can re-initialize or restore previous
408 state (as needed by the hardware), and placed the device into a low-power state.
411 runtime PM may already have performed some or all of these steps.]
417 and :c:func:`pci_enable_wake()` does something similar for the PCI PME signal.
419 If any of these callbacks returns an error, the system won't enter the desired
420 low-power state. Instead, the PM core will unwind its actions by resuming all
425 ----------------------
430 1. The ``->resume_noirq`` callback methods should perform any actions
432 generally means undoing the actions of the ``suspend_noirq`` phase. If
435 driver can recognize if the device is the source of incoming interrupts,
438 For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device
439 into the full-power state (D0 in the PCI terminology) and restores the
440 standard configuration registers of the device. Then it calls the
441 device driver's ``->pm.resume_noirq()`` method to perform device-specific
444 2. The ``->resume_early`` methods should prepare devices for the execution
445 of the resume methods. This generally involves undoing the actions of
448 3. The ``->resume`` methods should bring the device back to its operating
450 undoing the actions of the ``suspend`` phase.
452 4. The ``complete`` phase should undo the actions of the ``prepare`` phase.
453 For this reason, unlike the other resume-related phases, during the
454 ``complete`` phase the device hierarchy is traversed bottom-up.
457 soon as the ``->resume`` callbacks occur; it's not necessary to wait
460 Moreover, if the preceding ``->prepare`` callback returned a positive
462 whole system suspend and resume (its ``->suspend``, ``->suspend_late``,
463 ``->suspend_noirq``, ``->resume_noirq``,
464 ``->resume_early``, and ``->resume`` callbacks may have been
465 skipped). In that case, the ``->complete`` callback is entirely
469 the case, the ``->complete`` callback can consult the device's
471 ``->complete`` callback is being run then the direct-complete mechanism
475 At the end of these phases, drivers should be as functional as they were before
479 However, the details here may again be platform-specific. For example,
481 the end of resume might not be the one which preceded suspension.
482 That means availability of certain clocks or power supplies changed,
485 Drivers need to be able to handle hardware which has been reset since all of the
490 system sleep entered was suspend-to-idle. For the other system sleep states
491 that may not be the case (and usually isn't for ACPI-defined system sleep
496 PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
497 where common Linux platforms will see such removal. Details of how drivers
498 will notice and handle such removals are currently bus-specific, and often
507 --------------------
511 more phases for hibernation, with a different set of callbacks. These phases
515 create an image of the system memory while everything is stable, reactivate all
525 2. The ``->freeze`` methods should quiesce the device so that it doesn't
526 generate IRQs or DMA, and they may need to save the values of device
527 registers. However the device does not have to be put in a low-power
533 low-power state and should not be allowed to generate wakeup events.
537 a low-power state and should not be allowed to generate wakeup events.
540 the contents of memory should remain undisturbed while this happens, so that the
541 image forms an atomic snapshot of the system state.
545 the device is in the same state as at the end of the ``freeze_noirq``
549 described above. Its methods should undo the actions of the preceding
561 before putting the system into the suspend-to-idle, shallow or deep sleep state,
572 The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
573 should do essentially the same things as the ``->suspend``, ``->suspend_late``
574 and ``->suspend_noirq`` callbacks, respectively. A notable difference is
577 ``freeze_noirq`` phases. Also, on many machines the firmware will power-down
579 a low-power state.
583 -------------------
586 state in which the contents of main memory are preserved, because it requires
587 a system image to be loaded into memory and the pre-hibernation memory contents
591 pre-hibernation memory contents restored by the boot loader, in practice this
594 boot loader loads a fresh instance of the kernel, called "the restore kernel",
596 reads the system image, restores the pre-hibernation memory contents, and passes
604 include at least a subset of device drivers allowing it to access the storage
605 medium containing the image, although it doesn't need to include all of the
614 Should the restoration of the pre-hibernation memory contents fail, the restore
618 pre-hibernation memory contents are restored successfully and control is passed
622 To achieve this, the image kernel must restore the devices' pre-hibernation
638 of the device may be different from the state remembered from the ``freeze``,
640 reset and completely re-initialized. In many cases this difference doesn't
641 matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]``
658 For details refer to Documentation/driver-api/pm/notifiers.rst.
661 Device Low-Power (suspend) States
664 Device low-power states aren't standard. One device might only handle
665 "on" and "off", while another might support a dozen different versions of
670 gives one example: after the suspend sequence completes, a non-legacy
672 issues would be issued through the PME# bus signal. Plus, there are
673 several PCI-standard device states, some of which are optional.
675 In contrast, integrated system-on-chip processors often use IRQs as the
680 Some details here may be platform-specific. Systems may have devices that
682 refreshed using DMA while most of the system is sleeping lightly ... and
683 its frame buffer might even be updated by a DSP or other non-Linux CPU while
688 another might require a hard shut down with re-initialization on resume.
698 cases it generally is not possible to put devices into low-power states
699 individually. Instead, a set of devices sharing a power resource can be put
700 into a low-power state together at the same time by turning off the shared
701 power resource. Of course, they also need to be put into the full-power state
702 together, by turning the shared power resource on. A set of devices with this
705 sub-domain of the parent domain.
707 Support for power domains is provided through the :c:member:`pm_domain` field of
708 struct device. This field is a pointer to an object of type
710 of power management callbacks analogous to the subsystem-level and device driver
712 instead of the respective subsystem-level callbacks. Specifically, if a
713 device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
714 from the object pointed to by it will be executed instead of its subsystem's
715 (e.g. bus type's) ``->suspend()`` callback and analogously for all of the
723 support for power domains into subsystem-level callbacks, for example by
727 Devices may be defined as IRQ-safe which indicates to the PM core that their
730 IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
731 disallowed, unless the domain itself is defined as IRQ-safe. However, it
732 makes sense to define a PM domain as IRQ-safe only if all the devices in it
733 are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime
734 PM of the parent is only allowed if the parent itself is IRQ-safe too with the
735 additional restriction that all child domains of an IRQ-safe parent must also
736 be IRQ-safe.
745 often support a range of runtime power states, which might use names such
750 A system-wide power transition can be started while some devices are in low
753 necessary actions are subsystem-specific.
757 desirable to leave a suspended device in that state during a system-wide power
758 transition, but in other cases the device must be put back into the full-power
760 disabled. This all depends on the hardware and the design of the subsystem and
763 If it is necessary to resume a device from runtime suspend during a system-wide
765 :c:func:`pm_runtime_resume` from the ``->suspend`` callback (or the ``->freeze``
766 or ``->poweroff`` callback for transitions related to hibernation) of either the
768 However, subsystems must not otherwise change the runtime status of devices
769 from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
770 invoking device drivers' ``->suspend`` callbacks (or equivalent).
775 ------------------------------------------
778 suspend upfront in their ``->suspend`` callbacks, but that may not be really
779 necessary if the device's driver can cope with runtime-suspended devices.
781 :c:member:`power.driver_flags` at probe time, with the assistance of the
784 Setting that flag causes the PM core and middle-layer code
785 (bus types, PM domains etc.) to skip the ``->suspend_late`` and
786 ``->suspend_noirq`` callbacks provided by the driver if the device remains in
787 runtime suspend throughout those phases of the system-wide suspend (and
788 similarly for the "freeze" and "poweroff" parts of system hibernation).
791 be valid in general.] If the middle-layer system-wide PM callbacks are present
797 In addition, with ``DPM_FLAG_SMART_SUSPEND`` set, the driver's ``->thaw_noirq``
798 and ``->thaw_early`` callbacks are skipped in hibernation if the device remained
800 middle-layer callbacks are present for the device, they are responsible for
801 doing this, otherwise the PM core takes care of it.
805 --------------------------------------------
807 During system-wide resume from a sleep state it's easiest to put devices into
808 the full-power state, as explained in Documentation/power/runtime_pm.rst.
813 runtime suspend before the preceding system-wide suspend (or analogous)
817 indicate to the PM core and middle-layer code that they allow their "noirq" and
819 after system-wide PM transitions to the working state. Whether or not that is
820 the case generally depends on the state of the device before the given system
821 suspend-resume cycle and on the type of the system transition under way.
824 issued during the "restore" transition regardless of the flag settings,
828 In addition, a device is not allowed to remain in runtime suspend if any of its
833 "suspend" phase of suspend-type transitions. If the driver or the middle layer
836 clear :c:member:`power.may_skip_resume` in its ``->suspend``, ``->suspend_late``
837 or ``->suspend_noirq`` callback. [Note that the drivers setting
839 their ``->suspend`` callback in case the other two are skipped.]
849 "suspended" by the PM core. Otherwise, if the device was runtime-suspended
850 during the preceding system-wide suspend transition and its
853 ``DPM_FLAG_SMART_SUSPEND`` should not expect the runtime PM status of their
855 system-wide resume-type transitions.]
859 callbacks are skipped, its system-wide "noirq" and "early" resume callbacks, if
862 driver must be prepared to cope with the invocation of its system-wide resume
863 callbacks back-to-back with its ``->runtime_suspend`` one (without the
864 intervening ``->runtime_resume`` and system-wide suspend callbacks) and the
865 final state of the device must reflect the "active" runtime PM status in that
867 ``->suspend_late`` callback pointer points to the same function as its
868 ``->runtime_suspend`` one and its ``->resume_early`` callback pointer points to
869 the same function as the ``->runtime_resume`` one, while none of the other
870 system-wide suspend-resume callbacks of the driver are present, for example.]
873 system-wide "noirq" and "early" resume callbacks may be skipped while its "late"
875 of whether or not ``DPM_FLAG_SMART_SUSPEND`` is set). In that case, the driver
876 needs to be able to cope with the invocation of its ``->runtime_resume``
877 callback back-to-back with its "late" and "noirq" suspend ones. [For instance,
879 ``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same pair of suspend/resume callback
880 functions for runtime PM and system-wide suspend/resume.]