linux-kernel - Re: [PATCH 3/3] PM: runtime: Update kerneldoc return codes

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: <CAJZ5v0iJaXog5uWfaL1qf97ts_i42PbjK4F28M+UvDBO97wX0w@mail.gmail.com>
Date: Fri, 5 Sep 2025 19:54:21 +0200
From: "Rafael J. Wysocki" <rafael@...nel.org>
To: Sakari Ailus <sakari.ailus@...ux.intel.com>
Cc: Brian Norris <briannorris@...omium.org>, "Rafael J. Wysocki" <rafael@...nel.org>, 
	Pavel Machek <pavel@...nel.org>, "Rafael J . Wysocki" <rafael.j.wysocki@...el.com>, 
	kunit-dev@...glegroups.com, Len Brown <lenb@...nel.org>, linux-pm@...r.kernel.org, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH 3/3] PM: runtime: Update kerneldoc return codes

On Tue, Sep 2, 2025 at 9:18 AM Sakari Ailus
<sakari.ailus@...ux.intel.com> wrote:
>
> Hi Brian,
>
> Thanks for posting this. A few comments below.
>
> On Thu, Aug 28, 2025 at 05:28:28PM -0700, Brian Norris wrote:
> > APIs based on __pm_runtime_idle() (pm_runtime_idle(), pm_request_idle())
> > do not return 1 when already suspended. They return -EAGAIN. This is
> > already covered in the docs, so the entry for "1" is redundant and
> > conflicting.
> >
> > (pm_runtime_put() and pm_runtime_put_sync() were previously incorrect,
> > but that's fixed in "PM: runtime: pm_runtime_put{,_sync}() returns 1
> > when already suspended", to ensure consistency with APIs like
> > pm_runtime_put_autosuspend().)
> >
> > RPM_GET_PUT APIs based on __pm_runtime_suspend() do return 1 when
> > already suspended, but the language is a little unclear -- it's not
> > really an "error", so it seems better to list as a clarification before
> > the 0/success case. Additionally, they only actually return 1 when the
> > refcount makes it to 0; if the usage_count is still non-zero, we return
> > 0.
> >
> > pm_runtime_put(), etc., also don't appear at first like they can ever
> > see "-EAGAIN: Runtime PM usage_count non-zero", because in non-racy
> > conditions, pm_runtime_put() would drop its reference count, see it's
> > non-zero, and return early (in __pm_runtime_idle()). However, it's
> > possible to race with another actor that increments the usage_count
> > afterward, since rpm_idle() is protected by a separate lock; in such a
> > case, we may see -EAGAIN.
> >
> > Because this case is only seen in the presence of concurrent actors, it
> > makes sense to clarify that this is when "usage_count **became**
> > non-zero", by way of some racing actor.
> >
> > Lastly, pm_runtime_put_sync_suspend() duplicated some -EAGAIN language.
> > Fix that.
> >
> > Fixes: 271ff96d6066 ("PM: runtime: Document return values of suspend-related API functions")
> > Link: https://lore.kernel.org/linux-pm/aJ5pkEJuixTaybV4@google.com/
> > Signed-off-by: Brian Norris <briannorris@...omium.org>
> > ---
> >
> >  include/linux/pm_runtime.h | 33 ++++++++++++++++++---------------
> >  1 file changed, 18 insertions(+), 15 deletions(-)
> >
> > diff --git a/include/linux/pm_runtime.h b/include/linux/pm_runtime.h
> > index d88d6b6ccf5b..fd17ffe1bc79 100644
> > --- a/include/linux/pm_runtime.h
> > +++ b/include/linux/pm_runtime.h
> > @@ -356,7 +356,6 @@ static inline int pm_runtime_force_resume(struct device *dev) { return -ENXIO; }
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -EINPROGRESS: Suspend already in progress.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   * Other values and conditions for the above values are possible as returned by
> >   * Runtime PM idle and suspend callbacks.
> >   */
> > @@ -439,7 +438,6 @@ static inline int pm_runtime_resume(struct device *dev)
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -EINPROGRESS: Suspend already in progress.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   */
> >  static inline int pm_request_idle(struct device *dev)
> >  {
> > @@ -540,15 +538,16 @@ static inline int pm_runtime_resume_and_get(struct device *dev)
> >   * equal to 0, queue up a work item for @dev like in pm_request_idle().
> >   *
> >   * Return:
> > + * * 1: Usage counts dropped to zero, but device was already suspended.
>
> Does this actually happen? pm_runtime_put() calls __pm_runtime_idle() that
> doesn't appear to return 1 in any case.

Except when it calls rpm_suspend() that may return 1.

> >   * * 0: Success.
> >   * * -EINVAL: Runtime PM error.
> >   * * -EACCES: Runtime PM disabled.
> > - * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
> > + * * -EAGAIN: Runtime PM usage_count became non-zero or Runtime PM status
> > + *            change ongoing.
> >   * * -EBUSY: Runtime PM child_count non-zero.
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -EINPROGRESS: Suspend already in progress.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   */
> >  static inline int pm_runtime_put(struct device *dev)
> >  {
> > @@ -565,15 +564,16 @@ DEFINE_FREE(pm_runtime_put, struct device *, if (_T) pm_runtime_put(_T))
> >   * equal to 0, queue up a work item for @dev like in pm_request_autosuspend().
> >   *
> >   * Return:
> > + * * 1: Usage counts dropped to zero, but device was already suspended.
> >   * * 0: Success.
>
> "usage_count" and "usage counter" is being used in kernel-doc already, I'd
> use either of the two. "usage_count" refers directly to the field in struct
> dev_pm_info (and is used a few lines below). Same elsewhere.

"Usage counter", please!

> >   * * -EINVAL: Runtime PM error.
> >   * * -EACCES: Runtime PM disabled.
> > - * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
> > + * * -EAGAIN: Runtime PM usage_count became non-zero or Runtime PM status
> > + *            change ongoing.
> >   * * -EBUSY: Runtime PM child_count non-zero.
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -EINPROGRESS: Suspend already in progress.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   */
> >  static inline int __pm_runtime_put_autosuspend(struct device *dev)
> >  {
> > @@ -590,15 +590,16 @@ static inline int __pm_runtime_put_autosuspend(struct device *dev)
> >   * in pm_request_autosuspend().
> >   *
> >   * Return:
> > + * * 1: Usage counts dropped to zero, but device was already suspended.
> >   * * 0: Success.
> >   * * -EINVAL: Runtime PM error.
> >   * * -EACCES: Runtime PM disabled.
> > - * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
> > + * * -EAGAIN: Runtime PM usage_count became non-zero or Runtime PM status
> > + *            change ongoing.
> >   * * -EBUSY: Runtime PM child_count non-zero.
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -EINPROGRESS: Suspend already in progress.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   */
> >  static inline int pm_runtime_put_autosuspend(struct device *dev)
> >  {
> > @@ -619,14 +620,15 @@ static inline int pm_runtime_put_autosuspend(struct device *dev)
> >   * if it returns an error code.
> >   *
> >   * Return:
> > + * * 1: Usage counts dropped to zero, but device was already suspended.
> >   * * 0: Success.
>
> Does this happen (pm_runtime_put_sync() calls __pm_runtime_idle())?

It does (see above).

> >   * * -EINVAL: Runtime PM error.
> >   * * -EACCES: Runtime PM disabled.
> > - * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
> > + * * -EAGAIN: Runtime PM usage_count became non-zero or Runtime PM status
> > + *            change ongoing.
> >   * * -EBUSY: Runtime PM child_count non-zero.
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   * Other values and conditions for the above values are possible as returned by
> >   * Runtime PM suspend callbacks.
> >   */
> > @@ -646,15 +648,15 @@ static inline int pm_runtime_put_sync(struct device *dev)
> >   * if it returns an error code.
> >   *
> >   * Return:
> > + * * 1: Usage counts dropped to zero, but device was already suspended.
> >   * * 0: Success.
> >   * * -EINVAL: Runtime PM error.
> >   * * -EACCES: Runtime PM disabled.
> > - * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
> > - * * -EAGAIN: usage_count non-zero or Runtime PM status change ongoing.
> > + * * -EAGAIN: Runtime PM usage_count became non-zero or Runtime PM status
> > + *            change ongoing.
> >   * * -EBUSY: Runtime PM child_count non-zero.
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   * Other values and conditions for the above values are possible as returned by
> >   * Runtime PM suspend callbacks.
> >   */
> > @@ -677,15 +679,16 @@ static inline int pm_runtime_put_sync_suspend(struct device *dev)
> >   * if it returns an error code.
> >   *
> >   * Return:
> > + * * 1: Usage counts dropped to zero, but device was already suspended.
> >   * * 0: Success.
> >   * * -EINVAL: Runtime PM error.
> >   * * -EACCES: Runtime PM disabled.
> > - * * -EAGAIN: Runtime PM usage_count non-zero or Runtime PM status change ongoing.
> > + * * -EAGAIN: Runtime PM usage_count became non-zero or Runtime PM status
> > + *            change ongoing.
> >   * * -EBUSY: Runtime PM child_count non-zero.
> >   * * -EPERM: Device PM QoS resume latency 0.
> >   * * -EINPROGRESS: Suspend already in progress.
> >   * * -ENOSYS: CONFIG_PM not enabled.
> > - * * 1: Device already suspended.
> >   * Other values and conditions for the above values are possible as returned by
> >   * Runtime PM suspend callbacks.
> >   */
>
> --