Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 1 | Device Power Management |
| 2 | |
Rafael J. Wysocki | 7538e3d | 2011-02-16 21:53:17 +0100 | [diff] [blame] | 3 | Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 4 | Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> |
| 5 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 6 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 7 | Most of the code in Linux is device drivers, so most of the Linux power |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 8 | management (PM) code is also driver-specific. Most drivers will do very |
| 9 | little; others, especially for platforms with small batteries (like cell |
| 10 | phones), will do a lot. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 11 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 12 | This writeup gives an overview of how drivers interact with system-wide |
| 13 | power management goals, emphasizing the models and interfaces that are |
| 14 | shared by everything that hooks up to the driver model core. Read it as |
| 15 | background for the domain-specific work you'd do with any specific driver. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 16 | |
| 17 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 18 | Two Models for Device Power Management |
| 19 | ====================================== |
| 20 | Drivers will use one or both of these models to put devices into low-power |
| 21 | states: |
| 22 | |
| 23 | System Sleep model: |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 24 | Drivers can enter low-power states as part of entering system-wide |
| 25 | low-power states like "suspend" (also known as "suspend-to-RAM"), or |
| 26 | (mostly for systems with disks) "hibernation" (also known as |
| 27 | "suspend-to-disk"). |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 28 | |
| 29 | This is something that device, bus, and class drivers collaborate on |
| 30 | by implementing various role-specific suspend and resume methods to |
| 31 | cleanly power down hardware and software subsystems, then reactivate |
| 32 | them without loss of data. |
| 33 | |
| 34 | Some drivers can manage hardware wakeup events, which make the system |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 35 | leave the low-power state. This feature may be enabled or disabled |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 36 | using the relevant /sys/devices/.../power/wakeup file (for Ethernet |
| 37 | drivers the ioctl interface used by ethtool may also be used for this |
| 38 | purpose); enabling it may cost some power usage, but let the whole |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 39 | system enter low-power states more often. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 40 | |
| 41 | Runtime Power Management model: |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 42 | Devices may also be put into low-power states while the system is |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 43 | running, independently of other power management activity in principle. |
| 44 | However, devices are not generally independent of each other (for |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 45 | example, a parent device cannot be suspended unless all of its child |
| 46 | devices have been suspended). Moreover, depending on the bus type the |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 47 | device is on, it may be necessary to carry out some bus-specific |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 48 | operations on the device for this purpose. Devices put into low power |
| 49 | states at run time may require special handling during system-wide power |
| 50 | transitions (suspend or hibernation). |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 51 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 52 | For these reasons not only the device driver itself, but also the |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 53 | appropriate subsystem (bus type, device type or device class) driver and |
| 54 | the PM core are involved in runtime power management. As in the system |
| 55 | sleep power management case, they need to collaborate by implementing |
| 56 | various role-specific suspend and resume methods, so that the hardware |
| 57 | is cleanly powered down and reactivated without data or service loss. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 58 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 59 | There's not a lot to be said about those low-power states except that they are |
| 60 | very system-specific, and often device-specific. Also, that if enough devices |
| 61 | have been put into low-power states (at runtime), the effect may be very similar |
| 62 | to entering some system-wide low-power state (system sleep) ... and that |
| 63 | synergies exist, so that several drivers using runtime PM might put the system |
| 64 | into a state where even deeper power saving options are available. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 65 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 66 | Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except |
| 67 | for wakeup events), no more data read or written, and requests from upstream |
| 68 | drivers are no longer accepted. A given bus or platform may have different |
| 69 | requirements though. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 70 | |
| 71 | Examples of hardware wakeup events include an alarm from a real time clock, |
| 72 | network wake-on-LAN packets, keyboard or mouse activity, and media insertion |
| 73 | or removal (for PCMCIA, MMC/SD, USB, and so on). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 74 | |
| 75 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 76 | Interfaces for Entering System Sleep States |
| 77 | =========================================== |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 78 | There are programming interfaces provided for subsystems (bus type, device type, |
| 79 | device class) and device drivers to allow them to participate in the power |
| 80 | management of devices they are concerned with. These interfaces cover both |
| 81 | system sleep and runtime power management. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 82 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 83 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 84 | Device Power Management Operations |
| 85 | ---------------------------------- |
| 86 | Device power management operations, at the subsystem level as well as at the |
| 87 | device driver level, are implemented by defining and populating objects of type |
| 88 | struct dev_pm_ops: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 89 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 90 | struct dev_pm_ops { |
| 91 | int (*prepare)(struct device *dev); |
| 92 | void (*complete)(struct device *dev); |
| 93 | int (*suspend)(struct device *dev); |
| 94 | int (*resume)(struct device *dev); |
| 95 | int (*freeze)(struct device *dev); |
| 96 | int (*thaw)(struct device *dev); |
| 97 | int (*poweroff)(struct device *dev); |
| 98 | int (*restore)(struct device *dev); |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 99 | int (*suspend_late)(struct device *dev); |
| 100 | int (*resume_early)(struct device *dev); |
| 101 | int (*freeze_late)(struct device *dev); |
| 102 | int (*thaw_early)(struct device *dev); |
| 103 | int (*poweroff_late)(struct device *dev); |
| 104 | int (*restore_early)(struct device *dev); |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 105 | int (*suspend_noirq)(struct device *dev); |
| 106 | int (*resume_noirq)(struct device *dev); |
| 107 | int (*freeze_noirq)(struct device *dev); |
| 108 | int (*thaw_noirq)(struct device *dev); |
| 109 | int (*poweroff_noirq)(struct device *dev); |
| 110 | int (*restore_noirq)(struct device *dev); |
| 111 | int (*runtime_suspend)(struct device *dev); |
| 112 | int (*runtime_resume)(struct device *dev); |
| 113 | int (*runtime_idle)(struct device *dev); |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 114 | }; |
| 115 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 116 | This structure is defined in include/linux/pm.h and the methods included in it |
| 117 | are also described in that file. Their roles will be explained in what follows. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 118 | For now, it should be sufficient to remember that the last three methods are |
| 119 | specific to runtime power management while the remaining ones are used during |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 120 | system-wide power transitions. |
| 121 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 122 | There also is a deprecated "old" or "legacy" interface for power management |
| 123 | operations available at least for some subsystems. This approach does not use |
| 124 | struct dev_pm_ops objects and it is suitable only for implementing system sleep |
| 125 | power management methods. Therefore it is not described in this document, so |
| 126 | please refer directly to the source code for more information about it. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 127 | |
| 128 | |
| 129 | Subsystem-Level Methods |
| 130 | ----------------------- |
| 131 | The core methods to suspend and resume devices reside in struct dev_pm_ops |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 132 | pointed to by the ops member of struct dev_pm_domain, or by the pm member of |
| 133 | struct bus_type, struct device_type and struct class. They are mostly of |
| 134 | interest to the people writing infrastructure for platforms and buses, like PCI |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 135 | or USB, or device type and device class drivers. They also are relevant to the |
| 136 | writers of device drivers whose subsystems (PM domains, device types, device |
| 137 | classes and bus types) don't provide all power management methods. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 138 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 139 | Bus drivers implement these methods as appropriate for the hardware and the |
| 140 | drivers using it; PCI works differently from USB, and so on. Not many people |
| 141 | write subsystem-level drivers; most driver code is a "device driver" that builds |
| 142 | on top of bus-specific framework code. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 143 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 144 | For more information on these driver calls, see the description later; |
| 145 | they are called in phases for every device, respecting the parent-child |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 146 | sequencing in the driver model tree. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 147 | |
| 148 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 149 | /sys/devices/.../power/wakeup files |
| 150 | ----------------------------------- |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 151 | All device objects in the driver model contain fields that control the handling |
| 152 | of system wakeup events (hardware signals that can force the system out of a |
| 153 | sleep state). These fields are initialized by bus or device driver code using |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 154 | device_set_wakeup_capable() and device_set_wakeup_enable(), defined in |
| 155 | include/linux/pm_wakeup.h. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 156 | |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 157 | The "power.can_wakeup" flag just records whether the device (and its driver) can |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 158 | physically support wakeup events. The device_set_wakeup_capable() routine |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 159 | affects this flag. The "power.wakeup" field is a pointer to an object of type |
| 160 | struct wakeup_source used for controlling whether or not the device should use |
| 161 | its system wakeup mechanism and for notifying the PM core of system wakeup |
| 162 | events signaled by the device. This object is only present for wakeup-capable |
| 163 | devices (i.e. devices whose "can_wakeup" flags are set) and is created (or |
| 164 | removed) by device_set_wakeup_capable(). |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 165 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 166 | Whether or not a device is capable of issuing wakeup events is a hardware |
| 167 | matter, and the kernel is responsible for keeping track of it. By contrast, |
| 168 | whether or not a wakeup-capable device should issue wakeup events is a policy |
| 169 | decision, and it is managed by user space through a sysfs attribute: the |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 170 | "power/wakeup" file. User space can write the strings "enabled" or "disabled" |
| 171 | to it to indicate whether or not, respectively, the device is supposed to signal |
| 172 | system wakeup. This file is only present if the "power.wakeup" object exists |
| 173 | for the given device and is created (or removed) along with that object, by |
| 174 | device_set_wakeup_capable(). Reads from the file will return the corresponding |
| 175 | string. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 176 | |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 177 | The "power/wakeup" file is supposed to contain the "disabled" string initially |
| 178 | for the majority of devices; the major exceptions are power buttons, keyboards, |
| 179 | and Ethernet adapters whose WoL (wake-on-LAN) feature has been set up with |
| 180 | ethtool. It should also default to "enabled" for devices that don't generate |
| 181 | wakeup requests on their own but merely forward wakeup requests from one bus to |
| 182 | another (like PCI Express ports). |
| 183 | |
| 184 | The device_may_wakeup() routine returns true only if the "power.wakeup" object |
| 185 | exists and the corresponding "power/wakeup" file contains the string "enabled". |
Rafael J. Wysocki | cb8f51b | 2011-02-08 23:26:02 +0100 | [diff] [blame] | 186 | This information is used by subsystems, like the PCI bus type code, to see |
| 187 | whether or not to enable the devices' wakeup mechanisms. If device wakeup |
| 188 | mechanisms are enabled or disabled directly by drivers, they also should use |
| 189 | device_may_wakeup() to decide what to do during a system sleep transition. |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 190 | Device drivers, however, are not supposed to call device_set_wakeup_enable() |
| 191 | directly in any case. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 192 | |
Rafael J. Wysocki | fafba48 | 2011-11-23 21:20:15 +0100 | [diff] [blame] | 193 | It ought to be noted that system wakeup is conceptually different from "remote |
| 194 | wakeup" used by runtime power management, although it may be supported by the |
| 195 | same physical mechanism. Remote wakeup is a feature allowing devices in |
| 196 | low-power states to trigger specific interrupts to signal conditions in which |
| 197 | they should be put into the full-power state. Those interrupts may or may not |
| 198 | be used to signal system wakeup events, depending on the hardware design. On |
| 199 | some systems it is impossible to trigger them from system sleep states. In any |
| 200 | case, remote wakeup should always be enabled for runtime power management for |
| 201 | all devices and drivers that support it. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 202 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 203 | /sys/devices/.../power/control files |
| 204 | ------------------------------------ |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 205 | Each device in the driver model has a flag to control whether it is subject to |
| 206 | runtime power management. This flag, called runtime_auto, is initialized by the |
| 207 | bus type (or generally subsystem) code using pm_runtime_allow() or |
| 208 | pm_runtime_forbid(); the default is to allow runtime power management. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 209 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 210 | The setting can be adjusted by user space by writing either "on" or "auto" to |
| 211 | the device's power/control sysfs file. Writing "auto" calls pm_runtime_allow(), |
| 212 | setting the flag and allowing the device to be runtime power-managed by its |
| 213 | driver. Writing "on" calls pm_runtime_forbid(), clearing the flag, returning |
| 214 | the device to full power if it was in a low-power state, and preventing the |
| 215 | device from being runtime power-managed. User space can check the current value |
| 216 | of the runtime_auto flag by reading the file. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 217 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 218 | The device's runtime_auto flag has no effect on the handling of system-wide |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 219 | power transitions. In particular, the device can (and in the majority of cases |
| 220 | should and will) be put into a low-power state during a system-wide transition |
| 221 | to a sleep state even though its runtime_auto flag is clear. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 222 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 223 | For more information about the runtime power management framework, refer to |
| 224 | Documentation/power/runtime_pm.txt. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 225 | |
| 226 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 227 | Calling Drivers to Enter and Leave System Sleep States |
| 228 | ====================================================== |
| 229 | When the system goes into a sleep state, each device's driver is asked to |
| 230 | suspend the device by putting it into a state compatible with the target |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 231 | system state. That's usually some version of "off", but the details are |
| 232 | system-specific. Also, wakeup-enabled devices will usually stay partly |
| 233 | functional in order to wake the system. |
| 234 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 235 | When the system leaves that low-power state, the device's driver is asked to |
| 236 | resume it by returning it to full power. The suspend and resume operations |
| 237 | always go together, and both are multi-phase operations. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 238 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 239 | For simple drivers, suspend might quiesce the device using class code |
| 240 | and then turn its hardware as "off" as possible during suspend_noirq. The |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 241 | matching resume calls would then completely reinitialize the hardware |
| 242 | before reactivating its class I/O queues. |
| 243 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 244 | More power-aware drivers might prepare the devices for triggering system wakeup |
| 245 | events. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 246 | |
| 247 | |
| 248 | Call Sequence Guarantees |
| 249 | ------------------------ |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 250 | To ensure that bridges and similar links needing to talk to a device are |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 251 | available when the device is suspended or resumed, the device tree is |
| 252 | walked in a bottom-up order to suspend devices. A top-down order is |
| 253 | used to resume those devices. |
| 254 | |
| 255 | The ordering of the device tree is defined by the order in which devices |
| 256 | get registered: a child can never be registered, probed or resumed before |
| 257 | its parent; and can't be removed or suspended after that parent. |
| 258 | |
| 259 | The policy is that the device tree should match hardware bus topology. |
| 260 | (Or at least the control bus, for devices which use multiple busses.) |
Rafael J. Wysocki | 58aca23 | 2008-03-12 00:57:22 +0100 | [diff] [blame] | 261 | In particular, this means that a device registration may fail if the parent of |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 262 | the device is suspending (i.e. has been chosen by the PM core as the next |
Rafael J. Wysocki | 58aca23 | 2008-03-12 00:57:22 +0100 | [diff] [blame] | 263 | device to suspend) or has already suspended, as well as after all of the other |
| 264 | devices have been suspended. Device drivers must be prepared to cope with such |
| 265 | situations. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 266 | |
| 267 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 268 | System Power Management Phases |
| 269 | ------------------------------ |
| 270 | Suspending or resuming the system is done in several phases. Different phases |
| 271 | are used for standby or memory sleep states ("suspend-to-RAM") and the |
| 272 | hibernation state ("suspend-to-disk"). Each phase involves executing callbacks |
| 273 | for every device before the next phase begins. Not all busses or classes |
| 274 | support all these callbacks and not all drivers use all the callbacks. The |
| 275 | various phases always run after tasks have been frozen and before they are |
| 276 | unfrozen. Furthermore, the *_noirq phases run at a time when IRQ handlers have |
Rafael J. Wysocki | fa8ce72 | 2011-11-23 21:19:57 +0100 | [diff] [blame] | 277 | been disabled (except for those marked with the IRQF_NO_SUSPEND flag). |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 278 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 279 | All phases use PM domain, bus, type, class or driver callbacks (that is, methods |
| 280 | defined in dev->pm_domain->ops, dev->bus->pm, dev->type->pm, dev->class->pm or |
| 281 | dev->driver->pm). These callbacks are regarded by the PM core as mutually |
| 282 | exclusive. Moreover, PM domain callbacks always take precedence over all of the |
| 283 | other callbacks and, for example, type callbacks take precedence over bus, class |
| 284 | and driver callbacks. To be precise, the following rules are used to determine |
| 285 | which callback to execute in the given phase: |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 286 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 287 | 1. If dev->pm_domain is present, the PM core will choose the callback |
| 288 | included in dev->pm_domain->ops for execution |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 289 | |
| 290 | 2. Otherwise, if both dev->type and dev->type->pm are present, the callback |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 291 | included in dev->type->pm will be chosen for execution. |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 292 | |
| 293 | 3. Otherwise, if both dev->class and dev->class->pm are present, the |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 294 | callback included in dev->class->pm will be chosen for execution. |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 295 | |
| 296 | 4. Otherwise, if both dev->bus and dev->bus->pm are present, the callback |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 297 | included in dev->bus->pm will be chosen for execution. |
Rafael J. Wysocki | 5841eb6 | 2011-11-23 21:18:39 +0100 | [diff] [blame] | 298 | |
| 299 | This allows PM domains and device types to override callbacks provided by bus |
| 300 | types or device classes if necessary. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 301 | |
Rafael J. Wysocki | 35cd133 | 2011-12-18 00:34:13 +0100 | [diff] [blame] | 302 | The PM domain, type, class and bus callbacks may in turn invoke device- or |
| 303 | driver-specific methods stored in dev->driver->pm, but they don't have to do |
| 304 | that. |
| 305 | |
| 306 | If the subsystem callback chosen for execution is not present, the PM core will |
| 307 | execute the corresponding method from dev->driver->pm instead if there is one. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 308 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 309 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 310 | Entering System Suspend |
| 311 | ----------------------- |
| 312 | When the system goes into the standby or memory sleep state, the phases are: |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 313 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 314 | prepare, suspend, suspend_late, suspend_noirq. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 315 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 316 | 1. The prepare phase is meant to prevent races by preventing new devices |
| 317 | from being registered; the PM core would never know that all the |
| 318 | children of a device had been suspended if new children could be |
| 319 | registered at will. (By contrast, devices may be unregistered at any |
| 320 | time.) Unlike the other suspend-related phases, during the prepare |
| 321 | phase the device tree is traversed top-down. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 322 | |
Rafael J. Wysocki | 91e7c75 | 2011-05-17 23:26:00 +0200 | [diff] [blame] | 323 | After the prepare callback method returns, no new children may be |
| 324 | registered below the device. The method may also prepare the device or |
Rafael J. Wysocki | fa8ce72 | 2011-11-23 21:19:57 +0100 | [diff] [blame] | 325 | driver in some way for the upcoming system power transition, but it |
| 326 | should not put the device into a low-power state. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 327 | |
| 328 | 2. The suspend methods should quiesce the device to stop it from performing |
| 329 | I/O. They also may save the device registers and put it into the |
| 330 | appropriate low-power state, depending on the bus type the device is on, |
| 331 | and they may enable wakeup events. |
| 332 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 333 | 3 For a number of devices it is convenient to split suspend into the |
| 334 | "quiesce device" and "save device state" phases, in which cases |
| 335 | suspend_late is meant to do the latter. It is always executed after |
| 336 | runtime power management has been disabled for all devices. |
| 337 | |
| 338 | 4. The suspend_noirq phase occurs after IRQ handlers have been disabled, |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 339 | which means that the driver's interrupt handler will not be called while |
| 340 | the callback method is running. The methods should save the values of |
| 341 | the device's registers that weren't saved previously and finally put the |
| 342 | device into the appropriate low-power state. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 343 | |
| 344 | The majority of subsystems and device drivers need not implement this |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 345 | callback. However, bus types allowing devices to share interrupt |
| 346 | vectors, like PCI, generally need it; otherwise a driver might encounter |
| 347 | an error during the suspend phase by fielding a shared interrupt |
| 348 | generated by some other device after its own device had been set to low |
| 349 | power. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 350 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 351 | At the end of these phases, drivers should have stopped all I/O transactions |
| 352 | (DMA, IRQs), saved enough state that they can re-initialize or restore previous |
| 353 | state (as needed by the hardware), and placed the device into a low-power state. |
| 354 | On many platforms they will gate off one or more clock sources; sometimes they |
| 355 | will also switch off power supplies or reduce voltages. (Drivers supporting |
| 356 | runtime PM may already have performed some or all of these steps.) |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 357 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 358 | If device_may_wakeup(dev) returns true, the device should be prepared for |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 359 | generating hardware wakeup signals to trigger a system wakeup event when the |
| 360 | system is in the sleep state. For example, enable_irq_wake() might identify |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 361 | GPIO signals hooked up to a switch or other external hardware, and |
| 362 | pci_enable_wake() does something similar for the PCI PME signal. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 363 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 364 | If any of these callbacks returns an error, the system won't enter the desired |
| 365 | low-power state. Instead the PM core will unwind its actions by resuming all |
| 366 | the devices that were suspended. |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 367 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 368 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 369 | Leaving System Suspend |
| 370 | ---------------------- |
| 371 | When resuming from standby or memory sleep, the phases are: |
| 372 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 373 | resume_noirq, resume_early, resume, complete. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 374 | |
| 375 | 1. The resume_noirq callback methods should perform any actions needed |
| 376 | before the driver's interrupt handlers are invoked. This generally |
| 377 | means undoing the actions of the suspend_noirq phase. If the bus type |
| 378 | permits devices to share interrupt vectors, like PCI, the method should |
| 379 | bring the device and its driver into a state in which the driver can |
| 380 | recognize if the device is the source of incoming interrupts, if any, |
| 381 | and handle them correctly. |
| 382 | |
| 383 | For example, the PCI bus type's ->pm.resume_noirq() puts the device into |
| 384 | the full-power state (D0 in the PCI terminology) and restores the |
| 385 | standard configuration registers of the device. Then it calls the |
| 386 | device driver's ->pm.resume_noirq() method to perform device-specific |
| 387 | actions. |
| 388 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 389 | 2. The resume_early methods should prepare devices for the execution of |
| 390 | the resume methods. This generally involves undoing the actions of the |
| 391 | preceding suspend_late phase. |
| 392 | |
| 393 | 3 The resume methods should bring the the device back to its operating |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 394 | state, so that it can perform normal I/O. This generally involves |
| 395 | undoing the actions of the suspend phase. |
| 396 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 397 | 4. The complete phase should undo the actions of the prepare phase. Note, |
| 398 | however, that new children may be registered below the device as soon as |
| 399 | the resume callbacks occur; it's not necessary to wait until the |
| 400 | complete phase. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 401 | |
| 402 | At the end of these phases, drivers should be as functional as they were before |
| 403 | suspending: I/O can be performed using DMA and IRQs, and the relevant clocks are |
| 404 | gated on. Even if the device was in a low-power state before the system sleep |
| 405 | because of runtime power management, afterwards it should be back in its |
| 406 | full-power state. There are multiple reasons why it's best to do this; they are |
| 407 | discussed in more detail in Documentation/power/runtime_pm.txt. |
| 408 | |
| 409 | However, the details here may again be platform-specific. For example, |
| 410 | some systems support multiple "run" states, and the mode in effect at |
| 411 | the end of resume might not be the one which preceded suspension. |
| 412 | That means availability of certain clocks or power supplies changed, |
| 413 | which could easily affect how a driver works. |
| 414 | |
| 415 | Drivers need to be able to handle hardware which has been reset since the |
| 416 | suspend methods were called, for example by complete reinitialization. |
| 417 | This may be the hardest part, and the one most protected by NDA'd documents |
| 418 | and chip errata. It's simplest if the hardware state hasn't changed since |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 419 | the suspend was carried out, but that can't be guaranteed (in fact, it usually |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 420 | is not the case). |
| 421 | |
| 422 | Drivers must also be prepared to notice that the device has been removed |
| 423 | while the system was powered down, whenever that's physically possible. |
| 424 | PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses |
| 425 | where common Linux platforms will see such removal. Details of how drivers |
| 426 | will notice and handle such removals are currently bus-specific, and often |
| 427 | involve a separate thread. |
| 428 | |
| 429 | These callbacks may return an error value, but the PM core will ignore such |
| 430 | errors since there's nothing it can do about them other than printing them in |
| 431 | the system log. |
| 432 | |
| 433 | |
| 434 | Entering Hibernation |
| 435 | -------------------- |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 436 | Hibernating the system is more complicated than putting it into the standby or |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 437 | memory sleep state, because it involves creating and saving a system image. |
| 438 | Therefore there are more phases for hibernation, with a different set of |
| 439 | callbacks. These phases always run after tasks have been frozen and memory has |
| 440 | been freed. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 441 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 442 | The general procedure for hibernation is to quiesce all devices (freeze), create |
| 443 | an image of the system memory while everything is stable, reactivate all |
| 444 | devices (thaw), write the image to permanent storage, and finally shut down the |
| 445 | system (poweroff). The phases used to accomplish this are: |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 446 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 447 | prepare, freeze, freeze_late, freeze_noirq, thaw_noirq, thaw_early, |
| 448 | thaw, complete, prepare, poweroff, poweroff_late, poweroff_noirq |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 449 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 450 | 1. The prepare phase is discussed in the "Entering System Suspend" section |
| 451 | above. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 452 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 453 | 2. The freeze methods should quiesce the device so that it doesn't generate |
| 454 | IRQs or DMA, and they may need to save the values of device registers. |
| 455 | However the device does not have to be put in a low-power state, and to |
| 456 | save time it's best not to do so. Also, the device should not be |
| 457 | prepared to generate wakeup events. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 458 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 459 | 3. The freeze_late phase is analogous to the suspend_late phase described |
| 460 | above, except that the device should not be put in a low-power state and |
| 461 | should not be allowed to generate wakeup events by it. |
| 462 | |
| 463 | 4. The freeze_noirq phase is analogous to the suspend_noirq phase discussed |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 464 | above, except again that the device should not be put in a low-power |
| 465 | state and should not be allowed to generate wakeup events. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 466 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 467 | At this point the system image is created. All devices should be inactive and |
| 468 | the contents of memory should remain undisturbed while this happens, so that the |
| 469 | image forms an atomic snapshot of the system state. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 470 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 471 | 5. The thaw_noirq phase is analogous to the resume_noirq phase discussed |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 472 | above. The main difference is that its methods can assume the device is |
| 473 | in the same state as at the end of the freeze_noirq phase. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 474 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 475 | 6. The thaw_early phase is analogous to the resume_early phase described |
| 476 | above. Its methods should undo the actions of the preceding |
| 477 | freeze_late, if necessary. |
| 478 | |
| 479 | 7. The thaw phase is analogous to the resume phase discussed above. Its |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 480 | methods should bring the device back to an operating state, so that it |
| 481 | can be used for saving the image if necessary. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 482 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 483 | 8. The complete phase is discussed in the "Leaving System Suspend" section |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 484 | above. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 485 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 486 | At this point the system image is saved, and the devices then need to be |
| 487 | prepared for the upcoming system shutdown. This is much like suspending them |
| 488 | before putting the system into the standby or memory sleep state, and the phases |
| 489 | are similar. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 490 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 491 | 9. The prepare phase is discussed above. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 492 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 493 | 10. The poweroff phase is analogous to the suspend phase. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 494 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 495 | 11. The poweroff_late phase is analogous to the suspend_late phase. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 496 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 497 | 12. The poweroff_noirq phase is analogous to the suspend_noirq phase. |
| 498 | |
| 499 | The poweroff, poweroff_late and poweroff_noirq callbacks should do essentially |
| 500 | the same things as the suspend, suspend_late and suspend_noirq callbacks, |
| 501 | respectively. The only notable difference is that they need not store the |
| 502 | device register values, because the registers should already have been stored |
| 503 | during the freeze, freeze_late or freeze_noirq phases. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 504 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 505 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 506 | Leaving Hibernation |
| 507 | ------------------- |
| 508 | Resuming from hibernation is, again, more complicated than resuming from a sleep |
| 509 | state in which the contents of main memory are preserved, because it requires |
| 510 | a system image to be loaded into memory and the pre-hibernation memory contents |
| 511 | to be restored before control can be passed back to the image kernel. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 512 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 513 | Although in principle, the image might be loaded into memory and the |
| 514 | pre-hibernation memory contents restored by the boot loader, in practice this |
| 515 | can't be done because boot loaders aren't smart enough and there is no |
| 516 | established protocol for passing the necessary information. So instead, the |
| 517 | boot loader loads a fresh instance of the kernel, called the boot kernel, into |
| 518 | memory and passes control to it in the usual way. Then the boot kernel reads |
| 519 | the system image, restores the pre-hibernation memory contents, and passes |
| 520 | control to the image kernel. Thus two different kernels are involved in |
| 521 | resuming from hibernation. In fact, the boot kernel may be completely different |
| 522 | from the image kernel: a different configuration and even a different version. |
| 523 | This has important consequences for device drivers and their subsystems. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 524 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 525 | To be able to load the system image into memory, the boot kernel needs to |
| 526 | include at least a subset of device drivers allowing it to access the storage |
| 527 | medium containing the image, although it doesn't need to include all of the |
| 528 | drivers present in the image kernel. After the image has been loaded, the |
| 529 | devices managed by the boot kernel need to be prepared for passing control back |
| 530 | to the image kernel. This is very similar to the initial steps involved in |
| 531 | creating a system image, and it is accomplished in the same way, using prepare, |
| 532 | freeze, and freeze_noirq phases. However the devices affected by these phases |
| 533 | are only those having drivers in the boot kernel; other devices will still be in |
| 534 | whatever state the boot loader left them. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 535 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 536 | Should the restoration of the pre-hibernation memory contents fail, the boot |
| 537 | kernel would go through the "thawing" procedure described above, using the |
| 538 | thaw_noirq, thaw, and complete phases, and then continue running normally. This |
| 539 | happens only rarely. Most often the pre-hibernation memory contents are |
| 540 | restored successfully and control is passed to the image kernel, which then |
| 541 | becomes responsible for bringing the system back to the working state. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 542 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 543 | To achieve this, the image kernel must restore the devices' pre-hibernation |
| 544 | functionality. The operation is much like waking up from the memory sleep |
| 545 | state, although it involves different phases: |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 546 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 547 | restore_noirq, restore_early, restore, complete |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 548 | |
| 549 | 1. The restore_noirq phase is analogous to the resume_noirq phase. |
| 550 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 551 | 2. The restore_early phase is analogous to the resume_early phase. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 552 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 553 | 3. The restore phase is analogous to the resume phase. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 554 | |
Rafael J. Wysocki | cf579df | 2012-01-29 20:38:29 +0100 | [diff] [blame] | 555 | 4. The complete phase is discussed above. |
| 556 | |
| 557 | The main difference from resume[_early|_noirq] is that restore[_early|_noirq] |
| 558 | must assume the device has been accessed and reconfigured by the boot loader or |
| 559 | the boot kernel. Consequently the state of the device may be different from the |
| 560 | state remembered from the freeze, freeze_late and freeze_noirq phases. The |
| 561 | device may even need to be reset and completely re-initialized. In many cases |
| 562 | this difference doesn't matter, so the resume[_early|_noirq] and |
| 563 | restore[_early|_norq] method pointers can be set to the same routines. |
| 564 | Nevertheless, different callback pointers are used in case there is a situation |
| 565 | where it actually does matter. |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 566 | |
| 567 | |
Rafael J. Wysocki | 564b905 | 2011-06-23 01:52:55 +0200 | [diff] [blame] | 568 | Device Power Management Domains |
| 569 | ------------------------------- |
Rafael J. Wysocki | 7538e3d | 2011-02-16 21:53:17 +0100 | [diff] [blame] | 570 | Sometimes devices share reference clocks or other power resources. In those |
| 571 | cases it generally is not possible to put devices into low-power states |
| 572 | individually. Instead, a set of devices sharing a power resource can be put |
| 573 | into a low-power state together at the same time by turning off the shared |
| 574 | power resource. Of course, they also need to be put into the full-power state |
| 575 | together, by turning the shared power resource on. A set of devices with this |
| 576 | property is often referred to as a power domain. |
| 577 | |
Rafael J. Wysocki | 564b905 | 2011-06-23 01:52:55 +0200 | [diff] [blame] | 578 | Support for power domains is provided through the pm_domain field of struct |
| 579 | device. This field is a pointer to an object of type struct dev_pm_domain, |
Rafael J. Wysocki | 7538e3d | 2011-02-16 21:53:17 +0100 | [diff] [blame] | 580 | defined in include/linux/pm.h, providing a set of power management callbacks |
| 581 | analogous to the subsystem-level and device driver callbacks that are executed |
Rafael J. Wysocki | ca9c689 | 2011-06-21 23:25:32 +0200 | [diff] [blame] | 582 | for the given device during all power transitions, instead of the respective |
| 583 | subsystem-level callbacks. Specifically, if a device's pm_domain pointer is |
| 584 | not NULL, the ->suspend() callback from the object pointed to by it will be |
| 585 | executed instead of its subsystem's (e.g. bus type's) ->suspend() callback and |
| 586 | anlogously for all of the remaining callbacks. In other words, power management |
| 587 | domain callbacks, if defined for the given device, always take precedence over |
| 588 | the callbacks provided by the device's subsystem (e.g. bus type). |
Rafael J. Wysocki | 7538e3d | 2011-02-16 21:53:17 +0100 | [diff] [blame] | 589 | |
Rafael J. Wysocki | ca9c689 | 2011-06-21 23:25:32 +0200 | [diff] [blame] | 590 | The support for device power management domains is only relevant to platforms |
| 591 | needing to use the same device driver power management callbacks in many |
| 592 | different power domain configurations and wanting to avoid incorporating the |
| 593 | support for power domains into subsystem-level callbacks, for example by |
| 594 | modifying the platform bus type. Other platforms need not implement it or take |
| 595 | it into account in any way. |
Rafael J. Wysocki | 7538e3d | 2011-02-16 21:53:17 +0100 | [diff] [blame] | 596 | |
| 597 | |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 598 | Device Low Power (suspend) States |
| 599 | --------------------------------- |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 600 | Device low-power states aren't standard. One device might only handle |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 601 | "on" and "off, while another might support a dozen different versions of |
| 602 | "on" (how many engines are active?), plus a state that gets back to "on" |
| 603 | faster than from a full "off". |
| 604 | |
| 605 | Some busses define rules about what different suspend states mean. PCI |
| 606 | gives one example: after the suspend sequence completes, a non-legacy |
| 607 | PCI device may not perform DMA or issue IRQs, and any wakeup events it |
| 608 | issues would be issued through the PME# bus signal. Plus, there are |
| 609 | several PCI-standard device states, some of which are optional. |
| 610 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 611 | In contrast, integrated system-on-chip processors often use IRQs as the |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 612 | wakeup event sources (so drivers would call enable_irq_wake) and might |
| 613 | be able to treat DMA completion as a wakeup event (sometimes DMA can stay |
| 614 | active too, it'd only be the CPU and some peripherals that sleep). |
| 615 | |
| 616 | Some details here may be platform-specific. Systems may have devices that |
| 617 | can be fully active in certain sleep states, such as an LCD display that's |
| 618 | refreshed using DMA while most of the system is sleeping lightly ... and |
| 619 | its frame buffer might even be updated by a DSP or other non-Linux CPU while |
| 620 | the Linux control processor stays idle. |
| 621 | |
| 622 | Moreover, the specific actions taken may depend on the target system state. |
| 623 | One target system state might allow a given device to be very operational; |
| 624 | another might require a hard shut down with re-initialization on resume. |
| 625 | And two different target systems might use the same device in different |
| 626 | ways; the aforementioned LCD might be active in one product's "standby", |
| 627 | but a different product using the same SOC might work differently. |
| 628 | |
| 629 | |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 630 | Power Management Notifiers |
| 631 | -------------------------- |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 632 | There are some operations that cannot be carried out by the power management |
| 633 | callbacks discussed above, because the callbacks occur too late or too early. |
| 634 | To handle these cases, subsystems and device drivers may register power |
| 635 | management notifiers that are called before tasks are frozen and after they have |
| 636 | been thawed. Generally speaking, the PM notifiers are suitable for performing |
| 637 | actions that either require user space to be available, or at least won't |
| 638 | interfere with user space. |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 639 | |
| 640 | For details refer to Documentation/power/notifiers.txt. |
| 641 | |
| 642 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 643 | Runtime Power Management |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 644 | ======================== |
| 645 | Many devices are able to dynamically power down while the system is still |
| 646 | running. This feature is useful for devices that are not being used, and |
| 647 | can offer significant power savings on a running system. These devices |
| 648 | often support a range of runtime power states, which might use names such |
| 649 | as "off", "sleep", "idle", "active", and so on. Those states will in some |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 650 | cases (like PCI) be partially constrained by the bus the device uses, and will |
David Brownell | 4fc0840 | 2006-08-10 16:38:28 -0700 | [diff] [blame] | 651 | usually include hardware states that are also used in system sleep states. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 652 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 653 | A system-wide power transition can be started while some devices are in low |
| 654 | power states due to runtime power management. The system sleep PM callbacks |
| 655 | should recognize such situations and react to them appropriately, but the |
| 656 | necessary actions are subsystem-specific. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 657 | |
Alan Stern | d6f9cda | 2010-03-26 23:53:55 +0100 | [diff] [blame] | 658 | In some cases the decision may be made at the subsystem level while in other |
| 659 | cases the device driver may be left to decide. In some cases it may be |
| 660 | desirable to leave a suspended device in that state during a system-wide power |
| 661 | transition, but in other cases the device must be put back into the full-power |
| 662 | state temporarily, for example so that its system wakeup capability can be |
| 663 | disabled. This all depends on the hardware and the design of the subsystem and |
| 664 | device driver in question. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 665 | |
Rafael J. Wysocki | 455716e | 2011-07-01 22:29:05 +0200 | [diff] [blame] | 666 | During system-wide resume from a sleep state it's easiest to put devices into |
| 667 | the full-power state, as explained in Documentation/power/runtime_pm.txt. Refer |
| 668 | to that document for more information regarding this particular issue as well as |
Rafael J. Wysocki | 624f6ec | 2010-03-26 23:53:42 +0100 | [diff] [blame] | 669 | for information on the device runtime power management framework in general. |