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 // Endpoint address and its capabilities
 143 //
 144 typedef struct _USB_ENDPOINT {
 145   UINT8                     DevAddr;
 146   UINT8                     EpAddr;   // Endpoint address, no direction encoded in
 147   EFI_USB_DATA_DIRECTION    Direction;
 148   UINT8                     DevSpeed;
 149   UINTN                     MaxPacket;
 150   UINT8                     HubAddr;
 151   UINT8                     HubPort;
 152   UINT8                     Toggle;   // Data toggle, not used for control transfer
 153   UINTN                     Type;
 154   UINTN                     PollRate; // Polling interval used by EHCI
 155 } USB_ENDPOINT;
 156
 157 //
 158 // Software QTD strcture, this is used to manage all the
 159 // QTD generated from a URB. Don't add fields before QtdHw.
 160 //
 161 struct _PEI_EHC_QTD {
 162   QTD_HW            QtdHw;
 163   UINT32            Signature;
 164   EFI_LIST_ENTRY    QtdList;         // The list of QTDs to one end point
 165   UINT8             *Data;           // Buffer of the original data
 166   UINTN             DataLen;         // Original amount of data in this QTD
 167 };
 168
 169 //
 170 // Software QH structure. All three different transaction types
 171 // supported by UEFI USB, that is the control/bulk/interrupt
 172 // transfers use the queue head and queue token strcuture.
 173 //
 174 // Interrupt QHs are linked to periodic frame list in the reversed
 175 // 2^N tree. Each interrupt QH is linked to the list starting at
 176 // frame 0. There is a dummy interrupt QH linked to each frame as
 177 // a sentinental whose polling interval is 1. Synchronous interrupt
 178 // transfer is linked after this dummy QH.
 179 //
 180 // For control/bulk transfer, only synchronous (in the sense of UEFI)
 181 // transfer is supported. A dummy QH is linked to EHCI AsyncListAddr
 182 // as the reclamation header. New transfer is inserted after this QH.
 183 //
 184 struct _PEI_EHC_QH {
 185   QH_HW             QhHw;
 186   UINT32            Signature;
 187   PEI_EHC_QH        *NextQh;          // The queue head pointed to by horizontal link
 188   EFI_LIST_ENTRY    Qtds;             // The list of QTDs to this queue head
 189   UINTN             Interval;
 190 };
 191
 192 //
 193 // URB (Usb Request Block) contains information for all kinds of
 194 // usb requests.
 195 //
 196 struct _PEI_URB {
 197   UINT32                             Signature;
 198   EFI_LIST_ENTRY                     UrbList;
 199
 200   //
 201   // Transaction information
 202   //
 203   USB_ENDPOINT                       Ep;
 204   EFI_USB_DEVICE_REQUEST             *Request;    // Control transfer only
 205   VOID                               *RequestPhy; // Address of the mapped request
 206   VOID                               *RequestMap;
 207   VOID                               *Data;
 208   UINTN                              DataLen;
 209   VOID                               *DataPhy;  // Address of the mapped user data
 210   VOID                               *DataMap;
 211   EFI_ASYNC_USB_TRANSFER_CALLBACK    Callback;
 212   VOID                               *Context;
 213
 214   //
 215   // Schedule data
 216   //
 217   PEI_EHC_QH                         *Qh;
 218
 219   //
 220   // Transaction result
 221   //
 222   UINT32                             Result;
 223   UINTN                              Completed; // completed data length
 224   UINT8                              DataToggle;
 225 };
 226
 227 /**
 228   Delete a single asynchronous interrupt transfer for
 229   the device and endpoint.
 230
 231   @param  Ehc         The EHCI device.
 232   @param  Data        Current data not associated with a QTD.
 233   @param  DataLen     The length of the data.
 234   @param  PktId       Packet ID to use in the QTD.
 235   @param  Toggle      Data toggle to use in the QTD.
 236   @param  MaxPacket   Maximu packet length of the endpoint.
 237
 238   @retval the pointer to the created QTD or NULL if failed to create one.
 239
 240 **/
 241 PEI_EHC_QTD *
 242 EhcCreateQtd (
 243   IN PEI_USB2_HC_DEV  *Ehc,
 244   IN UINT8            *Data,
 245   IN UINTN            DataLen,
 246   IN UINT8            PktId,
 247   IN UINT8            Toggle,
 248   IN UINTN            MaxPacket
 249   )
 250 ;
 251
 252 /**
 253   Allocate and initialize a EHCI queue head.
 254
 255   @param  Ehci      The EHCI device.
 256   @param  Ep        The endpoint to create queue head for.
 257
 258   @retval the pointer to the created queue head or NULL if failed to create one.
 259
 260 **/
 261 PEI_EHC_QH *
 262 EhcCreateQh (
 263   IN PEI_USB2_HC_DEV  *Ehci,
 264   IN USB_ENDPOINT     *Ep
 265   )
 266 ;
 267
 268 /**
 269   Free an allocated URB. It is possible for it to be partially inited.
 270
 271   @param  Ehc         The EHCI device.
 272   @param  Urb         The URB to free.
 273
 274 **/
 275 VOID
 276 EhcFreeUrb (
 277   IN PEI_USB2_HC_DEV  *Ehc,
 278   IN PEI_URB          *Urb
 279   )
 280 ;
 281
 282 /**
 283   Create a new URB and its associated QTD.
 284
 285   @param  Ehc               The EHCI device.
 286   @param  DevAddr           The device address.
 287   @param  EpAddr            Endpoint addrress & its direction.
 288   @param  DevSpeed          The device speed.
 289   @param  Toggle            Initial data toggle to use.
 290   @param  MaxPacket         The max packet length of the endpoint.
 291   @param  Hub               The transaction translator to use.
 292   @param  Type              The transaction type.
 293   @param  Request           The standard USB request for control transfer.
 294   @param  Data              The user data to transfer.
 295   @param  DataLen           The length of data buffer.
 296   @param  Callback          The function to call when data is transferred.
 297   @param  Context           The context to the callback.
 298   @param  Interval          The interval for interrupt transfer.
 299
 300   @retval the pointer to the created URB or NULL.
 301
 302 **/
 303 PEI_URB *
 304 EhcCreateUrb (
 305   IN PEI_USB2_HC_DEV                     *Ehc,
 306   IN UINT8                               DevAddr,
 307   IN UINT8                               EpAddr,
 308   IN UINT8                               DevSpeed,
 309   IN UINT8                               Toggle,
 310   IN UINTN                               MaxPacket,
 311   IN EFI_USB2_HC_TRANSACTION_TRANSLATOR  *Hub,
 312   IN UINTN                               Type,
 313   IN EFI_USB_DEVICE_REQUEST              *Request,
 314   IN VOID                                *Data,
 315   IN UINTN                               DataLen,
 316   IN EFI_ASYNC_USB_TRANSFER_CALLBACK     Callback,
 317   IN VOID                                *Context,
 318   IN UINTN                               Interval
 319   )
 320 ;
 321
 322 #endif