MdeModulePkg/Include/Ppi/UsbIo.h

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