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.
-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, 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.
+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
~~~~~
FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
the TBBR.
-FWU Overview
-------------
+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
|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
- 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
requested BL1 to resume normal world execution.
BL1 SMC Interface
------------------
+~~~~~~~~~~~~~~~~~
BL1_SMC_CALL_COUNT
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
::
This SMC returns the number of SMCs supported by BL1.
BL1_SMC_UID
-~~~~~~~~~~~
+^^^^^^^^^^^
::
BL1 SMC service.
BL1_SMC_VERSION
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
::
This SMC returns the current version of the BL1 SMC service.
BL1_SMC_RUN_IMAGE
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
::
this SMC for BL1 to pass execution control to BL31.
FWU_SMC_IMAGE_COPY
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
::
Once the SMC is handled, BL1 returns from exception to the normal world caller.
FWU_SMC_IMAGE_AUTH
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
::
the -EAUTH error and sets the image state back to RESET.
FWU_SMC_IMAGE_EXECUTE
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
::
EXECUTED, and returns from exception to the secure image.
FWU_SMC_IMAGE_RESUME
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
::
returned to the caller.
FWU_SMC_SEC_IMAGE_DONE
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
::
world.
FWU_SMC_UPDATE_DONE
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
::
a ``void *``. The SMC does not return.
FWU_SMC_IMAGE_RESET
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
::
--------------
-*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
+*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/
rmm_el3_manifest_struct_layers = "Background"
rmm_el3_manifest_struct_opts =
-all:$(RESET_PNGS) $(INT_PNGS) $(XLAT_PNG) $(RMM_PNG) $(RMM_EL3_MANIFEST_PNG)
+PSA_FWU_DIA = PSA-FWU.dia
+PSA_FWU_PNG = PSA-FWU.png
+
+FWU-update_struct_layers = "background"
+FWU-update_struct_opts =
+
+all:$(RESET_PNGS) $(INT_PNGS) $(XLAT_PNG) $(RMM_PNG) $(RMM_EL3_MANIFEST_PNG) $(PSA_FWU_PNG)
$(RESET_PNGS):$(RESET_DIA)
$(call generate_image,$($(patsubst %.png,%_layers,$@)),$@,png,$($(patsubst %.png,%_opts,$@)),$<)
$(RMM_EL3_MANIFEST_PNG):$(RMM_EL3_MANIFEST_DIA)
$(call generate_image,$($(patsubst %.png,%_layers,$@)),$@,png,$($(patsubst %.png,%_opts,$@)),$<)
+
+$(PSA_FWU_PNG):$(PSA_FWU_DIA)
+ $(call generate_image,$($(patsubst %.png,%_layers,$@)),$@,png,$($(patsubst %.png,%_opts,$@)),$<)
projects / arm-tf.git / commitdiff
