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