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