Merge tag 'dmaengine-3.17' of git://git.kernel.org/pub/scm/linux/kernel/git/djbw...

[firefly-linux-kernel-4.4.55.git] / include / linux / pm.h

diff --git a/include/linux/pm.h b/include/linux/pm.h
index d915d0345fa1beb770a742e82247916c440e9543..72c0fe098a27871aa1ea44ea0076d45ab696ea2e 100644 (file)
--- a/include/linux/pm.h
+++ b/include/linux/pm.h
@@ -93,13 +93,23 @@ typedef struct pm_message {
  *     been registered) to recover from the race condition.
  *     This method is executed for all kinds of suspend transitions and is
  *     followed by one of the suspend callbacks: @suspend(), @freeze(), or
- *     @poweroff().  The PM core executes subsystem-level @prepare() for all
- *     devices before starting to invoke suspend callbacks for any of them, so
- *     generally devices may be assumed to be functional or to respond to
- *     runtime resume requests while @prepare() is being executed.  However,
- *     device drivers may NOT assume anything about the availability of user
- *     space at that time and it is NOT valid to request firmware from within
- *     @prepare() (it's too late to do that).  It also is NOT valid to allocate
+ *     @poweroff().  If the transition is a suspend to memory or standby (that
+ *     is, not related to hibernation), the return value of @prepare() may be
+ *     used to indicate to the PM core to leave the device in runtime suspend
+ *     if applicable.  Namely, if @prepare() returns a positive number, the PM
+ *     core will understand that as a declaration that the device appears to be
+ *     runtime-suspended and it may be left in that state during the entire
+ *     transition and during the subsequent resume if all of its descendants
+ *     are left in runtime suspend too.  If that happens, @complete() will be
+ *     executed directly after @prepare() and it must ensure the proper
+ *     functioning of the device after the system resume.
+ *     The PM core executes subsystem-level @prepare() for all devices before
+ *     starting to invoke suspend callbacks for any of them, so generally
+ *     devices may be assumed to be functional or to respond to runtime resume
+ *     requests while @prepare() is being executed.  However, device drivers
+ *     may NOT assume anything about the availability of user space at that
+ *     time and it is NOT valid to request firmware from within @prepare()
+ *     (it's too late to do that).  It also is NOT valid to allocate
  *     substantial amounts of memory from @prepare() in the GFP_KERNEL mode.
  *     [To work around these limitations, drivers may register suspend and
  *     hibernation notifiers to be executed before the freezing of tasks.]
@@ -112,7 +122,16 @@ typedef struct pm_message {
  *     of the other devices that the PM core has unsuccessfully attempted to
  *     suspend earlier).
  *     The PM core executes subsystem-level @complete() after it has executed
- *     the appropriate resume callbacks for all devices.
+ *     the appropriate resume callbacks for all devices.  If the corresponding
+ *     @prepare() at the beginning of the suspend transition returned a
+ *     positive number and the device was left in runtime suspend (without
+ *     executing any suspend and resume callbacks for it), @complete() will be
+ *     the only callback executed for the device during resume.  In that case,
+ *     @complete() must be prepared to do whatever is necessary to ensure the
+ *     proper functioning of the device after the system resume.  To this end,
+ *     @complete() can check the power.direct_complete flag of the device to
+ *     learn whether (unset) or not (set) the previous suspend and resume
+ *     callbacks have been executed for it.
  *
  * @suspend: Executed before putting the system into a sleep state in which the
  *     contents of main memory are preserved.  The exact action to perform
@@ -546,6 +565,7 @@ struct dev_pm_info {
        bool                    is_late_suspended:1;
        bool                    ignore_children:1;
        bool                    early_init:1;   /* Owned by the PM core */
+       bool                    direct_complete:1;      /* Owned by the PM core */
        spinlock_t              lock;
 #ifdef CONFIG_PM_SLEEP
        struct list_head        entry;