lkml.org 
[lkml]   [2004]   [Nov]   [24]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    SubjectSuspend 2 merge: 25/51: Documentation
    From
    Date
    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.

    -
    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: 2005-03-22 14:08    [W:4.113 / U:0.080 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site