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