MdePkg/Include/Protocol/SimpleTextInEx.h

   1 /** @file
   2   Simple Text Input Ex protocol from the UEFI 2.0 specification.
   3
   4   This protocol defines an extension to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL
   5   which exposes much more state and modifier information from the input device,
   6   also allows one to register a notification for a particular keystroke.
   7
   8   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12
  13 #ifndef __SIMPLE_TEXT_IN_EX_H__
  14 #define __SIMPLE_TEXT_IN_EX_H__
  15
  16 #include <Protocol/SimpleTextIn.h>
  17
  18 #define EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL_GUID \
  19   {0xdd9e7534, 0x7762, 0x4698, { 0x8c, 0x14, 0xf5, 0x85, 0x17, 0xa6, 0x25, 0xaa } }
  20
  21
  22 typedef struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL;
  23
  24 /**
  25   The Reset() function resets the input device hardware. As part
  26   of initialization process, the firmware/device will make a quick
  27   but reasonable attempt to verify that the device is functioning.
  28   If the ExtendedVerification flag is TRUE the firmware may take
  29   an extended amount of time to verify the device is operating on
  30   reset. Otherwise the reset operation is to occur as quickly as
  31   possible. The hardware verification process is not defined by
  32   this specification and is left up to the platform firmware or
  33   driver to implement.
  34
  35   @param This                 A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
  36
  37   @param ExtendedVerification Indicates that the driver may
  38                               perform a more exhaustive
  39                               verification operation of the
  40                               device during reset.
  41
  42
  43   @retval EFI_SUCCESS       The device was reset.
  44
  45   @retval EFI_DEVICE_ERROR  The device is not functioning
  46                             correctly and could not be reset.
  47
  48 **/
  49 typedef
  50 EFI_STATUS
  51 (EFIAPI *EFI_INPUT_RESET_EX)(
  52   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
  53   IN BOOLEAN                           ExtendedVerification
  54 );
  55
  56
  57 ///
  58 /// EFI_KEY_TOGGLE_STATE. The toggle states are defined.
  59 /// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE
  60 /// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE
  61 ///
  62 typedef UINT8 EFI_KEY_TOGGLE_STATE;
  63
  64 typedef struct _EFI_KEY_STATE {
  65   ///
  66   /// Reflects the currently pressed shift
  67   /// modifiers for the input device. The
  68   /// returned value is valid only if the high
  69   /// order bit has been set.
  70   ///
  71   UINT32                KeyShiftState;
  72   ///
  73   /// Reflects the current internal state of
  74   /// various toggled attributes. The returned
  75   /// value is valid only if the high order
  76   /// bit has been set.
  77   ///
  78   EFI_KEY_TOGGLE_STATE  KeyToggleState;
  79 } EFI_KEY_STATE;
  80
  81 typedef struct {
  82   ///
  83   /// The EFI scan code and Unicode value returned from the input device.
  84   ///
  85   EFI_INPUT_KEY   Key;
  86   ///
  87   /// The current state of various toggled attributes as well as input modifier values.
  88   ///
  89   EFI_KEY_STATE   KeyState;
  90 } EFI_KEY_DATA;
  91
  92 //
  93 // Any Shift or Toggle State that is valid should have
  94 // high order bit set.
  95 //
  96 // Shift state
  97 //
  98 #define EFI_SHIFT_STATE_VALID     0x80000000
  99 #define EFI_RIGHT_SHIFT_PRESSED   0x00000001
 100 #define EFI_LEFT_SHIFT_PRESSED    0x00000002
 101 #define EFI_RIGHT_CONTROL_PRESSED 0x00000004
 102 #define EFI_LEFT_CONTROL_PRESSED  0x00000008
 103 #define EFI_RIGHT_ALT_PRESSED     0x00000010
 104 #define EFI_LEFT_ALT_PRESSED      0x00000020
 105 #define EFI_RIGHT_LOGO_PRESSED    0x00000040
 106 #define EFI_LEFT_LOGO_PRESSED     0x00000080
 107 #define EFI_MENU_KEY_PRESSED      0x00000100
 108 #define EFI_SYS_REQ_PRESSED       0x00000200
 109
 110 //
 111 // Toggle state
 112 //
 113 #define EFI_TOGGLE_STATE_VALID    0x80
 114 #define EFI_KEY_STATE_EXPOSED     0x40
 115 #define EFI_SCROLL_LOCK_ACTIVE    0x01
 116 #define EFI_NUM_LOCK_ACTIVE       0x02
 117 #define EFI_CAPS_LOCK_ACTIVE      0x04
 118
 119 //
 120 // EFI Scan codes
 121 //
 122 #define SCAN_F11                  0x0015
 123 #define SCAN_F12                  0x0016
 124 #define SCAN_PAUSE                0x0048
 125 #define SCAN_F13                  0x0068
 126 #define SCAN_F14                  0x0069
 127 #define SCAN_F15                  0x006A
 128 #define SCAN_F16                  0x006B
 129 #define SCAN_F17                  0x006C
 130 #define SCAN_F18                  0x006D
 131 #define SCAN_F19                  0x006E
 132 #define SCAN_F20                  0x006F
 133 #define SCAN_F21                  0x0070
 134 #define SCAN_F22                  0x0071
 135 #define SCAN_F23                  0x0072
 136 #define SCAN_F24                  0x0073
 137 #define SCAN_MUTE                 0x007F
 138 #define SCAN_VOLUME_UP            0x0080
 139 #define SCAN_VOLUME_DOWN          0x0081
 140 #define SCAN_BRIGHTNESS_UP        0x0100
 141 #define SCAN_BRIGHTNESS_DOWN      0x0101
 142 #define SCAN_SUSPEND              0x0102
 143 #define SCAN_HIBERNATE            0x0103
 144 #define SCAN_TOGGLE_DISPLAY       0x0104
 145 #define SCAN_RECOVERY             0x0105
 146 #define SCAN_EJECT                0x0106
 147
 148 /**
 149   The function reads the next keystroke from the input device. If
 150   there is no pending keystroke the function returns
 151   EFI_NOT_READY. If there is a pending keystroke, then
 152   KeyData.Key.ScanCode is the EFI scan code defined in Error!
 153   Reference source not found. The KeyData.Key.UnicodeChar is the
 154   actual printable character or is zero if the key does not
 155   represent a printable character (control key, function key,
 156   etc.). The KeyData.KeyState is shift state for the character
 157   reflected in KeyData.Key.UnicodeChar or KeyData.Key.ScanCode .
 158   When interpreting the data from this function, it should be
 159   noted that if a class of printable characters that are
 160   normally adjusted by shift modifiers (e.g. Shift Key + "f"
 161   key) would be presented solely as a KeyData.Key.UnicodeChar
 162   without the associated shift state. So in the previous example
 163   of a Shift Key + "f" key being pressed, the only pertinent
 164   data returned would be KeyData.Key.UnicodeChar with the value
 165   of "F". This of course would not typically be the case for
 166   non-printable characters such as the pressing of the Right
 167   Shift Key + F10 key since the corresponding returned data
 168   would be reflected both in the KeyData.KeyState.KeyShiftState
 169   and KeyData.Key.ScanCode values. UEFI drivers which implement
 170   the EFI_SIMPLE_TEXT_INPUT_EX protocol are required to return
 171   KeyData.Key and KeyData.KeyState values. These drivers must
 172   always return the most current state of
 173   KeyData.KeyState.KeyShiftState and
 174   KeyData.KeyState.KeyToggleState. It should also be noted that
 175   certain input devices may not be able to produce shift or toggle
 176   state information, and in those cases the high order bit in the
 177   respective Toggle and Shift state fields should not be active.
 178
 179
 180   @param This     A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
 181
 182   @param KeyData  A pointer to a buffer that is filled in with
 183                   the keystroke state data for the key that was
 184                   pressed.
 185
 186
 187   @retval EFI_SUCCESS      The keystroke information was returned.
 188   @retval EFI_NOT_READY    There was no keystroke data available.
 189   @retval EFI_DEVICE_ERROR The keystroke information was not returned due to
 190                            hardware errors.
 191
 192
 193 **/
 194 typedef
 195 EFI_STATUS
 196 (EFIAPI *EFI_INPUT_READ_KEY_EX)(
 197   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 198   OUT EFI_KEY_DATA                      *KeyData
 199 );
 200
 201 /**
 202   The SetState() function allows the input device hardware to
 203   have state settings adjusted.
 204
 205   @param This           A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
 206
 207   @param KeyToggleState Pointer to the EFI_KEY_TOGGLE_STATE to
 208                         set the state for the input device.
 209
 210
 211   @retval EFI_SUCCESS       The device state was set appropriately.
 212
 213   @retval EFI_DEVICE_ERROR  The device is not functioning
 214                             correctly and could not have the
 215                             setting adjusted.
 216
 217   @retval EFI_UNSUPPORTED   The device does not support the
 218                             ability to have its state set.
 219
 220 **/
 221 typedef
 222 EFI_STATUS
 223 (EFIAPI *EFI_SET_STATE)(
 224   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 225   IN EFI_KEY_TOGGLE_STATE              *KeyToggleState
 226 );
 227
 228 ///
 229 /// The function will be called when the key sequence is typed specified by KeyData.
 230 ///
 231 typedef
 232 EFI_STATUS
 233 (EFIAPI *EFI_KEY_NOTIFY_FUNCTION)(
 234   IN EFI_KEY_DATA *KeyData
 235 );
 236
 237 /**
 238   The RegisterKeystrokeNotify() function registers a function
 239   which will be called when a specified keystroke will occur.
 240
 241   @param This                     A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
 242
 243   @param KeyData                  A pointer to a buffer that is filled in with
 244                                   the keystroke information for the key that was
 245                                   pressed. If KeyData.Key, KeyData.KeyState.KeyToggleState
 246                                   and KeyData.KeyState.KeyShiftState are 0, then any incomplete
 247                                   keystroke will trigger a notification of the KeyNotificationFunction.
 248
 249   @param KeyNotificationFunction  Points to the function to be called when the key sequence
 250                                   is typed specified by KeyData. This notification function
 251                                   should be called at <=TPL_CALLBACK.
 252
 253
 254   @param NotifyHandle             Points to the unique handle assigned to
 255                                   the registered notification.
 256
 257   @retval EFI_SUCCESS           Key notify was registered successfully.
 258
 259   @retval EFI_OUT_OF_RESOURCES  Unable to allocate necessary
 260                                 data structures.
 261
 262 **/
 263 typedef
 264 EFI_STATUS
 265 (EFIAPI *EFI_REGISTER_KEYSTROKE_NOTIFY)(
 266   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 267   IN  EFI_KEY_DATA                      *KeyData,
 268   IN  EFI_KEY_NOTIFY_FUNCTION           KeyNotificationFunction,
 269   OUT VOID                              **NotifyHandle
 270 );
 271
 272 /**
 273   The UnregisterKeystrokeNotify() function removes the
 274   notification which was previously registered.
 275
 276   @param This               A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
 277
 278   @param NotificationHandle The handle of the notification
 279                             function being unregistered.
 280
 281   @retval EFI_SUCCESS           Key notify was unregistered successfully.
 282
 283   @retval EFI_INVALID_PARAMETER The NotificationHandle is
 284                                 invalid.
 285
 286 **/
 287 typedef
 288 EFI_STATUS
 289 (EFIAPI *EFI_UNREGISTER_KEYSTROKE_NOTIFY)(
 290   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 291   IN VOID                               *NotificationHandle
 292 );
 293
 294
 295 ///
 296 /// The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn
 297 /// device. It is an extension to the Simple Text Input protocol
 298 /// which allows a variety of extended shift state information to be
 299 /// returned.
 300 ///
 301 struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL{
 302   EFI_INPUT_RESET_EX              Reset;
 303   EFI_INPUT_READ_KEY_EX           ReadKeyStrokeEx;
 304   ///
 305   /// Event to use with WaitForEvent() to wait for a key to be available.
 306   ///
 307   EFI_EVENT                       WaitForKeyEx;
 308   EFI_SET_STATE                   SetState;
 309   EFI_REGISTER_KEYSTROKE_NOTIFY   RegisterKeyNotify;
 310   EFI_UNREGISTER_KEYSTROKE_NOTIFY UnregisterKeyNotify;
 311 };
 312
 313
 314 extern EFI_GUID gEfiSimpleTextInputExProtocolGuid;
 315
 316 #endif
 317