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