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

[Zhang, GuoQing (Sam)]

On 2025/7/8 22:36, Mario Limonciello wrote:
> 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 at 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.


Hi Mario, thank you for the feedback. I don't have experience on kdoc. 
do you mean generate new `Documentation/power/pm.rst` from 
`include/linux/pm.h` using the `scripts/kernel-doc` tool? Could you give 
some guidance on this? Thank you!

Regards
Sam


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