Merge pull request #310 from sandrine-bailleux/sb/tf-issue-304-phase1

Enhance BL3-1 entrypoint handling to support non-TF boot firmware - Phase 1

3 files changed, 18 insertions, 39 deletions

diff --git a/docs/firmware-design.md b/docs/firmware-design.md
index 70737b53..95bb8f1f 100644
--- a/docs/firmware-design.md
+++ b/docs/firmware-design.md
@@ -184,7 +184,7 @@ BL1 performs minimal architectural initialization as follows.
 
 #### Platform initialization
 
-BL1 enables issuing of snoop and DVM (Distributed Virtual Memory) requests from
+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. BL1 also initializes a UART (PL011 console), which enables access
 to the `printf` family of functions in BL1.
@@ -334,7 +334,9 @@ the clock frequency of the system counter, which is provided by the platform.
 BL3-1 performs detailed platform initialization, which enables normal world
 software to function correctly. It also retrieves entrypoint information for
 the BL3-3 image loaded by BL2 from the platform defined memory address populated
-by BL2. BL3-1 also initializes a UART (PL011 console), which enables
+by BL2. It enables issuing of snoop and DVM (Distributed Virtual Memory)
+requests to the CCI slave interface corresponding to the cluster that includes
+the primary CPU. BL3-1 also initializes a UART (PL011 console), which enables
 access to the `printf` family of functions in BL3-1.  It enables the system
 level implementation of the generic timer through the memory mapped interface.
 
@@ -412,8 +414,7 @@ updated to develop and exploit new functionality.
 
 #### Required CPU state when calling `bl31_entrypoint()` during cold boot
 
-This function must only be called by the primary CPU, if this is called by any
-other CPU the firmware will abort.
+This function must only be called by the primary CPU.
 
 On entry to this function the calling primary CPU must be executing in AArch64
 EL3, little-endian data access, and all interrupt sources masked:
@@ -543,11 +544,6 @@ implementation via a platform defined mechanism. On a cold boot, the platform
 must place any secondary CPUs into a safe state while the primary CPU executes
 a modified BL3-1 initialization, as described below.
 
-#### Architectural initialization
-
-As the first image to execute in this configuration BL3-1 must ensure that
-interconnect coherency is enabled (if required) before enabling the MMU.
-
 #### Platform initialization
 
 In this configuration, when the CPU resets to BL3-1 there are no parameters
@@ -962,7 +958,7 @@ The sample crash output is shown below.
 ---------------------------------
 
 Trusted Firmware implements a framework that allows CPU and platform ports to
-perform actions immediately after a CPU is released from reset in both the cold
+perform actions very early after a CPU is released from reset in both the cold
 and warm boot paths. This is done by calling the `reset_handler()` function in
 both the BL1 and BL3-1 images. It in turn calls the platform and CPU specific
 reset handling functions.
@@ -971,33 +967,12 @@ Details for implementing a CPU specific reset handler can be found in
 Section 8. Details for implementing a platform specific reset handler can be
 found in the [Porting Guide](see the `plat_reset_handler()` function).
 
-When adding functionality to a reset handler, the following points should be
-kept in mind.
-
-1.   The first reset handler in the system exists either in a ROM image
-     (e.g. BL1), or BL3-1 if `RESET_TO_BL31` is true. This may be detected at
-     compile time using the constant `FIRST_RESET_HANDLER_CALL`.
-
-2.   When considering ROM images, it's important to consider non TF-based ROMs
-     and ROMs based on previous versions of the TF code.
-
-3.   If the functionality should be applied to a ROM and there is no possibility
-     of a ROM being used that does not apply the functionality (or equivalent),
-     then the functionality should be applied within a `#if
-     FIRST_RESET_HANDLER_CALL` block.
-
-4.   If the functionality should execute in BL3-1 in order to override or
-     supplement a ROM version of the functionality, then the functionality
-     should be applied in the `#else` part of a `#if FIRST_RESET_HANDLER_CALL`
-     block.
-
-5.   If the functionality should be applied to a ROM but there is a possibility
-     of ROMs being used that do not apply the functionality, then the
-     functionality should be applied outside of a `FIRST_RESET_HANDLER_CALL`
-     block, so that BL3-1 has an opportunity to apply the functionality instead.
-     In this case, additional code may be needed to cope with different ROMs
-     that do or do not apply the functionality.
-
+When adding functionality to a reset handler, keep in mind that if a different
+reset handling behavior is required between the first and the subsequent
+invocations of the reset handling code, this should be detected at runtime.
+In other words, the reset handler should be able to detect whether an action has
+already been performed and act as appropriate. Possible courses of actions are,
+e.g. skip the action the second time, or undo/redo it.
 
 8.  CPU specific operations framework
 -----------------------------
diff --git a/docs/porting-guide.md b/docs/porting-guide.md
index 1e49deb8..436dc106 100644
--- a/docs/porting-guide.md
+++ b/docs/porting-guide.md
@@ -434,7 +434,7 @@ This function fulfills requirement 1 and 3 listed above.
 This function is called with the MMU and data caches disabled. It is responsible
 for placing the executing secondary CPU in a platform-specific state until the
 primary CPU performs the necessary actions to bring it out of that state and
-allow entry into the OS.
+allow entry into the OS. This function must not return.
 
 In the ARM FVP port, each secondary CPU powers itself off. The primary CPU is
 responsible for powering up the secondary CPU when normal world software
@@ -569,7 +569,7 @@ preserve the values of callee saved registers x19 to x29.
 
 The default implementation doesn't do anything. If a platform needs to override
 the default implementation, refer to the [Firmware Design] for general
-guidelines regarding placement of code in a reset handler.
+guidelines.
 
 ### Function : plat_disable_acp()
 
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 9a9334f2..ef26f118 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -320,6 +320,10 @@ performed.
 *   `BL33_KEY`: This option is used when `GENERATE_COT=1`. It specifies the
     file that contains the BL3-3 private key in PEM format.
 
+*   `PROGRAMMABLE_RESET_ADDRESS`: This option indicates whether the reset
+    vector address can be programmed or is fixed on the platform. It can take
+    either 0 (fixed) or 1 (programmable). Default is 0.
+
 #### ARM development platform specific build options
 
 *   `ARM_TSP_RAM_LOCATION`: location of the TSP binary. Options: