Add optional platform error handler API

This patch adds an optional API to the platform port:

    void plat_error_handler(int err) __dead2;

The platform error handler is called when there is a specific error
condition after which Trusted Firmware cannot continue. While panic()
simply prints the crash report (if enabled) and spins, the platform
error handler can be used to hand control over to the platform port
so it can perform specific bookeeping or post-error actions (for
example, reset the system). This function must not return.

The parameter indicates the type of error using standard codes from
errno.h. Possible errors reported by the generic code are:

    -EAUTH  : a certificate or image could not be authenticated
              (when Trusted Board Boot is enabled)
    -ENOENT : the requested image or certificate could not be found
              or an IO error was detected
    -ENOMEM : resources exhausted. Trusted Firmware does not use
              dynamic memory, so this error is usually an indication
              of an incorrect array size

A default weak implementation of this function has been provided.
It simply implements an infinite loop.

Change-Id: Iffaf9eee82d037da6caa43b3aed51df555e597a3

bl1/bl1_main.c

@@ -174,12 +174,8 @@ void bl1_main(void)
 			 &bl2_ep);
 
 	if (err) {
-		/*
-		 * TODO: print failure to load BL2 but also add a tzwdog timer
-		 * which will reset the system eventually.
-		 */
 		ERROR("Failed to load BL2 firmware.\n");
-		panic();
+		plat_error_handler(err);
 	}
 
 	/*

bl2/bl2_main.c

@@ -219,7 +219,7 @@ void bl2_main(void)
 	e = load_bl30();
 	if (e) {
 		ERROR("Failed to load BL3-0 (%i)\n", e);
-		panic();
+		plat_error_handler(e);
 	}
 
 	/* Perform platform setup in BL2 after loading BL3-0 */
@@ -235,14 +235,14 @@ void bl2_main(void)
 	e = load_bl31(bl2_to_bl31_params, bl31_ep_info);
 	if (e) {
 		ERROR("Failed to load BL3-1 (%i)\n", e);
-		panic();
+		plat_error_handler(e);
 	}
 
 	e = load_bl32(bl2_to_bl31_params);
 	if (e) {
 		if (e == -EAUTH) {
 			ERROR("Failed to authenticate BL3-2\n");
-			panic();
+			plat_error_handler(e);
 		} else {
 			WARN("Failed to load BL3-2 (%i)\n", e);
 		}
@@ -251,7 +251,7 @@ void bl2_main(void)
 	e = load_bl33(bl2_to_bl31_params);
 	if (e) {
 		ERROR("Failed to load BL3-3 (%i)\n", e);
-		panic();
+		plat_error_handler(e);
 	}
 
 	/* Flush the params to be passed to memory */

docs/porting-guide.md

@@ -650,6 +650,27 @@ it has restrictions for stack usage and it can use the registers x0 - x17 as
 scratch registers. It should preserve the value in x18 register as it is used
 by the caller to store the return address.
 
+### Function : plat_error_handler()
+
+    Argument : int
+    Return   : void
+
+This API is called when the generic code encounters an error situation from
+which it cannot continue. It allows the platform to perform error reporting or
+recovery actions (for example, reset the system). This function must not return.
+
+The parameter indicates the type of error using standard codes from `errno.h`.
+Possible errors reported by the generic code are:
+
+*   `-EAUTH`: a certificate or image could not be authenticated (when Trusted
+    Board Boot is enabled)
+*   `-ENOENT`: the requested image or certificate could not be found or an IO
+    error was detected
+*   `-ENOMEM`: resources exhausted. Trusted Firmware does not use dynamic
+    memory, so this error is usually an indication of an incorrect array size
+
+The default implementation simply spins.
+
 
 3.  Modifications specific to a Boot Loader stage
 -------------------------------------------------

include/plat/common/platform.h

@@ -81,6 +81,7 @@ unsigned long plat_get_my_stack(void);
 void plat_report_exception(unsigned long);
 int plat_crash_console_init(void);
 int plat_crash_console_putc(int c);
+void plat_error_handler(int err) __dead2;
 
 /*******************************************************************************
  * Mandatory BL1 functions

plat/common/aarch64/platform_helpers.S

@@ -38,6 +38,7 @@
 	.weak	plat_reset_handler
 	.weak	plat_disable_acp
 	.weak	bl1_plat_prepare_exit
+	.weak	plat_error_handler
 
 #if !ENABLE_PLAT_COMPAT
 	.globl	platform_get_core_pos
@@ -121,3 +122,12 @@ endfunc plat_disable_acp
 func bl1_plat_prepare_exit
 	ret
 endfunc bl1_plat_prepare_exit
+
+	/* -----------------------------------------------------
+	 * void plat_error_handler(int err) __dead2;
+	 * Endless loop by default.
+	 * -----------------------------------------------------
+	 */
+func plat_error_handler
+	b	plat_error_handler
+endfunc plat_error_handler