drivers: console: pl011: Move comments to header

Rather than having the description of each function in the
implementation, move it to the header so that it isn't needed to copy
it in each file that implements a console driver.

Change-Id: I1b437ae3d3ccff10979466727353bc1fa1d5b188
Signed-off-by: Antonio Nino Diaz <antonio.ninodiaz@arm.com>

4 files changed, 46 insertions, 87 deletions

diff --git a/drivers/arm/pl011/aarch32/pl011_console.S b/drivers/arm/pl011/aarch32/pl011_console.S
index 4c7bfe7..c65c4f6 100644
--- a/drivers/arm/pl011/aarch32/pl011_console.S
+++ b/drivers/arm/pl011/aarch32/pl011_console.S
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -33,13 +33,7 @@ console_base: .word 0x0
 	/* -----------------------------------------------
 	 * int console_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. It saves
-	 * the console base to the data section.
-	 * In: r0 - Console base address
-	 *     r1 - Uart clock in Hz
-	 *     r2 - Baud rate
-	 * Out: r0 - Return 1 on success, 0 on error.
+	 *
 	 * Clobber list : r1 - r3
 	 * -----------------------------------------------
 	 */
@@ -105,11 +99,7 @@ endfunc console_core_init
 
 	/* ---------------------------------------------
 	 * int console_putc(int c)
-	 * Function to output a character over the
-	 * console. It returns the character printed on
-	 * success or an error code.
-	 * In : r0 - Character to be printed
-	 * Out : r0 - Input character or error code.
+	 *
 	 * Clobber list : r1, r2
 	 * ---------------------------------------------
 	 */
@@ -161,12 +151,7 @@ endfunc console_core_putc
 
 	/* ---------------------------------------------
 	 * int console_getc(void)
-	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or an error code on error. This function is
-	 * blocking, it waits until there is an
-	 * available character to return.
-	 * Out : r0 - Return character or error code.
+	 *
 	 * Clobber list : r0 - r3
 	 * ---------------------------------------------
 	 */
@@ -186,11 +171,7 @@ endfunc console_getc
 
 	/* ---------------------------------------------
 	 * int console_try_getc(void)
-	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or an error code on error. This function is
-	 * non-blocking, it returns immediately.
-	 * Out : r0 - Return character or error code.
+	 *
 	 * Clobber list : r0, r1
 	 * ---------------------------------------------
 	 */
@@ -235,11 +216,7 @@ endfunc console_core_getc
 
 	/* ---------------------------------------------
 	 * int console_flush(void)
-	 * Function to force a write of all buffered
-	 * data that hasn't been output. It returns 0
-	 * upon successful completion, otherwise it
-	 * returns an error code.
-	 * Out: r0 - Error code or 0.
+	 *
 	 * Clobber list : r0, r1
 	 * ---------------------------------------------
 	 */
diff --git a/drivers/arm/pl011/aarch64/pl011_console.S b/drivers/arm/pl011/aarch64/pl011_console.S
index 4e7ad2d..8b1e062 100644
--- a/drivers/arm/pl011/aarch64/pl011_console.S
+++ b/drivers/arm/pl011/aarch64/pl011_console.S
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -33,13 +33,7 @@ console_base: .quad 0x0
 	/* -----------------------------------------------
 	 * int console_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. It saves
-	 * the console base to the data section.
-	 * In: x0 - Console base address
-	 *     w1 - Uart clock in Hz
-	 *     w2 - Baud rate
-	 * Out: w0 - Return 1 on success, 0 on error.
+	 *
 	 * Clobber list : x1 - x3
 	 * -----------------------------------------------
 	 */
@@ -101,11 +95,7 @@ endfunc console_core_init
 
 	/* ---------------------------------------------
 	 * int console_putc(int c)
-	 * Function to output a character over the
-	 * console. It returns the character printed on
-	 * success or an error code.
-	 * In : x0 - Character to be printed
-	 * Out : w0 - Input character or error code.
+	 *
 	 * Clobber list : x1, x2
 	 * ---------------------------------------------
 	 */
@@ -154,12 +144,7 @@ endfunc console_core_putc
 
 	/* ---------------------------------------------
 	 * int console_getc(void)
-	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or an error code on error. This function is
-	 * blocking, it waits until there is an
-	 * available character to return.
-	 * Out : w0 - Return character or error code.
+	 *
 	 * Clobber list : x0 - x3
 	 * ---------------------------------------------
 	 */
