/** @file\r
+ Helper routine and corresponding data struct used by USB Mouse Driver.\r
\r
- Helper routine and corrsponding data struct used by USB Mouse Driver.\r
-\r
-Copyright (c) 2004 - 2008, Intel Corporation\r
-All rights reserved. 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
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+Copyright (c) 2004 - 2018, Intel Corporation. All rights reserved.<BR>\r
+SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include <Library/UefiBootServicesTableLib.h>\r
#include <Library/UefiLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
-#include <Library/PcdLib.h>\r
#include <Library/UefiUsbLib.h>\r
+#include <Library/DebugLib.h>\r
\r
#include <IndustryStandard/Usb.h>\r
\r
#define BOOT_PROTOCOL 0\r
#define REPORT_PROTOCOL 1\r
\r
-#define USB_MOUSE_DEV_SIGNATURE EFI_SIGNATURE_32 ('u', 'm', 'o', 'u')\r
+#define USB_MOUSE_DEV_SIGNATURE SIGNATURE_32 ('u', 'm', 'o', 'u')\r
\r
+//\r
+// A common header for usb standard descriptor.\r
+// Each stand descriptor has a length and type.\r
+//\r
+#pragma pack(1)\r
+typedef struct {\r
+ UINT8 Len;\r
+ UINT8 Type;\r
+} USB_DESC_HEAD;\r
+#pragma pack()\r
+\r
+///\r
+/// Button range and status\r
+///\r
typedef struct {\r
BOOLEAN ButtonDetected;\r
UINT8 ButtonMinIndex;\r
UINT8 ButtonMaxIndex;\r
UINT8 Reserved;\r
-} PRIVATE_DATA;\r
+} USB_MOUSE_BUTTON_DATA;\r
\r
+///\r
+/// Device instance of USB mouse.\r
+///\r
typedef struct {\r
UINTN Signature;\r
EFI_DEVICE_PATH_PROTOCOL *DevicePath;\r
EFI_EVENT DelayedRecoveryEvent;\r
EFI_USB_IO_PROTOCOL *UsbIo;\r
- EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescriptor;\r
- EFI_USB_ENDPOINT_DESCRIPTOR *IntEndpointDescriptor;\r
+ EFI_USB_INTERFACE_DESCRIPTOR InterfaceDescriptor;\r
+ EFI_USB_ENDPOINT_DESCRIPTOR IntEndpointDescriptor;\r
UINT8 NumberOfButtons;\r
INT32 XLogicMax;\r
INT32 XLogicMin;\r
EFI_SIMPLE_POINTER_STATE State;\r
EFI_SIMPLE_POINTER_MODE Mode;\r
BOOLEAN StateChanged;\r
- PRIVATE_DATA PrivateData;\r
+ USB_MOUSE_BUTTON_DATA PrivateData;\r
EFI_UNICODE_STRING_TABLE *ControllerNameTable;\r
} USB_MOUSE_DEV;\r
\r
+///\r
+/// General HID Item structure\r
+///\r
+\r
+typedef union {\r
+ UINT8 Uint8;\r
+ UINT16 Uint16;\r
+ UINT32 Uint32;\r
+ INT8 Int8;\r
+ INT16 Int16;\r
+ INT32 Int32;\r
+ UINT8 *LongData;\r
+} HID_DATA;\r
+\r
+typedef struct {\r
+ UINT16 Format;\r
+ UINT8 Size;\r
+ UINT8 Type;\r
+ UINT8 Tag;\r
+ HID_DATA Data;\r
+} HID_ITEM;\r
+\r
#define USB_MOUSE_DEV_FROM_MOUSE_PROTOCOL(a) \\r
CR(a, USB_MOUSE_DEV, SimplePointerProtocol, USB_MOUSE_DEV_SIGNATURE)\r
\r
+//\r
+// Global Variables\r
+//\r
+extern EFI_DRIVER_BINDING_PROTOCOL gUsbMouseDriverBinding;\r
+extern EFI_COMPONENT_NAME_PROTOCOL gUsbMouseComponentName;\r
+extern EFI_COMPONENT_NAME2_PROTOCOL gUsbMouseComponentName2;\r
+\r
+//\r
+// Functions of Driver Binding Protocol\r
+//\r
\r
/**\r
- Timer handler for Delayed Recovery timer.\r
+ Check whether USB mouse driver supports this device.\r
\r
- @param Event The Delayed Recovery event.\r
- @param Context Points to the USB_KB_DEV instance.\r
+ @param This The USB mouse driver binding protocol.\r
+ @param Controller The controller handle to check.\r
+ @param RemainingDevicePath The remaining device path.\r
\r
+ @retval EFI_SUCCESS The driver supports this controller.\r
+ @retval other This device isn't supported.\r
\r
**/\r
-VOID\r
+EFI_STATUS\r
EFIAPI\r
-USBMouseRecoveryHandler (\r
- IN EFI_EVENT Event,\r
- IN VOID *Context\r
+USBMouseDriverBindingSupported (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
);\r
\r
-//\r
-// Global Variables\r
-//\r
-extern EFI_DRIVER_BINDING_PROTOCOL gUsbMouseDriverBinding;\r
-extern EFI_COMPONENT_NAME_PROTOCOL gUsbMouseComponentName;\r
-extern EFI_COMPONENT_NAME2_PROTOCOL gUsbMouseComponentName2;\r
-extern EFI_GUID gEfiUsbMouseDriverGuid;\r
+/**\r
+ Starts the mouse device with this driver.\r
\r
+ This function consumes USB I/O Protocol, initializes USB mouse device,\r
+ installs Simple Pointer Protocol, and submits Asynchronous Interrupt\r
+ Transfer to manage the USB mouse device.\r
+\r
+ @param This The USB mouse driver binding instance.\r
+ @param Controller Handle of device to bind driver to.\r
+ @param RemainingDevicePath Optional parameter use to pick a specific child\r
+ device to start.\r
+\r
+ @retval EFI_SUCCESS This driver supports this device.\r
+ @retval EFI_UNSUPPORTED This driver does not support this device.\r
+ @retval EFI_DEVICE_ERROR This driver cannot be started due to device Error.\r
+ @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
+ @retval EFI_ALREADY_STARTED This driver has been started.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+USBMouseDriverBindingStart (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+ );\r
\r
/**\r
- Report Status Code in Usb Bot Driver.\r
+ Stop the USB mouse device handled by this driver.\r
\r
- @param DevicePath Use this to get Device Path\r
- @param CodeType Status Code Type\r
- @param CodeValue Status Code Value\r
+ @param This The USB mouse 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
- @return None\r
+ @retval EFI_SUCCESS The device was stopped.\r
+ @retval EFI_UNSUPPORTED Simple Pointer Protocol is not installed on Controller.\r
+ @retval Others Fail to uninstall protocols attached on the device.\r
\r
**/\r
-VOID\r
-MouseReportStatusCode (\r
- IN EFI_DEVICE_PATH_PROTOCOL *DevicePath,\r
- IN EFI_STATUS_CODE_TYPE CodeType,\r
- IN EFI_STATUS_CODE_VALUE Value\r
+EFI_STATUS\r
+EFIAPI\r
+USBMouseDriverBindingStop (\r
+ IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
+ IN EFI_HANDLE Controller,\r
+ IN UINTN NumberOfChildren,\r
+ IN EFI_HANDLE *ChildHandleBuffer\r
);\r
\r
+//\r
+// EFI Component Name Functions\r
+//\r
+\r
/**\r
- The USB Mouse driver entry pointer.\r
+ Retrieves a Unicode string that is the user readable name of the driver.\r
+\r
+ This function retrieves the user readable name of a driver in the form of a\r
+ Unicode string. If the driver specified by This has a user readable name in\r
+ the language specified by Language, then a pointer to the driver name is\r
+ returned in DriverName, and EFI_SUCCESS is returned. If the driver specified\r
+ by This does not support the language specified by Language,\r
+ then EFI_UNSUPPORTED is returned.\r
+\r
+ @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r
+ EFI_COMPONENT_NAME_PROTOCOL instance.\r
+ @param Language A pointer to a Null-terminated ASCII string\r
+ array indicating the language. This is the\r
+ language of the driver name that the caller is\r
+ requesting, and it must match one of the\r
+ languages specified in SupportedLanguages. The\r
+ number of languages supported by a driver is up\r
+ to the driver writer. Language is specified\r
+ in RFC 4646 or ISO 639-2 language code format.\r
+ @param DriverName A pointer to the Unicode string to return.\r
+ This Unicode string is the name of the\r
+ driver specified by This in the language\r
+ specified by Language.\r
+\r
+ @retval EFI_SUCCESS The Unicode string for the Driver specified by\r
+ This and the language specified by Language was\r
+ returned in DriverName.\r
+ @retval EFI_INVALID_PARAMETER Language is NULL.\r
+ @retval EFI_INVALID_PARAMETER DriverName is NULL.\r
+ @retval EFI_UNSUPPORTED The driver specified by This does not support\r
+ the language specified by Language.\r
\r
- @param ImageHandle The driver image handle.\r
- @param SystemTable The system table.\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+UsbMouseComponentNameGetDriverName (\r
+ IN EFI_COMPONENT_NAME_PROTOCOL *This,\r
+ IN CHAR8 *Language,\r
+ OUT CHAR16 **DriverName\r
+ );\r
\r
- @return EFI_SUCCESS The component name protocol is installed.\r
- @return Others Failed to init the usb driver.\r
+/**\r
+ Retrieves a Unicode string that is the user readable name of the controller\r
+ that is being managed by a driver.\r
+\r
+ This function retrieves the user readable name of the controller specified by\r
+ ControllerHandle and ChildHandle in the form of a Unicode string. If the\r
+ driver specified by This has a user readable name in the language specified by\r
+ Language, then a pointer to the controller name is returned in ControllerName,\r
+ and EFI_SUCCESS is returned. If the driver specified by This is not currently\r
+ managing the controller specified by ControllerHandle and ChildHandle,\r
+ then EFI_UNSUPPORTED is returned. If the driver specified by This does not\r
+ support the language specified by Language, then EFI_UNSUPPORTED is returned.\r
+\r
+ @param This A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or\r
+ EFI_COMPONENT_NAME_PROTOCOL instance.\r
+ @param ControllerHandle The handle of a controller that the driver\r
+ specified by This is managing. This handle\r
+ specifies the controller whose name is to be\r
+ returned.\r
+ @param ChildHandle The handle of the child controller to retrieve\r
+ the name of. This is an optional parameter that\r
+ may be NULL. It will be NULL for device\r
+ drivers. It will also be NULL for a bus drivers\r
+ that wish to retrieve the name of the bus\r
+ controller. It will not be NULL for a bus\r
+ driver that wishes to retrieve the name of a\r
+ child controller.\r
+ @param Language A pointer to a Null-terminated ASCII string\r
+ array indicating the language. This is the\r
+ language of the driver name that the caller is\r
+ requesting, and it must match one of the\r
+ languages specified in SupportedLanguages. The\r
+ number of languages supported by a driver is up\r
+ to the driver writer. Language is specified in\r
+ RFC 4646 or ISO 639-2 language code format.\r
+ @param ControllerName A pointer to the Unicode string to return.\r
+ This Unicode string is the name of the\r
+ controller specified by ControllerHandle and\r
+ ChildHandle in the language specified by\r
+ Language from the point of view of the driver\r
+ specified by This.\r
+\r
+ @retval EFI_SUCCESS The Unicode string for the user readable name in\r
+ the language specified by Language for the\r
+ driver specified by This was returned in\r
+ DriverName.\r
+ @retval EFI_INVALID_PARAMETER ControllerHandle is NULL.\r
+ @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid\r
+ EFI_HANDLE.\r
+ @retval EFI_INVALID_PARAMETER Language is NULL.\r
+ @retval EFI_INVALID_PARAMETER ControllerName is NULL.\r
+ @retval EFI_UNSUPPORTED The driver specified by This is not currently\r
+ managing the controller specified by\r
+ ControllerHandle and ChildHandle.\r
+ @retval EFI_UNSUPPORTED The driver specified by This does not support\r
+ the language specified by Language.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
-USBMouseDriverBindingEntryPoint (\r
- IN EFI_HANDLE ImageHandle,\r
- IN EFI_SYSTEM_TABLE *SystemTable\r
+UsbMouseComponentNameGetControllerName (\r
+ IN EFI_COMPONENT_NAME_PROTOCOL *This,\r
+ IN EFI_HANDLE ControllerHandle,\r
+ IN EFI_HANDLE ChildHandle OPTIONAL,\r
+ IN CHAR8 *Language,\r
+ OUT CHAR16 **ControllerName\r
);\r
\r
+//\r
+// Functions of EFI_SIMPLE_POINTER_PROTOCOL\r
+//\r
+\r
/**\r
- Test to see if this driver supports ControllerHandle. Any ControllerHandle\r
- that has UsbIoProtocol installed will be supported.\r
+ Retrieves the current state of a pointer device.\r
\r
- @param This Protocol instance pointer.\r
- @param Controller Handle of device to test.\r
- @param RemainingDevicePath Not used.\r
+ @param This A pointer to the EFI_SIMPLE_POINTER_PROTOCOL instance.\r
+ @param MouseState A pointer to the state information on the pointer device.\r
\r
- @retval EFI_SUCCESS This driver supports this device.\r
- @retval EFI_UNSUPPORTED This driver does not support this device.\r
+ @retval EFI_SUCCESS The state of the pointer device was returned in State.\r
+ @retval EFI_NOT_READY The state of the pointer device has not changed since the last call to\r
+ GetState().\r
+ @retval EFI_DEVICE_ERROR A device error occurred while attempting to retrieve the pointer device's\r
+ current state.\r
+ @retval EFI_INVALID_PARAMETER MouseState is NULL.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
-USBMouseDriverBindingSupported (\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE Controller,\r
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+GetMouseState (\r
+ IN EFI_SIMPLE_POINTER_PROTOCOL *This,\r
+ OUT EFI_SIMPLE_POINTER_STATE *MouseState\r
);\r
\r
/**\r
- Starting the Usb Mouse Driver.\r
+ Resets the pointer device hardware.\r
\r
- @param This Protocol instance pointer.\r
- @param Controller Handle of device to test\r
- @param RemainingDevicePath Not used\r
+ @param This A pointer to the EFI_SIMPLE_POINTER_PROTOCOL instance.\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 This driver supports this device.\r
- @retval EFI_UNSUPPORTED This driver does not support this device.\r
- @retval EFI_DEVICE_ERROR This driver cannot be started due to device Error.\r
- @retval EFI_OUT_OF_RESOURCES Can't allocate memory resources.\r
- @retval EFI_ALREADY_STARTED Thios driver has been started.\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
EFIAPI\r
-USBMouseDriverBindingStart (\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE Controller,\r
- IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath\r
+UsbMouseReset (\r
+ IN EFI_SIMPLE_POINTER_PROTOCOL *This,\r
+ IN BOOLEAN ExtendedVerification\r
+ );\r
+\r
+/**\r
+ Event notification function for SIMPLE_POINTER.WaitForInput event.\r
+\r
+ @param Event Event to be signaled when there's input from mouse.\r
+ @param Context Points to USB_MOUSE_DEV instance.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+UsbMouseWaitForInput (\r
+ IN EFI_EVENT Event,\r
+ IN VOID *Context\r
+ );\r
+\r
+//\r
+// Internal worker functions\r
+//\r
+\r
+/**\r
+ Uses USB I/O to check whether the device is a USB mouse device.\r
+\r
+ @param UsbIo Pointer to a USB I/O protocol instance.\r
+\r
+ @retval TRUE Device is a USB mouse device.\r
+ @retval FALSE Device is a not USB mouse device.\r
+\r
+**/\r
+BOOLEAN\r
+IsUsbMouse (\r
+ IN EFI_USB_IO_PROTOCOL *UsbIo\r
+ );\r
+\r
+/**\r
+ Initialize the USB mouse device.\r
+\r
+ This function retrieves and parses HID report descriptor, and\r
+ initializes state of USB_MOUSE_DEV. Then it sets indefinite idle\r
+ rate for the device. Finally it creates event for delayed recovery,\r
+ which deals with device error.\r
+\r
+ @param UsbMouseDev Device instance to be initialized.\r
+\r
+ @retval EFI_SUCCESS USB mouse device successfully initialized..\r
+ @retval EFI_UNSUPPORTED HID descriptor type is not report descriptor.\r
+ @retval Other USB mouse device was not initialized successfully.\r
+\r
+**/\r
+EFI_STATUS\r
+InitializeUsbMouseDevice (\r
+ IN OUT USB_MOUSE_DEV *UsbMouseDev\r
);\r
\r
/**\r
- Stop this driver on ControllerHandle. Support stoping any child handles\r
- created by this driver.\r
+ Handler function for USB mouse's asynchronous interrupt transfer.\r
\r
- @param This Protocol instance pointer.\r
- @param Controller Handle of device to stop driver on.\r
- @param NumberOfChildren Number of Children in the ChildHandleBuffer.\r
- @param ChildHandleBuffer List of handles for the children we need to stop.\r
+ This function is the handler function for USB mouse's asynchronous interrupt transfer\r
+ to manage the mouse. It parses data returned from asynchronous interrupt transfer, and\r
+ get button and movement state.\r
\r
- @retval EFI_SUCCESS The controller or children are stopped.\r
- @retval Other Failed to stop the driver.\r
+ @param Data A pointer to a buffer that is filled with key data which is\r
+ retrieved via asynchronous interrupt transfer.\r
+ @param DataLength Indicates the size of the data buffer.\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 Asynchronous interrupt transfer is handled successfully.\r
+ @retval EFI_DEVICE_ERROR Hardware error occurs.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
-USBMouseDriverBindingStop (\r
- IN EFI_DRIVER_BINDING_PROTOCOL *This,\r
- IN EFI_HANDLE Controller,\r
- IN UINTN NumberOfChildren,\r
- IN EFI_HANDLE *ChildHandleBuffer\r
+OnMouseInterruptComplete (\r
+ IN VOID *Data,\r
+ IN UINTN DataLength,\r
+ IN VOID *Context,\r
+ IN UINT32 Result\r
+ );\r
+\r
+/**\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_MOUSE_DEV instance.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+USBMouseRecoveryHandler (\r
+ IN EFI_EVENT Event,\r
+ IN VOID *Context\r
+ );\r
+\r
+/**\r
+ Parse Mouse Report Descriptor.\r
+\r
+ According to USB HID Specification, report descriptors are\r
+ composed of pieces of information. Each piece of information\r
+ is called an Item. This function retrieves each item from\r
+ the report descriptor and updates USB_MOUSE_DEV.\r
+\r
+ @param UsbMouse The instance of USB_MOUSE_DEV\r
+ @param ReportDescriptor Report descriptor to parse\r
+ @param ReportSize Report descriptor size\r
+\r
+ @retval EFI_SUCCESS Report descriptor successfully parsed.\r
+ @retval EFI_UNSUPPORTED Report descriptor contains long item.\r
+\r
+**/\r
+EFI_STATUS\r
+ParseMouseReportDescriptor (\r
+ OUT USB_MOUSE_DEV *UsbMouse,\r
+ IN UINT8 *ReportDescriptor,\r
+ IN UINTN ReportSize\r
);\r
\r
#endif\r
projects / mirror_edk2.git / blobdiff