PM: sleep: Add kerneldoc comments to some functions

Commit Message

Rafael J. Wysocki May 17, 2019, 10:56 a.m. UTC

From: Rafael J. Wysocki <[e-mail]>

Add kerneldoc comments to pm_suspend_via_firmware(),
pm_resume_via_firmware() and pm_suspend_via_s2idle() to explain
what they do.

Signed-off-by: Rafael J. Wysocki <[e-mail]>
---
 include/linux/suspend.h |   20 ++++++++++++++++++++
 kernel/power/suspend.c  |    6 ++++++
 2 files changed, 26 insertions(+)

Comments

Christoph Hellwig May 20, 2019, 6:02 a.m. UTC | #1

>  
> +/**
> + * pm_suspend_via_firmware - Check if platform firmware will suspend the system.
> + *
> + * To be called during system-wide power management transitions to sleep states.
> + *
> + * Return 'true' if the platform firmware is going to be invoked at the end of
> + * the system-wide power management transition in progress in order to complete
> + * it.
> + */

Ok, so this only returns true if the firmware gets invoked for this
particular transition we are currently in.  That was my main confusion
here.  Also any chance to add an example of why this might matter?

Rafael J. Wysocki May 27, 2019, 9:36 a.m. UTC | #2

On Mon, May 20, 2019 at 8:03 AM Christoph Hellwig <[e-mail]> wrote:
>
> >
> > +/**
> > + * pm_suspend_via_firmware - Check if platform firmware will suspend the system.
> > + *
> > + * To be called during system-wide power management transitions to sleep states.
> > + *
> > + * Return 'true' if the platform firmware is going to be invoked at the end of
> > + * the system-wide power management transition in progress in order to complete
> > + * it.
> > + */
>
> Ok, so this only returns true if the firmware gets invoked for this
> particular transition we are currently in.

Right.

> That was my main confusion here.
> Also any chance to add an example of why this might matter?

Sure, I will send an update shortly.

Patch

Index: linux-pm/include/linux/suspend.h
===================================================================
--- linux-pm.orig/include/linux/suspend.h
+++ linux-pm/include/linux/suspend.h
@@ -227,11 +227,31 @@  static inline void pm_set_resume_via_fir
 	pm_suspend_global_flags |= PM_SUSPEND_FLAG_FW_RESUME;
 }
 
+/**
+ * pm_suspend_via_firmware - Check if platform firmware will suspend the system.
+ *
+ * To be called during system-wide power management transitions to sleep states.
+ *
+ * Return 'true' if the platform firmware is going to be invoked at the end of
+ * the system-wide power management transition in progress in order to complete
+ * it.
+ */
 static inline bool pm_suspend_via_firmware(void)
 {
 	return !!(pm_suspend_global_flags & PM_SUSPEND_FLAG_FW_SUSPEND);
 }
 
+/**
+ * pm_resume_via_firmware - Check if platform firmware has woken up the system.
+ *
+ * To be called during system-wide power management transitions from sleep
+ * states.
+ *
+ * Return 'true' if the platform firmware has passed control to the kernel at
+ * the beginning of the system-wide power management transition in progress, so
+ * the event that woke up the system from sleep has been handled by the platform
+ * firmware.
+ */
 static inline bool pm_resume_via_firmware(void)
 {
 	return !!(pm_suspend_global_flags & PM_SUSPEND_FLAG_FW_RESUME);
Index: linux-pm/kernel/power/suspend.c
===================================================================
--- linux-pm.orig/kernel/power/suspend.c
+++ linux-pm/kernel/power/suspend.c
@@ -62,6 +62,12 @@  static DECLARE_SWAIT_QUEUE_HEAD(s2idle_w
 enum s2idle_states __read_mostly s2idle_state;
 static DEFINE_RAW_SPINLOCK(s2idle_lock);
 
+/**
+ * pm_suspend_via_s2idle - Check if suspend-to-idle is the default suspend.
+ *
+ * Return 'true' if suspend-to-idle has been selected as the default system
+ * suspend method.
+ */
 bool pm_suspend_via_s2idle(void)
 {
 	return mem_sleep_current == PM_SUSPEND_TO_IDLE;