1Firmware Update (FWU) 2===================== 3 4Introduction 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, LPDDR2-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) 16specification, Arm DEN0006C-1. It should be used in conjunction with the 17:ref:`Trusted Board Boot` design document, which describes the image 18authentication parts of the Trusted Firmware-A (TF-A) TBBR implementation. 19 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 :ref:`Porting Guide` for details of this interface. 57 58TF-A uses abbreviated image terminology for FWU images like for other TF-A 59images. See the :ref:`Image Terminology` document for an explanation of these 60terms. 61 62The following diagram shows the FWU boot flow for Arm development platforms. 63Arm CSS platforms like Juno have a System Control Processor (SCP), and these 64use 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 74Chain of Trust (Refer to the :ref:`Authentication Framework & Chain of Trust` 75document for more information). 76 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 131BL1_SMC_CALL_COUNT 132~~~~~~~~~~~~~~~~~~ 133 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 144BL1_SMC_UID 145~~~~~~~~~~~ 146 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 158BL1_SMC_VERSION 159~~~~~~~~~~~~~~~ 160 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 172BL1_SMC_RUN_IMAGE 173~~~~~~~~~~~~~~~~~ 174 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 189``entry_point_info_t`` structure. In the normal TF-A boot flow, BL2 invokes 190this SMC for BL1 to pass execution control to BL31. 191 192FWU_SMC_IMAGE_COPY 193~~~~~~~~~~~~~~~~~~ 194 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 241FWU_SMC_IMAGE_AUTH 242~~~~~~~~~~~~~~~~~~ 243 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 262 if (image_addr/image_size is not mapped into BL1) return -ENOMEM 263 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 269 if (image_addr/image_size not mapped into BL1) return -ENOMEM 270 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 281FWU_SMC_IMAGE_EXECUTE 282~~~~~~~~~~~~~~~~~~~~~ 283 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 309FWU_SMC_IMAGE_RESUME 310~~~~~~~~~~~~~~~~~~~~ 311 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 336FWU_SMC_SEC_IMAGE_DONE 337~~~~~~~~~~~~~~~~~~~~~~ 338 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 357FWU_SMC_UPDATE_DONE 358~~~~~~~~~~~~~~~~~~~ 359 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 373FWU_SMC_IMAGE_RESET 374~~~~~~~~~~~~~~~~~~~ 375 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 396*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.* 397 398.. _Universally Unique Identifier: https://tools.ietf.org/rfc/rfc4122.txt 399.. |Flow Diagram| image:: ../resources/diagrams/fwu_flow.png 400.. |FWU state machine| image:: ../resources/diagrams/fwu_states.png 401
