Re: [PATCH v3 7/8] PM: runtime: Expand introduction with core concepts and structure

[Ulf Hansson]

On Wed, Sep 30, 2026 at 4:51 AM Brian Norris <briannorris@xxxxxxxxxxxx> wrote:
>
> I commonly see people have difficulty learning how runtime PM works
> because of the following key points [*]:
>
>  1) there are several boolean concepts in runtime PM, with somewhat
>     similar meanings:
>
>      enabled / disabled
>      active / suspended
>      allowed / forbidden
>
>  2) if these concepts are documented at all, they're scattered across
>     the kerneldoc or Documentation/
>
>  3) the runtime_pm.rst docs don't make any attempt to ease a reader into
>     understanding the concepts, and instead jump straight into how it's
>     implemented (queues, 'struct device' fields, helpers).
>
> Let's try to remedy this a bit by discussing the core concepts and
> highlights at the top of the introduction, and introduce a few
> sub-headings, so it's easier to navigate different aspects of the
> introduction.
>
> While shuffling the intro around, I also see that the existing text
> largely mirrors the layout of the following sections (2, 3, and 4), but
> does so out of order. Reorder those, and point to section numbers.
>
> [*] In addition to API complexity. I count 61 pm_*() helpers, 7 of which
>     are variations of put() and 8 of which are variations of get().
>
> Signed-off-by: Brian Norris <briannorris@xxxxxxxxxxxx>

I guess Rafael may have some further comment on this one, but from my
point of view this looks fine. Please add:

Reviewed-by: Ulf Hansson <ulfh@xxxxxxxxxx>

Kind regards
Uffe

