EmbeddedPkg/Include/Protocol/AndroidFastbootTransport.h

   1 /** @file
   2
   3   Copyright (c) 2014, ARM Ltd. All rights reserved.<BR>
   4
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 /*
  10   Transport protocol over which Android Fastboot transactions can be made.
  11   Fastboot is designed for USB, but this protocol is intended as an abstraction
  12    so that it can be implemented over any transport mechanism.
  13 */
  14
  15 #ifndef __ANDROID_FASTBOOT_TRANSPORT_H__
  16 #define __ANDROID_FASTBOOT_TRANSPORT_H__
  17
  18 extern EFI_GUID gAndroidFastbootTransportProtocolGuid;
  19
  20 /*
  21   Set up the transport system for use by Fastboot.
  22   e.g. For USB this probably means making the device enumerable. For TCP,
  23        preparing to accept incoming connections.
  24
  25   It is _not_ the responsibility of this protocol's implementer to unite the
  26   data phase into a single buffer - that is handled by the Fastboot UEFI
  27   application. As the Fastboot protocol spec says: "Short packets are always
  28    acceptable and zero-length packets are ignored."
  29   However the commands and responses must be in a single packet, and the order
  30   of the packets must of course be maintained.
  31
  32   If there is a fatal error in the receive channel, ReceiveEvent will be
  33   signalled, and a subsequent call to Receive() will return an error. This
  34   allows data transported prior to the error to be received.
  35
  36   @param[in] ReceiveEvent  Event to be Signalled when a packet has been received
  37                            and is ready to be retrieved via Receive().
  38
  39   @retval EFI_SUCCESS       Initialised successfully.
  40   @retval EFI_DEVICE_ERROR  Error in initialising hardware
  41   @retval (other)           Error return from LocateProtocol functions.
  42 */
  43 typedef
  44 EFI_STATUS
  45 (*FASTBOOT_TRANSPORT_START) (
  46   IN EFI_EVENT ReceiveEvent
  47   );
  48
  49 /*
  50   Function to be called when all Fastboot transactions are finished, to
  51   de-initialise the transport system.
  52   e.g. A USB OTG system might want to get out of peripheral mode so it can be
  53        a USB host.
  54
  55   Note that this function will be called after an error is reported by Send or
  56   Receive
  57
  58   @retval EFI_SUCCESS       De-initialised successfully.
  59   @retval EFI_DEVICE_ERROR  Error de-initialising hardware.
  60 */
  61 typedef
  62 EFI_STATUS
  63 (* FASTBOOT_TRANSPORT_STOP) (
  64   VOID
  65   );
  66
  67 /*
  68   Send data. This function can be used both for command responses like "OKAY"
  69   and for the data phase (the protocol doesn't describe any situation when the
  70    latter might be necessary, but does allow it)
  71
  72   Transmission need not finish before the function returns.
  73   If there is an error in transmission from which the transport system cannot
  74   recover, FatalErrorEvent will be signalled. Otherwise, it is assumed that all
  75   data was delivered successfully.
  76
  77   @param[in] BufferSize       Size in bytes of data to send.
  78   @param[in] Buffer           Data to send.
  79   @param[in] FatalErrorEvent  Event to signal if there was an error in
  80                               transmission from which the transport system
  81                               cannot recover.
  82
  83   @retval EFI_SUCCESS       The data was sent or queued for send.
  84   @retval EFI_DEVICE_ERROR  There was an error preparing to send the data.
  85  */
  86 typedef
  87 EFI_STATUS
  88 (*FASTBOOT_TRANSPORT_SEND) (
  89   IN        UINTN      BufferSize,
  90   IN  CONST VOID      *Buffer,
  91   IN        EFI_EVENT *FatalErrorEvent
  92   );
  93
  94 /*
  95   When the event has been Signalled to say data is available from the host,
  96   this function is used to get data. In order to handle the case where several
  97   packets are received before ReceiveEvent's notify function is called, packets
  98   received are queued, and each call to this function returns the next packet in
  99   the queue. It should therefore be called in a loop, the exit condition being a
 100   return of EFI_NOT_READY.
 101
 102   @param[out]  Buffer       Pointer to received data. Callee allocated - the
 103                             caller must free it with FreePool.
 104   @param[out]  BufferSize   The size of received data in bytes
 105
 106   @retval EFI_NOT_READY     There is no data available
 107   @retval EFI_DEVICE_ERROR  There was a fatal error in the receive channel.
 108                             e.g. for USB the cable was unplugged or for TCP the
 109                             connection was closed by the remote host..
 110 */
 111 typedef
 112 EFI_STATUS
 113 (*FASTBOOT_TRANSPORT_RECEIVE) (
 114   OUT UINTN  *BufferSize,
 115   OUT VOID  **Buffer
 116   );
 117
 118 typedef struct _FASTBOOT_TRANSPORT_PROTOCOL {
 119   FASTBOOT_TRANSPORT_START                     Start;
 120   FASTBOOT_TRANSPORT_STOP                      Stop;
 121   FASTBOOT_TRANSPORT_SEND                      Send;
 122   FASTBOOT_TRANSPORT_RECEIVE                   Receive;
 123 } FASTBOOT_TRANSPORT_PROTOCOL;
 124
 125 #endif