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