Software-suspend-linux-mini-HOWTO <author>Florent Chabaud <url url="mailto:fchabaud@free.fr"> <date>v0.2, Februar 2003 <abstract> This is about how to suspend linux kernels on disk using the software suspend (swsusp) kernel patch and various scripts. </abstract> <toc>  <sect> Introduction <sect1> What is software suspend ? Software suspend is the ability to freeze the kernel state and dump it on disk, then restore it upon resuming. This allows to completely stop a computer for a long period while keeping an internal session opened. In modern laptops, suspension is no more done by the BIOS, even the unbuggy ones. It uses ACPI and ask the operating system to do most of the job. If you can't satisfy yourself with standby mode (suspension to RAM) because you leave your computer in suspension mode for too long a time, then you have to suspend on disk. <sect1>Copyright (skip this if you're in a hurry) Copyright (c) 2002, 2003 by Florent Chabaud. Please freely copy and distribute (sell or give away) this document in any format. Send any corrections and comments to the document maintainer. You may create a derivative work and distribute it provided that you: <enum> <item> If it's not a translation: Email a copy of your derivative work to the author(s) and maintainer (could be the same person). <item>License the derivative work in the spirit of this license or use GPL. Include a copyright notice and at least a pointer to the license used. <item>Give due credit to previous authors and major contributors. </enum> <sect1>Why I wrote this ? Software suspend has a long story, but for a long time it was considered as alpha. This is mainly due to the fact that suspension has to deal with a lot of aspects in kernel. It is therefore difficult to follow the kernel development (for instance transition from 2.2 to 2.4 was not straightforward). The patch can now be considered in a beta stage since it seems to work rather reliably and a lot of bugs have been fixed. This is perhaps a little too optimistic but we need some beta-testers ;-) If you have a mono-processor machine with Pentium like CPU and ide disks, it is very likely that swsusp will perform correctly. However, installing, configuring and using software suspension is not straightforward, since it involves recompiling the kernel and setting some boot parameters. Hence, as long as software suspension will not be taken in account by modern linux distributions (and probably even after that :-) a mini-howto may be found useful. <sect> Installing software suspend <sect1> Downloading Software suspend (aka swsusp) is hosted by <url url="http://sourceforge.net">. You can access its site directly at <url url="http://sourceforge.net/projects/swsusp">. <sect1> Overview <sect2> Kernel 2.2.X Software suspend was first developped by Gabor Kuti and he used to maintain a page <url url="http://falcon.sch.bme.hu/~seasons/linux/swsusp.html"> for his patch. A patch is available against 2.2.20 kernel named v7c. Since this patch is no more maintained, this document will not provide much information on this version. <sect2> Kernel 2.4.X Kernel 2.4.X is the most recent stable release of linux kernel. Unfortunately, software suspension isn't part of this kernel and should therefore be added using one of the patches provided on the above pages. The swsusp patch is named with a few conventions that includes: <itemize> <item> A version that is increased from one release of swsusp to the other. <item> A mention alpha/beta (maybe one day stable ;-) that indicates if the patch is reliable concerning data loss in case of failure. <item> The kernel version on which the swsusp patch applies. It is currently either a vanilla kernel 2.4.18, 2.4.19, and so on, or an already patched kernel such as acpi. </itemize> <sect2> Kernel 2.5.X Software suspension is directly included since 2.5.18 in the main development kernel tree. As this kernel isn't stable and evolves fastly, this document will not provide information specific to this version, but some of the present informations may be found useful for using 2.5 software suspension support. <sect1> Requirements Software suspension on a 2.4 kernel base needs a mono-processor machine with a CPU featuring pse or pse36 feature. Your hardware disks should be IDE (swsusp with SCSI is trying to be supported in 2.5 kernel). <sect1> Compiling the kernel You need to choose the kernel source tree you want to use as basis. For instance, v15beta-acpi20020918 is the swsusp patch version 15 against the acpi20020918 patched kernel. As acpi20020918 is itself based upon a 2.4.19 vanilla kernel, you'll need to download this kernel source tree. Compiling a kernel is not that hard (see the Kernel-HOWTO) but be sure to save your running kernel as something like /boot/vmlinuz.old and add an entry in your lilo.conf file to be able to boot on this one. Before applying any patch, 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 setup, can be found on <url url="http://www.kernel.org">. <sect1> Patching the kernel Once you have succeeded in compiling your kernel and reboot apply the software suspend patch against /usr/src/linux. <verb> cd /usr/src/linux gzip -d < patch-vanilla-2.4.Y-swsuspX.gz | patch -p1 </verb> If the kernel versions match, then no error should happen. Otherwise you may have to manually edit some rejected hunks. Load your previously saved configuration settings and add in General Setup section, Power Management and Software Suspend. You should find the following somewhere in the generated .config file. <verb> CONFIG_SOFTWARE_SUSPEND=y </verb> You can now compile your kernel... <sect1> Installing the new kernel In order to set the suspendable kernel, you will have to add two new entries in your /etc/lilo.conf file. You must have a swap partition on your disk. This swap partition should be at least 30% larger than your RAM (this is a rough estimation: it depends on the number of applications you suspend and their memory consumption). If you have 128M RAM, you may use 160M swap. It has to be formatted by mkswap and used as a swap area through /etc/fstab configuration file. You <bf>don't</bf> need a specific partition for swsusp. Now you must set the resume kernel option to the swap partition you want to use for suspension. If your partition is, for instance, the third primary one on first ide disk (/dev/hda3) you have to append "resume=/dev/hda3" as kernel parameter in your lilo.conf file. <bf>IMPORTANT</bf>: make this entry the default entry in lilo.conf file. Otherwise, it is likely that you will reboot a non suspendable kernel on a resume image which may lead to impredictable results, including severely damage your filesystem. It may be useful to have another boot option with kernel parameters "resume=/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 and reboot the suspendable kernel. It should boot and run the same way as your original kernel. In fact, if you never suspend it is intended to be as stable as the original one ;-) <sect> Testing software suspend <sect1> Installing the suspend script The best way to use swsusp is to use the suspend.sh script. This script should be available on same sites as swsusp. Download it to <tt>/tmp</tt> and type <tt>/tmp/suspend.sh --install</tt>. You may have to change the file rights. This will create two files : hibernate (formerly suspend) and suspend.conf. The former is the suspending script itself, the latter its configuration file. The location of these files depends upon your distribution. In most cases, you will have /usr/local/sbin/hibernate (formerly /usr/local/sbin/suspend) and /etc/suspend.conf. Check that the directory of hibernate is in your PATH variable before going further. If you want users to be able to suspend, use <tt>visudo</tt> and add the following lines to your /etc/sudoers file: <verb> Host_Alias LOCALHOST=localhost,<your hostname> ALL LOCALHOST=NOPASSWD: /usr/local/sbin/hibernate * </verb> See man sudoers(5) for more information. Users will then be able to do <tt>sudo /usr/local/sbin/hibernate</tt>. <sect1> Suspending in text mode For testing swsusp, you should begin by testing text only suspension. Switch to a console by <tt>Ctrl-Alt F1</tt>, login as root and type <tt>init 3</tt> to switch to console state. Now try <tt>hibernate</tt>. The suspension should take place ending with machine halting. Power on the computer and it should recover your session. If not see the troubleshooting section. <sect1> Suspending in X mode You can now recover your graphical session by typing <tt>init 5</tt>. Log in as user under X. Try <tt>sudo /usr/local/sbin/hibernate</tt> and see if suspension works correctly. <sect> Troubleshooting <sect1> Suspend script configuration The suspend.conf file has several options that may help you to get swsusp work correctly on your specific hardware. <sect2> Leave X On some hardware, the graphic chipset isn't properly restored by BIOS upon resume and the state memorized by the resumed kernel becomes incoherent. That may help to switch to a text console before suspending and swith back to X only after resume. The special option nvidia may also help if you experience strange things such as 3D lack upon resume. It launches a fake xserver that should cause proper initialization of the chipset. <sect2> Stop services It is wise to stop before suspension all services that could be resumed in a different environment. This includes usb, pcmcia but also network services. If your suspension is aborted because a task cannot be stopped by swsusp, and this task corresponds to a service, you can tell suspend script to stop this service before suspension. Upon resume, you can specify the services you want to start again. This is done with the following options of hibernate (version 0.11) <sect3> SWSUSP_STOP_SERVICES_BEFORE_SUSPEND Those services are stopped before suspension, that is to say that the corresponding script is executed with stop option. <sect3> SWSUSP_START_SERVICES_AFTER_RESUME Those services are started after resuming, that is to say that the corresponding script is executed with start option. <sect3> SWSUSP_RESTART_SERVICES Those services are stopped before suspension and restarted upon resume. Before stopping those scripts, hibernate check if they are launched in your current runlevel. It is not equivalent to both above options because if a runlevel doesn't use a service it will be started upon resume if it is in SWSUSP_START_SERVICES_AFTER_RESUME list, not in SWSUSP_RESTART_SERVICES one. <sect2> Stop/start processes You can stop (kill) processes before suspension and start other ones after resume using SWSUSP_KILL_PROGS_BEFORE_SUSPEND and SWSUSP_START_PROGS_AFTER_RESUME. Some programs may be incompatible with swsusp because, for instance, they access directly some hardware and ignore power management events. You also may ask suspend script to abort suspension if some specified processes are running using SWSUSP_NON_COMPATIBLE_PROGS. <sect2> Unload modules In the same spirit it is wise to unload before suspension all modules that are unused. You can also force the insertion of specific modules upon resume but usually the kernel knows upon resume the modules i needs to reload. <sect2> Umount filesystems Suspending while network filesystems or removable devices are mounted may lead to impredictible results. You can specify the mount points that must be unused before suspension. If not, suspend script will abort suspension unless the --force and/or --kill option is used. The --force option will simply ignore those mount points. The --kill option will try to kill the processes that use these mountpoints. <sect2> Shutdown network interfaces In the same spirit you can specify the network interfaces that must be shut down before suspension. Upon resume, you can ask suspend script to have some interfaces up. You can also use the keyword auto to let the network interfaces be restarted in reverse order (the default). However, you will most preferably include network script in service restart option above. <sect2> Force suspend mode By default, suspend script uses the /proc/sys/kernel/swsusp interface to activate suspension. If you run an ACPI kernel, you may try the acpi keyword. This way, the /proc/acpi/sleep interface will be used instead and this may better notify some hardware that a suspension take place here. Note that ACPI stuff currently ignore suspension event if you don't use software suspend. <sect2> Save clock on suspend It is a feature that the resumed kernel recovers its entire memory image, including the system date which therefore appears uncorrect. The suspend script calls hwclock on resume to reset the date according to the CMOS clock. You can ask the script to also save the system date to CMOS just before suspending. Most of the time this is unuseful and may even lead to drifting of your clock. <sect1>Enabling debug messaging and other obscure features <label id=eatmem> The /proc/sys/kernel/swsusp interface provides a way to activate useful debug messages. It takes three integers each taken as a collection of flag bits. The first integer only uses bit 0. A null value means normal state. One means that suspension is required at kernel level. Hence, <tt>echo 1 > /proc/sys/kernel/swsusp</tt> should provoke immediate suspension. The second integer uses two bits. The first one is the behaviour of swsusp after writing the suspend image. Zero means halt the computer (if possible). You need apm or acpi compiled in kernel for this feature to work correctly. Otherwise, the machine just hangs forever and can be safely powered off. The second bit tells swsusp what kind of memory freeing it should use. The default value is zero which means to use "eatmem". Before writing suspend image, swsusp will try to eat as many memory as possible. This causes all processes to have their RAM pages swapped. This method makes the suspend image as small as possible, but upon resume, all processes will have to unswap their pages. Therefore, your system will sucks for a while. On the contrary a value of one in the second bit will activate freemem method. In this case, swsusp will just frees the no more used pages and try to memorize its suspend image in the remaining free pages. With this method, you need to have a physical RAM about twice as large as the amount of physical RAM that is effectively used before suspension. Writing pages takes a longer time since the image is bigger, but you get a usable system at once upon resume. Hence, <tt>echo "1 3" > /proc/sys/kernel/swsusp</tt> will try to use freemem instead of eatmem and reboot the computer after suspension. The third integer uses four bits. The first one activates debugging messages. The second one displays a cute progressing bar during suspension. The third one activates a lot more messages. The fourth one adds some delays to be able to read messages before power off. You can set parameters without asking for suspension. For instance <tt>echo "0 1 13 > /proc/sys/kernel/swsusp"</tt> will activate debug, verbose and slow down flags on next suspension, which should end with reboot of the machine instead of halt. The eatmem method will be used. To activate suspension, use <tt>echo 1 > /proc/sys/kernel/swsusp</tt>. <sect>How it works For the most curious users, here are briefly the steps of suspension. This may also help in tracking why it doesn't suspend. <enum> <item> stop all processes. If some processes can't be stopped, abort. This is your case. <item> eat memory to swap as much data as possible (see section on <ref id="eatmem" name="obscure features"> for more details) <item> copy memory to RAM (that sounds strange but this is what is done) to prepare the suspend image. If not enough memory here, abort and restart tasks. <item> copy suspend image to disk. At this stage nothing should prevent from really suspend except a bug. <item> change signature of swap partition to suspend partition, so that next reboot will resume. <item> power down. </enum> </article>