* Re: [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation
2025-10-22 20:26 [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation Rafael J. Wysocki
@ 2025-10-22 20:44 ` Brian Norris
2025-10-23 10:17 ` Rafael J. Wysocki
2025-10-23 10:14 ` Ulf Hansson
2025-10-23 13:16 ` Ilpo Järvinen
2 siblings, 1 reply; 5+ messages in thread
From: Brian Norris @ 2025-10-22 20:44 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Linux PM, LKML, Ulf Hansson, Lukas Wunner, Ilpo Järvinen
Hi Rafael,
On Wed, Oct 22, 2025 at 10:26:23PM +0200, Rafael J. Wysocki wrote:
> From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
>
> Drop confusing descriptions of pm_runtime_allow() and pm_runtime_forbid()
> from Documentation/power/runtime_pm.rst and update the kerneldoc comments
> of these functions to better explain their purpose.
>
> Link: https://lore.kernel.org/linux-pm/08976178-298f-79d9-1d63-cff5a4e56cc3@linux.intel.com/
> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> ---
> Documentation/power/runtime_pm.rst | 10 ----------
> drivers/base/power/runtime.c | 17 +++++++++++++----
> 2 files changed, 13 insertions(+), 14 deletions(-)
>
> --- a/Documentation/power/runtime_pm.rst
> +++ b/Documentation/power/runtime_pm.rst
> @@ -480,16 +480,6 @@ drivers/base/power/runtime.c and include
> `bool pm_runtime_status_suspended(struct device *dev);`
> - return true if the device's runtime PM status is 'suspended'
>
> - `void pm_runtime_allow(struct device *dev);`
> - - set the power.runtime_auto flag for the device and decrease its usage
> - counter (used by the /sys/devices/.../power/control interface to
> - effectively allow the device to be power managed at run time)
> -
> - `void pm_runtime_forbid(struct device *dev);`
> - - unset the power.runtime_auto flag for the device and increase its usage
> - counter (used by the /sys/devices/.../power/control interface to
> - effectively prevent the device from being power managed at run time)
> -
It feels a little odd just to strip 2 of the APIs from this doc, while
the rest remain. I'm not too familiar with ReST, nor with kerneldoc
integration, but would something like this work as a replacement?
.. kernel-doc:: drivers/base/power/runtime.c
:export:
.. kernel-doc:: include/linux/pm_runtime.h
> `void pm_runtime_no_callbacks(struct device *dev);`
> - set the power.no_callbacks flag for the device and remove the runtime
> PM attributes from /sys/devices/.../power (or prevent them from being
> --- a/drivers/base/power/runtime.c
> +++ b/drivers/base/power/runtime.c
> @@ -1664,9 +1664,12 @@ EXPORT_SYMBOL_GPL(devm_pm_runtime_get_no
> * pm_runtime_forbid - Block runtime PM of a device.
> * @dev: Device to handle.
> *
> - * Increase the device's usage count and clear its power.runtime_auto flag,
> - * so that it cannot be suspended at run time until pm_runtime_allow() is called
> - * for it.
> + * Resume @dev if already suspended and block runtime suspend of @dev in such
> + * a way that it can be unblocked via the /sys/devices/.../power/control
> + * interface, or otherwise by calling pm_runtime_allow().
> + *
> + * Calling this function many times in a row has the same effect as calling it
> + * once.
> */
> void pm_runtime_forbid(struct device *dev)
> {
> @@ -1687,7 +1690,13 @@ EXPORT_SYMBOL_GPL(pm_runtime_forbid);
> * pm_runtime_allow - Unblock runtime PM of a device.
> * @dev: Device to handle.
> *
> - * Decrease the device's usage count and set its power.runtime_auto flag.
> + * Unblock runtime suspend of @dev after it has been blocked by
> + * pm_runtime_forbid() (for instance, if it has been blocked via the
> + * /sys/devices/.../power/control interface), check if @dev can be
> + * suspended and suspend it in that case.
> + *
> + * Calling this function many times in a row has the same effect as calling it
> + * once.
> */
> void pm_runtime_allow(struct device *dev)
> {
The rewording looks helpful, as it's much more API-user-oriented now. So
this looks good to me as-is, even if there are other potential
improvements to make:
Reviewed-by: Brian Norris <briannorris@chromium.org>
Thanks!
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation
2025-10-22 20:44 ` Brian Norris
@ 2025-10-23 10:17 ` Rafael J. Wysocki
0 siblings, 0 replies; 5+ messages in thread
From: Rafael J. Wysocki @ 2025-10-23 10:17 UTC (permalink / raw)
To: Brian Norris
Cc: Rafael J. Wysocki, Linux PM, LKML, Ulf Hansson, Lukas Wunner,
Ilpo Järvinen
Hi Brian,
On Wed, Oct 22, 2025 at 10:44 PM Brian Norris <briannorris@chromium.org> wrote:
>
> Hi Rafael,
>
> On Wed, Oct 22, 2025 at 10:26:23PM +0200, Rafael J. Wysocki wrote:
> > From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> >
> > Drop confusing descriptions of pm_runtime_allow() and pm_runtime_forbid()
> > from Documentation/power/runtime_pm.rst and update the kerneldoc comments
> > of these functions to better explain their purpose.
> >
> > Link: https://lore.kernel.org/linux-pm/08976178-298f-79d9-1d63-cff5a4e56cc3@linux.intel.com/
> > Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> > ---
> > Documentation/power/runtime_pm.rst | 10 ----------
> > drivers/base/power/runtime.c | 17 +++++++++++++----
> > 2 files changed, 13 insertions(+), 14 deletions(-)
> >
> > --- a/Documentation/power/runtime_pm.rst
> > +++ b/Documentation/power/runtime_pm.rst
> > @@ -480,16 +480,6 @@ drivers/base/power/runtime.c and include
> > `bool pm_runtime_status_suspended(struct device *dev);`
> > - return true if the device's runtime PM status is 'suspended'
> >
> > - `void pm_runtime_allow(struct device *dev);`
> > - - set the power.runtime_auto flag for the device and decrease its usage
> > - counter (used by the /sys/devices/.../power/control interface to
> > - effectively allow the device to be power managed at run time)
> > -
> > - `void pm_runtime_forbid(struct device *dev);`
> > - - unset the power.runtime_auto flag for the device and increase its usage
> > - counter (used by the /sys/devices/.../power/control interface to
> > - effectively prevent the device from being power managed at run time)
> > -
>
> It feels a little odd just to strip 2 of the APIs from this doc, while
> the rest remain. I'm not too familiar with ReST, nor with kerneldoc
> integration, but would something like this work as a replacement?
>
> .. kernel-doc:: drivers/base/power/runtime.c
> :export:
>
> .. kernel-doc:: include/linux/pm_runtime.h
Well, that's the plan for the future.
> > `void pm_runtime_no_callbacks(struct device *dev);`
> > - set the power.no_callbacks flag for the device and remove the runtime
> > PM attributes from /sys/devices/.../power (or prevent them from being
> > --- a/drivers/base/power/runtime.c
> > +++ b/drivers/base/power/runtime.c
> > @@ -1664,9 +1664,12 @@ EXPORT_SYMBOL_GPL(devm_pm_runtime_get_no
> > * pm_runtime_forbid - Block runtime PM of a device.
> > * @dev: Device to handle.
> > *
> > - * Increase the device's usage count and clear its power.runtime_auto flag,
> > - * so that it cannot be suspended at run time until pm_runtime_allow() is called
> > - * for it.
> > + * Resume @dev if already suspended and block runtime suspend of @dev in such
> > + * a way that it can be unblocked via the /sys/devices/.../power/control
> > + * interface, or otherwise by calling pm_runtime_allow().
> > + *
> > + * Calling this function many times in a row has the same effect as calling it
> > + * once.
> > */
> > void pm_runtime_forbid(struct device *dev)
> > {
> > @@ -1687,7 +1690,13 @@ EXPORT_SYMBOL_GPL(pm_runtime_forbid);
> > * pm_runtime_allow - Unblock runtime PM of a device.
> > * @dev: Device to handle.
> > *
> > - * Decrease the device's usage count and set its power.runtime_auto flag.
> > + * Unblock runtime suspend of @dev after it has been blocked by
> > + * pm_runtime_forbid() (for instance, if it has been blocked via the
> > + * /sys/devices/.../power/control interface), check if @dev can be
> > + * suspended and suspend it in that case.
> > + *
> > + * Calling this function many times in a row has the same effect as calling it
> > + * once.
> > */
> > void pm_runtime_allow(struct device *dev)
> > {
>
> The rewording looks helpful, as it's much more API-user-oriented now. So
> this looks good to me as-is, even if there are other potential
> improvements to make:
>
> Reviewed-by: Brian Norris <briannorris@chromium.org>
Thanks!
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation
2025-10-22 20:26 [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation Rafael J. Wysocki
2025-10-22 20:44 ` Brian Norris
@ 2025-10-23 10:14 ` Ulf Hansson
2025-10-23 13:16 ` Ilpo Järvinen
2 siblings, 0 replies; 5+ messages in thread
From: Ulf Hansson @ 2025-10-23 10:14 UTC (permalink / raw)
To: Rafael J. Wysocki
Cc: Linux PM, LKML, Brian Norris, Lukas Wunner, Ilpo Järvinen
On Wed, 22 Oct 2025 at 22:26, Rafael J. Wysocki <rafael@kernel.org> wrote:
>
> From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
>
> Drop confusing descriptions of pm_runtime_allow() and pm_runtime_forbid()
> from Documentation/power/runtime_pm.rst and update the kerneldoc comments
> of these functions to better explain their purpose.
>
> Link: https://lore.kernel.org/linux-pm/08976178-298f-79d9-1d63-cff5a4e56cc3@linux.intel.com/
> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
Reviewed-by: Ulf Hansson <ulf.hansson@linaro.org>
Kind regards
Uffe
> ---
> Documentation/power/runtime_pm.rst | 10 ----------
> drivers/base/power/runtime.c | 17 +++++++++++++----
> 2 files changed, 13 insertions(+), 14 deletions(-)
>
> --- a/Documentation/power/runtime_pm.rst
> +++ b/Documentation/power/runtime_pm.rst
> @@ -480,16 +480,6 @@ drivers/base/power/runtime.c and include
> `bool pm_runtime_status_suspended(struct device *dev);`
> - return true if the device's runtime PM status is 'suspended'
>
> - `void pm_runtime_allow(struct device *dev);`
> - - set the power.runtime_auto flag for the device and decrease its usage
> - counter (used by the /sys/devices/.../power/control interface to
> - effectively allow the device to be power managed at run time)
> -
> - `void pm_runtime_forbid(struct device *dev);`
> - - unset the power.runtime_auto flag for the device and increase its usage
> - counter (used by the /sys/devices/.../power/control interface to
> - effectively prevent the device from being power managed at run time)
> -
> `void pm_runtime_no_callbacks(struct device *dev);`
> - set the power.no_callbacks flag for the device and remove the runtime
> PM attributes from /sys/devices/.../power (or prevent them from being
> --- a/drivers/base/power/runtime.c
> +++ b/drivers/base/power/runtime.c
> @@ -1664,9 +1664,12 @@ EXPORT_SYMBOL_GPL(devm_pm_runtime_get_no
> * pm_runtime_forbid - Block runtime PM of a device.
> * @dev: Device to handle.
> *
> - * Increase the device's usage count and clear its power.runtime_auto flag,
> - * so that it cannot be suspended at run time until pm_runtime_allow() is called
> - * for it.
> + * Resume @dev if already suspended and block runtime suspend of @dev in such
> + * a way that it can be unblocked via the /sys/devices/.../power/control
> + * interface, or otherwise by calling pm_runtime_allow().
> + *
> + * Calling this function many times in a row has the same effect as calling it
> + * once.
> */
> void pm_runtime_forbid(struct device *dev)
> {
> @@ -1687,7 +1690,13 @@ EXPORT_SYMBOL_GPL(pm_runtime_forbid);
> * pm_runtime_allow - Unblock runtime PM of a device.
> * @dev: Device to handle.
> *
> - * Decrease the device's usage count and set its power.runtime_auto flag.
> + * Unblock runtime suspend of @dev after it has been blocked by
> + * pm_runtime_forbid() (for instance, if it has been blocked via the
> + * /sys/devices/.../power/control interface), check if @dev can be
> + * suspended and suspend it in that case.
> + *
> + * Calling this function many times in a row has the same effect as calling it
> + * once.
> */
> void pm_runtime_allow(struct device *dev)
> {
>
>
>
^ permalink raw reply [flat|nested] 5+ messages in thread* Re: [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation
2025-10-22 20:26 [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation Rafael J. Wysocki
2025-10-22 20:44 ` Brian Norris
2025-10-23 10:14 ` Ulf Hansson
@ 2025-10-23 13:16 ` Ilpo Järvinen
2 siblings, 0 replies; 5+ messages in thread
From: Ilpo Järvinen @ 2025-10-23 13:16 UTC (permalink / raw)
To: Rafael J. Wysocki; +Cc: Linux PM, LKML, Ulf Hansson, Brian Norris, Lukas Wunner
[-- Attachment #1: Type: text/plain, Size: 3430 bytes --]
On Wed, 22 Oct 2025, Rafael J. Wysocki wrote:
> From: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
>
> Drop confusing descriptions of pm_runtime_allow() and pm_runtime_forbid()
> from Documentation/power/runtime_pm.rst and update the kerneldoc comments
> of these functions to better explain their purpose.
>
> Link: https://lore.kernel.org/linux-pm/08976178-298f-79d9-1d63-cff5a4e56cc3@linux.intel.com/
> Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
> ---
> Documentation/power/runtime_pm.rst | 10 ----------
> drivers/base/power/runtime.c | 17 +++++++++++++----
> 2 files changed, 13 insertions(+), 14 deletions(-)
>
> --- a/Documentation/power/runtime_pm.rst
> +++ b/Documentation/power/runtime_pm.rst
> @@ -480,16 +480,6 @@ drivers/base/power/runtime.c and include
> `bool pm_runtime_status_suspended(struct device *dev);`
> - return true if the device's runtime PM status is 'suspended'
>
> - `void pm_runtime_allow(struct device *dev);`
> - - set the power.runtime_auto flag for the device and decrease its usage
> - counter (used by the /sys/devices/.../power/control interface to
> - effectively allow the device to be power managed at run time)
> -
> - `void pm_runtime_forbid(struct device *dev);`
> - - unset the power.runtime_auto flag for the device and increase its usage
> - counter (used by the /sys/devices/.../power/control interface to
> - effectively prevent the device from being power managed at run time)
> -
> `void pm_runtime_no_callbacks(struct device *dev);`
> - set the power.no_callbacks flag for the device and remove the runtime
> PM attributes from /sys/devices/.../power (or prevent them from being
> --- a/drivers/base/power/runtime.c
> +++ b/drivers/base/power/runtime.c
> @@ -1664,9 +1664,12 @@ EXPORT_SYMBOL_GPL(devm_pm_runtime_get_no
> * pm_runtime_forbid - Block runtime PM of a device.
> * @dev: Device to handle.
> *
> - * Increase the device's usage count and clear its power.runtime_auto flag,
> - * so that it cannot be suspended at run time until pm_runtime_allow() is called
> - * for it.
> + * Resume @dev if already suspended and block runtime suspend of @dev in such
> + * a way that it can be unblocked via the /sys/devices/.../power/control
> + * interface, or otherwise by calling pm_runtime_allow().
> + *
> + * Calling this function many times in a row has the same effect as calling it
> + * once.
> */
> void pm_runtime_forbid(struct device *dev)
> {
> @@ -1687,7 +1690,13 @@ EXPORT_SYMBOL_GPL(pm_runtime_forbid);
> * pm_runtime_allow - Unblock runtime PM of a device.
> * @dev: Device to handle.
> *
> - * Decrease the device's usage count and set its power.runtime_auto flag.
> + * Unblock runtime suspend of @dev after it has been blocked by
> + * pm_runtime_forbid() (for instance, if it has been blocked via the
> + * /sys/devices/.../power/control interface), check if @dev can be
> + * suspended and suspend it in that case.
> + *
> + * Calling this function many times in a row has the same effect as calling it
> + * once.
> */
> void pm_runtime_allow(struct device *dev)
> {
FWIW,
Reviewed-by: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
(And I didn't check that "many times in a row" claim from the code but I
assume you know things much better than I do. :-))
--
i.
^ permalink raw reply [flat|nested] 5+ messages in thread