Clarify platform porting interface to TSP

* Move TSP platform porting functions to new file:
  include/bl32/tsp/platform_tsp.h.

* Create new TSP_IRQ_SEC_PHY_TIMER definition for use by the generic
  TSP interrupt handling code, instead of depending on the FVP
  specific definition IRQ_SEC_PHY_TIMER.

* Rename TSP platform porting functions from bl32_* to tsp_*, and
  definitions from BL32_* to TSP_*.

* Update generic TSP code to use new platform porting function names
  and definitions.

* Update FVP port accordingly and move all TSP source files to:
  plat/fvp/tsp/.

* Update porting guide with above changes.

Note: THIS CHANGE REQUIRES ALL PLATFORM PORTS OF THE TSP TO
      BE UPDATED

Fixes ARM-software/tf-issues#167

Change-Id: Ic0ff8caf72aebb378d378193d2f017599fc6b78f

Makefile

@@ -174,8 +174,6 @@ endif
 
 INCLUDES		+=	-Iinclude/bl31			\
 				-Iinclude/bl31/services		\
-				-Iinclude/bl32			\
-				-Iinclude/bl32/payloads		\
 				-Iinclude/common		\
 				-Iinclude/drivers		\
 				-Iinclude/drivers/arm		\

bl32/tsp/aarch64/tsp_entrypoint.S

@@ -120,8 +120,8 @@ func tsp_entrypoint
 	 * specific early arch. setup e.g. mmu setup
 	 * ---------------------------------------------
 	 */
-	bl	bl32_early_platform_setup
+	bl	tsp_early_platform_setup
-	bl	bl32_plat_arch_setup
+	bl	tsp_plat_arch_setup
 
 	/* ---------------------------------------------
 	 * Jump to main function.

bl32/tsp/tsp.ld.S

@@ -68,8 +68,8 @@ SECTIONS
         __DATA_END__ = .;
     } >RAM
 
-#ifdef BL32_PROGBITS_LIMIT
+#ifdef TSP_PROGBITS_LIMIT
-    ASSERT(. <= BL32_PROGBITS_LIMIT, "BL3-2 progbits has exceeded its limit.")
+    ASSERT(. <= TSP_PROGBITS_LIMIT, "TSP progbits has exceeded its limit.")
 #endif
 
     stacks (NOLOAD) : {

bl32/tsp/tsp.mk

@@ -28,6 +28,8 @@
 # POSSIBILITY OF SUCH DAMAGE.
 #
 
+INCLUDES		+=	-Iinclude/bl32/tsp
+
 BL32_SOURCES		+=	bl32/tsp/tsp_main.c			\
 				bl32/tsp/aarch64/tsp_entrypoint.S	\
 				bl32/tsp/aarch64/tsp_exceptions.S	\
@@ -50,7 +52,7 @@ $(eval $(call add_define,TSP_INIT_ASYNC))
 # Include the platform-specific TSP Makefile
 # If no platform-specific TSP Makefile exists, it means TSP is not supported
 # on this platform.
-TSP_PLAT_MAKEFILE := bl32/tsp/tsp-${PLAT}.mk
+TSP_PLAT_MAKEFILE := plat/${PLAT}/tsp/tsp-${PLAT}.mk
 ifeq (,$(wildcard ${TSP_PLAT_MAKEFILE}))
   $(error TSP is not supported on platform ${PLAT})
 else

bl32/tsp/tsp_interrupt.c

@@ -88,7 +88,7 @@ int32_t tsp_fiq_handler(void)
 	id = plat_ic_get_pending_interrupt_id();
 
 	/* TSP can only handle the secure physical timer interrupt */
-	if (id != IRQ_SEC_PHY_TIMER)
+	if (id != TSP_IRQ_SEC_PHY_TIMER)
 		return TSP_EL3_FIQ;
 
 	/*
@@ -96,7 +96,7 @@ int32_t tsp_fiq_handler(void)
 	 * another secure interrupt through an assertion.
 	 */
 	id = plat_ic_acknowledge_interrupt();
-	assert(id == IRQ_SEC_PHY_TIMER);
+	assert(id == TSP_IRQ_SEC_PHY_TIMER);
 	tsp_generic_timer_handler();
 	plat_ic_end_of_interrupt(id);
 

bl32/tsp/tsp_main.c

@@ -33,6 +33,7 @@
 #include <debug.h>
 #include <platform.h>
 #include <platform_def.h>
+#include <platform_tsp.h>
 #include <spinlock.h>
 #include <tsp.h>
 #include "tsp_private.h"
@@ -116,7 +117,7 @@ uint64_t tsp_main(void)
 	uint32_t linear_id = platform_get_core_pos(mpidr);
 
 	/* Initialize the platform */
-	bl32_platform_setup();
+	tsp_platform_setup();
 
 	/* Initialize secure/applications state here */
 	tsp_generic_timer_start();

