0001 .. SPDX-License-Identifier: GPL-2.0
0002 .. include:: <isonum.txt>
0003
0004 ===================
0005 System Sleep States
0006 ===================
0007
0008 :Copyright: |copy| 2017 Intel Corporation
0009
0010 :Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com>
0011
0012
0013 Sleep states are global low-power states of the entire system in which user
0014 space code cannot be executed and the overall system activity is significantly
0015 reduced.
0016
0017
0018 Sleep States That Can Be Supported
0019 ==================================
0020
0021 Depending on its configuration and the capabilities of the platform it runs on,
0022 the Linux kernel can support up to four system sleep states, including
0023 hibernation and up to three variants of system suspend. The sleep states that
0024 can be supported by the kernel are listed below.
0025
0026 .. _s2idle:
0027
0028 Suspend-to-Idle
0029 ---------------
0030
0031 This is a generic, pure software, light-weight variant of system suspend (also
0032 referred to as S2I or S2Idle). It allows more energy to be saved relative to
0033 runtime idle by freezing user space, suspending the timekeeping and putting all
0034 I/O devices into low-power states (possibly lower-power than available in the
0035 working state), such that the processors can spend time in their deepest idle
0036 states while the system is suspended.
0037
0038 The system is woken up from this state by in-band interrupts, so theoretically
0039 any devices that can cause interrupts to be generated in the working state can
0040 also be set up as wakeup devices for S2Idle.
0041
0042 This state can be used on platforms without support for :ref:`standby <standby>`
0043 or :ref:`suspend-to-RAM <s2ram>`, or it can be used in addition to any of the
0044 deeper system suspend variants to provide reduced resume latency. It is always
0045 supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set.
0046
0047 .. _standby:
0048
0049 Standby
0050 -------
0051
0052 This state, if supported, offers moderate, but real, energy savings, while
0053 providing a relatively straightforward transition back to the working state. No
0054 operating state is lost (the system core logic retains power), so the system can
0055 go back to where it left off easily enough.
0056
0057 In addition to freezing user space, suspending the timekeeping and putting all
0058 I/O devices into low-power states, which is done for :ref:`suspend-to-idle
0059 <s2idle>` too, nonboot CPUs are taken offline and all low-level system functions
0060 are suspended during transitions into this state. For this reason, it should
0061 allow more energy to be saved relative to :ref:`suspend-to-idle <s2idle>`, but
0062 the resume latency will generally be greater than for that state.
0063
0064 The set of devices that can wake up the system from this state usually is
0065 reduced relative to :ref:`suspend-to-idle <s2idle>` and it may be necessary to
0066 rely on the platform for setting up the wakeup functionality as appropriate.
0067
0068 This state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration
0069 option is set and the support for it is registered by the platform with the
0070 core system suspend subsystem. On ACPI-based systems this state is mapped to
0071 the S1 system state defined by ACPI.
0072
0073 .. _s2ram:
0074
0075 Suspend-to-RAM
0076 --------------
0077
0078 This state (also referred to as STR or S2RAM), if supported, offers significant
0079 energy savings as everything in the system is put into a low-power state, except
0080 for memory, which should be placed into the self-refresh mode to retain its
0081 contents. All of the steps carried out when entering :ref:`standby <standby>`
0082 are also carried out during transitions to S2RAM. Additional operations may
0083 take place depending on the platform capabilities. In particular, on ACPI-based
0084 systems the kernel passes control to the platform firmware (BIOS) as the last
0085 step during S2RAM transitions and that usually results in powering down some
0086 more low-level components that are not directly controlled by the kernel.
0087
0088 The state of devices and CPUs is saved and held in memory. All devices are
0089 suspended and put into low-power states. In many cases, all peripheral buses
0090 lose power when entering S2RAM, so devices must be able to handle the transition
0091 back to the "on" state.
0092
0093 On ACPI-based systems S2RAM requires some minimal boot-strapping code in the
0094 platform firmware to resume the system from it. This may be the case on other
0095 platforms too.
0096
0097 The set of devices that can wake up the system from S2RAM usually is reduced
0098 relative to :ref:`suspend-to-idle <s2idle>` and :ref:`standby <standby>` and it
0099 may be necessary to rely on the platform for setting up the wakeup functionality
0100 as appropriate.
0101
0102 S2RAM is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option
0103 is set and the support for it is registered by the platform with the core system
0104 suspend subsystem. On ACPI-based systems it is mapped to the S3 system state
0105 defined by ACPI.
0106
0107 .. _hibernation:
0108
0109 Hibernation
0110 -----------
0111
0112 This state (also referred to as Suspend-to-Disk or STD) offers the greatest
0113 energy savings and can be used even in the absence of low-level platform support
0114 for system suspend. However, it requires some low-level code for resuming the
0115 system to be present for the underlying CPU architecture.
0116
0117 Hibernation is significantly different from any of the system suspend variants.
0118 It takes three system state changes to put it into hibernation and two system
0119 state changes to resume it.
0120
0121 First, when hibernation is triggered, the kernel stops all system activity and
0122 creates a snapshot image of memory to be written into persistent storage. Next,
0123 the system goes into a state in which the snapshot image can be saved, the image
0124 is written out and finally the system goes into the target low-power state in
0125 which power is cut from almost all of its hardware components, including memory,
0126 except for a limited set of wakeup devices.
0127
0128 Once the snapshot image has been written out, the system may either enter a
0129 special low-power state (like ACPI S4), or it may simply power down itself.
0130 Powering down means minimum power draw and it allows this mechanism to work on
0131 any system. However, entering a special low-power state may allow additional
0132 means of system wakeup to be used (e.g. pressing a key on the keyboard or
0133 opening a laptop lid).
0134
0135 After wakeup, control goes to the platform firmware that runs a boot loader
0136 which boots a fresh instance of the kernel (control may also go directly to
0137 the boot loader, depending on the system configuration, but anyway it causes
0138 a fresh instance of the kernel to be booted). That new instance of the kernel
0139 (referred to as the ``restore kernel``) looks for a hibernation image in
0140 persistent storage and if one is found, it is loaded into memory. Next, all
0141 activity in the system is stopped and the restore kernel overwrites itself with
0142 the image contents and jumps into a special trampoline area in the original
0143 kernel stored in the image (referred to as the ``image kernel``), which is where
0144 the special architecture-specific low-level code is needed. Finally, the
0145 image kernel restores the system to the pre-hibernation state and allows user
0146 space to run again.
0147
0148 Hibernation is supported if the :c:macro:`CONFIG_HIBERNATION` kernel
0149 configuration option is set. However, this option can only be set if support
0150 for the given CPU architecture includes the low-level code for system resume.
0151
0152
0153 Basic ``sysfs`` Interfaces for System Suspend and Hibernation
0154 =============================================================
0155
0156 The power management subsystem provides userspace with a unified ``sysfs``
0157 interface for system sleep regardless of the underlying system architecture or
0158 platform. That interface is located in the :file:`/sys/power/` directory
0159 (assuming that ``sysfs`` is mounted at :file:`/sys`) and it consists of the
0160 following attributes (files):
0161
0162 ``state``
0163 This file contains a list of strings representing sleep states supported
0164 by the kernel. Writing one of these strings into it causes the kernel
0165 to start a transition of the system into the sleep state represented by
0166 that string.
0167
0168 In particular, the "disk", "freeze" and "standby" strings represent the
0169 :ref:`hibernation <hibernation>`, :ref:`suspend-to-idle <s2idle>` and
0170 :ref:`standby <standby>` sleep states, respectively. The "mem" string
0171 is interpreted in accordance with the contents of the ``mem_sleep`` file
0172 described below.
0173
0174 If the kernel does not support any system sleep states, this file is
0175 not present.
0176
0177 ``mem_sleep``
0178 This file contains a list of strings representing supported system
0179 suspend variants and allows user space to select the variant to be
0180 associated with the "mem" string in the ``state`` file described above.
0181
0182 The strings that may be present in this file are "s2idle", "shallow"
0183 and "deep". The "s2idle" string always represents :ref:`suspend-to-idle
0184 <s2idle>` and, by convention, "shallow" and "deep" represent
0185 :ref:`standby <standby>` and :ref:`suspend-to-RAM <s2ram>`,
0186 respectively.
0187
0188 Writing one of the listed strings into this file causes the system
0189 suspend variant represented by it to be associated with the "mem" string
0190 in the ``state`` file. The string representing the suspend variant
0191 currently associated with the "mem" string in the ``state`` file is
0192 shown in square brackets.
0193
0194 If the kernel does not support system suspend, this file is not present.
0195
0196 ``disk``
0197 This file controls the operating mode of hibernation (Suspend-to-Disk).
0198 Specifically, it tells the kernel what to do after creating a
0199 hibernation image.
0200
0201 Reading from it returns a list of supported options encoded as:
0202
0203 ``platform``
0204 Put the system into a special low-power state (e.g. ACPI S4) to
0205 make additional wakeup options available and possibly allow the
0206 platform firmware to take a simplified initialization path after
0207 wakeup.
0208
0209 It is only available if the platform provides a special
0210 mechanism to put the system to sleep after creating a
0211 hibernation image (platforms with ACPI do that as a rule, for
0212 example).
0213
0214 ``shutdown``
0215 Power off the system.
0216
0217 ``reboot``
0218 Reboot the system (useful for diagnostics mostly).
0219
0220 ``suspend``
0221 Hybrid system suspend. Put the system into the suspend sleep
0222 state selected through the ``mem_sleep`` file described above.
0223 If the system is successfully woken up from that state, discard
0224 the hibernation image and continue. Otherwise, use the image
0225 to restore the previous state of the system.
0226
0227 It is available if system suspend is supported.
0228
0229 ``test_resume``
0230 Diagnostic operation. Load the image as though the system had
0231 just woken up from hibernation and the currently running kernel
0232 instance was a restore kernel and follow up with full system
0233 resume.
0234
0235 Writing one of the strings listed above into this file causes the option
0236 represented by it to be selected.
0237
0238 The currently selected option is shown in square brackets, which means
0239 that the operation represented by it will be carried out after creating
0240 and saving the image when hibernation is triggered by writing ``disk``
0241 to :file:`/sys/power/state`.
0242
0243 If the kernel does not support hibernation, this file is not present.
0244
0245 ``image_size``
0246 This file controls the size of hibernation images.
0247
0248 It can be written a string representing a non-negative integer that will
0249 be used as a best-effort upper limit of the image size, in bytes. The
0250 hibernation core will do its best to ensure that the image size will not
0251 exceed that number, but if that turns out to be impossible to achieve, a
0252 hibernation image will still be created and its size will be as small as
0253 possible. In particular, writing '0' to this file causes the size of
0254 hibernation images to be minimum.
0255
0256 Reading from it returns the current image size limit, which is set to
0257 around 2/5 of the available RAM size by default.
0258
0259 ``pm_trace``
0260 This file controls the "PM trace" mechanism saving the last suspend
0261 or resume event point in the RTC memory across reboots. It helps to
0262 debug hard lockups or reboots due to device driver failures that occur
0263 during system suspend or resume (which is more common) more effectively.
0264
0265 If it contains "1", the fingerprint of each suspend/resume event point
0266 in turn will be stored in the RTC memory (overwriting the actual RTC
0267 information), so it will survive a system crash if one occurs right
0268 after storing it and it can be used later to identify the driver that
0269 caused the crash to happen.
0270
0271 It contains "0" by default, which may be changed to "1" by writing a
0272 string representing a nonzero integer into it.
0273
0274 According to the above, there are two ways to make the system go into the
0275 :ref:`suspend-to-idle <s2idle>` state. The first one is to write "freeze"
0276 directly to :file:`/sys/power/state`. The second one is to write "s2idle" to
0277 :file:`/sys/power/mem_sleep` and then to write "mem" to
0278 :file:`/sys/power/state`. Likewise, there are two ways to make the system go
0279 into the :ref:`standby <standby>` state (the strings to write to the control
0280 files in that case are "standby" or "shallow" and "mem", respectively) if that
0281 state is supported by the platform. However, there is only one way to make the
0282 system go into the :ref:`suspend-to-RAM <s2ram>` state (write "deep" into
0283 :file:`/sys/power/mem_sleep` and "mem" into :file:`/sys/power/state`).
0284
0285 The default suspend variant (ie. the one to be used without writing anything
0286 into :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems
0287 supporting :ref:`suspend-to-RAM <s2ram>`) or "s2idle", but it can be overridden
0288 by the value of the ``mem_sleep_default`` parameter in the kernel command line.
0289 On some systems with ACPI, depending on the information in the ACPI tables, the
0290 default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported in
0291 principle.
