diff options
Diffstat (limited to 'docs/porting-guide.md')
| -rw-r--r-- | docs/porting-guide.md | 84 |
1 files changed, 44 insertions, 40 deletions
diff --git a/docs/porting-guide.md b/docs/porting-guide.md index 5dca6fd5..868eb338 100644 --- a/docs/porting-guide.md +++ b/docs/porting-guide.md @@ -81,7 +81,7 @@ for the firmware to work correctly. Each platform must export a header file of this name with the following constants defined. In the ARM FVP port, this file is found in -[../plat/fvp/platform.h]. +[plat/fvp/platform.h]. * **#define : PLATFORM_LINKER_FORMAT** @@ -96,7 +96,14 @@ constants defined. In the ARM FVP port, this file is found in * **#define : PLATFORM_STACK_SIZE** Defines the normal stack memory available to each CPU. This constant is used - by `platform_set_stack()`. + by [plat/common/aarch64/platform_mp_stack.S] and + [plat/common/aarch64/platform_up_stack.S]. + +* **#define : PCPU_DV_MEM_STACK_SIZE** + + Defines the coherent stack memory available to each CPU. This constant is used + by [plat/common/aarch64/platform_mp_stack.S] and + [plat/common/aarch64/platform_up_stack.S]. * **#define : FIRMWARE_WELCOME_STR** @@ -192,21 +199,7 @@ constants defined. In the ARM FVP port, this file is found in The following mandatory modifications may be implemented in any file the implementer chooses. In the ARM FVP port, they are implemented in -[../plat/fvp/aarch64/plat_common.c]. - -* **Variable : unsigned char platform_normal_stacks[X][Y]** - - where X = PLATFORM_STACK_SIZE - and Y = PLATFORM_CORE_COUNT - - Each platform must allocate a block of memory with Normal Cacheable, Write - back, Write allocate and Inner Shareable attributes aligned to the size (in - bytes) of the largest cache line amongst all caches implemented in the - system. A pointer to this memory should be exported with the name - `platform_normal_stacks`. This pointer is used by the common platform helper - functions `platform_set_stack()` (to allocate a stack for each CPU in the - platform) & `platform_get_stack()` (to return the base address of that - stack) (see [../plat/common/aarch64/platform_helpers.S]). +[plat/fvp/aarch64/plat_common.c]. * **Function : uint64_t plat_get_syscnt_freq(void)** @@ -216,6 +209,7 @@ the implementer chooses. In the ARM FVP port, they are implemented in In the ARM FVP port, it returns the base frequency of the system counter, which is retrieved from the first entry in the frequency modes table. + 2.2 Common optional modifications --------------------------------- @@ -253,13 +247,18 @@ certain operations like: * Flushing caches prior to powering down a CPU or cluster. Each BL stage allocates this coherent stack memory for each CPU in the -`tzfw_coherent_mem` section. A pointer to this memory (`pcpu_dv_mem_stack`) is -used by this function to allocate a coherent stack for each CPU. A CPU is -identified by its `MPIDR`, which is passed as an argument to this function. +`tzfw_coherent_mem` section. -The size of the stack allocated to each CPU is specified by the constant +This function sets the current stack pointer to the coherent stack that +has been allocated for the CPU specified by MPIDR. For BL images that only +require a stack for the primary CPU the parameter is ignored. The size of +the stack allocated to each CPU is specified by the platform defined constant `PCPU_DV_MEM_STACK_SIZE`. +Common implementations of this function for the UP and MP BL images are +provided in [plat/common/aarch64/platform_up_stack.S] and +[plat/common/aarch64/platform_mp_stack.S] + ### Function : platform_is_primary_cpu() @@ -277,13 +276,15 @@ return value indicates that the CPU is the primary CPU. Argument : unsigned long Return : void -This function uses the `platform_normal_stacks` pointer variable to allocate -stacks to each CPU. Further details are given in the description of the -`platform_normal_stacks` variable below. A CPU is identified by its `MPIDR`, -which is passed as the argument. +This function sets the current stack pointer to the normal memory stack that +has been allocated for the CPU specificed by MPIDR. For BL images that only +require a stack for the primary CPU the parameter is ignored. The size of +the stack allocated to each CPU is specified by the platform defined constant +`PLATFORM_STACK_SIZE`. -The size of the stack allocated to each CPU is specified by the platform defined -constant `PLATFORM_STACK_SIZE`. +Common implementations of this function for the UP and MP BL images are +provided in [plat/common/aarch64/platform_up_stack.S] and +[plat/common/aarch64/platform_mp_stack.S] ### Function : platform_get_stack() @@ -291,13 +292,15 @@ constant `PLATFORM_STACK_SIZE`. Argument : unsigned long Return : unsigned long -This function uses the `platform_normal_stacks` pointer variable to return the -base address of the stack memory reserved for a CPU. Further details are given -in the description of the `platform_normal_stacks` variable below. A CPU is -identified by its `MPIDR`, which is passed as the argument. +This function returns the base address of the normal memory stack that +has been allocated for the CPU specificed by MPIDR. For BL images that only +require a stack for the primary CPU the parameter is ignored. The size of +the stack allocated to each CPU is specified by the platform defined constant +`PLATFORM_STACK_SIZE`. -The size of the stack allocated to each CPU is specified by the platform defined -constant `PLATFORM_STACK_SIZE`. +Common implementations of this function for the UP and MP BL images are +provided in [plat/common/aarch64/platform_up_stack.S] and +[plat/common/aarch64/platform_mp_stack.S] ### Function : plat_report_exception() @@ -319,7 +322,7 @@ The default implementation doesn't do anything, to avoid making assumptions about the way the platform displays its status information. This function receives the exception type as its argument. Possible values for -exceptions types are listed in the [../include/runtime_svc.h] header file. Note +exceptions types are listed in the [include/runtime_svc.h] header file. Note that these constants are not related to any architectural exception code; they are just an ARM Trusted Firmware convention. @@ -933,7 +936,7 @@ handler routines for platform-specific power management actions by populating the passed pointer with a pointer to BL3-1's private `plat_pm_ops` structure. A description of each member of this structure is given below. Please refer to -the ARM FVP specific implementation of these handlers in [../plat/fvp/plat_pm.c] +the ARM FVP specific implementation of these handlers in [plat/fvp/plat_pm.c] as an example. A platform port may choose not implement some of the power management operations. For example, the ARM FVP port does not implement the `affinst_standby()` function. @@ -1135,8 +1138,9 @@ _Copyright (c) 2013-2014, ARM Limited and Contributors. All rights reserved._ [User Guide]: user-guide.md [FreeBSD]: http://www.freebsd.org -[../plat/common/aarch64/platform_helpers.S]: ../plat/common/aarch64/platform_helpers.S -[../plat/fvp/platform.h]: ../plat/fvp/platform.h -[../plat/fvp/aarch64/plat_common.c]: ../plat/fvp/aarch64/plat_common.c -[../plat/fvp/plat_pm.c]: ../plat/fvp/plat_pm.c -[../include/runtime_svc.h]: ../include/runtime_svc.h +[plat/common/aarch64/platform_mp_stack.S]: ../plat/common/aarch64/platform_mp_stack.S +[plat/common/aarch64/platform_up_stack.S]: ../plat/common/aarch64/platform_up_stack.S +[plat/fvp/platform.h]: ../plat/fvp/platform.h +[plat/fvp/aarch64/plat_common.c]: ../plat/fvp/aarch64/plat_common.c +[plat/fvp/plat_pm.c]: ../plat/fvp/plat_pm.c +[include/runtime_svc.h]: ../include/runtime_svc.h |