FWU: Add documentation for Firmware Update feature

This patch adds design documentation for the Firmware Update (FWU)
feature in `firmware-update.md`. It provides an overview of FWU,
describes the BL1 SMC interface, and includes diagrams showing
an example FWU boot flow and the FWU state machine.

This patch also updates the existing TF documents where needed:

*   `porting-guide.md`
*   `user-guide.md`
*   `firmware-design.md`
*   `rt-svc-writers-guide.md`
*   `trusted_board_boot.md`

Change-Id: Ie6de31544429b18f01327bd763175e218299a4ce
Co-Authored-By: Dan Handley <dan.handley@arm.com>

1 files changed, 72 insertions, 15 deletions

diff --git a/docs/user-guide.md b/docs/user-guide.md
index fa39c4bd..3d4033ec 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -208,6 +208,21 @@ performed.
 *   `FIP_NAME`: This is an optional build option which specifies the FIP
     filename for the `fip` target. Default is `fip.bin`.
 
+*   `FWU_FIP_NAME`: This is an optional build option which specifies the FWU
+    FIP filename for the `fwu_fip` target. Default is `fwu_fip.bin`.
+
+*   `BL2U`:  This is an optional build option which specifies the path to
+    BL2U image. In this case, the BL2U in the ARM Trusted Firmware will not
+    be built.
+
+*   `SCP_BL2U`: Path to SCP_BL2U image in the host file system. This image is
+    optional. It is only needed if the platform makefile specifies that it
+    is required in order to build the `fwu_fip` target.
+
+*   `NS_BL2U`: Path to NS_BL2U image in the host file system. This image is
+    optional. It is only needed if the platform makefile specifies that it
+    is required in order to build the `fwu_fip` target.
+
 *   `CROSS_COMPILE`: Prefix to toolchain binaries. Please refer to examples in
     this document for usage.
 
@@ -290,26 +305,29 @@ performed.
 
 *   `TRUSTED_BOARD_BOOT`: Boolean flag to include support for the Trusted Board
     Boot feature. When set to '1', BL1 and BL2 images include support to load
-    and verify the certificates and images in a FIP. The default value is '0'.
-    Generation and inclusion of certificates in the FIP depends upon the value
-    of the `GENERATE_COT` option.
+    and verify the certificates and images in a FIP, and BL1 includes support
+    for the Firmware Update. The default value is '0'. Generation and inclusion
+    of certificates in the FIP and FWU_FIP depends upon the value of the
+    `GENERATE_COT` option.
 
 *   `GENERATE_COT`: Boolean flag used to build and execute the `cert_create`
     tool to create certificates as per the Chain of Trust described in
     [Trusted Board Boot].  The build system then calls the `fip_create` tool to
-    include the certificates in the FIP. Default value is '0'.
+    include the certificates in the FIP and FWU_FIP. Default value is '0'.
 
-    Specify `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support for
-    the Trusted Board Boot Sequence in the BL1 and BL2 images and the FIP.
+    Specify both `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=1` to include support
+    for the Trusted Board Boot feature in the BL1 and BL2 images, to generate
+    the corresponding certificates, and to include those certificates in the
+    FIP and FWU_FIP.
 
     Note that if `TRUSTED_BOARD_BOOT=0` and `GENERATE_COT=1`, the BL1 and BL2
     images will not include support for Trusted Board Boot. The FIP will still
-    include the key and content certificates. This FIP can be used to verify the
+    include the corresponding certificates. This FIP can be used to verify the
     Chain of Trust on the host machine through other mechanisms.
 
     Note that if `TRUSTED_BOARD_BOOT=1` and `GENERATE_COT=0`, the BL1 and BL2
-    images will include support for Trusted Board Boot, but the FIP will not
-    include the key and content certificates, causing a boot failure.
+    images will include support for Trusted Board Boot, but the FIP and FWU_FIP
+    will not include the corresponding certificates, causing a boot failure.
 
 *   `CREATE_KEYS`: This option is used when `GENERATE_COT=1`. It tells the
     certificate generation tool to create new keys in case no valid keys are
@@ -617,11 +635,15 @@ The `cert_create` tool is automatically built with the `fip` target when
 `GENERATE_COT=1`.
 
 
-### Building a FIP image with support for Trusted Board Boot
+### Building FIP images with support for Trusted Board Boot
+
+Trusted Board Boot primarily consists of the following two features:
 
-The Trusted Board Boot feature is described in [Trusted Board Boot]. The
-following steps should be followed to build a FIP image with support for this
-feature.
+*   Image Authentication, described in [Trusted Board Boot], and
+*   Firmware Update, described in [Firmware Update]
+
+The following steps should be followed to build FIP and (optionally) FWU_FIP
+images with support for these features:
 
 1.  Fulfill the dependencies of the `mbedtls` cryptographic and image parser
     modules by checking out a recent version of the [mbed TLS Repository]. It
@@ -638,8 +660,8 @@ feature.
     license. Using mbed TLS source code will affect the licensing of
     Trusted Firmware binaries that are built using this library.
 
-2.  Ensure that the following command line variables are set while invoking
-    `make` to build Trusted Firmware:
+2.  To build the FIP image, ensure the following command line variables are set
+    while invoking `make` to build Trusted Firmware:
 
     *   `MBEDTLS_DIR=<path of the directory containing mbed TLS sources>`
     *   `TRUSTED_BOARD_BOOT=1`
@@ -677,6 +699,40 @@ feature.
     the Chain of Trust described in the TBBR-client document. These certificates
     can also be found in the output build directory.
 
+3.  The optional FWU_FIP contains any additional images to be loaded from
+    Non-Volatile storage during the [Firmware Update] process. To build the
+    FWU_FIP, any FWU images required by the platform must be specified on the
+    command line. On ARM development platforms like Juno, these are:
+
+    *   NS_BL2U. The AP non-secure Firmware Updater image.
+    *   SCP_BL2U. The SCP Firmware Update Configuration image.
+
+    Example of Juno command line for generating both `fwu` and `fwu_fip`
+    targets using RSA development:
+
+        CROSS_COMPILE=<path-to-aarch64-gcc>/bin/aarch64-none-elf-       \
+        BL33=<path-to>/<bl33_image>                                     \
+        SCP_BL2=<path-to>/<scp_bl2_image>                               \
+        SCP_BL2U=<path-to>/<scp_bl2u_image>                             \
+        NS_BL2U=<path-to>/<ns_bl2u_image>                               \
+        MBEDTLS_DIR=<path of the directory containing mbed TLS sources> \
+        make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1              \
+        ARM_ROTPK_LOCATION=devel_rsa                                    \
+        ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
+        all fip fwu_fip
+
+    Note:   The BL2U image will be built by default and added to the FWU_FIP.
+            The user may override this by adding `BL2U=<path-to>/<bl2u_image>`
+            to the command line above.
+
+    Note:   Building and installing the non-secure and SCP FWU images (NS_BL1U,
+            NS_BL2U and SCP_BL2U) is outside the scope of this document.
+
+    The result of this build will be bl1.bin, fip.bin and fwu_fip.bin binaries.
+    Both the FIP and FWU_FIP will include the certificates corresponding to the
+    Chain of Trust described in the TBBR-client document. These certificates
+    can also be found in the output build directory.
+
 
 ### Checking source code style
 
@@ -1308,3 +1364,4 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
 [mbed TLS Security Center]:    https://tls.mbed.org/security
 [PSCI]:                        http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf "Power State Coordination Interface PDD (ARM DEN 0022C)"
 [Trusted Board Boot]:          trusted-board-boot.md
+[Firmware Update]:             ./firmware-update.md