diff options
Diffstat (limited to 'Documentation/power')
| -rw-r--r-- | Documentation/power/devices.txt | 96 | ||||
| -rw-r--r-- | Documentation/power/notifiers.txt | 4 | ||||
| -rw-r--r-- | Documentation/power/opp.txt | 2 | ||||
| -rw-r--r-- | Documentation/power/runtime_pm.txt | 13 | ||||
| -rw-r--r-- | Documentation/power/states.txt | 12 | ||||
| -rw-r--r-- | Documentation/power/swsusp.txt | 4 | ||||
| -rw-r--r-- | Documentation/power/userland-swsusp.txt | 6 |
7 files changed, 88 insertions, 49 deletions
diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt index 57080cd74575..1971bcf48a60 100644 --- a/Documentation/power/devices.txt +++ b/Documentation/power/devices.txt @@ -1,6 +1,6 @@ Device Power Management -Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +Copyright (c) 2010-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu> @@ -159,18 +159,18 @@ matter, and the kernel is responsible for keeping track of it. By contrast, whether or not a wakeup-capable device should issue wakeup events is a policy decision, and it is managed by user space through a sysfs attribute: the power/wakeup file. User space can write the strings "enabled" or "disabled" to -set or clear the should_wakeup flag, respectively. Reads from the file will -return the corresponding string if can_wakeup is true, but if can_wakeup is -false then reads will return an empty string, to indicate that the device -doesn't support wakeup events. (But even though the file appears empty, writes -will still affect the should_wakeup flag.) +set or clear the "should_wakeup" flag, respectively. This file is only present +for wakeup-capable devices (i.e. devices whose "can_wakeup" flags are set) +and is created (or removed) by device_set_wakeup_capable(). Reads from the +file will return the corresponding string. The device_may_wakeup() routine returns true only if both flags are set. -Drivers should check this routine when putting devices in a low-power state -during a system sleep transition, to see whether or not to enable the devices' -wakeup mechanisms. However for runtime power management, wakeup events should -be enabled whenever the device and driver both support them, regardless of the -should_wakeup flag. +This information is used by subsystems, like the PCI bus type code, to see +whether or not to enable the devices' wakeup mechanisms. If device wakeup +mechanisms are enabled or disabled directly by drivers, they also should use +device_may_wakeup() to decide what to do during a system sleep transition. +However for runtime power management, wakeup events should be enabled whenever +the device and driver both support them, regardless of the should_wakeup flag. /sys/devices/.../power/control files @@ -249,23 +249,18 @@ various phases always run after tasks have been frozen and before they are unfrozen. Furthermore, the *_noirq phases run at a time when IRQ handlers have been disabled (except for those marked with the IRQ_WAKEUP flag). -Most phases use bus, type, and class callbacks (that is, methods defined in -dev->bus->pm, dev->type->pm, and dev->class->pm). The prepare and complete -phases are exceptions; they use only bus callbacks. When multiple callbacks -are used in a phase, they are invoked in the order: <class, type, bus> during -power-down transitions and in the opposite order during power-up transitions. -For example, during the suspend phase the PM core invokes - - dev->class->pm.suspend(dev); - dev->type->pm.suspend(dev); - dev->bus->pm.suspend(dev); - -before moving on to the next device, whereas during the resume phase the core -invokes - - dev->bus->pm.resume(dev); - dev->type->pm.resume(dev); - dev->class->pm.resume(dev); +All phases use bus, type, or class callbacks (that is, methods defined in +dev->bus->pm, dev->type->pm, or dev->class->pm). These callbacks are mutually +exclusive, so if the device type provides a struct dev_pm_ops object pointed to +by its pm field (i.e. both dev->type and dev->type->pm are defined), the +callbacks included in that object (i.e. dev->type->pm) will be used. Otherwise, +if the class provides a struct dev_pm_ops object pointed to by its pm field +(i.e. both dev->class and dev->class->pm are defined), the PM core will use the +callbacks from that object (i.e. dev->class->pm). Finally, if the pm fields of +both the device type and class objects are NULL (or those objects do not exist), +the callbacks provided by the bus (that is, the callbacks from dev->bus->pm) +will be used (this allows device types to override callbacks provided by bus +types or classes if necessary). These callbacks may in turn invoke device- or driver-specific methods stored in dev->driver->pm, but they don't have to. @@ -372,7 +367,7 @@ Drivers need to be able to handle hardware which has been reset since the suspend methods were called, for example by complete reinitialization. This may be the hardest part, and the one most protected by NDA'd documents and chip errata. It's simplest if the hardware state hasn't changed since -the suspend was carried out, but that can't be guaranteed (in fact, it ususally +the suspend was carried out, but that can't be guaranteed (in fact, it usually is not the case). Drivers must also be prepared to notice that the device has been removed @@ -507,6 +502,49 @@ routines. Nevertheless, different callback pointers are used in case there is a situation where it actually matters. +Device Power Domains +-------------------- +Sometimes devices share reference clocks or other power resources. In those +cases it generally is not possible to put devices into low-power states +individually. Instead, a set of devices sharing a power resource can be put +into a low-power state together at the same time by turning off the shared +power resource. Of course, they also need to be put into the full-power state +together, by turning the shared power resource on. A set of devices with this +property is often referred to as a power domain. + +Support for power domains is provided through the pwr_domain field of struct +device. This field is a pointer to an object of type struct dev_power_domain, +defined in include/linux/pm.h, providing a set of power management callbacks +analogous to the subsystem-level and device driver callbacks that are executed +for the given device during all power transitions, in addition to the respective +subsystem-level callbacks. Specifically, the power domain "suspend" callbacks +(i.e. ->runtime_suspend(), ->suspend(), ->freeze(), ->poweroff(), etc.) are +executed after the analogous subsystem-level callbacks, while the power domain +"resume" callbacks (i.e. ->runtime_resume(), ->resume(), ->thaw(), ->restore, +etc.) are executed before the analogous subsystem-level callbacks. Error codes +returned by the "suspend" and "resume" power domain callbacks are ignored. + +Power domain ->runtime_idle() callback is executed before the subsystem-level +->runtime_idle() callback and the result returned by it is not ignored. Namely, +if it returns error code, the subsystem-level ->runtime_idle() callback will not +be called and the helper function rpm_idle() executing it will return error +code. This mechanism is intended to help platforms where saving device state +is a time consuming operation and should only be carried out if all devices +in the power domain are idle, before turning off the shared power resource(s). +Namely, the power domain ->runtime_idle() callback may return error code until +the pm_runtime_idle() helper (or its asychronous version) has been called for +all devices in the power domain (it is recommended that the returned error code +be -EBUSY in those cases), preventing the subsystem-level ->runtime_idle() +callback from being run prematurely. + +The support for device power domains is only relevant to platforms needing to +use the same subsystem-level (e.g. platform bus type) and device driver power +management callbacks in many different power domain configurations and wanting +to avoid incorporating the support for power domains into the subsystem-level +callbacks. The other platforms need not implement it or take it into account +in any way. + + System Devices -------------- System devices (sysdevs) follow a slightly different API, which can be found in diff --git a/Documentation/power/notifiers.txt b/Documentation/power/notifiers.txt index ae1b7ec07684..cf980709122a 100644 --- a/Documentation/power/notifiers.txt +++ b/Documentation/power/notifiers.txt @@ -24,7 +24,7 @@ PM_HIBERNATION_PREPARE The system is going to hibernate or suspend, tasks will be frozen immediately. PM_POST_HIBERNATION The system memory state has been restored from a - hibernation image or an error occured during the + hibernation image or an error occurred during the hibernation. Device drivers' .resume() callbacks have been executed and tasks have been thawed. @@ -38,7 +38,7 @@ PM_POST_RESTORE An error occurred during the hibernation restore. PM_SUSPEND_PREPARE The system is preparing for a suspend. -PM_POST_SUSPEND The system has just resumed or an error occured during +PM_POST_SUSPEND The system has just resumed or an error occurred during the suspend. Device drivers' .resume() callbacks have been executed and tasks have been thawed. diff --git a/Documentation/power/opp.txt b/Documentation/power/opp.txt index cd445582d1f8..5ae70a12c1e2 100644 --- a/Documentation/power/opp.txt +++ b/Documentation/power/opp.txt @@ -178,7 +178,7 @@ opp_find_freq_ceil - Search for an available OPP which is *at least* the if (!IS_ERR(opp)) soc_switch_to_freq_voltage(freq); else - /* do something when we cant satisfy the req */ + /* do something when we can't satisfy the req */ /* do other stuff */ } diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index ffe55ffa540a..654097b130b4 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -1,6 +1,6 @@ Run-time Power Management Framework for I/O Devices -(C) 2009 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. +(C) 2009-2011 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc. (C) 2010 Alan Stern <stern@rowland.harvard.edu> 1. Introduction @@ -44,11 +44,12 @@ struct dev_pm_ops { }; The ->runtime_suspend(), ->runtime_resume() and ->runtime_idle() callbacks are -executed by the PM core for either the bus type, or device type (if the bus -type's callback is not defined), or device class (if the bus type's and device -type's callbacks are not defined) of given device. The bus type, device type -and device class callbacks are referred to as subsystem-level callbacks in what -follows. +executed by the PM core for either the device type, or the class (if the device +type's struct dev_pm_ops object does not exist), or the bus type (if the +device type's and class' struct dev_pm_ops objects do not exist) of the given +device (this allows device types to override callbacks provided by bus types or +classes if necessary). The bus type, device type and class callbacks are +referred to as subsystem-level callbacks in what follows. By default, the callbacks are always invoked in process context with interrupts enabled. However, subsystems can use the pm_runtime_irq_safe() helper function diff --git a/Documentation/power/states.txt b/Documentation/power/states.txt index 34800cc521bf..4416b28630df 100644 --- a/Documentation/power/states.txt +++ b/Documentation/power/states.txt @@ -62,12 +62,12 @@ setup via another operating system for it to use. Despite the inconvenience, this method requires minimal work by the kernel, since the firmware will also handle restoring memory contents on resume. -For suspend-to-disk, a mechanism called swsusp called 'swsusp' (Swap -Suspend) is used to write memory contents to free swap space. -swsusp has some restrictive requirements, but should work in most -cases. Some, albeit outdated, documentation can be found in -Documentation/power/swsusp.txt. Alternatively, userspace can do most -of the actual suspend to disk work, see userland-swsusp.txt. +For suspend-to-disk, a mechanism called 'swsusp' (Swap Suspend) is used +to write memory contents to free swap space. swsusp has some restrictive +requirements, but should work in most cases. Some, albeit outdated, +documentation can be found in Documentation/power/swsusp.txt. +Alternatively, userspace can do most of the actual suspend to disk work, +see userland-swsusp.txt. Once memory state is written to disk, the system may either enter a low-power state (like ACPI S4), or it may simply power down. Powering diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index ea718891a665..ac190cf1963e 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -192,7 +192,7 @@ Q: There don't seem to be any generally useful behavioral distinctions between SUSPEND and FREEZE. A: Doing SUSPEND when you are asked to do FREEZE is always correct, -but it may be unneccessarily slow. If you want your driver to stay simple, +but it may be unnecessarily slow. If you want your driver to stay simple, slowness may not matter to you. It can always be fixed later. For devices like disk it does matter, you do not want to spindown for @@ -237,7 +237,7 @@ disk. Whole sequence goes like running system, user asks for suspend-to-disk - user processes are stopped (in common case there are none, but with resume-from-initrd, noone knows) + user processes are stopped (in common case there are none, but with resume-from-initrd, no one knows) read image from disk diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt index 81680f9f5909..1101bee4e822 100644 --- a/Documentation/power/userland-swsusp.txt +++ b/Documentation/power/userland-swsusp.txt @@ -98,7 +98,7 @@ SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to The device's read() operation can be used to transfer the snapshot image from the kernel. It has the following limitations: - you cannot read() more than one virtual memory page at a time -- read()s accross page boundaries are impossible (ie. if ypu read() 1/2 of +- read()s across page boundaries are impossible (ie. if ypu read() 1/2 of a page in the previous call, you will only be able to read() _at_ _most_ 1/2 of the page in the next call) @@ -137,7 +137,7 @@ mechanism and the userland utilities using the interface SHOULD use additional means, such as checksums, to ensure the integrity of the snapshot image. The suspending and resuming utilities MUST lock themselves in memory, -preferrably using mlockall(), before calling SNAPSHOT_FREEZE. +preferably using mlockall(), before calling SNAPSHOT_FREEZE. The suspending utility MUST check the value stored by SNAPSHOT_CREATE_IMAGE in the memory location pointed to by the last argument of ioctl() and proceed @@ -147,7 +147,7 @@ in accordance with it: (a) The suspending utility MUST NOT close the snapshot device _unless_ the whole suspend procedure is to be cancelled, in which case, if the snapshot image has already been saved, the - suspending utility SHOULD destroy it, preferrably by zapping + suspending utility SHOULD destroy it, preferably by zapping its header. If the suspend is not to be cancelled, the system MUST be powered off or rebooted after the snapshot image has been saved. |