1 /** @file 2 Usb Peim definition. 3 4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved. <BR> 5 6 SPDX-License-Identifier: BSD-2-Clause-Patent 7 8 **/ 9 10 #ifndef _PEI_USB_PEIM_H_ 11 #define _PEI_USB_PEIM_H_ 12 13 14 #include <PiPei.h> 15 16 #include <Ppi/UsbHostController.h> 17 #include <Ppi/Usb2HostController.h> 18 #include <Ppi/UsbIo.h> 19 20 #include <Library/DebugLib.h> 21 #include <Library/PeimEntryPoint.h> 22 #include <Library/PeiServicesLib.h> 23 #include <Library/BaseMemoryLib.h> 24 #include <Library/TimerLib.h> 25 #include <Library/PcdLib.h> 26 27 #include <IndustryStandard/Usb.h> 28 29 // 30 // A common header for usb standard descriptor. 31 // Each stand descriptor has a length and type. 32 // 33 #pragma pack(1) 34 typedef struct { 35 UINT8 Len; 36 UINT8 Type; 37 } USB_DESC_HEAD; 38 #pragma pack() 39 40 #define MAX_INTERFACE 8 41 #define MAX_ENDPOINT 16 42 43 #define PEI_USB_DEVICE_SIGNATURE SIGNATURE_32 ('U', 's', 'b', 'D') 44 typedef struct { 45 UINTN Signature; 46 PEI_USB_IO_PPI UsbIoPpi; 47 EFI_PEI_PPI_DESCRIPTOR UsbIoPpiList; 48 UINT16 MaxPacketSize0; 49 UINT16 DataToggle; 50 UINT8 DeviceAddress; 51 UINT8 DeviceSpeed; 52 UINT8 IsHub; 53 UINT8 DownStreamPortNo; 54 UINTN AllocateAddress; 55 PEI_USB_HOST_CONTROLLER_PPI *UsbHcPpi; 56 PEI_USB2_HOST_CONTROLLER_PPI *Usb2HcPpi; 57 UINT8 ConfigurationData[1024]; 58 EFI_USB_CONFIG_DESCRIPTOR *ConfigDesc; 59 EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDesc; 60 EFI_USB_INTERFACE_DESCRIPTOR *InterfaceDescList[MAX_INTERFACE]; 61 EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDesc[MAX_ENDPOINT]; 62 EFI_USB_ENDPOINT_DESCRIPTOR *EndpointDescList[MAX_INTERFACE][MAX_ENDPOINT]; 63 EFI_USB2_HC_TRANSACTION_TRANSLATOR Translator; 64 UINT8 Tier; 65 } PEI_USB_DEVICE; 66 67 #define PEI_USB_DEVICE_FROM_THIS(a) CR (a, PEI_USB_DEVICE, UsbIoPpi, PEI_USB_DEVICE_SIGNATURE) 68 69 #define USB_BIT_IS_SET(Data, Bit) ((BOOLEAN)(((Data) & (Bit)) == (Bit))) 70 71 #define USB_BUS_1_MILLISECOND 1000 72 73 // 74 // Wait for port reset, refers to specification 75 // [USB20-7.1.7.5, it says 10ms for hub and 50ms for 76 // root hub] 77 // 78 // According to USB2.0, Chapter 11.5.1.5 Resetting, 79 // the worst case for TDRST is 20ms 80 // 81 #define USB_SET_PORT_RESET_STALL (20 * USB_BUS_1_MILLISECOND) 82 #define USB_SET_ROOT_PORT_RESET_STALL (50 * USB_BUS_1_MILLISECOND) 83 84 // 85 // Wait for clear roothub port reset, set by experience 86 // 87 #define USB_CLR_ROOT_PORT_RESET_STALL (20 * USB_BUS_1_MILLISECOND) 88 89 // 90 // Wait for port statue reg change, set by experience 91 // 92 #define USB_WAIT_PORT_STS_CHANGE_STALL (100) 93 94 // 95 // Host software return timeout if port status doesn't change 96 // after 500ms(LOOP * STALL = 5000 * 0.1ms), set by experience 97 // 98 #define USB_WAIT_PORT_STS_CHANGE_LOOP 5000 99 100 // 101 // Wait for hub port power-on, refers to specification 102 // [USB20-11.23.2] 103 // 104 #define USB_SET_PORT_POWER_STALL (2 * USB_BUS_1_MILLISECOND) 105 106 // 107 // Wait for set device address, refers to specification 108 // [USB20-9.2.6.3, it says 2ms] 109 // 110 #define USB_SET_DEVICE_ADDRESS_STALL (2 * USB_BUS_1_MILLISECOND) 111 112 // 113 // Wait for get configuration descriptor, set by experience 114 // 115 #define USB_GET_CONFIG_DESCRIPTOR_STALL (1 * USB_BUS_1_MILLISECOND) 116 117 /** 118 Submits control transfer to a target USB device. 119 120 @param PeiServices The pointer of EFI_PEI_SERVICES. 121 @param This The pointer of PEI_USB_IO_PPI. 122 @param Request USB device request to send. 123 @param Direction Specifies the data direction for the data stage. 124 @param Timeout Indicates the maximum timeout, in millisecond. If Timeout 125 is 0, then the caller must wait for the function to be 126 completed until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 127 @param Data Data buffer to be transmitted or received from USB device. 128 @param DataLength The size (in bytes) of the data buffer. 129 130 @retval EFI_SUCCESS Transfer was completed successfully. 131 @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resources. 132 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 133 @retval EFI_TIMEOUT Transfer failed due to timeout. 134 @retval EFI_DEVICE_ERROR Transfer failed due to host controller or device error. 135 136 **/ 137 EFI_STATUS 138 EFIAPI 139 PeiUsbControlTransfer ( 140 IN EFI_PEI_SERVICES **PeiServices, 141 IN PEI_USB_IO_PPI *This, 142 IN EFI_USB_DEVICE_REQUEST *Request, 143 IN EFI_USB_DATA_DIRECTION Direction, 144 IN UINT32 Timeout, 145 IN OUT VOID *Data, OPTIONAL 146 IN UINTN DataLength OPTIONAL 147 ); 148 149 /** 150 Submits bulk transfer to a bulk endpoint of a USB device. 151 152 @param PeiServices The pointer of EFI_PEI_SERVICES. 153 @param This The pointer of PEI_USB_IO_PPI. 154 @param DeviceEndpoint Endpoint number and its direction in bit 7. 155 @param Data A pointer to the buffer of data to transmit 156 from or receive into. 157 @param DataLength The lenght of the data buffer. 158 @param Timeout Indicates the maximum time, in millisecond, which the 159 transfer is allowed to complete. If Timeout is 0, then 160 the caller must wait for the function to be completed 161 until EFI_SUCCESS or EFI_DEVICE_ERROR is returned. 162 163 @retval EFI_SUCCESS The transfer was completed successfully. 164 @retval EFI_OUT_OF_RESOURCES The transfer failed due to lack of resource. 165 @retval EFI_INVALID_PARAMETER Parameters are invalid. 166 @retval EFI_TIMEOUT The transfer failed due to timeout. 167 @retval EFI_DEVICE_ERROR The transfer failed due to host controller error. 168 169 **/ 170 EFI_STATUS 171 EFIAPI 172 PeiUsbBulkTransfer ( 173 IN EFI_PEI_SERVICES **PeiServices, 174 IN PEI_USB_IO_PPI *This, 175 IN UINT8 DeviceEndpoint, 176 IN OUT VOID *Data, 177 IN OUT UINTN *DataLength, 178 IN UINTN Timeout 179 ); 180 181 /** 182 Get the usb interface descriptor. 183 184 @param PeiServices General-purpose services that are available to every PEIM. 185 @param This Indicates the PEI_USB_IO_PPI instance. 186 @param InterfaceDescriptor Request interface descriptor. 187 188 189 @retval EFI_SUCCESS Usb interface descriptor is obtained successfully. 190 191 **/ 192 EFI_STATUS 193 EFIAPI 194 PeiUsbGetInterfaceDescriptor ( 195 IN EFI_PEI_SERVICES **PeiServices, 196 IN PEI_USB_IO_PPI *This, 197 OUT EFI_USB_INTERFACE_DESCRIPTOR **InterfaceDescriptor 198 ); 199 200 /** 201 Get the usb endpoint descriptor. 202 203 @param PeiServices General-purpose services that are available to every PEIM. 204 @param This Indicates the PEI_USB_IO_PPI instance. 205 @param EndpointIndex The valid index of the specified endpoint. 206 @param EndpointDescriptor Request endpoint descriptor. 207 208 @retval EFI_SUCCESS Usb endpoint descriptor is obtained successfully. 209 @retval EFI_NOT_FOUND Usb endpoint descriptor is NOT found. 210 211 **/ 212 EFI_STATUS 213 EFIAPI 214 PeiUsbGetEndpointDescriptor ( 215 IN EFI_PEI_SERVICES **PeiServices, 216 IN PEI_USB_IO_PPI *This, 217 IN UINT8 EndpointIndex, 218 OUT EFI_USB_ENDPOINT_DESCRIPTOR **EndpointDescriptor 219 ); 220 221 /** 222 Reset the port and re-configure the usb device. 223 224 @param PeiServices General-purpose services that are available to every PEIM. 225 @param This Indicates the PEI_USB_IO_PPI instance. 226 227 @retval EFI_SUCCESS Usb device is reset and configured successfully. 228 @retval Others Other failure occurs. 229 230 **/ 231 EFI_STATUS 232 EFIAPI 233 PeiUsbPortReset ( 234 IN EFI_PEI_SERVICES **PeiServices, 235 IN PEI_USB_IO_PPI *This 236 ); 237 238 /** 239 Send reset signal over the given root hub port. 240 241 @param PeiServices Describes the list of possible PEI Services. 242 @param UsbHcPpi The pointer of PEI_USB_HOST_CONTROLLER_PPI instance. 243 @param Usb2HcPpi The pointer of PEI_USB2_HOST_CONTROLLER_PPI instance. 244 @param PortNum The port to be reset. 245 @param RetryIndex The retry times. 246 247 **/ 248 VOID 249 ResetRootPort ( 250 IN EFI_PEI_SERVICES **PeiServices, 251 IN PEI_USB_HOST_CONTROLLER_PPI *UsbHcPpi, 252 IN PEI_USB2_HOST_CONTROLLER_PPI *Usb2HcPpi, 253 IN UINT8 PortNum, 254 IN UINT8 RetryIndex 255 ); 256 257 #endif 258