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 - 2010, 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   @param[in,out] Data          A pointer to the buffer of data that will be
  53                                transmitted to or received from the USB device.
  54   @param[in]     DataLength    On input, indicates the size, in bytes, of the data
  55                                buffer specified by Data.
  56
  57   @retval EFI_SUCCESS             The control transfer was completed successfully.
  58   @retval EFI_INVALID_PARAMETER   Some parameters are invalid.
  59   @retval EFI_OUT_OF_RESOURCES    The control transfer could not be completed due
  60                                   to a lack of resources.
  61   @retval EFI_TIMEOUT             The control transfer failed due to timeout.
  62   @retval EFI_DEVICE_ERROR        The control transfer failed due to host controller
  63                                   or device error.
  64                                   Caller should check TransferResult for detailed
  65                                   error information.
  66
  67 **/
  68 typedef
  69 EFI_STATUS
  70 (EFIAPI *PEI_USB_CONTROL_TRANSFER)(
  71   IN     EFI_PEI_SERVICES        **PeiServices,
  72   IN     PEI_USB_IO_PPI          *This,
  73   IN     EFI_USB_DEVICE_REQUEST  *Request,
  74   IN     EFI_USB_DATA_DIRECTION  Direction,
  75   IN     UINT32                  Timeout,
  76   IN OUT VOID                    *Data OPTIONAL,
  77   IN     UINTN                   DataLength  OPTIONAL
  78   );
  79
  80 /**
  81   Submits bulk transfer to a target USB device.
  82
  83   @param[in] PeiServices       The pointer to the PEI Services Table.
  84   @param[in] This              The pointer to this instance of the PEI_USB_IO_PPI.
  85   @param[in] EndPointAddress   The endpoint address.
  86   @param[in] Data              The data buffer to be transfered.
  87   @param[in] DataLength        The length of data buffer.
  88   @param[in] TimeOut           The timeout for the transfer, in milliseconds.
  89
  90   @retval EFI_SUCCESS             The bulk transfer completed successfully.
  91   @retval EFI_INVALID_PARAMETER   Some parameters are invalid.
  92   @retval EFI_OUT_OF_RESOURCES    The bulk transfer could not be completed due to
  93                                   a lack of resources.
  94   @retval EFI_TIMEOUT             The bulk transfer failed due to timeout.
  95   @retval EFI_DEVICE_ERROR        The bulk transfer failed due to host controller
  96                                   or device error.
  97                                   Caller should check TransferResult for detailed
  98                                   error information.
  99
 100 **/
 101 typedef
 102 EFI_STATUS
 103 (EFIAPI *PEI_USB_BULK_TRANSFER)(
 104   IN EFI_PEI_SERVICES  **PeiServices,
 105   IN PEI_USB_IO_PPI    *This,
 106   IN UINT8             DeviceEndpoint,
 107   IN OUT VOID          *Data,
 108   IN OUT UINTN         *DataLength,
 109   IN UINTN             Timeout
 110   );
 111
 112 /**
 113   Get interface descriptor from a USB device.
 114
 115   @param[in] PeiServices           The pointer to the PEI Services Table.
 116   @param[in] This                  The pointer to this instance of the PEI_USB_IO_PPI.
 117   @param[in] InterfaceDescriptor   The interface descriptor.
 118
 119   @retval EFI_SUCCESS             The interface descriptor was returned.
 120   @retval EFI_INVALID_PARAMETER   Some parameters are invalid.
 121   @retval EFI_DEVICE_ERROR        A device error occurred, the function failed to
 122                                   get the interface descriptor.
 123
 124 **/
 125 typedef
 126 EFI_STATUS
 127 (EFIAPI *PEI_USB_GET_INTERFACE_DESCRIPTOR)(
 128   IN EFI_PEI_SERVICES              **PeiServices,
 129   IN PEI_USB_IO_PPI                *This,
 130   IN EFI_USB_INTERFACE_DESCRIPTOR  **InterfaceDescriptor
 131   );
 132
 133 /**
 134   Get endpoint descriptor from a USB device.
 135
 136   @param[in] PeiServices          The pointer to the PEI Services Table.
 137   @param[in] This                 The pointer to this instance of the PEI_USB_IO_PPI.
 138   @param[in] EndPointIndex        The index of the end point.
 139   @param[in] EndpointDescriptor   The endpoint descriptor.
 140
 141   @retval EFI_SUCCESS             The endpoint descriptor was returned.
 142   @retval EFI_INVALID_PARAMETER   Some parameters are invalid.
 143   @retval EFI_DEVICE_ERROR        A device error occurred, the function failed to
 144                                   get the endpoint descriptor.
 145
 146 **/
 147 typedef
 148 EFI_STATUS
 149 (EFIAPI *PEI_USB_GET_ENDPOINT_DESCRIPTOR)(
 150   IN EFI_PEI_SERVICES               **PeiServices,
 151   IN PEI_USB_IO_PPI                 *This,
 152   IN UINT8                          EndpointIndex,
 153   IN EFI_USB_ENDPOINT_DESCRIPTOR    **EndpointDescriptor
 154   );
 155
 156 /**
 157   Issue a port reset to the device.
 158
 159   @param[in] PeiServices   The pointer to the PEI Services Table.
 160   @param[in] This          The pointer to this instance of the PEI_USB_IO_PPI.
 161
 162   @retval EFI_SUCCESS             The port reset was issued successfully.
 163   @retval EFI_INVALID_PARAMETER   Some parameters are invalid.
 164   @retval EFI_DEVICE_ERROR        Device error occurred.
 165
 166 **/
 167 typedef
 168 EFI_STATUS
 169 (EFIAPI *PEI_USB_PORT_RESET)(
 170   IN EFI_PEI_SERVICES  **PeiServices,
 171   IN PEI_USB_IO_PPI    *This
 172   );
 173
 174 ///
 175 /// This PPI contains a set of services to interact with the USB host controller.
 176 /// These interfaces are modeled on the UEFI 2.3 specification EFI_USB_IO_PROTOCOL.
 177 /// Refer to section 16.2.4 of the UEFI 2.3 Specification for more information on
 178 /// these interfaces.
 179 ///
 180 struct _PEI_USB_IO_PPI {
 181   PEI_USB_CONTROL_TRANSFER          UsbControlTransfer;
 182   PEI_USB_BULK_TRANSFER             UsbBulkTransfer;
 183   PEI_USB_GET_INTERFACE_DESCRIPTOR  UsbGetInterfaceDescriptor;
 184   PEI_USB_GET_ENDPOINT_DESCRIPTOR   UsbGetEndpointDescriptor;
 185   PEI_USB_PORT_RESET                UsbPortReset;
 186 };
 187
 188 extern EFI_GUID gPeiUsbIoPpiGuid;
 189
 190 #endif