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
  13 #include "EfiKey.h"
  14
  15 #define USB_KEYBOARD_KEY_COUNT            105
  16
  17 #define USB_KEYBOARD_LANGUAGE_STR_LEN     5         // RFC4646 Language Code: "en-US"
  18 #define USB_KEYBOARD_DESCRIPTION_STR_LEN  (16 + 1)  // Description: "English Keyboard"
  19
  20 #pragma pack (1)
  21 typedef struct {
  22   //
  23   // This 4-bytes total array length is required by PreparePackageList()
  24   //
  25   UINT32                 Length;
  26
  27   //
  28   // Keyboard Layout package definition
  29   //
  30   EFI_HII_PACKAGE_HEADER PackageHeader;
  31   UINT16                 LayoutCount;
  32
  33   //
  34   // EFI_HII_KEYBOARD_LAYOUT
  35   //
  36   UINT16                 LayoutLength;
  37   EFI_GUID               Guid;
  38   UINT32                 LayoutDescriptorStringOffset;
  39   UINT8                  DescriptorCount;
  40   EFI_KEY_DESCRIPTOR     KeyDescriptor[USB_KEYBOARD_KEY_COUNT];
  41   UINT16                 DescriptionCount;
  42   CHAR16                 Language[USB_KEYBOARD_LANGUAGE_STR_LEN];
  43   CHAR16                 Space;
  44   CHAR16                 DescriptionString[USB_KEYBOARD_DESCRIPTION_STR_LEN];
  45 } USB_KEYBOARD_LAYOUT_PACK_BIN;
  46 #pragma pack()
  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 /**
 197   Create the queue.
 198
 199   @param  Queue     Points to the queue.
 200   @param  ItemSize  Size of the single item.
 201
 202 **/
 203 VOID
 204 InitQueue (
 205   IN OUT  USB_SIMPLE_QUEUE   *Queue,
 206   IN      UINTN              ItemSize
 207   );
 208
 209 /**
 210   Destroy the queue
 211
 212   @param Queue    Points to the queue.
 213 **/
 214 VOID
 215 DestroyQueue (
 216   IN OUT USB_SIMPLE_QUEUE   *Queue
 217   );
 218
 219
 220 /**
 221   Check whether the queue is empty.
 222
 223   @param  Queue     Points to the queue.
 224
 225   @retval TRUE      Queue is empty.
 226   @retval FALSE     Queue is not empty.
 227
 228 **/
 229 BOOLEAN
 230 IsQueueEmpty (
 231   IN  USB_SIMPLE_QUEUE   *Queue
 232   );
 233
 234
 235 /**
 236   Check whether the queue is full.
 237
 238   @param  Queue     Points to the queue.
 239
 240   @retval TRUE      Queue is full.
 241   @retval FALSE     Queue is not full.
 242
 243 **/
 244 BOOLEAN
 245 IsQueueFull (
 246   IN  USB_SIMPLE_QUEUE   *Queue
 247   );
 248
 249
 250 /**
 251   Enqueue the item to the queue.
 252
 253   @param  Queue     Points to the queue.
 254   @param  Item      Points to the item to be enqueued.
 255   @param  ItemSize  Size of the item.
 256 **/
 257 VOID
 258 Enqueue (
 259   IN OUT  USB_SIMPLE_QUEUE *Queue,
 260   IN      VOID             *Item,
 261   IN      UINTN            ItemSize
 262   );
 263
 264
 265 /**
 266   Dequeue a item from the queue.
 267
 268   @param  Queue     Points to the queue.
 269   @param  Item      Receives the item.
 270   @param  ItemSize  Size of the item.
 271
 272   @retval EFI_SUCCESS        Item was successfully dequeued.
 273   @retval EFI_DEVICE_ERROR   The queue is empty.
 274
 275 **/
 276 EFI_STATUS
 277 Dequeue (
 278   IN OUT  USB_SIMPLE_QUEUE *Queue,
 279      OUT  VOID             *Item,
 280   IN      UINTN            ItemSize
 281   );
 282
 283 /**
 284   Handler for Repeat Key event.
 285
 286   This function is the handler for Repeat Key event triggered
 287   by timer.
 288   After a repeatable key is pressed, the event would be triggered
 289   with interval of USBKBD_REPEAT_DELAY. Once the event is triggered,
 290   following trigger will come with interval of USBKBD_REPEAT_RATE.
 291
 292   @param  Event              The Repeat Key event.
 293   @param  Context            Points to the USB_KB_DEV instance.
 294
 295 **/
 296 VOID
 297 EFIAPI
 298 USBKeyboardRepeatHandler (
 299   IN    EFI_EVENT    Event,
 300   IN    VOID         *Context
 301   );
 302
 303 /**
 304   Sets USB keyboard LED state.
 305
 306   @param  UsbKeyboardDevice  The USB_KB_DEV instance.
 307
 308 **/
 309 VOID
 310 SetKeyLED (
 311   IN  USB_KB_DEV    *UsbKeyboardDevice
 312   );
 313
 314 /**
 315   Initialize the key state.
 316
 317   @param  UsbKeyboardDevice     The USB_KB_DEV instance.
 318   @param  KeyState              A pointer to receive the key state information.
 319 **/
 320 VOID
 321 InitializeKeyState (
 322   IN  USB_KB_DEV           *UsbKeyboardDevice,
 323   OUT EFI_KEY_STATE        *KeyState
 324   );
 325
 326 #endif