MdeModulePkg/Bus/Usb/UsbMouseDxe/UsbMouse.c

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