mirror of
https://github.com/CTCaer/switch-l4t-atf.git
synced 2025-01-31 15:22:32 +00:00
Merge pull request #472 from danh-arm/dh/fwu-docs
FWU: Add documentation for Firmware Update feature
This commit is contained in:
danh-arm
commit
6f0be12536
BIN
docs/diagrams/fwu_flow.png
Normal file
BIN
docs/diagrams/fwu_flow.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 163 KiB |
BIN
docs/diagrams/fwu_states.png
Normal file
BIN
docs/diagrams/fwu_states.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 112 KiB |
@ -194,9 +194,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
|
||||
@ -1728,3 +1740,4 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
|
||||
[Reset Design]: ./reset-design.md
|
||||
[INTRG]: ./interrupt-framework-design.md
|
||||
[CPUBM]: ./cpu-specific-build-macros.md.md
|
||||
[Firmware Update]: ./firmware-update.md
|
||||
|
||||
357
docs/firmware-update.md
Normal file
357
docs/firmware-update.md
Normal file
@ -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"
|
||||
@ -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]
|
||||
|
||||
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 @@ 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
|
||||
|
||||
@ -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)"
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
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 @@ 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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user