Merge "console: update skeleton" into integration

drivers/console/aarch32/skeleton_console.S

 /*
- * Copyright (c) 2016-2017, ARM Limited and Contributors. All rights reserved.
+ * Copyright (c) 2016-2019, ARM Limited and Contributors. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
 #include <asm_macros.S>
+#include <console_macros.S>
 
 	/*
-	 * This file contains a skeleton console implementation that can
-	 * be used as basis for a real console implementation by platforms
-	 * that do not contain PL011 hardware.
+	 * This file contains a skeleton console driver that can be used as a
+	 * basis for a real console driver. Console drivers in Trusted Firmware
+	 * can be instantiated multiple times. Each instance is described by a
+	 * separate console_t structure which must be registered with the common
+	 * console framework via console_register(). Console drivers should
+	 * define a console_xxx_register() function that initializes a new
+	 * console_t structure passed in from the caller and registers it after
+	 * initializing the console hardware. Drivers may define their own
+	 * structures extending console_t to store private driver information.
+	 * Console drivers *MUST* ensure that the console callbacks they
+	 * implement only change registers allowed in the clobber lists defined
+	 * in this file. (Note that in addition to the explicit clobber lists,
+	 * any function may always clobber the intra-procedure-call register
+	 * r12, but may never depend on it retaining its value across any
+	 * function call.)
 	 */
 
-	.globl	console_core_init
-	.globl	console_core_putc
-	.globl	console_core_getc
-	.globl	console_core_flush
+	.globl	console_xxx_register
+	.globl	console_xxx_putc
+	.globl	console_xxx_getc
+	.globl	console_xxx_flush
 
 	/* -----------------------------------------------
-	 * int console_core_init(uintptr_t base_addr,
-	 * unsigned int uart_clk, unsigned int baud_rate)
-	 * Function to initialize the console without a
-	 * C Runtime to print debug information. This
-	 * function will be accessed by console_init and
-	 * crash reporting.
-	 * In: r0 - console base address
-	 *     r1 - Uart clock in Hz
-	 *     r2 - Baud rate
-	 * Out: return 1 on success else 0 on error
-	 * Clobber list : r1, r2
+	 * int console_xxx_register(console_xxx_t *console,
+	 * 	...additional parameters as desired...)
+	 * Function to initialize and register the console.
+	 * The caller needs to pass an empty console_xxx_t
+	 * structure in which *MUST* be allocated in
+	 * persistent memory (e.g. a global or static local
+	 * variable, *NOT* on the stack).
+	 * In : r0 - pointer to empty console_t structure
+	 *      r1 through r7: additional parameters as desired
+	 * Out: r0 - 1 on success, 0 on error
+	 * Clobber list : r0 - r7
 	 * -----------------------------------------------
 	 */
