1===================
2System Sleep States
3===================
4
5::
6
7 Copyright (c) 2017 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
8
9Sleep states are global low-power states of the entire system in which user
10space code cannot be executed and the overall system activity is significantly
11reduced.
12
13
14Sleep States That Can Be Supported
15==================================
16
17Depending on its configuration and the capabilities of the platform it runs on,
18the Linux kernel can support up to four system sleep states, including
19hibernation and up to three variants of system suspend.  The sleep states that
20can be supported by the kernel are listed below.
21
22.. _s2idle:
23
24Suspend-to-Idle
25---------------
26
27This is a generic, pure software, light-weight variant of system suspend (also
28referred to as S2I or S2Idle).  It allows more energy to be saved relative to
29runtime idle by freezing user space, suspending the timekeeping and putting all
30I/O devices into low-power states (possibly lower-power than available in the
31working state), such that the processors can spend time in their deepest idle
32states while the system is suspended.
33
34The system is woken up from this state by in-band interrupts, so theoretically
35any devices that can cause interrupts to be generated in the working state can
36also be set up as wakeup devices for S2Idle.
37
38This state can be used on platforms without support for :ref:`standby <standby>`
39or :ref:`suspend-to-RAM <s2ram>`, or it can be used in addition to any of the
40deeper system suspend variants to provide reduced resume latency.  It is always
41supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set.
42
43.. _standby:
44
45Standby
46-------
47
48This state, if supported, offers moderate, but real, energy savings, while
49providing a relatively straightforward transition back to the working state.  No
50operating state is lost (the system core logic retains power), so the system can
51go back to where it left off easily enough.
52
53In addition to freezing user space, suspending the timekeeping and putting all
54I/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
56are suspended during transitions into this state.  For this reason, it should
57allow more energy to be saved relative to :ref:`suspend-to-idle <s2idle>`, but
58the resume latency will generally be greater than for that state.
59
60The set of devices that can wake up the system from this state usually is
61reduced relative to :ref:`suspend-to-idle <s2idle>` and it may be necessary to
62rely on the platform for setting up the wakeup functionality as appropriate.
63
64This state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration
65option is set and the support for it is registered by the platform with the
66core system suspend subsystem.  On ACPI-based systems this state is mapped to
67the S1 system state defined by ACPI.
68
69.. _s2ram:
70
71Suspend-to-RAM
72--------------
73
74This state (also referred to as STR or S2RAM), if supported, offers significant
75energy savings as everything in the system is put into a low-power state, except
76for memory, which should be placed into the self-refresh mode to retain its
77contents.  All of the steps carried out when entering :ref:`standby <standby>`
78are also carried out during transitions to S2RAM.  Additional operations may
79take place depending on the platform capabilities.  In particular, on ACPI-based
80systems the kernel passes control to the platform firmware (BIOS) as the last
81step during S2RAM transitions and that usually results in powering down some
82more low-level components that are not directly controlled by the kernel.
83
84The state of devices and CPUs is saved and held in memory.  All devices are
85suspended and put into low-power states.  In many cases, all peripheral buses
86lose power when entering S2RAM, so devices must be able to handle the transition
87back to the "on" state.
88
89On ACPI-based systems S2RAM requires some minimal boot-strapping code in the
90platform firmware to resume the system from it.  This may be the case on other
91platforms too.
92
93The set of devices that can wake up the system from S2RAM usually is reduced
94relative to :ref:`suspend-to-idle <s2idle>` and :ref:`standby <standby>` and it
95may be necessary to rely on the platform for setting up the wakeup functionality
96as appropriate.
97
98S2RAM is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option
99is set and the support for it is registered by the platform with the core system
100suspend subsystem.  On ACPI-based systems it is mapped to the S3 system state
101defined by ACPI.
102
103.. _hibernation:
104
105Hibernation
106-----------
107
108This state (also referred to as Suspend-to-Disk or STD) offers the greatest
109energy savings and can be used even in the absence of low-level platform support
110for system suspend.  However, it requires some low-level code for resuming the
111system to be present for the underlying CPU architecture.
112
113Hibernation is significantly different from any of the system suspend variants.
114It takes three system state changes to put it into hibernation and two system
115state changes to resume it.
116
117First, when hibernation is triggered, the kernel stops all system activity and
118creates a snapshot image of memory to be written into persistent storage.  Next,
119the system goes into a state in which the snapshot image can be saved, the image
120is written out and finally the system goes into the target low-power state in
121which power is cut from almost all of its hardware components, including memory,
122except for a limited set of wakeup devices.
123
124Once the snapshot image has been written out, the system may either enter a
125special low-power state (like ACPI S4), or it may simply power down itself.
126Powering down means minimum power draw and it allows this mechanism to work on
127any system.  However, entering a special low-power state may allow additional
128means of system wakeup to be used  (e.g. pressing a key on the keyboard or
129opening a laptop lid).
130
131After wakeup, control goes to the platform firmware that runs a boot loader
132which boots a fresh instance of the kernel (control may also go directly to
133the boot loader, depending on the system configuration, but anyway it causes
134a 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
136persistent storage and if one is found, it is loaded into memory.  Next, all
137activity in the system is stopped and the restore kernel overwrites itself with
138the image contents and jumps into a special trampoline area in the original
139kernel stored in the image (referred to as the ``image kernel``), which is where
140the special architecture-specific low-level code is needed.  Finally, the
141image kernel restores the system to the pre-hibernation state and allows user
142space to run again.
143
144Hibernation is supported if the :c:macro:`CONFIG_HIBERNATION` kernel
145configuration option is set.  However, this option can only be set if support
146for the given CPU architecture includes the low-level code for system resume.
147
148
149Basic ``sysfs`` Interfaces for System Suspend and Hibernation
150=============================================================
151
152The following files located in the :file:`/sys/power/` directory can be used by
153user 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
229According 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"
231directly 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
234into the :ref:`standby <standby>` state (the strings to write to the control
235files in that case are "standby" or "shallow" and "mem", respectively) if that
236state is supported by the platform.  However, there is only one way to make the
237system 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
240The default suspend variant (ie. the one to be used without writing anything
241into :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems
242supporting :ref:`suspend-to-RAM <s2ram>`) or "s2idle", but it can be overridden
243by the value of the "mem_sleep_default" parameter in the kernel command line.
244On some ACPI-based systems, depending on the information in the ACPI tables, the
245default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported.
246