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