Merge pull request #473 from labapart/documentation-clean-legacy-variables
Documentation: Clean legacy variables in User Guide
diff --git a/docs/diagrams/fwu_flow.png b/docs/diagrams/fwu_flow.png
new file mode 100644
index 0000000..534095f
--- /dev/null
+++ b/docs/diagrams/fwu_flow.png
Binary files differ
diff --git a/docs/diagrams/fwu_states.png b/docs/diagrams/fwu_states.png
new file mode 100644
index 0000000..fda4d8f
--- /dev/null
+++ b/docs/diagrams/fwu_states.png
Binary files differ
diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index fb94f56..c32f0bd 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -194,9 +194,21 @@
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
@@ -1728,3 +1740,4 @@
[Reset Design]: ./reset-design.md
[INTRG]: ./interrupt-framework-design.md
[CPUBM]: ./cpu-specific-build-macros.md.md
+[Firmware Update]: ./firmware-update.md
diff --git a/docs/firmware-update.md b/docs/firmware-update.md
new file mode 100644
index 0000000..419ac85
--- /dev/null
+++ b/docs/firmware-update.md
@@ -0,0 +1,357 @@
+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.
+
+
+
+
+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.
+
+
+
+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"
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index 5d903e6..57e167b 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -13,10 +13,11 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
[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
+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]
+
-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.
+ 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 @@
BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
+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.2 Boot Loader Stage 3-1 (BL31)
+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 @@
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 @@
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 @@
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 @@
[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
diff --git a/docs/rt-svc-writers-guide.md b/docs/rt-svc-writers-guide.md
index 947f4a5..e9d489c 100644
--- a/docs/rt-svc-writers-guide.md
+++ b/docs/rt-svc-writers-guide.md
@@ -114,7 +114,7 @@
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 @@
[`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)"
diff --git a/docs/trusted-board-boot.md b/docs/trusted-board-boot.md
index 40b1e10..f076cd3 100644
--- a/docs/trusted-board-boot.md
+++ b/docs/trusted-board-boot.md
@@ -18,10 +18,10 @@
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 @@
[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
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 32bf73d..45b6f50 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -208,6 +208,21 @@
* `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 @@
* `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 @@
`GENERATE_COT=1`.
-### Building a FIP image with support for Trusted Board Boot
+### Building FIP images with support for Trusted Board Boot
-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.
+Trusted Board Boot primarily consists of the following two features:
+
+* 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 @@
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 @@
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
@@ -1302,3 +1358,4 @@
[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
