Re: [RFC v1 1/8] Documentation: PM: Add documentation for Runtime Standby States

[Rafael J. Wysocki]

On Fri, Dec 26, 2025 at 11:27 AM Antheas Kapenekakis <lkml@xxxxxxxxxxx> wrote:
>
> Introduce the runtime standby state ABI, which allows for firing the
> Modern Standby firmware notifications found in Windows during runtime.
> These notifications allow to make systems that support them look
> suspended.

The "look suspended" thing is misguided IMV.

I'd rather say something like

 This will allow "dark mode" indicating the lack of system activity
related to running user workloads.

> Signed-off-by: Antheas Kapenekakis <lkml@xxxxxxxxxxx>
> ---
>  Documentation/ABI/testing/sysfs-power         |  20 ++++
>  .../admin-guide/pm/standby-states.rst         | 100 ++++++++++++++++++
>  Documentation/admin-guide/pm/system-wide.rst  |   1 +
>  3 files changed, 121 insertions(+)
>  create mode 100644 Documentation/admin-guide/pm/standby-states.rst
>
> diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power
> index d38da077905a..16378be2dc13 100644
> --- a/Documentation/ABI/testing/sysfs-power
> +++ b/Documentation/ABI/testing/sysfs-power
> @@ -39,6 +39,26 @@ Description:
>                 See Documentation/admin-guide/pm/sleep-states.rst for more
>                 information.
>
> +What:          /sys/power/standby

I've already commented on this in my reply to the cover letter.

> +Date:          February 2026
> +Contact:       Antheas Kapenekakis <lkml@xxxxxxxxxxx>
> +Description:
> +               The /sys/power/standby file allows userspace to inform the
> +               kernel of the current runtime standby mode depending on user
> +               activity. The options are "active", "inactive", "sleep",
> +               and "resume". Only the ones supported by the platform will be
> +               available. Depending on the mode, the appearance of the device
> +               will change (e.g., keyboard backlight will turn off as part of
> +               "inactive"), and its thermal envelope might be affected.
> +
> +               Reading from this file returns the available standby modes,
> +               with the current one enclosed in square brackets. Writing one
> +               of the above strings to this file causes the kernel to
> +               transition to it.
> +
> +               See Documentation/admin-guide/pm/standby-states.rst for more
> +               information.
> +
>  What:          /sys/power/disk
>  Date:          September 2006
>  Contact:       Rafael J. Wysocki <rafael@xxxxxxxxxx>
> diff --git a/Documentation/admin-guide/pm/standby-states.rst b/Documentation/admin-guide/pm/standby-states.rst
> new file mode 100644
> index 000000000000..af7f32721d1c
> --- /dev/null
> +++ b/Documentation/admin-guide/pm/standby-states.rst
> @@ -0,0 +1,100 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +.. include:: <isonum.txt>
> +
> +=====================
> +Runtime Standby States
> +=====================
> +
> +:Copyright: |copy| 2026 Antheas Kapenekakis
> +
> +:Author: Antheas Kapenekakis <lkml@xxxxxxxxxxx>
> +
> +This document describes the runtime standby states ABI available in the Linux
> +kernel, which is designed as a generic superset of the s0ix/Modern Standby
> +firmware notifications. Devices with these notifications support hardware states
> +where they look like they are asleep, while still performing basic computation.
> +Specifically, those are "Sleep", "Inactive", and "Active" states, with an
> +additional state "Resume". Transitioning between these states follows the
> +flowchart below.
> +
> +Runtime Standby States
> +==================================
> +The following runtime standby are supported::
> +
> +    <S2idle> ↔ <Sleep> ↔ <Inactive> ↔ <Active>
> +        →       →  <Resume>  ↑
> +
> +.. _s2idle_drips:
> +
> +
> +.. _s2idle_active:
> +
> +Active
> +------
> +
> +The "Active" state is the default state of the system and the one it has when
> +it is turned on. It is the state where the device is on, and the user is
> +interacting with it.
> +
> +.. _s2idle_screen_off:
> +
> +Inactive
> +----------
> +
> +The "Inactive" state is a state in which users have stopped interacting with
> +the device, e.g., 5 seconds after the displays have turned off due to inactivity
> +or due to the user pressing the power button. It is the responsibility of
> +userspace to keep track of user interaction so it can inform the kernel to
> +transition to this state. The response to this state for devices that support
> +is to turn off their keyboard backlight, and some might pulse their power light.
> +
> +.. _s2idle_sleep:
> +
> +Sleep

