GameCube/PPC32 kexec port
_________________________

Excerpt from the README of the original author of kexec:
(http://www.xmission.com/~ebiederm/files/kexec/README)

"kexec is a set of systems call that allows you to load another kernel
from the currently executing Linux kernel.  The current implementation
has only been tested, and had the kinks worked out on x86, but the
generic code should work on any architecture."

You can read more about kexec in this interesting LWN.net article:

	http://lwn.net/Articles/15468/

or here on this IBM developerWorks document:

	http://www-106.ibm.com/developerworks/linux/library/l-kexec.html?ca=dgr-lnxw04RebootFast


I have ported kexec to the GameCube, so it is now posible to load linux 
from linux also in the GameCube Linux (gc-linux) port.

If you want to learn more about Linux on the GameCube please visit

	http://www.gc-linux.org


The GameCube is a gaming console developed by Nintendo featuring a
PowerPC processor called "Gecko" which is very similar to the PPC 750FX.

The port has been tested only on the GameCube but I think it should be very
easy now to support other PPC32 embedded platforms. See DEVELOPER NOTES near 
the end of this file.

There is support for loading DOL executables (GameCube native) and Elf32
PowerPC executables through the modified version of the kexec-tools package.


CONTENTS

./README_PLEASE
./gc-linux-2.6.6-isobel.kexec.patch
./kexec-266.diff
./kexec-tools-1.8-isobel.gc-linux-2.6.6.patch
./kexec-tools-1.8.tar.gz


COMPILING A KERNEL WITH KEXEC SUPPORT

This version of the GameCube/PPC32 kexec port supports kernel version 2.6.6.

The standard kexec for Linux 2.6.6 is available at

	http://developer.osdl.org/rddunlap/kexec/2.6.6/


- Put the kernel tarball, the standard kexec patch and the GameCube/PPC32 
  kexec patch on a directory where you have permissions.

	linux-2.6.6.tar.bz2
	kexec-266.diff
	gc-linux-2.6.6-isobel.kexec.patch

- Unpack the kernel tarball.

	tar xjvf linux-2.6.6.tar.bz2

- Patch the kernel source with the standard kexec patch and the GameCube/PPC32
  kexec patch.

	cd linux-2.6.6
	patch -p1 <../kexec-266.diff
	patch -p1 <../gc-linux-2.6.6-isobel.kexec.patch

  NOTE: this assumes you have the patches on the parent directory
        of the top level directory of the kernel source

- Compile the kernel source as usual.


COMPILING KEXEC TOOLS

This version of the GameCube/PPC32 kexec port supports kexec-tools 1.8.

The standard kexec userspace tools are at

	http://developer.osdl.org/rddunlap/kexec/kexec-tools/

- Put the kexec-tools tarball and the GameCube/PPC32 kexec-tools patch on
  a directory where you have permissions.

	kexec-tools-1.8.tar.gz
	kexec-tools-1.8-isobel.gc-linux-2.6.6.patch

- Unpack the kexec-tools tarball.

	tar xzvf kexec-tools-1.8.tar.gz

- Patch the kexec-tools source with GameCube/PPC32 kexec-tools patch.

	cd kexec-tools-1.8
	patch -p1 <../kexec-tools-1.8-isobel.gc-linux-2.6.6.patch

  NOTE: this assumes you have the patches on the parent directory
        of the top level directory of the kexec-tools source.

- Compile the kexec-tools.

  If you are using the toolchain available at 
  http://www.gc-linux.org/down/ppc-linux-uclibc-toolchain.tar.bz2
  and you want to compile the kexec-tools for the GameCube you can use:

	make GAMECUBE=1

  Otherwise you may need or not to specify correctly ARCH and CROSSCOMPILE.

  The target architecture for GameCube/PPC32 is ppc (ARCH=ppc).
  The resulting executable "kexec" is built on ./objdir/build/sbin/kexec.
  You will need to copy that file to /sbin on your real filesystem for use.


INSTALLING KEXEC

You need to perform basically these actions:

- Copy kexec executable from kexec-tools to your real /usr/sbin.

- Modify your reboot script to perform a "kexec -e" prior to the real "reboot".
  Usually that means modifying /etc/init.d/reboot and placing a

	/sbin/kexec -e

  before the line that calls the reboot executable.

  NOTE: If you fail to modify your reboot script correcly you may see
        your system rebooting and not reloading the kexec'ed image.


USING KEXEC ON GC-LINUX

We can reload a new kernel from gc-linux without going through PSOLoad again
using a kexec-enabled kernel.

But not only that. kexec allows you to also load and transfer total
control of the GameCube to existing homebrew DOLs from within gc-linux.
However, once control is transferred to the DOL, you won't be able to
get control back unless the loaded DOL supports such a mechanism
(like for example, Costis! PSOLoad V2.0 reloader).

In any case, you should think of kexec as a shutdown operation from the 
linux point of view. This is because you exit completely linux when you kexec 
a kernel image or a DOL.

Examples:

- Restart the system with a new kernel in DOL format:

	/sbin/kexec zImage.dol

- Restart the system with a new kernel in ELF format:

	/sbin/kexec zImage.initrd.elf

- Load a homebrew demo:

	/sbin/kexec testdemo4.dol


DEVELOPER NOTES

I've created two loader modules for the kexec-tools: DOL and Elf32-PPC.

The DOL loader is only useful for the GameCube, and uses a special setup glue
targetted for the GameCube (ppc-setup-dol.S).

The Elf32 loader can use the setup glue of the GameCube but also a "simple" 
setup glue that may work on a embedded platform that boots with the MMU 
switched off (ppc-setup-simple.S).
You can use the simple setup glue invoking kexec with the --gamecube=0 
parameter, which is the default behaviour if you compile the kexec-tools for
a different target than the GameCube.

NOTE: The only PPC platform I have access to is a GameCube, so no real tests
      on other platforms. Sorry.

It may be necessary to develop different setup glues targetted for "special"
platforms out there. That is currently done on kexec-tools so no need to
modify the kernel for that.

!!!IMPORTANT!!!
I've intentionatelly put a #error directive in get_memory_ranges() in file
kexec/kexec-ppc.c. This is because the use of /proc/iomem to get the real
memory ranges doesn't work always on embedded, as happened with the
GameCube port of Linux. If you think /proc/iomem is the right way for you 
then you only need to remove the #error directive. Otherwise, you'll need to 
recode the function for your platform, which should be easy.

I've also integrated two patches to the platform independent code to fix 
bugs that I've found while porting kexec to the GameCube.
The patches modify kimage_free() and kimage_alloc_page() in kernel/kexec.c.
The first modification allows to really free some pages by first clearing
the reservation bit on them.
The second modification, which is still under investigation, zeroes pages
at allocation time to avoid the kernel to touch unwanted memory when walking
through for_each_kimage_entry().


SPECIAL CREDITS
- Eric Biederman and others for the original kexec
- Costis for PSOLoad
- mist, ionic, gimli, tmbinc and others for bootstrapping gc-linux
- apgo for keeping gc-linux kernel versions up to date
- hamtitampti for a working network driver
- Groepaz for inspiration
- Steve_- for testing and putting my stuff in /down
- dmp for his useful logbot-dmp ;)


I would like to dedicate this work specially to my friend Mario Franco Mendoza.
I wish we could have a kind of human-aware kexec to restart and fix us before
going for a walk with Miss Disease and Miss Death.


Have fun!
Albert "isobel" Herranz