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

[Mario Limonciello <mario.limonciello@amd.com>]

On 7/8/2025 3:42 AM, Samuel Zhang wrote:
> 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        | 16 ++++++++++++++++
>   2 files changed, 21 insertions(+)
> 
> 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..d1cb77ede1a2 100644
> --- a/include/linux/pm.h
> +++ b/include/linux/pm.h
> @@ -657,6 +657,22 @@ struct pm_subsys_data {
>   #define DPM_FLAG_SMART_SUSPEND		BIT(2)
>   #define DPM_FLAG_MAY_SKIP_RESUME	BIT(3)
>   
> +/**
> + * pm_transition_event() - Query the current pm transition event value.
> + *
> + * Used to query the reason why thaw() is called. It will be one of 2 values:
> + *
> + * PM_EVENT_THAW: normal case.
> + *		hibernation image has been created.
> + *
> + * PM_EVENT_RECOVER: error case.
> + *		creation of a hibernation image or restoration of the main memory
> + *		contents from a hibernation image has failed.

I don't believe this documentation is complete.  In the use in this 
series those are two events used, but as this is now exported this might 
be used by other callers later which could use it for other PM_EVENT_*.

So because of this I think it's best to convert the comment in 
include/linux/pm.h to kdoc and then reference that from this kdoc.

> + *
> + * Return: PM_EVENT_ messages
> + */
> +int pm_transition_event(void);
> +
>   struct dev_pm_info {
>   	pm_message_t		power_state;
>   	bool			can_wakeup:1;