Re: [PATCH v3 0/8] PM: runtime: Overhaul kerneldoc, runtime_pm.rst docs

[Rafael J. Wysocki (Intel)]

On Wed, Sep 30, 2026 at 4:51 AM Brian Norris <briannorris@xxxxxxxxxxxx> wrote:
>
> The runtime PM documentation could use some improvements and additions,
> to help guide people less familiar with the main runtime PM concepts and
> its internal implementation details.
>
> v1 is here:
> https://lore.kernel.org/all/20260904212000.4167880-1-briannorris@xxxxxxxxxxxx/
>
> v2 is here:
> https://lore.kernel.org/all/20260923174711.1283986-1-briannorris@xxxxxxxxxxxx/
>
> The first part of the v1 series has already been applied. For the
> remaining work:
>
>  - Formatting and clarity improvements.
>
>  - Clarifying core concepts in the Introduction. (Pretty much all new
>    readers I encounter have a hard time with the difference between
>    "enabled", "allowed", and "active".)
>
>  - Adding Example driver patterns -- because the API is so large and
>    complicated, it can help to try to walk people through standard
>    practices, and what everything means in context.
>
> I tried to keep some of the larger changes toward the end, to hopefully
> make it easier to rework or reject them while cherry-picking some of the
> easier stuff from the first part of the series.
>
> Feel free to add suggestions! Within reason, I'm open to tackling more
> here, as I think many people have many valid perspectives on exactly why
> and how the docs do or don't serve people well today. Or I can tackle
> less, if you think some of my choices are not improvements.
>
> Some possible follow-ups I'm toying with:
>
>  * Slimming down the API might be better than heavily documenting it. A
>    smaller API is a more digestible API.
>
>    My only concrete next step: drop __pm_runtime_put_autosuspend(). Its
>    last user is nearly gone:
>    https://lore.kernel.org/all/20260806-smmu-rpm-v4-1-8183d007331c@xxxxxxxxxxxxxxxx/
>
>    I could also see deprecating one of
>    pm_runtime_put_sync{,_suspend,_autosuspend}(). They all do slightly
>    different things, but I'm not sure every difference is actually fully
>    intentional (or at least, not necessary).
>
>  * Tweaking some of the behavior on pm_runtime_barrier(). Today, it's
>    very asymmetric, as it prefers resume. But I believe there may be
>    value in making it flush (not just cancel) pending suspend too. That
>    may be in a future proposal; for now, I just try to make its
>    asymmetry more clear in the docs.
>
>  * Sand down some more rough edges on return codes. For example, it's
>    very difficult to get any useful meaning out of pm_runtime_put_sync()
>    return codes. There's a high chance that anyone trying to treat
>    return codes as errors is inviting bugs. (Is -EAGAIN a failure?)
>
>    Of course, the answer there is not "document it better" -- we can
>    make it easier to use.
>
>  * Adjust the way devm_pm_runtime_enable() works, specifically for
>    remove()/teardown. Currently, this is very hard to use correctly --
>    some common driver patterns may assume that a device will tear down
>    while RPM_SUSPENDED; but that's not actually guaranteed. Notably,
>    this makes some of the "Examples" section fairly tricky/subtle.
>
> Regards,
> Brian
>
> Changes in v3:
>  * Misc formatting improvements
>  * Rewrite Examples to avoid devm_* at first, to highlight correct
>    approaches
>  * Include error-handling and remove() in any probe() Examples
>  * Advise more caution when using devm_*, as ordering issues are subtle
>
> Changes in v2:
>  * Major rework on Introduction section, especially regarding "enabled"
>    and "active"
>  * Add appropriate teardown to "Probe with Hardware Powered Off"
>    Example, as the remove() + power-off behavior is subtle here, and
>    easy to get wrong
>  * Drop changes that are already applied
>  * Add a few new fix patches, noticed while reviewing the rest
>  * Move Introduction patch near the end of the series, as it is a likely
>    target for further discussion and modification.
>  * Correct Ulf's email address
>  * CC linux-doc
>
> Brian Norris (8):
>   PM: runtime: Correct pm_runtime_autosuspend_expiration() doc
>   PM: runtime: More kerneldoc formatting
>   PM: runtime: Misc improvements to runtime_pm.rst
>   PM: runtime: Add "Section" hyperlinks
>   PM: runtime: Clarify ->runtime_idle() callback return value handling
>   PM: runtime: Clarify driver callback expectations and structure
>     Section 2
>   PM: runtime: Expand introduction with core concepts and structure
>   PM: runtime: Add Example Driver Patterns section

Patches [1-6/8] are fine with me now, so applied (as 7.4 material).

I will send comments on patch [7/8] separately and the last one is
still under review.

Thanks!