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