lkml.org 
[lkml]   [2006]   [Jan]   [4]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[RFC/RFT][PATCH -mm 5/5] swsusp: userland interface documentation and config
    Date
     Documentation/power/userland-swsusp.txt |  120 ++++++++++++++++++++++++++++++++
    kernel/power/Kconfig | 74 +++++++++++++------
    kernel/power/Makefile | 6 +
    kernel/power/disk.c | 1
    kernel/power/power.h | 2
    kernel/power/swsusp.c | 2
    6 files changed, 179 insertions(+), 26 deletions(-)

    Index: linux-2.6.15-rc5-mm3/kernel/power/Kconfig
    ===================================================================
    --- linux-2.6.15-rc5-mm3.orig/kernel/power/Kconfig 2006-01-04 20:26:57.000000000 +0100
    +++ linux-2.6.15-rc5-mm3/kernel/power/Kconfig 2006-01-04 20:28:29.000000000 +0100
    @@ -42,27 +42,65 @@ config SOFTWARE_SUSPEND
    ---help---
    Enable the possibility of suspending the machine.
    It doesn't need APM.
    - You may suspend your machine by 'swsusp' or 'shutdown -z <time>'
    - (patch for sysvinit needed).

    - It creates an image which is saved in your active swap. Upon next
    - boot, pass the 'resume=/dev/swappartition' argument to the kernel to
    - have it detect the saved image, restore memory state from it, and
    - continue to run as before. If you do not want the previous state to
    - be reloaded, then use the 'noresume' kernel argument. However, note
    - that your partitions will be fsck'd and you must re-mkswap your swap
    - partitions. It does not work with swap files.
    +if SOFTWARE_SUSPEND

    - Right now you may boot without resuming and then later resume but
    +config USERLAND_SUSPEND
    + bool "User interface for software suspend"
    + depends on SOFTWARE_SUSPEND
    + default y
    + ---help---
    + Enable the interface allowing user space processes to handle the suspend
    + and resume of the system.
    +
    + If this interface is used for suspend, the kernel creates a snapshot of
    + the system memory that may be encrypted, compressed, etc. and has to be
    + written to a storage by a user space utility. On resume the image
    + is read, uncompressed, decrypted, etc. by a user space utility and
    + transferred to the kernel which restores the system memory state from
    + it.
    +
    + This is the recommended way of handling software suspend and the
    + future development will be focused on it, so if you enable software
    + suspend, you should say Y here.
    +
    + Of course special user space utilities are necessary to use it.
    +
    + For more information please read <file:Documentation/power/userland-swsusp.txt>.
    +
    +config SWAP_SUSPEND
    + bool "Legacy swap suspend"
    + depends on SOFTWARE_SUSPEND
    + default y
    + ---help---
    + Enable the built-in legacy swap suspend.
    +
    + It allows you to suspend the machine by 'echo disk > /sys/power/state'
    + or 'shutdown -z <time>' (patch for sysvinit needed).
    +
    + It creates an image which is saved in the swap partition specified
    + with the 'resume=/dev/swappartition' kernel command line argument.
    +
    + On the next boot, the 'resume=/dev/swappartition' command line argument
    + causes the kernel to look for the saved image, restore memory state from it,
    + and continue to run as before. If you do not want the previous state to
    + be reloaded, then use the 'noresume' kernel argument. However, note
    + that your partitions will be fsck'd and you must re-mkswap your resume
    + partition. It does not work with swap files.
    +
    + In principle you may boot without resuming and then later resume but
    in meantime you cannot use those swap partitions/files which were
    - involved in suspending. Also in this case there is a risk that buffers
    + involved in suspending. Also in this case there is a risk that buffers
    on disk won't match with saved ones.

    + You may want to say Y here if your distribution contains power management
    + utilities that assume this feature to be present.
    +
    For more information take a look at <file:Documentation/power/swsusp.txt>.

    config PM_STD_PARTITION
    string "Default resume partition"
    - depends on SOFTWARE_SUSPEND
    + depends on SWAP_SUSPEND
    default ""
    ---help---
    The default resume partition is the partition that the suspend-
    @@ -82,17 +120,7 @@ config PM_STD_PARTITION
    suspended image to. It will simply pick the first available swap
    device.

    -config SWSUSP_ENCRYPT
    - bool "Encrypt suspend image"
    - depends on SOFTWARE_SUSPEND && CRYPTO=y && (CRYPTO_AES=y || CRYPTO_AES_586=y || CRYPTO_AES_X86_64=y)
    - default ""
    - ---help---
    - To prevent data gathering from swap after resume you can encrypt
    - the suspend image with a temporary key that is deleted on
    - resume.
    -
    - Note that the temporary key is stored unencrypted on disk while the
    - system is suspended.
    +endif # SOFTWARE_SUSPEND

    config SUSPEND_SMP
    bool
    Index: linux-2.6.15-rc5-mm3/kernel/power/Makefile
    ===================================================================
    --- linux-2.6.15-rc5-mm3.orig/kernel/power/Makefile 2006-01-04 20:28:29.000000000 +0100
    +++ linux-2.6.15-rc5-mm3/kernel/power/Makefile 2006-01-04 20:28:29.000000000 +0100
    @@ -5,7 +5,11 @@ endif

    obj-y := main.o process.o console.o
    obj-$(CONFIG_PM_LEGACY) += pm.o
    -obj-$(CONFIG_SOFTWARE_SUSPEND) += swsusp.o disk.o snapshot.o user.o swap.o
    +obj-$(CONFIG_SOFTWARE_SUSPEND) += swsusp.o snapshot.o
    +
    +obj-$(CONFIG_USERLAND_SUSPEND) += user.o
    +
    +obj-$(CONFIG_SWAP_SUSPEND) += disk.o swap.o

    obj-$(CONFIG_SUSPEND_SMP) += smp.o

    Index: linux-2.6.15-rc5-mm3/kernel/power/disk.c
    ===================================================================
    --- linux-2.6.15-rc5-mm3.orig/kernel/power/disk.c 2006-01-04 20:26:57.000000000 +0100
    +++ linux-2.6.15-rc5-mm3/kernel/power/disk.c 2006-01-04 20:28:29.000000000 +0100
    @@ -35,7 +35,6 @@ extern int swsusp_resume(void);

    static int noresume = 0;
    char resume_file[256] = CONFIG_PM_STD_PARTITION;
    -dev_t swsusp_resume_device;

    /**
    * power_down - Shut machine down for hibernate.
    Index: linux-2.6.15-rc5-mm3/kernel/power/swsusp.c
    ===================================================================
    --- linux-2.6.15-rc5-mm3.orig/kernel/power/swsusp.c 2006-01-04 20:28:29.000000000 +0100
    +++ linux-2.6.15-rc5-mm3/kernel/power/swsusp.c 2006-01-04 20:28:29.000000000 +0100
    @@ -62,6 +62,8 @@ unsigned int image_size = 500;

    int in_suspend __nosavedata = 0;

    +dev_t swsusp_resume_device;
    +
    #ifdef CONFIG_HIGHMEM
    static unsigned int count_highmem_pages(void)
    {
    Index: linux-2.6.15-rc5-mm3/kernel/power/power.h
    ===================================================================
    --- linux-2.6.15-rc5-mm3.orig/kernel/power/power.h 2006-01-04 20:28:29.000000000 +0100
    +++ linux-2.6.15-rc5-mm3/kernel/power/power.h 2006-01-04 20:28:29.000000000 +0100
    @@ -20,7 +20,7 @@ struct swsusp_info {



    -#ifdef CONFIG_SOFTWARE_SUSPEND
    +#ifdef CONFIG_SWAP_SUSPEND
    extern int pm_suspend_disk(void);

    #else
    Index: linux-2.6.15-rc5-mm3/Documentation/power/userland-swsusp.txt
    ===================================================================
    --- /dev/null 1970-01-01 00:00:00.000000000 +0000
    +++ linux-2.6.15-rc5-mm3/Documentation/power/userland-swsusp.txt 2006-01-04 20:34:11.000000000 +0100
    @@ -0,0 +1,120 @@
    +Documentation for userland software suspend interface
    + (C) 2006 Rafael J. Wysocki <rjw@sisk.pl>
    +
    +First, the warnings at the beginning of swsusp.txt still apply.
    +
    +Second, you should read the FAQ in swsusp.txt _now_ if you have not
    +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.
    +
    +The interface consists of a character device providing the open(),
    +release(), read(), and write() operations as well as several ioctl()
    +commands defined in kernel/power/power.h.
    +
    +Currently the device's major number is allocated dynamically, so the
    +major:minor pair is exported via sysfs, as the /sys/power/snapshot attribute.
    +
    +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 imposiible to have the device open
    +more than once at a time.
    +
    +The ioctl() commands recognized by the device are:
    +
    +SNAPSHOT_IOCFREEZE - freeze user space processes (the current process is
    + not frozen); this is required for SNAPSHOT_IOCATOMIC_SNAPSHOT
    + and SNAPSHOT_IOCATOMIC_RESTORE to succeed
    +
    +SNAPSHOT_IOCUNFREEZE - thaw user space processes frozen by SNAPSHOT_IOCFREEZE
    +
    +SNAPSHOT_IOCATOMIC_SNAPSHOT - create a snapshot of the system memory; the
    + last argument of ioctl() should be a pointer to an int variable,
    + the value of which will indicate whether the call returned after
    + creating the snapshot (1) or after restoring the system memory state
    + from it (0) (after resume the system finds itself finishing the
    + SNAPSHOT_IOCATOMIC_SNAPSHOT ioctl() again); after the snapshot
    + has been created the read() operation can be used to transfer
    + it out of the kernel
    +
    +SNAPSHOT_IOCATOMIC_RESTORE - restore the system memory state from the
    + uploaded snapshot image; before calling it you should transfer
    + the systme memory snapshot back to the kernel using the write()
    + operation; this call will not succeed if the snapshot
    + image is not available to the kernel
    +
    +SNAPSHOT_IOCFREE - free memory allocated for the snapshot image
    +
    +SNAPSHOT_IOCSET_IMAGE_SIZE - set the preferred maximum size of the image
    + (the kernel will do its best to ensure the image size will not exceed
    + this number, but if it turns out to be impossible, the kernel will
    + create the smallest image possible)
    +
    +SNAPSHOT_IOCAVAIL_SWAP - check the amount of available swap (the last argument
    + should be a pointer to an unsigned int variable that will contain
    + the result if the call is successful)
    +
    +SNAPSHOT_IOCGET_SWAP_PAGE - allocate a swap page from the resume partition
    + (the last argument should be a pointer to an unsigned int variable that
    + will contain the swap page offset if the call is successful)
    +
    +SNAPSHOT_IOCFREE_SWAP_PAGES - free all swap pages allocated with
    + SNAPSHOT_IOCGET_SWAP_PAGE
    +
    +SNAPSHOT_IOCSET_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 other code the could have set the resume partition
    + need not be present in the kernel
    +
    +The device's read() operation can be used to transfer the snapshot image from
    +the kernel. It has the following limitations:
    +- you cannot read() more than one virtual memory page at a time
    +- read()s accross page boundaries are impossible (ie. if ypu read() 1/2 of
    + a page in the previous call, you will only be able to read()
    + _at_ _most_ 1/2 of the page in the next call)
    +
    +The device's write() operation is used for uploading the system memory snapshot
    +into the kernel. It has the same limitations as the read() operation.
    +
    +The release() operation frees all memory allocated for the snapshot image
    +and all swap pages allocated with SNAPSHOT_IOCGET_SWAP_PAGE (if any).
    +Thus it is not necessary to use either SNAPSHOT_IOCFREE or
    +SNAPSHOT_IOCFREE_SWAP_PAGES before closing the device (in fact it will also
    +unfreeze user space processes frozen by SNAPSHOT_IOCUNFREEZE 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 parition, 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_IOCATOMIC_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
    +assumed to start with an swsusp_info structure, as specified in
    +kernel/power/power.h. This structure MAY be used by the userland utilities
    +to obtain some information about the snapshot image, such as the total
    +number of the image pages, including the metadata and the header itself,
    +contained in the .pages member of swsusp_info.
    +
    +The snapshot image MUST be written to the kernel unaltered (ie. all of the image
    +data, metadata and header MUST be written in _exactly_ the same amount, form
    +and order in which they have been read). Otherwise, the behavior of the
    +resumed system may be totally unpredictable.
    +
    +While executing SNAPSHOT_IOCATOMIC_RESTORE the kernel checks if the
    +structure of the snapshot image is consistent with the information stored
    +in the image header. If any inconsistencies are detected,
    +SNAPSHOT_IOCATOMIC_RESTORE will not succeed. Still, this is not a fool-proof
    +mechanism and the userland utilities using the interface SHOULD use additional
    +means, such as checksums, to ensure the integrity of the snapshot image.
    +
    +For details, please refer to the source code.
    -
    To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
    the body of a message to majordomo@vger.kernel.org
    More majordomo info at http://vger.kernel.org/majordomo-info.html
    Please read the FAQ at http://www.tux.org/lkml/
    \
     
     \ /
      Last update: 2006-01-05 00:11    [W:2.844 / U:1.120 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site