diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/maintainers.rst | 2 | ||||
| -rw-r--r-- | docs/components/firmware-update.rst | 147 | ||||
| -rw-r--r-- | docs/resources/diagrams/Makefile | 11 | ||||
| -rw-r--r-- | docs/resources/diagrams/PSA-FWU.dia | bin | 0 -> 3516 bytes | |||
| -rw-r--r-- | docs/resources/diagrams/PSA-FWU.png | bin | 0 -> 52886 bytes |
5 files changed, 133 insertions, 27 deletions
diff --git a/docs/about/maintainers.rst b/docs/about/maintainers.rst index a77981267..9ce6ff2b5 100644 --- a/docs/about/maintainers.rst +++ b/docs/about/maintainers.rst @@ -729,7 +729,7 @@ Xilinx platform port :|G|: `michalsimek`_ :|M|: Venkatesh Yadav Abbarapu <venkatesh.abbarapu@amd.com> :|G|: `venkatesh`_ -:|F|: docs/plat/xilinx-zynqmp.rst +:|F|: docs/plat/xilinx\* :|F|: plat/xilinx/ diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst index a59156568..1ba1e1c6e 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. -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 ~~~~~ @@ -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/ diff --git a/docs/resources/diagrams/Makefile b/docs/resources/diagrams/Makefile index 4e65569c1..c951754cf 100644 --- a/docs/resources/diagrams/Makefile +++ b/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,$@)),$<) diff --git a/docs/resources/diagrams/PSA-FWU.dia b/docs/resources/diagrams/PSA-FWU.dia Binary files differnew file mode 100644 index 000000000..aac527697 --- /dev/null +++ b/docs/resources/diagrams/PSA-FWU.dia diff --git a/docs/resources/diagrams/PSA-FWU.png b/docs/resources/diagrams/PSA-FWU.png Binary files differnew file mode 100644 index 000000000..d58ba8697 --- /dev/null +++ b/docs/resources/diagrams/PSA-FWU.png |
