MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h

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