iPXE
SimpleTextInEx.h
Go to the documentation of this file.
00001 /** @file
00002   Simple Text Input Ex protocol from the UEFI 2.0 specification.
00003 
00004   This protocol defines an extension to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
00005   which exposes much more state and modifier information from the input device,
00006   also allows one to register a notification for a particular keystroke.
00007 
00008   Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
00009   This program and the accompanying materials
00010   are licensed and made available under the terms and conditions of the BSD License
00011   which accompanies this distribution.  The full text of the license may be found at
00012   http://opensource.org/licenses/bsd-license.php
00013 
00014   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00015   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00016 
00017 **/
00018 
00019 #ifndef __SIMPLE_TEXT_IN_EX_H__
00020 #define __SIMPLE_TEXT_IN_EX_H__
00021 
00022 FILE_LICENCE ( BSD3 );
00023 
00024 #include <ipxe/efi/Protocol/SimpleTextIn.h>
00025 
00026 #define EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL_GUID \
00027   {0xdd9e7534, 0x7762, 0x4698, { 0x8c, 0x14, 0xf5, 0x85, 0x17, 0xa6, 0x25, 0xaa } }
00028 
00029 
00030 typedef struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL;
00031 
00032 /**
00033   The Reset() function resets the input device hardware. As part
00034   of initialization process, the firmware/device will make a quick
00035   but reasonable attempt to verify that the device is functioning.
00036   If the ExtendedVerification flag is TRUE the firmware may take
00037   an extended amount of time to verify the device is operating on
00038   reset. Otherwise the reset operation is to occur as quickly as
00039   possible. The hardware verification process is not defined by
00040   this specification and is left up to the platform firmware or
00041   driver to implement.
00042 
00043   @param This                 A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
00044 
00045   @param ExtendedVerification Indicates that the driver may
00046                               perform a more exhaustive
00047                               verification operation of the
00048                               device during reset.
00049 
00050 
00051   @retval EFI_SUCCESS       The device was reset.
00052 
00053   @retval EFI_DEVICE_ERROR  The device is not functioning
00054                             correctly and could not be reset.
00055 
00056 **/
00057 typedef
00058 EFI_STATUS
00059 (EFIAPI *EFI_INPUT_RESET_EX)(
00060   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
00061   IN BOOLEAN                           ExtendedVerification
00062 );
00063 
00064 
00065 ///
00066 /// EFI_KEY_TOGGLE_STATE. The toggle states are defined.
00067 /// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE
00068 /// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE
00069 ///
00070 typedef UINT8 EFI_KEY_TOGGLE_STATE;
00071 
00072 typedef struct _EFI_KEY_STATE {
00073   ///
00074   /// Reflects the currently pressed shift
00075   /// modifiers for the input device. The
00076   /// returned value is valid only if the high
00077   /// order bit has been set.
00078   ///
00079   UINT32                KeyShiftState;
00080   ///
00081   /// Reflects the current internal state of
00082   /// various toggled attributes. The returned
00083   /// value is valid only if the high order
00084   /// bit has been set.
00085   ///
00086   EFI_KEY_TOGGLE_STATE  KeyToggleState;
00087 } EFI_KEY_STATE;
00088 
00089 typedef struct {
00090   ///
00091   /// The EFI scan code and Unicode value returned from the input device.
00092   ///
00093   EFI_INPUT_KEY   Key;
00094   ///
00095   /// The current state of various toggled attributes as well as input modifier values.
00096   ///
00097   EFI_KEY_STATE   KeyState;
00098 } EFI_KEY_DATA;
00099 
00100 //
00101 // Any Shift or Toggle State that is valid should have
00102 // high order bit set.
00103 //
00104 // Shift state
00105 //
00106 #define EFI_SHIFT_STATE_VALID     0x80000000
00107 #define EFI_RIGHT_SHIFT_PRESSED   0x00000001
00108 #define EFI_LEFT_SHIFT_PRESSED    0x00000002
00109 #define EFI_RIGHT_CONTROL_PRESSED 0x00000004
00110 #define EFI_LEFT_CONTROL_PRESSED  0x00000008
00111 #define EFI_RIGHT_ALT_PRESSED     0x00000010
00112 #define EFI_LEFT_ALT_PRESSED      0x00000020
00113 #define EFI_RIGHT_LOGO_PRESSED    0x00000040
00114 #define EFI_LEFT_LOGO_PRESSED     0x00000080
00115 #define EFI_MENU_KEY_PRESSED      0x00000100
00116 #define EFI_SYS_REQ_PRESSED       0x00000200
00117 
00118 //
00119 // Toggle state
00120 //
00121 #define EFI_TOGGLE_STATE_VALID    0x80
00122 #define EFI_KEY_STATE_EXPOSED     0x40
00123 #define EFI_SCROLL_LOCK_ACTIVE    0x01
00124 #define EFI_NUM_LOCK_ACTIVE       0x02
00125 #define EFI_CAPS_LOCK_ACTIVE      0x04
00126 
00127 //
00128 // EFI Scan codes
00129 //
00130 #define SCAN_F11                  0x0015
00131 #define SCAN_F12                  0x0016
00132 #define SCAN_PAUSE                0x0048
00133 #define SCAN_F13                  0x0068
00134 #define SCAN_F14                  0x0069
00135 #define SCAN_F15                  0x006A
00136 #define SCAN_F16                  0x006B
00137 #define SCAN_F17                  0x006C
00138 #define SCAN_F18                  0x006D
00139 #define SCAN_F19                  0x006E
00140 #define SCAN_F20                  0x006F
00141 #define SCAN_F21                  0x0070
00142 #define SCAN_F22                  0x0071
00143 #define SCAN_F23                  0x0072
00144 #define SCAN_F24                  0x0073
00145 #define SCAN_MUTE                 0x007F
00146 #define SCAN_VOLUME_UP            0x0080
00147 #define SCAN_VOLUME_DOWN          0x0081
00148 #define SCAN_BRIGHTNESS_UP        0x0100
00149 #define SCAN_BRIGHTNESS_DOWN      0x0101
00150 #define SCAN_SUSPEND              0x0102
00151 #define SCAN_HIBERNATE            0x0103
00152 #define SCAN_TOGGLE_DISPLAY       0x0104
00153 #define SCAN_RECOVERY             0x0105
00154 #define SCAN_EJECT                0x0106
00155 
00156 /**
00157   The function reads the next keystroke from the input device. If
00158   there is no pending keystroke the function returns
00159   EFI_NOT_READY. If there is a pending keystroke, then
00160   KeyData.Key.ScanCode is the EFI scan code defined in Error!
00161   Reference source not found. The KeyData.Key.UnicodeChar is the
00162   actual printable character or is zero if the key does not
00163   represent a printable character (control key, function key,
00164   etc.). The KeyData.KeyState is shift state for the character
00165   reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode .
00166   When interpreting the data from this function, it should be
00167   noted that if a class of printable characters that are
00168   normally adjusted by shift modifiers (e.g. Shift Key + "f"
00169   key) would be presented solely as a KeyData.Key.UnicodeChar
00170   without the associated shift state. So in the previous example
00171   of a Shift Key + "f" key being pressed, the only pertinent
00172   data returned would be KeyData.Key.UnicodeChar with the value
00173   of "F". This of course would not typically be the case for
00174   non-printable characters such as the pressing of the Right
00175   Shift Key + F10 key since the corresponding returned data
00176   would be reflected both in the KeyData.KeyState.KeyShiftState
00177   and KeyData.Key.ScanCode values. UEFI drivers which implement
00178   the EFI_SIMPLE_TEXT_INPUT_EX protocol are required to return
00179   KeyData.Key and KeyData.KeyState values. These drivers must
00180   always return the most current state of
00181   KeyData.KeyState.KeyShiftState and
00182   KeyData.KeyState.KeyToggleState. It should also be noted that
00183   certain input devices may not be able to produce shift or toggle
00184   state information, and in those cases the high order bit in the
00185   respective Toggle and Shift state fields should not be active.
00186 
00187 
00188   @param This     A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
00189 
00190   @param KeyData  A pointer to a buffer that is filled in with
00191                   the keystroke state data for the key that was
00192                   pressed.
00193 
00194 
00195   @retval EFI_SUCCESS     The keystroke information was
00196                           returned.
00197 
00198   @retval EFI_NOT_READY   There was no keystroke data available.
00199                           EFI_DEVICE_ERROR The keystroke
00200                           information was not returned due to
00201                           hardware errors.
00202 
00203 
00204 **/
00205 typedef
00206 EFI_STATUS
00207 (EFIAPI *EFI_INPUT_READ_KEY_EX)(
00208   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
00209   OUT EFI_KEY_DATA                      *KeyData
00210 );
00211 
00212 /**
00213   The SetState() function allows the input device hardware to
00214   have state settings adjusted.
00215 
00216   @param This           A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
00217 
00218   @param KeyToggleState Pointer to the EFI_KEY_TOGGLE_STATE to
00219                         set the state for the input device.
00220 
00221 
00222   @retval EFI_SUCCESS       The device state was set appropriately.
00223 
00224   @retval EFI_DEVICE_ERROR  The device is not functioning
00225                             correctly and could not have the
00226                             setting adjusted.
00227 
00228   @retval EFI_UNSUPPORTED   The device does not support the
00229                             ability to have its state set.
00230 
00231 **/
00232 typedef
00233 EFI_STATUS
00234 (EFIAPI *EFI_SET_STATE)(
00235   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
00236   IN EFI_KEY_TOGGLE_STATE              *KeyToggleState
00237 );
00238 
00239 ///
00240 /// The function will be called when the key sequence is typed specified by KeyData.
00241 ///
00242 typedef
00243 EFI_STATUS
00244 (EFIAPI *EFI_KEY_NOTIFY_FUNCTION)(
00245   IN EFI_KEY_DATA *KeyData
00246 );
00247 
00248 /**
00249   The RegisterKeystrokeNotify() function registers a function
00250   which will be called when a specified keystroke will occur.
00251 
00252   @param This                     A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
00253 
00254   @param KeyData                  A pointer to a buffer that is filled in with
00255                                   the keystroke information for the key that was
00256                                   pressed.
00257 
00258   @param KeyNotificationFunction  Points to the function to be
00259                                   called when the key sequence
00260                                   is typed specified by KeyData.
00261 
00262 
00263   @param NotifyHandle             Points to the unique handle assigned to
00264                                   the registered notification.
00265 
00266   @retval EFI_SUCCESS           The device state was set
00267                                 appropriately.
00268 
00269   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
00270                                 data structures.
00271 
00272 **/
00273 typedef
00274 EFI_STATUS
00275 (EFIAPI *EFI_REGISTER_KEYSTROKE_NOTIFY)(
00276   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
00277   IN  EFI_KEY_DATA                      *KeyData,
00278   IN  EFI_KEY_NOTIFY_FUNCTION           KeyNotificationFunction,
00279   OUT VOID                              **NotifyHandle
00280 );
00281 
00282 /**
00283   The UnregisterKeystrokeNotify() function removes the
00284   notification which was previously registered.
00285 
00286   @param This               A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
00287 
00288   @param NotificationHandle The handle of the notification
00289                             function being unregistered.
00290 
00291   @retval EFI_SUCCESS The device state was set appropriately.
00292 
00293   @retval EFI_INVALID_PARAMETER The NotificationHandle is
00294                                 invalid.
00295 
00296 **/
00297 typedef
00298 EFI_STATUS
00299 (EFIAPI *EFI_UNREGISTER_KEYSTROKE_NOTIFY)(
00300   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
00301   IN VOID                               *NotificationHandle
00302 );
00303 
00304 
00305 ///
00306 /// The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn
00307 /// device. It is an extension to the Simple Text Input protocol
00308 /// which allows a variety of extended shift state information to be
00309 /// returned.
00310 ///
00311 struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL{
00312   EFI_INPUT_RESET_EX              Reset;
00313   EFI_INPUT_READ_KEY_EX           ReadKeyStrokeEx;
00314   ///
00315   /// Event to use with WaitForEvent() to wait for a key to be available.
00316   ///
00317   EFI_EVENT                       WaitForKeyEx;
00318   EFI_SET_STATE                   SetState;
00319   EFI_REGISTER_KEYSTROKE_NOTIFY   RegisterKeyNotify;
00320   EFI_UNREGISTER_KEYSTROKE_NOTIFY UnregisterKeyNotify;
00321 };
00322 
00323 
00324 extern EFI_GUID gEfiSimpleTextInputExProtocolGuid;
00325 
00326 #endif
00327