[PATCH] swsusp: update userland interface documentation

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

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()

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:

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:

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