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