linux-kernel - Re: [PATCH v3 4/5] PM: hibernate: add new api pm_transition

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <fe24f8ab-39f7-4471-beb5-e623ea3fb75a@amd.com>
Date: Tue, 8 Jul 2025 12:11:07 -0400
From: Mario Limonciello <mario.limonciello@....com>
To: "Zhang, GuoQing (Sam)" <guoqzhan@....com>,
 Samuel Zhang <guoqing.zhang@....com>, alexander.deucher@....com,
 christian.koenig@....com, rafael@...nel.org, len.brown@...el.com,
 pavel@...nel.org, gregkh@...uxfoundation.org, dakr@...nel.org,
 airlied@...il.com, simona@...ll.ch, ray.huang@....com,
 matthew.auld@...el.com, matthew.brost@...el.com,
 maarten.lankhorst@...ux.intel.com, mripard@...nel.org, tzimmermann@...e.de
Cc: lijo.lazar@....com, victor.zhao@....com, haijun.chang@....com,
 Qing.Ma@....com, Owen.Zhang2@....com, linux-pm@...r.kernel.org,
 linux-kernel@...r.kernel.org, amd-gfx@...ts.freedesktop.org,
 dri-devel@...ts.freedesktop.org
Subject: Re: [PATCH v3 4/5] PM: hibernate: add new api pm_transition_event()

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@....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;
>>