Skip to content

Commit 4afbce7

Browse files
rafaeljwrafaeljw
committed
Merge branch 'pm-docs'
* pm-docs: PM: docs: Delete the obsolete states.txt document PM: docs: Describe high-level PM strategies and sleep states
2 parents 835f128 + 7aa7a03 commit 4afbce7

File tree

6 files changed

+317
-136
lines changed

6 files changed

+317
-136
lines changed

‎Documentation/admin-guide/pm/index.rst

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,6 @@ Power Management
55
.. toctree::
66
:maxdepth: 2
77

8-
cpufreq
9-
intel_pstate
10-
11-
.. only:: subproject and html
12-
13-
Indices
14-
=======
15-
16-
* :ref:`genindex`
8+
strategies
9+
system-wide
10+
working-state

‎Documentation/admin-guide/pm/sleep-states.rst

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
===================
2+
System Sleep States
3+
===================
4+
5+
::
6+
7+
Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <[email protected]>
8+
9+
Sleep states are global low-power states of the entire system in which user
10+
space code cannot be executed and the overall system activity is significantly
11+
reduced.
12+
13+
14+
Sleep States That Can Be Supported
15+
==================================
16+
17+
Depending on its configuration and the capabilities of the platform it runs on,
18+
the Linux kernel can support up to four system sleep states, includig
19+
hibernation and up to three variants of system suspend. The sleep states that
20+
can be supported by the kernel are listed below.
21+
22+
.. _s2idle:
23+
24+
Suspend-to-Idle
25+
---------------
26+
27+
This is a generic, pure software, light-weight variant of system suspend (also
28+
referred to as S2I or S2Idle). It allows more energy to be saved relative to
29+
runtime idle by freezing user space, suspending the timekeeping and putting all
30+
I/O devices into low-power states (possibly lower-power than available in the
31+
working state), such that the processors can spend time in their deepest idle
32+
states while the system is suspended.
33+
34+
The system is woken up from this state by in-band interrupts, so theoretically
35+
any devices that can cause interrupts to be generated in the working state can
36+
also be set up as wakeup devices for S2Idle.
37+
38+
This state can be used on platforms without support for :ref:`standby <standby>`
39+
or :ref:`suspend-to-RAM <s2ram>`, or it can be used in addition to any of the
40+
deeper system suspend variants to provide reduced resume latency. It is always
41+
supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set.
42+
43+
.. _standby:
44+
45+
Standby
46+
-------
47+
48+
This state, if supported, offers moderate, but real, energy savings, while
49+
providing a relatively straightforward transition back to the working state. No
50+
operating state is lost (the system core logic retains power), so the system can
51+
go back to where it left off easily enough.
52+
53+
In addition to freezing user space, suspending the timekeeping and putting all
54+
I/O devices into low-power states, which is done for :ref:`suspend-to-idle
55+
<s2idle>` too, nonboot CPUs are taken offline and all low-level system functions
56+
are suspended during transitions into this state. For this reason, it should
57+
allow more energy to be saved relative to :ref:`suspend-to-idle <s2idle>`, but
58+
the resume latency will generally be greater than for that state.
59+
60+
The set of devices that can wake up the system from this state usually is
61+
reduced relative to :ref:`suspend-to-idle <s2idle>` and it may be necessary to
62+
rely on the platform for setting up the wakeup functionality as appropriate.
63+
64+
This state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration
65+
option is set and the support for it is registered by the platform with the
66+
core system suspend subsystem. On ACPI-based systems this state is mapped to
67+
the S1 system state defined by ACPI.
68+
69+
.. _s2ram:
70+
71+
Suspend-to-RAM
72+
--------------
73+
74+
This state (also referred to as STR or S2RAM), if supported, offers significant
75+
energy savings as everything in the system is put into a low-power state, except
76+
for memory, which should be placed into the self-refresh mode to retain its
77+
contents. All of the steps carried out when entering :ref:`standby <standby>`
78+
are also carried out during transitions to S2RAM. Additional operations may
79+
take place depending on the platform capabilities. In particular, on ACPI-based
80+
systems the kernel passes control to the platform firmware (BIOS) as the last
81+
step during S2RAM transitions and that usually results in powering down some
82+
more low-level components that are not directly controlled by the kernel.
83+
84+
The state of devices and CPUs is saved and held in memory. All devices are
85+
suspended and put into low-power states. In many cases, all peripheral buses
86+
lose power when entering S2RAM, so devices must be able to handle the transition
87+
back to the "on" state.
88+
89+
On ACPI-based systems S2RAM requires some minimal boot-strapping code in the
90+
platform firmware to resume the system from it. This may be the case on other
91+
platforms too.
92+
93+
The set of devices that can wake up the system from S2RAM usually is reduced
94+
relative to :ref:`suspend-to-idle <s2idle>` and :ref:`standby <standby>` and it
95+
may be necessary to rely on the platform for setting up the wakeup functionality
96+
as appropriate.
97+
98+
S2RAM is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option
99+
is set and the support for it is registered by the platform with the core system
100+
suspend subsystem. On ACPI-based systems it is mapped to the S3 system state
101+
defined by ACPI.
102+
103+
.. _hibernation:
104+
105+
Hibernation
106+
-----------
107+
108+
This state (also referred to as Suspend-to-Disk or STD) offers the greatest
109+
energy savings and can be used even in the absence of low-level platform support
110+
for system suspend. However, it requires some low-level code for resuming the
111+
system to be present for the underlying CPU architecture.
112+
113+
Hibernation is significantly different from any of the system suspend variants.
114+
It takes three system state changes to put it into hibernation and two system
115+
state changes to resume it.
116+
117+
First, when hibernation is triggered, the kernel stops all system activity and
118+
creates a snapshot image of memory to be written into persistent storage. Next,
119+
the system goes into a state in which the snapshot image can be saved, the image
120+
is written out and finally the system goes into the target low-power state in
121+
which power is cut from almost all of its hardware components, including memory,
122+
except for a limited set of wakeup devices.
123+
124+
Once the snapshot image has been written out, the system may either enter a
125+
special low-power state (like ACPI S4), or it may simply power down itself.
126+
Powering down means minimum power draw and it allows this mechanism to work on
127+
any system. However, entering a special low-power state may allow additional
128+
means of system wakeup to be used (e.g. pressing a key on the keyboard or
129+
opening a laptop lid).
130+
131+
After wakeup, control goes to the platform firmware that runs a boot loader
132+
which boots a fresh instance of the kernel (control may also go directly to
133+
the boot loader, depending on the system configuration, but anyway it causes
134+
a fresh instance of the kernel to be booted). That new instance of the kernel
135+
(referred to as the ``restore kernel``) looks for a hibernation image in
136+
persistent storage and if one is found, it is loaded into memory. Next, all
137+
activity in the system is stopped and the restore kernel overwrites itself with
138+
the image contents and jumps into a special trampoline area in the original
139+
kernel stored in the image (referred to as the ``image kernel``), which is where
140+
the special architecture-specific low-level code is needed. Finally, the
141+
image kernel restores the system to the pre-hibernation state and allows user
142+
space to run again.
143+
144+
Hibernation is supported if the :c:macro:`CONFIG_HIBERNATION` kernel
145+
configuration option is set. However, this option can only be set if support
146+
for the given CPU architecture includes the low-level code for system resume.
147+
148+
149+
Basic ``sysfs`` Interfaces for System Suspend and Hibernation
150+
=============================================================
151+
152+
The following files located in the :file:`/sys/power/` directory can be used by
153+
user space for sleep states control.
154+
155+
``state``
156+
This file contains a list of strings representing sleep states supported
157+
by the kernel. Writing one of these strings into it causes the kernel
158+
to start a transition of the system into the sleep state represented by
159+
that string.
160+
161+
In particular, the strings "disk", "freeze" and "standby" represent the
162+
:ref:`hibernation <hibernation>`, :ref:`suspend-to-idle <s2idle>` and
163+
:ref:`standby <standby>` sleep states, respectively. The string "mem"
164+
is interpreted in accordance with the contents of the ``mem_sleep`` file
165+
described below.
166+
167+
If the kernel does not support any system sleep states, this file is
168+
not present.
169+
170+
``mem_sleep``
171+
This file contains a list of strings representing supported system
172+
suspend variants and allows user space to select the variant to be
173+
associated with the "mem" string in the ``state`` file described above.
174+
175+
The strings that may be present in this file are "s2idle", "shallow"
176+
and "deep". The string "s2idle" always represents :ref:`suspend-to-idle
177+
<s2idle>` and, by convention, "shallow" and "deep" represent
178+
:ref:`standby <standby>` and :ref:`suspend-to-RAM <s2ram>`,
179+
respectively.
180+
181+
Writing one of the listed strings into this file causes the system
182+
suspend variant represented by it to be associated with the "mem" string
183+
in the ``state`` file. The string representing the suspend variant
184+
currently associated with the "mem" string in the ``state`` file
185+
is listed in square brackets.
186+
187+
If the kernel does not support system suspend, this file is not present.
188+
189+
``disk``
190+
This file contains a list of strings representing different operations
191+
that can be carried out after the hibernation image has been saved. The
192+
possible options are as follows:
193+
194+
``platform``
195+
Put the system into a special low-power state (e.g. ACPI S4) to
196+
make additional wakeup options available and possibly allow the
197+
platform firmware to take a simplified initialization path after
198+
wakeup.
199+
200+
``shutdown``
201+
Power off the system.
202+
203+
``reboot``
204+
Reboot the system (useful for diagnostics mostly).
205+
206+
``suspend``
207+
Hybrid system suspend. Put the system into the suspend sleep
208+
state selected through the ``mem_sleep`` file described above.
209+
If the system is successfully woken up from that state, discard
210+
the hibernation image and continue. Otherwise, use the image
211+
to restore the previous state of the system.
212+
213+
``test_resume``
214+
Diagnostic operation. Load the image as though the system had
215+
just woken up from hibernation and the currently running kernel
216+
instance was a restore kernel and follow up with full system
217+
resume.
218+
219+
Writing one of the listed strings into this file causes the option
220+
represented by it to be selected.
221+
222+
The currently selected option is shown in square brackets which means
223+
that the operation represented by it will be carried out after creating
224+
and saving the image next time hibernation is triggered by writing
225+
``disk`` to :file:`/sys/power/state`.
226+
227+
If the kernel does not support hibernation, this file is not present.
228+
229+
According to the above, there are two ways to make the system go into the
230+
:ref:`suspend-to-idle <s2idle>` state. The first one is to write "freeze"
231+
directly to :file:`/sys/power/state`. The second one is to write "s2idle" to
232+
:file:`/sys/power/mem_sleep` and then to write "mem" to
233+
:file:`/sys/power/state`. Likewise, there are two ways to make the system go
234+
into the :ref:`standby <standby>` state (the strings to write to the control
235+
files in that case are "standby" or "shallow" and "mem", respectively) if that
236+
state is supported by the platform. However, there is only one way to make the
237+
system go into the :ref:`suspend-to-RAM <s2ram>` state (write "deep" into
238+
:file:`/sys/power/mem_sleep` and "mem" into :file:`/sys/power/state`).
239+
240+
The default suspend variant (ie. the one to be used without writing anything
241+
into :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems
242+
supporting :ref:`suspend-to-RAM <s2ram>`) or "s2idle", but it can be overridden
243+
by the value of the "mem_sleep_default" parameter in the kernel command line.
244+
On some ACPI-based systems, depending on the information in the ACPI tables, the
245+
default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported.

