aboutsummaryrefslogtreecommitdiffstats
path: root/roms/u-boot/doc/board/emulation
diff options
context:
space:
mode:
authorAngelos Mouzakitis <a.mouzakitis@virtualopensystems.com>2023-10-10 14:33:42 +0000
committerAngelos Mouzakitis <a.mouzakitis@virtualopensystems.com>2023-10-10 14:33:42 +0000
commitaf1a266670d040d2f4083ff309d732d648afba2a (patch)
tree2fc46203448ddcc6f81546d379abfaeb323575e9 /roms/u-boot/doc/board/emulation
parente02cda008591317b1625707ff8e115a4841aa889 (diff)
Add submodule dependency filesHEADmaster
Change-Id: Iaf8d18082d3991dec7c0ebbea540f092188eb4ec
Diffstat (limited to 'roms/u-boot/doc/board/emulation')
-rw-r--r--roms/u-boot/doc/board/emulation/index.rst14
-rw-r--r--roms/u-boot/doc/board/emulation/qemu-arm.rst92
-rw-r--r--roms/u-boot/doc/board/emulation/qemu-mips.rst129
-rw-r--r--roms/u-boot/doc/board/emulation/qemu-ppce500.rst93
-rw-r--r--roms/u-boot/doc/board/emulation/qemu-riscv.rst115
-rw-r--r--roms/u-boot/doc/board/emulation/qemu-x86.rst118
-rw-r--r--roms/u-boot/doc/board/emulation/qemu_capsule_update.rst210
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.