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. + +![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" 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] - - Argument : image_info *, entry_point_info * - 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. - - ### Function : bl1_plat_prepare_exit() [optional] Argument : entry_point_info_t * 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. +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] + + Argument : unsigned int image_id, entry_point_info_t *ep_info + Return : void + +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] + + 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.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 @@ 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 fa39c4b..3d4033e 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=` * `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=/bin/aarch64-none-elf- \ + BL33=/ \ + SCP_BL2=/ \ + SCP_BL2U=/ \ + NS_BL2U=/ \ + MBEDTLS_DIR= \ + 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=/` + 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 @@ [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