MdeModulePkg/Bus/Usb/UsbKbDxe/KeyBoard.h

   1 /** @file
   2   Function prototype for USB Keyboard Driver.
   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
  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 EFIAPI
  74 IsUSBKeyboard (
  75   IN  EFI_USB_IO_PROTOCOL       *UsbIo
  76   );
  77
  78 /**
  79   Initialize USB keyboard device and all private data structures.
  80
  81   @param  UsbKeyboardDevice  The USB_KB_DEV instance.
  82
  83   @retval EFI_SUCCESS        Initialization is successful.
  84   @retval EFI_DEVICE_ERROR   Keyboard initialization failed.
  85
  86 **/
  87 EFI_STATUS
  88 EFIAPI
  89 InitUSBKeyboard (
  90   IN OUT USB_KB_DEV   *UsbKeyboardDevice
  91   );
  92
  93 /**
  94   Initialize USB keyboard layout.
  95
  96   This function initializes Key Convertion Table for the USB keyboard device.
  97   It first tries to retrieve layout from HII database. If failed and default
  98   layout is enabled, then it just uses the default layout.
  99
 100   @param  UsbKeyboardDevice      The USB_KB_DEV instance.
 101
 102   @retval EFI_SUCCESS            Initialization succeeded.
 103   @retval EFI_NOT_READY          Keyboard layout cannot be retrieve from HII
 104                                  database, and default layout is disabled.
 105   @retval Other                  Fail to register event to EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID group.
 106
 107 **/
 108 EFI_STATUS
 109 EFIAPI
 110 InitKeyboardLayout (
 111   OUT USB_KB_DEV   *UsbKeyboardDevice
 112   );
 113
 114 /**
 115   Destroy resources for keyboard layout.
 116
 117   @param  UsbKeyboardDevice    The USB_KB_DEV instance.
 118
 119 **/
 120 VOID
 121 EFIAPI
 122 ReleaseKeyboardLayoutResources (
 123   IN OUT USB_KB_DEV              *UsbKeyboardDevice
 124   );
 125
 126 /**
 127   Handler function for USB keyboard's asynchronous interrupt transfer.
 128
 129   This function is the handler function for USB keyboard's asynchronous interrupt transfer
 130   to manage the keyboard. It parses the USB keyboard input report, and inserts data to
 131   keyboard buffer according to state of modifer keys and normal keys. Timer for repeat key
 132   is also set accordingly.
 133
 134   @param  Data             A pointer to a buffer that is filled with key data which is
 135                            retrieved via asynchronous interrupt transfer.
 136   @param  DataLength       Indicates the size of the data buffer.
 137   @param  Context          Pointing to USB_KB_DEV instance.
 138   @param  Result           Indicates the result of the asynchronous interrupt transfer.
 139
 140   @retval EFI_SUCCESS      Asynchronous interrupt transfer is handled successfully.
 141   @retval EFI_DEVICE_ERROR Hardware error occurs.
 142
 143 **/
 144 EFI_STATUS
 145 EFIAPI
 146 KeyboardHandler (
 147   IN  VOID          *Data,
 148   IN  UINTN         DataLength,
 149   IN  VOID          *Context,
 150   IN  UINT32        Result
 151   );
 152
 153 /**
 154   Handler for Delayed Recovery event.
 155
 156   This function is the handler for Delayed Recovery event triggered
 157   by timer.
 158   After a device error occurs, the event would be triggered
 159   with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY
 160   is defined in USB standard for error handling.
 161
 162   @param  Event              The Delayed Recovery event.
 163   @param  Context            Points to the USB_KB_DEV instance.
 164
 165 **/
 166 VOID
 167 EFIAPI
 168 USBKeyboardRecoveryHandler (
 169   IN    EFI_EVENT    Event,
 170   IN    VOID         *Context
 171   );
 172
 173 /**
 174   Retrieves a USB keycode after parsing the raw data in keyboard buffer.
 175
 176   This function parses keyboard buffer. It updates state of modifier key for
 177   USB_KB_DEV instancem, and returns keycode for output.
 178
 179   @param  UsbKeyboardDevice    The USB_KB_DEV instance.
 180   @param  KeyCode              Pointer to the USB keycode for output.
 181
 182   @retval EFI_SUCCESS          Keycode successfully parsed.
 183   @retval EFI_NOT_READY        Keyboard buffer is not ready for a valid keycode
 184
 185 **/
 186 EFI_STATUS
 187 EFIAPI
 188 USBParseKey (
 189   IN OUT  USB_KB_DEV  *UsbKeyboardDevice,
 190   OUT     UINT8       *KeyCode
 191   );
 192
 193 /**
 194   Converts USB Keycode ranging from 0x4 to 0x65 to EFI_INPUT_KEY.
 195
 196   @param  UsbKeyboardDevice     The USB_KB_DEV instance.
 197   @param  KeyCode               Indicates the key code that will be interpreted.
 198   @param  Key                   A pointer to a buffer that is filled in with
 199                                 the keystroke information for the key that
 200                                 was pressed.
 201
 202   @retval EFI_SUCCESS           Success.
 203   @retval EFI_INVALID_PARAMETER KeyCode is not in the range of 0x4 to 0x65.
 204   @retval EFI_INVALID_PARAMETER Translated EFI_INPUT_KEY has zero for both ScanCode and UnicodeChar.
 205   @retval EFI_NOT_READY         KeyCode represents a dead key with EFI_NS_KEY_MODIFIER
 206   @retval EFI_DEVICE_ERROR      Keyboard layout is invalid.
 207
 208 **/
 209 EFI_STATUS
 210 EFIAPI
 211 UsbKeyCodeToEfiInputKey (
 212   IN  USB_KB_DEV      *UsbKeyboardDevice,
 213   IN  UINT8           KeyCode,
 214   OUT EFI_INPUT_KEY   *Key
 215   );
 216
 217 /**
 218   Resets USB keyboard buffer.
 219
 220   @param  KeyboardBuffer     Points to the USB keyboard buffer.
 221
 222 **/
 223 VOID
 224 EFIAPI
 225 InitUSBKeyBuffer (
 226   OUT  USB_KB_BUFFER   *KeyboardBuffer
 227   );
 228
 229 /**
 230   Check whether USB keyboard buffer is empty.
 231
 232   @param  KeyboardBuffer     USB keyboard buffer
 233
 234   @retval TRUE               Keyboard buffer is empty.
 235   @retval FALSE              Keyboard buffer is not empty.
 236
 237 **/
 238 BOOLEAN
 239 EFIAPI
 240 IsUSBKeyboardBufferEmpty (
 241   IN  USB_KB_BUFFER   *KeyboardBuffer
 242   );
 243
 244 /**
 245   Check whether USB keyboard buffer is full.
 246
 247   @param  KeyboardBuffer     USB keyboard buffer
 248
 249   @retval TRUE               Keyboard buffer is full.
 250   @retval FALSE              Keyboard buffer is not full.
 251
 252 **/
 253 BOOLEAN
 254 EFIAPI
 255 IsUSBKeyboardBufferFull (
 256   IN  USB_KB_BUFFER   *KeyboardBuffer
 257   );
 258
 259 /**
 260   Inserts a keycode into keyboard buffer.
 261
 262   @param  KeyboardBuffer     Points to the USB keyboard buffer.
 263   @param  Key                Keycode to insert.
 264   @param  Down               TRUE means key is pressed.
 265                              FALSE means key is released.
 266
 267 **/
 268 VOID
 269 EFIAPI
 270 InsertKeyCode (
 271   IN OUT  USB_KB_BUFFER *KeyboardBuffer,
 272   IN      UINT8         Key,
 273   IN      BOOLEAN       Down
 274   );
 275
 276 /**
 277   Remove a keycode from keyboard buffer and return it.
 278
 279   @param  KeyboardBuffer     Points to the USB keyboard buffer.
 280   @param  UsbKey             Points to the buffer that contains keycode for output.
 281
 282   @retval EFI_SUCCESS        Keycode successfully removed from keyboard buffer.
 283   @retval EFI_DEVICE_ERROR   Keyboard buffer is empty.
 284
 285 **/
 286 EFI_STATUS
 287 EFIAPI
 288 RemoveKeyCode (
 289   IN OUT  USB_KB_BUFFER *KeyboardBuffer,
 290      OUT  USB_KEY       *UsbKey
 291   );
 292
 293 /**
 294   Handler for Repeat Key event.
 295
 296   This function is the handler for Repeat Key event triggered
 297   by timer.
 298   After a repeatable key is pressed, the event would be triggered
 299   with interval of USBKBD_REPEAT_DELAY. Once the event is triggered,
 300   following trigger will come with interval of USBKBD_REPEAT_RATE.
 301
 302   @param  Event              The Repeat Key event.
 303   @param  Context            Points to the USB_KB_DEV instance.
 304
 305 **/
 306 VOID
 307 EFIAPI
 308 USBKeyboardRepeatHandler (
 309   IN    EFI_EVENT    Event,
 310   IN    VOID         *Context
 311   );
 312
 313 /**
 314   Sets USB keyboard LED state.
 315
 316   @param  UsbKeyboardDevice  The USB_KB_DEV instance.
 317
 318 **/
 319 VOID
 320 EFIAPI
 321 SetKeyLED (
 322   IN  USB_KB_DEV    *UsbKeyboardDevice
 323   );
 324
 325 #endif