MdeModulePkg/Bus/Usb/UsbMouseDxe/UsbMouse.h

   1 /** @file
   2   Helper routine and corresponding data struct used by USB Mouse Driver.
   3
   4 Copyright (c) 2004 - 2010, Intel Corporation
   5 All rights reserved. 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_USB_MOUSE_H_
  16 #define _EFI_USB_MOUSE_H_
  17
  18
  19 #include <Uefi.h>
  20
  21 #include <Protocol/SimplePointer.h>
  22 #include <Protocol/UsbIo.h>
  23 #include <Protocol/DevicePath.h>
  24
  25 #include <Library/ReportStatusCodeLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/UefiDriverEntryPoint.h>
  28 #include <Library/UefiBootServicesTableLib.h>
  29 #include <Library/UefiLib.h>
  30 #include <Library/MemoryAllocationLib.h>
  31 #include <Library/UefiUsbLib.h>
  32 #include <Library/DebugLib.h>
  33
  34 #include <IndustryStandard/Usb.h>
  35
  36 #define CLASS_HID               3
  37 #define SUBCLASS_BOOT           1
  38 #define PROTOCOL_MOUSE          2
  39
  40 #define BOOT_PROTOCOL           0
  41 #define REPORT_PROTOCOL         1
  42
  43 #define USB_MOUSE_DEV_SIGNATURE SIGNATURE_32 ('u', 'm', 'o', 'u')
  44
  45 ///
  46 /// Button range and status
  47 ///
  48 typedef struct {
  49   BOOLEAN ButtonDetected;
  50   UINT8   ButtonMinIndex;
  51   UINT8   ButtonMaxIndex;
  52   UINT8   Reserved;
  53 } USB_MOUSE_BUTTON_DATA;
  54
  55 ///
  56 /// Device instance of USB mouse.
  57 ///
  58 typedef struct {
  59   UINTN                         Signature;
  60   EFI_DEVICE_PATH_PROTOCOL      *DevicePath;
  61   EFI_EVENT                     DelayedRecoveryEvent;
  62   EFI_USB_IO_PROTOCOL           *UsbIo;
  63   EFI_USB_INTERFACE_DESCRIPTOR  InterfaceDescriptor;
  64   EFI_USB_ENDPOINT_DESCRIPTOR   IntEndpointDescriptor;
  65   UINT8                         NumberOfButtons;
  66   INT32                         XLogicMax;
  67   INT32                         XLogicMin;
  68   INT32                         YLogicMax;
  69   INT32                         YLogicMin;
  70   EFI_SIMPLE_POINTER_PROTOCOL   SimplePointerProtocol;
  71   EFI_SIMPLE_POINTER_STATE      State;
  72   EFI_SIMPLE_POINTER_MODE       Mode;
  73   BOOLEAN                       StateChanged;
  74   USB_MOUSE_BUTTON_DATA         PrivateData;
  75   EFI_UNICODE_STRING_TABLE      *ControllerNameTable;
  76 } USB_MOUSE_DEV;
  77
  78 ///
  79 /// General HID Item structure
  80 ///
  81
  82 typedef union {
  83   UINT8   Uint8;
  84   UINT16  Uint16;
  85   UINT32  Uint32;
  86   INT8    Int8;
  87   INT16   Int16;
  88   INT32   Int32;
  89   UINT8   *LongData;
  90 } HID_DATA;
  91
  92 typedef struct {
  93   UINT16    Format;
  94   UINT8     Size;
  95   UINT8     Type;
  96   UINT8     Tag;
  97   HID_DATA  Data;
  98 } HID_ITEM;
  99
 100 #define USB_MOUSE_DEV_FROM_MOUSE_PROTOCOL(a) \
 101     CR(a, USB_MOUSE_DEV, SimplePointerProtocol, USB_MOUSE_DEV_SIGNATURE)
 102
 103 //
 104 // Global Variables
 105 //
 106 extern EFI_DRIVER_BINDING_PROTOCOL   gUsbMouseDriverBinding;
 107 extern EFI_COMPONENT_NAME_PROTOCOL   gUsbMouseComponentName;
 108 extern EFI_COMPONENT_NAME2_PROTOCOL  gUsbMouseComponentName2;
 109
 110 //
 111 // Functions of Driver Binding Protocol
 112 //
 113
 114 /**
 115   Check whether USB mouse driver supports this device.
 116
 117   @param  This                   The USB mouse driver binding protocol.
 118   @param  Controller             The controller handle to check.
 119   @param  RemainingDevicePath    The remaining device path.
 120
 121   @retval EFI_SUCCESS            The driver supports this controller.
 122   @retval other                  This device isn't supported.
 123
 124 **/
 125 EFI_STATUS
 126 EFIAPI
 127 USBMouseDriverBindingSupported (
 128   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 129   IN EFI_HANDLE                     Controller,
 130   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 131   );
 132
 133 /**
 134   Starts the mouse device with this driver.
 135
 136   This function consumes USB I/O Portocol, intializes USB mouse device,
 137   installs Simple Pointer Protocol, and submits Asynchronous Interrupt
 138   Transfer to manage the USB mouse device.
 139
 140   @param  This                  The USB mouse driver binding instance.
 141   @param  Controller            Handle of device to bind driver to.
 142   @param  RemainingDevicePath   Optional parameter use to pick a specific child
 143                                 device to start.
 144
 145   @retval EFI_SUCCESS           This driver supports this device.
 146   @retval EFI_UNSUPPORTED       This driver does not support this device.
 147   @retval EFI_DEVICE_ERROR      This driver cannot be started due to device Error.
 148   @retval EFI_OUT_OF_RESOURCES  Can't allocate memory resources.
 149   @retval EFI_ALREADY_STARTED   This driver has been started.
 150
 151 **/
 152 EFI_STATUS
 153 EFIAPI
 154 USBMouseDriverBindingStart (
 155   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 156   IN EFI_HANDLE                     Controller,
 157   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 158   );
 159
 160 /**
 161   Stop the USB mouse device handled by this driver.
 162
 163   @param  This                   The USB mouse driver binding protocol.
 164   @param  Controller             The controller to release.
 165   @param  NumberOfChildren       The number of handles in ChildHandleBuffer.
 166   @param  ChildHandleBuffer      The array of child handle.
 167
 168   @retval EFI_SUCCESS            The device was stopped.
 169   @retval EFI_UNSUPPORTED        Simple Pointer Protocol is not installed on Controller.
 170   @retval Others                 Fail to uninstall protocols attached on the device.
 171
 172 **/
 173 EFI_STATUS
 174 EFIAPI
 175 USBMouseDriverBindingStop (
 176   IN  EFI_DRIVER_BINDING_PROTOCOL   *This,
 177   IN  EFI_HANDLE                    Controller,
 178   IN  UINTN                         NumberOfChildren,
 179   IN  EFI_HANDLE                    *ChildHandleBuffer
 180   );
 181
 182 //
 183 // EFI Component Name Functions
 184 //
 185
 186 /**
 187   Retrieves a Unicode string that is the user readable name of the driver.
 188
 189   This function retrieves the user readable name of a driver in the form of a
 190   Unicode string. If the driver specified by This has a user readable name in
 191   the language specified by Language, then a pointer to the driver name is
 192   returned in DriverName, and EFI_SUCCESS is returned. If the driver specified
 193   by This does not support the language specified by Language,
 194   then EFI_UNSUPPORTED is returned.
 195
 196   @param  This                  A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 197                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 198   @param  Language              A pointer to a Null-terminated ASCII string
 199                                 array indicating the language. This is the
 200                                 language of the driver name that the caller is
 201                                 requesting, and it must match one of the
 202                                 languages specified in SupportedLanguages. The
 203                                 number of languages supported by a driver is up
 204                                 to the driver writer. Language is specified
 205                                 in RFC 4646 or ISO 639-2 language code format.
 206   @param  DriverName            A pointer to the Unicode string to return.
 207                                 This Unicode string is the name of the
 208                                 driver specified by This in the language
 209                                 specified by Language.
 210
 211   @retval EFI_SUCCESS           The Unicode string for the Driver specified by
 212                                 This and the language specified by Language was
 213                                 returned in DriverName.
 214   @retval EFI_INVALID_PARAMETER Language is NULL.
 215   @retval EFI_INVALID_PARAMETER DriverName is NULL.
 216   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 217                                 the language specified by Language.
 218
 219 **/
 220 EFI_STATUS
 221 EFIAPI
 222 UsbMouseComponentNameGetDriverName (
 223   IN  EFI_COMPONENT_NAME_PROTOCOL  *This,
 224   IN  CHAR8                        *Language,
 225   OUT CHAR16                       **DriverName
 226   );
 227
 228 /**
 229   Retrieves a Unicode string that is the user readable name of the controller
 230   that is being managed by a driver.
 231
 232   This function retrieves the user readable name of the controller specified by
 233   ControllerHandle and ChildHandle in the form of a Unicode string. If the
 234   driver specified by This has a user readable name in the language specified by
 235   Language, then a pointer to the controller name is returned in ControllerName,
 236   and EFI_SUCCESS is returned.  If the driver specified by This is not currently
 237   managing the controller specified by ControllerHandle and ChildHandle,
 238   then EFI_UNSUPPORTED is returned.  If the driver specified by This does not
 239   support the language specified by Language, then EFI_UNSUPPORTED is returned.
 240
 241   @param  This                  A pointer to the EFI_COMPONENT_NAME2_PROTOCOL or
 242                                 EFI_COMPONENT_NAME_PROTOCOL instance.
 243   @param  ControllerHandle      The handle of a controller that the driver
 244                                 specified by This is managing.  This handle
 245                                 specifies the controller whose name is to be
 246                                 returned.
 247   @param  ChildHandle           The handle of the child controller to retrieve
 248                                 the name of.  This is an optional parameter that
 249                                 may be NULL.  It will be NULL for device
 250                                 drivers.  It will also be NULL for a bus drivers
 251                                 that wish to retrieve the name of the bus
 252                                 controller.  It will not be NULL for a bus
 253                                 driver that wishes to retrieve the name of a
 254                                 child controller.
 255   @param  Language              A pointer to a Null-terminated ASCII string
 256                                 array indicating the language.  This is the
 257                                 language of the driver name that the caller is
 258                                 requesting, and it must match one of the
 259                                 languages specified in SupportedLanguages. The
 260                                 number of languages supported by a driver is up
 261                                 to the driver writer. Language is specified in
 262                                 RFC 4646 or ISO 639-2 language code format.
 263   @param  ControllerName        A pointer to the Unicode string to return.
 264                                 This Unicode string is the name of the
 265                                 controller specified by ControllerHandle and
 266                                 ChildHandle in the language specified by
 267                                 Language from the point of view of the driver
 268                                 specified by This.
 269
 270   @retval EFI_SUCCESS           The Unicode string for the user readable name in
 271                                 the language specified by Language for the
 272                                 driver specified by This was returned in
 273                                 DriverName.
 274   @retval EFI_INVALID_PARAMETER ControllerHandle is not a valid EFI_HANDLE.
 275   @retval EFI_INVALID_PARAMETER ChildHandle is not NULL and it is not a valid
 276                                 EFI_HANDLE.
 277   @retval EFI_INVALID_PARAMETER Language is NULL.
 278   @retval EFI_INVALID_PARAMETER ControllerName is NULL.
 279   @retval EFI_UNSUPPORTED       The driver specified by This is not currently
 280                                 managing the controller specified by
 281                                 ControllerHandle and ChildHandle.
 282   @retval EFI_UNSUPPORTED       The driver specified by This does not support
 283                                 the language specified by Language.
 284
 285 **/
 286 EFI_STATUS
 287 EFIAPI
 288 UsbMouseComponentNameGetControllerName (
 289   IN  EFI_COMPONENT_NAME_PROTOCOL                     *This,
 290   IN  EFI_HANDLE                                      ControllerHandle,
 291   IN  EFI_HANDLE                                      ChildHandle        OPTIONAL,
 292   IN  CHAR8                                           *Language,
 293   OUT CHAR16                                          **ControllerName
 294   );
 295
 296 //
 297 // Functions of EFI_SIMPLE_POINTER_PROTOCOL
 298 //
 299
 300 /**
 301   Retrieves the current state of a pointer device.
 302
 303   @param  This                  A pointer to the EFI_SIMPLE_POINTER_PROTOCOL instance.
 304   @param  MouseState            A pointer to the state information on the pointer device.
 305
 306   @retval EFI_SUCCESS           The state of the pointer device was returned in State.
 307   @retval EFI_NOT_READY         The state of the pointer device has not changed since the last call to
 308                                 GetState().
 309   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to retrieve the pointer device's
 310                                 current state.
 311   @retval EFI_INVALID_PARAMETER MouseState is NULL.
 312
 313 **/
 314 EFI_STATUS
 315 EFIAPI
 316 GetMouseState (
 317   IN   EFI_SIMPLE_POINTER_PROTOCOL  *This,
 318   OUT  EFI_SIMPLE_POINTER_STATE     *MouseState
 319   );
 320
 321 /**
 322   Resets the pointer device hardware.
 323
 324   @param  This                  A pointer to the EFI_SIMPLE_POINTER_PROTOCOL instance.
 325   @param  ExtendedVerification  Indicates that the driver may perform a more exhaustive
 326                                 verification operation of the device during reset.
 327
 328   @retval EFI_SUCCESS           The device was reset.
 329   @retval EFI_DEVICE_ERROR      The device is not functioning correctly and could not be reset.
 330
 331 **/
 332 EFI_STATUS
 333 EFIAPI
 334 UsbMouseReset (
 335   IN EFI_SIMPLE_POINTER_PROTOCOL    *This,
 336   IN BOOLEAN                        ExtendedVerification
 337   );
 338
 339 /**
 340   Event notification function for SIMPLE_POINTER.WaitForInput event.
 341
 342   @param  Event        Event to be signaled when there's input from mouse.
 343   @param  Context      Points to USB_MOUSE_DEV instance.
 344
 345 **/
 346 VOID
 347 EFIAPI
 348 UsbMouseWaitForInput (
 349   IN  EFI_EVENT               Event,
 350   IN  VOID                    *Context
 351   );
 352
 353 //
 354 // Internal worker functions
 355 //
 356
 357 /**
 358   Uses USB I/O to check whether the device is a USB mouse device.
 359
 360   @param  UsbIo    Pointer to a USB I/O protocol instance.
 361
 362   @retval TRUE     Device is a USB mouse device.
 363   @retval FALSE    Device is a not USB mouse device.
 364
 365 **/
 366 BOOLEAN
 367 IsUsbMouse (
 368   IN  EFI_USB_IO_PROTOCOL     *UsbIo
 369   );
 370
 371 /**
 372   Initialize the USB mouse device.
 373
 374   This function retrieves and parses HID report descriptor, and
 375   initializes state of USB_MOUSE_DEV. Then it sets indefinite idle
 376   rate for the device. Finally it creates event for delayed recovery,
 377   which deals with device error.
 378
 379   @param  UsbMouseDev           Device instance to be initialized.
 380
 381   @retval EFI_SUCCESS           USB mouse device successfully initialized..
 382   @retval EFI_UNSUPPORTED       HID descriptor type is not report descriptor.
 383   @retval Other                 USB mouse device was not initialized successfully.
 384
 385 **/
 386 EFI_STATUS
 387 InitializeUsbMouseDevice (
 388   IN OUT USB_MOUSE_DEV           *UsbMouseDev
 389   );
 390
 391 /**
 392   Handler function for USB mouse's asynchronous interrupt transfer.
 393
 394   This function is the handler function for USB mouse's asynchronous interrupt transfer
 395   to manage the mouse. It parses data returned from asynchronous interrupt transfer, and
 396   get button and movement state.
 397
 398   @param  Data             A pointer to a buffer that is filled with key data which is
 399                            retrieved via asynchronous interrupt transfer.
 400   @param  DataLength       Indicates the size of the data buffer.
 401   @param  Context          Pointing to USB_KB_DEV instance.
 402   @param  Result           Indicates the result of the asynchronous interrupt transfer.
 403
 404   @retval EFI_SUCCESS      Asynchronous interrupt transfer is handled successfully.
 405   @retval EFI_DEVICE_ERROR Hardware error occurs.
 406
 407 **/
 408 EFI_STATUS
 409 EFIAPI
 410 OnMouseInterruptComplete (
 411   IN  VOID        *Data,
 412   IN  UINTN       DataLength,
 413   IN  VOID        *Context,
 414   IN  UINT32      Result
 415   );
 416
 417 /**
 418   Handler for Delayed Recovery event.
 419
 420   This function is the handler for Delayed Recovery event triggered
 421   by timer.
 422   After a device error occurs, the event would be triggered
 423   with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY
 424   is defined in USB standard for error handling.
 425
 426   @param  Event              The Delayed Recovery event.
 427   @param  Context            Points to the USB_MOUSE_DEV instance.
 428
 429 **/
 430 VOID
 431 EFIAPI
 432 USBMouseRecoveryHandler (
 433   IN    EFI_EVENT    Event,
 434   IN    VOID         *Context
 435   );
 436
 437 /**
 438   Parse Mouse Report Descriptor.
 439
 440   According to USB HID Specification, report descriptors are
 441   composed of pieces of information. Each piece of information
 442   is called an Item. This function retrieves each item from
 443   the report descriptor and updates USB_MOUSE_DEV.
 444
 445   @param  UsbMouse          The instance of USB_MOUSE_DEV
 446   @param  ReportDescriptor  Report descriptor to parse
 447   @param  ReportSize        Report descriptor size
 448
 449   @retval EFI_SUCCESS       Report descriptor successfully parsed.
 450   @retval EFI_UNSUPPORTED   Report descriptor contains long item.
 451
 452 **/
 453 EFI_STATUS
 454 ParseMouseReportDescriptor (
 455   OUT USB_MOUSE_DEV   *UsbMouse,
 456   IN  UINT8           *ReportDescriptor,
 457   IN  UINTN           ReportSize
 458   );
 459
 460 #endif