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

The PROBLEMS file contains a list of known problems - currently nice and short.

=====
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-enabled hypervisor 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.

0. Set-Up The Crash Kernel Region
=================================

In order to use kdump an area of memory has to be reserved at boot time.
This is the area of memory that the crash kernel will use, thus allowing it
to run without disrupting the memory used by the first kernel. This area is
called the crash kernel region and is reserved using the crashkernel
command line parameter to the Xen hypervisor. It has two forms:

  i) crashkernel=size

     This is the simplest and recommended way to reserve the crash kernel
     region. Just specify how large the region should be and the hypervisor
     will find a good location for it. A good size to start with is 128Mb

     e.g.

     crashkernel=128M

  ii) crashkernel=size@base

      In this form the base address is provided in addition to
      the size. Use this if auto-placement doesn't work for some reason.
      It is strongly recommended that the base address be aligned
      to 64Mb, else memory below the alignment point will not
      be usable.

      e.g. crashkernel=128M@256M

   Regardless of which of the two forms of the crashkernel command
   line you use, the crash kernel region should appear in
   /proc/iomem_machine. If it doesn't then either the crashkernel
   parameter is missing, or for some reason the region couldn't be placed -
   for instance because it is too large.

   # cat /proc/iomem_machine
   ...
   081d2000-3e875fff : System RAM
     10000000-17ffffff : Crash kernel
   ...


1. Load
=======

Once you are running in a kexec-enabled hypervisor 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 triggered (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 :(
