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 - 2010, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions of the BSD License
   7 which accompanies this distribution.  The full text of the license may be found at
   8 http://opensource.org/licenses/bsd-license.php
   9
  10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #include "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   UINT8                   ReportId;
 530   UINT8                   Duration;
 531
 532   UsbIo = UsbMouseDev->UsbIo;
 533
 534   //
 535   // Get HID descriptor
 536   //
 537   Status = UsbGetHidDescriptor (
 538              UsbIo,
 539              UsbMouseDev->InterfaceDescriptor.InterfaceNumber,
 540              &MouseHidDesc
 541              );
 542   if (EFI_ERROR (Status)) {
 543     return Status;
 544   }
 545
 546   //
 547   // Get report descriptor
 548   //
 549   if (MouseHidDesc.HidClassDesc[0].DescriptorType != USB_DESC_TYPE_REPORT) {
 550     return EFI_UNSUPPORTED;
 551   }
 552
 553   ReportDesc = AllocateZeroPool (MouseHidDesc.HidClassDesc[0].DescriptorLength);
 554   ASSERT (ReportDesc != NULL);
 555
 556   Status = UsbGetReportDescriptor (
 557              UsbIo,
 558              UsbMouseDev->InterfaceDescriptor.InterfaceNumber,
 559              MouseHidDesc.HidClassDesc[0].DescriptorLength,
 560              ReportDesc
 561              );
 562
 563   if (EFI_ERROR (Status)) {
 564     FreePool (ReportDesc);
 565     return Status;
 566   }
 567
 568   //
 569   // Parse report descriptor
 570   //
 571   Status = ParseMouseReportDescriptor (
 572              UsbMouseDev,
 573              ReportDesc,
 574              MouseHidDesc.HidClassDesc[0].DescriptorLength
 575              );
 576
 577   if (EFI_ERROR (Status)) {
 578     FreePool (ReportDesc);
 579     return Status;
 580   }
 581
 582   //
 583   // Check the presence of left and right buttons,
 584   // and initialize fields of EFI_SIMPLE_POINTER_MODE.
 585   //
 586   if (UsbMouseDev->NumberOfButtons >= 1) {
 587     UsbMouseDev->Mode.LeftButton = TRUE;
 588   }
 589   if (UsbMouseDev->NumberOfButtons > 1) {
 590     UsbMouseDev->Mode.RightButton = TRUE;
 591   }
 592   UsbMouseDev->Mode.ResolutionX = 8;
 593   UsbMouseDev->Mode.ResolutionY = 8;
 594   UsbMouseDev->Mode.ResolutionZ = 0;
 595
 596   //
 597   // Set boot protocol for the USB mouse.
 598   // This driver only supports boot protocol.
 599   //
 600   UsbGetProtocolRequest (
 601     UsbIo,
 602     UsbMouseDev->InterfaceDescriptor.InterfaceNumber,
 603     &Protocol
 604     );
 605   if (Protocol != BOOT_PROTOCOL) {
 606     Status = UsbSetProtocolRequest (
 607                UsbIo,
 608                0,
 609                BOOT_PROTOCOL
 610                );
 611
 612     if (EFI_ERROR (Status)) {
 613       FreePool (ReportDesc);
 614       return Status;
 615     }
 616   }
 617
 618   //
 619   // ReportId is zero, which means the idle rate applies to all input reports.
 620   //
 621   ReportId = 0;
 622   //
 623   // Duration is zero, which means the duration is infinite.
 624   // so the endpoint will inhibit reporting forever,
 625   // and only reporting when a change is detected in the report data.
 626   //
 627   Duration = 0;
 628   UsbSetIdleRequest (
 629     UsbIo,
 630     UsbMouseDev->InterfaceDescriptor.InterfaceNumber,
 631     ReportId,
 632     Duration
 633     );
 634
 635   FreePool (ReportDesc);
 636
 637   //
 638   // Create event for delayed recovery, which deals with device error.
 639   //
 640   if (UsbMouseDev->DelayedRecoveryEvent != NULL) {
 641     gBS->CloseEvent (UsbMouseDev->DelayedRecoveryEvent);
 642     UsbMouseDev->DelayedRecoveryEvent = 0;
 643   }
 644
 645   gBS->CreateEvent (
 646          EVT_TIMER | EVT_NOTIFY_SIGNAL,
 647          TPL_NOTIFY,
 648          USBMouseRecoveryHandler,
 649          UsbMouseDev,
 650          &UsbMouseDev->DelayedRecoveryEvent
 651          );
 652
 653   return EFI_SUCCESS;
 654 }
 655
 656
 657 /**
 658   Handler function for USB mouse's asynchronous interrupt transfer.
 659
 660   This function is the handler function for USB mouse's asynchronous interrupt transfer
 661   to manage the mouse. It parses data returned from asynchronous interrupt transfer, and
 662   get button and movement state.
 663
 664   @param  Data             A pointer to a buffer that is filled with key data which is
 665                            retrieved via asynchronous interrupt transfer.
 666   @param  DataLength       Indicates the size of the data buffer.
 667   @param  Context          Pointing to USB_KB_DEV instance.
 668   @param  Result           Indicates the result of the asynchronous interrupt transfer.
 669
 670   @retval EFI_SUCCESS      Asynchronous interrupt transfer is handled successfully.
 671   @retval EFI_DEVICE_ERROR Hardware error occurs.
 672
 673 **/
 674 EFI_STATUS
 675 EFIAPI
 676 OnMouseInterruptComplete (
 677   IN  VOID        *Data,
 678   IN  UINTN       DataLength,
 679   IN  VOID        *Context,
 680   IN  UINT32      Result
 681   )
 682 {
 683   USB_MOUSE_DEV       *UsbMouseDevice;
 684   EFI_USB_IO_PROTOCOL *UsbIo;
 685   UINT8               EndpointAddr;
 686   UINT32              UsbResult;
 687
 688   UsbMouseDevice  = (USB_MOUSE_DEV *) Context;
 689   UsbIo           = UsbMouseDevice->UsbIo;
 690
 691   if (Result != EFI_USB_NOERROR) {
 692     //
 693     // Some errors happen during the process
 694     //
 695     REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 696       EFI_ERROR_CODE | EFI_ERROR_MINOR,
 697       (EFI_PERIPHERAL_MOUSE | EFI_P_EC_INPUT_ERROR),
 698       UsbMouseDevice->DevicePath
 699       );
 700
 701     if ((Result & EFI_USB_ERR_STALL) == EFI_USB_ERR_STALL) {
 702       EndpointAddr = UsbMouseDevice->IntEndpointDescriptor.EndpointAddress;
 703
 704       UsbClearEndpointHalt (
 705         UsbIo,
 706         EndpointAddr,
 707         &UsbResult
 708         );
 709     }
 710
 711     //
 712     // Delete & Submit this interrupt again
 713     // Handler of DelayedRecoveryEvent triggered by timer will re-submit the interrupt.
 714     //
 715     UsbIo->UsbAsyncInterruptTransfer (
 716              UsbIo,
 717              UsbMouseDevice->IntEndpointDescriptor.EndpointAddress,
 718              FALSE,
 719              0,
 720              0,
 721              NULL,
 722              NULL
 723              );
 724     //
 725     // EFI_USB_INTERRUPT_DELAY is defined in USB standard for error handling.
 726     //
 727     gBS->SetTimer (
 728            UsbMouseDevice->DelayedRecoveryEvent,
 729            TimerRelative,
 730            EFI_USB_INTERRUPT_DELAY
 731            );
 732     return EFI_DEVICE_ERROR;
 733   }
 734
 735   //
 736   // If no error and no data, just return EFI_SUCCESS.
 737   //
 738   if (DataLength == 0 || Data == NULL) {
 739     return EFI_SUCCESS;
 740   }
 741
 742   UsbMouseDevice->StateChanged = TRUE;
 743
 744   //
 745   // Check mouse Data
 746   // USB HID Specification specifies following data format:
 747   // Byte    Bits    Description
 748   // 0       0       Button 1
 749   //         1       Button 2
 750   //         2       Button 3
 751   //         4 to 7  Device-specific
 752   // 1       0 to 7  X displacement
 753   // 2       0 to 7  Y displacement
 754   // 3 to n  0 to 7  Device specific (optional)
 755   //
 756   UsbMouseDevice->State.LeftButton  = (BOOLEAN) ((*(UINT8 *) Data & BIT0) != 0);
 757   UsbMouseDevice->State.RightButton = (BOOLEAN) ((*(UINT8 *) Data & BIT1) != 0);
 758   UsbMouseDevice->State.RelativeMovementX += *((INT8 *) Data + 1);
 759   UsbMouseDevice->State.RelativeMovementY += *((INT8 *) Data + 2);
 760
 761   if (DataLength > 3) {
 762     UsbMouseDevice->State.RelativeMovementZ += *((INT8 *) Data + 3);
 763   }
 764
 765   return EFI_SUCCESS;
 766 }
 767
 768 /**
 769   Retrieves the current state of a pointer device.
 770
 771   @param  This                  A pointer to the EFI_SIMPLE_POINTER_PROTOCOL instance.
 772   @param  MouseState            A pointer to the state information on the pointer device.
 773
 774   @retval EFI_SUCCESS           The state of the pointer device was returned in State.
 775   @retval EFI_NOT_READY         The state of the pointer device has not changed since the last call to
 776                                 GetState().
 777   @retval EFI_DEVICE_ERROR      A device error occurred while attempting to retrieve the pointer device's
 778                                 current state.
 779   @retval EFI_INVALID_PARAMETER MouseState is NULL.
 780
 781 **/
 782 EFI_STATUS
 783 EFIAPI
 784 GetMouseState (
 785   IN   EFI_SIMPLE_POINTER_PROTOCOL  *This,
 786   OUT  EFI_SIMPLE_POINTER_STATE     *MouseState
 787   )
 788 {
 789   USB_MOUSE_DEV *MouseDev;
 790
 791   if (MouseState == NULL) {
 792     return EFI_INVALID_PARAMETER;
 793   }
 794
 795   MouseDev = USB_MOUSE_DEV_FROM_MOUSE_PROTOCOL (This);
 796
 797   if (!MouseDev->StateChanged) {
 798     return EFI_NOT_READY;
 799   }
 800
 801   //
 802   // Retrieve mouse state from USB_MOUSE_DEV, which was filled by OnMouseInterruptComplete()
 803   //
 804   CopyMem (
 805     MouseState,
 806     &MouseDev->State,
 807     sizeof (EFI_SIMPLE_POINTER_STATE)
 808     );
 809
 810   //
 811   // Clear previous move state
 812   //
 813   MouseDev->State.RelativeMovementX = 0;
 814   MouseDev->State.RelativeMovementY = 0;
 815   MouseDev->State.RelativeMovementZ = 0;
 816
 817   MouseDev->StateChanged            = FALSE;
 818
 819   return EFI_SUCCESS;
 820 }
 821
 822
 823 /**
 824   Resets the pointer device hardware.
 825
 826   @param  This                  A pointer to the EFI_SIMPLE_POINTER_PROTOCOL instance.
 827   @param  ExtendedVerification  Indicates that the driver may perform a more exhaustive
 828                                 verification operation of the device during reset.
 829
 830   @retval EFI_SUCCESS           The device was reset.
 831   @retval EFI_DEVICE_ERROR      The device is not functioning correctly and could not be reset.
 832
 833 **/
 834 EFI_STATUS
 835 EFIAPI
 836 UsbMouseReset (
 837   IN EFI_SIMPLE_POINTER_PROTOCOL    *This,
 838   IN BOOLEAN                        ExtendedVerification
 839   )
 840 {
 841   USB_MOUSE_DEV       *UsbMouseDevice;
 842
 843   UsbMouseDevice  = USB_MOUSE_DEV_FROM_MOUSE_PROTOCOL (This);
 844
 845   REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 846     EFI_PROGRESS_CODE,
 847     (EFI_PERIPHERAL_MOUSE | EFI_P_PC_RESET),
 848     UsbMouseDevice->DevicePath
 849     );
 850
 851   //
 852   // Clear mouse state.
 853   //
 854   ZeroMem (
 855     &UsbMouseDevice->State,
 856     sizeof (EFI_SIMPLE_POINTER_STATE)
 857     );
 858   UsbMouseDevice->StateChanged = FALSE;
 859
 860   return EFI_SUCCESS;
 861 }
 862
 863 /**
 864   Event notification function for EFI_SIMPLE_POINTER_PROTOCOL.WaitForInput event.
 865
 866   @param  Event        Event to be signaled when there's input from mouse.
 867   @param  Context      Points to USB_MOUSE_DEV instance.
 868
 869 **/
 870 VOID
 871 EFIAPI
 872 UsbMouseWaitForInput (
 873   IN  EFI_EVENT               Event,
 874   IN  VOID                    *Context
 875   )
 876 {
 877   USB_MOUSE_DEV *UsbMouseDev;
 878
 879   UsbMouseDev = (USB_MOUSE_DEV *) Context;
 880
 881   //
 882   // If there's input from mouse, signal the event.
 883   //
 884   if (UsbMouseDev->StateChanged) {
 885     gBS->SignalEvent (Event);
 886   }
 887 }
 888
 889 /**
 890   Handler for Delayed Recovery event.
 891
 892   This function is the handler for Delayed Recovery event triggered
 893   by timer.
 894   After a device error occurs, the event would be triggered
 895   with interval of EFI_USB_INTERRUPT_DELAY. EFI_USB_INTERRUPT_DELAY
 896   is defined in USB standard for error handling.
 897
 898   @param  Event              The Delayed Recovery event.
 899   @param  Context            Points to the USB_MOUSE_DEV instance.
 900
 901 **/
 902 VOID
 903 EFIAPI
 904 USBMouseRecoveryHandler (
 905   IN    EFI_EVENT    Event,
 906   IN    VOID         *Context
 907   )
 908 {
 909   USB_MOUSE_DEV       *UsbMouseDev;
 910   EFI_USB_IO_PROTOCOL *UsbIo;
 911
 912   UsbMouseDev = (USB_MOUSE_DEV *) Context;
 913
 914   UsbIo       = UsbMouseDev->UsbIo;
 915
 916   //
 917   // Re-submit Asynchronous Interrupt Transfer for recovery.
 918   //
 919   UsbIo->UsbAsyncInterruptTransfer (
 920            UsbIo,
 921            UsbMouseDev->IntEndpointDescriptor.EndpointAddress,
 922            TRUE,
 923            UsbMouseDev->IntEndpointDescriptor.Interval,
 924            UsbMouseDev->IntEndpointDescriptor.MaxPacketSize,
 925            OnMouseInterruptComplete,
 926            UsbMouseDev
 927            );
 928 }