/** @file\r
- USB Keyboard Driver that includes the implementation of interface.\r
+ USB Keyboard Driver that manages USB keyboard and produces Simple Text Input\r
+ Protocol and Simple Text Input Ex Protocol.\r
\r
Copyright (c) 2004 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
}\r
\r
//\r
- // Use the USB I/O Protocol interface to check whether the Controller is\r
- // the Keyboard controller that can be managed by this driver.\r
+ // Use the USB I/O Protocol interface to check whether Controller is\r
+ // a keyboard device that can be managed by this driver.\r
//\r
Status = EFI_SUCCESS;\r
\r
}\r
\r
/**\r
- Start running driver on the controller.\r
+ Starts the device with this driver.\r
+\r
+ This function produces Simple Text Input Protocol and Simple Text Input Ex Protocol,\r
+ initializes the keyboard device, and submit Asynchronous Interrupt Transfer to manage\r
+ this keyboard device.\r
\r
@param This The USB keyboard driver binding instance.\r
@param Controller Handle of device to bind driver to.\r
\r
@retval EFI_SUCCESS The controller is controlled by the usb keyboard driver.\r
@retval EFI_UNSUPPORTED No interrupt endpoint can be found.\r
- @retval Other The keyboard driver cannot support this controller.\r
+ @retval Other This controller cannot be started.\r
\r
**/\r
EFI_STATUS\r
UsbKeyboardDevice->DevicePath\r
);\r
\r
- //\r
- // Initialize UsbKeyboardDevice\r
- //\r
UsbKeyboardDevice->UsbIo = UsbIo;\r
\r
//\r
\r
\r
/**\r
- Stop handling the controller by this USB keyboard driver.\r
+ Stop the USB keyboard device handled by this driver.\r
\r
@param This The USB keyboard driver binding protocol.\r
@param Controller The controller to release.\r
@param NumberOfChildren The number of handles in ChildHandleBuffer.\r
@param ChildHandleBuffer The array of child handle.\r
\r
- @retval EFI_SUCCESS The controller or children are stopped.\r
+ @retval EFI_SUCCESS The device was stopped.\r
@retval EFI_UNSUPPORTED Simple Text In Protocol or Simple Text In Ex Protocol\r
is not installed on Controller.\r
- @retval EFI_DEVICE_ERROR Failed to stop the driver.\r
+ @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.\r
+ @retval Others Fail to uninstall protocols attached on the device.\r
\r
**/\r
EFI_STATUS\r
if (EFI_ERROR (Status)) {\r
return EFI_UNSUPPORTED;\r
}\r
- //\r
- // Get USB_KB_DEV instance.\r
- //\r
+\r
UsbKeyboardDevice = USB_KB_DEV_FROM_THIS (SimpleInput);\r
\r
//\r
}\r
\r
/**\r
- Internal function to read the next keystroke from the input device.\r
+ Internal function to read the next keystroke from the keyboard buffer.\r
\r
- @param UsbKeyboardDevice Usb keyboard's private structure.\r
- @param KeyData A pointer to a buffer that is filled in with the keystroke\r
- state data for the key that was pressed.\r
+ @param UsbKeyboardDevice USB keyboard's private structure.\r
+ @param KeyData A pointer to buffer to hold the keystroke\r
+ data for the key that was pressed.\r
\r
- @return EFI_SUCCESS The keystroke information was returned.\r
- @return EFI_NOT_READY There was no keystroke data availiable.\r
- @return EFI_DEVICE_ERROR The keystroke information was not returned due to\r
+ @retval EFI_SUCCESS The keystroke information was returned.\r
+ @retval EFI_NOT_READY There was no keystroke data availiable.\r
+ @retval EFI_DEVICE_ERROR The keystroke information was not returned due to\r
hardware errors.\r
- @return EFI_INVALID_PARAMETER KeyData is NULL.\r
+ @retval EFI_INVALID_PARAMETER KeyData is NULL.\r
+ @retval Others Fail to translate keycode into EFI_INPUT_KEY\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
USBKeyboardReadKeyStrokeWorker (\r
- IN USB_KB_DEV *UsbKeyboardDevice,\r
- OUT EFI_KEY_DATA *KeyData\r
+ IN OUT USB_KB_DEV *UsbKeyboardDevice,\r
+ OUT EFI_KEY_DATA *KeyData\r
)\r
{\r
EFI_STATUS Status;\r
- UINT8 KeyChar; \r
+ UINT8 KeyCode; \r
LIST_ENTRY *Link;\r
KEYBOARD_CONSOLE_IN_EX_NOTIFY *CurrentNotify; \r
EFI_KEY_DATA OriginalKeyData;\r
}\r
\r
//\r
- // If there is no saved ASCII byte, fetch it\r
+ // If there is no saved USB keycode, fetch it\r
// by calling USBKeyboardCheckForKey().\r
//\r
- if (UsbKeyboardDevice->CurKeyChar == 0) {\r
+ if (UsbKeyboardDevice->CurKeyCode == 0) {\r
Status = USBKeyboardCheckForKey (UsbKeyboardDevice);\r
if (EFI_ERROR (Status)) {\r
return EFI_NOT_READY;\r
KeyData->Key.ScanCode = SCAN_NULL;\r
\r
//\r
- // Store the key char read by USBKeyboardCheckForKey() and clear it.\r
+ // Store the current keycode and clear it.\r
//\r
- KeyChar = UsbKeyboardDevice->CurKeyChar;\r
- UsbKeyboardDevice->CurKeyChar = 0;\r
+ KeyCode = UsbKeyboardDevice->CurKeyCode;\r
+ UsbKeyboardDevice->CurKeyCode = 0;\r
\r
//\r
- // Translate saved ASCII byte into EFI_INPUT_KEY\r
+ // Translate saved USB keycode into EFI_INPUT_KEY\r
//\r
- Status = UsbKeyCodeToEfiInputKey (UsbKeyboardDevice, KeyChar, &KeyData->Key);\r
+ Status = UsbKeyCodeToEfiInputKey (UsbKeyboardDevice, KeyCode, &KeyData->Key);\r
if (EFI_ERROR (Status)) {\r
return Status;\r
}\r
// here switch them back for notification function.\r
//\r
CopyMem (&OriginalKeyData, KeyData, sizeof (EFI_KEY_DATA));\r
- if (UsbKeyboardDevice->CtrlOn != 0) {\r
+ if (UsbKeyboardDevice->CtrlOn) {\r
if (OriginalKeyData.Key.UnicodeChar >= 0x01 && OriginalKeyData.Key.UnicodeChar <= 0x1A) {\r
- if (UsbKeyboardDevice->CapsOn != 0) {\r
+ if (UsbKeyboardDevice->CapsOn) {\r
OriginalKeyData.Key.UnicodeChar = (CHAR16)(OriginalKeyData.Key.UnicodeChar + 'A' - 1);\r
} else {\r
OriginalKeyData.Key.UnicodeChar = (CHAR16)(OriginalKeyData.Key.UnicodeChar + 'a' - 1);\r
}\r
\r
return EFI_SUCCESS;\r
- \r
}\r
\r
/**\r
- Reset USB Keyboard.\r
+ Reset the input device and optionaly run diagnostics\r
\r
There are 2 types of reset for USB keyboard.\r
For non-exhaustive reset, only keyboard buffer is cleared.\r
For exhaustive reset, in addition to clearance of keyboard buffer, the hardware status\r
is also re-initialized.\r
\r
- @param This The protocol instance of EFI_SIMPLE_TEXT_INPUT_PROTOCOL.\r
- @param ExtendedVerification Indicates if exhaustive reset is used.\r
- TRUE for exhaustive reset.\r
- FALSE for non-exhaustive reset.\r
+ @param This Protocol instance pointer.\r
+ @param ExtendedVerification Driver may perform diagnostics on reset.\r
\r
- @retval EFI_SUCCESS Keyboard is reset successfully.\r
- @retval EFI_DEVICE_ERROR Failed to reset keyboard.\r
+ @retval EFI_SUCCESS The device was reset.\r
+ @retval EFI_DEVICE_ERROR The device is not functioning properly and could not be reset.\r
\r
**/\r
EFI_STATUS\r
// Clear the key buffer of this USB keyboard\r
//\r
InitUSBKeyBuffer (&(UsbKeyboardDevice->KeyboardBuffer));\r
- UsbKeyboardDevice->CurKeyChar = 0;\r
+ UsbKeyboardDevice->CurKeyCode = 0;\r
\r
return EFI_SUCCESS;\r
}\r
// Exhaustive reset\r
//\r
Status = InitUSBKeyboard (UsbKeyboardDevice);\r
- UsbKeyboardDevice->CurKeyChar = 0;\r
+ UsbKeyboardDevice->CurKeyCode = 0;\r
if (EFI_ERROR (Status)) {\r
return EFI_DEVICE_ERROR;\r
}\r
\r
\r
/**\r
- Implements EFI_SIMPLE_TEXT_INPUT_PROTOCOL.ReadKeyStroke() function.\r
+ Reads the next keystroke from the input device.\r
\r
@param This The EFI_SIMPLE_TEXT_INPUT_PROTOCOL instance.\r
@param Key A pointer to a buffer that is filled in with the keystroke\r
information for the key that was pressed.\r
\r
- @retval EFI_SUCCESS Read key stroke successfully.\r
- @retval Other Read key stroke failed.\r
+ @retval EFI_SUCCESS The keystroke information was returned.\r
+ @retval EFI_NOT_READY There was no keystroke data availiable.\r
+ @retval EFI_DEVICE_ERROR The keydtroke information was not returned due to\r
+ hardware errors.\r
\r
**/\r
EFI_STATUS\r
CopyMem (Key, &KeyData.Key, sizeof (EFI_INPUT_KEY));\r
\r
return EFI_SUCCESS;\r
-\r
}\r
\r
\r
/**\r
- Handler function for WaitForKey event.\r
+ Event notification function registered for EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.WaitForKeyEx\r
+ and EFI_SIMPLE_TEXT_INPUT_PROTOCOL.WaitForKey.\r
\r
@param Event Event to be signaled when a key is pressed.\r
@param Context Points to USB_KB_DEV instance.\r
\r
UsbKeyboardDevice = (USB_KB_DEV *) Context;\r
\r
- if (UsbKeyboardDevice->CurKeyChar == 0) {\r
+ if (UsbKeyboardDevice->CurKeyCode == 0) {\r
if (EFI_ERROR (USBKeyboardCheckForKey (UsbKeyboardDevice))) {\r
//\r
// If no pending key, simply return.\r
\r
\r
/**\r
- Check whether there is key pending.\r
+ Check whether there is key pending in the keyboard buffer.\r
\r
@param UsbKeyboardDevice The USB_KB_DEV instance.\r
\r
EFI_STATUS\r
EFIAPI\r
USBKeyboardCheckForKey (\r
- IN USB_KB_DEV *UsbKeyboardDevice\r
+ IN OUT USB_KB_DEV *UsbKeyboardDevice\r
)\r
{\r
EFI_STATUS Status;\r
- UINT8 KeyChar;\r
+ UINT8 KeyCode;\r
\r
//\r
- // Fetch raw data from the USB keyboard input,\r
- // and translate it into ASCII data.\r
+ // Fetch raw data from the USB keyboard buffer,\r
+ // and translate it into USB keycode.\r
//\r
- Status = USBParseKey (UsbKeyboardDevice, &KeyChar);\r
+ Status = USBParseKey (UsbKeyboardDevice, &KeyCode);\r
if (EFI_ERROR (Status)) {\r
return EFI_NOT_READY;\r
}\r
\r
- UsbKeyboardDevice->CurKeyChar = KeyChar;\r
+ UsbKeyboardDevice->CurKeyCode = KeyCode;\r
return EFI_SUCCESS;\r
}\r
\r
/**\r
Free keyboard notify list.\r
\r
- @param ListHead The list head.\r
+ @param NotifyList The keyboard notify list to free.\r
\r
@retval EFI_SUCCESS Free the notify list successfully.\r
- @retval EFI_INVALID_PARAMETER ListHead is invalid.\r
+ @retval EFI_INVALID_PARAMETER NotifyList is NULL.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
KbdFreeNotifyList (\r
- IN OUT LIST_ENTRY *ListHead\r
+ IN OUT LIST_ENTRY *NotifyList\r
)\r
{\r
KEYBOARD_CONSOLE_IN_EX_NOTIFY *NotifyNode;\r
+ LIST_ENTRY *Link;\r
\r
- if (ListHead == NULL) {\r
+ if (NotifyList == NULL) {\r
return EFI_INVALID_PARAMETER;\r
}\r
- while (!IsListEmpty (ListHead)) {\r
- NotifyNode = CR (\r
- ListHead->ForwardLink, \r
- KEYBOARD_CONSOLE_IN_EX_NOTIFY, \r
- NotifyEntry, \r
- USB_KB_CONSOLE_IN_EX_NOTIFY_SIGNATURE\r
- );\r
- RemoveEntryList (ListHead->ForwardLink);\r
+ while (!IsListEmpty (NotifyList)) {\r
+ Link = GetFirstNode (NotifyList);\r
+ NotifyNode = CR (Link, KEYBOARD_CONSOLE_IN_EX_NOTIFY, NotifyEntry, USB_KB_CONSOLE_IN_EX_NOTIFY_SIGNATURE);\r
+ RemoveEntryList (Link);\r
gBS->FreePool (NotifyNode);\r
}\r
\r
}\r
\r
/**\r
- Whether the pressed key matches a registered key or not.\r
+ Check whether the pressed key matches a registered key or not.\r
\r
- @param RegsiteredData A pointer to a buffer that is filled in with the keystroke\r
- state data for the key that was registered.\r
- @param InputData A pointer to a buffer that is filled in with the keystroke\r
- state data for the key that was pressed.\r
+ @param RegsiteredData A pointer to keystroke data for the key that was registered.\r
+ @param InputData A pointer to keystroke data for the key that was pressed.\r
\r
@retval TRUE Key pressed matches a registered key.\r
- @retval FLASE Match failed.\r
+ @retval FLASE Key pressed does not matche a registered key.\r
\r
**/\r
BOOLEAN\r
} \r
\r
return TRUE;\r
-\r
}\r
\r
//\r
// Simple Text Input Ex protocol functions \r
//\r
/**\r
- The extension routine to reset the input device.\r
+ Resets the input device hardware.\r
+\r
+ The Reset() function resets the input device hardware. As part\r
+ of initialization process, the firmware/device will make a quick\r
+ but reasonable attempt to verify that the device is functioning.\r
+ If the ExtendedVerification flag is TRUE the firmware may take\r
+ an extended amount of time to verify the device is operating on\r
+ reset. Otherwise the reset operation is to occur as quickly as\r
+ possible. The hardware verification process is not defined by\r
+ this specification and is left up to the platform firmware or\r
+ driver to implement.\r
\r
- @param This Protocol instance pointer.\r
- @param ExtendedVerification Driver may perform diagnostics on reset.\r
+ @param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.\r
\r
- @retval EFI_SUCCESS The device was reset.\r
- @retval EFI_DEVICE_ERROR The device is not functioning properly and could\r
- not be reset.\r
+ @param ExtendedVerification Indicates that the driver may perform a more exhaustive\r
+ verification operation of the device during reset.\r
+\r
+ @retval EFI_SUCCESS The device was reset.\r
+ @retval EFI_DEVICE_ERROR The device is not functioning correctly and could not be reset.\r
\r
**/\r
EFI_STATUS\r
}\r
\r
/**\r
- Reads the next keystroke from the input device. The WaitForKey Event can\r
- be used to test for existance of a keystroke via WaitForEvent () call.\r
+ Reads the next keystroke from the input device.\r
\r
- @param This Protocol instance pointer.\r
- @param KeyData A pointer to a buffer that is filled in with the keystroke\r
- state data for the key that was pressed.\r
+ @param This Protocol instance pointer.\r
+ @param KeyData A pointer to a buffer that is filled in with the keystroke\r
+ state data for the key that was pressed.\r
\r
- @return EFI_SUCCESS The keystroke information was returned successfully.\r
- @retval EFI_INVALID_PARAMETER KeyData is NULL.\r
- @retval Other Read key stroke information failed.\r
+ @retval EFI_SUCCESS The keystroke information was returned.\r
+ @retval EFI_NOT_READY There was no keystroke data available.\r
+ @retval EFI_DEVICE_ERROR The keystroke information was not returned due to\r
+ hardware errors.\r
+ @retval EFI_INVALID_PARAMETER KeyData is NULL.\r
\r
**/\r
EFI_STATUS\r
@param KeyToggleState A pointer to the EFI_KEY_TOGGLE_STATE to set the\r
state for the input device.\r
\r
- @retval EFI_SUCCESS The device state was set successfully.\r
- @retval EFI_UNSUPPORTED The device does not have the ability to set its state.\r
+ @retval EFI_SUCCESS The device state was set appropriately.\r
+ @retval EFI_DEVICE_ERROR The device is not functioning correctly and could\r
+ not have the setting adjusted.\r
+ @retval EFI_UNSUPPORTED The device does not support the ability to have its state set.\r
@retval EFI_INVALID_PARAMETER KeyToggleState is NULL.\r
\r
**/\r
// Update the status light\r
//\r
\r
- UsbKeyboardDevice->ScrollOn = 0;\r
- UsbKeyboardDevice->NumLockOn = 0;\r
- UsbKeyboardDevice->CapsOn = 0;\r
+ UsbKeyboardDevice->ScrollOn = FALSE;\r
+ UsbKeyboardDevice->NumLockOn = FALSE;\r
+ UsbKeyboardDevice->CapsOn = FALSE;\r
\r
if ((*KeyToggleState & EFI_SCROLL_LOCK_ACTIVE) == EFI_SCROLL_LOCK_ACTIVE) {\r
- UsbKeyboardDevice->ScrollOn = 1;\r
+ UsbKeyboardDevice->ScrollOn = TRUE;\r
}\r
if ((*KeyToggleState & EFI_NUM_LOCK_ACTIVE) == EFI_NUM_LOCK_ACTIVE) {\r
- UsbKeyboardDevice->NumLockOn = 1;\r
+ UsbKeyboardDevice->NumLockOn = TRUE;\r
}\r
if ((*KeyToggleState & EFI_CAPS_LOCK_ACTIVE) == EFI_CAPS_LOCK_ACTIVE) {\r
- UsbKeyboardDevice->CapsOn = 1;\r
+ UsbKeyboardDevice->CapsOn = TRUE;\r
}\r
\r
SetKeyLED (UsbKeyboardDevice);\r
\r
@retval EFI_SUCCESS The notification function was registered successfully.\r
@retval EFI_OUT_OF_RESOURCES Unable to allocate resources for necesssary data structures.\r
- @retval EFI_INVALID_PARAMETER KeyData or NotifyHandle is NULL.\r
+ @retval EFI_INVALID_PARAMETER KeyData or NotifyHandle or KeyNotificationFunction is NULL.\r
\r
**/\r
EFI_STATUS\r
@param NotificationHandle The handle of the notification function being unregistered.\r
\r
@retval EFI_SUCCESS The notification function was unregistered successfully.\r
- @retval EFI_INVALID_PARAMETER The NotificationHandle is invalid or opening gSimpleTextInExNotifyGuid\r
- on NotificationHandle fails.\r
- @retval EFI_NOT_FOUND Can not find the matching entry in database.\r
+ @retval EFI_INVALID_PARAMETER The NotificationHandle is invalid\r
+ @retval EFI_NOT_FOUND Cannot find the matching entry in database.\r
\r
**/\r
EFI_STATUS\r
projects / mirror_edk2.git / blobdiff