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 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 VOID *Data; 220 UINTN DataLen; 221 VOID *DataPhy; // Address of the mapped user data 222 VOID *DataMap; 223 EFI_ASYNC_USB_TRANSFER_CALLBACK Callback; 224 VOID *Context; 225 226 // 227 // Schedule data 228 // 229 EHC_QH *Qh; 230 231 // 232 // Transaction result 233 // 234 UINT32 Result; 235 UINTN Completed; // completed data length 236 UINT8 DataToggle; 237 }; 238 239 240 241 /** 242 Create a single QTD to hold the data. 243 244 @param Ehc The EHCI device. 245 @param Data The cpu memory address of current data not associated with a QTD. 246 @param DataPhy The pci bus address of current data not associated with a QTD. 247 @param DataLen The length of the data. 248 @param PktId Packet ID to use in the QTD. 249 @param Toggle Data toggle to use in the QTD. 250 @param MaxPacket Maximu packet length of the endpoint. 251 252 @return Created QTD or NULL if failed to create one. 253 254 **/ 255 EHC_QTD * 256 EhcCreateQtd ( 257 IN USB2_HC_DEV *Ehc, 258 IN UINT8 *Data, 259 IN UINT8 *DataPhy, 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 **/ 291 VOID 292 EhcFreeUrb ( 293 IN USB2_HC_DEV *Ehc, 294 IN URB *Urb 295 ); 296 297 298 /** 299 Create a new URB and its associated QTD. 300 301 @param Ehc The EHCI device. 302 @param DevAddr The device address. 303 @param EpAddr Endpoint addrress & its direction. 304 @param DevSpeed The device speed. 305 @param Toggle Initial data toggle to use. 306 @param MaxPacket The max packet length of the endpoint. 307 @param Hub The transaction translator to use. 308 @param Type The transaction type. 309 @param Request The standard USB request for control transfer. 310 @param Data The user data to transfer. 311 @param DataLen The length of data buffer. 312 @param Callback The function to call when data is transferred. 313 @param Context The context to the callback. 314 @param Interval The interval for interrupt transfer. 315 316 @return Created URB or NULL. 317 318 **/ 319 URB * 320 EhcCreateUrb ( 321 IN USB2_HC_DEV *Ehc, 322 IN UINT8 DevAddr, 323 IN UINT8 EpAddr, 324 IN UINT8 DevSpeed, 325 IN UINT8 Toggle, 326 IN UINTN MaxPacket, 327 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Hub, 328 IN UINTN Type, 329 IN EFI_USB_DEVICE_REQUEST *Request, 330 IN VOID *Data, 331 IN UINTN DataLen, 332 IN EFI_ASYNC_USB_TRANSFER_CALLBACK Callback, 333 IN VOID *Context, 334 IN UINTN Interval 335 ); 336 #endif 337