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