edk2/EdkCompatibilityPkg/Foundation/Protocol/Performance/Performance.h:

[mirror_edk2.git] / MdeModulePkg / Bus / Usb / UsbBusDxe / UsbEnumer.c

/** @file\r
\r
Copyright (c) 2007, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
  Module Name:\r
\r
    UsbEnumer.c\r
\r
  Abstract:\r
\r
    Usb bus enumeration support\r
\r
  Revision History\r
\r
\r
**/\r
\r
#include "UsbBus.h"\r
\r
\r
/**\r
  Return the endpoint descriptor in this interface\r
\r
  @param  UsbIf                 The interface to search in\r
  @param  EpAddr                The address of the endpoint to return\r
\r
  @return The endpoint descriptor or NULL\r
\r
**/\r
USB_ENDPOINT_DESC *\r
UsbGetEndpointDesc (\r
  IN USB_INTERFACE        *UsbIf,\r
  IN UINT8                EpAddr\r
  )\r
{\r
  USB_ENDPOINT_DESC       *EpDesc;\r
  UINTN                   Index;\r
\r
  for (Index = 0; Index < UsbIf->IfSetting->Desc.NumEndpoints; Index++) {\r
    EpDesc = UsbIf->IfSetting->Endpoints[Index];\r
\r
    if (EpDesc->Desc.EndpointAddress == EpAddr) {\r
      return EpDesc;\r
    }\r
  }\r
\r
  return NULL;\r
}\r
\r
\r
/**\r
  Free the resource used by USB interface\r
\r
  @param  UsbIf                 The USB interface to free\r
\r
  @return None\r
\r
**/\r
STATIC\r
VOID\r
UsbFreeInterface (\r
  IN USB_INTERFACE        *UsbIf\r
  )\r
{\r
  UsbCloseHostProtoByChild (UsbIf->Device->Bus, UsbIf->Handle);\r
\r
  gBS->UninstallMultipleProtocolInterfaces (\r
         UsbIf->Handle,\r
         &gEfiDevicePathProtocolGuid,\r
         UsbIf->DevicePath,\r
         &gEfiUsbIoProtocolGuid,\r
         &UsbIf->UsbIo,\r
         NULL\r
         );\r
\r
  if (UsbIf->DevicePath != NULL) {\r
    gBS->FreePool (UsbIf->DevicePath);\r
  }\r
\r
  gBS->FreePool (UsbIf);\r
}\r
\r
\r
/**\r
  Create an interface for the descriptor IfDesc. Each\r
  device's configuration can have several interfaces.\r
\r
  @param  Device                The device has the interface descriptor\r
  @param  IfDesc                The interface descriptor\r
\r
  @return The created USB interface for the descriptor, or NULL.\r
\r
**/\r
STATIC\r
USB_INTERFACE *\r
UsbCreateInterface (\r
  IN USB_DEVICE           *Device,\r
  IN USB_INTERFACE_DESC   *IfDesc\r
  )\r
{\r
  USB_DEVICE_PATH         UsbNode;\r
  USB_INTERFACE           *UsbIf;\r
  USB_INTERFACE           *HubIf;\r
  EFI_STATUS              Status;\r
\r
  UsbIf = AllocateZeroPool (sizeof (USB_INTERFACE));\r
\r
  if (UsbIf == NULL) {\r
    return NULL;\r
  }\r
\r
  UsbIf->Signature  = USB_INTERFACE_SIGNATURE;\r
  UsbIf->Device     = Device;\r
  UsbIf->IfDesc     = IfDesc;\r
  UsbIf->IfSetting  = IfDesc->Settings[IfDesc->ActiveIndex];\r
\r
  CopyMem (\r
    &(UsbIf->UsbIo),\r
    &mUsbIoProtocol,\r
    sizeof (EFI_USB_IO_PROTOCOL)\r
    );\r
\r
  //\r
  // Install protocols for USBIO and device path\r
  //\r
  UsbNode.Header.Type       = MESSAGING_DEVICE_PATH;\r
  UsbNode.Header.SubType    = MSG_USB_DP;\r
  UsbNode.ParentPortNumber  = Device->ParentPort;\r
  UsbNode.InterfaceNumber   = UsbIf->IfSetting->Desc.InterfaceNumber;\r
\r
  SetDevicePathNodeLength (&UsbNode.Header, sizeof (UsbNode));\r
\r
  HubIf = Device->ParentIf;\r
  ASSERT (HubIf != NULL);\r
\r
  UsbIf->DevicePath = AppendDevicePathNode (HubIf->DevicePath, &UsbNode.Header);\r
\r
  if (UsbIf->DevicePath == NULL) {\r
    DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to create device path\n"));\r
\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto ON_ERROR;\r
  }\r
\r
  Status = gBS->InstallMultipleProtocolInterfaces (\r
                  &UsbIf->Handle,\r
                  &gEfiDevicePathProtocolGuid,\r
                  UsbIf->DevicePath,\r
                  &gEfiUsbIoProtocolGuid,\r
                  &UsbIf->UsbIo,\r
                  NULL\r
                  );\r
\r
  if (EFI_ERROR (Status)) {\r
    DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to install UsbIo - %r\n", Status));\r
    goto ON_ERROR;\r
  }\r
\r
  //\r
  // Open USB Host Controller Protocol by Child\r
  //\r
  Status = UsbOpenHostProtoByChild (Device->Bus, UsbIf->Handle);\r
\r
  if (EFI_ERROR (Status)) {\r
    gBS->UninstallMultipleProtocolInterfaces (\r
           &UsbIf->Handle,\r
           &gEfiDevicePathProtocolGuid,\r
           UsbIf->DevicePath,\r
           &gEfiUsbIoProtocolGuid,\r
           &UsbIf->UsbIo,\r
           NULL\r
           );\r
\r
    DEBUG ((EFI_D_ERROR, "UsbCreateInterface: failed to open host for child - %r\n", Status));\r
    goto ON_ERROR;\r
  }\r
\r
  return UsbIf;\r
\r
ON_ERROR:\r
  if (UsbIf->DevicePath) {\r
    gBS->FreePool (UsbIf->DevicePath);\r
  }\r
\r
  gBS->FreePool (UsbIf);\r
  return NULL;\r
}\r
\r
\r
/**\r
  Free the resource used by this USB device\r
\r
  @param  Device                The USB device to free\r
\r
  @return None\r
\r
**/\r
STATIC\r
VOID\r
UsbFreeDevice (\r
  IN USB_DEVICE           *Device\r
  )\r
{\r
  if (Device->DevDesc != NULL) {\r
    UsbFreeDevDesc (Device->DevDesc);\r
  }\r
\r
  gBS->FreePool (Device);\r
}\r
\r
\r
/**\r
  Create a device which is on the parent's ParentPort port.\r
\r
  @param  ParentIf              The parent HUB interface\r
  @param  ParentPort            The port on the HUB this device is connected to\r
\r
  @return Created USB device\r
\r
**/\r
STATIC\r
USB_DEVICE *\r
UsbCreateDevice (\r
  IN USB_INTERFACE        *ParentIf,\r
  IN UINT8                ParentPort\r
  )\r
{\r
  USB_DEVICE              *Device;\r
\r
  ASSERT (ParentIf != NULL);\r
\r
  Device = AllocateZeroPool (sizeof (USB_DEVICE));\r
\r
  if (Device == NULL) {\r
    return NULL;\r
  }\r
\r
  Device->Bus         = ParentIf->Device->Bus;\r
  Device->MaxPacket0  = 8;\r
  Device->ParentAddr  = ParentIf->Device->Address;\r
  Device->ParentIf    = ParentIf;\r
  Device->ParentPort  = ParentPort;\r
  return Device;\r
}\r
\r
\r
/**\r
  Connect the USB interface with its driver. EFI USB bus will\r
  create a USB interface for each seperate interface descriptor.\r
\r
  @param  UsbIf                 The interface to connect driver to\r
\r
  @return EFI_SUCCESS : Interface is managed by some driver\r
  @return Others      : Failed to locate a driver for this interface\r
\r
**/\r
STATIC\r
EFI_STATUS\r
UsbConnectDriver (\r
  IN USB_INTERFACE        *UsbIf\r
  )\r
{\r
  EFI_STATUS              Status;\r
  EFI_TPL                 OldTpl;\r
\r
  Status = EFI_SUCCESS;\r
\r
  //\r
  // Hub is maintained by the USB bus driver. Otherwise try to\r
  // connect drivers with this interface\r
  //\r
  if (UsbIsHubInterface (UsbIf)) {\r
    DEBUG ((EFI_D_INFO, "UsbConnectDriver: found a hub device\n"));\r
    Status = mUsbHubApi.Init (UsbIf);\r
\r
  } else {\r
    //\r
    // This function is called in both UsbIoControlTransfer and\r
    // the timer callback in hub enumeration. So, at least it is\r
    // called at TPL_CALLBACK. Some driver sitting on USB has\r
    // twisted TPL used. It should be no problem for us to connect\r
    // or disconnect at CALLBACK.\r
    //\r
    \r
    //\r
    // Only recursively wanted usb child device\r
    //\r
    if (UsbBusIsWantedUsbIO (UsbIf->Device->Bus, UsbIf)) {\r
      OldTpl            = UsbGetCurrentTpl ();\r
      DEBUG ((EFI_D_INFO, "UsbConnectDriver: TPL before connect is %d\n", OldTpl));\r
\r
      gBS->RestoreTPL (TPL_CALLBACK);\r
\r
      Status            = gBS->ConnectController (UsbIf->Handle, NULL, NULL, TRUE);\r
      UsbIf->IsManaged  = (BOOLEAN)!EFI_ERROR (Status);\r
\r
      DEBUG ((EFI_D_INFO, "UsbConnectDriver: TPL after connect is %d\n", UsbGetCurrentTpl()));\r
      ASSERT (UsbGetCurrentTpl () == TPL_CALLBACK);\r
\r
      gBS->RaiseTPL (OldTpl);\r
    }\r
  }\r
\r
  return Status;\r
}\r
\r
\r
/**\r
  Select an alternate setting for the interface.\r
  Each interface can have several mutually exclusive\r
  settings. Only one setting is active. It will\r
  also reset its endpoints' toggle to zero.\r
\r
  @param  IfDesc                The interface descriptor to set\r
  @param  Alternate             The alternate setting number to locate\r
\r
  @retval EFI_NOT_FOUND         There is no setting with this alternate index\r
  @retval EFI_SUCCESS           The interface is set to Alternate setting.\r
\r
**/\r
EFI_STATUS\r
UsbSelectSetting (\r
  IN USB_INTERFACE_DESC   *IfDesc,\r
  IN UINT8                Alternate\r
  )\r
{\r
  USB_INTERFACE_SETTING   *Setting;\r
  UINT8                   Index;\r
\r
  //\r
  // Locate the active alternate setting\r
  //\r
  Setting = NULL;\r
\r
  for (Index = 0; Index < IfDesc->NumOfSetting; Index++) {\r
    Setting = IfDesc->Settings[Index];\r
\r
    if (Setting->Desc.AlternateSetting == Alternate) {\r
      break;\r
    }\r
  }\r
\r
  if (Index == IfDesc->NumOfSetting) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  IfDesc->ActiveIndex = Index;\r
\r
  DEBUG ((EFI_D_INFO, "UsbSelectSetting: setting %d selected for interface %d\n",\r
              Alternate, Setting->Desc.InterfaceNumber));\r
\r
  //\r
  // Reset the endpoint toggle to zero\r
  //\r
  for (Index = 0; Index < Setting->Desc.NumEndpoints; Index++) {\r
    Setting->Endpoints[Index]->Toggle = 0;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r
\r
\r
/**\r
  Select a new configuration for the device. Each\r
  device may support several configurations.\r
\r
  @param  Device                The device to select configuration\r
  @param  ConfigValue           The index of the configuration ( != 0)\r
\r
  @retval EFI_NOT_FOUND         There is no configuration with the index\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource\r
  @retval EFI_SUCCESS           The configuration is selected.\r
\r
**/\r
EFI_STATUS\r
UsbSelectConfig (\r
  IN USB_DEVICE           *Device,\r
  IN UINT8                ConfigValue\r
  )\r
{\r
  USB_DEVICE_DESC         *DevDesc;\r
  USB_CONFIG_DESC         *ConfigDesc;\r
  USB_INTERFACE_DESC      *IfDesc;\r
  USB_INTERFACE           *UsbIf;\r
  EFI_STATUS              Status;\r
  UINT8                   Index;\r
\r
  //\r
  // Locate the active config, then set the device's pointer\r
  //\r
  DevDesc     = Device->DevDesc;\r
  ConfigDesc  = NULL;\r
\r
  for (Index = 0; Index < DevDesc->Desc.NumConfigurations; Index++) {\r
    ConfigDesc = DevDesc->Configs[Index];\r
\r
    if (ConfigDesc->Desc.ConfigurationValue == ConfigValue) {\r
      break;\r
    }\r
  }\r
\r
  if (Index == DevDesc->Desc.NumConfigurations) {\r
    return EFI_NOT_FOUND;\r
  }\r
\r
  Device->ActiveConfig = ConfigDesc;\r
\r
  DEBUG ((EFI_D_INFO, "UsbSelectConfig: config %d selected for device %d\n",\r
              ConfigValue, Device->Address));\r
\r
  //\r
  // Create interfaces for each USB interface descriptor.\r
  //\r
  for (Index = 0; Index < ConfigDesc->Desc.NumInterfaces; Index++) {\r
    //\r
    // First select the default interface setting, and reset\r
    // the endpoint toggles to zero for its endpoints.\r
    //\r
    IfDesc = ConfigDesc->Interfaces[Index];\r
    UsbSelectSetting (IfDesc, IfDesc->Settings[0]->Desc.AlternateSetting);\r
\r
    //\r
    // Create a USB_INTERFACE and install USB_IO and other protocols\r
    //\r
    UsbIf = UsbCreateInterface (Device, ConfigDesc->Interfaces[Index]);\r
\r
    if (UsbIf == NULL) {\r
      return EFI_OUT_OF_RESOURCES;\r
    }\r
\r
    Device->Interfaces[Index] = UsbIf;\r
\r
    //\r
    // Connect the device to drivers, if it failed, ignore\r
    // the error. Don't let the unsupported interfaces to block\r
    // the supported interfaces.\r
    //\r
    Status = UsbConnectDriver (UsbIf);\r
\r
    if (EFI_ERROR (Status)) {\r
      DEBUG ((EFI_D_ERROR, "UsbSelectConfig: failed to connect driver %r, ignored\n", Status));\r
    }\r
  }\r
\r
  Device->NumOfInterface = Index;\r
\r
  return EFI_SUCCESS;\r
}\r
\r
\r
\r
/**\r
  Disconnect the USB interface with its driver.\r
\r
  @param  UsbIf                 The interface to disconnect driver from\r
\r
  @return None\r
\r
**/\r
STATIC\r
VOID\r
UsbDisconnectDriver (\r
  IN USB_INTERFACE        *UsbIf\r
  )\r
{\r
  EFI_TPL                 OldTpl;\r
\r
  //\r
  // Release the hub if it's a hub controller, otherwise\r
  // disconnect the driver if it is managed by other drivers.\r
  //\r
  if (UsbIf->IsHub) {\r
    UsbIf->HubApi->Release (UsbIf);\r
\r
  } else if (UsbIf->IsManaged) {\r
    //\r
    // This function is called in both UsbIoControlTransfer and\r
    // the timer callback in hub enumeration. So, at least it is\r
    // called at TPL_CALLBACK. Some driver sitting on USB has\r
    // twisted TPL used. It should be no problem for us to connect\r
    // or disconnect at CALLBACK.\r
    //\r
    OldTpl           = UsbGetCurrentTpl ();\r
    DEBUG ((EFI_D_INFO, "UsbDisconnectDriver: old TPL is %d\n", OldTpl));\r
\r
    gBS->RestoreTPL (TPL_CALLBACK);\r
\r
    gBS->DisconnectController (UsbIf->Handle, NULL, NULL);\r
    UsbIf->IsManaged = FALSE;\r
\r
    DEBUG (( EFI_D_INFO, "UsbDisconnectDriver: TPL after disconnect is %d\n", UsbGetCurrentTpl()));\r
    ASSERT (UsbGetCurrentTpl () == TPL_CALLBACK);\r
\r
    gBS->RaiseTPL (OldTpl);\r
  }\r
}\r
\r
\r
\r
/**\r
  Remove the current device configuration\r
\r
  @param  Device                The USB device to remove configuration from\r
\r
  @return None\r
\r
**/\r
VOID\r
UsbRemoveConfig (\r
  IN USB_DEVICE           *Device\r
  )\r
{\r
  USB_INTERFACE           *UsbIf;\r
  UINTN                   Index;\r
\r
  //\r
  // Remove each interface of the device\r
  //\r
  for (Index = 0; Index < Device->NumOfInterface; Index++) {\r
    UsbIf = Device->Interfaces[Index];\r
\r
    if (UsbIf == NULL) {\r
      continue;\r
    }\r
\r
    UsbDisconnectDriver (UsbIf);\r
    UsbFreeInterface (UsbIf);\r
    Device->Interfaces[Index] = NULL;\r
  }\r
\r
  Device->ActiveConfig    = NULL;\r
  Device->NumOfInterface  = 0;\r
}\r
\r
\r
\r
/**\r
  Remove the device and all its children from the bus.\r
\r
  @param  Device                The device to remove\r
\r
  @retval EFI_SUCCESS           The device is removed\r
\r
**/\r
EFI_STATUS\r
UsbRemoveDevice (\r
  IN USB_DEVICE           *Device\r
  )\r
{\r
  USB_BUS                 *Bus;\r
  USB_DEVICE              *Child;\r
  EFI_STATUS              Status;\r
  UINT8                   Index;\r
\r
  Bus = Device->Bus;\r
\r
  //\r
  // Remove all the devices on its downstream ports. Search from devices[1].\r
  // Devices[0] is the root hub.\r
  //\r
  for (Index = 1; Index < USB_MAX_DEVICES; Index++) {\r
    Child = Bus->Devices[Index];\r
\r
    if ((Child == NULL) || (Child->ParentAddr != Device->Address)) {\r
      continue;\r
    }\r
\r
    Status = UsbRemoveDevice (Child);\r
\r
    if (EFI_ERROR (Status)) {\r
      DEBUG ((EFI_D_ERROR, "UsbRemoveDevice: failed to remove child, ignore error\n"));\r
      Bus->Devices[Index] = NULL;\r
    }\r
  }\r
\r
  UsbRemoveConfig (Device);\r
\r
  DEBUG (( EFI_D_INFO, "UsbRemoveDevice: device %d removed\n", Device->Address));\r
\r
  Bus->Devices[Device->Address] = NULL;\r
  UsbFreeDevice (Device);\r
\r
  return EFI_SUCCESS;\r
}\r
\r
\r
/**\r
  Find the child device on the hub's port\r
\r
  @param  HubIf                 The hub interface\r
  @param  Port                  The port of the hub this child is connected to\r
\r
  @return The device on the hub's port, or NULL if there is none\r
\r
**/\r
STATIC\r
USB_DEVICE *\r
UsbFindChild (\r
  IN USB_INTERFACE        *HubIf,\r
  IN UINT8                Port\r
  )\r
{\r
  USB_DEVICE              *Device;\r
  USB_BUS                 *Bus;\r
  UINTN                   Index;\r
\r
  Bus = HubIf->Device->Bus;\r
\r
  //\r
  // Start checking from device 1, device 0 is the root hub\r
  //\r
  for (Index = 1; Index < USB_MAX_DEVICES; Index++) {\r
    Device = Bus->Devices[Index];\r
\r
    if ((Device != NULL) && (Device->ParentAddr == HubIf->Device->Address) &&\r
        (Device->ParentPort == Port)) {\r
\r
      return Device;\r
    }\r
  }\r
\r
  return NULL;\r
}\r
\r
\r
\r
/**\r
  Enumerate and configure the new device on the port of this HUB interface.\r
\r
  @param  HubIf                 The HUB that has the device connected\r
  @param  Port                  The port index of the hub (started with zero)\r
\r
  @retval EFI_SUCCESS           The device is enumerated (added or removed)\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the device\r
  @retval Others                Failed to enumerate the device\r
\r
**/\r
STATIC\r
EFI_STATUS\r
UsbEnumerateNewDev (\r
  IN USB_INTERFACE        *HubIf,\r
  IN UINT8                Port\r
  )\r
{\r
  USB_BUS                 *Bus;\r
  USB_HUB_API             *HubApi;\r
  USB_DEVICE              *Child;\r
  USB_DEVICE              *Parent;\r
  EFI_USB_PORT_STATUS     PortState;\r
  UINT8                   Address;\r
  UINT8                   Config;\r
  EFI_STATUS              Status;\r
\r
  Address = USB_MAX_DEVICES;\r
  Parent  = HubIf->Device;\r
  Bus     = Parent->Bus;\r
  HubApi  = HubIf->HubApi;\r
  \r
  gBS->Stall (USB_WAIT_PORT_STABLE_STALL);\r
  \r
  //\r
  // Hub resets the device for at least 10 milliseconds.\r
  // Host learns device speed. If device is of low/full speed\r
  // and the hub is a EHCI root hub, ResetPort will release\r
  // the device to its companion UHCI and return an error.\r
  //\r
  Status = HubApi->ResetPort (HubIf, Port);\r
\r
  if (EFI_ERROR (Status)) {\r
    DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to reset port %d - %r\n", Port, Status));\r
\r
    return Status;\r
  }\r
\r
  DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: hub port %d is reset\n", Port));\r
\r
  Child = UsbCreateDevice (HubIf, Port);\r
\r
  if (Child == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // OK, now identify the device speed. After reset, hub\r
  // fully knows the actual device speed.\r
  //\r
  Status = HubApi->GetPortStatus (HubIf, Port, &PortState);\r
\r
  if (EFI_ERROR (Status)) {\r
    DEBUG ((EFI_D_ERROR, "UsbEnumerateNewDev: failed to get speed of port %d\n", Port));\r
    goto ON_ERROR;\r
  }\r
\r
  if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_LOW_SPEED)) {\r
    Child->Speed = EFI_USB_SPEED_LOW;\r
\r
  } else if (USB_BIT_IS_SET (PortState.PortStatus, USB_PORT_STAT_HIGH_SPEED)) {\r
    Child->Speed = EFI_USB_SPEED_HIGH;\r
\r
  } else {\r
    Child->Speed = EFI_USB_SPEED_FULL;\r
  }\r
\r
  DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device is of %d speed\n", Child->Speed));\r
\r
  if (Child->Speed != EFI_USB_SPEED_HIGH) {\r
    //\r
    // If the child isn't a high speed device, it is necessary to\r
    // set the transaction translator. This is quite simple:\r
    //  1. if parent is of high speed, then parent is our translator\r
    //  2. otherwise use parent's translator.\r
    //\r
    if (Parent->Speed == EFI_USB_SPEED_HIGH) {\r
      Child->Translator.TranslatorHubAddress  = Parent->Address;\r
      Child->Translator.TranslatorPortNumber  = Port;\r
\r
    } else {\r
      Child->Translator = Parent->Translator;\r
    }\r
\r
    DEBUG (( EFI_D_INFO, "UsbEnumerateNewDev: device uses translator (%d, %d)\n",\r
                Child->Translator.TranslatorHubAddress,\r
                Child->Translator.TranslatorPortNumber));\r
  }\r
\r
  //\r
  // After port is reset, hub establishes a signal path between\r