doc/usage/bootefi.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2 .. Copyright 2020, Heinrich Schuchardt <xypron.glpk@gmx.de>
   3
   4 bootefi command
   5 ===============
   6
   7 Synopsis
   8 --------
   9
  10 ::
  11
  12     bootefi [image_addr] [fdt_addr]
  13     bootefi bootmgr [fdt_addr]
  14     bootefi hello [fdt_addr]
  15     bootefi selftest [fdt_addr]
  16
  17 Description
  18 -----------
  19
  20 The *bootefi* command is used to launch a UEFI binary which can be either of
  21
  22 * UEFI application
  23 * UEFI boot services driver
  24 * UEFI run-time services driver
  25
  26 An operating system requires a hardware description which can either be
  27 presented as ACPI table (CONFIG\_GENERATE\_ACPI\_TABLE=y) or as device-tree
  28 The load address of the device-tree may be provided as parameter *fdt\_addr*. If
  29 this address is not specified, the bootefi command will try to fall back in
  30 sequence to:
  31
  32 * the device-tree specified by environment variable *fdt\_addr*
  33 * the device-tree specified by environment variable *fdtcontroladdr*
  34
  35 The load address of the binary is specified by parameter *image_address*. A
  36 command sequence to run a UEFI application might look like
  37
  38 ::
  39
  40     load mmc 0:2 $fdt_addr_r dtb
  41     load mmc 0:1 $kernel_addr_r /EFI/grub/grubaa64.efi
  42     bootefi $kernel_addr_r $fdt_addr_r
  43
  44 The last file loaded defines the image file path in the loaded image protocol.
  45 Hence the executable should always be loaded last.
  46
  47 The value of the environment variable *bootargs* is converted from UTF-8 to
  48 UTF-16 and passed as load options in the loaded image protocol to the UEFI
  49 binary.
  50
  51 Note
  52     UEFI binaries that are contained in FIT images are launched via the
  53     *bootm* command.
  54
  55 UEFI boot manager
  56 '''''''''''''''''
  57
  58 The UEFI boot manager is invoked by the *bootefi bootmgr* sub-command.
  59 Here boot options are defined by UEFI variables with a name consisting of the
  60 letters *Boot* followed by a four digit hexadecimal number, e.g. *Boot0001* or
  61 *BootA03E*. The boot variable defines a label, the device path of the binary to
  62 execute as well as the load options passed in the loaded image protocol.
  63
  64 If the UEFI variable *BootNext* is defined, it specifies the number of the boot
  65 option to execute next. If no binary can be loaded via *BootNext* the variable
  66 *BootOrder* specifies in which sequence boot options shalled be tried.
  67
  68 The values of these variables can be managed using the U-Boot command
  69 *efidebug*.
  70
  71 UEFI hello world application
  72 ''''''''''''''''''''''''''''
  73
  74 U-Boot can be compiled with a hello world application that can be launched using
  75 the *bootefi hello* sub-command. A session might look like
  76
  77 ::
  78
  79     => setenv bootargs 'Greetings to the world'
  80     => bootefi hello
  81     Booting /MemoryMapped(0x0,0x10001000,0x1000)
  82     Hello, world!
  83     Running on UEFI 2.8
  84     Have SMBIOS table
  85     Have device tree
  86     Load options: Greetings to the world
  87
  88 UEFI selftest
  89 '''''''''''''
  90
  91 U-Boot can be compiled with UEFI unit tests. These unit tests are invoked using
  92 the *bootefi selftest* sub-command.
  93
  94 Which unit test is executed is controlled by the environment variable
  95 *efi\_selftest*. If this variable is not set, all unit tests that are not marked
  96 as 'on request' are executed.
  97
  98 To show a list of the available unit tests the value *list* can be used
  99
 100 ::
 101
 102     => setenv efi_selftest list
 103     => bootefi selftest
 104
 105     Available tests:
 106     'block image transfer' - on request
 107     'block device'
 108     'configuration tables'
 109     ...
 110
 111 A single test is selected for execution by setting the *efi\_selftest*
 112 environment variable to match one of the listed identifiers
 113
 114 ::
 115
 116     => setenv efi_selftest 'block image transfer'
 117     => bootefi selftest
 118
 119 Some of the tests execute the ExitBootServices() UEFI boot service and will not
 120 return to the command line but require a board reset.
 121
 122 Configuration
 123 -------------
 124
 125 To use the *bootefi* command you must specify CONFIG\_CMD\_BOOTEFI=y.
 126 The *bootefi hello* sub-command requries CMD\_BOOTEFI\_HELLO=y.
 127 The *bootefi selftest* sub-command depends on CMD\_BOOTEFI\_SELFTEST=y.
 128
 129 See also
 130 --------
 131
 132 * *bootm* for launching UEFI binaries packed in FIT images
 133 * *booti*, *bootm*, *bootz* for launching a Linux kernel without using the
 134   UEFI sub-system
 135 * *efidebug* for setting UEFI boot variables