From d9bd35e35fc6a6b7ad99f64d1ad1617da1a10e8e Mon Sep 17 00:00:00 2001 From: Harrison Mutai Date: Mon, 6 Feb 2023 17:54:54 +0000 Subject: [PATCH] docs(qemu): delineate flash based boot method Make the language around the explanation for booting via secure flash clearer. Provide details into the intent of the options given to QEMU. Change-Id: Ia573b900aaa2346cad4f82191110b978f9bd5481 Signed-off-by: Harrison Mutai --- docs/plat/qemu.rst | 87 ++++++++++++++++++++++++++++------------------ 1 file changed, 53 insertions(+), 34 deletions(-) diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst index 698632697..f2a39e9af 100644 --- a/docs/plat/qemu.rst +++ b/docs/plat/qemu.rst @@ -44,7 +44,7 @@ or, can be built as follows: Then, you will get ``Build/ArmVirtQemuKernel-AARCH64/DEBUG_GCC5/FV/QEMU_EFI.fd`` Please note you do not need to use GCC 5 in spite of the environment variable -``GCC5_AARCH64_PREFIX`` +``GCC5_AARCH64_PREFIX``. The rootfs can be built by using Buildroot as follows: @@ -88,54 +88,73 @@ To start (QEMU v5.0.0): -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios bl1.bin \ -d unimp -semihosting-config enable,target=native -Booting via flash based firmwares ---------------------------------- +Booting via flash based firmware +-------------------------------- -Boot firmwares are loaded via secure FLASH0 device so ``bl1.bin`` and -``fip.bin`` should be concatenated to create a ``flash.bin`` that is flashed -onto secure FLASH0. +An alternate approach to deploy a full system stack on QEMU is to load the +firmware via a secure flash device. This involves concatenating ``bl1.bin`` and +``fip.bin`` to create a boot ROM that is flashed onto secure FLASH0 with the +``-bios`` option. -- ``bl32.bin`` -> BL32 (``tee-header_v2.bin``) -- ``bl32_extra1.bin`` -> BL32 Extra1 (``tee-pager_v2.bin``) -- ``bl32_extra2.bin`` -> BL32 Extra2 (``tee-pageable_v2.bin``) -- ``bl33.bin`` -> BL33 (``QEMU_EFI.fd``) +For example, to test the following firmware stack: + + +- BL32 - ``bl32.bin`` -> ``tee-header_v2.bin`` +- BL32 Extra1 - ``bl32_extra1.bin`` -> ``tee-pager_v2.bin`` +- BL32 Extra2 - ``bl32_extra2.bin`` -> ``tee-pageable_v2.bin`` +- BL33 - ``bl33.bin`` -> ``QEMU_EFI.fd`` (EDK II) - ``Image`` -> linux/arch/arm64/boot/Image -To build: -.. code:: shell +1. Compile TF-A - make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ - BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ - BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip + .. code:: shell -To build with TBBR enabled, BL31 and BL32 encrypted with test key: + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ + BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ + BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip -.. code:: shell + Or, alternatively, to build with TBBR enabled, as well as, BL31 and BL32 encrypted with + test key: - make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ - BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ - BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip \ - MBEDTLS_DIR= TRUSTED_BOARD_BOOT=1 \ - GENERATE_COT=1 DECRYPTION_SUPPORT=aes_gcm FW_ENC_STATUS=0 \ - ENCRYPT_BL31=1 ENCRYPT_BL32=1 + .. code:: shell -To build flash.bin: + make CROSS_COMPILE=aarch64-linux-gnu- PLAT=qemu BL32=bl32.bin \ + BL32_EXTRA1=bl32_extra1.bin BL32_EXTRA2=bl32_extra2.bin \ + BL33=bl33.bin BL32_RAM_LOCATION=tdram SPD=opteed all fip \ + MBEDTLS_DIR= TRUSTED_BOARD_BOOT=1 \ + GENERATE_COT=1 DECRYPTION_SUPPORT=aes_gcm FW_ENC_STATUS=0 \ + ENCRYPT_BL31=1 ENCRYPT_BL32=1 -.. code:: shell +2. Concatenate ``bl1.bin`` and ``fip.bin`` to create the boot ROM - dd if=build/qemu/release/bl1.bin of=flash.bin bs=4096 conv=notrunc - dd if=build/qemu/release/fip.bin of=flash.bin seek=64 bs=4096 conv=notrunc + .. code:: shell -To start (QEMU v5.0.0): + dd if=build/qemu/release/bl1.bin of=flash.bin bs=4096 conv=notrunc + dd if=build/qemu/release/fip.bin of=flash.bin seek=64 bs=4096 conv=notrunc -.. code:: shell +3. Launch QEMU - qemu-system-aarch64 -nographic -machine virt,secure=on -cpu cortex-a57 \ - -kernel Image -no-acpi \ - -append 'console=ttyAMA0,38400 keep_bootcon' \ - -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios flash.bin \ - -d unimp + .. code:: shell + + qemu-system-aarch64 -nographic -machine virt,secure=on + -cpu cortex-a57 -kernel Image \ + -append 'console=ttyAMA0,38400 keep_bootcon' \ + -initrd rootfs.cpio.gz -smp 2 -m 1024 -bios flash.bin \ + -d unimp + +The ``-bios`` option abstracts the loading of raw bare metal binaries into flash +or ROM memory. QEMU loads the binary into the region corresponding to +the hardware's entrypoint, from which the binary is executed upon a platform +"reset". In addition to this, it places the information about the kernel +provided with option ``-kernel``, and the RamDisk provided with ``-initrd``, +into the firmware configuration ``fw_cfg``. In this setup, EDK II is responsible +for extracting and launching these from ``fw_cfg``. + +.. note:: + QEMU may be launched with or without ACPI (``-acpi``/``-no-acpi``). In + either case, ensure that the kernel build options are aligned with the + parameters passed to QEMU. Running QEMU in OpenCI -----------------------