MdeModulePkg: Clean up source files

[mirror_edk2.git] / MdeModulePkg / Include / Ppi / UsbIo.h

/** @file\r
  Defines the PEI_USB_IO_PPI that the USB-related PEIM can use for I/O operations\r
  on the USB BUS.  This interface enables recovery from a\r
  USB-class storage device, such as USB CD/DVD, USB hard drive, or USB FLASH\r
  drive.  These interfaces are modeled on the UEFI 2.3 specification EFI_USB_IO_PROTOCOL.\r
  Refer to section 16.2.4 of the UEFI 2.3 Specification for more information on\r
  these interfaces.\r
\r
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
\r
This program and the accompanying materials\r
are licensed and made available under the terms and conditions\r
of the BSD License which accompanies this distribution.  The\r
full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _PEI_USB_IO_PPI_H_\r
#define _PEI_USB_IO_PPI_H_\r
\r
#include <Protocol/Usb2HostController.h>\r
\r
///\r
/// Global ID for the PEI_USB_IO_PPI.\r
///\r
#define PEI_USB_IO_PPI_GUID \\r
  { \\r
    0x7c29785c, 0x66b9, 0x49fc, { 0xb7, 0x97, 0x1c, 0xa5, 0x55, 0xe, 0xf2, 0x83} \\r
  }\r
\r
///\r
/// Forward declaration for the PEI_USB_IO_PPI.\r
///\r
typedef struct _PEI_USB_IO_PPI  PEI_USB_IO_PPI;\r
\r
/**\r
  Submits control transfer to a target USB device.\r
\r
  @param[in]     PeiServices   The pointer to the PEI Services Table.\r
  @param[in]     This          The pointer to this instance of the PEI_USB_IO_PPI.\r
  @param[in]     Request       A pointer to the USB device request that will be\r
                               sent to the USB device.\r
  @param[in]     Direction     Specifies the data direction for the transfer. There\r
                               are three values available:\r
                               EfiUsbDataIn, EfiUsbDataOut and EfiUsbNoData.\r
  @param[in]     Timeout       Indicates the maximum time, in milliseconds, that\r
                               the transfer is allowed to complete.\r
                               If Timeout is 0, then the caller must wait for the\r
                               function to be completed until EFI_SUCCESS or\r
                               EFI_DEVICE_ERROR is returned.\r
  @param[in,out] Data          A pointer to the buffer of data that will be\r
                               transmitted to or received from the USB device.\r
  @param[in]     DataLength    On input, indicates the size, in bytes, of the data\r
                               buffer specified by Data.\r
\r
  @retval EFI_SUCCESS             The control transfer was completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Some parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES    The control transfer could not be completed due\r
                                  to a lack of resources.\r
  @retval EFI_TIMEOUT             The control transfer failed due to timeout.\r
  @retval EFI_DEVICE_ERROR        The control transfer failed due to host controller\r
                                  or device error.\r
                                  Caller should check TransferResult for detailed\r
                                  error information.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *PEI_USB_CONTROL_TRANSFER)(\r
  IN     EFI_PEI_SERVICES        **PeiServices,\r
  IN     PEI_USB_IO_PPI          *This,\r
  IN     EFI_USB_DEVICE_REQUEST  *Request,\r
  IN     EFI_USB_DATA_DIRECTION  Direction,\r
  IN     UINT32                  Timeout,\r
  IN OUT VOID                    *Data OPTIONAL,\r
  IN     UINTN                   DataLength  OPTIONAL\r
  );\r
\r
/**\r
  Submits bulk transfer to a target USB device.\r
\r
  @param[in] PeiServices       The pointer to the PEI Services Table.\r
  @param[in] This              The pointer to this instance of the PEI_USB_IO_PPI.\r
  @param[in] DeviceEndpoint    The endpoint address.\r
  @param[in] Data              The data buffer to be transfered.\r
  @param[in] DataLength        The length of data buffer.\r
  @param[in] Timeout           The timeout for the transfer, in milliseconds.\r
                               If Timeout is 0, then the caller must wait for the\r
                               function to be completed until EFI_SUCCESS or\r
                               EFI_DEVICE_ERROR is returned.\r
\r
  @retval EFI_SUCCESS             The bulk transfer completed successfully.\r
  @retval EFI_INVALID_PARAMETER   Some parameters are invalid.\r
  @retval EFI_OUT_OF_RESOURCES    The bulk transfer could not be completed due to\r
                                  a lack of resources.\r
  @retval EFI_TIMEOUT             The bulk transfer failed due to timeout.\r
  @retval EFI_DEVICE_ERROR        The bulk transfer failed due to host controller\r
                                  or device error.\r
                                  Caller should check TransferResult for detailed\r
                                  error information.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *PEI_USB_BULK_TRANSFER)(\r
  IN EFI_PEI_SERVICES  **PeiServices,\r
  IN PEI_USB_IO_PPI    *This,\r
  IN UINT8             DeviceEndpoint,\r
  IN OUT VOID          *Data,\r
  IN OUT UINTN         *DataLength,\r
  IN UINTN             Timeout\r
  );\r
\r
/**\r
  Get interface descriptor from a USB device.\r
\r
  @param[in] PeiServices           The pointer to the PEI Services Table.\r
  @param[in] This                  The pointer to this instance of the PEI_USB_IO_PPI.\r
  @param[in] InterfaceDescriptor   The interface descriptor.\r
\r
  @retval EFI_SUCCESS             The interface descriptor was returned.\r
  @retval EFI_INVALID_PARAMETER   Some parameters are invalid.\r
  @retval EFI_DEVICE_ERROR        A device error occurred, the function failed to\r
                                  get the interface descriptor.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *PEI_USB_GET_INTERFACE_DESCRIPTOR)(\r
  IN EFI_PEI_SERVICES              **PeiServices,\r
  IN PEI_USB_IO_PPI                *This,\r
  IN EFI_USB_INTERFACE_DESCRIPTOR  **InterfaceDescriptor\r
  );\r
\r
/**\r
  Get endpoint descriptor from a USB device.\r
\r
  @param[in] PeiServices          The pointer to the PEI Services Table.\r
  @param[in] This                 The pointer to this instance of the PEI_USB_IO_PPI.\r
  @param[in] EndPointIndex        The index of the end point.\r
  @param[in] EndpointDescriptor   The endpoint descriptor.\r
\r
  @retval EFI_SUCCESS             The endpoint descriptor was returned.\r
  @retval EFI_INVALID_PARAMETER   Some parameters are invalid.\r
  @retval EFI_DEVICE_ERROR        A device error occurred, the function failed to\r
                                  get the endpoint descriptor.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *PEI_USB_GET_ENDPOINT_DESCRIPTOR)(\r
  IN EFI_PEI_SERVICES               **PeiServices,\r
  IN PEI_USB_IO_PPI                 *This,\r
  IN UINT8                          EndpointIndex,\r
  IN EFI_USB_ENDPOINT_DESCRIPTOR    **EndpointDescriptor\r
  );\r
\r
/**\r
  Issue a port reset to the device.\r
\r
  @param[in] PeiServices   The pointer to the PEI Services Table.\r
  @param[in] This          The pointer to this instance of the PEI_USB_IO_PPI.\r
\r
  @retval EFI_SUCCESS             The port reset was issued successfully.\r
  @retval EFI_INVALID_PARAMETER   Some parameters are invalid.\r
  @retval EFI_DEVICE_ERROR        Device error occurred.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *PEI_USB_PORT_RESET)(\r
  IN EFI_PEI_SERVICES  **PeiServices,\r
  IN PEI_USB_IO_PPI    *This\r
  );\r
\r
///\r
/// This PPI contains a set of services to interact with the USB host controller.\r
/// These interfaces are modeled on the UEFI 2.3 specification EFI_USB_IO_PROTOCOL.\r
/// Refer to section 16.2.4 of the UEFI 2.3 Specification for more information on\r
/// these interfaces.\r
///\r
struct _PEI_USB_IO_PPI {\r
  PEI_USB_CONTROL_TRANSFER          UsbControlTransfer;\r
  PEI_USB_BULK_TRANSFER             UsbBulkTransfer;\r
  PEI_USB_GET_INTERFACE_DESCRIPTOR  UsbGetInterfaceDescriptor;\r
  PEI_USB_GET_ENDPOINT_DESCRIPTOR   UsbGetEndpointDescriptor;\r
  PEI_USB_PORT_RESET                UsbPortReset;\r
};\r
\r
extern EFI_GUID gPeiUsbIoPpiGuid;\r
\r
#endif\r