1For x86, building xen.efi requires gcc 4.5.x or above (4.6.x or newer
2recommended, as 4.5.x was probably never really tested for this purpose) and
3binutils 2.22 or newer.  Additionally, the binutils build must be configured to
4include support for the x86_64-pep emulation (i.e.
5`--enable-targets=x86_64-pep` or an option of equivalent effect should be
6passed to the configure script).
7
8For arm64, the PE/COFF header is open-coded in assembly, so no toolchain
9support for PE/COFF is required.  Also, the PE/COFF header co-exists with the
10normal Image format, so a single binary may be booted as an Image file or as an
11EFI application.  When booted as an EFI application, Xen requires a
12configuration file as described below unless a bootloader, such as GRUB, has
13loaded the modules and describes them in the device tree provided to Xen.  If a
14bootloader provides a device tree containing modules then any configuration
15files are ignored, and the bootloader is responsible for populating all
16relevant device tree nodes.
17
18Once built, `make install-xen` will place the resulting binary directly into
19the EFI boot partition, provided `EFI_VENDOR` is set in the environment (and
20`EFI_MOUNTPOINT` is overridden as needed, should the default of `/boot/efi` not
21match your system). The xen.efi binary will also be installed in
22`/usr/lib64/efi/`, unless `EFI_DIR` is set in the environment to override this
23default.
24
25The binary itself will require a configuration file (names with the `.efi`
26extension of the binary's name replaced by `.cfg`, and - until an existing
27file is found - trailing name components dropped at `.`, `-`, and `_`
28separators will be tried) to be present in the same directory as the binary.
29(To illustrate the name handling, a binary named `xen-4.2-unstable.efi` would
30try `xen-4.2-unstable.cfg`, `xen-4.2.cfg`, `xen-4.cfg`, and `xen.cfg` in
31order.) One can override this with a command line option (`-cfg=<filename>`).
32This configuration file and EFI commandline are only used for booting directly
33from EFI firmware, or when using an EFI loader that does not support
34the multiboot2 protocol.  When booting using GRUB or another multiboot aware
35loader the EFI commandline is ignored and all information is passed from
36the loader to Xen using the multiboot protocol.
37
38The configuration file consists of one or more sections headed by a section
39name enclosed in square brackets, with individual values specified in each
40section. A section named `[global]` is treated specially to allow certain
41settings to apply to all other sections (or to provide defaults for certain
42settings in case individual sections don't specify them). This file (for now)
43needs to be of ASCII type and not e.g. UTF-8 or UTF-16. A typical file would
44thus look like this (`#` serving as comment character):
45
46    **************************example begin******************************
47
48    [global]
49    default=sle11sp2
50
51    [sle11sp2]
52    options=console=vga,com1 com1=57600 loglvl=all noreboot
53    kernel=vmlinuz-3.0.31-0.4-xen [domain 0 command line options]
54    ramdisk=initrd-3.0.31-0.4-xen
55
56    **************************example end********************************
57
58The individual values used here are:
59
60###`default=<name>`
61
62Specifies the section to use for booting, if none was specified on the command
63line; only meaningful in the `[global]` section. This isn't required; if
64absent, section headers will be ignored and for each value looked for the
65first instance within the file will be used.
66
67###`options=<text>`
68
69Specifies the options passed to the hypervisor, see [Xen Hypervisor Command
70Line Options](xen-command-line.html).
71
72###`kernel=<filename>[ <options>]`
73
74Specifies the Dom0 kernel binary and the options to pass to it.
75
76The options should in general be the same as is used when booting
77natively, e.g. including `root=...` etc.
78
79Check your bootloader (e.g. grub) configuration or `/proc/cmdline` for
80the native configuration.
81
82###`ramdisk=<filename>`
83
84Specifies a Linux-style initial RAM disk image to load.
85
86Other values to specify are:
87
88###`video=gfx-<xres>[x<yres>[x<depth>]]`
89
90Specifies a video mode to select if available. In case of problems, the
91`-basevideo` command line option can be used to skip altering video modes.
92
93###`xsm=<filename>`
94
95Specifies an XSM module to load.
96
97###`ucode=<filename>`
98
99Specifies a CPU microcode blob to load. (x86 only)
100
101###`dtb=<filename>`
102
103Specifies a device tree file to load.  The platform firmware may provide a
104DTB in an EFI configuration table, so this field is optional in that
105case. A dtb specified in the configuration file will override a device tree
106provided in the EFI configuration table. (ARM only)
107
108###`chain=<filename>`
109
110Specifies an alternate configuration file to use in case the specified section
111(and in particular its `kernel=` setting) can't be found in the default (or
112specified) configuration file. This is only meaningful in the [global] section
113and really not meant to be used together with the `-cfg=` command line option.
114
115Filenames must be specified relative to the location of the EFI binary.
116
117Extra options to be passed to Xen can also be specified on the command line,
118following a `--` separator option.
119