MdeModulePkg/Bus/Pci/XhciDxe/Xhci.h

   1 /** @file
   2
   3   Provides some data structure definitions used by the XHCI host controller driver.
   4
   5 Copyright (c) 2011, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef _EFI_XHCI_H_
  17 #define _EFI_XHCI_H_
  18
  19 #include <Uefi.h>
  20
  21 #include <Protocol/Usb2HostController.h>
  22 #include <Protocol/PciIo.h>
  23
  24 #include <Guid/EventGroup.h>
  25
  26 #include <Library/BaseLib.h>
  27 #include <Library/BaseMemoryLib.h>
  28 #include <Library/UefiDriverEntryPoint.h>
  29 #include <Library/UefiBootServicesTableLib.h>
  30 #include <Library/MemoryAllocationLib.h>
  31 #include <Library/UefiLib.h>
  32 #include <Library/PcdLib.h>
  33 #include <Library/DebugLib.h>
  34
  35 #include <IndustryStandard/Pci.h>
  36
  37 typedef struct _USB_XHCI_DEV    USB_XHCI_DEV;
  38 typedef struct _USB_DEV_CONTEXT USB_DEV_CONTEXT;
  39
  40 #include "XhciReg.h"
  41 #include "XhciSched.h"
  42 #include "ComponentName.h"
  43
  44 //
  45 // XHC timeout experience values
  46 //
  47 #define XHC_1_MICROSECOND            1
  48 #define XHC_1_MILLISECOND            (1000 * XHC_1_MICROSECOND)
  49 #define XHC_1_SECOND                 (1000 * XHC_1_MILLISECOND)
  50
  51 //
  52 // XHCI register operation timeout, set by experience
  53 //
  54 #define XHC_RESET_TIMEOUT            (1 * XHC_1_SECOND)
  55 #define XHC_GENERIC_TIMEOUT          (10 * XHC_1_MILLISECOND)
  56
  57 //
  58 // Wait for roothub port power stable, refers to Spec[XHCI1.0-2.3.9]
  59 //
  60 #define XHC_ROOT_PORT_RECOVERY_STALL (20 * XHC_1_MILLISECOND)
  61
  62 //
  63 // Sync and Async transfer polling interval, set by experience,
  64 // and the unit of Async is 100us, means 50ms as interval.
  65 //
  66 #define XHC_SYNC_POLL_INTERVAL       (20 * XHC_1_MILLISECOND)
  67 #define XHC_ASYNC_POLL_INTERVAL      (50 * 10000U)
  68
  69 //
  70 // XHC raises TPL to TPL_NOTIFY to serialize all its operations
  71 // to protect shared data structures.
  72 //
  73 #define XHC_TPL                      TPL_NOTIFY
  74
  75 #define CMD_RING_TRB_NUMBER          0x40
  76 #define TR_RING_TRB_NUMBER           0x40
  77 #define ERST_NUMBER                  0x01
  78 #define EVENT_RING_TRB_NUMBER        0x80
  79
  80 #define CMD_INTER                    0
  81 #define CTRL_INTER                   1
  82 #define BULK_INTER                   2
  83 #define INT_INTER                    3
  84 #define INT_INTER_ASYNC              4
  85
  86 //
  87 // Iterate through the doule linked list. This is delete-safe.
  88 // Don't touch NextEntry
  89 //
  90 #define EFI_LIST_FOR_EACH_SAFE(Entry, NextEntry, ListHead) \
  91   for (Entry = (ListHead)->ForwardLink, NextEntry = Entry->ForwardLink;\
  92       Entry != (ListHead); Entry = NextEntry, NextEntry = Entry->ForwardLink)
  93
  94 #define EFI_LIST_CONTAINER(Entry, Type, Field) BASE_CR(Entry, Type, Field)
  95
  96 #define XHC_LOW_32BIT(Addr64)        ((UINT32)(((UINTN)(Addr64)) & 0xFFFFFFFF))
  97 #define XHC_HIGH_32BIT(Addr64)       ((UINT32)(RShiftU64((UINTN)(Addr64), 32) & 0xFFFFFFFF))
  98 #define XHC_BIT_IS_SET(Data, Bit)    ((BOOLEAN)(((Data) & (Bit)) == (Bit)))
  99
 100 #define XHC_REG_BIT_IS_SET(Xhc, Offset, Bit) \
 101           (XHC_BIT_IS_SET(XhcReadOpReg ((Xhc), (Offset)), (Bit)))
 102
 103 #define XHCI_IS_DATAIN(EndpointAddr) XHC_BIT_IS_SET((EndpointAddr), 0x80)
 104
 105 #define USB_XHCI_DEV_SIGNATURE       SIGNATURE_32 ('x', 'h', 'c', 'i')
 106 #define XHC_FROM_THIS(a)             CR(a, USB_XHCI_DEV, Usb2Hc, USB_XHCI_DEV_SIGNATURE)
 107
 108 #define USB_DESC_TYPE_HUB              0x29
 109 #define USB_DESC_TYPE_HUB_SUPER_SPEED  0x2a
 110
 111 //
 112 // Xhci Data and Ctrl Structures
 113 //
 114 #pragma pack(1)
 115 typedef struct {
 116   UINT8                     ProgInterface;
 117   UINT8                     SubClassCode;
 118   UINT8                     BaseCode;
 119 } USB_CLASSC;
 120
 121 typedef struct {
 122   UINT8                     Length;
 123   UINT8                     DescType;
 124   UINT8                     NumPorts;
 125   UINT16                    HubCharacter;
 126   UINT8                     PwrOn2PwrGood;
 127   UINT8                     HubContrCurrent;
 128   UINT8                     Filler[16];
 129 } EFI_USB_HUB_DESCRIPTOR;
 130 #pragma pack()
 131
 132 struct _USB_XHCI_DEV {
 133   UINT32                    Signature;
 134   EFI_PCI_IO_PROTOCOL       *PciIo;
 135   UINT64                    OriginalPciAttributes;
 136
 137   EFI_USB2_HC_PROTOCOL      Usb2Hc;
 138
 139   EFI_DEVICE_PATH_PROTOCOL  *DevicePath;
 140
 141   //
 142   // ExitBootServicesEvent is used to set OS semaphore and
 143   // stop the XHC DMA operation after exit boot service.
 144   //
 145   EFI_EVENT                 ExitBootServiceEvent;
 146   EFI_EVENT                 PollTimer;
 147   LIST_ENTRY                AsyncIntTransfers;
 148
 149   UINT8                     CapLength;    ///< Capability Register Length
 150   XHC_HCSPARAMS1            HcSParams1;   ///< Structural Parameters 1
 151   XHC_HCSPARAMS2            HcSParams2;   ///< Structural Parameters 2
 152   XHC_HCCPARAMS             HcCParams;    ///< Capability Parameters
 153   UINT32                    DBOff;        ///< Doorbell Offset
 154   UINT32                    RTSOff;       ///< Runtime Register Space Offset
 155   UINT16                    MaxInterrupt;
 156   UINT32                    PageSize;
 157   UINT64                    *ScratchBuf;
 158   UINT32                    MaxScratchpadBufs;
 159   UINT32                    ExtCapRegBase;
 160   UINT32                    UsbLegSupOffset;
 161   UINT64                    *DCBAA;
 162   UINT32                    MaxSlotsEn;
 163   //
 164   // Cmd Transfer Ring
 165   //
 166   TRANSFER_RING             CmdRing;
 167   //
 168   // CmdEventRing
 169   //
 170   EVENT_RING                CmdEventRing;
 171   //
 172   // ControlTREventRing
 173   //
 174   EVENT_RING                CtrlTrEventRing;
 175   //
 176   // BulkTREventRing
 177   //
 178   EVENT_RING                BulkTrEventRing;
 179   //
 180   // IntTREventRing
 181   //
 182   EVENT_RING                IntTrEventRing;
 183   //
 184   // AsyncIntTREventRing
 185   //
 186   EVENT_RING                AsynIntTrEventRing;
 187   //
 188   // Misc
 189   //
 190   EFI_UNICODE_STRING_TABLE  *ControllerNameTable;
 191
 192 };
 193
 194 struct _USB_DEV_CONTEXT {
 195   //
 196   // Whether this entry in UsbDevContext array is used or not.
 197   //
 198   BOOLEAN                   Enabled;
 199   //
 200   // The slot id assigned to the new device through XHCI's Enable_Slot cmd.
 201   //
 202   UINT8                     SlotId;
 203   //
 204   // The route string presented an attached usb device.
 205   //
 206   USB_DEV_ROUTE             RouteString;
 207   //
 208   // The route string of parent device if it exists. Otherwise it's zero.
 209   //
 210   USB_DEV_ROUTE             ParentRouteString;
 211   //
 212   // The actual device address assigned by XHCI through Address_Device command.
 213   //
 214   UINT8                     XhciDevAddr;
 215   //
 216   // The requested device address from UsbBus driver through Set_Address standard usb request.
 217   // As XHCI spec replaces this request with Address_Device command, we have to record the
 218   // requested device address and establish a mapping relationship with the actual device address.
 219   // Then UsbBus driver just need to be aware of the requested device address to access usb device
 220   // through EFI_USB2_HC_PROTOCOL. Xhci driver would be responsible for translating it to actual
 221   // device address and access the actual device.
 222   //
 223   UINT8                     BusDevAddr;
 224   //
 225   // The pointer to the input device context.
 226   //
 227   VOID                      *InputContext;
 228   //
 229   // The pointer to the output device context.
 230   //
 231   VOID                      *OutputDevContxt;
 232   //
 233   // The transfer queue for every endpoint.
 234   //
 235   VOID                      *EndpointTransferRing[31];
 236   //
 237   // The device descriptor which is stored to support XHCI's Evaluate_Context cmd.
 238   //
 239   EFI_USB_DEVICE_DESCRIPTOR DevDesc;
 240   //
 241   // As a usb device may include multiple configuration descriptors, we dynamically allocate an array
 242   // to store them.
 243   // Note that every configuration descriptor stored here includes those lower level descriptors,
 244   // such as Interface descriptor, Endpoint descriptor, and so on.
 245   // These information is used to support XHCI's Config_Endpoint cmd.
 246   //
 247   EFI_USB_CONFIG_DESCRIPTOR **ConfDesc;
 248 };
 249
 250 extern EFI_DRIVER_BINDING_PROTOCOL      gXhciDriverBinding;
 251 extern EFI_COMPONENT_NAME_PROTOCOL      gXhciComponentName;
 252 extern EFI_COMPONENT_NAME2_PROTOCOL     gXhciComponentName2;
 253 extern USB_DEV_CONTEXT                  UsbDevContext[];
 254
 255 /**
 256   Test to see if this driver supports ControllerHandle. Any
 257   ControllerHandle that has Usb2HcProtocol installed will
 258   be supported.
 259
 260   @param  This                 Protocol instance pointer.
 261   @param  Controller           Handle of device to test.
 262   @param  RemainingDevicePath  Not used.
 263
 264   @return EFI_SUCCESS          This driver supports this device.
 265   @return EFI_UNSUPPORTED      This driver does not support this device.
 266
 267 **/
 268 EFI_STATUS
 269 EFIAPI
 270 XhcDriverBindingSupported (
 271   IN EFI_DRIVER_BINDING_PROTOCOL *This,
 272   IN EFI_HANDLE                  Controller,
 273   IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath
 274   );
 275
 276 /**
 277   Starting the Usb XHCI Driver.
 278
 279   @param  This                 Protocol instance pointer.
 280   @param  Controller           Handle of device to test.
 281   @param  RemainingDevicePath  Not used.
 282
 283   @return EFI_SUCCESS          supports this device.
 284   @return EFI_UNSUPPORTED      do not support this device.
 285   @return EFI_DEVICE_ERROR     cannot be started due to device Error.
 286   @return EFI_OUT_OF_RESOURCES cannot allocate resources.
 287
 288 **/
 289 EFI_STATUS
 290 EFIAPI
 291 XhcDriverBindingStart (
 292   IN EFI_DRIVER_BINDING_PROTOCOL *This,
 293   IN EFI_HANDLE                  Controller,
 294   IN EFI_DEVICE_PATH_PROTOCOL    *RemainingDevicePath
 295   );
 296
 297 /**
 298   Stop this driver on ControllerHandle. Support stoping any child handles
 299   created by this driver.
 300
 301   @param  This                 Protocol instance pointer.
 302   @param  Controller           Handle of device to stop driver on.
 303   @param  NumberOfChildren     Number of Children in the ChildHandleBuffer.
 304   @param  ChildHandleBuffer    List of handles for the children we need to stop.
 305
 306   @return EFI_SUCCESS          Success.
 307   @return EFI_DEVICE_ERROR     Fail.
 308
 309 **/
 310 EFI_STATUS
 311 EFIAPI
 312 XhcDriverBindingStop (
 313   IN EFI_DRIVER_BINDING_PROTOCOL *This,
 314   IN EFI_HANDLE                  Controller,
 315   IN UINTN                       NumberOfChildren,
 316   IN EFI_HANDLE                  *ChildHandleBuffer
 317   );
 318
 319 /**
 320   Sets a feature for the specified root hub port.
 321
 322   @param  This                  This EFI_USB2_HC_PROTOCOL instance.
 323   @param  PortNumber            Root hub port to set.
 324   @param  PortFeature           Feature to set.
 325
 326   @retval EFI_SUCCESS           The feature specified by PortFeature was set.
 327   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
 328   @retval EFI_DEVICE_ERROR      Can't read register.
 329
 330 **/
 331 EFI_STATUS
 332 EFIAPI
 333 XhcSetRootHubPortFeature (
 334   IN EFI_USB2_HC_PROTOCOL  *This,
 335   IN UINT8                 PortNumber,
 336   IN EFI_USB_PORT_FEATURE  PortFeature
 337   );
 338
 339 /**
 340   Clears a feature for the specified root hub port.
 341
 342   @param  This                  A pointer to the EFI_USB2_HC_PROTOCOL instance.
 343   @param  PortNumber            Specifies the root hub port whose feature is
 344                                 requested to be cleared.
 345   @param  PortFeature           Indicates the feature selector associated with the
 346                                 feature clear request.
 347
 348   @retval EFI_SUCCESS           The feature specified by PortFeature was cleared
 349                                 for the USB root hub port specified by PortNumber.
 350   @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid.
 351   @retval EFI_DEVICE_ERROR      Can't read register.
 352
 353 **/
 354 EFI_STATUS
 355 EFIAPI
 356 XhcClearRootHubPortFeature (
 357   IN EFI_USB2_HC_PROTOCOL  *This,
 358   IN UINT8                 PortNumber,
 359   IN EFI_USB_PORT_FEATURE  PortFeature
 360   );
 361
 362 #endif