The term "sleep" has already been allocated (sorry about that) and it
means any non-working states of the system, that may include ACPI S3,
ACPI S4 (hibernation), suspend-to-idle etc.

Some other name needs to be used here to avoid confusion with the
existing terminology.

> +-----
> +
> +In the sleep state, certain devices will limit their thermal envelope so it is
> +safe for them to be put into a bag and still perform basic computation such as
> +fetching email. Then, some devices will pulse their power light. Userspace can
> +use this state to perform basic tasks such as wake-up checks while maintaining
> +the appearance the device is asleep.
> +
> +.. _s2idle_resume:
> +
> +Resume
> +------
> +
> +The resume state is a transient state that may only be entered from the sleep
> +state. It can be used to notify hardware that the device should boost its
> +thermal envelope as preparation for the user interacting with it. As in, it
> +undoes the thermal envelope effects of the "sleep" state while keeping its
> +appearance.
> +
> +S2idle
> +-----
> +
> +The "S2idle" state in the diagram corresponds to suspending normally by writing
> +``mem`` to ``/sys/power/state``. Userspace is fully frozen, and the kernel parks
> +the CPUs and turns off most devices. It is shown in the graph as a reference.
> +If the runtime standby state is not "sleep" when entering s2idle, the kernel
> +will first transition to "sleep" before entering s2idle.

Overall, I personally don't like the terminology used above too much.

You seem to be talking about a state machine, but there really isn't
one.  The state of the system after evaluating PNP0D80 _DSM function 3
(screen off) need not be different from its preceding state, and even
so the difference may be relatively small.

I would rather describe all of this in terms of indicating certain
conditions to the user.  For instance, "inactive" is written to
/sysfs/attribute/to/be/determined to indicate to the user that there's
no activity in the system related to running user workloads.

It's almost like selecting "work profiles" for the platform.

> +
> +Basic ``sysfs`` Interface for runtime standby transitions
> +=============================================================
> +
> +The file :file:`/sys/power/standby` can be used to transition the system between
> +the different standby states.

I'm not sure if the effects of using this interface (or its future
replacement) can be referred to as "transitions".  Some devices will
be affected, but the general state of the system will not be changed
as a result of using them.

> The file accepts the following values: ``active``,
> +``inactive``, ``sleep``, and ``resume``. File writes will block until the
> +transition completes. The system will cross all states shown in the flowchart
> +above to reach the desired state. It will return ``-EINVAL`` when asking for an
> +unsupported state or, e.g., requesting ``resume`` when not in the ``sleep``
> +state. If there is an error during the transition, the transition will pause on
> +the last error-free state and return an error.
> +
> +The file can be read to retrieve the current state (and potential ones) with the
> +following format: ``[active] inactive sleep resume``. Only supported states
> +will be shown.
> +
> +Userspace may transition between all supported states including s2idle
> +arbitrarily, except for the ``resume`` state which may only be requested from
> +the ``sleep`` state.
> \ No newline at end of file
> diff --git a/Documentation/admin-guide/pm/system-wide.rst b/Documentation/admin-guide/pm/system-wide.rst
> index 1a1924d71006..411775fae4ac 100644
> --- a/Documentation/admin-guide/pm/system-wide.rst
> +++ b/Documentation/admin-guide/pm/system-wide.rst
> @@ -8,4 +8,5 @@ System-Wide Power Management
>     :maxdepth: 2
>
>     sleep-states
> +   standby-states
>     suspend-flows
> --