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. 17The property "xen,uefi-cfg-load" can be specified in the /chosen node to force 18Xen to load the configuration file even if multiboot modules are found. 19 20Once built, `make install-xen` will place the resulting binary directly into 21the EFI boot partition, provided `EFI_VENDOR` is set in the environment (and 22`EFI_MOUNTPOINT` is overridden as needed, should the default of `/boot/efi` not 23match your system). When built with debug info, the binary can be quite large. 24Setting `INSTALL_EFI_STRIP=1` in the environment will cause it to be stripped 25of debug info in the process of installing. `INSTALL_EFI_STRIP` can also be set 26to any combination of options suitable to pass to `strip`, in case the default 27ones don't do. The xen.efi binary will also be installed in `/usr/lib64/efi/`, 28unless `EFI_DIR` is set in the environment to override this default. This 29binary will not be stripped in the process. 30 31The binary itself will require a configuration file (names with the `.efi` 32extension of the binary's name replaced by `.cfg`, and - until an existing 33file is found - trailing name components dropped at `.`, `-`, and `_` 34separators will be tried) to be present in the same directory as the binary. 35(To illustrate the name handling, a binary named `xen-4.2-unstable.efi` would 36try `xen-4.2-unstable.cfg`, `xen-4.2.cfg`, `xen-4.cfg`, and `xen.cfg` in 37order.) One can override this with a command line option (`-cfg=<filename>`). 38This configuration file and EFI commandline are only used for booting directly 39from EFI firmware, or when using an EFI loader that does not support 40the multiboot2 protocol. When booting using GRUB or another multiboot aware 41loader the EFI commandline is ignored and all information is passed from 42the loader to Xen using the multiboot protocol. 43 44The configuration file consists of one or more sections headed by a section 45name enclosed in square brackets, with individual values specified in each 46section. A section named `[global]` is treated specially to allow certain 47settings to apply to all other sections (or to provide defaults for certain 48settings in case individual sections don't specify them). This file (for now) 49needs to be of ASCII type and not e.g. UTF-8 or UTF-16. A typical file would 50thus look like this (`#` serving as comment character): 51 52 **************************example begin****************************** 53 54 [global] 55 default=sle11sp2 56 57 [sle11sp2] 58 options=console=vga,com1 com1=57600 loglvl=all noreboot 59 kernel=vmlinuz-3.0.31-0.4-xen [domain 0 command line options] 60 ramdisk=initrd-3.0.31-0.4-xen 61 62 **************************example end******************************** 63 64The individual values used here are: 65 66###`default=<name>` 67 68Specifies the section to use for booting, if none was specified on the command 69line; only meaningful in the `[global]` section. This isn't required; if 70absent, section headers will be ignored and for each value looked for the 71first instance within the file will be used. 72 73###`options=<text>` 74 75Specifies the options passed to the hypervisor, see [Xen Hypervisor Command 76Line Options](xen-command-line.html). 77 78###`kernel=<filename>[ <options>]` 79 80Specifies the Dom0 kernel binary and the options to pass to it. 81 82The options should in general be the same as is used when booting 83natively, e.g. including `root=...` etc. 84 85Check your bootloader (e.g. grub) configuration or `/proc/cmdline` for 86the native configuration. 87 88###`ramdisk=<filename>` 89 90Specifies a Linux-style initial RAM disk image to load. 91 92Other values to specify are: 93 94###`video=gfx-<xres>[x<yres>[x<depth>]]` 95 96Specifies a video mode to select if available. In case of problems, the 97`-basevideo` command line option can be used to skip altering video modes. 98 99###`xsm=<filename>` 100 101Specifies an XSM module to load. 102 103###`ucode=<filename>` 104 105Specifies a CPU microcode blob to load. (x86 only) 106 107###`dtb=<filename>` 108 109Specifies a device tree file to load. The platform firmware may provide a 110DTB in an EFI configuration table, so this field is optional in that 111case. A dtb specified in the configuration file will override a device tree 112provided in the EFI configuration table. (ARM only) 113 114###`chain=<filename>` 115 116Specifies an alternate configuration file to use in case the specified section 117(and in particular its `kernel=` setting) can't be found in the default (or 118specified) configuration file. This is only meaningful in the [global] section 119and really not meant to be used together with the `-cfg=` command line option. 120 121Filenames must be specified relative to the location of the EFI binary. 122 123Extra options to be passed to Xen can also be specified on the command line, 124following a `--` separator option. 125 126## Unified Xen kernel image 127 128The "Unified" kernel image can be generated by adding additional 129sections to the Xen EFI executable with objcopy, similar to how 130[systemd-boot uses the stub to add them to the Linux kernel](https://wiki.archlinux.org/index.php/systemd-boot#Preparing_a_unified_kernel_image) 131 132The sections for the xen configuration file, the dom0 kernel, dom0 initrd, 133XSM and CPU microcode should be added after the Xen `.pad` section, the 134ending address of which can be located with: 135 136``` 137objdump -h xen.efi \ 138 | perl -ane '/\.pad/ && printf "0x%016x\n", hex($F[2]) + hex($F[3])' 139``` 140 141For all the examples the `.pad` section ended at 0xffff82d041000000. 142All the sections are optional (`.config`, `.kernel`, `.ramdisk`, `.xsm`, 143`.ucode` (x86) and `.dtb` (ARM)) and the order does not matter. 144The virtual addresses do not need to be contiguous, although they should not 145be overlapping and should all be greater than the last virtual address of the 146hypervisor components. 147 148``` 149objcopy \ 150 --add-section .config=xen.cfg \ 151 --change-section-vma .config=0xffff82d041000000 152 --add-section .ucode=ucode.bin \ 153 --change-section-vma .ucode=0xffff82d041010000 \ 154 --add-section .xsm=xsm.cfg \ 155 --change-section-vma .xsm=0xffff82d041080000 \ 156 --add-section .kernel=vmlinux \ 157 --change-section-vma .kernel=0xffff82d041100000 \ 158 --add-section .ramdisk=initrd.img \ 159 --change-section-vma .ramdisk=0xffff82d042000000 \ 160 xen.efi \ 161 xen.unified.efi 162``` 163 164The unified executable can be signed with sbsigntool to make 165it usable with UEFI secure boot: 166 167``` 168sbsign \ 169 --key signing.key \ 170 --cert cert.pem \ 171 --output xen.signed.efi \ 172 xen.unified.efi 173``` 174## UEFI boot and Dom0 modules on ARM 175 176When booting using UEFI on ARM, it is possible to specify the Dom0 modules 177directly from the device tree without using the Xen configuration file, here an 178example: 179 180chosen { 181 #size-cells = <0x1>; 182 #address-cells = <0x1>; 183 xen,xen-bootargs = "[Xen boot arguments]" 184 185 module@1 { 186 compatible = "multiboot,kernel", "multiboot,module"; 187 xen,uefi-binary = "vmlinuz-3.0.31-0.4-xen"; 188 bootargs = "[domain 0 command line options]"; 189 }; 190 191 module@2 { 192 compatible = "multiboot,ramdisk", "multiboot,module"; 193 xen,uefi-binary = "initrd-3.0.31-0.4-xen"; 194 }; 195} 196 197## UEFI boot and dom0less on ARM 198 199Dom0less feature is supported by ARM and it is possible to use it when Xen is 200started as an EFI application. 201The way to specify the domU domains is by Device Tree as specified in the 202[dom0less](dom0less.html) documentation page under the "Device Tree 203configuration" section, but instead of declaring the reg property in the boot 204module, the user must specify the "xen,uefi-binary" property containing the name 205of the binary file that has to be loaded in memory. 206The UEFI stub will load the binary in memory and it will add the reg property 207accordingly. 208 209An example here: 210 211domU1 { 212 #address-cells = <1>; 213 #size-cells = <1>; 214 compatible = "xen,domain"; 215 memory = <0 0x20000>; 216 cpus = <1>; 217 vpl011; 218 219 module@1 { 220 compatible = "multiboot,kernel", "multiboot,module"; 221 xen,uefi-binary = "vmlinuz-3.0.31-0.4-xen"; 222 bootargs = "console=ttyAMA0"; 223 }; 224 module@2 { 225 compatible = "multiboot,ramdisk", "multiboot,module"; 226 xen,uefi-binary = "initrd-3.0.31-0.4-xen"; 227 }; 228 module@3 { 229 compatible = "multiboot,device-tree", "multiboot,module"; 230 xen,uefi-binary = "passthrough.dtb"; 231 }; 232}; 233 234## How to boot different Xen setup using UEFI 235 236These are the different ways to boot a Xen system from UEFI: 237 238 - Boot Xen and Dom0 (minimum required) 239 - Boot Xen and DomU(s) (true dom0less, only on ARM) 240 - Boot Xen, Dom0 and DomU(s) (only on ARM) 241 242### Boot Xen and Dom0 243 244This configuration can be started using the Xen configuration file in the 245example above. 246 247### Boot Xen and DomU(s) 248 249This configuration needs the domU domain(s) specified in the /chosen node, 250examples of how to do that are provided by the documentation about dom0less 251and the example above shows how to use the "xen,uefi-binary" property to use the 252UEFI stub for module loading. 253When adding DomU modules to device tree, also add the property 254xen,uefi-cfg-load under chosen for Xen to load the Xen config file. 255Otherwise, Xen will skip the config file and rely on device tree alone. 256When using the Xen configuration file in conjunction with the device tree, you 257can specify the Xen boot arguments in the configuration file with the "options=" 258keyword or in the device tree with the "xen,xen-bootargs" property, but be 259aware that the Xen configuration file value has a precedence over the DT value. 260 261Example 1 of how to boot a true dom0less configuration: 262 263Xen configuration file: skipped. 264 265Device tree: 266 267``` 268chosen { 269 #size-cells = <0x1>; 270 #address-cells = <0x1>; 271 xen,xen-bootargs = "<Xen command line>" 272 273 domU1 { 274 #size-cells = <0x1>; 275 #address-cells = <0x1>; 276 compatible = "xen,domain"; 277 cpus = <0x1>; 278 memory = <0x0 0xc0000>; 279 vpl011; 280 281 module@1 { 282 compatible = "multiboot,kernel", "multiboot,module"; 283 xen,uefi-binary = "Image-domu1.bin"; 284 bootargs = "console=ttyAMA0 root=/dev/ram0 rw"; 285 }; 286 }; 287 domU2 { 288 #size-cells = <0x1>; 289 #address-cells = <0x1>; 290 compatible = "xen,domain"; 291 cpus = <0x1>; 292 memory = <0x0 0x100000>; 293 vpl011; 294 295 module@2 { 296 compatible = "multiboot,kernel", "multiboot,module"; 297 xen,uefi-binary = "Image-domu2.bin"; 298 bootargs = "console=ttyAMA0 root=/dev/ram0 rw"; 299 }; 300 }; 301}; 302``` 303 304Example 2 of how to boot a true dom0less configuration: 305 306Xen configuration file: 307 308``` 309[global] 310default=xen 311 312[xen] 313options=<Xen command line> 314dtb=<optional DTB> 315``` 316 317Device tree: 318 319``` 320chosen { 321 #size-cells = <0x1>; 322 #address-cells = <0x1>; 323 xen,uefi-cfg-load; 324 325 domU1 { 326 #size-cells = <0x1>; 327 #address-cells = <0x1>; 328 compatible = "xen,domain"; 329 cpus = <0x1>; 330 memory = <0x0 0xc0000>; 331 vpl011; 332 333 module@1 { 334 compatible = "multiboot,kernel", "multiboot,module"; 335 xen,uefi-binary = "Image-domu1.bin"; 336 bootargs = "console=ttyAMA0 root=/dev/ram0 rw"; 337 }; 338 }; 339 domU2 { 340 #size-cells = <0x1>; 341 #address-cells = <0x1>; 342 compatible = "xen,domain"; 343 cpus = <0x1>; 344 memory = <0x0 0x100000>; 345 vpl011; 346 347 module@2 { 348 compatible = "multiboot,kernel", "multiboot,module"; 349 xen,uefi-binary = "Image-domu2.bin"; 350 bootargs = "console=ttyAMA0 root=/dev/ram0 rw"; 351 }; 352 }; 353}; 354``` 355 356### Boot Xen, Dom0 and DomU(s) 357 358This configuration is a mix of the two configuration above, to boot this one 359the configuration file can be processed or the Dom0 modules can be read from 360the device tree. 361 362Here the first example: 363 364Xen configuration file: 365 366``` 367[global] 368default=xen 369 370[xen] 371options=<Xen command line> 372kernel=vmlinuz-3.0.31-0.4-xen [domain 0 command line options] 373ramdisk=initrd-3.0.31-0.4-xen 374dtb=<optional DTB> 375``` 376 377Device tree: 378 379``` 380chosen { 381 #size-cells = <0x1>; 382 #address-cells = <0x1>; 383 xen,uefi-cfg-load; 384 385 domU1 { 386 #size-cells = <0x1>; 387 #address-cells = <0x1>; 388 compatible = "xen,domain"; 389 cpus = <0x1>; 390 memory = <0x0 0xc0000>; 391 vpl011; 392 393 module@1 { 394 compatible = "multiboot,kernel", "multiboot,module"; 395 xen,uefi-binary = "Image-domu1.bin"; 396 bootargs = "console=ttyAMA0 root=/dev/ram0 rw"; 397 }; 398 }; 399}; 400``` 401 402Here the second example: 403 404Device tree: 405 406``` 407chosen { 408 #size-cells = <0x1>; 409 #address-cells = <0x1>; 410 xen,xen-bootargs = "[Xen boot arguments]" 411 412 module@1 { 413 compatible = "multiboot,kernel", "multiboot,module"; 414 xen,uefi-binary = "vmlinuz-3.0.31-0.4-xen"; 415 bootargs = "[domain 0 command line options]"; 416 }; 417 418 module@2 { 419 compatible = "multiboot,ramdisk", "multiboot,module"; 420 xen,uefi-binary = "initrd-3.0.31-0.4-xen"; 421 }; 422 423 domU1 { 424 #size-cells = <0x1>; 425 #address-cells = <0x1>; 426 compatible = "xen,domain"; 427 cpus = <0x1>; 428 memory = <0x0 0xc0000>; 429 vpl011; 430 431 module@1 { 432 compatible = "multiboot,kernel", "multiboot,module"; 433 xen,uefi-binary = "Image-domu1.bin"; 434 bootargs = "console=ttyAMA0 root=/dev/ram0 rw"; 435 }; 436 }; 437}; 438``` 439