1# Xen x86 PV Bootloader Protocol
2
3## Introduction
4
5One method for booting an x86 Xen PV guest is to use a PV bootloader,
6that is, a bootloader which is itself a PV kernel but which behaves as
7a bootloader (examples include the pvgrub-legacy and grub2 targeting
8Xen).
9
10In many cases the user wishes to manage this PV bootloader from within
11the guest, and therefore wishes to chainload something from the guest
12filesystem, most likely via a stage 1 PV bootloader provided by dom0.
13
14The purpose of this document is to define the paths within the guest
15filesystem where a stage 1 bootloader should look for the in-guest PV
16bootloader to load and the protocol/format expected from the
17to-be-chainloaded bootloader.
18
19## Protocol
20
21The bootloader binary should be an ELF file of the appropriate type
22(32- or 64-bit). It should contain the standard Xen ELF notes allowing
23it to be loaded by the Xen toolstack domain builder (TBD: Reference).
24
25## Path
26
27The second stage bootloader should be installed into the guest
28filesystem as:
29
30 * `/boot/xen/pvboot-<ARCH>.elf`
31
32Where `<ARCH>` is the first element of the GNU triplet e.g. one of:
33
34 * `i386` (nb only `i386`, not `i686` etc), corresponding to the Xen
35   `x86_32(p)` arch;
36 * `x86_64`, corresponding to the Xen `x86_64` arch;
37
38It is allowable for `/boot` to be a separate filesystem from `/` and
39therefore stage 1 bootloaders should search
40`/boot/xen/pvboot-<ARCH>.elf` and `/xen/pvboot-<ARCH>.elf` (in that
41order). The `xen` directory should be on the same filesystem as /boot
42and therefore it is not necessary to search for /pvboot-<ARCH>.elf.
43
44It is not in general possible under Xen for a bootloader to boot a
45kernel of a different width from itself, and this extends to
46chainloading from a stage one. Therefore it is permissible to have
47both `/boot/xen/pvboot-i386.elf` and `/boot/xen/pvboot-x86_64.elf`
48present in a guest to be used by the appropriate stage 1 (e.g. for
49systems with 32-bit userspace and an optional 64-bit kernel).
50