From 0f20e50b26f29db7c6ae033446e6b4c9ae9f2c86 Mon Sep 17 00:00:00 2001 From: Manish V Badarkhe Date: Sun, 20 Jun 2021 21:14:46 +0100 Subject: [PATCH] docs(fwu): add firmware update documentation Added firmware update documentation for: 1. PSA firmware update build flag 2. Porting guidelines to set the addresses of FWU metadata image and updated components in I/O policy Change-Id: Iad3eb68b4be01a0b5850b69a067c60fcb464f54b Signed-off-by: Manish V Badarkhe --- docs/getting_started/build-options.rst | 8 +++++ docs/getting_started/porting-guide.rst | 48 ++++++++++++++++++++++++++ docs/index.rst | 2 ++ 3 files changed, 58 insertions(+) diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst index 2d0d82636..901a72a9b 100644 --- a/docs/getting_started/build-options.rst +++ b/docs/getting_started/build-options.rst @@ -873,6 +873,14 @@ Firmware update options This flag is used in defining the firmware update metadata structure. This flag is by default set to '1'. +- ``PSA_FWU_SUPPORT``: Enable the firmware update mechanism as per the + `PSA FW update specification`_. The default value is 0, and this is an + experimental feature. + PSA firmware update implementation has some limitations, such as BL2 is + not part of the protocol-updatable images, if BL2 needs to be updated, then + it should be done through another platform-defined mechanism, and it assumes + that the platform's hardware supports CRC32 instructions. + -------------- *Copyright (c) 2019-2021, Arm Limited. All rights reserved.* diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst index 906daf811..54754fe6e 100644 --- a/docs/getting_started/porting-guide.rst +++ b/docs/getting_started/porting-guide.rst @@ -894,6 +894,54 @@ On success the function should return 0 and a negative error code otherwise. Note that this API depends on ``DECRYPTION_SUPPORT`` build flag which is marked as experimental. +Function : plat_fwu_set_images_source() [when PSA_FWU_SUPPORT == 1] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : struct fwu_metadata *metadata + Return : void + +This function is mandatory when PSA_FWU_SUPPORT is enabled. +It provides a means to retrieve image specification (offset in +non-volatile storage and length) of active/updated images using the passed +FWU metadata, and update I/O policies of active/updated images using retrieved +image specification information. +Further I/O layer operations such as I/O open, I/O read, etc. on these +images rely on this function call. + +In Arm platforms, this function is used to set an I/O policy of the FIP image, +container of all active/updated secure and non-secure images. + +Function : plat_fwu_set_metadata_image_source() [when PSA_FWU_SUPPORT == 1] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + Argument : unsigned int image_id, uintptr_t *dev_handle, + uintptr_t *image_spec + Return : int + +This function is mandatory when PSA_FWU_SUPPORT is enabled. It is +responsible for setting up the platform I/O policy of the requested metadata +image (either FWU_METADATA_IMAGE_ID or BKUP_FWU_METADATA_IMAGE_ID) that will +be used to load this image from the platform's non-volatile storage. + +FWU metadata can not be always stored as a raw image in non-volatile storage +to define its image specification (offset in non-volatile storage and length) +statically in I/O policy. +For example, the FWU metadata image is stored as a partition inside the GUID +partition table image. Its specification is defined in the partition table +that needs to be parsed dynamically. +This function provides a means to retrieve such dynamic information to set +the I/O policy of the FWU metadata image. +Further I/O layer operations such as I/O open, I/O read, etc. on FWU metadata +image relies on this function call. + +It returns '0' on success, otherwise a negative error value on error. +Alongside, returns device handle and image specification from the I/O policy +of the requested FWU metadata image. + Common optional modifications ----------------------------- diff --git a/docs/index.rst b/docs/index.rst index 29e5839c8..edc2535a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,6 +30,7 @@ such as: - `SMC Calling Convention`_ - `System Control and Management Interface (SCMI)`_ - `Software Delegated Exception Interface (SDEI)`_ +- `PSA FW update specification`_ Where possible, the code is designed for reuse or porting to other Armv7-A and Armv8-A model and hardware platforms. @@ -92,3 +93,4 @@ have previously been raised against the software. .. _System Control and Management Interface (SCMI): http://infocenter.arm.com/help/topic/com.arm.doc.den0056a/DEN0056A_System_Control_and_Management_Interface.pdf .. _Software Delegated Exception Interface (SDEI): http://infocenter.arm.com/help/topic/com.arm.doc.den0054a/ARM_DEN0054A_Software_Delegated_Exception_Interface.pdf .. _SMC Calling Convention: https://developer.arm.com/docs/den0028/latest +.. _PSA FW update specification: https://developer.arm.com/documentation/den0118/a/