1.. SPDX-License-Identifier: CC-BY-4.0
2
3How Xen Boots
4=============
5
6This is an at-a-glance reference of Xen's booting capabilities and
7expectations.
8
9
10Build
11-----
12
13A build of xen produces ``xen.gz`` and optionally ``xen.efi`` as final
14artefacts.
15
16 * For BIOS, Xen supports the Multiboot 1 and 2 protocols.
17
18 * For EFI, Xen supports Multiboot 2 with EFI extensions, and native EFI64.
19
20 * For virtualisation, Xen supports starting directly with the PVH boot
21   protocol.
22
23
24Objects
25~~~~~~~
26
27To begin with, most object files are compiled and linked.  This includes the
28Multiboot 1 and 2 headers and entrypoints, including the Multiboot 2 tags for
29EFI extensions.  When ``CONFIG_PVH_GUEST`` is selected at build time, this
30includes the PVH entrypoint and associated ELF notes.
31
32Depending on whether the compiler supports ``__attribute__((__ms_abi__))`` or
33not, either an EFI stub is included which nops/fails applicable setup and
34runtime calls, or full EFI support is included.
35
36
37Protocols and entrypoints
38~~~~~~~~~~~~~~~~~~~~~~~~~
39
40All headers and tags are built in ``xen/arch/x86/boot/head.S``
41
42The Multiboot 1 headers request aligned modules and memory information.  Entry
43is via the start of the binary image, which is the ``start`` symbol.  This
44entrypoint must be started in 32bit mode.
45
46The Multiboot 2 headers are more flexible, and in addition request that the
47image be loaded as high as possible below the 4G boundary, with 2M alignment.
48Entry is still via the ``start`` symbol as with MB1, and still in 32bit mode.
49
50Headers for the EFI MB2 extensions are also present.  These request that
51``ExitBootServices()`` not be called, and register ``__efi_mb2_start`` as an
52alternative entrypoint, entered in 64bit mode.
53
54If ``CONFIG_PVH_GUEST`` was selected at build time, an Elf note is included
55which indicates the ability to use the PVH boot protocol, and registers
56``__pvh_start`` as the entrypoint, entered in 32bit mode.
57
58
59xen.gz
60~~~~~~
61
62The objects are linked together to form ``xen-syms`` which is an ELF64
63executable with full debugging symbols.  ``xen.gz`` is formed by stripping
64``xen-syms``, then repackaging the result as an ELF32 object with a single
65load section at 2MB, and ``gzip``-ing the result.  Despite the ELF32 having a
66fixed load address, its contents are relocatable.
67
68Any bootloader which unzips the binary and follows the ELF headers will place
69it at the 2M boundary and jump to ``start`` which is the identified entry
70point.  However, Xen depends on being entered with the MB1 or MB2 protocols,
71and will terminate otherwise.
72
73The MB2+EFI entrypoint depends on being entered with the MB2 protocol, and
74will terminate if the entry protocol is wrong, or if EFI details aren't
75provided, or if EFI Boot Services are not available.
76
77
78xen.efi
79~~~~~~~
80
81When a PEI-capable toolchain is found, the objects are linked together and a
82PE32+ binary is created.  It can be run directly from the EFI shell, and has
83``efi_start`` as its entry symbol.
84
85.. note::
86
87   xen.efi does contain all MB1/MB2/PVH tags included in the rest of the
88   build.  However, entry via anything other than the EFI64 protocol is
89   unsupported, and won't work.
90
91
92Boot
93----
94
95Xen, once loaded into memory, identifies its position in order to relocate
96system structures.  For 32bit entrypoints, this necessarily requires a call
97instruction, and therefore a stack, but none of the ABIs provide one.
98
99Overall, given that on a BIOS-based system, the IVT and BDA occupy the first
1005/16ths of the first page of RAM, with the rest free to use, Xen assumes the
101top of the page is safe to use.
102