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 <harrison.mutai@arm.com>
diff --git a/docs/plat/qemu.rst b/docs/plat/qemu.rst
index 6986326..f2a39e9 100644
--- a/docs/plat/qemu.rst
+++ b/docs/plat/qemu.rst
@@ -44,7 +44,7 @@
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 @@
-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=<path-to-mbedtls-repo> 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=<path-to-mbedtls-repo> 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
-----------------------