1################
2RSE FWU Metadata
3################
4
5As per the PSA firmware update architecture specification `_DEN0118
6<https://developer.arm.com/documentation/den0118/latest/>`_ , fwu metadata and
7private metadata is a collection of fields that primarily serves as an information
8exchange channel between the firmware update agent and the early stage bootloader.
9Current code implements version 2 of the metadata as per the spec section A3.2.2.
10
11For RSE, if option ``RSE_GPT_SUPPORT`` is enabled, then the firmware store
12expects the GPT image with following layout:
13
14+-------------------------------------------+
15| Protective MBR                            |
16+-------------------------------------------+
17| Primary GPT Header                        |
18+-------------------------------------------+
19| GUID Partition Table                      |
20|   +---------------------------------+     |
21|   | FIP_A                           |     |
22|   +---------------------------------+     |
23|   | FIP_B                           |     |
24|   +---------------------------------+     |
25|   | FWU-Metadata                    |     |
26|   +---------------------------------+     |
27|   | Bkup-FWU-Metadata               |     |
28|   +---------------------------------+     |
29|   | private_metadata_1              |     |
30|   +---------------------------------+     |
31+-------------------------------------------+
32| Backup Partition Table                    |
33+-------------------------------------------+
34| Secondary GPT Header                      |
35+-------------------------------------------+
36
37As per section A1.1. *Platform Boot* of the spec, the mechanism to
38determine a failed boot attempt is platform specific. To meet this requirement,
39a private metadata partition has been added to the RSE platform.
40
41The partitions mentioned above are parsed during the early boot stages,
42specifically BL1_2 and BL2, with BL2 being the first stage capable of protocol
43updates. If any of the metadata partitions are missing, the bootloader enters an
44error state and triggers a panic.
45
46Upon locating the metadata during the parsing of the GPT image, its contents are
47used to determine the appropriate bank from which the image should be loaded.
48
49Failure and recovery actions
50----------------------------
51
52For any reason, if a failure is encountered while loading the image from the
53bank pointed by metadata, then the *failed_boot_count* for corresponding bank is
54incremented in the private metadata. And if the *failed_boot_count* exceeds the
55``FWU_MAX_FAILED_BOOT``, then an image is restored from the the last known bank
56which had a successful boot.
57
58--------------
59
60*SPDX-License-Identifier: BSD-3-Clause*
61
62*SPDX-FileCopyrightText: Copyright The TrustedFirmware-M Contributors*
63