1*f334afcfSToomas Soome /** @file
2*f334afcfSToomas Soome   EFI Multicast Trivial File Transfer Protocol Definition
3*f334afcfSToomas Soome 
4*f334afcfSToomas Soome Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5*f334afcfSToomas Soome SPDX-License-Identifier: BSD-2-Clause-Patent
6*f334afcfSToomas Soome 
7*f334afcfSToomas Soome   @par Revision Reference:
8*f334afcfSToomas Soome   This Protocol is introduced in UEFI Specification 2.0
9*f334afcfSToomas Soome 
10*f334afcfSToomas Soome **/
11*f334afcfSToomas Soome 
12*f334afcfSToomas Soome #ifndef __EFI_MTFTP4_PROTOCOL_H__
13*f334afcfSToomas Soome #define __EFI_MTFTP4_PROTOCOL_H__
14*f334afcfSToomas Soome 
15*f334afcfSToomas Soome #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
16*f334afcfSToomas Soome   { \
17*f334afcfSToomas Soome     0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
18*f334afcfSToomas Soome   }
19*f334afcfSToomas Soome 
20*f334afcfSToomas Soome #define EFI_MTFTP4_PROTOCOL_GUID \
21*f334afcfSToomas Soome   { \
22*f334afcfSToomas Soome     0x78247c57, 0x63db, 0x4708, {0x99, 0xc2, 0xa8, 0xb4, 0xa9, 0xa6, 0x1f, 0x6b } \
23*f334afcfSToomas Soome   }
24*f334afcfSToomas Soome 
25*f334afcfSToomas Soome typedef struct _EFI_MTFTP4_PROTOCOL  EFI_MTFTP4_PROTOCOL;
26*f334afcfSToomas Soome typedef struct _EFI_MTFTP4_TOKEN     EFI_MTFTP4_TOKEN;
27*f334afcfSToomas Soome 
28*f334afcfSToomas Soome //
29*f334afcfSToomas Soome // MTFTP4 packet opcode definition
30*f334afcfSToomas Soome //
31*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_RRQ    1
32*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_WRQ    2
33*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_DATA   3
34*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_ACK    4
35*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_ERROR  5
36*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_OACK   6
37*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_DIR    7
38*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_DATA8  8
39*f334afcfSToomas Soome #define EFI_MTFTP4_OPCODE_ACK8   9
40*f334afcfSToomas Soome 
41*f334afcfSToomas Soome //
42*f334afcfSToomas Soome // MTFTP4 error code definition
43*f334afcfSToomas Soome //
44*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED          0
45*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND       1
46*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION     2
47*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_DISK_FULL            3
48*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION    4
49*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID  5
50*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS  6
51*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER         7
52*f334afcfSToomas Soome #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED       8
53*f334afcfSToomas Soome 
54*f334afcfSToomas Soome //
55*f334afcfSToomas Soome // MTFTP4 pacekt definitions
56*f334afcfSToomas Soome //
57*f334afcfSToomas Soome #pragma pack(1)
58*f334afcfSToomas Soome 
59*f334afcfSToomas Soome typedef struct {
60*f334afcfSToomas Soome   UINT16    OpCode;
61*f334afcfSToomas Soome   UINT8     Filename[1];
62*f334afcfSToomas Soome } EFI_MTFTP4_REQ_HEADER;
63*f334afcfSToomas Soome 
64*f334afcfSToomas Soome typedef struct {
65*f334afcfSToomas Soome   UINT16    OpCode;
66*f334afcfSToomas Soome   UINT8     Data[1];
67*f334afcfSToomas Soome } EFI_MTFTP4_OACK_HEADER;
68*f334afcfSToomas Soome 
69*f334afcfSToomas Soome typedef struct {
70*f334afcfSToomas Soome   UINT16    OpCode;
71*f334afcfSToomas Soome   UINT16    Block;
72*f334afcfSToomas Soome   UINT8     Data[1];
73*f334afcfSToomas Soome } EFI_MTFTP4_DATA_HEADER;
74*f334afcfSToomas Soome 
75*f334afcfSToomas Soome typedef struct {
76*f334afcfSToomas Soome   UINT16    OpCode;
77*f334afcfSToomas Soome   UINT16    Block[1];
78*f334afcfSToomas Soome } EFI_MTFTP4_ACK_HEADER;
79*f334afcfSToomas Soome 
80*f334afcfSToomas Soome typedef struct {
81*f334afcfSToomas Soome   UINT16    OpCode;
82*f334afcfSToomas Soome   UINT64    Block;
83*f334afcfSToomas Soome   UINT8     Data[1];
84*f334afcfSToomas Soome } EFI_MTFTP4_DATA8_HEADER;
85*f334afcfSToomas Soome 
86*f334afcfSToomas Soome typedef struct {
87*f334afcfSToomas Soome   UINT16    OpCode;
88*f334afcfSToomas Soome   UINT64    Block[1];
89*f334afcfSToomas Soome } EFI_MTFTP4_ACK8_HEADER;
90*f334afcfSToomas Soome 
91*f334afcfSToomas Soome typedef struct {
92*f334afcfSToomas Soome   UINT16    OpCode;
93*f334afcfSToomas Soome   UINT16    ErrorCode;
94*f334afcfSToomas Soome   UINT8     ErrorMessage[1];
95*f334afcfSToomas Soome } EFI_MTFTP4_ERROR_HEADER;
96*f334afcfSToomas Soome 
97*f334afcfSToomas Soome typedef union {
98*f334afcfSToomas Soome   ///
99*f334afcfSToomas Soome   /// Type of packets as defined by the MTFTPv4 packet opcodes.
100*f334afcfSToomas Soome   ///
101*f334afcfSToomas Soome   UINT16                     OpCode;
102*f334afcfSToomas Soome   ///
103*f334afcfSToomas Soome   /// Read request packet header.
104*f334afcfSToomas Soome   ///
105*f334afcfSToomas Soome   EFI_MTFTP4_REQ_HEADER      Rrq;
106*f334afcfSToomas Soome   ///
107*f334afcfSToomas Soome   /// Write request packet header.
108*f334afcfSToomas Soome   ///
109*f334afcfSToomas Soome   EFI_MTFTP4_REQ_HEADER      Wrq;
110*f334afcfSToomas Soome   ///
111*f334afcfSToomas Soome   /// Option acknowledge packet header.
112*f334afcfSToomas Soome   ///
113*f334afcfSToomas Soome   EFI_MTFTP4_OACK_HEADER     Oack;
114*f334afcfSToomas Soome   ///
115*f334afcfSToomas Soome   /// Data packet header.
116*f334afcfSToomas Soome   ///
117*f334afcfSToomas Soome   EFI_MTFTP4_DATA_HEADER     Data;
118*f334afcfSToomas Soome   ///
119*f334afcfSToomas Soome   /// Acknowledgement packet header.
120*f334afcfSToomas Soome   ///
121*f334afcfSToomas Soome   EFI_MTFTP4_ACK_HEADER      Ack;
122*f334afcfSToomas Soome   ///
123*f334afcfSToomas Soome   /// Data packet header with big block number.
124*f334afcfSToomas Soome   ///
125*f334afcfSToomas Soome   EFI_MTFTP4_DATA8_HEADER    Data8;
126*f334afcfSToomas Soome   ///
127*f334afcfSToomas Soome   /// Acknowledgement header with big block num.
128*f334afcfSToomas Soome   ///
129*f334afcfSToomas Soome   EFI_MTFTP4_ACK8_HEADER     Ack8;
130*f334afcfSToomas Soome   ///
131*f334afcfSToomas Soome   /// Error packet header.
132*f334afcfSToomas Soome   ///
133*f334afcfSToomas Soome   EFI_MTFTP4_ERROR_HEADER    Error;
134*f334afcfSToomas Soome } EFI_MTFTP4_PACKET;
135*f334afcfSToomas Soome 
136*f334afcfSToomas Soome #pragma pack()
137*f334afcfSToomas Soome 
138*f334afcfSToomas Soome ///
139*f334afcfSToomas Soome /// MTFTP4 option definition.
140*f334afcfSToomas Soome ///
141*f334afcfSToomas Soome typedef struct {
142*f334afcfSToomas Soome   UINT8    *OptionStr;
143*f334afcfSToomas Soome   UINT8    *ValueStr;
144*f334afcfSToomas Soome } EFI_MTFTP4_OPTION;
145*f334afcfSToomas Soome 
146*f334afcfSToomas Soome typedef struct {
147*f334afcfSToomas Soome   BOOLEAN             UseDefaultSetting;
148*f334afcfSToomas Soome   EFI_IPv4_ADDRESS    StationIp;
149*f334afcfSToomas Soome   EFI_IPv4_ADDRESS    SubnetMask;
150*f334afcfSToomas Soome   UINT16              LocalPort;
151*f334afcfSToomas Soome   EFI_IPv4_ADDRESS    GatewayIp;
152*f334afcfSToomas Soome   EFI_IPv4_ADDRESS    ServerIp;
153*f334afcfSToomas Soome   UINT16              InitialServerPort;
154*f334afcfSToomas Soome   UINT16              TryCount;
155*f334afcfSToomas Soome   UINT16              TimeoutValue;
156*f334afcfSToomas Soome } EFI_MTFTP4_CONFIG_DATA;
157*f334afcfSToomas Soome 
158*f334afcfSToomas Soome typedef struct {
159*f334afcfSToomas Soome   EFI_MTFTP4_CONFIG_DATA    ConfigData;
160*f334afcfSToomas Soome   UINT8                     SupportedOptionCount;
161*f334afcfSToomas Soome   UINT8                     **SupportedOptoins;
162*f334afcfSToomas Soome   UINT8                     UnsupportedOptionCount;
163*f334afcfSToomas Soome   UINT8                     **UnsupportedOptoins;
164*f334afcfSToomas Soome } EFI_MTFTP4_MODE_DATA;
165*f334afcfSToomas Soome 
166*f334afcfSToomas Soome typedef struct {
167*f334afcfSToomas Soome   EFI_IPv4_ADDRESS    GatewayIp;
168*f334afcfSToomas Soome   EFI_IPv4_ADDRESS    ServerIp;
169*f334afcfSToomas Soome   UINT16              ServerPort;
170*f334afcfSToomas Soome   UINT16              TryCount;
171*f334afcfSToomas Soome   UINT16              TimeoutValue;
172*f334afcfSToomas Soome } EFI_MTFTP4_OVERRIDE_DATA;
173*f334afcfSToomas Soome 
174*f334afcfSToomas Soome //
175*f334afcfSToomas Soome // Protocol interfaces definition
176*f334afcfSToomas Soome //
177*f334afcfSToomas Soome 
178*f334afcfSToomas Soome /**
179*f334afcfSToomas Soome   A callback function that is provided by the caller to intercept
180*f334afcfSToomas Soome   the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
181*f334afcfSToomas Soome   EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
182*f334afcfSToomas Soome   EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
183*f334afcfSToomas Soome   EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
184*f334afcfSToomas Soome 
185*f334afcfSToomas Soome   @param  This        The pointer to the EFI_MTFTP4_PROTOCOL instance.
186*f334afcfSToomas Soome   @param  Token       The token that the caller provided in the
187*f334afcfSToomas Soome                       EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
188*f334afcfSToomas Soome                       or ReadDirectory() function.
189*f334afcfSToomas Soome   @param  PacketLen   Indicates the length of the packet.
190*f334afcfSToomas Soome   @param  Packet      The pointer to an MTFTPv4 packet.
191*f334afcfSToomas Soome 
192*f334afcfSToomas Soome   @retval EFI_SUCCESS The operation was successful.
193*f334afcfSToomas Soome   @retval Others      Aborts the transfer process.
194*f334afcfSToomas Soome 
195*f334afcfSToomas Soome **/
196*f334afcfSToomas Soome typedef
197*f334afcfSToomas Soome EFI_STATUS
198*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
199*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL  *This,
200*f334afcfSToomas Soome   IN EFI_MTFTP4_TOKEN     *Token,
201*f334afcfSToomas Soome   IN UINT16               PacketLen,
202*f334afcfSToomas Soome   IN EFI_MTFTP4_PACKET    *Paket
203*f334afcfSToomas Soome   );
204*f334afcfSToomas Soome 
205*f334afcfSToomas Soome /**
206*f334afcfSToomas Soome   Timeout callback function.
207*f334afcfSToomas Soome 
208*f334afcfSToomas Soome   @param  This           The pointer to the EFI_MTFTP4_PROTOCOL instance.
209*f334afcfSToomas Soome   @param  Token          The token that is provided in the
210*f334afcfSToomas Soome                          EFI_MTFTP4_PROTOCOL.ReadFile() or
211*f334afcfSToomas Soome                          EFI_MTFTP4_PROTOCOL.WriteFile() or
212*f334afcfSToomas Soome                          EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
213*f334afcfSToomas Soome                          by the caller.
214*f334afcfSToomas Soome 
215*f334afcfSToomas Soome   @retval EFI_SUCCESS   The operation was successful.
216*f334afcfSToomas Soome   @retval Others        Aborts download process.
217*f334afcfSToomas Soome 
218*f334afcfSToomas Soome **/
219*f334afcfSToomas Soome typedef
220*f334afcfSToomas Soome EFI_STATUS
221*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
222*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL  *This,
223*f334afcfSToomas Soome   IN EFI_MTFTP4_TOKEN     *Token
224*f334afcfSToomas Soome   );
225*f334afcfSToomas Soome 
226*f334afcfSToomas Soome /**
227*f334afcfSToomas Soome   A callback function that the caller provides to feed data to the
228*f334afcfSToomas Soome   EFI_MTFTP4_PROTOCOL.WriteFile() function.
229*f334afcfSToomas Soome 
230*f334afcfSToomas Soome   @param  This   The pointer to the EFI_MTFTP4_PROTOCOL instance.
231*f334afcfSToomas Soome   @param  Token  The token provided in the
232*f334afcfSToomas Soome                  EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
233*f334afcfSToomas Soome   @param  Length Indicates the length of the raw data wanted on input, and the
234*f334afcfSToomas Soome                  length the data available on output.
235*f334afcfSToomas Soome   @param  Buffer The pointer to the buffer where the data is stored.
236*f334afcfSToomas Soome 
237*f334afcfSToomas Soome   @retval EFI_SUCCESS The operation was successful.
238*f334afcfSToomas Soome   @retval Others      Aborts session.
239*f334afcfSToomas Soome 
240*f334afcfSToomas Soome **/
241*f334afcfSToomas Soome typedef
242*f334afcfSToomas Soome EFI_STATUS
243*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
244*f334afcfSToomas Soome   IN  EFI_MTFTP4_PROTOCOL *This,
245*f334afcfSToomas Soome   IN  EFI_MTFTP4_TOKEN    *Token,
246*f334afcfSToomas Soome   IN  OUT UINT16          *Length,
247*f334afcfSToomas Soome   OUT VOID                **Buffer
248*f334afcfSToomas Soome   );
249*f334afcfSToomas Soome 
250*f334afcfSToomas Soome /**
251*f334afcfSToomas Soome   Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
252*f334afcfSToomas Soome 
253*f334afcfSToomas Soome   @param  This     The pointer to the EFI_MTFTP4_PROTOCOL instance.
254*f334afcfSToomas Soome   @param  ModeData The pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
255*f334afcfSToomas Soome 
256*f334afcfSToomas Soome   @retval EFI_SUCCESS           The configuration data was successfully returned.
257*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES  The required mode data could not be allocated.
258*f334afcfSToomas Soome   @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
259*f334afcfSToomas Soome 
260*f334afcfSToomas Soome **/
261*f334afcfSToomas Soome typedef
262*f334afcfSToomas Soome EFI_STATUS
263*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
264*f334afcfSToomas Soome   IN  EFI_MTFTP4_PROTOCOL     *This,
265*f334afcfSToomas Soome   OUT EFI_MTFTP4_MODE_DATA    *ModeData
266*f334afcfSToomas Soome   );
267*f334afcfSToomas Soome 
268*f334afcfSToomas Soome /**
269*f334afcfSToomas Soome   Initializes, changes, or resets the default operational setting for this
270*f334afcfSToomas Soome   EFI MTFTPv4 Protocol driver instance.
271*f334afcfSToomas Soome 
272*f334afcfSToomas Soome   @param  This            The pointer to the EFI_MTFTP4_PROTOCOL instance.
273*f334afcfSToomas Soome   @param  MtftpConfigData The pointer to the configuration data structure.
274*f334afcfSToomas Soome 
275*f334afcfSToomas Soome   @retval EFI_SUCCESS           The EFI MTFTPv4 Protocol driver was configured successfully.
276*f334afcfSToomas Soome   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
277*f334afcfSToomas Soome   @retval EFI_ACCESS_DENIED     The EFI configuration could not be changed at this time because
278*f334afcfSToomas Soome                                 there is one MTFTP background operation in progress.
279*f334afcfSToomas Soome   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
280*f334afcfSToomas Soome                                 RARP, etc.) has not finished yet.
281*f334afcfSToomas Soome   @retval EFI_UNSUPPORTED       A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
282*f334afcfSToomas Soome                                 be located when clients choose to use the default address
283*f334afcfSToomas Soome                                 settings.
284*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES  The EFI MTFTPv4 Protocol driver instance data could not be
285*f334afcfSToomas Soome                                 allocated.
286*f334afcfSToomas Soome   @retval EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI
287*f334afcfSToomas Soome                                  MTFTPv4 Protocol driver instance is not configured.
288*f334afcfSToomas Soome 
289*f334afcfSToomas Soome **/
290*f334afcfSToomas Soome typedef
291*f334afcfSToomas Soome EFI_STATUS
292*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_CONFIGURE)(
293*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL       *This,
294*f334afcfSToomas Soome   IN EFI_MTFTP4_CONFIG_DATA    *MtftpConfigData OPTIONAL
295*f334afcfSToomas Soome   );
296*f334afcfSToomas Soome 
297*f334afcfSToomas Soome /**
298*f334afcfSToomas Soome   Gets information about a file from an MTFTPv4 server.
299*f334afcfSToomas Soome 
300*f334afcfSToomas Soome   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
301*f334afcfSToomas Soome   @param  OverrideData Data that is used to override the existing parameters. If NULL,
302*f334afcfSToomas Soome                        the default parameters that were set in the
303*f334afcfSToomas Soome                        EFI_MTFTP4_PROTOCOL.Configure() function are used.
304*f334afcfSToomas Soome   @param  Filename     The pointer to null-terminated ASCII file name string.
305*f334afcfSToomas Soome   @param  ModeStr      The pointer to null-terminated ASCII mode string. If NULL, "octet" will be used.
306*f334afcfSToomas Soome   @param  OptionCount  Number of option/value string pairs in OptionList.
307*f334afcfSToomas Soome   @param  OptionList   The pointer to array of option/value string pairs. Ignored if
308*f334afcfSToomas Soome                        OptionCount is zero.
309*f334afcfSToomas Soome   @param  PacketLength The number of bytes in the returned packet.
310*f334afcfSToomas Soome   @param  Packet       The pointer to the received packet. This buffer must be freed by
311*f334afcfSToomas Soome                        the caller.
312*f334afcfSToomas Soome 
313*f334afcfSToomas Soome   @retval EFI_SUCCESS              An MTFTPv4 OACK packet was received and is in the Packet.
314*f334afcfSToomas Soome   @retval EFI_INVALID_PARAMETER    One or more of the following conditions is TRUE:
315*f334afcfSToomas Soome                                    - This is NULL.
316*f334afcfSToomas Soome                                    - Filename is NULL.
317*f334afcfSToomas Soome                                    - OptionCount is not zero and OptionList is NULL.
318*f334afcfSToomas Soome                                    - One or more options in OptionList have wrong format.
319*f334afcfSToomas Soome                                    - PacketLength is NULL.
320*f334afcfSToomas Soome                                    - One or more IPv4 addresses in OverrideData are not valid
321*f334afcfSToomas Soome                                      unicast IPv4 addresses if OverrideData is not NULL.
322*f334afcfSToomas Soome   @retval EFI_UNSUPPORTED          One or more options in the OptionList are in the
323*f334afcfSToomas Soome                                    unsupported list of structure EFI_MTFTP4_MODE_DATA.
324*f334afcfSToomas Soome   @retval EFI_NOT_STARTED          The EFI MTFTPv4 Protocol driver has not been started.
325*f334afcfSToomas Soome   @retval EFI_NO_MAPPING           When using a default address, configuration (DHCP, BOOTP,
326*f334afcfSToomas Soome                                    RARP, etc.) has not finished yet.
327*f334afcfSToomas Soome   @retval EFI_ACCESS_DENIED        The previous operation has not completed yet.
328*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
329*f334afcfSToomas Soome   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received and is in the Packet.
330*f334afcfSToomas Soome   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received and the Packet is set to NULL.
331*f334afcfSToomas Soome   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received and the Packet is set to NULL.
332*f334afcfSToomas Soome   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
333*f334afcfSToomas Soome   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received and the Packet is set to NULL.
334*f334afcfSToomas Soome   @retval EFI_ICMP_ERROR           Some other ICMP ERROR packet was received and is in the Buffer.
335*f334afcfSToomas Soome   @retval EFI_PROTOCOL_ERROR       An unexpected MTFTPv4 packet was received and is in the Packet.
336*f334afcfSToomas Soome   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
337*f334afcfSToomas Soome   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
338*f334afcfSToomas Soome   @retval EFI_NO_MEDIA             There was a media error.
339*f334afcfSToomas Soome 
340*f334afcfSToomas Soome **/
341*f334afcfSToomas Soome typedef
342*f334afcfSToomas Soome EFI_STATUS
343*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_GET_INFO)(
344*f334afcfSToomas Soome   IN  EFI_MTFTP4_PROTOCOL      *This,
345*f334afcfSToomas Soome   IN  EFI_MTFTP4_OVERRIDE_DATA *OverrideData   OPTIONAL,
346*f334afcfSToomas Soome   IN  UINT8                    *Filename,
347*f334afcfSToomas Soome   IN  UINT8                    *ModeStr        OPTIONAL,
348*f334afcfSToomas Soome   IN  UINT8                    OptionCount,
349*f334afcfSToomas Soome   IN  EFI_MTFTP4_OPTION        *OptionList,
350*f334afcfSToomas Soome   OUT UINT32                   *PacketLength,
351*f334afcfSToomas Soome   OUT EFI_MTFTP4_PACKET        **Packet        OPTIONAL
352*f334afcfSToomas Soome   );
353*f334afcfSToomas Soome 
354*f334afcfSToomas Soome /**
355*f334afcfSToomas Soome   Parses the options in an MTFTPv4 OACK packet.
356*f334afcfSToomas Soome 
357*f334afcfSToomas Soome   @param  This         The pointer to the EFI_MTFTP4_PROTOCOL instance.
358*f334afcfSToomas Soome   @param  PacketLen    Length of the OACK packet to be parsed.
359*f334afcfSToomas Soome   @param  Packet       The pointer to the OACK packet to be parsed.
360*f334afcfSToomas Soome   @param  OptionCount  The pointer to the number of options in following OptionList.
361*f334afcfSToomas Soome   @param  OptionList   The pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
362*f334afcfSToomas Soome                        Service FreePool() to release the OptionList if the options
363*f334afcfSToomas Soome                        in this OptionList are not needed any more.
364*f334afcfSToomas Soome 
365*f334afcfSToomas Soome   @retval EFI_SUCCESS           The OACK packet was valid and the OptionCount and
366*f334afcfSToomas Soome                                 OptionList parameters have been updated.
367*f334afcfSToomas Soome   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
368*f334afcfSToomas Soome                                 - PacketLen is 0.
369*f334afcfSToomas Soome                                 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
370*f334afcfSToomas Soome                                 - OptionCount is NULL.
371*f334afcfSToomas Soome   @retval EFI_NOT_FOUND         No options were found in the OACK packet.
372*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES  Storage for the OptionList array cannot be allocated.
373*f334afcfSToomas Soome   @retval EFI_PROTOCOL_ERROR    One or more of the option fields is invalid.
374*f334afcfSToomas Soome 
375*f334afcfSToomas Soome **/
376*f334afcfSToomas Soome typedef
377*f334afcfSToomas Soome EFI_STATUS
378*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
379*f334afcfSToomas Soome   IN  EFI_MTFTP4_PROTOCOL      *This,
380*f334afcfSToomas Soome   IN  UINT32                   PacketLen,
381*f334afcfSToomas Soome   IN  EFI_MTFTP4_PACKET        *Packet,
382*f334afcfSToomas Soome   OUT UINT32                   *OptionCount,
383*f334afcfSToomas Soome   OUT EFI_MTFTP4_OPTION        **OptionList OPTIONAL
384*f334afcfSToomas Soome   );
385*f334afcfSToomas Soome 
386*f334afcfSToomas Soome /**
387*f334afcfSToomas Soome   Downloads a file from an MTFTPv4 server.
388*f334afcfSToomas Soome 
389*f334afcfSToomas Soome   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
390*f334afcfSToomas Soome   @param  Token The pointer to the token structure to provide the parameters that are
391*f334afcfSToomas Soome                 used in this operation.
392*f334afcfSToomas Soome 
393*f334afcfSToomas Soome   @retval EFI_SUCCESS              The data file has been transferred successfully.
394*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
395*f334afcfSToomas Soome   @retval EFI_BUFFER_TOO_SMALL     BufferSize is not zero but not large enough to hold the
396*f334afcfSToomas Soome                                    downloaded data in downloading process.
397*f334afcfSToomas Soome   @retval EFI_ABORTED              Current operation is aborted by user.
398*f334afcfSToomas Soome   @retval EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received.
399*f334afcfSToomas Soome   @retval EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received.
400*f334afcfSToomas Soome   @retval EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
401*f334afcfSToomas Soome   @retval EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received.
402*f334afcfSToomas Soome   @retval EFI_ICMP_ERROR           Some other  ICMP ERROR packet was received.
403*f334afcfSToomas Soome   @retval EFI_TIMEOUT              No responses were received from the MTFTPv4 server.
404*f334afcfSToomas Soome   @retval EFI_TFTP_ERROR           An MTFTPv4 ERROR packet was received.
405*f334afcfSToomas Soome   @retval EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
406*f334afcfSToomas Soome   @retval EFI_NO_MEDIA             There was a media error.
407*f334afcfSToomas Soome 
408*f334afcfSToomas Soome **/
409*f334afcfSToomas Soome typedef
410*f334afcfSToomas Soome EFI_STATUS
411*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_READ_FILE)(
412*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL       *This,
413*f334afcfSToomas Soome   IN EFI_MTFTP4_TOKEN          *Token
414*f334afcfSToomas Soome   );
415*f334afcfSToomas Soome 
416*f334afcfSToomas Soome /**
417*f334afcfSToomas Soome   Sends a file to an MTFTPv4 server.
418*f334afcfSToomas Soome 
419*f334afcfSToomas Soome   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
420*f334afcfSToomas Soome   @param  Token The pointer to the token structure to provide the parameters that are
421*f334afcfSToomas Soome                 used in this operation.
422*f334afcfSToomas Soome 
423*f334afcfSToomas Soome   @retval EFI_SUCCESS           The upload session has started.
424*f334afcfSToomas Soome   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
425*f334afcfSToomas Soome   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
426*f334afcfSToomas Soome   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
427*f334afcfSToomas Soome                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
428*f334afcfSToomas Soome   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
429*f334afcfSToomas Soome   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
430*f334afcfSToomas Soome                                 RARP, etc.) is not finished yet.
431*f334afcfSToomas Soome   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
432*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
433*f334afcfSToomas Soome   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
434*f334afcfSToomas Soome   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
435*f334afcfSToomas Soome 
436*f334afcfSToomas Soome **/
437*f334afcfSToomas Soome typedef
438*f334afcfSToomas Soome EFI_STATUS
439*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
440*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL       *This,
441*f334afcfSToomas Soome   IN EFI_MTFTP4_TOKEN          *Token
442*f334afcfSToomas Soome   );
443*f334afcfSToomas Soome 
444*f334afcfSToomas Soome /**
445*f334afcfSToomas Soome   Downloads a data file "directory" from an MTFTPv4 server. May be unsupported in some EFI
446*f334afcfSToomas Soome   implementations.
447*f334afcfSToomas Soome 
448*f334afcfSToomas Soome   @param  This  The pointer to the EFI_MTFTP4_PROTOCOL instance.
449*f334afcfSToomas Soome   @param  Token The pointer to the token structure to provide the parameters that are
450*f334afcfSToomas Soome                 used in this operation.
451*f334afcfSToomas Soome 
452*f334afcfSToomas Soome   @retval EFI_SUCCESS           The MTFTPv4 related file "directory" has been downloaded.
453*f334afcfSToomas Soome   @retval EFI_UNSUPPORTED       The operation is not supported by this implementation.
454*f334afcfSToomas Soome   @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
455*f334afcfSToomas Soome   @retval EFI_UNSUPPORTED       One or more options in the Token.OptionList are in
456*f334afcfSToomas Soome                                 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
457*f334afcfSToomas Soome   @retval EFI_NOT_STARTED       The EFI MTFTPv4 Protocol driver has not been started.
458*f334afcfSToomas Soome   @retval EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
459*f334afcfSToomas Soome                                 RARP, etc.) is not finished yet.
460*f334afcfSToomas Soome   @retval EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv4 session.
461*f334afcfSToomas Soome   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
462*f334afcfSToomas Soome   @retval EFI_ACCESS_DENIED     The previous operation has not completed yet.
463*f334afcfSToomas Soome   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
464*f334afcfSToomas Soome 
465*f334afcfSToomas Soome **/
466*f334afcfSToomas Soome typedef
467*f334afcfSToomas Soome EFI_STATUS
468*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
469*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL       *This,
470*f334afcfSToomas Soome   IN EFI_MTFTP4_TOKEN          *Token
471*f334afcfSToomas Soome   );
472*f334afcfSToomas Soome 
473*f334afcfSToomas Soome /**
474*f334afcfSToomas Soome   Polls for incoming data packets and processes outgoing data packets.
475*f334afcfSToomas Soome 
476*f334afcfSToomas Soome   @param  This The pointer to the EFI_MTFTP4_PROTOCOL instance.
477*f334afcfSToomas Soome 
478*f334afcfSToomas Soome   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
479*f334afcfSToomas Soome   @retval  EFI_NOT_STARTED       This EFI MTFTPv4 Protocol instance has not been started.
480*f334afcfSToomas Soome   @retval  EFI_NO_MAPPING        When using a default address, configuration (DHCP, BOOTP,
481*f334afcfSToomas Soome                                  RARP, etc.) is not finished yet.
482*f334afcfSToomas Soome   @retval  EFI_INVALID_PARAMETER This is NULL.
483*f334afcfSToomas Soome   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
484*f334afcfSToomas Soome   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
485*f334afcfSToomas Soome                                  Consider increasing the polling rate.
486*f334afcfSToomas Soome 
487*f334afcfSToomas Soome **/
488*f334afcfSToomas Soome typedef
489*f334afcfSToomas Soome EFI_STATUS
490*f334afcfSToomas Soome (EFIAPI *EFI_MTFTP4_POLL)(
491*f334afcfSToomas Soome   IN EFI_MTFTP4_PROTOCOL       *This
492*f334afcfSToomas Soome   );
493*f334afcfSToomas Soome 
494*f334afcfSToomas Soome ///
495*f334afcfSToomas Soome /// The EFI_MTFTP4_PROTOCOL is designed to be used by UEFI drivers and applications
496*f334afcfSToomas Soome /// to transmit and receive data files. The EFI MTFTPv4 Protocol driver uses
497*f334afcfSToomas Soome /// the underlying EFI UDPv4 Protocol driver and EFI IPv4 Protocol driver.
498*f334afcfSToomas Soome ///
499*f334afcfSToomas Soome struct _EFI_MTFTP4_PROTOCOL {
500*f334afcfSToomas Soome   EFI_MTFTP4_GET_MODE_DATA     GetModeData;
501*f334afcfSToomas Soome   EFI_MTFTP4_CONFIGURE         Configure;
502*f334afcfSToomas Soome   EFI_MTFTP4_GET_INFO          GetInfo;
503*f334afcfSToomas Soome   EFI_MTFTP4_PARSE_OPTIONS     ParseOptions;
504*f334afcfSToomas Soome   EFI_MTFTP4_READ_FILE         ReadFile;
505*f334afcfSToomas Soome   EFI_MTFTP4_WRITE_FILE        WriteFile;
506*f334afcfSToomas Soome   EFI_MTFTP4_READ_DIRECTORY    ReadDirectory;
507*f334afcfSToomas Soome   EFI_MTFTP4_POLL              Poll;
508*f334afcfSToomas Soome };
509*f334afcfSToomas Soome 
510*f334afcfSToomas Soome struct _EFI_MTFTP4_TOKEN {
511*f334afcfSToomas Soome   ///
512*f334afcfSToomas Soome   /// The status that is returned to the caller at the end of the operation
513*f334afcfSToomas Soome   /// to indicate whether this operation completed successfully.
514*f334afcfSToomas Soome   ///
515*f334afcfSToomas Soome   EFI_STATUS                     Status;
516*f334afcfSToomas Soome   ///
517*f334afcfSToomas Soome   /// The event that will be signaled when the operation completes. If
518*f334afcfSToomas Soome   /// set to NULL, the corresponding function will wait until the read or
519*f334afcfSToomas Soome   /// write operation finishes. The type of Event must be
520*f334afcfSToomas Soome   /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of
521*f334afcfSToomas Soome   /// Event must be lower than or equal to TPL_CALLBACK.
522*f334afcfSToomas Soome   ///
523*f334afcfSToomas Soome   EFI_EVENT                      Event;
524*f334afcfSToomas Soome   ///
525*f334afcfSToomas Soome   /// If not NULL, the data that will be used to override the existing configure data.
526*f334afcfSToomas Soome   ///
527*f334afcfSToomas Soome   EFI_MTFTP4_OVERRIDE_DATA       *OverrideData;
528*f334afcfSToomas Soome   ///
529*f334afcfSToomas Soome   /// The pointer to the null-terminated ASCII file name string.
530*f334afcfSToomas Soome   ///
531*f334afcfSToomas Soome   UINT8                          *Filename;
532*f334afcfSToomas Soome   ///
533*f334afcfSToomas Soome   /// The pointer to the null-terminated ASCII mode string. If NULL, "octet" is used.
534*f334afcfSToomas Soome   ///
535*f334afcfSToomas Soome   UINT8                          *ModeStr;
536*f334afcfSToomas Soome   ///
537*f334afcfSToomas Soome   /// Number of option/value string pairs.
538*f334afcfSToomas Soome   ///
539*f334afcfSToomas Soome   UINT32                         OptionCount;
540*f334afcfSToomas Soome   ///
541*f334afcfSToomas Soome   /// The pointer to an array of option/value string pairs. Ignored if OptionCount is zero.
542*f334afcfSToomas Soome   ///
543*f334afcfSToomas Soome   EFI_MTFTP4_OPTION              *OptionList;
544*f334afcfSToomas Soome   ///
545*f334afcfSToomas Soome   /// The size of the data buffer.
546*f334afcfSToomas Soome   ///
547*f334afcfSToomas Soome   UINT64                         BufferSize;
548*f334afcfSToomas Soome   ///
549*f334afcfSToomas Soome   /// The pointer to the data buffer. Data that is downloaded from the
550*f334afcfSToomas Soome   /// MTFTPv4 server is stored here. Data that is uploaded to the
551*f334afcfSToomas Soome   /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.
552*f334afcfSToomas Soome   ///
553*f334afcfSToomas Soome   VOID                           *Buffer;
554*f334afcfSToomas Soome   ///
555*f334afcfSToomas Soome   /// The pointer to the context that will be used by CheckPacket,
556*f334afcfSToomas Soome   /// TimeoutCallback and PacketNeeded.
557*f334afcfSToomas Soome   ///
558*f334afcfSToomas Soome   VOID                           *Context;
559*f334afcfSToomas Soome   ///
560*f334afcfSToomas Soome   /// The pointer to the callback function to check the contents of the received packet.
561*f334afcfSToomas Soome   ///
562*f334afcfSToomas Soome   EFI_MTFTP4_CHECK_PACKET        CheckPacket;
563*f334afcfSToomas Soome   ///
564*f334afcfSToomas Soome   /// The pointer to the function to be called when a timeout occurs.
565*f334afcfSToomas Soome   ///
566*f334afcfSToomas Soome   EFI_MTFTP4_TIMEOUT_CALLBACK    TimeoutCallback;
567*f334afcfSToomas Soome   ///
568*f334afcfSToomas Soome   /// The pointer to the function to provide the needed packet contents.
569*f334afcfSToomas Soome   ///
570*f334afcfSToomas Soome   EFI_MTFTP4_PACKET_NEEDED       PacketNeeded;
571*f334afcfSToomas Soome };
572*f334afcfSToomas Soome 
573*f334afcfSToomas Soome extern EFI_GUID  gEfiMtftp4ServiceBindingProtocolGuid;
574*f334afcfSToomas Soome extern EFI_GUID  gEfiMtftp4ProtocolGuid;
575*f334afcfSToomas Soome 
576*f334afcfSToomas Soome #endif
577