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