blob: 741ee20775113035f80aad286bacace2c5ae5740 [file] [log] [blame] [view]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001ARM Trusted Firmware Porting Guide
2==================================
3
4Contents
5--------
6
Joakim Bech14a5b342014-11-25 10:55:26 +010071. [Introduction](#1--introduction)
82. [Common Modifications](#2--common-modifications)
9 * [Common mandatory modifications](#21-common-mandatory-modifications)
10 * [Handling reset](#22-handling-reset)
Soby Mathew58523c02015-06-08 12:32:50 +010011 * [Common mandatory modifications](#23-common-mandatory-modifications)
12 * [Common optional modifications](#24-common-optional-modifications)
Joakim Bech14a5b342014-11-25 10:55:26 +0100133. [Boot Loader stage specific modifications](#3--modifications-specific-to-a-boot-loader-stage)
14 * [Boot Loader stage 1 (BL1)](#31-boot-loader-stage-1-bl1)
15 * [Boot Loader stage 2 (BL2)](#32-boot-loader-stage-2-bl2)
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +000016 * [FWU Boot Loader stage 2 (BL2U)](#33-fwu-boot-loader-stage-2-bl2u)
17 * [Boot Loader stage 3-1 (BL31)](#34-boot-loader-stage-3-1-bl31)
18 * [PSCI implementation (in BL31)](#35-power-state-coordination-interface-in-bl31)
19 * [Interrupt Management framework (in BL31)](#36--interrupt-management-framework-in-bl31)
20 * [Crash Reporting mechanism (in BL31)](#37--crash-reporting-mechanism-in-bl31)
Joakim Bech14a5b342014-11-25 10:55:26 +0100214. [Build flags](#4--build-flags)
225. [C Library](#5--c-library)
236. [Storage abstraction layer](#6--storage-abstraction-layer)
Achin Gupta4f6ad662013-10-25 09:08:21 +010024
25- - - - - - - - - - - - - - - - - -
26
271. Introduction
28----------------
29
Soby Mathew58523c02015-06-08 12:32:50 +010030Please note that this document has been updated for the new platform API
31as required by the PSCI v1.0 implementation. Please refer to the
32[Migration Guide] for the previous platform API.
33
Achin Gupta4f6ad662013-10-25 09:08:21 +010034Porting the ARM Trusted Firmware to a new platform involves making some
35mandatory and optional modifications for both the cold and warm boot paths.
36Modifications consist of:
37
38* Implementing a platform-specific function or variable,
39* Setting up the execution context in a certain way, or
40* Defining certain constants (for example #defines).
41
Dan Handley4a75b842015-03-19 19:24:43 +000042The platform-specific functions and variables are declared in
Dan Handleyb68954c2014-05-29 12:30:24 +010043[include/plat/common/platform.h]. The firmware provides a default implementation
44of variables and functions to fulfill the optional requirements. These
45implementations are all weakly defined; they are provided to ease the porting
46effort. Each platform port can override them with its own implementation if the
47default implementation is inadequate.
Achin Gupta4f6ad662013-10-25 09:08:21 +010048
Dan Handley4a75b842015-03-19 19:24:43 +000049Platform ports that want to be aligned with standard ARM platforms (for example
50FVP and Juno) may also use [include/plat/arm/common/plat_arm.h] and the
51corresponding source files in `plat/arm/common/`. These provide standard
52implementations for some of the required platform porting functions. However,
53using these functions requires the platform port to implement additional
54ARM standard platform porting functions. These additional functions are not
55documented here.
56
Achin Gupta4f6ad662013-10-25 09:08:21 +010057Some modifications are common to all Boot Loader (BL) stages. Section 2
58discusses these in detail. The subsequent sections discuss the remaining
59modifications for each BL stage in detail.
60
61This document should be read in conjunction with the ARM Trusted Firmware
62[User Guide].
63
64
652. Common modifications
66------------------------
67
68This section covers the modifications that should be made by the platform for
69each BL stage to correctly port the firmware stack. They are categorized as
70either mandatory or optional.
71
72
732.1 Common mandatory modifications
74----------------------------------
Sandrine Bailleuxef7fb9e2015-12-02 10:19:06 +000075
76A platform port must enable the Memory Management Unit (MMU) as well as the
77instruction and data caches for each BL stage. Setting up the translation
78tables is the responsibility of the platform port because memory maps differ
79across platforms. A memory translation library (see `lib/aarch64/xlat_helpers.c`
80and `lib/aarch64/xlat_tables.c`) is provided to help in this setup. Note that
81although this library supports non-identity mappings, this is intended only for
82re-mapping peripheral physical addresses and allows platforms with high I/O
83addresses to reduce their virtual address space. All other addresses
84corresponding to code and data must currently use an identity mapping.
85
86In ARM standard platforms, each BL stage configures the MMU in the
87platform-specific architecture setup function, `blX_plat_arch_setup()`, and uses
88an identity mapping for all addresses.
Achin Gupta4f6ad662013-10-25 09:08:21 +010089
Andrew Thoelkeee7b35c2015-09-10 11:39:36 +010090If the build option `USE_COHERENT_MEM` is enabled, each platform can allocate a
Soby Mathewab8707e2015-01-08 18:02:44 +000091block of identity mapped secure memory with Device-nGnRE attributes aligned to
Andrew Thoelkeee7b35c2015-09-10 11:39:36 +010092page boundary (4K) for each BL stage. All sections which allocate coherent
93memory are grouped under `coherent_ram`. For ex: Bakery locks are placed in a
94section identified by name `bakery_lock` inside `coherent_ram` so that its
95possible for the firmware to place variables in it using the following C code
96directive:
Achin Gupta4f6ad662013-10-25 09:08:21 +010097
Soren Brinkmann65cd2992016-01-14 10:11:05 -080098 __section("bakery_lock")
Achin Gupta4f6ad662013-10-25 09:08:21 +010099
100Or alternatively the following assembler code directive:
101
Andrew Thoelkeee7b35c2015-09-10 11:39:36 +0100102 .section bakery_lock
Achin Gupta4f6ad662013-10-25 09:08:21 +0100103
Andrew Thoelkeee7b35c2015-09-10 11:39:36 +0100104The `coherent_ram` section is a sum of all sections like `bakery_lock` which are
105used to allocate any data structures that are accessed both when a CPU is
106executing with its MMU and caches enabled, and when it's running with its MMU
107and caches disabled. Examples are given below.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100108
109The following variables, functions and constants must be defined by the platform
110for the firmware to work correctly.
111
112
Dan Handleyb68954c2014-05-29 12:30:24 +0100113### File : platform_def.h [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100114
Dan Handleyb68954c2014-05-29 12:30:24 +0100115Each platform must ensure that a header file of this name is in the system
116include path with the following constants defined. This may require updating the
Dan Handley4a75b842015-03-19 19:24:43 +0000117list of `PLAT_INCLUDES` in the `platform.mk` file. In the ARM development
118platforms, this file is found in `plat/arm/board/<plat_name>/include/`.
119
120Platform ports may optionally use the file [include/plat/common/common_def.h],
121which provides typical values for some of the constants below. These values are
122likely to be suitable for all platform ports.
123
124Platform ports that want to be aligned with standard ARM platforms (for example
125FVP and Juno) may also use [include/plat/arm/common/arm_def.h], which provides
126standard values for some of the constants below. However, this requires the
127platform port to define additional platform porting constants in
128`platform_def.h`. These additional constants are not documented here.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100129
James Morrisseyba3155b2013-10-29 10:56:46 +0000130* **#define : PLATFORM_LINKER_FORMAT**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100131
132 Defines the linker format used by the platform, for example
Dan Handley4a75b842015-03-19 19:24:43 +0000133 `elf64-littleaarch64`.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100134
James Morrisseyba3155b2013-10-29 10:56:46 +0000135* **#define : PLATFORM_LINKER_ARCH**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100136
137 Defines the processor architecture for the linker by the platform, for
Dan Handley4a75b842015-03-19 19:24:43 +0000138 example `aarch64`.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100139
James Morrisseyba3155b2013-10-29 10:56:46 +0000140* **#define : PLATFORM_STACK_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100141
142 Defines the normal stack memory available to each CPU. This constant is used
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000143 by [plat/common/aarch64/platform_mp_stack.S] and
144 [plat/common/aarch64/platform_up_stack.S].
145
Dan Handley4a75b842015-03-19 19:24:43 +0000146* **define : CACHE_WRITEBACK_GRANULE**
147
148 Defines the size in bits of the largest cache line across all the cache
149 levels in the platform.
150
James Morrisseyba3155b2013-10-29 10:56:46 +0000151* **#define : FIRMWARE_WELCOME_STR**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100152
153 Defines the character string printed by BL1 upon entry into the `bl1_main()`
154 function.
155
James Morrisseyba3155b2013-10-29 10:56:46 +0000156* **#define : PLATFORM_CORE_COUNT**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100157
158 Defines the total number of CPUs implemented by the platform across all
159 clusters in the system.
160
Soby Mathew58523c02015-06-08 12:32:50 +0100161* **#define : PLAT_NUM_PWR_DOMAINS**
Andrew Thoelke6c0b45d2014-06-20 00:36:14 +0100162
Soby Mathew58523c02015-06-08 12:32:50 +0100163 Defines the total number of nodes in the power domain topology
164 tree at all the power domain levels used by the platform.
165 This macro is used by the PSCI implementation to allocate
166 data structures to represent power domain topology.
Andrew Thoelke6c0b45d2014-06-20 00:36:14 +0100167
Soby Mathew58523c02015-06-08 12:32:50 +0100168* **#define : PLAT_MAX_PWR_LVL**
Soby Mathew8c32bc22015-02-12 14:45:02 +0000169
Soby Mathew58523c02015-06-08 12:32:50 +0100170 Defines the maximum power domain level that the power management operations
171 should apply to. More often, but not always, the power domain level
172 corresponds to affinity level. This macro allows the PSCI implementation
173 to know the highest power domain level that it should consider for power
174 management operations in the system that the platform implements. For
175 example, the Base AEM FVP implements two clusters with a configurable
176 number of CPUs and it reports the maximum power domain level as 1.
177
178* **#define : PLAT_MAX_OFF_STATE**
179
180 Defines the local power state corresponding to the deepest power down
181 possible at every power domain level in the platform. The local power
182 states for each level may be sparsely allocated between 0 and this value
183 with 0 being reserved for the RUN state. The PSCI implementation uses this
184 value to initialize the local power states of the power domain nodes and
185 to specify the requested power state for a PSCI_CPU_OFF call.
186
187* **#define : PLAT_MAX_RET_STATE**
188
189 Defines the local power state corresponding to the deepest retention state
190 possible at every power domain level in the platform. This macro should be
191 a value less than PLAT_MAX_OFF_STATE and greater than 0. It is used by the
192 PSCI implementation to distuiguish between retention and power down local
193 power states within PSCI_CPU_SUSPEND call.
Soby Mathew8c32bc22015-02-12 14:45:02 +0000194
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100195* **#define : BL1_RO_BASE**
196
197 Defines the base address in secure ROM where BL1 originally lives. Must be
198 aligned on a page-size boundary.
199
200* **#define : BL1_RO_LIMIT**
201
202 Defines the maximum address in secure ROM that BL1's actual content (i.e.
203 excluding any data section allocated at runtime) can occupy.
204
205* **#define : BL1_RW_BASE**
206
207 Defines the base address in secure RAM where BL1's read-write data will live
208 at runtime. Must be aligned on a page-size boundary.
209
210* **#define : BL1_RW_LIMIT**
211
212 Defines the maximum address in secure RAM that BL1's read-write data can
213 occupy at runtime.
214
James Morrisseyba3155b2013-10-29 10:56:46 +0000215* **#define : BL2_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100216
217 Defines the base address in secure RAM where BL1 loads the BL2 binary image.
Sandrine Bailleuxcd29b0a2013-11-27 10:32:17 +0000218 Must be aligned on a page-size boundary.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100219
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100220* **#define : BL2_LIMIT**
221
222 Defines the maximum address in secure RAM that the BL2 image can occupy.
223
James Morrisseyba3155b2013-10-29 10:56:46 +0000224* **#define : BL31_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100225
Juan Castillod1786372015-12-14 09:35:25 +0000226 Defines the base address in secure RAM where BL2 loads the BL31 binary
Sandrine Bailleuxcd29b0a2013-11-27 10:32:17 +0000227 image. Must be aligned on a page-size boundary.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100228
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100229* **#define : BL31_LIMIT**
230
Juan Castillod1786372015-12-14 09:35:25 +0000231 Defines the maximum address in secure RAM that the BL31 image can occupy.
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100232
Harry Liebeld265bd72014-01-31 19:04:10 +0000233* **#define : NS_IMAGE_OFFSET**
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100234
Juan Castillod1786372015-12-14 09:35:25 +0000235 Defines the base address in non-secure DRAM where BL2 loads the BL33 binary
Harry Liebeld265bd72014-01-31 19:04:10 +0000236 image. Must be aligned on a page-size boundary.
237
Juan Castillo16948ae2015-04-13 17:36:19 +0100238For every image, the platform must define individual identifiers that will be
239used by BL1 or BL2 to load the corresponding image into memory from non-volatile
240storage. For the sake of performance, integer numbers will be used as
241identifiers. The platform will use those identifiers to return the relevant
242information about the image to be loaded (file handler, load address,
243authentication information, etc.). The following image identifiers are
244mandatory:
245
246* **#define : BL2_IMAGE_ID**
247
248 BL2 image identifier, used by BL1 to load BL2.
249
250* **#define : BL31_IMAGE_ID**
251
Juan Castillod1786372015-12-14 09:35:25 +0000252 BL31 image identifier, used by BL2 to load BL31.
Juan Castillo16948ae2015-04-13 17:36:19 +0100253
254* **#define : BL33_IMAGE_ID**
255
Juan Castillod1786372015-12-14 09:35:25 +0000256 BL33 image identifier, used by BL2 to load BL33.
Juan Castillo16948ae2015-04-13 17:36:19 +0100257
258If Trusted Board Boot is enabled, the following certificate identifiers must
259also be defined:
260
Juan Castillo516beb52015-12-03 10:19:21 +0000261* **#define : TRUSTED_BOOT_FW_CERT_ID**
Juan Castillo16948ae2015-04-13 17:36:19 +0100262
263 BL2 content certificate identifier, used by BL1 to load the BL2 content
264 certificate.
265
266* **#define : TRUSTED_KEY_CERT_ID**
267
268 Trusted key certificate identifier, used by BL2 to load the trusted key
269 certificate.
270
Juan Castillo516beb52015-12-03 10:19:21 +0000271* **#define : SOC_FW_KEY_CERT_ID**
Juan Castillo16948ae2015-04-13 17:36:19 +0100272
Juan Castillod1786372015-12-14 09:35:25 +0000273 BL31 key certificate identifier, used by BL2 to load the BL31 key
Juan Castillo16948ae2015-04-13 17:36:19 +0100274 certificate.
275
Juan Castillo516beb52015-12-03 10:19:21 +0000276* **#define : SOC_FW_CONTENT_CERT_ID**
Juan Castillo16948ae2015-04-13 17:36:19 +0100277
Juan Castillod1786372015-12-14 09:35:25 +0000278 BL31 content certificate identifier, used by BL2 to load the BL31 content
Juan Castillo16948ae2015-04-13 17:36:19 +0100279 certificate.
280
Juan Castillo516beb52015-12-03 10:19:21 +0000281* **#define : NON_TRUSTED_FW_KEY_CERT_ID**
Juan Castillo16948ae2015-04-13 17:36:19 +0100282
Juan Castillod1786372015-12-14 09:35:25 +0000283 BL33 key certificate identifier, used by BL2 to load the BL33 key
Juan Castillo16948ae2015-04-13 17:36:19 +0100284 certificate.
285
Juan Castillo516beb52015-12-03 10:19:21 +0000286* **#define : NON_TRUSTED_FW_CONTENT_CERT_ID**
Juan Castillo16948ae2015-04-13 17:36:19 +0100287
Juan Castillod1786372015-12-14 09:35:25 +0000288 BL33 content certificate identifier, used by BL2 to load the BL33 content
Juan Castillo16948ae2015-04-13 17:36:19 +0100289 certificate.
290
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +0000291* **#define : FWU_CERT_ID**
292
293 Firmware Update (FWU) certificate identifier, used by NS_BL1U to load the
294 FWU content certificate.
295
296
297If the AP Firmware Updater Configuration image, BL2U is used, the following
298must also be defined:
299
300* **#define : BL2U_BASE**
301
302 Defines the base address in secure memory where BL1 copies the BL2U binary
303 image. Must be aligned on a page-size boundary.
304
305* **#define : BL2U_LIMIT**
306
307 Defines the maximum address in secure memory that the BL2U image can occupy.
308
309* **#define : BL2U_IMAGE_ID**
310
311 BL2U image identifier, used by BL1 to fetch an image descriptor
312 corresponding to BL2U.
313
314If the SCP Firmware Update Configuration Image, SCP_BL2U is used, the following
315must also be defined:
316
317* **#define : SCP_BL2U_IMAGE_ID**
318
319 SCP_BL2U image identifier, used by BL1 to fetch an image descriptor
320 corresponding to SCP_BL2U.
321 NOTE: TF does not provide source code for this image.
322
323If the Non-Secure Firmware Updater ROM, NS_BL1U is used, the following must
324also be defined:
325
326* **#define : NS_BL1U_BASE**
327
328 Defines the base address in non-secure ROM where NS_BL1U executes.
329 Must be aligned on a page-size boundary.
330 NOTE: TF does not provide source code for this image.
331
332* **#define : NS_BL1U_IMAGE_ID**
333
334 NS_BL1U image identifier, used by BL1 to fetch an image descriptor
335 corresponding to NS_BL1U.
336
337If the Non-Secure Firmware Updater, NS_BL2U is used, the following must also
338be defined:
339
340* **#define : NS_BL2U_BASE**
341
342 Defines the base address in non-secure memory where NS_BL2U executes.
343 Must be aligned on a page-size boundary.
344 NOTE: TF does not provide source code for this image.
345
346* **#define : NS_BL2U_IMAGE_ID**
347
348 NS_BL2U image identifier, used by BL1 to fetch an image descriptor
349 corresponding to NS_BL2U.
350
351
Juan Castillof59821d2015-12-10 15:49:17 +0000352If a SCP_BL2 image is supported by the platform, the following constants must
Achin Gupta8d35f612015-01-25 22:44:23 +0000353also be defined:
354
Juan Castillof59821d2015-12-10 15:49:17 +0000355* **#define : SCP_BL2_IMAGE_ID**
Achin Gupta8d35f612015-01-25 22:44:23 +0000356
Juan Castillof59821d2015-12-10 15:49:17 +0000357 SCP_BL2 image identifier, used by BL2 to load SCP_BL2 into secure memory
358 from platform storage before being transfered to the SCP.
Achin Gupta8d35f612015-01-25 22:44:23 +0000359
Juan Castillo516beb52015-12-03 10:19:21 +0000360* **#define : SCP_FW_KEY_CERT_ID**
Achin Gupta8d35f612015-01-25 22:44:23 +0000361
Juan Castillof59821d2015-12-10 15:49:17 +0000362 SCP_BL2 key certificate identifier, used by BL2 to load the SCP_BL2 key
Juan Castillo16948ae2015-04-13 17:36:19 +0100363 certificate (mandatory when Trusted Board Boot is enabled).
Achin Gupta8d35f612015-01-25 22:44:23 +0000364
Juan Castillo516beb52015-12-03 10:19:21 +0000365* **#define : SCP_FW_CONTENT_CERT_ID**
Achin Gupta8d35f612015-01-25 22:44:23 +0000366
Juan Castillof59821d2015-12-10 15:49:17 +0000367 SCP_BL2 content certificate identifier, used by BL2 to load the SCP_BL2
368 content certificate (mandatory when Trusted Board Boot is enabled).
Achin Gupta8d35f612015-01-25 22:44:23 +0000369
Juan Castillod1786372015-12-14 09:35:25 +0000370If a BL32 image is supported by the platform, the following constants must
Dan Handley5a06bb72014-08-04 11:41:20 +0100371also be defined:
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100372
Juan Castillo16948ae2015-04-13 17:36:19 +0100373* **#define : BL32_IMAGE_ID**
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100374
Juan Castillod1786372015-12-14 09:35:25 +0000375 BL32 image identifier, used by BL2 to load BL32.
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100376
Juan Castillo516beb52015-12-03 10:19:21 +0000377* **#define : TRUSTED_OS_FW_KEY_CERT_ID**
Achin Gupta8d35f612015-01-25 22:44:23 +0000378
Juan Castillod1786372015-12-14 09:35:25 +0000379 BL32 key certificate identifier, used by BL2 to load the BL32 key
Juan Castillo16948ae2015-04-13 17:36:19 +0100380 certificate (mandatory when Trusted Board Boot is enabled).
Achin Gupta8d35f612015-01-25 22:44:23 +0000381
Juan Castillo516beb52015-12-03 10:19:21 +0000382* **#define : TRUSTED_OS_FW_CONTENT_CERT_ID**
Achin Gupta8d35f612015-01-25 22:44:23 +0000383
Juan Castillod1786372015-12-14 09:35:25 +0000384 BL32 content certificate identifier, used by BL2 to load the BL32 content
Juan Castillo16948ae2015-04-13 17:36:19 +0100385 certificate (mandatory when Trusted Board Boot is enabled).
Achin Gupta8d35f612015-01-25 22:44:23 +0000386
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100387* **#define : BL32_BASE**
388
Juan Castillod1786372015-12-14 09:35:25 +0000389 Defines the base address in secure memory where BL2 loads the BL32 binary
Dan Handley5a06bb72014-08-04 11:41:20 +0100390 image. Must be aligned on a page-size boundary.
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100391
392* **#define : BL32_LIMIT**
393
Juan Castillod1786372015-12-14 09:35:25 +0000394 Defines the maximum address that the BL32 image can occupy.
Dan Handley5a06bb72014-08-04 11:41:20 +0100395
Juan Castillod1786372015-12-14 09:35:25 +0000396If the Test Secure-EL1 Payload (TSP) instantiation of BL32 is supported by the
Dan Handley5a06bb72014-08-04 11:41:20 +0100397platform, the following constants must also be defined:
398
399* **#define : TSP_SEC_MEM_BASE**
400
401 Defines the base address of the secure memory used by the TSP image on the
402 platform. This must be at the same address or below `BL32_BASE`.
403
404* **#define : TSP_SEC_MEM_SIZE**
405
Juan Castillod1786372015-12-14 09:35:25 +0000406 Defines the size of the secure memory used by the BL32 image on the
Dan Handley5a06bb72014-08-04 11:41:20 +0100407 platform. `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE` must fully accomodate
Juan Castillod1786372015-12-14 09:35:25 +0000408 the memory required by the BL32 image, defined by `BL32_BASE` and
Dan Handley5a06bb72014-08-04 11:41:20 +0100409 `BL32_LIMIT`.
410
411* **#define : TSP_IRQ_SEC_PHY_TIMER**
412
413 Defines the ID of the secure physical generic timer interrupt used by the
414 TSP's interrupt handling code.
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100415
Dan Handley4a75b842015-03-19 19:24:43 +0000416If the platform port uses the translation table library code, the following
417constant must also be defined:
418
419* **#define : MAX_XLAT_TABLES**
420
421 Defines the maximum number of translation tables that are allocated by the
422 translation table library code. To minimize the amount of runtime memory
423 used, choose the smallest value needed to map the required virtual addresses
424 for each BL stage.
425
Juan Castillo359b60d2016-01-07 11:29:15 +0000426* **#define : MAX_MMAP_REGIONS**
427
428 Defines the maximum number of regions that are allocated by the translation
429 table library code. A region consists of physical base address, virtual base
430 address, size and attributes (Device/Memory, RO/RW, Secure/Non-Secure), as
431 defined in the `mmap_region_t` structure. The platform defines the regions
432 that should be mapped. Then, the translation table library will create the
433 corresponding tables and descriptors at runtime. To minimize the amount of
434 runtime memory used, choose the smallest value needed to register the
435 required regions for each BL stage.
436
437* **#define : ADDR_SPACE_SIZE**
438
439 Defines the total size of the address space in bytes. For example, for a 32
440 bit address space, this value should be `(1ull << 32)`.
441
Dan Handley6d16ce02014-08-04 18:31:43 +0100442If the platform port uses the IO storage framework, the following constants
443must also be defined:
444
445* **#define : MAX_IO_DEVICES**
446
447 Defines the maximum number of registered IO devices. Attempting to register
448 more devices than this value using `io_register_device()` will fail with
Juan Castillo7e26fe12015-10-01 17:55:11 +0100449 -ENOMEM.
Dan Handley6d16ce02014-08-04 18:31:43 +0100450
451* **#define : MAX_IO_HANDLES**
452
453 Defines the maximum number of open IO handles. Attempting to open more IO
Juan Castillo7e26fe12015-10-01 17:55:11 +0100454 entities than this value using `io_open()` will fail with -ENOMEM.
Dan Handley6d16ce02014-08-04 18:31:43 +0100455
Soby Mathewab8707e2015-01-08 18:02:44 +0000456If the platform needs to allocate data within the per-cpu data framework in
Juan Castillod1786372015-12-14 09:35:25 +0000457BL31, it should define the following macro. Currently this is only required if
Soby Mathewab8707e2015-01-08 18:02:44 +0000458the platform decides not to use the coherent memory section by undefining the
Sandrine Bailleux1645d3e2015-12-17 13:58:58 +0000459`USE_COHERENT_MEM` build flag. In this case, the framework allocates the
460required memory within the the per-cpu data to minimize wastage.
Soby Mathewab8707e2015-01-08 18:02:44 +0000461
462* **#define : PLAT_PCPU_DATA_SIZE**
463
464 Defines the memory (in bytes) to be reserved within the per-cpu data
465 structure for use by the platform layer.
466
Sandrine Bailleux46d49f632014-06-23 17:00:23 +0100467The following constants are optional. They should be defined when the platform
Dan Handley4a75b842015-03-19 19:24:43 +0000468memory layout implies some image overlaying like in ARM standard platforms.
Sandrine Bailleux46d49f632014-06-23 17:00:23 +0100469
470* **#define : BL31_PROGBITS_LIMIT**
471
Juan Castillod1786372015-12-14 09:35:25 +0000472 Defines the maximum address in secure RAM that the BL31's progbits sections
Sandrine Bailleux46d49f632014-06-23 17:00:23 +0100473 can occupy.
474
Dan Handley5a06bb72014-08-04 11:41:20 +0100475* **#define : TSP_PROGBITS_LIMIT**
Sandrine Bailleux46d49f632014-06-23 17:00:23 +0100476
477 Defines the maximum address that the TSP's progbits sections can occupy.
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100478
Haojian Zhuang7dc4b222016-02-03 22:35:04 +0800479If the platform port uses the PL061 GPIO driver, the following constant may
480optionally be defined:
481
482* **PLAT_PL061_MAX_GPIOS**
483 Maximum number of GPIOs required by the platform. This allows control how
484 much memory is allocated for PL061 GPIO controllers. The default value is
485 32.
486 [For example, define the build flag in platform.mk]:
487 PLAT_PL061_MAX_GPIOS := 160
488 $(eval $(call add_define,PLAT_PL061_MAX_GPIOS))
489
490
Dan Handleyb68954c2014-05-29 12:30:24 +0100491### File : plat_macros.S [mandatory]
Soby Mathewa43d4312014-04-07 15:28:55 +0100492
Dan Handleyb68954c2014-05-29 12:30:24 +0100493Each platform must ensure a file of this name is in the system include path with
Dan Handley4a75b842015-03-19 19:24:43 +0000494the following macro defined. In the ARM development platforms, this file is
495found in `plat/arm/board/<plat_name>/include/plat_macros.S`.
Soby Mathewa43d4312014-04-07 15:28:55 +0100496
497* **Macro : plat_print_gic_regs**
498
499 This macro allows the crash reporting routine to print GIC registers
Juan Castillod1786372015-12-14 09:35:25 +0000500 in case of an unhandled exception in BL31. This aids in debugging and
Soby Mathewa43d4312014-04-07 15:28:55 +0100501 this macro can be defined to be empty in case GIC register reporting is
502 not desired.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100503
Soby Mathew8c106902014-07-16 09:23:52 +0100504* **Macro : plat_print_interconnect_regs**
505
Dan Handley4a75b842015-03-19 19:24:43 +0000506 This macro allows the crash reporting routine to print interconnect
Juan Castillod1786372015-12-14 09:35:25 +0000507 registers in case of an unhandled exception in BL31. This aids in debugging
Dan Handley4a75b842015-03-19 19:24:43 +0000508 and this macro can be defined to be empty in case interconnect register
509 reporting is not desired. In ARM standard platforms, the CCI snoop
510 control registers are reported.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100511
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000512
Vikram Kanigirie452cd82014-05-23 15:56:12 +01005132.2 Handling Reset
514------------------
515
516BL1 by default implements the reset vector where execution starts from a cold
Juan Castillod1786372015-12-14 09:35:25 +0000517or warm boot. BL31 can be optionally set as a reset vector using the
Sandrine Bailleux1645d3e2015-12-17 13:58:58 +0000518`RESET_TO_BL31` make variable.
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100519
520For each CPU, the reset vector code is responsible for the following tasks:
521
5221. Distinguishing between a cold boot and a warm boot.
523
5242. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
525 the CPU is placed in a platform-specific state until the primary CPU
526 performs the necessary steps to remove it from this state.
527
5283. In the case of a warm boot, ensuring that the CPU jumps to a platform-
Juan Castillod1786372015-12-14 09:35:25 +0000529 specific address in the BL31 image in the same processor mode as it was
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100530 when released from reset.
531
532The following functions need to be implemented by the platform port to enable
533reset vector code to perform the above tasks.
534
535
Soby Mathew58523c02015-06-08 12:32:50 +0100536### Function : plat_get_my_entrypoint() [mandatory when PROGRAMMABLE_RESET_ADDRESS == 0]
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100537
Soby Mathew58523c02015-06-08 12:32:50 +0100538 Argument : void
539 Return : unsigned long
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100540
Soby Mathew58523c02015-06-08 12:32:50 +0100541This function is called with the called with the MMU and caches disabled
542(`SCTLR_EL3.M` = 0 and `SCTLR_EL3.C` = 0). The function is responsible for
543distinguishing between a warm and cold reset for the current CPU using
544platform-specific means. If it's a warm reset, then it returns the warm
545reset entrypoint point provided to `plat_setup_psci_ops()` during
Juan Castillod1786372015-12-14 09:35:25 +0000546BL31 initialization. If it's a cold reset then this function must return zero.
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100547
548This function does not follow the Procedure Call Standard used by the
549Application Binary Interface for the ARM 64-bit architecture. The caller should
550not assume that callee saved registers are preserved across a call to this
551function.
552
553This function fulfills requirement 1 and 3 listed above.
554
Soby Mathew58523c02015-06-08 12:32:50 +0100555Note that for platforms that support programming the reset address, it is
556expected that a CPU will start executing code directly at the right address,
557both on a cold and warm reset. In this case, there is no need to identify the
558type of reset nor to query the warm reset entrypoint. Therefore, implementing
559this function is not required on such platforms.
560
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100561
Sandrine Bailleuxa9bec672015-10-30 15:05:17 +0000562### Function : plat_secondary_cold_boot_setup() [mandatory when COLD_BOOT_SINGLE_CPU == 0]
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100563
564 Argument : void
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100565
566This function is called with the MMU and data caches disabled. It is responsible
567for placing the executing secondary CPU in a platform-specific state until the
568primary CPU performs the necessary actions to bring it out of that state and
Sandrine Bailleux52010cc2015-05-19 11:54:45 +0100569allow entry into the OS. This function must not return.
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100570
Sandrine Bailleuxcdf14082015-10-02 14:35:25 +0100571In the ARM FVP port, when using the normal boot flow, each secondary CPU powers
572itself off. The primary CPU is responsible for powering up the secondary CPUs
573when normal world software requires them. When booting an EL3 payload instead,
574they stay powered on and are put in a holding pen until their mailbox gets
575populated.
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100576
577This function fulfills requirement 2 above.
578
Sandrine Bailleuxa9bec672015-10-30 15:05:17 +0000579Note that for platforms that can't release secondary CPUs out of reset, only the
580primary CPU will execute the cold boot code. Therefore, implementing this
581function is not required on such platforms.
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100582
Sandrine Bailleuxa9bec672015-10-30 15:05:17 +0000583
584### Function : plat_is_my_cpu_primary() [mandatory when COLD_BOOT_SINGLE_CPU == 0]
Juan Castillo53fdceb2014-07-16 15:53:43 +0100585
Soby Mathew58523c02015-06-08 12:32:50 +0100586 Argument : void
Juan Castillo53fdceb2014-07-16 15:53:43 +0100587 Return : unsigned int
588
Soby Mathew58523c02015-06-08 12:32:50 +0100589This function identifies whether the current CPU is the primary CPU or a
590secondary CPU. A return value of zero indicates that the CPU is not the
591primary CPU, while a non-zero return value indicates that the CPU is the
592primary CPU.
Juan Castillo53fdceb2014-07-16 15:53:43 +0100593
Sandrine Bailleuxa9bec672015-10-30 15:05:17 +0000594Note that for platforms that can't release secondary CPUs out of reset, only the
595primary CPU will execute the cold boot code. Therefore, there is no need to
596distinguish between primary and secondary CPUs and implementing this function is
597not required.
598
Juan Castillo53fdceb2014-07-16 15:53:43 +0100599
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100600### Function : platform_mem_init() [mandatory]
601
602 Argument : void
603 Return : void
604
605This function is called before any access to data is made by the firmware, in
606order to carry out any essential memory initialization.
607
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100608
Juan Castillo95cfd4a2015-04-14 12:49:03 +0100609### Function: plat_get_rotpk_info()
610
611 Argument : void *, void **, unsigned int *, unsigned int *
612 Return : int
613
614This function is mandatory when Trusted Board Boot is enabled. It returns a
615pointer to the ROTPK stored in the platform (or a hash of it) and its length.
616The ROTPK must be encoded in DER format according to the following ASN.1
617structure:
618
619 AlgorithmIdentifier ::= SEQUENCE {
620 algorithm OBJECT IDENTIFIER,
621 parameters ANY DEFINED BY algorithm OPTIONAL
622 }
623
624 SubjectPublicKeyInfo ::= SEQUENCE {
625 algorithm AlgorithmIdentifier,
626 subjectPublicKey BIT STRING
627 }
628
629In case the function returns a hash of the key:
630
631 DigestInfo ::= SEQUENCE {
632 digestAlgorithm AlgorithmIdentifier,
633 digest OCTET STRING
634 }
635
636The function returns 0 on success. Any other value means the ROTPK could not be
637retrieved from the platform. The function also reports extra information related
638to the ROTPK in the flags parameter.
639
640
Soby Mathew58523c02015-06-08 12:32:50 +01006412.3 Common mandatory modifications
642---------------------------------
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100643
Soby Mathew58523c02015-06-08 12:32:50 +0100644The following functions are mandatory functions which need to be implemented
645by the platform port.
646
647### Function : plat_my_core_pos()
648
649 Argument : void
650 Return : unsigned int
651
652This funtion returns the index of the calling CPU which is used as a
653CPU-specific linear index into blocks of memory (for example while allocating
654per-CPU stacks). This function will be invoked very early in the
655initialization sequence which mandates that this function should be
656implemented in assembly and should not rely on the avalability of a C
Antonio Nino Diaze5846732016-02-08 10:39:42 +0000657runtime environment. This function can clobber x0 - x8 and must preserve
658x9 - x29.
Soby Mathew58523c02015-06-08 12:32:50 +0100659
660This function plays a crucial role in the power domain topology framework in
661PSCI and details of this can be found in [Power Domain Topology Design].
662
663### Function : plat_core_pos_by_mpidr()
664
665 Argument : u_register_t
666 Return : int
667
668This function validates the `MPIDR` of a CPU and converts it to an index,
669which can be used as a CPU-specific linear index into blocks of memory. In
670case the `MPIDR` is invalid, this function returns -1. This function will only
Juan Castillod1786372015-12-14 09:35:25 +0000671be invoked by BL31 after the power domain topology is initialized and can
Soby Mathew58523c02015-06-08 12:32:50 +0100672utilize the C runtime environment. For further details about how ARM Trusted
673Firmware represents the power domain topology and how this relates to the
674linear CPU index, please refer [Power Domain Topology Design].
675
676
677
6782.4 Common optional modifications
Achin Gupta4f6ad662013-10-25 09:08:21 +0100679---------------------------------
680
681The following are helper functions implemented by the firmware that perform
682common platform-specific tasks. A platform may choose to override these
683definitions.
684
Soby Mathew58523c02015-06-08 12:32:50 +0100685### Function : plat_set_my_stack()
Achin Gupta4f6ad662013-10-25 09:08:21 +0100686
Soby Mathew58523c02015-06-08 12:32:50 +0100687 Argument : void
Achin Gupta4f6ad662013-10-25 09:08:21 +0100688 Return : void
689
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000690This function sets the current stack pointer to the normal memory stack that
Soby Mathew58523c02015-06-08 12:32:50 +0100691has been allocated for the current CPU. For BL images that only require a
692stack for the primary CPU, the UP version of the function is used. The size
693of the stack allocated to each CPU is specified by the platform defined
694constant `PLATFORM_STACK_SIZE`.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100695
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000696Common implementations of this function for the UP and MP BL images are
697provided in [plat/common/aarch64/platform_up_stack.S] and
698[plat/common/aarch64/platform_mp_stack.S]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100699
700
Soby Mathew58523c02015-06-08 12:32:50 +0100701### Function : plat_get_my_stack()
Achin Guptac8afc782013-11-25 18:45:02 +0000702
Soby Mathew58523c02015-06-08 12:32:50 +0100703 Argument : void
Achin Guptac8afc782013-11-25 18:45:02 +0000704 Return : unsigned long
705
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000706This function returns the base address of the normal memory stack that
Soby Mathew58523c02015-06-08 12:32:50 +0100707has been allocated for the current CPU. For BL images that only require a
708stack for the primary CPU, the UP version of the function is used. The size
709of the stack allocated to each CPU is specified by the platform defined
710constant `PLATFORM_STACK_SIZE`.
Achin Guptac8afc782013-11-25 18:45:02 +0000711
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000712Common implementations of this function for the UP and MP BL images are
713provided in [plat/common/aarch64/platform_up_stack.S] and
714[plat/common/aarch64/platform_mp_stack.S]
Achin Guptac8afc782013-11-25 18:45:02 +0000715
716
Achin Gupta4f6ad662013-10-25 09:08:21 +0100717### Function : plat_report_exception()
718
719 Argument : unsigned int
720 Return : void
721
722A platform may need to report various information about its status when an
723exception is taken, for example the current exception level, the CPU security
724state (secure/non-secure), the exception type, and so on. This function is
725called in the following circumstances:
726
727* In BL1, whenever an exception is taken.
728* In BL2, whenever an exception is taken.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100729
730The default implementation doesn't do anything, to avoid making assumptions
731about the way the platform displays its status information.
732
733This function receives the exception type as its argument. Possible values for
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +0000734exceptions types are listed in the [include/common/bl_common.h] header file.
735Note that these constants are not related to any architectural exception code;
736they are just an ARM Trusted Firmware convention.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100737
738
Soby Mathew24fb8382014-08-14 12:22:32 +0100739### Function : plat_reset_handler()
740
741 Argument : void
742 Return : void
743
744A platform may need to do additional initialization after reset. This function
745allows the platform to do the platform specific intializations. Platform
746specific errata workarounds could also be implemented here. The api should
Soby Mathew683f7882015-01-29 12:00:58 +0000747preserve the values of callee saved registers x19 to x29.
Soby Mathew24fb8382014-08-14 12:22:32 +0100748
Yatharth Kochar79a97b22014-11-20 18:09:41 +0000749The default implementation doesn't do anything. If a platform needs to override
Dan Handley4a75b842015-03-19 19:24:43 +0000750the default implementation, refer to the [Firmware Design] for general
Sandrine Bailleux452b7fa2015-05-27 17:14:22 +0100751guidelines.
Soby Mathew24fb8382014-08-14 12:22:32 +0100752
Soby Mathewadd40352014-08-14 12:49:05 +0100753### Function : plat_disable_acp()
754
755 Argument : void
756 Return : void
757
758This api allows a platform to disable the Accelerator Coherency Port (if
759present) during a cluster power down sequence. The default weak implementation
760doesn't do anything. Since this api is called during the power down sequence,
761it has restrictions for stack usage and it can use the registers x0 - x17 as
762scratch registers. It should preserve the value in x18 register as it is used
763by the caller to store the return address.
764
Juan Castillo40fc6cd2015-09-25 15:41:14 +0100765### Function : plat_error_handler()
766
767 Argument : int
768 Return : void
769
770This API is called when the generic code encounters an error situation from
771which it cannot continue. It allows the platform to perform error reporting or
772recovery actions (for example, reset the system). This function must not return.
773
774The parameter indicates the type of error using standard codes from `errno.h`.
775Possible errors reported by the generic code are:
776
777* `-EAUTH`: a certificate or image could not be authenticated (when Trusted
778 Board Boot is enabled)
779* `-ENOENT`: the requested image or certificate could not be found or an IO
780 error was detected
781* `-ENOMEM`: resources exhausted. Trusted Firmware does not use dynamic
782 memory, so this error is usually an indication of an incorrect array size
783
784The default implementation simply spins.
785
Soby Mathew24fb8382014-08-14 12:22:32 +0100786
Achin Gupta4f6ad662013-10-25 09:08:21 +01007873. Modifications specific to a Boot Loader stage
788-------------------------------------------------
789
7903.1 Boot Loader Stage 1 (BL1)
791-----------------------------
792
793BL1 implements the reset vector where execution starts from after a cold or
794warm boot. For each CPU, BL1 is responsible for the following tasks:
795
Vikram Kanigirie452cd82014-05-23 15:56:12 +01007961. Handling the reset as described in section 2.2
Achin Gupta4f6ad662013-10-25 09:08:21 +0100797
7982. In the case of a cold boot and the CPU being the primary CPU, ensuring that
799 only this CPU executes the remaining BL1 code, including loading and passing
800 control to the BL2 stage.
801
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +00008023. Identifying and starting the Firmware Update process (if required).
803
8044. Loading the BL2 image from non-volatile storage into secure memory at the
Achin Gupta4f6ad662013-10-25 09:08:21 +0100805 address specified by the platform defined constant `BL2_BASE`.
806
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +00008075. Populating a `meminfo` structure with the following information in memory,
Achin Gupta4f6ad662013-10-25 09:08:21 +0100808 accessible by BL2 immediately upon entry.
809
810 meminfo.total_base = Base address of secure RAM visible to BL2
811 meminfo.total_size = Size of secure RAM visible to BL2
812 meminfo.free_base = Base address of secure RAM available for
813 allocation to BL2
814 meminfo.free_size = Size of secure RAM available for allocation to BL2
815
816 BL1 places this `meminfo` structure at the beginning of the free memory
817 available for its use. Since BL1 cannot allocate memory dynamically at the
818 moment, its free memory will be available for BL2's use as-is. However, this
819 means that BL2 must read the `meminfo` structure before it starts using its
820 free memory (this is discussed in Section 3.2).
821
822 In future releases of the ARM Trusted Firmware it will be possible for
823 the platform to decide where it wants to place the `meminfo` structure for
824 BL2.
825
Sandrine Bailleux8f55dfb2014-06-24 14:02:34 +0100826 BL1 implements the `bl1_init_bl2_mem_layout()` function to populate the
Achin Gupta4f6ad662013-10-25 09:08:21 +0100827 BL2 `meminfo` structure. The platform may override this implementation, for
828 example if the platform wants to restrict the amount of memory visible to
829 BL2. Details of how to do this are given below.
830
831The following functions need to be implemented by the platform port to enable
832BL1 to perform the above tasks.
833
834
Dan Handley4a75b842015-03-19 19:24:43 +0000835### Function : bl1_early_platform_setup() [mandatory]
836
837 Argument : void
838 Return : void
839
840This function executes with the MMU and data caches disabled. It is only called
841by the primary CPU.
842
843In ARM standard platforms, this function initializes the console and enables
844snoop requests into the primary CPU's cluster.
845
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100846### Function : bl1_plat_arch_setup() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100847
848 Argument : void
849 Return : void
850
Achin Gupta4f6ad662013-10-25 09:08:21 +0100851This function performs any platform-specific and architectural setup that the
Dan Handley4a75b842015-03-19 19:24:43 +0000852platform requires. Platform-specific setup might include configuration of
853memory controllers and the interconnect.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100854
Dan Handley4a75b842015-03-19 19:24:43 +0000855In ARM standard platforms, this function enables the MMU.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100856
857This function helps fulfill requirement 2 above.
858
859
860### Function : bl1_platform_setup() [mandatory]
861
862 Argument : void
863 Return : void
864
865This function executes with the MMU and data caches enabled. It is responsible
866for performing any remaining platform-specific setup that can occur after the
867MMU and data cache have been enabled.
868
Dan Handley4a75b842015-03-19 19:24:43 +0000869In ARM standard platforms, this function initializes the storage abstraction
870layer used to load the next bootloader image.
Harry Liebeld265bd72014-01-31 19:04:10 +0000871
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +0000872This function helps fulfill requirement 4 above.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100873
874
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000875### Function : bl1_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100876
877 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000878 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100879
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000880This function should only be called on the cold boot path. It executes with the
881MMU and data caches enabled. The pointer returned by this function must point to
882a `meminfo` structure containing the extents and availability of secure RAM for
883the BL1 stage.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100884
885 meminfo.total_base = Base address of secure RAM visible to BL1
886 meminfo.total_size = Size of secure RAM visible to BL1
887 meminfo.free_base = Base address of secure RAM available for allocation
888 to BL1
889 meminfo.free_size = Size of secure RAM available for allocation to BL1
890
891This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
892populates a similar structure to tell BL2 the extents of memory available for
893its own use.
894
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +0000895This function helps fulfill requirements 4 and 5 above.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100896
897
Sandrine Bailleux8f55dfb2014-06-24 14:02:34 +0100898### Function : bl1_init_bl2_mem_layout() [optional]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100899
900 Argument : meminfo *, meminfo *, unsigned int, unsigned long
901 Return : void
902
Vikram Kanigirie452cd82014-05-23 15:56:12 +0100903BL1 needs to tell the next stage the amount of secure RAM available
904for it to use. This information is populated in a `meminfo`
Achin Gupta4f6ad662013-10-25 09:08:21 +0100905structure.
906
907Depending upon where BL2 has been loaded in secure RAM (determined by
908`BL2_BASE`), BL1 calculates the amount of free memory available for BL2 to use.
909BL1 also ensures that its data sections resident in secure RAM are not visible
Dan Handley4a75b842015-03-19 19:24:43 +0000910to BL2. An illustration of how this is done in ARM standard platforms is given
911in the **Memory layout on ARM development platforms** section in the
912[Firmware Design].
Achin Gupta4f6ad662013-10-25 09:08:21 +0100913
914
Juan Castilloe3f67122015-10-05 16:59:38 +0100915### Function : bl1_plat_prepare_exit() [optional]
916
Sandrine Bailleux862b5dc2015-11-10 15:01:57 +0000917 Argument : entry_point_info_t *
Juan Castilloe3f67122015-10-05 16:59:38 +0100918 Return : void
919
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +0000920This function is called prior to exiting BL1 in response to the
921`BL1_SMC_RUN_IMAGE` SMC request raised by BL2. It should be used to perform
922platform specific clean up or bookkeeping operations before transferring
923control to the next image. It receives the address of the `entry_point_info_t`
924structure passed from BL2. This function runs with MMU disabled.
925
926### Function : bl1_plat_set_ep_info() [optional]
927
928 Argument : unsigned int image_id, entry_point_info_t *ep_info
929 Return : void
930
931This function allows platforms to override `ep_info` for the given `image_id`.
932
933The default implementation just returns.
934
935### Function : bl1_plat_get_next_image_id() [optional]
936
937 Argument : void
938 Return : unsigned int
939
940This and the following function must be overridden to enable the FWU feature.
941
942BL1 calls this function after platform setup to identify the next image to be
943loaded and executed. If the platform returns `BL2_IMAGE_ID` then BL1 proceeds
944with the normal boot sequence, which loads and executes BL2. If the platform
945returns a different image id, BL1 assumes that Firmware Update is required.
946
947The default implementation always returns `BL2_IMAGE_ID`. The ARM development
948platforms override this function to detect if firmware update is required, and
949if so, return the first image in the firmware update process.
950
951### Function : bl1_plat_get_image_desc() [optional]
952
953 Argument : unsigned int image_id
954 Return : image_desc_t *
955
956BL1 calls this function to get the image descriptor information `image_desc_t`
957for the provided `image_id` from the platform.
958
959The default implementation always returns a common BL2 image descriptor. ARM
960standard platforms return an image descriptor corresponding to BL2 or one of
961the firmware update images defined in the Trusted Board Boot Requirements
962specification.
963
964### Function : bl1_plat_fwu_done() [optional]
965
966 Argument : unsigned int image_id, uintptr_t image_src,
967 unsigned int image_size
968 Return : void
969
970BL1 calls this function when the FWU process is complete. It must not return.
971The platform may override this function to take platform specific action, for
972example to initiate the normal boot flow.
973
974The default implementation spins forever.
975
976### Function : bl1_plat_mem_check() [mandatory]
977
978 Argument : uintptr_t mem_base, unsigned int mem_size,
979 unsigned int flags
980 Return : void
981
982BL1 calls this function while handling FWU copy and authenticate SMCs. The
983platform must ensure that the provided `mem_base` and `mem_size` are mapped into
984BL1, and that this memory corresponds to either a secure or non-secure memory
985region as indicated by the security state of the `flags` argument.
986
987The default implementation of this function asserts therefore platforms must
988override it when using the FWU feature.
Juan Castilloe3f67122015-10-05 16:59:38 +0100989
990
Achin Gupta4f6ad662013-10-25 09:08:21 +01009913.2 Boot Loader Stage 2 (BL2)
992-----------------------------
993
994The BL2 stage is executed only by the primary CPU, which is determined in BL1
995using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at
996`BL2_BASE`. BL2 executes in Secure EL1 and is responsible for:
997
Juan Castillof59821d2015-12-10 15:49:17 +00009981. (Optional) Loading the SCP_BL2 binary image (if present) from platform
999 provided non-volatile storage. To load the SCP_BL2 image, BL2 makes use of
1000 the `meminfo` returned by the `bl2_plat_get_scp_bl2_meminfo()` function.
1001 The platform also defines the address in memory where SCP_BL2 is loaded
1002 through the optional constant `SCP_BL2_BASE`. BL2 uses this information
1003 to determine if there is enough memory to load the SCP_BL2 image.
1004 Subsequent handling of the SCP_BL2 image is platform-specific and is
1005 implemented in the `bl2_plat_handle_scp_bl2()` function.
1006 If `SCP_BL2_BASE` is not defined then this step is not performed.
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001007
Juan Castillod1786372015-12-14 09:35:25 +000010082. Loading the BL31 binary image into secure RAM from non-volatile storage. To
1009 load the BL31 image, BL2 makes use of the `meminfo` structure passed to it
Harry Liebeld265bd72014-01-31 19:04:10 +00001010 by BL1. This structure allows BL2 to calculate how much secure RAM is
1011 available for its use. The platform also defines the address in secure RAM
Juan Castillod1786372015-12-14 09:35:25 +00001012 where BL31 is loaded through the constant `BL31_BASE`. BL2 uses this
1013 information to determine if there is enough memory to load the BL31 image.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001014
Juan Castillod1786372015-12-14 09:35:25 +000010153. (Optional) Loading the BL32 binary image (if present) from platform
1016 provided non-volatile storage. To load the BL32 image, BL2 makes use of
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001017 the `meminfo` returned by the `bl2_plat_get_bl32_meminfo()` function.
Juan Castillod1786372015-12-14 09:35:25 +00001018 The platform also defines the address in memory where BL32 is loaded
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001019 through the optional constant `BL32_BASE`. BL2 uses this information
Juan Castillod1786372015-12-14 09:35:25 +00001020 to determine if there is enough memory to load the BL32 image.
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001021 If `BL32_BASE` is not defined then this and the next step is not performed.
Achin Guptaa3050ed2014-02-19 17:52:35 +00001022
Juan Castillod1786372015-12-14 09:35:25 +000010234. (Optional) Arranging to pass control to the BL32 image (if present) that
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001024 has been pre-loaded at `BL32_BASE`. BL2 populates an `entry_point_info`
Dan Handley1151c822014-04-15 11:38:38 +01001025 structure in memory provided by the platform with information about how
Juan Castillod1786372015-12-14 09:35:25 +00001026 BL31 should pass control to the BL32 image.
Achin Guptaa3050ed2014-02-19 17:52:35 +00001027
Juan Castillod1786372015-12-14 09:35:25 +000010285. Loading the normal world BL33 binary image into non-secure DRAM from
1029 platform storage and arranging for BL31 to pass control to this image. This
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001030 address is determined using the `plat_get_ns_image_entrypoint()` function
1031 described below.
1032
10336. BL2 populates an `entry_point_info` structure in memory provided by the
Juan Castillod1786372015-12-14 09:35:25 +00001034 platform with information about how BL31 should pass control to the
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001035 other BL images.
1036
Achin Gupta4f6ad662013-10-25 09:08:21 +01001037The following functions must be implemented by the platform port to enable BL2
1038to perform the above tasks.
1039
1040
1041### Function : bl2_early_platform_setup() [mandatory]
1042
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001043 Argument : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +01001044 Return : void
1045
1046This function executes with the MMU and data caches disabled. It is only called
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001047by the primary CPU. The arguments to this function is the address of the
1048`meminfo` structure populated by BL1.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001049
1050The platform must copy the contents of the `meminfo` structure into a private
1051variable as the original memory may be subsequently overwritten by BL2. The
1052copied structure is made available to all BL2 code through the
Achin Guptae4d084e2014-02-19 17:18:23 +00001053`bl2_plat_sec_mem_layout()` function.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001054
Dan Handley4a75b842015-03-19 19:24:43 +00001055In ARM standard platforms, this function also initializes the storage
1056abstraction layer used to load further bootloader images. It is necessary to do
Juan Castillof59821d2015-12-10 15:49:17 +00001057this early on platforms with a SCP_BL2 image, since the later
1058`bl2_platform_setup` must be done after SCP_BL2 is loaded.
Dan Handley4a75b842015-03-19 19:24:43 +00001059
Achin Gupta4f6ad662013-10-25 09:08:21 +01001060
1061### Function : bl2_plat_arch_setup() [mandatory]
1062
1063 Argument : void
1064 Return : void
1065
1066This function executes with the MMU and data caches disabled. It is only called
1067by the primary CPU.
1068
1069The purpose of this function is to perform any architectural initialization
1070that varies across platforms, for example enabling the MMU (since the memory
1071map differs across platforms).
1072
1073
1074### Function : bl2_platform_setup() [mandatory]
1075
1076 Argument : void
1077 Return : void
1078
1079This function may execute with the MMU and data caches enabled if the platform
1080port does the necessary initialization in `bl2_plat_arch_setup()`. It is only
1081called by the primary CPU.
1082
Achin Guptae4d084e2014-02-19 17:18:23 +00001083The purpose of this function is to perform any platform initialization
Dan Handley4a75b842015-03-19 19:24:43 +00001084specific to BL2.
Harry Liebelce19cf12014-04-01 19:28:07 +01001085
Dan Handley4a75b842015-03-19 19:24:43 +00001086In ARM standard platforms, this function performs security setup, including
1087configuration of the TrustZone controller to allow non-secure masters access
1088to most of DRAM. Part of DRAM is reserved for secure world use.
Harry Liebeld265bd72014-01-31 19:04:10 +00001089
Achin Gupta4f6ad662013-10-25 09:08:21 +01001090
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +00001091### Function : bl2_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001092
1093 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +00001094 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +01001095
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +00001096This function should only be called on the cold boot path. It may execute with
1097the MMU and data caches enabled if the platform port does the necessary
1098initialization in `bl2_plat_arch_setup()`. It is only called by the primary CPU.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001099
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +00001100The purpose of this function is to return a pointer to a `meminfo` structure
1101populated with the extents of secure RAM available for BL2 to use. See
Achin Gupta4f6ad662013-10-25 09:08:21 +01001102`bl2_early_platform_setup()` above.
1103
1104
Juan Castillof59821d2015-12-10 15:49:17 +00001105### Function : bl2_plat_get_scp_bl2_meminfo() [mandatory]
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001106
1107 Argument : meminfo *
1108 Return : void
1109
1110This function is used to get the memory limits where BL2 can load the
Juan Castillof59821d2015-12-10 15:49:17 +00001111SCP_BL2 image. The meminfo provided by this is used by load_image() to
1112validate whether the SCP_BL2 image can be loaded within the given
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001113memory from the given base.
1114
1115
Juan Castillof59821d2015-12-10 15:49:17 +00001116### Function : bl2_plat_handle_scp_bl2() [mandatory]
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001117
1118 Argument : image_info *
1119 Return : int
1120
Juan Castillof59821d2015-12-10 15:49:17 +00001121This function is called after loading SCP_BL2 image and it is used to perform
1122any platform-specific actions required to handle the SCP firmware. Typically it
Sandrine Bailleux93d81d62014-06-24 14:19:36 +01001123transfers the image into SCP memory using a platform-specific protocol and waits
1124until SCP executes it and signals to the Application Processor (AP) for BL2
1125execution to continue.
1126
1127This function returns 0 on success, a negative error code otherwise.
1128
1129
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001130### Function : bl2_plat_get_bl31_params() [mandatory]
Harry Liebeld265bd72014-01-31 19:04:10 +00001131
1132 Argument : void
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001133 Return : bl31_params *
Harry Liebeld265bd72014-01-31 19:04:10 +00001134
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001135BL2 platform code needs to return a pointer to a `bl31_params` structure it
Juan Castillod1786372015-12-14 09:35:25 +00001136will use for passing information to BL31. The `bl31_params` structure carries
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001137the following information.
1138 - Header describing the version information for interpreting the bl31_param
1139 structure
Juan Castillod1786372015-12-14 09:35:25 +00001140 - Information about executing the BL33 image in the `bl33_ep_info` field
1141 - Information about executing the BL32 image in the `bl32_ep_info` field
1142 - Information about the type and extents of BL31 image in the
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001143 `bl31_image_info` field
Juan Castillod1786372015-12-14 09:35:25 +00001144 - Information about the type and extents of BL32 image in the
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001145 `bl32_image_info` field
Juan Castillod1786372015-12-14 09:35:25 +00001146 - Information about the type and extents of BL33 image in the
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001147 `bl33_image_info` field
1148
1149The memory pointed by this structure and its sub-structures should be
Juan Castillod1786372015-12-14 09:35:25 +00001150accessible from BL31 initialisation code. BL31 might choose to copy the
1151necessary content, or maintain the structures until BL33 is initialised.
Harry Liebeld265bd72014-01-31 19:04:10 +00001152
1153
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001154### Funtion : bl2_plat_get_bl31_ep_info() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001155
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001156 Argument : void
1157 Return : entry_point_info *
1158
1159BL2 platform code returns a pointer which is used to populate the entry point
Juan Castillod1786372015-12-14 09:35:25 +00001160information for BL31 entry point. The location pointed by it should be
1161accessible from BL1 while processing the synchronous exception to run to BL31.
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001162
Dan Handley4a75b842015-03-19 19:24:43 +00001163In ARM standard platforms this is allocated inside a bl2_to_bl31_params_mem
1164structure in BL2 memory.
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001165
1166
1167### Function : bl2_plat_set_bl31_ep_info() [mandatory]
1168
1169 Argument : image_info *, entry_point_info *
Achin Gupta4f6ad662013-10-25 09:08:21 +01001170 Return : void
1171
Juan Castillod1786372015-12-14 09:35:25 +00001172In the normal boot flow, this function is called after loading BL31 image and
Sandrine Bailleux4c117f62015-11-26 16:31:34 +00001173it can be used to overwrite the entry point set by loader and also set the
Juan Castillod1786372015-12-14 09:35:25 +00001174security state and SPSR which represents the entry point system state for BL31.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001175
Sandrine Bailleux4c117f62015-11-26 16:31:34 +00001176When booting an EL3 payload instead, this function is called after populating
1177its entry point address and can be used for the same purpose for the payload
1178image. It receives a null pointer as its first argument in this case.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001179
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001180### Function : bl2_plat_set_bl32_ep_info() [mandatory]
1181
1182 Argument : image_info *, entry_point_info *
1183 Return : void
1184
Juan Castillod1786372015-12-14 09:35:25 +00001185This function is called after loading BL32 image and it can be used to
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001186overwrite the entry point set by loader and also set the security state
Juan Castillod1786372015-12-14 09:35:25 +00001187and SPSR which represents the entry point system state for BL32.
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001188
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001189
1190### Function : bl2_plat_set_bl33_ep_info() [mandatory]
1191
1192 Argument : image_info *, entry_point_info *
1193 Return : void
1194
Juan Castillod1786372015-12-14 09:35:25 +00001195This function is called after loading BL33 image and it can be used to
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001196overwrite the entry point set by loader and also set the security state
Juan Castillod1786372015-12-14 09:35:25 +00001197and SPSR which represents the entry point system state for BL33.
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001198
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001199
1200### Function : bl2_plat_get_bl32_meminfo() [mandatory]
1201
1202 Argument : meminfo *
1203 Return : void
1204
1205This function is used to get the memory limits where BL2 can load the
Juan Castillod1786372015-12-14 09:35:25 +00001206BL32 image. The meminfo provided by this is used by load_image() to
1207validate whether the BL32 image can be loaded with in the given
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001208memory from the given base.
1209
1210### Function : bl2_plat_get_bl33_meminfo() [mandatory]
1211
1212 Argument : meminfo *
1213 Return : void
1214
1215This function is used to get the memory limits where BL2 can load the
Juan Castillod1786372015-12-14 09:35:25 +00001216BL33 image. The meminfo provided by this is used by load_image() to
1217validate whether the BL33 image can be loaded with in the given
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001218memory from the given base.
1219
1220### Function : bl2_plat_flush_bl31_params() [mandatory]
1221
1222 Argument : void
1223 Return : void
1224
1225Once BL2 has populated all the structures that needs to be read by BL1
Juan Castillod1786372015-12-14 09:35:25 +00001226and BL31 including the bl31_params structures and its sub-structures,
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001227the bl31_ep_info structure and any platform specific data. It flushes
1228all these data to the main memory so that it is available when we jump to
1229later Bootloader stages with MMU off
Achin Gupta4f6ad662013-10-25 09:08:21 +01001230
1231### Function : plat_get_ns_image_entrypoint() [mandatory]
1232
1233 Argument : void
1234 Return : unsigned long
1235
1236As previously described, BL2 is responsible for arranging for control to be
Juan Castillod1786372015-12-14 09:35:25 +00001237passed to a normal world BL image through BL31. This function returns the
1238entrypoint of that image, which BL31 uses to jump to it.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001239
Juan Castillod1786372015-12-14 09:35:25 +00001240BL2 is responsible for loading the normal world BL33 image (e.g. UEFI).
Achin Gupta4f6ad662013-10-25 09:08:21 +01001241
1242
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +000012433.3 FWU Boot Loader Stage 2 (BL2U)
1244----------------------------------
1245
1246The AP Firmware Updater Configuration, BL2U, is an optional part of the FWU
1247process and is executed only by the primary CPU. BL1 passes control to BL2U at
1248`BL2U_BASE`. BL2U executes in Secure-EL1 and is responsible for:
1249
12501. (Optional) Transfering the optional SCP_BL2U binary image from AP secure
1251 memory to SCP RAM. BL2U uses the SCP_BL2U `image_info` passed by BL1.
1252 `SCP_BL2U_BASE` defines the address in AP secure memory where SCP_BL2U
1253 should be copied from. Subsequent handling of the SCP_BL2U image is
1254 implemented by the platform specific `bl2u_plat_handle_scp_bl2u()` function.
1255 If `SCP_BL2U_BASE` is not defined then this step is not performed.
1256
12572. Any platform specific setup required to perform the FWU process. For
1258 example, ARM standard platforms initialize the TZC controller so that the
1259 normal world can access DDR memory.
1260
1261The following functions must be implemented by the platform port to enable
1262BL2U to perform the tasks mentioned above.
1263
1264### Function : bl2u_early_platform_setup() [mandatory]
1265
1266 Argument : meminfo *mem_info, void *plat_info
1267 Return : void
1268
1269This function executes with the MMU and data caches disabled. It is only
1270called by the primary CPU. The arguments to this function is the address
1271of the `meminfo` structure and platform specific info provided by BL1.
1272
1273The platform must copy the contents of the `mem_info` and `plat_info` into
1274private storage as the original memory may be subsequently overwritten by BL2U.
1275
1276On ARM CSS platforms `plat_info` is interpreted as an `image_info_t` structure,
1277to extract SCP_BL2U image information, which is then copied into a private
1278variable.
1279
1280### Function : bl2u_plat_arch_setup() [mandatory]
1281
1282 Argument : void
1283 Return : void
1284
1285This function executes with the MMU and data caches disabled. It is only
1286called by the primary CPU.
1287
1288The purpose of this function is to perform any architectural initialization
1289that varies across platforms, for example enabling the MMU (since the memory
1290map differs across platforms).
1291
1292### Function : bl2u_platform_setup() [mandatory]
1293
1294 Argument : void
1295 Return : void
1296
1297This function may execute with the MMU and data caches enabled if the platform
1298port does the necessary initialization in `bl2u_plat_arch_setup()`. It is only
1299called by the primary CPU.
1300
1301The purpose of this function is to perform any platform initialization
1302specific to BL2U.
1303
1304In ARM standard platforms, this function performs security setup, including
1305configuration of the TrustZone controller to allow non-secure masters access
1306to most of DRAM. Part of DRAM is reserved for secure world use.
1307
1308### Function : bl2u_plat_handle_scp_bl2u() [optional]
1309
1310 Argument : void
1311 Return : int
1312
1313This function is used to perform any platform-specific actions required to
1314handle the SCP firmware. Typically it transfers the image into SCP memory using
1315a platform-specific protocol and waits until SCP executes it and signals to the
1316Application Processor (AP) for BL2U execution to continue.
1317
1318This function returns 0 on success, a negative error code otherwise.
1319This function is included if SCP_BL2U_BASE is defined.
1320
1321
13223.4 Boot Loader Stage 3-1 (BL31)
Achin Gupta4f6ad662013-10-25 09:08:21 +01001323---------------------------------
1324
Juan Castillod1786372015-12-14 09:35:25 +00001325During cold boot, the BL31 stage is executed only by the primary CPU. This is
Achin Gupta4f6ad662013-10-25 09:08:21 +01001326determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes
Juan Castillod1786372015-12-14 09:35:25 +00001327control to BL31 at `BL31_BASE`. During warm boot, BL31 is executed by all
1328CPUs. BL31 executes at EL3 and is responsible for:
Achin Gupta4f6ad662013-10-25 09:08:21 +01001329
13301. Re-initializing all architectural and platform state. Although BL1 performs
Juan Castillod1786372015-12-14 09:35:25 +00001331 some of this initialization, BL31 remains resident in EL3 and must ensure
Achin Gupta4f6ad662013-10-25 09:08:21 +01001332 that EL3 architectural and platform state is completely initialized. It
1333 should make no assumptions about the system state when it receives control.
1334
13352. Passing control to a normal world BL image, pre-loaded at a platform-
Juan Castillod1786372015-12-14 09:35:25 +00001336 specific address by BL2. BL31 uses the `entry_point_info` structure that BL2
Achin Gupta4f6ad662013-10-25 09:08:21 +01001337 populated in memory to do this.
1338
Juan Castillod1786372015-12-14 09:35:25 +000013393. Providing runtime firmware services. Currently, BL31 only implements a
Achin Gupta4f6ad662013-10-25 09:08:21 +01001340 subset of the Power State Coordination Interface (PSCI) API as a runtime
1341 service. See Section 3.3 below for details of porting the PSCI
1342 implementation.
1343
Juan Castillod1786372015-12-14 09:35:25 +000013444. Optionally passing control to the BL32 image, pre-loaded at a platform-
1345 specific address by BL2. BL31 exports a set of apis that allow runtime
Achin Gupta35ca3512014-02-19 17:58:33 +00001346 services to specify the security state in which the next image should be
Juan Castillod1786372015-12-14 09:35:25 +00001347 executed and run the corresponding image. BL31 uses the `entry_point_info`
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001348 structure populated by BL2 to do this.
1349
Juan Castillod1786372015-12-14 09:35:25 +00001350If BL31 is a reset vector, It also needs to handle the reset as specified in
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001351section 2.2 before the tasks described above.
Achin Gupta35ca3512014-02-19 17:58:33 +00001352
Juan Castillod1786372015-12-14 09:35:25 +00001353The following functions must be implemented by the platform port to enable BL31
Achin Gupta4f6ad662013-10-25 09:08:21 +01001354to perform the above tasks.
1355
1356
1357### Function : bl31_early_platform_setup() [mandatory]
1358
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001359 Argument : bl31_params *, void *
Achin Gupta4f6ad662013-10-25 09:08:21 +01001360 Return : void
1361
1362This function executes with the MMU and data caches disabled. It is only called
1363by the primary CPU. The arguments to this function are:
1364
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001365* The address of the `bl31_params` structure populated by BL2.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001366* An opaque pointer that the platform may use as needed.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001367
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001368The platform can copy the contents of the `bl31_params` structure and its
1369sub-structures into private variables if the original memory may be
Juan Castillod1786372015-12-14 09:35:25 +00001370subsequently overwritten by BL31 and similarly the `void *` pointing
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001371to the platform data also needs to be saved.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001372
Dan Handley4a75b842015-03-19 19:24:43 +00001373In ARM standard platforms, BL2 passes a pointer to a `bl31_params` structure
Juan Castillod1786372015-12-14 09:35:25 +00001374in BL2 memory. BL31 copies the information in this pointer to internal data
Dan Handley4a75b842015-03-19 19:24:43 +00001375structures.
1376
Achin Gupta4f6ad662013-10-25 09:08:21 +01001377
1378### Function : bl31_plat_arch_setup() [mandatory]
1379
1380 Argument : void
1381 Return : void
1382
1383This function executes with the MMU and data caches disabled. It is only called
1384by the primary CPU.
1385
1386The purpose of this function is to perform any architectural initialization
1387that varies across platforms, for example enabling the MMU (since the memory
1388map differs across platforms).
1389
1390
1391### Function : bl31_platform_setup() [mandatory]
1392
1393 Argument : void
1394 Return : void
1395
1396This function may execute with the MMU and data caches enabled if the platform
1397port does the necessary initialization in `bl31_plat_arch_setup()`. It is only
1398called by the primary CPU.
1399
1400The purpose of this function is to complete platform initialization so that both
Juan Castillod1786372015-12-14 09:35:25 +00001401BL31 runtime services and normal world software can function correctly.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001402
Dan Handley4a75b842015-03-19 19:24:43 +00001403In ARM standard platforms, this function does the following:
Achin Gupta4f6ad662013-10-25 09:08:21 +01001404* Initializes the generic interrupt controller.
Sandrine Bailleux9e864902014-03-31 11:25:18 +01001405* Enables system-level implementation of the generic timer counter.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001406* Grants access to the system counter timer module
Dan Handley4a75b842015-03-19 19:24:43 +00001407* Initializes the power controller device
Achin Gupta4f6ad662013-10-25 09:08:21 +01001408* Detects the system topology.
1409
1410
Soby Mathew78e61612015-12-09 11:28:43 +00001411### Function : bl31_plat_runtime_setup() [optional]
1412
1413 Argument : void
1414 Return : void
1415
1416The purpose of this function is allow the platform to perform any BL31 runtime
1417setup just prior to BL31 exit during cold boot. The default weak
1418implementation of this function will invoke `console_uninit()` which will
1419suppress any BL31 runtime logs.
1420
Soby Mathew080225d2015-12-09 11:38:43 +00001421In ARM Standard platforms, this function will initialize the BL31 runtime
1422console which will cause all further BL31 logs to be output to the
1423runtime console.
1424
Soby Mathew78e61612015-12-09 11:28:43 +00001425
Achin Gupta4f6ad662013-10-25 09:08:21 +01001426### Function : bl31_get_next_image_info() [mandatory]
1427
Achin Gupta35ca3512014-02-19 17:58:33 +00001428 Argument : unsigned int
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001429 Return : entry_point_info *
Achin Gupta4f6ad662013-10-25 09:08:21 +01001430
1431This function may execute with the MMU and data caches enabled if the platform
1432port does the necessary initializations in `bl31_plat_arch_setup()`.
1433
1434This function is called by `bl31_main()` to retrieve information provided by
Juan Castillod1786372015-12-14 09:35:25 +00001435BL2 for the next image in the security state specified by the argument. BL31
Achin Gupta35ca3512014-02-19 17:58:33 +00001436uses this information to pass control to that image in the specified security
Vikram Kanigirie452cd82014-05-23 15:56:12 +01001437state. This function must return a pointer to the `entry_point_info` structure
Achin Gupta35ca3512014-02-19 17:58:33 +00001438(that was copied during `bl31_early_platform_setup()`) if the image exists. It
1439should return NULL otherwise.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001440
Dan Handley4a75b842015-03-19 19:24:43 +00001441### Function : plat_get_syscnt_freq() [mandatory]
1442
1443 Argument : void
1444 Return : uint64_t
1445
1446This function is used by the architecture setup code to retrieve the counter
1447frequency for the CPU's generic timer. This value will be programmed into the
1448`CNTFRQ_EL0` register. In ARM standard platforms, it returns the base frequency
1449of the system counter, which is retrieved from the first entry in the frequency
1450modes table.
1451
Achin Gupta4f6ad662013-10-25 09:08:21 +01001452
Vikram Kanigiri7173f5f2015-09-24 15:45:43 +01001453### #define : PLAT_PERCPU_BAKERY_LOCK_SIZE [optional]
Andrew Thoelkeee7b35c2015-09-10 11:39:36 +01001454
Vikram Kanigiri7173f5f2015-09-24 15:45:43 +01001455 When `USE_COHERENT_MEM = 0`, this constant defines the total memory (in
1456 bytes) aligned to the cache line boundary that should be allocated per-cpu to
1457 accommodate all the bakery locks.
1458
1459 If this constant is not defined when `USE_COHERENT_MEM = 0`, the linker
1460 calculates the size of the `bakery_lock` input section, aligns it to the
1461 nearest `CACHE_WRITEBACK_GRANULE`, multiplies it with `PLATFORM_CORE_COUNT`
1462 and stores the result in a linker symbol. This constant prevents a platform
1463 from relying on the linker and provide a more efficient mechanism for
1464 accessing per-cpu bakery lock information.
1465
1466 If this constant is defined and its value is not equal to the value
1467 calculated by the linker then a link time assertion is raised. A compile time
1468 assertion is raised if the value of the constant is not aligned to the cache
1469 line boundary.
Andrew Thoelkeee7b35c2015-09-10 11:39:36 +01001470
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +000014713.5 Power State Coordination Interface (in BL31)
Achin Gupta4f6ad662013-10-25 09:08:21 +01001472------------------------------------------------
1473
1474The ARM Trusted Firmware's implementation of the PSCI API is based around the
Soby Mathew58523c02015-06-08 12:32:50 +01001475concept of a _power domain_. A _power domain_ is a CPU or a logical group of
1476CPUs which share some state on which power management operations can be
1477performed as specified by [PSCI]. Each CPU in the system is assigned a cpu
1478index which is a unique number between `0` and `PLATFORM_CORE_COUNT - 1`.
Sandrine Bailleux1645d3e2015-12-17 13:58:58 +00001479The _power domains_ are arranged in a hierarchical tree structure and
Soby Mathew58523c02015-06-08 12:32:50 +01001480each _power domain_ can be identified in a system by the cpu index of any CPU
1481that is part of that domain and a _power domain level_. A processing element
1482(for example, a CPU) is at level 0. If the _power domain_ node above a CPU is
1483a logical grouping of CPUs that share some state, then level 1 is that group
1484of CPUs (for example, a cluster), and level 2 is a group of clusters
1485(for example, the system). More details on the power domain topology and its
1486organization can be found in [Power Domain Topology Design].
Achin Gupta4f6ad662013-10-25 09:08:21 +01001487
Juan Castillod1786372015-12-14 09:35:25 +00001488BL31's platform initialization code exports a pointer to the platform-specific
Achin Gupta4f6ad662013-10-25 09:08:21 +01001489power management operations required for the PSCI implementation to function
Soby Mathew58523c02015-06-08 12:32:50 +01001490correctly. This information is populated in the `plat_psci_ops` structure. The
1491PSCI implementation calls members of the `plat_psci_ops` structure for performing
1492power management operations on the power domains. For example, the target
1493CPU is specified by its `MPIDR` in a PSCI `CPU_ON` call. The `pwr_domain_on()`
1494handler (if present) is called for the CPU power domain.
1495
1496The `power-state` parameter of a PSCI `CPU_SUSPEND` call can be used to
1497describe composite power states specific to a platform. The PSCI implementation
1498defines a generic representation of the power-state parameter viz which is an
1499array of local power states where each index corresponds to a power domain
1500level. Each entry contains the local power state the power domain at that power
1501level could enter. It depends on the `validate_power_state()` handler to
1502convert the power-state parameter (possibly encoding a composite power state)
1503passed in a PSCI `CPU_SUSPEND` call to this representation.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001504
1505The following functions must be implemented to initialize PSCI functionality in
1506the ARM Trusted Firmware.
1507
1508
Soby Mathew58523c02015-06-08 12:32:50 +01001509### Function : plat_get_target_pwr_state() [optional]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001510
Soby Mathew58523c02015-06-08 12:32:50 +01001511 Argument : unsigned int, const plat_local_state_t *, unsigned int
1512 Return : plat_local_state_t
Achin Gupta4f6ad662013-10-25 09:08:21 +01001513
Soby Mathew58523c02015-06-08 12:32:50 +01001514The PSCI generic code uses this function to let the platform participate in
1515state coordination during a power management operation. The function is passed
1516a pointer to an array of platform specific local power state `states` (second
1517argument) which contains the requested power state for each CPU at a particular
1518power domain level `lvl` (first argument) within the power domain. The function
1519is expected to traverse this array of upto `ncpus` (third argument) and return
1520a coordinated target power state by the comparing all the requested power
1521states. The target power state should not be deeper than any of the requested
1522power states.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001523
Soby Mathew58523c02015-06-08 12:32:50 +01001524A weak definition of this API is provided by default wherein it assumes
1525that the platform assigns a local state value in order of increasing depth
1526of the power state i.e. for two power states X & Y, if X < Y
1527then X represents a shallower power state than Y. As a result, the
1528coordinated target local power state for a power domain will be the minimum
1529of the requested local power state values.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001530
1531
Soby Mathew58523c02015-06-08 12:32:50 +01001532### Function : plat_get_power_domain_tree_desc() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001533
Soby Mathew58523c02015-06-08 12:32:50 +01001534 Argument : void
1535 Return : const unsigned char *
Achin Gupta4f6ad662013-10-25 09:08:21 +01001536
Soby Mathew58523c02015-06-08 12:32:50 +01001537This function returns a pointer to the byte array containing the power domain
1538topology tree description. The format and method to construct this array are
Juan Castillod1786372015-12-14 09:35:25 +00001539described in [Power Domain Topology Design]. The BL31 PSCI initilization code
Soby Mathew58523c02015-06-08 12:32:50 +01001540requires this array to be described by the platform, either statically or
1541dynamically, to initialize the power domain topology tree. In case the array
1542is populated dynamically, then plat_core_pos_by_mpidr() and
1543plat_my_core_pos() should also be implemented suitably so that the topology
1544tree description matches the CPU indices returned by these APIs. These APIs
1545together form the platform interface for the PSCI topology framework.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001546
1547
Soby Mathew58523c02015-06-08 12:32:50 +01001548## Function : plat_setup_psci_ops() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001549
Soby Mathew58523c02015-06-08 12:32:50 +01001550 Argument : uintptr_t, const plat_psci_ops **
Achin Gupta4f6ad662013-10-25 09:08:21 +01001551 Return : int
1552
1553This function may execute with the MMU and data caches enabled if the platform
1554port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
1555called by the primary CPU.
1556
Soby Mathew58523c02015-06-08 12:32:50 +01001557This function is called by PSCI initialization code. Its purpose is to let
1558the platform layer know about the warm boot entrypoint through the
1559`sec_entrypoint` (first argument) and to export handler routines for
1560platform-specific psci power management actions by populating the passed
Juan Castillod1786372015-12-14 09:35:25 +00001561pointer with a pointer to BL31's private `plat_psci_ops` structure.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001562
1563A description of each member of this structure is given below. Please refer to
Dan Handley4a75b842015-03-19 19:24:43 +00001564the ARM FVP specific implementation of these handlers in
Soby Mathew58523c02015-06-08 12:32:50 +01001565[plat/arm/board/fvp/fvp_pm.c] as an example. For each PSCI function that the
1566platform wants to support, the associated operation or operations in this
1567structure must be provided and implemented (Refer section 4 of
1568[Firmware Design] for the PSCI API supported in Trusted Firmware). To disable
1569a PSCI function in a platform port, the operation should be removed from this
1570structure instead of providing an empty implementation.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001571
Soby Mathew58523c02015-06-08 12:32:50 +01001572#### plat_psci_ops.cpu_standby()
Achin Gupta4f6ad662013-10-25 09:08:21 +01001573
Soby Mathew58523c02015-06-08 12:32:50 +01001574Perform the platform-specific actions to enter the standby state for a cpu
1575indicated by the passed argument. This provides a fast path for CPU standby
1576wherein overheads of PSCI state management and lock acquistion is avoided.
1577For this handler to be invoked by the PSCI `CPU_SUSPEND` API implementation,
1578the suspend state type specified in the `power-state` parameter should be
1579STANDBY and the target power domain level specified should be the CPU. The
1580handler should put the CPU into a low power retention state (usually by
1581issuing a wfi instruction) and ensure that it can be woken up from that
1582state by a normal interrupt. The generic code expects the handler to succeed.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001583
Soby Mathew58523c02015-06-08 12:32:50 +01001584#### plat_psci_ops.pwr_domain_on()
Achin Gupta4f6ad662013-10-25 09:08:21 +01001585
Soby Mathew58523c02015-06-08 12:32:50 +01001586Perform the platform specific actions to power on a CPU, specified
1587by the `MPIDR` (first argument). The generic code expects the platform to
1588return PSCI_E_SUCCESS on success or PSCI_E_INTERN_FAIL for any failure.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001589
Soby Mathew58523c02015-06-08 12:32:50 +01001590#### plat_psci_ops.pwr_domain_off()
Achin Gupta4f6ad662013-10-25 09:08:21 +01001591
Soby Mathew58523c02015-06-08 12:32:50 +01001592Perform the platform specific actions to prepare to power off the calling CPU
1593and its higher parent power domain levels as indicated by the `target_state`
1594(first argument). It is called by the PSCI `CPU_OFF` API implementation.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001595
Soby Mathew58523c02015-06-08 12:32:50 +01001596The `target_state` encodes the platform coordinated target local power states
1597for the CPU power domain and its parent power domain levels. The handler
1598needs to perform power management operation corresponding to the local state
1599at each power level.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001600
Soby Mathew58523c02015-06-08 12:32:50 +01001601For this handler, the local power state for the CPU power domain will be a
1602power down state where as it could be either power down, retention or run state
1603for the higher power domain levels depending on the result of state
1604coordination. The generic code expects the handler to succeed.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001605
Soby Mathew58523c02015-06-08 12:32:50 +01001606#### plat_psci_ops.pwr_domain_suspend()
Achin Gupta4f6ad662013-10-25 09:08:21 +01001607
Soby Mathew58523c02015-06-08 12:32:50 +01001608Perform the platform specific actions to prepare to suspend the calling
1609CPU and its higher parent power domain levels as indicated by the
1610`target_state` (first argument). It is called by the PSCI `CPU_SUSPEND`
1611API implementation.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001612
Soby Mathew58523c02015-06-08 12:32:50 +01001613The `target_state` has a similar meaning as described in
1614the `pwr_domain_off()` operation. It encodes the platform coordinated
1615target local power states for the CPU power domain and its parent
1616power domain levels. The handler needs to perform power management operation
1617corresponding to the local state at each power level. The generic code
1618expects the handler to succeed.
1619
1620The difference between turning a power domain off versus suspending it
1621is that in the former case, the power domain is expected to re-initialize
1622its state when it is next powered on (see `pwr_domain_on_finish()`). In the
1623latter case, the power domain is expected to save enough state so that it can
Achin Gupta4f6ad662013-10-25 09:08:21 +01001624resume execution by restoring this state when its powered on (see
Soby Mathew58523c02015-06-08 12:32:50 +01001625`pwr_domain_suspend_finish()`).
Achin Gupta4f6ad662013-10-25 09:08:21 +01001626
Soby Mathew58523c02015-06-08 12:32:50 +01001627#### plat_psci_ops.pwr_domain_on_finish()
Achin Gupta4f6ad662013-10-25 09:08:21 +01001628
1629This function is called by the PSCI implementation after the calling CPU is
1630powered on and released from reset in response to an earlier PSCI `CPU_ON` call.
1631It performs the platform-specific setup required to initialize enough state for
1632this CPU to enter the normal world and also provide secure runtime firmware
1633services.
1634
Soby Mathew58523c02015-06-08 12:32:50 +01001635The `target_state` (first argument) is the prior state of the power domains
1636immediately before the CPU was turned on. It indicates which power domains
1637above the CPU might require initialization due to having previously been in
1638low power states. The generic code expects the handler to succeed.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001639
Soby Mathew58523c02015-06-08 12:32:50 +01001640#### plat_psci_ops.pwr_domain_suspend_finish()
Achin Gupta4f6ad662013-10-25 09:08:21 +01001641
1642This function is called by the PSCI implementation after the calling CPU is
1643powered on and released from reset in response to an asynchronous wakeup
1644event, for example a timer interrupt that was programmed by the CPU during the
Soby Mathewc0aff0e2014-12-17 14:47:57 +00001645`CPU_SUSPEND` call or `SYSTEM_SUSPEND` call. It performs the platform-specific
1646setup required to restore the saved state for this CPU to resume execution
1647in the normal world and also provide secure runtime firmware services.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001648
Soby Mathew58523c02015-06-08 12:32:50 +01001649The `target_state` (first argument) has a similar meaning as described in
1650the `pwr_domain_on_finish()` operation. The generic code expects the platform
1651to succeed.
Soby Mathew539dced2014-10-02 16:56:51 +01001652
Soby Mathew58523c02015-06-08 12:32:50 +01001653#### plat_psci_ops.validate_power_state()
Soby Mathew539dced2014-10-02 16:56:51 +01001654
1655This function is called by the PSCI implementation during the `CPU_SUSPEND`
Soby Mathew58523c02015-06-08 12:32:50 +01001656call to validate the `power_state` parameter of the PSCI API and if valid,
1657populate it in `req_state` (second argument) array as power domain level
1658specific local states. If the `power_state` is invalid, the platform must
1659return PSCI_E_INVALID_PARAMS as error, which is propagated back to the
1660normal world PSCI client.
Soby Mathew539dced2014-10-02 16:56:51 +01001661
Soby Mathew58523c02015-06-08 12:32:50 +01001662#### plat_psci_ops.validate_ns_entrypoint()
Soby Mathew539dced2014-10-02 16:56:51 +01001663
Soby Mathewc0aff0e2014-12-17 14:47:57 +00001664This function is called by the PSCI implementation during the `CPU_SUSPEND`,
1665`SYSTEM_SUSPEND` and `CPU_ON` calls to validate the non-secure `entry_point`
Soby Mathew58523c02015-06-08 12:32:50 +01001666parameter passed by the normal world. If the `entry_point` is invalid,
1667the platform must return PSCI_E_INVALID_ADDRESS as error, which is
Soby Mathewc0aff0e2014-12-17 14:47:57 +00001668propagated back to the normal world PSCI client.
1669
Soby Mathew58523c02015-06-08 12:32:50 +01001670#### plat_psci_ops.get_sys_suspend_power_state()
Soby Mathewc0aff0e2014-12-17 14:47:57 +00001671
1672This function is called by the PSCI implementation during the `SYSTEM_SUSPEND`
Soby Mathew58523c02015-06-08 12:32:50 +01001673call to get the `req_state` parameter from platform which encodes the power
1674domain level specific local states to suspend to system affinity level. The
1675`req_state` will be utilized to do the PSCI state coordination and
1676`pwr_domain_suspend()` will be invoked with the coordinated target state to
1677enter system suspend.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001678
Achin Gupta4f6ad662013-10-25 09:08:21 +01001679
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +000016803.6 Interrupt Management framework (in BL31)
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001681----------------------------------------------
Juan Castillod1786372015-12-14 09:35:25 +00001682BL31 implements an Interrupt Management Framework (IMF) to manage interrupts
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001683generated in either security state and targeted to EL1 or EL2 in the non-secure
1684state or EL3/S-EL1 in the secure state. The design of this framework is
1685described in the [IMF Design Guide]
1686
1687A platform should export the following APIs to support the IMF. The following
Dan Handley4a75b842015-03-19 19:24:43 +00001688text briefly describes each api and its implementation in ARM standard
1689platforms. The API implementation depends upon the type of interrupt controller
Soby Mathew81123e82015-11-23 14:01:21 +00001690present in the platform. ARM standard platform layer supports both [ARM Generic
1691Interrupt Controller version 2.0 (GICv2)][ARM GIC Architecture Specification 2.0]
1692and [3.0 (GICv3)][ARM GIC Architecture Specification 3.0]. Juno builds the ARM
1693Standard layer to use GICv2 and the FVP can be configured to use either GICv2 or
1694GICv3 depending on the build flag `FVP_USE_GIC_DRIVER` (See FVP platform
1695specific build options in [User Guide] for more details).
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001696
1697### Function : plat_interrupt_type_to_line() [mandatory]
1698
1699 Argument : uint32_t, uint32_t
1700 Return : uint32_t
1701
1702The ARM processor signals an interrupt exception either through the IRQ or FIQ
1703interrupt line. The specific line that is signaled depends on how the interrupt
1704controller (IC) reports different interrupt types from an execution context in
1705either security state. The IMF uses this API to determine which interrupt line
1706the platform IC uses to signal each type of interrupt supported by the framework
Soby Mathew81123e82015-11-23 14:01:21 +00001707from a given security state. This API must be invoked at EL3.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001708
1709The first parameter will be one of the `INTR_TYPE_*` values (see [IMF Design
1710Guide]) indicating the target type of the interrupt, the second parameter is the
1711security state of the originating execution context. The return result is the
1712bit position in the `SCR_EL3` register of the respective interrupt trap: IRQ=1,
1713FIQ=2.
1714
Soby Mathew81123e82015-11-23 14:01:21 +00001715In the case of ARM standard platforms using GICv2, S-EL1 interrupts are
1716configured as FIQs and Non-secure interrupts as IRQs from either security
1717state.
1718
1719In the case of ARM standard platforms using GICv3, the interrupt line to be
1720configured depends on the security state of the execution context when the
1721interrupt is signalled and are as follows:
1722* The S-EL1 interrupts are signaled as IRQ in S-EL0/1 context and as FIQ in
1723 NS-EL0/1/2 context.
1724* The Non secure interrupts are signaled as FIQ in S-EL0/1 context and as IRQ
1725 in the NS-EL0/1/2 context.
1726* The EL3 interrupts are signaled as FIQ in both S-EL0/1 and NS-EL0/1/2
1727 context.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001728
1729
1730### Function : plat_ic_get_pending_interrupt_type() [mandatory]
1731
1732 Argument : void
1733 Return : uint32_t
1734
1735This API returns the type of the highest priority pending interrupt at the
1736platform IC. The IMF uses the interrupt type to retrieve the corresponding
1737handler function. `INTR_TYPE_INVAL` is returned when there is no interrupt
1738pending. The valid interrupt types that can be returned are `INTR_TYPE_EL3`,
Soby Mathew81123e82015-11-23 14:01:21 +00001739`INTR_TYPE_S_EL1` and `INTR_TYPE_NS`. This API must be invoked at EL3.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001740
Soby Mathew81123e82015-11-23 14:01:21 +00001741In the case of ARM standard platforms using GICv2, the _Highest Priority
1742Pending Interrupt Register_ (`GICC_HPPIR`) is read to determine the id of
1743the pending interrupt. The type of interrupt depends upon the id value as
1744follows.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001745
17461. id < 1022 is reported as a S-EL1 interrupt
17472. id = 1022 is reported as a Non-secure interrupt.
17483. id = 1023 is reported as an invalid interrupt type.
1749
Soby Mathew81123e82015-11-23 14:01:21 +00001750In the case of ARM standard platforms using GICv3, the system register
1751`ICC_HPPIR0_EL1`, _Highest Priority Pending group 0 Interrupt Register_,
1752is read to determine the id of the pending interrupt. The type of interrupt
1753depends upon the id value as follows.
1754
17551. id = `PENDING_G1S_INTID` (1020) is reported as a S-EL1 interrupt
17562. id = `PENDING_G1NS_INTID` (1021) is reported as a Non-secure interrupt.
17573. id = `GIC_SPURIOUS_INTERRUPT` (1023) is reported as an invalid interrupt type.
17584. All other interrupt id's are reported as EL3 interrupt.
1759
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001760
1761### Function : plat_ic_get_pending_interrupt_id() [mandatory]
1762
1763 Argument : void
1764 Return : uint32_t
1765
1766This API returns the id of the highest priority pending interrupt at the
Sandrine Bailleux1645d3e2015-12-17 13:58:58 +00001767platform IC. `INTR_ID_UNAVAILABLE` is returned when there is no interrupt
Soby Mathew54718412015-10-27 10:01:06 +00001768pending.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001769
Soby Mathew81123e82015-11-23 14:01:21 +00001770In the case of ARM standard platforms using GICv2, the _Highest Priority
1771Pending Interrupt Register_ (`GICC_HPPIR`) is read to determine the id of the
1772pending interrupt. The id that is returned by API depends upon the value of
1773the id read from the interrupt controller as follows.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001774
17751. id < 1022. id is returned as is.
17762. id = 1022. The _Aliased Highest Priority Pending Interrupt Register_
Soby Mathew81123e82015-11-23 14:01:21 +00001777 (`GICC_AHPPIR`) is read to determine the id of the non-secure interrupt.
1778 This id is returned by the API.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +010017793. id = 1023. `INTR_ID_UNAVAILABLE` is returned.
1780
Soby Mathew81123e82015-11-23 14:01:21 +00001781In the case of ARM standard platforms using GICv3, if the API is invoked from
1782EL3, the system register `ICC_HPPIR0_EL1`, _Highest Priority Pending Interrupt
1783group 0 Register_, is read to determine the id of the pending interrupt. The id
1784that is returned by API depends upon the value of the id read from the
1785interrupt controller as follows.
1786
17871. id < `PENDING_G1S_INTID` (1020). id is returned as is.
17882. id = `PENDING_G1S_INTID` (1020) or `PENDING_G1NS_INTID` (1021). The system
1789 register `ICC_HPPIR1_EL1`, _Highest Priority Pending Interrupt group 1
1790 Register_ is read to determine the id of the group 1 interrupt. This id
1791 is returned by the API as long as it is a valid interrupt id
17923. If the id is any of the special interrupt identifiers,
1793 `INTR_ID_UNAVAILABLE` is returned.
1794
1795When the API invoked from S-EL1 for GICv3 systems, the id read from system
1796register `ICC_HPPIR1_EL1`, _Highest Priority Pending group 1 Interrupt
1797Register_, is returned if is not equal to GIC_SPURIOUS_INTERRUPT (1023) else
1798`INTR_ID_UNAVAILABLE` is returned.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001799
1800### Function : plat_ic_acknowledge_interrupt() [mandatory]
1801
1802 Argument : void
1803 Return : uint32_t
1804
1805This API is used by the CPU to indicate to the platform IC that processing of
1806the highest pending interrupt has begun. It should return the id of the
1807interrupt which is being processed.
1808
Soby Mathew81123e82015-11-23 14:01:21 +00001809This function in ARM standard platforms using GICv2, reads the _Interrupt
1810Acknowledge Register_ (`GICC_IAR`). This changes the state of the highest
1811priority pending interrupt from pending to active in the interrupt controller.
1812It returns the value read from the `GICC_IAR`. This value is the id of the
1813interrupt whose state has been changed.
1814
1815In the case of ARM standard platforms using GICv3, if the API is invoked
1816from EL3, the function reads the system register `ICC_IAR0_EL1`, _Interrupt
1817Acknowledge Register group 0_. If the API is invoked from S-EL1, the function
1818reads the system register `ICC_IAR1_EL1`, _Interrupt Acknowledge Register
1819group 1_. The read changes the state of the highest pending interrupt from
1820pending to active in the interrupt controller. The value read is returned
1821and is the id of the interrupt whose state has been changed.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001822
1823The TSP uses this API to start processing of the secure physical timer
1824interrupt.
1825
1826
1827### Function : plat_ic_end_of_interrupt() [mandatory]
1828
1829 Argument : uint32_t
1830 Return : void
1831
1832This API is used by the CPU to indicate to the platform IC that processing of
1833the interrupt corresponding to the id (passed as the parameter) has
1834finished. The id should be the same as the id returned by the
1835`plat_ic_acknowledge_interrupt()` API.
1836
Dan Handley4a75b842015-03-19 19:24:43 +00001837ARM standard platforms write the id to the _End of Interrupt Register_
Soby Mathew81123e82015-11-23 14:01:21 +00001838(`GICC_EOIR`) in case of GICv2, and to `ICC_EOIR0_EL1` or `ICC_EOIR1_EL1`
1839system register in case of GICv3 depending on where the API is invoked from,
1840EL3 or S-EL1. This deactivates the corresponding interrupt in the interrupt
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001841controller.
1842
1843The TSP uses this API to finish processing of the secure physical timer
1844interrupt.
1845
1846
1847### Function : plat_ic_get_interrupt_type() [mandatory]
1848
1849 Argument : uint32_t
1850 Return : uint32_t
1851
1852This API returns the type of the interrupt id passed as the parameter.
1853`INTR_TYPE_INVAL` is returned if the id is invalid. If the id is valid, a valid
1854interrupt type (one of `INTR_TYPE_EL3`, `INTR_TYPE_S_EL1` and `INTR_TYPE_NS`) is
1855returned depending upon how the interrupt has been configured by the platform
Soby Mathew81123e82015-11-23 14:01:21 +00001856IC. This API must be invoked at EL3.
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001857
Soby Mathew81123e82015-11-23 14:01:21 +00001858ARM standard platforms using GICv2 configures S-EL1 interrupts as Group0 interrupts
1859and Non-secure interrupts as Group1 interrupts. It reads the group value
1860corresponding to the interrupt id from the relevant _Interrupt Group Register_
1861(`GICD_IGROUPRn`). It uses the group value to determine the type of interrupt.
1862
1863In the case of ARM standard platforms using GICv3, both the _Interrupt Group
1864Register_ (`GICD_IGROUPRn`) and _Interrupt Group Modifier Register_
1865(`GICD_IGRPMODRn`) is read to figure out whether the interrupt is configured
1866as Group 0 secure interrupt, Group 1 secure interrupt or Group 1 NS interrupt.
Dan Handley4a75b842015-03-19 19:24:43 +00001867
Achin Guptaa4fa3cb2014-06-02 22:27:36 +01001868
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +000018693.7 Crash Reporting mechanism (in BL31)
Soby Mathewc67b09b2014-07-14 16:57:23 +01001870----------------------------------------------
Juan Castillod1786372015-12-14 09:35:25 +00001871BL31 implements a crash reporting mechanism which prints the various registers
Sandrine Bailleux44804252014-08-06 11:27:23 +01001872of the CPU to enable quick crash analysis and debugging. It requires that a
1873console is designated as the crash console by the platform which will be used to
1874print the register dump.
Soby Mathewc67b09b2014-07-14 16:57:23 +01001875
Sandrine Bailleux44804252014-08-06 11:27:23 +01001876The following functions must be implemented by the platform if it wants crash
Juan Castillod1786372015-12-14 09:35:25 +00001877reporting mechanism in BL31. The functions are implemented in assembly so that
Sandrine Bailleux44804252014-08-06 11:27:23 +01001878they can be invoked without a C Runtime stack.
Soby Mathewc67b09b2014-07-14 16:57:23 +01001879
1880### Function : plat_crash_console_init
1881
1882 Argument : void
1883 Return : int
1884
Sandrine Bailleux44804252014-08-06 11:27:23 +01001885This API is used by the crash reporting mechanism to initialize the crash
Juan Castillo9400b402015-11-26 14:52:15 +00001886console. It must only use the general purpose registers x0 to x4 to do the
Sandrine Bailleux44804252014-08-06 11:27:23 +01001887initialization and returns 1 on success.
Soby Mathewc67b09b2014-07-14 16:57:23 +01001888
Soby Mathewc67b09b2014-07-14 16:57:23 +01001889### Function : plat_crash_console_putc
1890
1891 Argument : int
1892 Return : int
1893
1894This API is used by the crash reporting mechanism to print a character on the
Juan Castillo9400b402015-11-26 14:52:15 +00001895designated crash console. It must only use general purpose registers x1 and
Soby Mathewc67b09b2014-07-14 16:57:23 +01001896x2 to do its work. The parameter and the return value are in general purpose
1897register x0.
1898
Soby Mathew27713fb2014-09-08 17:51:01 +010018994. Build flags
1900---------------
1901
Soby Mathew58523c02015-06-08 12:32:50 +01001902* **ENABLE_PLAT_COMPAT**
1903 All the platforms ports conforming to this API specification should define
1904 the build flag `ENABLE_PLAT_COMPAT` to 0 as the compatibility layer should
1905 be disabled. For more details on compatibility layer, refer
1906 [Migration Guide].
1907
Soby Mathew27713fb2014-09-08 17:51:01 +01001908There are some build flags which can be defined by the platform to control
1909inclusion or exclusion of certain BL stages from the FIP image. These flags
1910need to be defined in the platform makefile which will get included by the
1911build system.
1912
Soby Mathew27713fb2014-09-08 17:51:01 +01001913* **NEED_BL33**
1914 By default, this flag is defined `yes` by the build system and `BL33`
1915 build option should be supplied as a build option. The platform has the option
Juan Castillod1786372015-12-14 09:35:25 +00001916 of excluding the BL33 image in the `fip` image by defining this flag to
Soby Mathew27713fb2014-09-08 17:51:01 +01001917 `no`.
1918
19195. C Library
Harry Liebela960f282013-12-12 16:03:44 +00001920-------------
1921
1922To avoid subtle toolchain behavioral dependencies, the header files provided
1923by the compiler are not used. The software is built with the `-nostdinc` flag
1924to ensure no headers are included from the toolchain inadvertently. Instead the
1925required headers are included in the ARM Trusted Firmware source tree. The
1926library only contains those C library definitions required by the local
1927implementation. If more functionality is required, the needed library functions
1928will need to be added to the local implementation.
1929
1930Versions of [FreeBSD] headers can be found in `include/stdlib`. Some of these
1931headers have been cut down in order to simplify the implementation. In order to
1932minimize changes to the header files, the [FreeBSD] layout has been maintained.
1933The generic C library definitions can be found in `include/stdlib` with more
1934system and machine specific declarations in `include/stdlib/sys` and
1935`include/stdlib/machine`.
1936
1937The local C library implementations can be found in `lib/stdlib`. In order to
1938extend the C library these files may need to be modified. It is recommended to
1939use a release version of [FreeBSD] as a starting point.
1940
1941The C library header files in the [FreeBSD] source tree are located in the
1942`include` and `sys/sys` directories. [FreeBSD] machine specific definitions
1943can be found in the `sys/<machine-type>` directories. These files define things
1944like 'the size of a pointer' and 'the range of an integer'. Since an AArch64
1945port for [FreeBSD] does not yet exist, the machine specific definitions are
1946based on existing machine types with similar properties (for example SPARC64).
1947
1948Where possible, C library function implementations were taken from [FreeBSD]
1949as found in the `lib/libc` directory.
1950
1951A copy of the [FreeBSD] sources can be downloaded with `git`.
1952
1953 git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0
1954
1955
Soby Mathew27713fb2014-09-08 17:51:01 +010019566. Storage abstraction layer
Harry Liebeld265bd72014-01-31 19:04:10 +00001957-----------------------------
1958
1959In order to improve platform independence and portability an storage abstraction
1960layer is used to load data from non-volatile platform storage.
1961
1962Each platform should register devices and their drivers via the Storage layer.
1963These drivers then need to be initialized by bootloader phases as
1964required in their respective `blx_platform_setup()` functions. Currently
1965storage access is only required by BL1 and BL2 phases. The `load_image()`
1966function uses the storage layer to access non-volatile platform storage.
1967
Dan Handley4a75b842015-03-19 19:24:43 +00001968It is mandatory to implement at least one storage driver. For the ARM
1969development platforms the Firmware Image Package (FIP) driver is provided as
1970the default means to load data from storage (see the "Firmware Image Package"
1971section in the [User Guide]). The storage layer is described in the header file
1972`include/drivers/io/io_storage.h`. The implementation of the common library
Sandrine Bailleux121f2ae2015-01-28 10:11:48 +00001973is in `drivers/io/io_storage.c` and the driver files are located in
1974`drivers/io/`.
Harry Liebeld265bd72014-01-31 19:04:10 +00001975
1976Each IO driver must provide `io_dev_*` structures, as described in
1977`drivers/io/io_driver.h`. These are returned via a mandatory registration
1978function that is called on platform initialization. The semi-hosting driver
1979implementation in `io_semihosting.c` can be used as an example.
1980
1981The Storage layer provides mechanisms to initialize storage devices before
1982IO operations are called. The basic operations supported by the layer
1983include `open()`, `close()`, `read()`, `write()`, `size()` and `seek()`.
1984Drivers do not have to implement all operations, but each platform must
1985provide at least one driver for a device capable of supporting generic
1986operations such as loading a bootloader image.
1987
1988The current implementation only allows for known images to be loaded by the
Juan Castillo16948ae2015-04-13 17:36:19 +01001989firmware. These images are specified by using their identifiers, as defined in
1990[include/plat/common/platform_def.h] (or a separate header file included from
1991there). The platform layer (`plat_get_image_source()`) then returns a reference
1992to a device and a driver-specific `spec` which will be understood by the driver
1993to allow access to the image data.
Harry Liebeld265bd72014-01-31 19:04:10 +00001994
1995The layer is designed in such a way that is it possible to chain drivers with
1996other drivers. For example, file-system drivers may be implemented on top of
1997physical block devices, both represented by IO devices with corresponding
1998drivers. In such a case, the file-system "binding" with the block device may
1999be deferred until the file-system device is initialised.
2000
2001The abstraction currently depends on structures being statically allocated
2002by the drivers and callers, as the system does not yet provide a means of
2003dynamically allocating memory. This may also have the affect of limiting the
2004amount of open resources per driver.
2005
2006
Achin Gupta4f6ad662013-10-25 09:08:21 +01002007- - - - - - - - - - - - - - - - - - - - - - - - - -
2008
Dan Handley4a75b842015-03-19 19:24:43 +00002009_Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
Achin Gupta4f6ad662013-10-25 09:08:21 +01002010
2011
Yuping Luo6b140412016-01-15 11:17:27 +08002012[ARM GIC Architecture Specification 2.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
2013[ARM GIC Architecture Specification 3.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html
Soby Mathew81123e82015-11-23 14:01:21 +00002014[IMF Design Guide]: interrupt-framework-design.md
2015[User Guide]: user-guide.md
2016[FreeBSD]: http://www.freebsd.org
2017[Firmware Design]: firmware-design.md
2018[Power Domain Topology Design]: psci-pd-tree.md
2019[PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
2020[Migration Guide]: platform-migration-guide.md
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +00002021[Firmware Update]: firmware-update.md
Achin Gupta4f6ad662013-10-25 09:08:21 +01002022
Andrew Thoelke2bf28e62014-03-20 10:48:23 +00002023[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S
2024[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S
Dan Handley4a75b842015-03-19 19:24:43 +00002025[plat/arm/board/fvp/fvp_pm.c]: ../plat/arm/board/fvp/fvp_pm.c
Yatharth Kochar84a5d6d2015-10-27 15:55:18 +00002026[include/common/bl_common.h]: ../include/common/bl_common.h
Dan Handley4a75b842015-03-19 19:24:43 +00002027[include/plat/arm/common/arm_def.h]: ../include/plat/arm/common/arm_def.h
2028[include/plat/common/common_def.h]: ../include/plat/common/common_def.h
Dan Handleyb68954c2014-05-29 12:30:24 +01002029[include/plat/common/platform.h]: ../include/plat/common/platform.h
Dan Handley4a75b842015-03-19 19:24:43 +00002030[include/plat/arm/common/plat_arm.h]: ../include/plat/arm/common/plat_arm.h]