docs/components/firmware-update.rst

4 This document describes the design of the various Firmware Update (FWU)
10 PSA Firmware Update implements the specification of the same name (Arm document
13 On the other hand, TBBR Firmware Update only covers firmware recovery. Arguably,
14 its name is somewhat misleading but the TBBR specification and terminology
15 predates PSA FWU. Both mechanisms are complementary in the sense that PSA FWU
16 assumes that the device has a backup or recovery capability in the event of a
26 The `PSA FW update specification`_ defines the concepts of ``Firmware Update
28 The new firmware images are provided by the ``Client`` to the ``Update Agent``
31 A common system design will place the ``Update Agent`` in the Secure-world
32 while the ``Client`` executes in the Normal-world.
34 entity aka ``Client`` to transmit the firmware images to the ``Update Agent``.
38 The design of the ``Client`` and ``Update Agent`` is out of scope of this
40 This document mainly covers ``Platform Boot`` details i.e. the role of
41 the second stage Bootloader after FWU has been done by ``Client`` and
47 There are active and update banks in the non-volatile storage identified
48 by the ``active_index`` and the ``update_index`` respectively.
52 Once Firmwares are updated in the update bank of the non-volatile
53 storage, then ``Update Agent`` marks the update bank as the active bank,
55 On subsequent reboot, the second stage Bootloader (BL2) performs the
59 -  Retrieve the image specification (offset and length) of updated images
60    present in non-volatile storage with the help of FWU metadata
61 -  Set these image specification in the corresponding I/O policies of the
62    updated images using the FWU platform functions
65 -  Use these I/O policies to read the images from this address into the memory
67 By default, the platform uses the active bank of non-volatile storage to boot
68 the images in ``trial state``. If images pass through the authentication check
69 and also if the system successfully booted the Normal-world image then
73 The second stage Bootloader (BL2) avoids upgrading the platform NV-counter until
80 If the platform fails to boot from active bank due to any reasons such
81 as authentication failure or non-fuctionality of Normal-world software then the
82 watchdog will reset to give a chance to the platform to fix the issue. This
84 After that, the platform can decide to boot from the ``previous_active_index``
87 If the images still does not boot successfully from the ``previous_active_index``
88 bank (e.g. due to ageing effect of non-volatile storage) then the platform can
103 by the platform.
104 This feature functions even when the current firmware in the system is corrupt
108 FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
109 specification, Arm DEN0006C-1. It should be used in conjunction with the
110 :ref:`Trusted Board Boot` design document, which describes the image
111 authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation.
114 as part of the :ref:`PSA Firmware Update` procedure have failed to function.
119 This document describes the secure world FWU design. It is beyond its scope to
121 FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
122 the TBBR.
128 it is usually desirable to minimize the amount of ROM code, the design allows
130 Platform code may choose which parts are implemented in which images but the
135    -  Detection and initiation of the FWU boot flow.
138    -  Context switching between the normal and secure world during the FWU
142    the FWU process.
146 The primary requirements of the FWU feature are:
150 #. Export a platform interface to provide FWU common code with the information
151    it needs, and to enable platform specific FWU functionality. See the
155 images. See the :ref:`Image Terminology` document for an explanation of these
158 The following diagram shows the FWU boot flow for Arm development platforms.
167 Each FWU image and certificate is identified by a unique ID, defined by the
169 call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
170 Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust`
173 The image descriptor includes the following information:
175 -  Executable or non-executable image. This indicates whether the normal world
179 -  Secure or non-secure image. This indicates whether the image is
185 BL1 uses the FWU image descriptors to:
187 -  Validate the arguments of FWU SMCs
188 -  Manage the state of the FWU process
189 -  Initialize the execution state of the next FWU image.
197 transitions are shown in the diagram below. Note that secure images have a more
202 The following is a brief description of the supported states:
204 -  RESET: This is the initial state of every image at the start of FWU.
209 -  COPYING: This is the state of a secure image while BL1 is copying it
212 -  COPIED: This is the state of a secure image when BL1 has completed
215 -  AUTHENTICATED: This is the state of an image when BL1 has successfully
218 -  EXECUTED: This is the state of a secure, executable image when BL1 has
221 -  INTERRUPTED: This is the state of a secure, executable image after it has
238 This SMC returns the number of SMCs supported by BL1.
251 This SMC returns the 128-bit `Universally Unique Identifier`_ for the
266 This SMC returns the current version of the BL1 SMC service.
284 This SMC passes execution control to an EL3 image described by the provided
285 ``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
317 This SMC copies the secure image indicated by ``image_id`` from non-secure memory
319 block or multiple blocks. In either case, the total size of the image must be
320 provided in ``image_size`` when invoking this SMC for the first time for each
321 image; it is ignored in subsequent calls (if any) for the same image.
323 The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
324 The destination address is provided by the platform code.
326 If ``block_size`` is greater than the amount of remaining bytes to copy for this
327 image then the former is truncated to the latter. The copy operation is then
328 considered as complete and the FWU state machine transitions to the "COPIED"
329 state. If there is still more to copy, the FWU state machine stays in or
330 transitions to the COPYING state (depending on the previous state).
332 When using multiple blocks, the source blocks do not necessarily need to be in
335 Once the SMC is handled, BL1 returns from exception to the normal world caller.
367 This SMC authenticates the image specified by ``image_id``. If the image is in the
368 RESET state, BL1 authenticates the image in place using the provided
369 ``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
370 state, BL1 authenticates the image from the secure memory that BL1 previously
371 copied the image into.
373 BL1 returns from exception to the caller. If authentication succeeds then BL1
374 sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
375 the -EAUTH error and sets the image state back to RESET.
398 ``image_id``, in the other security world to the caller. The current
402 BL1 saves the normal world caller's context, sets the secure image state to
403 EXECUTED, and returns from exception to the secure image.
421 This SMC resumes execution in the other security world while there is a secure
422 image in the EXECUTED/INTERRUPTED state.
424 For normal world callers, BL1 sets the previously interrupted secure image state
425 to EXECUTED. For secure world callers, BL1 sets the previously executing secure
426 image state to INTERRUPTED. In either case, BL1 saves the calling world's
427 context, restores the resuming world's context and returns from exception into
428 the resuming world. If the call is successful then the caller provided
429 ``image_param`` is returned to the resumed world, otherwise an error code is
430 returned to the caller.
449 BL1 sets the previously executing secure image state to the RESET state,
450 restores the normal world context and returns from exception into the normal
465 This SMC completes the firmware update process. BL1 calls the platform specific
466 function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
486 This SMC sets the state of an image to RESET and zeroes the memory used by it.
488 This is only allowed if the image is not being executed.