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