docs/porting-guide.md

@@ -193,30 +193,42 @@ file is found in [plat/fvp/include/platform_def.h].
     Defines the base address in non-secure DRAM where BL2 loads the BL3-3 binary
     image. Must be aligned on a page-size boundary.
 
-If the BL3-2 image is supported by the platform, the following constants must
+If a BL3-2 image is supported by the platform, the following constants must
-be defined as well:
+also be defined:
 
-*   **#define : TSP_SEC_MEM_BASE**
+*   **#define : BL32_IMAGE_NAME**
 
-    Defines the base address of the secure memory used by the BL3-2 image on the
+    Name of the BL3-2 binary image on the host file-system. This name is used by
-    platform.
+    BL2 to load BL3-2 into secure memory from platform storage.
-
-*   **#define : TSP_SEC_MEM_SIZE**
-
-    Defines the size of the secure memory used by the BL3-2 image on the
-    platform.
 
 *   **#define : BL32_BASE**
 
     Defines the base address in secure memory where BL2 loads the BL3-2 binary
-    image. Must be inside the secure memory identified by `TSP_SEC_MEM_BASE` and
+    image. Must be aligned on a page-size boundary.
-    `TSP_SEC_MEM_SIZE` constants. Must also be aligned on a page-size boundary.
 
 *   **#define : BL32_LIMIT**
 
-    Defines the maximum address that the BL3-2 image can occupy. Must be inside
+    Defines the maximum address that the BL3-2 image can occupy.
-    the secure memory identified by `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE`
+
-    constants.
+If the Test Secure-EL1 Payload (TSP) instantiation of BL3-2 is supported by the
+platform, the following constants must also be defined:
+
+*   **#define : TSP_SEC_MEM_BASE**
+
+    Defines the base address of the secure memory used by the TSP image on the
+    platform. This must be at the same address or below `BL32_BASE`.
+
+*   **#define : TSP_SEC_MEM_SIZE**
+
+    Defines the size of the secure memory used by the BL3-2 image on the
+    platform. `TSP_SEC_MEM_BASE` and `TSP_SEC_MEM_SIZE` must fully accomodate
+    the memory required by the BL3-2 image, defined by `BL32_BASE` and
+    `BL32_LIMIT`.
+
+*   **#define : TSP_IRQ_SEC_PHY_TIMER**
+
+    Defines the ID of the secure physical generic timer interrupt used by the
+    TSP's interrupt handling code.
 
 If the platform port uses the IO storage framework, the following constants
 must also be defined:
@@ -241,7 +253,7 @@ memory layout implies some image overlaying like on FVP.
     Defines the maximum address in secure RAM that the BL3-1's progbits sections
     can occupy.
 
-*   **#define : BL32_PROGBITS_LIMIT**
+*   **#define : TSP_PROGBITS_LIMIT**
 
     Defines the maximum address that the TSP's progbits sections can occupy.
 

include/bl32/tsp/platform_tsp.h

@@ -0,0 +1,44 @@
+/*
+ * Copyright (c) 2014, ARM Limited and Contributors. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
+ *
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * Neither the name of ARM nor the names of its contributors may be used
+ * to endorse or promote products derived from this software without specific
+ * prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+#ifndef __PLATFORM_TSP_H__
+
+
+/*******************************************************************************
+ * Mandatory TSP functions (only if platform contains a TSP)
+ ******************************************************************************/
+void tsp_early_platform_setup(void);
+void tsp_plat_arch_setup(void);
+void tsp_platform_setup(void);
+
+
+#define __PLATFORM_H__
+
+#endif

include/plat/common/platform.h

@@ -78,6 +78,7 @@ int plat_crash_console_putc(int c);
 /*******************************************************************************
  * Mandatory BL1 functions
  ******************************************************************************/
+void bl1_early_platform_setup(void);
 void bl1_plat_arch_setup(void);
 void bl1_platform_setup(void);
 struct meminfo *bl1_plat_sec_mem_layout(void);
