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