Re: [PATCH v2 1/2] PM: docs: Describe high-level PM strategies and sleep states

[Rafael J. Wysocki]

On Monday, August 21, 2017 3:14:56 PM CEST Rafael J. Wysocki wrote:
> From: Rafael J. Wysocki 
> 
> Reorganize the power management part of admin-guide by adding a
> description of major power management strategies supported by the
> kernel (system-wide and working-state power management) to it and
> dividing the rest of the material into the system-wide PM and
> working-state PM chapters.
> 
> On top of that, add a description of system sleep states to the
> system-wide PM chapter.
> 
> Signed-off-by: Rafael J. Wysocki 
> Reviewed-by: Lukas Wunner 
> ---
> 
> -> v2:
>  - Changed the wording in the strategies.rst document slightly
>to address Lukas' comments.
>  - Changed refs in the sleep-states.rst document to address
>Markus' comments.
>  - Followed Markus' suggestion to drop C 'only' blocks in a few
>places.
>  - Added Reviewed-by from Lukas as the changes to the content are
>very small.
> 

I haven't seen any more comments on this which I'm taking as the lack of
objections, so I'm going to queue it up for 4.14.

Thanks,
Rafael

Re: [PATCH v2 1/2] PM: docs: Describe high-level PM strategies and sleep states

[Rafael J. Wysocki]

On Monday, August 21, 2017 3:14:56 PM CEST Rafael J. Wysocki wrote:
> From: Rafael J. Wysocki 
> 
> Reorganize the power management part of admin-guide by adding a
> description of major power management strategies supported by the
> kernel (system-wide and working-state power management) to it and
> dividing the rest of the material into the system-wide PM and
> working-state PM chapters.
> 
> On top of that, add a description of system sleep states to the
> system-wide PM chapter.
> 
> Signed-off-by: Rafael J. Wysocki 
> Reviewed-by: Lukas Wunner 
> ---
> 
> -> v2:
>  - Changed the wording in the strategies.rst document slightly
>to address Lukas' comments.
>  - Changed refs in the sleep-states.rst document to address
>Markus' comments.
>  - Followed Markus' suggestion to drop C 'only' blocks in a few
>places.
>  - Added Reviewed-by from Lukas as the changes to the content are
>very small.
> 

I haven't seen any more comments on this which I'm taking as the lack of
objections, so I'm going to queue it up for 4.14.

Thanks,
Rafael

[PATCH v2 1/2] PM: docs: Describe high-level PM strategies and sleep states

[Rafael J. Wysocki]

From: Rafael J. Wysocki 

Reorganize the power management part of admin-guide by adding a
description of major power management strategies supported by the
kernel (system-wide and working-state power management) to it and
dividing the rest of the material into the system-wide PM and
working-state PM chapters.

On top of that, add a description of system sleep states to the
system-wide PM chapter.

Signed-off-by: Rafael J. Wysocki 
Reviewed-by: Lukas Wunner 
---

-> v2:
 - Changed the wording in the strategies.rst document slightly
   to address Lukas' comments.
 - Changed refs in the sleep-states.rst document to address
   Markus' comments.
 - Followed Markus' suggestion to drop C 'only' blocks in a few
   places.
 - Added Reviewed-by from Lukas as the changes to the content are
   very small.

---
 Documentation/admin-guide/pm/index.rst |   12 -
 Documentation/admin-guide/pm/sleep-states.rst  |  245 +
 Documentation/admin-guide/pm/strategies.rst|   52 +
 Documentation/admin-guide/pm/system-wide.rst   |8 
 Documentation/admin-guide/pm/working-state.rst |9 
 5 files changed, 317 insertions(+), 9 deletions(-)

Index: linux-pm/Documentation/admin-guide/pm/index.rst
===
--- linux-pm.orig/Documentation/admin-guide/pm/index.rst
+++ linux-pm/Documentation/admin-guide/pm/index.rst
@@ -5,12 +5,6 @@ Power Management
 .. toctree::
:maxdepth: 2
 
-   cpufreq
-   intel_pstate
-
-.. only::  subproject and html
-
-   Indices
-   ===
-
-   * :ref:`genindex`
+   strategies
+   system-wide
+   working-state
Index: linux-pm/Documentation/admin-guide/pm/sleep-states.rst
===
--- /dev/null
+++ linux-pm/Documentation/admin-guide/pm/sleep-states.rst
@@ -0,0 +1,245 @@
+===
+System Sleep States
+===
+
+::
+
+ Copyright (c) 2017 Intel Corp., Rafael J. Wysocki 
+
+Sleep states are global low-power states of the entire system in which user
+space code cannot be executed and the overall system activity is significantly
+reduced.
+
+
+Sleep States That Can Be Supported
+==
+
+Depending on its configuration and the capabilities of the platform it runs on,
+the Linux kernel can support up to four system sleep states, includig
+hibernation and up to three variants of system suspend.  The sleep states that
+can be supported by the kernel are listed below.
+
+.. _s2idle:
+
+Suspend-to-Idle
+---
+
+This is a generic, pure software, light-weight variant of system suspend (also
+referred to as S2I or S2Idle).  It allows more energy to be saved relative to
+runtime idle by freezing user space, suspending the timekeeping and putting all
+I/O devices into low-power states (possibly lower-power than available in the
+working state), such that the processors can spend time in their deepest idle
+states while the system is suspended.
+
+The system is woken up from this state by in-band interrupts, so theoretically
+any devices that can cause interrupts to be generated in the working state can
+also be set up as wakeup devices for S2Idle.
+
+This state can be used on platforms without support for :ref:`standby 
`
+or :ref:`suspend-to-RAM `, or it can be used in addition to any of the
+deeper system suspend variants to provide reduced resume latency.  It is always
+supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set.
+
+.. _standby:
+
+Standby
+---
+
+This state, if supported, offers moderate, but real, energy savings, while
+providing a relatively straightforward transition back to the working state.  
No
+operating state is lost (the system core logic retains power), so the system 
can
+go back to where it left off easily enough.
+
+In addition to freezing user space, suspending the timekeeping and putting all
+I/O devices into low-power states, which is done for :ref:`suspend-to-idle
+` too, nonboot CPUs are taken offline and all low-level system 
functions
+are suspended during transitions into this state.  For this reason, it should
+allow more energy to be saved relative to :ref:`suspend-to-idle `, but
+the resume latency will generally be greater than for that state.
+
+The set of devices that can wake up the system from this state usually is
+reduced relative to :ref:`suspend-to-idle ` and it may be necessary to
+rely on the platform for setting up the wakeup functionality as appropriate.
+
+This state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration
+option is set and the support for it is registered by the platform with the
+core system suspend subsystem.  On ACPI-based systems this state is mapped to
+the S1 system state defined by ACPI.
+
+.. _s2ram:
+
+Suspend-to-RAM
+--
+
+This state (also referred to as STR or S2RAM), if 

