Documentation/power/swsusp.txt

   1 From kernel/suspend.c:
   2
   3  * BIG FAT WARNING *********************************************************
   4  *
   5  * If you have unsupported (*) devices using DMA...
   6  *                              ...say goodbye to your data.
   7  *
   8  * If you touch anything on disk between suspend and resume...
   9  *                              ...kiss your data goodbye.
  10  *
  11  * If your disk driver does not support suspend... (IDE does)
  12  *                              ...you'd better find out how to get along
  13  *                                 without your data.
  14  *
  15  * If you change kernel command line between suspend and resume...
  16  *                              ...prepare for nasty fsck or worse.
  17  *
  18  * If you change your hardware while system is suspended...
  19  *                              ...well, it was not good idea.
  20  *
  21  * (*) suspend/resume support is needed to make it safe.
  22
  23 You need to append resume=/dev/your_swap_partition to kernel command
  24 line. Then you suspend by
  25
  26 echo shutdown > /sys/power/disk; echo disk > /sys/power/state
  27
  28 . If you feel ACPI works pretty well on your system, you might try
  29
  30 echo platform > /sys/power/disk; echo disk > /sys/power/state
  31
  32
  33
  34 Article about goals and implementation of Software Suspend for Linux
  35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  36 Author: G‚ábor Kuti
  37 Last revised: 2003-10-20 by Pavel Machek
  38
  39 Idea and goals to achieve
  40
  41 Nowadays it is common in several laptops that they have a suspend button. It
  42 saves the state of the machine to a filesystem or to a partition and switches
  43 to standby mode. Later resuming the machine the saved state is loaded back to
  44 ram and the machine can continue its work. It has two real benefits. First we
  45 save ourselves the time machine goes down and later boots up, energy costs
  46 are real high when running from batteries. The other gain is that we don't have to
  47 interrupt our programs so processes that are calculating something for a long
  48 time shouldn't need to be written interruptible.
  49
  50 swsusp saves the state of the machine into active swaps and then reboots or
  51 powerdowns.  You must explicitly specify the swap partition to resume from with
  52 ``resume='' kernel option. If signature is found it loads and restores saved
  53 state. If the option ``noresume'' is specified as a boot parameter, it skips
  54 the resuming.
  55
  56 In the meantime while the system is suspended you should not add/remove any
  57 of the hardware, write to the filesystems, etc.
  58
  59 Sleep states summary
  60 ====================
  61
  62 There are three different interfaces you can use, /proc/acpi should
  63 work like this:
  64
  65 In a really perfect world:
  66 echo 1 > /proc/acpi/sleep       # for standby
  67 echo 2 > /proc/acpi/sleep       # for suspend to ram
  68 echo 3 > /proc/acpi/sleep       # for suspend to ram, but with more power conservative
  69 echo 4 > /proc/acpi/sleep       # for suspend to disk
  70 echo 5 > /proc/acpi/sleep       # for shutdown unfriendly the system
  71
  72 and perhaps
  73 echo 4b > /proc/acpi/sleep      # for suspend to disk via s4bios
  74
  75 Frequently Asked Questions
  76 ==========================
  77
  78 Q: well, suspending a server is IMHO a really stupid thing,
  79 but... (Diego Zuccato):
  80
  81 A: You bought new UPS for your server. How do you install it without
  82 bringing machine down? Suspend to disk, rearrange power cables,
  83 resume.
  84
  85 You have your server on UPS. Power died, and UPS is indicating 30
  86 seconds to failure. What do you do? Suspend to disk.
  87
  88 Ethernet card in your server died. You want to replace it. Your
  89 server is not hotplug capable. What do you do? Suspend to disk,
  90 replace ethernet card, resume. If you are fast your users will not
  91 even see broken connections.
  92
  93
  94 Q: Maybe I'm missing something, but why don't the regular I/O paths work?
  95
  96 A: We do use the regular I/O paths. However we cannot restore the data
  97 to its original location as we load it. That would create an
  98 inconsistent kernel state which would certainly result in an oops.
  99 Instead, we load the image into unused memory and then atomically copy
 100 it back to it original location. This implies, of course, a maximum
 101 image size of half the amount of memory.
 102
 103 There are two solutions to this:
 104
 105 * require half of memory to be free during suspend. That way you can
 106 read "new" data onto free spots, then cli and copy
 107
 108 * assume we had special "polling" ide driver that only uses memory
 109 between 0-640KB. That way, I'd have to make sure that 0-640KB is free
 110 during suspending, but otherwise it would work...
 111
 112 suspend2 shares this fundamental limitation, but does not include user
 113 data and disk caches into "used memory" by saving them in
 114 advance. That means that the limitation goes away in practice.
 115
 116 Q: Does linux support ACPI S4?
 117
 118 A: Yes. That's what echo platform > /sys/power/disk does.
 119
 120 Q: My machine doesn't work with ACPI. How can I use swsusp than ?
 121
 122 A: Do a reboot() syscall with right parameters. Warning: glibc gets in
 123 its way, so check with strace:
 124
 125 reboot(LINUX_REBOOT_MAGIC1, LINUX_REBOOT_MAGIC2, 0xd000fce2)
 126
 127 (Thanks to Peter Osterlund:)
 128
 129 #include <unistd.h>
 130 #include <syscall.h>
 131
 132 #define LINUX_REBOOT_MAGIC1     0xfee1dead
 133 #define LINUX_REBOOT_MAGIC2     672274793
 134 #define LINUX_REBOOT_CMD_SW_SUSPEND     0xD000FCE2
 135
 136 int main()
 137 {
 138     syscall(SYS_reboot, LINUX_REBOOT_MAGIC1, LINUX_REBOOT_MAGIC2,
 139             LINUX_REBOOT_CMD_SW_SUSPEND, 0);
 140     return 0;
 141 }
 142
 143 Also /sys/ interface should be still present.
 144
 145 Q: What is 'suspend2'?
 146
 147 A: suspend2 is 'Software Suspend 2', a forked implementation of
 148 suspend-to-disk which is available as separate patches for 2.4 and 2.6
 149 kernels from swsusp.sourceforge.net. It includes support for SMP, 4GB
 150 highmem and preemption. It also has a extensible architecture that
 151 allows for arbitrary transformations on the image (compression,
 152 encryption) and arbitrary backends for writing the image (eg to swap
 153 or an NFS share[Work In Progress]). Questions regarding suspend2
 154 should be sent to the mailing list available through the suspend2
 155 website, and not to the Linux Kernel Mailing List. We are working
 156 toward merging suspend2 into the mainline kernel.
 157
 158 Q: A kernel thread must voluntarily freeze itself (call 'refrigerator').
 159 I found some kernel threads that don't do it, and they don't freeze
 160 so the system can't sleep. Is this a known behavior?
 161
 162 A: All such kernel threads need to be fixed, one by one. Select the
 163 place where the thread is safe to be frozen (no kernel semaphores
 164 should be held at that point and it must be safe to sleep there), and
 165 add:
 166
 167        try_to_freeze();
 168
 169 If the thread is needed for writing the image to storage, you should
 170 instead set the PF_NOFREEZE process flag when creating the thread (and
 171 be very carefull).
 172
 173
 174 Q: What is the difference between between "platform", "shutdown" and
 175 "firmware" in /sys/power/disk?
 176
 177 A:
 178
 179 shutdown: save state in linux, then tell bios to powerdown
 180
 181 platform: save state in linux, then tell bios to powerdown and blink
 182           "suspended led"
 183
 184 firmware: tell bios to save state itself [needs BIOS-specific suspend
 185           partition, and has very little to do with swsusp]
 186
 187 "platform" is actually right thing to do, but "shutdown" is most
 188 reliable.
 189
 190 Q: I do not understand why you have such strong objections to idea of
 191 selective suspend.
 192
 193 A: Do selective suspend during runtime power managment, that's okay. But
 194 its useless for suspend-to-disk. (And I do not see how you could use
 195 it for suspend-to-ram, I hope you do not want that).
 196
 197 Lets see, so you suggest to
 198
 199 * SUSPEND all but swap device and parents
 200 * Snapshot
 201 * Write image to disk
 202 * SUSPEND swap device and parents
 203 * Powerdown
 204
 205 Oh no, that does not work, if swap device or its parents uses DMA,
 206 you've corrupted data. You'd have to do
 207
 208 * SUSPEND all but swap device and parents
 209 * FREEZE swap device and parents
 210 * Snapshot
 211 * UNFREEZE swap device and parents
 212 * Write
 213 * SUSPEND swap device and parents
 214
 215 Which means that you still need that FREEZE state, and you get more
 216 complicated code. (And I have not yet introduce details like system
 217 devices).
 218
 219 Q: There don't seem to be any generally useful behavioral
 220 distinctions between SUSPEND and FREEZE.
 221
 222 A: Doing SUSPEND when you are asked to do FREEZE is always correct,
 223 but it may be unneccessarily slow. If you want USB to stay simple,
 224 slowness may not matter to you. It can always be fixed later.
 225
 226 For devices like disk it does matter, you do not want to spindown for
 227 FREEZE.
 228
 229 Q: After resuming, system is paging heavilly, leading to very bad interactivity.
 230
 231 A: Try running
 232
 233 cat `cat /proc/[0-9]*/maps | grep / | sed 's:.* /:/:' | sort -u` > /dev/null
 234
 235 after resume. swapoff -a; swapon -a may also be usefull.
 236
 237 Q: What happens to devices during swsusp? They seem to be resumed
 238 during system suspend?
 239
 240 A: That's correct. We need to resume them if we want to write image to
 241 disk. Whole sequence goes like
 242
 243       Suspend part
 244       ~~~~~~~~~~~~
 245       running system, user asks for suspend-to-disk
 246
 247       user processes are stopped
 248
 249       suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
 250                       with state snapshot
 251
 252       state snapshot: copy of whole used memory is taken with interrupts disabled
 253
 254       resume(): devices are woken up so that we can write image to swap
 255
 256       write image to swap
 257
 258       suspend(PMSG_SUSPEND): suspend devices so that we can power off
 259
 260       turn the power off
 261
 262       Resume part
 263       ~~~~~~~~~~~
 264       (is actually pretty similar)
 265
 266       running system, user asks for suspend-to-disk
 267
 268       user processes are stopped (in common case there are none, but with resume-from-initrd, noone knows)
 269
 270       read image from disk
 271
 272       suspend(PMSG_FREEZE): devices are frozen so that they don't interfere
 273                       with image restoration
 274
 275       image restoration: rewrite memory with image
 276
 277       resume(): devices are woken up so that system can continue
 278
 279       thaw all user processes
 280
 281 Q: What is this 'Encrypt suspend image' for?
 282
 283 A: First of all: it is not a replacement for dm-crypt encrypted swap.
 284 It cannot protect your computer while it is suspended. Instead it does
 285 protect from leaking sensitive data after resume from suspend.
 286
 287 Think of the following: you suspend while an application is running
 288 that keeps sensitive data in memory. The application itself prevents
 289 the data from being swapped out. Suspend, however, must write these
 290 data to swap to be able to resume later on. Without suspend encryption
 291 your sensitive data are then stored in plaintext on disk.  This means
 292 that after resume your sensitive data are accessible to all
 293 applications having direct access to the swap device which was used
 294 for suspend. If you don't need swap after resume these data can remain
 295 on disk virtually forever. Thus it can happen that your system gets
 296 broken in weeks later and sensitive data which you thought were
 297 encrypted and protected are retrieved and stolen from the swap device.
 298 To prevent this situation you should use 'Encrypt suspend image'.
 299
 300 During suspend a temporary key is created and this key is used to
 301 encrypt the data written to disk. When, during resume, the data was
 302 read back into memory the temporary key is destroyed which simply
 303 means that all data written to disk during suspend are then
 304 inaccessible so they can't be stolen later on.  The only thing that
 305 you must then take care of is that you call 'mkswap' for the swap
 306 partition used for suspend as early as possible during regular
 307 boot. This asserts that any temporary key from an oopsed suspend or
 308 from a failed or aborted resume is erased from the swap device.
 309
 310 As a rule of thumb use encrypted swap to protect your data while your
 311 system is shut down or suspended. Additionally use the encrypted
 312 suspend image to prevent sensitive data from being stolen after
 313 resume.