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
 165 **/
 166 EFI_STATUS
 167 EFIAPI
 168 UsbKeyCodeToEfiInputKey (
 169   IN  USB_KB_DEV      *UsbKeyboardDevice,
 170   IN  UINT8           KeyCode,
 171   OUT EFI_INPUT_KEY   *Key
 172   );
 173
 174 /**
 175   Resets USB keyboard buffer.
 176
 177   @param  KeyboardBuffer     Points to the USB keyboard buffer.
 178
 179 **/
 180 VOID
 181 EFIAPI
 182 InitUSBKeyBuffer (
 183   OUT  USB_KB_BUFFER   *KeyboardBuffer
 184   );
 185
 186 /**
 187   Check whether USB keyboard buffer is empty.
 188
 189   @param  KeyboardBuffer     USB keyboard buffer
 190
 191   @retval TRUE               Keyboard buffer is empty.
 192   @retval FALSE              Keyboard buffer is not empty.
 193
 194 **/
 195 BOOLEAN
 196 EFIAPI
 197 IsUSBKeyboardBufferEmpty (
 198   IN  USB_KB_BUFFER   *KeyboardBuffer
 199   );
 200
 201 /**
 202   Check whether USB keyboard buffer is full.
 203
 204   @param  KeyboardBuffer     USB keyboard buffer
 205
 206   @retval TRUE               Keyboard buffer is full.
 207   @retval FALSE              Keyboard buffer is not full.
 208
 209 **/
 210 BOOLEAN
 211 EFIAPI
 212 IsUSBKeyboardBufferFull (
 213   IN  USB_KB_BUFFER   *KeyboardBuffer
 214   );
 215
 216 /**
 217   Inserts a keycode into keyboard buffer.
 218
 219   @param  KeyboardBuffer     Points to the USB keyboard buffer.
 220   @param  Key                Keycode to insert.
 221   @param  Down               TRUE means key is pressed.
 222                              FALSE means key is released.
 223
 224 **/
 225 VOID
 226 EFIAPI
 227 InsertKeyCode (
 228   IN OUT  USB_KB_BUFFER *KeyboardBuffer,
 229   IN      UINT8         Key,
 230   IN      BOOLEAN       Down
 231   );
 232
 233 /**
 234   Remove a keycode from keyboard buffer and return it.
 235
 236   @param  KeyboardBuffer     Points to the USB keyboard buffer.
 237   @param  UsbKey             Points to the buffer that contains keycode for output.
 238
 239   @retval EFI_SUCCESS        Keycode successfully removed from keyboard buffer.
 240   @retval EFI_DEVICE_ERROR   Keyboard buffer is empty.
 241
 242 **/
 243 EFI_STATUS
 244 EFIAPI
 245 RemoveKeyCode (
 246   IN OUT  USB_KB_BUFFER *KeyboardBuffer,
 247      OUT  USB_KEY       *UsbKey
 248   );
 249
 250 /**
 251   Handler for Repeat Key event.
 252
 253   This function is the handler for Repeat Key event triggered
 254   by timer.
 255   After a repeatable key is pressed, the event would be triggered
 256   with interval of USBKBD_REPEAT_DELAY. Once the event is triggered,
 257   following trigger will come with interval of USBKBD_REPEAT_RATE.
 258
 259   @param  Event              The Repeat Key event.
 260   @param  Context            Points to the USB_KB_DEV instance.
 261
 262 **/
 263 VOID
 264 EFIAPI
 265 USBKeyboardRepeatHandler (
 266   IN    EFI_EVENT    Event,
 267   IN    VOID         *Context
 268   );
 269
 270 /**
 271   Sets USB keyboard LED state.
 272
 273   @param  UsbKeyboardDevice  The USB_KB_DEV instance.
 274
 275 **/
 276 VOID
 277 EFIAPI
 278 SetKeyLED (
 279   IN  USB_KB_DEV    *UsbKeyboardDevice
 280   );
 281
 282 #endif