2. Overview

2.1 Kernel support

Kernel 2.2.X

Software Suspend was first developped by Gabor Kuti and he used to maintain a page for his patch which is mirrored here for historical reference only. A patch is available against 2.2.20 kernel named v7c. Since this patch is no longer maintained, this document will not provide much information on this version.

Kernel 2.4.x

Much of the development of hibernation support that has resulted in TuxOnIce was done on the 2.4 kernels, so historic patches can be found for that series. Patches for the 2.4 kernels are no longer maintained, however. All development is now focused on the 2.6 line.

Kernel 2.6.x

An early version of hibernation support was directly included in 2.5.18 the main development kernel tree, it was neglected for a long time, but then began to see further development in 2.6. In the meantime, Nigel Cunningham continued to work on the out-of-tree patch, adding many more features. This out-of-tree patch is what was known as Suspend2, and is now called TuxOnIce.

2.2 Requirements

TuxOnIce should run on any recent kernel. Like it's in-kernel sibling, it supports 32 and 64 bit kernels, single or multi-processor systems and both PC and PPC architectures.

You will also need to decide where you want to store your hibernation image. There are currently two choices - on a swap partition, with the swapwriter, or on a normal partition, with the filewriter.

Requirements for the swapwriter

The swapwriter supports writing your image to the available swap space on your machine. As a general rule, you should have as much spare swap space available as you have physical RAM (where spare swap does not include your typical swap usage). You can get away with a little less if you are using LZF compression - this usually attains around 30-50% compression, depending on the contents of RAM. If there isn't sufficient space, TuxOnIce will attempt to free caches until the image will fit, and if that isn't possible, it will abort gracefully.

Requirements for the filewriter

The filewriter can write your image to any file on your hard disk. The file must already be created, to the size that will be required (the hibernate script can do this for you). As for the size of the file, the same rules apply as for the swapwriter, however you do not need to take into account normal swap usage. The file must contain the string "TuxOnIce" at the beginning - the hibernate script will do this for you when you set the option "FilewriterLocation /suspend_file 1000" where the 1000 is the size (in megabytes) of the hibernation file to create. It will create the file the first time you hibernate (which takes a rather long time, so do not be alarmed).

The file can also be a block device such as /dev/hdaN, in which case the entire raw device is used. This is only recommended for people who know what they are doing. It must still contain the "TuxOnIce" signature string at the beginning of the device.

2.3 Compiling the kernel

Compiling a kernel is not too hard but may be a little daunting for those doing it for the first time - the Kernel-HOWTO is a good reference for doing so. Be sure to save your running kernel as something like /boot/vmlinuz.old and add an entry in your lilo.conf file or GRUB's menu.lst to be able to boot it.

You need to choose the kernel source tree you want to use as basis. The latest list of supported kernels is on the downloads page. You will need to download the tarball specific to your kernel version. Generally, the 2.6.X.Y kernels won't differ significantly from 2.6.X, so the same TuxOnIce patch can be used.

Before applying any patches, you should compile the original kernel and set all configuration options so that your computer works correctly. Save the configuration in /usr/src/myconfig or something like that. The installation instructions for a kernel, including LILO/GRUB setup, can be found on the Kernel-HOWTO.

2.4 Patching the kernel

Once you have succeeded in compiling your kernel, you can apply the TuxOnIce patches against your source tree. This is most easily done using a command along the lines of...

cd /usr/src/linux (the root directory of your tree)
bzcat /path/to/patch | patch -p1

If the kernel versions match, then no rejects or offsets should occur. If your kernel is not the vanilla one from kernel.org, you will have to apply these patches manually and edit some of the rejected hunks.

Load your previously saved configuration settings and make menuconfig (or equivalent) again. In the "Power management options" submenu, you will find a 'Hibernation' option' This is the generic, in kernel option. Since TuxOnIce shares code with it, this option needs to be enabled. Having selected this option, a new sub-option will appear: "Enhanced Hibernation (TuxOnIce)", with its own submenu. TuxOnIce can be built either directly into the kernel or as loadable modules. If the modular option is used, you will need to use an initrd or initramfs and ensure that it loads the modules and attempts to resume prior to mounting any device backed filesystems (ie hard disk filesystems). Instructions on doing this are below.

