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