efi_loader: comments EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL

Provide missing comments for the functions implementing the
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>

1 files changed, 115 insertions, 9 deletions

diff --git a/lib/efi_loader/efi_console.c b/lib/efi_loader/efi_console.c
index ac0dec1146f..426de779517 100644
--- a/lib/efi_loader/efi_console.c
+++ b/lib/efi_loader/efi_console.c
@@ -80,13 +80,13 @@ static int term_get_char(s32 *c)
 	return 0;
 }
 
-/*
+/**
  * Receive and parse a reply from the terminal.
  *
  * @n:		array of return values
  * @num:	number of return values expected
  * @end_char:	character indicating end of terminal message
- * @return:	non-zero indicates error
+ * Return:	non-zero indicates error
  */
 static int term_read_reply(int *n, int num, char end_char)
 {
@@ -127,6 +127,17 @@ static int term_read_reply(int *n, int num, char end_char)
 	return 0;
 }
 
+/**
+ * efi_cout_output_string() - write Unicode string to console
+ *
+ * This function implements the OutputString service of the simple text output
+ * protocol. See the Unified Extensible Firmware Interface (UEFI) specification
+ * for details.
+ *
+ * @this:	simple text output protocol
+ * @string:	u16 string
+ * Return:	status code
+ */
 static efi_status_t EFIAPI efi_cout_output_string(
 			struct efi_simple_text_output_protocol *this,
 			const efi_string_t string)
@@ -202,6 +213,20 @@ out:
 	return EFI_EXIT(ret);
 }
 
+/**
+ * efi_cout_test_string() - test writing Unicode string to console
+ *
+ * This function implements the TestString service of the simple text output
+ * protocol. See the Unified Extensible Firmware Interface (UEFI) specification
+ * for details.
+ *
+ * As in OutputString we simply convert UTF-16 to UTF-8 there are no unsupported
+ * code points and we can always return EFI_SUCCESS.
+ *
+ * @this:	simple text output protocol
+ * @string:	u16 string
+ * Return:	status code
+ */
 static efi_status_t EFIAPI efi_cout_test_string(
 			struct efi_simple_text_output_protocol *this,
 			const efi_string_t string)
@@ -210,6 +235,15 @@ static efi_status_t EFIAPI efi_cout_test_string(
 	return EFI_EXIT(EFI_SUCCESS);
 }
 
