| 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 |
|
|---|
