aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorAndrew Thoelke <andrew.thoelke@arm.com>2014-03-20 10:48:23 +0000
committerAndrew Thoelke <andrew.thoelke@arm.com>2014-04-15 15:49:29 +0100
commit2bf28e620a6f05700753a2b45a888c6623e20723 (patch)
treec35374e36508ddf0c10324e9b511c983655213e4 /docs
parent9c2c763d22469b0f73d76469442b474c08497e7a (diff)
downloadarm-trusted-firmware-2bf28e620a6f05700753a2b45a888c6623e20723.tar.gz
Allocate single stacks for BL1 and BL2
The BL images share common stack management code which provides one coherent and one cacheable stack for every CPU. BL1 and BL2 just execute on the primary CPU during boot and do not require the additional CPU stacks. This patch provides separate stack support code for UP and MP images, substantially reducing the RAM usage for BL1 and BL2 for the FVP platform. This patch also provides macros for declaring stacks and calculating stack base addresses to improve consistency where this has to be done in the firmware. The stack allocation source files are now included via platform.mk rather than the common BLx makefiles. This allows each platform to select the appropriate MP/UP stack support for each BL image. Each platform makefile must be updated when including this commit. Fixes ARM-software/tf-issues#76 Change-Id: Ia251f61b8148ffa73eae3f3711f57b1ffebfa632
Diffstat (limited to 'docs')
-rw-r--r--docs/porting-guide.md84
1 files changed, 44 insertions, 40 deletions
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index 5dca6fd..868eb33 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