+/**
+ * cout_mode_matches() - check if mode has given terminal size
+ *
+ * @mode:	text mode
+ * @rows:	number of rows
+ * @cols:	number of columns
+ * Return:	true if number of rows and columns matches the mode and
+ *		the mode is present
+ */
 static bool cout_mode_matches(struct cout_mode *mode, int rows, int cols)
 {
 	if (!mode->present)
@@ -221,6 +255,9 @@ static bool cout_mode_matches(struct cout_mode *mode, int rows, int cols)
 /**
  * query_console_serial() - query console size
  *
+ * When using a serial console or the net console we can only devise the
+ * terminal size by querying the terminal using ECMA-48 control sequences.
+ *
  * @rows:	pointer to return number of rows
  * @cols:	pointer to return number of columns
  * Returns:	0 on success
@@ -261,8 +298,8 @@ out:
 	return ret;
 }
 
-/*
- * Update the mode table.
+/**
+ * query_console_size() - update the mode table.
  *
  * By default the only mode available is 80x25. If the console has at least 50
  * lines, enable mode 80x50. If we can query the console size and it is neither
@@ -306,6 +343,20 @@ static void query_console_size(void)
 	}
 }
 
+
+/**
+ * efi_cout_query_mode() - get terminal size for a text mode
+ *
+ * This function implements the QueryMode service of the simple text output
+ * protocol. See the Unified Extensible Firmware Interface (UEFI) specification
+ * for details.
+ *
+ * @this:		simple text output protocol
+ * @mode_number:	mode number to retrieve information on
+ * @columns:		number of columns
+ * @rows:		number of rows
+ * Return:		status code
+ */
 static efi_status_t EFIAPI efi_cout_query_mode(
 			struct efi_simple_text_output_protocol *this,
 			unsigned long mode_number, unsigned long *columns,
@@ -341,7 +392,17 @@ static const struct {
 	{ 37, 47 },     /* 7: light gray, map to white */
 };
 
-/* See EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetAttribute(). */
+/**
+ * efi_cout_set_attribute() - set fore- and background color
+ *
+ * This function implements the SetAttribute service of the simple text output
+ * protocol. See the Unified Extensible Firmware Interface (UEFI) specification
+ * for details.
+ *
+ * @this:	simple text output protocol
+ * @attribute:	foreground color - bits 0-3, background color - bits 4-6
+ * Return:	status code
+ */
 static efi_status_t EFIAPI efi_cout_set_attribute(
 			struct efi_simple_text_output_protocol *this,
 			unsigned long attribute)
@@ -364,9 +425,9 @@ static efi_status_t EFIAPI efi_cout_set_attribute(
 /**
  * efi_cout_clear_screen() - clear screen
  *
- * This function implements the ClearScreen service of the
- * EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL. See the Unified Extensible Firmware
- * Interface (UEFI) specification for details.
+ * This function implements the ClearScreen service of the simple text output
+ * protocol. See the Unified Extensible Firmware Interface (UEFI) specification
+ * for details.
  *
  * @this:	pointer to the protocol instance
  * Return:	status code
@@ -387,6 +448,17 @@ static efi_status_t EFIAPI efi_cout_clear_screen(
 	return EFI_EXIT(EFI_SUCCESS);
 }
 
+/**
+ * efi_cout_clear_set_mode() - set text model
+ *
+ * This function implements the SetMode service of the simple text output
+ * protocol. See the Unified Extensible Firmware  Interface (UEFI) specification
+ * for details.
+ *
+ * @this:		pointer to the protocol instance
+ * @mode_number:	number of the text mode to set
+ * Return:		status code
+ */
 static efi_status_t EFIAPI efi_cout_set_mode(
 			struct efi_simple_text_output_protocol *this,
 			unsigned long mode_number)
@@ -405,6 +477,17 @@ static efi_status_t EFIAPI efi_cout_set_mode(
 	return EFI_EXIT(EFI_SUCCESS);
 }
 
+/**
+ * efi_cout_reset() - reset the terminal
+ *
+ * This function implements the Reset service of the simple text output
+ * protocol. See the Unified Extensible Firmware  Interface (UEFI) specification
+ * for details.
+ *
+ * @this:			pointer to the protocol instance
+ * @extended_verification:	if set an extended verification may be executed
+ * Return:			status code
+ */
 static efi_status_t EFIAPI efi_cout_reset(
 			struct efi_simple_text_output_protocol *this,
 			char extended_verification)
@@ -420,6 +503,18 @@ static efi_status_t EFIAPI efi_cout_reset(
 	return EFI_EXIT(EFI_SUCCESS);
 }
 
+/**
+ * efi_cout_set_cursor_position() - reset the terminal
+ *
+ * This function implements the SetCursorPosition service of the simple text
+ * output protocol. See the Unified Extensible Firmware  Interface (UEFI)
+ * specification for details.
+ *
+ * @this:	pointer to the protocol instance
+ * @column:	column to move to
+ * @row:	row to move to
+ * Return:	status code
+ */
 static efi_status_t EFIAPI efi_cout_set_cursor_position(
 			struct efi_simple_text_output_protocol *this,
 			unsigned long column, unsigned long row)
@@ -451,6 +546,17 @@ out:
 	return EFI_EXIT(ret);
 }
 
+/**
+ * efi_cout_enable_cursor() - enable the cursor
+ *
+ * This function implements the EnableCursor service of the simple text  output
+ * protocol. See the Unified Extensible Firmware  Interface (UEFI) specification
+ * for details.
+ *
+ * @this:	pointer to the protocol instance
+ * @enable:	if true enable, if false disable the cursor
+ * Return:	status code
+ */
 static efi_status_t EFIAPI efi_cout_enable_cursor(
 			struct efi_simple_text_output_protocol *this,
 			bool enable)
@@ -522,7 +628,7 @@ void set_shift_mask(int mod, struct efi_key_state *key_state)
  * This gets called when we have already parsed CSI.
  *
  * @key_state:  receives the state of the shift, alt, control, and logo keys
- * @return:	the unmodified code
+ * Return:	the unmodified code
  */
 static int analyze_modifiers(struct efi_key_state *key_state)
 {