diff options
author | 2023-10-10 14:33:42 +0000 | |
---|---|---|
committer | 2023-10-10 14:33:42 +0000 | |
commit | af1a266670d040d2f4083ff309d732d648afba2a (patch) | |
tree | 2fc46203448ddcc6f81546d379abfaeb323575e9 /roms/u-boot/doc/board/emulation | |
parent | e02cda008591317b1625707ff8e115a4841aa889 (diff) |
Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec
Diffstat (limited to 'roms/u-boot/doc/board/emulation')
-rw-r--r-- | roms/u-boot/doc/board/emulation/index.rst | 14 | ||||
-rw-r--r-- | roms/u-boot/doc/board/emulation/qemu-arm.rst | 92 | ||||
-rw-r--r-- | roms/u-boot/doc/board/emulation/qemu-mips.rst | 129 | ||||
-rw-r--r-- | roms/u-boot/doc/board/emulation/qemu-ppce500.rst | 93 | ||||
-rw-r--r-- | roms/u-boot/doc/board/emulation/qemu-riscv.rst | 115 | ||||
-rw-r--r-- | roms/u-boot/doc/board/emulation/qemu-x86.rst | 118 | ||||
-rw-r--r-- | roms/u-boot/doc/board/emulation/qemu_capsule_update.rst | 210 |
7 files changed, 771 insertions, 0 deletions
diff --git a/roms/u-boot/doc/board/emulation/index.rst b/roms/u-boot/doc/board/emulation/index.rst new file mode 100644 index 000000000..be66b6bb6 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/index.rst @@ -0,0 +1,14 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Emulation +========= + +.. toctree:: + :maxdepth: 2 + + qemu-arm + qemu-mips + qemu-ppce500 + qemu-riscv + qemu-x86 + qemu_capsule_update diff --git a/roms/u-boot/doc/board/emulation/qemu-arm.rst b/roms/u-boot/doc/board/emulation/qemu-arm.rst new file mode 100644 index 000000000..8d7fda10f --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-arm.rst @@ -0,0 +1,92 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2017, Tuomas Tynkkynen <tuomas.tynkkynen@iki.fi> + +QEMU ARM +======== + +QEMU for ARM supports a special 'virt' machine designed for emulation and +virtualization purposes. This document describes how to run U-Boot under it. +Both 32-bit ARM and AArch64 are supported. + +The 'virt' platform provides the following as the basic functionality: + + - A freely configurable amount of CPU cores + - U-Boot loaded and executing in the emulated flash at address 0x0 + - A generated device tree blob placed at the start of RAM + - A freely configurable amount of RAM, described by the DTB + - A PL011 serial port, discoverable via the DTB + - An ARMv7/ARMv8 architected timer + - PSCI for rebooting the system + - A generic ECAM-based PCI host controller, discoverable via the DTB + +Additionally, a number of optional peripherals can be added to the PCI bus. + +Building U-Boot +--------------- +Set the CROSS_COMPILE environment variable as usual, and run: + +- For ARM:: + + make qemu_arm_defconfig + make + +- For AArch64:: + + make qemu_arm64_defconfig + make + +Running U-Boot +-------------- +The minimal QEMU command line to get U-Boot up and running is: + +- For ARM:: + + qemu-system-arm -machine virt -bios u-boot.bin + +- For AArch64:: + + qemu-system-aarch64 -machine virt -cpu cortex-a57 -bios u-boot.bin + +Note that for some odd reason qemu-system-aarch64 needs to be explicitly +told to use a 64-bit CPU or it will boot in 32-bit mode. + +Additional persistent U-boot environment support can be added as follows: + +- Create envstore.img using qemu-img:: + + qemu-img create -f raw envstore.img 64M + +- Add a pflash drive parameter to the command line:: + + -drive if=pflash,format=raw,index=1,file=envstore.img + +Additional peripherals that have been tested to work in both U-Boot and Linux +can be enabled with the following command line parameters: + +- To add a Serial ATA disk via an Intel ICH9 AHCI controller, pass e.g.:: + + -drive if=none,file=disk.img,id=mydisk -device ich9-ahci,id=ahci -device ide-drive,drive=mydisk,bus=ahci.0 + +- To add an Intel E1000 network adapter, pass e.g.:: + + -netdev user,id=net0 -device e1000,netdev=net0 + +- To add an EHCI-compliant USB host controller, pass e.g.:: + + -device usb-ehci,id=ehci + +- To add a NVMe disk, pass e.g.:: + + -drive if=none,file=disk.img,id=mydisk -device nvme,drive=mydisk,serial=foo + +These have been tested in QEMU 2.9.0 but should work in at least 2.5.0 as well. + +Debug UART +---------- + +The debug UART on the ARM virt board uses these settings:: + + CONFIG_DEBUG_UART=y + CONFIG_DEBUG_UART_PL010=y + CONFIG_DEBUG_UART_BASE=0x9000000 + CONFIG_DEBUG_UART_CLOCK=0 diff --git a/roms/u-boot/doc/board/emulation/qemu-mips.rst b/roms/u-boot/doc/board/emulation/qemu-mips.rst new file mode 100644 index 000000000..5fd8a0a23 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-mips.rst @@ -0,0 +1,129 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Daniel Schwierzeck <daniel.schwierzeck@gmail.com> + +QEMU MIPS +========= + +Qemu for MIPS is based on the MIPS Malta board. The built Malta U-Boot +images can be used for Qemu and on physical hardware. The Malta board +supports all combinations of Little and Big Endian as well as 32 bit +and 64 bit. + +Limitations & comments +---------------------- +The memory size for Qemu is hard-coded to 256 MiB. For Malta Little Endian +targets an extra endianness swapped image named *u-boot-swap.bin* is +generated and required for Qemu. + +Example usage +------------- + +Build for 32 bit, big endian: + +.. code-block:: bash + + make malta_defconfig + make + UBOOT_BIN=u-boot.bin + QEMU_BIN=qemu-system-mips + QEMU_CPU=24Kc + +Build for 32 bit, little endian: + +.. code-block:: bash + + make maltael_defconfig + make + UBOOT_BIN=u-boot-swap.bin + QEMU_BIN=qemu-system-mipsel + QEMU_CPU=24Kc + +Build for 64 bit, big endian: + +.. code-block:: bash + + make malta64_defconfig + make + UBOOT_BIN=u-boot.bin + QEMU_BIN=qemu-system-mips64 + QEMU_CPU=MIPS64R2-generic + +Build for 64 bit, little endian: + +.. code-block:: bash + + make malta64el_defconfig + make + UBOOT_BIN=u-boot-swap.bin + QEMU_BIN=qemu-system-mips64el + QEMU_CPU=MIPS64R2-generic + +Generate NOR flash image with U-Boot binary: + +.. code-block:: bash + + dd if=/dev/zero bs=1M count=4 | tr '\000' '\377' > pflash.img + dd if=${UBOOT_BIN} of=pflash.img conv=notrunc + +Start Qemu: + +.. code-block:: bash + + mkdir tftproot + ${QEMU_BIN} -nographic -cpu ${QEMU_CPU} -m 256 -drive if=pflash,file="$(pwd)/pflash.img",format=raw -netdev user,id=net0,tftp="$(pwd)/tftproot" -device pcnet,netdev=net0 + +.. code-block:: bash + + U-Boot 2021.04-00963-g60279a2b1d (Apr 21 2021 - 19:54:32 +0200) + + Board: MIPS Malta CoreLV + DRAM: 256 MiB + Flash: 4 MiB + Loading Environment from Flash... *** Warning - bad CRC, using default environment + + In: serial@3f8 + Out: serial@3f8 + Err: serial@3f8 + Net: pcnet#0 + IDE: Bus 0: not available + maltael # + +How to debug U-Boot +------------------- + +In order to debug U-Boot you need to start qemu with gdb server support (-s) +and waiting the connection to start the CPU (-S). Start Qemu in the first console: + +.. code-block:: bash + + mkdir tftproot + ${QEMU_BIN} -s -S -nographic -cpu ${QEMU_CPU} -m 256 -drive if=pflash,file="$(pwd)/pflash.img",format=raw -netdev user,id=net0,tftp="$(pwd)/tftproot" -device pcnet,netdev=net0 + +In the second console start gdb: + +.. code-block:: bash + + gdb-multiarch --eval-command "target remote :1234" u-boot + +.. code-block:: bash + + GNU gdb (Ubuntu 9.2-0ubuntu1~20.04) 9.2 + Copyright (C) 2020 Free Software Foundation, Inc. + License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> + This is free software: you are free to change and redistribute it. + There is NO WARRANTY, to the extent permitted by law. + Type "show copying" and "show warranty" for details. + This GDB was configured as "x86_64-linux-gnu". + Type "show configuration" for configuration details. + For bug reporting instructions, please see: + <http://www.gnu.org/software/gdb/bugs/>. + Find the GDB manual and other documentation resources online at: + <http://www.gnu.org/software/gdb/documentation/>. + + For help, type "help". + Type "apropos word" to search for commands related to "word"... + Reading symbols from u-boot... + Remote debugging using :1234 + 0xbfc00000 in ?? () + (gdb) c + Continuing. diff --git a/roms/u-boot/doc/board/emulation/qemu-ppce500.rst b/roms/u-boot/doc/board/emulation/qemu-ppce500.rst new file mode 100644 index 000000000..5de0aaf55 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-ppce500.rst @@ -0,0 +1,93 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2021, Bin Meng <bmeng.cn@gmail.com> + +QEMU PPC E500 +============= + +QEMU for PPC supports a special 'ppce500' machine designed for emulation and +virtualization purposes. This document describes how to run U-Boot under it. + +The QEMU ppce500 machine models a generic PowerPC E500 virtual machine with +support for the VirtIO standard networking device connected to the built-in +PCI host controller. Some common devices in the CCSBAR space are modeled, +including MPIC, 16550A UART devices, GPIO, I2C and PCI host controller with +MSI delivery to MPIC. It uses device-tree to pass configuration information +to guest software. + +Building U-Boot +--------------- +Set the CROSS_COMPILE environment variable as usual, and run:: + + $ make qemu-ppce500_defconfig + $ make + +Running U-Boot +-------------- +The minimal QEMU command line to get U-Boot up and running is:: + + $ qemu-system-ppc -nographic -machine ppce500 -bios u-boot + +You can also run U-Boot using 'qemu-system-ppc64':: + + $ qemu-system-ppc64 -nographic -machine ppce500 -bios u-boot + +The commands above create a target with 128 MiB memory by default. A freely +configurable amount of RAM can be created via the '-m' parameter. For example, +'-m 2G' creates 2 GiB memory for the target, and the memory node in the +embedded DTB created by QEMU reflects the new setting. + +Both qemu-system-ppc and qemu-system-ppc64 provide emulation for the following +32-bit PowerPC CPUs: + +* e500v2 +* e500mc + +Additionally qemu-system-ppc64 provides support for the following 64-bit CPUs: + +* e5500 +* e6500 + +The CPU type can be specified via the '-cpu' command line. If not specified, +it creates a machine with e500v2 core. The following example shows an e6500 +based machine creation:: + + $ qemu-system-ppc64 -nographic -machine ppce500 -cpu e6500 -bios u-boot + +When U-Boot boots, you will notice the following:: + + CPU: Unknown, Version: 0.0, (0x00000000) + Core: e6500, Version: 2.0, (0x80400020) + +This is because we only specified a core name to QEMU and it does not have a +meaningful SVR value which represents an actual SoC that integrates such core. +You can specify a real world SoC device that QEMU has built-in support but all +these SoCs are e500v2 based MPC85xx series, hence you cannot test anything +built for P4080 (e500mc), P5020 (e5500) and T2080 (e6500). + +By default a VirtIO standard PCI networking device is connected as an ethernet +interface at PCI address 0.1.0, but we can switch that to an e1000 NIC by:: + + $ qemu-system-ppc -nographic -machine ppce500 -bios u-boot \ + -nic tap,ifname=tap0,script=no,downscript=no,model=e1000 + +The QEMU ppce500 machine can also dynamically instantiate an eTSEC device if +"-device eTSEC" is given to QEMU:: + + -netdev tap,ifname=tap0,script=no,downscript=no,id=net0 -device eTSEC,netdev=net0 + +VirtIO BLK driver is also enabled to support booting from a disk image where +a kernel image is stored. Append the following to QEMU:: + + -drive file=disk.img,format=raw,id=disk0 -device virtio-blk-pci,drive=disk0 + +Pericom pt7c4338 RTC is supported so we can use the 'date' command:: + + => date + Date: 2021-02-18 (Thursday) Time: 15:33:20 + +Additionally, 'poweroff' command is supported to shut down the QEMU session:: + + => poweroff + poweroff ... + +These have been tested in QEMU 5.2.0. diff --git a/roms/u-boot/doc/board/emulation/qemu-riscv.rst b/roms/u-boot/doc/board/emulation/qemu-riscv.rst new file mode 100644 index 000000000..4b8e104a2 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-riscv.rst @@ -0,0 +1,115 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2018, Bin Meng <bmeng.cn@gmail.com> + +QEMU RISC-V +=========== + +QEMU for RISC-V supports a special 'virt' machine designed for emulation and +virtualization purposes. This document describes how to run U-Boot under it. +Both 32-bit and 64-bit targets are supported, running in either machine or +supervisor mode. + +The QEMU virt machine models a generic RISC-V virtual machine with support for +the VirtIO standard networking and block storage devices. It has CLINT, PLIC, +16550A UART devices in addition to VirtIO and it also uses device-tree to pass +configuration information to guest software. It implements RISC-V privileged +architecture spec v1.10. + +Building U-Boot +--------------- +Set the CROSS_COMPILE environment variable as usual, and run: + +- For 32-bit RISC-V:: + + make qemu-riscv32_defconfig + make + +- For 64-bit RISC-V:: + + make qemu-riscv64_defconfig + make + +This will compile U-Boot for machine mode. To build supervisor mode binaries, +use the configurations qemu-riscv32_smode_defconfig and +qemu-riscv64_smode_defconfig instead. Note that U-Boot running in supervisor +mode requires a supervisor binary interface (SBI), such as RISC-V OpenSBI. + +Running U-Boot +-------------- +The minimal QEMU command line to get U-Boot up and running is: + +- For 32-bit RISC-V:: + + qemu-system-riscv32 -nographic -machine virt -bios u-boot + +- For 64-bit RISC-V:: + + qemu-system-riscv64 -nographic -machine virt -bios u-boot + +The commands above create targets with 128MiB memory by default. +A freely configurable amount of RAM can be created via the '-m' +parameter. For example, '-m 2G' creates 2GiB memory for the target, +and the memory node in the embedded DTB created by QEMU reflects +the new setting. + +For instructions on how to run U-Boot in supervisor mode on QEMU +with OpenSBI, see the documentation available with OpenSBI: +https://github.com/riscv/opensbi/blob/master/docs/platform/qemu_virt.md + +These have been tested in QEMU 5.0.0. + +Running U-Boot SPL +------------------ +In the default SPL configuration, U-Boot SPL starts in machine mode. U-Boot +proper and OpenSBI (FW_DYNAMIC firmware) are bundled as FIT image and made +available to U-Boot SPL. Both are then loaded by U-Boot SPL and the location +of U-Boot proper is passed to OpenSBI. After initialization, U-Boot proper is +started in supervisor mode by OpenSBI. + +OpenSBI must be compiled before compiling U-Boot. Version 0.4 and higher is +supported by U-Boot. Clone the OpenSBI repository and run the following command. + +.. code-block:: console + + git clone https://github.com/riscv/opensbi.git + cd opensbi + make PLATFORM=generic + +See the OpenSBI documentation for full details: +https://github.com/riscv/opensbi/blob/master/docs/platform/qemu_virt.md + +To make the FW_DYNAMIC binary (build/platform/qemu/virt/firmware/fw_dynamic.bin) +available to U-Boot, either copy it into the U-Boot root directory or specify +its location with the OPENSBI environment variable. Afterwards, compile U-Boot +with the following commands. + +- For 32-bit RISC-V:: + + make qemu-riscv32_spl_defconfig + make + +- For 64-bit RISC-V:: + + make qemu-riscv64_spl_defconfig + make + +The minimal QEMU commands to run U-Boot SPL in both 32-bit and 64-bit +configurations are: + +- For 32-bit RISC-V:: + + qemu-system-riscv32 -nographic -machine virt -bios spl/u-boot-spl \ + -device loader,file=u-boot.itb,addr=0x80200000 + +- For 64-bit RISC-V:: + + qemu-system-riscv64 -nographic -machine virt -bios spl/u-boot-spl \ + -device loader,file=u-boot.itb,addr=0x80200000 + +An attached disk can be emulated by adding:: + + -device ich9-ahci,id=ahci \ + -drive if=none,file=riscv64.img,format=raw,id=mydisk \ + -device ide-hd,drive=mydisk,bus=ahci.0 + +You will have to run 'scsi scan' to use it. diff --git a/roms/u-boot/doc/board/emulation/qemu-x86.rst b/roms/u-boot/doc/board/emulation/qemu-x86.rst new file mode 100644 index 000000000..db842f2ec --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu-x86.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. sectionauthor:: Bin Meng <bmeng.cn@gmail.com> + +QEMU x86 +======== + +Build instructions for bare mode +-------------------------------- + +To build u-boot.rom for QEMU x86 targets, just simply run:: + + $ make qemu-x86_defconfig (for 32-bit) + $ make qemu-x86_64_defconfig (for 64-bit) + $ make all + +Note this default configuration will build a U-Boot for the QEMU x86 i440FX +board. To build a U-Boot against QEMU x86 Q35 board, you can change the build +configuration during the 'make menuconfig' process like below:: + + Device Tree Control ---> + ... + (qemu-x86_q35) Default Device Tree for DT control + +Test with QEMU for bare mode +---------------------------- + +QEMU is a fancy emulator that can enable us to test U-Boot without access to +a real x86 board. Please make sure your QEMU version is 2.3.0 or above test +U-Boot. To launch QEMU with u-boot.rom, call QEMU as follows:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom + +This will instantiate an emulated x86 board with i440FX and PIIX chipset. QEMU +also supports emulating an x86 board with Q35 and ICH9 based chipset, which is +also supported by U-Boot. To instantiate such a machine, call QEMU with:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -M q35 + +Note by default QEMU instantiated boards only have 128 MiB system memory. But +it is enough to have U-Boot boot and function correctly. You can increase the +system memory by pass '-m' parameter to QEMU if you want more memory:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 + +This creates a board with 1 GiB system memory. Currently U-Boot for QEMU only +supports 3 GiB maximum system memory and reserves the last 1 GiB address space +for PCI device memory-mapped I/O and other stuff, so the maximum value of '-m' +would be 3072. + +QEMU emulates a graphic card which U-Boot supports. Removing '-nographic' will +show QEMU's VGA console window. Note this will disable QEMU's serial output. +If you want to check both consoles, use '-serial stdio'. + +Multicore is also supported by QEMU via '-smp n' where n is the number of cores +to instantiate. Note, the maximum supported CPU number in QEMU is 255. + +U-Boot uses 'distro_bootcmd' by default when booting on x86 QEMU. This tries to +load a boot script, kernel, and ramdisk from several different interfaces. For +the default boot order, see 'qemu-x86.h'. For more information, see +'README.distro'. Most Linux distros can be booted by writing a uboot script. +For example, Debian (stretch) can be booted by creating a script file named +'boot.txt' with the contents:: + + setenv bootargs root=/dev/sda1 ro + load ${devtype} ${devnum}:${distro_bootpart} ${kernel_addr_r} /vmlinuz + load ${devtype} ${devnum}:${distro_bootpart} ${ramdisk_addr_r} /initrd.img + zboot ${kernel_addr_r} - ${ramdisk_addr_r} ${filesize} + +Then compile and install it with:: + + $ apt install u-boot-tools && \ + mkimage -T script -C none -n "Boot script" -d boot.txt /boot/boot.scr + +The fw_cfg interface in QEMU also provides information about kernel data, +initrd, command-line arguments and more. U-Boot supports directly accessing +these informtion from fw_cfg interface, which saves the time of loading them +from hard disk or network again, through emulated devices. To use it , simply +providing them in QEMU command line:: + + $ qemu-system-i386 -nographic -bios path/to/u-boot.rom -m 1024 \ + -kernel /path/to/bzImage -append 'root=/dev/ram console=ttyS0' \ + -initrd /path/to/initrd -smp 8 + +Note: -initrd and -smp are both optional + +Then start QEMU, in U-Boot command line use the following U-Boot command to +setup kernel:: + + => qfw + qfw - QEMU firmware interface + + Usage: + qfw <command> + - list : print firmware(s) currently loaded + - cpus : print online cpu number + - load <kernel addr> <initrd addr> : load kernel and initrd (if any) and setup for zboot + + => qfw load + loading kernel to address 01000000 size 5d9d30 initrd 04000000 size 1b1ab50 + +Here the kernel (bzImage) is loaded to 01000000 and initrd is to 04000000. Then, +'zboot' can be used to boot the kernel:: + + => zboot 01000000 - 04000000 1b1ab50 + +To run 64-bit U-Boot, qemu-system-x86_64 should be used instead, e.g.:: + + $ qemu-system-x86_64 -nographic -bios path/to/u-boot.rom + +A specific CPU can be specified via the '-cpu' parameter but please make +sure the specified CPU supports 64-bit like '-cpu core2duo'. Conversely +'-cpu pentium' won't work for obvious reasons that the processor only +supports 32-bit. + +Note 64-bit support is very preliminary at this point. Lots of features +are missing in the 64-bit world. One notable feature is the VGA console +support which is currently missing, so that you must specify '-nographic' +to get 64-bit U-Boot up and running. diff --git a/roms/u-boot/doc/board/emulation/qemu_capsule_update.rst b/roms/u-boot/doc/board/emulation/qemu_capsule_update.rst new file mode 100644 index 000000000..33ce4bcd3 --- /dev/null +++ b/roms/u-boot/doc/board/emulation/qemu_capsule_update.rst @@ -0,0 +1,210 @@ +.. SPDX-License-Identifier: GPL-2.0+ +.. Copyright (C) 2020, Linaro Limited + +Enabling UEFI Capsule Update feature +------------------------------------ + +Support has been added for the UEFI capsule update feature which +enables updating the U-Boot image using the UEFI firmware management +protocol (fmp). The capsules are not passed to the firmware through +the UpdateCapsule runtime service. Instead, capsule-on-disk +functionality is used for fetching the capsule from the EFI System +Partition (ESP) by placing the capsule file under the +\EFI\UpdateCapsule directory. + +Currently, support has been added on the QEMU ARM64 virt platform for +updating the U-Boot binary as a raw image when the platform is booted +in non-secure mode, i.e. with CONFIG_TFABOOT disabled. For this +configuration, the QEMU platform needs to be booted with +'secure=off'. The U-Boot binary placed on the first bank of the NOR +flash at offset 0x0. The U-Boot environment is placed on the second +NOR flash bank at offset 0x4000000. + +The capsule update feature is enabled with the following configuration +settings:: + + CONFIG_MTD=y + CONFIG_FLASH_CFI_MTD=y + CONFIG_CMD_MTDPARTS=y + CONFIG_CMD_DFU=y + CONFIG_DFU_MTD=y + CONFIG_PCI_INIT_R=y + CONFIG_EFI_CAPSULE_ON_DISK=y + CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y + CONFIG_EFI_CAPSULE_FIRMWARE=y + CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y + CONFIG_EFI_CAPSULE_FMP_HEADER=y + +In addition, the following config needs to be disabled(QEMU ARM specific):: + + CONFIG_TFABOOT + +The capsule file can be generated by using the GenerateCapsule.py +script in EDKII:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + <capsule_file_name> --fw-version <val> --lsv <val> --guid \ + e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose --update-image-index \ + <val> --verbose <u-boot.bin> + +The above is a wrapper script(GenerateCapsule) which eventually calls +the actual GenerateCapsule.py script. + +As per the UEFI specification, the capsule file needs to be placed on +the EFI System Partition, under the \EFI\UpdateCapsule directory. The +EFI System Partition can be a virtio-blk-device. + +Before initiating the firmware update, the efi variables BootNext, +BootXXXX and OsIndications need to be set. The BootXXXX variable needs +to be pointing to the EFI System Partition which contains the capsule +file. The BootNext, BootXXXX and OsIndications variables can be set +using the following commands:: + + => efidebug boot add -b 0 Boot0000 virtio 0:1 <capsule_file_name> + => efidebug boot next 0 + => setenv -e -nv -bs -rt -v OsIndications =0x04 + => saveenv + +Finally, the capsule update can be initiated with the following +command:: + + => efidebug capsule disk-update + +The updated U-Boot image will be booted on subsequent boot. + +Enabling Capsule Authentication +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The UEFI specification defines a way of authenticating the capsule to +be updated by verifying the capsule signature. The capsule signature +is computed and prepended to the capsule payload at the time of +capsule generation. This signature is then verified by using the +public key stored as part of the X509 certificate. This certificate is +in the form of an efi signature list (esl) file, which is embedded as +part of the platform's device tree blob using the mkeficapsule +utility. + +On the QEMU virt platforms, the device-tree is generated on the fly +based on the devices configured. This device tree is then passed on to +the various software components booting on the platform, including +U-Boot. Therefore, on the QEMU virt platform, the signatute is +embedded on an overlay. This overlay is then applied at runtime to the +base platform device-tree. Steps needed for embedding the esl file in +the overlay are highlighted below. + +The capsule authentication feature can be enabled through the +following config, in addition to the configs listed above for capsule +update:: + + CONFIG_EFI_CAPSULE_AUTHENTICATE=y + +The public and private keys used for the signing process are generated +and used by the steps highlighted below:: + + 1. Install utility commands on your host + * OPENSSL + * efitools + + 2. Create signing keys and certificate files on your host + + $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ \ + -keyout CRT.key -out CRT.crt -nodes -days 365 + $ cert-to-efi-sig-list CRT.crt CRT.esl + + $ openssl x509 -in CRT.crt -out CRT.cer -outform DER + $ openssl x509 -inform DER -in CRT.cer -outform PEM -out CRT.pub.pem + + $ openssl pkcs12 -export -out CRT.pfx -inkey CRT.key -in CRT.crt + $ openssl pkcs12 -in CRT.pfx -nodes -out CRT.pem + +The capsule file can be generated by using the GenerateCapsule.py +script in EDKII:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + <capsule_file_name> --monotonic-count <val> --fw-version \ + <val> --lsv <val> --guid \ + e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose \ + --update-image-index <val> --signer-private-cert \ + /path/to/CRT.pem --trusted-public-cert \ + /path/to/CRT.pub.pem --other-public-cert /path/to/CRT.pub.pem \ + <u-boot.bin> + +Place the capsule generated in the above step on the EFI System +Partition under the EFI/UpdateCapsule directory + +For embedding the public key certificate, the following steps need to +be followed:: + + 1. Generate a skeleton overlay dts file, with a single fragment + node and an empty __overlay__ node + + A typical skeleton overlay file will look like this + + /dts-v1/; + /plugin/; + + / { + fragment@0 { + target-path = "/"; + __overlay__ { + }; + }; + }; + + + 2. Convert the dts to a corresponding dtb with the following + command + ./scripts/dtc/dtc -@ -I dts -O dtb -o <ov_dtb_file_name> \ + <dts_file> + + 3. Run the dtb file generated above through the mkeficapsule tool + in U-Boot + ./tools/mkeficapsule -O <pub_key.esl> -D <ov_dtb> + +Running the above command results in the creation of a 'signature' +node in the dtb, under which the public key is stored as a +'capsule-key' property. The '-O' option is to be used since the +public key certificate(esl) file is being embedded in an overlay. + +The dtb file embedded with the certificate is now to be placed on an +EFI System Partition. This would then be loaded and "merged" with the +base platform flattened device-tree(dtb) at runtime. + +Build U-Boot with the following steps(QEMU ARM64):: + + $ make qemu_arm64_defconfig + $ make menuconfig + Disable CONFIG_TFABOOT + Enable CONFIG_EFI_CAPSULE_AUTHENTICATE + Enable all configs needed for capsule update(listed above) + $ make all + +Boot the platform and perform the following steps on the U-Boot +command line:: + + 1. Enable capsule authentication by setting the following env + variable + + => setenv capsule_authentication_enabled 1 + => saveenv + + 2. Load the overlay dtb to memory and merge it with the base fdt + + => fatload virtio 0:1 <$fdtovaddr> EFI/<ov_dtb_file> + => fdt addr $fdtcontroladdr + => fdt resize <size_of_ov_dtb_file> + => fdt apply <$fdtovaddr> + + 3. Set the following environment and UEFI boot variables + + => setenv -e -nv -bs -rt -v OsIndications =0x04 + => efidebug boot add -b 0 Boot0000 virtio 0:1 <capsule_file_name> + => efidebug boot next 0 + => saveenv + + 4. Finally, the capsule update can be initiated with the following + command + + => efidebug capsule disk-update + +On subsequent reboot, the platform should boot the updated U-Boot binary. |