MdeModulePkg/Bus/Usb/UsbKbDxe/EfiKey.h

   1 /** @file
   2   Header file for USB Keyboard Driver's Data Structures.
   3
   4 Copyright (c) 2004 - 2008, Intel Corporation
   5 All rights reserved. This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14 #ifndef _EFI_USB_KB_H_
  15 #define _EFI_USB_KB_H_
  16
  17
  18 #include <Uefi.h>
  19
  20 #include <Protocol/SimpleTextIn.h>
  21 #include <Protocol/SimpleTextInEx.h>
  22 #include <Protocol/HiiDatabase.h>
  23 #include <Protocol/UsbIo.h>
  24 #include <Protocol/DevicePath.h>
  25 #include <Guid/HiiKeyBoardLayout.h>
  26 #include <Guid/HotPlugDevice.h>
  27
  28 #include <Library/DebugLib.h>
  29 #include <Library/ReportStatusCodeLib.h>
  30 #include <Library/BaseMemoryLib.h>
  31 #include <Library/UefiRuntimeServicesTableLib.h>
  32 #include <Library/UefiDriverEntryPoint.h>
  33 #include <Library/UefiBootServicesTableLib.h>
  34 #include <Library/UefiLib.h>
  35 #include <Library/MemoryAllocationLib.h>
  36 #include <Library/PcdLib.h>
  37 #include <Library/UefiUsbLib.h>
  38 #include <Library/BaseLib.h>
  39 #include <Library/UefiUsbLib.h>
  40
  41 #include <IndustryStandard/Usb.h>
  42
  43 #define MAX_KEY_ALLOWED     32
  44
  45 #define HZ                  1000 * 1000 * 10
  46 #define USBKBD_REPEAT_DELAY ((HZ) / 2)
  47 #define USBKBD_REPEAT_RATE  ((HZ) / 50)
  48
  49 #define CLASS_HID           3
  50 #define SUBCLASS_BOOT       1
  51 #define PROTOCOL_KEYBOARD   1
  52
  53 #define BOOT_PROTOCOL       0
  54 #define REPORT_PROTOCOL     1
  55
  56 typedef struct {
  57   UINT8 Down;
  58   UINT8 KeyCode;
  59 } USB_KEY;
  60
  61 typedef struct {
  62   USB_KEY Buffer[MAX_KEY_ALLOWED + 1];
  63   UINT8   BufferHead;
  64   UINT8   BufferTail;
  65 } USB_KB_BUFFER;
  66
  67 #define USB_KB_DEV_SIGNATURE  EFI_SIGNATURE_32 ('u', 'k', 'b', 'd')
  68 #define USB_KB_CONSOLE_IN_EX_NOTIFY_SIGNATURE EFI_SIGNATURE_32 ('u', 'k', 'b', 'x')
  69
  70 typedef struct _KEYBOARD_CONSOLE_IN_EX_NOTIFY {
  71   UINTN                                 Signature;
  72   EFI_HANDLE                            NotifyHandle;
  73   EFI_KEY_DATA                          KeyData;
  74   EFI_KEY_NOTIFY_FUNCTION               KeyNotificationFn;
  75   LIST_ENTRY                            NotifyEntry;
  76 } KEYBOARD_CONSOLE_IN_EX_NOTIFY;
  77
  78 #define USB_NS_KEY_SIGNATURE  EFI_SIGNATURE_32 ('u', 'n', 's', 'k')
  79
  80 typedef struct {
  81   UINTN                         Signature;
  82   LIST_ENTRY                    Link;
  83
  84   //
  85   // The number of EFI_NS_KEY_MODIFIER children definitions
  86   //
  87   UINTN                         KeyCount;
  88
  89   //
  90   // NsKey[0] : Non-spacing key
  91   // NsKey[1] ~ NsKey[KeyCount] : Physical keys
  92   //
  93   EFI_KEY_DESCRIPTOR            *NsKey;
  94 } USB_NS_KEY;
  95
  96 #define USB_NS_KEY_FORM_FROM_LINK(a)  CR (a, USB_NS_KEY, Link, USB_NS_KEY_SIGNATURE)
  97
  98 ///
  99 /// Structure to describe USB keyboard device
 100 ///
 101 typedef struct {
 102   UINTN                             Signature;
 103   EFI_DEVICE_PATH_PROTOCOL          *DevicePath;
 104   EFI_EVENT                         DelayedRecoveryEvent;
 105   EFI_SIMPLE_TEXT_INPUT_PROTOCOL    SimpleInput;
 106   EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL SimpleInputEx;
 107   EFI_USB_IO_PROTOCOL               *UsbIo;
 108
 109   EFI_USB_INTERFACE_DESCRIPTOR      InterfaceDescriptor;
 110   EFI_USB_ENDPOINT_DESCRIPTOR       IntEndpointDescriptor;
 111
 112   USB_KB_BUFFER                     KeyboardBuffer;
 113   UINT8                             CtrlOn;
 114   UINT8                             AltOn;
 115   UINT8                             ShiftOn;
 116   UINT8                             NumLockOn;
 117   UINT8                             CapsOn;
 118   UINT8                             ScrollOn;
 119   UINT8                             LastKeyCodeArray[8];
 120   UINT8                             CurKeyChar;
 121
 122   UINT8                             RepeatKey;
 123   EFI_EVENT                         RepeatTimer;
 124
 125   EFI_UNICODE_STRING_TABLE          *ControllerNameTable;
 126
 127   UINT8                             LeftCtrlOn;
 128   UINT8                             LeftAltOn;
 129   UINT8                             LeftShiftOn;
 130   UINT8                             LeftLogoOn;
 131   UINT8                             RightCtrlOn;
 132   UINT8                             RightAltOn;
 133   UINT8                             RightShiftOn;
 134   UINT8                             RightLogoOn;
 135   UINT8                             MenuKeyOn;
 136   UINT8                             SysReqOn;
 137   UINT8                             AltGrOn;
 138
 139   EFI_KEY_STATE                     KeyState;
 140   //
 141   // Notification function list
 142   //
 143   LIST_ENTRY                        NotifyList;
 144
 145   //
 146   // Non-spacing key list
 147   //
 148   LIST_ENTRY                        NsKeyList;
 149   USB_NS_KEY                        *CurrentNsKey;
 150   EFI_KEY_DESCRIPTOR                *KeyConvertionTable;
 151   EFI_EVENT                         KeyboardLayoutEvent;
 152 } USB_KB_DEV;
 153
 154 //
 155 // Global Variables
 156 //
 157 extern EFI_DRIVER_BINDING_PROTOCOL   gUsbKeyboardDriverBinding;
 158 extern EFI_COMPONENT_NAME_PROTOCOL   gUsbKeyboardComponentName;
 159 extern EFI_COMPONENT_NAME2_PROTOCOL  gUsbKeyboardComponentName2;
 160 extern EFI_GUID                      gSimpleTextInExNotifyGuid;
 161
 162 #define USB_KB_DEV_FROM_THIS(a) \
 163     CR(a, USB_KB_DEV, SimpleInput, USB_KB_DEV_SIGNATURE)
 164 #define TEXT_INPUT_EX_USB_KB_DEV_FROM_THIS(a) \
 165     CR(a, USB_KB_DEV, SimpleInputEx, USB_KB_DEV_SIGNATURE)
 166
 167
 168 #define MOD_CONTROL_L           0x01
 169 #define MOD_CONTROL_R           0x10
 170 #define MOD_SHIFT_L             0x02
 171 #define MOD_SHIFT_R             0x20
 172 #define MOD_ALT_L               0x04
 173 #define MOD_ALT_R               0x40
 174 #define MOD_WIN_L               0x08
 175 #define MOD_WIN_R               0x80
 176
 177 typedef struct {
 178   UINT8 Mask;
 179   UINT8 Key;
 180 } KB_MODIFIER;
 181
 182 #define USB_KEYCODE_MAX_MAKE      0x62
 183
 184 #define USBKBD_VALID_KEYCODE(key) ((UINT8) (key) > 3)
 185
 186 typedef struct {
 187   UINT8 NumLock : 1;
 188   UINT8 CapsLock : 1;
 189   UINT8 ScrollLock : 1;
 190   UINT8 Resrvd : 5;
 191 } LED_MAP;
 192
 193 //
 194 // Functions of Driver Binding Protocol
 195 //
 196 /**
 197   Check whether USB keyboard driver supports this device.
 198
 199   @param  This                   The USB keyboard driver binding protocol.
 200   @param  Controller             The controller handle to check.
 201   @param  RemainingDevicePath    The remaining device path.
 202
 203   @retval EFI_SUCCESS            The driver supports this controller.
 204   @retval other                  This device isn't supported.
 205
 206 **/
 207 EFI_STATUS
 208 EFIAPI
 209 USBKeyboardDriverBindingSupported (
 210   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 211   IN EFI_HANDLE                     Controller,
 212   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 213   );
 214
 215 /**
 216   Start running driver on the controller.
 217
 218   @param  This                   The USB keyboard driver binding instance.
 219   @param  Controller             Handle of device to bind driver to.
 220   @param  RemainingDevicePath    Optional parameter use to pick a specific child
 221                                  device to start.
 222
 223   @retval EFI_SUCCESS            The controller is controlled by the usb keyboard driver.
 224   @retval EFI_UNSUPPORTED        No interrupt endpoint can be found.
 225   @retval Other                  The keyboard driver cannot support this controller.
 226
 227 **/
 228 EFI_STATUS
 229 EFIAPI
 230 USBKeyboardDriverBindingStart (
 231   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 232   IN EFI_HANDLE                     Controller,
 233   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 234   );
 235
 236 /**
 237   Stop handling the controller by this USB keyboard driver.
 238
 239   @param  This                   The USB keyboard driver binding protocol.
 240   @param  Controller             The controller to release.
 241   @param  NumberOfChildren       The number of handles in ChildHandleBuffer.
 242   @param  ChildHandleBuffer      The array of child handle.
 243
 244   @retval EFI_SUCCESS            The controller or children are stopped.
 245   @retval EFI_UNSUPPORTED        Simple Text In Protocol or Simple Text In Ex Protocol
 246                                  is not installed on Controller.
 247   @retval EFI_DEVICE_ERROR       Failed to stop the driver.
 248
 249 **/
 250 EFI_STATUS
 251 EFIAPI
 252 USBKeyboardDriverBindingStop (
 253   IN  EFI_DRIVER_BINDING_PROTOCOL    *This,
 254   IN  EFI_HANDLE                     Controller,
 255   IN  UINTN                          NumberOfChildren,
 256   IN  EFI_HANDLE                     *ChildHandleBuffer
 257   );
 258
 259 //
 260 // Functions of Simple Text Input Protocol
 261 //
 262 /**
 263   Reset USB Keyboard.
 264
 265   There are 2 types of reset for USB keyboard.
 266   For non-exhaustive reset, only keyboard buffer is cleared.
 267   For exhaustive reset, in addition to clearance of keyboard buffer, the hardware status
 268   is also re-initialized.
 269
 270   @param  This                  The protocol instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL.
 271   @param  ExtendedVerification  Indicates if exhaustive reset is used.
 272                                 TRUE for exhaustive reset.
 273                                 FALSE for non-exhaustive reset.
 274
 275   @retval EFI_SUCCESS           Keyboard is reset successfully.
 276   @retval EFI_DEVICE_ERROR      Failed to reset keyboard.
 277
 278 **/
 279 EFI_STATUS
 280 EFIAPI
 281 USBKeyboardReset (
 282   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL   *This,
 283   IN  BOOLEAN                          ExtendedVerification
 284   );
 285
 286 /**
 287   Implements EFI_SIMPLE_TEXT_INPUT_PROTOCOL.ReadKeyStroke() function.
 288
 289   @param  This                 The EFI_SIMPLE_TEXT_INPUT_PROTOCOL instance.
 290   @param  Key                  A pointer to a buffer that is filled in with the keystroke
 291                                information for the key that was pressed.
 292
 293   @retval EFI_SUCCESS          Read key stroke successfully.
 294   @retval Other                Read key stroke failed.
 295
 296 **/
 297 EFI_STATUS
 298 EFIAPI
 299 USBKeyboardReadKeyStroke (
 300   IN  EFI_SIMPLE_TEXT_INPUT_PROTOCOL   *This,
 301   OUT EFI_INPUT_KEY                    *Key
 302   );
 303
 304 //
 305 // Simple Text Input Ex protocol functions
 306 //
 307 /**
 308   The extension routine to reset the input device.
 309
 310   @param This                     Protocol instance pointer.
 311   @param ExtendedVerification     Driver may perform diagnostics on reset.
 312
 313   @retval EFI_SUCCESS             The device was reset.
 314   @retval EFI_DEVICE_ERROR        The device is not functioning properly and could
 315                                   not be reset.
 316
 317 **/
 318 EFI_STATUS
 319 EFIAPI
 320 USBKeyboardResetEx (
 321   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 322   IN BOOLEAN                            ExtendedVerification
 323   );
 324
 325 /**
 326   Reads the next keystroke from the input device. The WaitForKey Event can
 327   be used to test for existance of a keystroke via WaitForEvent () call.
 328
 329   @param  This                    Protocol instance pointer.
 330   @param  KeyData                 A pointer to a buffer that is filled in with the keystroke
 331                                   state data for the key that was pressed.
 332
 333   @return EFI_SUCCESS             The keystroke information was returned successfully.
 334   @retval EFI_INVALID_PARAMETER   KeyData is NULL.
 335   @retval Other                   Read key stroke information failed.
 336
 337 **/
 338 EFI_STATUS
 339 EFIAPI
 340 USBKeyboardReadKeyStrokeEx (
 341   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL *This,
 342   OUT EFI_KEY_DATA                      *KeyData
 343   );
 344
 345 /**
 346   Set certain state for the input device.
 347
 348   @param  This                    Protocol instance pointer.
 349   @param  KeyToggleState          A pointer to the EFI_KEY_TOGGLE_STATE to set the
 350                                   state for the input device.
 351
 352   @retval EFI_SUCCESS             The device state was set successfully.
 353   @retval EFI_UNSUPPORTED         The device does not have the ability to set its state.
 354   @retval EFI_INVALID_PARAMETER   KeyToggleState is NULL.
 355
 356 **/
 357 EFI_STATUS
 358 EFIAPI
 359 USBKeyboardSetState (
 360   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 361   IN EFI_KEY_TOGGLE_STATE               *KeyToggleState
 362   );
 363
 364 /**
 365   Register a notification function for a particular keystroke for the input device.
 366
 367   @param  This                        Protocol instance pointer.
 368   @param  KeyData                     A pointer to a buffer that is filled in with the keystroke
 369                                       information data for the key that was pressed.
 370   @param  KeyNotificationFunction     Points to the function to be called when the key
 371                                       sequence is typed specified by KeyData.
 372   @param  NotifyHandle                Points to the unique handle assigned to the registered notification.
 373
 374   @retval EFI_SUCCESS                 The notification function was registered successfully.
 375   @retval EFI_OUT_OF_RESOURCES        Unable to allocate resources for necesssary data structures.
 376   @retval EFI_INVALID_PARAMETER       KeyData or NotifyHandle is NULL.
 377
 378 **/
 379 EFI_STATUS
 380 EFIAPI
 381 USBKeyboardRegisterKeyNotify (
 382   IN  EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 383   IN  EFI_KEY_DATA                       *KeyData,
 384   IN  EFI_KEY_NOTIFY_FUNCTION            KeyNotificationFunction,
 385   OUT EFI_HANDLE                         *NotifyHandle
 386   );
 387
 388 /**
 389   Remove a registered notification function from a particular keystroke.
 390
 391   @param  This                      Protocol instance pointer.
 392   @param  NotificationHandle        The handle of the notification function being unregistered.
 393
 394   @retval EFI_SUCCESS              The notification function was unregistered successfully.
 395   @retval EFI_INVALID_PARAMETER    The NotificationHandle is invalid or opening gSimpleTextInExNotifyGuid
 396                                    on NotificationHandle fails.
 397   @retval EFI_NOT_FOUND            Can not find the matching entry in database.
 398
 399 **/
 400 EFI_STATUS
 401 EFIAPI
 402 USBKeyboardUnregisterKeyNotify (
 403   IN EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL  *This,
 404   IN EFI_HANDLE                         NotificationHandle
 405   );
 406
 407 /**
 408   Handler function for WaitForKey event.
 409
 410   @param  Event        Event to be signaled when a key is pressed.
 411   @param  Context      Points to USB_KB_DEV instance.
 412
 413 **/
 414 VOID
 415 EFIAPI
 416 USBKeyboardWaitForKey (
 417   IN  EFI_EVENT               Event,
 418   IN  VOID                    *Context
 419   );
 420
 421 /**
 422   Free keyboard notify list.
 423
 424   @param  ListHead                The list head.
 425
 426   @retval EFI_SUCCESS             Free the notify list successfully.
 427   @retval EFI_INVALID_PARAMETER   ListHead is invalid.
 428
 429 **/
 430 EFI_STATUS
 431 EFIAPI
 432 KbdFreeNotifyList (
 433   IN OUT LIST_ENTRY           *ListHead
 434   );
 435
 436 /**
 437   Check whether there is key pending.
 438
 439   @param  UsbKeyboardDevice    The USB_KB_DEV instance.
 440
 441   @retval EFI_SUCCESS          There is pending key to read.
 442   @retval EFI_NOT_READY        No pending key to read.
 443
 444 **/
 445 EFI_STATUS
 446 EFIAPI
 447 USBKeyboardCheckForKey (
 448   IN  USB_KB_DEV    *UsbKeyboardDevice
 449   );
 450
 451 /**
 452   Whether the pressed key matches a registered key or not.
 453
 454   @param  RegsiteredData    A pointer to a buffer that is filled in with the keystroke
 455                             state data for the key that was registered.
 456   @param  InputData         A pointer to a buffer that is filled in with the keystroke
 457                             state data for the key that was pressed.
 458
 459   @retval TRUE              Key pressed matches a registered key.
 460   @retval FLASE             Match failed.
 461
 462 **/
 463 BOOLEAN
 464 EFIAPI
 465 IsKeyRegistered (
 466   IN EFI_KEY_DATA  *RegsiteredData,
 467   IN EFI_KEY_DATA  *InputData
 468   );
 469
 470 #endif
 471