Adding upstream version 2.8.0+dfsg.upstream/2.8.0+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 497 insertions, 0 deletions

diff --git a/docs/components/firmware-update.rst b/docs/components/firmware-update.rst
new file mode 100644
index 0000000..1ba1e1c
--- /dev/null
+++ b/docs/components/firmware-update.rst
@@ -0,0 +1,497 @@
+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.
+
+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
+~~~~~
+
+This document describes the secure world FWU design. It is beyond its scope to
+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.
+
+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
+some parts of FWU to be implemented in other secure and normal world images.
+Platform code may choose which parts are implemented in which images but the
+general expectation is:
+
+-  BL1 handles:
+
+   -  Detection and initiation of the FWU boot flow.
+   -  Copying images from non-secure to secure memory
+   -  FWU image authentication
+   -  Context switching between the normal and secure world during the FWU
+      process.
+
+-  Other secure world FWU images handle platform initialization required by
+   the FWU process.
+-  Normal world FWU images handle loading of firmware images from external
+   interfaces to non-secure memory.
+
+The primary requirements of the FWU feature are:
+
+#. Export a BL1 SMC interface to interoperate with other FWU images executing
+   at other Exception Levels.
+#. Export a platform interface to provide FWU common code with the information
+   it needs, and to enable platform specific FWU functionality. See the
+   :ref:`Porting Guide` for details of this interface.
+
+TF-A uses abbreviated image terminology for FWU images like for other TF-A
+images. See the :ref:`Image Terminology` document for an explanation of these
+terms.
+
+The following diagram shows the FWU boot flow for Arm development platforms.
+Arm CSS platforms like Juno have a System Control Processor (SCP), and these
+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
+call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
+Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust`
+document for more information).
+
+The image descriptor includes the following information:
+
+-  Executable or non-executable image. This indicates whether the normal world
+   is permitted to request execution of a secure world FWU image (after
+   authentication). Secure world certificates and non-AP images are examples
+   of non-executable images.
+-  Secure or non-secure image. This indicates whether the image is
+   authenticated/executed in secure or non-secure memory.
+-  Image base address and size.
+-  Image entry point configuration (an ``entry_point_info_t``).
+-  FWU image state.
+
+BL1 uses the FWU image descriptors to:
+
+-  Validate the arguments of FWU SMCs
+-  Manage the state of the FWU process
+-  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
+BL1 to update its FWU image state. The BL1 image states and valid state
+transitions are shown in the diagram below. Note that secure images have a more
+complex state machine than non-secure images.
+
+|FWU state machine|
+
+The following is a brief description of the supported states:
+
+-  RESET: This is the initial state of every image at the start of FWU.
+   Authentication failure also leads to this state. A secure
+   image may yield to this state if it has completed execution.
+   It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
+
+-  COPYING: This is the state of a secure image while BL1 is copying it
+   in blocks from non-secure to secure memory.
+
+-  COPIED: This is the state of a secure image when BL1 has completed
+   copying it to secure memory.
+
+-  AUTHENTICATED: This is the state of an image when BL1 has successfully
+   authenticated it.
+
+-  EXECUTED: This is the state of a secure, executable image when BL1 has
+   passed execution control to it.
+
+-  INTERRUPTED: This is the state of a secure, executable image after it has
+   requested BL1 to resume normal world execution.
+
+BL1 SMC Interface
+~~~~~~~~~~~~~~~~~
+
+BL1_SMC_CALL_COUNT
+^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t function ID : 0x0
+
+    Return:
+        uint32_t
+
+This SMC returns the number of SMCs supported by BL1.
+
+BL1_SMC_UID
+^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t function ID : 0x1
+
+    Return:
+        UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
+
+This SMC returns the 128-bit `Universally Unique Identifier`_ for the
+BL1 SMC service.
+
+BL1_SMC_VERSION
+^^^^^^^^^^^^^^^
+
+::
+
+    Argument:
+        uint32_t function ID : 0x3
+
+    Return:
+        uint32_t : Bits [31:16] Major Version
+                   Bits [15:0] Minor Version
+
+This SMC returns the current version of the BL1 SMC service.
+
+BL1_SMC_RUN_IMAGE
+^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t           function ID : 0x4
+        entry_point_info_t *ep_info
+
+    Return:
+        void
+
+    Pre-conditions:
+        if (normal world caller) synchronous exception
+        if (ep_info not EL3) synchronous exception
+
+This SMC passes execution control to an EL3 image described by the provided
+``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
+this SMC for BL1 to pass execution control to BL31.
+
+FWU_SMC_IMAGE_COPY
+^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x10
+        unsigned int image_id
+        uintptr_t    image_addr
+        unsigned int block_size
+        unsigned int image_size
+
+    Return:
+        int : 0 (Success)
+            : -ENOMEM
+            : -EPERM
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (image_id is non-secure image) return -EPERM
+        if (image_id state is not (RESET or COPYING)) return -EPERM
+        if (secure world caller) return -EPERM
+        if (image_addr + block_size overflows) return -ENOMEM
+        if (image destination address + image_size overflows) return -ENOMEM
+        if (source block is in secure memory) return -ENOMEM
+        if (source block is not mapped into BL1) return -ENOMEM
+        if (image_size > free secure memory) return -ENOMEM
+        if (image overlaps another image) return -EPERM
+
+This SMC copies the secure image indicated by ``image_id`` from non-secure memory
+to secure memory for later authentication. The image may be copied in a single
+block or multiple blocks. In either case, the total size of the image must be
+provided in ``image_size`` when invoking this SMC for the first time for each
+image; it is ignored in subsequent calls (if any) for the same image.
+
+The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
+The destination address is provided by the platform code.
+
+If ``block_size`` is greater than the amount of remaining bytes to copy for this
+image then the former is truncated to the latter. The copy operation is then
+considered as complete and the FWU state machine transitions to the "COPIED"
+state. If there is still more to copy, the FWU state machine stays in or
+transitions to the COPYING state (depending on the previous state).
+
+When using multiple blocks, the source blocks do not necessarily need to be in
+contiguous memory.
+
+Once the SMC is handled, BL1 returns from exception to the normal world caller.
+
+FWU_SMC_IMAGE_AUTH
+^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x11
+        unsigned int image_id
+        uintptr_t    image_addr
+        unsigned int image_size
+
+    Return:
+        int : 0 (Success)
+            : -ENOMEM
+            : -EPERM
+            : -EAUTH
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (secure world caller)
+            if (image_id state is not RESET) return -EPERM
+            if (image_addr/image_size is not mapped into BL1) return -ENOMEM
+        else // normal world caller
+            if (image_id is secure image)
+                if (image_id state is not COPIED) return -EPERM
+            else // image_id is non-secure image
+                if (image_id state is not RESET) return -EPERM
+                if (image_addr/image_size is in secure memory) return -ENOMEM
+                if (image_addr/image_size not mapped into BL1) return -ENOMEM
+
+This SMC authenticates the image specified by ``image_id``. If the image is in the
+RESET state, BL1 authenticates the image in place using the provided
+``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
+state, BL1 authenticates the image from the secure memory that BL1 previously
+copied the image into.
+
+BL1 returns from exception to the caller. If authentication succeeds then BL1
+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
+^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x12
+        unsigned int image_id
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (image_id is invalid) return -EPERM
+        if (secure world caller) return -EPERM
+        if (image_id is non-secure image) return -EPERM
+        if (image_id is non-executable image) return -EPERM
+        if (image_id state is not AUTHENTICATED) return -EPERM
+
+This SMC initiates execution of a previously authenticated image specified by
+``image_id``, in the other security world to the caller. The current
+implementation only supports normal world callers initiating execution of a
+secure world image.
+
+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
+^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t   function ID : 0x13
+        register_t image_param
+
+    Return:
+        register_t : image_param (Success)
+                   : -EPERM
+
+    Pre-conditions:
+        if (normal world caller and no INTERRUPTED secure image) return -EPERM
+
+This SMC resumes execution in the other security world while there is a secure
+image in the EXECUTED/INTERRUPTED state.
+
+For normal world callers, BL1 sets the previously interrupted secure image state
+to EXECUTED. For secure world callers, BL1 sets the previously executing secure
+image state to INTERRUPTED. In either case, BL1 saves the calling world's
+context, restores the resuming world's context and returns from exception into
+the resuming world. If the call is successful then the caller provided
+``image_param`` is returned to the resumed world, otherwise an error code is
+returned to the caller.
+
+FWU_SMC_SEC_IMAGE_DONE
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t function ID : 0x14
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (normal world caller) return -EPERM
+
+This SMC indicates completion of a previously executing secure image.
+
+BL1 sets the previously executing secure image state to the RESET state,
+restores the normal world context and returns from exception into the normal
+world.
+
+FWU_SMC_UPDATE_DONE
+^^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t   function ID : 0x15
+        register_t client_cookie
+
+    Return:
+        N/A
+
+This SMC completes the firmware update process. BL1 calls the platform specific
+function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
+a ``void *``. The SMC does not return.
+
+FWU_SMC_IMAGE_RESET
+^^^^^^^^^^^^^^^^^^^
+
+::
+
+    Arguments:
+        uint32_t     function ID : 0x16
+        unsigned int image_id
+
+    Return:
+        int : 0 (Success)
+            : -EPERM
+
+    Pre-conditions:
+        if (secure world caller) return -EPERM
+        if (image in EXECUTED) return -EPERM
+
+This SMC sets the state of an image to RESET and zeroes the memory used by it.
+
+This is only allowed if the image is not being executed.
+
+--------------
+
+*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/