/** @file
USB Keyboard Driver that manages USB keyboard and produces Simple Text Input
Protocol and Simple Text Input Ex Protocol.
Copyright (c) 2004 - 2011, Intel Corporation. All rights reserved.<BR>
This program and the accompanying materials
are licensed and made available under the terms and conditions of the BSD License
which accompanies this distribution. The full text of the license may be found at
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#include "EfiKey.h"
#include "KeyBoard.h"
//
// USB Keyboard Driver Global Variables
//
0xa,
NULL,
};
/**
Entrypoint of USB Keyboard Driver.
This function is the entrypoint of USB Keyboard Driver. It installs Driver Binding
Protocols together with Component Name Protocols.
@param ImageHandle The firmware allocated handle for the EFI image.
@param SystemTable A pointer to the EFI System Table.
@retval EFI_SUCCESS The entry point is executed successfully.
**/
)
{
);
return EFI_SUCCESS;
}
/**
Check whether USB keyboard driver supports this device.
@param This The USB keyboard driver binding protocol.
@param Controller The controller handle to check.
@param RemainingDevicePath The remaining device path.
@retval EFI_SUCCESS The driver supports this controller.
@retval other This device isn't supported.
**/
)
{
//
// Check if USB I/O Protocol is attached on the controller handle.
//
);
return Status;
}
//
// Use the USB I/O Protocol interface to check whether Controller is
// a keyboard device that can be managed by this driver.
//
if (!IsUSBKeyboard (UsbIo)) {
}
gBS->CloseProtocol (
);
return Status;
}
/**
Starts the keyboard device with this driver.
This function produces Simple Text Input Protocol and Simple Text Input Ex Protocol,
initializes the keyboard device, and submit Asynchronous Interrupt Transfer to manage
this keyboard device.
@param This The USB keyboard driver binding instance.
@param Controller Handle of device to bind driver to.
@param RemainingDevicePath Optional parameter use to pick a specific child
device to start.
@retval EFI_SUCCESS The controller is controlled by the usb keyboard driver.
@retval EFI_UNSUPPORTED No interrupt endpoint can be found.
@retval Other This controller cannot be started.
**/
)
{
//
// Open USB I/O Protocol
//
);
goto ErrorExit1;
}
//
// Get the Device Path Protocol on Controller's handle
//
);
goto ErrorExit;
}
//
// Report that the USB keyboard is being enabled
//
);
//
// This is pretty close to keyboard detection, so log progress
//
);
//
// Get interface & endpoint descriptor
//
);
//
// Traverse endpoints to find interrupt endpoint
//
);
//
// We only care interrupt endpoint here
//
CopyMem(&UsbKeyboardDevice->IntEndpointDescriptor, &EndpointDescriptor, sizeof(EndpointDescriptor));
break;
}
}
if (!Found) {
//
// No interrupt endpoint found, then return unsupported.
//
goto ErrorExit;
}
);
}
goto ErrorExit;
}
);
goto ErrorExit;
}
);
goto ErrorExit;
}
//
// Install Simple Text Input Protocol and Simple Text Input Ex Protocol
// for the USB keyboard device.
// USB keyboard is a hot plug device, and expected to work immediately
// when plugging into system, other conventional console devices could
// distinguish it by its device path.
//
);
goto ErrorExit;
}
);
goto ErrorExit;
}
//
// Reset USB Keyboard Device exhaustively.
//
);
);
goto ErrorExit;
}
//
// Submit Asynchronous Interrupt Transfer to manage this device.
//
TRUE,
);
);
goto ErrorExit;
}
"eng",
L"Generic Usb Keyboard",
);
"en",
L"Generic Usb Keyboard",
);
return EFI_SUCCESS;
//
// Error handler
//
if (UsbKeyboardDevice != NULL) {
}
}
}
}
}
gBS->CloseProtocol (
);
return Status;
}
/**
Stop the USB keyboard device handled by this driver.
@param This The USB keyboard driver binding protocol.
@param Controller The controller to release.
@param NumberOfChildren The number of handles in ChildHandleBuffer.
@param ChildHandleBuffer The array of child handle.
@retval EFI_SUCCESS The device was stopped.
@retval EFI_UNSUPPORTED Simple Text In Protocol or Simple Text In Ex Protocol
is not installed on Controller.
@retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
@retval Others Fail to uninstall protocols attached on the device.
**/
)
{
(VOID **) &SimpleInput,
);
return EFI_UNSUPPORTED;
}
NULL,
);
return EFI_UNSUPPORTED;
}
//
// The key data input from this device will be disabled.
//
);
//
// Delete the Asynchronous Interrupt Transfer from this device
//
0,
NULL,
);
gBS->CloseProtocol (
);
);
//
// Free all resources.
//
}
return Status;
}
/**
Internal function to read the next keystroke from the keyboard buffer.
@param UsbKeyboardDevice USB keyboard's private structure.
@param KeyData A pointer to buffer to hold the keystroke
data for the key that was pressed.
@retval EFI_SUCCESS The keystroke information was returned.
@retval EFI_NOT_READY There was no keystroke data availiable.
@retval EFI_DEVICE_ERROR The keystroke information was not returned due to
hardware errors.
@retval EFI_INVALID_PARAMETER KeyData is NULL.
@retval Others Fail to translate keycode into EFI_INPUT_KEY
**/
)
{
return EFI_INVALID_PARAMETER;
}
return EFI_NOT_READY;
}
return EFI_SUCCESS;
}
/**
Reset the input device and optionally run diagnostics
There are 2 types of reset for USB keyboard.
For non-exhaustive reset, only keyboard buffer is cleared.
For exhaustive reset, in addition to clearance of keyboard buffer, the hardware status
is also re-initialized.
@param This Protocol instance pointer.
@param ExtendedVerification Driver may perform diagnostics on reset.
@retval EFI_SUCCESS The device was reset.
@retval EFI_DEVICE_ERROR The device is not functioning properly and could not be reset.
**/
)
{
);
//
// Non-exhaustive reset:
// only reset private data structures.
//
if (!ExtendedVerification) {
);
//
// Clear the key buffer of this USB keyboard
//
return EFI_SUCCESS;
}
//
// Exhaustive reset
//
return EFI_DEVICE_ERROR;
}
return EFI_SUCCESS;
}
/**
Reads the next keystroke from the input device.
@param This The EFI_SIMPLE_TEXT_INPUT_PROTOCOL instance.
@param Key A pointer to a buffer that is filled in with the keystroke
information for the key that was pressed.
@retval EFI_SUCCESS The keystroke information was returned.
@retval EFI_NOT_READY There was no keystroke data availiable.
@retval EFI_DEVICE_ERROR The keystroke information was not returned due to
hardware errors.
**/
)
{
//
// Considering if the partial keystroke is enabled, there maybe a partial
// keystroke in the queue, so here skip the partial keystroke and get the
// next key from the queue
//
while (1) {
return Status;
}
//
// SimpleTextIn Protocol doesn't support partial keystroke;
//
continue;
}
//
// Translate the CTRL-Alpha characters to their corresponding control value
// (ctrl-a = 0x0001 through ctrl-Z = 0x001A)
//
if ((KeyData.KeyState.KeyShiftState & (EFI_LEFT_CONTROL_PRESSED | EFI_RIGHT_CONTROL_PRESSED)) != 0) {
}
}
return EFI_SUCCESS;
}
}
/**
Event notification function registered for EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL.WaitForKeyEx
and EFI_SIMPLE_TEXT_INPUT_PROTOCOL.WaitForKey.
@param Event Event to be signaled when a key is pressed.
@param Context Points to USB_KB_DEV instance.
**/
)
{
//
// Enter critical section
//
//
// WaitforKey doesn't suppor the partial key.
// Considering if the partial keystroke is enabled, there maybe a partial
// keystroke in the queue, so here skip the partial keystroke and get the
// next key from the queue
//
//
// If there is pending key, signal the event.
//
CopyMem (
&KeyData,
sizeof (EFI_KEY_DATA)
);
continue;
}
break;
}
//
// Leave critical section and return
//
}
/**
Timer handler to convert the key from USB.
@param Event Indicates the event that invoke this function.
@param Context Indicates the calling context.
**/
)
{
//
// Fetch raw data from the USB keyboard buffer,
// and translate it into USB keycode.
//
return ;
}
//
// Translate saved USB keycode into EFI_INPUT_KEY
//
return ;
}
//
// Insert to the EFI Key queue
//
}
/**
Free keyboard notify list.
@param NotifyList The keyboard notify list to free.
@retval EFI_SUCCESS Free the notify list successfully.
@retval EFI_INVALID_PARAMETER NotifyList is NULL.
**/
)
{
if (NotifyList == NULL) {
return EFI_INVALID_PARAMETER;
}
while (!IsListEmpty (NotifyList)) {
NotifyNode = CR (Link, KEYBOARD_CONSOLE_IN_EX_NOTIFY, NotifyEntry, USB_KB_CONSOLE_IN_EX_NOTIFY_SIGNATURE);
}
return EFI_SUCCESS;
}
/**
Check whether the pressed key matches a registered key or not.
@param RegsiteredData A pointer to keystroke data for the key that was registered.
@param InputData A pointer to keystroke data for the key that was pressed.
@retval TRUE Key pressed matches a registered key.
@retval FLASE Key pressed does not matches a registered key.
**/
)
{
return FALSE;
}
//
// Assume KeyShiftState/KeyToggleState = 0 in Registered key data means these state could be ignored.
//
return FALSE;
}
return FALSE;
}
return TRUE;
}
//
// Simple Text Input Ex protocol functions
//
/**
Resets the input device hardware.
The Reset() function resets the input device hardware. As part
but reasonable attempt to verify that the device is functioning.
If the ExtendedVerification flag is TRUE the firmware may take
an extended amount of time to verify the device is operating on
reset. Otherwise the reset operation is to occur as quickly as
possible. The hardware verification process is not defined by
this specification and is left up to the platform firmware or
driver to implement.
@param This A pointer to the EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL instance.
@param ExtendedVerification Indicates that the driver may perform a more exhaustive
verification operation of the device during reset.
@retval EFI_SUCCESS The device was reset.
@retval EFI_DEVICE_ERROR The device is not functioning correctly and could not be reset.
**/
)
{
Status = UsbKeyboardDevice->SimpleInput.Reset (&UsbKeyboardDevice->SimpleInput, ExtendedVerification);
return EFI_DEVICE_ERROR;
}
return EFI_SUCCESS;
}
/**
Reads the next keystroke from the input device.
@param This Protocol instance pointer.
@param KeyData A pointer to a buffer that is filled in with the keystroke
state data for the key that was pressed.
@retval EFI_SUCCESS The keystroke information was returned.
@retval EFI_NOT_READY There was no keystroke data available.
@retval EFI_DEVICE_ERROR The keystroke information was not returned due to
hardware errors.
@retval EFI_INVALID_PARAMETER KeyData is NULL.
**/
)
{
return EFI_INVALID_PARAMETER;
}
}
/**
Set certain state for the input device.
@param This Protocol instance pointer.
@param KeyToggleState A pointer to the EFI_KEY_TOGGLE_STATE to set the
state for the input device.
@retval EFI_SUCCESS The device state was set appropriately.
@retval EFI_DEVICE_ERROR The device is not functioning correctly and could
not have the setting adjusted.
@retval EFI_UNSUPPORTED The device does not support the ability to have its state set.
@retval EFI_INVALID_PARAMETER KeyToggleState is NULL.
**/
)
{
if (KeyToggleState == NULL) {
return EFI_INVALID_PARAMETER;
}
if (((UsbKeyboardDevice->KeyState.KeyToggleState & EFI_TOGGLE_STATE_VALID) != EFI_TOGGLE_STATE_VALID) ||
return EFI_UNSUPPORTED;
}
//
// Update the status light
//
}
}
}
}
return EFI_SUCCESS;
}
/**
Register a notification function for a particular keystroke for the input device.
@param This Protocol instance pointer.
@param KeyData A pointer to a buffer that is filled in with the keystroke
information data for the key that was pressed.
@param KeyNotificationFunction Points to the function to be called when the key
sequence is typed specified by KeyData.
@param NotifyHandle Points to the unique handle assigned to the registered notification.
@retval EFI_SUCCESS The notification function was registered successfully.
@retval EFI_OUT_OF_RESOURCES Unable to allocate resources for necessary data structures.
@retval EFI_INVALID_PARAMETER KeyData or NotifyHandle or KeyNotificationFunction is NULL.
**/
)
{
return EFI_INVALID_PARAMETER;
}
//
// Return EFI_SUCCESS if the (KeyData, NotificationFunction) is already registered.
//
CurrentNotify = CR (
Link,
);
return EFI_SUCCESS;
}
}
}
//
// Allocate resource to save the notification function
//
NewNotify = (KEYBOARD_CONSOLE_IN_EX_NOTIFY *) AllocateZeroPool (sizeof (KEYBOARD_CONSOLE_IN_EX_NOTIFY));
return EFI_OUT_OF_RESOURCES;
}
return EFI_SUCCESS;
}
/**
Remove a registered notification function from a particular keystroke.
@param This Protocol instance pointer.
@param NotificationHandle The handle of the notification function being unregistered.
@retval EFI_SUCCESS The notification function was unregistered successfully.
@retval EFI_INVALID_PARAMETER The NotificationHandle is invalid
**/
)
{
if (NotificationHandle == NULL) {
return EFI_INVALID_PARAMETER;
}
if (((KEYBOARD_CONSOLE_IN_EX_NOTIFY *) NotificationHandle)->Signature != USB_KB_CONSOLE_IN_EX_NOTIFY_SIGNATURE) {
return EFI_INVALID_PARAMETER;
}
//
// Traverse notify list of USB keyboard and remove the entry of NotificationHandle.
//
CurrentNotify = CR (
Link,
);
//
// Remove the notification function from NotifyList and free resources
//
return EFI_SUCCESS;
}
}
//
// Cannot find the matching entry in database.
//
return EFI_INVALID_PARAMETER;
}