EmbeddedPkg/Include/Protocol/UsbDevice.h

   1 /** @file
   2
   3   Copyright (c) 2013-2014, ARM Ltd. All rights reserved.<BR>
   4
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef __USB_DEVICE_PROTOCOL_H__
  16 #define __USB_DEVICE_PROTOCOL_H__
  17
  18 #include <IndustryStandard/Usb.h>
  19
  20 extern EFI_GUID gUsbDeviceProtocolGuid;
  21
  22 /*
  23  * Note: This Protocol is just  the bare minimum for Android Fastboot. It
  24  * only makes sense for devices that only do Bulk Transfers and only have one
  25  * endpoint.
  26  */
  27
  28 /*
  29   Callback to be called when data is received.
  30   Buffer is callee-allocated and it's the caller's responsibility to free it with
  31   FreePool.
  32
  33   @param[in] Size        Size in bytes of data.
  34   @param[in] Buffer      Pointer to data.
  35 */
  36 typedef
  37 VOID
  38 (*USB_DEVICE_RX_CALLBACK) (
  39   IN UINTN    Size,
  40   IN VOID    *Buffer
  41   );
  42
  43 /*
  44   Callback to be called when the host asks for data by sending an IN token
  45   (excluding during the data stage of a control transfer).
  46   When this function is called, data previously buffered by calling Send() has
  47   been sent.
  48
  49   @param[in]Endpoint    Endpoint index, as specified in endpoint descriptors, of
  50                         the endpoint the IN token was sent to.
  51 */
  52 typedef
  53 VOID
  54 (*USB_DEVICE_TX_CALLBACK) (
  55   IN UINT8    EndpointIndex
  56   );
  57
  58 /*
  59   Put data in the Tx buffer to be sent on the next IN token.
  60   Don't call this function again until the TxCallback has been called.
  61
  62   @param[in]Endpoint    Endpoint index, as specified in endpoint descriptors, of
  63                         the endpoint to send the data from.
  64   @param[in]Size        Size in bytes of data.
  65   @param[in]Buffer      Pointer to data.
  66
  67   @retval EFI_SUCCESS           The data was queued successfully.
  68   @retval EFI_INVALID_PARAMETER There was an error sending the data.
  69 */
  70 typedef
  71 EFI_STATUS
  72 (*USB_DEVICE_SEND) (
  73   IN       UINT8    EndpointIndex,
  74   IN       UINTN    Size,
  75   IN CONST VOID    *Buffer
  76   );
  77
  78 /*
  79   Restart the USB peripheral controller and respond to enumeration.
  80
  81   @param[in] DeviceDescriptor   pointer to device descriptor
  82   @param[in] Descriptors        Array of pointers to buffers, where
  83                                 Descriptors[n] contains the response to a
  84                                 GET_DESCRIPTOR request for configuration n. From
  85                                 USB Spec section 9.4.3:
  86                                 "The first interface descriptor follows the
  87                                 configuration descriptor. The endpoint
  88                                 descriptors for the first interface follow the
  89                                 first interface descriptor. If there are
  90                                 additional interfaces, their interface
  91                                 descriptor and endpoint descriptors follow the
  92                                 first interface’s endpoint descriptors".
  93
  94                                 The size of each buffer is the TotalLength
  95                                 member of the Configuration Descriptor.
  96
  97                                 The size of the array is
  98                                 DeviceDescriptor->NumConfigurations.
  99   @param[in]RxCallback          See USB_DEVICE_RX_CALLBACK
 100   @param[in]TxCallback          See USB_DEVICE_TX_CALLBACK
 101 */
 102 typedef
 103 EFI_STATUS
 104 (*USB_DEVICE_START) (
 105   IN USB_DEVICE_DESCRIPTOR     *DeviceDescriptor,
 106   IN VOID                     **Descriptors,
 107   IN USB_DEVICE_RX_CALLBACK     RxCallback,
 108   IN USB_DEVICE_TX_CALLBACK     TxCallback
 109   );
 110
 111 struct _USB_DEVICE_PROTOCOL {
 112   USB_DEVICE_START Start;
 113   USB_DEVICE_SEND  Send;
 114 };
 115
 116 typedef struct _USB_DEVICE_PROTOCOL USB_DEVICE_PROTOCOL;
 117
 118 #endif //ifndef __USB_DEVICE_PROTOCOL_H__