MdeModulePkg/Bus/Pci/EhciPei/EhciUrb.h

   1 /** @file
   2 Private Header file for Usb Host Controller PEIM
   3
   4 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved.<BR>
   5
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef _EFI_EHCI_URB_H_
  11 #define _EFI_EHCI_URB_H_
  12
  13 typedef struct _PEI_EHC_QTD PEI_EHC_QTD;
  14 typedef struct _PEI_EHC_QH  PEI_EHC_QH;
  15 typedef struct _PEI_URB     PEI_URB;
  16
  17 #define EHC_CTRL_TRANSFER       0x01
  18 #define EHC_BULK_TRANSFER       0x02
  19 #define EHC_INT_TRANSFER_SYNC   0x04
  20 #define EHC_INT_TRANSFER_ASYNC  0x08
  21
  22 #define EHC_QTD_SIG             SIGNATURE_32 ('U', 'S', 'B', 'T')
  23 #define EHC_QH_SIG              SIGNATURE_32 ('U', 'S', 'B', 'H')
  24 #define EHC_URB_SIG             SIGNATURE_32 ('U', 'S', 'B', 'R')
  25
  26 //
  27 // Hardware related bit definitions
  28 //
  29 #define EHC_TYPE_ITD            0x00
  30 #define EHC_TYPE_QH             0x02
  31 #define EHC_TYPE_SITD           0x04
  32 #define EHC_TYPE_FSTN           0x06
  33
  34 #define QH_NAK_RELOAD           3
  35 #define QH_HSHBW_MULTI          1
  36
  37 #define QTD_MAX_ERR             3
  38 #define QTD_PID_OUTPUT          0x00
  39 #define QTD_PID_INPUT           0x01
  40 #define QTD_PID_SETUP           0x02
  41
  42 #define QTD_STAT_DO_OUT         0
  43 #define QTD_STAT_DO_SS          0
  44 #define QTD_STAT_DO_PING        0x01
  45 #define QTD_STAT_DO_CS          0x02
  46 #define QTD_STAT_TRANS_ERR      0x08
  47 #define QTD_STAT_BABBLE_ERR     0x10
  48 #define QTD_STAT_BUFF_ERR       0x20
  49 #define QTD_STAT_HALTED         0x40
  50 #define QTD_STAT_ACTIVE         0x80
  51 #define QTD_STAT_ERR_MASK       (QTD_STAT_TRANS_ERR | QTD_STAT_BABBLE_ERR | QTD_STAT_BUFF_ERR)
  52
  53 #define QTD_MAX_BUFFER          4
  54 #define QTD_BUF_LEN             4096
  55 #define QTD_BUF_MASK            0x0FFF
  56
  57 #define QH_MICROFRAME_0         0x01
  58 #define QH_MICROFRAME_1         0x02
  59 #define QH_MICROFRAME_2         0x04
  60 #define QH_MICROFRAME_3         0x08
  61 #define QH_MICROFRAME_4         0x10
  62 #define QH_MICROFRAME_5         0x20
  63 #define QH_MICROFRAME_6         0x40
  64 #define QH_MICROFRAME_7         0x80
  65
  66 #define USB_ERR_SHORT_PACKET    0x200
  67
  68 //
  69 // Fill in the hardware link point: pass in a EHC_QH/QH_HW
  70 // pointer to QH_LINK; A EHC_QTD/QTD_HW pointer to QTD_LINK
  71 //
  72 #define QH_LINK(Addr, Type, Term) \
  73           ((UINT32) ((EHC_LOW_32BIT (Addr) & 0xFFFFFFE0) | (Type) | ((Term) ? 1 : 0)))
  74
  75 #define QTD_LINK(Addr, Term)      QH_LINK((Addr), 0, (Term))
  76
  77 //
  78 // The defination of EHCI hardware used data structure for
  79 // little endian architecture. The QTD and QH structures
  80 // are required to be 32 bytes aligned. Don't add members
  81 // to the head of the associated software strucuture.
  82 //
  83 #pragma pack(1)
  84 typedef struct {
  85   UINT32                  NextQtd;
  86   UINT32                  AltNext;
  87
  88   UINT32                  Status       : 8;
  89   UINT32                  Pid          : 2;
  90   UINT32                  ErrCnt       : 2;
  91   UINT32                  CurPage      : 3;
  92   UINT32                  Ioc          : 1;
  93   UINT32                  TotalBytes   : 15;
  94   UINT32                  DataToggle   : 1;
  95
  96   UINT32                  Page[5];
  97   UINT32                  PageHigh[5];
  98 } QTD_HW;
  99
 100 typedef struct {
 101   UINT32                  HorizonLink;
 102   //
 103   // Endpoint capabilities/Characteristics DWord 1 and DWord 2
 104   //
 105   UINT32                  DeviceAddr   : 7;
 106   UINT32                  Inactive     : 1;
 107   UINT32                  EpNum        : 4;
 108   UINT32                  EpSpeed      : 2;
 109   UINT32                  DtCtrl       : 1;
 110   UINT32                  ReclaimHead  : 1;
 111   UINT32                  MaxPacketLen : 11;
 112   UINT32                  CtrlEp       : 1;
 113   UINT32                  NakReload    : 4;
 114
 115   UINT32                  SMask        : 8;
 116   UINT32                  CMask        : 8;
 117   UINT32                  HubAddr      : 7;
 118   UINT32                  PortNum      : 7;
 119   UINT32                  Multiplier   : 2;
 120
 121   //
 122   // Transaction execution overlay area
 123   //
 124   UINT32                  CurQtd;
 125   UINT32                  NextQtd;
 126   UINT32                  AltQtd;
 127
 128   UINT32                  Status       : 8;
 129   UINT32                  Pid          : 2;
 130   UINT32                  ErrCnt       : 2;
 131   UINT32                  CurPage      : 3;
 132   UINT32                  Ioc          : 1;
 133   UINT32                  TotalBytes   : 15;
 134   UINT32                  DataToggle   : 1;
 135
 136   UINT32                  Page[5];
 137   UINT32                  PageHigh[5];
 138 } QH_HW;
 139 #pragma pack()
 140
 141
 142 //
 143 // Endpoint address and its capabilities
 144 //
 145 typedef struct _USB_ENDPOINT {
 146   UINT8                   DevAddr;
 147   UINT8                   EpAddr;     // Endpoint address, no direction encoded in
 148   EFI_USB_DATA_DIRECTION  Direction;
 149   UINT8                   DevSpeed;
 150   UINTN                   MaxPacket;
 151   UINT8                   HubAddr;
 152   UINT8                   HubPort;
 153   UINT8                   Toggle;     // Data toggle, not used for control transfer
 154   UINTN                   Type;
 155   UINTN                   PollRate;   // Polling interval used by EHCI
 156 } USB_ENDPOINT;
 157
 158 //
 159 // Software QTD strcture, this is used to manage all the
 160 // QTD generated from a URB. Don't add fields before QtdHw.
 161 //
 162 struct _PEI_EHC_QTD {
 163   QTD_HW                  QtdHw;
 164   UINT32                  Signature;
 165   EFI_LIST_ENTRY          QtdList;   // The list of QTDs to one end point
 166   UINT8                   *Data;     // Buffer of the original data
 167   UINTN                   DataLen;   // Original amount of data in this QTD
 168 };
 169
 170
 171
 172 //
 173 // Software QH structure. All three different transaction types
 174 // supported by UEFI USB, that is the control/bulk/interrupt
 175 // transfers use the queue head and queue token strcuture.
 176 //
 177 // Interrupt QHs are linked to periodic frame list in the reversed
 178 // 2^N tree. Each interrupt QH is linked to the list starting at
 179 // frame 0. There is a dummy interrupt QH linked to each frame as
 180 // a sentinental whose polling interval is 1. Synchronous interrupt
 181 // transfer is linked after this dummy QH.
 182 //
 183 // For control/bulk transfer, only synchronous (in the sense of UEFI)
 184 // transfer is supported. A dummy QH is linked to EHCI AsyncListAddr
 185 // as the reclamation header. New transfer is inserted after this QH.
 186 //
 187 struct _PEI_EHC_QH {
 188   QH_HW                   QhHw;
 189   UINT32                  Signature;
 190   PEI_EHC_QH              *NextQh;    // The queue head pointed to by horizontal link
 191   EFI_LIST_ENTRY          Qtds;       // The list of QTDs to this queue head
 192   UINTN                   Interval;
 193 };
 194
 195 //
 196 // URB (Usb Request Block) contains information for all kinds of
 197 // usb requests.
 198 //
 199 struct _PEI_URB {
 200   UINT32                          Signature;
 201   EFI_LIST_ENTRY                  UrbList;
 202
 203   //
 204   // Transaction information
 205   //
 206   USB_ENDPOINT                    Ep;
 207   EFI_USB_DEVICE_REQUEST          *Request;     // Control transfer only
 208   VOID                            *RequestPhy;  // Address of the mapped request
 209   VOID                            *RequestMap;
 210   VOID                            *Data;
 211   UINTN                           DataLen;
 212   VOID                            *DataPhy;     // Address of the mapped user data
 213   VOID                            *DataMap;
 214   EFI_ASYNC_USB_TRANSFER_CALLBACK Callback;
 215   VOID                            *Context;
 216
 217   //
 218   // Schedule data
 219   //
 220   PEI_EHC_QH                      *Qh;
 221
 222   //
 223   // Transaction result
 224   //
 225   UINT32                          Result;
 226   UINTN                           Completed;    // completed data length
 227   UINT8                           DataToggle;
 228 };
 229
 230 /**
 231   Delete a single asynchronous interrupt transfer for
 232   the device and endpoint.
 233
 234   @param  Ehc         The EHCI device.
 235   @param  Data        Current data not associated with a QTD.
 236   @param  DataLen     The length of the data.
 237   @param  PktId       Packet ID to use in the QTD.
 238   @param  Toggle      Data toggle to use in the QTD.
 239   @param  MaxPacket   Maximu packet length of the endpoint.
 240
 241   @retval the pointer to the created QTD or NULL if failed to create one.
 242
 243 **/
 244 PEI_EHC_QTD *
 245 EhcCreateQtd (
 246   IN PEI_USB2_HC_DEV      *Ehc,
 247   IN UINT8                *Data,
 248   IN UINTN                DataLen,
 249   IN UINT8                PktId,
 250   IN UINT8                Toggle,
 251   IN UINTN                MaxPacket
 252   )
 253 ;
 254
 255 /**
 256   Allocate and initialize a EHCI queue head.
 257
 258   @param  Ehci      The EHCI device.
 259   @param  Ep        The endpoint to create queue head for.
 260
 261   @retval the pointer to the created queue head or NULL if failed to create one.
 262
 263 **/
 264 PEI_EHC_QH *
 265 EhcCreateQh (
 266   IN PEI_USB2_HC_DEV      *Ehci,
 267   IN USB_ENDPOINT         *Ep
 268   )
 269 ;
 270
 271 /**
 272   Free an allocated URB. It is possible for it to be partially inited.
 273
 274   @param  Ehc         The EHCI device.
 275   @param  Urb         The URB to free.
 276
 277 **/
 278 VOID
 279 EhcFreeUrb (
 280   IN PEI_USB2_HC_DEV      *Ehc,
 281   IN PEI_URB              *Urb
 282   )
 283 ;
 284
 285 /**
 286   Create a new URB and its associated QTD.
 287
 288   @param  Ehc               The EHCI device.
 289   @param  DevAddr           The device address.
 290   @param  EpAddr            Endpoint addrress & its direction.
 291   @param  DevSpeed          The device speed.
 292   @param  Toggle            Initial data toggle to use.
 293   @param  MaxPacket         The max packet length of the endpoint.
 294   @param  Hub               The transaction translator to use.
 295   @param  Type              The transaction type.
 296   @param  Request           The standard USB request for control transfer.
 297   @param  Data              The user data to transfer.
 298   @param  DataLen           The length of data buffer.
 299   @param  Callback          The function to call when data is transferred.
 300   @param  Context           The context to the callback.
 301   @param  Interval          The interval for interrupt transfer.
 302
 303   @retval the pointer to the created URB or NULL.
 304
 305 **/
 306 PEI_URB *
 307 EhcCreateUrb (
 308   IN PEI_USB2_HC_DEV                    *Ehc,
 309   IN UINT8                              DevAddr,
 310   IN UINT8                              EpAddr,
 311   IN UINT8                              DevSpeed,
 312   IN UINT8                              Toggle,
 313   IN UINTN                              MaxPacket,
 314   IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Hub,
 315   IN UINTN                              Type,
 316   IN EFI_USB_DEVICE_REQUEST             *Request,
 317   IN VOID                               *Data,
 318   IN UINTN                              DataLen,
 319   IN EFI_ASYNC_USB_TRANSFER_CALLBACK    Callback,
 320   IN VOID                               *Context,
 321   IN UINTN                              Interval
 322   )
 323 ;
 324 #endif