‎Documentation/admin-guide/pm/strategies.rst

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
===========================
2+
Power Management Strategies
3+
===========================
4+
5+
::
6+
7+
Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <[email protected]>
8+
9+
The Linux kernel supports two major high-level power management strategies.
10+
11+
One of them is based on using global low-power states of the whole system in
12+
which user space code cannot be executed and the overall system activity is
13+
significantly reduced, referred to as :doc:`sleep states <sleep-states>`. The
14+
kernel puts the system into one of these states when requested by user space
15+
and the system stays in it until a special signal is received from one of
16+
designated devices, triggering a transition to the ``working state`` in which
17+
user space code can run. Because sleep states are global and the whole system
18+
is affected by the state changes, this strategy is referred to as the
19+
:doc:`system-wide power management <system-wide>`.
20+
21+
The other strategy, referred to as the :doc:`working-state power management
22+
<working-state>`, is based on adjusting the power states of individual hardware
23+
components of the system, as needed, in the working state. In consequence, if
24+
this strategy is in use, the working state of the system usually does not
25+
correspond to any particular physical configuration of it, but can be treated as
26+
a metastate covering a range of different power states of the system in which
27+
the individual components of it can be either ``active`` (in use) or
28+
``inactive`` (idle). If they are active, they have to be in power states
29+
allowing them to process data and to be accessed by software. In turn, if they
30+
are inactive, ideally, they should be in low-power states in which they may not
31+
be accessible.
32+
33+
If all of the system components are active, the system as a whole is regarded as
34+
"runtime active" and that situation typically corresponds to the maximum power
35+
draw (or maximum energy usage) of it. If all of them are inactive, the system
36+
as a whole is regarded as "runtime idle" which may be very close to a sleep
37+
state from the physical system configuration and power draw perspective, but
38+
then it takes much less time and effort to start executing user space code than
39+
for the same system in a sleep state. However, transitions from sleep states
40+
back to the working state can only be started by a limited set of devices, so
41+
typically the system can spend much more time in a sleep state than it can be
42+
runtime idle in one go. For this reason, systems usually use less energy in
43+
sleep states than when they are runtime idle most of the time.
44+
45+
Moreover, the two power management strategies address different usage scenarios.
46+
Namely, if the user indicates that the system will not be in use going forward,
47+
for example by closing its lid (if the system is a laptop), it probably should
48+
go into a sleep state at that point. On the other hand, if the user simply goes
49+
away from the laptop keyboard, it probably should stay in the working state and
50+
use the working-state power management in case it becomes idle, because the user
51+
may come back to it at any time and then may want the system to be immediately
52+
accessible.

‎Documentation/admin-guide/pm/system-wide.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
============================
2+
System-Wide Power Management
3+
============================
4+
5+
.. toctree::
6+
:maxdepth: 2
7+
8+
sleep-states

‎Documentation/admin-guide/pm/working-state.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
==============================
2+
Working-State Power Management
3+
==============================
4+
5+
.. toctree::
6+
:maxdepth: 2
7+
8+
cpufreq
9+
intel_pstate

0 commit comments

Comments
 (0)