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) 2006 - 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_USB_HOST_CONTROLLER_PPI_H_ 22 #define _PEI_USB_HOST_CONTROLLER_PPI_H_ 23 24 #include <Protocol/Usb2HostController.h> 25 26 /// 27 /// Global ID for the PEI_USB_HOST_CONTROLLER_PPI. 28 /// 29 #define PEI_USB_HOST_CONTROLLER_PPI_GUID \ 30 { \ 31 0x652b38a9, 0x77f4, 0x453f, { 0x89, 0xd5, 0xe7, 0xbd, 0xc3, 0x52, 0xfc, 0x53} \ 32 } 33 34 /// 35 /// Forward declaration for the PEI_USB_HOST_CONTROLLER_PPI. 36 /// 37 typedef struct _PEI_USB_HOST_CONTROLLER_PPI PEI_USB_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_USB_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[out] TransferResult A pointer to the detailed result information 69 generated by this control transfer. 70 71 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller 72 or device error. 73 @retval EFI_SUCCESS The control transfer was completed successfully. 74 75 **/ 76 typedef 77 EFI_STATUS 78 (EFIAPI *PEI_USB_HOST_CONTROLLER_CONTROL_TRANSFER)( 79 IN EFI_PEI_SERVICES **PeiServices, 80 IN PEI_USB_HOST_CONTROLLER_PPI *This, 81 IN UINT8 DeviceAddress, 82 IN UINT8 DeviceSpeed, 83 IN UINT8 MaximumPacketLength, 84 IN USB_DEVICE_REQUEST *Request, 85 IN EFI_USB_DATA_DIRECTION TransferDirection, 86 IN OUT VOID *Data OPTIONAL, 87 IN OUT UINTN *DataLength OPTIONAL, 88 IN UINTN TimeOut, 89 OUT UINT32 *TransferResult 90 ); 91 92 /** 93 Initiate a USB bulk transfer using a specific USB Host controller on the USB bus. 94 95 @param[in] PeiServices The pointer to the PEI Services Table. 96 @param[in] This The pointer to this instance of the 97 PEI_USB_HOST_CONTROLLER_PPI. 98 @param[in] DeviceAddress Represents the address of the target device 99 on the USB. 100 @param[in] EndPointAddress The combination of an endpoint number and 101 an endpoint direction of the target USB device. 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[out] TransferResult A pointer to the detailed result information 117 of the bulk transfer. 118 119 @retval EFI_SUCCESS The bulk transfer was completed successfully. 120 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. 121 Caller should check TransferResult for detailed error information. 122 123 **/ 124 typedef 125 EFI_STATUS 126 (EFIAPI *PEI_USB_HOST_CONTROLLER_BULK_TRANSFER)( 127 IN EFI_PEI_SERVICES **PeiServices, 128 IN PEI_USB_HOST_CONTROLLER_PPI *This, 129 IN UINT8 DeviceAddress, 130 IN UINT8 EndPointAddress, 131 IN UINT8 MaximumPacketLength, 132 IN OUT VOID *Data, 133 IN OUT UINTN *DataLength, 134 IN OUT UINT8 *DataToggle, 135 IN UINTN TimeOut, 136 OUT UINT32 *TransferResult 137 ); 138 139 /** 140 Retrieves the number of root hub ports. 141 142 @param[in] PeiServices The pointer to the PEI Services Table. 143 @param[in] This The pointer to this instance of the 144 PEI_USB_HOST_CONTROLLER_PPI. 145 @param[out] PortNumber The pointer to the number of the root hub ports. 146 147 @retval EFI_SUCCESS The port number was retrieved successfully. 148 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve 149 the port number. 150 @retval EFI_INVALID_PARAMETER PortNumber is NULL. 151 152 **/ 153 typedef 154 EFI_STATUS 155 (EFIAPI *PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER)( 156 IN EFI_PEI_SERVICES **PeiServices, 157 IN PEI_USB_HOST_CONTROLLER_PPI *This, 158 OUT UINT8 *PortNumber 159 ); 160 161 /** 162 Retrieves the current status of a USB root hub port. 163 164 @param[in] PeiServices The pointer to the PEI Services Table. 165 @param[in] This The pointer to this instance of the 166 PEI_USB_HOST_CONTROLLER_PPI. 167 @param[in] PortNumber Specifies the root hub port from which the status is 168 to be retrieved. 169 This value is zero based. 170 @param[out] PortStatus A pointer to the current port status bits and port 171 status change bits. 172 173 @retval EFI_SUCCESS The status of the USB root hub port specified by 174 PortNumber was returned in PortStatus. 175 @retval EFI_INVALID_PARAMETER PortNumber is invalid. 176 177 **/ 178 typedef 179 EFI_STATUS 180 (EFIAPI *PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS)( 181 IN EFI_PEI_SERVICES **PeiServices, 182 IN PEI_USB_HOST_CONTROLLER_PPI *This, 183 IN UINT8 PortNumber, 184 OUT EFI_USB_PORT_STATUS *PortStatus 185 ); 186 187 /** 188 Sets a feature for the specified root hub port. 189 190 @param[in] PeiServices The pointer to the PEI Services Table. 191 @param[in] This The pointer to this instance of the 192 PEI_USB_HOST_CONTROLLER_PPI. 193 @param[in] PortNumber Specifies the root hub port whose feature is requested 194 to be set. This value is zero based. 195 @param[in] PortFeature Indicates the feature selector associated with the feature 196 set request. 197 198 @retval EFI_SUCCESS The feature specified by PortFeature was set for 199 the USB root hub port specified by PortNumber. 200 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid 201 for this function. 202 203 **/ 204 typedef 205 EFI_STATUS 206 (EFIAPI *PEI_USB_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE)( 207 IN EFI_PEI_SERVICES **PeiServices, 208 IN PEI_USB_HOST_CONTROLLER_PPI *This, 209 IN UINT8 PortNumber, 210 IN EFI_USB_PORT_FEATURE PortFeature 211 ); 212 213 /** 214 Clears a feature for the specified root hub port. 215 216 @param[in] PeiServices The pointer to the PEI Services Table. 217 @param[in] This The pointer to this instance of the 218 PEI_USB_HOST_CONTROLLER_PPI. 219 @param[in] PortNumber Specifies the root hub port whose feature is 220 requested to be cleared. 221 @param[in] PortFeature Indicates the feature selector associated with the 222 feature clear request. 223 224 @return EFI_SUCCESS The feature specified by PortFeature was cleared 225 for the USB root hub port specified by PortNumber. 226 @return EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid. 227 @return EFI_DEVICE_ERROR Can't read the register. 228 229 **/ 230 typedef 231 EFI_STATUS 232 (EFIAPI *PEI_USB_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE)( 233 IN EFI_PEI_SERVICES **PeiServices, 234 IN PEI_USB_HOST_CONTROLLER_PPI *This, 235 IN UINT8 PortNumber, 236 IN EFI_USB_PORT_FEATURE PortFeature 237 ); 238 239 /// 240 /// This PPI contains a set of services to interact with the USB host controller. 241 /// These interfaces are modeled on the UEFI 2.3 specification protocol 242 /// EFI_USB2_HOST_CONTROLLER_PROTOCOL. Refer to section 16.1 of the UEFI 2.3 243 /// Specification for more information on these interfaces. 244 /// 245 struct _PEI_USB_HOST_CONTROLLER_PPI { 246 PEI_USB_HOST_CONTROLLER_CONTROL_TRANSFER ControlTransfer; 247 PEI_USB_HOST_CONTROLLER_BULK_TRANSFER BulkTransfer; 248 PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber; 249 PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; 250 PEI_USB_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; 251 PEI_USB_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; 252 }; 253 254 extern EFI_GUID gPeiUsbHostControllerPpiGuid; 255 256 #endif 257 258