> ---
>
> (no changes since v2)
>
> Changes in v2:
> Address review feedback around descriptions of "enabled" and "active". I
> know not every point of discussion was settled, but I hope this updated
> version resolves many of them and provides a better basis for further
> improvement.
>  * Avoid calling enabled and active "orthogonal"
>  * Describe more of their inter-relationship
>  * Prioritize talking about "enabled" first, since that's the first
>    concept a reader should know about
>  * Brief mentions of parent/child and supplier/consumer, and dependency
>    handling
>  * Other tweaks
>
>  Documentation/power/runtime_pm.rst | 103 +++++++++++++++++++++++------
>  1 file changed, 84 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/power/runtime_pm.rst b/Documentation/power/runtime_pm.rst
> index 68903d93a3e7..c63fbf0ff862 100644
> --- a/Documentation/power/runtime_pm.rst
> +++ b/Documentation/power/runtime_pm.rst
> @@ -13,31 +13,96 @@ Runtime Power Management Framework for I/O Devices
>  1. Introduction
>  ===============
>
> -Support for runtime power management (runtime PM) of I/O devices is provided
> -at the power management core (PM core) level by means of:
> -
> -* The power management workqueue pm_wq in which bus types and device drivers can
> -  put their PM-related work items.  It is strongly recommended that pm_wq be
> -  used for queuing all work items related to runtime PM, because this allows
> -  them to be synchronized with system-wide power transitions (suspend to RAM,
> -  hibernation and resume from system sleep states).  pm_wq is declared in
> -  include/linux/pm_runtime.h and defined in kernel/power/main.c.
> -
> -* A number of runtime PM fields in the 'power' member of 'struct device' (which
> -  is of the type 'struct dev_pm_info', defined in include/linux/pm.h) that can
> -  be used for synchronizing runtime PM operations with one another.
> +Runtime power management (or runtime PM, sometimes shortened to RPM) allows
> +individual I/O devices to transition between high and low-power states
> +dynamically while the system is running, conserving power without waiting for a
> +system-wide sleep state.
> +
> +Core Concepts
> +-------------
> +
> +Understanding runtime PM requires distinguishing between several pairs of
> +related but distinct concepts that apply to each device: **enabled** /
> +**disabled**, **active** / **suspended**, and **allowed** / **forbidden**.
> +
> +* **Enabled**: To use runtime PM to manage a device's power states, it must
> +  first be **enabled**. If RPM is never enabled for a device, it generally
> +  stays inactive from an RPM perspective, and the PM core will ignore it.
> +  If it is enabled, the PM core can manage the device status (see **Active**
> +  below) according to its understanding of whether the device is in use, and
> +  perform state transitions via the appropriate PM callbacks
> +  (->runtime_suspend(), ->runtime_resume()).
> +
> +  Each device has an internal disable counter (``disable_depth``) which
> +  determines whether runtime PM is currently enabled. Devices are initially
> +  registered with runtime PM disabled (``disable_depth == 1``), though some bus
> +  types (such as PCI) may enable it before driver probe.
> +
> +  To opt into runtime PM, a driver first ensures that the device's recorded
> +  status matches its actual physical state (for example, by calling
> +  pm_runtime_set_active() if the device was powered on at probe) and then calls
> +  pm_runtime_enable(), decrementing ``disable_depth`` to zero (i.e.,
> +  **enabled**). Runtime PM may be disabled again explicitly via
> +  pm_runtime_disable() or temporarily during system sleep transitions.
> +
> +* **Active**: The PM core tracks a device's runtime status as either **active**
> +  (the device is operational, having completed its resume callback or otherwise
> +  marked active) or **suspended** (the device is idle or in a low-power state,
> +  having completed its suspend callback or otherwise marked suspended), along
> +  with transitional **suspending** and **resuming** phases. When runtime PM is
> +  **enabled**, state transitions are primarily driven by reference counting:
> +  drivers call pm_runtime_resume_and_get() (or related variants) before using
> +  the hardware, to ensure the device is active; and pm_runtime_put() (or
> +  related variants) once work completes. When a device's usage counter drops to
> +  zero and its dependencies (children or consumers) are suspended, the PM core
> +  can suspend the device immediately or after an autosuspend delay.
> +
> +  Besides driving the state of the device in question, a device's runtime
> +  status also affects those of its dependencies — its parent (if the parent's
> +  ``power.ignore_children`` is false) and its linked supplier device(s) (for
> +  links with the ``DL_FLAG_PM_RUNTIME`` flag). An **active** device holds
> +  reference counts on its dependencies, preventing them from suspending.
> +
> +* **Allowed**: System policy and user space govern whether dynamic suspension
> +  is permitted through the concepts of **allowed** and **forbidden**,
> +  manipulated in-kernel via pm_runtime_allow() and pm_runtime_forbid() and
> +  exposed to user space through the ``/sys/devices/.../power/control``
> +  attribute. When runtime PM is forbidden (``control`` set to ``on``), the PM
> +  core increments the device's usage counter, forcing the device to remain
> +  active regardless of whether the driver is idle. When runtime PM is allowed
> +  (``control`` set to ``auto``), this reference is dropped, permitting the PM
> +  core to automatically suspend the device whenever its driver and child
> +  devices are no longer using it.
> +
> +Notably, runtime PM also has a feature called "autosuspend." This is different
> +than the ``control`` notion of "auto" (i.e., "allowed"). Autosuspend is
> +described in more detail in `Section 9`_.
> +
> +Implementation Structure
> +------------------------
> +
> +Support for runtime power management is provided at the power management core
> +(PM core) level by means of:
>
>  * Three device runtime PM callbacks in 'struct dev_pm_ops' (defined in
> -  include/linux/pm.h).
> +  include/linux/pm.h). See `Section 2`_.
> +
> +* A number of runtime PM fields in the 'power' member of 'struct device' that
> +  can be used for synchronizing runtime PM operations with one another. These
> +  are covered in `Section 3`_.
>
>  * A set of helper functions defined in drivers/base/power/runtime.c that can be
>    used for carrying out runtime PM operations in such a way that the
> -  synchronization between them is taken care of by the PM core.  Bus types and
> -  device drivers are encouraged to use these functions.
> +  synchronization between them is taken care of by the PM core. Bus types and
> +  device drivers are encouraged to use these functions. They are covered in
> +  `Section 4`_.
>
> -The runtime PM callbacks present in 'struct dev_pm_ops', the device runtime PM
> -fields of 'struct dev_pm_info' and the core helper functions provided for
> -runtime PM are described below.
> +* The power management workqueue pm_wq in which bus types and device drivers can
> +  put their PM-related work items. It is strongly recommended that pm_wq be
> +  used for queuing all work items related to runtime PM, because this allows
> +  them to be synchronized with system-wide power transitions (suspend to RAM,
> +  hibernation and resume from system sleep states). pm_wq is declared in
> +  include/linux/pm_runtime.h and defined in kernel/power/main.c.
>
>  .. _Section 2:
>
> --
> 2.56.0.rc1.315.gc6ed9934b7-goog
>