diff options
Diffstat (limited to 'Documentation/power/runtime_pm.txt')
| -rw-r--r-- | Documentation/power/runtime_pm.txt | 66 |
1 files changed, 41 insertions, 25 deletions
diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index b6ce00b2be9..f32ce541957 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -2,6 +2,7 @@ Runtime Power Management Framework for I/O Devices (C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. (C) 2010 Alan Stern <stern@rowland.harvard.edu> +(C) 2014 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> 1. Introduction @@ -232,7 +233,7 @@ defined in include/linux/pm.h: equal to zero); the initial value of it is 1 (i.e. runtime PM is initially disabled for all devices) - unsigned int runtime_error; + int runtime_error; - if set, there was a fatal error (one of the callbacks returned error code as described in Section 2), so the helper funtions will not work until this flag is cleared; this is the error code returned by the failing @@ -401,11 +402,11 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: int pm_runtime_disable(struct device *dev); - increment the device's 'power.disable_depth' field (if the value of that field was previously zero, this prevents subsystem-level runtime PM - callbacks from being run for the device), make sure that all of the pending - runtime PM operations on the device are either completed or canceled; - returns 1 if there was a resume request pending and it was necessary to - execute the subsystem-level resume callback for the device to satisfy that - request, otherwise 0 is returned + callbacks from being run for the device), make sure that all of the + pending runtime PM operations on the device are either completed or + canceled; returns 1 if there was a resume request pending and it was + necessary to execute the subsystem-level resume callback for the device + to satisfy that request, otherwise 0 is returned int pm_runtime_barrier(struct device *dev); - check if there's a resume request pending for the device and resume it @@ -444,6 +445,10 @@ drivers/base/power/runtime.c and include/linux/pm_runtime.h: bool pm_runtime_status_suspended(struct device *dev); - return true if the device's runtime PM status is 'suspended' + bool pm_runtime_suspended_if_enabled(struct device *dev); + - return true if the device's runtime PM status is 'suspended' and its + 'power.disable_depth' field is equal to 1 + void pm_runtime_allow(struct device *dev); - set the power.runtime_auto flag for the device and decrease its usage counter (used by the /sys/devices/.../power/control interface to @@ -644,19 +649,33 @@ place (in particular, if the system is not waking up from hibernation), it may be more efficient to leave the devices that had been suspended before the system suspend began in the suspended state. +To this end, the PM core provides a mechanism allowing some coordination between +different levels of device hierarchy. Namely, if a system suspend .prepare() +callback returns a positive number for a device, that indicates to the PM core +that the device appears to be runtime-suspended and its state is fine, so it +may be left in runtime suspend provided that all of its descendants are also +left in runtime suspend. If that happens, the PM core will not execute any +system suspend and resume callbacks for all of those devices, except for the +complete callback, which is then entirely responsible for handling the device +as appropriate. This only applies to system suspend transitions that are not +related to hibernation (see Documentation/power/devices.txt for more +information). + The PM core does its best to reduce the probability of race conditions between the runtime PM and system suspend/resume (and hibernation) callbacks by carrying out the following operations: - * During system suspend it calls pm_runtime_get_noresume() and - pm_runtime_barrier() for every device right before executing the - subsystem-level .suspend() callback for it. In addition to that it calls - __pm_runtime_disable() with 'false' as the second argument for every device - right before executing the subsystem-level .suspend_late() callback for it. - - * During system resume it calls pm_runtime_enable() and pm_runtime_put() - for every device right after executing the subsystem-level .resume_early() - callback and right after executing the subsystem-level .resume() callback + * During system suspend pm_runtime_get_noresume() is called for every device + right before executing the subsystem-level .prepare() callback for it and + pm_runtime_barrier() is called for every device right before executing the + subsystem-level .suspend() callback for it. In addition to that the PM core + calls __pm_runtime_disable() with 'false' as the second argument for every + device right before executing the subsystem-level .suspend_late() callback + for it. + + * During system resume pm_runtime_enable() and pm_runtime_put() are called for + every device right after executing the subsystem-level .resume_early() + callback and right after executing the subsystem-level .complete() callback for it, respectively. 7. Generic subsystem callbacks @@ -667,11 +686,11 @@ driver/base/power/generic_ops.c: int pm_generic_runtime_suspend(struct device *dev); - invoke the ->runtime_suspend() callback provided by the driver of this - device and return its result, or return -EINVAL if not defined + device and return its result, or return 0 if not defined int pm_generic_runtime_resume(struct device *dev); - invoke the ->runtime_resume() callback provided by the driver of this - device and return its result, or return -EINVAL if not defined + device and return its result, or return 0 if not defined int pm_generic_suspend(struct device *dev); - if the device has not been suspended at run time, invoke the ->suspend() @@ -727,15 +746,12 @@ driver/base/power/generic_ops.c: int pm_generic_restore_noirq(struct device *dev); - invoke the ->restore_noirq() callback provided by the device's driver -These functions can be assigned to the ->runtime_idle(), ->runtime_suspend(), +These functions are the defaults used by the PM core, if a subsystem doesn't +provide its own callbacks for ->runtime_idle(), ->runtime_suspend(), ->runtime_resume(), ->suspend(), ->suspend_noirq(), ->resume(), ->resume_noirq(), ->freeze(), ->freeze_noirq(), ->thaw(), ->thaw_noirq(), -->poweroff(), ->poweroff_noirq(), ->restore(), ->restore_noirq() callback -pointers in the subsystem-level dev_pm_ops structures. - -If a subsystem wishes to use all of them at the same time, it can simply assign -the GENERIC_SUBSYS_PM_OPS macro, defined in include/linux/pm.h, to its -dev_pm_ops structure pointer. +->poweroff(), ->poweroff_noirq(), ->restore(), ->restore_noirq() in the +subsystem-level dev_pm_ops structure. Device drivers that wish to use the same function as a system suspend, freeze, poweroff and runtime suspend callback, and similarly for system resume, thaw, @@ -873,7 +889,7 @@ Here is a schematic pseudo-code example: foo->is_suspended = 0; pm_runtime_mark_last_busy(&foo->dev); if (foo->num_pending_requests > 0) - foo_process_requests(foo); + foo_process_next_request(foo); unlock(&foo->private_lock); return 0; } |