MdeModulePkg/Bus/Usb/UsbBusDxe/UsbEnumer.c

   1 /** @file
   2
   3     Usb bus enumeration support.
   4
   5 Copyright (c) 2007 - 2008, Intel Corporation
   6 All rights reserved. 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 /**
  20   Return the endpoint descriptor in this interface.
  21
  22   @param  UsbIf                 The interface to search in.
  23   @param  EpAddr                The address of the endpoint to return.
  24
  25   @return The endpoint descriptor or NULL.
  26
  27 **/
  28 USB_ENDPOINT_DESC *
  29 UsbGetEndpointDesc (
  30   IN USB_INTERFACE        *UsbIf,
  31   IN UINT8                EpAddr
  32   )
  33 {
  34   USB_ENDPOINT_DESC       *EpDesc;
  35   UINTN                   Index;
  36
  37   for (Index = 0; Index < UsbIf->IfSetting->Desc.NumEndpoints; Index++) {
  38     EpDesc = UsbIf->IfSetting->Endpoints[Index];
  39
  40     if (EpDesc->Desc.EndpointAddress == EpAddr) {
  41       return EpDesc;
  42     }
  43   }
  44
  45   return NULL;
  46 }
  47
  48
  49 /**
  50   Free the resource used by USB interface.
  51
  52   @param  UsbIf                 The USB interface to free.
  53
  54   @return None.
  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     gBS->FreePool (UsbIf->DevicePath);
  75   }
  76
  77   gBS->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   UsbIf->IfSetting  = IfDesc->Settings[IfDesc->ActiveIndex];
 112
 113   CopyMem (
 114     &(UsbIf->UsbIo),
 115     &mUsbIoProtocol,
 116     sizeof (EFI_USB_IO_PROTOCOL)
 117     );
 118
 119   //
 120   // Install protocols for USBIO and device path
 121   //
 122   UsbNode.Header.Type       = MESSAGING_DEVICE_PATH;
 123   UsbNode.Header.SubType    = MSG_USB_DP;
 124   UsbNode.ParentPortNumber  = Device->ParentPort;
 125   UsbNode.InterfaceNumber   = UsbIf->IfSetting->Desc.InterfaceNumber;
 126
 127   SetDevicePathNodeLength (&UsbNode.Header, sizeof (UsbNode));
 128
 129   HubIf = Device->ParentIf;
 130   ASSERT (HubIf != NULL);
 131
 132   UsbIf->DevicePath = AppendDevicePathNode (HubIf->DevicePath, &UsbNode.Header);
 133
 134   if (UsbIf->DevicePath == NULL) {
 135     DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to create device path\n"));
 136
 137     Status = EFI_OUT_OF_RESOURCES;
 138     goto ON_ERROR;
 139   }
 140
 141   Status = gBS->InstallMultipleProtocolInterfaces (
 142                   &UsbIf->Handle,
 143                   &gEfiDevicePathProtocolGuid,
 144                   UsbIf->DevicePath,
 145                   &gEfiUsbIoProtocolGuid,
 146                   &UsbIf->UsbIo,
 147                   NULL
 148                   );
 149
 150   if (EFI_ERROR (Status)) {
 151     DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to install UsbIo - %r\n", Status));
 152     goto ON_ERROR;
 153   }
 154
 155   //
 156   // Open USB Host Controller Protocol by Child
 157   //
 158   Status = UsbOpenHostProtoByChild (Device->Bus, UsbIf->Handle);
 159
 160   if (EFI_ERROR (Status)) {
 161     gBS->UninstallMultipleProtocolInterfaces (
 162            &UsbIf->Handle,
 163            &gEfiDevicePathProtocolGuid,
 164            UsbIf->DevicePath,
 165            &gEfiUsbIoProtocolGuid,
 166            &UsbIf->UsbIo,
 167            NULL
 168            );
 169
 170     DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to open host for child - %r\n", Status));
 171     goto ON_ERROR;
 172   }
 173
 174   return UsbIf;
 175
 176 ON_ERROR:
 177   if (UsbIf->DevicePath != NULL) {
 178     gBS->FreePool (UsbIf->DevicePath);
 179   }
 180
 181   gBS->FreePool (UsbIf);
 182   return NULL;
 183 }
 184
 185
 186 /**
 187   Free the resource used by this USB device.
 188
 189   @param  Device                The USB device to free.
 190
 191   @return None.
 192
 193 **/
 194 VOID
 195 UsbFreeDevice (
 196   IN USB_DEVICE           *Device
 197   )
 198 {
 199   if (Device->DevDesc != NULL) {
 200     UsbFreeDevDesc (Device->DevDesc);
 201   }
 202
 203   gBS->FreePool (Device);
 204 }
 205
 206
 207 /**
 208   Create a device which is on the parent's ParentPort port.
 209
 210   @param  ParentIf              The parent HUB interface.
 211   @param  ParentPort            The port on the HUB this device is connected to.
 212
 213   @return Created USB device, Or NULL.
 214
 215 **/
 216 USB_DEVICE *
 217 UsbCreateDevice (
 218   IN USB_INTERFACE        *ParentIf,
 219   IN UINT8                ParentPort
 220   )
 221 {
 222   USB_DEVICE              *Device;
 223
 224   ASSERT (ParentIf != NULL);
 225
 226   Device = AllocateZeroPool (sizeof (USB_DEVICE));
 227
 228   if (Device == NULL) {
 229     return NULL;
 230   }
 231
 232   Device->Bus         = ParentIf->Device->Bus;
 233   Device->MaxPacket0  = 8;
 234   Device->ParentAddr  = ParentIf->Device->Address;
 235   Device->ParentIf    = ParentIf;
 236   Device->ParentPort  = ParentPort;
 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 seperate 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\n", (UINT32)OldTpl));
 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   UINT8                   Index;
 322
 323   //
 324   // Locate the active alternate setting
 325   //
 326   Setting = NULL;
 327
 328   for (Index = 0; Index < IfDesc->NumOfSetting; Index++) {
 329     Setting = IfDesc->Settings[Index];
 330
 331     if (Setting->Desc.AlternateSetting == Alternate) {
 332       break;
 333     }
 334   }
 335
 336   if (Index == IfDesc->NumOfSetting) {
 337     return EFI_NOT_FOUND;
 338   }
 339
 340   IfDesc->ActiveIndex = Index;
 341
 342   DEBUG ((EFI_D_INFO, "UsbSelectSetting: setting %d selected for interface %d\n",
 343               Alternate, Setting->Desc.InterfaceNumber));
 344
 345   //
 346   // Reset the endpoint toggle to zero
 347   //
 348   for (Index = 0; Index < Setting->Desc.NumEndpoints; Index++) {
 349     Setting->Endpoints[Index]->Toggle = 0;
 350   }
 351
 352   return EFI_SUCCESS;
 353 }
 354
 355
 356 /**
 357   Select a new configuration for the device. Each
 358   device may support several configurations.
 359
 360   @param  Device                The device to select configuration.
 361   @param  ConfigValue           The index of the configuration ( != 0).
 362
 363   @retval EFI_NOT_FOUND         There is no configuration with the index.
 364   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource.
 365   @retval EFI_SUCCESS           The configuration is selected.
 366
 367 **/
 368 EFI_STATUS
 369 UsbSelectConfig (
 370   IN USB_DEVICE           *Device,
 371   IN UINT8                ConfigValue
 372   )
 373 {
 374   USB_DEVICE_DESC         *DevDesc;
 375   USB_CONFIG_DESC         *ConfigDesc;
 376   USB_INTERFACE_DESC      *IfDesc;
 377   USB_INTERFACE           *UsbIf;
 378   EFI_STATUS              Status;
 379   UINT8                   Index;
 380
 381   //
 382   // Locate the active config, then set the device's pointer
 383   //
 384   DevDesc     = Device->DevDesc;
 385   ConfigDesc  = NULL;
 386
 387   for (Index = 0; Index < DevDesc->Desc.NumConfigurations; Index++) {
 388     ConfigDesc = DevDesc->Configs[Index];
 389
 390     if (ConfigDesc->Desc.ConfigurationValue == ConfigValue) {
 391       break;
 392     }
 393   }
 394
 395   if (Index == DevDesc->Desc.NumConfigurations) {
 396     return EFI_NOT_FOUND;
 397   }
 398
 399   Device->ActiveConfig = ConfigDesc;
 400
 401   DEBUG ((EFI_D_INFO, "UsbSelectConfig: config %d selected for device %d\n",
 402               ConfigValue, Device->Address));
 403
 404   //
 405   // Create interfaces for each USB interface descriptor.
 406   //
 407   for (Index = 0; Index < ConfigDesc->Desc.NumInterfaces; Index++) {
 408     //
 409     // First select the default interface setting, and reset
 410     // the endpoint toggles to zero for its endpoints.
 411     //
 412     IfDesc = ConfigDesc->Interfaces[Index];
 413     UsbSelectSetting (IfDesc, IfDesc->Settings[0]->Desc.AlternateSetting);
 414
 415     //
 416     // Create a USB_INTERFACE and install USB_IO and other protocols
 417     //
 418     UsbIf = UsbCreateInterface (Device, ConfigDesc->Interfaces[Index]);
 419
 420     if (UsbIf == NULL) {
 421       return EFI_OUT_OF_RESOURCES;
 422     }
 423
 424     Device->Interfaces[Index] = UsbIf;
 425
 426     //
 427     // Connect the device to drivers, if it failed, ignore
 428     // the error. Don't let the unsupported interfaces to block
 429     // the supported interfaces.
 430     //
 431     Status = UsbConnectDriver (UsbIf);
 432
 433     if (EFI_ERROR (Status)) {
 434       DEBUG ((EFI_D_ERROR, "UsbSelectConfig: failed to connect driver %r, ignored\n", Status));
 435     }
 436   }
 437
 438   Device->NumOfInterface = Index;
 439
 440   return EFI_SUCCESS;
 441 }
 442
 443
 444 /**
 445   Disconnect the USB interface with its driver.
 446
 447   @param  UsbIf                 The interface to disconnect driver from.
 448
 449   @return None.
 450
 451 **/
 452 VOID
 453 UsbDisconnectDriver (
 454   IN USB_INTERFACE        *UsbIf
 455   )
 456 {
 457   EFI_TPL                 OldTpl;
 458
 459   //
 460   // Release the hub if it's a hub controller, otherwise
 461   // disconnect the driver if it is managed by other drivers.
 462   //
 463   if (UsbIf->IsHub) {
 464     UsbIf->HubApi->Release (UsbIf);
 465
 466   } else if (UsbIf->IsManaged) {
 467     //
 468     // This function is called in both UsbIoControlTransfer and
 469     // the timer callback in hub enumeration. So, at least it is
 470     // called at TPL_CALLBACK. Some driver sitting on USB has
 471     // twisted TPL used. It should be no problem for us to connect
 472     // or disconnect at CALLBACK.
 473     //
 474     OldTpl           = UsbGetCurrentTpl ();
 475     DEBUG ((EFI_D_INFO, "UsbDisconnectDriver: old TPL is %d\n", (UINT32)OldTpl));
 476
 477     gBS->RestoreTPL (TPL_CALLBACK);
 478
 479     gBS->DisconnectController (UsbIf->Handle, NULL, NULL);
 480     UsbIf->IsManaged = FALSE;
 481
 482     DEBUG (( EFI_D_INFO, "UsbDisconnectDriver: TPL after disconnect is %d\n", (UINT32)UsbGetCurrentTpl()));
 483     ASSERT (UsbGetCurrentTpl () == TPL_CALLBACK);
 484
 485     gBS->RaiseTPL (OldTpl);
 486   }
 487 }
 488
 489
 490 /**
 491   Remove the current device configuration.
 492
 493   @param  Device                The USB device to remove configuration from.
 494
 495   @return None.
 496
 497 **/
 498 VOID
 499 UsbRemoveConfig (
 500   IN USB_DEVICE           *Device
 501   )
 502 {
 503   USB_INTERFACE           *UsbIf;
 504   UINTN                   Index;
 505
 506   //
 507   // Remove each interface of the device
 508   //
 509   for (Index = 0; Index < Device->NumOfInterface; Index++) {
 510     UsbIf = Device->Interfaces[Index];
 511
 512     if (UsbIf == NULL) {
 513       continue;
 514     }
 515
 516     UsbDisconnectDriver (UsbIf);
 517     UsbFreeInterface (UsbIf);
 518     Device->Interfaces[Index] = NULL;
 519   }
 520
 521   Device->ActiveConfig    = NULL;
 522   Device->NumOfInterface  = 0;
 523 }
 524
 525
 526 /**
 527   Remove the device and all its children from the bus.
 528
 529   @param  Device                The device to remove.
 530
 531   @retval EFI_SUCCESS           The device is removed.
 532
 533 **/
 534 EFI_STATUS
 535 UsbRemoveDevice (
 536   IN USB_DEVICE           *Device
 537   )
 538 {
 539   USB_BUS                 *Bus;
 540   USB_DEVICE              *Child;
 541   EFI_STATUS              Status;
 542   UINT8                   Index;
 543
 544   Bus = Device->Bus;
 545
 546   //
 547   // Remove all the devices on its downstream ports. Search from devices[1].
 548   // Devices[0] is the root hub.
 549   //
 550   for (Index = 1; Index < USB_MAX_DEVICES; Index++) {
 551     Child = Bus->Devices[Index];
 552
 553     if ((Child == NULL) || (Child->ParentAddr != Device->Address)) {
 554       continue;
 555     }
 556
 557     Status = UsbRemoveDevice (Child);
 558
 559     if (EFI_ERROR (Status)) {
 560       DEBUG ((EFI_D_ERROR, "UsbRemoveDevice: failed to remove child, ignore error\n"));
 561       Bus->Devices[Index] = NULL;
 562     }
 563   }
 564
 565   UsbRemoveConfig (Device);
 566
 567   DEBUG (( EFI_D_INFO, "UsbRemoveDevice: device %d removed\n", Device->Address));
 568
 569   Bus->Devices[Device->Address] = NULL;
 570   UsbFreeDevice (Device);
 571
 572   return EFI_SUCCESS;
 573 }
 574
 575
 576 /**
 577   Find the child device on the hub's port.
 578
 579   @param  HubIf                 The hub interface.
 580   @param  Port                  The port of the hub this child is connected to.
 581
 582   @return The device on the hub's port, or NULL if there is none.
 583
 584 **/
 585 USB_DEVICE *
 586 UsbFindChild (
 587   IN USB_INTERFACE        *HubIf,
 588   IN UINT8                Port
 589   )
 590 {
 591   USB_DEVICE              *Device;
 592   USB_BUS                 *Bus;
 593   UINTN                   Index;
 594
 595   Bus = HubIf->Device->Bus;
 596
 597   //
 598   // Start checking from device 1, device 0 is the root hub
 599   //
 600   for (Index = 1; Index < USB_MAX_DEVICES; Index++) {
 601     Device = Bus->Devices[Index];
 602
 603     if ((Device != NULL) && (Device->ParentAddr == HubIf->Device->Address) &&
 604         (Device->ParentPort == Port)) {
 605
 606       return Device;
 607     }
 608   }
 609
 610   return NULL;
 611 }
 612
 613
 614 /**
 615   Enumerate and configure the new device on the port of this HUB interface.
 616
 617   @param  HubIf                 The HUB that has the device connected.
 618   @param  Port                  The port index of the hub (started with zero).
 619
 620   @retval EFI_SUCCESS           The device is enumerated (added or removed).
 621   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the device.
 622   @retval Others                Failed to enumerate the device.
 623
 624 **/
 625 EFI_STATUS
 626 UsbEnumerateNewDev (
 627   IN USB_INTERFACE        *HubIf,
 628   IN UINT8                Port
 629   )
 630 {
 631   USB_BUS                 *Bus;
 632   USB_HUB_API             *HubApi;
 633   USB_DEVICE              *Child;
 634   USB_DEVICE              *Parent;
 635   EFI_USB_PORT_STATUS     PortState;
 636   UINT8                   Address;
 637   UINT8                   Config;
 638   EFI_STATUS              Status;
 639
 640   Address = USB_MAX_DEVICES;
 641   Parent  = HubIf->Device;
 642   Bus     = Parent->Bus;
 643   HubApi  = HubIf->HubApi;
 644
 645   gBS->Stall (USB_WAIT_PORT_STABLE_STALL);
 646
 647   //
 648   // Hub resets the device for at least 10 milliseconds.
 649   // Host learns device speed. If device is of low/full speed
 650   // and the hub is a EHCI root hub, ResetPort will release
 651   // the device to its companion UHCI and return an error.
 652   //
 653   Status = HubApi->ResetPort (HubIf, Port);
 654
 655   if (EFI_ERROR (Status)) {
 656     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to reset port %d - %r\n", Port, Status));
 657
 658     return Status;
 659   }
 660
 661   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: hub port %d is reset\n", Port));
 662
 663   Child = UsbCreateDevice (HubIf, Port);
 664
 665   if (Child == NULL) {
 666     return EFI_OUT_OF_RESOURCES;
 667   }
 668
 669   //
 670   // OK, now identify the device speed. After reset, hub
 671   // fully knows the actual device speed.
 672   //
 673   Status = HubApi->GetPortStatus (HubIf, Port, &PortState);
 674
 675   if (EFI_ERROR (Status)) {
 676     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to get speed of port %d\n", Port));
 677     goto ON_ERROR;
 678   }
 679
 680   if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_LOW_SPEED)) {
 681     Child->Speed = EFI_USB_SPEED_LOW;
 682
 683   } else if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_HIGH_SPEED)) {
 684     Child->Speed = EFI_USB_SPEED_HIGH;
 685
 686   } else {
 687     Child->Speed = EFI_USB_SPEED_FULL;
 688   }
 689
 690   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device is of %d speed\n", Child->Speed));
 691
 692   if (Child->Speed != EFI_USB_SPEED_HIGH) {
 693     //
 694     // If the child isn't a high speed device, it is necessary to
 695     // set the transaction translator. Port TT is 1-based.
 696     // This is quite simple:
 697     //  1. if parent is of high speed, then parent is our translator
 698     //  2. otherwise use parent's translator.
 699     //
 700     if (Parent->Speed == EFI_USB_SPEED_HIGH) {
 701       Child->Translator.TranslatorHubAddress  = Parent->Address;
 702       Child->Translator.TranslatorPortNumber  = (UINT8) (Port + 1);
 703
 704     } else {
 705       Child->Translator = Parent->Translator;
 706     }
 707
 708     DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device uses translator (%d, %d)\n",
 709                 Child->Translator.TranslatorHubAddress,
 710                 Child->Translator.TranslatorPortNumber));
 711   }
 712
 713   //
 714   // After port is reset, hub establishes a signal path between
 715   // the device and host (DEFALUT state). Device's registers are
 716   // reset, use default address 0 (host enumerates one device at
 717   // a time) , and ready to respond to control transfer at EP 0.
 718   //
 719
 720   //
 721   // Host sends a Get_Descriptor request to learn the max packet
 722   // size of default pipe (only part of the device's descriptor).
 723   //
 724   Status = UsbGetMaxPacketSize0 (Child);
 725
 726   if (EFI_ERROR (Status)) {
 727     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to get max packet for EP 0 - %r\n", Status));
 728     goto ON_ERROR;
 729   }
 730
 731   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: max packet size for EP 0 is %d\n", Child->MaxPacket0));
 732
 733   //
 734   // Host assigns an address to the device. Device completes the
 735   // status stage with default address, then switches to new address.
 736   // ADDRESS state. Address zero is reserved for root hub.
 737   //
 738   for (Address = 1; Address < USB_MAX_DEVICES; Address++) {
 739     if (Bus->Devices[Address] == NULL) {
 740       break;
 741     }
 742   }
 743
 744   if (Address == USB_MAX_DEVICES) {
 745     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: address pool is full for port %d\n", Port));
 746
 747     Status = EFI_ACCESS_DENIED;
 748     goto ON_ERROR;
 749   }
 750
 751   Bus->Devices[Address] = Child;
 752   Status                = UsbSetAddress (Child, Address);
 753   Child->Address        = Address;
 754
 755   if (EFI_ERROR (Status)) {
 756     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to set device address - %r\n", Status));
 757     goto ON_ERROR;
 758   }
 759
 760   gBS->Stall (USB_SET_DEVICE_ADDRESS_STALL);
 761
 762   DEBUG ((EFI_D_INFO, "UsbEnumerateNewDev: device is now ADDRESSED at %d\n", Address));
 763
 764   //
 765   // Host learns about the device's abilities by requesting device's
 766   // entire descriptions.
 767   //
 768   Status = UsbBuildDescTable (Child);
 769
 770   if (EFI_ERROR (Status)) {
 771     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to build descriptor table - %r\n", Status));
 772     goto ON_ERROR;
 773   }
 774
 775   //
 776   // Select a default configuration: UEFI must set the configuration
 777   // before the driver can connect to the device.
 778   //
 779   Config = Child->DevDesc->Configs[0]->Desc.ConfigurationValue;
 780   Status = UsbSetConfig (Child, Config);
 781
 782   if (EFI_ERROR (Status)) {
 783     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to set configure %d - %r\n", Config, Status));
 784     goto ON_ERROR;
 785   }
 786
 787   DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device %d is now in CONFIGED state\n", Address));
 788
 789   //
 790   // Host assigns and loads a device driver.
 791   //
 792   Status = UsbSelectConfig (Child, Config);
 793
 794   if (EFI_ERROR (Status)) {
 795     DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to create interfaces - %r\n", Status));
 796     goto ON_ERROR;
 797   }
 798
 799   return EFI_SUCCESS;
 800
 801 ON_ERROR:
 802   if (Address != USB_MAX_DEVICES) {
 803     Bus->Devices[Address] = NULL;
 804   }
 805
 806   if (Child != NULL) {
 807     UsbFreeDevice (Child);
 808   }
 809
 810   return Status;
 811 }
 812
 813
 814 /**
 815   Process the events on the port.
 816
 817   @param  HubIf                 The HUB that has the device connected.
 818   @param  Port                  The port index of the hub (started with zero).
 819
 820   @retval EFI_SUCCESS           The device is enumerated (added or removed).
 821   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the device.
 822   @retval Others                Failed to enumerate the device.
 823
 824 **/
 825 EFI_STATUS
 826 UsbEnumeratePort (
 827   IN USB_INTERFACE        *HubIf,
 828   IN UINT8                Port
 829   )
 830 {
 831   USB_HUB_API             *HubApi;
 832   USB_DEVICE              *Child;
 833   EFI_USB_PORT_STATUS     PortState;
 834   EFI_STATUS              Status;
 835
 836   Child   = NULL;
 837   HubApi  = HubIf->HubApi;
 838
 839   //
 840   // Host learns of the new device by polling the hub for port changes.
 841   //
 842   Status = HubApi->GetPortStatus (HubIf, Port, &PortState);
 843
 844   if (EFI_ERROR (Status)) {
 845     DEBUG ((EFI_D_ERROR, "UsbEnumeratePort: failed to get state of port %d\n", Port));
 846     return Status;
 847   }
 848
 849   if (PortState.PortChangeStatus == 0) {
 850     return EFI_SUCCESS;
 851   }
 852
 853   DEBUG (( EFI_D_INFO, "UsbEnumeratePort: port %d state - %x, change - %x\n",
 854               Port, PortState.PortStatus, PortState.PortChangeStatus));
 855
 856   //
 857   // This driver only process two kinds of events now: over current and
 858   // connect/disconnect. Other three events are: ENABLE, SUSPEND, RESET.
 859   // ENABLE/RESET is used to reset port. SUSPEND isn't supported.
 860   //
 861
 862   if (USB_BIT_IS_SET (PortState.PortChangeStatus, USB_PORT_STAT_C_OVERCURRENT)) {
 863
 864     if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_OVERCURRENT)) {
 865       //
 866       // Case1:
 867       //   Both OverCurrent and OverCurrentChange set, means over current occurs,
 868       //   which probably is caused by short circuit. It has to wait system hardware
 869       //   to perform recovery.
 870       //
 871       DEBUG (( EFI_D_ERROR, "UsbEnumeratePort: Critical Over Current\n", Port));
 872       return EFI_DEVICE_ERROR;
 873
 874     }
 875     //
 876     // Case2:
 877     //   Only OverCurrentChange set, means system has been recoveried from
 878     //   over current. As a result, all ports are nearly power-off, so
 879     //   it's necessary to detach and enumerate all ports again.
 880     //
 881     DEBUG (( EFI_D_ERROR, "UsbEnumeratePort: 2.0 device Recovery Over Current\n", Port));
 882   }
 883
 884   if (USB_BIT_IS_SET (PortState.PortChangeStatus, USB_PORT_STAT_C_ENABLE)) {
 885     //
 886     // Case3:
 887     //   1.1 roothub port reg doesn't reflect over-current state, while its counterpart
 888     //   on 2.0 roothub does. When over-current has influence on 1.1 device, the port
 889     //   would be disabled, so it's also necessary to detach and enumerate again.
 890     //
 891     DEBUG (( EFI_D_ERROR, "UsbEnumeratePort: 1.1 device Recovery Over Current\n", Port));
 892   }
 893
 894   if (USB_BIT_IS_SET (PortState.PortChangeStatus, USB_PORT_STAT_C_CONNECTION)) {
 895     //
 896     // Case4:
 897     //   Device connected or disconnected normally.
 898     //
 899     DEBUG ((EFI_D_ERROR, "UsbEnumeratePort: Device Connect/Discount Normally\n", Port));
 900   }
 901
 902   //
 903   // Following as the above cases, it's safety to remove and create again.
 904   //
 905   Child = UsbFindChild (HubIf, Port);
 906
 907   if (Child != NULL) {
 908     DEBUG (( EFI_D_INFO, "UsbEnumeratePort: device at port %d removed from system\n", Port));
 909     UsbRemoveDevice (Child);
 910   }
 911
 912   if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_CONNECTION)) {
 913     //
 914     // Now, new device connected, enumerate and configure the device
 915     //
 916     DEBUG (( EFI_D_INFO, "UsbEnumeratePort: new device connected at port %d\n", Port));
 917     Status = UsbEnumerateNewDev (HubIf, Port);
 918
 919   } else {
 920     DEBUG (( EFI_D_INFO, "UsbEnumeratePort: device disconnected event on port %d\n", Port));
 921   }
 922
 923   HubApi->ClearPortChange (HubIf, Port);
 924   return Status;
 925 }
 926
 927
 928 /**
 929   Enumerate all the changed hub ports.
 930
 931   @param  Event                 The event that is triggered.
 932   @param  Context               The context to the event.
 933
 934   @return None.
 935
 936 **/
 937 VOID
 938 EFIAPI
 939 UsbHubEnumeration (
 940   IN EFI_EVENT            Event,
 941   IN VOID                 *Context
 942   )
 943 {
 944   USB_INTERFACE           *HubIf;
 945   UINT8                   Byte;
 946   UINT8                   Bit;
 947   UINT8                   Index;
 948
 949   ASSERT (Context);
 950
 951   HubIf = (USB_INTERFACE *) Context;
 952
 953   if (HubIf->ChangeMap == NULL) {
 954     return ;
 955   }
 956
 957   //
 958   // HUB starts its port index with 1.
 959   //
 960   Byte  = 0;
 961   Bit   = 1;
 962
 963   for (Index = 0; Index < HubIf->NumOfPort; Index++) {
 964     if (USB_BIT_IS_SET (HubIf->ChangeMap[Byte], USB_BIT (Bit))) {
 965       UsbEnumeratePort (HubIf, Index);
 966     }
 967
 968     USB_NEXT_BIT (Byte, Bit);
 969   }
 970
 971   UsbHubAckHubStatus (HubIf->Device);
 972
 973   gBS->FreePool (HubIf->ChangeMap);
 974   HubIf->ChangeMap = NULL;
 975   return ;
 976 }
 977
 978
 979 /**
 980   Enumerate all the changed hub ports.
 981
 982   @param  Event                 The event that is triggered.
 983   @param  Context               The context to the event.
 984
 985   @return None.
 986
 987 **/
 988 VOID
 989 EFIAPI
 990 UsbRootHubEnumeration (
 991   IN EFI_EVENT            Event,
 992   IN VOID                 *Context
 993   )
 994 {
 995   USB_INTERFACE           *RootHub;
 996   UINT8                   Index;
 997
 998   RootHub = (USB_INTERFACE *) Context;
 999
1000   for (Index = 0; Index < RootHub->NumOfPort; Index++) {
1001     UsbEnumeratePort (RootHub, Index);
1002   }
1003 }