Added some functions header.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5406 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 309 insertions, 30 deletions

diff --git a/MdeModulePkg/Universal/Console/TerminalDxe/Terminal.h b/MdeModulePkg/Universal/Console/TerminalDxe/Terminal.h
index eaa4a74..7410f33 100644
--- a/MdeModulePkg/Universal/Console/TerminalDxe/Terminal.h
+++ b/MdeModulePkg/Universal/Console/TerminalDxe/Terminal.h
@@ -192,10 +192,8 @@ InitializeTerminal (
   @param  This                     Indicates the calling context.

   @param  ExtendedVerification     Skip by this driver.

 

-  @return EFI_SUCCESS

-  @return The reset operation succeeds.

-  @return EFI_DEVICE_ERROR

-  @return The dependent serial port reset fails.

+  @return EFI_SUCCESS              The reset operation succeeds.

+  @return EFI_DEVICE_ERROR         The dependent serial port reset fails.

 

 **/

 EFI_STATUS

@@ -210,17 +208,14 @@ TerminalConInReset (
 /**

   Implements EFI_SIMPLE_TEXT_INPUT_PROTOCOL.ReadKeyStroke().

 

-  @param  This                     Indicates the calling context.

-  @param  Key                      A pointer to a buffer that is filled in with the

-                                   keystroke information for the key that was sent

-                                   from terminal.

-

-  @return EFI_SUCCESS

-  @return The keystroke information is returned successfully.

-  @return EFI_NOT_READY

-  @return There is no keystroke data available.

-  @return EFI_DEVICE_ERROR

-  @return The dependent serial device encounters error.

+  @param  This                Indicates the calling context.

+  @param  Key                 A pointer to a buffer that is filled in with the

+                              keystroke information for the key that was sent

+                              from terminal.

+

+  @return EFI_SUCCESS         The keystroke information is returned successfully.

+  @return EFI_NOT_READY       There is no keystroke data available.

+  @return EFI_DEVICE_ERROR    The dependent serial device encounters error.

 

 **/

 EFI_STATUS

@@ -231,8 +226,8 @@ TerminalConInReadKeyStroke (
   )

 ;

 

-

 /**

+  Check if the key already has been registered.

 

   @param  RegsiteredData           A pointer to a buffer that is filled in with the

                                    keystroke state data for the key that was

@@ -419,10 +414,8 @@ TerminalConInWaitForKey (
                                 exhaustive verification operation of the device

                                 during reset.

 

-  @return EFI_SUCCESS

-  @return The reset operation succeeds.

-  @return EFI_DEVICE_ERROR

-  @return The terminal is not functioning correctly or the serial port reset fails.

+  @return EFI_SUCCESS           The reset operation succeeds.

+  @return EFI_DEVICE_ERROR      The terminal is not functioning correctly or the serial port reset fails.

 

 **/

 EFI_STATUS

@@ -442,11 +435,11 @@ TerminalConOutReset (
   @param  WString                 The Null-terminated Unicode string to be displayed

                                   on the terminal screen.

 

-  @return EFI_SUCCESS             The string is output successfully.

-  @return EFI_DEVICE_ERROR        The serial port fails to send the string out.

-  @return EFI_WARN_UNKNOWN_GLYPH  Indicates that some of the characters in the Unicode string could not

+  @retval EFI_SUCCESS             The string is output successfully.

+  @retval EFI_DEVICE_ERROR        The serial port fails to send the string out.

+  @retval EFI_WARN_UNKNOWN_GLYPH  Indicates that some of the characters in the Unicode string could not

                                   be rendered and are skipped.

-  @return EFI_UNSUPPORTED

+  @retval EFI_UNSUPPORTED         If current display mode is out of range.

 

 **/

 EFI_STATUS

@@ -609,6 +602,19 @@ TerminalConOutEnableCursor (
   )

 ;

 

+/**

+  Test to see if this driver supports ControllerHandle. 

+

+  @param  This                Protocol instance pointer.

+  @param  ControllerHandle    Handle of device to test

+  @param  RemainingDevicePath Optional parameter use to pick a specific child

+                              device to start.

+

+  @retval EFI_SUCCESS         This driver supports this device

+  @retval EFI_ALREADY_STARTED This driver is already running on this device

+  @retval other               This driver does not support this device

+

+**/

 EFI_STATUS

 EFIAPI

 TerminalDriverBindingSupported (

@@ -617,6 +623,22 @@ TerminalDriverBindingSupported (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   );

 

+/**

+  Start this driver on ControllerHandle by opening a Serial IO protocol,

+  reading Device Path, and creating a child handle with a Simple Text In,

+  Simple Text In Ex and Simple Text Out protocol, and device path protocol.

+  And store Console Device Environment Variables.

+

+  @param  This                 Protocol instance pointer.

+  @param  ControllerHandle     Handle of device to bind driver to

+  @param  RemainingDevicePath  Optional parameter use to pick a specific child

+                               device to start.

+

+  @retval EFI_SUCCESS          This driver is added to ControllerHandle

+  @retval EFI_ALREADY_STARTED  This driver is already running on ControllerHandle

+  @retval other                This driver does not support this device

+

+**/

 EFI_STATUS

 EFIAPI

 TerminalDriverBindingStart (

@@ -625,6 +647,21 @@ TerminalDriverBindingStart (
   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath

   );

 

+/**

+  Stop this driver on ControllerHandle by closing Simple Text In, Simple Text

+  In Ex, Simple Text Out protocol, and removing parent device path from

+  Console Device Environment Variables.    

+

+  @param  This              Protocol instance pointer.

+  @param  ControllerHandle  Handle of device to stop driver on

+  @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

+                            children is zero stop the entire bus driver.

+  @param  ChildHandleBuffer List of Child Handles to Stop.

+

+  @retval EFI_SUCCESS       This driver is removed ControllerHandle.

+  @retval other             This driver could not be removed from this device.

+

+**/

 EFI_STATUS

 EFIAPI

 TerminalDriverBindingStop (

@@ -770,11 +807,9 @@ TerminalComponentNameGetControllerName (
 

   @param  This                     Indicates the calling context.

 

-  @return EFI_SUCCESS

-  @return There is key pending.

-  @return EFI_NOT_READY

-  @return There is no key pending.

-  @return EFI_DEVICE_ERROR

+  @retval EFI_SUCCESS              There is key pending.

+  @retval EFI_NOT_READY            There is no key pending.

+  @retval EFI_DEVICE_ERROR         If Serial IO is not attched to serial device.

 

 **/

 EFI_STATUS

@@ -783,6 +818,15 @@ TerminalConInCheckForKey (
   )

 ;

 

+/**

+  Update terminal device path in Console Device Environment Variables.

+

+  @param  VariableName           The Console Device Environment Variable.

+  @param  ParentDevicePath       The terminal devcie path to be updated.

+

+  @return None.

+

+**/

 VOID

 TerminalUpdateConsoleDevVariable (

   IN CHAR16                    *VariableName,

@@ -827,6 +871,18 @@ TerminalGetVariableAndSize (
   )

 ;

 

+/**

+  Build termial device path according to terminal type.

+

+  @param  TerminalType           The terminal type is PC ANSI, VT100, VT100+ or VT-UTF8.

+  @param  ParentDevicePath       Parent devcie path.

+  @param  TerminalDevicePath     Returned terminal device path, if building successfully.

+

+  @retval EFI_UNSUPPORTED        Terminal does not belong to the supported type.

+  @retval EFI_OUT_OF_RESOURCES   Generate terminal device path failed.

+  @retval EFI_SUCCESS            Build terminal device path successfully.

+

+**/

 EFI_STATUS

 SetTerminalDevicePath (

   IN  UINT8                       TerminalType,

@@ -835,18 +891,42 @@ SetTerminalDevicePath (
   )

 ;

 

+/**

+  Initialize the Raw Data FIFO.

+

+  @param TerminalDevice          The terminal device.

+

+  @return None.

+

+**/

 VOID

 InitializeRawFiFo (

   IN  TERMINAL_DEV  *TerminalDevice

   )

 ;

 

+/**

+  Initialize the Unicode FIFO.

+

+  @param TerminalDevice          The terminal device.

+

+  @return None.

+

+**/

 VOID

 InitializeUnicodeFiFo (

   IN  TERMINAL_DEV  *TerminalDevice

   )

 ;

 

+/**

+  Initialize the EFI Key FIFO.

+

+  @param TerminalDevice          The terminal device.

+

+  @return None.

+

+**/

 VOID

 InitializeEfiKeyFiFo (

   IN  TERMINAL_DEV  *TerminalDevice

@@ -1067,12 +1147,29 @@ IsUnicodeFiFoFull (
   )

 ;

 

+/**

+  Count Unicode FIFO buffer.

+

+  @param  TerminalDevice       Terminal driver private structure

+

+  @return The count in bytes of Unicode FIFO.

+

+**/

 UINT8

 UnicodeFiFoGetKeyCount (

   TERMINAL_DEV    *TerminalDevice

   )

 ;

 

+/**

+  Translate raw data into Unicode (according to different encode), and 

+  translate Unicode into key information. (according to different standard). 

+

+  @param  TerminalDevice       Terminal driver private structure.

+

+  @return none.

+

+**/

 VOID

 TranslateRawDataToEfiKey (

   IN  TERMINAL_DEV      *TerminalDevice

@@ -1082,18 +1179,104 @@ TranslateRawDataToEfiKey (
 //

 // internal functions for PC ANSI

 //

+

+/**

+  Translate all raw data in the Raw FIFI into unicode, and insert

+  them into Unicode FIFO.

+

+  @param TerminalDevice          The terminal device.

+

+  @return None.

+

+**/

 VOID

 AnsiRawDataToUnicode (

-  IN  TERMINAL_DEV    *PcAnsiDevice

+  IN  TERMINAL_DEV    *TerminalDevice

   )

 ;

 

+/**

+  Converts a stream of Unicode characters from a terminal input device into EFI Keys that

+  can be read through the Simple Input Protocol. 

+  

+  The table below shows the keyboard input mappings that this function supports.

+  If the ESC sequence listed in one of the columns is presented, then it is translated

+  into the coorespoding EFI Scan Code.  If a matching sequence is not found, then the raw

+  key strokes are converted into EFI Keys.

+

+  2 seconds are allowed for an ESC sequence to be completed.  If the ESC sequence is not

+  completed in 2 seconds, then the raw key strokes of the partial ESC sequence are

+  converted into EFI Keys.

+  There is one special input sequence that will force the system to reset.

+  This is ESC R ESC r ESC R.

+

+  Symbols used in table below

+  ===========================

+    ESC = 0x1B

+    CSI = 0x9B

+    DEL = 0x7f

+    ^   = CTRL

+  +=========+======+===========+==========+==========+

+  |         | EFI  | UEFI 2.0  |          |          |

+  |         | Scan |           |  VT100+  |          |

+  |   KEY   | Code |  PC ANSI  |  VTUTF8  |   VT100  |

+  +=========+======+===========+==========+==========+

+  | NULL    | 0x00 |           |          |          |

+  | UP      | 0x01 | ESC [ A   | ESC [ A  | ESC [ A  |

+  | DOWN    | 0x02 | ESC [ B   | ESC [ B  | ESC [ B  |

+  | RIGHT   | 0x03 | ESC [ C   | ESC [ C  | ESC [ C  |

+  | LEFT    | 0x04 | ESC [ D   | ESC [ D  | ESC [ D  |

+  | HOME    | 0x05 | ESC [ H   | ESC h    | ESC [ H  |

+  | END     | 0x06 | ESC [ F   | ESC k    | ESC [ K  |

+  | INSERT  | 0x07 | ESC [ @   | ESC +    | ESC [ @  |

+  |         |      | ESC [ L   |          | ESC [ L  |

+  | DELETE  | 0x08 | ESC [ X   | ESC -    | ESC [ P  |

+  | PG UP   | 0x09 | ESC [ I   | ESC ?    | ESC [ V  |

+  |         |      |           |          | ESC [ ?  |

+  | PG DOWN | 0x0A | ESC [ G   | ESC /    | ESC [ U  |

+  |         |      |           |          | ESC [ /  |

+  | F1      | 0x0B | ESC [ M   | ESC 1    | ESC O P  |

+  | F2      | 0x0C | ESC [ N   | ESC 2    | ESC O Q  |

+  | F3      | 0x0D | ESC [ O   | ESC 3    | ESC O w  |

+  | F4      | 0x0E | ESC [ P   | ESC 4    | ESC O x  |

+  | F5      | 0x0F | ESC [ Q   | ESC 5    | ESC O t  |

+  | F6      | 0x10 | ESC [ R   | ESC 6    | ESC O u  |

+  | F7      | 0x11 | ESC [ S   | ESC 7    | ESC O q  |

+  | F8      | 0x12 | ESC [ T   | ESC 8    | ESC O r  |

+  | F9      | 0x13 | ESC [ U   | ESC 9    | ESC O p  |

+  | F10     | 0x14 | ESC [ V   | ESC 0    | ESC O M  |

+  | Escape  | 0x17 | ESC       | ESC      | ESC      |

+  | F11     | 0x15 |           | ESC !    |          |

+  | F12     | 0x16 |           | ESC @    |          |

+  +=========+======+===========+==========+==========+

+  

+  Special Mappings

+  ================

+  ESC R ESC r ESC R = Reset System

+

+

+  @param TerminalDevice   The terminal device to use to translate raw input into EFI Keys

+

+  @return None.

+

+**/

 VOID

 UnicodeToEfiKey (

   IN  TERMINAL_DEV    *PcAnsiDevice

   )

 ;

 

+/**

+  Check if input string is valid Ascii string, valid EFI control characters

+  or valid text graphics.

+

+  @param  TerminalDevice          The terminal device.

+  @param  WString                 The input string.          

+ 

+  @retval EFI_UNSUPPORTED         If not all input characters are valid.

+  @retval EFI_SUCCESS             If all input characters are valid.

+

+**/

 EFI_STATUS

 AnsiTestString (

   IN  TERMINAL_DEV    *TerminalDevice,

@@ -1104,12 +1287,31 @@ AnsiTestString (
 //

 // internal functions for VTUTF8

 //

+

+/**

+  Translate all VT-UTF8 characters in the Raw FIFI into unicode characters, 

+  and insert them into Unicode FIFO.

+

+  @param VtUtf8Device          The terminal device.

+

+  @return None.

+

+**/

 VOID

 VTUTF8RawDataToUnicode (

   IN  TERMINAL_DEV    *VtUtf8Device

   )

 ;

 

+/**

+  Check if input string is valid VT-UTF8 string.

+

+  @param  TerminalDevice          The terminal device.

+  @param  WString                 The input string.          

+ 

+  @retval EFI_SUCCESS             If all input characters are valid.

+

+**/

 EFI_STATUS

 VTUTF8TestString (

   IN  TERMINAL_DEV    *TerminalDevice,

@@ -1117,6 +1319,24 @@ VTUTF8TestString (
   )

 ;

 

+/** 

+  Translate one Unicode character into VT-UTF8 characters.

+

+  UTF8 Encoding Table

+  Bits per Character | Unicode Character Range | Unicode Binary  Encoding |	UTF8 Binary Encoding

+        0-7	         |     0x0000 - 0x007F	   |     00000000 0xxxxxxx	  |   0xxxxxxx

+        8-11 	       |     0x0080 - 0x07FF	   |     00000xxx xxxxxxxx 	  |   110xxxxx 10xxxxxx

+       12-16	       |     0x0800 - 0xFFFF	   |     xxxxxxxx xxxxxxxx	  |   1110xxxx 10xxxxxx 10xxxxxx

+

+

+  @param  Unicode          Unicode character need translating.

+  @param  Utf8Char         Return VT-UTF8 character set.

+  @param  ValidBytes       The count of valid VT-UTF8 characters. If

+                           ValidBytes is zero, no valid VT-UTF8 returned.

+  

+  @return None.

+

+**/

 VOID

 UnicodeToUtf8 (

   IN  CHAR16      Unicode,

@@ -1125,6 +1345,17 @@ UnicodeToUtf8 (
   )

 ;

 

+/**

+  Get one valid VT-UTF8 characters set from Raw Data FIFO.

+

+  @param  Utf8Device          The terminal device.

+  @param  Utf8Char            Returned valid VT-UTF8 characters set.

+  @param  ValidBytes          The count of returned VT-VTF8 characters. 

+                              If ValidBytes is zero, no valid VT-UTF8 returned.

+

+  @retval None.

+

+**/

 VOID

 GetOneValidUtf8Char (

   IN  TERMINAL_DEV      *Utf8Device,

@@ -1133,6 +1364,23 @@ GetOneValidUtf8Char (
   )

 ;

 

+/** 

+  Translate VT-UTF8 characters into one Unicode character.

+

+  UTF8 Encoding Table

+  Bits per Character | Unicode Character Range | Unicode Binary  Encoding |	UTF8 Binary Encoding

+        0-7	         |     0x0000 - 0x007F	   |     00000000 0xxxxxxx	  |   0xxxxxxx

+        8-11 	       |     0x0080 - 0x07FF	   |     00000xxx xxxxxxxx 	  |   110xxxxx 10xxxxxx

+       12-16	       |     0x0800 - 0xFFFF	   |     xxxxxxxx xxxxxxxx	  |   1110xxxx 10xxxxxx 10xxxxxx

+

+

+  @param  Utf8Char         VT-UTF8 character set needs translating.

+  @param  ValidBytes       The count of valid VT-UTF8 characters.

+  @param  UnicodeChar      Returned unicode character. 

+  

+  @return None.

+

+**/

 VOID

 Utf8ToUnicode (

   IN  UTF8_CHAR       Utf8Char,

@@ -1144,6 +1392,19 @@ Utf8ToUnicode (
 //

 // functions for boxdraw unicode

 //

+

+/**

+  Detects if a Unicode char is for Box Drawing text graphics.

+

+  @param  Graphic      Unicode char to test.

+  @param  PcAnsi       Optional pointer to return PCANSI equivalent of

+                       Graphic.

+  @param  Ascii        Optional pointer to return ASCII equivalent of

+                       Graphic.

+

+  @return TRUE         If Graphic is a supported Unicode Box Drawing character.

+

+**/

 BOOLEAN

 TerminalIsValidTextGraphics (

   IN  CHAR16  Graphic,

@@ -1152,12 +1413,30 @@ TerminalIsValidTextGraphics (
   )

 ;

 

+/**

+  Detects if a valid ASCII char.

+

+  @param  Ascii        An ASCII character.

+                       

+  @retval TRUE         If it is a valid ASCII character.

+  @retval FALSE        If it is not a valid ASCII character.

+

+**/

 BOOLEAN

 TerminalIsValidAscii (

   IN  CHAR16  Ascii

   )

 ;

 

+/**

+  Detects if a valid EFI control character.

+

+  @param  CharC        An input EFI Control character.

+                       

+  @retval TRUE         If it is a valid EFI control character.

+  @retval FALSE        If it is not a valid EFI control character.

+

+**/

 BOOLEAN

 TerminalIsValidEfiCntlChar (

   IN  CHAR16  CharC