Lines Matching +full:low +full:- +full:power
1 .. SPDX-License-Identifier: GPL-2.0
15 Device Power Management Basics
18 :Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
25 Most of the code in Linux is device drivers, so most of the Linux power
26 management (PM) code is also driver-specific. Most drivers will do very
30 This writeup gives an overview of how drivers interact with system-wide
31 power management goals, emphasizing the models and interfaces that are
33 background for the domain-specific work you'd do with any specific driver.
36 Two Models for Device Power Management
39 Drivers will use one or both of these models to put devices into low-power
44 Drivers can enter low-power states as part of entering system-wide
45 low-power states like "suspend" (also known as "suspend-to-RAM"), or
47 "suspend-to-disk").
50 by implementing various role-specific suspend and resume methods to
51 cleanly power down hardware and software subsystems, then reactivate
55 leave the low-power state. This feature may be enabled or disabled
56 using the relevant :file:`/sys/devices/.../power/wakeup` file (for
58 for this purpose); enabling it may cost some power usage, but let the
59 whole system enter low-power states more often.
61 Runtime Power Management model:
63 Devices may also be put into low-power states while the system is
64 running, independently of other power management activity in principle.
68 device is on, it may be necessary to carry out some bus-specific
69 operations on the device for this purpose. Devices put into low power
70 states at run time may require special handling during system-wide power
75 the PM core are involved in runtime power management. As in the system
76 sleep power management case, they need to collaborate by implementing
77 various role-specific suspend and resume methods, so that the hardware
80 There's not a lot to be said about those low-power states except that they are
81 very system-specific, and often device-specific. Also, that if enough devices
82 have been put into low-power states (at runtime), the effect may be very similar
83 to entering some system-wide low-power state (system sleep) ... and that
85 into a state where even deeper power saving options are available.
93 network wake-on-LAN packets, keyboard or mouse activity, and media insertion
100 device class) and device drivers to allow them to participate in the power
102 system sleep and runtime power management.
105 Device Power Management Operations
106 ----------------------------------
108 Device power management operations, at the subsystem level as well as at the
112 sufficient to remember that the last three methods are specific to runtime power
113 management while the remaining ones are used during system-wide power
116 There also is a deprecated "old" or "legacy" interface for power management
119 sleep power management methods in a limited way. Therefore it is not described
124 Subsystem-Level Methods
125 -----------------------
134 bus types) don't provide all power management methods.
138 write subsystem-level drivers; most driver code is a "device driver" that builds
139 on top of bus-specific framework code.
142 they are called in phases for every device, respecting the parent-child
146 :file:`/sys/devices/.../power/wakeup` files
147 -------------------------------------------
155 The :c:member:`power.can_wakeup` flag just records whether the device (and its
158 :c:member:`power.wakeup` field is a pointer to an object of type
161 events signaled by the device. This object is only present for wakeup-capable
167 whether or not a wakeup-capable device should issue wakeup events is a policy
169 :file:`power/wakeup` file. User space can write the "enabled" or "disabled"
172 :c:member:`power.wakeup` object exists for the given device and is created (or
176 The initial value in the :file:`power/wakeup` file is "disabled" for the
177 majority of devices; the major exceptions are power buttons, keyboards, and
178 Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool.
184 :c:member:`power.wakeup` object exists and the corresponding :file:`power/wakeup`
193 wakeup" used by runtime power management, although it may be supported by the
195 low-power states to trigger specific interrupts to signal conditions in which
196 they should be put into the full-power state. Those interrupts may or may not
199 case, remote wakeup should always be enabled for runtime power management for
203 :file:`/sys/devices/.../power/control` files
204 --------------------------------------------
207 runtime power management. This flag, :c:member:`runtime_auto`, is initialized
209 or :c:func:`pm_runtime_forbid()`; the default is to allow runtime power
213 the device's :file:`power/control` sysfs file. Writing "auto" calls
215 runtime power-managed by its driver. Writing "on" calls
217 power if it was in a low-power state, and preventing the
218 device from being runtime power-managed. User space can check the current value
222 system-wide power transitions. In particular, the device can (and in the
223 majority of cases should and will) be put into a low-power state during a
224 system-wide transition to a sleep state even though its :c:member:`runtime_auto`
227 For more information about the runtime power management framework, refer to
228 :file:`Documentation/power/runtime_pm.rst`.
237 system-specific. Also, wakeup-enabled devices will usually stay partly
240 When the system leaves that low-power state, the device's driver is asked to
241 resume it by returning it to full power. The suspend and resume operations
242 always go together, and both are multi-phase operations.
249 More power-aware drivers might prepare the devices for triggering system wakeup
254 ------------------------
258 walked in a bottom-up order to suspend devices. A top-down order is
274 System Power Management Phases
275 ------------------------------
278 are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM")
279 sleep states and the hibernation state ("suspend-to-disk"). Each phase involves
288 defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``,
289 ``dev->class->pm`` or ``dev->driver->pm``). These callbacks are regarded by the
295 1. If ``dev->pm_domain`` is present, the PM core will choose the callback
296 provided by ``dev->pm_domain->ops`` for execution.
298 2. Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the
299 callback provided by ``dev->type->pm`` will be chosen for execution.
301 3. Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present,
302 the callback provided by ``dev->class->pm`` will be chosen for
305 4. Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the
306 callback provided by ``dev->bus->pm`` will be chosen for execution.
311 The PM domain, type, class and bus callbacks may in turn invoke device- or
312 driver-specific methods stored in ``dev->driver->pm``, but they don't have to do
316 execute the corresponding method from the ``dev->driver->pm`` set instead if
321 -----------------------
331 suspend-related phases, during the ``prepare`` phase the device
332 hierarchy is traversed top-down.
334 After the ``->prepare`` callback method returns, no new children may be
336 driver in some way for the upcoming system power transition, but it
337 should not put the device into a low-power state. Moreover, if the
338 device supports runtime power management, the ``->prepare`` callback
342 For devices supporting runtime power management, the return value of the
344 safely leave the device in runtime suspend (if runtime-suspended
348 and all of them (including the device itself) are runtime-suspended, the
352 the ``->complete`` callback will be invoked directly after the
353 ``->prepare`` callback and is entirely responsible for putting the
356 Note that this direct-complete procedure applies even if the device is
357 disabled for runtime PM; only the runtime-PM status matters. It follows
358 that if a device has system-sleep callbacks but does not support runtime
360 is because all such devices are initially set to runtime-suspended with
364 ``DPM_FLAG_NEVER_SKIP`` and ``DPM_FLAG_SMART_PREPARE`` driver power
368 these flags is set, the PM core will not apply the direct-complete
372 the return value of the ``->prepare`` callback provided by the driver
374 ``->prepare`` callback if the driver's one also has returned a positive
377 2. The ``->suspend`` methods should quiesce the device to stop it from
379 the appropriate low-power state, depending on the bus type the device is
382 However, for devices supporting runtime power management, the
383 ``->suspend`` methods provided by subsystems (bus types and PM domains
385 to the devices before their drivers' ``->suspend`` methods are called.
390 suspend in their ``->suspend`` methods).
395 runtime power management has been disabled for the device in question.
399 the callback method is running. The ``->suspend_noirq`` methods should
401 and finally put the device into the appropriate low-power state.
407 generated by some other device after its own device had been set to low
408 power.
411 (DMA, IRQs), saved enough state that they can re-initialize or restore previous
412 state (as needed by the hardware), and placed the device into a low-power state.
414 will also switch off power supplies or reduce voltages. [Drivers supporting
424 low-power state. Instead, the PM core will unwind its actions by resuming all
429 ----------------------
434 1. The ``->resume_noirq`` callback methods should perform any actions
442 For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device
443 into the full-power state (D0 in the PCI terminology) and restores the
445 device driver's ``->pm.resume_noirq()`` method to perform device-specific
448 2. The ``->resume_early`` methods should prepare devices for the execution
452 3. The ``->resume`` methods should bring the device back to its operating
457 For this reason, unlike the other resume-related phases, during the
458 ``complete`` phase the device hierarchy is traversed bottom-up.
461 soon as the ``->resume`` callbacks occur; it's not necessary to wait
464 Moreover, if the preceding ``->prepare`` callback returned a positive
469 skipped for it). In that case, the ``->complete`` callback is entirely
473 the case, the ``->complete`` callback can consult the device's
474 ``power.direct_complete`` flag. Namely, if that flag is set when the
475 ``->complete`` callback is being run, it has been called directly after
476 the preceding ``->prepare`` and special actions may be required
483 However, the details here may again be platform-specific. For example,
486 That means availability of certain clocks or power supplies changed,
494 system sleep entered was suspend-to-idle. For the other system sleep states
495 that may not be the case (and usually isn't for ACPI-defined system sleep
502 will notice and handle such removals are currently bus-specific, and often
511 --------------------
521 the system ("power off"). The phases used to accomplish this are: ``prepare``,
529 2. The ``->freeze`` methods should quiesce the device so that it doesn't
531 registers. However the device does not have to be put in a low-power
537 low-power state and should not be allowed to generate wakeup events.
541 a low-power state and should not be allowed to generate wakeup events.
565 before putting the system into the suspend-to-idle, shallow or deep sleep state,
576 The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
577 should do essentially the same things as the ``->suspend``, ``->suspend_late``
578 and ``->suspend_noirq`` callbacks, respectively. The only notable difference is
585 -------------------
589 a system image to be loaded into memory and the pre-hibernation memory contents
593 pre-hibernation memory contents restored by the boot loader, in practice this
598 reads the system image, restores the pre-hibernation memory contents, and passes
616 Should the restoration of the pre-hibernation memory contents fail, the restore
620 pre-hibernation memory contents are restored successfully and control is passed
624 To achieve this, the image kernel must restore the devices' pre-hibernation
642 reset and completely re-initialized. In many cases this difference doesn't
643 matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]``
649 Power Management Notifiers
652 There are some operations that cannot be carried out by the power management
654 To handle these cases, subsystems and device drivers may register power
663 Device Low-Power (suspend) States
666 Device low-power states aren't standard. One device might only handle
672 gives one example: after the suspend sequence completes, a non-legacy
675 several PCI-standard device states, some of which are optional.
677 In contrast, integrated system-on-chip processors often use IRQs as the
682 Some details here may be platform-specific. Systems may have devices that
685 its frame buffer might even be updated by a DSP or other non-Linux CPU while
690 another might require a hard shut down with re-initialization on resume.
696 Device Power Management Domains
699 Sometimes devices share reference clocks or other power resources. In those
700 cases it generally is not possible to put devices into low-power states
701 individually. Instead, a set of devices sharing a power resource can be put
702 into a low-power state together at the same time by turning off the shared
703 power resource. Of course, they also need to be put into the full-power state
704 together, by turning the shared power resource on. A set of devices with this
705 property is often referred to as a power domain. A power domain may also be
706 nested inside another power domain. The nested domain is referred to as the
707 sub-domain of the parent domain.
709 Support for power domains is provided through the :c:member:`pm_domain` field of
712 of power management callbacks analogous to the subsystem-level and device driver
713 callbacks that are executed for the given device during all power transitions,
714 instead of the respective subsystem-level callbacks. Specifically, if a
715 device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
717 (e.g. bus type's) ``->suspend()`` callback and analogously for all of the
718 remaining callbacks. In other words, power management domain callbacks, if
722 The support for device power management domains is only relevant to platforms
723 needing to use the same device driver power management callbacks in many
724 different power domain configurations and wanting to avoid incorporating the
725 support for power domains into subsystem-level callbacks, for example by
729 Devices may be defined as IRQ-safe which indicates to the PM core that their
731 :file:`Documentation/power/runtime_pm.rst` for more information). If an
732 IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
733 disallowed, unless the domain itself is defined as IRQ-safe. However, it
734 makes sense to define a PM domain as IRQ-safe only if all the devices in it
735 are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime
736 PM of the parent is only allowed if the parent itself is IRQ-safe too with the
737 additional restriction that all child domains of an IRQ-safe parent must also
738 be IRQ-safe.
741 Runtime Power Management
744 Many devices are able to dynamically power down while the system is still
746 can offer significant power savings on a running system. These devices
747 often support a range of runtime power states, which might use names such
752 A system-wide power transition can be started while some devices are in low
753 power states due to runtime power management. The system sleep PM callbacks
755 necessary actions are subsystem-specific.
759 desirable to leave a suspended device in that state during a system-wide power
760 transition, but in other cases the device must be put back into the full-power
765 If it is necessary to resume a device from runtime suspend during a system-wide
767 :c:func:`pm_runtime_resume` for it from the ``->suspend`` callback (or its
772 from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
773 invoking device drivers' ``->suspend`` callbacks (or equivalent).
776 suspend upfront in their ``->suspend`` callbacks, but that may not be really
777 necessary if the driver of the device can cope with runtime-suspended devices.
779 :c:member:`power.driver_flags` at the probe time, by passing it to the
780 :c:func:`dev_pm_set_driver_flags` helper. That also may cause middle-layer code
781 (bus types, PM domains etc.) to skip the ``->suspend_late`` and
782 ``->suspend_noirq`` callbacks provided by the driver if the device remains in
783 runtime suspend at the beginning of the ``suspend_late`` phase of system-wide
786 after that point until the system-wide transition is over (the PM core itself
787 does that for devices whose "noirq", "late" and "early" system-wide PM callbacks
788 are executed directly by it). If that happens, the driver's system-wide resume
789 callbacks, if present, may still be invoked during the subsequent system-wide
790 resume transition and the device's runtime power management status may be set
792 cope with the invocation of its system-wide resume callbacks back-to-back with
793 its ``->runtime_suspend`` one (without the intervening ``->runtime_resume`` and
797 During system-wide resume from a sleep state it's easiest to put devices into
798 the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
800 well as for information on the device runtime power management framework in
805 runtime suspend before the preceding system-wide suspend (or analogous)
807 indicate to the PM core (and middle-layer code) that they prefer the specific
809 skipping their system-wide resume callbacks for this reason. Whether or not the
811 given system suspend-resume cycle and on the type of the system transition under
816 The middle-layer code involved in the handling of the device is expected to
818 :c:member:`power.may_skip_resume` status bit which is checked by the PM core
819 during the "noirq" phase of the preceding system-wide suspend (or analogous)
823 (except for ``->complete``) will be skipped automatically by the PM core if the
827 directly by the PM core, all of the system-wide resume callbacks are skipped if