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.
Find version 1 of this series here:
https://lore.kernel.org/all/20260904212000.4167880-1-briannorris@chromium.org/
The first part of that 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@oss.qualcomm.com/
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 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
Documentation/power/runtime_pm.rst | 568 ++++++++++++++++++++++++++---
drivers/base/power/runtime.c | 8 +-
2 files changed, 525 insertions(+), 51 deletions(-)
--
2.56.0.rc1.310.g51773c2048-goog