/** @file\r
Function prototype for USB Keyboard Driver.\r
\r
-Copyright (c) 2004 - 2008, Intel Corporation\r
-All rights reserved. This program and the accompanying materials\r
+Copyright (c) 2004 - 2011, Intel Corporation. All rights reserved.<BR>\r
+This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution. The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
#include "EfiKey.h"\r
\r
+#define USB_KEYBOARD_KEY_COUNT 104\r
+\r
+#define USB_KEYBOARD_LANGUAGE_STR_LEN 5 // RFC4646 Language Code: "en-US"\r
+#define USB_KEYBOARD_DESCRIPTION_STR_LEN (16 + 1) // Description: "English Keyboard"\r
+\r
+#pragma pack (1)\r
+typedef struct {\r
+ //\r
+ // This 4-bytes total array length is required by PreparePackageList()\r
+ //\r
+ UINT32 Length;\r
+\r
+ //\r
+ // Keyboard Layout package definition\r
+ //\r
+ EFI_HII_PACKAGE_HEADER PackageHeader;\r
+ UINT16 LayoutCount;\r
+\r
+ //\r
+ // EFI_HII_KEYBOARD_LAYOUT\r
+ //\r
+ UINT16 LayoutLength;\r
+ EFI_GUID Guid;\r
+ UINT32 LayoutDescriptorStringOffset;\r
+ UINT8 DescriptorCount;\r
+ EFI_KEY_DESCRIPTOR KeyDescriptor[USB_KEYBOARD_KEY_COUNT];\r
+ UINT16 DescriptionCount;\r
+ CHAR16 Language[USB_KEYBOARD_LANGUAGE_STR_LEN];\r
+ CHAR16 Space;\r
+ CHAR16 DescriptionString[USB_KEYBOARD_DESCRIPTION_STR_LEN];\r
+} USB_KEYBOARD_LAYOUT_PACK_BIN;\r
+#pragma pack()\r
/**\r
- Uses USB I/O to check whether the device is a USB Keyboard device.\r
+ Uses USB I/O to check whether the device is a USB keyboard device.\r
\r
- @param UsbIo Points to a USB I/O protocol instance.\r
- @retval None\r
+ @param UsbIo Pointer to a USB I/O protocol instance.\r
+\r
+ @retval TRUE Device is a USB keyboard device.\r
+ @retval FALSE Device is a not USB keyboard device.\r
\r
**/\r
BOOLEAN\r
-EFIAPI\r
IsUSBKeyboard (\r
IN EFI_USB_IO_PROTOCOL *UsbIo\r
);\r
\r
/**\r
- Initialize USB Keyboard device and all private data structures.\r
+ Initialize USB keyboard device and all private data structures.\r
\r
@param UsbKeyboardDevice The USB_KB_DEV instance.\r
\r
@retval EFI_SUCCESS Initialization is successful.\r
- @retval EFI_DEVICE_ERROR Configure hardware failed.\r
+ @retval EFI_DEVICE_ERROR Keyboard initialization failed.\r
\r
**/\r
EFI_STATUS\r
-EFIAPI\r
InitUSBKeyboard (\r
- IN USB_KB_DEV *UsbKeyboardDevice\r
+ IN OUT USB_KB_DEV *UsbKeyboardDevice\r
);\r
\r
/**\r
- Initialize USB Keyboard layout.\r
+ Initialize USB keyboard layout.\r
+\r
+ This function initializes Key Convertion Table for the USB keyboard device.\r
+ It first tries to retrieve layout from HII database. If failed and default\r
+ layout is enabled, then it just uses the default layout.\r
\r
@param UsbKeyboardDevice The USB_KB_DEV instance.\r
\r
- @retval EFI_SUCCESS Initialization Success.\r
- @retval Other Keyboard layout initial failed.\r
+ @retval EFI_SUCCESS Initialization succeeded.\r
+ @retval EFI_NOT_READY Keyboard layout cannot be retrieve from HII\r
+ database, and default layout is disabled.\r
+ @retval Other Fail to register event to EFI_HII_SET_KEYBOARD_LAYOUT_EVENT_GUID group.\r
\r
**/\r
EFI_STATUS\r
-EFIAPI\r
InitKeyboardLayout (\r
- IN USB_KB_DEV *UsbKeyboardDevice\r
+ OUT USB_KB_DEV *UsbKeyboardDevice\r
);\r
\r
/**\r
- Destroy resources for Keyboard layout.\r
+ Destroy resources for keyboard layout.\r
\r
@param UsbKeyboardDevice The USB_KB_DEV instance.\r
\r
**/\r
VOID\r
-EFIAPI\r
ReleaseKeyboardLayoutResources (\r
- IN USB_KB_DEV *UsbKeyboardDevice\r
+ IN OUT USB_KB_DEV *UsbKeyboardDevice\r
);\r
\r
/**\r
- Handler function for USB Keyboard's asynchronous interrupt transfer.\r
+ Handler function for USB keyboard's asynchronous interrupt transfer.\r
+\r
+ This function is the handler function for USB keyboard's asynchronous interrupt transfer\r
+ to manage the keyboard. It parses the USB keyboard input report, and inserts data to\r
+ keyboard buffer according to state of modifer keys and normal keys. Timer for repeat key\r
+ is also set accordingly.\r
\r
@param Data A pointer to a buffer that is filled with key data which is\r
retrieved via asynchronous interrupt transfer.\r
@param Context Pointing to USB_KB_DEV instance.\r
@param Result Indicates the result of the asynchronous interrupt transfer.\r
\r
- @retval EFI_SUCCESS Handler is successful.\r
- @retval EFI_DEVICE_ERROR Hardware Error\r
+ @retval EFI_SUCCESS Asynchronous interrupt transfer is handled successfully.\r
+ @retval EFI_DEVICE_ERROR Hardware error occurs.\r
\r
**/\r
EFI_STATUS\r
);\r
\r
/**\r
- Timer handler for Delayed Recovery timer.\r
+ Handler for Delayed Recovery event.\r
+\r
+ This function is the handler for Delayed Recovery event triggered\r
+ by timer.\r
+ After a device error occurs, the event would be triggered\r
+ with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY\r
+ is defined in USB standard for error handling.\r
\r
@param Event The Delayed Recovery event.\r
@param Context Points to the USB_KB_DEV instance.\r
\r
-\r
**/\r
VOID\r
EFIAPI\r
);\r
\r
/**\r
- Retrieves a key character after parsing the raw data in keyboard buffer.\r
+ Retrieves a USB keycode after parsing the raw data in keyboard buffer.\r
+\r
+ This function parses keyboard buffer. It updates state of modifier key for\r
+ USB_KB_DEV instancem, and returns keycode for output.\r
\r
@param UsbKeyboardDevice The USB_KB_DEV instance.\r
- @param KeyChar Points to the Key character after key parsing.\r
+ @param KeyCode Pointer to the USB keycode for output.\r
\r
- @retval EFI_SUCCESS Parse key is successful.\r
- @retval EFI_NOT_READY Device is not ready.\r
+ @retval EFI_SUCCESS Keycode successfully parsed.\r
+ @retval EFI_NOT_READY Keyboard buffer is not ready for a valid keycode\r
\r
**/\r
EFI_STATUS\r
-EFIAPI\r
USBParseKey (\r
IN OUT USB_KB_DEV *UsbKeyboardDevice,\r
- OUT UINT8 *KeyChar\r
+ OUT UINT8 *KeyCode\r
);\r
\r
/**\r
- Converts USB Keyboard code to EFI Scan Code.\r
+ Converts USB Keycode ranging from 0x4 to 0x65 to EFI_INPUT_KEY.\r
\r
- @param UsbKeyboardDevice The USB_KB_DEV instance.\r
- @param KeyChar Indicates the key code that will be interpreted.\r
- @param Key A pointer to a buffer that is filled in with\r
- the keystroke information for the key that\r
- was pressed.\r
+ @param UsbKeyboardDevice The USB_KB_DEV instance.\r
+ @param KeyCode Indicates the key code that will be interpreted.\r
+ @param KeyData A pointer to a buffer that is filled in with\r
+ the keystroke information for the key that\r
+ was pressed.\r
\r
- @retval EFI_NOT_READY Device is not ready\r
- @retval EFI_SUCCESS Success.\r
+ @retval EFI_SUCCESS Success.\r
+ @retval EFI_INVALID_PARAMETER KeyCode is not in the range of 0x4 to 0x65.\r
+ @retval EFI_INVALID_PARAMETER Translated EFI_INPUT_KEY has zero for both ScanCode and UnicodeChar.\r
+ @retval EFI_NOT_READY KeyCode represents a dead key with EFI_NS_KEY_MODIFIER\r
+ @retval EFI_DEVICE_ERROR Keyboard layout is invalid.\r
\r
**/\r
EFI_STATUS\r
-EFIAPI\r
UsbKeyCodeToEfiInputKey (\r
IN USB_KB_DEV *UsbKeyboardDevice,\r
- IN UINT8 KeyChar,\r
- OUT EFI_INPUT_KEY *Key\r
+ IN UINT8 KeyCode,\r
+ OUT EFI_KEY_DATA *KeyData\r
);\r
\r
+\r
/**\r
- Resets USB Keyboard Buffer.\r
+ Create the queue.\r
\r
- @param KeyboardBuffer Points to the USB Keyboard Buffer.\r
+ @param Queue Points to the queue.\r
+ @param ItemSize Size of the single item.\r
\r
**/\r
VOID\r
-EFIAPI\r
-InitUSBKeyBuffer (\r
- IN OUT USB_KB_BUFFER *KeyboardBuffer\r
+InitQueue (\r
+ IN OUT USB_SIMPLE_QUEUE *Queue,\r
+ IN UINTN ItemSize\r
);\r
\r
/**\r
- Check whether USB Keyboard buffer is empty.\r
+ Destroy the queue\r
\r
- @param KeyboardBuffer USB Keyboard Buffer.\r
+ @param Queue Points to the queue.\r
+**/\r
+VOID\r
+DestroyQueue (\r
+ IN OUT USB_SIMPLE_QUEUE *Queue\r
+ );\r
+\r
+\r
+/**\r
+ Check whether the queue is empty.\r
\r
- @retval TRUE Key buffer is empty.\r
- @retval FALSE Key buffer is not empty.\r
+ @param Queue Points to the queue.\r
+\r
+ @retval TRUE Queue is empty.\r
+ @retval FALSE Queue is not empty.\r
\r
**/\r
BOOLEAN\r
-EFIAPI\r
-IsUSBKeyboardBufferEmpty (\r
- IN USB_KB_BUFFER *KeyboardBuffer\r
+IsQueueEmpty (\r
+ IN USB_SIMPLE_QUEUE *Queue\r
);\r
\r
+\r
/**\r
- Check whether USB Keyboard buffer is full.\r
+ Check whether the queue is full.\r
\r
- @param KeyboardBuffer USB Keyboard Buffer.\r
+ @param Queue Points to the queue.\r
\r
- @retval TRUE Key buffer is full.\r
- @retval FALSE Key buffer is not full.\r
+ @retval TRUE Queue is full.\r
+ @retval FALSE Queue is not full.\r
\r
**/\r
BOOLEAN\r
-EFIAPI\r
-IsUSBKeyboardBufferFull (\r
- IN USB_KB_BUFFER *KeyboardBuffer\r
+IsQueueFull (\r
+ IN USB_SIMPLE_QUEUE *Queue\r
);\r
\r
-/**\r
- Inserts a key code into keyboard buffer.\r
\r
- @param KeyboardBuffer Points to the USB Keyboard Buffer.\r
- @param Key Key code\r
- @param Down Special key\r
+/**\r
+ Enqueue the item to the queue.\r
\r
+ @param Queue Points to the queue.\r
+ @param Item Points to the item to be enqueued.\r
+ @param ItemSize Size of the item.\r
**/\r
VOID\r
-EFIAPI\r
-InsertKeyCode (\r
- IN OUT USB_KB_BUFFER *KeyboardBuffer,\r
- IN UINT8 Key,\r
- IN UINT8 Down\r
+Enqueue (\r
+ IN OUT USB_SIMPLE_QUEUE *Queue,\r
+ IN VOID *Item,\r
+ IN UINTN ItemSize\r
);\r
\r
+\r
/**\r
- Pops a key code off from keyboard buffer.\r
+ Dequeue a item from the queue.\r
\r
- @param KeyboardBuffer Points to the USB Keyboard Buffer.\r
- @param UsbKey Points to the buffer that contains a usb key code.\r
+ @param Queue Points to the queue.\r
+ @param Item Receives the item.\r
+ @param ItemSize Size of the item.\r
\r
- @retval EFI_SUCCESS Success\r
- @retval EFI_DEVICE_ERROR Hardware Error\r
+ @retval EFI_SUCCESS Item was successfully dequeued.\r
+ @retval EFI_DEVICE_ERROR The queue is empty.\r
\r
**/\r
EFI_STATUS\r
-EFIAPI\r
-RemoveKeyCode (\r
- IN OUT USB_KB_BUFFER *KeyboardBuffer,\r
- OUT USB_KEY *UsbKey\r
+Dequeue (\r
+ IN OUT USB_SIMPLE_QUEUE *Queue,\r
+ OUT VOID *Item,\r
+ IN UINTN ItemSize\r
);\r
\r
/**\r
- Timer handler for Repeat Key timer.\r
+ Handler for Repeat Key event.\r
+\r
+ This function is the handler for Repeat Key event triggered\r
+ by timer.\r
+ After a repeatable key is pressed, the event would be triggered\r
+ with interval of USBKBD_REPEAT_DELAY. Once the event is triggered,\r
+ following trigger will come with interval of USBKBD_REPEAT_RATE.\r
\r
@param Event The Repeat Key event.\r
@param Context Points to the USB_KB_DEV instance.\r
\r
-\r
**/\r
VOID\r
EFIAPI\r
);\r
\r
/**\r
- Sets USB Keyboard LED state.\r
+ Sets USB keyboard LED state.\r
\r
@param UsbKeyboardDevice The USB_KB_DEV instance.\r
\r
**/\r
VOID\r
-EFIAPI\r
SetKeyLED (\r
IN USB_KB_DEV *UsbKeyboardDevice\r
);\r