Documentation/ABI/testing/sysfs-power

   1 What:           /sys/power/
   2 Date:           August 2006
   3 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
   4 Description:
   5                 The /sys/power directory will contain files that will
   6                 provide a unified interface to the power management
   7                 subsystem.
   8
   9 What:           /sys/power/state
  10 Date:           May 2014
  11 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
  12 Description:
  13                 The /sys/power/state file controls system sleep states.
  14                 Reading from this file returns the available sleep state
  15                 labels, which may be "mem", "standby", "freeze" and "disk"
  16                 (hibernation).  The meanings of the first three labels depend on
  17                 the relative_sleep_states command line argument as follows:
  18                  1) relative_sleep_states = 1
  19                     "mem", "standby", "freeze" represent non-hibernation sleep
  20                     states from the deepest ("mem", always present) to the
  21                     shallowest ("freeze").  "standby" and "freeze" may or may
  22                     not be present depending on the capabilities of the
  23                     platform.  "freeze" can only be present if "standby" is
  24                     present.
  25                  2) relative_sleep_states = 0 (default)
  26                     "mem" - "suspend-to-RAM", present if supported.
  27                     "standby" - "power-on suspend", present if supported.
  28                     "freeze" - "suspend-to-idle", always present.
  29
  30                 Writing to this file one of these strings causes the system to
  31                 transition into the corresponding state, if available.  See
  32                 Documentation/power/states.txt for a description of what
  33                 "suspend-to-RAM", "power-on suspend" and "suspend-to-idle" mean.
  34
  35 What:           /sys/power/disk
  36 Date:           September 2006
  37 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
  38 Description:
  39                 The /sys/power/disk file controls the operating mode of the
  40                 suspend-to-disk mechanism.  Reading from this file returns
  41                 the name of the method by which the system will be put to
  42                 sleep on the next suspend.  There are four methods supported:
  43                 'firmware' - means that the memory image will be saved to disk
  44                 by some firmware, in which case we also assume that the
  45                 firmware will handle the system suspend.
  46                 'platform' - the memory image will be saved by the kernel and
  47                 the system will be put to sleep by the platform driver (e.g.
  48                 ACPI or other PM registers).
  49                 'shutdown' - the memory image will be saved by the kernel and
  50                 the system will be powered off.
  51                 'reboot' - the memory image will be saved by the kernel and
  52                 the system will be rebooted.
  53
  54                 Additionally, /sys/power/disk can be used to turn on one of the
  55                 two testing modes of the suspend-to-disk mechanism: 'testproc'
  56                 or 'test'.  If the suspend-to-disk mechanism is in the
  57                 'testproc' mode, writing 'disk' to /sys/power/state will cause
  58                 the kernel to disable nonboot CPUs and freeze tasks, wait for 5
  59                 seconds, unfreeze tasks and enable nonboot CPUs.  If it is in
  60                 the 'test' mode, writing 'disk' to /sys/power/state will cause
  61                 the kernel to disable nonboot CPUs and freeze tasks, shrink
  62                 memory, suspend devices, wait for 5 seconds, resume devices,
  63                 unfreeze tasks and enable nonboot CPUs.  Then, we are able to
  64                 look in the log messages and work out, for example, which code
  65                 is being slow and which device drivers are misbehaving.
  66
  67                 The suspend-to-disk method may be chosen by writing to this
  68                 file one of the accepted strings:
  69
  70                 'firmware'
  71                 'platform'
  72                 'shutdown'
  73                 'reboot'
  74                 'testproc'
  75                 'test'
  76
  77                 It will only change to 'firmware' or 'platform' if the system
  78                 supports that.
  79
  80 What:           /sys/power/image_size
  81 Date:           August 2006
  82 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
  83 Description:
  84                 The /sys/power/image_size file controls the size of the image
  85                 created by the suspend-to-disk mechanism.  It can be written a
  86                 string representing a non-negative integer that will be used
  87                 as an upper limit of the image size, in bytes.  The kernel's
  88                 suspend-to-disk code will do its best to ensure the image size
  89                 will not exceed this number.  However, if it turns out to be
  90                 impossible, the kernel will try to suspend anyway using the
  91                 smallest image possible.  In particular, if "0" is written to
  92                 this file, the suspend image will be as small as possible.
  93
  94                 Reading from this file will display the current image size
  95                 limit, which is set to 500 MB by default.
  96
  97 What:           /sys/power/pm_trace
  98 Date:           August 2006
  99 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 100 Description:
 101                 The /sys/power/pm_trace file controls the code which saves the
 102                 last PM event point in the RTC across reboots, so that you can
 103                 debug a machine that just hangs during suspend (or more
 104                 commonly, during resume).  Namely, the RTC is only used to save
 105                 the last PM event point if this file contains '1'.  Initially
 106                 it contains '0' which may be changed to '1' by writing a
 107                 string representing a nonzero integer into it.
 108
 109                 To use this debugging feature you should attempt to suspend
 110                 the machine, then reboot it and run
 111
 112                 dmesg -s 1000000 | grep 'hash matches'
 113
 114                 If you do not get any matches (or they appear to be false
 115                 positives), it is possible that the last PM event point
 116                 referred to a device created by a loadable kernel module.  In
 117                 this case cat /sys/power/pm_trace_dev_match (see below) after
 118                 your system is started up and the kernel modules are loaded.
 119
 120                 CAUTION: Using it will cause your machine's real-time (CMOS)
 121                 clock to be set to a random invalid time after a resume.
 122
 123 What;           /sys/power/pm_trace_dev_match
 124 Date:           October 2010
 125 Contact:        James Hogan <james@albanarts.com>
 126 Description:
 127                 The /sys/power/pm_trace_dev_match file contains the name of the
 128                 device associated with the last PM event point saved in the RTC
 129                 across reboots when pm_trace has been used.  More precisely it
 130                 contains the list of current devices (including those
 131                 registered by loadable kernel modules since boot) which match
 132                 the device hash in the RTC at boot, with a newline after each
 133                 one.
 134
 135                 The advantage of this file over the hash matches printed to the
 136                 kernel log (see /sys/power/pm_trace), is that it includes
 137                 devices created after boot by loadable kernel modules.
 138
 139                 Due to the small hash size necessary to fit in the RTC, it is
 140                 possible that more than one device matches the hash, in which
 141                 case further investigation is required to determine which
 142                 device is causing the problem.  Note that genuine RTC clock
 143                 values (such as when pm_trace has not been used), can still
 144                 match a device and output it's name here.
 145
 146 What:           /sys/power/pm_async
 147 Date:           January 2009
 148 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 149 Description:
 150                 The /sys/power/pm_async file controls the switch allowing the
 151                 user space to enable or disable asynchronous suspend and resume
 152                 of devices.  If enabled, this feature will cause some device
 153                 drivers' suspend and resume callbacks to be executed in parallel
 154                 with each other and with the main suspend thread.  It is enabled
 155                 if this file contains "1", which is the default.  It may be
 156                 disabled by writing "0" to this file, in which case all devices
 157                 will be suspended and resumed synchronously.
 158
 159 What:           /sys/power/wakeup_count
 160 Date:           July 2010
 161 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 162 Description:
 163                 The /sys/power/wakeup_count file allows user space to put the
 164                 system into a sleep state while taking into account the
 165                 concurrent arrival of wakeup events.  Reading from it returns
 166                 the current number of registered wakeup events and it blocks if
 167                 some wakeup events are being processed at the time the file is
 168                 read from.  Writing to it will only succeed if the current
 169                 number of wakeup events is equal to the written value and, if
 170                 successful, will make the kernel abort a subsequent transition
 171                 to a sleep state if any wakeup events are reported after the
 172                 write has returned.
 173
 174 What:           /sys/power/reserved_size
 175 Date:           May 2011
 176 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 177 Description:
 178                 The /sys/power/reserved_size file allows user space to control
 179                 the amount of memory reserved for allocations made by device
 180                 drivers during the "device freeze" stage of hibernation.  It can
 181                 be written a string representing a non-negative integer that
 182                 will be used as the amount of memory to reserve for allocations
 183                 made by device drivers' "freeze" callbacks, in bytes.
 184
 185                 Reading from this file will display the current value, which is
 186                 set to 1 MB by default.
 187
 188 What:           /sys/power/autosleep
 189 Date:           April 2012
 190 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 191 Description:
 192                 The /sys/power/autosleep file can be written one of the strings
 193                 returned by reads from /sys/power/state.  If that happens, a
 194                 work item attempting to trigger a transition of the system to
 195                 the sleep state represented by that string is queued up.  This
 196                 attempt will only succeed if there are no active wakeup sources
 197                 in the system at that time.  After every execution, regardless
 198                 of whether or not the attempt to put the system to sleep has
 199                 succeeded, the work item requeues itself until user space
 200                 writes "off" to /sys/power/autosleep.
 201
 202                 Reading from this file causes the last string successfully
 203                 written to it to be returned.
 204
 205 What:           /sys/power/wake_lock
 206 Date:           February 2012
 207 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 208 Description:
 209                 The /sys/power/wake_lock file allows user space to create
 210                 wakeup source objects and activate them on demand (if one of
 211                 those wakeup sources is active, reads from the
 212                 /sys/power/wakeup_count file block or return false).  When a
 213                 string without white space is written to /sys/power/wake_lock,
 214                 it will be assumed to represent a wakeup source name.  If there
 215                 is a wakeup source object with that name, it will be activated
 216                 (unless active already).  Otherwise, a new wakeup source object
 217                 will be registered, assigned the given name and activated.
 218                 If a string written to /sys/power/wake_lock contains white
 219                 space, the part of the string preceding the white space will be
 220                 regarded as a wakeup source name and handled as descrived above.
 221                 The other part of the string will be regarded as a timeout (in
 222                 nanoseconds) such that the wakeup source will be automatically
 223                 deactivated after it has expired.  The timeout, if present, is
 224                 set regardless of the current state of the wakeup source object
 225                 in question.
 226
 227                 Reads from this file return a string consisting of the names of
 228                 wakeup sources created with the help of it that are active at
 229                 the moment, separated with spaces.
 230
 231
 232 What:           /sys/power/wake_unlock
 233 Date:           February 2012
 234 Contact:        Rafael J. Wysocki <rjw@rjwysocki.net>
 235 Description:
 236                 The /sys/power/wake_unlock file allows user space to deactivate
 237                 wakeup sources created with the help of /sys/power/wake_lock.
 238                 When a string is written to /sys/power/wake_unlock, it will be
 239                 assumed to represent the name of a wakeup source to deactivate.
 240                 If a wakeup source object of that name exists and is active at
 241                 the moment, it will be deactivated.
 242
 243                 Reads from this file return a string consisting of the names of
 244                 wakeup sources created with the help of /sys/power/wake_lock
 245                 that are inactive at the moment, separated with spaces.
 246
 247 What:           /sys/power/pm_print_times
 248 Date:           May 2012
 249 Contact:        Sameer Nanda <snanda@chromium.org>
 250 Description:
 251                 The /sys/power/pm_print_times file allows user space to
 252                 control whether the time taken by devices to suspend and
 253                 resume is printed.  These prints are useful for hunting down
 254                 devices that take too long to suspend or resume.
 255
 256                 Writing a "1" enables this printing while writing a "0"
 257                 disables it.  The default value is "0".  Reading from this file
 258                 will display the current value.
 259
 260 What:           /sys/power/pm_wakeup_irq
 261 Date:           April 2015
 262 Contact:        Alexandra Yates <alexandra.yates@linux.intel.org>
 263 Description:
 264                 The /sys/power/pm_wakeup_irq file reports to user space the IRQ
 265                 number of the first wakeup interrupt (that is, the first
 266                 interrupt from an IRQ line armed for system wakeup) seen by the
 267                 kernel during the most recent system suspend/resume cycle.
 268
 269                 This output is useful for system wakeup diagnostics of spurious
 270                 wakeup interrupts.