linux-kernel - Re: [PATCH v1] PM: runtime: docs: Update pm_runtime

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: <CAJZ5v0jFdUDN_Z5isEpWoisxzMHSgzu460VH2LDCLQTRsUtEDA@mail.gmail.com>
Date: Thu, 23 Oct 2025 12:17:06 +0200
From: "Rafael J. Wysocki" <rafael@...nel.org>
To: Brian Norris <briannorris@...omium.org>
Cc: "Rafael J. Wysocki" <rafael@...nel.org>, Linux PM <linux-pm@...r.kernel.org>, 
	LKML <linux-kernel@...r.kernel.org>, Ulf Hansson <ulf.hansson@...aro.org>, 
	Lukas Wunner <lukas@...ner.de>, Ilpo Järvinen <ilpo.jarvinen@...ux.intel.com>
Subject: Re: [PATCH v1] PM: runtime: docs: Update pm_runtime_allow/forbid() documentation

Hi Brian,

On Wed, Oct 22, 2025 at 10:44 PM Brian Norris <briannorris@...omium.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@...el.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@...el.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@...omium.org>

Thanks!