_START__` Start address of a given section named `

`. * `__

_END__` End address of a given section named `

`. If there is an alignment constraint on the section's end address then `__

_END__` corresponds to the end address of the section's actual contents, rounded up to the right boundary. Refer to the value of `__

_UNALIGNED_END__` to know the actual end address of the section's contents. * `__

_UNALIGNED_END__` End address of a given section named `

` without any padding or rounding up due to some alignment constraint. * `__

_SIZE__` Size (in bytes) of a given section named `

`. If there is an alignment constraint on the section's end address then `__

_SIZE__` corresponds to the size of the section's actual contents, rounded up to the right boundary. In other words, `__

_SIZE__ = __

_END__ - _

_START__`. Refer to the value of `__

_UNALIGNED_SIZE__` to know the actual size of the section's contents. * `__

_UNALIGNED_SIZE__` Size (in bytes) of a given section named `

` without any padding or rounding up due to some alignment constraint. In other words, `__

_UNALIGNED_SIZE__ = __

_UNALIGNED_END__ - __

_START__`. Some of the linker symbols are mandatory as the trusted firmware code relies on them to be defined. They are listed in the following subsections. Some of them must be provided for each bootloader stage and some are specific to a given bootloader stage. The linker scripts define some extra, optional symbols. They are not actually used by any code but they help in undertanding the bootloader images' memory layout as they are easy to spot in the link map files. #### Common linker symbols Early setup code needs to know the extents of the BSS section to zero-initialise it before executing any C code. The following linker symbols are defined for this purpose: * `__BSS_START__` This address must be aligned on a 16-byte boundary. * `__BSS_SIZE__` Similarly, the coherent memory section must be zero-initialised. Also, the MMU setup code needs to know the extents of this section to set the right memory attributes for it. The following linker symbols are defined for this purpose: * `__COHERENT_RAM_START__` This address must be aligned on a page-size boundary. * `__COHERENT_RAM_END__` This address must be aligned on a page-size boundary. * `__COHERENT_RAM_UNALIGNED_SIZE__` #### BL1's linker symbols BL1's early setup code needs to know the extents of the .data section to relocate it from ROM to RAM before executing any C code. The following linker symbols are defined for this purpose: * `__DATA_ROM_START__` This address must be aligned on a 16-byte boundary. * `__DATA_RAM_START__` This address must be aligned on a 16-byte boundary. * `__DATA_SIZE__` BL1's platform setup code needs to know the extents of its read-write data region to figure out its memory layout. The following linker symbols are defined for this purpose: * `__BL1_RAM_START__` This is the start address of BL1 RW data. * `__BL1_RAM_END__` This is the end address of BL1 RW data. #### BL2's and BL3-1's linker symbols Both BL2 and BL3-1 need to know the extents of their read-only section to set the right memory attributes for this memory region in their MMU setup code. The following linker symbols are defined for this purpose: * `__RO_START__` * `__RO_END__` #### How to choose the right base address for each bootloader stage image The current implementation of the image loader has some limitations. It is designed to load images dynamically, at a load address chosen to minimize memory fragmentation. The chosen image location can be either at the top or the bottom of free memory. However, until this feature is fully functional, the code also contains support for loading images at a link-time fixed address. BL1 is always loaded at address `0x0`. BL2 and BL3-1 are loaded at specified locations in Trusted SRAM. The lack of dynamic image loader support means these load addresses must currently be adjusted as the code grows. The individual images must be linked against their ultimate runtime locations. BL2 is loaded near the top of the Trusted SRAM. BL3-1 is loaded between BL1 and BL2. All three images are resident concurrently in Trusted RAM during boot so overlaps are not permitted. The image end addresses can be determined from the link map files of the different images. These are the `build///bl/bl.map` files, with `` the stage bootloader. * `bl1.map` link map file provides `__BL1_RAM_END__` address. * `bl2.map` link map file provides `__BL2_END__` address. * `bl31.map` link map file provides `__BL31_END__` address. To prevent images from overlapping each other, the following constraints must be enforced: 1. `__BL1_RAM_END__ <= BL31_BASE` 2. `__BL31_END__ <= BL2_BASE` 3. `__BL2_END__ <= ()` This is illustrated by the following memory layout diagram: +----------+ 0x04040000 | | |----------| __BL2_END__ | BL2 | |----------| BL2_BASE | | |----------| __BL31_END__ | BL31 | |----------| BL31_BASE | | |----------| __BL1_RAM_END__ | BL1 (rw) | +----------+ 0x04000000 Overlaps are detected during image linking as follows. Constraint 1 is enforced by BL1's linker script. If it is violated then the linker will report an error while building BL1 to indicate that it doesn't fit: aarch64-none-elf-ld: BL31 image overlaps BL1 image. This error means that the BL3-1 base address needs to be incremented. Ensure that the new memory layout still obeys all constraints. Constraint 2 is enforced by BL3-1's linker script. If it is violated then the linker will report an error while building BL3-1 to indicate that it doesn't fit: aarch64-none-elf-ld: BL31 image overlaps BL2 image. This error can either mean that the BL3-1 base address needs to be decremented or that BL2 base address needs to be incremented. Ensure that the new memory layout still obeys all constraints. Constraint 3 is enforced by BL2's linker script. If it is violated then the linker will report an error while building BL2 to indicate that it doesn't fit. For example: aarch64-none-elf-ld: address 0x40400c8 of bl2.elf section `.bss' is not within region `RAM' This error means that the BL2 base address needs to be decremented. Ensure that the new memory layout still obeys all constraints. Since constraint checks are scattered across linker scripts, it is required to `make clean` prior to building to ensure that all possible overlapping scenarios are checked. The current implementation of the image loader can result in wasted space because of the simplified data structure used to represent the extents of free memory. For example, to load BL2 at address `0x0402D000`, the resulting memory layout should be as follows: ------------ 0x04040000 | | <- Free space (1) |----------| | BL2 | |----------| BL2_BASE (0x0402D000) | | <- Free space (2) |----------| | BL1 | ------------ 0x04000000 In the current implementation, we need to specify whether BL2 is loaded at the top or bottom of the free memory. BL2 is top-loaded so in the example above, the free space (1) above BL2 is hidden, resulting in the following view of memory: ------------ 0x04040000 | | | | | BL2 | |----------| BL2_BASE (0x0402D000) | | <- Free space (2) |----------| | BL1 | ------------ 0x04000000 BL3-1 is bottom-loaded above BL1. For example, if BL3-1 is bottom-loaded at `0x0400E000`, the memory layout should look like this: ------------ 0x04040000 | | | | | BL2 | |----------| BL2_BASE (0x0402D000) | | <- Free space (2) | | |----------| | | | BL31 | |----------| BL31_BASE (0x0400E000) | | <- Free space (3) |----------| | BL1 | ------------ 0x04000000 But the free space (3) between BL1 and BL3-1 is wasted, resulting in the following view: ------------ 0x04040000 | | | | | BL2 | |----------| BL2_BASE (0x0402D000) | | <- Free space (2) | | |----------| | | | | | BL31 | BL31_BASE (0x0400E000) | | |----------| | BL1 | ------------ 0x04000000 ### Code Structure Trusted Firmware code is logically divided between the three boot loader stages mentioned in the previous sections. The code is also divided into the following categories (present as directories in the source code): * **Architecture specific.** This could be AArch32 or AArch64. * **Platform specific.** Choice of architecture specific code depends upon the platform. * **Common code.** This is platform and architecture agnostic code. * **Library code.** This code comprises of functionality commonly used by all other code. * **Stage specific.** Code specific to a boot stage. * **Drivers.** Each boot loader stage uses code from one or more of the above mentioned categories. Based upon the above, the code layout looks like this: Directory Used by BL1? Used by BL2? Used by BL3? bl1 Yes No No bl2 No Yes No bl31 No No Yes arch Yes Yes Yes plat Yes Yes Yes drivers Yes No Yes common Yes Yes Yes lib Yes Yes Yes All assembler files have the `.S` extension. The linker source files for each boot stage have the extension `.ld.S`. These are processed by GCC to create the linker scripts which have the extension `.ld`. FDTs provide a description of the hardware platform and are used by the Linux kernel at boot time. These can be found in the `fdts` directory. 4. References -------------- 1. Trusted Board Boot Requirements CLIENT PDD (ARM DEN 0006B-5). Available under NDA through your ARM account representative. 2. [Power State Coordination Interface PDD (ARM DEN 0022B.b)][PSCI]. 3. [SMC Calling Convention PDD (ARM DEN 0028A)][SMCCC]. - - - - - - - - - - - - - - - - - - - - - - - - - - _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._ [Change Log]: change-log.md [ARM FVP website]: http://www.arm.com/fvp [Linaro Toolchain]: http://releases.linaro.org/13.09/components/toolchain/binaries/ [EDK2]: http://github.com/tianocore/edk2 [DS-5]: http://www.arm.com/products/tools/software-tools/ds-5/index.php [PSCI]: http://infocenter.arm.com/help/topic/com.arm.doc.den0022b/index.html "Power State Coordination Interface PDD (ARM DEN 0022B.b)" [SMCCC]: http://infocenter.arm.com/help/topic/com.arm.doc.den0028a/index.html "SMC Calling Convention PDD (ARM DEN 0028A)"