diff options
Diffstat (limited to 'docs/porting-guide.md')
| -rw-r--r-- | docs/porting-guide.md | 124 |
1 files changed, 85 insertions, 39 deletions
diff --git a/docs/porting-guide.md b/docs/porting-guide.md index bd1b4489..f8d0ff38 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -76,12 +76,12 @@ either mandatory or optional. A platform port must enable the Memory Management Unit (MMU) as well as the instruction and data caches for each BL stage. Setting up the translation tables is the responsibility of the platform port because memory maps differ -across platforms. A memory translation library (see `lib/aarch64/xlat_helpers.c` -and `lib/aarch64/xlat_tables.c`) is provided to help in this setup. Note that -although this library supports non-identity mappings, this is intended only for -re-mapping peripheral physical addresses and allows platforms with high I/O -addresses to reduce their virtual address space. All other addresses -corresponding to code and data must currently use an identity mapping. +across platforms. A memory translation library (see `lib/aarch64/xlat_tables.c`) +is provided to help in this setup. Note that although this library supports +non-identity mappings, this is intended only for re-mapping peripheral physical +addresses and allows platforms with high I/O addresses to reduce their virtual +address space. All other addresses corresponding to code and data must currently +use an identity mapping. In ARM standard platforms, each BL stage configures the MMU in the platform-specific architecture setup function, `blX_plat_arch_setup()`, and uses @@ -230,11 +230,6 @@ platform port to define additional platform porting constants in Defines the maximum address in secure RAM that the BL31 image can occupy. -* **#define : NS_IMAGE_OFFSET** - - Defines the base address in non-secure DRAM where BL2 loads the BL33 binary - image. Must be aligned on a page-size boundary. - For every image, the platform must define individual identifiers that will be used by BL1 or BL2 to load the corresponding image into memory from non-volatile storage. For the sake of performance, integer numbers will be used as @@ -854,8 +849,16 @@ BL1 to perform the above tasks. This function executes with the MMU and data caches disabled. It is only called by the primary CPU. -In ARM standard platforms, this function initializes the console and enables -snoop requests into the primary CPU's cluster. +On ARM standard platforms, this function: + +* Enables a secure instance of SP805 to act as the Trusted Watchdog. + +* Initializes a UART (PL011 console), which enables access to the `printf` + family of functions in BL1. + +* Enables issuing of snoop and DVM (Distributed Virtual Memory) requests to + the CCI slave interface corresponding to the cluster that includes the + primary CPU. ### Function : bl1_plat_arch_setup() [mandatory] @@ -1039,10 +1042,10 @@ using the `platform_is_primary_cpu()` function. BL1 passed control to BL2 at structure in memory provided by the platform with information about how BL31 should pass control to the BL32 image. -5. Loading the normal world BL33 binary image into non-secure DRAM from - platform storage and arranging for BL31 to pass control to this image. This - address is determined using the `plat_get_ns_image_entrypoint()` function - described below. +5. (Optional) Loading the normal world BL33 binary image (if not loaded by + other means) into non-secure DRAM from platform storage and arranging for + BL31 to pass control to this image. This address is determined using the + `plat_get_ns_image_entrypoint()` function described below. 6. BL2 populates an `entry_point_info` structure in memory provided by the platform with information about how BL31 should pass control to the @@ -1061,15 +1064,19 @@ This function executes with the MMU and data caches disabled. It is only called by the primary CPU. The arguments to this function is the address of the `meminfo` structure populated by BL1. -The platform must copy the contents of the `meminfo` structure into a private +The platform may copy the contents of the `meminfo` structure into a private variable as the original memory may be subsequently overwritten by BL2. The copied structure is made available to all BL2 code through the `bl2_plat_sec_mem_layout()` function. -In ARM standard platforms, this function also initializes the storage -abstraction layer used to load further bootloader images. It is necessary to do -this early on platforms with a SCP_BL2 image, since the later -`bl2_platform_setup` must be done after SCP_BL2 is loaded. +On ARM standard platforms, this function also: + +* Initializes a UART (PL011 console), which enables access to the `printf` + family of functions in BL2. + +* Initializes the storage abstraction layer used to load further bootloader + images. It is necessary to do this early on platforms with a SCP_BL2 image, + since the later `bl2_platform_setup` must be done after SCP_BL2 is loaded. ### Function : bl2_plat_arch_setup() [mandatory] @@ -1081,9 +1088,9 @@ This function executes with the MMU and data caches disabled. It is only called by the primary CPU. The purpose of this function is to perform any architectural initialization -that varies across platforms, for example enabling the MMU (since the memory -map differs across platforms). +that varies across platforms. +On ARM standard platforms, this function enables the MMU. ### Function : bl2_platform_setup() [mandatory] @@ -1210,6 +1217,10 @@ This function is called after loading BL33 image and it can be used to overwrite the entry point set by loader and also set the security state and SPSR which represents the entry point system state for BL33. +In the preloaded BL33 alternative boot flow, this function is called after +populating its entry point address. It is passed a null pointer as its first +argument in this case. + ### Function : bl2_plat_get_bl32_meminfo() [mandatory] @@ -1231,6 +1242,9 @@ BL33 image. The meminfo provided by this is used by load_image() to validate whether the BL33 image can be loaded with in the given memory from the given base. +This function isn't needed if either `BL33_BASE` or `EL3_PAYLOAD_BASE` build +options are used. + ### Function : bl2_plat_flush_bl31_params() [mandatory] Argument : void @@ -1245,7 +1259,7 @@ later Bootloader stages with MMU off ### Function : plat_get_ns_image_entrypoint() [mandatory] Argument : void - Return : unsigned long + Return : uintptr_t As previously described, BL2 is responsible for arranging for control to be passed to a normal world BL image through BL31. This function returns the @@ -1253,6 +1267,9 @@ entrypoint of that image, which BL31 uses to jump to it. BL2 is responsible for loading the normal world BL33 image (e.g. UEFI). +This function isn't needed if either `BL33_BASE` or `EL3_PAYLOAD_BASE` build +options are used. + 3.3 FWU Boot Loader Stage 2 (BL2U) ---------------------------------- @@ -1284,7 +1301,7 @@ This function executes with the MMU and data caches disabled. It is only called by the primary CPU. The arguments to this function is the address of the `meminfo` structure and platform specific info provided by BL1. -The platform must copy the contents of the `mem_info` and `plat_info` into +The platform may copy the contents of the `mem_info` and `plat_info` into private storage as the original memory may be subsequently overwritten by BL2U. On ARM CSS platforms `plat_info` is interpreted as an `image_info_t` structure, @@ -1386,7 +1403,14 @@ to the platform data also needs to be saved. In ARM standard platforms, BL2 passes a pointer to a `bl31_params` structure in BL2 memory. BL31 copies the information in this pointer to internal data -structures. +structures. It also performs the following: + +* Initialize a UART (PL011 console), which enables access to the `printf` + family of functions in BL31. + +* Enable issuing of snoop and DVM (Distributed Virtual Memory) requests to the + CCI slave interface corresponding to the cluster that includes the primary + CPU. ### Function : bl31_plat_arch_setup() [mandatory] @@ -1398,8 +1422,9 @@ This function executes with the MMU and data caches disabled. It is only called by the primary CPU. The purpose of this function is to perform any architectural initialization -that varies across platforms, for example enabling the MMU (since the memory -map differs across platforms). +that varies across platforms. + +On ARM standard platforms, this function enables the MMU. ### Function : bl31_platform_setup() [mandatory] @@ -1414,12 +1439,32 @@ called by the primary CPU. The purpose of this function is to complete platform initialization so that both BL31 runtime services and normal world software can function correctly. -In ARM standard platforms, this function does the following: -* Initializes the generic interrupt controller. -* Enables system-level implementation of the generic timer counter. -* Grants access to the system counter timer module -* Initializes the power controller device -* Detects the system topology. +On ARM standard platforms, this function does the following: + +* Initialize the generic interrupt controller. + + Depending on the GIC driver selected by the platform, the appropriate GICv2 + or GICv3 initialization will be done, which mainly consists of: + + - Enable secure interrupts in the GIC CPU interface. + - Disable the legacy interrupt bypass mechanism. + - Configure the priority mask register to allow interrupts of all priorities + to be signaled to the CPU interface. + - Mark SGIs 8-15 and the other secure interrupts on the platform as secure. + - Target all secure SPIs to CPU0. + - Enable these secure interrupts in the GIC distributor. + - Configure all other interrupts as non-secure. + - Enable signaling of secure interrupts in the GIC distributor. + +* Enable system-level implementation of the generic timer counter through the + memory mapped interface. + +* Grant access to the system counter timer module + +* Initialize the power controller device. + + In particular, initialise the locks that prevent concurrent accesses to the + power controller device. ### Function : bl31_plat_runtime_setup() [optional] @@ -1926,9 +1971,10 @@ build system. * **NEED_BL33** By default, this flag is defined `yes` by the build system and `BL33` - build option should be supplied as a build option. The platform has the option - of excluding the BL33 image in the `fip` image by defining this flag to - `no`. + build option should be supplied as a build option. The platform has the + option of excluding the BL33 image in the `fip` image by defining this flag + to `no`. If any of the options `EL3_PAYLOAD_BASE` or `BL33_BASE` are used, + this flag will be set to `no` automatically. 5. C Library ------------- @@ -2020,7 +2066,7 @@ amount of open resources per driver. - - - - - - - - - - - - - - - - - - - - - - - - - - -_Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._ +_Copyright (c) 2013-2016, ARM Limited and Contributors. All rights reserved._ [ARM GIC Architecture Specification 2.0]: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html |