From 8fd9831511a7df7a79bfc1de939d7840359856ea Mon Sep 17 00:00:00 2001 From: vanjeff Date: Thu, 3 Jul 2008 05:17:49 +0000 Subject: Added some functions header. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5406 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Universal/Console/TerminalDxe/Terminal.h | 339 +++++++++++++++++++-- 1 file changed, 309 insertions(+), 30 deletions(-) (limited to 'MdeModulePkg/Universal/Console/TerminalDxe/Terminal.h') 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 -- cgit v1.1