]>
Commit | Line | Data |
---|---|---|
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 |