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