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 321