docs/components/firmware-update.rst

   1 Firmware Update (FWU)
   2 =====================
   3
   4 .. contents::
   5
   6 --------------
   7
   8 Introduction
   9 ------------
  10
  11 This document describes the design of the Firmware Update (FWU) feature, which
  12 enables authenticated firmware to update firmware images from external
  13 interfaces such as USB, UART, SD-eMMC, NAND, NOR or Ethernet to SoC Non-Volatile
  14 memories such as NAND Flash, LPPDR2-NVM or any memory determined by the
  15 platform. This feature functions even when the current firmware in the system
  16 is corrupt or missing; it therefore may be used as a recovery mode. It may also
  17 be complemented by other, higher level firmware update software.
  18
  19 FWU implements a specific part of the Trusted Board Boot Requirements (TBBR)
  20 specification, Arm DEN0006C-1. It should be used in conjunction with the
  21 `Trusted Board Boot`_ design document, which describes the image authentication
  22 parts of the Trusted Firmware-A (TF-A) TBBR implementation.
  23
  24 Scope
  25 ~~~~~
  26
  27 This document describes the secure world FWU design. It is beyond its scope to
  28 describe how normal world FWU images should operate. To implement normal world
  29 FWU images, please refer to the "Non-Trusted Firmware Updater" requirements in
  30 the TBBR.
  31
  32 FWU Overview
  33 ------------
  34
  35 The FWU boot flow is primarily mediated by BL1. Since BL1 executes in ROM, and
  36 it is usually desirable to minimize the amount of ROM code, the design allows
  37 some parts of FWU to be implemented in other secure and normal world images.
  38 Platform code may choose which parts are implemented in which images but the
  39 general 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
  54 The 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
  62 TF-A uses abbreviated image terminology for FWU images like for other TF-A
  63 images. An overview of this terminology can be found `here`_.
  64
  65 The following diagram shows the FWU boot flow for Arm development platforms.
  66 Arm CSS platforms like Juno have a System Control Processor (SCP), and these
  67 use all defined FWU images. Other platforms may use a subset of these.
  68
  69 |Flow Diagram|
  70
  71 Image Identification
  72 --------------------
  73
  74 Each FWU image and certificate is identified by a unique ID, defined by the
  75 platform, which BL1 uses to fetch an image descriptor (``image_desc_t``) via a
  76 call to ``bl1_plat_get_image_desc()``. The same ID is also used to prepare the
  77 Chain of Trust (Refer to the `Authentication Framework Design`_
  78 for more information).
  79
  80 The 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
  92 BL1 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
  98 FWU State Machine
  99 -----------------
 100
 101 BL1 maintains state for each FWU image during FWU execution. FWU images at lower
 102 Exception Levels raise SMCs to invoke FWU functionality in BL1, which causes
 103 BL1 to update its FWU image state. The BL1 image states and valid state
 104 transitions are shown in the diagram below. Note that secure images have a more
 105 complex state machine than non-secure images.
 106
 107 |FWU state machine|
 108
 109 The 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
 131 BL1 SMC Interface
 132 -----------------
 133
 134 BL1_SMC_CALL_COUNT
 135 ~~~~~~~~~~~~~~~~~~
 136
 137 ::
 138
 139     Arguments:
 140         uint32_t function ID : 0x0
 141
 142     Return:
 143         uint32_t
 144
 145 This SMC returns the number of SMCs supported by BL1.
 146
 147 BL1_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
 158 This SMC returns the 128-bit `Universally Unique Identifier`_ for the
 159 BL1 SMC service.
 160
 161 BL1_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
 173 This SMC returns the current version of the BL1 SMC service.
 174
 175 BL1_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
 191 This 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
 193 this SMC for BL1 to pass execution control to BL31.
 194
 195 FWU_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
 224 This SMC copies the secure image indicated by ``image_id`` from non-secure memory
 225 to secure memory for later authentication. The image may be copied in a single
 226 block or multiple blocks. In either case, the total size of the image must be
 227 provided in ``image_size`` when invoking this SMC for the first time for each
 228 image; it is ignored in subsequent calls (if any) for the same image.
 229
 230 The ``image_addr`` and ``block_size`` specify the source memory block to copy from.
 231 The destination address is provided by the platform code.
 232
 233 If ``block_size`` is greater than the amount of remaining bytes to copy for this
 234 image then the former is truncated to the latter. The copy operation is then
 235 considered as complete and the FWU state machine transitions to the "COPIED"
 236 state. If there is still more to copy, the FWU state machine stays in or
 237 transitions to the COPYING state (depending on the previous state).
 238
 239 When using multiple blocks, the source blocks do not necessarily need to be in
 240 contiguous memory.
 241
 242 Once the SMC is handled, BL1 returns from exception to the normal world caller.
 243
 244 FWU_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
 274 This SMC authenticates the image specified by ``image_id``. If the image is in the
 275 RESET 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
 277 state, BL1 authenticates the image from the secure memory that BL1 previously
 278 copied the image into.
 279
 280 BL1 returns from exception to the caller. If authentication succeeds then BL1
 281 sets the image state to AUTHENTICATED. If authentication fails then BL1 returns
 282 the -EAUTH error and sets the image state back to RESET.
 283
 284 FWU_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
 304 This SMC initiates execution of a previously authenticated image specified by
 305 ``image_id``, in the other security world to the caller. The current
 306 implementation only supports normal world callers initiating execution of a
 307 secure world image.
 308
 309 BL1 saves the normal world caller's context, sets the secure image state to
 310 EXECUTED, and returns from exception to the secure image.
 311
 312 FWU_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
 328 This SMC resumes execution in the other security world while there is a secure
 329 image in the EXECUTED/INTERRUPTED state.
 330
 331 For normal world callers, BL1 sets the previously interrupted secure image state
 332 to EXECUTED. For secure world callers, BL1 sets the previously executing secure
 333 image state to INTERRUPTED. In either case, BL1 saves the calling world's
 334 context, restores the resuming world's context and returns from exception into
 335 the 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
 337 returned to the caller.
 338
 339 FWU_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
 354 This SMC indicates completion of a previously executing secure image.
 355
 356 BL1 sets the previously executing secure image state to the RESET state,
 357 restores the normal world context and returns from exception into the normal
 358 world.
 359
 360 FWU_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
 372 This SMC completes the firmware update process. BL1 calls the platform specific
 373 function ``bl1_plat_fwu_done``, passing the optional argument ``client_cookie`` as
 374 a ``void *``. The SMC does not return.
 375
 376 FWU_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
 393 This SMC sets the state of an image to RESET and zeroes the memory used by it.
 394
 395 This 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