aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/power
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/power')
-rw-r--r--Documentation/power/runtime_pm.txt130
1 files changed, 65 insertions, 65 deletions
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt
index ca15bbbe1891..40e47c75f064 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,7 +289,7 @@ 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 and -EACCES means that 294 to suspend the device again in future and -EACCES means that
295 'power.disable_depth' is different from 0 295 'power.disable_depth' is different from 0
@@ -302,7 +302,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
302 302
303 int pm_runtime_resume(struct device *dev); 303 int pm_runtime_resume(struct device *dev);
304 - 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
305 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
306 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
307 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
308 checked additionally, and -EACCES means that 'power.disable_depth' is 308 checked additionally, and -EACCES means that 'power.disable_depth' is
@@ -323,7 +323,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
323 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
324 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
325 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
326 run-time status was already 'suspended', or error code if the request 326 runtime status was already 'suspended', or error code if the request
327 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
328 ->runtime_suspend() is already scheduled and not yet expired, the new 328 ->runtime_suspend() is already scheduled and not yet expired, the new
329 value of 'delay' will be used as the time to wait 329 value of 'delay' will be used as the time to wait
@@ -331,7 +331,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
331 int pm_request_resume(struct device *dev); 331 int pm_request_resume(struct device *dev);
332 - 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
333 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
334 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
335 error code if the request hasn't been queued up 335 error code if the request hasn't been queued up
336 336
337 void pm_runtime_get_noresume(struct device *dev); 337 void pm_runtime_get_noresume(struct device *dev);
@@ -370,14 +370,14 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
370 370
371 void pm_runtime_enable(struct device *dev); 371 void pm_runtime_enable(struct device *dev);
372 - decrement the device's 'power.disable_depth' field; if that field is equal 372 - decrement the device's 'power.disable_depth' field; if that field is equal
373 to zero, the run-time PM helper functions can execute subsystem-level 373 to zero, the runtime PM helper functions can execute subsystem-level
374 callbacks described in Section 2 for the device 374 callbacks described in Section 2 for the device
375 375
376 int pm_runtime_disable(struct device *dev); 376 int pm_runtime_disable(struct device *dev);
377 - increment the device's 'power.disable_depth' field (if the value of that 377 - increment the device's 'power.disable_depth' field (if the value of that
378 field was previously zero, this prevents subsystem-level runtime PM 378 field was previously zero, this prevents subsystem-level runtime PM
379 callbacks from being run for the device), make sure that all of the pending 379 callbacks from being run for the device), make sure that all of the pending
380 run-time PM operations on the device are either completed or canceled; 380 runtime PM operations on the device are either completed or canceled;
381 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
382 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
383 request, otherwise 0 is returned 383 request, otherwise 0 is returned
@@ -394,7 +394,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
394 - set/unset the power.ignore_children flag of the device 394 - set/unset the power.ignore_children flag of the device
395 395
396 int pm_runtime_set_active(struct device *dev); 396 int pm_runtime_set_active(struct device *dev);
397 - 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
398 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'
399 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
400 '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
@@ -402,7 +402,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
402 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
403 403
404 void pm_runtime_set_suspended(struct device *dev); 404 void pm_runtime_set_suspended(struct device *dev);
405 - 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
406 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'
407 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
408 '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
@@ -423,7 +423,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
423 effectively prevent the device from being power managed at run time) 423 effectively prevent the device from being power managed at run time)
424 424
425 void pm_runtime_no_callbacks(struct device *dev); 425 void pm_runtime_no_callbacks(struct device *dev);
426 - set the power.no_callbacks flag for the device and remove the run-time 426 - set the power.no_callbacks flag for the device and remove the runtime
427 PM attributes from /sys/devices/.../power (or prevent them from being 427 PM attributes from /sys/devices/.../power (or prevent them from being
428 added when the device is registered) 428 added when the device is registered)
429 429
@@ -443,7 +443,7 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h:
443 443
444 void pm_runtime_set_autosuspend_delay(struct device *dev, int delay); 444 void pm_runtime_set_autosuspend_delay(struct device *dev, int delay);
445 - set the power.autosuspend_delay value to 'delay' (expressed in 445 - set the power.autosuspend_delay value to 'delay' (expressed in
446 milliseconds); if 'delay' is negative then run-time suspends are 446 milliseconds); if 'delay' is negative then runtime suspends are
447 prevented 447 prevented
448 448
449 unsigned long pm_runtime_autosuspend_expiration(struct device *dev); 449 unsigned long pm_runtime_autosuspend_expiration(struct device *dev);
@@ -482,35 +482,35 @@ pm_runtime_resume()
482pm_runtime_get_sync() 482pm_runtime_get_sync()
483pm_runtime_put_sync_suspend() 483pm_runtime_put_sync_suspend()
484 484
4855. Run-time PM Initialization, Device Probing and Removal 4855. Runtime PM Initialization, Device Probing and Removal
486 486
487Initially, the run-time PM is disabled for all devices, which means that the 487Initially, the runtime PM is disabled for all devices, which means that the
488majority of the run-time PM helper funtions described in Section 4 will return 488majority of the runtime PM helper funtions described in Section 4 will return
489-EAGAIN until pm_runtime_enable() is called for the device. 489-EAGAIN until pm_runtime_enable() is called for the device.
490 490
491In addition to that, the initial run-time PM status of all devices is 491In addition to that, the initial runtime PM status of all devices is
492'suspended', but it need not reflect the actual physical state of the device. 492'suspended', but it need not reflect the actual physical state of the device.
493Thus, if the device is initially active (i.e. it is able to process I/O), its 493Thus, if the device is initially active (i.e. it is able to process I/O), its
494run-time PM status must be changed to 'active', with the help of 494runtime PM status must be changed to 'active', with the help of
495pm_runtime_set_active(), before pm_runtime_enable() is called for the device. 495pm_runtime_set_active(), before pm_runtime_enable() is called for the device.
496 496
497However, if the device has a parent and the parent's run-time PM is enabled, 497However, if the device has a parent and the parent's runtime PM is enabled,
498calling pm_runtime_set_active() for the device will affect the parent, unless 498calling pm_runtime_set_active() for the device will affect the parent, unless
499the parent's 'power.ignore_children' flag is set. Namely, in that case the 499the parent's 'power.ignore_children' flag is set. Namely, in that case the
500parent won't be able to suspend at run time, using the PM core's helper 500parent won't be able to suspend at run time, using the PM core's helper
501functions, as long as the child's status is 'active', even if the child's 501functions, as long as the child's status is 'active', even if the child's
502run-time PM is still disabled (i.e. pm_runtime_enable() hasn't been called for 502runtime PM is still disabled (i.e. pm_runtime_enable() hasn't been called for
503the child yet or pm_runtime_disable() has been called for it). For this reason, 503the child yet or pm_runtime_disable() has been called for it). For this reason,
504once pm_runtime_set_active() has been called for the device, pm_runtime_enable() 504once pm_runtime_set_active() has been called for the device, pm_runtime_enable()
505should be called for it too as soon as reasonably possible or its run-time PM 505should be called for it too as soon as reasonably possible or its runtime PM
506status should be changed back to 'suspended' with the help of 506status should be changed back to 'suspended' with the help of
507pm_runtime_set_suspended(). 507pm_runtime_set_suspended().
508 508
509If the default initial run-time PM status of the device (i.e. 'suspended') 509If the default initial runtime PM status of the device (i.e. 'suspended')
510reflects the actual state of the device, its bus type's or its driver's 510reflects the actual state of the device, its bus type's or its driver's
511->probe() callback will likely need to wake it up using one of the PM core's 511->probe() callback will likely need to wake it up using one of the PM core's
512helper functions described in Section 4. In that case, pm_runtime_resume() 512helper functions described in Section 4. In that case, pm_runtime_resume()
513should be used. Of course, for this purpose the device's run-time PM has to be 513should be used. Of course, for this purpose the device's runtime PM has to be
514enabled earlier by calling pm_runtime_enable(). 514enabled earlier by calling pm_runtime_enable().
515 515
516If the device bus type's or driver's ->probe() callback runs 516If the device bus type's or driver's ->probe() callback runs
@@ -541,29 +541,29 @@ The user space can effectively disallow the driver of the device to power manage
541it at run time by changing the value of its /sys/devices/.../power/control 541it at run time by changing the value of its /sys/devices/.../power/control
542attribute to "on", which causes pm_runtime_forbid() to be called. In principle, 542attribute to "on", which causes pm_runtime_forbid() to be called. In principle,
543this mechanism may also be used by the driver to effectively turn off the 543this mechanism may also be used by the driver to effectively turn off the
544run-time power management of the device until the user space turns it on. 544runtime power management of the device until the user space turns it on.
545Namely, during the initialization the driver can make sure that the run-time PM 545Namely, during the initialization the driver can make sure that the runtime PM
546status of the device is 'active' and call pm_runtime_forbid(). It should be 546status of the device is 'active' and call pm_runtime_forbid(). It should be
547noted, however, that if the user space has already intentionally changed the 547noted, however, that if the user space has already intentionally changed the
548value of /sys/devices/.../power/control to "auto" to allow the driver to power 548value of /sys/devices/.../power/control to "auto" to allow the driver to power
549manage the device at run time, the driver may confuse it by using 549manage the device at run time, the driver may confuse it by using
550pm_runtime_forbid() this way. 550pm_runtime_forbid() this way.
551 551
5526. Run-time PM and System Sleep 5526. Runtime PM and System Sleep
553 553
554Run-time PM and system sleep (i.e., system suspend and hibernation, also known 554Runtime PM and system sleep (i.e., system suspend and hibernation, also known
555as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of 555as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of
556ways. If a device is active when a system sleep starts, everything is 556ways. If a device is active when a system sleep starts, everything is
557straightforward. But what should happen if the device is already suspended? 557straightforward. But what should happen if the device is already suspended?
558 558
559The device may have different wake-up settings for run-time PM and system sleep. 559The device may have different wake-up settings for runtime PM and system sleep.
560For example, remote wake-up may be enabled for run-time suspend but disallowed 560For example, remote wake-up may be enabled for runtime suspend but disallowed
561for system sleep (device_may_wakeup(dev) returns 'false'). When this happens, 561for system sleep (device_may_wakeup(dev) returns 'false'). When this happens,
562the subsystem-level system suspend callback is responsible for changing the 562the subsystem-level system suspend callback is responsible for changing the
563device's wake-up setting (it may leave that to the device driver's system 563device's wake-up setting (it may leave that to the device driver's system
564suspend routine). It may be necessary to resume the device and suspend it again 564suspend routine). It may be necessary to resume the device and suspend it again
565in order to do so. The same is true if the driver uses different power levels 565in order to do so. The same is true if the driver uses different power levels
566or other settings for run-time suspend and system sleep. 566or other settings for runtime suspend and system sleep.
567 567
568During system resume, the simplest approach is to bring all devices back to full 568During system resume, the simplest approach is to bring all devices back to full
569power, even if they had been suspended before the system suspend began. There 569power, even if they had been suspended before the system suspend began. There
@@ -582,10 +582,10 @@ are several reasons for this, including:
582 * The device might need to be reset. 582 * The device might need to be reset.
583 583
584 * Even though the device was suspended, if its usage counter was > 0 then most 584 * Even though the device was suspended, if its usage counter was > 0 then most
585 likely it would need a run-time resume in the near future anyway. 585 likely it would need a runtime resume in the near future anyway.
586 586
587If the device had been suspended before the system suspend began and it's 587If the device had been suspended before the system suspend began and it's
588brought back to full power during resume, then its run-time PM status will have 588brought back to full power during resume, then its runtime PM status will have
589to be updated to reflect the actual post-system sleep status. The way to do 589to be updated to reflect the actual post-system sleep status. The way to do
590this is: 590this is:
591 591
@@ -593,9 +593,9 @@ this is:
593 pm_runtime_set_active(dev); 593 pm_runtime_set_active(dev);
594 pm_runtime_enable(dev); 594 pm_runtime_enable(dev);
595 595
596The PM core always increments the run-time usage counter before calling the 596The PM core always increments the runtime usage counter before calling the
597->suspend() callback and decrements it after calling the ->resume() callback. 597->suspend() callback and decrements it after calling the ->resume() callback.
598Hence disabling run-time PM temporarily like this will not cause any runtime 598Hence disabling runtime PM temporarily like this will not cause any runtime
599suspend attempts to be permanently lost. If the usage count goes to zero 599suspend attempts to be permanently lost. If the usage count goes to zero
600following the return of the ->resume() callback, the ->runtime_idle() callback 600following the return of the ->resume() callback, the ->runtime_idle() callback
601will be invoked as usual. 601will be invoked as usual.
@@ -710,8 +710,8 @@ the GENERIC_SUBSYS_PM_OPS macro, defined in include/linux/pm.h, to its
710dev_pm_ops structure pointer. 710dev_pm_ops structure pointer.
711 711
712Device drivers that wish to use the same function as a system suspend, freeze, 712Device drivers that wish to use the same function as a system suspend, freeze,
713poweroff and run-time suspend callback, and similarly for system resume, thaw, 713poweroff and runtime suspend callback, and similarly for system resume, thaw,
714restore, and run-time resume, can achieve this with the help of the 714restore, and runtime resume, can achieve this with the help of the
715UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its 715UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its
716last argument to NULL). 716last argument to NULL).
717 717
@@ -721,7 +721,7 @@ Some "devices" are only logical sub-devices of their parent and cannot be
721power-managed on their own. (The prototype example is a USB interface. Entire 721power-managed on their own. (The prototype example is a USB interface. Entire
722USB devices can go into low-power mode or send wake-up requests, but neither is 722USB devices can go into low-power mode or send wake-up requests, but neither is
723possible for individual interfaces.) The drivers for these devices have no 723possible for individual interfaces.) The drivers for these devices have no
724need of run-time PM callbacks; if the callbacks did exist, ->runtime_suspend() 724need of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend()
725and ->runtime_resume() would always return 0 without doing anything else and 725and ->runtime_resume() would always return 0 without doing anything else and
726->runtime_idle() would always call pm_runtime_suspend(). 726->runtime_idle() would always call pm_runtime_suspend().
727 727
@@ -729,7 +729,7 @@ Subsystems can tell the PM core about these devices by calling
729pm_runtime_no_callbacks(). This should be done after the device structure is 729pm_runtime_no_callbacks(). This should be done after the device structure is
730initialized and before it is registered (although after device registration is 730initialized and before it is registered (although after device registration is
731also okay). The routine will set the device's power.no_callbacks flag and 731also okay). The routine will set the device's power.no_callbacks flag and
732prevent the non-debugging run-time PM sysfs attributes from being created. 732prevent the non-debugging runtime PM sysfs attributes from being created.
733 733
734When power.no_callbacks is set, the PM core will not invoke the 734When power.no_callbacks is set, the PM core will not invoke the
735->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks. 735->runtime_idle(), ->runtime_suspend(), or ->runtime_resume() callbacks.
@@ -737,7 +737,7 @@ Instead it will assume that suspends and resumes always succeed and that idle
737devices should be suspended. 737devices should be suspended.
738 738
739As a consequence, the PM core will never directly inform the device's subsystem 739As a consequence, the PM core will never directly inform the device's subsystem
740or driver about run-time power changes. Instead, the driver for the device's 740or driver about runtime power changes. Instead, the driver for the device's
741parent must take responsibility for telling the device's driver when the 741parent must take responsibility for telling the device's driver when the
742parent's power state changes. 742parent's power state changes.
743 743
@@ -748,13 +748,13 @@ A device should be put in a low-power state only when there's some reason to
748think it will remain in that state for a substantial time. A common heuristic 748think it will remain in that state for a substantial time. A common heuristic
749says that a device which hasn't been used for a while is liable to remain 749says that a device which hasn't been used for a while is liable to remain
750unused; following this advice, drivers should not allow devices to be suspended 750unused; following this advice, drivers should not allow devices to be suspended
751at run-time until they have been inactive for some minimum period. Even when 751at runtime until they have been inactive for some minimum period. Even when
752the heuristic ends up being non-optimal, it will still prevent devices from 752the heuristic ends up being non-optimal, it will still prevent devices from
753"bouncing" too rapidly between low-power and full-power states. 753"bouncing" too rapidly between low-power and full-power states.
754 754
755The term "autosuspend" is an historical remnant. It doesn't mean that the 755The term "autosuspend" is an historical remnant. It doesn't mean that the
756device is automatically suspended (the subsystem or driver still has to call 756device is automatically suspended (the subsystem or driver still has to call
757the appropriate PM routines); rather it means that run-time suspends will 757the appropriate PM routines); rather it means that runtime suspends will
758automatically be delayed until the desired period of inactivity has elapsed. 758automatically be delayed until the desired period of inactivity has elapsed.
759 759
760Inactivity is determined based on the power.last_busy field. Drivers should 760Inactivity is determined based on the power.last_busy field. Drivers should