MdeModulePkg/Bus/Usb/UsbBusDxe/UsbBus.h

   1 /** @file
   2
   3     Usb Bus Driver Binding and Bus IO Protocol.
   4
   5 Copyright (c) 2004 - 2007, 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 #ifndef _EFI_USB_BUS_H_
  17 #define _EFI_USB_BUS_H_
  18
  19
  20 #include <PiDxe.h>
  21
  22 #include <Protocol/Usb2HostController.h>
  23 #include <Protocol/UsbHostController.h>
  24 #include <Protocol/UsbIo.h>
  25 #include <Protocol/DevicePath.h>
  26
  27 #include <Library/BaseLib.h>
  28 #include <Library/DebugLib.h>
  29 #include <Library/BaseMemoryLib.h>
  30 #include <Library/UefiDriverEntryPoint.h>
  31 #include <Library/UefiBootServicesTableLib.h>
  32 #include <Library/UefiLib.h>
  33 #include <Library/DevicePathLib.h>
  34 #include <Library/MemoryAllocationLib.h>
  35
  36
  37 #include <IndustryStandard/Usb.h>
  38
  39 typedef struct _USB_DEVICE     USB_DEVICE;
  40 typedef struct _USB_INTERFACE  USB_INTERFACE;
  41 typedef struct _USB_BUS        USB_BUS;
  42 typedef struct _USB_HUB_API    USB_HUB_API;
  43
  44
  45 #include "UsbUtility.h"
  46 #include "UsbDesc.h"
  47 #include "UsbHub.h"
  48 #include "UsbEnumer.h"
  49
  50 typedef enum {
  51   USB_MAX_LANG_ID           = 16,
  52   USB_MAX_INTERFACE         = 16,
  53   USB_MAX_DEVICES           = 128,
  54
  55   USB_BUS_1_MILLISECOND     = 1000,
  56
  57   //
  58   // Roothub and hub's polling interval, set by experience,
  59   // The unit of roothub is 100us, means 1s as interval, and
  60   // the unit of hub is 1ms, means 64ms as interval.
  61   //
  62   USB_ROOTHUB_POLL_INTERVAL = 1000 * 10000U,
  63   USB_HUB_POLL_INTERVAL     = 64,
  64
  65   //
  66   // Wait for port stable to work, refers to specification
  67   // [USB20-9.1.2]
  68   //
  69   USB_WAIT_PORT_STABLE_STALL     = 100 * USB_BUS_1_MILLISECOND,
  70
  71   //
  72   // Wait for port statue reg change, set by experience
  73   //
  74   USB_WAIT_PORT_STS_CHANGE_STALL = 5 * USB_BUS_1_MILLISECOND,
  75
  76   //
  77   // Wait for set device address, refers to specification
  78   // [USB20-9.2.6.3, it says 2ms]
  79   //
  80   USB_SET_DEVICE_ADDRESS_STALL   = 20 * USB_BUS_1_MILLISECOND,
  81
  82   //
  83   // Wait for retry max packet size, set by experience
  84   //
  85   USB_RETRY_MAX_PACK_SIZE_STALL  = 100 * USB_BUS_1_MILLISECOND,
  86
  87   //
  88   // Wait for hub port power-on, refers to specification
  89   // [USB20-11.23.2]
  90   //
  91   USB_SET_PORT_POWER_STALL       = 2 * USB_BUS_1_MILLISECOND,
  92
  93   //
  94   // Wait for port reset, refers to specification
  95   // [USB20-7.1.7.5, it says 10ms for hub and 50ms for
  96   // root hub]
  97   //
  98   USB_SET_PORT_RESET_STALL       = 20 * USB_BUS_1_MILLISECOND,
  99   USB_SET_ROOT_PORT_RESET_STALL  = 50 * USB_BUS_1_MILLISECOND,
 100
 101   //
 102   // Wait for clear roothub port reset, set by experience
 103   //
 104   USB_CLR_ROOT_PORT_RESET_STALL  = 1 * USB_BUS_1_MILLISECOND,
 105
 106   //
 107   // Wait for set roothub port enable, set by experience
 108   //
 109   USB_SET_ROOT_PORT_ENABLE_STALL = 20 * USB_BUS_1_MILLISECOND,
 110
 111   //
 112   // Send general device request timeout, refers to
 113   // specification[USB20-11.24.1]
 114   //
 115   USB_GENERAL_DEVICE_REQUEST_TIMEOUT = 50 * USB_BUS_1_MILLISECOND,
 116
 117   //
 118   // Send clear feature request timeout, set by experience
 119   //
 120   USB_CLEAR_FEATURE_REQUEST_TIMEOUT  = 10 * USB_BUS_1_MILLISECOND
 121 }USB_BUS_TIMEOUT_EXPERIENCE_VALUE;
 122
 123 //
 124 // Bus raises TPL to TPL_NOTIFY to serialize all its operations
 125 // to protect shared data structures.
 126 //
 127 #define  USB_BUS_TPL               TPL_NOTIFY
 128
 129 #define  USB_INTERFACE_SIGNATURE   EFI_SIGNATURE_32 ('U', 'S', 'B', 'I')
 130 #define  USB_BUS_SIGNATURE         EFI_SIGNATURE_32 ('U', 'S', 'B', 'B')
 131
 132 #define USB_BIT(a)                  ((UINTN)(1 << (a)))
 133 #define USB_BIT_IS_SET(Data, Bit)   ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
 134
 135 #define EFI_USB_BUS_PROTOCOL_GUID \
 136           {0x2B2F68CC, 0x0CD2, 0x44cf, {0x8E, 0x8B, 0xBB, 0xA2, 0x0B, 0x1B, 0x5B, 0x75}}
 137
 138 #define USB_INTERFACE_FROM_USBIO(a) \
 139           CR(a, USB_INTERFACE, UsbIo, USB_INTERFACE_SIGNATURE)
 140
 141 #define USB_BUS_FROM_THIS(a) \
 142           CR(a, USB_BUS, BusId, USB_BUS_SIGNATURE)
 143
 144 //
 145 // Used to locate USB_BUS
 146 //
 147 typedef struct _EFI_USB_BUS_PROTOCOL {
 148   UINT64                    Reserved;
 149 } EFI_USB_BUS_PROTOCOL;
 150
 151
 152 //
 153 // Stands for the real USB device. Each device may
 154 // has several seperately working interfaces.
 155 //
 156 struct _USB_DEVICE {
 157   USB_BUS                   *Bus;
 158
 159   //
 160   // Configuration information
 161   //
 162   UINT8                     Speed;
 163   UINT8                     Address;
 164   UINT8                     MaxPacket0;
 165
 166   //
 167   // The device's descriptors and its configuration
 168   //
 169   USB_DEVICE_DESC           *DevDesc;
 170   USB_CONFIG_DESC           *ActiveConfig;
 171
 172   UINT16                    LangId [USB_MAX_LANG_ID];
 173   UINT16                    TotalLangId;
 174
 175   UINT8                     NumOfInterface;
 176   USB_INTERFACE             *Interfaces [USB_MAX_INTERFACE];
 177
 178   //
 179   // Parent child relationship
 180   //
 181   EFI_USB2_HC_TRANSACTION_TRANSLATOR Translator;
 182
 183   UINT8                     ParentAddr;
 184   USB_INTERFACE             *ParentIf;
 185   UINT8                     ParentPort;       // Start at 0
 186 };
 187
 188 //
 189 // Stands for different functions of USB device
 190 //
 191 struct _USB_INTERFACE {
 192   UINTN                     Signature;
 193   USB_DEVICE                *Device;
 194   USB_INTERFACE_DESC        *IfDesc;
 195   USB_INTERFACE_SETTING     *IfSetting;
 196
 197   //
 198   // Handles and protocols
 199   //
 200   EFI_HANDLE                Handle;
 201   EFI_USB_IO_PROTOCOL       UsbIo;
 202   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 203   BOOLEAN                   IsManaged;
 204
 205   //
 206   // Hub device special data
 207   //
 208   BOOLEAN                   IsHub;
 209   USB_HUB_API               *HubApi;
 210   UINT8                     NumOfPort;
 211   EFI_EVENT                 HubNotify;
 212
 213   //
 214   // Data used only by normal hub devices
 215   //
 216   USB_ENDPOINT_DESC         *HubEp;
 217   UINT8                     *ChangeMap;
 218
 219   //
 220   // Data used only by root hub to hand over device to
 221   // companion UHCI driver if low/full speed devices are
 222   // connected to EHCI.
 223   //
 224   UINT8                     MaxSpeed;
 225 };
 226
 227 //
 228 // Stands for the current USB Bus
 229 //
 230 struct _USB_BUS {
 231   UINTN                     Signature;
 232   EFI_USB_BUS_PROTOCOL      BusId;
 233
 234   //
 235   // Managed USB host controller
 236   //
 237   EFI_HANDLE                HostHandle;
 238   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 239   EFI_USB2_HC_PROTOCOL      *Usb2Hc;
 240   EFI_USB_HC_PROTOCOL       *UsbHc;
 241
 242   //
 243   // An array of device that is on the bus. Devices[0] is
 244   // for root hub. Device with address i is at Devices[i].
 245   //
 246   USB_DEVICE                *Devices[USB_MAX_DEVICES];
 247
 248   //
 249   // USB Bus driver need to control the recursive connect policy of the bus, only those wanted
 250   // usb child device will be recursively connected.
 251   //
 252   // WantedUsbIoDPList tracks the Usb child devices which user want to recursivly fully connecte,
 253   // every wanted child device is stored in a item of the WantedUsbIoDPList, whose structrure is
 254   // DEVICE_PATH_LIST_ITEM
 255   //
 256   LIST_ENTRY                WantedUsbIoDPList;
 257
 258 };
 259
 260 //
 261 // USB Hub Api
 262 //
 263 struct _USB_HUB_API{
 264   USB_HUB_INIT                Init;
 265   USB_HUB_GET_PORT_STATUS     GetPortStatus;
 266   USB_HUB_CLEAR_PORT_CHANGE   ClearPortChange;
 267   USB_HUB_SET_PORT_FEATURE    SetPortFeature;
 268   USB_HUB_CLEAR_PORT_FEATURE  ClearPortFeature;
 269   USB_HUB_RESET_PORT          ResetPort;
 270   USB_HUB_RELEASE             Release;
 271 };
 272
 273 #define USB_US_LAND_ID   0x0409
 274
 275 #define DEVICE_PATH_LIST_ITEM_SIGNATURE     EFI_SIGNATURE_32('d','p','l','i')
 276 typedef struct _DEVICE_PATH_LIST_ITEM{
 277   UINTN                                 Signature;
 278   LIST_ENTRY                            Link;
 279   EFI_DEVICE_PATH_PROTOCOL              *DevicePath;
 280 } DEVICE_PATH_LIST_ITEM;
 281
 282 typedef struct {
 283   USB_CLASS_DEVICE_PATH           UsbClass;
 284   EFI_DEVICE_PATH_PROTOCOL        End;
 285 } USB_CLASS_FORMAT_DEVICE_PATH;
 286
 287 /**
 288   Free a DEVICE_PATH_LIST_ITEM list.
 289
 290   @param  UsbIoDPList            a DEVICE_PATH_LIST_ITEM list pointer.
 291
 292   @retval EFI_INVALID_PARAMETER  If parameters are invalid, return this value.
 293   @retval EFI_SUCCESS            If free operation is successful, return this value.
 294
 295 **/
 296 EFI_STATUS
 297 EFIAPI
 298 UsbBusFreeUsbDPList (
 299   IN     LIST_ENTRY                                 *UsbIoDPList
 300   );
 301
 302 /**
 303   Store a wanted usb child device info (its Usb part of device path) which is indicated by
 304   RemainingDevicePath in a Usb bus which  is indicated by UsbBusId.
 305
 306   @param  UsbBusId               Point to EFI_USB_BUS_PROTOCOL interface.
 307   @param  RemainingDevicePath    The remaining device patch.
 308
 309   @retval EFI_SUCCESS            Add operation is successful.
 310   @retval EFI_INVALID_PARAMETER  The parameters are invalid.
 311
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 UsbBusAddWantedUsbIoDP (
 316   IN EFI_USB_BUS_PROTOCOL         *UsbBusId,
 317   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath
 318   );
 319
 320 /**
 321   Check whether a usb child device is the wanted device in a bus.
 322
 323   @param  Bus     The Usb bus's private data pointer.
 324   @param  UsbIf   The usb child device inferface.
 325
 326   @retval True    If a usb child device is the wanted device in a bus.
 327   @retval False   If a usb child device is *NOT* the wanted device in a bus.
 328
 329 **/
 330 BOOLEAN
 331 EFIAPI
 332 UsbBusIsWantedUsbIO (
 333   IN USB_BUS                 *Bus,
 334   IN USB_INTERFACE           *UsbIf
 335   );
 336
 337 /**
 338   Recursively connnect every wanted usb child device to ensure they all fully connected.
 339   Check all the child Usb IO handles in this bus, recursively connecte if it is wanted usb child device.
 340
 341   @param  UsbBusId                  Point to EFI_USB_BUS_PROTOCOL interface.
 342
 343   @retval EFI_SUCCESS               Connect is done successfully.
 344   @retval EFI_INVALID_PARAMETER     The parameter is invalid.
 345
 346 **/
 347 EFI_STATUS
 348 EFIAPI
 349 UsbBusRecursivelyConnectWantedUsbIo (
 350   IN EFI_USB_BUS_PROTOCOL         *UsbBusId
 351   );
 352
 353 extern EFI_USB_IO_PROTOCOL            mUsbIoProtocol;
 354 extern EFI_DRIVER_BINDING_PROTOCOL    mUsbBusDriverBinding;
 355 extern EFI_COMPONENT_NAME_PROTOCOL    mUsbBusComponentName;
 356 extern EFI_COMPONENT_NAME2_PROTOCOL   mUsbBusComponentName2;
 357
 358 #endif