You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
412 lines
13 KiB
412 lines
13 KiB
Trusted Firmware-A - Firmware Update design guide
|
|
=================================================
|
|
|
|
|
|
.. section-numbering::
|
|
:suffix: .
|
|
|
|
.. contents::
|
|
|
|
--------------
|
|
|
|
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-A (TF-A) 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.
|
|
|
|
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:
|
|
|
|
#. Export a BL1 SMC interface to interoperate with other FWU images executing
|
|
at other Exception Levels.
|
|
#. 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-A uses abbreviated image terminology for FWU images like for other TF-A
|
|
images. An overview of this terminology can be found `here`_.
|
|
|
|
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|
|
|
|
|
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`_
|
|
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.
|
|
|
|
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|
|
|
|
|
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.
|
|
It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
|
|
|
|
- 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.
|
|
|
|
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`_ 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-A 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 (image_addr + block_size overflows) return -ENOMEM
|
|
if (image destination address + image_size overflows) return -ENOMEM
|
|
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
|
|
if (image overlaps another image) return -EPERM
|
|
|
|
This SMC copies the secure image indicated by ``image_id`` from non-secure memory
|
|
to secure memory for later authentication. 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 for the first time for each
|
|
image; it is ignored in subsequent calls (if any) for the same image.
|
|
|
|
The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
|
|
The destination address is provided by the platform code.
|
|
|
|
If ``block_size`` is greater than the amount of remaining bytes to copy for this
|
|
image then the former is truncated to the latter. The copy operation is then
|
|
considered as complete and the FWU state machine transitions to the "COPIED"
|
|
state. If there is still more to copy, the FWU state machine stays in or
|
|
transitions to the COPYING state (depending on the previous state).
|
|
|
|
When using multiple blocks, the source blocks do not necessarily need to be in
|
|
contiguous memory.
|
|
|
|
Once the SMC is handled, 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.
|
|
|
|
FWU\_SMC\_IMAGE\_RESET
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
::
|
|
|
|
Arguments:
|
|
uint32_t function ID : 0x16
|
|
unsigned int image_id
|
|
|
|
Return:
|
|
int : 0 (Success)
|
|
: -EPERM
|
|
|
|
Pre-conditions:
|
|
if (secure world caller) return -EPERM
|
|
if (image in EXECUTED) return -EPERM
|
|
|
|
This SMC sets the state of an image to RESET and zeroes the memory used by it.
|
|
|
|
This is only allowed if the image is not being executed.
|
|
|
|
--------------
|
|
|
|
*Copyright (c) 2015-2018, Arm Limited and Contributors. All rights reserved.*
|
|
|
|
.. _Trusted Board Boot: ./trusted-board-boot.rst
|
|
.. _Porting Guide: ./porting-guide.rst
|
|
.. _here: https://github.com/ARM-software/arm-trusted-firmware/wiki/ARM-Trusted-Firmware-Image-Terminology
|
|
.. _Authentication Framework Design: ./auth-framework.rst
|
|
.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
|
|
|
|
.. |Flow Diagram| image:: diagrams/fwu_flow.png?raw=true
|
|
.. |FWU state machine| image:: diagrams/fwu_states.png?raw=true
|
|
|