1.. SPDX-License-Identifier: GPL-2.0+
2.. Copyright (c) 2022 Linaro Limited
3
4FWU Multi Bank Updates in U-Boot
5================================
6
7The FWU Multi Bank Update feature implements the firmware update
8mechanism described in the PSA Firmware Update for A-profile Arm
9Architecture specification [1]. Certain aspects of the Dependable
10Boot specification [2] are also implemented. The feature provides a
11mechanism to have multiple banks of updatable firmware images and for
12updating the firmware images on the non-booted bank. On a successful
13update, the platform boots from the updated bank on subsequent
14boot. The UEFI capsule-on-disk update feature is used for performing
15the actual updates of the updatable firmware images.
16
17The bookkeeping of the updatable images is done through a structure
18called metadata. Currently, the FWU metadata supports identification
19of images based on image GUIDs stored on a GPT partitioned storage
20media. There are plans to extend the metadata structure for non GPT
21partitioned devices as well.
22
23Accessing the FWU metadata is done through generic API's which are
24defined in a driver which complies with the U-Boot's driver model. A
25new uclass UCLASS_FWU_MDATA has been added for accessing the FWU
26metadata. Individual drivers can be added based on the type of storage
27media, and its partitioning method. Details of the storage device
28containing the FWU metadata partitions are specified through a U-Boot
29specific device tree property `fwu-mdata-store`. Please refer to
30U-Boot :download:`fwu-mdata-gpt.yaml
31</device-tree-bindings/firmware/fwu-mdata-gpt.yaml>`
32for the device tree bindings.
33
34Enabling the FWU Multi Bank Update feature
35------------------------------------------
36
37The feature can be enabled by specifying the following configs::
38
39    CONFIG_EFI_CAPSULE_ON_DISK=y
40    CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y
41    CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y
42
43    CONFIG_FWU_MULTI_BANK_UPDATE=y
44    CONFIG_FWU_MDATA=y
45    CONFIG_FWU_MDATA_GPT_BLK=y
46    CONFIG_FWU_NUM_BANKS=<val>
47    CONFIG_FWU_NUM_IMAGES_PER_BANK=<val>
48
49in the .config file
50
51By enabling the CONFIG_CMD_FWU_METADATA config option, the
52fwu_mdata_read command can be used to check the current state of the
53FWU metadata structure.
54
55The first group of configuration settings enable the UEFI
56capsule-on-disk update functionality. The second group of configs
57enable the FWU Multi Bank Update functionality. Please refer to the
58section :ref:`uefi_capsule_update_ref` for more details on generation
59of the UEFI capsule.
60
61Setting up the device for GPT partitioned storage
62-------------------------------------------------
63
64Before enabling the functionality in U-Boot, a GPT partitioned storage
65device is required. Assuming a GPT partitioned storage device, the
66storage media needs to be partitioned with the correct number of
67partitions, given the number of banks and number of images per bank
68that the platform is going to support. Each updatable firmware image
69will be stored on a separate partition. In addition, the two copies
70of the FWU metadata will be stored on two separate partitions. These
71partitions need to be created at the time of the platform's
72provisioning.
73
74As an example, a platform supporting two banks with each bank
75containing three images would need to have 2 * 3 = 6 partitions plus
76the two metadata partitions, or 8 partitions. In addition the storage
77media can have additional partitions of non-updatable images, like the
78EFI System Partition(ESP), a partition for the root file system
79etc. An example list of images on the storage medium would be
80
81* FWU metadata 1
82* U-Boot 1
83* OP-TEE 1
84* FWU metadata 2
85* OP-TEE 2
86* U-Boot 2
87* ESP
88* rootfs
89
90When generating the partitions, a few aspects need to be taken care
91of. Each GPT partition entry in the GPT header has two GUIDs::
92
93* PartitionTypeGUID
94* UniquePartitionGUID
95
96The PartitionTypeGUID value should correspond to the
97``image_type_uuid`` field of the FWU metadata. This field is used to
98identify a given type of updatable firmware image, e.g. U-Boot,
99OP-TEE, FIP etc. This GUID should also be used for specifying the
100`--guid` parameter when generating the capsule.
101
102The UniquePartitionGUID value should correspond to the ``image_uuid``
103field in the FWU metadata. This GUID is used to identify images of a
104given image type in different banks.
105
106The FWU specification defines the GUID value to be used for the
107metadata partitions. This would be the PartitionTypeGUID for the
108metadata partitions. Similarly, the UEFI specification defines the ESP
109GUID to be be used.
110
111When generating the metadata, the ``image_type_uuid`` and the
112``image_uuid`` values should match the *PartitionTypeGUID* and the
113*UniquePartitionGUID* values respectively.
114
115Performing the Update
116---------------------
117
118Once the storage media has been partitioned and populated with the
119metadata partitions, the UEFI capsule-on-disk update functionality can
120be used for performing the update. Refer to the section
121:ref:`uefi_capsule_update_ref` for details on how the update can be
122invoked.
123
124On a successful update, the FWU metadata gets updated to reflect the
125bank from which the platform would be booting on subsequent boot.
126
127Based on the value of bit15 of the Flags member of the capsule header,
128the updated images would either be accepted by the U-Boot's UEFI
129implementation, or by the Operating System. If the Operating System is
130accepting the firmware images, it does so by generating an empty
131*accept* capsule. The Operating System can also reject the updated
132firmware by generating a *revert* capsule. The empty capsule can be
133applied by using the exact same procedure used for performing the
134capsule-on-disk update.
135
136The task of accepting the different firmware images, post an update
137may be done by multiple, separate components in the Operating
138System. To help identify the firmware image that is being accepted,
139the accept capsule passes the image GUID of the firmware image being
140accepted. The relevant code in U-Boot then sets the Accept bit of the
141corresponding firmware image for which the accept capsule was
142found. Only when all the firmware components in a bank have been
143accepted does the platform transition from trial state to regular
144state.
145
146The revert capsule on the other hand does not pass any image GUID,
147since reverting any image of the bank has the same result of the
148platform booting from the other bank on subsequent boot.
149
150In the scenario that bit15 of the Flags member of the capsule header
151has not been set, the images being updated are accepted by the
152U-Boot's UEFI firmware implementation by default, on successful
153update of the image.
154
155Generating an empty capsule
156---------------------------
157
158The empty capsule can be generated using the mkeficapsule utility. To
159build the tool, enable::
160
161    CONFIG_TOOLS_MKEFICAPSULE=y
162
163Run the following commands to generate the accept/revert capsules::
164
165.. code-block:: bash
166
167    $ ./tools/mkeficapsule \
168      [--fw-accept --guid <image guid>] | \
169      [--fw-revert] \
170      <capsule_file_name>
171
172Some examples of using the mkeficapsule tool for generation of the
173empty capsule would be::
174
175.. code-block:: bash
176
177    $ ./tools/mkeficapsule --fw-accept --guid <image guid> \
178    <accept_capsule_name>
179    $ ./tools/mkeficapsule --fw-revert <revert_capsule_name>
180
181Links
182-----
183
184* [1] https://developer.arm.com/documentation/den0118/a/ - FWU Specification
185* [2] https://git.codelinaro.org/linaro/dependable-boot/mbfw/uploads/6f7ddfe3be24e18d4319e108a758d02e/mbfw.pdf - Dependable Boot Specification
186