MdeModulePkg/Bus/Pci/EhciDxe/EhciUrb.h

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