If the 'Hibernation' option isn't available, this is probably because you haven't selected CPU hotplugging on an SMP system. Although TuxOnIce can work without swap support, the generic option requires swap support, so this can also make the option disappear.

In the TuxOnIce submenu, you will need to select support for allocating storage from swapspace or a generic file. You will probably also want compression support (unless your harddrive is significantly faster than your processor(s)), and support for the userspace user interface ('userui' - nice interface).

Keep Image mode is primarily intended for kiosks. It allows you to use the same image again and again, and is therefore suited to configurations in which no writeable filesystems are mounted, or in which writeable filesystems are mounted post-resume and unmounted before powering down. (In this mode, after an image is stored, an attempt to hibernate results in a simple poweroff).

Replacing swsusp (the generic implementation) by default is a good idea if you previously had a working swsusp configuration, and just want to switch to TuxOnIce. After compiling and installing the new kernel, everything should 'just work'.

Cluster support is support for hibernating and resuming a number of networked computers in a synchronised fashion. At the time of writing (late November 2007), this support is incomplete.

Checksumming pageset 2: A TuxOnIce image is stored in two parts, and is not strictly an atomic copy. To ensure that we do get the equivalent of an atomic copy, you can enable checksumming of the first (and largest) part of the image. Checksums will be calculated prior to starting to save the pages in this image, and then again after stopping all other activity but prior to doing the atomic copy of remaining pages. If any pages have changed, they can be resaved in the atomic copy, or the cycle can be aborted. Most of the time, checksumming should not be needed. The debugging information available post-resume will tell you how many pages (if any) needed to be resaved.

Initrd/Initramfs's with TuxOnIce

Using an initrd/initramfs with TuxOnIce is possible, but you will have to trigger a resume yourself in your linuxrc/init. To do this, you MUST either modify your distro's initrd/ramfs generation routines or edit your linuxrc (or init) script yourself to contain the line

echo 1 > /sys/power/tuxonice/do_resume

Either way, this call must come BEFORE your initrd/ramfs mounts your filesystem. If the line is missing, your system will not resume. If the line comes after mounting file systems, you will most likely suffer from filesystem corruption. You have been warned.

This will work with most initrd setups produced by the various mkinitrd's. If you however use a kernel command-line containing something like

root=/dev/ram0 init=/linuxrc

You can now recompile your kernel with TuxOnIce...

2.5 Installing the new kernel

You must set the resume= kernel option to the swap partition or file location you want to use for hibernating. For swap storage, if your swap partition is, for instance, the third primary one on first ide disk (/dev/hda3) you have to append "resume=swap:/dev/hda3" as a kernel parameter in your lilo.conf file or GRUB's menu.lst.

Note that this value only determines which swap header used to indicate whether we have an image, and where it is. TuxOnIce can and will use any storage that is swapon'd at the time you start to hibernate. All of these devices need to be accessible when we come to resume. If you have encryped swap or are using the device mapper support, all of your swap needs to be configured prior to the echo > do_resume in your initrd/ramfs. It should not be swapon'd, and filesystems on which swap files are located must not be mounted, but the steps prior to doing a mount or swapon should be completed. (This applies accessibility requirement applies for the file allocator, too).

For the file allocator, you should first prepare your hibernation file - this can be done by configuring your hibernate.conf file with the "FilewriterLocation" option, and running hibernate --no-suspend. Then take a look in /sys/power/tuxonice/resume for what to pass to your kernel. You should see something like file:/dev/hda7:0x10011f, in which case you should append "resume=file:/dev/hda7:0x10011f" as a kernel parameter in your lilo.conf file or GRUB's menu.lst.

IMPORTANT: make this entry the default entry in lilo.conf file.

Otherwise, it is likely that you will reboot a non hibernatable kernel on a resume image which may lead to unpredictable results, including severely damaging your filesystem. It may be useful to have another boot option with kernel parameters "resume=swap:/dev/hda3 noresume" instead. This will allow you to skip resuming and boot normally. Once again, it is also advisable to keep an original version of the kernel in your boot options.

When you're happy with your file don't forget to run lilo (if you use LILO) and reboot into the hibernation-enabled kernel. It should boot and run the same way as your original kernel. The only difference you should see immediately is that the boot messages (dmesg | less) should contain a note that TuxOnIce has started (eg, "TuxOnIce 3.0-rc2: Normal swapspace found.").