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