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
    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 --vmm="/boot/xen.gz" /boot/vmlinuz.gz

  OR

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

  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
    KEXEC_ARGS: additional kexec-tools command line arguments

  e.g. kexec -l /boot/second-vmlinuz.gz

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.

  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
		       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 "init 1 irqpoll maxcpus=1"

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 :(