For building instructions, please see the BUILD file in the
same directory as this file.

The PROBLEMS file contains a list of known problems - there are many :(
If you are looking for a way to help out, please start by looking
in there.

=====
Kexec
=====

To kexec from Xen to Linux or Xen you need to prepare Xen, the domain~0
kernel, kexec-tools and possibly a separate kernel image. This process is
described in the BUILD file.

1. Load
=======

Once you are running in a kexec-anabled hypervsior and domain~0,
you can prepare to kexec by loading the second kernel into the
running kernel.

  a. To kexec into Xen (Xen->Xen)

  kexec -l --append="XEN_ARGS -- DOM0_ARGS" \
	--vmm="XEN_IMAGE" "DOM0_IMAGE" KEXEC_ARGS

  where:
    XEN_ARGS: command line arguments to the xen hypervisor
	      The current code also needs maxcpus=1 as smp is broken
	      phys_efi needs to be set if it was set when
	      the original hypervisor was booted.
    DOM0_ARGS: command line arguments to the domain 0 kernel
    XEN_IMAGE: xen hypervisor image
    DOM0_IMAGE: domain 0 kernel image
    KEXEC_ARGS: additional kexec-tools command line arguments

  e.g. kexec -l --append="phys_efi maxcpus=1" \
	--vmm="/boot/xen.gz" /boot/vmlinuz.gz \
	--initrd=/boot/initramfs_data.cpio

  OR

  b. To kexec into Linux (Xen->Linux)

  *** In order to kexec from Xen to Linux, Xen must have been
      booted with the phys_efi option passed as a command line
      parameter to the hypervisor. This is because the
      PAGE_OFFSET of Linux and Xen are different. And
      as the efi can't be remapped due to hardware restrictions,
      it needs to be left in physical mode. Or at least that
      is the best solution I have so far.

      This is tested and known to work on Tiger 4 machines
      This is tested and known not to work on HP RX2620 machines

  kexec -l LINUX_IMAGE --append "$LINUX_ARGS" KEXEC_ARGS

  where:
    LINUX_IMAGE: the second linux kernel image
    LINUX_ARGS: command line arguments to the second linux kernel
                phys_efi is required
    KEXEC_ARGS: additional kexec-tools command line arguments

  e.g. kexec -l /boot/second-vmlinuz.gz --append="phys_efi maxcpus=1" \
	--initrd=/boot/second-initramfs_data.cpio

2. Execute
==========

Once the second kernel is loaded, it can be executed at any time.
If you don't see the second kernel booting within a second or so,
you are in trouble :(

   kexec -e

=====
Kdump
=====

As per kexec, to kdump from Xen (to Linux) prepare Xen, the domain~0
kernel, kexec-tools and a crash-kernel image. This process is
described in the BUILD file.

1. Load
=======

Once you are running in a kexec-anabled hypervsior and domain~0,
you can prepare to kdump by loading the crash-kernel into the
running kernel.

  *** In order to kdump from Xen (to Linux), Xen must have been
      booted with the phys_efi option passed as a command line
      parameter to the hypervisor. This is because the
      PAGE_OFFSET of Linux and Xen are different. And
      as the efi can't be remapped due to hardware restrictions,
      it needs to be left in physical mode. Or at least that
      is the best solution I have so far.

  kexec -p CRASH_KERNEL_IMAGE --append "$CRASH_KERNEL_ARGS" KEXEC_ARGS

  where:
    CRASH_KERNEL_IMAGE: the crash-kernel image
    CRASH_KERNEL_ARGS: command line arguments to the crash-kernel
                       phys_efi is required
		       init 1 is strongly recommended
		       irqpoll is strongly recommended
		       maxcpus=1 is required if the crash-kernel is SMP
    KEXEC_ARGS: additional kexec-tools command line arguments

  e.g. kexec -p /boot/crash-vmlinuz.gz \
        --append "phys_efi init 1 irqpoll maxcpus=1" \
	--initrd=/boot/crash-initramfs_data.cpio

2. Execute
==========

Once the second kernel is loaded, the crash kernel will be executed
if the hypervisor panics. It will also be executed if domain~0 panics
and /proc/sys/kernel/panic_on_oops is set to a non-zero value

echo 1 > /proc/sys/kernel/panic_on_oops

Kdump may also be trigged (for testing)

  a. From linux

  echo c > /proc/sysrq-trigger

  b. from Xen

     Enter the xen console

     ctrl^a ctrl^a  (may be bound to a different key, this is the default)

     Select C for "trigger a crashdump"

     C

If you don't see the crash-kernel booting within a second or so,
you are in trouble :(
