| Firmware Update (FWU) |
| ===================== |
| |
| This document describes the design of the various Firmware Update (FWU) |
| mechanisms available in TF-A. |
| |
| 1. PSA Firmware Update (PSA FWU) |
| 2. TBBR Firmware Update (TBBR FWU) |
| |
| PSA Firmware Update implements the specification of the same name (Arm document |
| IHI 0093), which defines a standard firmware interface for installing firmware |
| updates. |
| On the other hand, TBBR Firmware Update only covers firmware recovery. Arguably, |
| its name is somewhat misleading but the TBBR specification and terminology |
| predates PSA FWU. Both mechanisms are complementary in the sense that PSA FWU |
| assumes that the device has a backup or recovery capability in the event of a |
| failed update, which can be fulfilled with TBBR FWU implementation. |
| |
| .. _PSA Firmware Update: |
| |
| PSA Firmware Update (PSA FWU) |
| ----------------------------- |
| |
| Introduction |
| ~~~~~~~~~~~~ |
| The `PSA FW update specification`_ defines the concepts of ``Firmware Update |
| Client`` and ``Firmware Update Agent``. |
| The new firmware images are provided by the ``Client`` to the ``Update Agent`` |
| to flash them in non-volatile storage. |
| |
| A common system design will place the ``Update Agent`` in the Secure-world |
| while the ``Client`` executes in the Normal-world. |
| The `PSA FW update specification`_ provides ABIs meant for a Normal-world |
| entity aka ``Client`` to transmit the firmware images to the ``Update Agent``. |
| |
| Scope |
| ~~~~~ |
| The design of the ``Client`` and ``Update Agent`` is out of scope of this |
| document. |
| This document mainly covers ``Platform Boot`` details i.e. the role of |
| the second stage Bootloader after FWU has been done by ``Client`` and |
| ``Update Agent``. |
| |
| Overview |
| ~~~~~~~~ |
| |
| There are active and update banks in the non-volatile storage identified |
| by the ``active_index`` and the ``update_index`` respectively. |
| An active bank stores running firmware, whereas an update bank contains |
| firmware updates. |
| |
| Once Firmwares are updated in the update bank of the non-volatile |
| storage, then ``Update Agent`` marks the update bank as the active bank, |
| and write updated FWU metadata in non-volatile storage. |
| On subsequent reboot, the second stage Bootloader (BL2) performs the |
| following actions: |
| |
| - Read FWU metadata in memory |
| - Retrieve the image specification (offset and length) of updated images |
| present in non-volatile storage with the help of FWU metadata |
| - Set these image specification in the corresponding I/O policies of the |
| updated images using the FWU platform functions |
| ``plat_fwu_set_images_source()`` and ``plat_fwu_set_metadata_image_source()``, |
| please refer :ref:`Porting Guide` |
| - Use these I/O policies to read the images from this address into the memory |
| |
| By default, the platform uses the active bank of non-volatile storage to boot |
| the images in ``trial state``. If images pass through the authentication check |
| and also if the system successfully booted the Normal-world image then |
| ``Update Agent`` marks this update as accepted after further sanitisation |
| checking at Normal-world. |
| |
| The second stage Bootloader (BL2) avoids upgrading the platform NV-counter until |
| it's been confirmed that given update is accepted. |
| |
| The following sequence diagram shows platform-boot flow: |
| |
| .. image:: ../resources/diagrams/PSA-FWU.png |
| |
| If the platform fails to boot from active bank due to any reasons such |
| as authentication failure or non-fuctionality of Normal-world software then the |
| watchdog will reset to give a chance to the platform to fix the issue. This |
| boot failure & reset sequence might be repeated up to ``trial state`` times. |
| After that, the platform can decide to boot from the ``previous_active_index`` |
| bank. |
| |
| If the images still does not boot successfully from the ``previous_active_index`` |
| bank (e.g. due to ageing effect of non-volatile storage) then the platform can |
| choose firmware recovery mechanism :ref:`TBBR Firmware Update` to bring system |
| back to life. |
| |
| .. _TBBR Firmware Update: |
| |
| TBBR Firmware Update (TBBR FWU) |
| ------------------------------- |
| |
| Introduction |
| ~~~~~~~~~~~~ |
| |
| This technique 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, LPDDR2-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 |
| :ref:`Trusted Board Boot` design document, which describes the image |
| authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation. |
| |
| It can be used as a last resort when all firmware updates that are carried out |
| as part of the :ref:`PSA Firmware Update` procedure have failed to function. |
| |
| 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. |
| |
| 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 |
| :ref:`Porting Guide` for details of this interface. |
| |
| TF-A uses abbreviated image terminology for FWU images like for other TF-A |
| images. See the :ref:`Image Terminology` document for an explanation of these |
| terms. |
| |
| 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 :ref:`Authentication Framework & Chain of Trust` |
| document 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 mapped 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 mapped 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-2022, Arm Limited and Contributors. All rights reserved.* |
| |
| .. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt |
| .. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png |
| .. |FWU state machine| image:: ../resources/diagrams/fwu_states.png |
| .. _PSA FW update specification: https://developer.arm.com/documentation/den0118/a/ |