1fc7db767SRafael J. Wysocki.. SPDX-License-Identifier: GPL-2.0 2fc1860d6SRafael J. Wysocki.. include:: <isonum.txt> 3fc7db767SRafael J. Wysocki 40c0b6b7bSRafael J. Wysocki=================== 50c0b6b7bSRafael J. WysockiSystem Sleep States 60c0b6b7bSRafael J. Wysocki=================== 70c0b6b7bSRafael J. Wysocki 8fc1860d6SRafael J. Wysocki:Copyright: |copy| 2017 Intel Corporation 90c0b6b7bSRafael J. Wysocki 10fc1860d6SRafael J. Wysocki:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> 11fc1860d6SRafael J. Wysocki 120c0b6b7bSRafael J. Wysocki 130c0b6b7bSRafael J. WysockiSleep states are global low-power states of the entire system in which user 140c0b6b7bSRafael J. Wysockispace code cannot be executed and the overall system activity is significantly 150c0b6b7bSRafael J. Wysockireduced. 160c0b6b7bSRafael J. Wysocki 170c0b6b7bSRafael J. Wysocki 180c0b6b7bSRafael J. WysockiSleep States That Can Be Supported 190c0b6b7bSRafael J. Wysocki================================== 200c0b6b7bSRafael J. Wysocki 210c0b6b7bSRafael J. WysockiDepending on its configuration and the capabilities of the platform it runs on, 22c72a0dedSJonathan Neuschäferthe Linux kernel can support up to four system sleep states, including 230c0b6b7bSRafael J. Wysockihibernation and up to three variants of system suspend. The sleep states that 240c0b6b7bSRafael J. Wysockican be supported by the kernel are listed below. 250c0b6b7bSRafael J. Wysocki 260c0b6b7bSRafael J. Wysocki.. _s2idle: 270c0b6b7bSRafael J. Wysocki 280c0b6b7bSRafael J. WysockiSuspend-to-Idle 290c0b6b7bSRafael J. Wysocki--------------- 300c0b6b7bSRafael J. Wysocki 310c0b6b7bSRafael J. WysockiThis is a generic, pure software, light-weight variant of system suspend (also 320c0b6b7bSRafael J. Wysockireferred to as S2I or S2Idle). It allows more energy to be saved relative to 330c0b6b7bSRafael J. Wysockiruntime idle by freezing user space, suspending the timekeeping and putting all 340c0b6b7bSRafael J. WysockiI/O devices into low-power states (possibly lower-power than available in the 350c0b6b7bSRafael J. Wysockiworking state), such that the processors can spend time in their deepest idle 360c0b6b7bSRafael J. Wysockistates while the system is suspended. 370c0b6b7bSRafael J. Wysocki 380c0b6b7bSRafael J. WysockiThe system is woken up from this state by in-band interrupts, so theoretically 390c0b6b7bSRafael J. Wysockiany devices that can cause interrupts to be generated in the working state can 400c0b6b7bSRafael J. Wysockialso be set up as wakeup devices for S2Idle. 410c0b6b7bSRafael J. Wysocki 420c0b6b7bSRafael J. WysockiThis state can be used on platforms without support for :ref:`standby <standby>` 430c0b6b7bSRafael J. Wysockior :ref:`suspend-to-RAM <s2ram>`, or it can be used in addition to any of the 440c0b6b7bSRafael J. Wysockideeper system suspend variants to provide reduced resume latency. It is always 450c0b6b7bSRafael J. Wysockisupported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option is set. 460c0b6b7bSRafael J. Wysocki 470c0b6b7bSRafael J. Wysocki.. _standby: 480c0b6b7bSRafael J. Wysocki 490c0b6b7bSRafael J. WysockiStandby 500c0b6b7bSRafael J. Wysocki------- 510c0b6b7bSRafael J. Wysocki 520c0b6b7bSRafael J. WysockiThis state, if supported, offers moderate, but real, energy savings, while 530c0b6b7bSRafael J. Wysockiproviding a relatively straightforward transition back to the working state. No 540c0b6b7bSRafael J. Wysockioperating state is lost (the system core logic retains power), so the system can 550c0b6b7bSRafael J. Wysockigo back to where it left off easily enough. 560c0b6b7bSRafael J. Wysocki 570c0b6b7bSRafael J. WysockiIn addition to freezing user space, suspending the timekeeping and putting all 580c0b6b7bSRafael J. WysockiI/O devices into low-power states, which is done for :ref:`suspend-to-idle 590c0b6b7bSRafael J. Wysocki<s2idle>` too, nonboot CPUs are taken offline and all low-level system functions 600c0b6b7bSRafael J. Wysockiare suspended during transitions into this state. For this reason, it should 610c0b6b7bSRafael J. Wysockiallow more energy to be saved relative to :ref:`suspend-to-idle <s2idle>`, but 620c0b6b7bSRafael J. Wysockithe resume latency will generally be greater than for that state. 630c0b6b7bSRafael J. Wysocki 640c0b6b7bSRafael J. WysockiThe set of devices that can wake up the system from this state usually is 650c0b6b7bSRafael J. Wysockireduced relative to :ref:`suspend-to-idle <s2idle>` and it may be necessary to 660c0b6b7bSRafael J. Wysockirely on the platform for setting up the wakeup functionality as appropriate. 670c0b6b7bSRafael J. Wysocki 680c0b6b7bSRafael J. WysockiThis state is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration 690c0b6b7bSRafael J. Wysockioption is set and the support for it is registered by the platform with the 700c0b6b7bSRafael J. Wysockicore system suspend subsystem. On ACPI-based systems this state is mapped to 710c0b6b7bSRafael J. Wysockithe S1 system state defined by ACPI. 720c0b6b7bSRafael J. Wysocki 730c0b6b7bSRafael J. Wysocki.. _s2ram: 740c0b6b7bSRafael J. Wysocki 750c0b6b7bSRafael J. WysockiSuspend-to-RAM 760c0b6b7bSRafael J. Wysocki-------------- 770c0b6b7bSRafael J. Wysocki 780c0b6b7bSRafael J. WysockiThis state (also referred to as STR or S2RAM), if supported, offers significant 790c0b6b7bSRafael J. Wysockienergy savings as everything in the system is put into a low-power state, except 800c0b6b7bSRafael J. Wysockifor memory, which should be placed into the self-refresh mode to retain its 810c0b6b7bSRafael J. Wysockicontents. All of the steps carried out when entering :ref:`standby <standby>` 820c0b6b7bSRafael J. Wysockiare also carried out during transitions to S2RAM. Additional operations may 830c0b6b7bSRafael J. Wysockitake place depending on the platform capabilities. In particular, on ACPI-based 840c0b6b7bSRafael J. Wysockisystems the kernel passes control to the platform firmware (BIOS) as the last 850c0b6b7bSRafael J. Wysockistep during S2RAM transitions and that usually results in powering down some 860c0b6b7bSRafael J. Wysockimore low-level components that are not directly controlled by the kernel. 870c0b6b7bSRafael J. Wysocki 880c0b6b7bSRafael J. WysockiThe state of devices and CPUs is saved and held in memory. All devices are 890c0b6b7bSRafael J. Wysockisuspended and put into low-power states. In many cases, all peripheral buses 900c0b6b7bSRafael J. Wysockilose power when entering S2RAM, so devices must be able to handle the transition 910c0b6b7bSRafael J. Wysockiback to the "on" state. 920c0b6b7bSRafael J. Wysocki 930c0b6b7bSRafael J. WysockiOn ACPI-based systems S2RAM requires some minimal boot-strapping code in the 940c0b6b7bSRafael J. Wysockiplatform firmware to resume the system from it. This may be the case on other 950c0b6b7bSRafael J. Wysockiplatforms too. 960c0b6b7bSRafael J. Wysocki 970c0b6b7bSRafael J. WysockiThe set of devices that can wake up the system from S2RAM usually is reduced 980c0b6b7bSRafael J. Wysockirelative to :ref:`suspend-to-idle <s2idle>` and :ref:`standby <standby>` and it 990c0b6b7bSRafael J. Wysockimay be necessary to rely on the platform for setting up the wakeup functionality 1000c0b6b7bSRafael J. Wysockias appropriate. 1010c0b6b7bSRafael J. Wysocki 1020c0b6b7bSRafael J. WysockiS2RAM is supported if the :c:macro:`CONFIG_SUSPEND` kernel configuration option 1030c0b6b7bSRafael J. Wysockiis set and the support for it is registered by the platform with the core system 1040c0b6b7bSRafael J. Wysockisuspend subsystem. On ACPI-based systems it is mapped to the S3 system state 1050c0b6b7bSRafael J. Wysockidefined by ACPI. 1060c0b6b7bSRafael J. Wysocki 1070c0b6b7bSRafael J. Wysocki.. _hibernation: 1080c0b6b7bSRafael J. Wysocki 1090c0b6b7bSRafael J. WysockiHibernation 1100c0b6b7bSRafael J. Wysocki----------- 1110c0b6b7bSRafael J. Wysocki 1120c0b6b7bSRafael J. WysockiThis state (also referred to as Suspend-to-Disk or STD) offers the greatest 1130c0b6b7bSRafael J. Wysockienergy savings and can be used even in the absence of low-level platform support 1140c0b6b7bSRafael J. Wysockifor system suspend. However, it requires some low-level code for resuming the 1150c0b6b7bSRafael J. Wysockisystem to be present for the underlying CPU architecture. 1160c0b6b7bSRafael J. Wysocki 1170c0b6b7bSRafael J. WysockiHibernation is significantly different from any of the system suspend variants. 1180c0b6b7bSRafael J. WysockiIt takes three system state changes to put it into hibernation and two system 1190c0b6b7bSRafael J. Wysockistate changes to resume it. 1200c0b6b7bSRafael J. Wysocki 1210c0b6b7bSRafael J. WysockiFirst, when hibernation is triggered, the kernel stops all system activity and 1220c0b6b7bSRafael J. Wysockicreates a snapshot image of memory to be written into persistent storage. Next, 1230c0b6b7bSRafael J. Wysockithe system goes into a state in which the snapshot image can be saved, the image 1240c0b6b7bSRafael J. Wysockiis written out and finally the system goes into the target low-power state in 1250c0b6b7bSRafael J. Wysockiwhich power is cut from almost all of its hardware components, including memory, 1260c0b6b7bSRafael J. Wysockiexcept for a limited set of wakeup devices. 1270c0b6b7bSRafael J. Wysocki 1280c0b6b7bSRafael J. WysockiOnce the snapshot image has been written out, the system may either enter a 1290c0b6b7bSRafael J. Wysockispecial low-power state (like ACPI S4), or it may simply power down itself. 1300c0b6b7bSRafael J. WysockiPowering down means minimum power draw and it allows this mechanism to work on 1310c0b6b7bSRafael J. Wysockiany system. However, entering a special low-power state may allow additional 1320c0b6b7bSRafael J. Wysockimeans of system wakeup to be used (e.g. pressing a key on the keyboard or 1330c0b6b7bSRafael J. Wysockiopening a laptop lid). 1340c0b6b7bSRafael J. Wysocki 1350c0b6b7bSRafael J. WysockiAfter wakeup, control goes to the platform firmware that runs a boot loader 1360c0b6b7bSRafael J. Wysockiwhich boots a fresh instance of the kernel (control may also go directly to 1370c0b6b7bSRafael J. Wysockithe boot loader, depending on the system configuration, but anyway it causes 1380c0b6b7bSRafael J. Wysockia fresh instance of the kernel to be booted). That new instance of the kernel 1390c0b6b7bSRafael J. Wysocki(referred to as the ``restore kernel``) looks for a hibernation image in 1400c0b6b7bSRafael J. Wysockipersistent storage and if one is found, it is loaded into memory. Next, all 1410c0b6b7bSRafael J. Wysockiactivity in the system is stopped and the restore kernel overwrites itself with 1420c0b6b7bSRafael J. Wysockithe image contents and jumps into a special trampoline area in the original 1430c0b6b7bSRafael J. Wysockikernel stored in the image (referred to as the ``image kernel``), which is where 1440c0b6b7bSRafael J. Wysockithe special architecture-specific low-level code is needed. Finally, the 1450c0b6b7bSRafael J. Wysockiimage kernel restores the system to the pre-hibernation state and allows user 1460c0b6b7bSRafael J. Wysockispace to run again. 1470c0b6b7bSRafael J. Wysocki 1480c0b6b7bSRafael J. WysockiHibernation is supported if the :c:macro:`CONFIG_HIBERNATION` kernel 1490c0b6b7bSRafael J. Wysockiconfiguration option is set. However, this option can only be set if support 1500c0b6b7bSRafael J. Wysockifor the given CPU architecture includes the low-level code for system resume. 1510c0b6b7bSRafael J. Wysocki 1520c0b6b7bSRafael J. Wysocki 1530c0b6b7bSRafael J. WysockiBasic ``sysfs`` Interfaces for System Suspend and Hibernation 1540c0b6b7bSRafael J. Wysocki============================================================= 1550c0b6b7bSRafael J. Wysocki 156c21502efSRafael J. WysockiThe power management subsystem provides userspace with a unified ``sysfs`` 157c21502efSRafael J. Wysockiinterface for system sleep regardless of the underlying system architecture or 158c21502efSRafael J. Wysockiplatform. That interface is located in the :file:`/sys/power/` directory 159c21502efSRafael J. Wysocki(assuming that ``sysfs`` is mounted at :file:`/sys`) and it consists of the 160c21502efSRafael J. Wysockifollowing attributes (files): 1610c0b6b7bSRafael J. Wysocki 1620c0b6b7bSRafael J. Wysocki``state`` 1630c0b6b7bSRafael J. Wysocki This file contains a list of strings representing sleep states supported 1640c0b6b7bSRafael J. Wysocki by the kernel. Writing one of these strings into it causes the kernel 1650c0b6b7bSRafael J. Wysocki to start a transition of the system into the sleep state represented by 1660c0b6b7bSRafael J. Wysocki that string. 1670c0b6b7bSRafael J. Wysocki 168c21502efSRafael J. Wysocki In particular, the "disk", "freeze" and "standby" strings represent the 1690c0b6b7bSRafael J. Wysocki :ref:`hibernation <hibernation>`, :ref:`suspend-to-idle <s2idle>` and 170c21502efSRafael J. Wysocki :ref:`standby <standby>` sleep states, respectively. The "mem" string 1710c0b6b7bSRafael J. Wysocki is interpreted in accordance with the contents of the ``mem_sleep`` file 1720c0b6b7bSRafael J. Wysocki described below. 1730c0b6b7bSRafael J. Wysocki 1740c0b6b7bSRafael J. Wysocki If the kernel does not support any system sleep states, this file is 1750c0b6b7bSRafael J. Wysocki not present. 1760c0b6b7bSRafael J. Wysocki 1770c0b6b7bSRafael J. Wysocki``mem_sleep`` 1780c0b6b7bSRafael J. Wysocki This file contains a list of strings representing supported system 1790c0b6b7bSRafael J. Wysocki suspend variants and allows user space to select the variant to be 1800c0b6b7bSRafael J. Wysocki associated with the "mem" string in the ``state`` file described above. 1810c0b6b7bSRafael J. Wysocki 1820c0b6b7bSRafael J. Wysocki The strings that may be present in this file are "s2idle", "shallow" 183c21502efSRafael J. Wysocki and "deep". The "s2idle" string always represents :ref:`suspend-to-idle 1840c0b6b7bSRafael J. Wysocki <s2idle>` and, by convention, "shallow" and "deep" represent 1850c0b6b7bSRafael J. Wysocki :ref:`standby <standby>` and :ref:`suspend-to-RAM <s2ram>`, 1860c0b6b7bSRafael J. Wysocki respectively. 1870c0b6b7bSRafael J. Wysocki 1880c0b6b7bSRafael J. Wysocki Writing one of the listed strings into this file causes the system 1890c0b6b7bSRafael J. Wysocki suspend variant represented by it to be associated with the "mem" string 1900c0b6b7bSRafael J. Wysocki in the ``state`` file. The string representing the suspend variant 191c21502efSRafael J. Wysocki currently associated with the "mem" string in the ``state`` file is 192c21502efSRafael J. Wysocki shown in square brackets. 1930c0b6b7bSRafael J. Wysocki 1940c0b6b7bSRafael J. Wysocki If the kernel does not support system suspend, this file is not present. 1950c0b6b7bSRafael J. Wysocki 1960c0b6b7bSRafael J. Wysocki``disk`` 197c21502efSRafael J. Wysocki This file controls the operating mode of hibernation (Suspend-to-Disk). 198c21502efSRafael J. Wysocki Specifically, it tells the kernel what to do after creating a 199c21502efSRafael J. Wysocki hibernation image. 200c21502efSRafael J. Wysocki 201c21502efSRafael J. Wysocki Reading from it returns a list of supported options encoded as: 2020c0b6b7bSRafael J. Wysocki 2030c0b6b7bSRafael J. Wysocki ``platform`` 2040c0b6b7bSRafael J. Wysocki Put the system into a special low-power state (e.g. ACPI S4) to 2050c0b6b7bSRafael J. Wysocki make additional wakeup options available and possibly allow the 2060c0b6b7bSRafael J. Wysocki platform firmware to take a simplified initialization path after 2070c0b6b7bSRafael J. Wysocki wakeup. 2080c0b6b7bSRafael J. Wysocki 209c21502efSRafael J. Wysocki It is only available if the platform provides a special 210c21502efSRafael J. Wysocki mechanism to put the system to sleep after creating a 211c21502efSRafael J. Wysocki hibernation image (platforms with ACPI do that as a rule, for 212c21502efSRafael J. Wysocki example). 213c21502efSRafael J. Wysocki 2140c0b6b7bSRafael J. Wysocki ``shutdown`` 2150c0b6b7bSRafael J. Wysocki Power off the system. 2160c0b6b7bSRafael J. Wysocki 2170c0b6b7bSRafael J. Wysocki ``reboot`` 2180c0b6b7bSRafael J. Wysocki Reboot the system (useful for diagnostics mostly). 2190c0b6b7bSRafael J. Wysocki 2200c0b6b7bSRafael J. Wysocki ``suspend`` 2210c0b6b7bSRafael J. Wysocki Hybrid system suspend. Put the system into the suspend sleep 2220c0b6b7bSRafael J. Wysocki state selected through the ``mem_sleep`` file described above. 2230c0b6b7bSRafael J. Wysocki If the system is successfully woken up from that state, discard 2240c0b6b7bSRafael J. Wysocki the hibernation image and continue. Otherwise, use the image 2250c0b6b7bSRafael J. Wysocki to restore the previous state of the system. 2260c0b6b7bSRafael J. Wysocki 227c21502efSRafael J. Wysocki It is available if system suspend is supported. 228c21502efSRafael J. Wysocki 2290c0b6b7bSRafael J. Wysocki ``test_resume`` 2300c0b6b7bSRafael J. Wysocki Diagnostic operation. Load the image as though the system had 2310c0b6b7bSRafael J. Wysocki just woken up from hibernation and the currently running kernel 2320c0b6b7bSRafael J. Wysocki instance was a restore kernel and follow up with full system 2330c0b6b7bSRafael J. Wysocki resume. 2340c0b6b7bSRafael J. Wysocki 235c21502efSRafael J. Wysocki Writing one of the strings listed above into this file causes the option 2360c0b6b7bSRafael J. Wysocki represented by it to be selected. 2370c0b6b7bSRafael J. Wysocki 238c21502efSRafael J. Wysocki The currently selected option is shown in square brackets, which means 2390c0b6b7bSRafael J. Wysocki that the operation represented by it will be carried out after creating 240c21502efSRafael J. Wysocki and saving the image when hibernation is triggered by writing ``disk`` 241c21502efSRafael J. Wysocki to :file:`/sys/power/state`. 2420c0b6b7bSRafael J. Wysocki 2430c0b6b7bSRafael J. Wysocki If the kernel does not support hibernation, this file is not present. 2440c0b6b7bSRafael J. Wysocki 245c21502efSRafael J. Wysocki``image_size`` 246c21502efSRafael J. Wysocki This file controls the size of hibernation images. 247c21502efSRafael J. Wysocki 248c21502efSRafael J. Wysocki It can be written a string representing a non-negative integer that will 249c21502efSRafael J. Wysocki be used as a best-effort upper limit of the image size, in bytes. The 250c21502efSRafael J. Wysocki hibernation core will do its best to ensure that the image size will not 251c21502efSRafael J. Wysocki exceed that number, but if that turns out to be impossible to achieve, a 252c21502efSRafael J. Wysocki hibernation image will still be created and its size will be as small as 253c21502efSRafael J. Wysocki possible. In particular, writing '0' to this file causes the size of 254c21502efSRafael J. Wysocki hibernation images to be minimum. 255c21502efSRafael J. Wysocki 256c21502efSRafael J. Wysocki Reading from it returns the current image size limit, which is set to 257c21502efSRafael J. Wysocki around 2/5 of the available RAM size by default. 258c21502efSRafael J. Wysocki 259c21502efSRafael J. Wysocki``pm_trace`` 260c21502efSRafael J. Wysocki This file controls the "PM trace" mechanism saving the last suspend 261c21502efSRafael J. Wysocki or resume event point in the RTC memory across reboots. It helps to 262c21502efSRafael J. Wysocki debug hard lockups or reboots due to device driver failures that occur 263c21502efSRafael J. Wysocki during system suspend or resume (which is more common) more effectively. 264c21502efSRafael J. Wysocki 265c21502efSRafael J. Wysocki If it contains "1", the fingerprint of each suspend/resume event point 266c21502efSRafael J. Wysocki in turn will be stored in the RTC memory (overwriting the actual RTC 267c21502efSRafael J. Wysocki information), so it will survive a system crash if one occurs right 268c21502efSRafael J. Wysocki after storing it and it can be used later to identify the driver that 269c21502efSRafael J. Wysocki caused the crash to happen. 270c21502efSRafael J. Wysocki 271c21502efSRafael J. Wysocki It contains "0" by default, which may be changed to "1" by writing a 272c21502efSRafael J. Wysocki string representing a nonzero integer into it. 273c21502efSRafael J. Wysocki 2740c0b6b7bSRafael J. WysockiAccording to the above, there are two ways to make the system go into the 2750c0b6b7bSRafael J. Wysocki:ref:`suspend-to-idle <s2idle>` state. The first one is to write "freeze" 2760c0b6b7bSRafael J. Wysockidirectly to :file:`/sys/power/state`. The second one is to write "s2idle" to 2770c0b6b7bSRafael J. Wysocki:file:`/sys/power/mem_sleep` and then to write "mem" to 2780c0b6b7bSRafael J. Wysocki:file:`/sys/power/state`. Likewise, there are two ways to make the system go 2790c0b6b7bSRafael J. Wysockiinto the :ref:`standby <standby>` state (the strings to write to the control 2800c0b6b7bSRafael J. Wysockifiles in that case are "standby" or "shallow" and "mem", respectively) if that 2810c0b6b7bSRafael J. Wysockistate is supported by the platform. However, there is only one way to make the 2820c0b6b7bSRafael J. Wysockisystem go into the :ref:`suspend-to-RAM <s2ram>` state (write "deep" into 2830c0b6b7bSRafael J. Wysocki:file:`/sys/power/mem_sleep` and "mem" into :file:`/sys/power/state`). 2840c0b6b7bSRafael J. Wysocki 2850c0b6b7bSRafael J. WysockiThe default suspend variant (ie. the one to be used without writing anything 2860c0b6b7bSRafael J. Wysockiinto :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems 2870c0b6b7bSRafael J. Wysockisupporting :ref:`suspend-to-RAM <s2ram>`) or "s2idle", but it can be overridden 288c21502efSRafael J. Wysockiby the value of the ``mem_sleep_default`` parameter in the kernel command line. 289c21502efSRafael J. WysockiOn some systems with ACPI, depending on the information in the ACPI tables, the 290c21502efSRafael J. Wysockidefault may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported in 291c21502efSRafael J. Wysockiprinciple. 292