bootefi.rst 4.0 KB

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