4.7.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 documentIHI 0093), which defines a standard firmware interface for installing firmwareupdates.On the other hand, TBBR Firmware Update only covers firmware recovery. Arguably,its name is somewhat misleading but the TBBR specification and terminologypredates PSA FWU. Both mechanisms are complementary in the sense that PSA FWUassumes that the device has a backup or recovery capability in the event of afailed update, which can be fulfilled with TBBR FWU implementation.

4.7.1.PSA Firmware Update (PSA FWU)

4.7.1.1.Introduction

ThePSA FW update specification defines the concepts ofFirmwareUpdateClient andFirmwareUpdateAgent.The new firmware images are provided by theClient to theUpdateAgentto flash them in non-volatile storage.

A common system design will place theUpdateAgent in the Secure-worldwhile theClient executes in the Normal-world.ThePSA FW update specification provides ABIs meant for a Normal-worldentity akaClient to transmit the firmware images to theUpdateAgent.

4.7.1.2.Scope

The design of theClient andUpdateAgent is out of scope of thisdocument.This document mainly coversPlatformBoot details i.e. the role ofthe second stage Bootloader after FWU has been done byClient andUpdateAgent.

4.7.1.3.Overview

There are active and update banks in the non-volatile storage identifiedby theactive_index and theupdate_index respectively.An active bank stores running firmware, whereas an update bank containsfirmware updates.

Once Firmwares are updated in the update bank of the non-volatilestorage, thenUpdateAgent 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 thefollowing actions:

  • Read FWU metadata in memory

  • Retrieve the image specification (offset and length) of updated imagespresent in non-volatile storage with the help of FWU metadata

  • Set these image specification in the corresponding I/O policies of theupdated images using the FWU platform functionsplat_fwu_set_images_source() andplat_fwu_set_metadata_image_source(),please referPorting 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 bootthe images intrialstate. If images pass through the authentication checkand also if the system successfully booted the Normal-world image thenUpdateAgent marks this update as accepted after further sanitisationchecking at Normal-world.

The second stage Bootloader (BL2) avoids upgrading the platform NV-counter untilit’s been confirmed that given update is accepted.

The following sequence diagram shows platform-boot flow:

../_images/PSA-FWU.png

If the platform fails to boot from active bank due to any reasons suchas authentication failure or non-fuctionality of Normal-world software then thewatchdog will reset to give a chance to the platform to fix the issue. Thisboot failure & reset sequence might be repeated up totrialstate times.After that, the platform can decide to boot from theprevious_active_indexbank.

If the images still does not boot successfully from theprevious_active_indexbank (e.g. due to ageing effect of non-volatile storage) then the platform canchoose firmware recovery mechanismTBBR Firmware Update (TBBR FWU) to bring systemback to life.

4.7.2.TBBR Firmware Update (TBBR FWU)

4.7.2.1.Introduction

This technique enables authenticated firmware to update firmware images fromexternal interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoCNon-Volatile memories such as NAND Flash, LPDDR2-NVM or any memory determinedby the platform.This feature functions even when the current firmware in the system is corruptor missing; it therefore may be used as a recovery mode. It may also becomplemented 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 theTrusted Board Boot design document, which describes the imageauthentication 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 outas part of thePSA Firmware Update (PSA FWU) procedure have failed to function.

4.7.2.2.Scope

This document describes the secure world FWU design. It is beyond its scope todescribe how normal world FWU images should operate. To implement normal worldFWU images, please refer to the “Non-Trusted Firmware Updater” requirements inthe TBBR.

4.7.2.3.Overview

The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, andit is usually desirable to minimize the amount of ROM code, the design allowssome 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 thegeneral 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 FWUprocess.

  • Other secure world FWU images handle platform initialization required bythe FWU process.

  • Normal world FWU images handle loading of firmware images from externalinterfaces to non-secure memory.

The primary requirements of the FWU feature are:

  1. Export a BL1 SMC interface to interoperate with other FWU images executingat other Exception Levels.

  2. Export a platform interface to provide FWU common code with the informationit needs, and to enable platform specific FWU functionality. See thePorting Guide for details of this interface.

TF-A uses abbreviated image terminology for FWU images like for other TF-Aimages. See theImage Terminology document for an explanation of theseterms.

