[PATCH v4 4/5] PM: hibernate: add new api pm_transition_event()

[Samuel Zhang <guoqing.zhang@amd.com>]

dev_pm_ops.thaw() is called in following cases:
* normal case: after hibernation image has been created.
* error case 1: creation of a hibernation image has failed.
* error case 2: restoration from a hibernation image has failed.

For normal case, it is called mainly for resume storage devices for
saving the hibernation image. Other devices that are not involved
in the image saving do not need to resume the device. But since there's
no api to know which case thaw() is called, device drivers can't
conditionally resume device in thaw().

The new pm_transition_event() is such a api to query if thaw() is called
in normal case. The returned value in thaw() is:
* PM_EVENT_THAW: normal case, no need to resume non-storage devices.
* PM_EVENT_RECOVER: error case, need to resume devices.

Signed-off-by: Samuel Zhang <guoqing.zhang@amd.com>
---
 drivers/base/power/main.c |  5 +++
 include/linux/pm.h        | 85 +++++++++++++++++++++++----------------
 2 files changed, 56 insertions(+), 34 deletions(-)

diff --git a/drivers/base/power/main.c b/drivers/base/power/main.c
index 40e1d8d8a589..7e0982caa4d4 100644
--- a/drivers/base/power/main.c
+++ b/drivers/base/power/main.c
@@ -62,6 +62,11 @@ static LIST_HEAD(dpm_noirq_list);
 
 static DEFINE_MUTEX(dpm_list_mtx);
 static pm_message_t pm_transition;
+int pm_transition_event(void)
+{
+	return pm_transition.event;
+}
+EXPORT_SYMBOL_GPL(pm_transition_event);
 
 static int async_error;
 
diff --git a/include/linux/pm.h b/include/linux/pm.h
index 78855d794342..7e7b843ba823 100644
--- a/include/linux/pm.h
+++ b/include/linux/pm.h
@@ -471,58 +471,59 @@ const struct dev_pm_ops name = { \
 #define pm_ptr(_ptr) PTR_IF(IS_ENABLED(CONFIG_PM), (_ptr))
 #define pm_sleep_ptr(_ptr) PTR_IF(IS_ENABLED(CONFIG_PM_SLEEP), (_ptr))
 
-/*
- * PM_EVENT_ messages
+/**
+ * pm_transition_event() - Query the current pm transition event value.
+ *
+ * One example is used to query the reason why thaw() is called.
+ * It will return one of 2 values in this usage:
+ * * %PM_EVENT_THAW: normal case.
+ * * %PM_EVENT_RECOVER: error case.
+ *
+ * For other usage, it may return other values. See :ref:`PM_EVENT_ messages`
+ * for all possible values.
+ *
+ * Return: One of the %PM_EVENT_ messages
+ */
+int pm_transition_event(void);
+
+/**
+ * DOC: PM_EVENT_ messages
  *
- * The following PM_EVENT_ messages are defined for the internal use of the PM
+ * The possible return values of %pm_transition_event().
+ *
+ * The following PM_EVENT_ messages are defined for the use of drivers and PM
  * core, in order to provide a mechanism allowing the high level suspend and
  * hibernation code to convey the necessary information to the device PM core
  * code:
  *
- * ON		No transition.
+ * %PM_EVENT_ON:		No transition.
  *
- * FREEZE	System is going to hibernate, call ->prepare() and ->freeze()
- *		for all devices.
+ * %PM_EVENT_FREEZE:	System is going to hibernate, call ->prepare() and
+ *		->freeze() for all devices.
  *
- * SUSPEND	System is going to suspend, call ->prepare() and ->suspend()
- *		for all devices.
+ * %PM_EVENT_SUSPEND:	System is going to suspend, call ->prepare() and
+ *		->suspend() for all devices.
  *
- * HIBERNATE	Hibernation image has been saved, call ->prepare() and
+ * %PM_EVENT_HIBERNATE:	Hibernation image has been saved, call ->prepare() and
  *		->poweroff() for all devices.
  *
- * QUIESCE	Contents of main memory are going to be restored from a (loaded)
- *		hibernation image, call ->prepare() and ->freeze() for all
+ * %PM_EVENT_QUIESCE:	Contents of main memory are going to be restored from
+ *		a (loaded) hibernation image, call ->prepare() and ->freeze() for all
  *		devices.
  *
- * RESUME	System is resuming, call ->resume() and ->complete() for all
- *		devices.
+ * %PM_EVENT_RESUME:	System is resuming, call ->resume() and ->complete()
+ *		for all devices.
  *
- * THAW		Hibernation image has been created, call ->thaw() and
+ * %PM_EVENT_THAW:		Hibernation image has been created, call ->thaw() and
  *		->complete() for all devices.
  *
- * RESTORE	Contents of main memory have been restored from a hibernation
- *		image, call ->restore() and ->complete() for all devices.
+ * %PM_EVENT_RESTORE:	Contents of main memory have been restored from a
+ *		hibernation image, call ->restore() and ->complete() for all devices.
  *
- * RECOVER	Creation of a hibernation image or restoration of the main
- *		memory contents from a hibernation image has failed, call
+ * %PM_EVENT_RECOVER:	Creation of a hibernation image or restoration of the
+ *		main memory contents from a hibernation image has failed, call
  *		->thaw() and ->complete() for all devices.
- *
- * The following PM_EVENT_ messages are defined for internal use by
- * kernel subsystems.  They are never issued by the PM core.
- *
- * USER_SUSPEND		Manual selective suspend was issued by userspace.
- *
- * USER_RESUME		Manual selective resume was issued by userspace.
- *
- * REMOTE_WAKEUP	Remote-wakeup request was received from the device.
- *
- * AUTO_SUSPEND		Automatic (device idle) runtime suspend was
- *			initiated by the subsystem.
- *
- * AUTO_RESUME		Automatic (device needed) runtime resume was
- *			requested by a driver.
  */
-
 #define PM_EVENT_INVALID	(-1)
 #define PM_EVENT_ON		0x0000
 #define PM_EVENT_FREEZE		0x0001
@@ -537,6 +538,22 @@ const struct dev_pm_ops name = { \
 #define PM_EVENT_REMOTE		0x0200
 #define PM_EVENT_AUTO		0x0400
 
+/*
+ * The following PM_EVENT_ messages are defined for internal use by
+ * kernel subsystems.  They are never issued by the PM core.
+ *
+ * USER_SUSPEND	Manual selective suspend was issued by userspace.
+ *
+ * USER_RESUME	Manual selective resume was issued by userspace.
+ *
+ * REMOTE_WAKEUP	Remote-wakeup request was received from the device.
+ *
+ * AUTO_SUSPEND	Automatic (device idle) runtime suspend was
+ *			initiated by the subsystem.
+ *
+ * AUTO_RESUME	Automatic (device needed) runtime resume was
+ *			requested by a driver.
+ */
 #define PM_EVENT_SLEEP		(PM_EVENT_SUSPEND | PM_EVENT_HIBERNATE)
 #define PM_EVENT_USER_SUSPEND	(PM_EVENT_USER | PM_EVENT_SUSPEND)
 #define PM_EVENT_USER_RESUME	(PM_EVENT_USER | PM_EVENT_RESUME)
-- 
2.43.5