5. Troubleshooting

5.1 It panics!

D'oh. If you can capture the panic somehow (either over a serial console, or digital camera if need be), and send it to the list, somebody might hopefully be able to do something about it. Before you send it to the list, try hibernating from single user mode (described below) and see if the same thing happens.

Panics captured on 2.4 must be run through the ksymoops program before any useful information can be obtained from them.

5.2 It hangs!

The most common symptom of a non-functioning TuxOnIce is a hang either during hibernating or resuming. Hangs while resuming have two sources:

1. Foul ups by Nigel in the kernel code
2. Driver issues

Type 1 issues will generally affect areas other than the point where you see "Copying original kernel back".

Type 2 issues are more common, and affect particular hardware (and therefore some computers/configurations, but not others). There are usually workarounds for these issues, and the workarounds generally involve building functionality as modules and stopping related userpace daemons and unloading the modules prior to hibernate, and reloading/restarting afterwards. Particularly common here are issues with USB, DRI/DRM, FireWire, cpufreq, sound card and network drivers. In the case of DRI/DRM, you can't simply disable it prior to resuming, so people (unfortunately) have to choose between 3D performance and the ability to hibernate (unless you're willing to stop X prior to hibernating and restart it afterwards). As driver writers improve their support for hibernating and resuming, it is expected that these issues will ultimately go away.

Finding which driver is causing hibernation to hang is sometimes less than obvious. In these cases, we recommend starting with a minimal environment (init S) and seeing if you can hibernate from there, or failing that with init=/bin/sh. If you have success, add more and more components of your normal configuration until you find something that breaks hibernating. If you can't even hibernate from init S, it may be that you've compiled the driver that's causing problems into the kernel. In this case, look at your kernel configuration and seek to compile as modules as much as possible. Then try with a minimal configuration again.

5.3 Hibernating in a minimalist environment

To eliminate problems with drivers, people will often recommend to hibernate from single user mode or use init=/bin/sh.

Single user mode (init S)

Linux distributions where many services are not enabled, and ideally, many modules are not enabled. It can be entered by adding the letter "S" to the kernel command line when you boot. Unfortunately some distributions will still load many modules in this runlevel, so if hibernation still fails here, you might need to try using init=/bin/sh.

init=/bin/sh

In this mode, absolutely nothing else is done afer loading the kernel. It requires a bit of manual intervention to get things going into a usable state, documented below, but should help in isolating bad drivers causing TuxOnIce to fail.

• To enter this mode, as you boot your machine you need to catch your bootloader (eg, LILO or GRUB) before it boots your kernel. Edit the kernel command-line to add the text "init=/bin/sh". In LILO this can be done by holding the Ctrl key down to bring up the menu, selecting your kernel with the arrow keys, then typing " init=/bin/sh" and press Enter. In GRUB, you can do this by highlighting your kernel in the menu, press E to edit, highlight the line that begins "kernel ...", press E to edit that, and type " init=/bin/sh" on the end, press Enter to save, and press B to boot.
• You should be greeted with a screen of the kernel booting and a prompt that looks a little like

  sh-3.00# 
  

• From here, enter the following commands:
  • # mount -o remount,rw /
  • # mount -t proc proc proc
  • # swapon -a
  You may need to start devfsd or udev too:
  • # /etc/init.d/devfsd start
  And now try running the hibernate script to see if it succeeds. If so, you can blame a module and now the process begins to load modules one by one until hibernation breaks.
• To cleanly reboot from this point, you will want to do the following:
  • # mount -o remount,ro /
  • # sync
  • # reboot

5.4 Asking for help

People on the suspend2-users and suspend2-devel mailing lists are generally pretty helpful, but they'll be better able to help you if you can provide more information. In particular, it will help if you provide information regaring what make/model of computer you have, what modules you have loaded while trying to hibernate, and a copy of your kernel configuration. Most of details can be quickly and easily gathered using the 1.03 or later hibernate script with the --bug-report option.

If you are sending a kernel panic from a 2.4 kernel, be sure to run the output through ksymoops and send the result. Otherwise the panic is of very little use to anybody.