OpenE2K/linux
6
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[PATCH] swsusp: update userland interface documentation

Browse Source 
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>
This commit is contained in:
Rafael J. Wysocki 2006-12-06 20:34:16 -08:00 committed by Linus Torvalds
parent 37b2ba12df
commit bf73bae6ba
2 changed files with 63 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Documentation/power/swsusp-and-swap-files.txt
View File

@ -38,15 +38,21 @@ resume=<swap_file_partition> resume_offset=<swap_file_offset>
where <swap_file_partition> is the partition on which the swap file is located
and <swap_file_offset> is the offset of the swap header determined by the
application in 2). [Of course, this step may be carried out automatically
application in 2) (of course, this step may be carried out automatically
by the same application that determies the swap file's header offset using the
FIBMAP ioctl.]
FIBMAP ioctl)
OR
Use a userland suspend application that will set the partition and offset
with the help of the SNAPSHOT_SET_SWAP_AREA ioctl described in
Documentation/power/userland-swsusp.txt (this is the only method to suspend
to a swap file allowing the resume to be initiated from an initrd or initramfs
image).
Now, swsusp will use the swap file in the same way in which it would use a swap
partition. [Of course this means that the resume from a swap file cannot be
initiated from whithin an initrd of initramfs image.] In particular, the
swap file has to be active (ie. be present in /proc/swaps) so that it can be
used for suspending.
partition. In particular, the swap file has to be active (ie. be present in
/proc/swaps) so that it can be used for suspending.
Note that if the swap file used for suspending is deleted and recreated,
the location of its header need not be the same as before. Thus every time

64
Documentation/power/userland-swsusp.txt
View File

@ -9,9 +9,8 @@ done it already.
Now, to use the userland interface for software suspend you need special
utilities that will read/write the system memory snapshot from/to the
kernel. Such utilities are available, for example, from
<http://www.sisk.pl/kernel/utilities/suspend>. You may want to have
a look at them if you are going to develop your own suspend/resume
utilities.
<http://suspend.sourceforge.net>. You may want to have a look at them if you
are going to develop your own suspend/resume utilities.
The interface consists of a character device providing the open(),
release(), read(), and write() operations as well as several ioctl()
@ -21,9 +20,9 @@ be read from /sys/class/misc/snapshot/dev.
The device can be open either for reading or for writing. If open for
reading, it is considered to be in the suspend mode. Otherwise it is
assumed to be in the resume mode. The device cannot be open for reading
and writing. It is also impossible to have the device open more than once
at a time.
assumed to be in the resume mode. The device cannot be open for simultaneous
reading and writing. It is also impossible to have the device open more than
once at a time.
The ioctl() commands recognized by the device are:
@ -69,9 +68,46 @@ SNAPSHOT_FREE_SWAP_PAGES - free all swap pages allocated with
SNAPSHOT_SET_SWAP_FILE - set the resume partition (the last ioctl() argument
should specify the device's major and minor numbers in the old
two-byte format, as returned by the stat() function in the .st_rdev
member of the stat structure); it is recommended to always use this
call, because the code to set the resume partition could be removed from
future kernels
member of the stat structure)
SNAPSHOT_SET_SWAP_AREA - set the resume partition and the offset (in <PAGE_SIZE>
units) from the beginning of the partition at which the swap header is
located (the last ioctl() argument should point to a struct
resume_swap_area, as defined in kernel/power/power.h, containing the
resume device specification, as for the SNAPSHOT_SET_SWAP_FILE ioctl(),
and the offset); for swap partitions the offset is always 0, but it is
different to zero for swap files (please see
Documentation/swsusp-and-swap-files.txt for details).
The SNAPSHOT_SET_SWAP_AREA ioctl() is considered as a replacement for
SNAPSHOT_SET_SWAP_FILE which is regarded as obsolete. It is
recommended to always use this call, because the code to set the resume
partition may be removed from future kernels
SNAPSHOT_S2RAM - suspend to RAM; using this call causes the kernel to
immediately enter the suspend-to-RAM state, so this call must always
be preceded by the SNAPSHOT_FREEZE call and it is also necessary
to use the SNAPSHOT_UNFREEZE call after the system wakes up. This call
is needed to implement the suspend-to-both mechanism in which the
suspend image is first created, as though the system had been suspended
to disk, and then the system is suspended to RAM (this makes it possible
to resume the system from RAM if there's enough battery power or restore
its state on the basis of the saved suspend image otherwise)
SNAPSHOT_PMOPS - enable the usage of the pmops->prepare, pmops->enter and
pmops->finish methods (the in-kernel swsusp knows these as the "platform
method") which are needed on many machines to (among others) speed up
the resume by letting the BIOS skip some steps or to let the system
recognise the correct state of the hardware after the resume (in
particular on many machines this ensures that unplugged AC
adapters get correctly detected and that kacpid does not run wild after
the resume). The last ioctl() argument can take one of the three
values, defined in kernel/power/power.h:
PMOPS_PREPARE - make the kernel carry out the
pm_ops->prepare(PM_SUSPEND_DISK) operation
PMOPS_ENTER - make the kernel power off the system by calling
pm_ops->enter(PM_SUSPEND_DISK)
PMOPS_FINISH - make the kernel carry out the
pm_ops->finish(PM_SUSPEND_DISK) operation
The device's read() operation can be used to transfer the snapshot image from
the kernel. It has the following limitations:
@ -91,10 +127,12 @@ unfreeze user space processes frozen by SNAPSHOT_UNFREEZE if they are
still frozen when the device is being closed).
Currently it is assumed that the userland utilities reading/writing the
snapshot image from/to the kernel will use a swap partition, called the resume
partition, as storage space. However, this is not really required, as they
can use, for example, a special (blank) suspend partition or a file on a partition
that is unmounted before SNAPSHOT_ATOMIC_SNAPSHOT and mounted afterwards.
snapshot image from/to the kernel will use a swap parition, called the resume
partition, or a swap file as storage space (if a swap file is used, the resume
partition is the partition that holds this file). However, this is not really
required, as they can use, for example, a special (blank) suspend partition or
a file on a partition that is unmounted before SNAPSHOT_ATOMIC_SNAPSHOT and
mounted afterwards.
These utilities SHOULD NOT make any assumptions regarding the ordering of
data within the snapshot image, except for the image header that MAY be