Enable preloaded BL33 alternative boot flow

Enable alternative boot flow where BL2 does not load BL33 from
non-volatile storage, and BL31 hands execution over to a preloaded
BL33.

The flag used to enable this bootflow is BL33_BASE, which must hold
the entrypoint address of the BL33 image. The User Guide has been
updated with an example of how to use this option with a bootwrapped
kernel.

Change-Id: I48087421a7b0636ac40dca7d457d745129da474f

1 files changed, 64 insertions, 9 deletions

diff --git a/docs/user-guide.md b/docs/user-guide.md
index e6929134..d6c6c93f 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -10,10 +10,11 @@ Contents :
 5.  [Building the Trusted Firmware](#5--building-the-trusted-firmware)
 6.  [Building the rest of the software stack](#6--building-the-rest-of-the-software-stack)
 7.  [EL3 payloads alternative boot flow](#7--el3-payloads-alternative-boot-flow)
-8.  [Preparing the images to run on FVP](#8--preparing-the-images-to-run-on-fvp)
-9.  [Running the software on FVP](#9--running-the-software-on-fvp)
-10. [Running the software on Juno](#10--running-the-software-on-juno)
-11. [Changes required for booting Linux on FVP in GICv3 mode](#11--changes-required-for-booting-linux-on-fvp-in-gicv3-mode)
+8.  [Preloaded BL33 alternative boot flow](#8--preloaded-bl33-alternative-boot-flow)
+9.  [Preparing the images to run on FVP](#9--preparing-the-images-to-run-on-fvp)
+10. [Running the software on FVP](#10--running-the-software-on-fvp)
+11. [Running the software on Juno](#11--running-the-software-on-juno)
+12. [Changes required for booting Linux on FVP in GICv3 mode](#12--changes-required-for-booting-linux-on-fvp-in-gicv3-mode)
 
 
 1.  Introduction
@@ -407,6 +408,12 @@ performed.
     payload. Please refer to the "Booting an EL3 payload" section for more
     details.
 
+*   `BL33_BASE`: This option enables booting a preloaded BL33 image instead of
+    the normal boot flow. When defined, it must specify the entry point address
+    for the preloaded BL33 image. This option is incompatible with
+    `EL3_PAYLOAD_BASE`. If both are defined, `EL3_PAYLOAD_BASE` has priority
+    over `BL33_BASE`.
+
 *   `PL011_GENERIC_UART`: Boolean option to indicate the PL011 driver that
     the underlying hardware is not a full PL011 UART but a minimally compliant
     generic UART, which is a subset of the PL011. The driver will not access
@@ -938,7 +945,55 @@ Alternatively, the same DS-5 command mentioned in the FVP section above can
 be used to load the EL3 payload's ELF file over JTAG on Juno.
 
 
-8.  Preparing the images to run on FVP
+8.  Preloaded BL33 alternative boot flow
+----------------------------------------
+
+Some platforms have the ability to preload BL33 into memory instead of relying
+on Trusted Firmware to load it. This may simplify packaging of the normal world
+code and improve performance in a development environment. When secure world
+cold boot is complete, Trusted Firmware simply jumps to a BL33 base address
+provided at build time.
+
+For this option to be used, the `BL33_BASE` build option has to be used when
+compiling the Trusted Firmware. For example, the following command will create
+a FIP without a BL33 and prepare to jump to a BL33 image loaded at address
+0x80000000:
+
+    CROSS_COMPILE=<path-to>/bin/aarch64-linux-gnu- \
+    make BL33_BASE=0x80000000 PLAT=fvp all fip
+
+#### Boot of a preloaded bootwrapped kernel image on Base FVP
+
+The following example uses the AArch64 boot wrapper. This simplifies normal
+world booting while also making use of TF features. It can be obtained from its
+repository with:
+
+    git clone git://git.kernel.org/pub/scm/linux/kernel/git/mark/boot-wrapper-aarch64.git
+
+After compiling it, an ELF file is generated. It can be loaded with the
+following command:
+
+    <path-to>/FVP_Base_AEMv8A-AEMv8A              \
+        -C bp.secureflashloader.fname=bl1.bin     \
+        -C bp.flashloader0.fname=fip.bin          \
+        -a cluster0.cpu0=<bootwrapped-kernel.elf> \
+        --start cluster0.cpu0=0x0
+
+The `-a cluster0.cpu0=<bootwrapped-kernel.elf>` option loads the ELF file. It
+also sets the PC register to the ELF entry point address, which is not the
+desired behaviour, so the `--start cluster0.cpu0=0x0` option forces the PC back
+to 0x0 (the BL1 entry point address) on CPU #0. The `BL33_BASE` define used when
+compiling the FIP must match the ELF entry point.
+
+#### Boot of a preloaded bootwrapped kernel image on Juno
+
+The procedure to obtain and compile the boot wrapper is very similar to the case
+of the FVP. Once compiled, the `SPIN_ON_BL1_EXIT=1` loading method explained
+above in the EL3 payload boot flow section may be used to load the ELF file over
+JTAG on Juno.
+
+
+9.  Preparing the images to run on FVP
 --------------------------------------
 
 Note: This section can be ignored when booting an EL3 payload, as no Flattened
@@ -991,8 +1046,8 @@ Copy the kernel image file `linux/arch/arm64/boot/Image` to the directory from
 which the FVP is launched. Alternatively a symbolic link may be used.
 
 
-9.  Running the software on FVP
--------------------------------
+10.  Running the software on FVP
+--------------------------------
 
 This version of the ARM Trusted Firmware has been tested on the following ARM
 FVPs (64-bit versions only).
@@ -1290,7 +1345,7 @@ The `bp.variant` parameter corresponds to the build variant field of the
 detect the legacy VE memory map while configuring the GIC.
 
 
-10.  Running the software on Juno
+11.  Running the software on Juno
 ---------------------------------
 
 This version of the ARM Trusted Firmware has been tested on Juno r0 and Juno r1.
@@ -1372,7 +1427,7 @@ The Juno board should suspend to RAM and then wakeup after 10 seconds due to
 wakeup interrupt from RTC.
 
 
-11.  Changes required for booting Linux on FVP in GICv3 mode
+12.  Changes required for booting Linux on FVP in GICv3 mode
 ------------------------------------------------------------
 
 In case the TF FVP port is built with the build option