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