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 - 2018, Intel Corporation. All rights reserved.<BR> 9 10 SPDX-License-Identifier: BSD-2-Clause-Patent 11 12 **/ 13 14 #ifndef _PEI_USB_HOST_CONTROLLER_PPI_H_ 15 #define _PEI_USB_HOST_CONTROLLER_PPI_H_ 16 17 #include <Protocol/Usb2HostController.h> 18 19 /// 20 /// Global ID for the PEI_USB_HOST_CONTROLLER_PPI. 21 /// 22 #define PEI_USB_HOST_CONTROLLER_PPI_GUID \ 23 { \ 24 0x652b38a9, 0x77f4, 0x453f, { 0x89, 0xd5, 0xe7, 0xbd, 0xc3, 0x52, 0xfc, 0x53} \ 25 } 26 27 /// 28 /// Forward declaration for the PEI_USB_HOST_CONTROLLER_PPI. 29 /// 30 typedef struct _PEI_USB_HOST_CONTROLLER_PPI PEI_USB_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_USB_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[out] TransferResult A pointer to the detailed result information 62 generated by this control transfer. 63 64 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller 65 or device error. 66 @retval EFI_SUCCESS The control transfer was completed successfully. 67 68 **/ 69 typedef 70 EFI_STATUS 71 (EFIAPI *PEI_USB_HOST_CONTROLLER_CONTROL_TRANSFER)( 72 IN EFI_PEI_SERVICES **PeiServices, 73 IN PEI_USB_HOST_CONTROLLER_PPI *This, 74 IN UINT8 DeviceAddress, 75 IN UINT8 DeviceSpeed, 76 IN UINT8 MaximumPacketLength, 77 IN USB_DEVICE_REQUEST *Request, 78 IN EFI_USB_DATA_DIRECTION TransferDirection, 79 IN OUT VOID *Data OPTIONAL, 80 IN OUT UINTN *DataLength OPTIONAL, 81 IN UINTN TimeOut, 82 OUT UINT32 *TransferResult 83 ); 84 85 /** 86 Initiate a USB bulk transfer using a specific USB Host controller on the USB bus. 87 88 @param[in] PeiServices The pointer to the PEI Services Table. 89 @param[in] This The pointer to this instance of the 90 PEI_USB_HOST_CONTROLLER_PPI. 91 @param[in] DeviceAddress Represents the address of the target device 92 on the USB. 93 @param[in] EndPointAddress The combination of an endpoint number and 94 an endpoint direction of the target USB device. 95 @param[in] MaximumPacketLength Indicates the maximum packet size the target 96 endpoint is capable of sending or receiving. 97 @param[in,out] Data Array of pointers to the buffers of data 98 that will be transmitted to USB device or 99 received from USB device. 100 @param[in,out] DataLength When input, indicates the size, in bytes, of 101 the data buffers specified by Data. When output, 102 indicates the data size actually transferred. 103 @param[in,out] DataToggle A pointer to the data toggle value. 104 @param[in] TimeOut Indicates the maximum time, in milliseconds, 105 in which the transfer is allowed to complete. 106 If Timeout is 0, then the caller must wait for 107 the function to be completed until EFI_SUCCESS 108 or EFI_DEVICE_ERROR is returned. 109 @param[out] TransferResult A pointer to the detailed result information 110 of the bulk transfer. 111 112 @retval EFI_SUCCESS The bulk transfer was completed successfully. 113 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller or device error. 114 Caller should check TransferResult for detailed error information. 115 116 **/ 117 typedef 118 EFI_STATUS 119 (EFIAPI *PEI_USB_HOST_CONTROLLER_BULK_TRANSFER)( 120 IN EFI_PEI_SERVICES **PeiServices, 121 IN PEI_USB_HOST_CONTROLLER_PPI *This, 122 IN UINT8 DeviceAddress, 123 IN UINT8 EndPointAddress, 124 IN UINT8 MaximumPacketLength, 125 IN OUT VOID *Data, 126 IN OUT UINTN *DataLength, 127 IN OUT UINT8 *DataToggle, 128 IN UINTN TimeOut, 129 OUT UINT32 *TransferResult 130 ); 131 132 /** 133 Retrieves the number of root hub ports. 134 135 @param[in] PeiServices The pointer to the PEI Services Table. 136 @param[in] This The pointer to this instance of the 137 PEI_USB_HOST_CONTROLLER_PPI. 138 @param[out] PortNumber The pointer to the number of the root hub ports. 139 140 @retval EFI_SUCCESS The port number was retrieved successfully. 141 @retval EFI_DEVICE_ERROR An error was encountered while attempting to retrieve 142 the port number. 143 @retval EFI_INVALID_PARAMETER PortNumber is NULL. 144 145 **/ 146 typedef 147 EFI_STATUS 148 (EFIAPI *PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER)( 149 IN EFI_PEI_SERVICES **PeiServices, 150 IN PEI_USB_HOST_CONTROLLER_PPI *This, 151 OUT UINT8 *PortNumber 152 ); 153 154 /** 155 Retrieves the current status of a USB root hub port. 156 157 @param[in] PeiServices The pointer to the PEI Services Table. 158 @param[in] This The pointer to this instance of the 159 PEI_USB_HOST_CONTROLLER_PPI. 160 @param[in] PortNumber Specifies the root hub port from which the status is 161 to be retrieved. 162 This value is zero based. 163 @param[out] PortStatus A pointer to the current port status bits and port 164 status change bits. 165 166 @retval EFI_SUCCESS The status of the USB root hub port specified by 167 PortNumber was returned in PortStatus. 168 @retval EFI_INVALID_PARAMETER PortNumber is invalid. 169 170 **/ 171 typedef 172 EFI_STATUS 173 (EFIAPI *PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS)( 174 IN EFI_PEI_SERVICES **PeiServices, 175 IN PEI_USB_HOST_CONTROLLER_PPI *This, 176 IN UINT8 PortNumber, 177 OUT EFI_USB_PORT_STATUS *PortStatus 178 ); 179 180 /** 181 Sets a feature for the specified root hub port. 182 183 @param[in] PeiServices The pointer to the PEI Services Table. 184 @param[in] This The pointer to this instance of the 185 PEI_USB_HOST_CONTROLLER_PPI. 186 @param[in] PortNumber Specifies the root hub port whose feature is requested 187 to be set. This value is zero based. 188 @param[in] PortFeature Indicates the feature selector associated with the feature 189 set request. 190 191 @retval EFI_SUCCESS The feature specified by PortFeature was set for 192 the USB root hub port specified by PortNumber. 193 @retval EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid 194 for this function. 195 196 **/ 197 typedef 198 EFI_STATUS 199 (EFIAPI *PEI_USB_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE)( 200 IN EFI_PEI_SERVICES **PeiServices, 201 IN PEI_USB_HOST_CONTROLLER_PPI *This, 202 IN UINT8 PortNumber, 203 IN EFI_USB_PORT_FEATURE PortFeature 204 ); 205 206 /** 207 Clears a feature for the specified root hub port. 208 209 @param[in] PeiServices The pointer to the PEI Services Table. 210 @param[in] This The pointer to this instance of the 211 PEI_USB_HOST_CONTROLLER_PPI. 212 @param[in] PortNumber Specifies the root hub port whose feature is 213 requested to be cleared. 214 @param[in] PortFeature Indicates the feature selector associated with the 215 feature clear request. 216 217 @return EFI_SUCCESS The feature specified by PortFeature was cleared 218 for the USB root hub port specified by PortNumber. 219 @return EFI_INVALID_PARAMETER PortNumber is invalid or PortFeature is invalid. 220 @return EFI_DEVICE_ERROR Can't read the register. 221 222 **/ 223 typedef 224 EFI_STATUS 225 (EFIAPI *PEI_USB_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE)( 226 IN EFI_PEI_SERVICES **PeiServices, 227 IN PEI_USB_HOST_CONTROLLER_PPI *This, 228 IN UINT8 PortNumber, 229 IN EFI_USB_PORT_FEATURE PortFeature 230 ); 231 232 /// 233 /// This PPI contains a set of services to interact with the USB host controller. 234 /// These interfaces are modeled on the UEFI 2.3 specification protocol 235 /// EFI_USB2_HOST_CONTROLLER_PROTOCOL. Refer to section 16.1 of the UEFI 2.3 236 /// Specification for more information on these interfaces. 237 /// 238 struct _PEI_USB_HOST_CONTROLLER_PPI { 239 PEI_USB_HOST_CONTROLLER_CONTROL_TRANSFER ControlTransfer; 240 PEI_USB_HOST_CONTROLLER_BULK_TRANSFER BulkTransfer; 241 PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_NUMBER GetRootHubPortNumber; 242 PEI_USB_HOST_CONTROLLER_GET_ROOTHUB_PORT_STATUS GetRootHubPortStatus; 243 PEI_USB_HOST_CONTROLLER_SET_ROOTHUB_PORT_FEATURE SetRootHubPortFeature; 244 PEI_USB_HOST_CONTROLLER_CLEAR_ROOTHUB_PORT_FEATURE ClearRootHubPortFeature; 245 }; 246 247 extern EFI_GUID gPeiUsbHostControllerPpiGuid; 248 249 #endif 250 251