@@ -98,6 +99,7 @@ void bl1_init_bl2_mem_layout(const struct meminfo *bl1_mem_layout,
 /*******************************************************************************
  * Mandatory BL2 functions
  ******************************************************************************/
+void bl2_early_platform_setup(struct meminfo *mem_layout);
 void bl2_plat_arch_setup(void);
 void bl2_platform_setup(void);
 struct meminfo *bl2_plat_sec_mem_layout(void);
@@ -184,11 +186,6 @@ unsigned int plat_get_aff_state(unsigned int, unsigned long);
  ******************************************************************************/
 void bl31_plat_enable_mmu(uint32_t flags);
 
-/*******************************************************************************
- * Mandatory BL3-2 functions (only if platform contains a BL3-2)
- ******************************************************************************/
-void bl32_platform_setup(void);
-
 /*******************************************************************************
  * Optional BL3-2 functions (may be overridden)
  ******************************************************************************/

plat/fvp/aarch64/fvp_helpers.S

@@ -32,9 +32,9 @@
 #include <asm_macros.S>
 #include <bl_common.h>
 #include <gic_v2.h>
+#include <platform_def.h>
 #include <pl011.h>
 #include "../drivers/pwrc/fvp_pwrc.h"
-#include "platform_def.h"
 
 	.globl	platform_get_entrypoint
 	.globl	plat_secondary_cold_boot_setup

plat/fvp/include/platform_def.h

@@ -32,7 +32,7 @@
 #define __PLATFORM_DEF_H__
 
 #include <arch.h>
-#include <../fvp_def.h>
+#include "../fvp_def.h"
 
 
 /*******************************************************************************
@@ -131,8 +131,8 @@
 #if FVP_TSP_RAM_LOCATION_ID == FVP_IN_TRUSTED_SRAM
 # define TSP_SEC_MEM_BASE		FVP_TRUSTED_SRAM_BASE
 # define TSP_SEC_MEM_SIZE		FVP_TRUSTED_SRAM_SIZE
+# define TSP_PROGBITS_LIMIT		BL2_BASE
 # define BL32_BASE			FVP_TRUSTED_SRAM_BASE
-# define BL32_PROGBITS_LIMIT		BL2_BASE
 # define BL32_LIMIT			BL31_BASE
 #elif FVP_TSP_RAM_LOCATION_ID == FVP_IN_TRUSTED_DRAM
 # define TSP_SEC_MEM_BASE		FVP_TRUSTED_DRAM_BASE
@@ -144,6 +144,11 @@
 # error "Unsupported FVP_TSP_RAM_LOCATION_ID value"
 #endif
 
+/*
+ * ID of the secure physical generic timer interrupt used by the TSP.
+ */
+#define TSP_IRQ_SEC_PHY_TIMER		IRQ_SEC_PHY_TIMER
+
 /*******************************************************************************
  * Platform specific page table and MMU setup constants
  ******************************************************************************/
@@ -151,11 +156,6 @@
 #define MAX_XLAT_TABLES			2
 #define MAX_MMAP_REGIONS		16
 
-/*******************************************************************************
- * ID of the secure physical generic timer interrupt.
- ******************************************************************************/
-#define IRQ_SEC_PHY_TIMER		29
-
 /*******************************************************************************
  * Declarations and constants to access the mailboxes safely. Each mailbox is
  * aligned on the biggest cache line size in the platform. This is known only

plat/fvp/tsp/tsp-fvp.mk

@@ -35,4 +35,4 @@ BL32_SOURCES		+=	drivers/arm/gic/arm_gic.c			\
 				plat/common/plat_gic.c				\
 				plat/fvp/aarch64/fvp_common.c			\
 				plat/fvp/aarch64/fvp_helpers.S			\
-				plat/fvp/bl32_fvp_setup.c
+				plat/fvp/tsp/tsp_fvp_setup.c

plat/fvp/tsp/tsp_fvp_setup.c

@@ -30,9 +30,9 @@
 
 #include <bl_common.h>
 #include <console.h>
-#include <platform.h>
+#include <platform_tsp.h>
-#include "fvp_def.h"
+#include "../fvp_def.h"
-#include "fvp_private.h"
+#include "../fvp_private.h"
 
 /*******************************************************************************
  * Declarations of linker defined symbols which will help us find the layout
@@ -66,7 +66,7 @@ extern unsigned long __COHERENT_RAM_END__;
 /*******************************************************************************
  * Initialize the UART
  ******************************************************************************/
-void bl32_early_platform_setup(void)
+void tsp_early_platform_setup(void)
 {
 	/*
 	 * Initialize a different console than already in use to display
@@ -81,7 +81,7 @@ void bl32_early_platform_setup(void)
 /*******************************************************************************
  * Perform platform specific setup placeholder
  ******************************************************************************/
-void bl32_platform_setup(void)
+void tsp_platform_setup(void)
 {
 	fvp_gic_init();
 }
@@ -90,7 +90,7 @@ void bl32_platform_setup(void)
  * Perform the very early platform specific architectural setup here. At the
  * moment this is only intializes the MMU
  ******************************************************************************/
-void bl32_plat_arch_setup(void)
+void tsp_plat_arch_setup(void)
 {
 	fvp_configure_mmu_el1(BL32_RO_BASE,
 			      (BL32_COHERENT_RAM_LIMIT - BL32_RO_BASE),

services/spd/tspd/tspd.mk

@@ -29,7 +29,7 @@
 #
 
 TSPD_DIR		:=	services/spd/tspd
-SPD_INCLUDES		:=	-Iinclude/bl32/payloads
+SPD_INCLUDES		:=	-Iinclude/bl32/tsp
 
 SPD_SOURCES		:=	services/spd/tspd/tspd_common.c		\
 				services/spd/tspd/tspd_helpers.S	\