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

[Mario Limonciello]

On 7/8/2025 12:07 PM, Zhang, GuoQing (Sam) wrote:
> 
> 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!

If the comment starts with /* it's a regular comment.  If it starts with 
/** it's a kernel doc.

You should just need to convert it to a kdoc by changing it to /**.

Then you can reference it using a link (IIRC)

https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html

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