MdeModulePkg/Bus/Usb/UsbKbDxe/KeyBoard.h

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