1 /** @file 2 Defines the USB Host Controller PPI that provides I/O services for a USB Host 3 Controller that may be used to access recovery devices. These interfaces are 4 modeled on the UEFI 2.3 specification EFI_USB2_HOST_CONTROLLER_PROTOCOL. 5 Refer to section 16.1 of the UEFI 2.3 Specification for more information on 6 these interfaces. 7 8 Copyright (c) 2010 - 2018, Intel Corporation. All rights reserved. <BR> 9 10 SPDX-License-Identifier: BSD-2-Clause-Patent 11 12 **/ 13 14 #ifndef _PEI_USB2_HOST_CONTROLLER_PPI_H_ 15 #define _PEI_USB2_HOST_CONTROLLER_PPI_H_ 16 17 #include <Protocol/Usb2HostController.h> 18 19 /// 20 /// Global ID for the PEI_USB2_HOST_CONTROLLER_PPI. 21 /// 22 #define PEI_USB2_HOST_CONTROLLER_PPI_GUID \ 23 { \ 24 0xa7d09fe1, 0x74d4, 0x4ba5, { 0x84, 0x7c, 0x12, 0xed, 0x5b, 0x19, 0xad, 0xe4 } \ 25 } 26 27 /// 28 /// Forward declaration for the PEI_USB2_HOST_CONTROLLER_PPI. 29 /// 30 typedef struct _PEI_USB2_HOST_CONTROLLER_PPI PEI_USB2_HOST_CONTROLLER_PPI; 31 32 /** 33 Initiate a USB control transfer using a specific USB Host controller on the USB bus. 34 35 @param[in] PeiServices The pointer to the PEI Services Table. 36 @param[in] This The pointer to this instance of the 37 PEI_USB2_HOST_CONTROLLER_PPI. 38 @param[in] DeviceAddress Represents the address of the target device 39 on the USB. 40 @param[in] DeviceSpeed Indicates device speed. 41 @param[in] MaximumPacketLength Indicates the maximum packet size that the 42 default control transfer 43 endpoint is capable of sending or receiving. 44 @param[in] Request A pointer to the USB device request that 45 will be sent to the USB device. 46 @param[in] TransferDirection Specifies the data direction for the transfer. 47 There are three values available: 48 EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. 49 @param[in,out] Data A pointer to the buffer of data that will 50 be transmitted to USB device or 51 received from USB device. 52 @param[in,out] DataLength On input, indicates the size, in bytes, of 53 the data buffer specified by Data. 54 On output, indicates the amount of data 55 actually transferred. 56 @param[in] TimeOut Indicates the maximum time, in milliseconds, 57 that the transfer is allowed to complete. 58 If Timeout is 0, then the caller must wait for 59 the function to be completed until EFI_SUCCESS 60 or EFI_DEVICE_ERROR is returned. 61 @param[in] Translator A pointer to the transaction translator data. 62 @param[out] TransferResult A pointer to the detailed result information 63 generated by this control transfer. 64 65 @retval EFI_SUCCESS The control transfer was completed successfully. 66 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller 67 or device error. 68 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 69 @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due to a lack of resources. 70 @retval EFI_TIMEOUT The control transfer failed due to timeout. 71 72 73 **/ 74 typedef 75 EFI_STATUS 76 (EFIAPI *PEI_USB2_HOST_CONTROLLER_CONTROL_TRANSFER)( 77 IN EFI_PEI_SERVICES **PeiServices, 78 IN PEI_USB2_HOST_CONTROLLER_PPI *This, 79 IN UINT8 DeviceAddress, 80 IN UINT8 DeviceSpeed, 81 IN UINTN MaximumPacketLength, 82 IN USB_DEVICE_REQUEST *Request, 83 IN EFI_USB_DATA_DIRECTION TransferDirection, 84 IN OUT VOID *Data OPTIONAL, 85 IN OUT UINTN *DataLength OPTIONAL, 86 IN UINTN TimeOut, 87 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, 88 OUT UINT32 *TransferResult 89 ); 90 91 /** 92 Initiate a USB bulk transfer using a specific USB Host controller on the USB bus. 93 94 @param[in] PeiServices The pointer to the PEI Services Table. 95 @param[in] This The pointer to this instance of the 96 PEI_USB2_HOST_CONTROLLER_PPI. 97 @param[in] DeviceAddress Represents the address of the target device 98 on the USB. 99 @param[in] EndPointAddress The combination of an endpoint number and 100 an endpoint direction of the target USB device. 101 @param[in] DeviceSpeed Indicates device speed. 102 @param[in] MaximumPacketLength Indicates the maximum packet size the target 103 endpoint is capable of sending or receiving. 104 @param[in,out] Data Array of pointers to the buffers of data 105 that will be transmitted to USB device or 106 received from USB device. 107 @param[in,out] DataLength When input, indicates the size, in bytes, of 108 the data buffers specified by Data. When output, 109 indicates the data size actually transferred. 110 @param[in,out] DataToggle A pointer to the data toggle value. 111 @param[in] TimeOut Indicates the maximum time, in milliseconds, 112 in which the transfer is allowed to complete. 113 If Timeout is 0, then the caller must wait for 114 the function to be completed until EFI_SUCCESS 115 or EFI_DEVICE_ERROR is returned. 116 @param[in] Translator A pointer to the transaction translator data. 117 @param[out] TransferResult A pointer to the detailed result information 118 of the bulk transfer. 119 120 @retval EFI_SUCCESS The bulk transfer was completed successfully. 121 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. 122 Caller should check TransferResult for detailed error information. 123 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 124 @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be submitted due to a lack of resources. 125 @retval EFI_TIMEOUT The bulk transfer failed due to timeout. 126 127 128 **/ 129 typedef 130 EFI_STATUS 131 (EFIAPI *PEI_USB2_HOST_CONTROLLER_BULK_TRANSFER)( 132 IN EFI_PEI_SERVICES **PeiServices, 133 IN PEI_USB2_HOST_CONTROLLER_PPI *This, 134 IN UINT8 DeviceAddress, 135 IN UINT8 EndPointAddress, 136 IN UINT8 DeviceSpeed, 137 IN UINTN MaximumPacketLength, 138 IN OUT VOID *Data[EFI_USB_MAX_BULK_BUFFER_NUM], 139 IN OUT UINTN *DataLength, 140 IN OUT UINT8 *DataToggle, 141 IN UINTN TimeOut, 142 IN EFI_USB2_HC_TRANSACTION_TRANSLATOR *Translator, 143 OUT UINT32 *TransferResult 144 ); 145 146 /** 147 Retrieves the number of root hub ports. 148 149 @param[in] PeiServices The pointer to the PEI Services Table. 150 @param[in] This The pointer to this instance of the 151 PEI_USB2_HOST_CONTROLLER_PPI. 152 @param[out] PortNumber The pointer to the number of the root hub ports. 153 154 @retval EFI_SUCCESS The port number was retrieved successfully. 155 @retval EFI_INVALID_PARAMETER PortNumber is NULL. 156 157 **/ 158 typedef 159 EFI_STATUS 160 (EFIAPI *PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER)( 161 IN EFI_PEI_SERVICES **PeiServices, 162 IN PEI_USB2_HOST_CONTROLLER_PPI *This, 163 OUT UINT8 *PortNumber 164 ); 165 166 /** 167 Retrieves the current status of a USB root hub port. 168 169 @param[in] PeiServices The pointer to the PEI Services Table. 170 @param[in] This The pointer to this instance of the 171 PEI_USB2_HOST_CONTROLLER_PPI. 172 @param[in] PortNumber Specifies the root hub port from which the status is 173 to be retrieved. 174 This value is zero based. 175 @param[out] PortStatus A pointer to the current port status bits and port 176 status change bits. 177 178 @retval EFI_SUCCESS The status of the USB root hub port specified by 179 PortNumber was returned in PortStatus. 180 @retval EFI_INVALID_PARAMETER PortNumber is invalid. 181 182 **/ 183 typedef 184 EFI_STATUS 185 (EFIAPI *PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS)( 186 IN EFI_PEI_SERVICES **PeiServices, 187 IN PEI_USB2_HOST_CONTROLLER_PPI *This, 188 IN UINT8 PortNumber, 189 OUT EFI_USB_PORT_STATUS *PortStatus 190 ); 191 192 /** 193 Sets a feature for the specified root hub port. 194 195 @param[in] PeiServices The pointer to the PEI Services Table. 196 @param[in] This The pointer to this instance of the 197 PEI_USB2_HOST_CONTROLLER_PPI. 198 @param[in] PortNumber Specifies the root hub port whose feature is requested 199 to be set. This value is zero based. 200 @param[in] PortFeature Indicates the feature selector associated with the feature 201 set request. 202 203 @retval EFI_SUCCESS The feature specified by PortFeature was set for 204 the USB root hub port specified by PortNumber. 205 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid 206 for this function. 207 @retval EFI_TIMEOUT The time out occurred 208 209 **/ 210 typedef 211 EFI_STATUS 212 (EFIAPI *PEI_USB2_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE)( 213 IN EFI_PEI_SERVICES **PeiServices, 214 IN PEI_USB2_HOST_CONTROLLER_PPI *This, 215 IN UINT8 PortNumber, 216 IN EFI_USB_PORT_FEATURE PortFeature 217 ); 218 219 /** 220 Clears a feature for the specified root hub port. 221 222 @param[in] PeiServices The pointer to the PEI Services Table. 223 @param[in] This The pointer to this instance of the 224 PEI_USB2_HOST_CONTROLLER_PPI. 225 @param[in] PortNumber Specifies the root hub port whose feature is 226 requested to be cleared. 227 @param[in] PortFeature Indicates the feature selector associated with the 228 feature clear request. 229 230 @return EFI_SUCCESS The feature specified by PortFeature was cleared 231 for the USB root hub port specified by PortNumber. 232 @return EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid. 233 234 **/ 235 typedef 236 EFI_STATUS 237 (EFIAPI *PEI_USB2_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE)( 238 IN EFI_PEI_SERVICES **PeiServices, 239 IN PEI_USB2_HOST_CONTROLLER_PPI *This, 240 IN UINT8 PortNumber, 241 IN EFI_USB_PORT_FEATURE PortFeature 242 ); 243 244 /// 245 /// This PPI contains a set of services to interact with the USB host controller. 246 /// These interfaces are modeled on the UEFI 2.3 specification protocol 247 /// EFI_USB2_HOST_CONTROLLER_PROTOCOL. Refer to section 16.1 of the UEFI 2.3 248 /// Specification for more information on these interfaces. 249 /// 250 struct _PEI_USB2_HOST_CONTROLLER_PPI { 251 PEI_USB2_HOST_CONTROLLER_CONTROL_TRANSFER ControlTransfer; 252 PEI_USB2_HOST_CONTROLLER_BULK_TRANSFER BulkTransfer; 253 PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber; 254 PEI_USB2_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; 255 PEI_USB2_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; 256 PEI_USB2_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; 257 }; 258 259 extern EFI_GUID gPeiUsb2HostControllerPpiGuid; 260 261 #endif 262 263