docs/components/firmware-update.rst

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