1#######################
2Firmware Update Service
3#######################
4
5:Author: Sherry Zhang
6:Organization: Arm Limited
7
8.. contents:: Table of Contents
9   :depth: 3
10
11***************************************
12Introduction of Firmware Update service
13***************************************
14The Firmware Update(FWU) service provides the functionality of updating firmware
15images. It provides a standard interface for updating firmware and it is
16platform independent. TF-M defines a shim layer to support cooperation between
17bootloader and FWU service.
18
19This partition supports the following features:
20
21- Query the firmware store information.
22- Image preparation: prepare a new firmware image in the component's firmware store.
23- Image installation: install prepared firmware images on all components that have been prepared for installation.
24- Image trial: manage a trial of new firmware images atomically on all components that are in TRIAL state.
25
26A typical flow through the component states is shown below [1]_.
27
28.. figure:: /design_docs/media/fwu-states.svg
29   :scale: 65 %
30   :align: center
31   :name: The component state model transitions.
32
33**********
34Components
35**********
36The structure of the TF-M Firmware Update service is listed below:
37   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
38   | **Component name**          | **Description**                                               | **Location**                                                                          |
39   +=============================+===============================================================+=======================================================================================+
40   | Client API interface        | This module exports the client API of PSA Firmware Update to  | ``./interface/src/tfm_fwu_api.c``                                                     |
41   |                             | the users.                                                    |                                                                                       |
42   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
43   | Manifest                    | The manifest file is a description of the service components. | ``./secure_fw/partitions/firmware_update/tfm_firmware_update.yaml``                   |
44   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
45   | NSPE client API interface   | This module exports the client API of PSA Firmware Update to  | ``./interface/src/tfm_fwu_api.c``                                                     |
46   |                             | the NSPE(i.e. to the applications).                           |                                                                                       |
47   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
48   | IPC request handlers        | This module handles all the secure requests in IPC model.     | ``./secure_fw/partitions/firmware_update/tfm_fwu_req_mngr.c``                         |
49   |                             | It maintains the image state context and calls the image ID   |                                                                                       |
50   |                             | converter to achieve the firmware update functionalities.     |                                                                                       |
51   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
52   | Shim layer between FWU and  | This module provides the APIs with the functionality of       | ``./secure_fw/partitions/firmware_update/bootloader/tfm_bootloader_fwu_abstraction.h``|
53   | bootloader                  | operating the bootloader to cooperate with the Firmware Update|                                                                                       |
54   |                             | service                                                       |                                                                                       |
55   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
56   | Shim layer example based on | This module is the implementation of the shim layer between   | ``./secure_fw/partitions/firmware_update/bootloader/mcuboot/tfm_mcuboot_fwu.c``       |
57   | MCUboot                     | FWU and bootloader based on MCUboot.                          |                                                                                       |
58   |                             |                                                               |                                                                                       |
59   +-----------------------------+---------------------------------------------------------------+---------------------------------------------------------------------------------------+
60
61***********************
62Service API description
63***********************
64This service follows the PSA Firmware Update API spec of version 1.0 [1]_. Please refer to
65Firmware Update spec for the detailed description.
66
67*************************************
68Shim Layer between FWU and bootloader
69*************************************
70The firmware update operations are achieved by calling the shim layer APIs
71between bootloader and FWU.
72
73Shim layer introduction
74=======================
75This shim layer provides the APIs with the functionality of operating the
76bootloader to cooperate with the Firmware Update service. This shim layer
77is decoupled from bootloader implementation. Users can specify a specific
78bootloader by setting ``TFM_FWU_BOOTLOADER_LIB`` build configuration and
79adding the specific build scripts into that file. By default, the MCUboot
80is chosen as the bootloader.
81
82Interfaces of the shim Layer
83============================
84
85fwu_bootloader_init(function)
86-----------------------------
87Prototype
88^^^^^^^^^
89.. code-block:: c
90
91    psa_status_t fwu_bootloader_init(void);
92
93Description
94^^^^^^^^^^^
95Bootloader related initialization for the firmware update. It reads
96some necessary shared data from the memory if needed. It initializes
97the flash drivers defined in FLASH_DRIVER_LIST. Platform can define
98FLASH_DRIVER_LIST in flash_layout.h to overload the default driver list.
99
100Parameters
101^^^^^^^^^^
102    N/A
103
104fwu_bootloader_staging_area_init(function)
105------------------------------------------
106**Prototype**
107
108.. code-block:: c
109
110    psa_status_t fwu_bootloader_staging_area_init(psa_fwu_component_t component,
111                                                  const void *manifest,
112                                                  size_t manifest_size);
113
114**Description**
115
116The component is in READY state. Prepare the staging area of the component for image download.
117For example, initialize the staging area, open the flash area, and so on.
118
119**Parameters**
120
121- ``component``: The identifier of the target component in bootloader.
122- ``manifest``: A pointer to a buffer containing a detached manifest for the update.
123  If the manifest is bundled with the firmware image, manifest must be NULL.
124- ``manifest_size``: Size of the manifest buffer in bytes.
125
126fwu_bootloader_load_image(function)
127-----------------------------------
128**Prototype**
129
130.. code-block:: c
131
132    psa_status_t fwu_bootloader_load_image(psa_fwu_component_t component,
133                                           size_t        image_offset,
134                                           const void    *block,
135                                           size_t        block_size);
136
137**Description**
138
139Load the image into the target component.
140
141**Parameters**
142
143- ``component``: The identifier of the target component in bootloader.
144- ``image_offset``: The offset of the image being passed into block, in bytes.
145- ``block``: A buffer containing a block of image data. This might be a complete image or a subset.
146- ``block_size``: Size of block.
147
148fwu_bootloader_install_image(function)
149---------------------------------------------
150**Prototype**
151
152.. code-block:: c
153
154    psa_status_t fwu_bootloader_install_image(psa_fwu_component_t *candidates,
155                                              uint8_t number);
156
157**Description**
158
159Check the authenticity and integrity of the image. If a reboot is required to
160complete the check, then mark this image as a candidate so that the next time
161bootloader runs it will take this image as a candidate one to boot-up. Return
162the error code PSA_SUCCESS_REBOOT.
163
164**Parameters**
165
166- ``candidates``: A list of components in CANDIDATE state.
167- ``number``: Number of components in CANDIDATE state.
168
169fwu_bootloader_mark_image_accepted(function)
170--------------------------------------------
171**Prototype**
172
173.. code-block:: c
174
175    psa_status_t fwu_bootloader_mark_image_accepted(const psa_fwu_component_t *trials,
176                                                    uint8_t number);
177
178**Description**
179
180Call this API to mark the TRIAL(running) image in component as confirmed to avoid
181revert when next time boot-up. Usually, this API is called after the running
182images have been verified as valid.
183
184**Parameters**
185
186- ``trials``: A list of components in TRIAL state.
187- ``number``: Number of components in TRIAL state.
188
189fwu_bootloader_reject_staged_image(function)
190--------------------------------------------
191**Prototype**
192
193.. code-block:: c
194
195    psa_status_t fwu_bootloader_reject_staged_image(psa_fwu_component_t component);
196
197**Description**
198
199The component is in STAGED state. Call this API to Uninstall the staged image in the
200component so that this image will not be treated as a candidate next time boot-up.
201
202**Parameters**
203
204- ``component``: The identifier of the target component in bootloader.
205
206fwu_bootloader_reject_trial_image(function)
207--------------------------------------------
208**Prototype**
209
210.. code-block:: c
211
212    psa_status_t fwu_bootloader_reject_trial_image(psa_fwu_component_t component);
213
214**Description**
215
216The component is in TRIAL state. Mark the running image in the component as rejected.
217
218**Parameters**
219
220- ``component``: The identifier of the target component in bootloader.
221
222fwu_bootloader_clean_component(function)
223----------------------------------------
224**Prototype**
225
226.. code-block:: c
227
228    psa_status_t fwu_bootloader_clean_component(psa_fwu_component_t component);
229
230**Description**
231
232The component is in FAILED or UPDATED state. Clean the staging area of the component.
233
234**Parameters**
235
236- ``component``: The identifier of the target component in bootloader.
237
238fwu_bootloader_get_image_info(function)
239---------------------------------------
240**Prototype**
241
242.. code-block:: c
243
244    psa_status_t fwu_bootloader_get_image_info(psa_fwu_component_t component,
245                                               bool query_state,
246                                               bool query_impl_info,
247                                               psa_fwu_component_info_t *info);
248
249**Description**
250
251Get the image information of the given bootloader_image_id in the staging area
252or the running area.
253
254**Parameters**
255
256    - ``component``: The identifier of the target component in bootloader.
257    - ``query_state``: Whether query the 'state' field of psa_fwu_component_info_t.
258    - ``query_impl_info``: Whether Query 'impl' field of psa_fwu_component_info_t.
259    - ``info``: Buffer containing return the component information.
260
261******************************************
262Additional shared data between BL2 and SPE
263******************************************
264An additional TLV area "image version" is added into the shared memory between
265BL2 and TF-M. So that the firmware update partition can get the image version.
266Even though the image version information is also included in the ``BOOT RECORD``
267TLV area which is encoded by CBOR, adding a dedicated ``image version`` TLV area
268is preferred to avoid involving the CBOR encoder which can increase the code
269size. The FWU partition will read the shared data at the partition
270initialization.
271
272*********************************************
273Build configurations related to FWU partition
274*********************************************
275- ``TFM_PARTITION_FIRMWARE_UPDATE`` Controls whether FWU partition is enabled or not.
276- ``TFM_FWU_BOOTLOADER_LIB`` Bootloader configure file for FWU partition.
277- ``TFM_CONFIG_FWU_MAX_WRITE_SIZE`` The maximum permitted size for block in psa_fwu_write, in bytes.
278- ``TFM_FWU_BUF_SIZE`` Size of the FWU internal data transfer buffer (defaults to
279  TFM_CONFIG_FWU_MAX_WRITE_SIZE if not set).
280- ``FWU_STACK_SIZE`` The stack size of FWU Partition.
281- ``FWU_DEVICE_CONFIG_FILE`` The device configuration file for FWU partition. The default value is
282  the configuration file generated for MCUboot. The following macros should be defined in the
283  configuration file:
284
285  - ``FWU_COMPONENT_NUMBER`` The number of components on the device.
286
287    .. Note::
288
289        In this design, component ID ranges from 0 to ``FWU_COMPONENT_NUMBER`` - 1.
290
291  - ``FWU_SUPPORT_TRIAL_STATE`` Whether TRIAL component state is supported.
292- ``TEST_NS_FWU`` FWU nonsecure tests switch.
293- ``TEST_S_FWU`` FWU secure tests switch.
294
295    .. Note::
296
297        The running image which supports revert mechanism should be confirmed before initiating a
298        firmware update process. For example, if the running image is built with
299        ``-DMCUBOOT_UPGRADE_STRATEGY=SWAP_USING_MOVE``, the image should be confirmed either by
300        adding ``-DMCUBOOT_CONFIRM_IMAGE=ON`` build option or by calling ``psa_fwu_accept()`` API
301        before initiating a firmware update process. Otherwise, ``PSA_ERROR_BAD_STATE`` will be
302        returned by ``psa_fwu_start()``.
303
304*************************************
305Limitations of current implementation
306*************************************
307Currently, the MCUboot based implementation does not record image update results like failure or
308success. And FWU partition does not detect failure errors in bootloader installation. If an image
309installation fails in the bootloader and the old image still runs after reboot, ``PSA_FWU_READY``
310state will be returned by ``psa_fwu_query()`` after reboot.
311
312Currently, image download recovery after a reboot is not supported. If a reboot happens in image
313preparation, the downloaded image data will be ignored after the reboot.
314
315***********************************
316Benefits Analysis on this Partition
317***********************************
318
319Implement the FWU functionality in the non-secure side
320======================================================
321The APIs listed in PSA Firmware Update API spec [1]_ can also be implemented in
322the non-secure side.
323
324Pros and Cons for implementing FWU APIs in secure side
325======================================================
326
327Pros
328----
329- It protects the image in the passive or staging area from being tampered with
330  by the NSPE. Otherwise, a malicious actor from NSPE can tamper the image
331  stored in the non-secure area to break image update.
332
333- It protects secure image information from disclosure. In some cases, the
334  non-secure side shall not be permitted to get secure image information.
335
336- It protects the active image from being manipulated by NSPE. Some bootloader
337  supports testing the image. After the image is successfully installed and
338  starts to run, the user should set the image as permanent image if the image
339  passes the test. To achieve this, the area of the active image needs to be
340  accessed. In this case, implementing FWU service in SPE can prevent NSPE
341  from manipulating the active image area.
342
343- On some devices, such as the Arm Musca-B1 board, the passive or staging area
344  is restricted as secure access only. In this case, the FWU partition should
345  be implemented in the secure side.
346
347Cons
348----
349- It increases the image size of the secure image.
350- It increases the execution latency and footprint. Compared to implementing
351  FWU in NSPE directly, calling the Firmware Update APIs which are implemented
352  in the secure side increases the execution latency and footprint.
353- It can increase the attack surface of the secure runtime.
354
355Users can decide whether to call the FWU service in TF-M directly or implement
356the Firmware Update APIs in the non-secure side based on the pros and cons
357analysis above.
358
359*********
360Reference
361*********
362
363.. [1] `PSA Firmware Update API <https://arm-software.github.io/psa-api/fwu/1.0/>`_
364
365--------------
366
367*Copyright (c) 2021-2022, Arm Limited. All rights reserved.*
368