1 /** @file 2 Defines the PEI_USB_IO_PPI that the USB-related PEIM can use for I/O operations 3 on the USB BUS. This interface enables recovery from a 4 USB-class storage device, such as USB CD/DVD, USB hard drive, or USB FLASH 5 drive. These interfaces are modeled on the UEFI 2.3 specification EFI_USB_IO_PROTOCOL. 6 Refer to section 16.2.4 of the UEFI 2.3 Specification for more information on 7 these interfaces. 8 9 Copyright (c) 2006 - 2013, Intel Corporation. All rights reserved.<BR> 10 11 This program and the accompanying materials 12 are licensed and made available under the terms and conditions 13 of the BSD License which accompanies this distribution. The 14 full text of the license may be found at 15 http://opensource.org/licenses/bsd-license.php 16 17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 19 20 **/ 21 22 #ifndef _PEI_USB_IO_PPI_H_ 23 #define _PEI_USB_IO_PPI_H_ 24 25 #include <Protocol/Usb2HostController.h> 26 27 /// 28 /// Global ID for the PEI_USB_IO_PPI. 29 /// 30 #define PEI_USB_IO_PPI_GUID \ 31 { \ 32 0x7c29785c, 0x66b9, 0x49fc, { 0xb7, 0x97, 0x1c, 0xa5, 0x55, 0xe, 0xf2, 0x83} \ 33 } 34 35 /// 36 /// Forward declaration for the PEI_USB_IO_PPI. 37 /// 38 typedef struct _PEI_USB_IO_PPI PEI_USB_IO_PPI; 39 40 /** 41 Submits control transfer to a target USB device. 42 43 @param[in] PeiServices The pointer to the PEI Services Table. 44 @param[in] This The pointer to this instance of the PEI_USB_IO_PPI. 45 @param[in] Request A pointer to the USB device request that will be 46 sent to the USB device. 47 @param[in] Direction Specifies the data direction for the transfer. There 48 are three values available: 49 EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData. 50 @param[in] Timeout Indicates the maximum time, in milliseconds, that 51 the transfer is allowed to complete. 52 If Timeout is 0, then the caller must wait for the 53 function to be completed until EFI_SUCCESS or 54 EFI_DEVICE_ERROR is returned. 55 @param[in,out] Data A pointer to the buffer of data that will be 56 transmitted to or received from the USB device. 57 @param[in] DataLength On input, indicates the size, in bytes, of the data 58 buffer specified by Data. 59 60 @retval EFI_SUCCESS The control transfer was completed successfully. 61 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 62 @retval EFI_OUT_OF_RESOURCES The control transfer could not be completed due 63 to a lack of resources. 64 @retval EFI_TIMEOUT The control transfer failed due to timeout. 65 @retval EFI_DEVICE_ERROR The control transfer failed due to host controller 66 or device error. 67 Caller should check TransferResult for detailed 68 error information. 69 70 **/ 71 typedef 72 EFI_STATUS 73 (EFIAPI *PEI_USB_CONTROL_TRANSFER)( 74 IN EFI_PEI_SERVICES **PeiServices, 75 IN PEI_USB_IO_PPI *This, 76 IN EFI_USB_DEVICE_REQUEST *Request, 77 IN EFI_USB_DATA_DIRECTION Direction, 78 IN UINT32 Timeout, 79 IN OUT VOID *Data OPTIONAL, 80 IN UINTN DataLength OPTIONAL 81 ); 82 83 /** 84 Submits bulk transfer to a target USB device. 85 86 @param[in] PeiServices The pointer to the PEI Services Table. 87 @param[in] This The pointer to this instance of the PEI_USB_IO_PPI. 88 @param[in] DeviceEndpoint The endpoint address. 89 @param[in] Data The data buffer to be transfered. 90 @param[in] DataLength The length of data buffer. 91 @param[in] Timeout The timeout for the transfer, in milliseconds. 92 If Timeout is 0, then the caller must wait for the 93 function to be completed until EFI_SUCCESS or 94 EFI_DEVICE_ERROR is returned. 95 96 @retval EFI_SUCCESS The bulk transfer completed successfully. 97 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 98 @retval EFI_OUT_OF_RESOURCES The bulk transfer could not be completed due to 99 a lack of resources. 100 @retval EFI_TIMEOUT The bulk transfer failed due to timeout. 101 @retval EFI_DEVICE_ERROR The bulk transfer failed due to host controller 102 or device error. 103 Caller should check TransferResult for detailed 104 error information. 105 106 **/ 107 typedef 108 EFI_STATUS 109 (EFIAPI *PEI_USB_BULK_TRANSFER)( 110 IN EFI_PEI_SERVICES **PeiServices, 111 IN PEI_USB_IO_PPI *This, 112 IN UINT8 DeviceEndpoint, 113 IN OUT VOID *Data, 114 IN OUT UINTN *DataLength, 115 IN UINTN Timeout 116 ); 117 118 /** 119 Get interface descriptor from a USB device. 120 121 @param[in] PeiServices The pointer to the PEI Services Table. 122 @param[in] This The pointer to this instance of the PEI_USB_IO_PPI. 123 @param[in] InterfaceDescriptor The interface descriptor. 124 125 @retval EFI_SUCCESS The interface descriptor was returned. 126 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 127 @retval EFI_DEVICE_ERROR A device error occurred, the function failed to 128 get the interface descriptor. 129 130 **/ 131 typedef 132 EFI_STATUS 133 (EFIAPI *PEI_USB_GET_INTERFACE_DESCRIPTOR)( 134 IN EFI_PEI_SERVICES **PeiServices, 135 IN PEI_USB_IO_PPI *This, 136 IN EFI_USB_INTERFACE_DESCRIPTOR **InterfaceDescriptor 137 ); 138 139 /** 140 Get endpoint descriptor from a USB device. 141 142 @param[in] PeiServices The pointer to the PEI Services Table. 143 @param[in] This The pointer to this instance of the PEI_USB_IO_PPI. 144 @param[in] EndPointIndex The index of the end point. 145 @param[in] EndpointDescriptor The endpoint descriptor. 146 147 @retval EFI_SUCCESS The endpoint descriptor was returned. 148 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 149 @retval EFI_DEVICE_ERROR A device error occurred, the function failed to 150 get the endpoint descriptor. 151 152 **/ 153 typedef 154 EFI_STATUS 155 (EFIAPI *PEI_USB_GET_ENDPOINT_DESCRIPTOR)( 156 IN EFI_PEI_SERVICES **PeiServices, 157 IN PEI_USB_IO_PPI *This, 158 IN UINT8 EndpointIndex, 159 IN EFI_USB_ENDPOINT_DESCRIPTOR **EndpointDescriptor 160 ); 161 162 /** 163 Issue a port reset to the device. 164 165 @param[in] PeiServices The pointer to the PEI Services Table. 166 @param[in] This The pointer to this instance of the PEI_USB_IO_PPI. 167 168 @retval EFI_SUCCESS The port reset was issued successfully. 169 @retval EFI_INVALID_PARAMETER Some parameters are invalid. 170 @retval EFI_DEVICE_ERROR Device error occurred. 171 172 **/ 173 typedef 174 EFI_STATUS 175 (EFIAPI *PEI_USB_PORT_RESET)( 176 IN EFI_PEI_SERVICES **PeiServices, 177 IN PEI_USB_IO_PPI *This 178 ); 179 180 /// 181 /// This PPI contains a set of services to interact with the USB host controller. 182 /// These interfaces are modeled on the UEFI 2.3 specification EFI_USB_IO_PROTOCOL. 183 /// Refer to section 16.2.4 of the UEFI 2.3 Specification for more information on 184 /// these interfaces. 185 /// 186 struct _PEI_USB_IO_PPI { 187 PEI_USB_CONTROL_TRANSFER UsbControlTransfer; 188 PEI_USB_BULK_TRANSFER UsbBulkTransfer; 189 PEI_USB_GET_INTERFACE_DESCRIPTOR UsbGetInterfaceDescriptor; 190 PEI_USB_GET_ENDPOINT_DESCRIPTOR UsbGetEndpointDescriptor; 191 PEI_USB_PORT_RESET UsbPortReset; 192 }; 193 194 extern EFI_GUID gPeiUsbIoPpiGuid; 195 196 #endif 197