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