1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 .. include:: <isonum.txt> 2 .. include:: <isonum.txt>
3 3
4 =================== 4 ===================
5 System Sleep States 5 System Sleep States
6 =================== 6 ===================
7 7
8 :Copyright: |copy| 2017 Intel Corporation 8 :Copyright: |copy| 2017 Intel Corporation
9 9
10 :Author: Rafael J. Wysocki <rafael.j.wysocki@in 10 :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
11 11
12 12
13 Sleep states are global low-power states of th 13 Sleep states are global low-power states of the entire system in which user
14 space code cannot be executed and the overall 14 space code cannot be executed and the overall system activity is significantly
15 reduced. 15 reduced.
16 16
17 17
18 Sleep States That Can Be Supported 18 Sleep States That Can Be Supported
19 ================================== 19 ==================================
20 20
21 Depending on its configuration and the capabil 21 Depending on its configuration and the capabilities of the platform it runs on,
22 the Linux kernel can support up to four system 22 the Linux kernel can support up to four system sleep states, including
23 hibernation and up to three variants of system 23 hibernation and up to three variants of system suspend. The sleep states that
24 can be supported by the kernel are listed belo 24 can be supported by the kernel are listed below.
25 25
26 .. _s2idle: 26 .. _s2idle:
27 27
28 Suspend-to-Idle 28 Suspend-to-Idle
29 --------------- 29 ---------------
30 30
31 This is a generic, pure software, light-weight 31 This is a generic, pure software, light-weight variant of system suspend (also
32 referred to as S2I or S2Idle). It allows more 32 referred to as S2I or S2Idle). It allows more energy to be saved relative to
33 runtime idle by freezing user space, suspendin 33 runtime idle by freezing user space, suspending the timekeeping and putting all
34 I/O devices into low-power states (possibly lo 34 I/O devices into low-power states (possibly lower-power than available in the
35 working state), such that the processors can s 35 working state), such that the processors can spend time in their deepest idle
36 states while the system is suspended. 36 states while the system is suspended.
37 37
38 The system is woken up from this state by in-b 38 The system is woken up from this state by in-band interrupts, so theoretically
39 any devices that can cause interrupts to be ge 39 any devices that can cause interrupts to be generated in the working state can
40 also be set up as wakeup devices for S2Idle. 40 also be set up as wakeup devices for S2Idle.
41 41
42 This state can be used on platforms without su 42 This state can be used on platforms without support for :ref:`standby <standby>`
43 or :ref:`suspend-to-RAM <s2ram>`, or it can be 43 or :ref:`suspend-to-RAM <s2ram>`, or it can be used in addition to any of the
44 deeper system suspend variants to provide redu 44 deeper system suspend variants to provide reduced resume latency. It is always
45 supported if the :c:macro:`CONFIG_SUSPEND` ker 45 supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set.
46 46
47 .. _standby: 47 .. _standby:
48 48
49 Standby 49 Standby
50 ------- 50 -------
51 51
52 This state, if supported, offers moderate, but 52 This state, if supported, offers moderate, but real, energy savings, while
53 providing a relatively straightforward transit 53 providing a relatively straightforward transition back to the working state. No
54 operating state is lost (the system core logic 54 operating state is lost (the system core logic retains power), so the system can
55 go back to where it left off easily enough. 55 go back to where it left off easily enough.
56 56
57 In addition to freezing user space, suspending 57 In addition to freezing user space, suspending the timekeeping and putting all
58 I/O devices into low-power states, which is do 58 I/O devices into low-power states, which is done for :ref:`suspend-to-idle
59 <s2idle>` too, nonboot CPUs are taken offline 59 <s2idle>` too, nonboot CPUs are taken offline and all low-level system functions
60 are suspended during transitions into this sta 60 are suspended during transitions into this state. For this reason, it should
61 allow more energy to be saved relative to :ref 61 allow more energy to be saved relative to :ref:`suspend-to-idle <s2idle>`, but
62 the resume latency will generally be greater t 62 the resume latency will generally be greater than for that state.
63 63
64 The set of devices that can wake up the system 64 The set of devices that can wake up the system from this state usually is
65 reduced relative to :ref:`suspend-to-idle <s2i 65 reduced relative to :ref:`suspend-to-idle <s2idle>` and it may be necessary to
66 rely on the platform for setting up the wakeup 66 rely on the platform for setting up the wakeup functionality as appropriate.
67 67
68 This state is supported if the :c:macro:`CONFI 68 This state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration
69 option is set and the support for it is regist 69 option is set and the support for it is registered by the platform with the
70 core system suspend subsystem. On ACPI-based 70 core system suspend subsystem. On ACPI-based systems this state is mapped to
71 the S1 system state defined by ACPI. 71 the S1 system state defined by ACPI.
72 72
73 .. _s2ram: 73 .. _s2ram:
74 74
75 Suspend-to-RAM 75 Suspend-to-RAM
76 -------------- 76 --------------
77 77
78 This state (also referred to as STR or S2RAM), 78 This state (also referred to as STR or S2RAM), if supported, offers significant
79 energy savings as everything in the system is 79 energy savings as everything in the system is put into a low-power state, except
80 for memory, which should be placed into the se 80 for memory, which should be placed into the self-refresh mode to retain its
81 contents. All of the steps carried out when e 81 contents. All of the steps carried out when entering :ref:`standby <standby>`
82 are also carried out during transitions to S2R 82 are also carried out during transitions to S2RAM. Additional operations may
83 take place depending on the platform capabilit 83 take place depending on the platform capabilities. In particular, on ACPI-based
84 systems the kernel passes control to the platf 84 systems the kernel passes control to the platform firmware (BIOS) as the last
85 step during S2RAM transitions and that usually 85 step during S2RAM transitions and that usually results in powering down some
86 more low-level components that are not directl 86 more low-level components that are not directly controlled by the kernel.
87 87
88 The state of devices and CPUs is saved and hel 88 The state of devices and CPUs is saved and held in memory. All devices are
89 suspended and put into low-power states. In m 89 suspended and put into low-power states. In many cases, all peripheral buses
90 lose power when entering S2RAM, so devices mus 90 lose power when entering S2RAM, so devices must be able to handle the transition
91 back to the "on" state. 91 back to the "on" state.
92 92
93 On ACPI-based systems S2RAM requires some mini 93 On ACPI-based systems S2RAM requires some minimal boot-strapping code in the
94 platform firmware to resume the system from it 94 platform firmware to resume the system from it. This may be the case on other
95 platforms too. 95 platforms too.
96 96
97 The set of devices that can wake up the system 97 The set of devices that can wake up the system from S2RAM usually is reduced
98 relative to :ref:`suspend-to-idle <s2idle>` an 98 relative to :ref:`suspend-to-idle <s2idle>` and :ref:`standby <standby>` and it
99 may be necessary to rely on the platform for s 99 may be necessary to rely on the platform for setting up the wakeup functionality
100 as appropriate. 100 as appropriate.
101 101
102 S2RAM is supported if the :c:macro:`CONFIG_SUS 102 S2RAM is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option
103 is set and the support for it is registered by 103 is set and the support for it is registered by the platform with the core system
104 suspend subsystem. On ACPI-based systems it i 104 suspend subsystem. On ACPI-based systems it is mapped to the S3 system state
105 defined by ACPI. 105 defined by ACPI.
106 106
107 .. _hibernation: 107 .. _hibernation:
108 108
109 Hibernation 109 Hibernation
110 ----------- 110 -----------
111 111
112 This state (also referred to as Suspend-to-Dis 112 This state (also referred to as Suspend-to-Disk or STD) offers the greatest
113 energy savings and can be used even in the abs 113 energy savings and can be used even in the absence of low-level platform support
114 for system suspend. However, it requires some 114 for system suspend. However, it requires some low-level code for resuming the
115 system to be present for the underlying CPU ar 115 system to be present for the underlying CPU architecture.
116 116
117 Hibernation is significantly different from an 117 Hibernation is significantly different from any of the system suspend variants.
118 It takes three system state changes to put it 118 It takes three system state changes to put it into hibernation and two system
119 state changes to resume it. 119 state changes to resume it.
120 120
121 First, when hibernation is triggered, the kern 121 First, when hibernation is triggered, the kernel stops all system activity and
122 creates a snapshot image of memory to be writt 122 creates a snapshot image of memory to be written into persistent storage. Next,
123 the system goes into a state in which the snap 123 the system goes into a state in which the snapshot image can be saved, the image
124 is written out and finally the system goes int 124 is written out and finally the system goes into the target low-power state in
125 which power is cut from almost all of its hard 125 which power is cut from almost all of its hardware components, including memory,
126 except for a limited set of wakeup devices. 126 except for a limited set of wakeup devices.
127 127
128 Once the snapshot image has been written out, 128 Once the snapshot image has been written out, the system may either enter a
129 special low-power state (like ACPI S4), or it 129 special low-power state (like ACPI S4), or it may simply power down itself.
130 Powering down means minimum power draw and it 130 Powering down means minimum power draw and it allows this mechanism to work on
131 any system. However, entering a special low-p 131 any system. However, entering a special low-power state may allow additional
132 means of system wakeup to be used (e.g. press 132 means of system wakeup to be used (e.g. pressing a key on the keyboard or
133 opening a laptop lid). 133 opening a laptop lid).
134 134
135 After wakeup, control goes to the platform fir 135 After wakeup, control goes to the platform firmware that runs a boot loader
136 which boots a fresh instance of the kernel (co 136 which boots a fresh instance of the kernel (control may also go directly to
137 the boot loader, depending on the system confi 137 the boot loader, depending on the system configuration, but anyway it causes
138 a fresh instance of the kernel to be booted). 138 a fresh instance of the kernel to be booted). That new instance of the kernel
139 (referred to as the ``restore kernel``) looks 139 (referred to as the ``restore kernel``) looks for a hibernation image in
140 persistent storage and if one is found, it is 140 persistent storage and if one is found, it is loaded into memory. Next, all
141 activity in the system is stopped and the rest 141 activity in the system is stopped and the restore kernel overwrites itself with
142 the image contents and jumps into a special tr 142 the image contents and jumps into a special trampoline area in the original
143 kernel stored in the image (referred to as the 143 kernel stored in the image (referred to as the ``image kernel``), which is where
144 the special architecture-specific low-level co 144 the special architecture-specific low-level code is needed. Finally, the
145 image kernel restores the system to the pre-hi 145 image kernel restores the system to the pre-hibernation state and allows user
146 space to run again. 146 space to run again.
147 147
148 Hibernation is supported if the :c:macro:`CONF 148 Hibernation is supported if the :c:macro:`CONFIG_HIBERNATION` kernel
149 configuration option is set. However, this op 149 configuration option is set. However, this option can only be set if support
150 for the given CPU architecture includes the lo 150 for the given CPU architecture includes the low-level code for system resume.
151 151
152 152
153 Basic ``sysfs`` Interfaces for System Suspend 153 Basic ``sysfs`` Interfaces for System Suspend and Hibernation
154 ============================================== 154 =============================================================
155 155
156 The power management subsystem provides usersp !! 156 The following files located in the :file:`/sys/power/` directory can be used by
157 interface for system sleep regardless of the u !! 157 user space for sleep states control.
158 platform. That interface is located in the :f <<
159 (assuming that ``sysfs`` is mounted at :file:` <<
160 following attributes (files): <<
161 158
162 ``state`` 159 ``state``
163 This file contains a list of strings r 160 This file contains a list of strings representing sleep states supported
164 by the kernel. Writing one of these s 161 by the kernel. Writing one of these strings into it causes the kernel
165 to start a transition of the system in 162 to start a transition of the system into the sleep state represented by
166 that string. 163 that string.
167 164
168 In particular, the "disk", "freeze" an !! 165 In particular, the strings "disk", "freeze" and "standby" represent the
169 :ref:`hibernation <hibernation>`, :ref 166 :ref:`hibernation <hibernation>`, :ref:`suspend-to-idle <s2idle>` and
170 :ref:`standby <standby>` sleep states, !! 167 :ref:`standby <standby>` sleep states, respectively. The string "mem"
171 is interpreted in accordance with the 168 is interpreted in accordance with the contents of the ``mem_sleep`` file
172 described below. 169 described below.
173 170
174 If the kernel does not support any sys 171 If the kernel does not support any system sleep states, this file is
175 not present. 172 not present.
176 173
177 ``mem_sleep`` 174 ``mem_sleep``
178 This file contains a list of strings r 175 This file contains a list of strings representing supported system
179 suspend variants and allows user space 176 suspend variants and allows user space to select the variant to be
180 associated with the "mem" string in th 177 associated with the "mem" string in the ``state`` file described above.
181 178
182 The strings that may be present in thi 179 The strings that may be present in this file are "s2idle", "shallow"
183 and "deep". The "s2idle" string alway !! 180 and "deep". The string "s2idle" always represents :ref:`suspend-to-idle
184 <s2idle>` and, by convention, "shallow 181 <s2idle>` and, by convention, "shallow" and "deep" represent
185 :ref:`standby <standby>` and :ref:`sus 182 :ref:`standby <standby>` and :ref:`suspend-to-RAM <s2ram>`,
186 respectively. 183 respectively.
187 184
188 Writing one of the listed strings into 185 Writing one of the listed strings into this file causes the system
189 suspend variant represented by it to b 186 suspend variant represented by it to be associated with the "mem" string
190 in the ``state`` file. The string rep 187 in the ``state`` file. The string representing the suspend variant
191 currently associated with the "mem" st !! 188 currently associated with the "mem" string in the ``state`` file
192 shown in square brackets. !! 189 is listed in square brackets.
193 190
194 If the kernel does not support system 191 If the kernel does not support system suspend, this file is not present.
195 192
196 ``disk`` 193 ``disk``
197 This file controls the operating mode !! 194 This file contains a list of strings representing different operations
198 Specifically, it tells the kernel what !! 195 that can be carried out after the hibernation image has been saved. The
199 hibernation image. !! 196 possible options are as follows:
200 <<
201 Reading from it returns a list of supp <<
202 197
203 ``platform`` 198 ``platform``
204 Put the system into a special 199 Put the system into a special low-power state (e.g. ACPI S4) to
205 make additional wakeup options 200 make additional wakeup options available and possibly allow the
206 platform firmware to take a si 201 platform firmware to take a simplified initialization path after
207 wakeup. 202 wakeup.
208 203
209 It is only available if the pl <<
210 mechanism to put the system to <<
211 hibernation image (platforms w <<
212 example). <<
213 <<
214 ``shutdown`` 204 ``shutdown``
215 Power off the system. 205 Power off the system.
216 206
217 ``reboot`` 207 ``reboot``
218 Reboot the system (useful for 208 Reboot the system (useful for diagnostics mostly).
219 209
220 ``suspend`` 210 ``suspend``
221 Hybrid system suspend. Put th 211 Hybrid system suspend. Put the system into the suspend sleep
222 state selected through the ``m 212 state selected through the ``mem_sleep`` file described above.
223 If the system is successfully 213 If the system is successfully woken up from that state, discard
224 the hibernation image and cont 214 the hibernation image and continue. Otherwise, use the image
225 to restore the previous state 215 to restore the previous state of the system.
226 216
227 It is available if system susp <<
228 <<
229 ``test_resume`` 217 ``test_resume``
230 Diagnostic operation. Load th 218 Diagnostic operation. Load the image as though the system had
231 just woken up from hibernation 219 just woken up from hibernation and the currently running kernel
232 instance was a restore kernel 220 instance was a restore kernel and follow up with full system
233 resume. 221 resume.
234 222
235 Writing one of the strings listed abov !! 223 Writing one of the listed strings into this file causes the option
236 represented by it to be selected. 224 represented by it to be selected.
237 225
238 The currently selected option is shown !! 226 The currently selected option is shown in square brackets which means
239 that the operation represented by it w 227 that the operation represented by it will be carried out after creating
240 and saving the image when hibernation !! 228 and saving the image next time hibernation is triggered by writing
241 to :file:`/sys/power/state`. !! 229 ``disk`` to :file:`/sys/power/state`.
242 230
243 If the kernel does not support hiberna 231 If the kernel does not support hibernation, this file is not present.
244 232
245 ``image_size`` <<
246 This file controls the size of hiberna <<
247 <<
248 It can be written a string representin <<
249 be used as a best-effort upper limit o <<
250 hibernation core will do its best to e <<
251 exceed that number, but if that turns <<
252 hibernation image will still be create <<
253 possible. In particular, writing '0' <<
254 hibernation images to be minimum. <<
255 <<
256 Reading from it returns the current im <<
257 around 2/5 of the available RAM size b <<
258 <<
259 ``pm_trace`` <<
260 This file controls the "PM trace" mech <<
261 or resume event point in the RTC memor <<
262 debug hard lockups or reboots due to d <<
263 during system suspend or resume (which <<
264 <<
265 If it contains "1", the fingerprint of <<
266 in turn will be stored in the RTC memo <<
267 information), so it will survive a sys <<
268 after storing it and it can be used la <<
269 caused the crash to happen. <<
270 <<
271 It contains "0" by default, which may <<
272 string representing a nonzero integer <<
273 <<
274 According to the above, there are two ways to 233 According to the above, there are two ways to make the system go into the
275 :ref:`suspend-to-idle <s2idle>` state. The fi 234 :ref:`suspend-to-idle <s2idle>` state. The first one is to write "freeze"
276 directly to :file:`/sys/power/state`. The sec 235 directly to :file:`/sys/power/state`. The second one is to write "s2idle" to
277 :file:`/sys/power/mem_sleep` and then to write 236 :file:`/sys/power/mem_sleep` and then to write "mem" to
278 :file:`/sys/power/state`. Likewise, there are 237 :file:`/sys/power/state`. Likewise, there are two ways to make the system go
279 into the :ref:`standby <standby>` state (the s 238 into the :ref:`standby <standby>` state (the strings to write to the control
280 files in that case are "standby" or "shallow" 239 files in that case are "standby" or "shallow" and "mem", respectively) if that
281 state is supported by the platform. However, 240 state is supported by the platform. However, there is only one way to make the
282 system go into the :ref:`suspend-to-RAM <s2ram 241 system go into the :ref:`suspend-to-RAM <s2ram>` state (write "deep" into
283 :file:`/sys/power/mem_sleep` and "mem" into :f 242 :file:`/sys/power/mem_sleep` and "mem" into :file:`/sys/power/state`).
284 243
285 The default suspend variant (ie. the one to be 244 The default suspend variant (ie. the one to be used without writing anything
286 into :file:`/sys/power/mem_sleep`) is either " 245 into :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems
287 supporting :ref:`suspend-to-RAM <s2ram>`) or " 246 supporting :ref:`suspend-to-RAM <s2ram>`) or "s2idle", but it can be overridden
288 by the value of the ``mem_sleep_default`` para !! 247 by the value of the "mem_sleep_default" parameter in the kernel command line.
289 On some systems with ACPI, depending on the in !! 248 On some ACPI-based systems, depending on the information in the ACPI tables, the
290 default may be "s2idle" even if :ref:`suspend- !! 249 default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported.
291 principle. <<
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.