From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S262696AbUKXNYq (ORCPT ); Wed, 24 Nov 2004 08:24:46 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S262685AbUKXNWr (ORCPT ); Wed, 24 Nov 2004 08:22:47 -0500 Received: from pop5-1.us4.outblaze.com ([205.158.62.125]:59540 "HELO pop5-1.us4.outblaze.com") by vger.kernel.org with SMTP id S262657AbUKXNCv (ORCPT ); Wed, 24 Nov 2004 08:02:51 -0500 Subject: Suspend 2 merge: 25/51: Documentation From: Nigel Cunningham Reply-To: ncunningham@linuxmail.org To: Linux Kernel Mailing List In-Reply-To: <1101292194.5805.180.camel@desktop.cunninghams> References: <1101292194.5805.180.camel@desktop.cunninghams> Content-Type: text/plain Message-Id: <1101296512.5805.289.camel@desktop.cunninghams> Mime-Version: 1.0 X-Mailer: Ximian Evolution 1.4.6-1mdk Date: Wed, 24 Nov 2004 23:59:08 +1100 Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org X-Mailing-List: linux-kernel@vger.kernel.org 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: :. + 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.