1Image Terminology 2================= 3 4This page contains the current name, abbreviated name and purpose of the various 5images referred to in the Trusted Firmware project. 6 7General 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 40Trusted Firmware Images 41----------------------- 42 43AP Boot ROM: ``AP_BL1`` 44~~~~~~~~~~~~~~~~~~~~~~~ 45 46Typically, this is the first code to execute on the AP and cannot be modified. 47Its primary purpose is to perform the minimum initialization necessary to load 48and authenticate an updateable AP firmware image into an executable RAM 49location, then hand-off control to that image. 50 51AP RAM Firmware: ``AP_BL2`` 52~~~~~~~~~~~~~~~~~~~~~~~~~~~ 53 54This is the 2nd stage AP firmware. It is currently also known as the "Trusted 55Boot Firmware". Its primary purpose is to perform any additional initialization 56required to load and authenticate all 3rd level firmware images into their 57executable RAM locations, then hand-off control to the EL3 Runtime Firmware. 58 59EL3 Runtime Firmware: ``AP_BL31`` 60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 62Also known as "SoC AP firmware" or "EL3 monitor firmware". Its primary purpose 63is to handle transitions between the normal and secure world. 64 65Secure-EL1 Payload (SP): ``AP_BL32`` 66~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 67 68Typically this is a TEE or Trusted OS, providing runtime secure services to the 69normal world. However, it may refer to a more abstract Secure-EL1 Payload (SP). 70Note that this abbreviation should only be used in systems where there is a 71single or primary image executing at Secure-EL1. In systems where there are 72potentially multiple SPs and there is no concept of a primary SP, this 73abbreviation should be avoided; use the recommended **Other AP 3rd level 74images** abbreviation instead. 75 76AP Normal World Firmware: ``AP_BL33`` 77~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 78 79For example, UEFI or uboot. Its primary purpose is to boot a normal world OS. 80 81Other AP 3rd level images: ``AP_BL3_XXX`` 82~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 83 84The abbreviated names of the existing 3rd level images imply a load/execution 85ordering (for example, ``AP_BL31 -> AP_BL32 -> AP_BL33``). Some systems may 86have additional images and/or a different load/execution ordering. The 87abbreviated names of the existing images are retained for backward compatibility 88but new 3rd level images should be suffixed with an underscore followed by text 89identifier, not a number. 90 91In systems where 3rd level images are provided by different vendors, the 92abbreviated name should identify the vendor as well as the image 93function. For example, ``AP_BL3_ARM_RAS``. 94 95Realm Monitor Management Firmware: ``RMM`` 96~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 97 98This is the Realm-EL2 firmware. It is required if 99:ref:`Realm Management Extension (RME)` feature is enabled. If a path to RMM 100image is not provided, TF-A builds Test Realm Payload (TRP) image by default 101and uses it as the RMM image. 102 103SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``) 104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 105 106Typically, this is the first code to execute on the SCP and cannot be modified. 107Its primary purpose is to perform the minimum initialization necessary to load 108and authenticate an updateable SCP firmware image into an executable RAM 109location, then hand-off control to that image. This may be performed in 110conjunction with other processor firmware (for example, ``AP_BL1`` and 111``AP_BL2``). 112 113This image was previously abbreviated as ``BL0`` but in some systems, the SCP 114may directly load/authenticate its own firmware. In these systems, it doesn't 115make sense to interleave the image terminology for AP and SCP; both AP and SCP 116Boot ROMs are ``BL1`` from their own point of view. 117 118SCP RAM Firmware: ``SCP_BL2`` (previously ``BL3-0``) 119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 121This is the 2nd stage SCP firmware. It is currently also known as the "SCP 122runtime firmware" but it could potentially be an intermediate firmware if the 123SCP needs to load/authenticate multiple 3rd level images in future. 124 125This image was previously abbreviated as BL3-0 but from the SCP's point of view, 126this has always been the 2nd stage firmware. The previous name is too 127AP-centric. 128 129Firmware Update (FWU) Images 130---------------------------- 131 132The terminology for these images has not been widely adopted yet but they have 133to be considered in a production Trusted Board Boot solution. 134 135AP Firmware Update Boot ROM: ``AP_NS_BL1U`` 136~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 137 138Typically, this is the first normal world code to execute on the AP during a 139firmware update operation, and cannot be modified. Its primary purpose is to 140load subsequent firmware update images from an external interface and communicate 141with ``AP_BL1`` to authenticate those images. 142 143During firmware update, there are (potentially) multiple transitions between the 144secure and normal world. The "level" of the BL image is relative to the world 145it's in so it makes sense to encode "NS" in the normal world images. The absence 146of "NS" implies a secure world image. 147 148AP Firmware Update Config: ``AP_BL2U`` 149~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 150 151This image does the minimum necessary AP secure world configuration required to 152complete the firmware update operation. It is potentially a subset of ``AP_BL2`` 153functionality. 154 155SCP Firmware Update Config: ``SCP_BL2U`` (previously ``BL2-U0``) 156~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 157 158This image does the minimum necessary SCP secure world configuration required to 159complete the firmware update operation. It is potentially a subset of 160``SCP_BL2`` functionality. 161 162AP Firmware Updater: ``AP_NS_BL2U`` (previously ``BL3-U``) 163~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 164 165This is the 2nd stage AP normal world firmware updater. Its primary purpose is 166to load a new set of firmware images from an external interface and write them 167into non-volatile storage. 168 169Other Processor Firmware Images 170------------------------------- 171 172Some systems may have additional processors to the AP and SCP. For example, a 173Management Control Processor (MCP). Images for these processors should follow 174the same terminology, with the processor abbreviation prefix, followed by 175underscore and the level of the firmware image. 176 177For example, 178 179MCP Boot ROM: ``MCP_BL1`` 180~~~~~~~~~~~~~~~~~~~~~~~~~ 181 182MCP RAM Firmware: ``MCP_BL2`` 183~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 184