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