Documentation: admin-guide: PM: Update sleep states documentation

Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

kernel os linux

There is some information in Documentation/power/interface.rst that
is still missing from Documentation/admin-guide/pm/sleep-states.rst
and really should be present in there, so update the latter by
adding that information to it and delete the former (as it becomes
redundant after that and it is somewhat outdated).

While at it, clean up some assorted pieces of sleep-states.rst a bit.

Signed-off-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

Rafael J. Wysocki 6 years ago c21502ef ffda81b6

+59 -96

2 changed files

expand all

Documentation

admin-guide

sleep-states.rst

power

interface.rst

+59 -17

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

··· 153 153 Basic ``sysfs`` Interfaces for System Suspend and Hibernation 154 154 ============================================================= 155 155 156 - The following files located in the :file:`/sys/power/` directory can be used by 157 - user space for sleep states control. 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): 158 161 159 162 ``state`` 160 163 This file contains a list of strings representing sleep states supported ··· 165 162 to start a transition of the system into the sleep state represented by 166 163 that string. 167 164 168 - In particular, the strings "disk", "freeze" and "standby" represent the 165 + In particular, the "disk", "freeze" and "standby" strings represent the 169 166 :ref:`hibernation <hibernation>`, :ref:`suspend-to-idle <s2idle>` and 170 - :ref:`standby <standby>` sleep states, respectively. The string "mem" 167 + :ref:`standby <standby>` sleep states, respectively. The "mem" string 171 168 is interpreted in accordance with the contents of the ``mem_sleep`` file 172 169 described below. 173 170 ··· 180 177 associated with the "mem" string in the ``state`` file described above. 181 178 182 179 The strings that may be present in this file are "s2idle", "shallow" 183 - and "deep". The string "s2idle" always represents :ref:`suspend-to-idle 180 + and "deep". The "s2idle" string always represents :ref:`suspend-to-idle 184 181 <s2idle>` and, by convention, "shallow" and "deep" represent 185 182 :ref:`standby <standby>` and :ref:`suspend-to-RAM <s2ram>`, 186 183 respectively. ··· 188 185 Writing one of the listed strings into this file causes the system 189 186 suspend variant represented by it to be associated with the "mem" string 190 187 in the ``state`` file. The string representing the suspend variant 191 - currently associated with the "mem" string in the ``state`` file 192 - is listed in square brackets. 188 + currently associated with the "mem" string in the ``state`` file is 189 + shown in square brackets. 193 190 194 191 If the kernel does not support system suspend, this file is not present. 195 192 196 193 ``disk`` 197 - This file contains a list of strings representing different operations 198 - that can be carried out after the hibernation image has been saved. The 199 - possible options are as follows: 194 + This file controls the operating mode of hibernation (Suspend-to-Disk). 195 + Specifically, it tells the kernel what to do after creating a 196 + hibernation image. 197 + 198 + Reading from it returns a list of supported options encoded as: 200 199 201 200 ``platform`` 202 201 Put the system into a special low-power state (e.g. ACPI S4) to 203 202 make additional wakeup options available and possibly allow the 204 203 platform firmware to take a simplified initialization path after 205 204 wakeup. 205 + 206 + It is only available if the platform provides a special 207 + mechanism to put the system to sleep after creating a 208 + hibernation image (platforms with ACPI do that as a rule, for 209 + example). 206 210 207 211 ``shutdown`` 208 212 Power off the system. ··· 224 214 the hibernation image and continue. Otherwise, use the image 225 215 to restore the previous state of the system. 226 216 217 + It is available if system suspend is supported. 218 + 227 219 ``test_resume`` 228 220 Diagnostic operation. Load the image as though the system had 229 221 just woken up from hibernation and the currently running kernel 230 222 instance was a restore kernel and follow up with full system 231 223 resume. 232 224 233 - Writing one of the listed strings into this file causes the option 225 + Writing one of the strings listed above into this file causes the option 234 226 represented by it to be selected. 235 227 236 - The currently selected option is shown in square brackets which means 228 + The currently selected option is shown in square brackets, which means 237 229 that the operation represented by it will be carried out after creating 238 - and saving the image next time hibernation is triggered by writing 239 - ``disk`` to :file:`/sys/power/state`. 230 + and saving the image when hibernation is triggered by writing ``disk`` 231 + to :file:`/sys/power/state`. 240 232 241 233 If the kernel does not support hibernation, this file is not present. 234 + 235 + ``image_size`` 236 + This file controls the size of hibernation images. 237 + 238 + It can be written a string representing a non-negative integer that will 239 + be used as a best-effort upper limit of the image size, in bytes. The 240 + hibernation core will do its best to ensure that the image size will not 241 + exceed that number, but if that turns out to be impossible to achieve, a 242 + hibernation image will still be created and its size will be as small as 243 + possible. In particular, writing '0' to this file causes the size of 244 + hibernation images to be minimum. 245 + 246 + Reading from it returns the current image size limit, which is set to 247 + around 2/5 of the available RAM size by default. 248 + 249 + ``pm_trace`` 250 + This file controls the "PM trace" mechanism saving the last suspend 251 + or resume event point in the RTC memory across reboots. It helps to 252 + debug hard lockups or reboots due to device driver failures that occur 253 + during system suspend or resume (which is more common) more effectively. 254 + 255 + If it contains "1", the fingerprint of each suspend/resume event point 256 + in turn will be stored in the RTC memory (overwriting the actual RTC 257 + information), so it will survive a system crash if one occurs right 258 + after storing it and it can be used later to identify the driver that 259 + caused the crash to happen. 260 + 261 + It contains "0" by default, which may be changed to "1" by writing a 262 + string representing a nonzero integer into it. 242 263 243 264 According to the above, there are two ways to make the system go into the 244 265 :ref:`suspend-to-idle <s2idle>` state. The first one is to write "freeze" ··· 285 244 The default suspend variant (ie. the one to be used without writing anything 286 245 into :file:`/sys/power/mem_sleep`) is either "deep" (on the majority of systems 287 246 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 ACPI-based systems, depending on the information in the ACPI tables, the 290 - default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported. 247 + by the value of the ``mem_sleep_default`` parameter in the kernel command line. 248 + On some systems with ACPI, depending on the information in the ACPI tables, the 249 + default may be "s2idle" even if :ref:`suspend-to-RAM <s2ram>` is supported in 250 + principle.

-79

Documentation/power/interface.rst

··· 1 - =========================================== 2 - Power Management Interface for System Sleep 3 - =========================================== 4 - 5 - Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com> 6 - 7 - The power management subsystem provides userspace with a unified sysfs interface 8 - for system sleep regardless of the underlying system architecture or platform. 9 - The interface is located in the /sys/power/ directory (assuming that sysfs is 10 - mounted at /sys). 11 - 12 - /sys/power/state is the system sleep state control file. 13 - 14 - Reading from it returns a list of supported sleep states, encoded as: 15 - 16 - - 'freeze' (Suspend-to-Idle) 17 - - 'standby' (Power-On Suspend) 18 - - 'mem' (Suspend-to-RAM) 19 - - 'disk' (Suspend-to-Disk) 20 - 21 - Suspend-to-Idle is always supported. Suspend-to-Disk is always supported 22 - too as long the kernel has been configured to support hibernation at all 23 - (ie. CONFIG_HIBERNATION is set in the kernel configuration file). Support 24 - for Suspend-to-RAM and Power-On Suspend depends on the capabilities of the 25 - platform. 26 - 27 - If one of the strings listed in /sys/power/state is written to it, the system 28 - will attempt to transition into the corresponding sleep state. Refer to 29 - Documentation/admin-guide/pm/sleep-states.rst for a description of each of 30 - those states. 31 - 32 - /sys/power/disk controls the operating mode of hibernation (Suspend-to-Disk). 33 - Specifically, it tells the kernel what to do after creating a hibernation image. 34 - 35 - Reading from it returns a list of supported options encoded as: 36 - 37 - - 'platform' (put the system into sleep using a platform-provided method) 38 - - 'shutdown' (shut the system down) 39 - - 'reboot' (reboot the system) 40 - - 'suspend' (trigger a Suspend-to-RAM transition) 41 - - 'test_resume' (resume-after-hibernation test mode) 42 - 43 - The currently selected option is printed in square brackets. 44 - 45 - The 'platform' option is only available if the platform provides a special 46 - mechanism to put the system to sleep after creating a hibernation image (ACPI 47 - does that, for example). The 'suspend' option is available if Suspend-to-RAM 48 - is supported. Refer to Documentation/power/basic-pm-debugging.rst for the 49 - description of the 'test_resume' option. 50 - 51 - To select an option, write the string representing it to /sys/power/disk. 52 - 53 - /sys/power/image_size controls the size of hibernation images. 54 - 55 - It can be written a string representing a non-negative integer that will be 56 - used as a best-effort upper limit of the image size, in bytes. The hibernation 57 - core will do its best to ensure that the image size will not exceed that number. 58 - However, if that turns out to be impossible to achieve, a hibernation image will 59 - still be created and its size will be as small as possible. In particular, 60 - writing '0' to this file will enforce hibernation images to be as small as 61 - possible. 62 - 63 - Reading from this file returns the current image size limit, which is set to 64 - around 2/5 of available RAM by default. 65 - 66 - /sys/power/pm_trace controls the PM trace mechanism saving the last suspend 67 - or resume event point in the RTC across reboots. 68 - 69 - It helps to debug hard lockups or reboots due to device driver failures that 70 - occur during system suspend or resume (which is more common) more effectively. 71 - 72 - If /sys/power/pm_trace contains '1', the fingerprint of each suspend/resume 73 - event point in turn will be stored in the RTC memory (overwriting the actual 74 - RTC information), so it will survive a system crash if one occurs right after 75 - storing it and it can be used later to identify the driver that caused the crash 76 - to happen (see Documentation/power/s2ram.rst for more information). 77 - 78 - Initially it contains '0' which may be changed to '1' by writing a string 79 - representing a nonzero integer into it.