^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) .. include:: <isonum.txt>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) .. _driverapi_pm_devices:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Device Power Management Basics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) :Copyright: |copy| 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) :Copyright: |copy| 2010 Alan Stern <stern@rowland.harvard.edu>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) :Copyright: |copy| 2016 Intel Corporation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Most of the code in Linux is device drivers, so most of the Linux power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) management (PM) code is also driver-specific. Most drivers will do very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) little; others, especially for platforms with small batteries (like cell
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) phones), will do a lot.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) This writeup gives an overview of how drivers interact with system-wide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) power management goals, emphasizing the models and interfaces that are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) shared by everything that hooks up to the driver model core. Read it as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) background for the domain-specific work you'd do with any specific driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Two Models for Device Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) ======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Drivers will use one or both of these models to put devices into low-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) states:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) System Sleep model:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) Drivers can enter low-power states as part of entering system-wide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) low-power states like "suspend" (also known as "suspend-to-RAM"), or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) (mostly for systems with disks) "hibernation" (also known as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) "suspend-to-disk").
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) This is something that device, bus, and class drivers collaborate on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) by implementing various role-specific suspend and resume methods to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) cleanly power down hardware and software subsystems, then reactivate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) them without loss of data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Some drivers can manage hardware wakeup events, which make the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) leave the low-power state. This feature may be enabled or disabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) using the relevant :file:`/sys/devices/.../power/wakeup` file (for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) Ethernet drivers the ioctl interface used by ethtool may also be used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) for this purpose); enabling it may cost some power usage, but let the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) whole system enter low-power states more often.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) Runtime Power Management model:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) Devices may also be put into low-power states while the system is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) running, independently of other power management activity in principle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) However, devices are not generally independent of each other (for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) example, a parent device cannot be suspended unless all of its child
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) devices have been suspended). Moreover, depending on the bus type the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) device is on, it may be necessary to carry out some bus-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) operations on the device for this purpose. Devices put into low power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) states at run time may require special handling during system-wide power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) transitions (suspend or hibernation).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) For these reasons not only the device driver itself, but also the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) appropriate subsystem (bus type, device type or device class) driver and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) the PM core are involved in runtime power management. As in the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) sleep power management case, they need to collaborate by implementing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) various role-specific suspend and resume methods, so that the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) is cleanly powered down and reactivated without data or service loss.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) There's not a lot to be said about those low-power states except that they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) very system-specific, and often device-specific. Also, that if enough devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) have been put into low-power states (at runtime), the effect may be very similar
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) to entering some system-wide low-power state (system sleep) ... and that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) synergies exist, so that several drivers using runtime PM might put the system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) into a state where even deeper power saving options are available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) for wakeup events), no more data read or written, and requests from upstream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) drivers are no longer accepted. A given bus or platform may have different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) requirements though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Examples of hardware wakeup events include an alarm from a real time clock,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) network wake-on-LAN packets, keyboard or mouse activity, and media insertion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) or removal (for PCMCIA, MMC/SD, USB, and so on).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Interfaces for Entering System Sleep States
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) ===========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) There are programming interfaces provided for subsystems (bus type, device type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) device class) and device drivers to allow them to participate in the power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) management of devices they are concerned with. These interfaces cover both
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) system sleep and runtime power management.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) Device Power Management Operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Device power management operations, at the subsystem level as well as at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) device driver level, are implemented by defining and populating objects of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) struct dev_pm_ops defined in :file:`include/linux/pm.h`. The roles of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) methods included in it will be explained in what follows. For now, it should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) sufficient to remember that the last three methods are specific to runtime power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) management while the remaining ones are used during system-wide power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) transitions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) There also is a deprecated "old" or "legacy" interface for power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) operations available at least for some subsystems. This approach does not use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) struct dev_pm_ops objects and it is suitable only for implementing system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) sleep power management methods in a limited way. Therefore it is not described
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) in this document, so please refer directly to the source code for more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) information about it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Subsystem-Level Methods
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) The core methods to suspend and resume devices reside in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) struct dev_pm_ops pointed to by the :c:member:`ops` member of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) struct dev_pm_domain, or by the :c:member:`pm` member of struct bus_type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) struct device_type and struct class. They are mostly of interest to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) people writing infrastructure for platforms and buses, like PCI or USB, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) device type and device class drivers. They also are relevant to the writers of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) device drivers whose subsystems (PM domains, device types, device classes and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) bus types) don't provide all power management methods.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) Bus drivers implement these methods as appropriate for the hardware and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) drivers using it; PCI works differently from USB, and so on. Not many people
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) write subsystem-level drivers; most driver code is a "device driver" that builds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) on top of bus-specific framework code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) For more information on these driver calls, see the description later;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) they are called in phases for every device, respecting the parent-child
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) sequencing in the driver model tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) :file:`/sys/devices/.../power/wakeup` files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) -------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) All device objects in the driver model contain fields that control the handling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) of system wakeup events (hardware signals that can force the system out of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) sleep state). These fields are initialized by bus or device driver code using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) :c:func:`device_set_wakeup_capable()` and :c:func:`device_set_wakeup_enable()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) defined in :file:`include/linux/pm_wakeup.h`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) The :c:member:`power.can_wakeup` flag just records whether the device (and its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) driver) can physically support wakeup events. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) :c:func:`device_set_wakeup_capable()` routine affects this flag. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) :c:member:`power.wakeup` field is a pointer to an object of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) struct wakeup_source used for controlling whether or not the device should use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) its system wakeup mechanism and for notifying the PM core of system wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) events signaled by the device. This object is only present for wakeup-capable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) devices (i.e. devices whose :c:member:`can_wakeup` flags are set) and is created
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) (or removed) by :c:func:`device_set_wakeup_capable()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) Whether or not a device is capable of issuing wakeup events is a hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) matter, and the kernel is responsible for keeping track of it. By contrast,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) whether or not a wakeup-capable device should issue wakeup events is a policy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) decision, and it is managed by user space through a sysfs attribute: the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) :file:`power/wakeup` file. User space can write the "enabled" or "disabled"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) strings to it to indicate whether or not, respectively, the device is supposed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) to signal system wakeup. This file is only present if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) :c:member:`power.wakeup` object exists for the given device and is created (or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) removed) along with that object, by :c:func:`device_set_wakeup_capable()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) Reads from the file will return the corresponding string.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) The initial value in the :file:`power/wakeup` file is "disabled" for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) majority of devices; the major exceptions are power buttons, keyboards, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with ethtool.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) It should also default to "enabled" for devices that don't generate wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) requests on their own but merely forward wakeup requests from one bus to another
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) (like PCI Express ports).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) The :c:func:`device_may_wakeup()` routine returns true only if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) :c:member:`power.wakeup` object exists and the corresponding :file:`power/wakeup`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) file contains the "enabled" string. This information is used by subsystems,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) like the PCI bus type code, to see whether or not to enable the devices' wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) mechanisms. If device wakeup mechanisms are enabled or disabled directly by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) drivers, they also should use :c:func:`device_may_wakeup()` to decide what to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) during a system sleep transition. Device drivers, however, are not expected to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) call :c:func:`device_set_wakeup_enable()` directly in any case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) It ought to be noted that system wakeup is conceptually different from "remote
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) wakeup" used by runtime power management, although it may be supported by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) same physical mechanism. Remote wakeup is a feature allowing devices in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) low-power states to trigger specific interrupts to signal conditions in which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) they should be put into the full-power state. Those interrupts may or may not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) be used to signal system wakeup events, depending on the hardware design. On
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) some systems it is impossible to trigger them from system sleep states. In any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) case, remote wakeup should always be enabled for runtime power management for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) all devices and drivers that support it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) :file:`/sys/devices/.../power/control` files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Each device in the driver model has a flag to control whether it is subject to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) runtime power management. This flag, :c:member:`runtime_auto`, is initialized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) by the bus type (or generally subsystem) code using :c:func:`pm_runtime_allow()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) or :c:func:`pm_runtime_forbid()`; the default is to allow runtime power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) management.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) The setting can be adjusted by user space by writing either "on" or "auto" to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) the device's :file:`power/control` sysfs file. Writing "auto" calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) :c:func:`pm_runtime_allow()`, setting the flag and allowing the device to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) runtime power-managed by its driver. Writing "on" calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) :c:func:`pm_runtime_forbid()`, clearing the flag, returning the device to full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) power if it was in a low-power state, and preventing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) device from being runtime power-managed. User space can check the current value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) of the :c:member:`runtime_auto` flag by reading that file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) The device's :c:member:`runtime_auto` flag has no effect on the handling of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) system-wide power transitions. In particular, the device can (and in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) majority of cases should and will) be put into a low-power state during a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) system-wide transition to a sleep state even though its :c:member:`runtime_auto`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) flag is clear.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) For more information about the runtime power management framework, refer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) :file:`Documentation/power/runtime_pm.rst`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) Calling Drivers to Enter and Leave System Sleep States
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) ======================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) When the system goes into a sleep state, each device's driver is asked to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) suspend the device by putting it into a state compatible with the target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) system state. That's usually some version of "off", but the details are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) system-specific. Also, wakeup-enabled devices will usually stay partly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) functional in order to wake the system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) When the system leaves that low-power state, the device's driver is asked to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) resume it by returning it to full power. The suspend and resume operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) always go together, and both are multi-phase operations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) For simple drivers, suspend might quiesce the device using class code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) and then turn its hardware as "off" as possible during suspend_noirq. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) matching resume calls would then completely reinitialize the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) before reactivating its class I/O queues.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) More power-aware drivers might prepare the devices for triggering system wakeup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) Call Sequence Guarantees
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) To ensure that bridges and similar links needing to talk to a device are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) available when the device is suspended or resumed, the device hierarchy is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) walked in a bottom-up order to suspend devices. A top-down order is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) used to resume those devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) The ordering of the device hierarchy is defined by the order in which devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) get registered: a child can never be registered, probed or resumed before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) its parent; and can't be removed or suspended after that parent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) The policy is that the device hierarchy should match hardware bus topology.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) [Or at least the control bus, for devices which use multiple busses.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) In particular, this means that a device registration may fail if the parent of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) the device is suspending (i.e. has been chosen by the PM core as the next
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) device to suspend) or has already suspended, as well as after all of the other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) devices have been suspended. Device drivers must be prepared to cope with such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) situations.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) System Power Management Phases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) Suspending or resuming the system is done in several phases. Different phases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) are used for suspend-to-idle, shallow (standby), and deep ("suspend-to-RAM")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) sleep states and the hibernation state ("suspend-to-disk"). Each phase involves
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) executing callbacks for every device before the next phase begins. Not all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) buses or classes support all these callbacks and not all drivers use all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) callbacks. The various phases always run after tasks have been frozen and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) before they are unfrozen. Furthermore, the ``*_noirq`` phases run at a time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) when IRQ handlers have been disabled (except for those marked with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) IRQF_NO_SUSPEND flag).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) All phases use PM domain, bus, type, class or driver callbacks (that is, methods
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) defined in ``dev->pm_domain->ops``, ``dev->bus->pm``, ``dev->type->pm``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) ``dev->class->pm`` or ``dev->driver->pm``). These callbacks are regarded by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) PM core as mutually exclusive. Moreover, PM domain callbacks always take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) precedence over all of the other callbacks and, for example, type callbacks take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) precedence over bus, class and driver callbacks. To be precise, the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) rules are used to determine which callback to execute in the given phase:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 1. If ``dev->pm_domain`` is present, the PM core will choose the callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) provided by ``dev->pm_domain->ops`` for execution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) 2. Otherwise, if both ``dev->type`` and ``dev->type->pm`` are present, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) callback provided by ``dev->type->pm`` will be chosen for execution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) 3. Otherwise, if both ``dev->class`` and ``dev->class->pm`` are present,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) the callback provided by ``dev->class->pm`` will be chosen for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) execution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) 4. Otherwise, if both ``dev->bus`` and ``dev->bus->pm`` are present, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) callback provided by ``dev->bus->pm`` will be chosen for execution.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) This allows PM domains and device types to override callbacks provided by bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) types or device classes if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) The PM domain, type, class and bus callbacks may in turn invoke device- or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) driver-specific methods stored in ``dev->driver->pm``, but they don't have to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) that.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) If the subsystem callback chosen for execution is not present, the PM core will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) execute the corresponding method from the ``dev->driver->pm`` set instead if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) there is one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) Entering System Suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) When the system goes into the freeze, standby or memory sleep state,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) the phases are: ``prepare``, ``suspend``, ``suspend_late``, ``suspend_noirq``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) 1. The ``prepare`` phase is meant to prevent races by preventing new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) devices from being registered; the PM core would never know that all the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) children of a device had been suspended if new children could be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) registered at will. [By contrast, from the PM core's perspective,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) devices may be unregistered at any time.] Unlike the other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) suspend-related phases, during the ``prepare`` phase the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) hierarchy is traversed top-down.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) After the ``->prepare`` callback method returns, no new children may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) registered below the device. The method may also prepare the device or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) driver in some way for the upcoming system power transition, but it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) should not put the device into a low-power state. Moreover, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) device supports runtime power management, the ``->prepare`` callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) method must not update its state in case it is necessary to resume it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) from runtime suspend later on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) For devices supporting runtime power management, the return value of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) prepare callback can be used to indicate to the PM core that it may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) safely leave the device in runtime suspend (if runtime-suspended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) already), provided that all of the device's descendants are also left in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) runtime suspend. Namely, if the prepare callback returns a positive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) number and that happens for all of the descendants of the device too,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) and all of them (including the device itself) are runtime-suspended, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) PM core will skip the ``suspend``, ``suspend_late`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) ``suspend_noirq`` phases as well as all of the corresponding phases of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) the subsequent device resume for all of these devices. In that case,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) the ``->complete`` callback will be the next one invoked after the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) ``->prepare`` callback and is entirely responsible for putting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) device into a consistent state as appropriate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) Note that this direct-complete procedure applies even if the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) disabled for runtime PM; only the runtime-PM status matters. It follows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) that if a device has system-sleep callbacks but does not support runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) PM, then its prepare callback must never return a positive value. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) is because all such devices are initially set to runtime-suspended with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) runtime PM disabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) This feature also can be controlled by device drivers by using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) ``DPM_FLAG_NO_DIRECT_COMPLETE`` and ``DPM_FLAG_SMART_PREPARE`` driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) power management flags. [Typically, they are set at the time the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) is probed against the device in question by passing them to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) :c:func:`dev_pm_set_driver_flags` helper function.] If the first of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) these flags is set, the PM core will not apply the direct-complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) procedure described above to the given device and, consequenty, to any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) of its ancestors. The second flag, when set, informs the middle layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) code (bus types, device types, PM domains, classes) that it should take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) the return value of the ``->prepare`` callback provided by the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) into account and it may only return a positive value from its own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) ``->prepare`` callback if the driver's one also has returned a positive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) 2. The ``->suspend`` methods should quiesce the device to stop it from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) performing I/O. They also may save the device registers and put it into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) the appropriate low-power state, depending on the bus type the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) on, and they may enable wakeup events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) However, for devices supporting runtime power management, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) ``->suspend`` methods provided by subsystems (bus types and PM domains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) in particular) must follow an additional rule regarding what can be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) to the devices before their drivers' ``->suspend`` methods are called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) Namely, they may resume the devices from runtime suspend by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) calling :c:func:`pm_runtime_resume` for them, if that is necessary, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) they must not update the state of the devices in any other way at that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) time (in case the drivers need to resume the devices from runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) suspend in their ``->suspend`` methods). In fact, the PM core prevents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) subsystems or drivers from putting devices into runtime suspend at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) these times by calling :c:func:`pm_runtime_get_noresume` before issuing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) the ``->prepare`` callback (and calling :c:func:`pm_runtime_put` after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) issuing the ``->complete`` callback).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) 3. For a number of devices it is convenient to split suspend into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) "quiesce device" and "save device state" phases, in which cases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) ``suspend_late`` is meant to do the latter. It is always executed after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) runtime power management has been disabled for the device in question.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) 4. The ``suspend_noirq`` phase occurs after IRQ handlers have been disabled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) which means that the driver's interrupt handler will not be called while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) the callback method is running. The ``->suspend_noirq`` methods should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) save the values of the device's registers that weren't saved previously
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) and finally put the device into the appropriate low-power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) The majority of subsystems and device drivers need not implement this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) callback. However, bus types allowing devices to share interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) vectors, like PCI, generally need it; otherwise a driver might encounter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) an error during the suspend phase by fielding a shared interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) generated by some other device after its own device had been set to low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) power.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) At the end of these phases, drivers should have stopped all I/O transactions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) (DMA, IRQs), saved enough state that they can re-initialize or restore previous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) state (as needed by the hardware), and placed the device into a low-power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) On many platforms they will gate off one or more clock sources; sometimes they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) will also switch off power supplies or reduce voltages. [Drivers supporting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) runtime PM may already have performed some or all of these steps.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) If :c:func:`device_may_wakeup()` returns ``true``, the device should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) prepared for generating hardware wakeup signals to trigger a system wakeup event
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) when the system is in the sleep state. For example, :c:func:`enable_irq_wake()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) might identify GPIO signals hooked up to a switch or other external hardware,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) and :c:func:`pci_enable_wake()` does something similar for the PCI PME signal.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) If any of these callbacks returns an error, the system won't enter the desired
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) low-power state. Instead, the PM core will unwind its actions by resuming all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421) the devices that were suspended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) Leaving System Suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) When resuming from freeze, standby or memory sleep, the phases are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) ``resume_noirq``, ``resume_early``, ``resume``, ``complete``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) 1. The ``->resume_noirq`` callback methods should perform any actions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) needed before the driver's interrupt handlers are invoked. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) generally means undoing the actions of the ``suspend_noirq`` phase. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) the bus type permits devices to share interrupt vectors, like PCI, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434) method should bring the device and its driver into a state in which the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) driver can recognize if the device is the source of incoming interrupts,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) if any, and handle them correctly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) For example, the PCI bus type's ``->pm.resume_noirq()`` puts the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) into the full-power state (D0 in the PCI terminology) and restores the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) standard configuration registers of the device. Then it calls the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441) device driver's ``->pm.resume_noirq()`` method to perform device-specific
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) actions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) 2. The ``->resume_early`` methods should prepare devices for the execution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) of the resume methods. This generally involves undoing the actions of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) the preceding ``suspend_late`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) 3. The ``->resume`` methods should bring the device back to its operating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) state, so that it can perform normal I/O. This generally involves
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) undoing the actions of the ``suspend`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) 4. The ``complete`` phase should undo the actions of the ``prepare`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) For this reason, unlike the other resume-related phases, during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) ``complete`` phase the device hierarchy is traversed bottom-up.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) Note, however, that new children may be registered below the device as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) soon as the ``->resume`` callbacks occur; it's not necessary to wait
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) until the ``complete`` phase runs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) Moreover, if the preceding ``->prepare`` callback returned a positive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461) number, the device may have been left in runtime suspend throughout the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) whole system suspend and resume (its ``->suspend``, ``->suspend_late``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) ``->suspend_noirq``, ``->resume_noirq``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) ``->resume_early``, and ``->resume`` callbacks may have been
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) skipped). In that case, the ``->complete`` callback is entirely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) responsible for putting the device into a consistent state after system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) suspend if necessary. [For example, it may need to queue up a runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) resume request for the device for this purpose.] To check if that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) the case, the ``->complete`` callback can consult the device's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) ``power.direct_complete`` flag. If that flag is set when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) ``->complete`` callback is being run then the direct-complete mechanism
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) was used, and special actions may be required to make the device work
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) correctly afterward.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) At the end of these phases, drivers should be as functional as they were before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) gated on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) However, the details here may again be platform-specific. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) some systems support multiple "run" states, and the mode in effect at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) the end of resume might not be the one which preceded suspension.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) That means availability of certain clocks or power supplies changed,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) which could easily affect how a driver works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) Drivers need to be able to handle hardware which has been reset since all of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) suspend methods were called, for example by complete reinitialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) This may be the hardest part, and the one most protected by NDA'd documents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) and chip errata. It's simplest if the hardware state hasn't changed since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489) the suspend was carried out, but that can only be guaranteed if the target
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) system sleep entered was suspend-to-idle. For the other system sleep states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) that may not be the case (and usually isn't for ACPI-defined system sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) states, like S3).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) Drivers must also be prepared to notice that the device has been removed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) while the system was powered down, whenever that's physically possible.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) where common Linux platforms will see such removal. Details of how drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) will notice and handle such removals are currently bus-specific, and often
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) involve a separate thread.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) These callbacks may return an error value, but the PM core will ignore such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) errors since there's nothing it can do about them other than printing them in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) the system log.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) Entering Hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) Hibernating the system is more complicated than putting it into sleep states,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) because it involves creating and saving a system image. Therefore there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) more phases for hibernation, with a different set of callbacks. These phases
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) always run after tasks have been frozen and enough memory has been freed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) The general procedure for hibernation is to quiesce all devices ("freeze"),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) create an image of the system memory while everything is stable, reactivate all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516) devices ("thaw"), write the image to permanent storage, and finally shut down
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) the system ("power off"). The phases used to accomplish this are: ``prepare``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) ``freeze``, ``freeze_late``, ``freeze_noirq``, ``thaw_noirq``, ``thaw_early``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) ``thaw``, ``complete``, ``prepare``, ``poweroff``, ``poweroff_late``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520) ``poweroff_noirq``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) 1. The ``prepare`` phase is discussed in the "Entering System Suspend"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) section above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) 2. The ``->freeze`` methods should quiesce the device so that it doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) generate IRQs or DMA, and they may need to save the values of device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) registers. However the device does not have to be put in a low-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) state, and to save time it's best not to do so. Also, the device should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) not be prepared to generate wakeup events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) 3. The ``freeze_late`` phase is analogous to the ``suspend_late`` phase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) described earlier, except that the device should not be put into a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) low-power state and should not be allowed to generate wakeup events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535) 4. The ``freeze_noirq`` phase is analogous to the ``suspend_noirq`` phase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) discussed earlier, except again that the device should not be put into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) a low-power state and should not be allowed to generate wakeup events.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) At this point the system image is created. All devices should be inactive and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) the contents of memory should remain undisturbed while this happens, so that the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) image forms an atomic snapshot of the system state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) 5. The ``thaw_noirq`` phase is analogous to the ``resume_noirq`` phase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) discussed earlier. The main difference is that its methods can assume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) the device is in the same state as at the end of the ``freeze_noirq``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) 6. The ``thaw_early`` phase is analogous to the ``resume_early`` phase
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) described above. Its methods should undo the actions of the preceding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) ``freeze_late``, if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) 7. The ``thaw`` phase is analogous to the ``resume`` phase discussed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) earlier. Its methods should bring the device back to an operating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) state, so that it can be used for saving the image if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) 8. The ``complete`` phase is discussed in the "Leaving System Suspend"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) section above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) At this point the system image is saved, and the devices then need to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) prepared for the upcoming system shutdown. This is much like suspending them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) before putting the system into the suspend-to-idle, shallow or deep sleep state,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562) and the phases are similar.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) 9. The ``prepare`` phase is discussed above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) 10. The ``poweroff`` phase is analogous to the ``suspend`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568) 11. The ``poweroff_late`` phase is analogous to the ``suspend_late`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) 12. The ``poweroff_noirq`` phase is analogous to the ``suspend_noirq`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) The ``->poweroff``, ``->poweroff_late`` and ``->poweroff_noirq`` callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) should do essentially the same things as the ``->suspend``, ``->suspend_late``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) and ``->suspend_noirq`` callbacks, respectively. A notable difference is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) that they need not store the device register values, because the registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) should already have been stored during the ``freeze``, ``freeze_late`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) ``freeze_noirq`` phases. Also, on many machines the firmware will power-down
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) the entire system, so it is not necessary for the callback to put the device in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579) a low-power state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) Leaving Hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) Resuming from hibernation is, again, more complicated than resuming from a sleep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) state in which the contents of main memory are preserved, because it requires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) a system image to be loaded into memory and the pre-hibernation memory contents
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588) to be restored before control can be passed back to the image kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) Although in principle the image might be loaded into memory and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) pre-hibernation memory contents restored by the boot loader, in practice this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) can't be done because boot loaders aren't smart enough and there is no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593) established protocol for passing the necessary information. So instead, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) boot loader loads a fresh instance of the kernel, called "the restore kernel",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) into memory and passes control to it in the usual way. Then the restore kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) reads the system image, restores the pre-hibernation memory contents, and passes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) control to the image kernel. Thus two different kernel instances are involved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598) in resuming from hibernation. In fact, the restore kernel may be completely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) different from the image kernel: a different configuration and even a different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) version. This has important consequences for device drivers and their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) subsystems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603) To be able to load the system image into memory, the restore kernel needs to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) include at least a subset of device drivers allowing it to access the storage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) medium containing the image, although it doesn't need to include all of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606) drivers present in the image kernel. After the image has been loaded, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) devices managed by the boot kernel need to be prepared for passing control back
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) to the image kernel. This is very similar to the initial steps involved in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609) creating a system image, and it is accomplished in the same way, using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) ``prepare``, ``freeze``, and ``freeze_noirq`` phases. However, the devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611) affected by these phases are only those having drivers in the restore kernel;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) other devices will still be in whatever state the boot loader left them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) Should the restoration of the pre-hibernation memory contents fail, the restore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615) kernel would go through the "thawing" procedure described above, using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616) ``thaw_noirq``, ``thaw_early``, ``thaw``, and ``complete`` phases, and then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) continue running normally. This happens only rarely. Most often the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618) pre-hibernation memory contents are restored successfully and control is passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) to the image kernel, which then becomes responsible for bringing the system back
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) to the working state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) To achieve this, the image kernel must restore the devices' pre-hibernation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) functionality. The operation is much like waking up from a sleep state (with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624) the memory contents preserved), although it involves different phases:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) ``restore_noirq``, ``restore_early``, ``restore``, ``complete``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) 1. The ``restore_noirq`` phase is analogous to the ``resume_noirq`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629) 2. The ``restore_early`` phase is analogous to the ``resume_early`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631) 3. The ``restore`` phase is analogous to the ``resume`` phase.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633) 4. The ``complete`` phase is discussed above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635) The main difference from ``resume[_early|_noirq]`` is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) ``restore[_early|_noirq]`` must assume the device has been accessed and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637) reconfigured by the boot loader or the restore kernel. Consequently, the state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) of the device may be different from the state remembered from the ``freeze``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) ``freeze_late`` and ``freeze_noirq`` phases. The device may even need to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640) reset and completely re-initialized. In many cases this difference doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) matter, so the ``->resume[_early|_noirq]`` and ``->restore[_early|_norq]``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) method pointers can be set to the same routines. Nevertheless, different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643) callback pointers are used in case there is a situation where it actually does
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) matter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) Power Management Notifiers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) There are some operations that cannot be carried out by the power management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) callbacks discussed above, because the callbacks occur too late or too early.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) To handle these cases, subsystems and device drivers may register power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) management notifiers that are called before tasks are frozen and after they have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) been thawed. Generally speaking, the PM notifiers are suitable for performing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655) actions that either require user space to be available, or at least won't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) interfere with user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) For details refer to :doc:`notifiers`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) Device Low-Power (suspend) States
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664) Device low-power states aren't standard. One device might only handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665) "on" and "off", while another might support a dozen different versions of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) "on" (how many engines are active?), plus a state that gets back to "on"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667) faster than from a full "off".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669) Some buses define rules about what different suspend states mean. PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) gives one example: after the suspend sequence completes, a non-legacy
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671) PCI device may not perform DMA or issue IRQs, and any wakeup events it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) issues would be issued through the PME# bus signal. Plus, there are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) several PCI-standard device states, some of which are optional.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) In contrast, integrated system-on-chip processors often use IRQs as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676) wakeup event sources (so drivers would call :c:func:`enable_irq_wake`) and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) might be able to treat DMA completion as a wakeup event (sometimes DMA can stay
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) active too, it'd only be the CPU and some peripherals that sleep).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) Some details here may be platform-specific. Systems may have devices that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) can be fully active in certain sleep states, such as an LCD display that's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682) refreshed using DMA while most of the system is sleeping lightly ... and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) its frame buffer might even be updated by a DSP or other non-Linux CPU while
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) the Linux control processor stays idle.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) Moreover, the specific actions taken may depend on the target system state.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687) One target system state might allow a given device to be very operational;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) another might require a hard shut down with re-initialization on resume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) And two different target systems might use the same device in different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) ways; the aforementioned LCD might be active in one product's "standby",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) but a different product using the same SOC might work differently.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694) Device Power Management Domains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) Sometimes devices share reference clocks or other power resources. In those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) cases it generally is not possible to put devices into low-power states
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) individually. Instead, a set of devices sharing a power resource can be put
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700) into a low-power state together at the same time by turning off the shared
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701) power resource. Of course, they also need to be put into the full-power state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) together, by turning the shared power resource on. A set of devices with this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) property is often referred to as a power domain. A power domain may also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704) nested inside another power domain. The nested domain is referred to as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) sub-domain of the parent domain.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) Support for power domains is provided through the :c:member:`pm_domain` field of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) struct device. This field is a pointer to an object of type
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) struct dev_pm_domain, defined in :file:`include/linux/pm.h`, providing a set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) of power management callbacks analogous to the subsystem-level and device driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711) callbacks that are executed for the given device during all power transitions,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) instead of the respective subsystem-level callbacks. Specifically, if a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) device's :c:member:`pm_domain` pointer is not NULL, the ``->suspend()`` callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) from the object pointed to by it will be executed instead of its subsystem's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715) (e.g. bus type's) ``->suspend()`` callback and analogously for all of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) remaining callbacks. In other words, power management domain callbacks, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) defined for the given device, always take precedence over the callbacks provided
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) by the device's subsystem (e.g. bus type).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) The support for device power management domains is only relevant to platforms
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) needing to use the same device driver power management callbacks in many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722) different power domain configurations and wanting to avoid incorporating the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) support for power domains into subsystem-level callbacks, for example by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) modifying the platform bus type. Other platforms need not implement it or take
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725) it into account in any way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) Devices may be defined as IRQ-safe which indicates to the PM core that their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728) runtime PM callbacks may be invoked with disabled interrupts (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) :file:`Documentation/power/runtime_pm.rst` for more information). If an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730) IRQ-safe device belongs to a PM domain, the runtime PM of the domain will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) disallowed, unless the domain itself is defined as IRQ-safe. However, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) makes sense to define a PM domain as IRQ-safe only if all the devices in it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) are IRQ-safe. Moreover, if an IRQ-safe domain has a parent domain, the runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734) PM of the parent is only allowed if the parent itself is IRQ-safe too with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) additional restriction that all child domains of an IRQ-safe parent must also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) be IRQ-safe.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) Runtime Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) Many devices are able to dynamically power down while the system is still
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743) running. This feature is useful for devices that are not being used, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) can offer significant power savings on a running system. These devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) often support a range of runtime power states, which might use names such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) as "off", "sleep", "idle", "active", and so on. Those states will in some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) cases (like PCI) be partially constrained by the bus the device uses, and will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) usually include hardware states that are also used in system sleep states.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) A system-wide power transition can be started while some devices are in low
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) power states due to runtime power management. The system sleep PM callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) should recognize such situations and react to them appropriately, but the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) necessary actions are subsystem-specific.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755) In some cases the decision may be made at the subsystem level while in other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) cases the device driver may be left to decide. In some cases it may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) desirable to leave a suspended device in that state during a system-wide power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) transition, but in other cases the device must be put back into the full-power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) state temporarily, for example so that its system wakeup capability can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) disabled. This all depends on the hardware and the design of the subsystem and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) device driver in question.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) If it is necessary to resume a device from runtime suspend during a system-wide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) transition into a sleep state, that can be done by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) :c:func:`pm_runtime_resume` from the ``->suspend`` callback (or the ``->freeze``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766) or ``->poweroff`` callback for transitions related to hibernation) of either the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) device's driver or its subsystem (for example, a bus type or a PM domain).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768) However, subsystems must not otherwise change the runtime status of devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) from their ``->prepare`` and ``->suspend`` callbacks (or equivalent) *before*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) invoking device drivers' ``->suspend`` callbacks (or equivalent).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) .. _smart_suspend_flag:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) The ``DPM_FLAG_SMART_SUSPEND`` Driver Flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) Some bus types and PM domains have a policy to resume all devices from runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) suspend upfront in their ``->suspend`` callbacks, but that may not be really
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) necessary if the device's driver can cope with runtime-suspended devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780) The driver can indicate this by setting ``DPM_FLAG_SMART_SUSPEND`` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) :c:member:`power.driver_flags` at probe time, with the assistance of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) :c:func:`dev_pm_set_driver_flags` helper routine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) Setting that flag causes the PM core and middle-layer code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) (bus types, PM domains etc.) to skip the ``->suspend_late`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786) ``->suspend_noirq`` callbacks provided by the driver if the device remains in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) runtime suspend throughout those phases of the system-wide suspend (and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) similarly for the "freeze" and "poweroff" parts of system hibernation).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) [Otherwise the same driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) callback might be executed twice in a row for the same device, which would not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791) be valid in general.] If the middle-layer system-wide PM callbacks are present
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) for the device then they are responsible for skipping these driver callbacks;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) if not then the PM core skips them. The subsystem callback routines can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) determine whether they need to skip the driver callbacks by testing the return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) value from the :c:func:`dev_pm_skip_suspend` helper function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) In addition, with ``DPM_FLAG_SMART_SUSPEND`` set, the driver's ``->thaw_noirq``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) and ``->thaw_early`` callbacks are skipped in hibernation if the device remained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) in runtime suspend throughout the preceding "freeze" transition. Again, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) middle-layer callbacks are present for the device, they are responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) doing this, otherwise the PM core takes care of it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) The ``DPM_FLAG_MAY_SKIP_RESUME`` Driver Flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) --------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) During system-wide resume from a sleep state it's easiest to put devices into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808) the full-power state, as explained in :file:`Documentation/power/runtime_pm.rst`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) [Refer to that document for more information regarding this particular issue as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) well as for information on the device runtime power management framework in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811) general.] However, it often is desirable to leave devices in suspend after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) system transitions to the working state, especially if those devices had been in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) runtime suspend before the preceding system-wide suspend (or analogous)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) transition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) To that end, device drivers can use the ``DPM_FLAG_MAY_SKIP_RESUME`` flag to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817) indicate to the PM core and middle-layer code that they allow their "noirq" and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) "early" resume callbacks to be skipped if the device can be left in suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) after system-wide PM transitions to the working state. Whether or not that is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) the case generally depends on the state of the device before the given system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821) suspend-resume cycle and on the type of the system transition under way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) In particular, the "thaw" and "restore" transitions related to hibernation are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) not affected by ``DPM_FLAG_MAY_SKIP_RESUME`` at all. [All callbacks are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) issued during the "restore" transition regardless of the flag settings,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) and whether or not any driver callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) are skipped during the "thaw" transition depends whether or not the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) ``DPM_FLAG_SMART_SUSPEND`` flag is set (see `above <smart_suspend_flag_>`_).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) In addition, a device is not allowed to remain in runtime suspend if any of its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) children will be returned to full power.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) The ``DPM_FLAG_MAY_SKIP_RESUME`` flag is taken into account in combination with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) the :c:member:`power.may_skip_resume` status bit set by the PM core during the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) "suspend" phase of suspend-type transitions. If the driver or the middle layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) has a reason to prevent the driver's "noirq" and "early" resume callbacks from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) being skipped during the subsequent system resume transition, it should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) clear :c:member:`power.may_skip_resume` in its ``->suspend``, ``->suspend_late``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) or ``->suspend_noirq`` callback. [Note that the drivers setting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838) ``DPM_FLAG_SMART_SUSPEND`` need to clear :c:member:`power.may_skip_resume` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) their ``->suspend`` callback in case the other two are skipped.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) Setting the :c:member:`power.may_skip_resume` status bit along with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) ``DPM_FLAG_MAY_SKIP_RESUME`` flag is necessary, but generally not sufficient,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) for the driver's "noirq" and "early" resume callbacks to be skipped. Whether or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844) not they should be skipped can be determined by evaluating the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) :c:func:`dev_pm_skip_resume` helper function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) If that function returns ``true``, the driver's "noirq" and "early" resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) callbacks should be skipped and the device's runtime PM status will be set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) "suspended" by the PM core. Otherwise, if the device was runtime-suspended
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850) during the preceding system-wide suspend transition and its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) ``DPM_FLAG_SMART_SUSPEND`` is set, its runtime PM status will be set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) "active" by the PM core. [Hence, the drivers that do not set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853) ``DPM_FLAG_SMART_SUSPEND`` should not expect the runtime PM status of their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) devices to be changed from "suspended" to "active" by the PM core during
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855) system-wide resume-type transitions.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) If the ``DPM_FLAG_MAY_SKIP_RESUME`` flag is not set for a device, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858) ``DPM_FLAG_SMART_SUSPEND`` is set and the driver's "late" and "noirq" suspend
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) callbacks are skipped, its system-wide "noirq" and "early" resume callbacks, if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) present, are invoked as usual and the device's runtime PM status is set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) "active" by the PM core before enabling runtime PM for it. In that case, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862) driver must be prepared to cope with the invocation of its system-wide resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) callbacks back-to-back with its ``->runtime_suspend`` one (without the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) intervening ``->runtime_resume`` and system-wide suspend callbacks) and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) final state of the device must reflect the "active" runtime PM status in that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) case. [Note that this is not a problem at all if the driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) ``->suspend_late`` callback pointer points to the same function as its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868) ``->runtime_suspend`` one and its ``->resume_early`` callback pointer points to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) the same function as the ``->runtime_resume`` one, while none of the other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870) system-wide suspend-resume callbacks of the driver are present, for example.]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872) Likewise, if ``DPM_FLAG_MAY_SKIP_RESUME`` is set for a device, its driver's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) system-wide "noirq" and "early" resume callbacks may be skipped while its "late"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) and "noirq" suspend callbacks may have been executed (in principle, regardless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) of whether or not ``DPM_FLAG_SMART_SUSPEND`` is set). In that case, the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) needs to be able to cope with the invocation of its ``->runtime_resume``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) callback back-to-back with its "late" and "noirq" suspend ones. [For instance,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) that is not a concern if the driver sets both ``DPM_FLAG_SMART_SUSPEND`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) ``DPM_FLAG_MAY_SKIP_RESUME`` and uses the same pair of suspend/resume callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) functions for runtime PM and system-wide suspend/resume.]
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags