MdeModulePkg/Bus/Usb/UsbMouseAbsolutePointerDxe/UsbMouseAbsolutePointer.c

   1 /** @file
   2   USB Mouse Driver that manages USB mouse and produces Absolute Pointer Protocol.
   3
   4 Copyright (c) 2004 - 2010, Intel Corporation. All rights reserved.<BR>
   5 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 #include "UsbMouseAbsolutePointer.h"
  16
  17 EFI_DRIVER_BINDING_PROTOCOL gUsbMouseAbsolutePointerDriverBinding = {
  18   USBMouseAbsolutePointerDriverBindingSupported,
  19   USBMouseAbsolutePointerDriverBindingStart,
  20   USBMouseAbsolutePointerDriverBindingStop,
  21   0x1,
  22   NULL,
  23   NULL
  24 };
  25
  26 /**
  27   Entrypoint of USB Mouse Absolute Pointer Driver.
  28
  29   This function is the entrypoint of USB Mouse Driver. It installs Driver Binding
  30   Protocols together with Component Name Protocols.
  31
  32   @param  ImageHandle       The firmware allocated handle for the EFI image.
  33   @param  SystemTable       A pointer to the EFI System Table.
  34
  35   @retval EFI_SUCCESS       The entry point is executed successfully.
  36
  37 **/
  38 EFI_STATUS
  39 EFIAPI
  40 USBMouseAbsolutePointerDriverBindingEntryPoint (
  41   IN EFI_HANDLE           ImageHandle,
  42   IN EFI_SYSTEM_TABLE     *SystemTable
  43   )
  44 {
  45   EFI_STATUS              Status;
  46
  47   Status = EfiLibInstallDriverBindingComponentName2 (
  48              ImageHandle,
  49              SystemTable,
  50              &gUsbMouseAbsolutePointerDriverBinding,
  51              ImageHandle,
  52              &gUsbMouseAbsolutePointerComponentName,
  53              &gUsbMouseAbsolutePointerComponentName2
  54              );
  55   ASSERT_EFI_ERROR (Status);
  56
  57   return EFI_SUCCESS;
  58 }
  59
  60
  61 /**
  62   Check whether USB Mouse Absolute Pointer Driver supports this device.
  63
  64   @param  This                   The driver binding protocol.
  65   @param  Controller             The controller handle to check.
  66   @param  RemainingDevicePath    The remaining device path.
  67
  68   @retval EFI_SUCCESS            The driver supports this controller.
  69   @retval other                  This device isn't supported.
  70
  71 **/
  72 EFI_STATUS
  73 EFIAPI
  74 USBMouseAbsolutePointerDriverBindingSupported (
  75   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
  76   IN EFI_HANDLE                     Controller,
  77   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
  78   )
  79 {
  80   EFI_STATUS          Status;
  81   EFI_USB_IO_PROTOCOL *UsbIo;
  82
  83   Status = gBS->OpenProtocol (
  84                   Controller,
  85                   &gEfiUsbIoProtocolGuid,
  86                   (VOID **) &UsbIo,
  87                   This->DriverBindingHandle,
  88                   Controller,
  89                   EFI_OPEN_PROTOCOL_BY_DRIVER
  90                   );
  91   if (EFI_ERROR (Status)) {
  92     return Status;
  93   }
  94
  95   //
  96   // Use the USB I/O Protocol interface to check whether Controller is
  97   // a mouse device that can be managed by this driver.
  98   //
  99   Status = EFI_SUCCESS;
 100   if (!IsUsbMouse (UsbIo)) {
 101     Status = EFI_UNSUPPORTED;
 102   }
 103
 104   gBS->CloseProtocol (
 105         Controller,
 106         &gEfiUsbIoProtocolGuid,
 107         This->DriverBindingHandle,
 108         Controller
 109         );
 110
 111   return Status;
 112 }
 113
 114
 115 /**
 116   Starts the mouse device with this driver.
 117
 118   This function consumes USB I/O Portocol, intializes USB mouse device,
 119   installs Absolute Pointer Protocol, and submits Asynchronous Interrupt
 120   Transfer to manage the USB mouse device.
 121
 122   @param  This                  The driver binding instance.
 123   @param  Controller            Handle of device to bind driver to.
 124   @param  RemainingDevicePath   Optional parameter use to pick a specific child
 125                                 device to start.
 126
 127   @retval EFI_SUCCESS           This driver supports this device.
 128   @retval EFI_UNSUPPORTED       This driver does not support this device.
 129   @retval EFI_DEVICE_ERROR      This driver cannot be started due to device Error.
 130   @retval EFI_OUT_OF_RESOURCES  Can't allocate memory resources.
 131   @retval EFI_ALREADY_STARTED   This driver has been started.
 132
 133 **/
 134 EFI_STATUS
 135 EFIAPI
 136 USBMouseAbsolutePointerDriverBindingStart (
 137   IN EFI_DRIVER_BINDING_PROTOCOL    *This,
 138   IN EFI_HANDLE                     Controller,
 139   IN EFI_DEVICE_PATH_PROTOCOL       *RemainingDevicePath
 140   )
 141 {
 142   EFI_STATUS                     Status;
 143   EFI_USB_IO_PROTOCOL            *UsbIo;
 144   USB_MOUSE_ABSOLUTE_POINTER_DEV *UsbMouseAbsolutePointerDevice;
 145   UINT8                          EndpointNumber;
 146   EFI_USB_ENDPOINT_DESCRIPTOR    EndpointDescriptor;
 147   UINT8                          Index;
 148   UINT8                          EndpointAddr;
 149   UINT8                          PollingInterval;
 150   UINT8                          PacketSize;
 151   BOOLEAN                        Found;
 152
 153   //
 154   // Open USB I/O Protocol
 155   //
 156   Status = gBS->OpenProtocol (
 157                   Controller,
 158                   &gEfiUsbIoProtocolGuid,
 159                   (VOID **) &UsbIo,
 160                   This->DriverBindingHandle,
 161                   Controller,
 162                   EFI_OPEN_PROTOCOL_BY_DRIVER
 163                   );
 164   if (EFI_ERROR (Status)) {
 165     return Status;
 166   }
 167
 168   UsbMouseAbsolutePointerDevice = AllocateZeroPool (sizeof (USB_MOUSE_ABSOLUTE_POINTER_DEV));
 169   ASSERT (UsbMouseAbsolutePointerDevice != NULL);
 170
 171   UsbMouseAbsolutePointerDevice->UsbIo     = UsbIo;
 172   UsbMouseAbsolutePointerDevice->Signature = USB_MOUSE_ABSOLUTE_POINTER_DEV_SIGNATURE;
 173
 174   //
 175   // Get the Device Path Protocol on Controller's handle
 176   //
 177   Status = gBS->OpenProtocol (
 178                   Controller,
 179                   &gEfiDevicePathProtocolGuid,
 180                   (VOID **) &UsbMouseAbsolutePointerDevice->DevicePath,
 181                   This->DriverBindingHandle,
 182                   Controller,
 183                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 184                   );
 185
 186   if (EFI_ERROR (Status)) {
 187     goto ErrorExit;
 188   }
 189   //
 190   // Get interface & endpoint descriptor
 191   //
 192   UsbIo->UsbGetInterfaceDescriptor (
 193            UsbIo,
 194            &UsbMouseAbsolutePointerDevice->InterfaceDescriptor
 195            );
 196
 197   EndpointNumber = UsbMouseAbsolutePointerDevice->InterfaceDescriptor.NumEndpoints;
 198
 199   //
 200   // Traverse endpoints to find interrupt endpoint
 201   //
 202   Found = FALSE;
 203   for (Index = 0; Index < EndpointNumber; Index++) {
 204     UsbIo->UsbGetEndpointDescriptor (
 205              UsbIo,
 206              Index,
 207              &EndpointDescriptor
 208              );
 209
 210     if ((EndpointDescriptor.Attributes & (BIT0 | BIT1)) == USB_ENDPOINT_INTERRUPT) {
 211       //
 212       // We only care interrupt endpoint here
 213       //
 214       CopyMem (&UsbMouseAbsolutePointerDevice->IntEndpointDescriptor, &EndpointDescriptor, sizeof(EndpointDescriptor));
 215       Found = TRUE;
 216       break;
 217     }
 218   }
 219
 220   if (!Found) {
 221     //
 222     // No interrupt endpoint found, then return unsupported.
 223     //
 224     Status = EFI_UNSUPPORTED;
 225     goto ErrorExit;
 226   }
 227
 228   Status = InitializeUsbMouseDevice (UsbMouseAbsolutePointerDevice);
 229   if (EFI_ERROR (Status)) {
 230     //
 231     // Fail to initialize USB mouse device.
 232     //
 233     REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 234       EFI_ERROR_CODE | EFI_ERROR_MINOR,
 235       (EFI_PERIPHERAL_MOUSE | EFI_P_EC_INTERFACE_ERROR),
 236       UsbMouseAbsolutePointerDevice->DevicePath
 237       );
 238
 239     goto ErrorExit;
 240   }
 241
 242   //
 243   // Initialize and install EFI Absolute Pointer Protocol.
 244   //
 245   UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol.GetState = GetMouseAbsolutePointerState;
 246   UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol.Reset    = UsbMouseAbsolutePointerReset;
 247   UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol.Mode     = &UsbMouseAbsolutePointerDevice->Mode;
 248
 249   Status = gBS->CreateEvent (
 250                   EVT_NOTIFY_WAIT,
 251                   TPL_NOTIFY,
 252                   UsbMouseAbsolutePointerWaitForInput,
 253                   UsbMouseAbsolutePointerDevice,
 254                   &((UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol).WaitForInput)
 255                   );
 256   if (EFI_ERROR (Status)) {
 257     goto ErrorExit;
 258   }
 259
 260   Status = gBS->InstallProtocolInterface (
 261                   &Controller,
 262                   &gEfiAbsolutePointerProtocolGuid,
 263                   EFI_NATIVE_INTERFACE,
 264                   &UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol
 265                   );
 266
 267   if (EFI_ERROR (Status)) {
 268     goto ErrorExit;
 269   }
 270
 271   //
 272   // The next step would be submitting Asynchronous Interrupt Transfer on this mouse device.
 273   // After that we will be able to get key data from it. Thus this is deemed as
 274   // the enable action of the mouse, so report status code accordingly.
 275   //
 276   REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 277     EFI_PROGRESS_CODE,
 278     (EFI_PERIPHERAL_MOUSE | EFI_P_PC_ENABLE),
 279     UsbMouseAbsolutePointerDevice->DevicePath
 280     );
 281
 282   //
 283   // Submit Asynchronous Interrupt Transfer to manage this device.
 284   //
 285   EndpointAddr    = UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.EndpointAddress;
 286   PollingInterval = UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.Interval;
 287   PacketSize      = (UINT8) (UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.MaxPacketSize);
 288
 289   Status = UsbIo->UsbAsyncInterruptTransfer (
 290                     UsbIo,
 291                     EndpointAddr,
 292                     TRUE,
 293                     PollingInterval,
 294                     PacketSize,
 295                     OnMouseInterruptComplete,
 296                     UsbMouseAbsolutePointerDevice
 297                     );
 298
 299   if (EFI_ERROR (Status)) {
 300     //
 301     // If submit error, uninstall that interface
 302     //
 303     gBS->UninstallProtocolInterface (
 304            Controller,
 305            &gEfiAbsolutePointerProtocolGuid,
 306            &UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol
 307            );
 308     goto ErrorExit;
 309   }
 310
 311   UsbMouseAbsolutePointerDevice->ControllerNameTable = NULL;
 312   AddUnicodeString2 (
 313     "eng",
 314     gUsbMouseAbsolutePointerComponentName.SupportedLanguages,
 315     &UsbMouseAbsolutePointerDevice->ControllerNameTable,
 316     L"Generic Usb Mouse Absolute Pointer",
 317       TRUE
 318       );
 319   AddUnicodeString2 (
 320     "en",
 321     gUsbMouseAbsolutePointerComponentName2.SupportedLanguages,
 322     &UsbMouseAbsolutePointerDevice->ControllerNameTable,
 323     L"Generic Usb Mouse Absolute Pointer",
 324     FALSE
 325     );
 326
 327   return EFI_SUCCESS;
 328
 329 //
 330 // Error handler
 331 //
 332 ErrorExit:
 333   if (EFI_ERROR (Status)) {
 334     gBS->CloseProtocol (
 335           Controller,
 336           &gEfiUsbIoProtocolGuid,
 337           This->DriverBindingHandle,
 338           Controller
 339           );
 340
 341     if (UsbMouseAbsolutePointerDevice != NULL) {
 342       if ((UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol).WaitForInput != NULL) {
 343         gBS->CloseEvent ((UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol).WaitForInput);
 344       }
 345
 346       FreePool (UsbMouseAbsolutePointerDevice);
 347       UsbMouseAbsolutePointerDevice = NULL;
 348     }
 349   }
 350
 351   return Status;
 352 }
 353
 354
 355 /**
 356   Stop the USB mouse device handled by this driver.
 357
 358   @param  This                   The driver binding protocol.
 359   @param  Controller             The controller to release.
 360   @param  NumberOfChildren       The number of handles in ChildHandleBuffer.
 361   @param  ChildHandleBuffer      The array of child handle.
 362
 363   @retval EFI_SUCCESS            The device was stopped.
 364   @retval EFI_UNSUPPORTED        Absolute Pointer Protocol is not installed on Controller.
 365   @retval Others                 Fail to uninstall protocols attached on the device.
 366
 367 **/
 368 EFI_STATUS
 369 EFIAPI
 370 USBMouseAbsolutePointerDriverBindingStop (
 371   IN  EFI_DRIVER_BINDING_PROTOCOL   *This,
 372   IN  EFI_HANDLE                    Controller,
 373   IN  UINTN                         NumberOfChildren,
 374   IN  EFI_HANDLE                    *ChildHandleBuffer
 375   )
 376 {
 377   EFI_STATUS                      Status;
 378   USB_MOUSE_ABSOLUTE_POINTER_DEV  *UsbMouseAbsolutePointerDevice;
 379   EFI_ABSOLUTE_POINTER_PROTOCOL   *AbsolutePointerProtocol;
 380   EFI_USB_IO_PROTOCOL             *UsbIo;
 381
 382   Status = gBS->OpenProtocol (
 383                   Controller,
 384                   &gEfiAbsolutePointerProtocolGuid,
 385                   (VOID **) &AbsolutePointerProtocol,
 386                   This->DriverBindingHandle,
 387                   Controller,
 388                   EFI_OPEN_PROTOCOL_GET_PROTOCOL
 389                   );
 390
 391   if (EFI_ERROR (Status)) {
 392     return EFI_UNSUPPORTED;
 393   }
 394
 395   UsbMouseAbsolutePointerDevice = USB_MOUSE_ABSOLUTE_POINTER_DEV_FROM_MOUSE_PROTOCOL (AbsolutePointerProtocol);
 396
 397   UsbIo = UsbMouseAbsolutePointerDevice->UsbIo;
 398
 399   //
 400   // The key data input from this device will be disabled.
 401   //
 402   REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 403     EFI_PROGRESS_CODE,
 404     (EFI_PERIPHERAL_MOUSE | EFI_P_PC_DISABLE),
 405     UsbMouseAbsolutePointerDevice->DevicePath
 406     );
 407
 408   //
 409   // Delete the Asynchronous Interrupt Transfer from this device
 410   //
 411   UsbIo->UsbAsyncInterruptTransfer (
 412            UsbIo,
 413            UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.EndpointAddress,
 414            FALSE,
 415            UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.Interval,
 416            0,
 417            NULL,
 418            NULL
 419            );
 420
 421   Status = gBS->UninstallProtocolInterface (
 422                   Controller,
 423                   &gEfiAbsolutePointerProtocolGuid,
 424                   &UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol
 425                   );
 426   if (EFI_ERROR (Status)) {
 427     return Status;
 428   }
 429
 430   gBS->CloseProtocol (
 431          Controller,
 432          &gEfiUsbIoProtocolGuid,
 433          This->DriverBindingHandle,
 434          Controller
 435          );
 436
 437   //
 438   // Free all resources.
 439   //
 440   gBS->CloseEvent (UsbMouseAbsolutePointerDevice->AbsolutePointerProtocol.WaitForInput);
 441
 442   if (UsbMouseAbsolutePointerDevice->DelayedRecoveryEvent != NULL) {
 443     gBS->CloseEvent (UsbMouseAbsolutePointerDevice->DelayedRecoveryEvent);
 444     UsbMouseAbsolutePointerDevice->DelayedRecoveryEvent = NULL;
 445   }
 446
 447   if (UsbMouseAbsolutePointerDevice->ControllerNameTable != NULL) {
 448     FreeUnicodeStringTable (UsbMouseAbsolutePointerDevice->ControllerNameTable);
 449   }
 450
 451   FreePool (UsbMouseAbsolutePointerDevice);
 452
 453   return EFI_SUCCESS;
 454
 455 }
 456
 457
 458 /**
 459   Uses USB I/O to check whether the device is a USB mouse device.
 460
 461   @param  UsbIo    Pointer to a USB I/O protocol instance.
 462
 463   @retval TRUE     Device is a USB mouse device.
 464   @retval FALSE    Device is a not USB mouse device.
 465
 466 **/
 467 BOOLEAN
 468 IsUsbMouse (
 469   IN  EFI_USB_IO_PROTOCOL     *UsbIo
 470   )
 471 {
 472   EFI_STATUS                    Status;
 473   EFI_USB_INTERFACE_DESCRIPTOR  InterfaceDescriptor;
 474
 475   //
 476   // Get the default interface descriptor
 477   //
 478   Status = UsbIo->UsbGetInterfaceDescriptor (
 479                     UsbIo,
 480                     &InterfaceDescriptor
 481                     );
 482
 483   if (EFI_ERROR (Status)) {
 484     return FALSE;
 485   }
 486
 487   if ((InterfaceDescriptor.InterfaceClass == CLASS_HID) &&
 488       (InterfaceDescriptor.InterfaceSubClass == SUBCLASS_BOOT) &&
 489       (InterfaceDescriptor.InterfaceProtocol == PROTOCOL_MOUSE)
 490       ) {
 491     return TRUE;
 492   }
 493
 494   return FALSE;
 495 }
 496
 497
 498 /**
 499   Initialize the USB mouse device.
 500
 501   This function retrieves and parses HID report descriptor, and
 502   initializes state of USB_MOUSE_ABSOLUTE_POINTER_DEV. Then it sets indefinite idle
 503   rate for the device. Finally it creates event for delayed recovery,
 504   which deals with device error.
 505
 506   @param  UsbMouseAbsolutePointerDev   Device instance to be initialized.
 507
 508   @retval EFI_SUCCESS                  USB mouse device successfully initialized.
 509   @retval EFI_UNSUPPORTED              HID descriptor type is not report descriptor.
 510   @retval Other                        USB mouse device was not initialized successfully.
 511
 512 **/
 513 EFI_STATUS
 514 InitializeUsbMouseDevice (
 515   IN  USB_MOUSE_ABSOLUTE_POINTER_DEV           *UsbMouseAbsolutePointerDev
 516   )
 517 {
 518   EFI_USB_IO_PROTOCOL     *UsbIo;
 519   UINT8                   Protocol;
 520   EFI_STATUS              Status;
 521   EFI_USB_HID_DESCRIPTOR  MouseHidDesc;
 522   UINT8                   *ReportDesc;
 523   UINT8                   ReportId;
 524   UINT8                   Duration;
 525
 526   UsbIo = UsbMouseAbsolutePointerDev->UsbIo;
 527
 528   //
 529   // Get HID descriptor
 530   //
 531   Status = UsbGetHidDescriptor (
 532              UsbIo,
 533              UsbMouseAbsolutePointerDev->InterfaceDescriptor.InterfaceNumber,
 534              &MouseHidDesc
 535              );
 536   if (EFI_ERROR (Status)) {
 537     return Status;
 538   }
 539
 540   //
 541   // Get report descriptor
 542   //
 543   if (MouseHidDesc.HidClassDesc[0].DescriptorType != USB_DESC_TYPE_REPORT) {
 544     return EFI_UNSUPPORTED;
 545   }
 546
 547   ReportDesc = AllocateZeroPool (MouseHidDesc.HidClassDesc[0].DescriptorLength);
 548   ASSERT (ReportDesc != NULL);
 549
 550   Status = UsbGetReportDescriptor (
 551              UsbIo,
 552              UsbMouseAbsolutePointerDev->InterfaceDescriptor.InterfaceNumber,
 553              MouseHidDesc.HidClassDesc[0].DescriptorLength,
 554              ReportDesc
 555              );
 556
 557   if (EFI_ERROR (Status)) {
 558     FreePool (ReportDesc);
 559     return Status;
 560   }
 561
 562   //
 563   // Parse report descriptor
 564   //
 565   Status = ParseMouseReportDescriptor (
 566              UsbMouseAbsolutePointerDev,
 567              ReportDesc,
 568              MouseHidDesc.HidClassDesc[0].DescriptorLength
 569              );
 570
 571   if (EFI_ERROR (Status)) {
 572     FreePool (ReportDesc);
 573     return Status;
 574   }
 575
 576   UsbMouseAbsolutePointerDev->Mode.AbsoluteMaxX = 1024;
 577   UsbMouseAbsolutePointerDev->Mode.AbsoluteMaxY = 1024;
 578   UsbMouseAbsolutePointerDev->Mode.AbsoluteMaxZ = 0;
 579   UsbMouseAbsolutePointerDev->Mode.AbsoluteMinX = 0;
 580   UsbMouseAbsolutePointerDev->Mode.AbsoluteMinY = 0;
 581   UsbMouseAbsolutePointerDev->Mode.AbsoluteMinZ = 0;
 582   UsbMouseAbsolutePointerDev->Mode.Attributes   = 0x3;
 583
 584   //
 585   // Set boot protocol for the USB mouse.
 586   // This driver only supports boot protocol.
 587   //
 588   UsbGetProtocolRequest (
 589     UsbIo,
 590     UsbMouseAbsolutePointerDev->InterfaceDescriptor.InterfaceNumber,
 591     &Protocol
 592     );
 593   if (Protocol != BOOT_PROTOCOL) {
 594     Status = UsbSetProtocolRequest (
 595                UsbIo,
 596                0,
 597                BOOT_PROTOCOL
 598                );
 599
 600     if (EFI_ERROR (Status)) {
 601       FreePool (ReportDesc);
 602       return Status;
 603     }
 604   }
 605
 606   //
 607   // ReportId is zero, which means the idle rate applies to all input reports.
 608   //
 609   ReportId = 0;
 610   //
 611   // Duration is zero, which means the duration is infinite.
 612   // so the endpoint will inhibit reporting forever,
 613   // and only reporting when a change is detected in the report data.
 614   //
 615   Duration = 0;
 616   UsbSetIdleRequest (
 617     UsbIo,
 618     UsbMouseAbsolutePointerDev->InterfaceDescriptor.InterfaceNumber,
 619     ReportId,
 620     Duration
 621     );
 622
 623   FreePool (ReportDesc);
 624
 625   //
 626   // Create event for delayed recovery, which deals with device error.
 627   //
 628   if (UsbMouseAbsolutePointerDev->DelayedRecoveryEvent != NULL) {
 629     gBS->CloseEvent (UsbMouseAbsolutePointerDev->DelayedRecoveryEvent);
 630     UsbMouseAbsolutePointerDev->DelayedRecoveryEvent = 0;
 631   }
 632
 633   gBS->CreateEvent (
 634          EVT_TIMER | EVT_NOTIFY_SIGNAL,
 635          TPL_NOTIFY,
 636          USBMouseRecoveryHandler,
 637          UsbMouseAbsolutePointerDev,
 638          &UsbMouseAbsolutePointerDev->DelayedRecoveryEvent
 639          );
 640
 641   return EFI_SUCCESS;
 642 }
 643
 644
 645 /**
 646   Handler function for USB mouse's asynchronous interrupt transfer.
 647
 648   This function is the handler function for USB mouse's asynchronous interrupt transfer
 649   to manage the mouse. It parses data returned from asynchronous interrupt transfer, and
 650   get button and movement state.
 651
 652   @param  Data             A pointer to a buffer that is filled with key data which is
 653                            retrieved via asynchronous interrupt transfer.
 654   @param  DataLength       Indicates the size of the data buffer.
 655   @param  Context          Pointing to USB_KB_DEV instance.
 656   @param  Result           Indicates the result of the asynchronous interrupt transfer.
 657
 658   @retval EFI_SUCCESS      Asynchronous interrupt transfer is handled successfully.
 659   @retval EFI_DEVICE_ERROR Hardware error occurs.
 660
 661 **/
 662 EFI_STATUS
 663 EFIAPI
 664 OnMouseInterruptComplete (
 665   IN  VOID        *Data,
 666   IN  UINTN       DataLength,
 667   IN  VOID        *Context,
 668   IN  UINT32      Result
 669   )
 670 {
 671   USB_MOUSE_ABSOLUTE_POINTER_DEV   *UsbMouseAbsolutePointerDevice;
 672   EFI_USB_IO_PROTOCOL              *UsbIo;
 673   UINT8                            EndpointAddr;
 674   UINT32                           UsbResult;
 675
 676   UsbMouseAbsolutePointerDevice  = (USB_MOUSE_ABSOLUTE_POINTER_DEV *) Context;
 677   UsbIo                          = UsbMouseAbsolutePointerDevice->UsbIo;
 678
 679   if (Result != EFI_USB_NOERROR) {
 680     //
 681     // Some errors happen during the process
 682     //
 683     REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 684       EFI_ERROR_CODE | EFI_ERROR_MINOR,
 685       (EFI_PERIPHERAL_MOUSE | EFI_P_EC_INPUT_ERROR),
 686       UsbMouseAbsolutePointerDevice->DevicePath
 687       );
 688
 689     if ((Result & EFI_USB_ERR_STALL) == EFI_USB_ERR_STALL) {
 690       EndpointAddr = UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.EndpointAddress;
 691
 692       UsbClearEndpointHalt (
 693         UsbIo,
 694         EndpointAddr,
 695         &UsbResult
 696         );
 697     }
 698
 699     //
 700     // Delete & Submit this interrupt again
 701     // Handler of DelayedRecoveryEvent triggered by timer will re-submit the interrupt.
 702     //
 703     UsbIo->UsbAsyncInterruptTransfer (
 704              UsbIo,
 705              UsbMouseAbsolutePointerDevice->IntEndpointDescriptor.EndpointAddress,
 706              FALSE,
 707              0,
 708              0,
 709              NULL,
 710              NULL
 711              );
 712     //
 713     // EFI_USB_INTERRUPT_DELAY is defined in USB standard for error handling.
 714     //
 715     gBS->SetTimer (
 716            UsbMouseAbsolutePointerDevice->DelayedRecoveryEvent,
 717            TimerRelative,
 718            EFI_USB_INTERRUPT_DELAY
 719            );
 720     return EFI_DEVICE_ERROR;
 721   }
 722
 723   //
 724   // If no error and no data, just return EFI_SUCCESS.
 725   //
 726   if (DataLength == 0 || Data == NULL) {
 727     return EFI_SUCCESS;
 728   }
 729
 730   UsbMouseAbsolutePointerDevice->StateChanged = TRUE;
 731
 732   //
 733   // Check mouse Data
 734   // USB HID Specification specifies following data format:
 735   // Byte    Bits    Description
 736   // 0       0       Button 1
 737   //         1       Button 2
 738   //         2       Button 3
 739   //         4 to 7  Device-specific
 740   // 1       0 to 7  X displacement
 741   // 2       0 to 7  Y displacement
 742   // 3 to n  0 to 7  Device specific (optional)
 743   //
 744   UsbMouseAbsolutePointerDevice->State.CurrentX += *((INT8 *) Data + 1);
 745   UsbMouseAbsolutePointerDevice->State.CurrentY += *((INT8 *) Data + 2);
 746
 747   if (DataLength > 3) {
 748     UsbMouseAbsolutePointerDevice->State.CurrentZ += *((INT8 *) Data + 3);
 749   }
 750   UsbMouseAbsolutePointerDevice->State.ActiveButtons = *(UINT8 *) Data & (BIT0 | BIT1);
 751
 752   return EFI_SUCCESS;
 753 }
 754
 755 /**
 756   Retrieves the current state of a pointer device.
 757
 758   @param  This                  A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL instance.
 759   @param  MouseState            A pointer to the state information on the pointer device.
 760
 761   @retval EFI_SUCCESS           The state of the pointer device was returned in State.
 762   @retval EFI_NOT_READY         The state of the pointer device has not changed since the last call to
 763                                 GetState().
 764   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to retrieve the pointer device's
 765                                 current state.
 766   @retval EFI_INVALID_PARAMETER State is NULL.
 767
 768 **/
 769 EFI_STATUS
 770 EFIAPI
 771 GetMouseAbsolutePointerState (
 772   IN   EFI_ABSOLUTE_POINTER_PROTOCOL  *This,
 773   OUT  EFI_ABSOLUTE_POINTER_STATE     *State
 774   )
 775 {
 776   USB_MOUSE_ABSOLUTE_POINTER_DEV *MouseAbsolutePointerDev;
 777
 778   if (State == NULL) {
 779     return EFI_INVALID_PARAMETER;
 780   }
 781
 782   MouseAbsolutePointerDev = USB_MOUSE_ABSOLUTE_POINTER_DEV_FROM_MOUSE_PROTOCOL (This);
 783
 784   if (!MouseAbsolutePointerDev->StateChanged) {
 785     return EFI_NOT_READY;
 786   }
 787
 788   //
 789   // Retrieve mouse state from USB_MOUSE_ABSOLUTE_POINTER_DEV,
 790   // which was filled by OnMouseInterruptComplete()
 791   //
 792   CopyMem (
 793     State,
 794     &MouseAbsolutePointerDev->State,
 795     sizeof (EFI_ABSOLUTE_POINTER_STATE)
 796     );
 797
 798   //
 799   // Clear previous move state
 800   //
 801   MouseAbsolutePointerDev->State.CurrentX      = 0;
 802   MouseAbsolutePointerDev->State.CurrentY      = 0;
 803   MouseAbsolutePointerDev->State.CurrentZ      = 0;
 804   MouseAbsolutePointerDev->State.ActiveButtons = 0;
 805
 806   MouseAbsolutePointerDev->StateChanged = FALSE;
 807
 808   return EFI_SUCCESS;
 809 }
 810
 811
 812 /**
 813   Resets the pointer device hardware.
 814
 815   @param  This                  A pointer to the EFI_ABSOLUTE_POINTER_PROTOCOL instance.
 816   @param  ExtendedVerification  Indicates that the driver may perform a more exhaustive
 817                                 verification operation of the device during reset.
 818
 819   @retval EFI_SUCCESS           The device was reset.
 820   @retval EFI_DEVICE_ERROR      The device is not functioning correctly and could not be reset.
 821
 822 **/
 823 EFI_STATUS
 824 EFIAPI
 825 UsbMouseAbsolutePointerReset (
 826   IN EFI_ABSOLUTE_POINTER_PROTOCOL  *This,
 827   IN BOOLEAN                        ExtendedVerification
 828   )
 829 {
 830   USB_MOUSE_ABSOLUTE_POINTER_DEV       *UsbMouseAbsolutePointerDevice;
 831
 832   UsbMouseAbsolutePointerDevice  = USB_MOUSE_ABSOLUTE_POINTER_DEV_FROM_MOUSE_PROTOCOL (This);
 833
 834   REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 835     EFI_PROGRESS_CODE,
 836     (EFI_PERIPHERAL_MOUSE | EFI_P_PC_RESET),
 837     UsbMouseAbsolutePointerDevice->DevicePath
 838     );
 839
 840   //
 841   // Clear mouse state.
 842   //
 843   ZeroMem (
 844     &UsbMouseAbsolutePointerDevice->State,
 845     sizeof (EFI_ABSOLUTE_POINTER_STATE)
 846     );
 847   UsbMouseAbsolutePointerDevice->StateChanged = FALSE;
 848
 849   return EFI_SUCCESS;
 850 }
 851
 852 /**
 853   Event notification function for EFI_ABSOLUTE_POINTER_PROTOCOL.WaitForInput event.
 854
 855   @param  Event        Event to be signaled when there's input from mouse.
 856   @param  Context      Points to USB_MOUSE_ABSOLUTE_POINTER_DEV instance.
 857
 858 **/
 859 VOID
 860 EFIAPI
 861 UsbMouseAbsolutePointerWaitForInput (
 862   IN  EFI_EVENT               Event,
 863   IN  VOID                    *Context
 864   )
 865 {
 866   USB_MOUSE_ABSOLUTE_POINTER_DEV *UsbMouseAbsolutePointerDev;
 867
 868   UsbMouseAbsolutePointerDev = (USB_MOUSE_ABSOLUTE_POINTER_DEV *) Context;
 869
 870   //
 871   // If there's input from mouse, signal the event.
 872   //
 873   if (UsbMouseAbsolutePointerDev->StateChanged) {
 874     gBS->SignalEvent (Event);
 875   }
 876 }
 877
 878 /**
 879   Handler for Delayed Recovery event.
 880
 881   This function is the handler for Delayed Recovery event triggered
 882   by timer.
 883   After a device error occurs, the event would be triggered
 884   with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY
 885   is defined in USB standard for error handling.
 886
 887   @param  Event                 The Delayed Recovery event.
 888   @param  Context               Points to the USB_MOUSE_ABSOLUTE_POINTER_DEV instance.
 889
 890 **/
 891 VOID
 892 EFIAPI
 893 USBMouseRecoveryHandler (
 894   IN    EFI_EVENT    Event,
 895   IN    VOID         *Context
 896   )
 897 {
 898   USB_MOUSE_ABSOLUTE_POINTER_DEV       *UsbMouseAbsolutePointerDev;
 899   EFI_USB_IO_PROTOCOL                  *UsbIo;
 900
 901   UsbMouseAbsolutePointerDev = (USB_MOUSE_ABSOLUTE_POINTER_DEV *) Context;
 902
 903   UsbIo       = UsbMouseAbsolutePointerDev->UsbIo;
 904
 905   //
 906   // Re-submit Asynchronous Interrupt Transfer for recovery.
 907   //
 908   UsbIo->UsbAsyncInterruptTransfer (
 909            UsbIo,
 910            UsbMouseAbsolutePointerDev->IntEndpointDescriptor.EndpointAddress,
 911            TRUE,
 912            UsbMouseAbsolutePointerDev->IntEndpointDescriptor.Interval,
 913            UsbMouseAbsolutePointerDev->IntEndpointDescriptor.MaxPacketSize,
 914            OnMouseInterruptComplete,
 915            UsbMouseAbsolutePointerDev
 916            );
 917 }