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