Clean codes per ECC for TerminalDxe module.
[people/mcb30/edk2.git] / edk2 / MdeModulePkg / Universal / Console / TerminalDxe / TerminalConOut.c
index 06fda61..f6f78b6 100644 (file)
@@ -86,36 +86,30 @@ CHAR16 mSetCursorPositionString[]  = { ESC, '[', '0', '0', ';', '0', '0', 'H', 0
 //\r
 // Body of the ConOut functions\r
 //\r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.Reset().\r
+  If ExtendeVerification is TRUE, then perform dependent serial device reset,\r
+  and set display mode to mode 0.\r
+  If ExtendedVerification is FALSE, only set display mode to mode 0.\r
+\r
+  @param  This                  Indicates the calling context.\r
+  @param  ExtendedVerification  Indicates that the driver may perform a more\r
+                                exhaustive verification operation of the device\r
+                                during reset.\r
+\r
+  @return EFI_SUCCESS\r
+  @return The reset operation succeeds.\r
+  @return EFI_DEVICE_ERROR\r
+  @return The terminal is not functioning correctly or the serial port reset fails.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutReset (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,\r
   IN  BOOLEAN                          ExtendedVerification\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.Reset().\r
-    If ExtendeVerification is TRUE, then perform dependent serial device reset,\r
-    and set display mode to mode 0.\r
-    If ExtendedVerification is FALSE, only set display mode to mode 0.\r
-\r
-  Arguments:\r
-\r
-    This - Indicates the calling context.\r
-\r
-    ExtendedVerification - Indicates that the driver may perform a more exhaustive\r
-                           verification operation of the device during reset.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-       The reset operation succeeds.\r
-\r
-    EFI_DEVICE_ERROR\r
-      The terminal is not functioning correctly or the serial port reset fails.\r
-\r
---*/\r
 {\r
   EFI_STATUS    Status;\r
   TERMINAL_DEV  *TerminalDevice;\r
@@ -157,42 +151,29 @@ TerminalConOutReset (
   return Status;\r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.OutputString().\r
+  The Unicode string will be converted to terminal expressible data stream\r
+  and send to terminal via serial port.\r
+\r
+  @param  This                    Indicates the calling context.\r
+  @param  WString                 The Null-terminated Unicode string to be displayed\r
+                                  on the terminal screen.\r
+\r
+  @return EFI_SUCCESS             The string is output successfully.\r
+  @return EFI_DEVICE_ERROR        The serial port fails to send the string out.\r
+  @return EFI_WARN_UNKNOWN_GLYPH  Indicates that some of the characters in the Unicode string could not\r
+                                  be rendered and are skipped.\r
+  @return EFI_UNSUPPORTED\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutOutputString (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,\r
   IN  CHAR16                           *WString\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.OutputString().\r
-    The Unicode string will be converted to terminal expressible data stream\r
-    and send to terminal via serial port.\r
-\r
-\r
-  Arguments:\r
-\r
-    This - Indicates the calling context.\r
-\r
-    WString - The Null-terminated Unicode string to be displayed on\r
-              the terminal screen.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-       The string is output successfully.\r
-\r
-    EFI_DEVICE_ERROR\r
-      The serial port fails to send the string out.\r
-\r
-    EFI_WARN_UNKNOWN_GLYPH\r
-      Indicates that some of the characters in the Unicode string could not\r
-      be rendered and are skipped.\r
-\r
-    EFI_UNSUPPORTED\r
-\r
---*/\r
 {\r
   TERMINAL_DEV                *TerminalDevice;\r
   EFI_SIMPLE_TEXT_OUTPUT_MODE *Mode;\r
@@ -238,9 +219,9 @@ TerminalConOutOutputString (
 \r
     switch (TerminalDevice->TerminalType) {\r
 \r
-    case PcAnsiType:\r
-    case VT100Type:\r
-    case VT100PlusType:\r
+    case PCANSITYPE:\r
+    case VT100TYPE:\r
+    case VT100PLUSTYPE:\r
 \r
       if (!TerminalIsValidTextGraphics (*WString, &GraphicChar, &AsciiChar)) {\r
         //\r
@@ -266,7 +247,7 @@ TerminalConOutOutputString (
 \r
       }\r
 \r
-      if (TerminalDevice->TerminalType != PcAnsiType) {\r
+      if (TerminalDevice->TerminalType != PCANSITYPE) {\r
         GraphicChar = AsciiChar;\r
       }\r
 \r
@@ -284,7 +265,7 @@ TerminalConOutOutputString (
 \r
       break;\r
 \r
-    case VTUTF8Type:\r
+    case VTUTF8TYPE:\r
       UnicodeToUtf8 (*WString, &Utf8Char, &ValidBytes);\r
       Length = ValidBytes;\r
       Status = TerminalDevice->SerialIo->Write (\r
@@ -353,37 +334,27 @@ OutputError:
   return EFI_DEVICE_ERROR;\r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.TestString().\r
+  If one of the characters in the *Wstring is\r
+  neither valid Unicode drawing characters,\r
+  not ASCII code, then this function will return\r
+  EFI_UNSUPPORTED.\r
+\r
+  @param  This              Indicates the calling context.\r
+  @param  WString           The Null-terminated Unicode string to be tested.\r
+\r
+  @return EFI_SUCCESS       The terminal is capable of rendering the output string.\r
+  @return EFI_UNSUPPORTED   Some of the characters in the Unicode string cannot be rendered.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutTestString (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,\r
   IN  CHAR16                           *WString\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.TestString().\r
-    If one of the characters in the *Wstring is\r
-    neither valid Unicode drawing characters,\r
-    not ASCII code, then this function will return\r
-    EFI_UNSUPPORTED.\r
-\r
-\r
-  Arguments:\r
-\r
-    This - Indicates the calling context.\r
-\r
-    WString - The Null-terminated Unicode string to be tested.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-       The terminal is capable of rendering the output string.\r
-\r
-    EFI_UNSUPPORTED\r
-      Some of the characters in the Unicode string cannot be rendered.\r
-\r
---*/\r
 {\r
   TERMINAL_DEV  *TerminalDevice;\r
   EFI_STATUS    Status;\r
@@ -395,13 +366,13 @@ TerminalConOutTestString (
 \r
   switch (TerminalDevice->TerminalType) {\r
 \r
-  case PcAnsiType:\r
-  case VT100Type:\r
-  case VT100PlusType:\r
+  case PCANSITYPE:\r
+  case VT100TYPE:\r
+  case VT100PLUSTYPE:\r
     Status = AnsiTestString (TerminalDevice, WString);\r
     break;\r
 \r
-  case VTUTF8Type:\r
+  case VTUTF8TYPE:\r
     Status = VTUTF8TestString (TerminalDevice, WString);\r
     break;\r
 \r
@@ -413,6 +384,24 @@ TerminalConOutTestString (
   return Status;\r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.QueryMode().\r
+  It returns information for an available text mode\r
+  that the terminal supports.\r
+  In this driver, we support text mode 80x25 (mode 0),\r
+  80x50 (mode 1), 100x31 (mode 2).\r
+\r
+  @param This        Indicates the calling context.\r
+  @param ModeNumber  The mode number to return information on.\r
+  @param Columns     The returned columns of the requested mode.\r
+  @param Rows        The returned rows of the requested mode.\r
+\r
+  @return EFI_SUCCESS       The requested mode information is returned.\r
+  @return EFI_UNSUPPORTED   The mode number is not valid.\r
+  @return EFI_DEVICE_ERROR\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutQueryMode (\r
@@ -421,41 +410,6 @@ TerminalConOutQueryMode (
   OUT UINTN                            *Columns,\r
   OUT UINTN                            *Rows\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUT_PROTOCOL.QueryMode().\r
-    It returns information for an available text mode\r
-    that the terminal supports.\r
-    In this driver, we support text mode 80x25 (mode 0),\r
-    80x50 (mode 1), 100x31 (mode 2).\r
-\r
-\r
-  Arguments:\r
-\r
-    *This\r
-        Indicates the calling context.\r
-\r
-    ModeNumber\r
-        The mode number to return information on.\r
-\r
-    Columns\r
-        The returned columns of the requested mode.\r
-\r
-    Rows\r
-        The returned rows of the requested mode.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-      The requested mode information is returned.\r
-\r
-    EFI_UNSUPPORTED\r
-      The mode number is not valid.\r
-\r
-    EFI_DEVICE_ERROR\r
-\r
---*/\r
 {\r
   if (This->Mode->MaxMode > 3) {\r
     return EFI_DEVICE_ERROR;\r
@@ -478,39 +432,27 @@ TerminalConOutQueryMode (
   return EFI_UNSUPPORTED;\r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUT.SetMode().\r
+  Set the terminal to a specified display mode.\r
+  In this driver, we only support mode 0.\r
+\r
+  @param This          Indicates the calling context.\r
+  @param ModeNumber    The text mode to set.\r
+\r
+  @return EFI_SUCCESS       The requested text mode is set.\r
+  @return EFI_DEVICE_ERROR  The requested text mode cannot be set \r
+                            because of serial device error.\r
+  @return EFI_UNSUPPORTED   The text mode number is not valid.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutSetMode (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,\r
   IN  UINTN                            ModeNumber\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUT.SetMode().\r
-    Set the terminal to a specified display mode.\r
-    In this driver, we only support mode 0.\r
-\r
-  Arguments:\r
-\r
-    This\r
-        Indicates the calling context.\r
-\r
-    ModeNumber\r
-        The text mode to set.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-       The requested text mode is set.\r
-\r
-    EFI_DEVICE_ERROR\r
-      The requested text mode cannot be set because of serial device error.\r
-\r
-    EFI_UNSUPPORTED\r
-      The text mode number is not valid.\r
-\r
---*/\r
 {\r
   EFI_STATUS    Status;\r
   TERMINAL_DEV  *TerminalDevice;\r
@@ -550,38 +492,25 @@ TerminalConOutSetMode (
 \r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetAttribute().\r
+\r
+  @param This        Indicates the calling context.\r
+  @param Attribute   The attribute to set. Only bit0..6 are valid, all other bits\r
+                     are undefined and must be zero.\r
+\r
+  @return EFI_SUCCESS        The requested attribute is set.\r
+  @return EFI_DEVICE_ERROR   The requested attribute cannot be set due to serial port error.\r
+  @return EFI_UNSUPPORTED    The attribute requested is not defined by EFI spec.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutSetAttribute (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,\r
   IN  UINTN                            Attribute\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetAttribute().\r
-\r
-  Arguments:\r
-\r
-    This\r
-        Indicates the calling context.\r
-\r
-    Attribute\r
-        The attribute to set. Only bit0..6 are valid, all other bits\r
-        are undefined and must be zero.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-      The requested attribute is set.\r
-\r
-    EFI_DEVICE_ERROR\r
-      The requested attribute cannot be set due to serial port error.\r
-\r
-    EFI_UNSUPPORTED\r
-      The attribute requested is not defined by EFI spec.\r
-\r
---*/\r
 {\r
   UINT8         ForegroundControl;\r
   UINT8         BackgroundControl;\r
@@ -736,36 +665,24 @@ TerminalConOutSetAttribute (
 \r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.ClearScreen().\r
+  It clears the ANSI terminal's display to the\r
+  currently selected background color.\r
+\r
+  @param This     Indicates the calling context.\r
+\r
+  @return EFI_SUCCESS       The operation completed successfully.\r
+  @return EFI_DEVICE_ERROR  The terminal screen cannot be cleared due to serial port error.\r
+  @return EFI_UNSUPPORTED   The terminal is not in a valid display mode.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutClearScreen (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.ClearScreen().\r
-    It clears the ANSI terminal's display to the\r
-    currently selected background color.\r
-\r
-\r
-  Arguments:\r
-\r
-    This\r
-        Indicates the calling context.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-      The operation completed successfully.\r
-\r
-    EFI_DEVICE_ERROR\r
-      The terminal screen cannot be cleared due to serial port error.\r
-\r
-    EFI_UNSUPPORTED\r
-      The terminal is not in a valid display mode.\r
-\r
---*/\r
 {\r
   EFI_STATUS    Status;\r
   TERMINAL_DEV  *TerminalDevice;\r
@@ -788,6 +705,20 @@ TerminalConOutClearScreen (
   return Status;\r
 }\r
 \r
+\r
+/**\r
+  Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetCursorPosition().\r
+\r
+  @param This      Indicates the calling context.\r
+  @param Column    The row to set cursor to.\r
+  @param Row       The column to set cursor to.\r
+\r
+  @return EFI_SUCCESS       The operation completed successfully.\r
+  @return EFI_DEVICE_ERROR  The request fails due to serial port error.\r
+  @return EFI_UNSUPPORTED   The terminal is not in a valid text mode, or the cursor position\r
+                            is invalid for current mode.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutSetCursorPosition (\r
@@ -795,35 +726,6 @@ TerminalConOutSetCursorPosition (
   IN  UINTN                            Column,\r
   IN  UINTN                            Row\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.SetCursorPosition().\r
-\r
-  Arguments:\r
-\r
-    This\r
-        Indicates the calling context.\r
-\r
-    Column\r
-        The row to set cursor to.\r
-\r
-    Row\r
-        The column to set cursor to.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-      The operation completed successfully.\r
-\r
-    EFI_DEVICE_ERROR\r
-      The request fails due to serial port error.\r
-\r
-    EFI_UNSUPPORTED\r
-      The terminal is not in a valid text mode, or the cursor position\r
-      is invalid for current mode.\r
-\r
---*/\r
 {\r
   EFI_SIMPLE_TEXT_OUTPUT_MODE *Mode;\r
   UINTN                       MaxColumn;\r
@@ -879,36 +781,25 @@ TerminalConOutSetCursorPosition (
   return EFI_SUCCESS;\r
 }\r
 \r
+\r
+/**\r
+  Implements SIMPLE_TEXT_OUTPUT.EnableCursor().\r
+  In this driver, the cursor cannot be hidden.\r
+\r
+  @param This      Indicates the calling context.\r
+  @param Visible   If TRUE, the cursor is set to be visible,\r
+                   If FALSE, the cursor is set to be invisible.\r
+\r
+  @return EFI_SUCCESS      The request is valid.\r
+  @return EFI_UNSUPPORTED  The terminal does not support cursor hidden.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalConOutEnableCursor (\r
   IN  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *This,\r
   IN  BOOLEAN                          Visible\r
   )\r
-/*++\r
-  Routine Description:\r
-\r
-    Implements SIMPLE_TEXT_OUTPUT.EnableCursor().\r
-    In this driver, the cursor cannot be hidden.\r
-\r
-  Arguments:\r
-\r
-    This\r
-        Indicates the calling context.\r
-\r
-    Visible\r
-        If TRUE, the cursor is set to be visible,\r
-        If FALSE, the cursor is set to be invisible.\r
-\r
-  Returns:\r
-\r
-    EFI_SUCCESS\r
-      The request is valid.\r
-\r
-    EFI_UNSUPPORTED\r
-      The terminal does not support cursor hidden.\r
-\r
---*/\r
 {\r
   if (!Visible) {\r
     return EFI_UNSUPPORTED;\r
@@ -917,31 +808,25 @@ TerminalConOutEnableCursor (
   return EFI_SUCCESS;\r
 }\r
 \r
+\r
+/**\r
+  Detects if a Unicode char is for Box Drawing text graphics.\r
+\r
+  @param  Graphic      Unicode char to test.\r
+  @param  PcAnsi       Optional pointer to return PCANSI equivalent of\r
+                       Graphic.\r
+  @param  Ascii        Optional pointer to return ASCII equivalent of\r
+                       Graphic.\r
+\r
+  @return TRUE         If Graphic is a supported Unicode Box Drawing character.\r
+\r
+**/\r
 BOOLEAN\r
 TerminalIsValidTextGraphics (\r
   IN  CHAR16  Graphic,\r
   OUT CHAR8   *PcAnsi, OPTIONAL\r
   OUT CHAR8   *Ascii OPTIONAL\r
   )\r
-/*++\r
-\r
-Routine Description:\r
-\r
-    Detects if a Unicode char is for Box Drawing text graphics.\r
-\r
-Arguments:\r
-\r
-    Graphic  - Unicode char to test.\r
-\r
-    PcAnsi  - Optional pointer to return PCANSI equivalent of Graphic.\r
-\r
-    Ascii   - Optional pointer to return ASCII equivalent of Graphic.\r
-\r
-Returns:\r
-\r
-    TRUE if Graphic is a supported Unicode Box Drawing character.\r
-\r
---*/\r
 {\r
   UNICODE_TO_CHAR *Table;\r
 \r