BL1: Deprecate the bl1_init_bl2_mem_layout() API

The `bl1_init_bl2_mem_layout()` API is now deprecated. The default weak
implementation of `bl1_plat_handle_post_image_load()` calculates the
BL2 memory layout and populates the same in x1(r1). This ensures
compatibility for the deprecated API.

Change-Id: Id44bdc1f572dc42ee6ceef4036b3a46803689315
Signed-off-by: Soby Mathew <soby.mathew@arm.com>

bl1/bl1_main.c

@@ -25,24 +25,15 @@ DEFINE_SVC_UUID(bl1_svc_uid,
 	0xfd3967d4, 0x72cb, 0x4d9a, 0xb5, 0x75,
 	0x67, 0x15, 0xd6, 0xf4, 0xbb, 0x4a);
 
-
 static void bl1_load_bl2(void);
 
 /*******************************************************************************
- * The next function has a weak definition. Platform specific code can override
- * it if it wishes to.
+ * Helper utility to calculate the BL2 memory layout taking into consideration
+ * the BL1 RW data assuming that it is at the top of the memory layout.
  ******************************************************************************/
-#pragma weak bl1_init_bl2_mem_layout
-
-/*******************************************************************************
- * Function that takes a memory layout into which BL2 has been loaded and
- * populates a new memory layout for BL2 that ensures that BL1's data sections
- * resident in secure RAM are not visible to BL2.
- ******************************************************************************/
-void bl1_init_bl2_mem_layout(const meminfo_t *bl1_mem_layout,
+void bl1_calc_bl2_mem_layout(const meminfo_t *bl1_mem_layout,
 			meminfo_t *bl2_mem_layout)
 {
-
 	assert(bl1_mem_layout != NULL);
 	assert(bl2_mem_layout != NULL);
 
@@ -71,6 +62,25 @@ void bl1_init_bl2_mem_layout(const meminfo_t *bl1_mem_layout,
 	flush_dcache_range((unsigned long)bl2_mem_layout, sizeof(meminfo_t));
 }
 
+#if !ERROR_DEPRECATED
+/*******************************************************************************
+ * Compatibility default implementation for deprecated API. This has a weak
+ * definition. Platform specific code can override it if it wishes to.
+ ******************************************************************************/
+#pragma weak bl1_init_bl2_mem_layout
+
+/*******************************************************************************
+ * Function that takes a memory layout into which BL2 has been loaded and
+ * populates a new memory layout for BL2 that ensures that BL1's data sections
+ * resident in secure RAM are not visible to BL2.
+ ******************************************************************************/
+void bl1_init_bl2_mem_layout(const meminfo_t *bl1_mem_layout,
+			     meminfo_t *bl2_mem_layout)
+{
+	bl1_calc_bl2_mem_layout(bl1_mem_layout, bl2_mem_layout);
+}
+#endif
+
 /*******************************************************************************
  * Function to perform late architectural and platform specific initialization.
  * It also queries the platform to load and run next BL image. Only called
@@ -157,9 +167,6 @@ void bl1_load_bl2(void)
 {
 	image_desc_t *image_desc;
 	image_info_t *image_info;
-	entry_point_info_t *ep_info;
-	meminfo_t *bl1_tzram_layout;
-	meminfo_t *bl2_tzram_layout;
 	int err;
 
 	/* Get the image descriptor */
@@ -168,13 +175,6 @@ void bl1_load_bl2(void)
 
 	/* Get the image info */
 	image_info = &image_desc->image_info;
-
-	/* Get the entry point info */
-	ep_info = &image_desc->ep_info;
-
-	/* Find out how much free trusted ram remains after BL1 load */
-	bl1_tzram_layout = bl1_plat_sec_mem_layout();
-
 	INFO("BL1: Loading BL2\n");
 
 	err = bl1_plat_handle_pre_image_load(BL2_IMAGE_ID);
@@ -186,6 +186,15 @@ void bl1_load_bl2(void)
 #if LOAD_IMAGE_V2
 	err = load_auth_image(BL2_IMAGE_ID, image_info);
 #else
+	entry_point_info_t *ep_info;
+	meminfo_t *bl1_tzram_layout;
+
+	/* Get the entry point info */
+	ep_info = &image_desc->ep_info;
+
+	/* Find out how much free trusted ram remains after BL1 load */
+	bl1_tzram_layout = bl1_plat_sec_mem_layout();
+
 	/* Load the BL2 image */
 	err = load_auth_image(bl1_tzram_layout,
 			 BL2_IMAGE_ID,
@@ -207,25 +216,7 @@ void bl1_load_bl2(void)
 		plat_error_handler(err);
 	}
 
-#if LOAD_IMAGE_V2
-	/*
-	 * Create a new layout of memory for BL2 as seen by BL1 i.e.
-	 * tell it the amount of total and free memory available.
-	 * This layout is created at the first free address visible
-	 * to BL2. BL2 will read the memory layout before using its
-	 * memory for other purposes.
-	 */
-	bl2_tzram_layout = (meminfo_t *) bl1_tzram_layout->total_base;
-#else
-	bl2_tzram_layout = (meminfo_t *) bl1_tzram_layout->free_base;
-#endif /* LOAD_IMAGE_V2 */
-
-	bl1_init_bl2_mem_layout(bl1_tzram_layout, bl2_tzram_layout);
-
-	ep_info->args.arg1 = (uintptr_t)bl2_tzram_layout;
 	NOTICE("BL1: Booting BL2\n");
-	VERBOSE("BL1: BL2 memory layout address = %p\n",
-		(void *) bl2_tzram_layout);
 }
 
 /*******************************************************************************

docs/porting-guide.rst

@@ -1179,25 +1179,6 @@ its own use.
 
 This function helps fulfill requirements 4 and 5 above.
 
-Function : bl1\_init\_bl2\_mem\_layout() [optional]
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-::
-
-    Argument : meminfo *, meminfo *
-    Return   : void
-
-BL1 needs to tell the next stage the amount of secure RAM available
-for it to use. This information is populated in a ``meminfo``
-structure.
-
-Depending upon where BL2 has been loaded in secure RAM (determined by
-``BL2_BASE``), BL1 calculates the amount of free memory available for BL2 to use.
-BL1 also ensures that its data sections resident in secure RAM are not visible
-to BL2. An illustration of how this is done in ARM standard platforms is given
-in the **Memory layout on ARM development platforms** section in the
-`Firmware Design`_.
-
 Function : bl1\_plat\_prepare\_exit() [optional]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

include/bl1/bl1.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2015-2018, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -71,5 +71,9 @@ CASSERT(FWU_NUM_SMC_CALLS == 	\
 		(FWU_SMC_FID_END - FWU_SMC_FID_START + 1),\
 		assert_FWU_NUM_SMC_CALLS_mismatch);
 
+/* Utility functions */
+void bl1_calc_bl2_mem_layout(const meminfo_t *bl1_mem_layout,
+			meminfo_t *bl2_mem_layout);
+
 #endif /* __ASSEMBLY__ */
 #endif /* __BL1_FWU_H__ */

include/plat/common/platform.h

@@ -134,9 +134,10 @@ int bl1_plat_mem_check(uintptr_t mem_base, unsigned int mem_size,
 /*******************************************************************************
  * Optional BL1 functions (may be overridden)
  ******************************************************************************/
+#if !ERROR_DEPRECATED
 void bl1_init_bl2_mem_layout(const struct meminfo *bl1_mem_layout,
 			     struct meminfo *bl2_mem_layout);
-
+#endif
 /*
  * The following functions are used for image loading process in BL1.
  */

plat/common/plat_bl1_common.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2015, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2015-2018, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -7,6 +7,7 @@
 #include <arch_helpers.h>
 #include <assert.h>
 #include <bl_common.h>
+#include <bl1.h>
 #include <debug.h>
 #include <errno.h>
 #include <platform.h>
@@ -43,11 +44,6 @@ int bl1_plat_handle_pre_image_load(unsigned int image_id)
 	return 0;
 }
 
-int bl1_plat_handle_post_image_load(unsigned int image_id)
-{
-	return 0;
-}
-
 /*
  * Following is the default definition that always
  * returns BL2 image details.
@@ -75,3 +71,54 @@ int bl1_plat_mem_check(uintptr_t mem_base, unsigned int mem_size,
 	assert(0);
 	return -ENOMEM;
 }
+
+/*
+ * Default implementation for bl1_plat_handle_post_image_load(). This function
+ * populates the default arguments to BL2. The BL2 memory layout structure
+ * is allocated and the calculated layout is populated in arg1 to BL2.
+ */
+int bl1_plat_handle_post_image_load(unsigned int image_id)
+{
+	meminfo_t *bl2_tzram_layout;
+	meminfo_t *bl1_tzram_layout;
+	image_desc_t *image_desc;
+	entry_point_info_t *ep_info;
+
+	if (image_id != BL2_IMAGE_ID)
+		return 0;
+
+	/* Get the image descriptor */
+	image_desc = bl1_plat_get_image_desc(BL2_IMAGE_ID);
+	assert(image_desc);
+
+	/* Get the entry point info */
+	ep_info = &image_desc->ep_info;
+
+	/* Find out how much free trusted ram remains after BL1 load */
+	bl1_tzram_layout = bl1_plat_sec_mem_layout();
+
+	/*
+	 * Create a new layout of memory for BL2 as seen by BL1 i.e.
+	 * tell it the amount of total and free memory available.
+	 * This layout is created at the first free address visible
+	 * to BL2. BL2 will read the memory layout before using its
+	 * memory for other purposes.
+	 */
+#if LOAD_IMAGE_V2
+	bl2_tzram_layout = (meminfo_t *) bl1_tzram_layout->total_base;
+#else
+	bl2_tzram_layout = (meminfo_t *) bl1_tzram_layout->free_base;
+#endif /* LOAD_IMAGE_V2 */
+
+#if !ERROR_DEPRECATED
+	bl1_init_bl2_mem_layout(bl1_tzram_layout, bl2_tzram_layout);
+#else
+	bl1_calc_bl2_mem_layout(bl1_tzram_layout, bl2_tzram_layout);
+#endif
+
+	ep_info->args.arg1 = (uintptr_t)bl2_tzram_layout;
+
+	VERBOSE("BL1: BL2 memory layout address = %p\n",
+		(void *) bl2_tzram_layout);
+	return 0;
+}