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

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