sleep-states.rst 13 KB

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