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