@@ -179,11 +164,7 @@ endfunc console_getc
 
 	/* ---------------------------------------------
 	 * int console_try_getc(void)
-	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or an error code on error. This function is
-	 * non-blocking, it returns immediately.
-	 * Out : w0 - Return character or error code.
+	 *
 	 * Clobber list : x0, x1
 	 * ---------------------------------------------
 	 */
@@ -226,11 +207,7 @@ endfunc console_core_getc
 
 	/* ---------------------------------------------
 	 * int console_flush(void)
-	 * Function to force a write of all buffered
-	 * data that hasn't been output. It returns 0
-	 * upon successful completion, otherwise it
-	 * returns an error code.
-	 * Out: w0 - Error code or 0.
+	 *
 	 * Clobber list : x0, x1
 	 * ---------------------------------------------
 	 */
diff --git a/drivers/console/aarch64/dummy_console.S b/drivers/console/aarch64/dummy_console.S
index 50ac196..961ef96 100644
--- a/drivers/console/aarch64/dummy_console.S
+++ b/drivers/console/aarch64/dummy_console.S
@@ -16,13 +16,7 @@
 	/* -----------------------------------------------
 	 * int console_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. It saves
-	 * the console base to the data section.
-	 * In: x0 - Console base address
-	 *     w1 - Uart clock in Hz
-	 *     w2 - Baud rate
-	 * Out: w0 - Return 1 on success, 0 on error.
+	 *
 	 * Clobber list : x1 - x3
 	 * -----------------------------------------------
 	 */
@@ -33,11 +27,7 @@ endfunc console_init
 
 	/* ---------------------------------------------
 	 * int console_putc(int c)
-	 * Function to output a character over the
-	 * console. It returns the character printed on
-	 * success or an error code.
-	 * In : x0 - Character to be printed
-	 * Out : w0 - Input character or error code.
+	 *
 	 * Clobber list : x1, x2
 	 * ---------------------------------------------
 	 */
@@ -48,12 +38,7 @@ endfunc console_putc
 
 	/* ---------------------------------------------
 	 * int console_getc(void)
-	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or an error code on error. This function is
-	 * blocking, it waits until there is an
-	 * available character to return.
-	 * Out : w0 - Return character or error code.
+	 *
 	 * Clobber list : x0 - x3
 	 * ---------------------------------------------
 	 */
@@ -64,11 +49,7 @@ endfunc console_getc
 
 	/* ---------------------------------------------
 	 * int console_try_getc(void)
-	 * Function to get a character from the console.
-	 * It returns the character grabbed on success
-	 * or an error code on error. This function is
-	 * non-blocking, it returns immediately.
-	 * Out : w0 - Return character or error code.
+	 *
 	 * Clobber list : x0, x1
 	 * ---------------------------------------------
 	 */
@@ -79,11 +60,7 @@ endfunc console_try_getc
 
 	/* ---------------------------------------------
 	 * int console_flush(void)
-	 * Function to force a write of all buffered
-	 * data that hasn't been output. It returns 0
-	 * upon successful completion, otherwise it
-	 * returns an error code.
-	 * Out: w0 - Error code or 0.
+	 *
 	 * Clobber list : x0, x1
 	 * ---------------------------------------------
 	 */
diff --git a/include/drivers/console.h b/include/drivers/console.h
index 72decb9..4c22a99 100644
--- a/include/drivers/console.h
+++ b/include/drivers/console.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2018, Arm Limited. All rights reserved.
+ * Copyright (c) 2018-2019, Arm Limited. All rights reserved.
  *
  * SPDX-License-Identifier: BSD-3-Clause
  */
@@ -16,11 +16,39 @@
 
 #include <stdint.h>
 
+/*
+ * Function to initialize the console without a C Runtime to print debug
+ * information. It saves the console base to the data section. Returns 1 on
+ * success, 0 on error.
+ */
 int console_init(uintptr_t base_addr,
 		unsigned int uart_clk, unsigned int baud_rate);
+
+/*
+ * Function to output a character over the console. It returns the character
+ * printed on success or an error code.
+ */
 int console_putc(int c);
+
+/*
+ * Function to get a character from the console.  It returns the character
+ * grabbed on success or an error code on error. This function is blocking, it
+ * waits until there is an available character to return. Returns a character or
+ * error code.
+ */
 int console_getc(void);
+
+/*
+ * Function to get a character from the console.  It returns the character
+ * grabbed on success or an error code on error. This function is non-blocking,
+ * it returns immediately.
+ */
 int console_try_getc(void);
+
+/*
+ * Function to force a write of all buffered data that hasn't been output. It
+ * returns 0 upon successful completion, otherwise it returns an error code.
+ */
 int console_flush(void);
 
 #endif /* __ASSEMBLY__ */