blob: 30bdc24b289187c57b5fa4c8c1cdbc1df881734d [file] [log] [blame]
Paul Beesleyfc9ee362019-03-07 15:47:15 +00001Firmware Update (FWU)
2=====================
Douglas Raillardd7c21b72017-06-28 15:23:03 +01003
Douglas Raillardd7c21b72017-06-28 15:23:03 +01004Introduction
5------------
6
7This document describes the design of the Firmware Update (FWU) feature, which
8enables authenticated firmware to update firmware images from external
9interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile
10memories such as NAND Flash, LPPDR2-NVM or any memory determined by the
11platform. This feature functions even when the current firmware in the system
12is corrupt or missing; it therefore may be used as a recovery mode. It may also
13be complemented by other, higher level firmware update software.
14
15FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
Dan Handley610e7e12018-03-01 18:44:00 +000016specification, Arm DEN0006C-1. It should be used in conjunction with the
Douglas Raillardd7c21b72017-06-28 15:23:03 +010017`Trusted Board Boot`_ design document, which describes the image authentication
Dan Handley610e7e12018-03-01 18:44:00 +000018parts of the Trusted Firmware-A (TF-A) TBBR implementation.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010019
20Scope
21~~~~~
22
23This document describes the secure world FWU design. It is beyond its scope to
24describe how normal world FWU images should operate. To implement normal world
25FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
26the TBBR.
27
28FWU Overview
29------------
30
31The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
32it is usually desirable to minimize the amount of ROM code, the design allows
33some parts of FWU to be implemented in other secure and normal world images.
34Platform code may choose which parts are implemented in which images but the
35general expectation is:
36
37- BL1 handles:
38
39 - Detection and initiation of the FWU boot flow.
40 - Copying images from non-secure to secure memory
41 - FWU image authentication
42 - Context switching between the normal and secure world during the FWU
43 process.
44
45- Other secure world FWU images handle platform initialization required by
46 the FWU process.
47- Normal world FWU images handle loading of firmware images from external
48 interfaces to non-secure memory.
49
50The primary requirements of the FWU feature are:
51
52#. Export a BL1 SMC interface to interoperate with other FWU images executing
53 at other Exception Levels.
54#. Export a platform interface to provide FWU common code with the information
55 it needs, and to enable platform specific FWU functionality. See the
56 `Porting Guide`_ for details of this interface.
57
Dan Handley610e7e12018-03-01 18:44:00 +000058TF-A uses abbreviated image terminology for FWU images like for other TF-A
59images. An overview of this terminology can be found `here`_.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010060
Dan Handley610e7e12018-03-01 18:44:00 +000061The following diagram shows the FWU boot flow for Arm development platforms.
62Arm CSS platforms like Juno have a System Control Processor (SCP), and these
Douglas Raillardd7c21b72017-06-28 15:23:03 +010063use all defined FWU images. Other platforms may use a subset of these.
64
65|Flow Diagram|
66
67Image Identification
68--------------------
69
70Each FWU image and certificate is identified by a unique ID, defined by the
71platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
72call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
73Chain of Trust (Refer to the `Authentication Framework Design`_
74for more information).
75
76The image descriptor includes the following information:
77
78- Executable or non-executable image. This indicates whether the normal world
79 is permitted to request execution of a secure world FWU image (after
80 authentication). Secure world certificates and non-AP images are examples
81 of non-executable images.
82- Secure or non-secure image. This indicates whether the image is
83 authenticated/executed in secure or non-secure memory.
84- Image base address and size.
85- Image entry point configuration (an ``entry_point_info_t``).
86- FWU image state.
87
88BL1 uses the FWU image descriptors to:
89
90- Validate the arguments of FWU SMCs
91- Manage the state of the FWU process
92- Initialize the execution state of the next FWU image.
93
94FWU State Machine
95-----------------
96
97BL1 maintains state for each FWU image during FWU execution. FWU images at lower
98Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
99BL1 to update its FWU image state. The BL1 image states and valid state
100transitions are shown in the diagram below. Note that secure images have a more
101complex state machine than non-secure images.
102
103|FWU state machine|
104
105The following is a brief description of the supported states:
106
107- RESET: This is the initial state of every image at the start of FWU.
108 Authentication failure also leads to this state. A secure
109 image may yield to this state if it has completed execution.
110 It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
111
112- COPYING: This is the state of a secure image while BL1 is copying it
113 in blocks from non-secure to secure memory.
114
115- COPIED: This is the state of a secure image when BL1 has completed
116 copying it to secure memory.
117
118- AUTHENTICATED: This is the state of an image when BL1 has successfully
119 authenticated it.
120
121- EXECUTED: This is the state of a secure, executable image when BL1 has
122 passed execution control to it.
123
124- INTERRUPTED: This is the state of a secure, executable image after it has
125 requested BL1 to resume normal world execution.
126
127BL1 SMC Interface
128-----------------
129
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100130BL1_SMC_CALL_COUNT
131~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100132
133::
134
135 Arguments:
136 uint32_t function ID : 0x0
137
138 Return:
139 uint32_t
140
141This SMC returns the number of SMCs supported by BL1.
142
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100143BL1_SMC_UID
144~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100145
146::
147
148 Arguments:
149 uint32_t function ID : 0x1
150
151 Return:
152 UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
153
154This SMC returns the 128-bit `Universally Unique Identifier`_ for the
155BL1 SMC service.
156
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100157BL1_SMC_VERSION
158~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100159
160::
161
162 Argument:
163 uint32_t function ID : 0x3
164
165 Return:
166 uint32_t : Bits [31:16] Major Version
167 Bits [15:0] Minor Version
168
169This SMC returns the current version of the BL1 SMC service.
170
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100171BL1_SMC_RUN_IMAGE
172~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100173
174::
175
176 Arguments:
177 uint32_t function ID : 0x4
178 entry_point_info_t *ep_info
179
180 Return:
181 void
182
183 Pre-conditions:
184 if (normal world caller) synchronous exception
185 if (ep_info not EL3) synchronous exception
186
187This SMC passes execution control to an EL3 image described by the provided
Dan Handley610e7e12018-03-01 18:44:00 +0000188``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
189this SMC for BL1 to pass execution control to BL31.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100190
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100191FWU_SMC_IMAGE_COPY
192~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100193
194::
195
196 Arguments:
197 uint32_t function ID : 0x10
198 unsigned int image_id
199 uintptr_t image_addr
200 unsigned int block_size
201 unsigned int image_size
202
203 Return:
204 int : 0 (Success)
205 : -ENOMEM
206 : -EPERM
207
208 Pre-conditions:
209 if (image_id is invalid) return -EPERM
210 if (image_id is non-secure image) return -EPERM
211 if (image_id state is not (RESET or COPYING)) return -EPERM
212 if (secure world caller) return -EPERM
213 if (image_addr + block_size overflows) return -ENOMEM
214 if (image destination address + image_size overflows) return -ENOMEM
215 if (source block is in secure memory) return -ENOMEM
216 if (source block is not mapped into BL1) return -ENOMEM
217 if (image_size > free secure memory) return -ENOMEM
218 if (image overlaps another image) return -EPERM
219
220This SMC copies the secure image indicated by ``image_id`` from non-secure memory
221to secure memory for later authentication. The image may be copied in a single
222block or multiple blocks. In either case, the total size of the image must be
223provided in ``image_size`` when invoking this SMC for the first time for each
224image; it is ignored in subsequent calls (if any) for the same image.
225
226The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
227The destination address is provided by the platform code.
228
229If ``block_size`` is greater than the amount of remaining bytes to copy for this
230image then the former is truncated to the latter. The copy operation is then
231considered as complete and the FWU state machine transitions to the "COPIED"
232state. If there is still more to copy, the FWU state machine stays in or
233transitions to the COPYING state (depending on the previous state).
234
235When using multiple blocks, the source blocks do not necessarily need to be in
236contiguous memory.
237
238Once the SMC is handled, BL1 returns from exception to the normal world caller.
239
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100240FWU_SMC_IMAGE_AUTH
241~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100242
243::
244
245 Arguments:
246 uint32_t function ID : 0x11
247 unsigned int image_id
248 uintptr_t image_addr
249 unsigned int image_size
250
251 Return:
252 int : 0 (Success)
253 : -ENOMEM
254 : -EPERM
255 : -EAUTH
256
257 Pre-conditions:
258 if (image_id is invalid) return -EPERM
259 if (secure world caller)
260 if (image_id state is not RESET) return -EPERM
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000261 if (image_addr/image_size is not mapped into BL1) return -ENOMEM
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100262 else // normal world caller
263 if (image_id is secure image)
264 if (image_id state is not COPIED) return -EPERM
265 else // image_id is non-secure image
266 if (image_id state is not RESET) return -EPERM
267 if (image_addr/image_size is in secure memory) return -ENOMEM
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000268 if (image_addr/image_size not mapped into BL1) return -ENOMEM
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100269
270This SMC authenticates the image specified by ``image_id``. If the image is in the
271RESET state, BL1 authenticates the image in place using the provided
272``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
273state, BL1 authenticates the image from the secure memory that BL1 previously
274copied the image into.
275
276BL1 returns from exception to the caller. If authentication succeeds then BL1
277sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
278the -EAUTH error and sets the image state back to RESET.
279
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100280FWU_SMC_IMAGE_EXECUTE
281~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100282
283::
284
285 Arguments:
286 uint32_t function ID : 0x12
287 unsigned int image_id
288
289 Return:
290 int : 0 (Success)
291 : -EPERM
292
293 Pre-conditions:
294 if (image_id is invalid) return -EPERM
295 if (secure world caller) return -EPERM
296 if (image_id is non-secure image) return -EPERM
297 if (image_id is non-executable image) return -EPERM
298 if (image_id state is not AUTHENTICATED) return -EPERM
299
300This SMC initiates execution of a previously authenticated image specified by
301``image_id``, in the other security world to the caller. The current
302implementation only supports normal world callers initiating execution of a
303secure world image.
304
305BL1 saves the normal world caller's context, sets the secure image state to
306EXECUTED, and returns from exception to the secure image.
307
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100308FWU_SMC_IMAGE_RESUME
309~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100310
311::
312
313 Arguments:
314 uint32_t function ID : 0x13
315 register_t image_param
316
317 Return:
318 register_t : image_param (Success)
319 : -EPERM
320
321 Pre-conditions:
322 if (normal world caller and no INTERRUPTED secure image) return -EPERM
323
324This SMC resumes execution in the other security world while there is a secure
325image in the EXECUTED/INTERRUPTED state.
326
327For normal world callers, BL1 sets the previously interrupted secure image state
328to EXECUTED. For secure world callers, BL1 sets the previously executing secure
329image state to INTERRUPTED. In either case, BL1 saves the calling world's
330context, restores the resuming world's context and returns from exception into
331the resuming world. If the call is successful then the caller provided
332``image_param`` is returned to the resumed world, otherwise an error code is
333returned to the caller.
334
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100335FWU_SMC_SEC_IMAGE_DONE
336~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100337
338::
339
340 Arguments:
341 uint32_t function ID : 0x14
342
343 Return:
344 int : 0 (Success)
345 : -EPERM
346
347 Pre-conditions:
348 if (normal world caller) return -EPERM
349
350This SMC indicates completion of a previously executing secure image.
351
352BL1 sets the previously executing secure image state to the RESET state,
353restores the normal world context and returns from exception into the normal
354world.
355
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100356FWU_SMC_UPDATE_DONE
357~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100358
359::
360
361 Arguments:
362 uint32_t function ID : 0x15
363 register_t client_cookie
364
365 Return:
366 N/A
367
368This SMC completes the firmware update process. BL1 calls the platform specific
369function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
370a ``void *``. The SMC does not return.
371
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100372FWU_SMC_IMAGE_RESET
373~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100374
375::
376
377 Arguments:
378 uint32_t function ID : 0x16
379 unsigned int image_id
380
381 Return:
382 int : 0 (Success)
383 : -EPERM
384
385 Pre-conditions:
386 if (secure world caller) return -EPERM
387 if (image in EXECUTED) return -EPERM
388
389This SMC sets the state of an image to RESET and zeroes the memory used by it.
390
391This is only allowed if the image is not being executed.
392
393--------------
394
John Tsichritzis4730c112019-07-05 14:14:40 +0100395*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100396
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100397.. _Trusted Board Boot: ../design/trusted-board-boot.rst
Paul Beesleyea225122019-02-11 17:54:45 +0000398.. _Porting Guide: ../getting_started/porting-guide.rst
John Tsichritzis4730c112019-07-05 14:14:40 +0100399.. _here: ../getting_started/image-terminology.rst
John Tsichritzis2fd3d922019-05-28 13:13:39 +0100400.. _Authentication Framework Design: ../design/auth-framework.rst
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100401.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
402
Paul Beesley814f8c02019-03-13 15:49:27 +0000403.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
404.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png