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