aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorRafael J. Wysocki <rjw@sisk.pl>2011-07-15 17:59:25 -0400
committerRafael J. Wysocki <rjw@sisk.pl>2011-07-15 17:59:25 -0400
commit7ae033cc0dfce68d8e0c83aca60837cf2bf0d2e6 (patch)
tree91bb3b8ae2790c7fef06b1832a7df61ae496a77a /Documentation
parentba1389d74f34c0c6e95cc135a332cd29c29d9c20 (diff)
parentc8c9fda5069456eb9e0e403c19764b2e257802e1 (diff)
Merge branch 'pm-runtime' into for-linus
* pm-runtime: OMAP: PM: disable idle on suspend for GPIO and UART OMAP: PM: omap_device: add API to disable idle on suspend OMAP: PM: omap_device: add system PM methods for PM domain handling OMAP: PM: omap_device: conditionally use PM domain runtime helpers PM / Runtime: Add new helper function: pm_runtime_status_suspended() PM / Runtime: Consistent utilization of deferred_resume PM / Runtime: Prevent runtime_resume from racing with probe PM / Runtime: Replace "run-time" with "runtime" in documentation PM / Runtime: Improve documentation of enable, disable and barrier PM: Limit race conditions between runtime PM and system sleep (v2) PCI / PM: Detect early wakeup in pci_pm_prepare() PM / Runtime: Return special error code if runtime PM is disabled PM / Runtime: Update documentation of interactions with system sleep
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/power/devices.txt6
-rw-r--r--Documentation/power/runtime_pm.txt197
2 files changed, 125 insertions, 78 deletions
diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt
index 85c6f980b642..3384d5996be2 100644
--- a/Documentation/power/devices.txt
+++ b/Documentation/power/devices.txt
@@ -604,7 +604,7 @@ state temporarily, for example so that its system wakeup capability can be
604disabled. This all depends on the hardware and the design of the subsystem and 604disabled. This all depends on the hardware and the design of the subsystem and
605device driver in question. 605device driver in question.
606 606
607During system-wide resume from a sleep state it's best to put devices into the 607During system-wide resume from a sleep state it's easiest to put devices into
608full-power state, as explained in Documentation/power/runtime_pm.txt. Refer to 608the full-power state, as explained in Documentation/power/runtime_pm.txt. Refer
609that document for more information regarding this particular issue as well as 609to that document for more information regarding this particular issue as well as
610for information on the device runtime power management framework in general. 610for information on the device runtime power management framework in general.
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt
index 4b011b171be4..14dd3c6ad97e 100644
--- a/Documentation/power/runtime_pm.txt
+++ b/Documentation/power/runtime_pm.txt
@@ -1,39 +1,39 @@
1Run-time Power Management Framework for I/O Devices 1Runtime Power Management Framework for I/O Devices
2 2
3(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. 3(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
4(C) 2010 Alan Stern <stern@rowland.harvard.edu> 4(C) 2010 Alan Stern <stern@rowland.harvard.edu>
5 5
61. Introduction 61. Introduction
7 7
8Support for run-time power management (run-time PM) of I/O devices is provided 8Support for runtime power management (runtime PM) of I/O devices is provided
9at the power management core (PM core) level by means of: 9at the power management core (PM core) level by means of:
10 10
11* The power management workqueue pm_wq in which bus types and device drivers can 11* The power management workqueue pm_wq in which bus types and device drivers can
12 put their PM-related work items. It is strongly recommended that pm_wq be 12 put their PM-related work items. It is strongly recommended that pm_wq be
13 used for queuing all work items related to run-time PM, because this allows 13 used for queuing all work items related to runtime PM, because this allows
14 them to be synchronized with system-wide power transitions (suspend to RAM, 14 them to be synchronized with system-wide power transitions (suspend to RAM,
15 hibernation and resume from system sleep states). pm_wq is declared in 15 hibernation and resume from system sleep states). pm_wq is declared in
16 include/linux/pm_runtime.h and defined in kernel/power/main.c. 16 include/linux/pm_runtime.h and defined in kernel/power/main.c.
17 17
18* A number of run-time PM fields in the 'power' member of 'struct device' (which 18* A number of runtime PM fields in the 'power' member of 'struct device' (which
19 is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can 19 is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can
20 be used for synchronizing run-time PM operations with one another. 20 be used for synchronizing runtime PM operations with one another.
21 21
22* Three device run-time PM callbacks in 'struct dev_pm_ops' (defined in 22* Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in
23 include/linux/pm.h). 23 include/linux/pm.h).
24 24
25* A set of helper functions defined in drivers/base/power/runtime.c that can be 25* A set of helper functions defined in drivers/base/power/runtime.c that can be
26 used for carrying out run-time PM operations in such a way that the 26 used for carrying out runtime PM operations in such a way that the
27 synchronization between them is taken care of by the PM core. Bus types and 27 synchronization between them is taken care of by the PM core. Bus types and
28 device drivers are encouraged to use these functions. 28 device drivers are encouraged to use these functions.
29 29
30The run-time PM callbacks present in 'struct dev_pm_ops', the device run-time PM 30The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM
31fields of 'struct dev_pm_info' and the core helper functions provided for 31fields of 'struct dev_pm_info' and the core helper functions provided for
32run-time PM are described below. 32runtime PM are described below.
33 33
342. Device Run-time PM Callbacks 342. Device Runtime PM Callbacks
35 35
36There are three device run-time PM callbacks defined in 'struct dev_pm_ops': 36There are three device runtime PM callbacks defined in 'struct dev_pm_ops':
37 37
38struct dev_pm_ops { 38struct dev_pm_ops {
39 ... 39 ...
@@ -72,11 +72,11 @@ knows what to do to handle the device).
72 not mean that the device has been put into a low power state. It is 72 not mean that the device has been put into a low power state. It is
73 supposed to mean, however, that the device will not process data and will 73 supposed to mean, however, that the device will not process data and will
74 not communicate with the CPU(s) and RAM until the subsystem-level resume 74 not communicate with the CPU(s) and RAM until the subsystem-level resume
75 callback is executed for it. The run-time PM status of a device after 75 callback is executed for it. The runtime PM status of a device after
76 successful execution of the subsystem-level suspend callback is 'suspended'. 76 successful execution of the subsystem-level suspend callback is 'suspended'.
77 77
78 * If the subsystem-level suspend callback returns -EBUSY or -EAGAIN, 78 * If the subsystem-level suspend callback returns -EBUSY or -EAGAIN,
79 the device's run-time PM status is 'active', which means that the device 79 the device's runtime PM status is 'active', which means that the device
80 _must_ be fully operational afterwards. 80 _must_ be fully operational afterwards.
81 81
82 * If the subsystem-level suspend callback returns an error code different 82 * If the subsystem-level suspend callback returns an error code different
@@ -104,7 +104,7 @@ the device).
104 104
105 * Once the subsystem-level resume callback has completed successfully, the PM 105 * Once the subsystem-level resume callback has completed successfully, the PM
106 core regards the device as fully operational, which means that the device 106 core regards the device as fully operational, which means that the device
107 _must_ be able to complete I/O operations as needed. The run-time PM status 107 _must_ be able to complete I/O operations as needed. The runtime PM status
108 of the device is then 'active'. 108 of the device is then 'active'.
109 109
110 * If the subsystem-level resume callback returns an error code, the PM core 110 * If the subsystem-level resume callback returns an error code, the PM core
@@ -130,7 +130,7 @@ device in that case. The value returned by this callback is ignored by the PM
130core. 130core.
131 131
132The helper functions provided by the PM core, described in Section 4, guarantee 132The helper functions provided by the PM core, described in Section 4, guarantee
133that the following constraints are met with respect to the bus type's run-time 133that the following constraints are met with respect to the bus type's runtime
134PM callbacks: 134PM callbacks:
135 135
136(1) The callbacks are mutually exclusive (e.g. it is forbidden to execute 136(1) The callbacks are mutually exclusive (e.g. it is forbidden to execute
@@ -142,7 +142,7 @@ PM callbacks:
142 142
143(2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active' 143(2) ->runtime_idle() and ->runtime_suspend() can only be executed for 'active'
144 devices (i.e. the PM core will only execute ->runtime_idle() or 144 devices (i.e. the PM core will only execute ->runtime_idle() or
145 ->runtime_suspend() for the devices the run-time PM status of which is 145 ->runtime_suspend() for the devices the runtime PM status of which is
146 'active'). 146 'active').
147 147
148(3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device 148(3) ->runtime_idle() and ->runtime_suspend() can only be executed for a device
@@ -151,7 +151,7 @@ PM callbacks:
151 flag of which is set. 151 flag of which is set.
152 152
153(4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the 153(4) ->runtime_resume() can only be executed for 'suspended' devices (i.e. the
154 PM core will only execute ->runtime_resume() for the devices the run-time 154 PM core will only execute ->runtime_resume() for the devices the runtime
155 PM status of which is 'suspended'). 155 PM status of which is 'suspended').
156 156
157Additionally, the helper functions provided by the PM core obey the following 157Additionally, the helper functions provided by the PM core obey the following
@@ -171,9 +171,9 @@ rules:
171 scheduled requests to execute the other callbacks for the same device, 171 scheduled requests to execute the other callbacks for the same device,
172 except for scheduled autosuspends. 172 except for scheduled autosuspends.
173 173
1743. Run-time PM Device Fields 1743. Runtime PM Device Fields
175 175
176The following device run-time PM fields are present in 'struct dev_pm_info', as 176The following device runtime PM fields are present in 'struct dev_pm_info', as
177defined in include/linux/pm.h: 177defined in include/linux/pm.h:
178 178
179 struct timer_list suspend_timer; 179 struct timer_list suspend_timer;
@@ -205,7 +205,7 @@ defined in include/linux/pm.h:
205 205
206 unsigned int disable_depth; 206 unsigned int disable_depth;
207 - used for disabling the helper funcions (they work normally if this is 207 - used for disabling the helper funcions (they work normally if this is
208 equal to zero); the initial value of it is 1 (i.e. run-time PM is 208 equal to zero); the initial value of it is 1 (i.e. runtime PM is
209 initially disabled for all devices) 209 initially disabled for all devices)
210 210
211 unsigned int runtime_error; 211 unsigned int runtime_error;
@@ -229,10 +229,10 @@ defined in include/linux/pm.h:
229 suspend to complete; means "start a resume as soon as you've suspended" 229 suspend to complete; means "start a resume as soon as you've suspended"
230 230
231 unsigned int run_wake; 231 unsigned int run_wake;
232 - set if the device is capable of generating run-time wake-up events 232 - set if the device is capable of generating runtime wake-up events
233 233
234 enum rpm_status runtime_status; 234 enum rpm_status runtime_status;
235 - the run-time PM status of the device; this field's initial value is 235 - the runtime PM status of the device; this field's initial value is
236 RPM_SUSPENDED, which means that each device is initially regarded by the 236 RPM_SUSPENDED, which means that each device is initially regarded by the
237 PM core as 'suspended', regardless of its real hardware status 237 PM core as 'suspended', regardless of its real hardware status
238 238
@@ -243,7 +243,7 @@ defined in include/linux/pm.h:
243 and pm_runtime_forbid() helper functions 243 and pm_runtime_forbid() helper functions
244 244
245 unsigned int no_callbacks; 245 unsigned int no_callbacks;
246 - indicates that the device does not use the run-time PM callbacks (see 246 - indicates that the device does not use the runtime PM callbacks (see
247 Section 8); it may be modified only by the pm_runtime_no_callbacks() 247 Section 8); it may be modified only by the pm_runtime_no_callbacks()
248 helper function 248 helper function
249 249
@@ -270,16 +270,16 @@ defined in include/linux/pm.h:
270 270
271All of the above fields are members of the 'power' member of 'struct device'. 271All of the above fields are members of the 'power' member of 'struct device'.
272 272
2734. Run-time PM Device Helper Functions 2734. Runtime PM Device Helper Functions
274 274
275The following run-time PM helper functions are defined in 275The following runtime PM helper functions are defined in
276drivers/base/power/runtime.c and include/linux/pm_runtime.h: 276drivers/base/power/runtime.c and include/linux/pm_runtime.h:
277 277
278 void pm_runtime_init(struct device *dev); 278 void pm_runtime_init(struct device *dev);
279 - initialize the device run-time PM fields in 'struct dev_pm_info' 279 - initialize the device runtime PM fields in 'struct dev_pm_info'
280 280
281 void pm_runtime_remove(struct device *dev); 281 void pm_runtime_remove(struct device *dev);
282 - make sure that the run-time PM of the device will be disabled after 282 - make sure that the runtime PM of the device will be disabled after
283 removing the device from device hierarchy 283 removing the device from device hierarchy
284 284
285 int pm_runtime_idle(struct device *dev); 285 int pm_runtime_idle(struct device *dev);
@@ -289,9 +289,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
289 289
290 int pm_runtime_suspend(struct device *dev); 290 int pm_runtime_suspend(struct device *dev);
291 - execute the subsystem-level suspend callback for the device; returns 0 on 291 - execute the subsystem-level suspend callback for the device; returns 0 on
292 success, 1 if the device's run-time PM status was already 'suspended', or 292 success, 1 if the device's runtime PM status was already 'suspended', or
293 error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt 293 error code on failure, where -EAGAIN or -EBUSY means it is safe to attempt
294 to suspend the device again in future 294 to suspend the device again in future and -EACCES means that
295 'power.disable_depth' is different from 0
295 296
296 int pm_runtime_autosuspend(struct device *dev); 297 int pm_runtime_autosuspend(struct device *dev);
297 - same as pm_runtime_suspend() except that the autosuspend delay is taken 298 - same as pm_runtime_suspend() except that the autosuspend delay is taken
@@ -301,10 +302,11 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
301 302
302 int pm_runtime_resume(struct device *dev); 303 int pm_runtime_resume(struct device *dev);
303 - execute the subsystem-level resume callback for the device; returns 0 on 304 - execute the subsystem-level resume callback for the device; returns 0 on
304 success, 1 if the device's run-time PM status was already 'active' or 305 success, 1 if the device's runtime PM status was already 'active' or
305 error code on failure, where -EAGAIN means it may be safe to attempt to 306 error code on failure, where -EAGAIN means it may be safe to attempt to
306 resume the device again in future, but 'power.runtime_error' should be 307 resume the device again in future, but 'power.runtime_error' should be
307 checked additionally 308 checked additionally, and -EACCES means that 'power.disable_depth' is
309 different from 0
308 310
309 int pm_request_idle(struct device *dev); 311 int pm_request_idle(struct device *dev);
310 - submit a request to execute the subsystem-level idle callback for the 312 - submit a request to execute the subsystem-level idle callback for the
@@ -321,7 +323,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
321 device in future, where 'delay' is the time to wait before queuing up a 323 device in future, where 'delay' is the time to wait before queuing up a
322 suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work 324 suspend work item in pm_wq, in milliseconds (if 'delay' is zero, the work
323 item is queued up immediately); returns 0 on success, 1 if the device's PM 325 item is queued up immediately); returns 0 on success, 1 if the device's PM
324 run-time status was already 'suspended', or error code if the request 326 runtime status was already 'suspended', or error code if the request
325 hasn't been scheduled (or queued up if 'delay' is 0); if the execution of 327 hasn't been scheduled (or queued up if 'delay' is 0); if the execution of
326 ->runtime_suspend() is already scheduled and not yet expired, the new 328 ->runtime_suspend() is already scheduled and not yet expired, the new
327 value of 'delay' will be used as the time to wait 329 value of 'delay' will be used as the time to wait
@@ -329,7 +331,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
329 int pm_request_resume(struct device *dev); 331 int pm_request_resume(struct device *dev);
330 - submit a request to execute the subsystem-level resume callback for the 332 - submit a request to execute the subsystem-level resume callback for the
331 device (the request is represented by a work item in pm_wq); returns 0 on 333 device (the request is represented by a work item in pm_wq); returns 0 on
332 success, 1 if the device's run-time PM status was already 'active', or 334 success, 1 if the device's runtime PM status was already 'active', or
333 error code if the request hasn't been queued up 335 error code if the request hasn't been queued up
334 336
335 void pm_runtime_get_noresume(struct device *dev); 337 void pm_runtime_get_noresume(struct device *dev);
@@ -367,22 +369,32 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
367 pm_runtime_autosuspend(dev) and return its result 369 pm_runtime_autosuspend(dev) and return its result
368 370
369 void pm_runtime_enable(struct device *dev); 371 void pm_runtime_enable(struct device *dev);
370 - enable the run-time PM helper functions to run the device bus type's 372 - decrement the device's 'power.disable_depth' field; if that field is equal
371 run-time PM callbacks described in Section 2 373 to zero, the runtime PM helper functions can execute subsystem-level
374 callbacks described in Section 2 for the device
372 375
373 int pm_runtime_disable(struct device *dev); 376 int pm_runtime_disable(struct device *dev);
374 - prevent the run-time PM helper functions from running subsystem-level 377 - increment the device's 'power.disable_depth' field (if the value of that
375 run-time PM callbacks for the device, make sure that all of the pending 378 field was previously zero, this prevents subsystem-level runtime PM
376 run-time PM operations on the device are either completed or canceled; 379 callbacks from being run for the device), make sure that all of the pending
380 runtime PM operations on the device are either completed or canceled;
377 returns 1 if there was a resume request pending and it was necessary to 381 returns 1 if there was a resume request pending and it was necessary to
378 execute the subsystem-level resume callback for the device to satisfy that 382 execute the subsystem-level resume callback for the device to satisfy that
379 request, otherwise 0 is returned 383 request, otherwise 0 is returned
380 384
385 int pm_runtime_barrier(struct device *dev);
386 - check if there's a resume request pending for the device and resume it
387 (synchronously) in that case, cancel any other pending runtime PM requests
388 regarding it and wait for all runtime PM operations on it in progress to
389 complete; returns 1 if there was a resume request pending and it was
390 necessary to execute the subsystem-level resume callback for the device to
391 satisfy that request, otherwise 0 is returned
392
381 void pm_suspend_ignore_children(struct device *dev, bool enable); 393 void pm_suspend_ignore_children(struct device *dev, bool enable);
382 - set/unset the power.ignore_children flag of the device 394 - set/unset the power.ignore_children flag of the device
383 395
384 int pm_runtime_set_active(struct device *dev); 396 int pm_runtime_set_active(struct device *dev);
385 - clear the device's 'power.runtime_error' flag, set the device's run-time 397 - clear the device's 'power.runtime_error' flag, set the device's runtime
386 PM status to 'active' and update its parent's counter of 'active' 398 PM status to 'active' and update its parent's counter of 'active'
387 children as appropriate (it is only valid to use this function if 399 children as appropriate (it is only valid to use this function if
388 'power.runtime_error' is set or 'power.disable_depth' is greater than 400 'power.runtime_error' is set or 'power.disable_depth' is greater than
@@ -390,7 +402,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
390 which is not active and the 'power.ignore_children' flag of which is unset 402 which is not active and the 'power.ignore_children' flag of which is unset
391 403
392 void pm_runtime_set_suspended(struct device *dev); 404 void pm_runtime_set_suspended(struct device *dev);
393 - clear the device's 'power.runtime_error' flag, set the device's run-time 405 - clear the device's 'power.runtime_error' flag, set the device's runtime
394 PM status to 'suspended' and update its parent's counter of 'active' 406 PM status to 'suspended' and update its parent's counter of 'active'
395 children as appropriate (it is only valid to use this function if 407 children as appropriate (it is only valid to use this function if
396 'power.runtime_error' is set or 'power.disable_depth' is greater than 408 'power.runtime_error' is set or 'power.disable_depth' is greater than
@@ -400,6 +412,9 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
400 - return true if the device's runtime PM status is 'suspended' and its 412 - return true if the device's runtime PM status is 'suspended' and its
401 'power.disable_depth' field is equal to zero, or false otherwise 413 'power.disable_depth' field is equal to zero, or false otherwise
402 414
415 bool pm_runtime_status_suspended(struct device *dev);
416 - return true if the device's runtime PM status is 'suspended'
417
403 void pm_runtime_allow(struct device *dev); 418 void pm_runtime_allow(struct device *dev);
404 - set the power.runtime_auto flag for the device and decrease its usage 419 - set the power.runtime_auto flag for the device and decrease its usage
405 counter (used by the /sys/devices/.../power/control interface to 420 counter (used by the /sys/devices/.../power/control interface to
@@ -411,7 +426,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
411 effectively prevent the device from being power managed at run time) 426 effectively prevent the device from being power managed at run time)
412 427
413 void pm_runtime_no_callbacks(struct device *dev); 428 void pm_runtime_no_callbacks(struct device *dev);
414 - set the power.no_callbacks flag for the device and remove the run-time 429 - set the power.no_callbacks flag for the device and remove the runtime
415 PM attributes from /sys/devices/.../power (or prevent them from being 430 PM attributes from /sys/devices/.../power (or prevent them from being
416 added when the device is registered) 431 added when the device is registered)
417 432
@@ -431,7 +446,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
431 446
432 void pm_runtime_set_autosuspend_delay(struct device *dev, int delay); 447 void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
433 - set the power.autosuspend_delay value to 'delay' (expressed in 448 - set the power.autosuspend_delay value to 'delay' (expressed in
434 milliseconds); if 'delay' is negative then run-time suspends are 449 milliseconds); if 'delay' is negative then runtime suspends are
435 prevented 450 prevented
436 451
437 unsigned long pm_runtime_autosuspend_expiration(struct device *dev); 452 unsigned long pm_runtime_autosuspend_expiration(struct device *dev);
@@ -470,35 +485,35 @@ pm_runtime_resume()
470pm_runtime_get_sync() 485pm_runtime_get_sync()
471pm_runtime_put_sync_suspend() 486pm_runtime_put_sync_suspend()
472 487
4735. Run-time PM Initialization, Device Probing and Removal 4885. Runtime PM Initialization, Device Probing and Removal
474 489
475Initially, the run-time PM is disabled for all devices, which means that the 490Initially, the runtime PM is disabled for all devices, which means that the
476majority of the run-time PM helper funtions described in Section 4 will return 491majority of the runtime PM helper funtions described in Section 4 will return
477-EAGAIN until pm_runtime_enable() is called for the device. 492-EAGAIN until pm_runtime_enable() is called for the device.
478 493
479In addition to that, the initial run-time PM status of all devices is 494In addition to that, the initial runtime PM status of all devices is
480'suspended', but it need not reflect the actual physical state of the device. 495'suspended', but it need not reflect the actual physical state of the device.
481Thus, if the device is initially active (i.e. it is able to process I/O), its 496Thus, if the device is initially active (i.e. it is able to process I/O), its
482run-time PM status must be changed to 'active', with the help of 497runtime PM status must be changed to 'active', with the help of
483pm_runtime_set_active(), before pm_runtime_enable() is called for the device. 498pm_runtime_set_active(), before pm_runtime_enable() is called for the device.
484 499
485However, if the device has a parent and the parent's run-time PM is enabled, 500However, if the device has a parent and the parent's runtime PM is enabled,
486calling pm_runtime_set_active() for the device will affect the parent, unless 501calling pm_runtime_set_active() for the device will affect the parent, unless
487the parent's 'power.ignore_children' flag is set. Namely, in that case the 502the parent's 'power.ignore_children' flag is set. Namely, in that case the
488parent won't be able to suspend at run time, using the PM core's helper 503parent won't be able to suspend at run time, using the PM core's helper
489functions, as long as the child's status is 'active', even if the child's 504functions, as long as the child's status is 'active', even if the child's
490run-time PM is still disabled (i.e. pm_runtime_enable() hasn't been called for 505runtime PM is still disabled (i.e. pm_runtime_enable() hasn't been called for
491the child yet or pm_runtime_disable() has been called for it). For this reason, 506the child yet or pm_runtime_disable() has been called for it). For this reason,
492once pm_runtime_set_active() has been called for the device, pm_runtime_enable() 507once pm_runtime_set_active() has been called for the device, pm_runtime_enable()
493should be called for it too as soon as reasonably possible or its run-time PM 508should be called for it too as soon as reasonably possible or its runtime PM
494status should be changed back to 'suspended' with the help of 509status should be changed back to 'suspended' with the help of
495pm_runtime_set_suspended(). 510pm_runtime_set_suspended().
496 511
497If the default initial run-time PM status of the device (i.e. 'suspended') 512If the default initial runtime PM status of the device (i.e. 'suspended')
498reflects the actual state of the device, its bus type's or its driver's 513reflects the actual state of the device, its bus type's or its driver's
499->probe() callback will likely need to wake it up using one of the PM core's 514->probe() callback will likely need to wake it up using one of the PM core's
500helper functions described in Section 4. In that case, pm_runtime_resume() 515helper functions described in Section 4. In that case, pm_runtime_resume()
501should be used. Of course, for this purpose the device's run-time PM has to be 516should be used. Of course, for this purpose the device's runtime PM has to be
502enabled earlier by calling pm_runtime_enable(). 517enabled earlier by calling pm_runtime_enable().
503 518
504If the device bus type's or driver's ->probe() callback runs 519If the device bus type's or driver's ->probe() callback runs
@@ -529,33 +544,33 @@ The user space can effectively disallow the driver of the device to power manage
529it at run time by changing the value of its /sys/devices/.../power/control 544it at run time by changing the value of its /sys/devices/.../power/control
530attribute to "on", which causes pm_runtime_forbid() to be called. In principle, 545attribute to "on", which causes pm_runtime_forbid() to be called. In principle,
531this mechanism may also be used by the driver to effectively turn off the 546this mechanism may also be used by the driver to effectively turn off the
532run-time power management of the device until the user space turns it on. 547runtime power management of the device until the user space turns it on.
533Namely, during the initialization the driver can make sure that the run-time PM 548Namely, during the initialization the driver can make sure that the runtime PM
534status of the device is 'active' and call pm_runtime_forbid(). It should be 549status of the device is 'active' and call pm_runtime_forbid(). It should be
535noted, however, that if the user space has already intentionally changed the 550noted, however, that if the user space has already intentionally changed the
536value of /sys/devices/.../power/control to "auto" to allow the driver to power 551value of /sys/devices/.../power/control to "auto" to allow the driver to power
537manage the device at run time, the driver may confuse it by using 552manage the device at run time, the driver may confuse it by using
538pm_runtime_forbid() this way. 553pm_runtime_forbid() this way.
539 554
5406. Run-time PM and System Sleep 5556. Runtime PM and System Sleep
541 556
542Run-time PM and system sleep (i.e., system suspend and hibernation, also known 557Runtime PM and system sleep (i.e., system suspend and hibernation, also known
543as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of 558as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
544ways. If a device is active when a system sleep starts, everything is 559ways. If a device is active when a system sleep starts, everything is
545straightforward. But what should happen if the device is already suspended? 560straightforward. But what should happen if the device is already suspended?
546 561
547The device may have different wake-up settings for run-time PM and system sleep. 562The device may have different wake-up settings for runtime PM and system sleep.
548For example, remote wake-up may be enabled for run-time suspend but disallowed 563For example, remote wake-up may be enabled for runtime suspend but disallowed
549for system sleep (device_may_wakeup(dev) returns 'false'). When this happens, 564for system sleep (device_may_wakeup(dev) returns 'false'). When this happens,
550the subsystem-level system suspend callback is responsible for changing the 565the subsystem-level system suspend callback is responsible for changing the
551device's wake-up setting (it may leave that to the device driver's system 566device's wake-up setting (it may leave that to the device driver's system
552suspend routine). It may be necessary to resume the device and suspend it again 567suspend routine). It may be necessary to resume the device and suspend it again
553in order to do so. The same is true if the driver uses different power levels 568in order to do so. The same is true if the driver uses different power levels
554or other settings for run-time suspend and system sleep. 569or other settings for runtime suspend and system sleep.
555 570
556During system resume, devices generally should be brought back to full power, 571During system resume, the simplest approach is to bring all devices back to full
557even if they were suspended before the system sleep began. There are several 572power, even if they had been suspended before the system suspend began. There
558reasons for this, including: 573are several reasons for this, including:
559 574
560 * The device might need to switch power levels, wake-up settings, etc. 575 * The device might need to switch power levels, wake-up settings, etc.
561 576
@@ -570,18 +585,50 @@ reasons for this, including:
570 * The device might need to be reset. 585 * The device might need to be reset.
571 586
572 * Even though the device was suspended, if its usage counter was > 0 then most 587 * Even though the device was suspended, if its usage counter was > 0 then most
573 likely it would need a run-time resume in the near future anyway. 588 likely it would need a runtime resume in the near future anyway.
574 589
575 * Always going back to full power is simplest. 590If the device had been suspended before the system suspend began and it's
576 591brought back to full power during resume, then its runtime PM status will have
577If the device was suspended before the sleep began, then its run-time PM status 592to be updated to reflect the actual post-system sleep status. The way to do
578will have to be updated to reflect the actual post-system sleep status. The way 593this is:
579to do this is:
580 594
581 pm_runtime_disable(dev); 595 pm_runtime_disable(dev);
582 pm_runtime_set_active(dev); 596 pm_runtime_set_active(dev);
583 pm_runtime_enable(dev); 597 pm_runtime_enable(dev);
584 598
599The PM core always increments the runtime usage counter before calling the
600->suspend() callback and decrements it after calling the ->resume() callback.
601Hence disabling runtime PM temporarily like this will not cause any runtime
602suspend attempts to be permanently lost. If the usage count goes to zero
603following the return of the ->resume() callback, the ->runtime_idle() callback
604will be invoked as usual.
605
606On some systems, however, system sleep is not entered through a global firmware
607or hardware operation. Instead, all hardware components are put into low-power
608states directly by the kernel in a coordinated way. Then, the system sleep
609state effectively follows from the states the hardware components end up in
610and the system is woken up from that state by a hardware interrupt or a similar
611mechanism entirely under the kernel's control. As a result, the kernel never
612gives control away and the states of all devices during resume are precisely
613known to it. If that is the case and none of the situations listed above takes
614place (in particular, if the system is not waking up from hibernation), it may
615be more efficient to leave the devices that had been suspended before the system
616suspend began in the suspended state.
617
618The PM core does its best to reduce the probability of race conditions between
619the runtime PM and system suspend/resume (and hibernation) callbacks by carrying
620out the following operations:
621
622 * During system suspend it calls pm_runtime_get_noresume() and
623 pm_runtime_barrier() for every device right before executing the
624 subsystem-level .suspend() callback for it. In addition to that it calls
625 pm_runtime_disable() for every device right after executing the
626 subsystem-level .suspend() callback for it.
627
628 * During system resume it calls pm_runtime_enable() and pm_runtime_put_sync()
629 for every device right before and right after executing the subsystem-level
630 .resume() callback for it, respectively.
631
5857. Generic subsystem callbacks 6327. Generic subsystem callbacks
586 633
587Subsystems may wish to conserve code space by using the set of generic power 634Subsystems may wish to conserve code space by using the set of generic power
@@ -666,8 +713,8 @@ the GENERIC_SUBSYS_PM_OPS macro, defined in include/linux/pm.h, to its
666dev_pm_ops structure pointer. 713dev_pm_ops structure pointer.
667 714
668Device drivers that wish to use the same function as a system suspend, freeze, 715Device drivers that wish to use the same function as a system suspend, freeze,
669poweroff and run-time suspend callback, and similarly for system resume, thaw, 716poweroff and runtime suspend callback, and similarly for system resume, thaw,
670restore, and run-time resume, can achieve this with the help of the 717restore, and runtime resume, can achieve this with the help of the
671UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its 718UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its
672last argument to NULL). 719last argument to NULL).
673 720
@@ -677,7 +724,7 @@ Some "devices" are only logical sub-devices of their parent and cannot be
677power-managed on their own. (The prototype example is a USB interface. Entire 724power-managed on their own. (The prototype example is a USB interface. Entire
678USB devices can go into low-power mode or send wake-up requests, but neither is 725USB devices can go into low-power mode or send wake-up requests, but neither is
679possible for individual interfaces.) The drivers for these devices have no 726possible for individual interfaces.) The drivers for these devices have no
680need of run-time PM callbacks; if the callbacks did exist, ->runtime_suspend() 727need of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend()
681and ->runtime_resume() would always return 0 without doing anything else and 728and ->runtime_resume() would always return 0 without doing anything else and
682->runtime_idle() would always call pm_runtime_suspend(). 729->runtime_idle() would always call pm_runtime_suspend().
683 730
@@ -685,7 +732,7 @@ Subsystems can tell the PM core about these devices by calling
685pm_runtime_no_callbacks(). This should be done after the device structure is 732pm_runtime_no_callbacks(). This should be done after the device structure is
686initialized and before it is registered (although after device registration is 733initialized and before it is registered (although after device registration is
687also okay). The routine will set the device's power.no_callbacks flag and 734also okay). The routine will set the device's power.no_callbacks flag and
688prevent the non-debugging run-time PM sysfs attributes from being created. 735prevent the non-debugging runtime PM sysfs attributes from being created.
689 736
690When power.no_callbacks is set, the PM core will not invoke the 737When power.no_callbacks is set, the PM core will not invoke the
691->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks. 738->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks.
@@ -693,7 +740,7 @@ Instead it will assume that suspends and resumes always succeed and that idle
693devices should be suspended. 740devices should be suspended.
694 741
695As a consequence, the PM core will never directly inform the device's subsystem 742As a consequence, the PM core will never directly inform the device's subsystem
696or driver about run-time power changes. Instead, the driver for the device's 743or driver about runtime power changes. Instead, the driver for the device's
697parent must take responsibility for telling the device's driver when the 744parent must take responsibility for telling the device's driver when the
698parent's power state changes. 745parent's power state changes.
699 746
@@ -704,13 +751,13 @@ A device should be put in a low-power state only when there's some reason to
704think it will remain in that state for a substantial time. A common heuristic 751think it will remain in that state for a substantial time. A common heuristic
705says that a device which hasn't been used for a while is liable to remain 752says that a device which hasn't been used for a while is liable to remain
706unused; following this advice, drivers should not allow devices to be suspended 753unused; following this advice, drivers should not allow devices to be suspended
707at run-time until they have been inactive for some minimum period. Even when 754at runtime until they have been inactive for some minimum period. Even when
708the heuristic ends up being non-optimal, it will still prevent devices from 755the heuristic ends up being non-optimal, it will still prevent devices from
709"bouncing" too rapidly between low-power and full-power states. 756"bouncing" too rapidly between low-power and full-power states.
710 757
711The term "autosuspend" is an historical remnant. It doesn't mean that the 758The term "autosuspend" is an historical remnant. It doesn't mean that the
712device is automatically suspended (the subsystem or driver still has to call 759device is automatically suspended (the subsystem or driver still has to call
713the appropriate PM routines); rather it means that run-time suspends will 760the appropriate PM routines); rather it means that runtime suspends will
714automatically be delayed until the desired period of inactivity has elapsed. 761automatically be delayed until the desired period of inactivity has elapsed.
715 762
716Inactivity is determined based on the power.last_busy field. Drivers should 763Inactivity is determined based on the power.last_busy field. Drivers should