MdeModulePkg/Bus/Usb/UsbKbDxe/KeyBoard.h

   1 /** @file
   2   Function prototype for USB Keyboard Driver.
   3
   4 Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef _EFI_KEYBOARD_H_
  10 #define _EFI_KEYBOARD_H_
  11
  12 #include "EfiKey.h"
  13
  14 #define USB_KEYBOARD_KEY_COUNT  105
  15
  16 #define USB_KEYBOARD_LANGUAGE_STR_LEN     5         // RFC4646 Language Code: "en-US"
  17 #define USB_KEYBOARD_DESCRIPTION_STR_LEN  (16 + 1)  // Description: "English Keyboard"
  18
  19 #pragma pack (1)
  20 typedef struct {
  21   //
  22   // This 4-bytes total array length is required by PreparePackageList()
  23   //
  24   UINT32                    Length;
  25
  26   //
  27   // Keyboard Layout package definition
  28   //
  29   EFI_HII_PACKAGE_HEADER    PackageHeader;
  30   UINT16                    LayoutCount;
  31
  32   //
  33   // EFI_HII_KEYBOARD_LAYOUT
  34   //
  35   UINT16                    LayoutLength;
  36   EFI_GUID                  Guid;
  37   UINT32                    LayoutDescriptorStringOffset;
  38   UINT8                     DescriptorCount;
  39   EFI_KEY_DESCRIPTOR        KeyDescriptor[USB_KEYBOARD_KEY_COUNT];
  40   UINT16                    DescriptionCount;
  41   CHAR16                    Language[USB_KEYBOARD_LANGUAGE_STR_LEN];
  42   CHAR16                    Space;
  43   CHAR16                    DescriptionString[USB_KEYBOARD_DESCRIPTION_STR_LEN];
  44 } USB_KEYBOARD_LAYOUT_PACK_BIN;
  45 #pragma pack()
  46
  47 /**
  48   Uses USB I/O to check whether the device is a USB keyboard device.
  49
  50   @param  UsbIo    Pointer to a USB I/O protocol instance.
  51
  52   @retval TRUE     Device is a USB keyboard device.
  53   @retval FALSE    Device is a not USB keyboard device.
  54
  55 **/
  56 BOOLEAN
  57 IsUSBKeyboard (
  58   IN  EFI_USB_IO_PROTOCOL  *UsbIo
  59   );
  60
  61 /**
  62   Initialize USB keyboard device and all private data structures.
  63
  64   @param  UsbKeyboardDevice  The USB_KB_DEV instance.
  65
  66   @retval EFI_SUCCESS        Initialization is successful.
  67   @retval EFI_DEVICE_ERROR   Keyboard initialization failed.
  68
  69 **/
  70 EFI_STATUS
  71 InitUSBKeyboard (
  72   IN OUT USB_KB_DEV  *UsbKeyboardDevice
  73   );
  74
  75 /**
  76   Initialize USB keyboard layout.
  77
  78   This function initializes Key Convertion Table for the USB keyboard device.
  79   It first tries to retrieve layout from HII database. If failed and default
  80   layout is enabled, then it just uses the default layout.
  81
  82   @param  UsbKeyboardDevice      The USB_KB_DEV instance.
  83
  84   @retval EFI_SUCCESS            Initialization succeeded.
  85   @retval EFI_NOT_READY          Keyboard layout cannot be retrieve from HII
  86                                  database, and default layout is disabled.
  87   @retval Other                  Fail to register event to EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID group.
  88
  89 **/
  90 EFI_STATUS
  91 InitKeyboardLayout (
  92   OUT USB_KB_DEV  *UsbKeyboardDevice
  93   );
  94
  95 /**
  96   Destroy resources for keyboard layout.
  97
  98   @param  UsbKeyboardDevice    The USB_KB_DEV instance.
  99
 100 **/
 101 VOID
 102 ReleaseKeyboardLayoutResources (
 103   IN OUT USB_KB_DEV  *UsbKeyboardDevice
 104   );
 105
 106 /**
 107   Handler function for USB keyboard's asynchronous interrupt transfer.
 108
 109   This function is the handler function for USB keyboard's asynchronous interrupt transfer
 110   to manage the keyboard. It parses the USB keyboard input report, and inserts data to
 111   keyboard buffer according to state of modifier keys and normal keys. Timer for repeat key
 112   is also set accordingly.
 113
 114   @param  Data             A pointer to a buffer that is filled with key data which is
 115                            retrieved via asynchronous interrupt transfer.
 116   @param  DataLength       Indicates the size of the data buffer.
 117   @param  Context          Pointing to USB_KB_DEV instance.
 118   @param  Result           Indicates the result of the asynchronous interrupt transfer.
 119
 120   @retval EFI_SUCCESS      Asynchronous interrupt transfer is handled successfully.
 121   @retval EFI_DEVICE_ERROR Hardware error occurs.
 122
 123 **/
 124 EFI_STATUS
 125 EFIAPI
 126 KeyboardHandler (
 127   IN  VOID    *Data,
 128   IN  UINTN   DataLength,
 129   IN  VOID    *Context,
 130   IN  UINT32  Result
 131   );
 132
 133 /**
 134   Handler for Delayed Recovery event.
 135
 136   This function is the handler for Delayed Recovery event triggered
 137   by timer.
 138   After a device error occurs, the event would be triggered
 139   with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY
 140   is defined in USB standard for error handling.
 141
 142   @param  Event              The Delayed Recovery event.
 143   @param  Context            Points to the USB_KB_DEV instance.
 144
 145 **/
 146 VOID
 147 EFIAPI
 148 USBKeyboardRecoveryHandler (
 149   IN    EFI_EVENT  Event,
 150   IN    VOID       *Context
 151   );
 152
 153 /**
 154   Retrieves a USB keycode after parsing the raw data in keyboard buffer.
 155
 156   This function parses keyboard buffer. It updates state of modifier key for
 157   USB_KB_DEV instancem, and returns keycode for output.
 158
 159   @param  UsbKeyboardDevice    The USB_KB_DEV instance.
 160   @param  KeyCode              Pointer to the USB keycode for output.
 161
 162   @retval EFI_SUCCESS          Keycode successfully parsed.
 163   @retval EFI_NOT_READY        Keyboard buffer is not ready for a valid keycode
 164
 165 **/
 166 EFI_STATUS
 167 USBParseKey (
 168   IN OUT  USB_KB_DEV  *UsbKeyboardDevice,
 169   OUT     UINT8       *KeyCode
 170   );
 171
 172 /**
 173   Converts USB Keycode ranging from 0x4 to 0x65 to EFI_INPUT_KEY.
 174
 175   @param  UsbKeyboardDevice     The USB_KB_DEV instance.
 176   @param  KeyCode               Indicates the key code that will be interpreted.
 177   @param  KeyData               A pointer to a buffer that is filled in with
 178                                 the keystroke information for the key that
 179                                 was pressed.
 180
 181   @retval EFI_SUCCESS           Success.
 182   @retval EFI_INVALID_PARAMETER KeyCode is not in the range of 0x4 to 0x65.
 183   @retval EFI_INVALID_PARAMETER Translated EFI_INPUT_KEY has zero for both ScanCode and UnicodeChar.
 184   @retval EFI_NOT_READY         KeyCode represents a dead key with EFI_NS_KEY_MODIFIER
 185   @retval EFI_DEVICE_ERROR      Keyboard layout is invalid.
 186
 187 **/
 188 EFI_STATUS
 189 UsbKeyCodeToEfiInputKey (
 190   IN  USB_KB_DEV    *UsbKeyboardDevice,
 191   IN  UINT8         KeyCode,
 192   OUT EFI_KEY_DATA  *KeyData
 193   );
 194
 195 /**
 196   Create the queue.
 197
 198   @param  Queue     Points to the queue.
 199   @param  ItemSize  Size of the single item.
 200
 201 **/
 202 VOID
 203 InitQueue (
 204   IN OUT  USB_SIMPLE_QUEUE  *Queue,
 205   IN      UINTN             ItemSize
 206   );
 207
 208 /**
 209   Destroy the queue
 210
 211   @param Queue    Points to the queue.
 212 **/
 213 VOID
 214 DestroyQueue (
 215   IN OUT USB_SIMPLE_QUEUE  *Queue
 216   );
 217
 218 /**
 219   Check whether the queue is empty.
 220
 221   @param  Queue     Points to the queue.
 222
 223   @retval TRUE      Queue is empty.
 224   @retval FALSE     Queue is not empty.
 225
 226 **/
 227 BOOLEAN
 228 IsQueueEmpty (
 229   IN  USB_SIMPLE_QUEUE  *Queue
 230   );
 231
 232 /**
 233   Check whether the queue is full.
 234
 235   @param  Queue     Points to the queue.
 236
 237   @retval TRUE      Queue is full.
 238   @retval FALSE     Queue is not full.
 239
 240 **/
 241 BOOLEAN
 242 IsQueueFull (
 243   IN  USB_SIMPLE_QUEUE  *Queue
 244   );
 245
 246 /**
 247   Enqueue the item to the queue.
 248
 249   @param  Queue     Points to the queue.
 250   @param  Item      Points to the item to be enqueued.
 251   @param  ItemSize  Size of the item.
 252 **/
 253 VOID
 254 Enqueue (
 255   IN OUT  USB_SIMPLE_QUEUE  *Queue,
 256   IN      VOID              *Item,
 257   IN      UINTN             ItemSize
 258   );
 259
 260 /**
 261   Dequeue a item from the queue.
 262
 263   @param  Queue     Points to the queue.
 264   @param  Item      Receives the item.
 265   @param  ItemSize  Size of the item.
 266
 267   @retval EFI_SUCCESS        Item was successfully dequeued.
 268   @retval EFI_DEVICE_ERROR   The queue is empty.
 269
 270 **/
 271 EFI_STATUS
 272 Dequeue (
 273   IN OUT  USB_SIMPLE_QUEUE  *Queue,
 274   OUT  VOID                 *Item,
 275   IN      UINTN             ItemSize
 276   );
 277
 278 /**
 279   Handler for Repeat Key event.
 280
 281   This function is the handler for Repeat Key event triggered
 282   by timer.
 283   After a repeatable key is pressed, the event would be triggered
 284   with interval of USBKBD_REPEAT_DELAY. Once the event is triggered,
 285   following trigger will come with interval of USBKBD_REPEAT_RATE.
 286
 287   @param  Event              The Repeat Key event.
 288   @param  Context            Points to the USB_KB_DEV instance.
 289
 290 **/
 291 VOID
 292 EFIAPI
 293 USBKeyboardRepeatHandler (
 294   IN    EFI_EVENT  Event,
 295   IN    VOID       *Context
 296   );
 297
 298 /**
 299   Sets USB keyboard LED state.
 300
 301   @param  UsbKeyboardDevice  The USB_KB_DEV instance.
 302
 303 **/
 304 VOID
 305 SetKeyLED (
 306   IN  USB_KB_DEV  *UsbKeyboardDevice
 307   );
 308
 309 /**
 310   Initialize the key state.
 311
 312   @param  UsbKeyboardDevice     The USB_KB_DEV instance.
 313   @param  KeyState              A pointer to receive the key state information.
 314 **/
 315 VOID
 316 InitializeKeyState (
 317   IN  USB_KB_DEV     *UsbKeyboardDevice,
 318   OUT EFI_KEY_STATE  *KeyState
 319   );
 320
 321 #endif