blob: 6bba3604b7dcf794b9f8a46c6a86f38ed9de34a2 [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
84[../plat/fvp/platform.h].
85
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
99 by `platform_set_stack()`.
100
James Morrisseyba3155b2013-10-29 10:56:46 +0000101* **#define : FIRMWARE_WELCOME_STR**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100102
103 Defines the character string printed by BL1 upon entry into the `bl1_main()`
104 function.
105
James Morrisseyba3155b2013-10-29 10:56:46 +0000106* **#define : BL2_IMAGE_NAME**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100107
108 Name of the BL2 binary image on the host file-system. This name is used by
Harry Liebeld265bd72014-01-31 19:04:10 +0000109 BL1 to load BL2 into secure memory from non-volatile storage.
110
111* **#define : BL31_IMAGE_NAME**
112
113 Name of the BL3-1 binary image on the host file-system. This name is used by
114 BL2 to load BL3-1 into secure memory from platform storage.
115
116* **#define : BL33_IMAGE_NAME**
117
118 Name of the BL3-3 binary image on the host file-system. This name is used by
119 BL2 to load BL3-3 into non-secure memory from platform storage.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100120
James Morrisseyba3155b2013-10-29 10:56:46 +0000121* **#define : PLATFORM_CACHE_LINE_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100122
123 Defines the size (in bytes) of the largest cache line across all the cache
124 levels in the platform.
125
James Morrisseyba3155b2013-10-29 10:56:46 +0000126* **#define : PLATFORM_CLUSTER_COUNT**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100127
128 Defines the total number of clusters implemented by the platform in the
129 system.
130
James Morrisseyba3155b2013-10-29 10:56:46 +0000131* **#define : PLATFORM_CORE_COUNT**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100132
133 Defines the total number of CPUs implemented by the platform across all
134 clusters in the system.
135
James Morrisseyba3155b2013-10-29 10:56:46 +0000136* **#define : PLATFORM_MAX_CPUS_PER_CLUSTER**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100137
138 Defines the maximum number of CPUs that can be implemented within a cluster
139 on the platform.
140
James Morrisseyba3155b2013-10-29 10:56:46 +0000141* **#define : PRIMARY_CPU**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100142
143 Defines the `MPIDR` of the primary CPU on the platform. This value is used
144 after a cold boot to distinguish between primary and secondary CPUs.
145
James Morrisseyba3155b2013-10-29 10:56:46 +0000146* **#define : TZROM_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100147
148 Defines the base address of secure ROM on the platform, where the BL1 binary
149 is loaded. This constant is used by the linker scripts to ensure that the
150 BL1 image fits into the available memory.
151
James Morrisseyba3155b2013-10-29 10:56:46 +0000152* **#define : TZROM_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100153
154 Defines the size of secure ROM on the platform. This constant is used by the
155 linker scripts to ensure that the BL1 image fits into the available memory.
156
James Morrisseyba3155b2013-10-29 10:56:46 +0000157* **#define : TZRAM_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100158
159 Defines the base address of the secure RAM on platform, where the data
160 section of the BL1 binary is loaded. The BL2 and BL3-1 images are also
161 loaded in this secure RAM region. This constant is used by the linker
162 scripts to ensure that the BL1 data section and BL2/BL3-1 binary images fit
163 into the available memory.
164
James Morrisseyba3155b2013-10-29 10:56:46 +0000165* **#define : TZRAM_SIZE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100166
167 Defines the size of the secure RAM on the platform. This constant is used by
168 the linker scripts to ensure that the BL1 data section and BL2/BL3-1 binary
169 images fit into the available memory.
170
James Morrisseyba3155b2013-10-29 10:56:46 +0000171* **#define : SYS_CNTCTL_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100172
173 Defines the base address of the `CNTCTLBase` frame of the memory mapped
174 counter and timer in the system level implementation of the generic timer.
175
James Morrisseyba3155b2013-10-29 10:56:46 +0000176* **#define : BL2_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100177
178 Defines the base address in secure RAM where BL1 loads the BL2 binary image.
Sandrine Bailleuxcd29b0a2013-11-27 10:32:17 +0000179 Must be aligned on a page-size boundary.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100180
James Morrisseyba3155b2013-10-29 10:56:46 +0000181* **#define : BL31_BASE**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100182
183 Defines the base address in secure RAM where BL2 loads the BL3-1 binary
Sandrine Bailleuxcd29b0a2013-11-27 10:32:17 +0000184 image. Must be aligned on a page-size boundary.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100185
Harry Liebeld265bd72014-01-31 19:04:10 +0000186* **#define : NS_IMAGE_OFFSET**
187 Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary
188 image. Must be aligned on a page-size boundary.
189
Achin Gupta4f6ad662013-10-25 09:08:21 +0100190
191### Other mandatory modifications
192
James Morrisseyba3155b2013-10-29 10:56:46 +0000193The following mandatory modifications may be implemented in any file
Achin Gupta4f6ad662013-10-25 09:08:21 +0100194the implementer chooses. In the ARM FVP port, they are implemented in
Ryan Harkin03cb8fb2014-01-15 17:37:25 +0000195[../plat/fvp/aarch64/plat_common.c].
Achin Gupta4f6ad662013-10-25 09:08:21 +0100196
James Morrisseyba3155b2013-10-29 10:56:46 +0000197* **Variable : unsigned char platform_normal_stacks[X][Y]**
Achin Gupta4f6ad662013-10-25 09:08:21 +0100198
199 where X = PLATFORM_STACK_SIZE
200 and Y = PLATFORM_CORE_COUNT
201
202 Each platform must allocate a block of memory with Normal Cacheable, Write
203 back, Write allocate and Inner Shareable attributes aligned to the size (in
204 bytes) of the largest cache line amongst all caches implemented in the
205 system. A pointer to this memory should be exported with the name
206 `platform_normal_stacks`. This pointer is used by the common platform helper
Achin Guptac8afc782013-11-25 18:45:02 +0000207 functions `platform_set_stack()` (to allocate a stack for each CPU in the
208 platform) & `platform_get_stack()` (to return the base address of that
209 stack) (see [../plat/common/aarch64/platform_helpers.S]).
Achin Gupta4f6ad662013-10-25 09:08:21 +0100210
211
2122.2 Common optional modifications
213---------------------------------
214
215The following are helper functions implemented by the firmware that perform
216common platform-specific tasks. A platform may choose to override these
217definitions.
218
219
220### Function : platform_get_core_pos()
221
222 Argument : unsigned long
223 Return : int
224
225A platform may need to convert the `MPIDR` of a CPU to an absolute number, which
226can be used as a CPU-specific linear index into blocks of memory (for example
227while allocating per-CPU stacks). This routine contains a simple mechanism
228to perform this conversion, using the assumption that each cluster contains a
229maximum of 4 CPUs:
230
231 linear index = cpu_id + (cluster_id * 4)
232
233 cpu_id = 8-bit value in MPIDR at affinity level 0
234 cluster_id = 8-bit value in MPIDR at affinity level 1
235
236
237### Function : platform_set_coherent_stack()
238
239 Argument : unsigned long
240 Return : void
241
242A platform may need stack memory that is coherent with main memory to perform
243certain operations like:
244
245* Turning the MMU on, or
246* Flushing caches prior to powering down a CPU or cluster.
247
248Each BL stage allocates this coherent stack memory for each CPU in the
249`tzfw_coherent_mem` section. A pointer to this memory (`pcpu_dv_mem_stack`) is
250used by this function to allocate a coherent stack for each CPU. A CPU is
251identified by its `MPIDR`, which is passed as an argument to this function.
252
253The size of the stack allocated to each CPU is specified by the constant
254`PCPU_DV_MEM_STACK_SIZE`.
255
256
257### Function : platform_is_primary_cpu()
258
259 Argument : unsigned long
260 Return : unsigned int
261
262This function identifies a CPU by its `MPIDR`, which is passed as the argument,
263to determine whether this CPU is the primary CPU or a secondary CPU. A return
264value of zero indicates that the CPU is not the primary CPU, while a non-zero
265return value indicates that the CPU is the primary CPU.
266
267
268### Function : platform_set_stack()
269
270 Argument : unsigned long
271 Return : void
272
273This function uses the `platform_normal_stacks` pointer variable to allocate
274stacks to each CPU. Further details are given in the description of the
275`platform_normal_stacks` variable below. A CPU is identified by its `MPIDR`,
276which is passed as the argument.
277
278The size of the stack allocated to each CPU is specified by the platform defined
279constant `PLATFORM_STACK_SIZE`.
280
281
Achin Guptac8afc782013-11-25 18:45:02 +0000282### Function : platform_get_stack()
283
284 Argument : unsigned long
285 Return : unsigned long
286
287This function uses the `platform_normal_stacks` pointer variable to return the
288base address of the stack memory reserved for a CPU. Further details are given
289in the description of the `platform_normal_stacks` variable below. A CPU is
290identified by its `MPIDR`, which is passed as the argument.
291
292The size of the stack allocated to each CPU is specified by the platform defined
293constant `PLATFORM_STACK_SIZE`.
294
295
Achin Gupta4f6ad662013-10-25 09:08:21 +0100296### Function : plat_report_exception()
297
298 Argument : unsigned int
299 Return : void
300
301A platform may need to report various information about its status when an
302exception is taken, for example the current exception level, the CPU security
303state (secure/non-secure), the exception type, and so on. This function is
304called in the following circumstances:
305
306* In BL1, whenever an exception is taken.
307* In BL2, whenever an exception is taken.
308* In BL3-1, whenever an asynchronous exception or a synchronous exception
309 other than an SMC32/SMC64 exception is taken.
310
311The default implementation doesn't do anything, to avoid making assumptions
312about the way the platform displays its status information.
313
314This function receives the exception type as its argument. Possible values for
315exceptions types are listed in the [../include/runtime_svc.h] header file. Note
316that these constants are not related to any architectural exception code; they
317are just an ARM Trusted Firmware convention.
318
319
3203. Modifications specific to a Boot Loader stage
321-------------------------------------------------
322
3233.1 Boot Loader Stage 1 (BL1)
324-----------------------------
325
326BL1 implements the reset vector where execution starts from after a cold or
327warm boot. For each CPU, BL1 is responsible for the following tasks:
328
3291. Distinguishing between a cold boot and a warm boot.
330
3312. In the case of a cold boot and the CPU being the primary CPU, ensuring that
332 only this CPU executes the remaining BL1 code, including loading and passing
333 control to the BL2 stage.
334
3353. In the case of a cold boot and the CPU being a secondary CPU, ensuring that
336 the CPU is placed in a platform-specific state until the primary CPU
337 performs the necessary steps to remove it from this state.
338
3394. In the case of a warm boot, ensuring that the CPU jumps to a platform-
340 specific address in the BL3-1 image in the same processor mode as it was
341 when released from reset.
342
Harry Liebeld265bd72014-01-31 19:04:10 +00003435. Loading the BL2 image from non-volatile storage into secure memory at the
Achin Gupta4f6ad662013-10-25 09:08:21 +0100344 address specified by the platform defined constant `BL2_BASE`.
345
3466. Populating a `meminfo` structure with the following information in memory,
347 accessible by BL2 immediately upon entry.
348
349 meminfo.total_base = Base address of secure RAM visible to BL2
350 meminfo.total_size = Size of secure RAM visible to BL2
351 meminfo.free_base = Base address of secure RAM available for
352 allocation to BL2
353 meminfo.free_size = Size of secure RAM available for allocation to BL2
354
355 BL1 places this `meminfo` structure at the beginning of the free memory
356 available for its use. Since BL1 cannot allocate memory dynamically at the
357 moment, its free memory will be available for BL2's use as-is. However, this
358 means that BL2 must read the `meminfo` structure before it starts using its
359 free memory (this is discussed in Section 3.2).
360
361 In future releases of the ARM Trusted Firmware it will be possible for
362 the platform to decide where it wants to place the `meminfo` structure for
363 BL2.
364
365 BL1 implements the `init_bl2_mem_layout()` function to populate the
366 BL2 `meminfo` structure. The platform may override this implementation, for
367 example if the platform wants to restrict the amount of memory visible to
368 BL2. Details of how to do this are given below.
369
370The following functions need to be implemented by the platform port to enable
371BL1 to perform the above tasks.
372
373
374### Function : platform_get_entrypoint() [mandatory]
375
376 Argument : unsigned long
377 Return : unsigned int
378
379This function is called with the `SCTLR.M` and `SCTLR.C` bits disabled. The CPU
380is identified by its `MPIDR`, which is passed as the argument. The function is
381responsible for distinguishing between a warm and cold reset using platform-
382specific means. If it's a warm reset then it returns the entrypoint into the
383BL3-1 image that the CPU must jump to. If it's a cold reset then this function
384must return zero.
385
386This function is also responsible for implementing a platform-specific mechanism
387to handle the condition where the CPU has been warm reset but there is no
388entrypoint to jump to.
389
390This function does not follow the Procedure Call Standard used by the
391Application Binary Interface for the ARM 64-bit architecture. The caller should
392not assume that callee saved registers are preserved across a call to this
393function.
394
395This function fulfills requirement 1 listed above.
396
397
398### Function : plat_secondary_cold_boot_setup() [mandatory]
399
400 Argument : void
401 Return : void
402
403This function is called with the MMU and data caches disabled. It is responsible
404for placing the executing secondary CPU in a platform-specific state until the
405primary CPU performs the necessary actions to bring it out of that state and
406allow entry into the OS.
407
408In the ARM FVP port, each secondary CPU powers itself off. The primary CPU is
409responsible for powering up the secondary CPU when normal world software
410requires them.
411
412This function fulfills requirement 3 above.
413
414
415### Function : platform_cold_boot_init() [mandatory]
416
417 Argument : unsigned long
418 Return : unsigned int
419
420This function executes with the MMU and data caches disabled. It is only called
421by the primary CPU. The argument to this function is the address of the
422`bl1_main()` routine where the generic BL1-specific actions are performed.
423This function performs any platform-specific and architectural setup that the
424platform requires to make execution of `bl1_main()` possible.
425
426The platform must enable the MMU with identity mapped page tables and enable
427caches by setting the `SCTLR.I` and `SCTLR.C` bits.
428
429Platform-specific setup might include configuration of memory controllers,
430configuration of the interconnect to allow the cluster to service cache snoop
431requests from another cluster, zeroing of the ZI section, and so on.
432
433In the ARM FVP port, this function enables CCI snoops into the cluster that the
434primary CPU is part of. It also enables the MMU and initializes the ZI section
435in the BL1 image through the use of linker defined symbols.
436
437This function helps fulfill requirement 2 above.
438
439
440### Function : bl1_platform_setup() [mandatory]
441
442 Argument : void
443 Return : void
444
445This function executes with the MMU and data caches enabled. It is responsible
446for performing any remaining platform-specific setup that can occur after the
447MMU and data cache have been enabled.
448
Jeenu Viswambharan1c297bf2014-01-07 10:21:18 +0000449In the ARM FVP port, this function enables system-level implementation of the
450generic timer counter. It also initializes counter frequency for CPU's generic
451timers.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100452
Harry Liebeld265bd72014-01-31 19:04:10 +0000453This function is also responsible for initializing the storage abstraction layer
454which is used to load further bootloader images.
455
Achin Gupta4f6ad662013-10-25 09:08:21 +0100456This function helps fulfill requirement 5 above.
457
458
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000459### Function : bl1_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100460
461 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000462 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100463
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000464This function should only be called on the cold boot path. It executes with the
465MMU and data caches enabled. The pointer returned by this function must point to
466a `meminfo` structure containing the extents and availability of secure RAM for
467the BL1 stage.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100468
469 meminfo.total_base = Base address of secure RAM visible to BL1
470 meminfo.total_size = Size of secure RAM visible to BL1
471 meminfo.free_base = Base address of secure RAM available for allocation
472 to BL1
473 meminfo.free_size = Size of secure RAM available for allocation to BL1
474
475This information is used by BL1 to load the BL2 image in secure RAM. BL1 also
476populates a similar structure to tell BL2 the extents of memory available for
477its own use.
478
479This function helps fulfill requirement 5 above.
480
481
482### Function : init_bl2_mem_layout() [optional]
483
484 Argument : meminfo *, meminfo *, unsigned int, unsigned long
485 Return : void
486
487Each BL stage needs to tell the next stage the amount of secure RAM available
488for it to use. For example, as part of handing control to BL2, BL1 informs BL2
489of the extents of secure RAM available for BL2 to use. BL2 must do the same when
490passing control to BL3-1. This information is populated in a `meminfo`
491structure.
492
493Depending upon where BL2 has been loaded in secure RAM (determined by
494`BL2_BASE`), BL1 calculates the amount of free memory available for BL2 to use.
495BL1 also ensures that its data sections resident in secure RAM are not visible
496to BL2. An illustration of how this is done in the ARM FVP port is given in the
497[User Guide], in the Section "Memory layout on Base FVP".
498
499
5003.2 Boot Loader Stage 2 (BL2)
501-----------------------------
502
503The BL2 stage is executed only by the primary CPU, which is determined in BL1
504using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at
505`BL2_BASE`. BL2 executes in Secure EL1 and is responsible for:
506
Harry Liebeld265bd72014-01-31 19:04:10 +00005071. Loading the BL3-1 binary image into secure RAM from non-volatile storage. To
508 load the BL3-1 image, BL2 makes use of the `meminfo` structure passed to it
509 by BL1. This structure allows BL2 to calculate how much secure RAM is
510 available for its use. The platform also defines the address in secure RAM
511 where BL3-1 is loaded through the constant `BL31_BASE`. BL2 uses this
512 information to determine if there is enough memory to load the BL3-1 image.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100513
Harry Liebeld265bd72014-01-31 19:04:10 +00005142. Loading the normal world BL3-3 binary image into non-secure DRAM from
515 platform storage and arranging for BL3-1 to pass control to this image. This
516 address is determined using the `plat_get_ns_image_entrypoint()` function
517 described below.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100518
519 BL2 populates an `el_change_info` structure in memory provided by the
520 platform with information about how BL3-1 should pass control to the normal
521 world BL image.
522
5233. Populating a `meminfo` structure with the following information in
524 memory that is accessible by BL3-1 immediately upon entry.
525
526 meminfo.total_base = Base address of secure RAM visible to BL3-1
527 meminfo.total_size = Size of secure RAM visible to BL3-1
528 meminfo.free_base = Base address of secure RAM available for allocation
529 to BL3-1
530 meminfo.free_size = Size of secure RAM available for allocation to
531 BL3-1
532
Achin Guptae4d084e2014-02-19 17:18:23 +0000533 BL2 populates this information in the `bl31_meminfo` field of the pointer
534 returned by the `bl2_get_bl31_args_ptr() function. BL2 implements the
Achin Gupta4f6ad662013-10-25 09:08:21 +0100535 `init_bl31_mem_layout()` function to populate the BL3-1 meminfo structure
536 described above. The platform may override this implementation, for example
537 if the platform wants to restrict the amount of memory visible to BL3-1.
538 Details of this function are given below.
539
Achin Guptaa3050ed2014-02-19 17:52:35 +00005404. Loading the BL3-2 binary image (if present) in platform provided memory
541 using semi-hosting. To load the BL3-2 image, BL2 makes use of the
542 `bl32_meminfo` field in the `bl31_args` structure to which a pointer is
543 returned by the `bl2_get_bl31_args_ptr()` function. The platform also
544 defines the address in memory where BL3-2 is loaded through the constant
545 `BL32_BASE`. BL2 uses this information to determine if there is enough
546 memory to load the BL3-2 image.
547
5485. Arranging to pass control to the BL3-2 image (if present) that has been
549 pre-loaded at `BL32_BASE`. BL2 populates an `el_change_info` structure
550 in memory provided by the platform with information about how BL3-1 should
551 pass control to the BL3-2 image. This structure follows the
552 `el_change_info` structure populated for the normal world BL image in 2.
553 above.
554
5556. Populating a `meminfo` structure with the following information in
556 memory that is accessible by BL3-1 immediately upon entry.
557
558 meminfo.total_base = Base address of memory visible to BL3-2
559 meminfo.total_size = Size of memory visible to BL3-2
560 meminfo.free_base = Base address of memory available for allocation
561 to BL3-2
562 meminfo.free_size = Size of memory available for allocation to
563 BL3-2
564
565 BL2 populates this information in the `bl32_meminfo` field of the pointer
566 returned by the `bl2_get_bl31_args_ptr() function.
567
Achin Gupta4f6ad662013-10-25 09:08:21 +0100568The following functions must be implemented by the platform port to enable BL2
569to perform the above tasks.
570
571
572### Function : bl2_early_platform_setup() [mandatory]
573
574 Argument : meminfo *, void *
575 Return : void
576
577This function executes with the MMU and data caches disabled. It is only called
578by the primary CPU. The arguments to this function are:
579
580* The address of the `meminfo` structure populated by BL1
581* An opaque pointer that the platform may use as needed.
582
583The platform must copy the contents of the `meminfo` structure into a private
584variable as the original memory may be subsequently overwritten by BL2. The
585copied structure is made available to all BL2 code through the
Achin Guptae4d084e2014-02-19 17:18:23 +0000586`bl2_plat_sec_mem_layout()` function.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100587
588
589### Function : bl2_plat_arch_setup() [mandatory]
590
591 Argument : void
592 Return : void
593
594This function executes with the MMU and data caches disabled. It is only called
595by the primary CPU.
596
597The purpose of this function is to perform any architectural initialization
598that varies across platforms, for example enabling the MMU (since the memory
599map differs across platforms).
600
601
602### Function : bl2_platform_setup() [mandatory]
603
604 Argument : void
605 Return : void
606
607This function may execute with the MMU and data caches enabled if the platform
608port does the necessary initialization in `bl2_plat_arch_setup()`. It is only
609called by the primary CPU.
610
Achin Guptae4d084e2014-02-19 17:18:23 +0000611The purpose of this function is to perform any platform initialization
612specific to BL2. For example on the ARM FVP port this function initialises a
613internal pointer (`bl2_to_bl31_args`) to a `bl31_args` which will be used by
614BL2 to pass information to BL3_1. The pointer is initialized to the base
615address of Secure DRAM (`0x06000000`).
Achin Gupta4f6ad662013-10-25 09:08:21 +0100616
Achin Guptaa3050ed2014-02-19 17:52:35 +0000617The ARM FVP port also populates the `bl32_meminfo` field in the `bl31_args`
618structure pointed to by `bl2_to_bl31_args` with the extents of memory available
619for use by the BL3-2 image. The memory is allocated in the Secure DRAM from the
Dan Handley57de6d72014-02-27 19:46:37 +0000620address defined by the constant `BL32_BASE`. The ARM FVP port currently loads
621the BL3-2 image at the Secure DRAM address `0x6002000`.
Achin Guptaa3050ed2014-02-19 17:52:35 +0000622
Achin Guptae4d084e2014-02-19 17:18:23 +0000623The non-secure memory extents used for loading BL3-3 are also initialized in
624this function. This information is accessible in the `bl33_meminfo` field in
625the `bl31_args` structure pointed to by `bl2_to_bl31_args`.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100626
Harry Liebeld265bd72014-01-31 19:04:10 +0000627This function is also responsible for initializing the storage abstraction layer
628which is used to load further bootloader images.
629
Achin Gupta4f6ad662013-10-25 09:08:21 +0100630
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000631### Function : bl2_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100632
633 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000634 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100635
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000636This function should only be called on the cold boot path. It may execute with
637the MMU and data caches enabled if the platform port does the necessary
638initialization in `bl2_plat_arch_setup()`. It is only called by the primary CPU.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100639
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000640The purpose of this function is to return a pointer to a `meminfo` structure
641populated with the extents of secure RAM available for BL2 to use. See
Achin Gupta4f6ad662013-10-25 09:08:21 +0100642`bl2_early_platform_setup()` above.
643
644
Achin Guptae4d084e2014-02-19 17:18:23 +0000645### Function : bl2_get_bl31_args_ptr() [mandatory]
Harry Liebeld265bd72014-01-31 19:04:10 +0000646
647 Argument : void
Achin Guptae4d084e2014-02-19 17:18:23 +0000648 Return : bl31_args *
Harry Liebeld265bd72014-01-31 19:04:10 +0000649
Achin Guptae4d084e2014-02-19 17:18:23 +0000650BL2 platform code needs to return a pointer to a `bl31_args` structure it will
651use for passing information to BL3-1. The `bl31_args` structure carries the
652following information. This information is used by the `bl2_main()` function to
653load the BL3-2 (if present) and BL3-3 images.
654 - Extents of memory available to the BL3-1 image in the `bl31_meminfo` field
655 - Extents of memory available to the BL3-2 image in the `bl32_meminfo` field
656 - Extents of memory available to the BL3-3 image in the `bl33_meminfo` field
657 - Information about executing the BL3-3 image in the `bl33_image_info` field
658 - Information about executing the BL3-2 image in the `bl32_image_info` field
Harry Liebeld265bd72014-01-31 19:04:10 +0000659
660
Achin Gupta4f6ad662013-10-25 09:08:21 +0100661### Function : init_bl31_mem_layout() [optional]
662
663 Argument : meminfo *, meminfo *, unsigned int
664 Return : void
665
666Each BL stage needs to tell the next stage the amount of secure RAM that is
667available for it to use. For example, as part of handing control to BL2, BL1
668must inform BL2 about the extents of secure RAM that is available for BL2 to
669use. BL2 must do the same when passing control to BL3-1. This information is
670populated in a `meminfo` structure.
671
672Depending upon where BL3-1 has been loaded in secure RAM (determined by
673`BL31_BASE`), BL2 calculates the amount of free memory available for BL3-1 to
674use. BL2 also ensures that BL3-1 is able reclaim memory occupied by BL2. This
675is done because BL2 never executes again after passing control to BL3-1.
676An illustration of how this is done in the ARM FVP port is given in the
677[User Guide], in the section "Memory layout on Base FVP".
678
679
680### Function : plat_get_ns_image_entrypoint() [mandatory]
681
682 Argument : void
683 Return : unsigned long
684
685As previously described, BL2 is responsible for arranging for control to be
686passed to a normal world BL image through BL3-1. This function returns the
687entrypoint of that image, which BL3-1 uses to jump to it.
688
Harry Liebeld265bd72014-01-31 19:04:10 +0000689BL2 is responsible for loading the normal world BL3-3 image (e.g. UEFI).
Achin Gupta4f6ad662013-10-25 09:08:21 +0100690
691
6923.2 Boot Loader Stage 3-1 (BL3-1)
693---------------------------------
694
695During cold boot, the BL3-1 stage is executed only by the primary CPU. This is
696determined in BL1 using the `platform_is_primary_cpu()` function. BL1 passes
697control to BL3-1 at `BL31_BASE`. During warm boot, BL3-1 is executed by all
698CPUs. BL3-1 executes at EL3 and is responsible for:
699
7001. Re-initializing all architectural and platform state. Although BL1 performs
701 some of this initialization, BL3-1 remains resident in EL3 and must ensure
702 that EL3 architectural and platform state is completely initialized. It
703 should make no assumptions about the system state when it receives control.
704
7052. Passing control to a normal world BL image, pre-loaded at a platform-
706 specific address by BL2. BL3-1 uses the `el_change_info` structure that BL2
707 populated in memory to do this.
708
7093. Providing runtime firmware services. Currently, BL3-1 only implements a
710 subset of the Power State Coordination Interface (PSCI) API as a runtime
711 service. See Section 3.3 below for details of porting the PSCI
712 implementation.
713
Achin Gupta35ca3512014-02-19 17:58:33 +00007144. Optionally passing control to the BL3-2 image, pre-loaded at a platform-
715 specific address by BL2. BL3-1 exports a set of apis that allow runtime
716 services to specify the security state in which the next image should be
717 executed and run the corresponding image. BL3-1 uses the `el_change_info`
718 and `meminfo` structure populated by BL2 to do this.
719
Achin Gupta4f6ad662013-10-25 09:08:21 +0100720The following functions must be implemented by the platform port to enable BL3-1
721to perform the above tasks.
722
723
724### Function : bl31_early_platform_setup() [mandatory]
725
726 Argument : meminfo *, void *, unsigned long
727 Return : void
728
729This function executes with the MMU and data caches disabled. It is only called
730by the primary CPU. The arguments to this function are:
731
732* The address of the `meminfo` structure populated by BL2.
733* An opaque pointer that the platform may use as needed.
734* The `MPIDR` of the primary CPU.
735
Achin Guptae4d084e2014-02-19 17:18:23 +0000736The platform can copy the contents of the `meminfo` structure into a private
737variable if the original memory may be subsequently overwritten by BL3-1. The
738reference to this structure is made available to all BL3-1 code through the
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000739`bl31_plat_sec_mem_layout()` function.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100740
Achin Guptae4d084e2014-02-19 17:18:23 +0000741On the ARM FVP port, BL2 passes a pointer to a `bl31_args` structure populated
742in the secure DRAM at address `0x6000000` in the opaque pointer mentioned
743earlier. BL3-1 does not copy this information to internal data structures as it
744guarantees that the secure DRAM memory will not be overwritten. It maintains an
745internal reference to this information in the `bl2_to_bl31_args` variable.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100746
747### Function : bl31_plat_arch_setup() [mandatory]
748
749 Argument : void
750 Return : void
751
752This function executes with the MMU and data caches disabled. It is only called
753by the primary CPU.
754
755The purpose of this function is to perform any architectural initialization
756that varies across platforms, for example enabling the MMU (since the memory
757map differs across platforms).
758
759
760### Function : bl31_platform_setup() [mandatory]
761
762 Argument : void
763 Return : void
764
765This function may execute with the MMU and data caches enabled if the platform
766port does the necessary initialization in `bl31_plat_arch_setup()`. It is only
767called by the primary CPU.
768
769The purpose of this function is to complete platform initialization so that both
770BL3-1 runtime services and normal world software can function correctly.
771
772The ARM FVP port does the following:
773* Initializes the generic interrupt controller.
774* Configures the CLCD controller.
Jeenu Viswambharan1c297bf2014-01-07 10:21:18 +0000775* Initializes counter frequency for CPU's generic timer
Achin Gupta4f6ad662013-10-25 09:08:21 +0100776* Grants access to the system counter timer module
777* Initializes the FVP power controller device
778* Detects the system topology.
779
780
781### Function : bl31_get_next_image_info() [mandatory]
782
Achin Gupta35ca3512014-02-19 17:58:33 +0000783 Argument : unsigned int
Achin Gupta4f6ad662013-10-25 09:08:21 +0100784 Return : el_change_info *
785
786This function may execute with the MMU and data caches enabled if the platform
787port does the necessary initializations in `bl31_plat_arch_setup()`.
788
789This function is called by `bl31_main()` to retrieve information provided by
Achin Gupta35ca3512014-02-19 17:58:33 +0000790BL2 for the next image in the security state specified by the argument. BL3-1
791uses this information to pass control to that image in the specified security
792state. This function must return a pointer to the `el_change_info` structure
793(that was copied during `bl31_early_platform_setup()`) if the image exists. It
794should return NULL otherwise.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100795
796
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000797### Function : bl31_plat_sec_mem_layout() [mandatory]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100798
799 Argument : void
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000800 Return : meminfo *
Achin Gupta4f6ad662013-10-25 09:08:21 +0100801
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000802This function should only be called on the cold boot path. This function may
803execute with the MMU and data caches enabled if the platform port does the
804necessary initializations in `bl31_plat_arch_setup()`. It is only called by the
805primary CPU.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100806
Sandrine Bailleuxee12f6f2013-11-28 14:55:58 +0000807The purpose of this function is to return a pointer to a `meminfo` structure
808populated with the extents of secure RAM available for BL3-1 to use. See
Achin Gupta4f6ad662013-10-25 09:08:21 +0100809`bl31_early_platform_setup()` above.
810
811
Achin Gupta35ca3512014-02-19 17:58:33 +0000812### Function : bl31_plat_get_bl32_mem_layout() [mandatory]
813
814 Argument : void
815 Return : meminfo *
816
817This function should only be called on the cold boot path. This function may
818execute with the MMU and data caches enabled if the platform port does the
819necessary initializations in `bl31_plat_arch_setup()`. It is only called by the
820primary CPU.
821
822The purpose of this function is to return a pointer to a `meminfo` structure
823populated with the extents of memory available for BL3-2 to use. See
824`bl31_early_platform_setup()` above.
825
826
Achin Gupta4f6ad662013-10-25 09:08:21 +01008273.3 Power State Coordination Interface (in BL3-1)
828------------------------------------------------
829
830The ARM Trusted Firmware's implementation of the PSCI API is based around the
831concept of an _affinity instance_. Each _affinity instance_ can be uniquely
832identified in a system by a CPU ID (the processor `MPIDR` is used in the PSCI
833interface) and an _affinity level_. A processing element (for example, a
834CPU) is at level 0. If the CPUs in the system are described in a tree where the
835node above a CPU is a logical grouping of CPUs that share some state, then
836affinity level 1 is that group of CPUs (for example, a cluster), and affinity
837level 2 is a group of clusters (for example, the system). The implementation
838assumes that the affinity level 1 ID can be computed from the affinity level 0
839ID (for example, a unique cluster ID can be computed from the CPU ID). The
840current implementation computes this on the basis of the recommended use of
841`MPIDR` affinity fields in the ARM Architecture Reference Manual.
842
843BL3-1's platform initialization code exports a pointer to the platform-specific
844power management operations required for the PSCI implementation to function
845correctly. This information is populated in the `plat_pm_ops` structure. The
846PSCI implementation calls members of the `plat_pm_ops` structure for performing
847power management operations for each affinity instance. For example, the target
848CPU is specified by its `MPIDR` in a PSCI `CPU_ON` call. The `affinst_on()`
849handler (if present) is called for each affinity instance as the PSCI
850implementation powers up each affinity level implemented in the `MPIDR` (for
851example, CPU, cluster and system).
852
853The following functions must be implemented to initialize PSCI functionality in
854the ARM Trusted Firmware.
855
856
857### Function : plat_get_aff_count() [mandatory]
858
859 Argument : unsigned int, unsigned long
860 Return : unsigned int
861
862This function may execute with the MMU and data caches enabled if the platform
863port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
864called by the primary CPU.
865
866This function is called by the PSCI initialization code to detect the system
867topology. Its purpose is to return the number of affinity instances implemented
868at a given `affinity level` (specified by the first argument) and a given
869`MPIDR` (specified by the second argument). For example, on a dual-cluster
870system where first cluster implements 2 CPUs and the second cluster implements 4
871CPUs, a call to this function with an `MPIDR` corresponding to the first cluster
872(`0x0`) and affinity level 0, would return 2. A call to this function with an
873`MPIDR` corresponding to the second cluster (`0x100`) and affinity level 0,
874would return 4.
875
876
877### Function : plat_get_aff_state() [mandatory]
878
879 Argument : unsigned int, unsigned long
880 Return : unsigned int
881
882This function may execute with the MMU and data caches enabled if the platform
883port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
884called by the primary CPU.
885
886This function is called by the PSCI initialization code. Its purpose is to
887return the state of an affinity instance. The affinity instance is determined by
888the affinity ID at a given `affinity level` (specified by the first argument)
889and an `MPIDR` (specified by the second argument). The state can be one of
890`PSCI_AFF_PRESENT` or `PSCI_AFF_ABSENT`. The latter state is used to cater for
891system topologies where certain affinity instances are unimplemented. For
892example, consider a platform that implements a single cluster with 4 CPUs and
893another CPU implemented directly on the interconnect with the cluster. The
894`MPIDR`s of the cluster would range from `0x0-0x3`. The `MPIDR` of the single
895CPU would be 0x100 to indicate that it does not belong to cluster 0. Cluster 1
896is missing but needs to be accounted for to reach this single CPU in the
897topology tree. Hence it is marked as `PSCI_AFF_ABSENT`.
898
899
900### Function : plat_get_max_afflvl() [mandatory]
901
902 Argument : void
903 Return : int
904
905This function may execute with the MMU and data caches enabled if the platform
906port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
907called by the primary CPU.
908
909This function is called by the PSCI implementation both during cold and warm
910boot, to determine the maximum affinity level that the power management
James Morrisseyba3155b2013-10-29 10:56:46 +0000911operations should apply to. ARMv8-A has support for 4 affinity levels. It is
Achin Gupta4f6ad662013-10-25 09:08:21 +0100912likely that hardware will implement fewer affinity levels. This function allows
913the PSCI implementation to consider only those affinity levels in the system
914that the platform implements. For example, the Base AEM FVP implements two
915clusters with a configurable number of CPUs. It reports the maximum affinity
916level as 1, resulting in PSCI power control up to the cluster level.
917
918
919### Function : platform_setup_pm() [mandatory]
920
921 Argument : plat_pm_ops **
922 Return : int
923
924This function may execute with the MMU and data caches enabled if the platform
925port does the necessary initializations in `bl31_plat_arch_setup()`. It is only
926called by the primary CPU.
927
928This function is called by PSCI initialization code. Its purpose is to export
929handler routines for platform-specific power management actions by populating
930the passed pointer with a pointer to BL3-1's private `plat_pm_ops` structure.
931
932A description of each member of this structure is given below. Please refer to
Ryan Harkin03cb8fb2014-01-15 17:37:25 +0000933the ARM FVP specific implementation of these handlers in [../plat/fvp/plat_pm.c]
Achin Gupta4f6ad662013-10-25 09:08:21 +0100934as an example. A platform port may choose not implement some of the power
935management operations. For example, the ARM FVP port does not implement the
936`affinst_standby()` function.
937
938#### plat_pm_ops.affinst_standby()
939
940Perform the platform-specific setup to enter the standby state indicated by the
941passed argument.
942
943#### plat_pm_ops.affinst_on()
944
945Perform the platform specific setup to power on an affinity instance, specified
946by the `MPIDR` (first argument) and `affinity level` (fourth argument). The
947`state` (fifth argument) contains the current state of that affinity instance
948(ON or OFF). This is useful to determine whether any action must be taken. For
949example, while powering on a CPU, the cluster that contains this CPU might
950already be in the ON state. The platform decides what actions must be taken to
951transition from the current state to the target state (indicated by the power
952management operation).
953
954#### plat_pm_ops.affinst_off()
955
956Perform the platform specific setup to power off an affinity instance in the
957`MPIDR` of the calling CPU. It is called by the PSCI `CPU_OFF` API
958implementation.
959
960The `MPIDR` (first argument), `affinity level` (second argument) and `state`
961(third argument) have a similar meaning as described in the `affinst_on()`
962operation. They are used to identify the affinity instance on which the call
963is made and its current state. This gives the platform port an indication of the
964state transition it must make to perform the requested action. For example, if
965the calling CPU is the last powered on CPU in the cluster, after powering down
966affinity level 0 (CPU), the platform port should power down affinity level 1
967(the cluster) as well.
968
969This function is called with coherent stacks. This allows the PSCI
970implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +0000971stale stack state after turning off the caches. On ARMv8-A cache hits do not
972occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +0100973
974#### plat_pm_ops.affinst_suspend()
975
976Perform the platform specific setup to power off an affinity instance in the
977`MPIDR` of the calling CPU. It is called by the PSCI `CPU_SUSPEND` API
978implementation.
979
980The `MPIDR` (first argument), `affinity level` (third argument) and `state`
981(fifth argument) have a similar meaning as described in the `affinst_on()`
982operation. They are used to identify the affinity instance on which the call
983is made and its current state. This gives the platform port an indication of the
984state transition it must make to perform the requested action. For example, if
985the calling CPU is the last powered on CPU in the cluster, after powering down
986affinity level 0 (CPU), the platform port should power down affinity level 1
987(the cluster) as well.
988
989The difference between turning an affinity instance off versus suspending it
990is that in the former case, the affinity instance is expected to re-initialize
991its state when its next powered on (see `affinst_on_finish()`). In the latter
992case, the affinity instance is expected to save enough state so that it can
993resume execution by restoring this state when its powered on (see
994`affinst_suspend_finish()`).
995
996This function is called with coherent stacks. This allows the PSCI
997implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +0000998stale stack state after turning off the caches. On ARMv8-A cache hits do not
999occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001000
1001#### plat_pm_ops.affinst_on_finish()
1002
1003This function is called by the PSCI implementation after the calling CPU is
1004powered on and released from reset in response to an earlier PSCI `CPU_ON` call.
1005It performs the platform-specific setup required to initialize enough state for
1006this CPU to enter the normal world and also provide secure runtime firmware
1007services.
1008
1009The `MPIDR` (first argument), `affinity level` (second argument) and `state`
1010(third argument) have a similar meaning as described in the previous operations.
1011
1012This function is called with coherent stacks. This allows the PSCI
1013implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +00001014stale stack state after turning off the caches. On ARMv8-A cache hits do not
1015occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001016
1017#### plat_pm_ops.affinst_on_suspend()
1018
1019This function is called by the PSCI implementation after the calling CPU is
1020powered on and released from reset in response to an asynchronous wakeup
1021event, for example a timer interrupt that was programmed by the CPU during the
1022`CPU_SUSPEND` call. It performs the platform-specific setup required to
1023restore the saved state for this CPU to resume execution in the normal world
1024and also provide secure runtime firmware services.
1025
1026The `MPIDR` (first argument), `affinity level` (second argument) and `state`
1027(third argument) have a similar meaning as described in the previous operations.
1028
1029This function is called with coherent stacks. This allows the PSCI
1030implementation to flush caches at a given affinity level without running into
James Morrisseyba3155b2013-10-29 10:56:46 +00001031stale stack state after turning off the caches. On ARMv8-A cache hits do not
1032occur after the cache has been turned off.
Achin Gupta4f6ad662013-10-25 09:08:21 +01001033
1034BL3-1 platform initialization code must also detect the system topology and
1035the state of each affinity instance in the topology. This information is
1036critical for the PSCI runtime service to function correctly. More details are
1037provided in the description of the `plat_get_aff_count()` and
1038`plat_get_aff_state()` functions above.
1039
1040
Harry Liebela960f282013-12-12 16:03:44 +000010414. C Library
1042-------------
1043
1044To avoid subtle toolchain behavioral dependencies, the header files provided
1045by the compiler are not used. The software is built with the `-nostdinc` flag
1046to ensure no headers are included from the toolchain inadvertently. Instead the
1047required headers are included in the ARM Trusted Firmware source tree. The
1048library only contains those C library definitions required by the local
1049implementation. If more functionality is required, the needed library functions
1050will need to be added to the local implementation.
1051
1052Versions of [FreeBSD] headers can be found in `include/stdlib`. Some of these
1053headers have been cut down in order to simplify the implementation. In order to
1054minimize changes to the header files, the [FreeBSD] layout has been maintained.
1055The generic C library definitions can be found in `include/stdlib` with more
1056system and machine specific declarations in `include/stdlib/sys` and
1057`include/stdlib/machine`.
1058
1059The local C library implementations can be found in `lib/stdlib`. In order to
1060extend the C library these files may need to be modified. It is recommended to
1061use a release version of [FreeBSD] as a starting point.
1062
1063The C library header files in the [FreeBSD] source tree are located in the
1064`include` and `sys/sys` directories. [FreeBSD] machine specific definitions
1065can be found in the `sys/<machine-type>` directories. These files define things
1066like 'the size of a pointer' and 'the range of an integer'. Since an AArch64
1067port for [FreeBSD] does not yet exist, the machine specific definitions are
1068based on existing machine types with similar properties (for example SPARC64).
1069
1070Where possible, C library function implementations were taken from [FreeBSD]
1071as found in the `lib/libc` directory.
1072
1073A copy of the [FreeBSD] sources can be downloaded with `git`.
1074
1075 git clone git://github.com/freebsd/freebsd.git -b origin/release/9.2.0
1076
1077
Harry Liebeld265bd72014-01-31 19:04:10 +000010785. Storage abstraction layer
1079-----------------------------
1080
1081In order to improve platform independence and portability an storage abstraction
1082layer is used to load data from non-volatile platform storage.
1083
1084Each platform should register devices and their drivers via the Storage layer.
1085These drivers then need to be initialized by bootloader phases as
1086required in their respective `blx_platform_setup()` functions. Currently
1087storage access is only required by BL1 and BL2 phases. The `load_image()`
1088function uses the storage layer to access non-volatile platform storage.
1089
1090It is mandatory to implement at least one storage driver. For the FVP the
1091Firmware Image Package(FIP) driver is provided as the default means to load data
1092from storage (see the "Firmware Image Package" section in the [User Guide]).
1093The storage layer is described in the header file `include/io_storage.h`. The
1094implementation of the common library is in `lib/io_storage.c` and the driver
1095files are located in `drivers/io/`.
1096
1097Each IO driver must provide `io_dev_*` structures, as described in
1098`drivers/io/io_driver.h`. These are returned via a mandatory registration
1099function that is called on platform initialization. The semi-hosting driver
1100implementation in `io_semihosting.c` can be used as an example.
1101
1102The Storage layer provides mechanisms to initialize storage devices before
1103IO operations are called. The basic operations supported by the layer
1104include `open()`, `close()`, `read()`, `write()`, `size()` and `seek()`.
1105Drivers do not have to implement all operations, but each platform must
1106provide at least one driver for a device capable of supporting generic
1107operations such as loading a bootloader image.
1108
1109The current implementation only allows for known images to be loaded by the
1110firmware. These images are specified by using their names, as defined in the
1111`platform.h` file. The platform layer (`plat_get_image_source()`) then returns
1112a reference to a device and a driver-specific `spec` which will be understood
1113by the driver to allow access to the image data.
1114
1115The layer is designed in such a way that is it possible to chain drivers with
1116other drivers. For example, file-system drivers may be implemented on top of
1117physical block devices, both represented by IO devices with corresponding
1118drivers. In such a case, the file-system "binding" with the block device may
1119be deferred until the file-system device is initialised.
1120
1121The abstraction currently depends on structures being statically allocated
1122by the drivers and callers, as the system does not yet provide a means of
1123dynamically allocating memory. This may also have the affect of limiting the
1124amount of open resources per driver.
1125
1126
Achin Gupta4f6ad662013-10-25 09:08:21 +01001127- - - - - - - - - - - - - - - - - - - - - - - - - -
1128
Dan Handleye83b0ca2014-01-14 18:17:09 +00001129_Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._
Achin Gupta4f6ad662013-10-25 09:08:21 +01001130
1131
1132[User Guide]: user-guide.md
Harry Liebela960f282013-12-12 16:03:44 +00001133[FreeBSD]: http://www.freebsd.org
Achin Gupta4f6ad662013-10-25 09:08:21 +01001134
1135[../plat/common/aarch64/platform_helpers.S]: ../plat/common/aarch64/platform_helpers.S
1136[../plat/fvp/platform.h]: ../plat/fvp/platform.h
Ryan Harkin03cb8fb2014-01-15 17:37:25 +00001137[../plat/fvp/aarch64/plat_common.c]: ../plat/fvp/aarch64/plat_common.c
1138[../plat/fvp/plat_pm.c]: ../plat/fvp/plat_pm.c
Achin Gupta4f6ad662013-10-25 09:08:21 +01001139[../include/runtime_svc.h]: ../include/runtime_svc.h