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