MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c

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