diff options
author | Rafael J. Wysocki <rjw@sisk.pl> | 2011-07-15 17:59:25 -0400 |
---|---|---|
committer | Rafael J. Wysocki <rjw@sisk.pl> | 2011-07-15 17:59:25 -0400 |
commit | 7ae033cc0dfce68d8e0c83aca60837cf2bf0d2e6 (patch) | |
tree | 91bb3b8ae2790c7fef06b1832a7df61ae496a77a /Documentation | |
parent | ba1389d74f34c0c6e95cc135a332cd29c29d9c20 (diff) | |
parent | c8c9fda5069456eb9e0e403c19764b2e257802e1 (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.txt | 6 | ||||
-rw-r--r-- | Documentation/power/runtime_pm.txt | 197 |
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 | |||
604 | disabled. This all depends on the hardware and the design of the subsystem and | 604 | disabled. This all depends on the hardware and the design of the subsystem and |
605 | device driver in question. | 605 | device driver in question. |
606 | 606 | ||
607 | During system-wide resume from a sleep state it's best to put devices into the | 607 | During system-wide resume from a sleep state it's easiest to put devices into |
608 | full-power state, as explained in Documentation/power/runtime_pm.txt. Refer to | 608 | the full-power state, as explained in Documentation/power/runtime_pm.txt. Refer |
609 | that document for more information regarding this particular issue as well as | 609 | to that document for more information regarding this particular issue as well as |
610 | for information on the device runtime power management framework in general. | 610 | for 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 @@ | |||
1 | Run-time Power Management Framework for I/O Devices | 1 | Runtime 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 | ||
6 | 1. Introduction | 6 | 1. Introduction |
7 | 7 | ||
8 | Support for run-time power management (run-time PM) of I/O devices is provided | 8 | Support for runtime power management (runtime PM) of I/O devices is provided |
9 | at the power management core (PM core) level by means of: | 9 | at 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 | ||
30 | The run-time PM callbacks present in 'struct dev_pm_ops', the device run-time PM | 30 | The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM |
31 | fields of 'struct dev_pm_info' and the core helper functions provided for | 31 | fields of 'struct dev_pm_info' and the core helper functions provided for |
32 | run-time PM are described below. | 32 | runtime PM are described below. |
33 | 33 | ||
34 | 2. Device Run-time PM Callbacks | 34 | 2. Device Runtime PM Callbacks |
35 | 35 | ||
36 | There are three device run-time PM callbacks defined in 'struct dev_pm_ops': | 36 | There are three device runtime PM callbacks defined in 'struct dev_pm_ops': |
37 | 37 | ||
38 | struct dev_pm_ops { | 38 | struct 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 | |||
130 | core. | 130 | core. |
131 | 131 | ||
132 | The helper functions provided by the PM core, described in Section 4, guarantee | 132 | The helper functions provided by the PM core, described in Section 4, guarantee |
133 | that the following constraints are met with respect to the bus type's run-time | 133 | that the following constraints are met with respect to the bus type's runtime |
134 | PM callbacks: | 134 | PM 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 | ||
157 | Additionally, the helper functions provided by the PM core obey the following | 157 | Additionally, 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 | ||
174 | 3. Run-time PM Device Fields | 174 | 3. Runtime PM Device Fields |
175 | 175 | ||
176 | The following device run-time PM fields are present in 'struct dev_pm_info', as | 176 | The following device runtime PM fields are present in 'struct dev_pm_info', as |
177 | defined in include/linux/pm.h: | 177 | defined 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 | ||
271 | All of the above fields are members of the 'power' member of 'struct device'. | 271 | All of the above fields are members of the 'power' member of 'struct device'. |
272 | 272 | ||
273 | 4. Run-time PM Device Helper Functions | 273 | 4. Runtime PM Device Helper Functions |
274 | 274 | ||
275 | The following run-time PM helper functions are defined in | 275 | The following runtime PM helper functions are defined in |
276 | drivers/base/power/runtime.c and include/linux/pm_runtime.h: | 276 | drivers/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() | |||
470 | pm_runtime_get_sync() | 485 | pm_runtime_get_sync() |
471 | pm_runtime_put_sync_suspend() | 486 | pm_runtime_put_sync_suspend() |
472 | 487 | ||
473 | 5. Run-time PM Initialization, Device Probing and Removal | 488 | 5. Runtime PM Initialization, Device Probing and Removal |
474 | 489 | ||
475 | Initially, the run-time PM is disabled for all devices, which means that the | 490 | Initially, the runtime PM is disabled for all devices, which means that the |
476 | majority of the run-time PM helper funtions described in Section 4 will return | 491 | majority 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 | ||
479 | In addition to that, the initial run-time PM status of all devices is | 494 | In 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. |
481 | Thus, if the device is initially active (i.e. it is able to process I/O), its | 496 | Thus, if the device is initially active (i.e. it is able to process I/O), its |
482 | run-time PM status must be changed to 'active', with the help of | 497 | runtime PM status must be changed to 'active', with the help of |
483 | pm_runtime_set_active(), before pm_runtime_enable() is called for the device. | 498 | pm_runtime_set_active(), before pm_runtime_enable() is called for the device. |
484 | 499 | ||
485 | However, if the device has a parent and the parent's run-time PM is enabled, | 500 | However, if the device has a parent and the parent's runtime PM is enabled, |
486 | calling pm_runtime_set_active() for the device will affect the parent, unless | 501 | calling pm_runtime_set_active() for the device will affect the parent, unless |
487 | the parent's 'power.ignore_children' flag is set. Namely, in that case the | 502 | the parent's 'power.ignore_children' flag is set. Namely, in that case the |
488 | parent won't be able to suspend at run time, using the PM core's helper | 503 | parent won't be able to suspend at run time, using the PM core's helper |
489 | functions, as long as the child's status is 'active', even if the child's | 504 | functions, as long as the child's status is 'active', even if the child's |
490 | run-time PM is still disabled (i.e. pm_runtime_enable() hasn't been called for | 505 | runtime PM is still disabled (i.e. pm_runtime_enable() hasn't been called for |
491 | the child yet or pm_runtime_disable() has been called for it). For this reason, | 506 | the child yet or pm_runtime_disable() has been called for it). For this reason, |
492 | once pm_runtime_set_active() has been called for the device, pm_runtime_enable() | 507 | once pm_runtime_set_active() has been called for the device, pm_runtime_enable() |
493 | should be called for it too as soon as reasonably possible or its run-time PM | 508 | should be called for it too as soon as reasonably possible or its runtime PM |
494 | status should be changed back to 'suspended' with the help of | 509 | status should be changed back to 'suspended' with the help of |
495 | pm_runtime_set_suspended(). | 510 | pm_runtime_set_suspended(). |
496 | 511 | ||
497 | If the default initial run-time PM status of the device (i.e. 'suspended') | 512 | If the default initial runtime PM status of the device (i.e. 'suspended') |
498 | reflects the actual state of the device, its bus type's or its driver's | 513 | reflects 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 |
500 | helper functions described in Section 4. In that case, pm_runtime_resume() | 515 | helper functions described in Section 4. In that case, pm_runtime_resume() |
501 | should be used. Of course, for this purpose the device's run-time PM has to be | 516 | should be used. Of course, for this purpose the device's runtime PM has to be |
502 | enabled earlier by calling pm_runtime_enable(). | 517 | enabled earlier by calling pm_runtime_enable(). |
503 | 518 | ||
504 | If the device bus type's or driver's ->probe() callback runs | 519 | If 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 | |||
529 | it at run time by changing the value of its /sys/devices/.../power/control | 544 | it at run time by changing the value of its /sys/devices/.../power/control |
530 | attribute to "on", which causes pm_runtime_forbid() to be called. In principle, | 545 | attribute to "on", which causes pm_runtime_forbid() to be called. In principle, |
531 | this mechanism may also be used by the driver to effectively turn off the | 546 | this mechanism may also be used by the driver to effectively turn off the |
532 | run-time power management of the device until the user space turns it on. | 547 | runtime power management of the device until the user space turns it on. |
533 | Namely, during the initialization the driver can make sure that the run-time PM | 548 | Namely, during the initialization the driver can make sure that the runtime PM |
534 | status of the device is 'active' and call pm_runtime_forbid(). It should be | 549 | status of the device is 'active' and call pm_runtime_forbid(). It should be |
535 | noted, however, that if the user space has already intentionally changed the | 550 | noted, however, that if the user space has already intentionally changed the |
536 | value of /sys/devices/.../power/control to "auto" to allow the driver to power | 551 | value of /sys/devices/.../power/control to "auto" to allow the driver to power |
537 | manage the device at run time, the driver may confuse it by using | 552 | manage the device at run time, the driver may confuse it by using |
538 | pm_runtime_forbid() this way. | 553 | pm_runtime_forbid() this way. |
539 | 554 | ||
540 | 6. Run-time PM and System Sleep | 555 | 6. Runtime PM and System Sleep |
541 | 556 | ||
542 | Run-time PM and system sleep (i.e., system suspend and hibernation, also known | 557 | Runtime PM and system sleep (i.e., system suspend and hibernation, also known |
543 | as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of | 558 | as suspend-to-RAM and suspend-to-disk) interact with each other in a couple of |
544 | ways. If a device is active when a system sleep starts, everything is | 559 | ways. If a device is active when a system sleep starts, everything is |
545 | straightforward. But what should happen if the device is already suspended? | 560 | straightforward. But what should happen if the device is already suspended? |
546 | 561 | ||
547 | The device may have different wake-up settings for run-time PM and system sleep. | 562 | The device may have different wake-up settings for runtime PM and system sleep. |
548 | For example, remote wake-up may be enabled for run-time suspend but disallowed | 563 | For example, remote wake-up may be enabled for runtime suspend but disallowed |
549 | for system sleep (device_may_wakeup(dev) returns 'false'). When this happens, | 564 | for system sleep (device_may_wakeup(dev) returns 'false'). When this happens, |
550 | the subsystem-level system suspend callback is responsible for changing the | 565 | the subsystem-level system suspend callback is responsible for changing the |
551 | device's wake-up setting (it may leave that to the device driver's system | 566 | device's wake-up setting (it may leave that to the device driver's system |
552 | suspend routine). It may be necessary to resume the device and suspend it again | 567 | suspend routine). It may be necessary to resume the device and suspend it again |
553 | in order to do so. The same is true if the driver uses different power levels | 568 | in order to do so. The same is true if the driver uses different power levels |
554 | or other settings for run-time suspend and system sleep. | 569 | or other settings for runtime suspend and system sleep. |
555 | 570 | ||
556 | During system resume, devices generally should be brought back to full power, | 571 | During system resume, the simplest approach is to bring all devices back to full |
557 | even if they were suspended before the system sleep began. There are several | 572 | power, even if they had been suspended before the system suspend began. There |
558 | reasons for this, including: | 573 | are 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. | 590 | If the device had been suspended before the system suspend began and it's |
576 | 591 | brought back to full power during resume, then its runtime PM status will have | |
577 | If the device was suspended before the sleep began, then its run-time PM status | 592 | to be updated to reflect the actual post-system sleep status. The way to do |
578 | will have to be updated to reflect the actual post-system sleep status. The way | 593 | this is: |
579 | to 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 | ||
599 | The PM core always increments the runtime usage counter before calling the | ||
600 | ->suspend() callback and decrements it after calling the ->resume() callback. | ||
601 | Hence disabling runtime PM temporarily like this will not cause any runtime | ||
602 | suspend attempts to be permanently lost. If the usage count goes to zero | ||
603 | following the return of the ->resume() callback, the ->runtime_idle() callback | ||
604 | will be invoked as usual. | ||
605 | |||
606 | On some systems, however, system sleep is not entered through a global firmware | ||
607 | or hardware operation. Instead, all hardware components are put into low-power | ||
608 | states directly by the kernel in a coordinated way. Then, the system sleep | ||
609 | state effectively follows from the states the hardware components end up in | ||
610 | and the system is woken up from that state by a hardware interrupt or a similar | ||
611 | mechanism entirely under the kernel's control. As a result, the kernel never | ||
612 | gives control away and the states of all devices during resume are precisely | ||
613 | known to it. If that is the case and none of the situations listed above takes | ||
614 | place (in particular, if the system is not waking up from hibernation), it may | ||
615 | be more efficient to leave the devices that had been suspended before the system | ||
616 | suspend began in the suspended state. | ||
617 | |||
618 | The PM core does its best to reduce the probability of race conditions between | ||
619 | the runtime PM and system suspend/resume (and hibernation) callbacks by carrying | ||
620 | out 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 | |||
585 | 7. Generic subsystem callbacks | 632 | 7. Generic subsystem callbacks |
586 | 633 | ||
587 | Subsystems may wish to conserve code space by using the set of generic power | 634 | Subsystems 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 | |||
666 | dev_pm_ops structure pointer. | 713 | dev_pm_ops structure pointer. |
667 | 714 | ||
668 | Device drivers that wish to use the same function as a system suspend, freeze, | 715 | Device drivers that wish to use the same function as a system suspend, freeze, |
669 | poweroff and run-time suspend callback, and similarly for system resume, thaw, | 716 | poweroff and runtime suspend callback, and similarly for system resume, thaw, |
670 | restore, and run-time resume, can achieve this with the help of the | 717 | restore, and runtime resume, can achieve this with the help of the |
671 | UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its | 718 | UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its |
672 | last argument to NULL). | 719 | last argument to NULL). |
673 | 720 | ||
@@ -677,7 +724,7 @@ Some "devices" are only logical sub-devices of their parent and cannot be | |||
677 | power-managed on their own. (The prototype example is a USB interface. Entire | 724 | power-managed on their own. (The prototype example is a USB interface. Entire |
678 | USB devices can go into low-power mode or send wake-up requests, but neither is | 725 | USB devices can go into low-power mode or send wake-up requests, but neither is |
679 | possible for individual interfaces.) The drivers for these devices have no | 726 | possible for individual interfaces.) The drivers for these devices have no |
680 | need of run-time PM callbacks; if the callbacks did exist, ->runtime_suspend() | 727 | need of runtime PM callbacks; if the callbacks did exist, ->runtime_suspend() |
681 | and ->runtime_resume() would always return 0 without doing anything else and | 728 | and ->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 | |||
685 | pm_runtime_no_callbacks(). This should be done after the device structure is | 732 | pm_runtime_no_callbacks(). This should be done after the device structure is |
686 | initialized and before it is registered (although after device registration is | 733 | initialized and before it is registered (although after device registration is |
687 | also okay). The routine will set the device's power.no_callbacks flag and | 734 | also okay). The routine will set the device's power.no_callbacks flag and |
688 | prevent the non-debugging run-time PM sysfs attributes from being created. | 735 | prevent the non-debugging runtime PM sysfs attributes from being created. |
689 | 736 | ||
690 | When power.no_callbacks is set, the PM core will not invoke the | 737 | When 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 | |||
693 | devices should be suspended. | 740 | devices should be suspended. |
694 | 741 | ||
695 | As a consequence, the PM core will never directly inform the device's subsystem | 742 | As a consequence, the PM core will never directly inform the device's subsystem |
696 | or driver about run-time power changes. Instead, the driver for the device's | 743 | or driver about runtime power changes. Instead, the driver for the device's |
697 | parent must take responsibility for telling the device's driver when the | 744 | parent must take responsibility for telling the device's driver when the |
698 | parent's power state changes. | 745 | parent'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 | |||
704 | think it will remain in that state for a substantial time. A common heuristic | 751 | think it will remain in that state for a substantial time. A common heuristic |
705 | says that a device which hasn't been used for a while is liable to remain | 752 | says that a device which hasn't been used for a while is liable to remain |
706 | unused; following this advice, drivers should not allow devices to be suspended | 753 | unused; following this advice, drivers should not allow devices to be suspended |
707 | at run-time until they have been inactive for some minimum period. Even when | 754 | at runtime until they have been inactive for some minimum period. Even when |
708 | the heuristic ends up being non-optimal, it will still prevent devices from | 755 | the 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 | ||
711 | The term "autosuspend" is an historical remnant. It doesn't mean that the | 758 | The term "autosuspend" is an historical remnant. It doesn't mean that the |
712 | device is automatically suspended (the subsystem or driver still has to call | 759 | device is automatically suspended (the subsystem or driver still has to call |
713 | the appropriate PM routines); rather it means that run-time suspends will | 760 | the appropriate PM routines); rather it means that runtime suspends will |
714 | automatically be delayed until the desired period of inactivity has elapsed. | 761 | automatically be delayed until the desired period of inactivity has elapsed. |
715 | 762 | ||
716 | Inactivity is determined based on the power.last_busy field. Drivers should | 763 | Inactivity is determined based on the power.last_busy field. Drivers should |