blob: 37c2bf91ffef954faddef391e6d7883287890350 [file] [log] [blame] [view]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001ARM Trusted Firmware Porting Guide
2==================================
3
4Contents
5--------
6
71. Introduction
82. Common Modifications
9 * Common mandatory modifications
10 * Common optional modifications
113. Boot Loader stage specific modifications
12 * Boot Loader stage 1 (BL1)
13 * Boot Loader stage 2 (BL2)
14 * Boot Loader stage 3-1 (BL3-1)
15 * PSCI implementation (in BL3-1)
Harry Liebeld265bd72014-01-31 19:04:10 +0000164. C Library
175. Storage abstraction layer
Achin Gupta4f6ad662013-10-25 09:08:21 +010018
19- - - - - - - - - - - - - - - - - -
20
211. Introduction
22----------------
23
24Porting the ARM Trusted Firmware to a new platform involves making some
25mandatory and optional modifications for both the cold and warm boot paths.
26Modifications consist of:
27
28* Implementing a platform-specific function or variable,
29* Setting up the execution context in a certain way, or
30* Defining certain constants (for example #defines).
31
32The firmware provides a default implementation of variables and functions to
33fulfill the optional requirements. These implementations are all weakly defined;
34they are provided to ease the porting effort. Each platform port can override
35them with its own implementation if the default implementation is inadequate.
36
37Some modifications are common to all Boot Loader (BL) stages. Section 2
38discusses these in detail. The subsequent sections discuss the remaining
39modifications for each BL stage in detail.
40
41This document should be read in conjunction with the ARM Trusted Firmware
42[User Guide].
43
44
452. Common modifications
46------------------------
47
48This section covers the modifications that should be made by the platform for
49each BL stage to correctly port the firmware stack. They are categorized as
50either mandatory or optional.
51
52
532.1 Common mandatory modifications
54----------------------------------
55A platform port must enable the Memory Management Unit (MMU) with identity
56mapped page tables, and enable both the instruction and data caches for each BL
57stage. In the ARM FVP port, each BL stage configures the MMU in its platform-
58specific architecture setup function, for example `blX_plat_arch_setup()`.
59
60Each platform must allocate a block of identity mapped secure memory with
61Device-nGnRE attributes aligned to page boundary (4K) for each BL stage. This
62memory is identified by the section name `tzfw_coherent_mem` so that its
63possible for the firmware to place variables in it using the following C code
64directive:
65
66 __attribute__ ((section("tzfw_coherent_mem")))
67
68Or alternatively the following assembler code directive:
69
70 .section tzfw_coherent_mem
71
72The `tzfw_coherent_mem` section is used to allocate any data structures that are
73accessed both when a CPU is executing with its MMU and caches enabled, and when
74it's running with its MMU and caches disabled. Examples are given below.
75
76The following variables, functions and constants must be defined by the platform
77for the firmware to work correctly.
78
79
80### File : platform.h [mandatory]
81
82Each platform must export a header file of this name with the following
83constants defined. In the ARM FVP port, this file is found in
Andrew Thoelke2bf28e62014-03-20 10:48:23 +000084[plat/fvp/platform.h].
Achin Gupta4f6ad662013-10-25 09:08:21 +010085
James Morrisseyba3155b2013-10-29 10:56:46 +000086* **#define : PLATFORM_LINKER_FORMAT**
Achin Gupta4f6ad662013-10-25 09:08:21 +010087
88 Defines the linker format used by the platform, for example
89 `elf64-littleaarch64` used by the FVP.
90
James Morrisseyba3155b2013-10-29 10:56:46 +000091* **#define : PLATFORM_LINKER_ARCH**
Achin Gupta4f6ad662013-10-25 09:08:21 +010092
93 Defines the processor architecture for the linker by the platform, for
94 example `aarch64` used by the FVP.
95
James Morrisseyba3155b2013-10-29 10:56:46 +000096* **#define : PLATFORM_STACK_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +010097
98 Defines the normal stack memory available to each CPU. This constant is used
Andrew Thoelke2bf28e62014-03-20 10:48:23 +000099 by [plat/common/aarch64/platform_mp_stack.S] and
100 [plat/common/aarch64/platform_up_stack.S].
101
102* **#define : PCPU_DV_MEM_STACK_SIZE**
103
104 Defines the coherent stack memory available to each CPU. This constant is used
105 by [plat/common/aarch64/platform_mp_stack.S] and
106 [plat/common/aarch64/platform_up_stack.S].
Achin Gupta4f6ad662013-10-25 09:08:21 +0100107
James Morrisseyba3155b2013-10-29 10:56:46 +0000108* **#define : FIRMWARE_WELCOME_STR**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100109
110 Defines the character string printed by BL1 upon entry into the `bl1_main()`
111 function.
112
James Morrisseyba3155b2013-10-29 10:56:46 +0000113* **#define : BL2_IMAGE_NAME**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100114
115 Name of the BL2 binary image on the host file-system. This name is used by
Harry Liebeld265bd72014-01-31 19:04:10 +0000116 BL1 to load BL2 into secure memory from non-volatile storage.
117
118* **#define : BL31_IMAGE_NAME**
119
120 Name of the BL3-1 binary image on the host file-system. This name is used by
121 BL2 to load BL3-1 into secure memory from platform storage.
122
123* **#define : BL33_IMAGE_NAME**
124
125 Name of the BL3-3 binary image on the host file-system. This name is used by
126 BL2 to load BL3-3 into non-secure memory from platform storage.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100127
James Morrisseyba3155b2013-10-29 10:56:46 +0000128* **#define : PLATFORM_CACHE_LINE_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100129
130 Defines the size (in bytes) of the largest cache line across all the cache
131 levels in the platform.
132
James Morrisseyba3155b2013-10-29 10:56:46 +0000133* **#define : PLATFORM_CLUSTER_COUNT**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100134
135 Defines the total number of clusters implemented by the platform in the
136 system.
137
James Morrisseyba3155b2013-10-29 10:56:46 +0000138* **#define : PLATFORM_CORE_COUNT**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100139
140 Defines the total number of CPUs implemented by the platform across all
141 clusters in the system.
142
James Morrisseyba3155b2013-10-29 10:56:46 +0000143* **#define : PLATFORM_MAX_CPUS_PER_CLUSTER**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100144
145 Defines the maximum number of CPUs that can be implemented within a cluster
146 on the platform.
147
James Morrisseyba3155b2013-10-29 10:56:46 +0000148* **#define : PRIMARY_CPU**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100149
150 Defines the `MPIDR` of the primary CPU on the platform. This value is used
151 after a cold boot to distinguish between primary and secondary CPUs.
152
James Morrisseyba3155b2013-10-29 10:56:46 +0000153* **#define : TZROM_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100154
155 Defines the base address of secure ROM on the platform, where the BL1 binary
156 is loaded. This constant is used by the linker scripts to ensure that the
157 BL1 image fits into the available memory.
158
James Morrisseyba3155b2013-10-29 10:56:46 +0000159* **#define : TZROM_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100160
161 Defines the size of secure ROM on the platform. This constant is used by the
162 linker scripts to ensure that the BL1 image fits into the available memory.
163
James Morrisseyba3155b2013-10-29 10:56:46 +0000164* **#define : TZRAM_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100165
166 Defines the base address of the secure RAM on platform, where the data
167 section of the BL1 binary is loaded. The BL2 and BL3-1 images are also
168 loaded in this secure RAM region. This constant is used by the linker
169 scripts to ensure that the BL1 data section and BL2/BL3-1 binary images fit
170 into the available memory.
171
James Morrisseyba3155b2013-10-29 10:56:46 +0000172* **#define : TZRAM_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100173
174 Defines the size of the secure RAM on the platform. This constant is used by
175 the linker scripts to ensure that the BL1 data section and BL2/BL3-1 binary
176 images fit into the available memory.
177
James Morrisseyba3155b2013-10-29 10:56:46 +0000178* **#define : SYS_CNTCTL_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100179
180 Defines the base address of the `CNTCTLBase` frame of the memory mapped
181 counter and timer in the system level implementation of the generic timer.
182
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100183* **#define : BL1_RO_BASE**
184
185 Defines the base address in secure ROM where BL1 originally lives. Must be
186 aligned on a page-size boundary.
187
188* **#define : BL1_RO_LIMIT**
189
190 Defines the maximum address in secure ROM that BL1's actual content (i.e.
191 excluding any data section allocated at runtime) can occupy.
192
193* **#define : BL1_RW_BASE**
194
195 Defines the base address in secure RAM where BL1's read-write data will live
196 at runtime. Must be aligned on a page-size boundary.
197
198* **#define : BL1_RW_LIMIT**
199
200 Defines the maximum address in secure RAM that BL1's read-write data can
201 occupy at runtime.
202
James Morrisseyba3155b2013-10-29 10:56:46 +0000203* **#define : BL2_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100204
205 Defines the base address in secure RAM where BL1 loads the BL2 binary image.
Sandrine Bailleuxcd29b0a2013-11-27 10:32:17 +0000206 Must be aligned on a page-size boundary.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100207
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100208* **#define : BL2_LIMIT**
209
210 Defines the maximum address in secure RAM that the BL2 image can occupy.
211
James Morrisseyba3155b2013-10-29 10:56:46 +0000212* **#define : BL31_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100213
214 Defines the base address in secure RAM where BL2 loads the BL3-1 binary
Sandrine Bailleuxcd29b0a2013-11-27 10:32:17 +0000215 image. Must be aligned on a page-size boundary.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100216
Sandrine Bailleux638363e2014-05-21 17:08:26 +0100217* **#define : BL31_LIMIT**
218
219 Defines the maximum address in secure RAM that the BL3-1 image can occupy.
220
Harry Liebeld265bd72014-01-31 19:04:10 +0000221* **#define : NS_IMAGE_OFFSET**
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100222
Harry Liebeld265bd72014-01-31 19:04:10 +0000223 Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary
224 image. Must be aligned on a page-size boundary.
225
Sandrine Bailleux2467f702014-05-20 17:22:24 +0100226If the BL3-2 image is supported by the platform, the following constants must
227be defined as well:
228
229* **#define : TSP_SEC_MEM_BASE**
230
231 Defines the base address of the secure memory used by the BL3-2 image on the
232 platform.
233
234* **#define : TSP_SEC_MEM_SIZE**
235
236 Defines the size of the secure memory used by the BL3-2 image on the
237 platform.
238
239* **#define : BL32_BASE**
240
241 Defines the base address in secure memory where BL2 loads the BL3-2 binary
242 image. Must be inside the secure memory identified by `TSP_SEC_MEM_BASE` and
243 `TSP_SEC_MEM_SIZE` constants. Must also be aligned on a page-size boundary.
244
245* **#define : BL32_LIMIT**
246
247 Defines the maximum address that the BL3-2 image can occupy. Must be inside
248 the secure memory identified by `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE`
249 constants.
250
251
Soby Mathewa43d4312014-04-07 15:28:55 +0100252### File : platform_macros.S [mandatory]
253
254Each platform must export a file of this name with the following
255macro defined. In the ARM FVP port, this file is found in
256[plat/fvp/include/platform_macros.S].
257
258* **Macro : plat_print_gic_regs**
259
260 This macro allows the crash reporting routine to print GIC registers
261 in case of an unhandled IRQ or FIQ in BL3-1. This aids in debugging and
262 this macro can be defined to be empty in case GIC register reporting is
263 not desired.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100264
265### Other mandatory modifications
266
James Morrisseyba3155b2013-10-29 10:56:46 +0000267The following mandatory modifications may be implemented in any file
Achin Gupta4f6ad662013-10-25 09:08:21 +0100268the implementer chooses. In the ARM FVP port, they are implemented in
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000269[plat/fvp/aarch64/plat_common.c].
Achin Gupta4f6ad662013-10-25 09:08:21 +0100270
Sandrine Bailleux9e864902014-03-31 11:25:18 +0100271* **Function : uint64_t plat_get_syscnt_freq(void)**
272
273 This function is used by the architecture setup code to retrieve the
274 counter frequency for the CPU's generic timer. This value will be
275 programmed into the `CNTFRQ_EL0` register.
276 In the ARM FVP port, it returns the base frequency of the system counter,
277 which is retrieved from the first entry in the frequency modes table.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100278
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000279
Achin Gupta4f6ad662013-10-25 09:08:21 +01002802.2 Common optional modifications
281---------------------------------
282
283The following are helper functions implemented by the firmware that perform
284common platform-specific tasks. A platform may choose to override these
285definitions.
286
287
288### Function : platform_get_core_pos()
289
290 Argument : unsigned long
291 Return : int
292
293A platform may need to convert the `MPIDR` of a CPU to an absolute number, which
294can be used as a CPU-specific linear index into blocks of memory (for example
295while allocating per-CPU stacks). This routine contains a simple mechanism
296to perform this conversion, using the assumption that each cluster contains a
297maximum of 4 CPUs:
298
299 linear index = cpu_id + (cluster_id * 4)
300
301 cpu_id = 8-bit value in MPIDR at affinity level 0
302 cluster_id = 8-bit value in MPIDR at affinity level 1
303
304
305### Function : platform_set_coherent_stack()
306
307 Argument : unsigned long
308 Return : void
309
310A platform may need stack memory that is coherent with main memory to perform
311certain operations like:
312
313* Turning the MMU on, or
314* Flushing caches prior to powering down a CPU or cluster.
315
316Each BL stage allocates this coherent stack memory for each CPU in the
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000317`tzfw_coherent_mem` section.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100318
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000319This function sets the current stack pointer to the coherent stack that
320has been allocated for the CPU specified by MPIDR. For BL images that only
321require a stack for the primary CPU the parameter is ignored. The size of
322the stack allocated to each CPU is specified by the platform defined constant
Achin Gupta4f6ad662013-10-25 09:08:21 +0100323`PCPU_DV_MEM_STACK_SIZE`.
324
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000325Common implementations of this function for the UP and MP BL images are
326provided in [plat/common/aarch64/platform_up_stack.S] and
327[plat/common/aarch64/platform_mp_stack.S]
328
Achin Gupta4f6ad662013-10-25 09:08:21 +0100329
330### Function : platform_is_primary_cpu()
331
332 Argument : unsigned long
333 Return : unsigned int
334
335This function identifies a CPU by its `MPIDR`, which is passed as the argument,
336to determine whether this CPU is the primary CPU or a secondary CPU. A return
337value of zero indicates that the CPU is not the primary CPU, while a non-zero
338return value indicates that the CPU is the primary CPU.
339
340
341### Function : platform_set_stack()
342
343 Argument : unsigned long
344 Return : void
345
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000346This function sets the current stack pointer to the normal memory stack that
347has been allocated for the CPU specificed by MPIDR. For BL images that only
348require a stack for the primary CPU the parameter is ignored. The size of
349the stack allocated to each CPU is specified by the platform defined constant
350`PLATFORM_STACK_SIZE`.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100351
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000352Common implementations of this function for the UP and MP BL images are
353provided in [plat/common/aarch64/platform_up_stack.S] and
354[plat/common/aarch64/platform_mp_stack.S]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100355
356
Achin Guptac8afc782013-11-25 18:45:02 +0000357### Function : platform_get_stack()
358
359 Argument : unsigned long
360 Return : unsigned long
361
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000362This function returns the base address of the normal memory stack that
363has been allocated for the CPU specificed by MPIDR. For BL images that only
364require a stack for the primary CPU the parameter is ignored. The size of
365the stack allocated to each CPU is specified by the platform defined constant
366`PLATFORM_STACK_SIZE`.
Achin Guptac8afc782013-11-25 18:45:02 +0000367
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000368Common implementations of this function for the UP and MP BL images are
369provided in [plat/common/aarch64/platform_up_stack.S] and
370[plat/common/aarch64/platform_mp_stack.S]
Achin Guptac8afc782013-11-25 18:45:02 +0000371
372
Achin Gupta4f6ad662013-10-25 09:08:21 +0100373### Function : plat_report_exception()
374
375 Argument : unsigned int
376 Return : void
377
378A platform may need to report various information about its status when an
379exception is taken, for example the current exception level, the CPU security
380state (secure/non-secure), the exception type, and so on. This function is
381called in the following circumstances:
382
383* In BL1, whenever an exception is taken.
384* In BL2, whenever an exception is taken.
385* In BL3-1, whenever an asynchronous exception or a synchronous exception
386 other than an SMC32/SMC64 exception is taken.
387
388The default implementation doesn't do anything, to avoid making assumptions
389about the way the platform displays its status information.
390
391This function receives the exception type as its argument. Possible values for
Andrew Thoelke2bf28e62014-03-20 10:48:23 +0000392exceptions types are listed in the [include/runtime_svc.h] header file. Note
Achin Gupta4f6ad662013-10-25 09:08:21 +0100393that these constants are not related to any architectural exception code; they
394are just an ARM Trusted Firmware convention.
395
396
3973. Modifications specific to a Boot Loader stage
398-------------------------------------------------
399
4003.1 Boot Loader Stage 1 (BL1)
401-----------------------------
402
403BL1 implements the reset vector where execution starts from after a cold or
404warm boot. For each CPU, BL1 is responsible for the following tasks:
405
4061. Distinguishing between a cold boot and a warm boot.
407
4082. In the case of a cold boot and the CPU being the primary CPU, ensuring that
409 only this CPU executes the remaining BL1 code, including loading and passing
410 control to the BL2 stage.
411
4123. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
413 the CPU is placed in a platform-specific state until the primary CPU
414 performs the necessary steps to remove it from this state.
415
4164. In the case of a warm boot, ensuring that the CPU jumps to a platform-
417 specific address in the BL3-1 image in the same processor mode as it was
418 when released from reset.
419
Harry Liebeld265bd72014-01-31 19:04:10 +00004205. Loading the BL2 image from non-volatile storage into secure memory at the
Achin Gupta4f6ad662013-10-25 09:08:21 +0100421 address specified by the platform defined constant `BL2_BASE`.
422
4236. Populating a `meminfo` structure with the following information in memory,
424 accessible by BL2 immediately upon entry.
425
426 meminfo.total_base = Base address of secure RAM visible to BL2
427 meminfo.total_size = Size of secure RAM visible to BL2
428 meminfo.free_base = Base address of secure RAM available for
429 allocation to BL2
430 meminfo.free_size = Size of secure RAM available for allocation to BL2
431
432 BL1 places this `meminfo` structure at the beginning of the free memory
433 available for its use. Since BL1 cannot allocate memory dynamically at the
434 moment, its free memory will be available for BL2's use as-is. However, this
435 means that BL2 must read the `meminfo` structure before it starts using its
436 free memory (this is discussed in Section 3.2).
437
438 In future releases of the ARM Trusted Firmware it will be possible for
439 the platform to decide where it wants to place the `meminfo` structure for
440 BL2.
441
442 BL1 implements the `init_bl2_mem_layout()` function to populate the
443 BL2 `meminfo` structure. The platform may override this implementation, for
444 example if the platform wants to restrict the amount of memory visible to
445 BL2. Details of how to do this are given below.
446
447The following functions need to be implemented by the platform port to enable
448BL1 to perform the above tasks.
449
450
451### Function : platform_get_entrypoint() [mandatory]
452
453 Argument : unsigned long
454 Return : unsigned int
455
456This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The CPU
457is identified by its `MPIDR`, which is passed as the argument. The function is
458responsible for distinguishing between a warm and cold reset using platform-
459specific means. If it's a warm reset then it returns the entrypoint into the
460BL3-1 image that the CPU must jump to. If it's a cold reset then this function
461must return zero.
462
463This function is also responsible for implementing a platform-specific mechanism
464to handle the condition where the CPU has been warm reset but there is no
465entrypoint to jump to.
466
467This function does not follow the Procedure Call Standard used by the
468Application Binary Interface for the ARM 64-bit architecture. The caller should
469not assume that callee saved registers are preserved across a call to this
470function.
471
472This function fulfills requirement 1 listed above.
473
474
475### Function : plat_secondary_cold_boot_setup() [mandatory]
476
477 Argument : void
478 Return : void
479
480This function is called with the MMU and data caches disabled. It is responsible
481for placing the executing secondary CPU in a platform-specific state until the
482primary CPU performs the necessary actions to bring it out of that state and
483allow entry into the OS.
484
485In the ARM FVP port, each secondary CPU powers itself off. The primary CPU is
486responsible for powering up the secondary CPU when normal world software
487requires them.
488
489This function fulfills requirement 3 above.
490
491
492### Function : platform_cold_boot_init() [mandatory]
493
494 Argument : unsigned long
495 Return : unsigned int
496
497This function executes with the MMU and data caches disabled. It is only called
498by the primary CPU. The argument to this function is the address of the
499`bl1_main()` routine where the generic BL1-specific actions are performed.
500This function performs any platform-specific and architectural setup that the
501platform requires to make execution of `bl1_main()` possible.
502
503The platform must enable the MMU with identity mapped page tables and enable
504caches by setting the `SCTLR.I` and `SCTLR.C` bits.
505
506Platform-specific setup might include configuration of memory controllers,
507configuration of the interconnect to allow the cluster to service cache snoop
508requests from another cluster, zeroing of the ZI section, and so on.
509
510In the ARM FVP port, this function enables CCI snoops into the cluster that the
511primary CPU is part of. It also enables the MMU and initializes the ZI section
512in the BL1 image through the use of linker defined symbols.
513
514This function helps fulfill requirement 2 above.
515
516
517### Function : bl1_platform_setup() [mandatory]
518
519 Argument : void
520 Return : void
521
522This function executes with the MMU and data caches enabled. It is responsible
523for performing any remaining platform-specific setup that can occur after the
524MMU and data cache have been enabled.
525
Harry Liebeld265bd72014-01-31 19:04:10 +0000526This function is also responsible for initializing the storage abstraction layer
527which is used to load further bootloader images.
528
Achin Gupta4f6ad662013-10-25 09:08:21 +0100529This function helps fulfill requirement 5 above.
530
531
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000532### Function : bl1_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100533
534 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000535 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100536
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000537This function should only be called on the cold boot path. It executes with the
538MMU and data caches enabled. The pointer returned by this function must point to
539a `meminfo` structure containing the extents and availability of secure RAM for
540the BL1 stage.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100541
542 meminfo.total_base = Base address of secure RAM visible to BL1
543 meminfo.total_size = Size of secure RAM visible to BL1
544 meminfo.free_base = Base address of secure RAM available for allocation
545 to BL1
546 meminfo.free_size = Size of secure RAM available for allocation to BL1
547
548This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
549populates a similar structure to tell BL2 the extents of memory available for
550its own use.
551
552This function helps fulfill requirement 5 above.
553
554
555### Function : init_bl2_mem_layout() [optional]
556
557 Argument : meminfo *, meminfo *, unsigned int, unsigned long
558 Return : void
559
560Each BL stage needs to tell the next stage the amount of secure RAM available
561for it to use. For example, as part of handing control to BL2, BL1 informs BL2
562of the extents of secure RAM available for BL2 to use. BL2 must do the same when
563passing control to BL3-1. This information is populated in a `meminfo`
564structure.
565
566Depending upon where BL2 has been loaded in secure RAM (determined by
567`BL2_BASE`), BL1 calculates the amount of free memory available for BL2 to use.
568BL1 also ensures that its data sections resident in secure RAM are not visible
569to BL2. An illustration of how this is done in the ARM FVP port is given in the
570[User Guide], in the Section "Memory layout on Base FVP".
571
572
5733.2 Boot Loader Stage 2 (BL2)
574-----------------------------
575
576The BL2 stage is executed only by the primary CPU, which is determined in BL1
577using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at
578`BL2_BASE`. BL2 executes in Secure EL1 and is responsible for:
579
Harry Liebeld265bd72014-01-31 19:04:10 +00005801. Loading the BL3-1 binary image into secure RAM from non-volatile storage. To
581 load the BL3-1 image, BL2 makes use of the `meminfo` structure passed to it
582 by BL1. This structure allows BL2 to calculate how much secure RAM is
583 available for its use. The platform also defines the address in secure RAM
584 where BL3-1 is loaded through the constant `BL31_BASE`. BL2 uses this
585 information to determine if there is enough memory to load the BL3-1 image.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100586
Harry Liebeld265bd72014-01-31 19:04:10 +00005872. Loading the normal world BL3-3 binary image into non-secure DRAM from
588 platform storage and arranging for BL3-1 to pass control to this image. This
589 address is determined using the `plat_get_ns_image_entrypoint()` function
590 described below.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100591
592 BL2 populates an `el_change_info` structure in memory provided by the
593 platform with information about how BL3-1 should pass control to the normal
594 world BL image.
595
5963. Populating a `meminfo` structure with the following information in
597 memory that is accessible by BL3-1 immediately upon entry.
598
599 meminfo.total_base = Base address of secure RAM visible to BL3-1
600 meminfo.total_size = Size of secure RAM visible to BL3-1
601 meminfo.free_base = Base address of secure RAM available for allocation
602 to BL3-1
603 meminfo.free_size = Size of secure RAM available for allocation to
604 BL3-1
605
Achin Guptae4d084e2014-02-19 17:18:23 +0000606 BL2 populates this information in the `bl31_meminfo` field of the pointer
607 returned by the `bl2_get_bl31_args_ptr() function. BL2 implements the
Achin Gupta4f6ad662013-10-25 09:08:21 +0100608 `init_bl31_mem_layout()` function to populate the BL3-1 meminfo structure
609 described above. The platform may override this implementation, for example
610 if the platform wants to restrict the amount of memory visible to BL3-1.
611 Details of this function are given below.
612
Achin Guptaa3050ed2014-02-19 17:52:35 +00006134. Loading the BL3-2 binary image (if present) in platform provided memory
614 using semi-hosting. To load the BL3-2 image, BL2 makes use of the
615 `bl32_meminfo` field in the `bl31_args` structure to which a pointer is
616 returned by the `bl2_get_bl31_args_ptr()` function. The platform also
617 defines the address in memory where BL3-2 is loaded through the constant
618 `BL32_BASE`. BL2 uses this information to determine if there is enough
619 memory to load the BL3-2 image.
620
6215. Arranging to pass control to the BL3-2 image (if present) that has been
622 pre-loaded at `BL32_BASE`. BL2 populates an `el_change_info` structure
623 in memory provided by the platform with information about how BL3-1 should
624 pass control to the BL3-2 image. This structure follows the
625 `el_change_info` structure populated for the normal world BL image in 2.
626 above.
627
6286. Populating a `meminfo` structure with the following information in
629 memory that is accessible by BL3-1 immediately upon entry.
630
631 meminfo.total_base = Base address of memory visible to BL3-2
632 meminfo.total_size = Size of memory visible to BL3-2
633 meminfo.free_base = Base address of memory available for allocation
634 to BL3-2
635 meminfo.free_size = Size of memory available for allocation to
636 BL3-2
637
638 BL2 populates this information in the `bl32_meminfo` field of the pointer
639 returned by the `bl2_get_bl31_args_ptr() function.
640
Achin Gupta4f6ad662013-10-25 09:08:21 +0100641The following functions must be implemented by the platform port to enable BL2
642to perform the above tasks.
643
644
645### Function : bl2_early_platform_setup() [mandatory]
646
647 Argument : meminfo *, void *
648 Return : void
649
650This function executes with the MMU and data caches disabled. It is only called
651by the primary CPU. The arguments to this function are:
652
653* The address of the `meminfo` structure populated by BL1
654* An opaque pointer that the platform may use as needed.
655
656The platform must copy the contents of the `meminfo` structure into a private
657variable as the original memory may be subsequently overwritten by BL2. The
658copied structure is made available to all BL2 code through the
Achin Guptae4d084e2014-02-19 17:18:23 +0000659`bl2_plat_sec_mem_layout()` function.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100660
661
662### Function : bl2_plat_arch_setup() [mandatory]
663
664 Argument : void
665 Return : void
666
667This function executes with the MMU and data caches disabled. It is only called
668by the primary CPU.
669
670The purpose of this function is to perform any architectural initialization
671that varies across platforms, for example enabling the MMU (since the memory
672map differs across platforms).
673
674
675### Function : bl2_platform_setup() [mandatory]
676
677 Argument : void
678 Return : void
679
680This function may execute with the MMU and data caches enabled if the platform
681port does the necessary initialization in `bl2_plat_arch_setup()`. It is only
682called by the primary CPU.
683
Achin Guptae4d084e2014-02-19 17:18:23 +0000684The purpose of this function is to perform any platform initialization
685specific to BL2. For example on the ARM FVP port this function initialises a
686internal pointer (`bl2_to_bl31_args`) to a `bl31_args` which will be used by
687BL2 to pass information to BL3_1. The pointer is initialized to the base
688address of Secure DRAM (`0x06000000`).
Achin Gupta4f6ad662013-10-25 09:08:21 +0100689
Achin Guptaa3050ed2014-02-19 17:52:35 +0000690The ARM FVP port also populates the `bl32_meminfo` field in the `bl31_args`
691structure pointed to by `bl2_to_bl31_args` with the extents of memory available
692for use by the BL3-2 image. The memory is allocated in the Secure DRAM from the
Dan Handley57de6d72014-02-27 19:46:37 +0000693address defined by the constant `BL32_BASE`. The ARM FVP port currently loads
694the BL3-2 image at the Secure DRAM address `0x6002000`.
Achin Guptaa3050ed2014-02-19 17:52:35 +0000695
Achin Guptae4d084e2014-02-19 17:18:23 +0000696The non-secure memory extents used for loading BL3-3 are also initialized in
697this function. This information is accessible in the `bl33_meminfo` field in
698the `bl31_args` structure pointed to by `bl2_to_bl31_args`.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100699
Harry Liebelce19cf12014-04-01 19:28:07 +0100700Platform security components are configured if required. For the Base FVP the
Andrew Thoelke84dbf6f2014-05-09 15:36:13 +0100701TZC-400 TrustZone controller is configured to only grant non-secure access
702to DRAM. This avoids aliasing between secure and non-secure accesses in the
703TLB and cache - secure execution states can use the NS attributes in the
704MMU translation tables to access the DRAM.
Harry Liebelce19cf12014-04-01 19:28:07 +0100705
Harry Liebeld265bd72014-01-31 19:04:10 +0000706This function is also responsible for initializing the storage abstraction layer
707which is used to load further bootloader images.
708
Achin Gupta4f6ad662013-10-25 09:08:21 +0100709
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000710### Function : bl2_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100711
712 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000713 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100714
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000715This function should only be called on the cold boot path. It may execute with
716the MMU and data caches enabled if the platform port does the necessary
717initialization in `bl2_plat_arch_setup()`. It is only called by the primary CPU.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100718
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000719The purpose of this function is to return a pointer to a `meminfo` structure
720populated with the extents of secure RAM available for BL2 to use. See
Achin Gupta4f6ad662013-10-25 09:08:21 +0100721`bl2_early_platform_setup()` above.
722
723
Achin Guptae4d084e2014-02-19 17:18:23 +0000724### Function : bl2_get_bl31_args_ptr() [mandatory]
Harry Liebeld265bd72014-01-31 19:04:10 +0000725
726 Argument : void
Achin Guptae4d084e2014-02-19 17:18:23 +0000727 Return : bl31_args *
Harry Liebeld265bd72014-01-31 19:04:10 +0000728
Achin Guptae4d084e2014-02-19 17:18:23 +0000729BL2 platform code needs to return a pointer to a `bl31_args` structure it will
730use for passing information to BL3-1. The `bl31_args` structure carries the
731following information. This information is used by the `bl2_main()` function to
732load the BL3-2 (if present) and BL3-3 images.
733 - Extents of memory available to the BL3-1 image in the `bl31_meminfo` field
734 - Extents of memory available to the BL3-2 image in the `bl32_meminfo` field
735 - Extents of memory available to the BL3-3 image in the `bl33_meminfo` field
736 - Information about executing the BL3-3 image in the `bl33_image_info` field
737 - Information about executing the BL3-2 image in the `bl32_image_info` field
Harry Liebeld265bd72014-01-31 19:04:10 +0000738
739
Achin Gupta4f6ad662013-10-25 09:08:21 +0100740### Function : init_bl31_mem_layout() [optional]
741
742 Argument : meminfo *, meminfo *, unsigned int
743 Return : void
744
745Each BL stage needs to tell the next stage the amount of secure RAM that is
746available for it to use. For example, as part of handing control to BL2, BL1
747must inform BL2 about the extents of secure RAM that is available for BL2 to
748use. BL2 must do the same when passing control to BL3-1. This information is
749populated in a `meminfo` structure.
750
751Depending upon where BL3-1 has been loaded in secure RAM (determined by
752`BL31_BASE`), BL2 calculates the amount of free memory available for BL3-1 to
753use. BL2 also ensures that BL3-1 is able reclaim memory occupied by BL2. This
754is done because BL2 never executes again after passing control to BL3-1.
755An illustration of how this is done in the ARM FVP port is given in the
756[User Guide], in the section "Memory layout on Base FVP".
757
758
759### Function : plat_get_ns_image_entrypoint() [mandatory]
760
761 Argument : void
762 Return : unsigned long
763
764As previously described, BL2 is responsible for arranging for control to be
765passed to a normal world BL image through BL3-1. This function returns the
766entrypoint of that image, which BL3-1 uses to jump to it.
767
Harry Liebeld265bd72014-01-31 19:04:10 +0000768BL2 is responsible for loading the normal world BL3-3 image (e.g. UEFI).
Achin Gupta4f6ad662013-10-25 09:08:21 +0100769
770
7713.2 Boot Loader Stage 3-1 (BL3-1)
772---------------------------------
773
774During cold boot, the BL3-1 stage is executed only by the primary CPU. This is
775determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes
776control to BL3-1 at `BL31_BASE`. During warm boot, BL3-1 is executed by all
777CPUs. BL3-1 executes at EL3 and is responsible for:
778
7791. Re-initializing all architectural and platform state. Although BL1 performs
780 some of this initialization, BL3-1 remains resident in EL3 and must ensure
781 that EL3 architectural and platform state is completely initialized. It
782 should make no assumptions about the system state when it receives control.
783
7842. Passing control to a normal world BL image, pre-loaded at a platform-
785 specific address by BL2. BL3-1 uses the `el_change_info` structure that BL2
786 populated in memory to do this.
787
7883. Providing runtime firmware services. Currently, BL3-1 only implements a
789 subset of the Power State Coordination Interface (PSCI) API as a runtime
790 service. See Section 3.3 below for details of porting the PSCI
791 implementation.
792
Achin Gupta35ca3512014-02-19 17:58:33 +00007934. Optionally passing control to the BL3-2 image, pre-loaded at a platform-
794 specific address by BL2. BL3-1 exports a set of apis that allow runtime
795 services to specify the security state in which the next image should be
796 executed and run the corresponding image. BL3-1 uses the `el_change_info`
797 and `meminfo` structure populated by BL2 to do this.
798
Achin Gupta4f6ad662013-10-25 09:08:21 +0100799The following functions must be implemented by the platform port to enable BL3-1
800to perform the above tasks.
801
802
803### Function : bl31_early_platform_setup() [mandatory]
804
805 Argument : meminfo *, void *, unsigned long
806 Return : void
807
808This function executes with the MMU and data caches disabled. It is only called
809by the primary CPU. The arguments to this function are:
810
811* The address of the `meminfo` structure populated by BL2.
812* An opaque pointer that the platform may use as needed.
813* The `MPIDR` of the primary CPU.
814
Achin Guptae4d084e2014-02-19 17:18:23 +0000815The platform can copy the contents of the `meminfo` structure into a private
816variable if the original memory may be subsequently overwritten by BL3-1. The
817reference to this structure is made available to all BL3-1 code through the
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000818`bl31_plat_sec_mem_layout()` function.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100819
Achin Guptae4d084e2014-02-19 17:18:23 +0000820On the ARM FVP port, BL2 passes a pointer to a `bl31_args` structure populated
821in the secure DRAM at address `0x6000000` in the opaque pointer mentioned
822earlier. BL3-1 does not copy this information to internal data structures as it
823guarantees that the secure DRAM memory will not be overwritten. It maintains an
824internal reference to this information in the `bl2_to_bl31_args` variable.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100825
826### Function : bl31_plat_arch_setup() [mandatory]
827
828 Argument : void
829 Return : void
830
831This function executes with the MMU and data caches disabled. It is only called
832by the primary CPU.
833
834The purpose of this function is to perform any architectural initialization
835that varies across platforms, for example enabling the MMU (since the memory
836map differs across platforms).
837
838
839### Function : bl31_platform_setup() [mandatory]
840
841 Argument : void
842 Return : void
843
844This function may execute with the MMU and data caches enabled if the platform
845port does the necessary initialization in `bl31_plat_arch_setup()`. It is only
846called by the primary CPU.
847
848The purpose of this function is to complete platform initialization so that both
849BL3-1 runtime services and normal world software can function correctly.
850
851The ARM FVP port does the following:
852* Initializes the generic interrupt controller.
853* Configures the CLCD controller.
Sandrine Bailleux9e864902014-03-31 11:25:18 +0100854* Enables system-level implementation of the generic timer counter.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100855* Grants access to the system counter timer module
856* Initializes the FVP power controller device
857* Detects the system topology.
858
859
860### Function : bl31_get_next_image_info() [mandatory]
861
Achin Gupta35ca3512014-02-19 17:58:33 +0000862 Argument : unsigned int
Achin Gupta4f6ad662013-10-25 09:08:21 +0100863 Return : el_change_info *
864
865This function may execute with the MMU and data caches enabled if the platform
866port does the necessary initializations in `bl31_plat_arch_setup()`.
867
868This function is called by `bl31_main()` to retrieve information provided by
Achin Gupta35ca3512014-02-19 17:58:33 +0000869BL2 for the next image in the security state specified by the argument. BL3-1
870uses this information to pass control to that image in the specified security
871state. This function must return a pointer to the `el_change_info` structure
872(that was copied during `bl31_early_platform_setup()`) if the image exists. It
873should return NULL otherwise.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100874
875
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000876### Function : bl31_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100877
878 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000879 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100880
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000881This function should only be called on the cold boot path. This function may
882execute with the MMU and data caches enabled if the platform port does the
883necessary initializations in `bl31_plat_arch_setup()`. It is only called by the
884primary CPU.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100885
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000886The purpose of this function is to return a pointer to a `meminfo` structure
887populated with the extents of secure RAM available for BL3-1 to use. See
Achin Gupta4f6ad662013-10-25 09:08:21 +0100888`bl31_early_platform_setup()` above.
889
890
Achin Gupta35ca3512014-02-19 17:58:33 +0000891### Function : bl31_plat_get_bl32_mem_layout() [mandatory]
892
893 Argument : void
894 Return : meminfo *
895
896This function should only be called on the cold boot path. This function may
897execute with the MMU and data caches enabled if the platform port does the
898necessary initializations in `bl31_plat_arch_setup()`. It is only called by the
899primary CPU.
900
901The purpose of this function is to return a pointer to a `meminfo` structure
902populated with the extents of memory available for BL3-2 to use. See
903`bl31_early_platform_setup()` above.
904
905
Achin Gupta4f6ad662013-10-25 09:08:21 +01009063.3 Power State Coordination Interface (in BL3-1)
907------------------------------------------------
908
909The ARM Trusted Firmware's implementation of the PSCI API is based around the
910concept of an _affinity instance_. Each _affinity instance_ can be uniquely
911identified in a system by a CPU ID (the processor `MPIDR` is used in the PSCI
912interface) and an _affinity level_. A processing element (for example, a
913CPU) is at level 0. If the CPUs in the system are described in a tree where the
914node above a CPU is a logical grouping of CPUs that share some state, then
915affinity level 1 is that group of CPUs (for example, a cluster), and affinity
916level 2 is a group of clusters (for example, the system). The implementation
917assumes that the affinity level 1 ID can be computed from the affinity level 0
918ID (for example, a unique cluster ID can be computed from the CPU ID). The
919current implementation computes this on the basis of the recommended use of
920`MPIDR` affinity fields in the ARM Architecture Reference Manual.
921
922BL3-1's platform initialization code exports a pointer to the platform-specific
923power management operations required for the PSCI implementation to function
924correctly. This information is populated in the `plat_pm_ops` structure. The
925PSCI implementation calls members of the `plat_pm_ops` structure for performing
926power management operations for each affinity instance. For example, the target
927CPU is specified by its `MPIDR` in a PSCI `CPU_ON` call. The `affinst_on()`
928handler (if present) is called for each affinity instance as the PSCI
929implementation powers up each affinity level implemented in the `MPIDR` (for
930example, CPU, cluster and system).
931
932The following functions must be implemented to initialize PSCI functionality in
933the ARM Trusted Firmware.
934
935
936### Function : plat_get_aff_count() [mandatory]
937
938 Argument : unsigned int, unsigned long
939 Return : unsigned int
940
941This function may execute with the MMU and data caches enabled if the platform
942port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
943called by the primary CPU.
944
945This function is called by the PSCI initialization code to detect the system
946topology. Its purpose is to return the number of affinity instances implemented
947at a given `affinity level` (specified by the first argument) and a given
948`MPIDR` (specified by the second argument). For example, on a dual-cluster
949system where first cluster implements 2 CPUs and the second cluster implements 4
950CPUs, a call to this function with an `MPIDR` corresponding to the first cluster
951(`0x0`) and affinity level 0, would return 2. A call to this function with an
952`MPIDR` corresponding to the second cluster (`0x100`) and affinity level 0,
953would return 4.
954
955
956### Function : plat_get_aff_state() [mandatory]
957
958 Argument : unsigned int, unsigned long
959 Return : unsigned int
960
961This function may execute with the MMU and data caches enabled if the platform
962port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
963called by the primary CPU.
964
965This function is called by the PSCI initialization code. Its purpose is to
966return the state of an affinity instance. The affinity instance is determined by
967the affinity ID at a given `affinity level` (specified by the first argument)
968and an `MPIDR` (specified by the second argument). The state can be one of
969`PSCI_AFF_PRESENT` or `PSCI_AFF_ABSENT`. The latter state is used to cater for
970system topologies where certain affinity instances are unimplemented. For
971example, consider a platform that implements a single cluster with 4 CPUs and
972another CPU implemented directly on the interconnect with the cluster. The
973`MPIDR`s of the cluster would range from `0x0-0x3`. The `MPIDR` of the single
974CPU would be 0x100 to indicate that it does not belong to cluster 0. Cluster 1
975is missing but needs to be accounted for to reach this single CPU in the
976topology tree. Hence it is marked as `PSCI_AFF_ABSENT`.
977
978
979### Function : plat_get_max_afflvl() [mandatory]
980
981 Argument : void
982 Return : int
983
984This function may execute with the MMU and data caches enabled if the platform
985port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
986called by the primary CPU.
987
988This function is called by the PSCI implementation both during cold and warm
989boot, to determine the maximum affinity level that the power management
James Morrisseyba3155b2013-10-29 10:56:46 +0000990operations should apply to. ARMv8-A has support for 4 affinity levels. It is
Achin Gupta4f6ad662013-10-25 09:08:21 +0100991likely that hardware will implement fewer affinity levels. This function allows
992the PSCI implementation to consider only those affinity levels in the system
993that the platform implements. For example, the Base AEM FVP implements two
994clusters with a configurable number of CPUs. It reports the maximum affinity
995level as 1, resulting in PSCI power control up to the cluster level.
996
997
998### Function : platform_setup_pm() [mandatory]
999
1000 Argument : plat_pm_ops **
1001 Return : int
1002
1003This function may execute with the MMU and data caches enabled if the platform
1004port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
1005called by the primary CPU.
1006
1007This function is called by PSCI initialization code. Its purpose is to export
1008handler routines for platform-specific power management actions by populating
1009the passed pointer with a pointer to BL3-1's private `plat_pm_ops` structure.
1010
1011A description of each member of this structure is given below. Please refer to
Andrew Thoelke2bf28e62014-03-20 10:48:23 +00001012the ARM FVP specific implementation of these handlers in [plat/fvp/plat_pm.c]
Achin Gupta4f6ad662013-10-25 09:08:21 +01001013as an example. A platform port may choose not implement some of the power
1014management operations. For example, the ARM FVP port does not implement the
1015`affinst_standby()` function.
1016
1017#### plat_pm_ops.affinst_standby()
1018
1019Perform the platform-specific setup to enter the standby state indicated by the
1020passed argument.
1021
1022#### plat_pm_ops.affinst_on()
1023
1024Perform the platform specific setup to power on an affinity instance, specified
1025by the `MPIDR` (first argument) and `affinity level` (fourth argument). The
1026`state` (fifth argument) contains the current state of that affinity instance
1027(ON or OFF). This is useful to determine whether any action must be taken. For
1028example, while powering on a CPU, the cluster that contains this CPU might
1029already be in the ON state. The platform decides what actions must be taken to
1030transition from the current state to the target state (indicated by the power
1031management operation).
1032
1033#### plat_pm_ops.affinst_off()
1034
1035Perform the platform specific setup to power off an affinity instance in the
1036`MPIDR` of the calling CPU. It is called by the PSCI `CPU_OFF` API
1037implementation.
1038
1039The `MPIDR` (first argument), `affinity level` (second argument) and `state`
1040(third argument) have a similar meaning as described in the `affinst_on()`
1041operation. They are used to identify the affinity instance on which the call
1042is made and its current state. This gives the platform port an indication of the
1043state transition it must make to perform the requested action. For example, if
1044the calling CPU is the last powered on CPU in the cluster, after powering down
1045affinity level 0 (CPU), the platform port should power down affinity level 1
1046(the cluster) as well.
1047
1048This function is called with coherent stacks. This allows the PSCI
1049implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +00001050stale stack state after turning off the caches. On ARMv8-A cache hits do not
1051occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001052
1053#### plat_pm_ops.affinst_suspend()
1054
1055Perform the platform specific setup to power off an affinity instance in the
1056`MPIDR` of the calling CPU. It is called by the PSCI `CPU_SUSPEND` API
1057implementation.
1058
1059The `MPIDR` (first argument), `affinity level` (third argument) and `state`
1060(fifth argument) have a similar meaning as described in the `affinst_on()`
1061operation. They are used to identify the affinity instance on which the call
1062is made and its current state. This gives the platform port an indication of the
1063state transition it must make to perform the requested action. For example, if
1064the calling CPU is the last powered on CPU in the cluster, after powering down
1065affinity level 0 (CPU), the platform port should power down affinity level 1
1066(the cluster) as well.
1067
1068The difference between turning an affinity instance off versus suspending it
1069is that in the former case, the affinity instance is expected to re-initialize
1070its state when its next powered on (see `affinst_on_finish()`). In the latter
1071case, the affinity instance is expected to save enough state so that it can
1072resume execution by restoring this state when its powered on (see
1073`affinst_suspend_finish()`).
1074
1075This function is called with coherent stacks. This allows the PSCI
1076implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +00001077stale stack state after turning off the caches. On ARMv8-A cache hits do not
1078occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001079
1080#### plat_pm_ops.affinst_on_finish()
1081
1082This function is called by the PSCI implementation after the calling CPU is
1083powered on and released from reset in response to an earlier PSCI `CPU_ON` call.
1084It performs the platform-specific setup required to initialize enough state for
1085this CPU to enter the normal world and also provide secure runtime firmware
1086services.
1087
1088The `MPIDR` (first argument), `affinity level` (second argument) and `state`
1089(third argument) have a similar meaning as described in the previous operations.
1090
1091This function is called with coherent stacks. This allows the PSCI
1092implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +00001093stale stack state after turning off the caches. On ARMv8-A cache hits do not
1094occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001095
1096#### plat_pm_ops.affinst_on_suspend()
1097
1098This function is called by the PSCI implementation after the calling CPU is
1099powered on and released from reset in response to an asynchronous wakeup
1100event, for example a timer interrupt that was programmed by the CPU during the
1101`CPU_SUSPEND` call. It performs the platform-specific setup required to
1102restore the saved state for this CPU to resume execution in the normal world
1103and also provide secure runtime firmware services.
1104
1105The `MPIDR` (first argument), `affinity level` (second argument) and `state`
1106(third argument) have a similar meaning as described in the previous operations.
1107
1108This function is called with coherent stacks. This allows the PSCI
1109implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +00001110stale stack state after turning off the caches. On ARMv8-A cache hits do not
1111occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001112
1113BL3-1 platform initialization code must also detect the system topology and
1114the state of each affinity instance in the topology. This information is
1115critical for the PSCI runtime service to function correctly. More details are
1116provided in the description of the `plat_get_aff_count()` and
1117`plat_get_aff_state()` functions above.
1118
1119
Harry Liebela960f282013-12-12 16:03:44 +000011204. C Library
1121-------------
1122
1123To avoid subtle toolchain behavioral dependencies, the header files provided
1124by the compiler are not used. The software is built with the `-nostdinc` flag
1125to ensure no headers are included from the toolchain inadvertently. Instead the
1126required headers are included in the ARM Trusted Firmware source tree. The
1127library only contains those C library definitions required by the local
1128implementation. If more functionality is required, the needed library functions
1129will need to be added to the local implementation.
1130
1131Versions of [FreeBSD] headers can be found in `include/stdlib`. Some of these
1132headers have been cut down in order to simplify the implementation. In order to
1133minimize changes to the header files, the [FreeBSD] layout has been maintained.
1134The generic C library definitions can be found in `include/stdlib` with more
1135system and machine specific declarations in `include/stdlib/sys` and
1136`include/stdlib/machine`.
1137
1138The local C library implementations can be found in `lib/stdlib`. In order to
1139extend the C library these files may need to be modified. It is recommended to
1140use a release version of [FreeBSD] as a starting point.
1141
1142The C library header files in the [FreeBSD] source tree are located in the
1143`include` and `sys/sys` directories. [FreeBSD] machine specific definitions
1144can be found in the `sys/<machine-type>` directories. These files define things
1145like 'the size of a pointer' and 'the range of an integer'. Since an AArch64
1146port for [FreeBSD] does not yet exist, the machine specific definitions are
1147based on existing machine types with similar properties (for example SPARC64).
1148
1149Where possible, C library function implementations were taken from [FreeBSD]
1150as found in the `lib/libc` directory.
1151
1152A copy of the [FreeBSD] sources can be downloaded with `git`.
1153
1154 git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0
1155
1156
Harry Liebeld265bd72014-01-31 19:04:10 +000011575. Storage abstraction layer
1158-----------------------------
1159
1160In order to improve platform independence and portability an storage abstraction
1161layer is used to load data from non-volatile platform storage.
1162
1163Each platform should register devices and their drivers via the Storage layer.
1164These drivers then need to be initialized by bootloader phases as
1165required in their respective `blx_platform_setup()` functions. Currently
1166storage access is only required by BL1 and BL2 phases. The `load_image()`
1167function uses the storage layer to access non-volatile platform storage.
1168
1169It is mandatory to implement at least one storage driver. For the FVP the
1170Firmware Image Package(FIP) driver is provided as the default means to load data
1171from storage (see the "Firmware Image Package" section in the [User Guide]).
1172The storage layer is described in the header file `include/io_storage.h`. The
1173implementation of the common library is in `lib/io_storage.c` and the driver
1174files are located in `drivers/io/`.
1175
1176Each IO driver must provide `io_dev_*` structures, as described in
1177`drivers/io/io_driver.h`. These are returned via a mandatory registration
1178function that is called on platform initialization. The semi-hosting driver
1179implementation in `io_semihosting.c` can be used as an example.
1180
1181The Storage layer provides mechanisms to initialize storage devices before
1182IO operations are called. The basic operations supported by the layer
1183include `open()`, `close()`, `read()`, `write()`, `size()` and `seek()`.
1184Drivers do not have to implement all operations, but each platform must
1185provide at least one driver for a device capable of supporting generic
1186operations such as loading a bootloader image.
1187
1188The current implementation only allows for known images to be loaded by the
1189firmware. These images are specified by using their names, as defined in the
1190`platform.h` file. The platform layer (`plat_get_image_source()`) then returns
1191a reference to a device and a driver-specific `spec` which will be understood
1192by the driver to allow access to the image data.
1193
1194The layer is designed in such a way that is it possible to chain drivers with
1195other drivers. For example, file-system drivers may be implemented on top of
1196physical block devices, both represented by IO devices with corresponding
1197drivers. In such a case, the file-system "binding" with the block device may
1198be deferred until the file-system device is initialised.
1199
1200The abstraction currently depends on structures being statically allocated
1201by the drivers and callers, as the system does not yet provide a means of
1202dynamically allocating memory. This may also have the affect of limiting the
1203amount of open resources per driver.
1204
1205
Achin Gupta4f6ad662013-10-25 09:08:21 +01001206- - - - - - - - - - - - - - - - - - - - - - - - - -
1207
Dan Handleye83b0ca2014-01-14 18:17:09 +00001208_Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
Achin Gupta4f6ad662013-10-25 09:08:21 +01001209
1210
1211[User Guide]: user-guide.md
Harry Liebela960f282013-12-12 16:03:44 +00001212[FreeBSD]: http://www.freebsd.org
Achin Gupta4f6ad662013-10-25 09:08:21 +01001213
Andrew Thoelke2bf28e62014-03-20 10:48:23 +00001214[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S
1215[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S
1216[plat/fvp/platform.h]: ../plat/fvp/platform.h
Soby Mathewa43d4312014-04-07 15:28:55 +01001217[plat/fvp/include/platform_macros.S]: ../plat/fvp/include/platform_macros.S
Andrew Thoelke2bf28e62014-03-20 10:48:23 +00001218[plat/fvp/aarch64/plat_common.c]: ../plat/fvp/aarch64/plat_common.c
1219[plat/fvp/plat_pm.c]: ../plat/fvp/plat_pm.c
1220[include/runtime_svc.h]: ../include/runtime_svc.h