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

[Antheas Kapenekakis]

On Fri, 13 Mar 2026 at 21:08, Rafael J. Wysocki <rafael@xxxxxxxxxx> wrote:
>
> 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.

The current code implementation is as a state machine. Of course, this
is an implementation detail and need not be exposed to docs.

I will try to reword.

> > +
> > +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.

As said above, the implementation uses transition logic. This is not
needed to be reflected in the documentation.

> > 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
> > --
>