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