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>

docs/firmware-design.md

@@ -189,9 +189,21 @@ the CCI slave interface corresponding to the cluster that includes the
 primary CPU. BL1 also initializes a UART (PL011 console), which enables access
 to the `printf` family of functions in BL1.
 
+#### Firmware Update detection and execution
+
+After performing platform setup, BL1 common code calls
+`bl1_plat_get_next_image_id()` to determine if [Firmware Update] is required or
+to proceed with the normal boot process. If the platform code returns
+`BL2_IMAGE_ID` then the normal boot sequence is executed as described in the
+next section, else BL1 assumes that [Firmware Update] is required and execution
+passes to the first image in the [Firmware Update] process. In either case, BL1
+retrieves a descriptor of the next image by calling `bl1_plat_get_image_desc()`.
+The image descriptor contains an `entry_point_info_t` structure, which BL1
+uses to initialize the execution state of the next image.
+
 #### BL2 image load and execution
 
-BL1 execution continues as follows:
+In the normal boot flow, BL1 execution continues as follows:
 
 1.  BL1 determines the amount of free trusted SRAM memory available by
     calculating the extent of its own data section, which also resides in
@@ -1769,3 +1781,4 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
 [Porting Guide]:    ./porting-guide.md
 [INTRG]:            ./interrupt-framework-design.md
 [CPUBM]:            ./cpu-specific-build-macros.md.md
+[Firmware Update]:  ./firmware-update.md

docs/firmware-update.md

