diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2010-03-07 18:45:35 -0500 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2010-03-07 18:45:35 -0500 |
commit | 5980bb3ee6e733d66eea04c221a140dea15d52de (patch) | |
tree | 5365854f6fc7db6cc2d6a5cfc605942058c7a76a /Documentation | |
parent | 68ae6b5cc1e8b88754a64140b88e467e02abfea2 (diff) | |
parent | d690b2cd222afc75320b9b8e9da7df02e9e630ca (diff) |
Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/suspend-2.6
* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/rafael/suspend-2.6:
PM: Provide generic subsystem-level callbacks
PM / Runtime: Document power.runtime_auto and related functions
Diffstat (limited to 'Documentation')
-rw-r--r-- | Documentation/power/runtime_pm.txt | 93 |
1 files changed, 93 insertions, 0 deletions
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 356fd86f4ea8..ab00eeddecaf 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt | |||
@@ -224,6 +224,12 @@ defined in include/linux/pm.h: | |||
224 | RPM_SUSPENDED, which means that each device is initially regarded by the | 224 | RPM_SUSPENDED, which means that each device is initially regarded by the |
225 | PM core as 'suspended', regardless of its real hardware status | 225 | PM core as 'suspended', regardless of its real hardware status |
226 | 226 | ||
227 | unsigned int runtime_auto; | ||
228 | - if set, indicates that the user space has allowed the device driver to | ||
229 | power manage the device at run time via the /sys/devices/.../power/control | ||
230 | interface; it may only be modified with the help of the pm_runtime_allow() | ||
231 | and pm_runtime_forbid() helper functions | ||
232 | |||
227 | All of the above fields are members of the 'power' member of 'struct device'. | 233 | All of the above fields are members of the 'power' member of 'struct device'. |
228 | 234 | ||
229 | 4. Run-time PM Device Helper Functions | 235 | 4. Run-time PM Device Helper Functions |
@@ -329,6 +335,20 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: | |||
329 | 'power.runtime_error' is set or 'power.disable_depth' is greater than | 335 | 'power.runtime_error' is set or 'power.disable_depth' is greater than |
330 | zero) | 336 | zero) |
331 | 337 | ||
338 | bool pm_runtime_suspended(struct device *dev); | ||
339 | - return true if the device's runtime PM status is 'suspended', or false | ||
340 | otherwise | ||
341 | |||
342 | void pm_runtime_allow(struct device *dev); | ||
343 | - set the power.runtime_auto flag for the device and decrease its usage | ||
344 | counter (used by the /sys/devices/.../power/control interface to | ||
345 | effectively allow the device to be power managed at run time) | ||
346 | |||
347 | void pm_runtime_forbid(struct device *dev); | ||
348 | - unset the power.runtime_auto flag for the device and increase its usage | ||
349 | counter (used by the /sys/devices/.../power/control interface to | ||
350 | effectively prevent the device from being power managed at run time) | ||
351 | |||
332 | It is safe to execute the following helper functions from interrupt context: | 352 | It is safe to execute the following helper functions from interrupt context: |
333 | 353 | ||
334 | pm_request_idle() | 354 | pm_request_idle() |
@@ -382,6 +402,18 @@ may be desirable to suspend the device as soon as ->probe() or ->remove() has | |||
382 | finished, so the PM core uses pm_runtime_idle_sync() to invoke the | 402 | finished, so the PM core uses pm_runtime_idle_sync() to invoke the |
383 | subsystem-level idle callback for the device at that time. | 403 | subsystem-level idle callback for the device at that time. |
384 | 404 | ||
405 | The user space can effectively disallow the driver of the device to power manage | ||
406 | it at run time by changing the value of its /sys/devices/.../power/control | ||
407 | attribute to "on", which causes pm_runtime_forbid() to be called. In principle, | ||
408 | this mechanism may also be used by the driver to effectively turn off the | ||
409 | run-time power management of the device until the user space turns it on. | ||
410 | Namely, during the initialization the driver can make sure that the run-time PM | ||
411 | status of the device is 'active' and call pm_runtime_forbid(). It should be | ||
412 | noted, however, that if the user space has already intentionally changed the | ||
413 | value of /sys/devices/.../power/control to "auto" to allow the driver to power | ||
414 | manage the device at run time, the driver may confuse it by using | ||
415 | pm_runtime_forbid() this way. | ||
416 | |||
385 | 6. Run-time PM and System Sleep | 417 | 6. Run-time PM and System Sleep |
386 | 418 | ||
387 | Run-time PM and system sleep (i.e., system suspend and hibernation, also known | 419 | Run-time PM and system sleep (i.e., system suspend and hibernation, also known |
@@ -431,3 +463,64 @@ The PM core always increments the run-time usage counter before calling the | |||
431 | ->prepare() callback and decrements it after calling the ->complete() callback. | 463 | ->prepare() callback and decrements it after calling the ->complete() callback. |
432 | Hence disabling run-time PM temporarily like this will not cause any run-time | 464 | Hence disabling run-time PM temporarily like this will not cause any run-time |
433 | suspend callbacks to be lost. | 465 | suspend callbacks to be lost. |
466 | |||
467 | 7. Generic subsystem callbacks | ||
468 | |||
469 | Subsystems may wish to conserve code space by using the set of generic power | ||
470 | management callbacks provided by the PM core, defined in | ||
471 | driver/base/power/generic_ops.c: | ||
472 | |||
473 | int pm_generic_runtime_idle(struct device *dev); | ||
474 | - invoke the ->runtime_idle() callback provided by the driver of this | ||
475 | device, if defined, and call pm_runtime_suspend() for this device if the | ||
476 | return value is 0 or the callback is not defined | ||
477 | |||
478 | int pm_generic_runtime_suspend(struct device *dev); | ||
479 | - invoke the ->runtime_suspend() callback provided by the driver of this | ||
480 | device and return its result, or return -EINVAL if not defined | ||
481 | |||
482 | int pm_generic_runtime_resume(struct device *dev); | ||
483 | - invoke the ->runtime_resume() callback provided by the driver of this | ||
484 | device and return its result, or return -EINVAL if not defined | ||
485 | |||
486 | int pm_generic_suspend(struct device *dev); | ||
487 | - if the device has not been suspended at run time, invoke the ->suspend() | ||
488 | callback provided by its driver and return its result, or return 0 if not | ||
489 | defined | ||
490 | |||
491 | int pm_generic_resume(struct device *dev); | ||
492 | - invoke the ->resume() callback provided by the driver of this device and, | ||
493 | if successful, change the device's runtime PM status to 'active' | ||
494 | |||
495 | int pm_generic_freeze(struct device *dev); | ||
496 | - if the device has not been suspended at run time, invoke the ->freeze() | ||
497 | callback provided by its driver and return its result, or return 0 if not | ||
498 | defined | ||
499 | |||
500 | int pm_generic_thaw(struct device *dev); | ||
501 | - if the device has not been suspended at run time, invoke the ->thaw() | ||
502 | callback provided by its driver and return its result, or return 0 if not | ||
503 | defined | ||
504 | |||
505 | int pm_generic_poweroff(struct device *dev); | ||
506 | - if the device has not been suspended at run time, invoke the ->poweroff() | ||
507 | callback provided by its driver and return its result, or return 0 if not | ||
508 | defined | ||
509 | |||
510 | int pm_generic_restore(struct device *dev); | ||
511 | - invoke the ->restore() callback provided by the driver of this device and, | ||
512 | if successful, change the device's runtime PM status to 'active' | ||
513 | |||
514 | These functions can be assigned to the ->runtime_idle(), ->runtime_suspend(), | ||
515 | ->runtime_resume(), ->suspend(), ->resume(), ->freeze(), ->thaw(), ->poweroff(), | ||
516 | or ->restore() callback pointers in the subsystem-level dev_pm_ops structures. | ||
517 | |||
518 | If a subsystem wishes to use all of them at the same time, it can simply assign | ||
519 | the GENERIC_SUBSYS_PM_OPS macro, defined in include/linux/pm.h, to its | ||
520 | dev_pm_ops structure pointer. | ||
521 | |||
522 | Device drivers that wish to use the same function as a system suspend, freeze, | ||
523 | poweroff and run-time suspend callback, and similarly for system resume, thaw, | ||
524 | restore, and run-time resume, can achieve this with the help of the | ||
525 | UNIVERSAL_DEV_PM_OPS macro defined in include/linux/pm.h (possibly setting its | ||
526 | last argument to NULL). | ||