filesystem freeze: add error handling of write_super_lockfs/unlockfs

[safe/jmp/linux-2.6] / Documentation / usb / power-management.txt

diff --git a/Documentation/usb/power-management.txt b/Documentation/usb/power-management.txt
index b2fc4d4..ad64261 100644 (file)
--- a/Documentation/usb/power-management.txt
+++ b/Documentation/usb/power-management.txt
@@ -313,11 +313,13 @@ three of the methods listed above.  In addition, a driver indicates
 that it supports autosuspend by setting the .supports_autosuspend flag
 in its usb_driver structure.  It is then responsible for informing the
 USB core whenever one of its interfaces becomes busy or idle.  The
-driver does so by calling these three functions:
+driver does so by calling these five functions:
 
        int  usb_autopm_get_interface(struct usb_interface *intf);
        void usb_autopm_put_interface(struct usb_interface *intf);
        int  usb_autopm_set_interface(struct usb_interface *intf);
+       int  usb_autopm_get_interface_async(struct usb_interface *intf);
+       void usb_autopm_put_interface_async(struct usb_interface *intf);
 
 The functions work by maintaining a counter in the usb_interface
 structure.  When intf->pm_usage_count is > 0 then the interface is
@@ -330,10 +332,12 @@ associated with the device itself rather than any of its interfaces.
 This field is used only by the USB core.)
 
 The driver owns intf->pm_usage_count; it can modify the value however
-and whenever it likes.  A nice aspect of the usb_autopm_* routines is
-that the changes they make are protected by the usb_device structure's
-PM mutex (udev->pm_mutex); however drivers may change pm_usage_count
-without holding the mutex.
+and whenever it likes.  A nice aspect of the non-async usb_autopm_*
+routines is that the changes they make are protected by the usb_device
+structure's PM mutex (udev->pm_mutex); however drivers may change
+pm_usage_count without holding the mutex.  Drivers using the async
+routines are responsible for their own synchronization and mutual
+exclusion.
 
        usb_autopm_get_interface() increments pm_usage_count and
        attempts an autoresume if the new value is > 0 and the
@@ -348,14 +352,22 @@ without holding the mutex.
        is suspended, and it attempts an autosuspend if the value is
        <= 0 and the device isn't suspended.
 
-There also are a couple of utility routines drivers can use:
+       usb_autopm_get_interface_async() and
+       usb_autopm_put_interface_async() do almost the same things as
+       their non-async counterparts.  The differences are: they do
+       not acquire the PM mutex, and they use a workqueue to do their
+       jobs.  As a result they can be called in an atomic context,
+       such as an URB's completion handler, but when they return the
+       device will not generally not yet be in the desired state.
 
-       usb_autopm_enable() sets pm_usage_cnt to 1 and then calls
-       usb_autopm_set_interface(), which will attempt an autoresume.
+There also are a couple of utility routines drivers can use:
 
-       usb_autopm_disable() sets pm_usage_cnt to 0 and then calls
+       usb_autopm_enable() sets pm_usage_cnt to 0 and then calls
        usb_autopm_set_interface(), which will attempt an autosuspend.
 
+       usb_autopm_disable() sets pm_usage_cnt to 1 and then calls
+       usb_autopm_set_interface(), which will attempt an autoresume.
+
 The conventional usage pattern is that a driver calls
 usb_autopm_get_interface() in its open routine and
 usb_autopm_put_interface() in its close or release routine.  But
@@ -436,7 +448,12 @@ post_reset; the USB core guarantees that this is true of internal
 suspend/resume events as well.
 
 If a driver wants to block all suspend/resume calls during some
-critical section, it can simply acquire udev->pm_mutex.
+critical section, it can simply acquire udev->pm_mutex. Note that
+calls to resume may be triggered indirectly. Block IO due to memory
+allocations can make the vm subsystem resume a device. Thus while
+holding this lock you must not allocate memory with GFP_KERNEL or
+GFP_NOFS.
+
 Alternatively, if the critical section might call some of the
 usb_autopm_* routines, the driver can avoid deadlock by doing: