blob: a90ec0b3fd8d1291ed9060e85f1b142800f3dd9d [file] [log] [blame]
Paul Beesley236d2462019-03-05 17:19:37 +00001Image Terminology
2=================
3
Joel Hutton9e605632019-02-25 15:18:56 +00004This page contains the current name, abbreviated name and purpose of the various
5images referred to in the Trusted Firmware project.
6
Paul Beesley236d2462019-03-05 17:19:37 +00007General Notes
8-------------
Joel Hutton9e605632019-02-25 15:18:56 +00009
Paul Beesleyf2ec7142019-10-04 16:17:46 +000010- Some of the names and abbreviated names have changed to accommodate new
Joel Hutton9e605632019-02-25 15:18:56 +000011 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 Beesley236d2462019-03-05 17:19:37 +000040Trusted Firmware Images
41-----------------------
42
Joel Hutton9e605632019-02-25 15:18:56 +000043AP Boot ROM: ``AP_BL1``
44~~~~~~~~~~~~~~~~~~~~~~~
45
46Typically, this is the first code to execute on the AP and cannot be modified.
Paul Beesleyf2ec7142019-10-04 16:17:46 +000047Its primary purpose is to perform the minimum initialization necessary to load
Joel Hutton9e605632019-02-25 15:18:56 +000048and 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
Zelalem Aweke023b1a42021-10-21 13:59:45 -050095Realm 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
Joel Hutton9e605632019-02-25 15:18:56 +0000103SCP Boot ROM: ``SCP_BL1`` (previously ``BL0``)
104~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
105
106Typically, this is the first code to execute on the SCP and cannot be modified.
Paul Beesleyf2ec7142019-10-04 16:17:46 +0000107Its primary purpose is to perform the minimum initialization necessary to load
Joel Hutton9e605632019-02-25 15:18:56 +0000108and 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
Paul Beesley236d2462019-03-05 17:19:37 +0000129Firmware Update (FWU) Images
130----------------------------
Joel Hutton9e605632019-02-25 15:18:56 +0000131
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
Paul Beesleyf2ec7142019-10-04 16:17:46 +0000140load subsequent firmware update images from an external interface and communicate
Joel Hutton9e605632019-02-25 15:18:56 +0000141with ``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
Paul Beesley236d2462019-03-05 17:19:37 +0000169Other Processor Firmware Images
Joel Hutton9e605632019-02-25 15:18:56 +0000170-------------------------------
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~~~~~~~~~~~~~~~~~~~~~~~~~~~~~