-func console_core_init
-	/* Check the input base address */
-	cmp	r0, #0
-	beq	core_init_fail
-	/* Check baud rate and uart clock for sanity */
-	cmp	r1, #0
-	beq	core_init_fail
-	cmp	r2, #0
-	beq	core_init_fail
-	/* Insert implementation here */
-	mov	r0, #1
-	bx	lr
-core_init_fail:
+func console_xxx_register
+	/*
+	 * Store parameters (e.g. hardware base address) in driver-specific
+	 * console_xxx_t structure field if they will need to be retrieved
+	 * by later console callback (e.g. putc).
+	 * Example:
+	 */
+	str	r1, [r0, #CONSOLE_T_XXX_BASE]
+	str	r2, [r0, #CONSOLE_T_XXX_SOME_OTHER_VALUE]
+
+	/*
+	 * Initialize console hardware, using r1 - r7 parameters as needed.
+	 * Keep console_t pointer in r0 for later.
+	 */
+
+	/*
+	 * Macro to finish up registration and return (needs valid r0 + lr).
+	 * If any of the argument is unspecified, then the corresponding
+	 * entry in console_t is set to 0.
+	 */
+	finish_console_register xxx putc=1, getc=1, flush=1
+
+	/* Jump here if hardware init fails or parameters are invalid. */
+register_fail:
 	mov	r0, #0
 	bx	lr
-endfunc console_core_init
+endfunc console_xxx_register
 
 	/* --------------------------------------------------------
-	 * int console_core_putc(int c, uintptr_t base_addr)
+	 * int console_xxx_putc(int c, console_xxx_t *console)
 	 * Function to output a character over the console. It
 	 * returns the character printed on success or -1 on error.
 	 * In : r0 - character to be printed
-	 *      r1 - console base address
-	 * Out : return -1 on error else return character.
-	 * Clobber list : r2
+	 *      r1 - pointer to console_t struct
+	 * Out: r0 - printed character on success, < 0 on error.
+	 * Clobber list : r0, r1, r2
 	 * --------------------------------------------------------
 	 */
-func console_core_putc
-	/* Check the input parameter */
-	cmp	r1, #0
-	beq	putc_error
-	/* Insert implementation here */
+func console_xxx_putc
+	/*
+	 * Retrieve values we need (e.g. hardware base address) from
+	 * console_xxx_t structure pointed to by r1.
+	 * Example:
+	 */
+	ldr	r1, [r1, #CONSOLE_T_XXX_BASE]
+
+	/*
+	 * Write r0 to hardware.
+	 */
+
 	bx	lr
+
+	/* Jump here if output fails for any reason. */
 putc_error:
 	mov	r0, #-1
 	bx	lr
-endfunc console_core_putc
+endfunc console_xxx_putc
 
 	/* ---------------------------------------------
-	 * int console_core_getc(uintptr_t base_addr)
+	 * int console_xxx_getc(console_xxx_t *console)
 	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or -1 on error.
-	 * In : r0 - console base address
+	 * Even though console_getc() is blocking, this
+	 * callback has to be non-blocking and always
+	 * return immediately to allow polling multiple
+	 * drivers concurrently.
+	 * Returns the character grabbed on success,
+	 * ERROR_NO_PENDING_CHAR if no character was
+	 * available at this time, or any value
+	 * between -2 and -127 if there was an error.
+	 * In : r0 - pointer to console_t struct
+	 * Out: r0 - character on success,
+	 *           ERROR_NO_PENDING_CHAR if no char,
+	 *           < -1 on error
 	 * Clobber list : r0, r1
 	 * ---------------------------------------------
 	 */
-func console_core_getc
-	cmp	r0, #0
-	beq	getc_error
-	/* Insert implementation here */
+func console_xxx_getc
+	/*
+	 * Retrieve values we need (e.g. hardware base address) from
+	 * console_xxx_t structure pointed to by r0.
+	 * Example:
+	 */
+	ldr	r1, [r0, #CONSOLE_T_XXX_BASE]
+
+	/*
+	 * Try to read character into r0 from hardware.
+	 */
+
 	bx	lr
+
+	/* Jump here if there is no character available at this time. */
+getc_no_char:
+	mov	r0, #ERROR_NO_PENDING_CHAR
+	bx	lr
+
+	/* Jump here if there was any hardware error. */
 getc_error:
-	mov	r0, #-1
+	mov	r0, #-2		/* may pick error codes between -2 and -127 */
 	bx	lr
-endfunc console_core_getc
+endfunc console_xxx_getc
 
 	/* ---------------------------------------------
-	 * int console_core_flush(uintptr_t base_addr)
+	 * int console_xxx_flush(console_xxx_t *console)
 	 * Function to force a write of all buffered
 	 * data that hasn't been output.
-	 * In : r0 - console base address
-	 * Out : return -1 on error else return 0.
-	 * Clobber list : r0, r1
+	 * In : r0 - pointer to console_xxx_t struct
+	 * Out: r0 - 0 on success, < 0 on error
+	 * Clobber list : r0, r1, r2, r3, r4, r5
 	 * ---------------------------------------------
 	 */
-func console_core_flush
-	cmp	r0, #0
-	beq	flush_error
-	/* Insert implementation here */
+func console_xxx_flush
+	/*
+	 * Retrieve values we need (e.g. hardware base address) from
+	 * console_xxx_t structure pointed to by r0.
+	 * Example:
+	 */
+	ldr	r1, [r0, #CONSOLE_T_XXX_BASE]
+
+	/*
+	 * Flush all remaining output from hardware FIFOs. Do not return until
+	 * all data has been flushed or there was an unrecoverable error.
+	 */
+
 	mov	r0, #0
 	bx	lr
+
+	/* Jump here if an unrecoverable error has been encountered. */
 flush_error:
 	mov	r0, #-1
 	bx	lr
-endfunc console_core_flush
+endfunc console_xxx_flush

drivers/console/aarch64/skeleton_console.S

@@ -7,7 +7,7 @@
 #include <console_macros.S>
 
 	/*
-	 * This file contains a skeleton console driver that can be used as
+	 * This file contains a skeleton console driver that can be used as a
 	 * basis for a real console driver. Console drivers in Trusted Firmware
 	 * can be instantiated multiple times. Each instance is described by a
 	 * separate console_t structure which must be registered with the common
@@ -16,7 +16,7 @@
 	 * console_t structure passed in from the caller and registers it after
 	 * initializing the console hardware. Drivers may define their own
 	 * structures extending console_t to store private driver information.
-	 * Console drivers *MUST* take care that the console callbacks they
+	 * Console drivers *MUST* ensure that the console callbacks they
 	 * implement only change registers allowed in the clobber lists defined
 	 * in this file. (Note that in addition to the explicit clobber lists,
 	 * any function may always clobber the intra-procedure-call registers

include/arch/aarch32/console_macros.S

@@ -15,7 +15,7 @@
  * default consoles are enabled for the "boot" and "crash" states, this can be
  * changed after registration with the console_set_scope() function). It ends
  * with a tail call that will include return to the caller.
- * REQUIRES console_t pointer in x0 and a valid return address in x30.
+ * REQUIRES console_t pointer in r0 and a valid return address in lr.
  */
 	.macro	finish_console_register _driver, putc=0, getc=0, flush=0
 	/*