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