1. Patchew
  2. linux
  3. [PATCH v3 0/5] reduce system memory requirement for hibernation
  4. View patch

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

Samuel Zhang posted 5 patches 3 months ago
There is a newer version of this series
[PATCH v3 4/5] PM: hibernate: add new api pm_transition_event()
Posted by Samuel Zhang 3 months ago 
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.
+ *
+ * Return: PM_EVENT_ messages
+ */
+int pm_transition_event(void);
+
 struct dev_pm_info {
 	pm_message_t		power_state;
 	bool			can_wakeup:1;
-- 
2.43.5
Re: [PATCH v3 4/5] PM: hibernate: add new api pm_transition_event()
Posted by Mario Limonciello 3 months ago 
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;
Re: [PATCH v3 4/5] PM: hibernate: add new api pm_transition_event()
Posted by Zhang, GuoQing (Sam) 3 months ago 
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@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;
>
Re: [PATCH v3 4/5] PM: hibernate: add new api pm_transition_event()
Posted by Mario Limonciello 3 months ago 
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@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;
>>
Re: [PATCH v3 4/5] PM: hibernate: add new api pm_transition_event()
Posted by Rafael J. Wysocki 3 months ago 
On Tue, Jul 8, 2025 at 4:37 PM Mario Limonciello
<mario.limonciello@amd.com> 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@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.

+1

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

Patchew 2.1-devel-b67e4c2

© 2016 - 2025 Red Hat, Inc.