MdeModulePkg/Bus/Usb/UsbBusDxe/UsbHub.c

   1 /** @file
   2
   3 Copyright (c) 2007, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12   Module Name:
  13
  14     UsbHub.c
  15
  16   Abstract:
  17
  18     Unified interface for RootHub and Hub
  19
  20   Revision History
  21
  22
  23 **/
  24
  25 #include "UsbBus.h"
  26
  27 //
  28 // USB hub class specific requests. Although USB hub
  29 // is related to an interface, these requests are sent
  30 // to the control endpoint of the device.
  31 //
  32
  33
  34 /**
  35   USB hub control transfer to clear the hub feature
  36
  37   @param  HubDev                The device of the hub
  38   @param  Feature               The feature to clear
  39
  40   @retval EFI_SUCCESS           Feature of the hub is cleared
  41   @retval Others                Failed to clear the feature
  42
  43 **/
  44 STATIC
  45 EFI_STATUS
  46 UsbHubCtrlClearHubFeature (
  47   IN USB_DEVICE           *HubDev,
  48   IN UINT16               Feature
  49   )
  50 {
  51   EFI_STATUS              Status;
  52
  53   Status = UsbCtrlRequest (
  54              HubDev,
  55              EfiUsbNoData,
  56              USB_REQ_TYPE_CLASS,
  57              USB_HUB_TARGET_HUB,
  58              USB_HUB_REQ_CLEAR_FEATURE,
  59              Feature,
  60              0,
  61              NULL,
  62              0
  63              );
  64
  65   return Status;
  66 }
  67
  68
  69 /**
  70   Clear the feature of the device's port
  71
  72   @param  HubDev                The hub device
  73   @param  Port                  The port to clear feature
  74   @param  Feature               The feature to clear
  75
  76   @retval EFI_SUCCESS           The feature of the port is cleared.
  77   @retval Others                Failed to clear the feature.
  78
  79 **/
  80 STATIC
  81 EFI_STATUS
  82 UsbHubCtrlClearPortFeature (
  83   IN USB_DEVICE           *HubDev,
  84   IN UINT8                Port,
  85   IN UINT16               Feature
  86   )
  87 {
  88   EFI_STATUS              Status;
  89
  90   //
  91   // In USB bus, all the port index starts from 0. But HUB
  92   // indexes its port from 1. So, port number is added one.
  93   //
  94   Status = UsbCtrlRequest (
  95              HubDev,
  96              EfiUsbNoData,
  97              USB_REQ_TYPE_CLASS,
  98              USB_HUB_TARGET_PORT,
  99              USB_HUB_REQ_CLEAR_FEATURE,
 100              Feature,
 101              (UINT16) (Port + 1),
 102              NULL,
 103              0
 104              );
 105
 106   return Status;
 107 }
 108
 109
 110
 111 /**
 112   Clear the transaction translate buffer if full/low
 113   speed control/bulk transfer failed and the transfer
 114   uses this hub as translator.Remember to clear the TT
 115   buffer of transaction translator, not that of the
 116   parent.
 117
 118   @param  HubDev                The hub device
 119   @param  Port                  The port of the hub
 120   @param  DevAddr               Address of the failed transaction
 121   @param  EpNum                 The endpoint number of the failed transaction
 122   @param  EpType                The type of failed transaction
 123
 124   @retval EFI_SUCCESS           The TT buffer is cleared
 125   @retval Others                Failed to clear the TT buffer
 126
 127 **/
 128 EFI_STATUS
 129 UsbHubCtrlClearTTBuffer (
 130   IN USB_DEVICE           *HubDev,
 131   IN UINT8                Port,
 132   IN UINT16               DevAddr,
 133   IN UINT16               EpNum,
 134   IN UINT16               EpType
 135   )
 136 {
 137   EFI_STATUS              Status;
 138   UINT16                  Value;
 139
 140   //
 141   // Check USB2.0 spec page 424 for wValue's encoding
 142   //
 143   Value = (UINT16) ((EpNum & 0x0F) | (DevAddr << 4) |
 144           ((EpType & 0x03) << 11) | ((EpNum & 0x80) << 15));
 145
 146   Status = UsbCtrlRequest (
 147              HubDev,
 148              EfiUsbNoData,
 149              USB_REQ_TYPE_CLASS,
 150              USB_HUB_TARGET_PORT,
 151              USB_HUB_REQ_CLEAR_TT,
 152              Value,
 153              (UINT16) (Port + 1),
 154              NULL,
 155              0
 156              );
 157
 158   return Status;
 159 }
 160
 161
 162 /**
 163   Usb hub control transfer to get the hub descriptor
 164
 165   @param  HubDev                The hub device
 166   @param  Buf                   The buffer to hold the descriptor
 167   @param  Len                   The length to retrieve
 168
 169   @retval EFI_SUCCESS           The hub descriptor is retrieved
 170   @retval Others                Failed to retrieve the hub descriptor
 171
 172 **/
 173 STATIC
 174 EFI_STATUS
 175 UsbHubCtrlGetHubDesc (
 176   IN  USB_DEVICE          *HubDev,
 177   OUT VOID                *Buf,
 178   IN  UINTN               Len
 179   )
 180 {
 181   EFI_STATUS              Status;
 182
 183   Status = UsbCtrlRequest (
 184              HubDev,
 185              EfiUsbDataIn,
 186              USB_REQ_TYPE_CLASS,
 187              USB_HUB_TARGET_HUB,
 188              USB_HUB_REQ_GET_DESC,
 189              (UINT16) (USB_DESC_TYPE_HUB << 8),
 190              0,
 191              Buf,
 192              Len
 193              );
 194
 195   return Status;
 196 }
 197
 198
 199 /**
 200   Usb hub control transfer to get the hub status
 201
 202   @param  HubDev                The hub device
 203   @param  State                 The variable to return the status
 204
 205   @retval EFI_SUCCESS           The hub status is returned in State
 206   @retval Others                Failed to get the hub status
 207
 208 **/
 209 STATIC
 210 EFI_STATUS
 211 UsbHubCtrlGetHubStatus (
 212   IN  USB_DEVICE          *HubDev,
 213   OUT UINT32              *State
 214   )
 215 {
 216   EFI_STATUS              Status;
 217
 218   Status = UsbCtrlRequest (
 219              HubDev,
 220              EfiUsbDataIn,
 221              USB_REQ_TYPE_CLASS,
 222              USB_HUB_TARGET_HUB,
 223              USB_HUB_REQ_GET_STATUS,
 224              0,
 225              0,
 226              State,
 227              4
 228              );
 229
 230   return Status;
 231 }
 232
 233
 234 /**
 235   Usb hub control transfer to get the port status
 236
 237   @param  HubDev                The hub device
 238   @param  Port                  The port of the hub
 239   @param  State                 Variable to return the hub port state
 240
 241   @retval EFI_SUCCESS           The port state is returned in State
 242   @retval Others                Failed to retrive the port state
 243
 244 **/
 245 STATIC
 246 EFI_STATUS
 247 UsbHubCtrlGetPortStatus (
 248   IN  USB_DEVICE          *HubDev,
 249   IN  UINT8               Port,
 250   OUT VOID                *State
 251   )
 252 {
 253   EFI_STATUS              Status;
 254
 255   //
 256   // In USB bus, all the port index starts from 0. But HUB
 257   // indexes its port from 1. So, port number is added one.
 258   // No need to convert the hub bit to UEFI definition, they
 259   // are the same
 260   //
 261   Status = UsbCtrlRequest (
 262              HubDev,
 263              EfiUsbDataIn,
 264              USB_REQ_TYPE_CLASS,
 265              USB_HUB_TARGET_PORT,
 266              USB_HUB_REQ_GET_STATUS,
 267              0,
 268              (UINT16) (Port + 1),
 269              State,
 270              4
 271              );
 272
 273   return Status;
 274 }
 275
 276
 277 /**
 278   Usb hub control transfer to reset the TT (Transaction Transaltor)
 279
 280   @param  HubDev                The hub device
 281   @param  Port                  The port of the hub
 282
 283   @retval EFI_SUCCESS           The TT of the hub is reset
 284   @retval Others                Failed to reset the port
 285
 286 **/
 287 STATIC
 288 EFI_STATUS
 289 UsbHubCtrlResetTT (
 290   IN  USB_DEVICE          *HubDev,
 291   IN  UINT8               Port
 292   )
 293 {
 294   EFI_STATUS              Status;
 295
 296   Status = UsbCtrlRequest (
 297              HubDev,
 298              EfiUsbNoData,
 299              USB_REQ_TYPE_CLASS,
 300              USB_HUB_TARGET_HUB,
 301              USB_HUB_REQ_RESET_TT,
 302              0,
 303              (UINT16) (Port + 1),
 304              NULL,
 305              0
 306              );
 307
 308   return Status;
 309 }
 310
 311
 312 /**
 313   Usb hub control transfer to set the hub feature
 314
 315   @param  HubDev                The hub device
 316   @param  Feature               The feature to set
 317
 318   @retval EFI_SUCESS            The feature is set for the hub
 319   @retval Others                Failed to set the feature
 320
 321 **/
 322 STATIC
 323 EFI_STATUS
 324 UsbHubCtrlSetHubFeature (
 325   IN  USB_DEVICE          *HubDev,
 326   IN  UINT8               Feature
 327   )
 328 {
 329   EFI_STATUS              Status;
 330
 331   Status = UsbCtrlRequest (
 332              HubDev,
 333              EfiUsbNoData,
 334              USB_REQ_TYPE_CLASS,
 335              USB_HUB_TARGET_HUB,
 336              USB_HUB_REQ_SET_FEATURE,
 337              Feature,
 338              0,
 339              NULL,
 340              0
 341              );
 342
 343   return Status;
 344 }
 345
 346
 347 /**
 348   Usb hub control transfer to set the port feature
 349
 350   @param  HubDev                The Usb hub device
 351   @param  Port                  The Usb port to set feature for
 352   @param  Feature               The feature to set
 353
 354   @retval EFI_SUCCESS           The feature is set for the port
 355   @retval Others                Failed to set the feature
 356
 357 **/
 358 STATIC
 359 EFI_STATUS
 360 UsbHubCtrlSetPortFeature (
 361   IN USB_DEVICE           *HubDev,
 362   IN UINT8                Port,
 363   IN UINT8                Feature
 364   )
 365 {
 366   EFI_STATUS              Status;
 367
 368   //
 369   // In USB bus, all the port index starts from 0. But HUB
 370   // indexes its port from 1. So, port number is added one.
 371   //
 372   Status = UsbCtrlRequest (
 373              HubDev,
 374              EfiUsbNoData,
 375              USB_REQ_TYPE_CLASS,
 376              USB_HUB_TARGET_PORT,
 377              USB_HUB_REQ_SET_FEATURE,
 378              Feature,
 379              (UINT16) (Port + 1),
 380              NULL,
 381              0
 382              );
 383
 384   return Status;
 385 }
 386
 387
 388 /**
 389   Read the whole usb hub descriptor. It is necessary
 390   to do it in two steps because hub descriptor is of
 391   variable length
 392
 393   @param  HubDev                The hub device
 394   @param  HubDesc               The variable to return the descriptor
 395
 396   @retval EFI_SUCCESS           The hub descriptor is read
 397   @retval Others                Failed to read the hub descriptor
 398
 399 **/
 400 STATIC
 401 EFI_STATUS
 402 UsbHubReadDesc (
 403   IN  USB_DEVICE              *HubDev,
 404   OUT EFI_USB_HUB_DESCRIPTOR  *HubDesc
 405   )
 406 {
 407   EFI_STATUS              Status;
 408
 409   //
 410   // First get the hub descriptor length
 411   //
 412   Status = UsbHubCtrlGetHubDesc (HubDev, HubDesc, 2);
 413
 414   if (EFI_ERROR (Status)) {
 415     return Status;
 416   }
 417
 418   //
 419   // Get the whole hub descriptor
 420   //
 421   Status = UsbHubCtrlGetHubDesc (HubDev, HubDesc, HubDesc->Length);
 422
 423   return Status;
 424 }
 425
 426
 427
 428 /**
 429   Ack the hub change bits. If these bits are not ACKed, Hub will
 430   always return changed bit map from its interrupt endpoint.
 431
 432   @param  HubDev                The hub device
 433
 434   @retval EFI_SUCCESS           The hub change status is ACKed
 435   @retval Others                Failed to ACK the hub status
 436
 437 **/
 438 EFI_STATUS
 439 UsbHubAckHubStatus (
 440   IN  USB_DEVICE         *HubDev
 441   )
 442 {
 443   EFI_USB_PORT_STATUS     HubState;
 444   EFI_STATUS              Status;
 445
 446   Status = UsbHubCtrlGetHubStatus (HubDev, (UINT32 *) &HubState);
 447
 448   if (EFI_ERROR (Status)) {
 449     return Status;
 450   }
 451
 452   if (USB_BIT_IS_SET (HubState.PortChangeStatus, USB_HUB_STAT_C_LOCAL_POWER)) {
 453     UsbHubCtrlClearHubFeature (HubDev, USB_HUB_C_HUB_LOCAL_POWER);
 454   }
 455
 456   if (USB_BIT_IS_SET (HubState.PortChangeStatus, USB_HUB_STAT_C_OVER_CURRENT)) {
 457     UsbHubCtrlClearHubFeature (HubDev, USB_HUB_C_HUB_OVER_CURRENT);
 458   }
 459
 460   return EFI_SUCCESS;
 461 }
 462
 463
 464 /**
 465   Test whether the interface is a hub interface.
 466
 467   @param  UsbIf                 The interface to test
 468
 469   @retval TRUE                  The interface is a hub interface
 470   @retval FALSE                 The interface isn't a hub interface
 471
 472 **/
 473 BOOLEAN
 474 UsbIsHubInterface (
 475   IN USB_INTERFACE        *UsbIf
 476   )
 477 {
 478   EFI_USB_INTERFACE_DESCRIPTOR  *Setting;
 479
 480   //
 481   // If the hub is a high-speed hub with multiple TT,
 482   // the hub will has a default setting of single TT.
 483   //
 484   Setting = &UsbIf->IfSetting->Desc;
 485
 486   if ((Setting->InterfaceClass == USB_HUB_CLASS_CODE) &&
 487       (Setting->InterfaceSubClass == USB_HUB_SUBCLASS_CODE)) {
 488
 489     return TRUE;
 490   }
 491
 492   return FALSE;
 493 }
 494
 495
 496 /**
 497   The callback function to the USB hub status change
 498   interrupt endpoint. It is called periodically by
 499   the underlying host controller.
 500
 501   @param  Data                  The data read
 502   @param  DataLength            The length of the data read
 503   @param  Context               The context
 504   @param  Result                The result of the last interrupt transfer
 505
 506   @retval EFI_SUCCESS           The process is OK
 507   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource
 508
 509 **/
 510 STATIC
 511 EFI_STATUS
 512 UsbOnHubInterrupt (
 513   IN  VOID                *Data,
 514   IN  UINTN               DataLength,
 515   IN  VOID                *Context,
 516   IN  UINT32              Result
 517   )
 518 {
 519   USB_INTERFACE               *HubIf;
 520   EFI_USB_IO_PROTOCOL         *UsbIo;
 521   EFI_USB_ENDPOINT_DESCRIPTOR *EpDesc;
 522   EFI_STATUS                  Status;
 523
 524   HubIf   = (USB_INTERFACE *) Context;
 525   UsbIo   = &(HubIf->UsbIo);
 526   EpDesc  = &(HubIf->HubEp->Desc);
 527
 528   if (Result != EFI_USB_NOERROR) {
 529     //
 530     // If endpoint is stalled, clear the stall. Use UsbIo to access
 531     // the control transfer so internal status are maintained.
 532     //
 533     if (USB_BIT_IS_SET (Result, EFI_USB_ERR_STALL)) {
 534       UsbIoClearFeature (
 535         UsbIo,
 536         USB_TARGET_ENDPOINT,
 537         USB_FEATURE_ENDPOINT_HALT,
 538         EpDesc->EndpointAddress
 539         );
 540     }
 541
 542     //
 543     // Delete and submit a new async interrupt
 544     //
 545     Status = UsbIo->UsbAsyncInterruptTransfer (
 546                       UsbIo,
 547                       EpDesc->EndpointAddress,
 548                       FALSE,
 549                       0,
 550                       0,
 551                       NULL,
 552                       NULL
 553                       );
 554
 555     if (EFI_ERROR (Status)) {
 556       DEBUG (( EFI_D_ERROR, "UsbOnHubInterrupt: failed to remove async transfer - %r\n", Status));
 557       return Status;
 558     }
 559
 560     Status = UsbIo->UsbAsyncInterruptTransfer (
 561                       UsbIo,
 562                       EpDesc->EndpointAddress,
 563                       TRUE,
 564                       USB_HUB_POLL_INTERVAL,
 565                       HubIf->NumOfPort / 8 + 1,
 566                       UsbOnHubInterrupt,
 567                       HubIf
 568                       );
 569
 570     if (EFI_ERROR (Status)) {
 571       DEBUG (( EFI_D_ERROR, "UsbOnHubInterrupt: failed to submit new async transfer - %r\n", Status));
 572     }
 573
 574     return Status;
 575   }
 576
 577   if ((DataLength == 0) || (Data == NULL)) {
 578     return EFI_SUCCESS;
 579   }
 580
 581   //
 582   // OK, actually something is changed, save the change map
 583   // then signal the HUB to do enumeration. This is a good
 584   // practise since UsbOnHubInterrupt is called in the context
 585   // of host contrller's AsyncInterrupt monitor.
 586   //
 587   HubIf->ChangeMap = AllocateZeroPool (DataLength);
 588
 589   if (HubIf->ChangeMap == NULL) {
 590     return EFI_OUT_OF_RESOURCES;
 591   }
 592
 593   CopyMem (HubIf->ChangeMap, Data, DataLength);
 594   gBS->SignalEvent (HubIf->HubNotify);
 595
 596   return EFI_SUCCESS;
 597 }
 598
 599 //
 600 // Array that maps the change bit to feature value which is
 601 // used to clear these change bit. USB HUB API will clear
 602 // these change bit automatically. For non-root hub, these
 603 // bits determine whether hub will report the port in changed
 604 // bit maps.
 605 //
 606 #define USB_HUB_MAP_SIZE  5
 607
 608 USB_CHANGE_FEATURE_MAP  mHubFeatureMap[USB_HUB_MAP_SIZE] = {
 609   {USB_PORT_STAT_C_CONNECTION,  USB_HUB_C_PORT_CONNECT},
 610   {USB_PORT_STAT_C_ENABLE,      USB_HUB_C_PORT_ENABLE},
 611   {USB_PORT_STAT_C_SUSPEND,     USB_HUB_C_PORT_SUSPEND},
 612   {USB_PORT_STAT_C_OVERCURRENT, USB_HUB_C_PORT_OVER_CURRENT},
 613   {USB_PORT_STAT_C_RESET,       USB_HUB_C_PORT_RESET},
 614 };
 615
 616 #define USB_ROOT_HUB_MAP_SIZE 5
 617
 618 USB_CHANGE_FEATURE_MAP  mRootHubFeatureMap[USB_ROOT_HUB_MAP_SIZE] = {
 619   {USB_PORT_STAT_C_CONNECTION,  EfiUsbPortConnectChange},
 620   {USB_PORT_STAT_C_ENABLE,      EfiUsbPortEnableChange},
 621   {USB_PORT_STAT_C_SUSPEND,     EfiUsbPortSuspendChange},
 622   {USB_PORT_STAT_C_OVERCURRENT, EfiUsbPortOverCurrentChange},
 623   {USB_PORT_STAT_C_RESET,       EfiUsbPortResetChange},
 624 };
 625
 626
 627
 628 /**
 629   Initialize the device for a non-root hub
 630
 631   @param  HubIf                 The USB hub interface
 632
 633   @retval EFI_SUCCESS           The hub is initialized
 634   @retval EFI_DEVICE_ERROR      Failed to initialize the hub
 635
 636 **/
 637 STATIC
 638 EFI_STATUS
 639 UsbHubInit (
 640   IN USB_INTERFACE        *HubIf
 641   )
 642 {
 643   EFI_USB_HUB_DESCRIPTOR  HubDesc;
 644   USB_ENDPOINT_DESC       *EpDesc;
 645   USB_INTERFACE_SETTING   *Setting;
 646   EFI_USB_IO_PROTOCOL     *UsbIo;
 647   USB_DEVICE              *HubDev;
 648   EFI_STATUS              Status;
 649   UINT8                   Index;
 650
 651   //
 652   // Locate the interrupt endpoint for port change map
 653   //
 654   HubIf->IsHub  = FALSE;
 655   Setting       = HubIf->IfSetting;
 656   HubDev        = HubIf->Device;
 657   EpDesc        = NULL;
 658
 659   for (Index = 0; Index < Setting->Desc.NumEndpoints; Index++) {
 660     ASSERT ((Setting->Endpoints != NULL) && (Setting->Endpoints[Index] != NULL));
 661
 662     EpDesc = Setting->Endpoints[Index];
 663
 664     if (USB_BIT_IS_SET (EpDesc->Desc.EndpointAddress, USB_ENDPOINT_DIR_IN) &&
 665        (USB_ENDPOINT_TYPE (&EpDesc->Desc) == USB_ENDPOINT_INTERRUPT)) {
 666       break;
 667     }
 668   }
 669
 670   if (Index == Setting->Desc.NumEndpoints) {
 671     DEBUG (( EFI_D_ERROR, "UsbHubInit: no interrupt endpoint found for hub %d\n", HubDev->Address));
 672     return EFI_DEVICE_ERROR;
 673   }
 674
 675   Status = UsbHubReadDesc (HubDev, &HubDesc);
 676
 677   if (EFI_ERROR (Status)) {
 678     DEBUG (( EFI_D_ERROR, "UsbHubInit: failed to read HUB descriptor %r\n", Status));
 679     return Status;
 680   }
 681
 682   HubIf->NumOfPort = HubDesc.NumPorts;
 683
 684   DEBUG (( EFI_D_INFO, "UsbHubInit: hub %d has %d ports\n", HubDev->Address,HubIf->NumOfPort));
 685
 686   //
 687   // Create an event to enumerate the hub's port. On
 688   //
 689   Status = gBS->CreateEvent (
 690                   EVT_NOTIFY_SIGNAL,
 691                   TPL_CALLBACK,
 692                   UsbHubEnumeration,
 693                   HubIf,
 694                   &HubIf->HubNotify
 695                   );
 696
 697   if (EFI_ERROR (Status)) {
 698     DEBUG (( EFI_D_ERROR, "UsbHubInit: failed to create signal for hub %d - %r\n",
 699                 HubDev->Address, Status));
 700
 701     return Status;
 702   }
 703
 704   //
 705   // Create AsyncInterrupt to query hub port change endpoint
 706   // periodically. If the hub ports are changed, hub will return
 707   // changed port map from the interrupt endpoint. The port map
 708   // must be able to hold (HubIf->NumOfPort + 1) bits (one bit for
 709   // host change status).
 710   //
 711   UsbIo  = &HubIf->UsbIo;
 712   Status = UsbIo->UsbAsyncInterruptTransfer (
 713                     UsbIo,
 714                     EpDesc->Desc.EndpointAddress,
 715                     TRUE,
 716                     USB_HUB_POLL_INTERVAL,
 717                     HubIf->NumOfPort / 8 + 1,
 718                     UsbOnHubInterrupt,
 719                     HubIf
 720                     );
 721
 722   if (EFI_ERROR (Status)) {
 723     DEBUG (( EFI_D_ERROR, "UsbHubInit: failed to queue interrupt transfer for hub %d - %r\n",
 724                 HubDev->Address, Status));
 725
 726     gBS->CloseEvent (HubIf->HubNotify);
 727     HubIf->HubNotify = NULL;
 728
 729     return Status;
 730   }
 731
 732   //
 733   // OK, set IsHub to TRUE. Now usb bus can handle this device
 734   // as a working HUB. If failed eariler, bus driver will not
 735   // recognize it as a hub. Other parts of the bus should be able
 736   // to work.
 737   //
 738   HubIf->IsHub  = TRUE;
 739   HubIf->HubApi = &mUsbHubApi;
 740   HubIf->HubEp  = EpDesc;
 741
 742   //
 743   // Feed power to all the hub ports. It should be ok
 744   // for both gang/individual powered hubs.
 745   //
 746   for (Index = 0; Index < HubDesc.NumPorts; Index++) {
 747     UsbHubCtrlSetPortFeature (HubIf->Device, Index, (EFI_USB_PORT_FEATURE) USB_HUB_PORT_POWER);
 748   }
 749
 750   gBS->Stall (HubDesc.PwrOn2PwrGood * 2 * USB_STALL_1_MS);
 751   UsbHubAckHubStatus (HubIf->Device);
 752
 753   DEBUG (( EFI_D_INFO, "UsbHubInit: hub %d initialized\n", HubDev->Address));
 754   return Status;
 755 }
 756
 757
 758
 759 /**
 760   Get the port status. This function is required to
 761   ACK the port change bits although it will return
 762   the port changes in PortState. Bus enumeration code
 763   doesn't need to ACK the port change bits.
 764
 765   @param  HubIf                 The hub interface
 766   @param  Port                  The port of the hub to get state
 767   @param  PortState             Variable to return the port state
 768
 769   @retval EFI_SUCCESS           The port status is successfully returned
 770   @retval Others                Failed to return the status
 771
 772 **/
 773 STATIC
 774 EFI_STATUS
 775 UsbHubGetPortStatus (
 776   IN  USB_INTERFACE       *HubIf,
 777   IN  UINT8               Port,
 778   OUT EFI_USB_PORT_STATUS *PortState
 779   )
 780 {
 781   EFI_STATUS              Status;
 782
 783   Status  = UsbHubCtrlGetPortStatus (HubIf->Device, Port, PortState);
 784
 785   return Status;
 786 }
 787
 788
 789
 790 /**
 791   Clear the port change status.
 792
 793   @param  HubIf                 The hub interface
 794   @param  Port                  The hub port
 795
 796   @return None
 797
 798 **/
 799 STATIC
 800 VOID
 801 UsbHubClearPortChange (
 802   IN USB_INTERFACE        *HubIf,
 803   IN UINT8                Port
 804   )
 805 {
 806   EFI_USB_PORT_STATUS     PortState;
 807   USB_CHANGE_FEATURE_MAP  *Map;
 808   UINTN                   Index;
 809   EFI_STATUS              Status;
 810
 811   Status = UsbHubGetPortStatus (HubIf, Port, &PortState);
 812
 813   if (EFI_ERROR (Status)) {
 814     return;
 815   }
 816
 817   //
 818   // OK, get the usb port status, now ACK the change bits.
 819   // Don't return error when failed to clear the change bits.
 820   // It may lead to extra port state report. USB bus should
 821   // be able to handle this.
 822   //
 823   for (Index = 0; Index < USB_HUB_MAP_SIZE; Index++) {
 824     Map = &mHubFeatureMap[Index];
 825
 826     if (USB_BIT_IS_SET (PortState.PortChangeStatus, Map->ChangedBit)) {
 827       UsbHubCtrlClearPortFeature (HubIf->Device, Port, Map->Feature);
 828     }
 829   }
 830 }
 831
 832
 833
 834 /**
 835   Function to set the port feature for non-root hub
 836
 837   @param  HubIf                 The hub interface
 838   @param  Port                  The port of the hub
 839   @param  Feature               The feature of the port to set
 840
 841   @retval EFI_SUCCESS           The hub port feature is set
 842   @retval Others                Failed to set the port feature
 843
 844 **/
 845 STATIC
 846 EFI_STATUS
 847 UsbHubSetPortFeature (
 848   IN USB_INTERFACE        *HubIf,
 849   IN UINT8                Port,
 850   IN EFI_USB_PORT_FEATURE Feature
 851   )
 852 {
 853   EFI_STATUS              Status;
 854
 855   Status = UsbHubCtrlSetPortFeature (HubIf->Device, Port, (UINT8) Feature);
 856
 857   return Status;
 858 }
 859
 860
 861 /**
 862   Interface function to clear the port feature for non-root hub
 863
 864   @param  HubIf                 The hub interface
 865   @param  Port                  The port of the hub to clear feature for
 866   @param  Feature               The feature to clear
 867
 868   @retval EFI_SUCCESS           The port feature is cleared
 869   @retval Others                Failed to clear the port feature
 870
 871 **/
 872 STATIC
 873 EFI_STATUS
 874 UsbHubClearPortFeature (
 875   IN USB_INTERFACE        *HubIf,
 876   IN UINT8                Port,
 877   IN EFI_USB_PORT_FEATURE Feature
 878   )
 879 {
 880   EFI_STATUS              Status;
 881
 882   Status = UsbHubCtrlClearPortFeature (HubIf->Device, Port, (UINT8) Feature);
 883
 884   return Status;
 885 }
 886
 887
 888 /**
 889   Interface funtion to reset the port
 890
 891   @param  HubIf                 The hub interface
 892   @param  Port                  The port to reset
 893
 894   @retval EFI_SUCCESS           The hub port is reset
 895   @retval EFI_TIMEOUT           Failed to reset the port in time
 896   @retval Others                Failed to reset the port
 897
 898 **/
 899 STATIC
 900 EFI_STATUS
 901 UsbHubResetPort (
 902   IN USB_INTERFACE        *HubIf,
 903   IN UINT8                Port
 904   )
 905 {
 906   EFI_USB_PORT_STATUS     PortState;
 907   UINTN                   Index;
 908   EFI_STATUS              Status;
 909
 910   Status  = UsbHubSetPortFeature (HubIf, Port, (EFI_USB_PORT_FEATURE) USB_HUB_PORT_RESET);
 911
 912   if (EFI_ERROR (Status)) {
 913     return Status;
 914   }
 915
 916   //
 917   // Drive the reset signal for at least 10ms. Check USB 2.0 Spec
 918   // section 7.1.7.5 for timing requirements.
 919   //
 920   gBS->Stall (20 * USB_STALL_1_MS);
 921
 922   //
 923   // USB hub will clear RESET bit if reset is actually finished.
 924   //
 925   ZeroMem (&PortState, sizeof (EFI_USB_PORT_STATUS));
 926
 927   for (Index = 0; Index < 20; Index++) {
 928     Status = UsbHubGetPortStatus (HubIf, Port, &PortState);
 929
 930     if (!EFI_ERROR (Status) &&
 931         !USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_RESET)) {
 932
 933       return EFI_SUCCESS;
 934     }
 935
 936     gBS->Stall (5 * USB_STALL_1_MS);
 937   }
 938
 939   return EFI_TIMEOUT;
 940 }
 941
 942
 943 /**
 944   Release the hub's control of the interface
 945
 946   @param  HubIf                 The hub interface
 947
 948   @retval EFI_SUCCESS           The interface is release of hub control
 949
 950 **/
 951 STATIC
 952 EFI_STATUS
 953 UsbHubRelease (
 954   IN USB_INTERFACE        *HubIf
 955   )
 956 {
 957   EFI_USB_IO_PROTOCOL     *UsbIo;
 958   EFI_STATUS              Status;
 959
 960   UsbIo  = &HubIf->UsbIo;
 961   Status = UsbIo->UsbAsyncInterruptTransfer (
 962                     UsbIo,
 963                     HubIf->HubEp->Desc.EndpointAddress,
 964                     FALSE,
 965                     USB_HUB_POLL_INTERVAL,
 966                     0,
 967                     NULL,
 968                     0
 969                     );
 970
 971   if (EFI_ERROR (Status)) {
 972     return Status;
 973   }
 974
 975   gBS->CloseEvent (HubIf->HubNotify);
 976
 977   HubIf->IsHub      = FALSE;
 978   HubIf->HubApi     = NULL;
 979   HubIf->HubEp      = NULL;
 980   HubIf->HubNotify  = NULL;
 981
 982   DEBUG (( EFI_D_INFO, "UsbHubRelease: hub device %d released\n", HubIf->Device->Address));
 983   return EFI_SUCCESS;
 984 }
 985
 986
 987
 988 /**
 989   Initialize the interface for root hub
 990
 991   @param  HubIf                 The root hub interface
 992
 993   @retval EFI_SUCCESS           The interface is initialied for root hub
 994   @retval Others                Failed to initialize the hub
 995
 996 **/
 997 STATIC
 998 EFI_STATUS
 999 UsbRootHubInit (
1000   IN USB_INTERFACE        *HubIf
1001   )
1002 {
1003   EFI_STATUS              Status;
1004   UINT8                   MaxSpeed;
1005   UINT8                   NumOfPort;
1006   UINT8                   Support64;
1007
1008   Status = UsbHcGetCapability (HubIf->Device->Bus, &MaxSpeed, &NumOfPort, &Support64);
1009
1010   if (EFI_ERROR (Status)) {
1011     return Status;
1012   }
1013
1014   DEBUG (( EFI_D_INFO, "UsbRootHubInit: root hub %x - max speed %d, %d ports\n",
1015               HubIf, MaxSpeed, NumOfPort));
1016
1017   HubIf->IsHub      = TRUE;
1018   HubIf->HubApi     = &mUsbRootHubApi;
1019   HubIf->HubEp      = NULL;
1020   HubIf->MaxSpeed   = MaxSpeed;
1021   HubIf->NumOfPort  = NumOfPort;
1022   HubIf->HubNotify  = NULL;
1023
1024   //
1025   // Create a timer to poll root hub ports periodically
1026   //
1027   Status = gBS->CreateEvent (
1028                   EVT_TIMER | EVT_NOTIFY_SIGNAL,
1029                   TPL_CALLBACK,
1030                   UsbRootHubEnumeration,
1031                   HubIf,
1032                   &HubIf->HubNotify
1033                   );
1034
1035   if (EFI_ERROR (Status)) {
1036     return Status;
1037   }
1038
1039   //
1040   // It should signal the event immediately here, or device detection
1041   // by bus enumeration might be delayed by the timer interval.
1042   //
1043   gBS->SignalEvent (HubIf->HubNotify);
1044
1045   Status = gBS->SetTimer (
1046                   HubIf->HubNotify,
1047                   TimerPeriodic,
1048                   USB_ROOTHUB_POLL_INTERVAL
1049                   );
1050
1051   if (EFI_ERROR (Status)) {
1052     gBS->CloseEvent (HubIf->HubNotify);
1053   }
1054
1055   return Status;
1056 }
1057
1058
1059
1060 /**
1061   Get the port status. This function is required to
1062   ACK the port change bits although it will return
1063   the port changes in PortState. Bus enumeration code
1064   doesn't need to ACK the port change bits.
1065
1066   @param  HubIf                 The root hub interface
1067   @param  Port                  The root hub port to get the state
1068   @param  PortState             Variable to return the port state
1069
1070   @retval EFI_SUCCESS           The port state is returned
1071   @retval Others                Failed to retrieve the port state
1072
1073 **/
1074 STATIC
1075 EFI_STATUS
1076 UsbRootHubGetPortStatus (
1077   IN  USB_INTERFACE       *HubIf,
1078   IN  UINT8               Port,
1079   OUT EFI_USB_PORT_STATUS *PortState
1080   )
1081 {
1082   USB_BUS                 *Bus;
1083   EFI_STATUS              Status;
1084
1085   Bus     = HubIf->Device->Bus;
1086   Status  = UsbHcGetRootHubPortStatus (Bus, Port, PortState);
1087
1088   return Status;
1089 }
1090
1091
1092 /**
1093   Clear the port change status.
1094
1095   @param  HubIf                 The root hub interface
1096   @param  Port                  The root hub port
1097
1098   @retval EFI_SUCCESS           The port state is returned
1099   @retval Others                Failed to retrieve the port state
1100
1101 **/
1102 STATIC
1103 VOID
1104 UsbRootHubClearPortChange (
1105   IN USB_INTERFACE        *HubIf,
1106   IN UINT8                Port
1107   )
1108 {
1109   EFI_USB_PORT_STATUS     PortState;
1110   USB_CHANGE_FEATURE_MAP  *Map;
1111   UINTN                   Index;
1112   EFI_STATUS              Status;
1113
1114   Status = UsbRootHubGetPortStatus (HubIf, Port, &PortState);
1115
1116   if (EFI_ERROR (Status)) {
1117     return;
1118   }
1119
1120   //
1121   // OK, get the usb port status, now ACK the change bits.
1122   // Don't return error when failed to clear the change bits.
1123   // It may lead to extra port state report. USB bus should
1124   // be able to handle this.
1125   //
1126   for (Index = 0; Index < USB_ROOT_HUB_MAP_SIZE; Index++) {
1127     Map = &mRootHubFeatureMap[Index];
1128
1129     if (USB_BIT_IS_SET (PortState.PortChangeStatus, Map->ChangedBit)) {
1130       UsbHcClearRootHubPortFeature (HubIf->Device->Bus, Port, (EFI_USB_PORT_FEATURE) Map->Feature);
1131     }
1132   }
1133 }
1134
1135
1136
1137 /**
1138   Set the root hub port feature
1139
1140   @param  HubIf                 The Usb hub interface
1141   @param  Port                  The hub port
1142   @param  Feature               The feature to set
1143
1144   @retval EFI_SUCCESS           The root hub port is set with the feature
1145   @retval Others                Failed to set the feature
1146
1147 **/
1148 STATIC
1149 EFI_STATUS
1150 UsbRootHubSetPortFeature (
1151   IN USB_INTERFACE        *HubIf,
1152   IN UINT8                Port,
1153   IN EFI_USB_PORT_FEATURE Feature
1154   )
1155 {
1156   EFI_STATUS              Status;
1157
1158   Status  = UsbHcSetRootHubPortFeature (HubIf->Device->Bus, Port, Feature);
1159
1160   return Status;
1161 }
1162
1163
1164 /**
1165   Clear the root hub port feature
1166
1167   @param  HubIf                 The root hub interface
1168   @param  Port                  The root hub port
1169   @param  Feature               The feature to clear
1170
1171   @retval EFI_SUCCESS           The root hub port is cleared of the feature
1172   @retval Others                Failed to clear the feature
1173
1174 **/
1175 STATIC
1176 EFI_STATUS
1177 UsbRootHubClearPortFeature (
1178   IN USB_INTERFACE        *HubIf,
1179   IN UINT8                Port,
1180   IN EFI_USB_PORT_FEATURE Feature
1181   )
1182 {
1183   EFI_STATUS              Status;
1184
1185   Status  = UsbHcClearRootHubPortFeature (HubIf->Device->Bus, Port, Feature);
1186
1187   return Status;
1188 }
1189
1190
1191 /**
1192   Interface funtion to reset the root hub port
1193
1194   @param  RootIf                The root hub interface
1195   @param  Port                  The port to reset
1196
1197   @retval EFI_SUCCESS           The hub port is reset
1198   @retval EFI_TIMEOUT           Failed to reset the port in time
1199   @retval EFI_NOT_FOUND         The low/full speed device connected to high  speed
1200                                 root hub is released to the companion UHCI
1201   @retval Others                Failed to reset the port
1202
1203 **/
1204 STATIC
1205 EFI_STATUS
1206 UsbRootHubResetPort (
1207   IN USB_INTERFACE        *RootIf,
1208   IN UINT8                Port
1209   )
1210 {
1211   USB_BUS                 *Bus;
1212   EFI_STATUS              Status;
1213   EFI_USB_PORT_STATUS     PortState;
1214   UINTN                   Index;
1215
1216   //
1217   // Notice: although EHCI requires that ENABLED bit be cleared
1218   // when reset the port, we don't need to care that here. It
1219   // should be handled in the EHCI driver.
1220   //
1221   Bus     = RootIf->Device->Bus;
1222   Status  = UsbHcSetRootHubPortFeature (Bus, Port, EfiUsbPortReset);
1223
1224   if (EFI_ERROR (Status)) {
1225     DEBUG (( EFI_D_ERROR, "UsbRootHubResetPort: failed to start reset on port %d\n", Port));
1226     return Status;
1227   }
1228
1229   //
1230   // Drive the reset signal for at least 50ms. Check USB 2.0 Spec
1231   // section 7.1.7.5 for timing requirements.
1232   //
1233   gBS->Stall (50 * USB_STALL_1_MS);
1234
1235   Status = UsbHcClearRootHubPortFeature (Bus, Port, EfiUsbPortReset);
1236
1237   if (EFI_ERROR (Status)) {
1238     DEBUG (( EFI_D_ERROR, "UsbRootHubResetPort: failed to clear reset on port %d\n", Port));
1239     return Status;
1240   }
1241
1242   gBS->Stall (USB_STALL_1_MS);
1243
1244   //
1245   // USB host controller won't clear the RESET bit until
1246   // reset is actually finished.
1247   //
1248   ZeroMem (&PortState, sizeof (EFI_USB_PORT_STATUS));
1249
1250   for (Index = 0; Index < USB_HUB_LOOP; Index++) {
1251     Status = UsbHcGetRootHubPortStatus (Bus, Port, &PortState);
1252
1253     if (EFI_ERROR (Status)) {
1254       return Status;
1255     }
1256
1257     if (!USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_RESET)) {
1258       break;
1259     }
1260
1261     gBS->Stall (10 * USB_STALL_1_MS);
1262   }
1263
1264   if (Index == USB_HUB_LOOP) {
1265     DEBUG (( EFI_D_ERROR, "UsbRootHubResetPort: reset not finished in time on port %d\n", Port));
1266     return EFI_TIMEOUT;
1267   }
1268
1269   if (!USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_ENABLE)) {
1270     //
1271     // OK, the port is reset. If root hub is of high speed and
1272     // the device is of low/full speed, release the ownership to
1273     // companion UHCI. If root hub is of full speed, it won't
1274     // automatically enable the port, we need to enable it manually.
1275     //
1276     if (RootIf->MaxSpeed == EFI_USB_SPEED_HIGH) {
1277       DEBUG (( EFI_D_ERROR, "UsbRootHubResetPort: release low/full speed device (%d) to UHCI\n", Port));
1278
1279       UsbRootHubSetPortFeature (RootIf, Port, EfiUsbPortOwner);
1280       return EFI_NOT_FOUND;
1281
1282     } else {
1283
1284       Status = UsbRootHubSetPortFeature (RootIf, Port, EfiUsbPortEnable);
1285
1286       if (EFI_ERROR (Status)) {
1287         DEBUG (( EFI_D_ERROR, "UsbRootHubResetPort: failed to enable port %d for UHCI\n", Port));
1288         return Status;
1289       }
1290
1291       gBS->Stall (20 * USB_STALL_1_MS);
1292     }
1293   }
1294
1295   return EFI_SUCCESS;
1296 }
1297
1298
1299 /**
1300   Release the root hub's control of the interface
1301
1302   @param  HubIf                 The root hub interface
1303
1304   @retval EFI_SUCCESS           The root hub's control of the interface is
1305                                 released.
1306
1307 **/
1308 STATIC
1309 EFI_STATUS
1310 UsbRootHubRelease (
1311   IN USB_INTERFACE        *HubIf
1312   )
1313 {
1314   DEBUG (( EFI_D_INFO, "UsbRootHubRelease: root hub released for hub %x\n", HubIf));
1315
1316   gBS->SetTimer (HubIf->HubNotify, TimerCancel, USB_ROOTHUB_POLL_INTERVAL);
1317   gBS->CloseEvent (HubIf->HubNotify);
1318
1319   return EFI_SUCCESS;
1320 }
1321
1322 USB_HUB_API mUsbHubApi = {
1323   UsbHubInit,
1324   UsbHubGetPortStatus,
1325   UsbHubClearPortChange,
1326   UsbHubSetPortFeature,
1327   UsbHubClearPortFeature,
1328   UsbHubResetPort,
1329   UsbHubRelease
1330 };
1331
1332 USB_HUB_API mUsbRootHubApi = {
1333   UsbRootHubInit,
1334   UsbRootHubGetPortStatus,
1335   UsbRootHubClearPortChange,
1336   UsbRootHubSetPortFeature,
1337   UsbRootHubClearPortFeature,
1338   UsbRootHubResetPort,
1339   UsbRootHubRelease
1340 };