Suspend 2 merge: 25/51: Documentation

Nigel Cunningham
2004-11-24T13:24:46Z

Here is the kernel tree documentation. I have a word document that I'm
also working on, which will provide detail not given here, including an
explanation of the API for people who want to write new extensions.

diff -ruN 810-documentation-old/Documentation/kernel-parameters.txt 810-documentation-new/Documentation/kernel-parameters.txt
--- 810-documentation-old/Documentation/kernel-parameters.txt 2004-11-03 21:55:04.000000000 +1100
+++ 810-documentation-new/Documentation/kernel-parameters.txt 2004-11-04 16:27:40.000000000 +1100
@@ -804,6 +804,8 @@

noresume [SWSUSP] Disables resume and restore original swap space.

+ noresume2 [SWSUSP2] Disables resuming and restores original swap signature.
+
no-scroll [VGA] Disables scrollback.
This is required for the Braillex ib80-piezo Braille
reader made by F.H. Papenmeier (Germany).
@@ -1011,7 +1013,12 @@

reserve= [KNL,BUGS] Force the kernel to ignore some iomem area

- resume= [SWSUSP] Specify the partition device for software suspension
+ resume= [SWSUSP] Specify the partition device for software suspension.
+
+ resume2= [SWSUSP2] Specify the storage device for software suspend.
+ Format: <writer>:<writer-parameters>.
+ See Documentation/power/swsusp2.txt for details of the formats
+ for available image writers.

