docs/getting_started/image-terminology.rst

   1 Image Terminology
   2 =================
   3
   4 This page contains the current name, abbreviated name and purpose of the various
   5 images referred to in the Trusted Firmware project.
   6
   7 General Notes
   8 -------------
   9
  10 - Some of the names and abbreviated names have changed to accommodate new
  11   requirements. The changed names are as backward compatible as possible to
  12   minimize confusion. Where applicable, the previous names are indicated. Some
  13   code, documentation and build artefacts may still refer to the previous names;
  14   these will inevitably take time to catch up.
  15
  16 - The main name change is to prefix each image with the processor it corresponds
  17   to (for example ``AP_``, ``SCP_``, ...). In situations where there is no
  18   ambiguity (for example, within AP specific code/documentation), it is
  19   permitted to omit the processor prefix (for example, just BL1 instead of
  20   ``AP_BL1``).
  21
  22 - Previously, the format for 3rd level images had 2 forms; ``BL3`` was either
  23   suffixed with a dash ("-") followed by a number (for example, ``BL3-1``) or a
  24   subscript number, depending on whether rich text formatting was available.
  25   This was confusing and often the dash gets omitted in practice. Therefore the
  26   new form is to just omit the dash and not use subscript formatting.
  27
  28 - The names no longer contain dash ("-") characters at all. In some places (for
  29   example, function names) it's not possible to use this character. All dashes
  30   are either removed or replaced by underscores ("_").
  31
  32 - The abbreviation BL stands for BootLoader. This is a historical anomaly.
  33   Clearly, many of these images are not BootLoaders, they are simply firmware
  34   images. However, the BL abbreviation is now widely used and is retained for
  35   backwards compatibility.
  36
  37 - The image names are not case sensitive. For example, ``bl1`` is
  38   interchangeable with ``BL1``, although mixed case should be avoided.
  39
  40 Trusted Firmware Images
  41 -----------------------
  42
  43 AP Boot ROM: ``AP_BL1``
  44 ~~~~~~~~~~~~~~~~~~~~~~~
  45
  46 Typically, this is the first code to execute on the AP and cannot be modified.
  47 Its primary purpose is to perform the minimum initialization necessary to load
  48 and authenticate an updateable AP firmware image into an executable RAM
  49 location, then hand-off control to that image.
  50
  51 AP RAM Firmware: ``AP_BL2``
  52 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53
  54 This is the 2nd stage AP firmware. It is currently also known as the "Trusted
  55 Boot Firmware". Its primary purpose is to perform any additional initialization
  56 required to load and authenticate all 3rd level firmware images into their
  57 executable RAM locations, then hand-off control to the EL3 Runtime Firmware.
  58
  59 EL3 Runtime Firmware: ``AP_BL31``
  60 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  61
  62 Also known as "SoC AP firmware" or "EL3 monitor firmware". Its primary purpose
  63 is to handle transitions between the normal and secure world.
  64
  65 Secure-EL1 Payload (SP): ``AP_BL32``
  66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  67
  68 Typically this is a TEE or Trusted OS, providing runtime secure services to the
  69 normal world. However, it may refer to a more abstract Secure-EL1 Payload (SP).
  70 Note that this abbreviation should only be used in systems where there is a
  71 single or primary image executing at Secure-EL1. In systems where there are
  72 potentially multiple SPs and there is no concept of a primary SP, this
  73 abbreviation should be avoided; use the recommended **Other AP 3rd level
  74 images** abbreviation instead.
  75
  76 AP Normal World Firmware: ``AP_BL33``
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  78
  79 For example, UEFI or uboot. Its primary purpose is to boot a normal world OS.
  80
  81 Other AP 3rd level images: ``AP_BL3_XXX``
  82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  83
  84 The abbreviated names of the existing 3rd level images imply a load/execution
  85 ordering (for example, ``AP_BL31 -> AP_BL32 -> AP_BL33``).  Some systems may
  86 have additional images and/or a different load/execution ordering. The
  87 abbreviated names of the existing images are retained for backward compatibility
  88 but new 3rd level images should be suffixed with an underscore followed by text
  89 identifier, not a number.
  90
  91 In systems where 3rd level images are provided by different vendors, the
  92 abbreviated name should identify the vendor as well as the image
  93 function. For example, ``AP_BL3_ARM_RAS``.
  94
  95 SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``)
  96 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  97
  98 Typically, this is the first code to execute on the SCP and cannot be modified.
  99 Its primary purpose is to perform the minimum initialization necessary to load
 100 and authenticate an updateable SCP firmware image into an executable RAM
 101 location, then hand-off control to that image. This may be performed in
 102 conjunction with other processor firmware (for example, ``AP_BL1`` and
 103 ``AP_BL2``).
 104
 105 This image was previously abbreviated as ``BL0`` but in some systems, the SCP
 106 may directly load/authenticate its own firmware. In these systems, it doesn't
 107 make sense to interleave the image terminology for AP and SCP; both AP and SCP
 108 Boot ROMs are ``BL1`` from their own point of view.
 109
 110 SCP RAM Firmware: ``SCP_BL2`` (previously ``BL3-0``)
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 This is the 2nd stage SCP firmware. It is currently also known as the "SCP
 114 runtime firmware" but it could potentially be an intermediate firmware if the
 115 SCP needs to load/authenticate multiple 3rd level images in future.
 116
 117 This image was previously abbreviated as BL3-0 but from the SCP's point of view,
 118 this has always been the 2nd stage firmware. The previous name is too
 119 AP-centric.
 120
 121 Firmware Update (FWU) Images
 122 ----------------------------
 123
 124 The terminology for these images has not been widely adopted yet but they have
 125 to be considered in a production Trusted Board Boot solution.
 126
 127 AP Firmware Update Boot ROM: ``AP_NS_BL1U``
 128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 129
 130 Typically, this is the first normal world code to execute on the AP during a
 131 firmware update operation, and cannot be modified. Its primary purpose is to
 132 load subsequent firmware update images from an external interface and communicate
 133 with ``AP_BL1`` to authenticate those images.
 134
 135 During firmware update, there are (potentially) multiple transitions between the
 136 secure and normal world. The "level" of the BL image is relative to the world
 137 it's in so it makes sense to encode "NS" in the normal world images. The absence
 138 of "NS" implies a secure world image.
 139
 140 AP Firmware Update Config: ``AP_BL2U``
 141 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 142
 143 This image does the minimum necessary AP secure world configuration required to
 144 complete the firmware update operation. It is potentially a subset of ``AP_BL2``
 145 functionality.
 146
 147 SCP Firmware Update Config: ``SCP_BL2U`` (previously ``BL2-U0``)
 148 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 149
 150 This image does the minimum necessary SCP secure world configuration required to
 151 complete the firmware update operation. It is potentially a subset of
 152 ``SCP_BL2`` functionality.
 153
 154 AP Firmware Updater: ``AP_NS_BL2U`` (previously ``BL3-U``)
 155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 156
 157 This is the 2nd stage AP normal world firmware updater. Its primary purpose is
 158 to load a new set of firmware images from an external interface and write them
 159 into non-volatile storage.
 160
 161 Other Processor Firmware Images
 162 -------------------------------
 163
 164 Some systems may have additional processors to the AP and SCP. For example, a
 165 Management Control Processor (MCP). Images for these processors should follow
 166 the same terminology, with the processor abbreviation prefix, followed by
 167 underscore and the level of the firmware image.
 168
 169 For example,
 170
 171 MCP Boot ROM: ``MCP_BL1``
 172 ~~~~~~~~~~~~~~~~~~~~~~~~~
 173
 174 MCP RAM Firmware: ``MCP_BL2``
 175 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~