blob: a591565681f6bdd39580358daad9eaf5b3990a40 [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
Paul Beesleyf2ec7142019-10-04 16:17:46 +000010memories such as NAND Flash, LPDDR2-NVM or any memory determined by the
Douglas Raillardd7c21b72017-06-28 15:23:03 +010011platform. 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
Paul Beesleyf8640672019-04-12 14:19:42 +010017:ref:`Trusted Board Boot` design document, which describes the image
18authentication parts 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
Paul Beesleyf8640672019-04-12 14:19:42 +010056 :ref:`Porting Guide` for details of this interface.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010057
Dan Handley610e7e12018-03-01 18:44:00 +000058TF-A uses abbreviated image terminology for FWU images like for other TF-A
Paul Beesleyf8640672019-04-12 14:19:42 +010059images. See the :ref:`Image Terminology` document for an explanation of these
60terms.
Douglas Raillardd7c21b72017-06-28 15:23:03 +010061
Dan Handley610e7e12018-03-01 18:44:00 +000062The following diagram shows the FWU boot flow for Arm development platforms.
63Arm CSS platforms like Juno have a System Control Processor (SCP), and these
Douglas Raillardd7c21b72017-06-28 15:23:03 +010064use all defined FWU images. Other platforms may use a subset of these.
65
66|Flow Diagram|
67
68Image Identification
69--------------------
70
71Each FWU image and certificate is identified by a unique ID, defined by the
72platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
73call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
Paul Beesleyf8640672019-04-12 14:19:42 +010074Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust`
75document for more information).
Douglas Raillardd7c21b72017-06-28 15:23:03 +010076
77The image descriptor includes the following information:
78
79- Executable or non-executable image. This indicates whether the normal world
80 is permitted to request execution of a secure world FWU image (after
81 authentication). Secure world certificates and non-AP images are examples
82 of non-executable images.
83- Secure or non-secure image. This indicates whether the image is
84 authenticated/executed in secure or non-secure memory.
85- Image base address and size.
86- Image entry point configuration (an ``entry_point_info_t``).
87- FWU image state.
88
89BL1 uses the FWU image descriptors to:
90
91- Validate the arguments of FWU SMCs
92- Manage the state of the FWU process
93- Initialize the execution state of the next FWU image.
94
95FWU State Machine
96-----------------
97
98BL1 maintains state for each FWU image during FWU execution. FWU images at lower
99Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
100BL1 to update its FWU image state. The BL1 image states and valid state
101transitions are shown in the diagram below. Note that secure images have a more
102complex state machine than non-secure images.
103
104|FWU state machine|
105
106The following is a brief description of the supported states:
107
108- RESET: This is the initial state of every image at the start of FWU.
109 Authentication failure also leads to this state. A secure
110 image may yield to this state if it has completed execution.
111 It can also be reached by using ``FWU_SMC_IMAGE_RESET``.
112
113- COPYING: This is the state of a secure image while BL1 is copying it
114 in blocks from non-secure to secure memory.
115
116- COPIED: This is the state of a secure image when BL1 has completed
117 copying it to secure memory.
118
119- AUTHENTICATED: This is the state of an image when BL1 has successfully
120 authenticated it.
121
122- EXECUTED: This is the state of a secure, executable image when BL1 has
123 passed execution control to it.
124
125- INTERRUPTED: This is the state of a secure, executable image after it has
126 requested BL1 to resume normal world execution.
127
128BL1 SMC Interface
129-----------------
130
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100131BL1_SMC_CALL_COUNT
132~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100133
134::
135
136 Arguments:
137 uint32_t function ID : 0x0
138
139 Return:
140 uint32_t
141
142This SMC returns the number of SMCs supported by BL1.
143
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100144BL1_SMC_UID
145~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100146
147::
148
149 Arguments:
150 uint32_t function ID : 0x1
151
152 Return:
153 UUID : 32 bits in each of w0-w3 (or r0-r3 for AArch32 callers)
154
155This SMC returns the 128-bit `Universally Unique Identifier`_ for the
156BL1 SMC service.
157
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100158BL1_SMC_VERSION
159~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100160
161::
162
163 Argument:
164 uint32_t function ID : 0x3
165
166 Return:
167 uint32_t : Bits [31:16] Major Version
168 Bits [15:0] Minor Version
169
170This SMC returns the current version of the BL1 SMC service.
171
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100172BL1_SMC_RUN_IMAGE
173~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100174
175::
176
177 Arguments:
178 uint32_t function ID : 0x4
179 entry_point_info_t *ep_info
180
181 Return:
182 void
183
184 Pre-conditions:
185 if (normal world caller) synchronous exception
186 if (ep_info not EL3) synchronous exception
187
188This SMC passes execution control to an EL3 image described by the provided
Dan Handley610e7e12018-03-01 18:44:00 +0000189``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes
190this SMC for BL1 to pass execution control to BL31.
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100191
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100192FWU_SMC_IMAGE_COPY
193~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100194
195::
196
197 Arguments:
198 uint32_t function ID : 0x10
199 unsigned int image_id
200 uintptr_t image_addr
201 unsigned int block_size
202 unsigned int image_size
203
204 Return:
205 int : 0 (Success)
206 : -ENOMEM
207 : -EPERM
208
209 Pre-conditions:
210 if (image_id is invalid) return -EPERM
211 if (image_id is non-secure image) return -EPERM
212 if (image_id state is not (RESET or COPYING)) return -EPERM
213 if (secure world caller) return -EPERM
214 if (image_addr + block_size overflows) return -ENOMEM
215 if (image destination address + image_size overflows) return -ENOMEM
216 if (source block is in secure memory) return -ENOMEM
217 if (source block is not mapped into BL1) return -ENOMEM
218 if (image_size > free secure memory) return -ENOMEM
219 if (image overlaps another image) return -EPERM
220
221This SMC copies the secure image indicated by ``image_id`` from non-secure memory
222to secure memory for later authentication. The image may be copied in a single
223block or multiple blocks. In either case, the total size of the image must be
224provided in ``image_size`` when invoking this SMC for the first time for each
225image; it is ignored in subsequent calls (if any) for the same image.
226
227The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
228The destination address is provided by the platform code.
229
230If ``block_size`` is greater than the amount of remaining bytes to copy for this
231image then the former is truncated to the latter. The copy operation is then
232considered as complete and the FWU state machine transitions to the "COPIED"
233state. If there is still more to copy, the FWU state machine stays in or
234transitions to the COPYING state (depending on the previous state).
235
236When using multiple blocks, the source blocks do not necessarily need to be in
237contiguous memory.
238
239Once the SMC is handled, BL1 returns from exception to the normal world caller.
240
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100241FWU_SMC_IMAGE_AUTH
242~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100243
244::
245
246 Arguments:
247 uint32_t function ID : 0x11
248 unsigned int image_id
249 uintptr_t image_addr
250 unsigned int image_size
251
252 Return:
253 int : 0 (Success)
254 : -ENOMEM
255 : -EPERM
256 : -EAUTH
257
258 Pre-conditions:
259 if (image_id is invalid) return -EPERM
260 if (secure world caller)
261 if (image_id state is not RESET) return -EPERM
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000262 if (image_addr/image_size is not mapped into BL1) return -ENOMEM
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100263 else // normal world caller
264 if (image_id is secure image)
265 if (image_id state is not COPIED) return -EPERM
266 else // image_id is non-secure image
267 if (image_id state is not RESET) return -EPERM
268 if (image_addr/image_size is in secure memory) return -ENOMEM
Paul Beesley1fbc97b2019-01-11 18:26:51 +0000269 if (image_addr/image_size not mapped into BL1) return -ENOMEM
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100270
271This SMC authenticates the image specified by ``image_id``. If the image is in the
272RESET state, BL1 authenticates the image in place using the provided
273``image_addr`` and ``image_size``. If the image is a secure image in the COPIED
274state, BL1 authenticates the image from the secure memory that BL1 previously
275copied the image into.
276
277BL1 returns from exception to the caller. If authentication succeeds then BL1
278sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
279the -EAUTH error and sets the image state back to RESET.
280
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100281FWU_SMC_IMAGE_EXECUTE
282~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100283
284::
285
286 Arguments:
287 uint32_t function ID : 0x12
288 unsigned int image_id
289
290 Return:
291 int : 0 (Success)
292 : -EPERM
293
294 Pre-conditions:
295 if (image_id is invalid) return -EPERM
296 if (secure world caller) return -EPERM
297 if (image_id is non-secure image) return -EPERM
298 if (image_id is non-executable image) return -EPERM
299 if (image_id state is not AUTHENTICATED) return -EPERM
300
301This SMC initiates execution of a previously authenticated image specified by
302``image_id``, in the other security world to the caller. The current
303implementation only supports normal world callers initiating execution of a
304secure world image.
305
306BL1 saves the normal world caller's context, sets the secure image state to
307EXECUTED, and returns from exception to the secure image.
308
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100309FWU_SMC_IMAGE_RESUME
310~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100311
312::
313
314 Arguments:
315 uint32_t function ID : 0x13
316 register_t image_param
317
318 Return:
319 register_t : image_param (Success)
320 : -EPERM
321
322 Pre-conditions:
323 if (normal world caller and no INTERRUPTED secure image) return -EPERM
324
325This SMC resumes execution in the other security world while there is a secure
326image in the EXECUTED/INTERRUPTED state.
327
328For normal world callers, BL1 sets the previously interrupted secure image state
329to EXECUTED. For secure world callers, BL1 sets the previously executing secure
330image state to INTERRUPTED. In either case, BL1 saves the calling world's
331context, restores the resuming world's context and returns from exception into
332the resuming world. If the call is successful then the caller provided
333``image_param`` is returned to the resumed world, otherwise an error code is
334returned to the caller.
335
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100336FWU_SMC_SEC_IMAGE_DONE
337~~~~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100338
339::
340
341 Arguments:
342 uint32_t function ID : 0x14
343
344 Return:
345 int : 0 (Success)
346 : -EPERM
347
348 Pre-conditions:
349 if (normal world caller) return -EPERM
350
351This SMC indicates completion of a previously executing secure image.
352
353BL1 sets the previously executing secure image state to the RESET state,
354restores the normal world context and returns from exception into the normal
355world.
356
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100357FWU_SMC_UPDATE_DONE
358~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100359
360::
361
362 Arguments:
363 uint32_t function ID : 0x15
364 register_t client_cookie
365
366 Return:
367 N/A
368
369This SMC completes the firmware update process. BL1 calls the platform specific
370function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
371a ``void *``. The SMC does not return.
372
Sandrine Bailleux15530dd2019-02-08 15:26:36 +0100373FWU_SMC_IMAGE_RESET
374~~~~~~~~~~~~~~~~~~~
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100375
376::
377
378 Arguments:
379 uint32_t function ID : 0x16
380 unsigned int image_id
381
382 Return:
383 int : 0 (Success)
384 : -EPERM
385
386 Pre-conditions:
387 if (secure world caller) return -EPERM
388 if (image in EXECUTED) return -EPERM
389
390This SMC sets the state of an image to RESET and zeroes the memory used by it.
391
392This is only allowed if the image is not being executed.
393
394--------------
395
John Tsichritzis4730c112019-07-05 14:14:40 +0100396*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100397
Douglas Raillardd7c21b72017-06-28 15:23:03 +0100398.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt
Paul Beesley814f8c02019-03-13 15:49:27 +0000399.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png
400.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png