MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c

   1 /** @file
   2
   3     Usb bus enumeration support.
   4
   5 Copyright (c) 2007 - 2013, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #include "UsbBus.h"
  17
  18 /**
  19   Return the endpoint descriptor in this interface.
  20
  21   @param  UsbIf                 The interface to search in.
  22   @param  EpAddr                The address of the endpoint to return.
  23
  24   @return The endpoint descriptor or NULL.
  25
  26 **/
  27 USB_ENDPOINT_DESC *
  28 UsbGetEndpointDesc (
  29   IN USB_INTERFACE        *UsbIf,
  30   IN UINT8                EpAddr
  31   )
  32 {
  33   USB_ENDPOINT_DESC       *EpDesc;
  34   UINT8                   Index;
  35   UINT8                   NumEndpoints;
  36
  37   NumEndpoints = UsbIf->IfSetting->Desc.NumEndpoints;
  38
  39   for (Index = 0; Index < NumEndpoints; Index++) {
  40     EpDesc = UsbIf->IfSetting->Endpoints[Index];
  41
  42     if (EpDesc->Desc.EndpointAddress == EpAddr) {
  43       return EpDesc;
  44     }
  45   }
  46
  47   return NULL;
  48 }
  49
  50
  51 /**
  52   Free the resource used by USB interface.
  53
  54   @param  UsbIf                 The USB interface to free.
  55
  56 **/
  57 VOID
  58 UsbFreeInterface (
  59   IN USB_INTERFACE        *UsbIf
  60   )
  61 {
  62   UsbCloseHostProtoByChild (UsbIf->Device->Bus, UsbIf->Handle);
  63
  64   gBS->UninstallMultipleProtocolInterfaces (
  65          UsbIf->Handle,
  66          &gEfiDevicePathProtocolGuid,
  67          UsbIf->DevicePath,
  68          &gEfiUsbIoProtocolGuid,
  69          &UsbIf->UsbIo,
  70          NULL
  71          );
  72
  73   if (UsbIf->DevicePath != NULL) {
  74     FreePool (UsbIf->DevicePath);
  75   }
  76
  77   FreePool (UsbIf);
  78 }
  79
  80
  81 /**
  82   Create an interface for the descriptor IfDesc. Each
  83   device's configuration can have several interfaces.
  84
  85   @param  Device                The device has the interface descriptor.
  86   @param  IfDesc                The interface descriptor.
  87
  88   @return The created USB interface for the descriptor, or NULL.
  89
  90 **/
  91 USB_INTERFACE *
  92 UsbCreateInterface (
  93   IN USB_DEVICE           *Device,
  94   IN USB_INTERFACE_DESC   *IfDesc
  95   )
  96 {
  97   USB_DEVICE_PATH         UsbNode;
  98   USB_INTERFACE           *UsbIf;
  99   USB_INTERFACE           *HubIf;
 100   EFI_STATUS              Status;
 101
 102   UsbIf = AllocateZeroPool (sizeof (USB_INTERFACE));
 103
 104   if (UsbIf == NULL) {
 105     return NULL;
 106   }
 107
 108   UsbIf->Signature  = USB_INTERFACE_SIGNATURE;
 109   UsbIf->Device     = Device;
 110   UsbIf->IfDesc     = IfDesc;
 111   ASSERT (IfDesc->ActiveIndex < USB_MAX_INTERFACE_SETTING);
 112   UsbIf->IfSetting  = IfDesc->Settings[IfDesc->ActiveIndex];
 113
 114   CopyMem (
 115     &(UsbIf->UsbIo),
 116     &mUsbIoProtocol,
 117     sizeof (EFI_USB_IO_PROTOCOL)
 118     );
 119
 120   //
 121   // Install protocols for USBIO and device path
 122   //
 123   UsbNode.Header.Type       = MESSAGING_DEVICE_PATH;
 124   UsbNode.Header.SubType    = MSG_USB_DP;
 125   UsbNode.ParentPortNumber  = Device->ParentPort;
 126   UsbNode.InterfaceNumber   = UsbIf->IfSetting->Desc.InterfaceNumber;
 127
 128   SetDevicePathNodeLength (&UsbNode.Header, sizeof (UsbNode));
 129
 130   HubIf = Device->ParentIf;
 131   ASSERT (HubIf != NULL);
 132
 133   UsbIf->DevicePath = AppendDevicePathNode (HubIf->DevicePath, &UsbNode.Header);
 134
 135   if (UsbIf->DevicePath == NULL) {
 136     DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to create device path\n"));
 137
 138     Status = EFI_OUT_OF_RESOURCES;
 139     goto ON_ERROR;
 140   }
 141
 142   Status = gBS->InstallMultipleProtocolInterfaces (
 143                   &UsbIf->Handle,
 144                   &gEfiDevicePathProtocolGuid,
 145                   UsbIf->DevicePath,
 146                   &gEfiUsbIoProtocolGuid,
 147                   &UsbIf->UsbIo,
 148                   NULL
 149                   );
 150
 151   if (EFI_ERROR (Status)) {
 152     DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to install UsbIo - %r\n", Status));
 153     goto ON_ERROR;
 154   }
 155
 156   //
 157   // Open USB Host Controller Protocol by Child
 158   //
 159   Status = UsbOpenHostProtoByChild (Device->Bus, UsbIf->Handle);
 160
 161   if (EFI_ERROR (Status)) {
 162     gBS->UninstallMultipleProtocolInterfaces (
 163            &UsbIf->Handle,
 164            &gEfiDevicePathProtocolGuid,
 165            UsbIf->DevicePath,
 166            &gEfiUsbIoProtocolGuid,
 167            &UsbIf->UsbIo,
 168            NULL
 169            );
 170
 171     DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to open host for child - %r\n", Status));
 172     goto ON_ERROR;
 173   }
 174
 175   return UsbIf;
 176
 177 ON_ERROR:
 178   if (UsbIf->DevicePath != NULL) {
 179     FreePool (UsbIf->DevicePath);
 180   }
 181
 182   FreePool (UsbIf);
 183   return NULL;
 184 }
 185
 186
 187 /**
 188   Free the resource used by this USB device.
 189
 190   @param  Device                The USB device to free.
 191
 192 **/
 193 VOID
 194 UsbFreeDevice (
 195   IN USB_DEVICE           *Device
 196   )
 197 {
 198   if (Device->DevDesc != NULL) {
 199     UsbFreeDevDesc (Device->DevDesc);
 200   }
 201
 202   gBS->FreePool (Device);
 203 }
 204
 205
 206 /**
 207   Create a device which is on the parent's ParentPort port.
 208
 209   @param  ParentIf              The parent HUB interface.
 210   @param  ParentPort            The port on the HUB this device is connected to.
 211
 212   @return Created USB device, Or NULL.
 213
 214 **/
 215 USB_DEVICE *
 216 UsbCreateDevice (
 217   IN USB_INTERFACE        *ParentIf,
 218   IN UINT8                ParentPort
 219   )
 220 {
 221   USB_DEVICE              *Device;
 222
 223   ASSERT (ParentIf != NULL);
 224
 225   Device = AllocateZeroPool (sizeof (USB_DEVICE));
 226
 227   if (Device == NULL) {
 228     return NULL;
 229   }
 230
 231   Device->Bus         = ParentIf->Device->Bus;
 232   Device->MaxPacket0  = 8;
 233   Device->ParentAddr  = ParentIf->Device->Address;
 234   Device->ParentIf    = ParentIf;
 235   Device->ParentPort  = ParentPort;
 236   Device->Tier        = (UINT8)(ParentIf->Device->Tier + 1);
 237   return Device;
 238 }
 239
 240
 241 /**
 242   Connect the USB interface with its driver. EFI USB bus will
 243   create a USB interface for each separate interface descriptor.
 244
 245   @param  UsbIf             The interface to connect driver to.
 246
 247   @return EFI_SUCCESS       Interface is managed by some driver.
 248   @return Others            Failed to locate a driver for this interface.
 249
 250 **/
 251 EFI_STATUS
 252 UsbConnectDriver (
 253   IN USB_INTERFACE        *UsbIf
 254   )
 255 {
 256   EFI_STATUS              Status;
 257   EFI_TPL                 OldTpl;
 258
 259   Status = EFI_SUCCESS;
 260
 261   //
 262   // Hub is maintained by the USB bus driver. Otherwise try to
 263   // connect drivers with this interface
 264   //
 265   if (UsbIsHubInterface (UsbIf)) {
 266     DEBUG ((EFI_D_INFO, "UsbConnectDriver: found a hub device\n"));
 267     Status = mUsbHubApi.Init (UsbIf);
 268
 269   } else {
 270     //
 271     // This function is called in both UsbIoControlTransfer and
 272     // the timer callback in hub enumeration. So, at least it is
 273     // called at TPL_CALLBACK. Some driver sitting on USB has
 274     // twisted TPL used. It should be no problem for us to connect
 275     // or disconnect at CALLBACK.
 276     //
 277
 278     //
 279     // Only recursively wanted usb child device
 280     //
 281     if (UsbBusIsWantedUsbIO (UsbIf->Device->Bus, UsbIf)) {
 282       OldTpl            = UsbGetCurrentTpl ();
 283       DEBUG ((EFI_D_INFO, "UsbConnectDriver: TPL before connect is %d, %p\n", (UINT32)OldTpl, UsbIf->Handle));
 284
 285       gBS->RestoreTPL (TPL_CALLBACK);
 286
 287       Status            = gBS->ConnectController (UsbIf->Handle, NULL, NULL, TRUE);
 288       UsbIf->IsManaged  = (BOOLEAN)!EFI_ERROR (Status);
 289
 290       DEBUG ((EFI_D_INFO, "UsbConnectDriver: TPL after connect is %d\n", (UINT32)UsbGetCurrentTpl()));
 291       ASSERT (UsbGetCurrentTpl () == TPL_CALLBACK);
 292
 293       gBS->RaiseTPL (OldTpl);
 294     }
 295   }
 296
 297   return Status;
 298 }
 299
 300
 301 /**
 302   Select an alternate setting for the interface.
 303   Each interface can have several mutually exclusive
 304   settings. Only one setting is active. It will
 305   also reset its endpoints' toggle to zero.
 306
 307   @param  IfDesc                The interface descriptor to set.
 308   @param  Alternate             The alternate setting number to locate.
 309
 310   @retval EFI_NOT_FOUND         There is no setting with this alternate index.
 311   @retval EFI_SUCCESS           The interface is set to Alternate setting.
 312
 313 **/
 314 EFI_STATUS
 315 UsbSelectSetting (
 316   IN USB_INTERFACE_DESC   *IfDesc,
 317   IN UINT8                Alternate
 318   )
 319 {
 320   USB_INTERFACE_SETTING   *Setting;
 321   UINTN                   Index;
 322
 323   //
 324   // Locate the active alternate setting
 325   //
 326   Setting = NULL;
 327
 328   for (Index = 0; Index < IfDesc->NumOfSetting; Index++) {
 329     ASSERT (Index < USB_MAX_INTERFACE_SETTING);
 330     Setting = IfDesc->Settings[Index];
 331
 332     if (Setting->Desc.AlternateSetting == Alternate) {
 333       break;
 334     }
 335   }
 336
 337   if (Index == IfDesc->NumOfSetting) {
 338     return EFI_NOT_FOUND;
 339   }
 340
 341   IfDesc->ActiveIndex = Index;
 342
 343   ASSERT (Setting != NULL);
 344   DEBUG ((EFI_D_INFO, "UsbSelectSetting: setting %d selected for interface %d\n",
 345               Alternate, Setting->Desc.InterfaceNumber));
 346
 347   //
 348   // Reset the endpoint toggle to zero
 349   //
 350   for (Index = 0; Index < Setting->Desc.NumEndpoints; Index++) {
 351     Setting->Endpoints[Index]->Toggle = 0;
 352   }
 353
 354   return EFI_SUCCESS;
 355 }
 356
 357
 358 /**
 359   Select a new configuration for the device. Each
 360   device may support several configurations.
 361
 362   @param  Device                The device to select configuration.
 363   @param  ConfigValue           The index of the configuration ( != 0).
 364
 365   @retval EFI_NOT_FOUND         There is no configuration with the index.
 366   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource.
 367   @retval EFI_SUCCESS           The configuration is selected.
 368
 369 **/
 370 EFI_STATUS
 371 UsbSelectConfig (
 372   IN USB_DEVICE           *Device,
 373   IN UINT8                ConfigValue
 374   )
 375 {
 376   USB_DEVICE_DESC         *DevDesc;
 377   USB_CONFIG_DESC         *ConfigDesc;
 378   USB_INTERFACE_DESC      *IfDesc;
 379   USB_INTERFACE           *UsbIf;
 380   EFI_STATUS              Status;
 381   UINT8                   Index;
 382
 383   //
 384   // Locate the active config, then set the device's pointer
 385   //
 386   DevDesc     = Device->DevDesc;
 387   ConfigDesc  = NULL;
 388
 389   for (Index = 0; Index < DevDesc->Desc.NumConfigurations; Index++) {
 390     ConfigDesc = DevDesc->Configs[Index];
 391
 392     if (ConfigDesc->Desc.ConfigurationValue == ConfigValue) {
 393       break;
 394     }
 395   }
 396
 397   if (Index == DevDesc->Desc.NumConfigurations) {
 398     return EFI_NOT_FOUND;
 399   }
 400
 401   Device->ActiveConfig = ConfigDesc;
 402
 403   DEBUG ((EFI_D_INFO, "UsbSelectConfig: config %d selected for device %d\n",
 404               ConfigValue, Device->Address));
 405
 406   //
 407   // Create interfaces for each USB interface descriptor.
 408   //
 409   for (Index = 0; Index < ConfigDesc->Desc.NumInterfaces; Index++) {
 410     //
 411     // First select the default interface setting, and reset
 412     // the endpoint toggles to zero for its endpoints.
 413     //
 414     IfDesc = ConfigDesc->Interfaces[Index];
 415     UsbSelectSetting (IfDesc, IfDesc->Settings[0]->Desc.AlternateSetting);
 416
 417     //
 418     // Create a USB_INTERFACE and install USB_IO and other protocols
 419     //
 420     UsbIf = UsbCreateInterface (Device, ConfigDesc->Interfaces[Index]);
 421
 422     if (UsbIf == NULL) {
 423       return EFI_OUT_OF_RESOURCES;
 424     }
 425
 426     ASSERT (Index < USB_MAX_INTERFACE);
 427     Device->Interfaces[Index] = UsbIf;
 428
 429     //
 430     // Connect the device to drivers, if it failed, ignore
 431     // the error. Don't let the unsupported interfaces to block
 432     // the supported interfaces.
 433     //
 434     Status = UsbConnectDriver (UsbIf);
 435
 436     if (EFI_ERROR (Status)) {
 437       DEBUG ((EFI_D_ERROR, "UsbSelectConfig: failed to connect driver %r, ignored\n", Status));
 438     }
 439   }
 440
 441   Device->NumOfInterface = Index;
 442
 443   return EFI_SUCCESS;
 444 }
 445
 446
 447 /**
 448   Disconnect the USB interface with its driver.
 449
 450   @param  UsbIf                 The interface to disconnect driver from.
 451
 452 **/
 453 EFI_STATUS
 454 UsbDisconnectDriver (
 455   IN USB_INTERFACE        *UsbIf
 456   )
 457 {
 458   EFI_TPL                 OldTpl;
 459   EFI_STATUS              Status;
 460
 461   //
 462   // Release the hub if it's a hub controller, otherwise
 463   // disconnect the driver if it is managed by other drivers.
 464   //
 465   Status = EFI_SUCCESS;
 466   if (UsbIf->IsHub) {
 467     Status = UsbIf->HubApi->Release (UsbIf);
 468
 469   } else if (UsbIf->IsManaged) {
 470     //
 471     // This function is called in both UsbIoControlTransfer and
 472     // the timer callback in hub enumeration. So, at least it is
 473     // called at TPL_CALLBACK. Some driver sitting on USB has
 474     // twisted TPL used. It should be no problem for us to connect
 475     // or disconnect at CALLBACK.
 476     //
 477     OldTpl           = UsbGetCurrentTpl ();
 478     DEBUG ((EFI_D_INFO, "UsbDisconnectDriver: old TPL is %d, %p\n", (UINT32)OldTpl, UsbIf->Handle));
 479
 480     gBS->RestoreTPL (TPL_CALLBACK);
 481
 482     Status = gBS->DisconnectController (UsbIf->Handle, NULL, NULL);
 483     if (!EFI_ERROR (Status)) {
 484       UsbIf->IsManaged = FALSE;
 485     }
 486
 487     DEBUG (( EFI_D_INFO, "UsbDisconnectDriver: TPL after disconnect is %d, %d\n", (UINT32)UsbGetCurrentTpl(), Status));
 488     ASSERT (UsbGetCurrentTpl () == TPL_CALLBACK);
 489
 490     gBS->RaiseTPL (OldTpl);
 491   }
 492
 493   return Status;
 494 }
 495
 496
 497 /**
 498   Remove the current device configuration.
 499
 500   @param  Device                The USB device to remove configuration from.
 501
 502 **/
 503 EFI_STATUS
 504 UsbRemoveConfig (
 505   IN USB_DEVICE           *Device
 506   )
 507 {
 508   USB_INTERFACE           *UsbIf;
 509   UINTN                   Index;
 510   EFI_STATUS              Status;
 511   EFI_STATUS              ReturnStatus;
 512
 513   //
 514   // Remove each interface of the device
 515   //
 516   ReturnStatus = EFI_SUCCESS;
 517   for (Index = 0; Index < Device->NumOfInterface; Index++) {
 518     ASSERT (Index < USB_MAX_INTERFACE);
 519     UsbIf = Device->Interfaces[Index];
 520
 521     if (UsbIf == NULL) {
 522       continue;
 523     }
 524
 525     Status = UsbDisconnectDriver (UsbIf);
 526     if (!EFI_ERROR (Status)) {
 527       UsbFreeInterface (UsbIf);
 528       Device->Interfaces[Index] = NULL;
 529     } else {
 530       ReturnStatus = Status;
 531     }
 532   }
 533
 534   Device->ActiveConfig    = NULL;
 535   return ReturnStatus;
 536 }
 537
 538
 539 /**
 540   Remove the device and all its children from the bus.
 541
 542   @param  Device                The device to remove.
 543
 544   @retval EFI_SUCCESS           The device is removed.
 545
 546 **/
 547 EFI_STATUS
 548 UsbRemoveDevice (
 549   IN USB_DEVICE           *Device
 550   )
 551 {
 552   USB_BUS                 *Bus;
 553   USB_DEVICE              *Child;
 554   EFI_STATUS              Status;
 555   EFI_STATUS              ReturnStatus;
 556   UINTN                   Index;
 557
 558   Bus = Device->Bus;
 559
 560   //
 561   // Remove all the devices on its downstream ports. Search from devices[1].
 562   // Devices[0] is the root hub.
 563   //
 564   ReturnStatus = EFI_SUCCESS;
 565   for (Index = 1; Index < Bus->MaxDevices; Index++) {
 566     Child = Bus->Devices[Index];
 567
 568     if ((Child == NULL) || (Child->ParentAddr != Device->Address)) {
 569       continue;
 570     }
 571
 572     Status = UsbRemoveDevice (Child);
 573
 574     if (!EFI_ERROR (Status)) {
 575       Bus->Devices[Index] = NULL;
 576     } else {
 577       Bus->Devices[Index]->DisconnectFail = TRUE;
 578       ReturnStatus = Status;
 579       DEBUG ((EFI_D_INFO, "UsbRemoveDevice: failed to remove child %p at parent %p\n", Child, Device));
 580     }
 581   }
 582
 583   if (EFI_ERROR (ReturnStatus)) {
 584     return ReturnStatus;
 585   }
 586
 587   Status = UsbRemoveConfig (Device);
 588
 589   if (!EFI_ERROR (Status)) {
 590     DEBUG (( EFI_D_INFO, "UsbRemoveDevice: device %d removed\n", Device->Address));
 591
 592     ASSERT (Device->Address < Bus->MaxDevices);
 593     Bus->Devices[Device->Address] = NULL;
 594     UsbFreeDevice (Device);
 595   } else {
 596     Bus->Devices[Device->Address]->DisconnectFail = TRUE;
 597   }
 598   return Status;
 599 }
 600
 601
 602 /**
 603   Find the child device on the hub's port.
 604
 605   @param  HubIf                 The hub interface.
 606   @param  Port                  The port of the hub this child is connected to.
 607
 608   @return The device on the hub's port, or NULL if there is none.
 609
 610 **/
 611 USB_DEVICE *
 612 UsbFindChild (
 613   IN USB_INTERFACE        *HubIf,
 614   IN UINT8                Port
 615   )
 616 {
 617   USB_DEVICE              *Device;
 618   USB_BUS                 *Bus;
 619   UINTN                   Index;
 620
 621   Bus = HubIf->Device->Bus;
 622
 623   //
 624   // Start checking from device 1, device 0 is the root hub
 625   //
 626   for (Index = 1; Index < Bus->MaxDevices; Index++) {
 627     Device = Bus->Devices[Index];
 628
 629     if ((Device != NULL) && (Device->ParentAddr == HubIf->Device->Address) &&
 630         (Device->ParentPort == Port)) {
 631
 632       return Device;
 633     }
 634   }
 635
 636   return NULL;
 637 }
 638
 639
 640 /**
 641   Enumerate and configure the new device on the port of this HUB interface.
 642
 643   @param  HubIf                 The HUB that has the device connected.
 644   @param  Port                  The port index of the hub (started with zero).
 645
 646   @retval EFI_SUCCESS           The device is enumerated (added or removed).
 647   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the device.
 648   @retval Others                Failed to enumerate the device.
 649
 650 **/
 651 EFI_STATUS
 652 UsbEnumerateNewDev (
 653   IN USB_INTERFACE        *HubIf,
 654   IN UINT8                Port
 655   )
 656 {
 657   USB_BUS                 *Bus;
 658   USB_HUB_API             *HubApi;
 659   USB_DEVICE              *Child;
 660   USB_DEVICE              *Parent;
 661   EFI_USB_PORT_STATUS     PortState;
 662   UINTN                   Address;
 663   UINT8                   Config;
 664   EFI_STATUS              Status;
 665
 666   Parent  = HubIf->Device;
 667   Bus     = Parent->Bus;
 668   HubApi  = HubIf->HubApi;
 669   Address = Bus->MaxDevices;
 670
 671   gBS->Stall (USB_WAIT_PORT_STABLE_STALL);
 672
 673   //
 674   // Hub resets the device for at least 10 milliseconds.
 675   // Host learns device speed. If device is of low/full speed
 676   // and the hub is a EHCI root hub, ResetPort will release
 677   // the device to its companion UHCI and return an error.
 678   //
 679   Status = HubApi->ResetPort (HubIf, Port);
 680
 681   if (EFI_ERROR (Status)) {
 682     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to reset port %d - %r\n", Port, Status));
 683
 684     return Status;
 685   }
 686
 687   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: hub port %d is reset\n", Port));
 688
 689   Child = UsbCreateDevice (HubIf, Port);
 690
 691   if (Child == NULL) {
 692     return EFI_OUT_OF_RESOURCES;
 693   }
 694
 695   //
 696   // OK, now identify the device speed. After reset, hub
 697   // fully knows the actual device speed.
 698   //
 699   Status = HubApi->GetPortStatus (HubIf, Port, &PortState);
 700
 701   if (EFI_ERROR (Status)) {
 702     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to get speed of port %d\n", Port));
 703     goto ON_ERROR;
 704   }
 705
 706   if (!USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_CONNECTION)) {
 707     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: No device present at port %d\n", Port));
 708     goto ON_ERROR;
 709   } else if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_SUPER_SPEED)){
 710     Child->Speed      = EFI_USB_SPEED_SUPER;
 711     Child->MaxPacket0 = 512;
 712   } else if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_HIGH_SPEED)) {
 713     Child->Speed      = EFI_USB_SPEED_HIGH;
 714     Child->MaxPacket0 = 64;
 715   } else if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_LOW_SPEED)) {
 716     Child->Speed      = EFI_USB_SPEED_LOW;
 717     Child->MaxPacket0 = 8;
 718   } else {
 719     Child->Speed      = EFI_USB_SPEED_FULL;
 720     Child->MaxPacket0 = 8;
 721   }
 722
 723   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device is of %d speed\n", Child->Speed));
 724
 725   if (((Child->Speed == EFI_USB_SPEED_LOW) || (Child->Speed == EFI_USB_SPEED_FULL)) &&
 726       (Parent->Speed == EFI_USB_SPEED_HIGH)) {
 727     //
 728     // If the child is a low or full speed device, it is necessary to
 729     // set the transaction translator. Port TT is 1-based.
 730     // This is quite simple:
 731     //  1. if parent is of high speed, then parent is our translator
 732     //  2. otherwise use parent's translator.
 733     //
 734     Child->Translator.TranslatorHubAddress  = Parent->Address;
 735     Child->Translator.TranslatorPortNumber  = (UINT8) (Port + 1);
 736   } else {
 737     Child->Translator = Parent->Translator;
 738   }
 739   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device uses translator (%d, %d)\n",
 740            Child->Translator.TranslatorHubAddress,
 741            Child->Translator.TranslatorPortNumber));
 742
 743   //
 744   // After port is reset, hub establishes a signal path between
 745   // the device and host (DEFALUT state). Device's registers are
 746   // reset, use default address 0 (host enumerates one device at
 747   // a time) , and ready to respond to control transfer at EP 0.
 748   //
 749
 750   //
 751   // Host assigns an address to the device. Device completes the
 752   // status stage with default address, then switches to new address.
 753   // ADDRESS state. Address zero is reserved for root hub.
 754   //
 755   ASSERT (Bus->MaxDevices <= 256);
 756   for (Address = 1; Address < Bus->MaxDevices; Address++) {
 757     if (Bus->Devices[Address] == NULL) {
 758       break;
 759     }
 760   }
 761
 762   if (Address >= Bus->MaxDevices) {
 763     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: address pool is full for port %d\n", Port));
 764
 765     Status = EFI_ACCESS_DENIED;
 766     goto ON_ERROR;
 767   }
 768
 769   Status                = UsbSetAddress (Child, (UINT8)Address);
 770   Child->Address        = (UINT8)Address;
 771   Bus->Devices[Address] = Child;
 772
 773   if (EFI_ERROR (Status)) {
 774     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to set device address - %r\n", Status));
 775     goto ON_ERROR;
 776   }
 777
 778   gBS->Stall (USB_SET_DEVICE_ADDRESS_STALL);
 779
 780   DEBUG ((EFI_D_INFO, "UsbEnumerateNewDev: device is now ADDRESSED at %d\n", Address));
 781
 782   //
 783   // Host sends a Get_Descriptor request to learn the max packet
 784   // size of default pipe (only part of the device's descriptor).
 785   //
 786   Status = UsbGetMaxPacketSize0 (Child);
 787
 788   if (EFI_ERROR (Status)) {
 789     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to get max packet for EP 0 - %r\n", Status));
 790     goto ON_ERROR;
 791   }
 792
 793   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: max packet size for EP 0 is %d\n", Child->MaxPacket0));
 794
 795   //
 796   // Host learns about the device's abilities by requesting device's
 797   // entire descriptions.
 798   //
 799   Status = UsbBuildDescTable (Child);
 800
 801   if (EFI_ERROR (Status)) {
 802     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to build descriptor table - %r\n", Status));
 803     goto ON_ERROR;
 804   }
 805
 806   //
 807   // Select a default configuration: UEFI must set the configuration
 808   // before the driver can connect to the device.
 809   //
 810   Config = Child->DevDesc->Configs[0]->Desc.ConfigurationValue;
 811   Status = UsbSetConfig (Child, Config);
 812
 813   if (EFI_ERROR (Status)) {
 814     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to set configure %d - %r\n", Config, Status));
 815     goto ON_ERROR;
 816   }
 817
 818   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device %d is now in CONFIGED state\n", Address));
 819
 820   //
 821   // Host assigns and loads a device driver.
 822   //
 823   Status = UsbSelectConfig (Child, Config);
 824
 825   if (EFI_ERROR (Status)) {
 826     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to create interfaces - %r\n", Status));
 827     goto ON_ERROR;
 828   }
 829
 830   //
 831   // Report Status Code to indicate USB device has been detected by hotplug
 832   //
 833   REPORT_STATUS_CODE_WITH_DEVICE_PATH (
 834     EFI_PROGRESS_CODE,
 835     (EFI_IO_BUS_USB | EFI_IOB_PC_HOTPLUG),
 836     Bus->DevicePath
 837     );
 838   return EFI_SUCCESS;
 839
 840 ON_ERROR:
 841   //
 842   // If reach here, it means the enumeration process on a given port is interrupted due to error.
 843   // The s/w resources, including the assigned address(Address) and the allocated usb device data
 844   // structure(Bus->Devices[Address]), will NOT be freed here. These resources will be freed when
 845   // the device is unplugged from the port or DriverBindingStop() is invoked.
 846   //
 847   // This way is used to co-work with the lower layer EDKII UHCI/EHCI/XHCI host controller driver.
 848   // It's mainly because to keep UEFI spec unchanged EDKII XHCI driver have to maintain a state machine
 849   // to keep track of the mapping between actual address and request address. If the request address
 850   // (Address) is freed here, the Address value will be used by next enumerated device. Then EDKII XHCI
 851   // host controller driver will have wrong information, which will cause further transaction error.
 852   //
 853   // EDKII UHCI/EHCI doesn't get impacted as it's make sense to reserve s/w resource till it gets unplugged.
 854   //
 855   return Status;
 856 }
 857
 858
 859 /**
 860   Process the events on the port.
 861
 862   @param  HubIf                 The HUB that has the device connected.
 863   @param  Port                  The port index of the hub (started with zero).
 864
 865   @retval EFI_SUCCESS           The device is enumerated (added or removed).
 866   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the device.
 867   @retval Others                Failed to enumerate the device.
 868
 869 **/
 870 EFI_STATUS
 871 UsbEnumeratePort (
 872   IN USB_INTERFACE        *HubIf,
 873   IN UINT8                Port
 874   )
 875 {
 876   USB_HUB_API             *HubApi;
 877   USB_DEVICE              *Child;
 878   EFI_USB_PORT_STATUS     PortState;
 879   EFI_STATUS              Status;
 880
 881   Child   = NULL;
 882   HubApi  = HubIf->HubApi;
 883
 884   //
 885   // Host learns of the new device by polling the hub for port changes.
 886   //
 887   Status = HubApi->GetPortStatus (HubIf, Port, &PortState);
 888
 889   if (EFI_ERROR (Status)) {
 890     DEBUG ((EFI_D_ERROR, "UsbEnumeratePort: failed to get state of port %d\n", Port));
 891     return Status;
 892   }
 893
 894   //
 895   // Only handle connection/enable/overcurrent/reset change.
 896   // Usb super speed hub may report other changes, such as warm reset change. Ignore them.
 897   //
 898   if ((PortState.PortChangeStatus & (USB_PORT_STAT_C_CONNECTION | USB_PORT_STAT_C_ENABLE | USB_PORT_STAT_C_OVERCURRENT | USB_PORT_STAT_C_RESET)) == 0) {
 899     return EFI_SUCCESS;
 900   }
 901
 902   DEBUG (( EFI_D_INFO, "UsbEnumeratePort: port %d state - %02x, change - %02x on %p\n",
 903               Port, PortState.PortStatus, PortState.PortChangeStatus, HubIf));
 904
 905   //
 906   // This driver only process two kinds of events now: over current and
 907   // connect/disconnect. Other three events are: ENABLE, SUSPEND, RESET.
 908   // ENABLE/RESET is used to reset port. SUSPEND isn't supported.
 909   //
 910
 911   if (USB_BIT_IS_SET (PortState.PortChangeStatus, USB_PORT_STAT_C_OVERCURRENT)) {
 912
 913     if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_OVERCURRENT)) {
 914       //
 915       // Case1:
 916       //   Both OverCurrent and OverCurrentChange set, means over current occurs,
 917       //   which probably is caused by short circuit. It has to wait system hardware
 918       //   to perform recovery.
 919       //
 920       DEBUG (( EFI_D_ERROR, "UsbEnumeratePort: Critical Over Current\n", Port));
 921       return EFI_DEVICE_ERROR;
 922
 923     }
 924     //
 925     // Case2:
 926     //   Only OverCurrentChange set, means system has been recoveried from
 927     //   over current. As a result, all ports are nearly power-off, so
 928     //   it's necessary to detach and enumerate all ports again.
 929     //
 930     DEBUG (( EFI_D_ERROR, "UsbEnumeratePort: 2.0 device Recovery Over Current\n", Port));
 931   }
 932
 933   if (USB_BIT_IS_SET (PortState.PortChangeStatus, USB_PORT_STAT_C_ENABLE)) {
 934     //
 935     // Case3:
 936     //   1.1 roothub port reg doesn't reflect over-current state, while its counterpart
 937     //   on 2.0 roothub does. When over-current has influence on 1.1 device, the port
 938     //   would be disabled, so it's also necessary to detach and enumerate again.
 939     //
 940     DEBUG (( EFI_D_ERROR, "UsbEnumeratePort: 1.1 device Recovery Over Current\n", Port));
 941   }
 942
 943   if (USB_BIT_IS_SET (PortState.PortChangeStatus, USB_PORT_STAT_C_CONNECTION)) {
 944     //
 945     // Case4:
 946     //   Device connected or disconnected normally.
 947     //
 948     DEBUG ((EFI_D_INFO, "UsbEnumeratePort: Device Connect/Disconnect Normally\n", Port));
 949   }
 950
 951   //
 952   // Following as the above cases, it's safety to remove and create again.
 953   //
 954   Child = UsbFindChild (HubIf, Port);
 955
 956   if (Child != NULL) {
 957     DEBUG (( EFI_D_INFO, "UsbEnumeratePort: device at port %d removed from root hub %p\n", Port, HubIf));
 958     UsbRemoveDevice (Child);
 959   }
 960
 961   if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_CONNECTION)) {
 962     //
 963     // Now, new device connected, enumerate and configure the device
 964     //
 965     DEBUG (( EFI_D_INFO, "UsbEnumeratePort: new device connected at port %d\n", Port));
 966     Status = UsbEnumerateNewDev (HubIf, Port);
 967
 968   } else {
 969     DEBUG (( EFI_D_INFO, "UsbEnumeratePort: device disconnected event on port %d\n", Port));
 970   }
 971
 972   HubApi->ClearPortChange (HubIf, Port);
 973   return Status;
 974 }
 975
 976
 977 /**
 978   Enumerate all the changed hub ports.
 979
 980   @param  Event                 The event that is triggered.
 981   @param  Context               The context to the event.
 982
 983 **/
 984 VOID
 985 EFIAPI
 986 UsbHubEnumeration (
 987   IN EFI_EVENT            Event,
 988   IN VOID                 *Context
 989   )
 990 {
 991   USB_INTERFACE           *HubIf;
 992   UINT8                   Byte;
 993   UINT8                   Bit;
 994   UINT8                   Index;
 995   USB_DEVICE              *Child;
 996
 997   ASSERT (Context != NULL);
 998
 999   HubIf = (USB_INTERFACE *) Context;
1000
1001   for (Index = 0; Index < HubIf->NumOfPort; Index++) {
1002     Child = UsbFindChild (HubIf, Index);
1003     if ((Child != NULL) && (Child->DisconnectFail == TRUE)) {
1004       DEBUG (( EFI_D_INFO, "UsbEnumeratePort: The device disconnect fails at port %d from hub %p, try again\n", Index, HubIf));
1005       UsbRemoveDevice (Child);
1006     }
1007   }
1008
1009   if (HubIf->ChangeMap == NULL) {
1010     return ;
1011   }
1012
1013   //
1014   // HUB starts its port index with 1.
1015   //
1016   Byte  = 0;
1017   Bit   = 1;
1018
1019   for (Index = 0; Index < HubIf->NumOfPort; Index++) {
1020     if (USB_BIT_IS_SET (HubIf->ChangeMap[Byte], USB_BIT (Bit))) {
1021       UsbEnumeratePort (HubIf, Index);
1022     }
1023
1024     USB_NEXT_BIT (Byte, Bit);
1025   }
1026
1027   UsbHubAckHubStatus (HubIf->Device);
1028
1029   gBS->FreePool (HubIf->ChangeMap);
1030   HubIf->ChangeMap = NULL;
1031   return ;
1032 }
1033
1034
1035 /**
1036   Enumerate all the changed hub ports.
1037
1038   @param  Event                 The event that is triggered.
1039   @param  Context               The context to the event.
1040
1041 **/
1042 VOID
1043 EFIAPI
1044 UsbRootHubEnumeration (
1045   IN EFI_EVENT            Event,
1046   IN VOID                 *Context
1047   )
1048 {
1049   USB_INTERFACE           *RootHub;
1050   UINT8                   Index;
1051   USB_DEVICE              *Child;
1052
1053   RootHub = (USB_INTERFACE *) Context;
1054
1055   for (Index = 0; Index < RootHub->NumOfPort; Index++) {
1056     Child = UsbFindChild (RootHub, Index);
1057     if ((Child != NULL) && (Child->DisconnectFail == TRUE)) {
1058       DEBUG (( EFI_D_INFO, "UsbEnumeratePort: The device disconnect fails at port %d from root hub %p, try again\n", Index, RootHub));
1059       UsbRemoveDevice (Child);
1060     }
1061
1062     UsbEnumeratePort (RootHub, Index);
1063   }
1064 }