1 /** @file 2 Private Header file for Usb Host Controller PEIM 3 4 Copyright (c) 2010, Intel Corporation. All rights reserved.<BR> 5 6 This program and the accompanying materials 7 are licensed and made available under the terms and conditions 8 of the BSD License which accompanies this distribution. The 9 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 typedef struct _PEI_EHC_QTD PEI_EHC_QTD; 21 typedef struct _PEI_EHC_QH PEI_EHC_QH; 22 typedef struct _PEI_URB PEI_URB; 23 24 #define EHC_CTRL_TRANSFER 0x01 25 #define EHC_BULK_TRANSFER 0x02 26 #define EHC_INT_TRANSFER_SYNC 0x04 27 #define EHC_INT_TRANSFER_ASYNC 0x08 28 29 #define EHC_QTD_SIG SIGNATURE_32 ('U', 'S', 'B', 'T') 30 #define EHC_QH_SIG SIGNATURE_32 ('U', 'S', 'B', 'H') 31 #define EHC_URB_SIG SIGNATURE_32 ('U', 'S', 'B', 'R') 32 33 // 34 // Hardware related bit definitions 35 // 36 #define EHC_TYPE_ITD 0x00 37 #define EHC_TYPE_QH 0x02 38 #define EHC_TYPE_SITD 0x04 39 #define EHC_TYPE_FSTN 0x06 40 41 #define QH_NAK_RELOAD 3 42 #define QH_HSHBW_MULTI 1 43 44 #define QTD_MAX_ERR 3 45 #define QTD_PID_OUTPUT 0x00 46 #define QTD_PID_INPUT 0x01 47 #define QTD_PID_SETUP 0x02 48 49 #define QTD_STAT_DO_OUT 0 50 #define QTD_STAT_DO_SS 0 51 #define QTD_STAT_DO_PING 0x01 52 #define QTD_STAT_DO_CS 0x02 53 #define QTD_STAT_TRANS_ERR 0x08 54 #define QTD_STAT_BABBLE_ERR 0x10 55 #define QTD_STAT_BUFF_ERR 0x20 56 #define QTD_STAT_HALTED 0x40 57 #define QTD_STAT_ACTIVE 0x80 58 #define QTD_STAT_ERR_MASK (QTD_STAT_TRANS_ERR | QTD_STAT_BABBLE_ERR | QTD_STAT_BUFF_ERR) 59 60 #define QTD_MAX_BUFFER 4 61 #define QTD_BUF_LEN 4096 62 #define QTD_BUF_MASK 0x0FFF 63 64 #define QH_MICROFRAME_0 0x01 65 #define QH_MICROFRAME_1 0x02 66 #define QH_MICROFRAME_2 0x04 67 #define QH_MICROFRAME_3 0x08 68 #define QH_MICROFRAME_4 0x10 69 #define QH_MICROFRAME_5 0x20 70 #define QH_MICROFRAME_6 0x40 71 #define QH_MICROFRAME_7 0x80 72 73 #define USB_ERR_SHORT_PACKET 0x200 74 75 // 76 // Fill in the hardware link point: pass in a EHC_QH/QH_HW 77 // pointer to QH_LINK; A EHC_QTD/QTD_HW pointer to QTD_LINK 78 // 79 #define QH_LINK(Addr, Type, Term) \ 80 ((UINT32) ((EHC_LOW_32BIT (Addr) & 0xFFFFFFE0) | (Type) | ((Term) ? 1 : 0))) 81 82 #define QTD_LINK(Addr, Term) QH_LINK((Addr), 0, (Term)) 83 84 // 85 // The defination of EHCI hardware used data structure for 86 // little endian architecture. The QTD and QH structures 87 // are required to be 32 bytes aligned. Don't add members 88 // to the head of the associated software strucuture. 89 // 90 #pragma pack(1) 91 typedef struct { 92 UINT32 NextQtd; 93 UINT32 AltNext; 94 95 UINT32 Status : 8; 96 UINT32 Pid : 2; 97 UINT32 ErrCnt : 2; 98 UINT32 CurPage : 3; 99 UINT32 Ioc : 1; 100 UINT32 TotalBytes : 15; 101 UINT32 DataToggle : 1; 102 103 UINT32 Page[5]; 104 UINT32 PageHigh[5]; 105 } QTD_HW; 106 107 typedef struct { 108 UINT32 HorizonLink; 109 // 110 // Endpoint capabilities/Characteristics DWord 1 and DWord 2 111 // 112 UINT32 DeviceAddr : 7; 113 UINT32 Inactive : 1; 114 UINT32 EpNum : 4; 115 UINT32 EpSpeed : 2; 116 UINT32 DtCtrl : 1; 117 UINT32 ReclaimHead : 1; 118 UINT32 MaxPacketLen : 11; 119 UINT32 CtrlEp : 1; 120 UINT32 NakReload : 4; 121 122 UINT32 SMask : 8; 123 UINT32 CMask : 8; 124 UINT32 HubAddr : 7; 125 UINT32 PortNum : 7; 126 UINT32 Multiplier : 2; 127 128 // 129 // Transaction execution overlay area 130 // 131 UINT32 CurQtd; 132 UINT32 NextQtd; 133 UINT32 AltQtd; 134 135 UINT32 Status : 8; 136 UINT32 Pid : 2; 137 UINT32 ErrCnt : 2; 138 UINT32 CurPage : 3; 139 UINT32 Ioc : 1; 140 UINT32 TotalBytes : 15; 141 UINT32 DataToggle : 1; 142 143 UINT32 Page[5]; 144 UINT32 PageHigh[5]; 145 } QH_HW; 146 #pragma pack() 147 148 149 // 150 // Endpoint address and its capabilities 151 // 152 typedef struct _USB_ENDPOINT { 153 UINT8 DevAddr; 154 UINT8 EpAddr; // Endpoint address, no direction encoded in 155 EFI_USB_DATA_DIRECTION Direction; 156 UINT8 DevSpeed; 157 UINTN MaxPacket; 158 UINT8 HubAddr; 159 UINT8 HubPort; 160 UINT8 Toggle; // Data toggle, not used for control transfer 161 UINTN Type; 162 UINTN PollRate; // Polling interval used by EHCI 163 } USB_ENDPOINT; 164 165 // 166 // Software QTD strcture, this is used to manage all the 167 // QTD generated from a URB. Don't add fields before QtdHw. 168 // 169 struct _PEI_EHC_QTD { 170 QTD_HW QtdHw; 171 UINT32 Signature; 172 EFI_LIST_ENTRY QtdList; // The list of QTDs to one end point 173 UINT8 *Data; // Buffer of the original data 174 UINTN DataLen; // Original amount of data in this QTD 175 }; 176 177 178 179 // 180 // Software QH structure. All three different transaction types 181 // supported by UEFI USB, that is the control/bulk/interrupt 182 // transfers use the queue head and queue token strcuture. 183 // 184 // Interrupt QHs are linked to periodic frame list in the reversed 185 // 2^N tree. Each interrupt QH is linked to the list starting at 186 // frame 0. There is a dummy interrupt QH linked to each frame as 187 // a sentinental whose polling interval is 1. Synchronous interrupt 188 // transfer is linked after this dummy QH. 189 // 190 // For control/bulk transfer, only synchronous (in the sense of UEFI) 191 // transfer is supported. A dummy QH is linked to EHCI AsyncListAddr 192 // as the reclamation header. New transfer is inserted after this QH. 193 // 194 struct _PEI_EHC_QH { 195 QH_HW QhHw; 196 UINT32 Signature; 197 PEI_EHC_QH *NextQh; // The queue head pointed to by horizontal link 198 EFI_LIST_ENTRY Qtds; // The list of QTDs to this queue head 199 UINTN Interval; 200 }; 201 202 // 203 // URB (Usb Request Block) contains information for all kinds of 204 // usb requests. 205 // 206 struct _PEI_URB { 207 UINT32 Signature; 208 EFI_LIST_ENTRY UrbList; 209 210 // 211 // Transaction information 212 // 213 USB_ENDPOINT Ep; 214 EFI_USB_DEVICE_REQUEST *Request; // Control transfer only 215 VOID *RequestPhy; // Address of the mapped request 216 VOID *RequestMap; 217 VOID *Data; 218 UINTN DataLen; 219 VOID *DataPhy; // Address of the mapped user data 220 VOID *DataMap; 221 EFI_ASYNC_USB_TRANSFER_CALLBACK Callback; 222 VOID *Context; 223 224 // 225 // Schedule data 226 // 227 PEI_EHC_QH *Qh; 228 229 // 230 // Transaction result 231 // 232 UINT32 Result; 233 UINTN Completed; // completed data length 234 UINT8 DataToggle; 235 }; 236 237 /** 238 Delete a single asynchronous interrupt transfer for 239 the device and endpoint. 240 241 @param Ehc The EHCI device. 242 @param Data Current data not associated with a QTD. 243 @param DataLen The length of the data. 244 @param PktId Packet ID to use in the QTD. 245 @param Toggle Data toggle to use in the QTD. 246 @param MaxPacket Maximu packet length of the endpoint. 247 248 @retval the pointer to the created QTD or NULL if failed to create one. 249 250 **/ 251 PEI_EHC_QTD * 252 EhcCreateQtd ( 253 IN PEI_USB2_HC_DEV *Ehc, 254 IN UINT8 *Data, 255 IN UINTN DataLen, 256 IN UINT8 PktId, 257 IN UINT8 Toggle, 258 IN UINTN MaxPacket 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 @retval the pointer to the created queue head or NULL if failed to create one. 269 270 **/ 271 PEI_EHC_QH * 272 EhcCreateQh ( 273 IN PEI_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 PEI_USB2_HC_DEV *Ehc, 288 IN PEI_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 @retval the pointer to the created URB or NULL. 311 312 **/ 313 PEI_URB * 314 EhcCreateUrb ( 315 IN PEI_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 ; 331 #endif 332