Suspend: Introduce begin() and end() callbacks

On ACPI systems the target state set by acpi_pm_set_target() is
reset by acpi_pm_finish(), but that need not be called if the
suspend fails.  All platforms that use the .set_target() global
suspend callback are affected by analogous issues.

For this reason, we need an additional global suspend callback that
will reset the target state regardless of whether or not the suspend
is successful.  Also, it is reasonable to rename the .set_target()
callback, since it will be used for a different purpose on ACPI
systems (due to ACPI 1.0x code ordering requirements).

Introduce the global suspend callback .end() to be executed at the
end of the suspend sequence and rename the .set_target() global
suspend callback to .begin().

Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl>
Signed-off-by: Len Brown <len.brown@intel.com>

1 files changed, 18 insertions, 11 deletions

diff --git a/include/linux/suspend.h b/include/linux/suspend.h
index 51283e0745b..a0b1dbb5919 100644
--- a/include/linux/suspend.h
+++ b/include/linux/suspend.h
@@ -38,18 +38,16 @@ typedef int __bitwise suspend_state_t;
  *      There is the %suspend_valid_only_mem function available that can be
  *      assigned to this if the platform only supports mem sleep.
  *
- * @set_target: Tell the platform which system sleep state is going to be
- *      entered.
- *      @set_target() is executed right prior to suspending devices.  The
- *      information conveyed to the platform code by @set_target() should be
- *      disregarded by the platform as soon as @finish() is executed and if
- *      @prepare() fails.  If @set_target() fails (ie. returns nonzero),
+ * @begin: Initialise a transition to given system sleep state.
+ *      @begin() is executed right prior to suspending devices.  The information
+ *      conveyed to the platform code by @begin() should be disregarded by it as
+ *      soon as @end() is executed.  If @begin() fails (ie. returns nonzero),
  *      @prepare(), @enter() and @finish() will not be called by the PM core.
  *      This callback is optional.  However, if it is implemented, the argument
- *      passed to @enter() is meaningless and should be ignored.
+ *      passed to @enter() is redundant and should be ignored.
  *
  * @prepare: Prepare the platform for entering the system sleep state indicated
- *      by @set_target().
+ *      by @begin().
  *      @prepare() is called right after devices have been suspended (ie. the
  *      appropriate .suspend() method has been executed for each device) and
  *      before the nonboot CPUs are disabled (it is executed with IRQs enabled).
@@ -57,8 +55,8 @@ typedef int __bitwise suspend_state_t;
  *      error code otherwise, in which case the system cannot enter the desired
  *      sleep state (@enter() and @finish() will not be called in that case).
  *
- * @enter: Enter the system sleep state indicated by @set_target() or
- *      represented by the argument if @set_target() is not implemented.
+ * @enter: Enter the system sleep state indicated by @begin() or represented by
+ *      the argument if @begin() is not implemented.
  *      This callback is mandatory.  It returns 0 on success or a negative
  *      error code otherwise, in which case the system cannot enter the desired
  *      sleep state.
@@ -69,13 +67,22 @@ typedef int __bitwise suspend_state_t;
  *      This callback is optional, but should be implemented by the platforms
  *      that implement @prepare().  If implemented, it is always called after
  *      @enter() (even if @enter() fails).
+ *
+ * @end: Called by the PM core right after resuming devices, to indicate to
+ *      the platform that the system has returned to the working state or
+ *      the transition to the sleep state has been aborted.
+ *      This callback is optional, but should be implemented by the platforms
+ *      that implement @begin(), but platforms implementing @begin() should
+ *      also provide a @end() which cleans up transitions aborted before
+ *      @enter().
  */
 struct platform_suspend_ops {
         int (*valid)(suspend_state_t state);
-        int (*set_target)(suspend_state_t state);
+        int (*begin)(suspend_state_t state);
         int (*prepare)(void);
         int (*enter)(suspend_state_t state);
         void (*finish)(void);
+        void (*end)(void);
 };
 
 #ifdef CONFIG_SUSPEND