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: PM QOS update fix
  Freezer / cgroup freezer: Update stale locking comments
  PM / platform_bus: Allow runtime PM by default
  i2c: Fix bus-level power management callbacks
  PM QOS update
  PM / Hibernate: Fix block_io.c printk warning
  PM / Hibernate: Group swap ops
  PM / Hibernate: Move the first_sector out of swsusp_write
  PM / Hibernate: Separate block_io
  PM / Hibernate: Snapshot cleanup
  FS / libfs: Implement simple_write_to_buffer
  PM / Hibernate: document open(/dev/snapshot) side effects
  PM / Runtime: Add sysfs debug files
  PM: Improve device power management document
  PM: Update device power management document
  PM: Allow runtime_suspend methods to call pm_schedule_suspend()
  PM: pm_wakeup - switch to using bool

31 files changed, 1251 insertions, 949 deletions

diff --git a/Documentation/power/devices.txt b/Documentation/power/devices.txt
index c9abbd86bc18..57080cd74575 100644
--- a/Documentation/power/devices.txt
+++ b/Documentation/power/devices.txt
@@ -1,7 +1,13 @@
+Device Power Management
+
+Copyright (c) 2010 Rafael J. Wysocki <rjw@sisk.pl>, Novell Inc.
+Copyright (c) 2010 Alan Stern <stern@rowland.harvard.edu>
+
+
 Most of the code in Linux is device drivers, so most of the Linux power
-management code is also driver-specific.  Most drivers will do very little;
-others, especially for platforms with small batteries (like cell phones),
-will do a lot.
+management (PM) code is also driver-specific.  Most drivers will do very
+little; others, especially for platforms with small batteries (like cell
+phones), will do a lot.
 
 This writeup gives an overview of how drivers interact with system-wide
 power management goals, emphasizing the models and interfaces that are
@@ -15,9 +21,10 @@ Drivers will use one or both of these models to put devices into low-power
 states:
 
     System Sleep model:
-        Drivers can enter low power states as part of entering system-wide
-        low-power states like "suspend-to-ram", or (mostly for systems with
-        disks) "hibernate" (suspend-to-disk).
+        Drivers can enter low-power states as part of entering system-wide
+        low-power states like "suspend" (also known as "suspend-to-RAM"), or
+        (mostly for systems with disks) "hibernation" (also known as
+        "suspend-to-disk").
 
         This is something that device, bus, and class drivers collaborate on
         by implementing various role-specific suspend and resume methods to
@@ -25,33 +32,41 @@ states:
         them without loss of data.
 
         Some drivers can manage hardware wakeup events, which make the system
-        leave that low-power state.  This feature may be disabled using the
-        relevant /sys/devices/.../power/wakeup file; enabling it may cost some
-        power usage, but let the whole system enter low power states more often.
+        leave the low-power state.  This feature may be enabled or disabled
+        using the relevant /sys/devices/.../power/wakeup file (for Ethernet
+        drivers the ioctl interface used by ethtool may also be used for this
+        purpose); enabling it may cost some power usage, but let the whole
+        system enter low-power states more often.
 
     Runtime Power Management model:
-        Drivers may also enter low power states while the system is running,
-        independently of other power management activity.  Upstream drivers
-        will normally not know (or care) if the device is in some low power
-        state when issuing requests; the driver will auto-resume anything
-        that's needed when it gets a request.
-
-        This doesn't have, or need much infrastructure; it's just something you
-        should do when writing your drivers.  For example, clk_disable() unused
-        clocks as part of minimizing power drain for currently-unused hardware.
-        Of course, sometimes clusters of drivers will collaborate with each
-        other, which could involve task-specific power management.
-
-There's not a lot to be said about those low power states except that they
-are very system-specific, and often device-specific.  Also, that if enough
-drivers put themselves into low power states (at "runtime"), the effect may be
-the same as entering some system-wide low-power state (system sleep) ... and
-that synergies exist, so that several drivers using runtime pm might put the
-system into a state where even deeper power saving options are available.
-
-Most suspended devices will have quiesced all I/O:  no more DMA or irqs, no
-more data read or written, and requests from upstream drivers are no longer
-accepted.  A given bus or platform may have different requirements though.
+        Devices may also be put into low-power states while the system is
+        running, independently of other power management activity in principle.
+        However, devices are not generally independent of each other (for
+        example, a parent device cannot be suspended unless all of its child
+        devices have been suspended).  Moreover, depending on the bus type the
+        device is on, it may be necessary to carry out some bus-specific
+        operations on the device for this purpose.  Devices put into low power
+        states at run time may require special handling during system-wide power
+        transitions (suspend or hibernation).
+
+        For these reasons not only the device driver itself, but also the
+        appropriate subsystem (bus type, device type or device class) driver and
+        the PM core are involved in runtime power management.  As in the system
+        sleep power management case, they need to collaborate by implementing
+        various role-specific suspend and resume methods, so that the hardware
+        is cleanly powered down and reactivated without data or service loss.
+
+There's not a lot to be said about those low-power states except that they are
+very system-specific, and often device-specific.  Also, that if enough devices
+have been put into low-power states (at runtime), the effect may be very similar
+to entering some system-wide low-power state (system sleep) ... and that
+synergies exist, so that several drivers using runtime PM might put the system
+into a state where even deeper power saving options are available.
+
+Most suspended devices will have quiesced all I/O: no more DMA or IRQs (except
+for wakeup events), no more data read or written, and requests from upstream
+drivers are no longer accepted.  A given bus or platform may have different
+requirements though.
 
 Examples of hardware wakeup events include an alarm from a real time clock,
 network wake-on-LAN packets, keyboard or mouse activity, and media insertion
@@ -60,129 +75,152 @@ or removal (for PCMCIA, MMC/SD, USB, and so on).
 
 Interfaces for Entering System Sleep States
 ===========================================
-Most of the programming interfaces a device driver needs to know about
-relate to that first model:  entering a system-wide low power state,
-rather than just minimizing power consumption by one device.
-
-
-Bus Driver Methods
-------------------
-The core methods to suspend and resume devices reside in struct bus_type.
-These are mostly of interest to people writing infrastructure for busses
-like PCI or USB, or because they define the primitives that device drivers
-may need to apply in domain-specific ways to their devices:
-
-struct bus_type {
-        ...
-        int  (*suspend)(struct device *dev, pm_message_t state);
-        int  (*resume)(struct device *dev);
+There are programming interfaces provided for subsystems (bus type, device type,
+device class) and device drivers to allow them to participate in the power
+management of devices they are concerned with.  These interfaces cover both
+system sleep and runtime power management.
+
+
+Device Power Management Operations
+----------------------------------
+Device power management operations, at the subsystem level as well as at the
+device driver level, are implemented by defining and populating objects of type
+struct dev_pm_ops:
+
+struct dev_pm_ops {
+        int (*prepare)(struct device *dev);
+        void (*complete)(struct device *dev);
+        int (*suspend)(struct device *dev);
+        int (*resume)(struct device *dev);
+        int (*freeze)(struct device *dev);
+        int (*thaw)(struct device *dev);
+        int (*poweroff)(struct device *dev);
+        int (*restore)(struct device *dev);
+        int (*suspend_noirq)(struct device *dev);
+        int (*resume_noirq)(struct device *dev);