[PATCH] swsusp: documentation updates
[linux-2.6.git] / 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(PF_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.