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 698632697d59ea75106eafdf6f0c3c1159dd9740..f2a39e9afd0bd9ec233f6072de2d3284e5411ff0 100644 (file)
--- 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=<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
 -----------------------