MdeModulePkg/Bus/Usb/UsbKbDxe/KeyBoard.h

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