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