MdeModulePkg/Bus/Usb/UsbMouseAbsolutePointerDxe/UsbMouseAbsolutePointer.h

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