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