PSCI: Add documentation and fix plat_is_my_cpu_primary()

This patch adds the necessary documentation updates to porting_guide.md
for the changes in the platform interface mandated as a result of the new
PSCI Topology and power state management frameworks. It also adds a
new document `platform-migration-guide.md` to aid the migration of existing
platform ports to the new API.

The patch fixes the implementation and callers of
plat_is_my_cpu_primary() to use w0 as the return parameter as implied by
the function signature rather than x0 which was used previously.

Change-Id: Ic11e73019188c8ba2bd64c47e1729ff5acdcdd5b

docs/user-guide.md

@@ -351,7 +351,12 @@ performed.
 
 *   `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.
+    either 0 (fixed) or 1 (programmable). Default is 0. If the platform has a
+    programmable reset address, it is expected that a CPU will start executing
+    code directly at the right address, both on a cold and warm reset. In this
+    case, there is no need to identify the entrypoint on boot and this has
+    implication for `plat_get_my_entrypoint()` platform porting interface.
+    (see the [Porting Guide] for details)
 
 *   `PSCI_EXTENDED_STATE_ID`: As per PSCI1.0 Specification, there are 2 formats
     possible for the PSCI power-state parameter viz original and extended
@@ -1092,4 +1097,5 @@ _Copyright (c) 2013-2015, ARM Limited and Contributors. All rights reserved._
 [Juno Software Guide]:         http://community.arm.com/docs/DOC-8396
 [DS-5]:                        http://www.arm.com/products/tools/software-tools/ds-5/index.php
 [mbedTLS Repository]:          https://github.com/ARMmbed/mbedtls.git
+[Porting Guide]:               ./porting-guide.md
 [Trusted Board Boot]:          trusted-board-boot.md

include/common/el3_common_macros.S

@@ -181,7 +181,7 @@
 		 * -------------------------------------------------------------
 		 */
 		bl	plat_is_my_cpu_primary
-		cbnz	x0, do_primary_cold_boot
+		cbnz	w0, do_primary_cold_boot
 
 		/* This is a cold boot on a secondary CPU */
 		bl	plat_secondary_cold_boot_setup

plat/arm/board/fvp/aarch64/fvp_helpers.S

@@ -154,11 +154,17 @@ _panic:
 	b	_panic
 endfunc plat_get_my_entrypoint
 
-
+	/* -----------------------------------------------------
+	 * unsigned int plat_is_my_cpu_primary (void);
+	 *
+	 * Find out whether the current cpu is the primary
+	 * cpu.
+	 * -----------------------------------------------------
+	 */
 func plat_is_my_cpu_primary
 	mrs	x0, mpidr_el1
 	and	x0, x0, #(MPIDR_CLUSTER_MASK | MPIDR_CPU_MASK)
 	cmp	x0, #FVP_PRIMARY_CPU
-	cset	x0, eq
+	cset	w0, eq
 	ret
 endfunc plat_is_my_cpu_primary

plat/arm/css/common/aarch64/css_helpers.S

@@ -77,7 +77,7 @@ endfunc plat_get_my_entrypoint
 	 * Function to calculate the core position by
 	 * swapping the cluster order. This is necessary in order to
 	 * match the format of the boot information passed by the SCP
-	 * and read in platform_is_primary_cpu below.
+	 * and read in plat_is_my_cpu_primary below.
 	 * -----------------------------------------------------------
 	 */
 func plat_arm_calc_core_pos
@@ -102,6 +102,6 @@ func plat_is_my_cpu_primary
 	ldr	x1, [x1]
 	ubfx	x1, x1, #PRIMARY_CPU_SHIFT, #PRIMARY_CPU_BIT_WIDTH
 	cmp	x0, x1
-	cset	x0, eq
+	cset	w0, eq
 	ret	x9
 endfunc plat_is_my_cpu_primary