The following diagram shows the FWU boot flow for Arm development platforms.Arm CSS platforms like Juno have a System Control Processor (SCP), and theseuse all defined FWU images. Other platforms may use a subset of these.

Flow Diagram

4.7.2.4.Image Identification

Each FWU image and certificate is identified by a unique ID, defined by theplatform, which BL1 uses to fetch an image descriptor (image_desc_t) via acall tobl1_plat_get_image_desc(). The same ID is also used to prepare theChain of Trust (Refer to theAuthentication Framework & Chain of Trustdocument for more information).

The image descriptor includes the following information:

  • Executable or non-executable image. This indicates whether the normal worldis permitted to request execution of a secure world FWU image (afterauthentication). Secure world certificates and non-AP images are examplesof non-executable images.

  • Secure or non-secure image. This indicates whether the image isauthenticated/executed in secure or non-secure memory.

  • Image base address and size.

  • Image entry point configuration (anentry_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.7.2.5.FWU State Machine

BL1 maintains state for each FWU image during FWU execution. FWU images at lowerException Levels raise SMCs to invoke FWU functionality in BL1, which causesBL1 to update its FWU image state. The BL1 image states and valid statetransitions are shown in the diagram below. Note that secure images have a morecomplex 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 secureimage may yield to this state if it has completed execution.It can also be reached by usingFWU_SMC_IMAGE_RESET.

  • COPYING: This is the state of a secure image while BL1 is copying itin blocks from non-secure to secure memory.

  • COPIED: This is the state of a secure image when BL1 has completedcopying it to secure memory.

  • AUTHENTICATED: This is the state of an image when BL1 has successfullyauthenticated it.

  • EXECUTED: This is the state of a secure, executable image when BL1 haspassed execution control to it.

  • INTERRUPTED: This is the state of a secure, executable image after it hasrequested BL1 to resume normal world execution.

4.7.2.6.BL1 SMC Interface

4.7.2.6.1.BL1_SMC_CALL_COUNT

Arguments:uint32_tfunctionID:0x0Return:uint32_t

This SMC returns the number of SMCs supported by BL1.

4.7.2.6.2.BL1_SMC_UID

Arguments:uint32_tfunctionID:0x1Return:UUID:32bitsineachofw0-w3(orr0-r3forAArch32callers)

This SMC returns the 128-bitUniversally Unique Identifier for theBL1 SMC service.

4.7.2.6.3.BL1_SMC_VERSION

Argument:uint32_tfunctionID:0x3Return:uint32_t:Bits[31:16]MajorVersionBits[15:0]MinorVersion

This SMC returns the current version of the BL1 SMC service.

4.7.2.6.4.BL1_SMC_RUN_IMAGE

Arguments:uint32_tfunctionID:0x4entry_point_info_t*ep_infoReturn:voidPre-conditions:if(normalworldcaller)synchronousexceptionif(ep_infonotEL3)synchronousexception

This SMC passes execution control to an EL3 image described by the providedentry_point_info_t structure. In the normal TF-A boot flow, BL2 invokesthis SMC for BL1 to pass execution control to BL31.

4.7.2.6.5.FWU_SMC_IMAGE_COPY

Arguments:uint32_tfunctionID:0x10unsignedintimage_iduintptr_timage_addrunsignedintblock_sizeunsignedintimage_sizeReturn:int:0(Success):-ENOMEM:-EPERMPre-conditions:if(image_idisinvalid)return-EPERMif(image_idisnon-secureimage)return-EPERMif(image_idstateisnot(RESETorCOPYING))return-EPERMif(secureworldcaller)return-EPERMif(image_addr+block_sizeoverflows)return-ENOMEMif(imagedestinationaddress+image_sizeoverflows)return-ENOMEMif(sourceblockisinsecurememory)return-ENOMEMif(sourceblockisnotmappedintoBL1)return-ENOMEMif(image_size>freesecurememory)return-ENOMEMif(imageoverlapsanotherimage)return-EPERM

This SMC copies the secure image indicated byimage_id from non-secure memoryto secure memory for later authentication. The image may be copied in a singleblock or multiple blocks. In either case, the total size of the image must beprovided inimage_size when invoking this SMC for the first time for eachimage; it is ignored in subsequent calls (if any) for the same image.

Theimage_addr andblock_size specify the source memory block to copy from.The destination address is provided by the platform code.

Ifblock_size is greater than the amount of remaining bytes to copy for thisimage then the former is truncated to the latter. The copy operation is thenconsidered 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 ortransitions to the COPYING state (depending on the previous state).

When using multiple blocks, the source blocks do not necessarily need to be incontiguous memory.

Once the SMC is handled, BL1 returns from exception to the normal world caller.

4.7.2.6.6.FWU_SMC_IMAGE_AUTH

Arguments:uint32_tfunctionID:0x11unsignedintimage_iduintptr_timage_addrunsignedintimage_sizeReturn:int:0(Success):-ENOMEM:-EPERM:-EAUTHPre-conditions:if(image_idisinvalid)return-EPERMif(secureworldcaller)if(image_idstateisnotRESET)return-EPERMif(image_addr/image_sizeisnotmappedintoBL1)return-ENOMEMelse//normalworldcallerif(image_idissecureimage)if(image_idstateisnotCOPIED)return-EPERMelse//image_idisnon-secureimageif(image_idstateisnotRESET)return-EPERMif(image_addr/image_sizeisinsecurememory)return-ENOMEMif(image_addr/image_sizenotmappedintoBL1)return-ENOMEM

This SMC authenticates the image specified byimage_id. If the image is in theRESET state, BL1 authenticates the image in place using the providedimage_addr andimage_size. If the image is a secure image in the COPIEDstate, BL1 authenticates the image from the secure memory that BL1 previouslycopied the image into.

BL1 returns from exception to the caller. If authentication succeeds then BL1sets the image state to AUTHENTICATED. If authentication fails then BL1 returnsthe -EAUTH error and sets the image state back to RESET.

4.7.2.6.7.FWU_SMC_IMAGE_EXECUTE

Arguments:uint32_tfunctionID:0x12unsignedintimage_idReturn:int:0(Success):-EPERMPre-conditions:if(image_idisinvalid)return-EPERMif(secureworldcaller)return-EPERMif(image_idisnon-secureimage)return-EPERMif(image_idisnon-executableimage)return-EPERMif(image_idstateisnotAUTHENTICATED)return-EPERM

This SMC initiates execution of a previously authenticated image specified byimage_id, in the other security world to the caller. The currentimplementation only supports normal world callers initiating execution of asecure world image.

BL1 saves the normal world caller’s context, sets the secure image state toEXECUTED, and returns from exception to the secure image.

4.7.2.6.8.FWU_SMC_IMAGE_RESUME

Arguments:uint32_tfunctionID:0x13register_timage_paramReturn:register_t:image_param(Success):-EPERMPre-conditions:if(normalworldcallerandnoINTERRUPTEDsecureimage)return-EPERM

This SMC resumes execution in the other security world while there is a secureimage in the EXECUTED/INTERRUPTED state.

For normal world callers, BL1 sets the previously interrupted secure image stateto EXECUTED. For secure world callers, BL1 sets the previously executing secureimage state to INTERRUPTED. In either case, BL1 saves the calling world’scontext, restores the resuming world’s context and returns from exception intothe resuming world. If the call is successful then the caller providedimage_param is returned to the resumed world, otherwise an error code isreturned to the caller.

4.7.2.6.9.FWU_SMC_SEC_IMAGE_DONE

Arguments:uint32_tfunctionID:0x14Return:int:0(Success):-EPERMPre-conditions:if(normalworldcaller)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 normalworld.

4.7.2.6.10.FWU_SMC_UPDATE_DONE

Arguments:uint32_tfunctionID:0x15register_tclient_cookieReturn:N/A

This SMC completes the firmware update process. BL1 calls the platform specificfunctionbl1_plat_fwu_done, passing the optional argumentclient_cookie asavoid*. The SMC does not return.

4.7.2.6.11.FWU_SMC_IMAGE_RESET

Arguments:uint32_tfunctionID:0x16unsignedintimage_idReturn:int:0(Success):-EPERMPre-conditions:if(secureworldcaller)return-EPERMif(imageinEXECUTED)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.