rhash_entries= [KNL,NET]
Set number of hash buckets for route cache
diff -ruN 810-documentation-old/Documentation/power/suspend2.txt 810-documentation-new/Documentation/power/suspend2.txt
--- 810-documentation-old/Documentation/power/suspend2.txt 1970-01-01 10:00:00.000000000 +1000
+++ 810-documentation-new/Documentation/power/suspend2.txt 2004-11-04 16:27:40.000000000 +1100
@@ -0,0 +1,506 @@
+ --- Software Suspend for Linux, version 2.0 ---
+
+1. What is it?
+2. Why would you want it?
+3. What do you need to use it?
+4. How do you use it?
+5. What do all those entries in /proc/software_suspend do?
+6. How do you get support?
+7. I think I've found a bug. What should I do?
+8. When will XXX be supported?
+9. How does it work?
+10. Who wrote Software Suspend?
+
+1. What is it?
+
+ Imagine you're sitting at your computer, working away. For some reason, you
+ need to turn off your computer for a while - perhaps it's time to go home
+ for the day. When you come back to your computer next, you're going to want
+ to carry on where you left off. Now imagine that you could push a button and
+ have your computer store the contents of its memory to disk and power down.
+ Then, when you next start up your computer, it loads that image back into
+ memory and you can carry on from where you were, just as if you'd never
+ turned the computer off. Far less time to start up, no reopening
+ applications and finding what directory you put that file in yesterday.
+ That's what Software Suspend does.
+
+2. Why would you want it?
+
+ Why wouldn't you want it?
+
+ Being able to save the state of your system and quickly restore it improves
+ your productivity - you get a useful system in far less time than through
+ the normal boot process.
+
+3. What do you need to use it?
+
+ a. Kernel Support.
+
+ Software Suspend is part of the Linux Kernel. This version is not part of Linus's
+ 2.6 tree at the moment, so you will need to download the kernel source and
+ apply the latest patch. Having done that, enable the appropriate options in
+ make [menu|x]config (under General Setup), compile and install your kernel.
+ Software Suspend works with SMP, Highmem, preemption, x86-32, PPC and mac.
+ x86-64 support is coming.
+
+ Software Suspend patches are available from http://softwaresuspend.berlios.de.
+
+ You may also want to apply the optional patches. At the time of writing,
+ option patches are available to support Bootsplash (www.bootsplash.org, for
+ an even nicer display during suspend), Win4Lin. The Win4Lin option patch (only
+ needed for 2.4) provides support for Win4Lin.
+
+ Option patches should be applied after the main patch and after Win4Lin
+ or Bootsplash.
+
+ As of version 2.0.0.102, suspend can be built as modules. To use this
+ configuration, you need to have initrd support, because resuming needs
+ to occur before any filesystems that were mounted when you suspended
+ are remounted. For details on setting up suspend-as-modules, please
+ read the FAQs on suspend's web site.
+
+ b. Swapspace.
+
+ Software Suspend can store the suspend image in your swap partition,
+ a swap file or a combination thereof. Whichever combination you choose, you
+ will probably want to create enough swap space to store the largest image
+ you could have, plus the space you'd normally use for swap. A good rule of
+ thumb would be to calculate the amount of swap you'd want without using
+ Software Suspend, and then add the amount of memory you have. This swap
+ space can be arranged in any way you'd like. It can be in one partition or
+ file, or spread over a number. The only requirement is that they be active
+ when you start a suspend cycle.
+
+ There is one exception to this requirement. Software Suspend has
+ the ability to turn on one swap file or partition at the start of
+ suspending and turn it back off at the end. If you want to ensure you have
+ enough memory to store a image when your memory is fully used, you might
+ want to make one swap partition/file for 'normal' use, and another for
+ Software Suspend to activate & deactivate automatically. (Further details
+ below).
+
+ c. Bootloader configuration.
+
+ Using Software Suspend also requires that you add an extra parameter to
+ your lilo.conf or equivalent. Here's an example for a swap partition:
+
+ append="resume2=/dev/hda1"
+
+ This would tell Software Suspend that /dev/hda1 is a swap partition you
+ have. Software Suspend will use the swap signature of this partition as a
+ pointer to your data when you suspend. This means that (in this example)
+ /dev/hda1 doesn't need to be _the_ swap partition where all of your data
+ is actually stored. It just needs to be a swap partition that has a
+ valid signature.
+
+ You don't need to have a swap partition for this purpose. Software Suspend
+ can also use a swap file, but usage is a little more complex. Having made
+ your swap file, turn it on and do
+
+ cat /proc/software_suspend/header_locations
+
+ (this assumes you've already compiled your kernel with Software Suspend
+ support and booted it). The results of the cat command will tell you
+ what you need to put in lilo.conf:
+
+ For swap partitions like /dev/hda1, simply use resume2=/dev/hda1.
+ For swapfile `swapfile`, use resume2=/dev/hda2:0x242d@4096.
+
+ If the swapfile changes for any reason (it is moved to a different
+ location, it is deleted and recreated, or the filesystem is
+ defragmented) then you will have to check
+ /proc/software_suspend/header_locations for a new resume_block value.
+
+ Once you've compiled and installed the kernel, adjusted your lilo.conf
+ and rerun lilo, you should only need to reboot for the most basic part
+ of Software Suspend to be ready.
+
+ d. A suspend script.
+
+ Since the driver model in 2.6 kernels is still being developed, you may need
+ to do more, however. Users of Software Suspend usually start the process
+ via a script which prepares for the suspend, tells the kernel to do its
+ stuff and then restore things afterwards. This script might involve:
+
+ - Switching to a text console and back if X doesn't like the video card
+ status on resume.
+ - Running /sbin/hwclock [--directisa] to update the clock on resume
+ - Un/reloading PCMCIA support since it doesn't play well with suspend.
+
+ Note that you might not be able to unload some drivers if there are
+ processes using them. You might have to kill off processes that hold
+ devices open. Hint: if your X server accesses an USB mouse, doing a
+ 'chvt' to a text console releases the device and you can unload the
+ module.
+
+ Check out the latest script (available on Berlios).
+
+4. How do you use it?
+
+ Once your script is properly set up, you should just be able to start it
+ and everything should go like clockwork. Of course things aren't always
+ that easy out of the box.
+
+ Check out (in the kernel source tree) include/linux/suspend-debug for
+ settings you can use to get detailed information about what suspend is doing.
+ /proc/sys/kernel/swsusp and the kernel parameters suspend_act, suspend_dbg
+ and suspend_lvl allow you to set the action and debugging parameters prior
+ to starting a suspend and/or at the lilo prompt before resuming. There is
+ also a nice little program that should be available from Berlios which
+ makes it easier to turn these debugging settings on and off. Note that to
+ get any debugging output, you need to enable it when compiling the kernel.
+
+ A neat feature of Software Suspend is that you can press Escape at any time
+ during suspending, and the process will be aborted.
+
+ Due to the way suspend works, this means you'll have your system back and
+ perfectly usable almost instantly. The only exception is when it's at
+ the very end of writing the image. Then it will need to reload a small
+ (usually 4-50MBs) portion first.
+
+ If you run into problems with resuming, adding the "noresume2" option to
+ the kernel command line will let you skip the resume step and
+ (hopefully) recover your system.
+
+5. What do all those entries in /proc/software_suspend do?
+
+ /proc/software_suspend is the directory which contains files you can use to
+ tune and configure Software Suspend to your liking. The exact contents of
+ the directory will depend upon the version of Software Suspend you're
+ running, the options you selected at compile time and which modules you have
+ inserted at the moment (where appropriate). In the following
+ descriptions, names in brackets refer to compile time options and modules
+ that control whether the file exists. (Note that they're all dependant upon
+ you having selected CONFIG_SOFTWARE_SUSPEND2 in the first place!)
+
+ Since the values of these settings can open potential security risks, they
+ are usually accessible only to the root user. You can, however, enable a
+ compile time option which makes all of these files world-accessible. This
+ should only be done if you trust everyone with shell access to this
+ computer!
+
+ - activate:
+
+ When anything is written to this file suspend will be activated and suspend
+ the system. The value is completely ignored. It is just the fact that you
+ write to the file that initiates the suspend.
+
+ When accessed from an initrd, the software instead checks whether it needs
+ to initiate a resume. If it doesn't, the echo returns almost immediately.
+ If a resume is needed, the echo never returns.
+
+ - async_io_limit: (module suspend_block_io)
+
+ This value is the limit on the number of pages Software Suspend will submit
+ for reading or writing at once. The ideal value depends upon the speed of
+ your hard disks, but the default (and maximum) of 256 should be fine.
+
+ - debug_info:
+
+ This file returns information about your configuration that may be helpful
+ in diagnosing problems with suspending.
+
+ - debug_sections (CONFIG_SOFTWARE_SUSPEND_DEBUG, module suspend_core):
+
+ This value, together with the console log level, controls what debugging
+ information is displayed. The console log level determines the level of
+ detail, and this value determines what detail is displayed. This value is
+ a bit vector, and the meaning of the bits can be found in the kernel tree
+ in include/linux/suspend-debug.h. It can be over-ridden using the kernel's
+ command line option suspend_dbg.
+
+ - default_console_level (CONFIG_SOFTWARE_SUSPEND_DEBUG, module suspend_core):
+
+ This determines the value of the console log level at the start of a
+ suspend cycle. If debugging is compiled in, the console log level can be
+ changed during a cycle by pressing the digit keys. Meanings are:
+
+ 0: Nice display.
+ 1: Nice display plus numerical progress.
+ 2: Errors only.
+ 3: Low level debugging info.
+ 4: Medium level debugging info.
+ 5: High level debugging info.
+ 6: Verbose debugging info.
+
+ This value can be over-ridden using the kernel command line option
+ suspend_lvl.
+
+ - disable_gzip_compression (CONFIG_SOFTWARE_SUSPEND_GZIP_COMPRESSION,
+ module suspend_gzip):
+
+ If gzip compression support is compiled in, this option can be used to
+ disable this plugin.
+
+ - disable_lzf_compression (CONFIG_SOFTWARE_SUSPEND_LZF_COMPRESSION,
+ modules suspend_lzf):
+
+ If lzf compression support is compiled in, this option can be used to
+ disable this plugin.
+
+ - enable_escape (module suspend_core):
+
+ Setting this to "1" will enable you abort a suspend by
+ pressing escape, "0" (default) disables this feature. Note that enabling
+ this option means that you cannot initiate a suspend and then walk away
+ from your computer, expecting it to be secure. With feature disabled,
+ you can validly have this expectation once Suspend begins to write the
+ image to disk. (Prior to this point, it is possible that Suspend might
+ about because of failure to freeze all processes or because constraints
+ on its ability to save the image are not met).
+
+ - expected_gzip_compression (CONFIG_SOFTWARE_SUSPEND_GZIP_COMPRESSION,
+ module suspend_gzip):
+ - expected_lzf_compression (CONFIG_SOFTWARE_SUSPEND_LZF_COMPRESSION,
+ module suspend_lzf):
+
+ These values allow you to set an expected compression ratio, which Software
+ Suspend will use in calculating whether it meets constraints on the image
+ size. If this expected compression ratio is not attained, the suspend will
+ abort, so it is wise to allow some spare. You can see what compression
+ ratio is achieved in the logs after suspending.
+
+ Note that the values are cumulative. If you compile in both gzip and lzf
+ compression, have both enabled, and set both expected compression ratios
+ to 20, Suspend will expect that the storage required will be at most
+ .8 * .8 = 64% of the number of pages to be written.
+
+ - header_locations:
+
+ This option tells you the resume= options to use for swap devices you
+ currently have activated. It is particularly useful when you only want to
+ use a swap file to store your image. See above for further details.
+
+ - image_size_limit:
+
+ The maximum size of suspend image written to disk, measured in megabytes
+ (1024*1024).
+
+ - interface_version:
+
+ The value returned by this file can be used by scripts and configuration
+ tools to determine what entries should be looked for. The value is
+ incremented whenever an entry in /proc/software_suspend is obsoleted or
+ added.
+
+ - last_result:
+
+ The result of the last suspend, as defined in
+ include/linux/suspend-debug.h with the values SUSPEND_ABORTED to
+ SUSPEND_KEPT_IMAGE. This is a bitmask.
+
+ - log_everything (CONFIG_SOFTWARE_SUSPEND_DEBUG):
+
+ Setting this option results in all messages printed being logged. Normally,
+ only a subset are logged, so as to not slow the process and not clutter the
+ logs. Useful for debugging. It can be toggled during a cycle by pressing
+ 'L'.
+
+ - no_output:
+
+ Setting this to "1" disables all output from suspend. It may be useful if a
+ distribution wants to implement a static display while suspending.
+
+ - pause_between_steps (CONFIG_SOFTWARE_SUSPEND_DEBUG):
+
+ This option is used during debugging, to make Software Suspend pause between
+ each step of the process. It is ignored when the nice display is on.
+
+ - progressbar_granularity_limit (CONFIG_FBCON_SPLASHSCREEN):
+
+ This option can be used to limit the granularity of the progress bar
+ displayed with a bootsplash screen. The value is the maximum number of
+ steps. That is, 10 will make the progress bar jump in 10% increments.
+
+ - reboot (CONFIG_SOFTWARE_SUSPEND_DEBUG):
+
+ This option causes Software Suspend to reboot rather than powering down
+ at the end of saving an image. It can be toggled during a cycle by pressing
+ 'R'.
+
+ - slow:
+
+ This option inserts a couple of one+ second delays in the code. It should
+ not be needed, and may disappear in a future version.
+
+ - swapfile:
+
+ This entry is used to specify the swapfile or partition that
+ Software Suspend will attempt to swapon/swapoff automatically. Thus, if
+ I normally use /dev/hda1 for swap, and want to use /dev/hda2 for specifically
+ for my suspend image, I would
+
+ echo /dev/hda2 > /proc/software_suspend/swapfile
+
+ /dev/hda2 would then be automatically swapon'd and swapoff'd. Note that the
+ swapon and swapoff occur while other processes are frozen (including kswapd)
+ so this swap file will not be used up when attempting to free memory. The
+ parition/file is also given the highest priority, so other swapfiles/partitions
+ will only be used to save the image when this one is filled.
+
+ The value of this file is used by header_locations along with any currently
+ activated swapfiles/partitions.
+
+ - version:
+
+ The version of suspend you have compiled into the currently running kernel.
+
+6. How do you get support?
+
+ Glad you asked. Software Suspend is being actively maintained and supported,
+ both by Nigel (the guy doing most of the coding at the moment) and its
+ users. You can find the mailing list via the Sourceforge project page.
+
+7. I think I've found a bug. What should I do?
+
+ If you're seeing Software Suspend hang at some point, and especially if
+ lights are flashing on your keyboard, you should compile in debugging
+ support and try...
+
+ echo 1 > /proc/software_suspend/debug_sections
+ echo 3 > /proc/software_suspend/default_console_level
+ echo > /proc/software_suspend/activate
+
+ You should then see low level debugging information and eventually an
+ oops.
+
+ Good information on how to provide us with useful information from an
+ oops is found in the file REPORTING-BUGS, in the top level directory
+ of the kernel tree. If you get an oops, please especially note the
+ information about running what is printed on the screen through ksymoops.
+ The raw information is useless.
+
+ You might also read the FAQ and HOWTO on the web site for known issues,
+ and subscribe to the mailing list.
+
+ Beginning with 1.1rc10, you should include the contents of
+ /proc/software_suspend/debug_info in your report. Prior to this version,
+ similar information is written to /var/log/messages at the end of a
+ successful resume and should be sent. It is also a good idea to check
+ /var/log/messages for relevant information as well. Information from the
+ unloading and reloading of drivers and modules prior to and after
+ suspending is sometimes helpful.
+
+8. When will XXX be supported?
+
+ Software Suspend currently lacks support for x86-64..
+
+ Patches for the other items (and anything that's been missed) are welcome.
+ Please send to the list.
+
+ Because Nigel's main task is definitely not Software Suspend and he doesn't
+ have the hardware, he will be unlikely to develop support for any of these
+ in the near future. His development work to date has been driven by the
+ desire to be a user of a more feature complete Software Suspend.
+
+9. How does it work?
+
+ Software Suspend does its work in a number of steps.
+
+ a. Freezing system activity.
+
+ The first main stage in suspending is to stop all other activity. This is
+ achieved in stages. First, we stop tasks from submitting new I/O using hooks
+ in the system calls for reading, writing and at a number of other places as
+ well as at the kernel threads that start I/O. If any tasks are syncing,
+ we wait for them to complete. We then do our own sync, just in case no
+ syncs were running. Next, we stop all the others tasks. Some are signalled
+ and put in a 'refrigerator'. Others are simply not scheduled again until we
+ decide to wake them up.
+
+ b. Eating memory.
+
+ For a successful suspend, you need to have enough disk space to store the
+ image and enough memory for the various limitations of Software Suspend's
+ algorithm. You can also specify a maximum image size. In order to attain
+ to those constraints, Software Suspend may 'eat' memory. If, after freezing
+ processes, the constraints aren't met, Software Suspend will thaw all the
+ other processes and begin to eat memory until its calculations indicate
+ the constraints are met. It will then freeze processes again and recheck
+ its calculations.
+
+ c. Suspending drivers and storing processor context.
+
+ Software Suspend then calls the power management functions to notify
+ drivers of the suspend, and saves the processor state.
+
+ d. Storage of meta data and image.
+
+ Next, Software Suspend allocates the swap pages that will be used to save
+ the image and stores their locations, along with the locations of the pages
+ to be saved in what we call pagesets or pagedirs. Software Suspend stores
+ data in two pagesets. Pageset 2 contains pages on the active and inactive
+ lists; essentially the page cache. Pageset 1 contains all other pages,
+ including the kernel. We use two pagesets for one important reason: We
+ need to make an atomic copy of the kernel to ensure consistency of the
+ image. Without a second pagedir, that would limit us to an image that was
+ at most half the amount of memory available. Using two pagesets allows us
+ to store a full image. Since pageset 2 pages won't be needed in saving
+ pageset 1, we first save pageset 2 pages. We can then make our atomic copy
+ of the remaining pages using both pageset 2 pages and any other pages that
+ are free. While saving both pagesets, we are careful not to corrupt the
+ image. We immediately shoot down pages that are added to the page cache,
+ and we allocate a special memory pool of extra pages that can be used by
+ during suspending. All of the pages in this pool are saved along with the
+ rest of the pageset 1 pages, even if they're not used. This saves us having
+ to worry about the image becoming inconsistent while we're saving it.
+
+ e. Save a second copy of the pagedirs.
+
+ To reload pagedir 1 at resume time, we need to know where the data is
+ stored. This requires the saving of a second copy of the pagedirs.
+
+ f. Save the suspend header.
+
+ Nearly there! We save our settings and other parameters needed for
+ reloading pagedir 1 in a 'suspend header' this is a single swap page.
+
+ g. Set the swap header.
+
+ Finally, we edit the swap header for our resume= swap file/partition. The
+ swap signature is changed to record what kind of header it originally was
+ (swapspace 1 or 2) and the bdev and first block and block size details of
+ the suspend header.
+
+ h. Power down.
+
+ Or reboot if we're debugging and the appropriate option is selected.
+
+ Whew!
+
+ Reloading the image.
+ --------------------
+
+ Reloading the image is essentially the reverse of all the above. We load
+ our copy of pagedir 1, being careful to choose locations that aren't going
+ to be overwritten as we copy it back (We start very early in the boot
+ process, so there are no other processes to quiesce here). We then copy
+ pagedir 1 back to its original location in memory and restore the process
+ context. We are now running with the original kernel. Next, we reload the
+ pageset 2 pages, free the memory and swap used by Software Suspend, restore
+ the pagedir header and restart processes. Sounds easy in comparison to
+ suspending, doesn't it!
+
+ There is of course more to Software Suspend than this, but this explanation
+ should be a good start. If there's interest, I'll write further
+ documentation on range pages and the low level I/O.
+
+10. Who wrote Software Suspend?
+
+ (Answer based on the writings of Florent Chabaud, credits in files and
+ Nigel's limited knowledge; apologies to anyone missed out!)
+
+ The main developers of Software Suspend have been...
+
+ Gabor Kuti
+ Pavel Machek
+ Florent Chabaud
+ Nigel Cunningham
+
+ They have been aided in their efforts by a host of hundreds, if not thousands
+ of testers and people who have submitted bug fixes & suggestions. Of special
+ note are the efforts of Michael Frank, who had his computers repetitively
+ suspend and resume for literally tens of thousands of cycles and developed
+ scripts to stress the system and test Software Suspend far beyond the point
+ most of us (Nigel included!) would consider testing. His efforts have
+ contributed as much to Software Suspend as any of the names above.