+ARM Trusted Firmware - Firmware Update Design Guide
+===================================================
+
+Contents :
+
+1.  [Introduction](#1-introduction)
+2.  [FWU Overview](#2-fwu-overview)
+3.  [Image Identification](#3-image-identification)
+4.  [FWU State Machine](#4-fwu-state-machine)
+5.  [SMC Interface](#5-smc-interface)
+
+- - - - - - - - - - - - - - - - - -
+
+1.  Introduction
+----------------
+
+This document describes the design of the Firmware Update (FWU) feature, which
+enables authenticated firmware to update firmware images from external
+interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile
+memories such as NAND Flash, LPPDR2-NVM or any memory determined by the
+platform. This feature functions even when the current firmware in the system
+is corrupt or missing; it therefore may be used as a recovery mode. It may also
+be complemented by other, higher level firmware update software.
+
+FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
+specification, ARM DEN0006C-1. It should be used in conjunction with the
+[Trusted Board Boot] design document, which describes the image authentication
+parts of the Trusted Firmware (TF) TBBR implementation.
+
+### Scope
+
+This document describes the secure world FWU design. It is beyond its scope to
+describe how normal world FWU images should operate. To implement normal world
+FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
+the TBBR.
+
+
+2. FWU Overview
+---------------
+
+The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
+it is usually desirable to minimize the amount of ROM code, the design allows
+some parts of FWU to be implemented in other secure and normal world images.
+Platform code may choose which parts are implemented in which images but the
+general expectation is:
+
+*   BL1 handles:
+    *   Detection and initiation of the FWU boot flow.
+    *   Copying images from non-secure to secure memory
+    *   FWU image authentication
+    *   Context switching between the normal and secure world during the FWU
+        process.
+*   Other secure world FWU images handle platform initialization required by
+    the FWU process.
+*   Normal world FWU images handle loading of firmware images from external
+    interfaces to non-secure memory.
+
+The primary requirements of the FWU feature are:
+
+1.  Export a BL1 SMC interface to interoperate with other FWU images executing
+    at other Exception Levels.
+2.  Export a platform interface to provide FWU common code with the information
+    it needs, and to enable platform specific FWU functionality. See the
+    [Porting Guide] for details of this interface.
+
+TF uses abbreviated image terminology for FWU images like for other TF images.
+An overview of this terminology can be found [here][TF Image Terminology].
+
+The following diagram shows the FWU boot flow for ARM development platforms.
+ARM CSS platforms like Juno have a System Control Processor (SCP), and these
+use all defined FWU images. Other platforms may use a subset of these.
+
+![Flow Diagram](diagrams/fwu_flow.png?raw=true)
+
+
+3. Image Identification
+-----------------------
+
+Each FWU image and certificate is identified by a unique ID, defined by the
+platform, which BL1 uses to fetch an image descriptor (`image_desc_t`) via a
+call to `bl1_plat_get_image_desc()`. The same ID is also used to prepare the
+Chain of Trust (Refer to the [Authentication Framework Design][Auth Framework]
+for more information).
+
+The image descriptor includes the following information:
+
+*   Executable or non-executable image. This indicates whether the normal world
+    is permitted to request execution of a secure world FWU image (after
+    authentication). Secure world certificates and non-AP images are examples
+    of non-executable images.
+*   Secure or non-secure image. This indicates whether the image is
+    authenticated/executed in secure or non-secure memory.
+*   Image base address and size.
+*   Image entry point configuration (an `entry_point_info_t`).
+*   FWU image state.
+
+BL1 uses the FWU image descriptors to:
+
+*   Validate the arguments of FWU SMCs
+*   Manage the state of the FWU process
+*   Initialize the execution state of the next FWU image.
+
+
+4.  FWU State Machine
+---------------------
+
+BL1 maintains state for each FWU image during FWU execution. FWU images at lower
+Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
+BL1 to update its FWU image state. The BL1 image states and valid state
+transitions are shown in the diagram below. Note that secure images have a more
+complex state machine than non-secure images.
+
+![FWU state machine](diagrams/fwu_states.png?raw=true)
+
+The following is a brief description of the supported states:
+
+*   RESET:         This is the initial state of every image at the start of FWU.
+                   Authentication failure also leads to this state. A secure
+                   image may yield to this state if it has completed execution.
+
+*   COPYING:       This is the state of a secure image while BL1 is copying it
+                   in blocks from non-secure to secure memory.
+
+*   COPIED:        This is the state of a secure image when BL1 has completed
+                   copying it to secure memory.
+
+*   AUTHENTICATED: This is the state of an image when BL1 has successfully
+                   authenticated it.
+
+*   EXECUTED:      This is the state of a secure, executable image when BL1 has
+                   passed execution control to it.
+
+*   INTERRUPTED:   This is the state of a secure, executable image after it has
+                   requested BL1 to resume normal world execution.
+
+
+5.  BL1 SMC Interface
+-----------------
+
+### BL1_SMC_CALL_COUNT
+
+    Arguments:
+        uint32_t function ID : 0x0
+
+    Return:
+        uint32_t
+
+This SMC returns the number of SMCs supported by BL1.
+
+### BL1_SMC_UID
+
+    Arguments:
+        uint32_t function ID : 0x1
+
+    Return:
+        UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
+
+This SMC returns the 128-bit [Universally Unique Identifier][UUID] for the
+BL1 SMC service.
+
+### BL1_SMC_VERSION
+
+    Argument:
+        uint32_t function ID : 0x3
+
+    Return:
+        uint32_t : Bits [31:16] Major Version
+                   Bits [15:0] Minor Version
+
+This SMC returns the current version of the BL1 SMC service.
+
+### BL1_SMC_RUN_IMAGE
+
+    Arguments:
+        uint32_t           function ID : 0x4
+        entry_point_info_t *ep_info
+
+    Return:
+        void
+
+    Pre-conditions:
+        if (normal world caller) synchronous exception
+        if (ep_info not EL3) synchronous exception
+
+This SMC passes execution control to an EL3 image described by the provided
+`entry_point_info_t` structure. In the normal TF boot flow, BL2 invokes this SMC
+for BL1 to pass execution control to BL31.
+
+
+### FWU_SMC_IMAGE_COPY
+
+    Arguments:
+        uint32_t     function ID : 0x10
+        unsigned int image_id
+        uintptr_t    image_addr
+        unsigned int block_size
+        unsigned int image_size
+
+    Return:
+        int : 0 (Success)
+            : -ENOMEM
+            : -EPERM
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (image_id is non-secure image) return -EPERM
+        if (image_id state is not (RESET or COPYING)) return -EPERM
+        if (secure world caller) return -EPERM
+        if (source block is in secure memory) return -ENOMEM
+        if (source block is not mapped into BL1) return -ENOMEM
+        if (image_size > free secure memory) return -ENOMEM
+
+This SMC copies the secure image indicated by `image_id` into secure memory. The
+image may be copied in a single block or multiple blocks. In either case, the
+total size of the image must be provided in `image_size` when invoking this SMC
+the first time for each image. The `image_addr` and `block_size` specify the
+source memory block to copy from. If `block_size` >= the size of the remaining
+image to copy, then BL1 completes the copy operation and sets the image state
+to COPIED. If there is still more to copy, BL1 sets the image state to COPYING.
+When using multiple blocks, the source blocks do not necessarily need to be in
+contiguous memory.
+
+BL1 returns from exception to the normal world caller.
+
+
+### FWU_SMC_IMAGE_AUTH
+
+    Arguments:
+        uint32_t     function ID : 0x11
+        unsigned int image_id
+        uintptr_t    image_addr
+        unsigned int image_size
+
+    Return:
+        int : 0 (Success)
+            : -ENOMEM
+            : -EPERM
+            : -EAUTH
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (secure world caller)
+            if (image_id state is not RESET) return -EPERM
+            if (image_addr/image_size is not mappped into BL1) return -ENOMEM
+        else // normal world caller
+            if (image_id is secure image)
+                if (image_id state is not COPIED) return -EPERM
+            else // image_id is non-secure image
+                if (image_id state is not RESET) return -EPERM
+                if (image_addr/image_size is in secure memory) return -ENOMEM
+                if (image_addr/image_size not mappped into BL1) return -ENOMEM
+
+This SMC authenticates the image specified by `image_id`. If the image is in the
+ RESET state, BL1 authenticates the image in place using the provided
+`image_addr` and `image_size`. If the image is a secure image in the COPIED
+state, BL1 authenticates the image from the secure memory that BL1 previously
+copied the image into.
+
+BL1 returns from exception to the caller. If authentication succeeds then BL1
+sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
+the -EAUTH error and sets the image state back to RESET.
+
+
+### FWU_SMC_IMAGE_EXECUTE
+
+    Arguments:
+        uint32_t     function ID : 0x12
+        unsigned int image_id
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (secure world caller) return -EPERM
+        if (image_id is non-secure image) return -EPERM
+        if (image_id is non-executable image) return -EPERM
+        if (image_id state is not AUTHENTICATED) return -EPERM
+
+This SMC initiates execution of a previously authenticated image specified by
+`image_id`, in the other security world to the caller. The current
+implementation only supports normal world callers initiating execution of a
+secure world image.
+
+BL1 saves the normal world caller's context, sets the secure image state to
+EXECUTED, and returns from exception to the secure image.
+
+
+### FWU_SMC_IMAGE_RESUME
+
+    Arguments:
+        uint32_t   function ID : 0x13
+        register_t image_param
+
+    Return:
+        register_t : image_param (Success)
+                   : -EPERM
+
+    Pre-conditions:
+        if (normal world caller and no INTERRUPTED secure image) return -EPERM
+
+This SMC resumes execution in the other security world while there is a secure
+image in the EXECUTED/INTERRUPTED state.
+
+For normal world callers, BL1 sets the previously interrupted secure image state
+to EXECUTED. For secure world callers, BL1 sets the previously executing secure
+image state to INTERRUPTED. In either case, BL1 saves the calling world's
+context, restores the resuming world's context and returns from exception into
+the resuming world. If the call is successful then the caller provided
+`image_param` is returned to the resumed world, otherwise an error code is
+returned to the caller.
+
+
+### FWU_SMC_SEC_IMAGE_DONE
+
+    Arguments:
+        uint32_t function ID : 0x14
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (normal world caller) return -EPERM
+
+This SMC indicates completion of a previously executing secure image.
+
+BL1 sets the previously executing secure image state to the RESET state,
+restores the normal world context and returns from exception into the normal
+world.
+
+
+### FWU_SMC_UPDATE_DONE
+
+    Arguments:
+        uint32_t   function ID : 0x15
+        register_t client_cookie
+
+    Return:
+        N/A
+
+This SMC completes the firmware update process. BL1 calls the platform specific
+function `bl1_plat_fwu_done`, passing the optional argument `client_cookie` as
+a `void *`. The SMC does not return.
+
+
+- - - - - - - - - - - - - - - - - - - - - - - - - -
+
+_Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
+
+
+[Porting Guide]:        ./porting-guide.md
+[Auth Framework]:       ./auth-framework.md
+[Trusted Board Boot]:   ./trusted-board-boot.md
+[TF Image Terminology]: https://github.com/ARM-software/arm-trusted-firmware/wiki/Trusted-Firmware-Image-Terminology
+[UUID]:                 https://tools.ietf.org/rfc/rfc4122.txt "A Universally Unique IDentifier (UUID) URN Namespace"

docs/porting-guide.md

@@ -13,10 +13,11 @@ Contents
 3.  [Boot Loader stage specific modifications](#3--modifications-specific-to-a-boot-loader-stage)
     *   [Boot Loader stage 1 (BL1)](#31-boot-loader-stage-1-bl1)
     *   [Boot Loader stage 2 (BL2)](#32-boot-loader-stage-2-bl2)
-    *   [Boot Loader stage 3-1 (BL31)](#32-boot-loader-stage-3-1-bl3-1)
-    *   [PSCI implementation (in BL31)](#33-power-state-coordination-interface-in-bl3-1)
-    *   [Interrupt Management framework (in BL31)](#34--interrupt-management-framework-in-bl3-1)
-    *   [Crash Reporting mechanism (in BL31)](#35--crash-reporting-mechanism-in-bl3-1)
+    *   [FWU Boot Loader stage 2 (BL2U)](#33-fwu-boot-loader-stage-2-bl2u)
+    *   [Boot Loader stage 3-1 (BL31)](#34-boot-loader-stage-3-1-bl31)
+    *   [PSCI implementation (in BL31)](#35-power-state-coordination-interface-in-bl31)
+    *   [Interrupt Management framework (in BL31)](#36--interrupt-management-framework-in-bl31)
+    *   [Crash Reporting mechanism (in BL31)](#37--crash-reporting-mechanism-in-bl31)
 4.  [Build flags](#4--build-flags)
 5.  [C Library](#5--c-library)
 6.  [Storage abstraction layer](#6--storage-abstraction-layer)
@@ -277,6 +278,67 @@ also be defined:
     BL33 content certificate identifier, used by BL2 to load the BL33 content
     certificate.
 
+*   **#define : FWU_CERT_ID**
+
+    Firmware Update (FWU) certificate identifier, used by NS_BL1U to load the
+    FWU content certificate.
+
+
+If the AP Firmware Updater Configuration image, BL2U is used, the following
+must also be defined:
+
+*   **#define : BL2U_BASE**
+
+    Defines the base address in secure memory where BL1 copies the BL2U binary
+    image. Must be aligned on a page-size boundary.
+
+*   **#define : BL2U_LIMIT**
+
+    Defines the maximum address in secure memory that the BL2U image can occupy.
+
+*   **#define : BL2U_IMAGE_ID**
+
+    BL2U image identifier, used by BL1 to fetch an image descriptor
+    corresponding to BL2U.
+
+If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the following
+must also be defined:
+
+*   **#define : SCP_BL2U_IMAGE_ID**
+
+    SCP_BL2U image identifier, used by BL1 to fetch an image descriptor
+    corresponding to SCP_BL2U.
+    NOTE: TF does not provide source code for this image.
+
+If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must
+also be defined:
+
+*   **#define : NS_BL1U_BASE**
+
+    Defines the base address in non-secure ROM where NS_BL1U executes.
+    Must be aligned on a page-size boundary.
+    NOTE: TF does not provide source code for this image.
+
+*   **#define : NS_BL1U_IMAGE_ID**
+
+    NS_BL1U image identifier, used by BL1 to fetch an image descriptor
+    corresponding to NS_BL1U.
+
+If the Non-Secure Firmware Updater, NS_BL2U is used, the following must also
+be defined:
+
+*   **#define : NS_BL2U_BASE**
+
+    Defines the base address in non-secure memory where NS_BL2U executes.
+    Must be aligned on a page-size boundary.
+    NOTE: TF does not provide source code for this image.
+
+*   **#define : NS_BL2U_IMAGE_ID**
+
+    NS_BL2U image identifier, used by BL1 to fetch an image descriptor
+    corresponding to NS_BL2U.
+
+
 If a SCP_BL2 image is supported by the platform, the following constants must
 also be defined:
 
@@ -630,9 +692,9 @@ The default implementation doesn't do anything, to avoid making assumptions
 about the way the platform displays its status information.
 
 This function receives the exception type as its argument. Possible values for
-exceptions types are listed in the [include/runtime_svc.h] header file. Note
-that these constants are not related to any architectural exception code; they
-are just an ARM Trusted Firmware convention.
+exceptions types are listed in the [include/common/bl_common.h] header file.
+Note that these constants are not related to any architectural exception code;
+they are just an ARM Trusted Firmware convention.
 
 
 ### Function : plat_reset_handler()
@@ -698,10 +760,12 @@ warm boot. For each CPU, BL1 is responsible for the following tasks:
     only this CPU executes the remaining BL1 code, including loading and passing
     control to the BL2 stage.
 
-3.  Loading the BL2 image from non-volatile storage into secure memory at the
+3.  Identifying and starting the Firmware Update process (if required).
+
+4.  Loading the BL2 image from non-volatile storage into secure memory at the
     address specified by the platform defined constant `BL2_BASE`.
 
-4.  Populating a `meminfo` structure with the following information in memory,
+5.  Populating a `meminfo` structure with the following information in memory,
     accessible by BL2 immediately upon entry.
 
         meminfo.total_base = Base address of secure RAM visible to BL2
@@ -766,7 +830,7 @@ MMU and data cache have been enabled.
 In ARM standard platforms, this function initializes the storage abstraction
 layer used to load the next bootloader image.
 
-This function helps fulfill requirement 3 above.
+This function helps fulfill requirement 4 above.
 
 
 ### Function : bl1_plat_sec_mem_layout() [mandatory]
@@ -789,7 +853,7 @@ This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
 populates a similar structure to tell BL2 the extents of memory available for
 its own use.
 
-This function helps fulfill requirement 3 above.
+This function helps fulfill requirements 4 and 5 above.
 
 
 ### Function : bl1_init_bl2_mem_layout() [optional]
@@ -809,26 +873,80 @@ in the **Memory layout on ARM development platforms** section in the
 [Firmware Design].
 
 
-### Function : bl1_plat_set_bl2_ep_info() [mandatory]
+### Function : bl1_plat_prepare_exit() [optional]
 
-    Argument : image_info *, entry_point_info *
+    Argument : entry_point_info_t *
     Return   : void
 
-This function is called after loading BL2 image and it can be used to overwrite
-the entry point set by loader and also set the security state and SPSR which
-represents the entry point system state for BL2.
+This function is called prior to exiting BL1 in response to the
+`BL1_SMC_RUN_IMAGE` SMC request raised by BL2. It should be used to perform
+platform specific clean up or bookkeeping operations before transferring
+control to the next image. It receives the address of the `entry_point_info_t`
+structure passed from BL2. This function runs with MMU disabled.
 
+### Function : bl1_plat_set_ep_info() [optional]
 
-### Function : bl1_plat_prepare_exit() [optional]
+    Argument : unsigned int image_id, entry_point_info_t *ep_info
+    Return   : void
 
-    Argument : entry_point_info_t *
+This function allows platforms to override `ep_info` for the given `image_id`.
+
+The default implementation just returns.
+
+### Function : bl1_plat_get_next_image_id() [optional]
+
+    Argument : void
+    Return   : unsigned int
+
+This and the following function must be overridden to enable the FWU feature.
+
+BL1 calls this function after platform setup to identify the next image to be
+loaded and executed. If the platform returns `BL2_IMAGE_ID` then BL1 proceeds
+with the normal boot sequence, which loads and executes BL2. If the platform
+returns a different image id, BL1 assumes that Firmware Update is required.
+
+The default implementation always returns `BL2_IMAGE_ID`. The ARM development
+platforms override this function to detect if firmware update is required, and
+if so, return the first image in the firmware update process.
+
+### Function : bl1_plat_get_image_desc() [optional]
+
+    Argument : unsigned int image_id
+    Return   : image_desc_t *
+
+BL1 calls this function to get the image descriptor information `image_desc_t`
+for the provided `image_id` from the platform.
+
+The default implementation always returns a common BL2 image descriptor. ARM
+standard platforms return an image descriptor corresponding to BL2 or one of
+the firmware update images defined in the Trusted Board Boot Requirements
+specification.
+
+### Function : bl1_plat_fwu_done() [optional]
+
+    Argument : unsigned int image_id, uintptr_t image_src,
+               unsigned int image_size
     Return   : void
 
-This function is called prior to exiting BL1 in response to the `RUN_IMAGE` SMC
-request raised by BL2. It should be used to perform platform specific clean up
-or bookkeeping operations before transferring control to the next image. It
-receives the address of the `entry_point_info_t` structure passed from BL2.
-This function runs with MMU disabled.
+BL1 calls this function when the FWU process is complete. It must not return.
+The platform may override this function to take platform specific action, for
+example to initiate the normal boot flow.
+
+The default implementation spins forever.
+
+### Function : bl1_plat_mem_check() [mandatory]
+
+    Argument : uintptr_t mem_base, unsigned int mem_size,
+               unsigned int flags
+    Return   : void
+
+BL1 calls this function while handling FWU copy and authenticate SMCs. The
+platform must ensure that the provided `mem_base` and `mem_size` are mapped into
+BL1, and that this memory corresponds to either a secure or non-secure memory
+region as indicated by the security state of the `flags` argument.
+
+The default implementation of this function asserts therefore platforms must
+override it when using the FWU feature.
 
 
 3.2 Boot Loader Stage 2 (BL2)
@@ -1083,7 +1201,86 @@ entrypoint of that image, which BL31 uses to jump to it.
 BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
 
 
-3.2 Boot Loader Stage 3-1 (BL31)
+3.3 FWU Boot Loader Stage 2 (BL2U)
+----------------------------------
+
+The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU
+process and is executed only by the primary CPU. BL1 passes control to BL2U at
+`BL2U_BASE`. BL2U executes in Secure-EL1 and is responsible for:
+
+1.  (Optional) Transfering the optional SCP_BL2U binary image from AP secure
+    memory to SCP RAM. BL2U uses the SCP_BL2U `image_info` passed by BL1.
+    `SCP_BL2U_BASE` defines the address in AP secure memory where SCP_BL2U
+    should be copied from. Subsequent handling of the SCP_BL2U image is
+    implemented by the platform specific `bl2u_plat_handle_scp_bl2u()` function.
+    If `SCP_BL2U_BASE` is not defined then this step is not performed.
+
+2.  Any platform specific setup required to perform the FWU process. For
+    example, ARM standard platforms initialize the TZC controller so that the
+    normal world can access DDR memory.
+
+The following functions must be implemented by the platform port to enable
+BL2U to perform the tasks mentioned above.
+
+### Function : bl2u_early_platform_setup() [mandatory]
+
+    Argument : meminfo *mem_info, void *plat_info
+    Return   : void
+
+This function executes with the MMU and data caches disabled. It is only
+called by the primary CPU. The arguments to this function is the address
+of the `meminfo` structure and platform specific info provided by BL1.
+
+The platform must copy the contents of the `mem_info` and `plat_info` into
+private storage as the original memory may be subsequently overwritten by BL2U.
+
+On ARM CSS platforms `plat_info` is interpreted as an `image_info_t` structure,
+to extract SCP_BL2U image information, which is then copied into a private
+variable.
+
+### Function : bl2u_plat_arch_setup() [mandatory]
+
+    Argument : void
+    Return   : void
+
+This function executes with the MMU and data caches disabled. It is only
+called by the primary CPU.
+
+The purpose of this function is to perform any architectural initialization
+that varies across platforms, for example enabling the MMU (since the memory
+map differs across platforms).
+
+### Function : bl2u_platform_setup() [mandatory]
+
+    Argument : void
+    Return   : void
+
+This function may execute with the MMU and data caches enabled if the platform
+port does the necessary initialization in `bl2u_plat_arch_setup()`. It is only
+called by the primary CPU.
+
+The purpose of this function is to perform any platform initialization
+specific to BL2U.
+
+In ARM standard platforms, this function performs security setup, including
+configuration of the TrustZone controller to allow non-secure masters access
+to most of DRAM. Part of DRAM is reserved for secure world use.
+
+### Function : bl2u_plat_handle_scp_bl2u() [optional]
+
+    Argument : void
+    Return   : int
+
+This function is used to perform any platform-specific actions required to
+handle the SCP firmware. Typically it transfers the image into SCP memory using
+a platform-specific protocol and waits until SCP executes it and signals to the
+Application Processor (AP) for BL2U execution to continue.
+
+This function returns 0 on success, a negative error code otherwise.
+This function is included if SCP_BL2U_BASE is defined.
+
+
+3.4 Boot Loader Stage 3-1 (BL31)
 ---------------------------------
 
 During cold boot, the BL31 stage is executed only by the primary CPU. This is
@@ -1232,7 +1429,7 @@ modes table.
    assertion is raised if the value of the constant is not aligned to the cache
    line boundary.
 
-3.3 Power State Coordination Interface (in BL31)
+3.5 Power State Coordination Interface (in BL31)
 ------------------------------------------------
 
 The ARM Trusted Firmware's implementation of the PSCI API is based around the
@@ -1441,7 +1638,7 @@ domain level specific local states to suspend to system affinity level. The
 enter system suspend.
 
 
-3.4  Interrupt Management framework (in BL31)
+3.6  Interrupt Management framework (in BL31)
 ----------------------------------------------
 BL31 implements an Interrupt Management Framework (IMF) to manage interrupts
 generated in either security state and targeted to EL1 or EL2 in the non-secure
@@ -1630,7 +1827,7 @@ Register_ (`GICD_IGROUPRn`) and _Interrupt Group Modifier Register_
 as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
 
 
-3.5  Crash Reporting mechanism (in BL31)
+3.7  Crash Reporting mechanism (in BL31)
 ----------------------------------------------
 BL31 implements a crash reporting mechanism which prints the various registers
 of the CPU to enable quick crash analysis and debugging. It requires that a
@@ -1782,11 +1979,12 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
 [Power Domain Topology Design]:           psci-pd-tree.md
 [PSCI]:                                   http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 [Migration Guide]:                        platform-migration-guide.md
+[Firmware Update]:                        firmware-update.md
 
 [plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S
 [plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S
 [plat/arm/board/fvp/fvp_pm.c]:             ../plat/arm/board/fvp/fvp_pm.c
-[include/runtime_svc.h]:                   ../include/runtime_svc.h
+[include/common/bl_common.h]:              ../include/common/bl_common.h
 [include/plat/arm/common/arm_def.h]:       ../include/plat/arm/common/arm_def.h
 [include/plat/common/common_def.h]:        ../include/plat/common/common_def.h
 [include/plat/common/platform.h]:          ../include/plat/common/platform.h

docs/rt-svc-writers-guide.md

@@ -114,7 +114,7 @@ initialization and call handler functions.
     is also used for diagnostic purposes
 
 *   `_start` and `_end` values must be based on the `OEN_*` values defined in
-    [`runtime_svc.h`]
+    [`smcc_helpers.h`]
 
 *   `_type` must be one of `SMC_TYPE_FAST` or `SMC_TYPE_STD`
 
@@ -305,5 +305,6 @@ _Copyright (c) 2014, ARM Limited and Contributors. All rights reserved._
 [`services/std_svc/psci`]:  ../services/std_svc/psci
 [`std_svc_setup.c`]:        ../services/std_svc/std_svc_setup.c
 [`runtime_svc.h`]:          ../include/runtime_svc.h
+[`smcc_helpers.h`]:          ../include/common/smcc_helpers.h
 [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)"
 [SMCCC]:                    http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"

docs/trusted-board-boot.md

@@ -18,10 +18,10 @@ the platform by authenticating all firmware images up to and including the
 normal world bootloader. It does this by establishing a Chain of Trust using
 Public-Key-Cryptography Standards (PKCS).
 
-This document describes the design of the ARM Trusted Firmware TBB
-implementation. The current implementation is a proof of concept; future
-versions will provide stronger architectural interfaces and implement the
-missing functionality required in a production TBB-enabled system.
+This document describes the design of ARM Trusted Firmware TBB, which is an
+implementation of the Trusted Board Boot Requirements (TBBR) specification,
+ARM DEN0006C-1. It should be used in conjunction with the [Firmware Update]
+design document, which implements a specific aspect of the TBBR.
 
 
 2.  Chain of Trust
@@ -248,3 +248,4 @@ _Copyright (c) 2015, ARM Limited and Contributors. All rights reserved._
 [X.690]:             http://www.itu.int/ITU-T/studygroups/com17/languages/X.690-0207.pdf
 [Auth Framework]:    auth-framework.md
 [User Guide]:        user-guide.md
+[Firmware Update]:   firmware-update.md

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