diff options
Diffstat (limited to '')
| -rw-r--r-- | docs/components/firmware-update.rst | 497 |
1 files changed, 497 insertions, 0 deletions
diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst new file mode 100644 index 0000000..1ba1e1c --- /dev/null +++ b/docs/components/firmware-update.rst @@ -0,0 +1,497 @@ +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/ |