Added some functions header.
[people/mcb30/edk2.git] / edk2 / MdeModulePkg / Universal / Console / TerminalDxe / Terminal.h
index eaa4a74..7410f33 100644 (file)
@@ -192,10 +192,8 @@ InitializeTerminal (
   @param  This                     Indicates the calling context.\r
   @param  ExtendedVerification     Skip by this driver.\r
 \r
-  @return EFI_SUCCESS\r
-  @return The reset operation succeeds.\r
-  @return EFI_DEVICE_ERROR\r
-  @return The dependent serial port reset fails.\r
+  @return EFI_SUCCESS              The reset operation succeeds.\r
+  @return EFI_DEVICE_ERROR         The dependent serial port reset fails.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -210,17 +208,14 @@ TerminalConInReset (
 /**\r
   Implements EFI_SIMPLE_TEXT_INPUT_PROTOCOL.ReadKeyStroke().\r
 \r
-  @param  This                     Indicates the calling context.\r
-  @param  Key                      A pointer to a buffer that is filled in with the\r
-                                   keystroke information for the key that was sent\r
-                                   from terminal.\r
-\r
-  @return EFI_SUCCESS\r
-  @return The keystroke information is returned successfully.\r
-  @return EFI_NOT_READY\r
-  @return There is no keystroke data available.\r
-  @return EFI_DEVICE_ERROR\r
-  @return The dependent serial device encounters error.\r
+  @param  This                Indicates the calling context.\r
+  @param  Key                 A pointer to a buffer that is filled in with the\r
+                              keystroke information for the key that was sent\r
+                              from terminal.\r
+\r
+  @return EFI_SUCCESS         The keystroke information is returned successfully.\r
+  @return EFI_NOT_READY       There is no keystroke data available.\r
+  @return EFI_DEVICE_ERROR    The dependent serial device encounters error.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -231,8 +226,8 @@ TerminalConInReadKeyStroke (
   )\r
 ;\r
 \r
-\r
 /**\r
+  Check if the key already has been registered.\r
 \r
   @param  RegsiteredData           A pointer to a buffer that is filled in with the\r
                                    keystroke state data for the key that was\r
@@ -419,10 +414,8 @@ TerminalConInWaitForKey (
                                 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
+  @return EFI_SUCCESS           The reset operation succeeds.\r
+  @return EFI_DEVICE_ERROR      The terminal is not functioning correctly or the serial port reset fails.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -442,11 +435,11 @@ TerminalConOutReset (
   @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
+  @retval EFI_SUCCESS             The string is output successfully.\r
+  @retval EFI_DEVICE_ERROR        The serial port fails to send the string out.\r
+  @retval 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
+  @retval EFI_UNSUPPORTED         If current display mode is out of range.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -609,6 +602,19 @@ TerminalConOutEnableCursor (
   )\r
 ;\r
 \r
+/**\r
+  Test to see if this driver supports ControllerHandle. \r
+\r
+  @param  This                Protocol instance pointer.\r
+  @param  ControllerHandle    Handle of device to test\r
+  @param  RemainingDevicePath Optional parameter use to pick a specific child\r
+                              device to start.\r
+\r
+  @retval EFI_SUCCESS         This driver supports this device\r
+  @retval EFI_ALREADY_STARTED This driver is already running on this device\r
+  @retval other               This driver does not support this device\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalDriverBindingSupported (\r
@@ -617,6 +623,22 @@ TerminalDriverBindingSupported (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath\r
   );\r
 \r
+/**\r
+  Start this driver on ControllerHandle by opening a Serial IO protocol,\r
+  reading Device Path, and creating a child handle with a Simple Text In,\r
+  Simple Text In Ex and Simple Text Out protocol, and device path protocol.\r
+  And store Console Device Environment Variables.\r
+\r
+  @param  This                 Protocol instance pointer.\r
+  @param  ControllerHandle     Handle of device to bind driver to\r
+  @param  RemainingDevicePath  Optional parameter use to pick a specific child\r
+                               device to start.\r
+\r
+  @retval EFI_SUCCESS          This driver is added to ControllerHandle\r
+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle\r
+  @retval other                This driver does not support this device\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalDriverBindingStart (\r
@@ -625,6 +647,21 @@ TerminalDriverBindingStart (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath\r
   );\r
 \r
+/**\r
+  Stop this driver on ControllerHandle by closing Simple Text In, Simple Text\r
+  In Ex, Simple Text Out protocol, and removing parent device path from\r
+  Console Device Environment Variables.    \r
+\r
+  @param  This              Protocol instance pointer.\r
+  @param  ControllerHandle  Handle of device to stop driver on\r
+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of\r
+                            children is zero stop the entire bus driver.\r
+  @param  ChildHandleBuffer List of Child Handles to Stop.\r
+\r
+  @retval EFI_SUCCESS       This driver is removed ControllerHandle.\r
+  @retval other             This driver could not be removed from this device.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 TerminalDriverBindingStop (\r
@@ -770,11 +807,9 @@ TerminalComponentNameGetControllerName (
 \r
   @param  This                     Indicates the calling context.\r
 \r
-  @return EFI_SUCCESS\r
-  @return There is key pending.\r
-  @return EFI_NOT_READY\r
-  @return There is no key pending.\r
-  @return EFI_DEVICE_ERROR\r
+  @retval EFI_SUCCESS              There is key pending.\r
+  @retval EFI_NOT_READY            There is no key pending.\r
+  @retval EFI_DEVICE_ERROR         If Serial IO is not attched to serial device.\r
 \r
 **/\r
 EFI_STATUS\r
@@ -783,6 +818,15 @@ TerminalConInCheckForKey (
   )\r
 ;\r
 \r
+/**\r
+  Update terminal device path in Console Device Environment Variables.\r
+\r
+  @param  VariableName           The Console Device Environment Variable.\r
+  @param  ParentDevicePath       The terminal devcie path to be updated.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 TerminalUpdateConsoleDevVariable (\r
   IN CHAR16                    *VariableName,\r
@@ -827,6 +871,18 @@ TerminalGetVariableAndSize (
   )\r
 ;\r
 \r
+/**\r
+  Build termial device path according to terminal type.\r
+\r
+  @param  TerminalType           The terminal type is PC ANSI, VT100, VT100+ or VT-UTF8.\r
+  @param  ParentDevicePath       Parent devcie path.\r
+  @param  TerminalDevicePath     Returned terminal device path, if building successfully.\r
+\r
+  @retval EFI_UNSUPPORTED        Terminal does not belong to the supported type.\r
+  @retval EFI_OUT_OF_RESOURCES   Generate terminal device path failed.\r
+  @retval EFI_SUCCESS            Build terminal device path successfully.\r
+\r
+**/\r
 EFI_STATUS\r
 SetTerminalDevicePath (\r
   IN  UINT8                       TerminalType,\r
@@ -835,18 +891,42 @@ SetTerminalDevicePath (
   )\r
 ;\r
 \r
+/**\r
+  Initialize the Raw Data FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 InitializeRawFiFo (\r
   IN  TERMINAL_DEV  *TerminalDevice\r
   )\r
 ;\r
 \r
+/**\r
+  Initialize the Unicode FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 InitializeUnicodeFiFo (\r
   IN  TERMINAL_DEV  *TerminalDevice\r
   )\r
 ;\r
 \r
+/**\r
+  Initialize the EFI Key FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 InitializeEfiKeyFiFo (\r
   IN  TERMINAL_DEV  *TerminalDevice\r
@@ -1067,12 +1147,29 @@ IsUnicodeFiFoFull (
   )\r
 ;\r
 \r
+/**\r
+  Count Unicode FIFO buffer.\r
+\r
+  @param  TerminalDevice       Terminal driver private structure\r
+\r
+  @return The count in bytes of Unicode FIFO.\r
+\r
+**/\r
 UINT8\r
 UnicodeFiFoGetKeyCount (\r
   TERMINAL_DEV    *TerminalDevice\r
   )\r
 ;\r
 \r
+/**\r
+  Translate raw data into Unicode (according to different encode), and \r
+  translate Unicode into key information. (according to different standard). \r
+\r
+  @param  TerminalDevice       Terminal driver private structure.\r
+\r
+  @return none.\r
+\r
+**/\r
 VOID\r
 TranslateRawDataToEfiKey (\r
   IN  TERMINAL_DEV      *TerminalDevice\r
@@ -1082,18 +1179,104 @@ TranslateRawDataToEfiKey (
 //\r
 // internal functions for PC ANSI\r
 //\r
+\r
+/**\r
+  Translate all raw data in the Raw FIFI into unicode, and insert\r
+  them into Unicode FIFO.\r
+\r
+  @param TerminalDevice          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 AnsiRawDataToUnicode (\r
-  IN  TERMINAL_DEV    *PcAnsiDevice\r
+  IN  TERMINAL_DEV    *TerminalDevice\r
   )\r
 ;\r
 \r
+/**\r
+  Converts a stream of Unicode characters from a terminal input device into EFI Keys that\r
+  can be read through the Simple Input Protocol. \r
+  \r
+  The table below shows the keyboard input mappings that this function supports.\r
+  If the ESC sequence listed in one of the columns is presented, then it is translated\r
+  into the coorespoding EFI Scan Code.  If a matching sequence is not found, then the raw\r
+  key strokes are converted into EFI Keys.\r
+\r
+  2 seconds are allowed for an ESC sequence to be completed.  If the ESC sequence is not\r
+  completed in 2 seconds, then the raw key strokes of the partial ESC sequence are\r
+  converted into EFI Keys.\r
+  There is one special input sequence that will force the system to reset.\r
+  This is ESC R ESC r ESC R.\r
+\r
+  Symbols used in table below\r
+  ===========================\r
+    ESC = 0x1B\r
+    CSI = 0x9B\r
+    DEL = 0x7f\r
+    ^   = CTRL\r
+  +=========+======+===========+==========+==========+\r
+  |         | EFI  | UEFI 2.0  |          |          |\r
+  |         | Scan |           |  VT100+  |          |\r
+  |   KEY   | Code |  PC ANSI  |  VTUTF8  |   VT100  |\r
+  +=========+======+===========+==========+==========+\r
+  | NULL    | 0x00 |           |          |          |\r
+  | UP      | 0x01 | ESC [ A   | ESC [ A  | ESC [ A  |\r
+  | DOWN    | 0x02 | ESC [ B   | ESC [ B  | ESC [ B  |\r
+  | RIGHT   | 0x03 | ESC [ C   | ESC [ C  | ESC [ C  |\r
+  | LEFT    | 0x04 | ESC [ D   | ESC [ D  | ESC [ D  |\r
+  | HOME    | 0x05 | ESC [ H   | ESC h    | ESC [ H  |\r
+  | END     | 0x06 | ESC [ F   | ESC k    | ESC [ K  |\r
+  | INSERT  | 0x07 | ESC [ @   | ESC +    | ESC [ @  |\r
+  |         |      | ESC [ L   |          | ESC [ L  |\r
+  | DELETE  | 0x08 | ESC [ X   | ESC -    | ESC [ P  |\r
+  | PG UP   | 0x09 | ESC [ I   | ESC ?    | ESC [ V  |\r
+  |         |      |           |          | ESC [ ?  |\r
+  | PG DOWN | 0x0A | ESC [ G   | ESC /    | ESC [ U  |\r
+  |         |      |           |          | ESC [ /  |\r
+  | F1      | 0x0B | ESC [ M   | ESC 1    | ESC O P  |\r
+  | F2      | 0x0C | ESC [ N   | ESC 2    | ESC O Q  |\r
+  | F3      | 0x0D | ESC [ O   | ESC 3    | ESC O w  |\r
+  | F4      | 0x0E | ESC [ P   | ESC 4    | ESC O x  |\r
+  | F5      | 0x0F | ESC [ Q   | ESC 5    | ESC O t  |\r
+  | F6      | 0x10 | ESC [ R   | ESC 6    | ESC O u  |\r
+  | F7      | 0x11 | ESC [ S   | ESC 7    | ESC O q  |\r
+  | F8      | 0x12 | ESC [ T   | ESC 8    | ESC O r  |\r
+  | F9      | 0x13 | ESC [ U   | ESC 9    | ESC O p  |\r
+  | F10     | 0x14 | ESC [ V   | ESC 0    | ESC O M  |\r
+  | Escape  | 0x17 | ESC       | ESC      | ESC      |\r
+  | F11     | 0x15 |           | ESC !    |          |\r
+  | F12     | 0x16 |           | ESC @    |          |\r
+  +=========+======+===========+==========+==========+\r
+  \r
+  Special Mappings\r
+  ================\r
+  ESC R ESC r ESC R = Reset System\r
+\r
+\r
+  @param TerminalDevice   The terminal device to use to translate raw input into EFI Keys\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 UnicodeToEfiKey (\r
   IN  TERMINAL_DEV    *PcAnsiDevice\r
   )\r
 ;\r
 \r
+/**\r
+  Check if input string is valid Ascii string, valid EFI control characters\r
+  or valid text graphics.\r
+\r
+  @param  TerminalDevice          The terminal device.\r
+  @param  WString                 The input string.          \r
\r
+  @retval EFI_UNSUPPORTED         If not all input characters are valid.\r
+  @retval EFI_SUCCESS             If all input characters are valid.\r
+\r
+**/\r
 EFI_STATUS\r
 AnsiTestString (\r
   IN  TERMINAL_DEV    *TerminalDevice,\r
@@ -1104,12 +1287,31 @@ AnsiTestString (
 //\r
 // internal functions for VTUTF8\r
 //\r
+\r
+/**\r
+  Translate all VT-UTF8 characters in the Raw FIFI into unicode characters, \r
+  and insert them into Unicode FIFO.\r
+\r
+  @param VtUtf8Device          The terminal device.\r
+\r
+  @return None.\r
+\r
+**/\r
 VOID\r
 VTUTF8RawDataToUnicode (\r
   IN  TERMINAL_DEV    *VtUtf8Device\r
   )\r
 ;\r
 \r
+/**\r
+  Check if input string is valid VT-UTF8 string.\r
+\r
+  @param  TerminalDevice          The terminal device.\r
+  @param  WString                 The input string.          \r
\r
+  @retval EFI_SUCCESS             If all input characters are valid.\r
+\r
+**/\r
 EFI_STATUS\r
 VTUTF8TestString (\r
   IN  TERMINAL_DEV    *TerminalDevice,\r
@@ -1117,6 +1319,24 @@ VTUTF8TestString (
   )\r
 ;\r
 \r
+/** \r
+  Translate one Unicode character into VT-UTF8 characters.\r
+\r
+  UTF8 Encoding Table\r
+  Bits per Character | Unicode Character Range | Unicode Binary  Encoding |    UTF8 Binary Encoding\r
+        0-7             |     0x0000 - 0x007F     |     00000000 0xxxxxxx        |   0xxxxxxx\r
+        8-11          |     0x0080 - 0x07FF       |     00000xxx xxxxxxxx        |   110xxxxx 10xxxxxx\r
+       12-16          |     0x0800 - 0xFFFF       |     xxxxxxxx xxxxxxxx        |   1110xxxx 10xxxxxx 10xxxxxx\r
+\r
+\r
+  @param  Unicode          Unicode character need translating.\r
+  @param  Utf8Char         Return VT-UTF8 character set.\r
+  @param  ValidBytes       The count of valid VT-UTF8 characters. If\r
+                           ValidBytes is zero, no valid VT-UTF8 returned.\r
+  \r
+  @return None.\r
+\r
+**/\r
 VOID\r
 UnicodeToUtf8 (\r
   IN  CHAR16      Unicode,\r
@@ -1125,6 +1345,17 @@ UnicodeToUtf8 (
   )\r
 ;\r
 \r
+/**\r
+  Get one valid VT-UTF8 characters set from Raw Data FIFO.\r
+\r
+  @param  Utf8Device          The terminal device.\r
+  @param  Utf8Char            Returned valid VT-UTF8 characters set.\r
+  @param  ValidBytes          The count of returned VT-VTF8 characters. \r
+                              If ValidBytes is zero, no valid VT-UTF8 returned.\r
+\r
+  @retval None.\r
+\r
+**/\r
 VOID\r
 GetOneValidUtf8Char (\r
   IN  TERMINAL_DEV      *Utf8Device,\r
@@ -1133,6 +1364,23 @@ GetOneValidUtf8Char (
   )\r
 ;\r
 \r
+/** \r
+  Translate VT-UTF8 characters into one Unicode character.\r
+\r
+  UTF8 Encoding Table\r
+  Bits per Character | Unicode Character Range | Unicode Binary  Encoding |    UTF8 Binary Encoding\r
+        0-7             |     0x0000 - 0x007F     |     00000000 0xxxxxxx        |   0xxxxxxx\r
+        8-11          |     0x0080 - 0x07FF       |     00000xxx xxxxxxxx        |   110xxxxx 10xxxxxx\r
+       12-16          |     0x0800 - 0xFFFF       |     xxxxxxxx xxxxxxxx        |   1110xxxx 10xxxxxx 10xxxxxx\r
+\r
+\r
+  @param  Utf8Char         VT-UTF8 character set needs translating.\r
+  @param  ValidBytes       The count of valid VT-UTF8 characters.\r
+  @param  UnicodeChar      Returned unicode character. \r
+  \r
+  @return None.\r
+\r
+**/\r
 VOID\r
 Utf8ToUnicode (\r
   IN  UTF8_CHAR       Utf8Char,\r
@@ -1144,6 +1392,19 @@ Utf8ToUnicode (
 //\r
 // functions for boxdraw unicode\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
@@ -1152,12 +1413,30 @@ TerminalIsValidTextGraphics (
   )\r
 ;\r
 \r
+/**\r
+  Detects if a valid ASCII char.\r
+\r
+  @param  Ascii        An ASCII character.\r
+                       \r
+  @retval TRUE         If it is a valid ASCII character.\r
+  @retval FALSE        If it is not a valid ASCII character.\r
+\r
+**/\r
 BOOLEAN\r
 TerminalIsValidAscii (\r
   IN  CHAR16  Ascii\r
   )\r
 ;\r
 \r
+/**\r
+  Detects if a valid EFI control character.\r
+\r
+  @param  CharC        An input EFI Control character.\r
+                       \r
+  @retval TRUE         If it is a valid EFI control character.\r
+  @retval FALSE        If it is not a valid EFI control character.\r
+\r
+**/\r
 BOOLEAN\r
 TerminalIsValidEfiCntlChar (\r
   IN  CHAR16  CharC\r