PM: sleep: Add kerneldoc comments to some functions
Subsystems (2)
PATCH v2 1/1 PM: sleep: Add kerneldoc comments to some functions
From: Rafael J. Wysocki <[email protected]>
Add kerneldoc comments to pm_suspend_via_firmware(), pm_resume_via_firmware() and pm_suspend_via_s2idle() to explain what they do.
---
-> v2:
Put more information into the pm_suspend_via_firmware() kerneldoc comment.
--- include/linux/suspend.h | 31 +++++++++++++++++++++++++++++++ kernel/power/suspend.c | 6 ++++++ 2 files changed, 37 insertions(+)
include/linux/suspend.h +31 -0
@@ -227,11 +227,42 @@ 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 +* or during the subsequent system-wide transitions back to the working state. +* +* Return 'true' if the platform firmware is going to be invoked at the end of +* the system-wide power management transition (to a sleep state) in progress in +* order to complete it, or if the platform firmware has been invoked in order +* to complete the last (or preceding) transition of the system to a sleep +* state. +* +* This matters if the caller needs or wants to carry out some special actions +* depending on whether or not control will be passed to the platform firmware +* subsequently (for example, the device may need to be reset before letting the +* platform firmware manipulate it, which is not necessary when the platform +* firmware is not going to be invoked) or when such special actions may have +* been carried out during the preceding transition of the system to a sleep +* state (as they may need to be taken into account). +*/ 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 );
kernel/power/suspend.c +6 -0
@@ -62,6 +62,12 @@ static DECLARE_SWAIT_QUEUE_HEAD(s2idle_wenum 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 ;
Quoted 11 lines · CEST Rafael J. Wysocki
From: Rafael J. Wysocki <[email protected]>
Add kerneldoc comments to
pm_suspend_via_firmware(),pm_resume_via_firmware()andpm_suspend_via_s2idle()to explain what they do.Signed-off-by Rafael J. Wysocki <[email protected]>---
-> v2:
Put more information into thepm_suspend_via_firmware()kerneldoc comment.
It doesn't look like there are any more comments here, so I'll be queuing up this one.
Quoted 74 lines
--- include/linux/suspend.h | 31 +++++++++++++++++++++++++++++++ kernel/power/suspend.c | 6 ++++++ 2 files changed, 37 insertions(+)Index:
linux-pm/include/linux/suspend.h
===================================================================include/linux/suspend.h +31
-0@@ -227,11 +227,42 @@ 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 +* or during the subsequent system-wide transitions back to the working state. +* +* Return 'true' if the platform firmware is going to be invoked at the end of +* the system-wide power management transition (to a sleep state) in progress in +* order to complete it, or if the platform firmware has been invoked in order +* to complete the last (or preceding) transition of the system to a sleep +* state. +* +* This matters if the caller needs or wants to carry out some special actions +* depending on whether or not control will be passed to the platform firmware +* subsequently (for example, the device may need to be reset before letting the +* platform firmware manipulate it, which is not necessary when the platform +* firmware is not going to be invoked) or when such special actions may have +* been carried out during the preceding transition of the system to a sleep +* state (as they may need to be taken into account). +*/ 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
===================================================================kernel/power/suspend.c +6
-0@@ -62,6 +62,12 @@ static DECLARE_SWAIT_QUEUE_HEAD(s2idle_wenum 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 ;