[PATCH v2 1/2] PM: docs: Describe high-level PM strategies and sleep states

[Rafael J. Wysocki]

From: Rafael J. Wysocki 

Reorganize the power management part of admin-guide by adding a
description of major power management strategies supported by the
kernel (system-wide and working-state power management) to it and
dividing the rest of the material into the system-wide PM and
working-state PM chapters.

On top of that, add a description of system sleep states to the
system-wide PM chapter.

Signed-off-by: Rafael J. Wysocki 
Reviewed-by: Lukas Wunner 
---

-> v2:
 - Changed the wording in the strategies.rst document slightly
   to address Lukas' comments.
 - Changed refs in the sleep-states.rst document to address
   Markus' comments.
 - Followed Markus' suggestion to drop C 'only' blocks in a few
   places.
 - Added Reviewed-by from Lukas as the changes to the content are
   very small.

---
 Documentation/admin-guide/pm/index.rst |   12 -
 Documentation/admin-guide/pm/sleep-states.rst  |  245 +
 Documentation/admin-guide/pm/strategies.rst|   52 +
 Documentation/admin-guide/pm/system-wide.rst   |8 
 Documentation/admin-guide/pm/working-state.rst |9 
 5 files changed, 317 insertions(+), 9 deletions(-)

Index: linux-pm/Documentation/admin-guide/pm/index.rst
===
--- linux-pm.orig/Documentation/admin-guide/pm/index.rst
+++ linux-pm/Documentation/admin-guide/pm/index.rst
@@ -5,12 +5,6 @@ Power Management
 .. toctree::
:maxdepth: 2
 
-   cpufreq
-   intel_pstate
-
-.. only::  subproject and html
-
-   Indices
-   ===
-
-   * :ref:`genindex`
+   strategies
+   system-wide
+   working-state
Index: linux-pm/Documentation/admin-guide/pm/sleep-states.rst
===
--- /dev/null
+++ linux-pm/Documentation/admin-guide/pm/sleep-states.rst
@@ -0,0 +1,245 @@
+===
+System Sleep States
+===
+
+::
+
+ Copyright (c) 2017 Intel Corp., Rafael J. Wysocki 
+
+Sleep states are global low-power states of the entire system in which user
+space code cannot be executed and the overall system activity is significantly
+reduced.
+
+
+Sleep States That Can Be Supported
+==
+
+Depending on its configuration and the capabilities of the platform it runs on,
+the Linux kernel can support up to four system sleep states, includig
+hibernation and up to three variants of system suspend.  The sleep states that
+can be supported by the kernel are listed below.
+
+.. _s2idle:
+
+Suspend-to-Idle
+---
+
+This is a generic, pure software, light-weight variant of system suspend (also
+referred to as S2I or S2Idle).  It allows more energy to be saved relative to
+runtime idle by freezing user space, suspending the timekeeping and putting all
+I/O devices into low-power states (possibly lower-power than available in the
+working state), such that the processors can spend time in their deepest idle
+states while the system is suspended.
+
+The system is woken up from this state by in-band interrupts, so theoretically
+any devices that can cause interrupts to be generated in the working state can
+also be set up as wakeup devices for S2Idle.
+
+This state can be used on platforms without support for :ref:`standby 
`
+or :ref:`suspend-to-RAM `, or it can be used in addition to any of the
+deeper system suspend variants to provide reduced resume latency.  It is always
+supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set.
+
+.. _standby:
+
+Standby
+---
+
+This state, if supported, offers moderate, but real, energy savings, while
+providing a relatively straightforward transition back to the working state.  
No
+operating state is lost (the system core logic retains power), so the system 
can
+go back to where it left off easily enough.
+
+In addition to freezing user space, suspending the timekeeping and putting all
+I/O devices into low-power states, which is done for :ref:`suspend-to-idle
+` too, nonboot CPUs are taken offline and all low-level system 
functions
+are suspended during transitions into this state.  For this reason, it should
+allow more energy to be saved relative to :ref:`suspend-to-idle `, but
+the resume latency will generally be greater than for that state.
+
+The set of devices that can wake up the system from this state usually is
+reduced relative to :ref:`suspend-to-idle ` and it may be necessary to
+rely on the platform for setting up the wakeup functionality as appropriate.
+
+This state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration
+option is set and the support for it is registered by the platform with the
+core system suspend subsystem.  On ACPI-based systems this state is mapped to
+the S1 system state defined by ACPI.
+
+.. _s2ram:
+
+Suspend-to-RAM
+--
+
+This state (also referred to as STR or S2RAM), if supported, offers significant
+energy savings as everything in the system is put into a low-power