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