docs(fwu): update firmware update design
Refactored legacy firmware design and added details about PSA
firmware updates.
Signed-off-by: Manish V Badarkhe <Manish.Badarkhe@arm.com>
Change-Id: I9c123b3f62580d4271dbaff0a728b6412fae7890
diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst
index a591565..1ba1e1c 100644
--- a/docs/components/firmware-update.rst
+++ b/docs/components/firmware-update.rst
@@ -1,22 +1,118 @@
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.
-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.
+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 @@
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 @@
|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 @@
- 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 @@
requested BL1 to resume normal world execution.
BL1 SMC Interface
------------------
+~~~~~~~~~~~~~~~~~
BL1_SMC_CALL_COUNT
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
::
@@ -142,7 +238,7 @@
This SMC returns the number of SMCs supported by BL1.
BL1_SMC_UID
-~~~~~~~~~~~
+^^^^^^^^^^^
::
@@ -156,7 +252,7 @@
BL1 SMC service.
BL1_SMC_VERSION
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
::
@@ -170,7 +266,7 @@
This SMC returns the current version of the BL1 SMC service.
BL1_SMC_RUN_IMAGE
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
::
@@ -190,7 +286,7 @@
this SMC for BL1 to pass execution control to BL31.
FWU_SMC_IMAGE_COPY
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
::
@@ -239,7 +335,7 @@
Once the SMC is handled, BL1 returns from exception to the normal world caller.
FWU_SMC_IMAGE_AUTH
-~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^
::
@@ -279,7 +375,7 @@
the -EAUTH error and sets the image state back to RESET.
FWU_SMC_IMAGE_EXECUTE
-~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^
::
@@ -307,7 +403,7 @@
EXECUTED, and returns from exception to the secure image.
FWU_SMC_IMAGE_RESUME
-~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
::
@@ -334,7 +430,7 @@
returned to the caller.
FWU_SMC_SEC_IMAGE_DONE
-~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^
::
@@ -355,7 +451,7 @@
world.
FWU_SMC_UPDATE_DONE
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
::
@@ -371,7 +467,7 @@
a ``void *``. The SMC does not return.
FWU_SMC_IMAGE_RESET
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
::
@@ -393,8 +489,9 @@
--------------
-*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/
diff --git a/docs/resources/diagrams/Makefile b/docs/resources/diagrams/Makefile
index 4e65569..c951754 100644
--- a/docs/resources/diagrams/Makefile
+++ b/docs/resources/diagrams/Makefile
@@ -73,7 +73,13 @@
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_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,$@)),$<)
diff --git a/docs/resources/diagrams/PSA-FWU.dia b/docs/resources/diagrams/PSA-FWU.dia
new file mode 100644
index 0000000..aac5276
--- /dev/null
+++ b/docs/resources/diagrams/PSA-FWU.dia
Binary files differ
diff --git a/docs/resources/diagrams/PSA-FWU.png b/docs/resources/diagrams/PSA-FWU.png
new file mode 100644
index 0000000..d58ba86
--- /dev/null
+++ b/docs/resources/diagrams/PSA-FWU.png
Binary files differ
