Merge "docs(fwu): update firmware update design" into integration

docs/components/firmware-update.rst

@@ -1,22 +1,118 @@
 Firmware Update (FWU)
 =====================
 
-Introduction
+This document describes the design of the various Firmware Update (FWU)
-------------
+mechanisms available in TF-A.
 
-This document describes the design of the Firmware Update (FWU) feature, which
+1. PSA Firmware Update (PSA FWU)
-enables authenticated firmware to update firmware images from external
+2. TBBR Firmware Update (TBBR FWU)
-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
+PSA Firmware Update implements the specification of the same name (Arm document
-platform. This feature functions even when the current firmware in the system
+IHI 0093), which defines a standard firmware interface for installing firmware
-is corrupt or missing; it therefore may be used as a recovery mode. It may also
+updates.
-be complemented by other, higher level firmware update software.
+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
 ~~~~~
 
@@ -25,8 +121,8 @@ 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.
 
-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
@@ -66,7 +162,7 @@ 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
@@ -93,7 +189,7 @@ BL1 uses the FWU image descriptors to:
 -  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
@@ -126,10 +222,10 @@ The following is a brief description of the supported states:
    requested BL1 to resume normal world execution.
 
 BL1 SMC Interface
------------------
+~~~~~~~~~~~~~~~~~
 
 BL1_SMC_CALL_COUNT
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -142,7 +238,7 @@ BL1_SMC_CALL_COUNT
 This SMC returns the number of SMCs supported by BL1.
 
 BL1_SMC_UID
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 ::
 
@@ -156,7 +252,7 @@ This SMC returns the 128-bit `Universally Unique Identifier`_ for the
 BL1 SMC service.
 
 BL1_SMC_VERSION
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 ::
 
@@ -170,7 +266,7 @@ BL1_SMC_VERSION
 This SMC returns the current version of the BL1 SMC service.
 
 BL1_SMC_RUN_IMAGE
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -190,7 +286,7 @@ This SMC passes execution control to an EL3 image described by the provided
 this SMC for BL1 to pass execution control to BL31.
 
 FWU_SMC_IMAGE_COPY
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -239,7 +335,7 @@ contiguous memory.
 Once the SMC is handled, BL1 returns from exception to the normal world caller.
 
 FWU_SMC_IMAGE_AUTH
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -279,7 +375,7 @@ 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
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -307,7 +403,7 @@ 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
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -334,7 +430,7 @@ the resuming world. If the call is successful then the caller provided
 returned to the caller.
 
 FWU_SMC_SEC_IMAGE_DONE
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -355,7 +451,7 @@ restores the normal world context and returns from exception into the normal
 world.
 
 FWU_SMC_UPDATE_DONE
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -371,7 +467,7 @@ function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie``
 a ``void *``. The SMC does not return.
 
 FWU_SMC_IMAGE_RESET
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -393,8 +489,9 @@ This is only allowed if the image is not being executed.
 
 --------------
 
-*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/

docs/resources/diagrams/Makefile

@@ -73,7 +73,13 @@ RMM_EL3_MANIFEST_PNG			= rmm_el3_manifest_struct.png
 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,$@)),$<)
@@ -90,3 +96,6 @@ $(RMM_PNG):$(RMM_DIA)
 
 $(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,$@)),$<)