Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | .. Copyright (c) 2018 Heinrich Schuchardt |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 3 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 4 | UEFI on U-Boot |
| 5 | ============== |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 6 | |
| 7 | The Unified Extensible Firmware Interface Specification (UEFI) [1] has become |
| 8 | the default for booting on AArch64 and x86 systems. It provides a stable API for |
| 9 | the interaction of drivers and applications with the firmware. The API comprises |
| 10 | access to block storage, network, and console to name a few. The Linux kernel |
| 11 | and boot loaders like GRUB or the FreeBSD loader can be executed. |
| 12 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 13 | Development target |
| 14 | ------------------ |
Heinrich Schuchardt | a28d073 | 2019-03-28 08:09:16 +0100 | [diff] [blame] | 15 | |
Heinrich Schuchardt | 9ec8f5e | 2019-04-10 08:04:38 +0200 | [diff] [blame] | 16 | The implementation of UEFI in U-Boot strives to reach the requirements described |
Vincent Stehlé | c53cec6 | 2022-12-16 17:55:04 +0100 | [diff] [blame] | 17 | in the "Embedded Base Boot Requirements (EBBR) Specification - Release v2.1.0" |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 18 | [2]. The "Server Base Boot Requirements System Software on ARM Platforms" [3] |
Heinrich Schuchardt | 9ec8f5e | 2019-04-10 08:04:38 +0200 | [diff] [blame] | 19 | describes a superset of the EBBR specification and may be used as further |
| 20 | reference. |
Heinrich Schuchardt | a28d073 | 2019-03-28 08:09:16 +0100 | [diff] [blame] | 21 | |
| 22 | A full blown UEFI implementation would contradict the U-Boot design principle |
| 23 | "keep it small". |
| 24 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 25 | Building U-Boot for UEFI |
| 26 | ------------------------ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 27 | |
Heinrich Schuchardt | 1028840 | 2018-12-30 12:54:36 +0100 | [diff] [blame] | 28 | The UEFI standard supports only little-endian systems. The UEFI support can be |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 29 | activated for ARM and x86 by specifying:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 30 | |
| 31 | CONFIG_CMD_BOOTEFI=y |
| 32 | CONFIG_EFI_LOADER=y |
| 33 | |
| 34 | in the .config file. |
| 35 | |
| 36 | Support for attaching virtual block devices, e.g. iSCSI drives connected by the |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 37 | loaded UEFI application [4], requires:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 38 | |
| 39 | CONFIG_BLK=y |
| 40 | CONFIG_PARTITIONS=y |
| 41 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 42 | Executing a UEFI binary |
| 43 | ~~~~~~~~~~~~~~~~~~~~~~~ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 44 | |
| 45 | The bootefi command is used to start UEFI applications or to install UEFI |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 46 | drivers. It takes two parameters:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 47 | |
| 48 | bootefi <image address> [fdt address] |
| 49 | |
| 50 | * image address - the memory address of the UEFI binary |
| 51 | * fdt address - the memory address of the flattened device tree |
| 52 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 53 | Below you find the output of an example session starting GRUB:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 54 | |
| 55 | => load mmc 0:2 ${fdt_addr_r} boot/dtb |
| 56 | 29830 bytes read in 14 ms (2 MiB/s) |
| 57 | => load mmc 0:1 ${kernel_addr_r} efi/debian/grubaa64.efi |
| 58 | reading efi/debian/grubaa64.efi |
| 59 | 120832 bytes read in 7 ms (16.5 MiB/s) |
| 60 | => bootefi ${kernel_addr_r} ${fdt_addr_r} |
| 61 | |
Heinrich Schuchardt | 6b82159 | 2021-01-12 12:46:24 +0100 | [diff] [blame] | 62 | When booting from a memory location it is unknown from which file it was loaded. |
| 63 | Therefore the bootefi command uses the device path of the block device partition |
| 64 | or the network adapter and the file name of the most recently loaded PE-COFF |
| 65 | file when setting up the loaded image protocol. |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 66 | |
Cristian Ciocaltea | 62bb890 | 2019-12-24 18:05:41 +0200 | [diff] [blame] | 67 | Launching a UEFI binary from a FIT image |
| 68 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 69 | |
| 70 | A signed FIT image can be used to securely boot a UEFI image via the |
| 71 | bootm command. This feature is available if U-Boot is configured with:: |
| 72 | |
| 73 | CONFIG_BOOTM_EFI=y |
| 74 | |
| 75 | A sample configuration is provided as file doc/uImage.FIT/uefi.its. |
| 76 | |
| 77 | Below you find the output of an example session starting GRUB:: |
| 78 | |
| 79 | => load mmc 0:1 ${kernel_addr_r} image.fit |
| 80 | 4620426 bytes read in 83 ms (53.1 MiB/s) |
| 81 | => bootm ${kernel_addr_r}#config-grub-nofdt |
| 82 | ## Loading kernel from FIT Image at 40400000 ... |
| 83 | Using 'config-grub-nofdt' configuration |
| 84 | Verifying Hash Integrity ... sha256,rsa2048:dev+ OK |
| 85 | Trying 'efi-grub' kernel subimage |
| 86 | Description: GRUB EFI Firmware |
| 87 | Created: 2019-11-20 8:18:16 UTC |
| 88 | Type: Kernel Image (no loading done) |
| 89 | Compression: uncompressed |
| 90 | Data Start: 0x404000d0 |
| 91 | Data Size: 450560 Bytes = 440 KiB |
| 92 | Hash algo: sha256 |
| 93 | Hash value: 4dbee00021112df618f58b3f7cf5e1595533d543094064b9ce991e8b054a9eec |
| 94 | Verifying Hash Integrity ... sha256+ OK |
| 95 | XIP Kernel Image (no loading done) |
| 96 | ## Transferring control to EFI (at address 404000d0) ... |
| 97 | Welcome to GRUB! |
| 98 | |
| 99 | See doc/uImage.FIT/howto.txt for an introduction to FIT images. |
| 100 | |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 101 | Configuring UEFI secure boot |
| 102 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 103 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 104 | The UEFI specification[1] defines a secure way of executing UEFI images |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 105 | by verifying a signature (or message digest) of image with certificates. |
| 106 | This feature on U-Boot is enabled with:: |
| 107 | |
Jan Kiszka | 2191390 | 2022-03-16 12:12:16 +0100 | [diff] [blame] | 108 | CONFIG_EFI_SECURE_BOOT=y |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 109 | |
| 110 | To make the boot sequence safe, you need to establish a chain of trust; |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 111 | In UEFI secure boot the chain trust is defined by the following UEFI variables |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 112 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 113 | * PK - Platform Key |
| 114 | * KEK - Key Exchange Keys |
| 115 | * db - white list database |
| 116 | * dbx - black list database |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 117 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 118 | An in depth description of UEFI secure boot is beyond the scope of this |
| 119 | document. Please, refer to the UEFI specification and available online |
| 120 | documentation. Here is a simple example that you can follow for your initial |
| 121 | attempt (Please note that the actual steps will depend on your system and |
| 122 | environment.): |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 123 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 124 | Install the required tools on your host |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 125 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 126 | * openssl |
| 127 | * efitools |
| 128 | * sbsigntool |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 129 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 130 | Create signing keys and the key database on your host: |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 131 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 132 | The platform key |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 133 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 134 | .. code-block:: bash |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 135 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 136 | openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_PK/ \ |
| 137 | -keyout PK.key -out PK.crt -nodes -days 365 |
| 138 | cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ |
| 139 | PK.crt PK.esl; |
| 140 | sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 141 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 142 | The key exchange keys |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 143 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 144 | .. code-block:: bash |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 145 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 146 | openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_KEK/ \ |
| 147 | -keyout KEK.key -out KEK.crt -nodes -days 365 |
| 148 | cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ |
| 149 | KEK.crt KEK.esl |
| 150 | sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 151 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 152 | The whitelist database |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 153 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 154 | .. code-block:: bash |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 155 | |
Heinrich Schuchardt | 200584c | 2020-12-12 09:15:12 +0100 | [diff] [blame] | 156 | openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \ |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 157 | -keyout db.key -out db.crt -nodes -days 365 |
Heinrich Schuchardt | 200584c | 2020-12-12 09:15:12 +0100 | [diff] [blame] | 158 | cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \ |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 159 | db.crt db.esl |
Heinrich Schuchardt | 200584c | 2020-12-12 09:15:12 +0100 | [diff] [blame] | 160 | sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 161 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 162 | Copy the \*.auth files to media, say mmc, that is accessible from U-Boot. |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 163 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 164 | Sign an image with one of the keys in "db" on your host |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 165 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 166 | .. code-block:: bash |
| 167 | |
| 168 | sbsign --key db.key --cert db.crt helloworld.efi |
| 169 | |
| 170 | Now in U-Boot install the keys on your board:: |
| 171 | |
| 172 | fatload mmc 0:1 <tmpaddr> PK.auth |
Heinrich Schuchardt | fa11c86 | 2020-08-24 08:27:49 +0200 | [diff] [blame] | 173 | setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize PK |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 174 | fatload mmc 0:1 <tmpaddr> KEK.auth |
Heinrich Schuchardt | fa11c86 | 2020-08-24 08:27:49 +0200 | [diff] [blame] | 175 | setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize KEK |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 176 | fatload mmc 0:1 <tmpaddr> db.auth |
Heinrich Schuchardt | fa11c86 | 2020-08-24 08:27:49 +0200 | [diff] [blame] | 177 | setenv -e -nv -bs -rt -at -i <tmpaddr>:$filesize db |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 178 | |
| 179 | Set up boot parameters on your board:: |
| 180 | |
Ilias Apalodimas | 773c090 | 2021-03-17 21:55:01 +0200 | [diff] [blame] | 181 | efidebug boot add -b 1 HELLO mmc 0:1 /helloworld.efi.signed "" |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 182 | |
Ilias Apalodimas | c92aa4b | 2021-03-17 21:55:02 +0200 | [diff] [blame] | 183 | Since kernel 5.7 there's an alternative way of loading an initrd using |
| 184 | LoadFile2 protocol if CONFIG_EFI_LOAD_FILE2_INITRD is enabled. |
| 185 | The initrd path can be specified with:: |
| 186 | |
| 187 | efidebug boot add -b ABE0 'kernel' mmc 0:1 Image -i mmc 0:1 initrd |
| 188 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 189 | Now your board can run the signed image via the boot manager (see below). |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 190 | You can also try this sequence by running Pytest, test_efi_secboot, |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 191 | on the sandbox |
| 192 | |
| 193 | .. code-block:: bash |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 194 | |
Heinrich Schuchardt | 664ad18 | 2020-04-16 20:31:56 +0200 | [diff] [blame] | 195 | cd <U-Boot source directory> |
| 196 | pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox |
AKASHI Takahiro | e674d8d | 2020-04-14 11:51:54 +0900 | [diff] [blame] | 197 | |
Heinrich Schuchardt | 87f43de | 2020-07-14 12:52:51 +0200 | [diff] [blame] | 198 | UEFI binaries may be signed by Microsoft using the following certificates: |
| 199 | |
| 200 | * KEK: Microsoft Corporation KEK CA 2011 |
| 201 | http://go.microsoft.com/fwlink/?LinkId=321185. |
| 202 | * db: Microsoft Windows Production PCA 2011 |
| 203 | http://go.microsoft.com/fwlink/p/?linkid=321192. |
| 204 | * db: Microsoft Corporation UEFI CA 2011 |
| 205 | http://go.microsoft.com/fwlink/p/?linkid=321194. |
| 206 | |
Ilias Apalodimas | ef8bd41 | 2020-05-17 22:25:47 +0300 | [diff] [blame] | 207 | Using OP-TEE for EFI variables |
| 208 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 209 | |
| 210 | Instead of implementing UEFI variable services inside U-Boot they can |
| 211 | also be provided in the secure world by a module for OP-TEE[1]. The |
| 212 | interface between U-Boot and OP-TEE for variable services is enabled by |
| 213 | CONFIG_EFI_MM_COMM_TEE=y. |
| 214 | |
| 215 | Tianocore EDK II's standalone management mode driver for variables can |
| 216 | be linked to OP-TEE for this purpose. This module uses the Replay |
| 217 | Protected Memory Block (RPMB) of an eMMC device for persisting |
| 218 | non-volatile variables. When calling the variable services via the |
| 219 | OP-TEE API U-Boot's OP-TEE supplicant relays calls to the RPMB driver |
| 220 | which has to be enabled via CONFIG_SUPPORT_EMMC_RPMB=y. |
| 221 | |
Ilias Apalodimas | a300e44 | 2021-04-01 13:35:38 +0300 | [diff] [blame] | 222 | EDK2 Build instructions |
| 223 | *********************** |
| 224 | |
| 225 | .. code-block:: bash |
| 226 | |
| 227 | $ git clone https://github.com/tianocore/edk2.git |
| 228 | $ git clone https://github.com/tianocore/edk2-platforms.git |
| 229 | $ cd edk2 |
| 230 | $ git submodule init && git submodule update --init --recursive |
| 231 | $ cd .. |
| 232 | $ export WORKSPACE=$(pwd) |
| 233 | $ export PACKAGES_PATH=$WORKSPACE/edk2:$WORKSPACE/edk2-platforms |
| 234 | $ export ACTIVE_PLATFORM="Platform/StandaloneMm/PlatformStandaloneMmPkg/PlatformStandaloneMmRpmb.dsc" |
| 235 | $ export GCC5_AARCH64_PREFIX=aarch64-linux-gnu- |
| 236 | $ source edk2/edksetup.sh |
| 237 | $ make -C edk2/BaseTools |
| 238 | $ build -p $ACTIVE_PLATFORM -b RELEASE -a AARCH64 -t GCC5 -n `nproc` |
| 239 | |
| 240 | OP-TEE Build instructions |
| 241 | ************************* |
| 242 | |
| 243 | .. code-block:: bash |
| 244 | |
| 245 | $ git clone https://github.com/OP-TEE/optee_os.git |
| 246 | $ cd optee_os |
| 247 | $ ln -s ../Build/MmStandaloneRpmb/RELEASE_GCC5/FV/BL32_AP_MM.fd |
| 248 | $ export ARCH=arm |
| 249 | $ CROSS_COMPILE32=arm-linux-gnueabihf- make -j32 CFG_ARM64_core=y \ |
| 250 | PLATFORM=<myboard> CFG_STMM_PATH=BL32_AP_MM.fd CFG_RPMB_FS=y \ |
Ilias Apalodimas | 63cc27a | 2021-12-27 10:08:15 +0200 | [diff] [blame] | 251 | CFG_RPMB_FS_DEV_ID=0 CFG_CORE_HEAP_SIZE=524288 CFG_RPMB_WRITE_KEY=y \ |
| 252 | CFG_CORE_DYN_SHM=y CFG_RPMB_TESTKEY=y CFG_REE_FS=n \ |
| 253 | CFG_CORE_ARM64_PA_BITS=48 CFG_TEE_CORE_LOG_LEVEL=1 \ |
Ilias Apalodimas | a300e44 | 2021-04-01 13:35:38 +0300 | [diff] [blame] | 254 | CFG_TEE_TA_LOG_LEVEL=1 CFG_SCTLR_ALIGNMENT_CHECK=n |
| 255 | |
| 256 | U-Boot Build instructions |
| 257 | ************************* |
| 258 | |
| 259 | Although the StandAloneMM binary comes from EDK2, using and storing the |
| 260 | variables is currently available in U-Boot only. |
| 261 | |
| 262 | .. code-block:: bash |
| 263 | |
| 264 | $ git clone https://github.com/u-boot/u-boot.git |
| 265 | $ cd u-boot |
| 266 | $ export CROSS_COMPILE=aarch64-linux-gnu- |
| 267 | $ export ARCH=<arch> |
| 268 | $ make <myboard>_defconfig |
| 269 | $ make menuconfig |
| 270 | |
| 271 | Enable ``CONFIG_OPTEE``, ``CONFIG_CMD_OPTEE_RPMB`` and ``CONFIG_EFI_MM_COMM_TEE`` |
| 272 | |
| 273 | .. warning:: |
| 274 | |
| 275 | - Your OP-TEE platform port must support Dynamic shared memory, since that's |
| 276 | the only kind of memory U-Boot supports for now. |
| 277 | |
| 278 | [1] https://optee.readthedocs.io/en/latest/building/efi_vars/stmm.html |
Ilias Apalodimas | ef8bd41 | 2020-05-17 22:25:47 +0300 | [diff] [blame] | 279 | |
Sughosh Ganu | b08b857 | 2022-10-21 18:16:08 +0530 | [diff] [blame] | 280 | .. _uefi_capsule_update_ref: |
| 281 | |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 282 | Enabling UEFI Capsule Update feature |
| 283 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 284 | |
| 285 | Support has been added for the UEFI capsule update feature which |
| 286 | enables updating the U-Boot image using the UEFI firmware management |
| 287 | protocol (FMP). The capsules are not passed to the firmware through |
| 288 | the UpdateCapsule runtime service. Instead, capsule-on-disk |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 289 | functionality is used for fetching capsules from the EFI System |
| 290 | Partition (ESP) by placing capsule files under the directory:: |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 291 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 292 | \EFI\UpdateCapsule |
| 293 | |
| 294 | The directory is checked for capsules only within the |
| 295 | EFI system partition on the device specified in the active boot option, |
| 296 | which is determined by BootXXXX variable in BootNext, or if not, the highest |
| 297 | priority one within BootOrder. Any BootXXXX variables referring to devices |
| 298 | not present are ignored when determining the active boot option. |
| 299 | |
| 300 | Please note that capsules will be applied in the alphabetic order of |
| 301 | capsule file names. |
| 302 | |
| 303 | Creating a capsule file |
| 304 | *********************** |
| 305 | |
| 306 | A capsule file can be created by using tools/mkeficapsule. |
| 307 | To build this tool, enable:: |
| 308 | |
| 309 | CONFIG_TOOLS_MKEFICAPSULE=y |
| 310 | CONFIG_TOOLS_LIBCRYPTO=y |
| 311 | |
| 312 | Run the following command |
| 313 | |
| 314 | .. code-block:: console |
| 315 | |
| 316 | $ mkeficapsule \ |
Sughosh Ganu | 50ec472 | 2022-04-15 11:29:41 +0530 | [diff] [blame] | 317 | --index <index> --instance 0 \ |
| 318 | --guid <image GUID> \ |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 319 | <capsule_file_name> |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 320 | |
Masahisa Kojima | d20d4c4 | 2023-06-07 14:41:57 +0900 | [diff] [blame] | 321 | The UEFI specification does not define the firmware versioning mechanism. |
| 322 | EDK II reference implementation inserts the FMP Payload Header right before |
| 323 | the payload. It coutains the fw_version and lowest supported version, |
| 324 | EDK II reference implementation uses these information to implement the |
| 325 | firmware versioning and anti-rollback protection, the firmware version and |
| 326 | lowest supported version is stored into EFI non-volatile variable. |
| 327 | |
| 328 | In U-Boot, the firmware versioning is implemented utilizing |
| 329 | the FMP Payload Header same as EDK II reference implementation, |
| 330 | reads the FMP Payload Header and stores the firmware version into |
| 331 | "FmpStateXXXX" EFI non-volatile variable. XXXX indicates the image index, |
| 332 | since FMP protocol handles multiple image indexes. |
| 333 | |
| 334 | To add the fw_version into the FMP Payload Header, |
| 335 | add --fw-version option in mkeficapsule tool. |
| 336 | |
| 337 | .. code-block:: console |
| 338 | |
| 339 | $ mkeficapsule \ |
| 340 | --index <index> --instance 0 \ |
| 341 | --guid <image GUID> \ |
| 342 | --fw-version 5 \ |
| 343 | <capsule_file_name> |
| 344 | |
| 345 | If the --fw-version option is not set, FMP Payload Header is not inserted |
| 346 | and fw_version is set as 0. |
| 347 | |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 348 | Performing the update |
| 349 | ********************* |
| 350 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 351 | Put capsule files under the directory mentioned above. |
| 352 | Then, following the UEFI specification, you'll need to set |
| 353 | the EFI_OS_INDICATIONS_FILE_CAPSULE_DELIVERY_SUPPORTED |
| 354 | bit in OsIndications variable with |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 355 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 356 | .. code-block:: console |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 357 | |
Sughosh Ganu | fddb136 | 2022-05-31 12:45:35 +0530 | [diff] [blame] | 358 | => setenv -e -nv -bs -rt -v OsIndications =0x0000000000000004 |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 359 | |
Michal Simek | 50fa118 | 2023-05-17 09:17:16 +0200 | [diff] [blame] | 360 | Since U-Boot doesn't currently support SetVariable at runtime, its value |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 361 | won't be taken over across the reboot. If this is the case, you can skip |
| 362 | this feature check with the Kconfig option (CONFIG_EFI_IGNORE_OSINDICATIONS) |
| 363 | set. |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 364 | |
Sughosh Ganu | 50ec472 | 2022-04-15 11:29:41 +0530 | [diff] [blame] | 365 | A few values need to be defined in the board file for performing the |
| 366 | capsule update. These values are defined in the board file by |
| 367 | initialisation of a structure which provides information needed for |
| 368 | capsule updates. The following structures have been defined for |
| 369 | containing the image related information |
| 370 | |
| 371 | .. code-block:: c |
| 372 | |
| 373 | struct efi_fw_image { |
| 374 | efi_guid_t image_type_id; |
| 375 | u16 *fw_name; |
| 376 | u8 image_index; |
| 377 | }; |
| 378 | |
| 379 | struct efi_capsule_update_info { |
| 380 | const char *dfu_string; |
| 381 | struct efi_fw_image *images; |
| 382 | }; |
| 383 | |
| 384 | |
| 385 | A string is defined which is to be used for populating the |
| 386 | dfu_alt_info variable. This string is used by the function |
| 387 | set_dfu_alt_info. Instead of taking the variable from the environment, |
| 388 | the capsule update feature requires that the variable be set through |
| 389 | the function, since that is more robust. Allowing the user to change |
| 390 | the location of the firmware updates is not a very secure |
| 391 | practice. Getting this information from the firmware itself is more |
| 392 | secure, assuming the firmware has been verified by a previous stage |
| 393 | boot loader. |
| 394 | |
| 395 | The firmware images structure defines the GUID values, image index |
| 396 | values and the name of the images that are to be updated through |
| 397 | the capsule update feature. These values are to be defined as part of |
| 398 | an array. These GUID values would be used by the Firmware Management |
| 399 | Protocol(FMP) to populate the image descriptor array and also |
| 400 | displayed as part of the ESRT table. The image index values defined in |
| 401 | the array should be one greater than the dfu alt number that |
| 402 | corresponds to the firmware image. So, if the dfu alt number for an |
| 403 | image is 2, the value of image index in the fw_images array for that |
| 404 | image should be 3. The dfu alt number can be obtained by running the |
| 405 | following command:: |
| 406 | |
| 407 | dfu list |
| 408 | |
Sughosh Ganu | b08b857 | 2022-10-21 18:16:08 +0530 | [diff] [blame] | 409 | When the FWU Multi Bank Update feature is enabled on the platform, the |
| 410 | image index is used only to identify the image index with the image |
| 411 | GUID. The image index would not correspond to the dfu alt number. This |
| 412 | is because the FWU feature supports multiple partitions(banks) of |
| 413 | updatable images, and the actual dfu alt number to which the image is |
| 414 | to be written to is determined at runtime, based on the value of the |
| 415 | update bank to which the image is to be written. For more information |
Vincent Stehlé | ecf2151 | 2023-02-20 15:37:29 +0100 | [diff] [blame] | 416 | on the FWU Multi Bank Update feature, please refer to |
| 417 | :doc:`/develop/uefi/fwu_updates`. |
Sughosh Ganu | b08b857 | 2022-10-21 18:16:08 +0530 | [diff] [blame] | 418 | |
Sughosh Ganu | 50ec472 | 2022-04-15 11:29:41 +0530 | [diff] [blame] | 419 | When using the FMP for FIT images, the image index value needs to be |
| 420 | set to 1. |
| 421 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 422 | Finally, the capsule update can be initiated by rebooting the board. |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 423 | |
Sughosh Ganu | 50ec472 | 2022-04-15 11:29:41 +0530 | [diff] [blame] | 424 | An example of setting the values in the struct efi_fw_image and |
| 425 | struct efi_capsule_update_info is shown below |
| 426 | |
| 427 | .. code-block:: c |
| 428 | |
| 429 | struct efi_fw_image fw_images[] = { |
| 430 | { |
| 431 | .image_type_id = DEVELOPERBOX_UBOOT_IMAGE_GUID, |
| 432 | .fw_name = u"DEVELOPERBOX-UBOOT", |
| 433 | .image_index = 1, |
| 434 | }, |
| 435 | { |
| 436 | .image_type_id = DEVELOPERBOX_FIP_IMAGE_GUID, |
| 437 | .fw_name = u"DEVELOPERBOX-FIP", |
| 438 | .image_index = 2, |
| 439 | }, |
| 440 | { |
| 441 | .image_type_id = DEVELOPERBOX_OPTEE_IMAGE_GUID, |
| 442 | .fw_name = u"DEVELOPERBOX-OPTEE", |
| 443 | .image_index = 3, |
| 444 | }, |
| 445 | }; |
| 446 | |
| 447 | struct efi_capsule_update_info update_info = { |
| 448 | .dfu_string = "mtd nor1=u-boot.bin raw 200000 100000;" |
| 449 | "fip.bin raw 180000 78000;" |
| 450 | "optee.bin raw 500000 100000", |
| 451 | .images = fw_images, |
| 452 | }; |
| 453 | |
| 454 | Platforms must declare a variable update_info of type struct |
| 455 | efi_capsule_update_info as shown in the example above. The platform |
| 456 | will also define a fw_images array which contains information of all |
| 457 | the firmware images that are to be updated through capsule update |
| 458 | mechanism. The dfu_string is the string that is to be set as |
| 459 | dfu_alt_info. In the example above, the image index to be set for |
| 460 | u-boot.bin binary is 0x1, for fip.bin is 0x2 and for optee.bin is 0x3. |
| 461 | |
| 462 | As an example, for generating the capsule for the optee.bin image, the |
| 463 | following command can be issued |
| 464 | |
| 465 | .. code-block:: bash |
| 466 | |
| 467 | $ ./tools/mkeficapsule \ |
| 468 | --index 0x3 --instance 0 \ |
| 469 | --guid c1b629f1-ce0e-4894-82bf-f0a38387e630 \ |
| 470 | optee.bin optee.capsule |
| 471 | |
| 472 | |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 473 | Enabling Capsule Authentication |
| 474 | ******************************* |
| 475 | |
| 476 | The UEFI specification defines a way of authenticating the capsule to |
| 477 | be updated by verifying the capsule signature. The capsule signature |
| 478 | is computed and prepended to the capsule payload at the time of |
| 479 | capsule generation. This signature is then verified by using the |
| 480 | public key stored as part of the X509 certificate. This certificate is |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 481 | in the form of an efi signature list (esl) file, which is embedded in |
| 482 | a device tree. |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 483 | |
| 484 | The capsule authentication feature can be enabled through the |
| 485 | following config, in addition to the configs listed above for capsule |
| 486 | update:: |
| 487 | |
| 488 | CONFIG_EFI_CAPSULE_AUTHENTICATE=y |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 489 | |
| 490 | The public and private keys used for the signing process are generated |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 491 | and used by the steps highlighted below. |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 492 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 493 | 1. Install utility commands on your host |
| 494 | * openssl |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 495 | * efitools |
| 496 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 497 | 2. Create signing keys and certificate files on your host |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 498 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 499 | .. code-block:: console |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 500 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 501 | $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ \ |
| 502 | -keyout CRT.key -out CRT.crt -nodes -days 365 |
| 503 | $ cert-to-efi-sig-list CRT.crt CRT.esl |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 504 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 505 | 3. Run the following command to create and sign the capsule file |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 506 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 507 | .. code-block:: console |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 508 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 509 | $ mkeficapsule --monotonic-count 1 \ |
| 510 | --private-key CRT.key \ |
| 511 | --certificate CRT.crt \ |
| 512 | --index 1 --instance 0 \ |
AKASHI Takahiro | ba21243 | 2022-02-09 19:10:39 +0900 | [diff] [blame] | 513 | [--fit | --raw | --guid <guid-string] \ |
| 514 | <image_blob> <capsule_file_name> |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 515 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 516 | 4. Insert the signature list into a device tree in the following format:: |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 517 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 518 | { |
| 519 | signature { |
| 520 | capsule-key = [ <binary of signature list> ]; |
| 521 | } |
| 522 | ... |
| 523 | } |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 524 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 525 | You can do step-4 manually with |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 526 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 527 | .. code-block:: console |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 528 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 529 | $ dtc -@ -I dts -O dtb -o signature.dtbo signature.dts |
| 530 | $ fdtoverlay -i orig.dtb -o new.dtb -v signature.dtbo |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 531 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 532 | where signature.dts looks like:: |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 533 | |
AKASHI Takahiro | a7159db | 2022-02-09 19:10:37 +0900 | [diff] [blame] | 534 | &{/} { |
| 535 | signature { |
| 536 | capsule-key = /incbin/("CRT.esl"); |
| 537 | }; |
| 538 | }; |
AKASHI Takahiro | 60fc0c6 | 2021-10-07 15:23:31 +0900 | [diff] [blame] | 539 | |
Masahisa Kojima | 475a4f7 | 2023-06-07 14:41:58 +0900 | [diff] [blame] | 540 | Anti-rollback Protection |
| 541 | ************************ |
| 542 | |
| 543 | Anti-rollback prevents unintentional installation of outdated firmware. |
| 544 | To enable anti-rollback, you must add the lowest-supported-version property |
| 545 | to dtb and specify --fw-version when creating a capsule file with the |
| 546 | mkeficapsule tool. |
| 547 | When executing capsule update, U-Boot checks if fw_version is greater than |
| 548 | or equal to lowest-supported-version. If fw_version is less than |
| 549 | lowest-supported-version, the update will fail. |
| 550 | For example, if lowest-supported-version is set to 7 and you run capsule |
| 551 | update using a capsule file with --fw-version of 5, the update will fail. |
| 552 | When the --fw-version in the capsule file is updated, lowest-supported-version |
| 553 | in the dtb might be updated accordingly. |
| 554 | |
| 555 | To insert the lowest supported version into a dtb |
| 556 | |
| 557 | .. code-block:: console |
| 558 | |
| 559 | $ dtc -@ -I dts -O dtb -o version.dtbo version.dts |
| 560 | $ fdtoverlay -i orig.dtb -o new.dtb -v version.dtbo |
| 561 | |
| 562 | where version.dts looks like:: |
| 563 | |
| 564 | /dts-v1/; |
| 565 | /plugin/; |
| 566 | &{/} { |
| 567 | firmware-version { |
| 568 | image1 { |
| 569 | image-type-id = "09D7CF52-0720-4710-91D1-08469B7FE9C8"; |
| 570 | image-index = <1>; |
| 571 | lowest-supported-version = <3>; |
| 572 | }; |
| 573 | }; |
| 574 | }; |
| 575 | |
| 576 | The properties of image-type-id and image-index must match the value |
| 577 | defined in the efi_fw_image array as image_type_id and image_index. |
| 578 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 579 | Executing the boot manager |
| 580 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 581 | |
Heinrich Schuchardt | 8d343f8 | 2020-08-16 12:27:19 +0200 | [diff] [blame] | 582 | The UEFI specification foresees to define boot entries and boot sequence via |
| 583 | UEFI variables. Booting according to these variables is possible via:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 584 | |
| 585 | bootefi bootmgr [fdt address] |
| 586 | |
Heinrich Schuchardt | 8d343f8 | 2020-08-16 12:27:19 +0200 | [diff] [blame] | 587 | As of U-Boot v2020.10 UEFI variables cannot be set at runtime. The U-Boot |
| 588 | command 'efidebug' can be used to set the variables. |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 589 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 590 | Executing the built in hello world application |
| 591 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 592 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 593 | A hello world UEFI application can be built with:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 594 | |
| 595 | CONFIG_CMD_BOOTEFI_HELLO_COMPILE=y |
| 596 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 597 | It can be embedded into the U-Boot binary with:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 598 | |
| 599 | CONFIG_CMD_BOOTEFI_HELLO=y |
| 600 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 601 | The bootefi command is used to start the embedded hello world application:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 602 | |
| 603 | bootefi hello [fdt address] |
| 604 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 605 | Below you find the output of an example session:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 606 | |
| 607 | => bootefi hello ${fdtcontroladdr} |
| 608 | ## Starting EFI application at 01000000 ... |
| 609 | WARNING: using memory device/image path, this may confuse some payloads! |
| 610 | Hello, world! |
| 611 | Running on UEFI 2.7 |
| 612 | Have SMBIOS table |
| 613 | Have device tree |
| 614 | Load options: root=/dev/sdb3 init=/sbin/init rootwait ro |
| 615 | ## Application terminated, r = 0 |
| 616 | |
| 617 | The environment variable fdtcontroladdr points to U-Boot's internal device tree |
| 618 | (if available). |
| 619 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 620 | Executing the built-in self-test |
| 621 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 622 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 623 | An UEFI self-test suite can be embedded in U-Boot by building with:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 624 | |
| 625 | CONFIG_CMD_BOOTEFI_SELFTEST=y |
| 626 | |
| 627 | For testing the UEFI implementation the bootefi command can be used to start the |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 628 | self-test:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 629 | |
| 630 | bootefi selftest [fdt address] |
| 631 | |
| 632 | The environment variable 'efi_selftest' can be used to select a single test. If |
| 633 | it is not provided all tests are executed except those marked as 'on request'. |
| 634 | If the environment variable is set to 'list' a list of all tests is shown. |
| 635 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 636 | Below you can find the output of an example session:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 637 | |
| 638 | => setenv efi_selftest simple network protocol |
| 639 | => bootefi selftest |
| 640 | Testing EFI API implementation |
| 641 | Selected test: 'simple network protocol' |
| 642 | Setting up 'simple network protocol' |
| 643 | Setting up 'simple network protocol' succeeded |
| 644 | Executing 'simple network protocol' |
| 645 | DHCP Discover |
| 646 | DHCP reply received from 192.168.76.2 (52:55:c0:a8:4c:02) |
| 647 | as broadcast message. |
| 648 | Executing 'simple network protocol' succeeded |
| 649 | Tearing down 'simple network protocol' |
| 650 | Tearing down 'simple network protocol' succeeded |
| 651 | Boot services terminated |
| 652 | Summary: 0 failures |
| 653 | Preparing for reset. Press any key. |
| 654 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 655 | The UEFI life cycle |
| 656 | ------------------- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 657 | |
| 658 | After the U-Boot platform has been initialized the UEFI API provides two kinds |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 659 | of services: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 660 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 661 | * boot services |
| 662 | * runtime services |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 663 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 664 | The API can be extended by loading UEFI drivers which come in two variants: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 665 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 666 | * boot drivers |
| 667 | * runtime drivers |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 668 | |
| 669 | UEFI drivers are installed with U-Boot's bootefi command. With the same command |
| 670 | UEFI applications can be executed. |
| 671 | |
| 672 | Loaded images of UEFI drivers stay in memory after returning to U-Boot while |
| 673 | loaded images of applications are removed from memory. |
| 674 | |
| 675 | An UEFI application (e.g. an operating system) that wants to take full control |
| 676 | of the system calls ExitBootServices. After a UEFI application calls |
| 677 | ExitBootServices |
| 678 | |
| 679 | * boot services are not available anymore |
| 680 | * timer events are stopped |
| 681 | * the memory used by U-Boot except for runtime services is released |
| 682 | * the memory used by boot time drivers is released |
| 683 | |
| 684 | So this is a point of no return. Afterwards the UEFI application can only return |
| 685 | to U-Boot by rebooting. |
| 686 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 687 | The UEFI object model |
| 688 | --------------------- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 689 | |
| 690 | UEFI offers a flexible and expandable object model. The objects in the UEFI API |
| 691 | are devices, drivers, and loaded images. These objects are referenced by |
| 692 | handles. |
| 693 | |
| 694 | The interfaces implemented by the objects are referred to as protocols. These |
| 695 | are identified by GUIDs. They can be installed and uninstalled by calling the |
| 696 | appropriate boot services. |
| 697 | |
| 698 | Handles are created by the InstallProtocolInterface or the |
| 699 | InstallMultipleProtocolinterfaces service if NULL is passed as handle. |
| 700 | |
| 701 | Handles are deleted when the last protocol has been removed with the |
| 702 | UninstallProtocolInterface or the UninstallMultipleProtocolInterfaces service. |
| 703 | |
| 704 | Devices offer the EFI_DEVICE_PATH_PROTOCOL. A device path is the concatenation |
| 705 | of device nodes. By their device paths all devices of a system are arranged in a |
| 706 | tree. |
| 707 | |
| 708 | Drivers offer the EFI_DRIVER_BINDING_PROTOCOL. This protocol is used to connect |
| 709 | a driver to devices (which are referenced as controllers in this context). |
| 710 | |
| 711 | Loaded images offer the EFI_LOADED_IMAGE_PROTOCOL. This protocol provides meta |
| 712 | information about the image and a pointer to the unload callback function. |
| 713 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 714 | The UEFI events |
| 715 | --------------- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 716 | |
| 717 | In the UEFI terminology an event is a data object referencing a notification |
| 718 | function which is queued for calling when the event is signaled. The following |
| 719 | types of events exist: |
| 720 | |
| 721 | * periodic and single shot timer events |
| 722 | * exit boot services events, triggered by calling the ExitBootServices() service |
| 723 | * virtual address change events |
| 724 | * memory map change events |
| 725 | * read to boot events |
| 726 | * reset system events |
| 727 | * system table events |
| 728 | * events that are only triggered programmatically |
| 729 | |
| 730 | Events can be created with the CreateEvent service and deleted with CloseEvent |
| 731 | service. |
| 732 | |
| 733 | Events can be assigned to an event group. If any of the events in a group is |
| 734 | signaled, all other events in the group are also set to the signaled state. |
| 735 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 736 | The UEFI driver model |
| 737 | --------------------- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 738 | |
| 739 | A driver is specific for a single protocol installed on a device. To install a |
| 740 | driver on a device the ConnectController service is called. In this context |
| 741 | controller refers to the device for which the driver is installed. |
| 742 | |
| 743 | The relevant drivers are identified using the EFI_DRIVER_BINDING_PROTOCOL. This |
| 744 | protocol has has three functions: |
| 745 | |
| 746 | * supported - determines if the driver is compatible with the device |
| 747 | * start - installs the driver by opening the relevant protocol with |
| 748 | attribute EFI_OPEN_PROTOCOL_BY_DRIVER |
| 749 | * stop - uninstalls the driver |
| 750 | |
| 751 | The driver may create child controllers (child devices). E.g. a driver for block |
| 752 | IO devices will create the device handles for the partitions. The child |
| 753 | controllers will open the supported protocol with the attribute |
| 754 | EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER. |
| 755 | |
| 756 | A driver can be detached from a device using the DisconnectController service. |
| 757 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 758 | U-Boot devices mapped as UEFI devices |
| 759 | ------------------------------------- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 760 | |
| 761 | Some of the U-Boot devices are mapped as UEFI devices |
| 762 | |
| 763 | * block IO devices |
| 764 | * console |
| 765 | * graphical output |
| 766 | * network adapter |
| 767 | |
| 768 | As of U-Boot 2018.03 the logic for doing this is hard coded. |
| 769 | |
| 770 | The development target is to integrate the setup of these UEFI devices with the |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 771 | U-Boot driver model [5]. So when a U-Boot device is discovered a handle should |
| 772 | be created and the device path protocol and the relevant IO protocol should be |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 773 | installed. The UEFI driver then would be attached by calling ConnectController. |
| 774 | When a U-Boot device is removed DisconnectController should be called. |
| 775 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 776 | UEFI devices mapped as U-Boot devices |
| 777 | ------------------------------------- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 778 | |
| 779 | UEFI drivers binaries and applications may create new (virtual) devices, install |
| 780 | a protocol and call the ConnectController service. Now the matching UEFI driver |
| 781 | is determined by iterating over the implementations of the |
| 782 | EFI_DRIVER_BINDING_PROTOCOL. |
| 783 | |
| 784 | It is the task of the UEFI driver to create a corresponding U-Boot device and to |
| 785 | proxy calls for this U-Boot device to the controller. |
| 786 | |
| 787 | In U-Boot 2018.03 this has only been implemented for block IO devices. |
| 788 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 789 | UEFI uclass |
| 790 | ~~~~~~~~~~~ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 791 | |
| 792 | An UEFI uclass driver (lib/efi_driver/efi_uclass.c) has been created that |
| 793 | takes care of initializing the UEFI drivers and providing the |
| 794 | EFI_DRIVER_BINDING_PROTOCOL implementation for the UEFI drivers. |
| 795 | |
| 796 | A linker created list is used to keep track of the UEFI drivers. To create an |
| 797 | entry in the list the UEFI driver uses the U_BOOT_DRIVER macro specifying |
Simon Glass | 15c4d67 | 2021-12-04 08:56:30 -0700 | [diff] [blame] | 798 | UCLASS_EFI_LOADER as the ID of its uclass, e.g:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 799 | |
| 800 | /* Identify as UEFI driver */ |
| 801 | U_BOOT_DRIVER(efi_block) = { |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 802 | .name = "EFI block driver", |
Simon Glass | 15c4d67 | 2021-12-04 08:56:30 -0700 | [diff] [blame] | 803 | .id = UCLASS_EFI_LOADER, |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 804 | .ops = &driver_ops, |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 805 | }; |
| 806 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 807 | The available operations are defined via the structure struct efi_driver_ops:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 808 | |
| 809 | struct efi_driver_ops { |
| 810 | const efi_guid_t *protocol; |
| 811 | const efi_guid_t *child_protocol; |
| 812 | int (*bind)(efi_handle_t handle, void *interface); |
| 813 | }; |
| 814 | |
| 815 | When the supported() function of the EFI_DRIVER_BINDING_PROTOCOL is called the |
| 816 | uclass checks if the protocol GUID matches the protocol GUID of the UEFI driver. |
| 817 | In the start() function the bind() function of the UEFI driver is called after |
| 818 | checking the GUID. |
| 819 | The stop() function of the EFI_DRIVER_BINDING_PROTOCOL disconnects the child |
| 820 | controllers created by the UEFI driver and the UEFI driver. (In U-Boot v2013.03 |
| 821 | this is not yet completely implemented.) |
| 822 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 823 | UEFI block IO driver |
| 824 | ~~~~~~~~~~~~~~~~~~~~ |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 825 | |
| 826 | The UEFI block IO driver supports devices exposing the EFI_BLOCK_IO_PROTOCOL. |
| 827 | |
| 828 | When connected it creates a new U-Boot block IO device with interface type |
Simon Glass | dbfa32c | 2022-08-11 19:34:59 -0600 | [diff] [blame] | 829 | UCLASS_EFI_LOADER, adds child controllers mapping the partitions, and installs |
Simon Glass | 15c4d67 | 2021-12-04 08:56:30 -0700 | [diff] [blame] | 830 | the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL on these. This can be used together with the |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 831 | software iPXE to boot from iSCSI network drives [4]. |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 832 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 833 | This driver is only available if U-Boot is configured with:: |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 834 | |
| 835 | CONFIG_BLK=y |
| 836 | CONFIG_PARTITIONS=y |
| 837 | |
Heinrich Schuchardt | c4d4542 | 2020-02-22 07:47:20 +0100 | [diff] [blame] | 838 | Miscellaneous |
| 839 | ------------- |
| 840 | |
| 841 | Load file 2 protocol |
| 842 | ~~~~~~~~~~~~~~~~~~~~ |
| 843 | |
| 844 | The load file 2 protocol can be used by the Linux kernel to load the initial |
| 845 | RAM disk. U-Boot can be configured to provide an implementation with:: |
| 846 | |
| 847 | EFI_LOAD_FILE2_INITRD=y |
Ilias Apalodimas | c92aa4b | 2021-03-17 21:55:02 +0200 | [diff] [blame] | 848 | |
| 849 | When the option is enabled the user can add the initrd path with the efidebug |
| 850 | command. |
| 851 | |
| 852 | Load options Boot#### have a FilePathList[] member. The first element of |
| 853 | the array (FilePathList[0]) is the EFI binary to execute. When an initrd |
| 854 | is specified the Device Path for the initrd is denoted by a VenMedia node |
| 855 | with the EFI_INITRD_MEDIA_GUID. Each entry of the array is terminated by the |
| 856 | 'end of entire device path' subtype (0xff). If a user wants to define multiple |
| 857 | initrds, those must by separated by the 'end of this instance' identifier of |
| 858 | the end node (0x01). |
| 859 | |
| 860 | So our final format of the FilePathList[] is:: |
| 861 | |
| 862 | Loaded image - end node (0xff) - VenMedia - initrd_1 - [end node (0x01) - initrd_n ...] - end node (0xff) |
Heinrich Schuchardt | c4d4542 | 2020-02-22 07:47:20 +0100 | [diff] [blame] | 863 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 864 | Links |
| 865 | ----- |
Heinrich Schuchardt | 5fa03de | 2018-03-02 19:58:50 +0100 | [diff] [blame] | 866 | |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 867 | * [1] http://uefi.org/specifications - UEFI specifications |
Vincent Stehlé | c53cec6 | 2022-12-16 17:55:04 +0100 | [diff] [blame] | 868 | * [2] https://github.com/ARM-software/ebbr/releases/download/v2.1.0/ebbr-v2.1.0.pdf - |
| 869 | Embedded Base Boot Requirements (EBBR) Specification - Release v2.1.0 |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 870 | * [3] https://developer.arm.com/docs/den0044/latest/server-base-boot-requirements-system-software-on-arm-platforms-version-11 - |
Heinrich Schuchardt | a28d073 | 2019-03-28 08:09:16 +0100 | [diff] [blame] | 871 | Server Base Boot Requirements System Software on ARM Platforms - Version 1.1 |
Heinrich Schuchardt | fd0b53f | 2019-07-26 06:46:08 +0200 | [diff] [blame] | 872 | * [4] :doc:`iscsi` |
| 873 | * [5] :doc:`../driver-model/index` |