blob: 1ba1e1c6eea25473518a929c806850cfa5161510 [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Firmware Update (FWU)
2=====================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
Manish V Badarkhebd836552022-07-04 10:00:29 +01004This document describes the design of the various Firmware Update (FWU)
5mechanisms available in TF-A.
6
71. PSA Firmware Update (PSA FWU)
82. TBBR Firmware Update (TBBR FWU)
9
10PSA Firmware Update implements the specification of the same name (Arm document
11IHI 0093), which defines a standard firmware interface for installing firmware
12updates.
13On the other hand, TBBR Firmware Update only covers firmware recovery. Arguably,
14its name is somewhat misleading but the TBBR specification and terminology
15predates PSA FWU. Both mechanisms are complementary in the sense that PSA FWU
16assumes that the device has a backup or recovery capability in the event of a
17failed update, which can be fulfilled with TBBR FWU implementation.
18
19.. _PSA Firmware Update:
20
21PSA Firmware Update (PSA FWU)
22-----------------------------
23
Douglas Raillardd7c21b72017-06-28 15:23:03 +010024Introduction
Manish V Badarkhebd836552022-07-04 10:00:29 +010025~~~~~~~~~~~~
26The `PSA FW update specification`_ defines the concepts of ``Firmware Update
27Client`` and ``Firmware Update Agent``.
28The new firmware images are provided by the ``Client`` to the ``Update Agent``
29to flash them in non-volatile storage.
30
31A common system design will place the ``Update Agent`` in the Secure-world
32while the ``Client`` executes in the Normal-world.
33The `PSA FW update specification`_ provides ABIs meant for a Normal-world
34entity aka ``Client`` to transmit the firmware images to the ``Update Agent``.
35
36Scope
37~~~~~
38The design of the ``Client`` and ``Update Agent`` is out of scope of this
39document.
40This document mainly covers ``Platform Boot`` details i.e. the role of
41the second stage Bootloader after FWU has been done by ``Client`` and
42``Update Agent``.
43
44Overview
45~~~~~~~~
46
47There are active and update banks in the non-volatile storage identified
48by the ``active_index`` and the ``update_index`` respectively.
49An active bank stores running firmware, whereas an update bank contains
50firmware updates.
51
52Once Firmwares are updated in the update bank of the non-volatile
53storage, then ``Update Agent`` marks the update bank as the active bank,
54and write updated FWU metadata in non-volatile storage.
55On subsequent reboot, the second stage Bootloader (BL2) performs the
56following actions:
57
58- Read FWU metadata in memory
59- Retrieve the image specification (offset and length) of updated images
60 present in non-volatile storage with the help of FWU metadata
61- Set these image specification in the corresponding I/O policies of the
62 updated images using the FWU platform functions
63 ``plat_fwu_set_images_source()`` and ``plat_fwu_set_metadata_image_source()``,
64 please refer :ref:`Porting Guide`
65- Use these I/O policies to read the images from this address into the memory
66
67By default, the platform uses the active bank of non-volatile storage to boot
68the images in ``trial state``. If images pass through the authentication check
69and also if the system successfully booted the Normal-world image then
70``Update Agent`` marks this update as accepted after further sanitisation
71checking at Normal-world.
72
73The second stage Bootloader (BL2) avoids upgrading the platform NV-counter until
74it's been confirmed that given update is accepted.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010075
Manish V Badarkhebd836552022-07-04 10:00:29 +010076The following sequence diagram shows platform-boot flow:
77
78.. image:: ../resources/diagrams/PSA-FWU.png
79
80If the platform fails to boot from active bank due to any reasons such
81as authentication failure or non-fuctionality of Normal-world software then the
82watchdog will reset to give a chance to the platform to fix the issue. This
83boot failure & reset sequence might be repeated up to ``trial state`` times.
84After that, the platform can decide to boot from the ``previous_active_index``
85bank.
86
87If the images still does not boot successfully from the ``previous_active_index``
88bank (e.g. due to ageing effect of non-volatile storage) then the platform can
89choose firmware recovery mechanism :ref:`TBBR Firmware Update` to bring system
90back to life.
91
92.. _TBBR Firmware Update:
93
94TBBR Firmware Update (TBBR FWU)
95-------------------------------
96
97Introduction
98~~~~~~~~~~~~
99
100This technique enables authenticated firmware to update firmware images from
101external interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC
102Non-Volatile memories such as NAND Flash, LPDDR2-NVM or any memory determined
103by the platform.
104This feature functions even when the current firmware in the system is corrupt
105or missing; it therefore may be used as a recovery mode. It may also be
106complemented by other, higher level firmware update software.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100107
108FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
Dan Handley610e7e12018-03-01 18:44:00 +0000109specification, Arm DEN0006C-1. It should be used in conjunction with the
Paul Beesleyf8640672019-04-12 14:19:42 +0100110:ref:`Trusted Board Boot` design document, which describes the image
111authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100112
Manish V Badarkhebd836552022-07-04 10:00:29 +0100113It can be used as a last resort when all firmware updates that are carried out
114as part of the :ref:`PSA Firmware Update` procedure have failed to function.
115
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100116Scope
117~~~~~
118
119This document describes the secure world FWU design. It is beyond its scope to
120describe how normal world FWU images should operate. To implement normal world
121FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
122the TBBR.
123
Manish V Badarkhebd836552022-07-04 10:00:29 +0100124Overview
125~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100126
127The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
128it is usually desirable to minimize the amount of ROM code, the design allows
129some parts of FWU to be implemented in other secure and normal world images.
130Platform code may choose which parts are implemented in which images but the
131general expectation is:
132
133- BL1 handles:
134
135 - Detection and initiation of the FWU boot flow.
136 - Copying images from non-secure to secure memory
137 - FWU image authentication
138 - Context switching between the normal and secure world during the FWU
139 process.
140
141- Other secure world FWU images handle platform initialization required by
142 the FWU process.
143- Normal world FWU images handle loading of firmware images from external
144 interfaces to non-secure memory.
145
146The primary requirements of the FWU feature are:
147
148#. Export a BL1 SMC interface to interoperate with other FWU images executing
149 at other Exception Levels.
150#. Export a platform interface to provide FWU common code with the information
151 it needs, and to enable platform specific FWU functionality. See the
Paul Beesleyf8640672019-04-12 14:19:42 +0100152 :ref:`Porting Guide` for details of this interface.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100153
Dan Handley610e7e12018-03-01 18:44:00 +0000154TF-A uses abbreviated image terminology for FWU images like for other TF-A
Paul Beesleyf8640672019-04-12 14:19:42 +0100155images. See the :ref:`Image Terminology` document for an explanation of these
156terms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100157
Dan Handley610e7e12018-03-01 18:44:00 +0000158The following diagram shows the FWU boot flow for Arm development platforms.
159Arm CSS platforms like Juno have a System Control Processor (SCP), and these
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100160use all defined FWU images. Other platforms may use a subset of these.
161
162|Flow Diagram|
163
164Image Identification
Manish V Badarkhebd836552022-07-04 10:00:29 +0100165~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100166
167Each FWU image and certificate is identified by a unique ID, defined by the
168platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
169call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
Paul Beesleyf8640672019-04-12 14:19:42 +0100170Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust`
171document for more information).
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100172
173The image descriptor includes the following information:
174
175- Executable or non-executable image. This indicates whether the normal world
176 is permitted to request execution of a secure world FWU image (after
177 authentication). Secure world certificates and non-AP images are examples
178 of non-executable images.
179- Secure or non-secure image. This indicates whether the image is
180 authenticated/executed in secure or non-secure memory.
181- Image base address and size.
182- Image entry point configuration (an ``entry_point_info_t``).
183- FWU image state.
184
185BL1 uses the FWU image descriptors to:
186
187- Validate the arguments of FWU SMCs
188- Manage the state of the FWU process
189- Initialize the execution state of the next FWU image.
190
191FWU State Machine
Manish V Badarkhebd836552022-07-04 10:00:29 +0100192~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100193
194BL1 maintains state for each FWU image during FWU execution. FWU images at lower
195Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
196BL1 to update its FWU image state. The BL1 image states and valid state
197transitions are shown in the diagram below. Note that secure images have a more
198complex state machine than non-secure images.
199
200|FWU state machine|
201
202The following is a brief description of the supported states:
203
204- RESET: This is the initial state of every image at the start of FWU.
205 Authentication failure also leads to this state. A secure
206 image may yield to this state if it has completed execution.
207 It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
208
209- COPYING: This is the state of a secure image while BL1 is copying it
210 in blocks from non-secure to secure memory.
211
212- COPIED: This is the state of a secure image when BL1 has completed
213 copying it to secure memory.
214
215- AUTHENTICATED: This is the state of an image when BL1 has successfully
216 authenticated it.
217
218- EXECUTED: This is the state of a secure, executable image when BL1 has
219 passed execution control to it.
220
221- INTERRUPTED: This is the state of a secure, executable image after it has
222 requested BL1 to resume normal world execution.
223
224BL1 SMC Interface
Manish V Badarkhebd836552022-07-04 10:00:29 +0100225~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100226
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100227BL1_SMC_CALL_COUNT
Manish V Badarkhebd836552022-07-04 10:00:29 +0100228^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100229
230::
231
232 Arguments:
233 uint32_t function ID : 0x0
234
235 Return:
236 uint32_t
237
238This SMC returns the number of SMCs supported by BL1.
239
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100240BL1_SMC_UID
Manish V Badarkhebd836552022-07-04 10:00:29 +0100241^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100242
243::
244
245 Arguments:
246 uint32_t function ID : 0x1
247
248 Return:
249 UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
250
251This SMC returns the 128-bit `Universally Unique Identifier`_ for the
252BL1 SMC service.
253
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100254BL1_SMC_VERSION
Manish V Badarkhebd836552022-07-04 10:00:29 +0100255^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100256
257::
258
259 Argument:
260 uint32_t function ID : 0x3
261
262 Return:
263 uint32_t : Bits [31:16] Major Version
264 Bits [15:0] Minor Version
265
266This SMC returns the current version of the BL1 SMC service.
267
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100268BL1_SMC_RUN_IMAGE
Manish V Badarkhebd836552022-07-04 10:00:29 +0100269^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100270
271::
272
273 Arguments:
274 uint32_t function ID : 0x4
275 entry_point_info_t *ep_info
276
277 Return:
278 void
279
280 Pre-conditions:
281 if (normal world caller) synchronous exception
282 if (ep_info not EL3) synchronous exception
283
284This SMC passes execution control to an EL3 image described by the provided
Dan Handley610e7e12018-03-01 18:44:00 +0000285``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
286this SMC for BL1 to pass execution control to BL31.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100287
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100288FWU_SMC_IMAGE_COPY
Manish V Badarkhebd836552022-07-04 10:00:29 +0100289^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100290
291::
292
293 Arguments:
294 uint32_t function ID : 0x10
295 unsigned int image_id
296 uintptr_t image_addr
297 unsigned int block_size
298 unsigned int image_size
299
300 Return:
301 int : 0 (Success)
302 : -ENOMEM
303 : -EPERM
304
305 Pre-conditions:
306 if (image_id is invalid) return -EPERM
307 if (image_id is non-secure image) return -EPERM
308 if (image_id state is not (RESET or COPYING)) return -EPERM
309 if (secure world caller) return -EPERM
310 if (image_addr + block_size overflows) return -ENOMEM
311 if (image destination address + image_size overflows) return -ENOMEM
312 if (source block is in secure memory) return -ENOMEM
313 if (source block is not mapped into BL1) return -ENOMEM
314 if (image_size > free secure memory) return -ENOMEM
315 if (image overlaps another image) return -EPERM
316
317This SMC copies the secure image indicated by ``image_id`` from non-secure memory
318to secure memory for later authentication. The image may be copied in a single
319block or multiple blocks. In either case, the total size of the image must be
320provided in ``image_size`` when invoking this SMC for the first time for each
321image; it is ignored in subsequent calls (if any) for the same image.
322
323The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
324The destination address is provided by the platform code.
325
326If ``block_size`` is greater than the amount of remaining bytes to copy for this
327image then the former is truncated to the latter. The copy operation is then
328considered as complete and the FWU state machine transitions to the "COPIED"
329state. If there is still more to copy, the FWU state machine stays in or
330transitions to the COPYING state (depending on the previous state).
331
332When using multiple blocks, the source blocks do not necessarily need to be in
333contiguous memory.
334
335Once the SMC is handled, BL1 returns from exception to the normal world caller.
336
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100337FWU_SMC_IMAGE_AUTH
Manish V Badarkhebd836552022-07-04 10:00:29 +0100338^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100339
340::
341
342 Arguments:
343 uint32_t function ID : 0x11
344 unsigned int image_id
345 uintptr_t image_addr
346 unsigned int image_size
347
348 Return:
349 int : 0 (Success)
350 : -ENOMEM
351 : -EPERM
352 : -EAUTH
353
354 Pre-conditions:
355 if (image_id is invalid) return -EPERM
356 if (secure world caller)
357 if (image_id state is not RESET) return -EPERM
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000358 if (image_addr/image_size is not mapped into BL1) return -ENOMEM
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100359 else // normal world caller
360 if (image_id is secure image)
361 if (image_id state is not COPIED) return -EPERM
362 else // image_id is non-secure image
363 if (image_id state is not RESET) return -EPERM
364 if (image_addr/image_size is in secure memory) return -ENOMEM
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000365 if (image_addr/image_size not mapped into BL1) return -ENOMEM
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100366
367This SMC authenticates the image specified by ``image_id``. If the image is in the
368RESET state, BL1 authenticates the image in place using the provided
369``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
370state, BL1 authenticates the image from the secure memory that BL1 previously
371copied the image into.
372
373BL1 returns from exception to the caller. If authentication succeeds then BL1
374sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
375the -EAUTH error and sets the image state back to RESET.
376
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100377FWU_SMC_IMAGE_EXECUTE
Manish V Badarkhebd836552022-07-04 10:00:29 +0100378^^^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100379
380::
381
382 Arguments:
383 uint32_t function ID : 0x12
384 unsigned int image_id
385
386 Return:
387 int : 0 (Success)
388 : -EPERM
389
390 Pre-conditions:
391 if (image_id is invalid) return -EPERM
392 if (secure world caller) return -EPERM
393 if (image_id is non-secure image) return -EPERM
394 if (image_id is non-executable image) return -EPERM
395 if (image_id state is not AUTHENTICATED) return -EPERM
396
397This SMC initiates execution of a previously authenticated image specified by
398``image_id``, in the other security world to the caller. The current
399implementation only supports normal world callers initiating execution of a
400secure world image.
401
402BL1 saves the normal world caller's context, sets the secure image state to
403EXECUTED, and returns from exception to the secure image.
404
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100405FWU_SMC_IMAGE_RESUME
Manish V Badarkhebd836552022-07-04 10:00:29 +0100406^^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100407
408::
409
410 Arguments:
411 uint32_t function ID : 0x13
412 register_t image_param
413
414 Return:
415 register_t : image_param (Success)
416 : -EPERM
417
418 Pre-conditions:
419 if (normal world caller and no INTERRUPTED secure image) return -EPERM
420
421This SMC resumes execution in the other security world while there is a secure
422image in the EXECUTED/INTERRUPTED state.
423
424For normal world callers, BL1 sets the previously interrupted secure image state
425to EXECUTED. For secure world callers, BL1 sets the previously executing secure
426image state to INTERRUPTED. In either case, BL1 saves the calling world's
427context, restores the resuming world's context and returns from exception into
428the resuming world. If the call is successful then the caller provided
429``image_param`` is returned to the resumed world, otherwise an error code is
430returned to the caller.
431
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100432FWU_SMC_SEC_IMAGE_DONE
Manish V Badarkhebd836552022-07-04 10:00:29 +0100433^^^^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100434
435::
436
437 Arguments:
438 uint32_t function ID : 0x14
439
440 Return:
441 int : 0 (Success)
442 : -EPERM
443
444 Pre-conditions:
445 if (normal world caller) return -EPERM
446
447This SMC indicates completion of a previously executing secure image.
448
449BL1 sets the previously executing secure image state to the RESET state,
450restores the normal world context and returns from exception into the normal
451world.
452
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100453FWU_SMC_UPDATE_DONE
Manish V Badarkhebd836552022-07-04 10:00:29 +0100454^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100455
456::
457
458 Arguments:
459 uint32_t function ID : 0x15
460 register_t client_cookie
461
462 Return:
463 N/A
464
465This SMC completes the firmware update process. BL1 calls the platform specific
466function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
467a ``void *``. The SMC does not return.
468
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100469FWU_SMC_IMAGE_RESET
Manish V Badarkhebd836552022-07-04 10:00:29 +0100470^^^^^^^^^^^^^^^^^^^
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100471
472::
473
474 Arguments:
475 uint32_t function ID : 0x16
476 unsigned int image_id
477
478 Return:
479 int : 0 (Success)
480 : -EPERM
481
482 Pre-conditions:
483 if (secure world caller) return -EPERM
484 if (image in EXECUTED) return -EPERM
485
486This SMC sets the state of an image to RESET and zeroes the memory used by it.
487
488This is only allowed if the image is not being executed.
489
490--------------
491
Manish V Badarkhebd836552022-07-04 10:00:29 +0100492*Copyright (c) 2015-2022, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100493
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100494.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
Paul Beesley814f8c02019-03-13 15:49:27 +0000495.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
496.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png
Manish V Badarkhebd836552022-07-04 10:00:29 +0100497.. _PSA FW update specification: https://developer.arm.com/documentation/den0118/a/