aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/power/userland-swsusp.txt
diff options
context:
space:
mode:
authorRafael J. Wysocki <rjw@sisk.pl>2006-12-06 23:34:16 -0500
committerLinus Torvalds <torvalds@woody.osdl.org>2006-12-07 11:39:27 -0500
commitbf73bae6ba0dc4bd4f1e570feb34a06b72725af6 (patch)
tree3d224f68d04b6c9e96ebf5903406ada9307824d9 /Documentation/power/userland-swsusp.txt
parent37b2ba12df88f0e29f2d52aaf1ab22789377d5b5 (diff)
[PATCH] swsusp: update userland interface documentation
The swsusp userland interface has recently changed for a couple of times, but the changes have not been documented. Fix this, and document the SNAPSHOT_SET_SWAP_AREA ioctl(). Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl> Acked-by: Pavel Machek <pavel@ucw.cz> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation/power/userland-swsusp.txt')
-rw-r--r--Documentation/power/userland-swsusp.txt64
1 files changed, 51 insertions, 13 deletions
diff --git a/Documentation/power/userland-swsusp.txt b/Documentation/power/userland-swsusp.txt
index 64755e9285db..000556c932e9 100644
--- a/Documentation/power/userland-swsusp.txt
+++ b/Documentation/power/userland-swsusp.txt
@@ -9,9 +9,8 @@ done it already.
9Now, to use the userland interface for software suspend you need special 9Now, to use the userland interface for software suspend you need special
10utilities that will read/write the system memory snapshot from/to the 10utilities that will read/write the system memory snapshot from/to the
11kernel. Such utilities are available, for example, from 11kernel. Such utilities are available, for example, from
12<http://www.sisk.pl/kernel/utilities/suspend>. You may want to have 12<http://suspend.sourceforge.net>. You may want to have a look at them if you
13a look at them if you are going to develop your own suspend/resume 13are going to develop your own suspend/resume utilities.
14utilities.
15 14
16The interface consists of a character device providing the open(), 15The interface consists of a character device providing the open(),
17release(), read(), and write() operations as well as several ioctl() 16release(), read(), and write() operations as well as several ioctl()
@@ -21,9 +20,9 @@ be read from /sys/class/misc/snapshot/dev.
21 20
22The device can be open either for reading or for writing. If open for 21The device can be open either for reading or for writing. If open for
23reading, it is considered to be in the suspend mode. Otherwise it is 22reading, it is considered to be in the suspend mode. Otherwise it is
24assumed to be in the resume mode. The device cannot be open for reading 23assumed to be in the resume mode. The device cannot be open for simultaneous
25and writing. It is also impossible to have the device open more than once 24reading and writing. It is also impossible to have the device open more than
26at a time. 25once at a time.
27 26
28The ioctl() commands recognized by the device are: 27The ioctl() commands recognized by the device are:
29 28
@@ -69,9 +68,46 @@ SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated with
69SNAPSHOT_SET_SWAP_FILE - set the resume partition (the last ioctl() argument 68SNAPSHOT_SET_SWAP_FILE - set the resume partition (the last ioctl() argument
70 should specify the device's major and minor numbers in the old 69 should specify the device's major and minor numbers in the old
71 two-byte format, as returned by the stat() function in the .st_rdev 70 two-byte format, as returned by the stat() function in the .st_rdev
72 member of the stat structure); it is recommended to always use this 71 member of the stat structure)
73 call, because the code to set the resume partition could be removed from 72
74 future kernels 73SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
74 units) from the beginning of the partition at which the swap header is
75 located (the last ioctl() argument should point to a struct
76 resume_swap_area, as defined in kernel/power/power.h, containing the
77 resume device specification, as for the SNAPSHOT_SET_SWAP_FILE ioctl(),
78 and the offset); for swap partitions the offset is always 0, but it is
79 different to zero for swap files (please see
80 Documentation/swsusp-and-swap-files.txt for details).
81 The SNAPSHOT_SET_SWAP_AREA ioctl() is considered as a replacement for
82 SNAPSHOT_SET_SWAP_FILE which is regarded as obsolete. It is
83 recommended to always use this call, because the code to set the resume
84 partition may be removed from future kernels
85
86SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
87 immediately enter the suspend-to-RAM state, so this call must always
88 be preceded by the SNAPSHOT_FREEZE call and it is also necessary
89 to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call
90 is needed to implement the suspend-to-both mechanism in which the
91 suspend image is first created, as though the system had been suspended
92 to disk, and then the system is suspended to RAM (this makes it possible
93 to resume the system from RAM if there's enough battery power or restore
94 its state on the basis of the saved suspend image otherwise)
95
96SNAPSHOT_PMOPS - enable the usage of the pmops->prepare, pmops->enter and
97 pmops->finish methods (the in-kernel swsusp knows these as the "platform
98 method") which are needed on many machines to (among others) speed up
99 the resume by letting the BIOS skip some steps or to let the system
100 recognise the correct state of the hardware after the resume (in
101 particular on many machines this ensures that unplugged AC
102 adapters get correctly detected and that kacpid does not run wild after
103 the resume). The last ioctl() argument can take one of the three
104 values, defined in kernel/power/power.h:
105 PMOPS_PREPARE - make the kernel carry out the
106 pm_ops->prepare(PM_SUSPEND_DISK) operation
107 PMOPS_ENTER - make the kernel power off the system by calling
108 pm_ops->enter(PM_SUSPEND_DISK)
109 PMOPS_FINISH - make the kernel carry out the
110 pm_ops->finish(PM_SUSPEND_DISK) operation
75 111
76The device's read() operation can be used to transfer the snapshot image from 112The device's read() operation can be used to transfer the snapshot image from
77the kernel. It has the following limitations: 113the kernel. It has the following limitations:
@@ -91,10 +127,12 @@ unfreeze user space processes frozen by SNAPSHOT_UNFREEZE if they are
91still frozen when the device is being closed). 127still frozen when the device is being closed).
92 128
93Currently it is assumed that the userland utilities reading/writing the 129Currently it is assumed that the userland utilities reading/writing the
94snapshot image from/to the kernel will use a swap partition, called the resume 130snapshot image from/to the kernel will use a swap parition, called the resume
95partition, as storage space. However, this is not really required, as they 131partition, or a swap file as storage space (if a swap file is used, the resume
96can use, for example, a special (blank) suspend partition or a file on a partition 132partition is the partition that holds this file). However, this is not really
97that is unmounted before SNAPSHOT_ATOMIC_SNAPSHOT and mounted afterwards. 133required, as they can use, for example, a special (blank) suspend partition or
134a file on a partition that is unmounted before SNAPSHOT_ATOMIC_SNAPSHOT and
135mounted afterwards.
98 136
99These utilities SHOULD NOT make any assumptions regarding the ordering of 137These utilities SHOULD NOT make any assumptions regarding the ordering of
100data within the snapshot image, except for the image header that MAY be 138data within the snapshot image, except for the image header that MAY be