xref: /illumos-gate/usr/src/boot/efi/include/Protocol/Mtftp6.h (revision f334afcfaebea1b7dc3430015651d8d748fa8a3e)
1 /** @file
2   UEFI Multicast Trivial File Transfer Protocol v6 Definition, which is built upon
3   the EFI UDPv6 Protocol and provides basic services for client-side unicast and/or
4   multicast TFTP operations.
5 
6   Copyright (c) 2008 - 2011, Intel Corporation. All rights reserved.<BR>
7   (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
8 
9   SPDX-License-Identifier: BSD-2-Clause-Patent
10 
11   @par Revision Reference:
12   This Protocol is introduced in UEFI Specification 2.2
13 
14 **/
15 
16 #ifndef __EFI_MTFTP6_PROTOCOL_H__
17 #define __EFI_MTFTP6_PROTOCOL_H__
18 
19 #define EFI_MTFTP6_SERVICE_BINDING_PROTOCOL_GUID \
20   { \
21     0xd9760ff3, 0x3cca, 0x4267, {0x80, 0xf9, 0x75, 0x27, 0xfa, 0xfa, 0x42, 0x23 } \
22   }
23 
24 #define EFI_MTFTP6_PROTOCOL_GUID \
25   { \
26     0xbf0a78ba, 0xec29, 0x49cf, {0xa1, 0xc9, 0x7a, 0xe5, 0x4e, 0xab, 0x6a, 0x51 } \
27   }
28 
29 typedef struct _EFI_MTFTP6_PROTOCOL  EFI_MTFTP6_PROTOCOL;
30 typedef struct _EFI_MTFTP6_TOKEN     EFI_MTFTP6_TOKEN;
31 
32 ///
33 /// MTFTP Packet OpCodes
34 ///@{
35 #define EFI_MTFTP6_OPCODE_RRQ    1   ///< The MTFTPv6 packet is a read request.
36 #define EFI_MTFTP6_OPCODE_WRQ    2   ///< The MTFTPv6 packet is a write request.
37 #define EFI_MTFTP6_OPCODE_DATA   3   ///< The MTFTPv6 packet is a data packet.
38 #define EFI_MTFTP6_OPCODE_ACK    4   ///< The MTFTPv6 packet is an acknowledgement packet.
39 #define EFI_MTFTP6_OPCODE_ERROR  5   ///< The MTFTPv6 packet is an error packet.
40 #define EFI_MTFTP6_OPCODE_OACK   6   ///< The MTFTPv6 packet is an option acknowledgement packet.
41 #define EFI_MTFTP6_OPCODE_DIR    7   ///< The MTFTPv6 packet is a directory query packet.
42 #define EFI_MTFTP6_OPCODE_DATA8  8   ///< The MTFTPv6 packet is a data packet with a big block number.
43 #define EFI_MTFTP6_OPCODE_ACK8   9   ///< The MTFTPv6 packet is an acknowledgement packet with a big block number.
44 ///@}
45 
46 ///
47 /// MTFTP ERROR Packet ErrorCodes
48 ///@{
49 ///
50 /// The error code is not defined. See the error message in the packet (if any) for details.
51 ///
52 #define EFI_MTFTP6_ERRORCODE_NOT_DEFINED  0
53 ///
54 /// The file was not found.
55 ///
56 #define EFI_MTFTP6_ERRORCODE_FILE_NOT_FOUND  1
57 ///
58 /// There was an access violation.
59 ///
60 #define EFI_MTFTP6_ERRORCODE_ACCESS_VIOLATION  2
61 ///
62 /// The disk was full or its allocation was exceeded.
63 ///
64 #define EFI_MTFTP6_ERRORCODE_DISK_FULL  3
65 ///
66 /// The MTFTPv6 operation was illegal.
67 ///
68 #define EFI_MTFTP6_ERRORCODE_ILLEGAL_OPERATION  4
69 ///
70 /// The transfer ID is unknown.
71 ///
72 #define EFI_MTFTP6_ERRORCODE_UNKNOWN_TRANSFER_ID  5
73 ///
74 /// The file already exists.
75 ///
76 #define EFI_MTFTP6_ERRORCODE_FILE_ALREADY_EXISTS  6
77 ///
78 /// There is no such user.
79 ///
80 #define EFI_MTFTP6_ERRORCODE_NO_SUCH_USER  7
81 ///
82 /// The request has been denied due to option negotiation.
83 ///
84 #define EFI_MTFTP6_ERRORCODE_REQUEST_DENIED  8
85 ///@}
86 
87 #pragma pack(1)
88 
89 ///
90 /// EFI_MTFTP6_REQ_HEADER
91 ///
92 typedef struct {
93   ///
94   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_RRQ for a read request
95   /// or OpCode = EFI_MTFTP6_OPCODE_WRQ for a write request.
96   ///
97   UINT16    OpCode;
98   ///
99   /// The file name to be downloaded or uploaded.
100   ///
101   UINT8     Filename[1];
102 } EFI_MTFTP6_REQ_HEADER;
103 
104 ///
105 /// EFI_MTFTP6_OACK_HEADER
106 ///
107 typedef struct {
108   ///
109   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_OACK.
110   ///
111   UINT16    OpCode;
112   ///
113   /// The option strings in the option acknowledgement packet.
114   ///
115   UINT8     Data[1];
116 } EFI_MTFTP6_OACK_HEADER;
117 
118 ///
119 /// EFI_MTFTP6_DATA_HEADER
120 ///
121 typedef struct {
122   ///
123   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_DATA.
124   ///
125   UINT16    OpCode;
126   ///
127   /// Block number of this data packet.
128   ///
129   UINT16    Block;
130   ///
131   /// The content of this data packet.
132   ///
133   UINT8     Data[1];
134 } EFI_MTFTP6_DATA_HEADER;
135 
136 ///
137 /// EFI_MTFTP6_ACK_HEADER
138 ///
139 typedef struct {
140   ///
141   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_ACK.
142   ///
143   UINT16    OpCode;
144   ///
145   /// The block number of the data packet that is being acknowledged.
146   ///
147   UINT16    Block[1];
148 } EFI_MTFTP6_ACK_HEADER;
149 
150 ///
151 /// EFI_MTFTP6_DATA8_HEADER
152 ///
153 typedef struct {
154   ///
155   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_DATA8.
156   ///
157   UINT16    OpCode;
158   ///
159   /// The block number of data packet.
160   ///
161   UINT64    Block;
162   ///
163   /// The content of this data packet.
164   ///
165   UINT8     Data[1];
166 } EFI_MTFTP6_DATA8_HEADER;
167 
168 ///
169 /// EFI_MTFTP6_ACK8_HEADER
170 ///
171 typedef struct {
172   ///
173   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_ACK8.
174   ///
175   UINT16    OpCode;
176   ///
177   /// The block number of the data packet that is being acknowledged.
178   ///
179   UINT64    Block[1];
180 } EFI_MTFTP6_ACK8_HEADER;
181 
182 ///
183 /// EFI_MTFTP6_ERROR_HEADER
184 ///
185 typedef struct {
186   ///
187   /// For this packet type, OpCode = EFI_MTFTP6_OPCODE_ERROR.
188   ///
189   UINT16    OpCode;
190   ///
191   /// The error number as defined by the MTFTPv6 packet error codes.
192   ///
193   UINT16    ErrorCode;
194   ///
195   /// Error message string.
196   ///
197   UINT8     ErrorMessage[1];
198 } EFI_MTFTP6_ERROR_HEADER;
199 
200 ///
201 /// EFI_MTFTP6_PACKET
202 ///
203 typedef union {
204   UINT16                     OpCode; ///< Type of packets as defined by the MTFTPv6 packet opcodes.
205   EFI_MTFTP6_REQ_HEADER      Rrq;    ///< Read request packet header.
206   EFI_MTFTP6_REQ_HEADER      Wrq;    ///< write request packet header.
207   EFI_MTFTP6_OACK_HEADER     Oack;   ///< Option acknowledge packet header.
208   EFI_MTFTP6_DATA_HEADER     Data;   ///< Data packet header.
209   EFI_MTFTP6_ACK_HEADER      Ack;    ///< Acknowledgement packet header.
210   EFI_MTFTP6_DATA8_HEADER    Data8;  ///< Data packet header with big block number.
211   EFI_MTFTP6_ACK8_HEADER     Ack8;   ///< Acknowledgement header with big block number.
212   EFI_MTFTP6_ERROR_HEADER    Error;  ///< Error packet header.
213 } EFI_MTFTP6_PACKET;
214 
215 #pragma pack()
216 
217 ///
218 /// EFI_MTFTP6_CONFIG_DATA
219 ///
220 typedef struct {
221   ///
222   /// The local IP address to use. Set to zero to let the underlying IPv6
223   /// driver choose a source address. If not zero it must be one of the
224   /// configured IP addresses in the underlying IPv6 driver.
225   ///
226   EFI_IPv6_ADDRESS    StationIp;
227   ///
228   /// Local port number. Set to zero to use the automatically assigned port number.
229   ///
230   UINT16              LocalPort;
231   ///
232   /// The IP address of the MTFTPv6 server.
233   ///
234   EFI_IPv6_ADDRESS    ServerIp;
235   ///
236   /// The initial MTFTPv6 server port number. Request packets are
237   /// sent to this port. This number is almost always 69 and using zero
238   /// defaults to 69.
239   UINT16              InitialServerPort;
240   ///
241   /// The number of times to transmit MTFTPv6 request packets and wait for a response.
242   ///
243   UINT16              TryCount;
244   ///
245   /// The number of seconds to wait for a response after sending the MTFTPv6 request packet.
246   ///
247   UINT16              TimeoutValue;
248 } EFI_MTFTP6_CONFIG_DATA;
249 
250 ///
251 /// EFI_MTFTP6_MODE_DATA
252 ///
253 typedef struct {
254   ///
255   /// The configuration data of this instance.
256   ///
257   EFI_MTFTP6_CONFIG_DATA    ConfigData;
258   ///
259   /// The number of option strings in the following SupportedOptions array.
260   ///
261   UINT8                     SupportedOptionCount;
262   ///
263   /// An array of null-terminated ASCII option strings that are recognized and supported by
264   /// this EFI MTFTPv6 Protocol driver implementation. The buffer is
265   /// read only to the caller and the caller should NOT free the buffer.
266   ///
267   UINT8                     **SupportedOptions;
268 } EFI_MTFTP6_MODE_DATA;
269 
270 ///
271 /// EFI_MTFTP_OVERRIDE_DATA
272 ///
273 typedef struct {
274   ///
275   /// IP address of the MTFTPv6 server. If set to all zero, the value that
276   /// was set by the EFI_MTFTP6_PROTOCOL.Configure() function will be used.
277   ///
278   EFI_IPv6_ADDRESS    ServerIp;
279   ///
280   /// MTFTPv6 server port number. If set to zero, it will use the value
281   /// that was set by the EFI_MTFTP6_PROTOCOL.Configure() function.
282   ///
283   UINT16              ServerPort;
284   ///
285   /// Number of times to transmit MTFTPv6 request packets and wait
286   /// for a response. If set to zero, the value that was set by
287   /// theEFI_MTFTP6_PROTOCOL.Configure() function will be used.
288   ///
289   UINT16              TryCount;
290   ///
291   /// Number of seconds to wait for a response after sending the
292   /// MTFTPv6 request packet. If set to zero, the value that was set by
293   /// the EFI_MTFTP6_PROTOCOL.Configure() function will be used.
294   ///
295   UINT16              TimeoutValue;
296 } EFI_MTFTP6_OVERRIDE_DATA;
297 
298 ///
299 /// EFI_MTFTP6_OPTION
300 ///
301 typedef struct {
302   UINT8    *OptionStr;               ///< Pointer to the null-terminated ASCII MTFTPv6 option string.
303   UINT8    *ValueStr;                ///< Pointer to the null-terminated ASCII MTFTPv6 value string.
304 } EFI_MTFTP6_OPTION;
305 
306 /**
307   EFI_MTFTP6_TIMEOUT_CALLBACK is a callback function that the caller provides to capture the
308   timeout event in the EFI_MTFTP6_PROTOCOL.ReadFile(), EFI_MTFTP6_PROTOCOL.WriteFile() or
309   EFI_MTFTP6_PROTOCOL.ReadDirectory() functions.
310 
311   Whenever a timeout occurs, the EFI MTFTPv6 Protocol driver will call the EFI_MTFTP6_TIMEOUT_CALLBACK
312   function to notify the caller of the timeout event. Any status code other than EFI_SUCCESS
313   that is returned from this function will abort the current download process.
314 
315   @param[in] This          Pointer to the EFI_MTFTP6_PROTOCOL instance.
316   @param[in] Token         The token that the caller provided in the EFI_MTFTP6_PROTOCOl.ReadFile(),
317                            WriteFile() or ReadDirectory() function.
318   @param[in] PacketLen     Indicates the length of the packet.
319   @param[in] Packet        Pointer to an MTFTPv6 packet.
320 
321   @retval EFI_SUCCESS      Operation success.
322   @retval Others           Aborts session.
323 
324 **/
325 typedef
326 EFI_STATUS
327 (EFIAPI *EFI_MTFTP6_CHECK_PACKET)(
328   IN EFI_MTFTP6_PROTOCOL      *This,
329   IN EFI_MTFTP6_TOKEN         *Token,
330   IN UINT16                   PacketLen,
331   IN EFI_MTFTP6_PACKET        *Packet
332   );
333 
334 /**
335   EFI_MTFTP6_TIMEOUT_CALLBACK is a callback function that the caller provides to capture the
336   timeout event in the EFI_MTFTP6_PROTOCOL.ReadFile(), EFI_MTFTP6_PROTOCOL.WriteFile() or
337   EFI_MTFTP6_PROTOCOL.ReadDirectory() functions.
338 
339   Whenever a timeout occurs, the EFI MTFTPv6 Protocol driver will call the EFI_MTFTP6_TIMEOUT_CALLBACK
340   function to notify the caller of the timeout event. Any status code other than EFI_SUCCESS
341   that is returned from this function will abort the current download process.
342 
343   @param[in]      This     Pointer to the EFI_MTFTP6_PROTOCOL instance.
344   @param[in]      Token    The token that is provided in the EFI_MTFTP6_PROTOCOL.ReadFile() or
345                            EFI_MTFTP6_PROTOCOL.WriteFile() or EFI_MTFTP6_PROTOCOL.ReadDirectory()
346                            functions by the caller.
347 
348   @retval EFI_SUCCESS      Operation success.
349   @retval Others           Aborts session.
350 
351 **/
352 typedef
353 EFI_STATUS
354 (EFIAPI *EFI_MTFTP6_TIMEOUT_CALLBACK)(
355   IN EFI_MTFTP6_PROTOCOL      *This,
356   IN EFI_MTFTP6_TOKEN         *Token
357   );
358 
359 /**
360   EFI_MTFTP6_PACKET_NEEDED is a callback function that the caller provides to feed data to the
361   EFI_MTFTP6_PROTOCOL.WriteFile() function.
362 
363   EFI_MTFTP6_PACKET_NEEDED provides another mechanism for the caller to provide data to upload
364   other than a static buffer. The EFI MTFTP6 Protocol driver always calls EFI_MTFTP6_PACKET_NEEDED
365   to get packet data from the caller if no static buffer was given in the initial call to
366   EFI_MTFTP6_PROTOCOL.WriteFile() function. Setting *Length to zero signals the end of the session.
367   Returning a status code other than EFI_SUCCESS aborts the session.
368 
369   @param[in]      This     Pointer to the EFI_MTFTP6_PROTOCOL instance.
370   @param[in]      Token    The token provided in the EFI_MTFTP6_PROTOCOL.WriteFile() by the caller.
371   @param[in, out] Length   Indicates the length of the raw data wanted on input, and the
372                            length the data available on output.
373   @param[out]     Buffer   Pointer to the buffer where the data is stored.
374 
375   @retval EFI_SUCCESS      Operation success.
376   @retval Others           Aborts session.
377 
378 **/
379 typedef
380 EFI_STATUS
381 (EFIAPI *EFI_MTFTP6_PACKET_NEEDED)(
382   IN EFI_MTFTP6_PROTOCOL      *This,
383   IN EFI_MTFTP6_TOKEN         *Token,
384   IN OUT UINT16               *Length,
385   OUT VOID                    **Buffer
386   );
387 
388 struct _EFI_MTFTP6_TOKEN {
389   ///
390   /// The status that is returned to the caller at the end of the operation
391   /// to indicate whether this operation completed successfully.
392   /// Defined Status values are listed below.
393   ///
394   EFI_STATUS                     Status;
395   ///
396   /// The event that will be signaled when the operation completes. If
397   /// set to NULL, the corresponding function will wait until the read or
398   /// write operation finishes. The type of Event must be EVT_NOTIFY_SIGNAL.
399   ///
400   EFI_EVENT                      Event;
401   ///
402   /// If not NULL, the data that will be used to override the existing
403   /// configure data.
404   ///
405   EFI_MTFTP6_OVERRIDE_DATA       *OverrideData;
406   ///
407   /// Pointer to the null-terminated ASCII file name string.
408   ///
409   UINT8                          *Filename;
410   ///
411   /// Pointer to the null-terminated ASCII mode string. If NULL, octet is used.
412   ///
413   UINT8                          *ModeStr;
414   ///
415   /// Number of option/value string pairs.
416   ///
417   UINT32                         OptionCount;
418   ///
419   /// Pointer to an array of option/value string pairs. Ignored if
420   /// OptionCount is zero. Both a remote server and this driver
421   /// implementation should support these options. If one or more
422   /// options are unrecognized by this implementation, it is sent to the
423   /// remote server without being changed.
424   ///
425   EFI_MTFTP6_OPTION              *OptionList;
426   ///
427   /// On input, the size, in bytes, of Buffer. On output, the number
428   /// of bytes transferred.
429   ///
430   UINT64                         BufferSize;
431   ///
432   /// Pointer to the data buffer. Data that is downloaded from the
433   /// MTFTPv6 server is stored here. Data that is uploaded to the
434   /// MTFTPv6 server is read from here. Ignored if BufferSize is zero.
435   ///
436   VOID                           *Buffer;
437   ///
438   /// Pointer to the context that will be used by CheckPacket,
439   /// TimeoutCallback and PacketNeeded.
440   ///
441   VOID                           *Context;
442   ///
443   /// Pointer to the callback function to check the contents of the
444   /// received packet.
445   ///
446   EFI_MTFTP6_CHECK_PACKET        CheckPacket;
447   ///
448   /// Pointer to the function to be called when a timeout occurs.
449   ///
450   EFI_MTFTP6_TIMEOUT_CALLBACK    TimeoutCallback;
451   ///
452   /// Pointer to the function to provide the needed packet contents.
453   /// Only used in WriteFile() operation.
454   ///
455   EFI_MTFTP6_PACKET_NEEDED       PacketNeeded;
456 };
457 
458 /**
459   Read the current operational settings.
460 
461   The GetModeData() function reads the current operational settings of this EFI MTFTPv6
462   Protocol driver instance.
463 
464   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
465   @param[out] ModeData           The buffer in which the EFI MTFTPv6 Protocol driver mode
466                                  data is returned.
467 
468   @retval  EFI_SUCCESS           The configuration data was successfully returned.
469   @retval  EFI_OUT_OF_RESOURCES  The required mode data could not be allocated.
470   @retval  EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
471 
472 **/
473 typedef
474 EFI_STATUS
475 (EFIAPI *EFI_MTFTP6_GET_MODE_DATA)(
476   IN EFI_MTFTP6_PROTOCOL      *This,
477   OUT EFI_MTFTP6_MODE_DATA    *ModeData
478   );
479 
480 /**
481   Initializes, changes, or resets the default operational setting for this EFI MTFTPv6
482   Protocol driver instance.
483 
484   The Configure() function is used to set and change the configuration data for this EFI
485   MTFTPv6 Protocol driver instance. The configuration data can be reset to startup defaults by calling
486   Configure() with MtftpConfigData set to NULL. Whenever the instance is reset, any
487   pending operation is aborted. By changing the EFI MTFTPv6 Protocol driver instance configuration
488   data, the client can connect to different MTFTPv6 servers. The configuration parameters in
489   MtftpConfigData are used as the default parameters in later MTFTPv6 operations and can be
490   overridden in later operations.
491 
492   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
493   @param[in]  MtftpConfigData    Pointer to the configuration data structure.
494 
495   @retval  EFI_SUCCESS           The EFI MTFTPv6 Protocol instance was configured successfully.
496   @retval  EFI_INVALID_PARAMETER One or more following conditions are TRUE:
497                                  - This is NULL.
498                                  - MtftpConfigData.StationIp is neither zero nor one
499                                    of the configured IP addresses in the underlying IPv6 driver.
500                                  - MtftpCofigData.ServerIp is not a valid IPv6 unicast address.
501   @retval  EFI_ACCESS_DENIED     - The configuration could not be changed at this time because there
502                                    is some MTFTP background operation in progress.
503                                  - MtftpCofigData.LocalPort is already in use.
504   @retval  EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
505                                  address for this instance, but no source address was available for use.
506   @retval  EFI_OUT_OF_RESOURCES  The EFI MTFTPv6 Protocol driver instance data could not be
507                                  allocated.
508   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred. The EFI
509                                  MTFTPv6 Protocol driver instance is not configured.
510 
511 
512 **/
513 typedef
514 EFI_STATUS
515 (EFIAPI *EFI_MTFTP6_CONFIGURE)(
516   IN EFI_MTFTP6_PROTOCOL      *This,
517   IN EFI_MTFTP6_CONFIG_DATA   *MtftpConfigData OPTIONAL
518   );
519 
520 /**
521   Get information about a file from an MTFTPv6 server.
522 
523   The GetInfo() function assembles an MTFTPv6 request packet with options, sends it to the
524   MTFTPv6 server, and may return an MTFTPv6 OACK, MTFTPv6 ERROR, or ICMP ERROR packet.
525   Retries occur only if no response packets are received from the MTFTPv6 server before the
526   timeout expires.
527 
528   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
529   @param[in]  OverrideData       Data that is used to override the existing parameters. If NULL, the
530                                  default parameters that were set in the EFI_MTFTP6_PROTOCOL.Configure()
531                                  function are used.
532   @param[in]  Filename           Pointer to null-terminated ASCII file name string.
533   @param[in]  ModeStr            Pointer to null-terminated ASCII mode string. If NULL, octet will be used
534   @param[in]  OptionCount        Number of option/value string pairs in OptionList.
535   @param[in]  OptionList         Pointer to array of option/value string pairs. Ignored if
536                                  OptionCount is zero.
537   @param[out] PacketLength       The number of bytes in the returned packet.
538   @param[out] Packet             The pointer to the received packet. This buffer must be freed by
539                                  the caller.
540 
541   @retval  EFI_SUCCESS              An MTFTPv6 OACK packet was received and is in the Packet.
542   @retval  EFI_INVALID_PARAMETER    One or more of the following conditions is TRUE:
543                                     - This is NULL.
544                                     - Filename is NULL
545                                     - OptionCount is not zero and OptionList is NULL.
546                                     - One or more options in OptionList have wrong format.
547                                     - PacketLength is NULL.
548                                     - OverrideData.ServerIp is not valid unicast IPv6 addresses.
549   @retval  EFI_UNSUPPORTED          One or more options in the OptionList are unsupported by
550                                     this implementation.
551   @retval  EFI_NOT_STARTED          The EFI MTFTPv6 Protocol driver has not been started.
552   @retval  EFI_NO_MAPPING           The underlying IPv6 driver was responsible for choosing a source
553                                     address for this instance, but no source address was available for use.
554   @retval  EFI_ACCESS_DENIED        The previous operation has not completed yet.
555   @retval  EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
556   @retval  EFI_TFTP_ERROR           An MTFTPv6 ERROR packet was received and is in the Packet.
557   @retval  EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received and the Packet is set to NULL.
558   @retval  EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received and the Packet is set to NULL.
559   @retval  EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received and the Packet is set to NULL.
560   @retval  EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received and the Packet is set to NULL.
561   @retval  EFI_ICMP_ERROR           Some other ICMP ERROR packet was received and the Packet is set to NULL.
562   @retval  EFI_PROTOCOL_ERROR       An unexpected MTFTPv6 packet was received and is in the Packet.
563   @retval  EFI_TIMEOUT              No responses were received from the MTFTPv6 server.
564   @retval  EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
565   @retval  EFI_NO_MEDIA             There was a media error.
566 
567 **/
568 typedef
569 EFI_STATUS
570 (EFIAPI *EFI_MTFTP6_GET_INFO)(
571   IN EFI_MTFTP6_PROTOCOL      *This,
572   IN EFI_MTFTP6_OVERRIDE_DATA *OverrideData OPTIONAL,
573   IN UINT8                    *Filename,
574   IN UINT8                    *ModeStr OPTIONAL,
575   IN UINT8                    OptionCount,
576   IN EFI_MTFTP6_OPTION        *OptionList OPTIONAL,
577   OUT UINT32                  *PacketLength,
578   OUT EFI_MTFTP6_PACKET       **Packet OPTIONAL
579   );
580 
581 /**
582   Parse the options in an MTFTPv6 OACK packet.
583 
584   The ParseOptions() function parses the option fields in an MTFTPv6 OACK packet and
585   returns the number of options that were found and optionally a list of pointers to
586   the options in the packet.
587   If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is returned
588   and *OptionCount and *OptionList stop at the last valid option.
589 
590   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
591   @param[in]  PacketLen          Length of the OACK packet to be parsed.
592   @param[in]  Packet             Pointer to the OACK packet to be parsed.
593   @param[out] OptionCount        Pointer to the number of options in the following OptionList.
594   @param[out] OptionList         Pointer to EFI_MTFTP6_OPTION storage. Each pointer in the
595                                  OptionList points to the corresponding MTFTP option buffer
596                                  in the Packet. Call the EFI Boot Service FreePool() to
597                                  release the OptionList if the options in this OptionList
598                                  are not needed any more.
599 
600   @retval  EFI_SUCCESS           The OACK packet was valid and the OptionCount and
601                                  OptionList parameters have been updated.
602   @retval  EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
603                                  - PacketLen is 0.
604                                  - Packet is NULL or Packet is not a valid MTFTPv6 packet.
605                                  - OptionCount is NULL.
606   @retval  EFI_NOT_FOUND         No options were found in the OACK packet.
607   @retval  EFI_OUT_OF_RESOURCES  Storage for the OptionList array can not be allocated.
608   @retval  EFI_PROTOCOL_ERROR    One or more of the option fields is invalid.
609 
610 **/
611 typedef
612 EFI_STATUS
613 (EFIAPI *EFI_MTFTP6_PARSE_OPTIONS)(
614   IN EFI_MTFTP6_PROTOCOL      *This,
615   IN UINT32                   PacketLen,
616   IN EFI_MTFTP6_PACKET        *Packet,
617   OUT UINT32                  *OptionCount,
618   OUT EFI_MTFTP6_OPTION       **OptionList OPTIONAL
619   );
620 
621 /**
622   Download a file from an MTFTPv6 server.
623 
624   The ReadFile() function is used to initialize and start an MTFTPv6 download process and
625   optionally wait for completion. When the download operation completes, whether successfully or
626   not, the Token.Status field is updated by the EFI MTFTPv6 Protocol driver and then
627   Token.Event is signaled if it is not NULL.
628 
629   Data can be downloaded from the MTFTPv6 server into either of the following locations:
630   - A fixed buffer that is pointed to by Token.Buffer
631   - A download service function that is pointed to by Token.CheckPacket
632 
633   If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
634   will be called first. If the call is successful, the packet will be stored in Token.Buffer.
635 
636   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
637   @param[in]  Token              Pointer to the token structure to provide the parameters that are
638                                  used in this operation.
639 
640   @retval  EFI_SUCCESS              The data file has been transferred successfully.
641   @retval  EFI_OUT_OF_RESOURCES     Required system resources could not be allocated.
642   @retval  EFI_BUFFER_TOO_SMALL     BufferSize is not zero but not large enough to hold the
643                                     downloaded data in downloading process.
644   @retval  EFI_ABORTED              Current operation is aborted by user.
645   @retval  EFI_NETWORK_UNREACHABLE  An ICMP network unreachable error packet was received.
646   @retval  EFI_HOST_UNREACHABLE     An ICMP host unreachable error packet was received.
647   @retval  EFI_PROTOCOL_UNREACHABLE An ICMP protocol unreachable error packet was received.
648   @retval  EFI_PORT_UNREACHABLE     An ICMP port unreachable error packet was received.
649   @retval  EFI_ICMP_ERROR           An ICMP ERROR packet was received.
650   @retval  EFI_TIMEOUT              No responses were received from the MTFTPv6 server.
651   @retval  EFI_TFTP_ERROR           An MTFTPv6 ERROR packet was received.
652   @retval  EFI_DEVICE_ERROR         An unexpected network error or system error occurred.
653   @retval  EFI_NO_MEDIA             There was a media error.
654 
655 **/
656 typedef
657 EFI_STATUS
658 (EFIAPI *EFI_MTFTP6_READ_FILE)(
659   IN EFI_MTFTP6_PROTOCOL      *This,
660   IN EFI_MTFTP6_TOKEN         *Token
661   );
662 
663 /**
664   Send a file to an MTFTPv6 server. May be unsupported in some implementations.
665 
666   The WriteFile() function is used to initialize an uploading operation with the given option list
667   and optionally wait for completion. If one or more of the options is not supported by the server, the
668   unsupported options are ignored and a standard TFTP process starts instead. When the upload
669   process completes, whether successfully or not, Token.Event is signaled, and the EFI MTFTPv6
670   Protocol driver updates Token.Status.
671 
672   The caller can supply the data to be uploaded in the following two modes:
673   - Through the user-provided buffer
674   - Through a callback function
675 
676   With the user-provided buffer, the Token.BufferSize field indicates the length of the buffer,
677   and the driver will upload the data in the buffer. With an EFI_MTFTP6_PACKET_NEEDED
678   callback function, the driver will call this callback function to get more data from the user to upload.
679   See the definition of EFI_MTFTP6_PACKET_NEEDED for more information. These two modes
680   cannot be used at the same time. The callback function will be ignored if the user provides the
681   buffer.
682 
683   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
684   @param[in]  Token              Pointer to the token structure to provide the parameters that are
685                                  used in this operation.
686 
687   @retval  EFI_SUCCESS           The upload session has started.
688   @retval  EFI_UNSUPPORTED       The operation is not supported by this implementation.
689   @retval  EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
690                                  - This is NULL.
691                                  - Token is NULL.
692                                  - Token.Filename is NULL.
693                                  - Token.OptionCount is not zero and Token.OptionList is NULL.
694                                  - One or more options in Token.OptionList have wrong format.
695                                  - Token.Buffer and Token.PacketNeeded are both NULL.
696                                  - Token.OverrideData.ServerIp is not valid unicast IPv6 addresses.
697   @retval  EFI_UNSUPPORTED       One or more options in the Token.OptionList are not
698                                  supported by this implementation.
699   @retval  EFI_NOT_STARTED       The EFI MTFTPv6 Protocol driver has not been started.
700   @retval  EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
701                                  address for this instance, but no source address was available for use.
702   @retval  EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv6 session.
703   @retval  EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
704   @retval  EFI_ACCESS_DENIED     The previous operation has not completed yet.
705   @retval  EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
706 
707 **/
708 typedef
709 EFI_STATUS
710 (EFIAPI *EFI_MTFTP6_WRITE_FILE)(
711   IN EFI_MTFTP6_PROTOCOL      *This,
712   IN EFI_MTFTP6_TOKEN         *Token
713   );
714 
715 /**
716   Download a data file directory from an MTFTPv6 server. May be unsupported in some implementations.
717 
718   The ReadDirectory() function is used to return a list of files on the MTFTPv6 server that are
719   logically (or operationally) related to Token.Filename. The directory request packet that is sent
720   to the server is built with the option list that was provided by caller, if present.
721 
722   The file information that the server returns is put into either of the following locations:
723   - A fixed buffer that is pointed to by Token.Buffer
724   - A download service function that is pointed to by Token.CheckPacket
725 
726   If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
727   will be called first. If the call is successful, the packet will be stored in Token.Buffer.
728 
729   The returned directory listing in the Token.Buffer or EFI_MTFTP6_PACKET consists of a list
730   of two or three variable-length ASCII strings, each terminated by a null character, for each file in the
731   directory. If the multicast option is involved, the first field of each directory entry is the static
732   multicast IP address and UDP port number that is associated with the file name. The format of the
733   field is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its terminating
734   null character are not present.
735 
736   The next field of each directory entry is the file name and the last field is the file information string.
737   The information string contains the file size and the create/modify timestamp. The format of the
738   information string is filesize yyyy-mm-dd hh:mm:ss:ffff. The timestamp is
739   Coordinated Universal Time (UTC; also known as Greenwich Mean Time [GMT]).
740 
741   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
742   @param[in]  Token              Pointer to the token structure to provide the parameters that are
743                                  used in this operation.
744 
745   @retval  EFI_SUCCESS           The MTFTPv6 related file "directory" has been downloaded.
746   @retval  EFI_UNSUPPORTED       The EFI MTFTPv6 Protocol driver does not support this function.
747   @retval  EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
748                                  - This is NULL.
749                                  - Token is NULL.
750                                  - Token.Filename is NULL.
751                                  - Token.OptionCount is not zero and Token.OptionList is NULL.
752                                  - One or more options in Token.OptionList have wrong format.
753                                  - Token.Buffer and Token.CheckPacket are both NULL.
754                                  - Token.OverrideData.ServerIp is not valid unicast IPv6 addresses.
755   @retval  EFI_UNSUPPORTED       One or more options in the Token.OptionList are not
756                                  supported by this implementation.
757   @retval  EFI_NOT_STARTED       The EFI MTFTPv6 Protocol driver has not been started.
758   @retval  EFI_NO_MAPPING        The underlying IPv6 driver was responsible for choosing a source
759                                  address for this instance, but no source address was available for use.
760   @retval  EFI_ALREADY_STARTED   This Token is already being used in another MTFTPv6 session.
761   @retval  EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
762   @retval  EFI_ACCESS_DENIED     The previous operation has not completed yet.
763   @retval  EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
764 
765 **/
766 typedef
767 EFI_STATUS
768 (EFIAPI *EFI_MTFTP6_READ_DIRECTORY)(
769   IN EFI_MTFTP6_PROTOCOL      *This,
770   IN EFI_MTFTP6_TOKEN         *Token
771   );
772 
773 /**
774   Polls for incoming data packets and processes outgoing data packets.
775 
776   The Poll() function can be used by network drivers and applications to increase the rate that data
777   packets are moved between the communications device and the transmit and receive queues.
778   In some systems, the periodic timer event in the managed network driver may not poll the
779   underlying communications device fast enough to transmit and/or receive all data packets without
780   missing incoming packets or dropping outgoing packets. Drivers and applications that are
781   experiencing packet loss should try calling the Poll() function more often.
782 
783   @param[in]  This               Pointer to the EFI_MTFTP6_PROTOCOL instance.
784 
785   @retval  EFI_SUCCESS           Incoming or outgoing data was processed.
786   @retval  EFI_NOT_STARTED       This EFI MTFTPv6 Protocol instance has not been started.
787   @retval  EFI_INVALID_PARAMETER This is NULL.
788   @retval  EFI_DEVICE_ERROR      An unexpected system or network error occurred.
789   @retval  EFI_TIMEOUT           Data was dropped out of the transmit and/or receive queue.
790                                  Consider increasing the polling rate.
791 
792 **/
793 typedef
794 EFI_STATUS
795 (EFIAPI *EFI_MTFTP6_POLL)(
796   IN EFI_MTFTP6_PROTOCOL      *This
797   );
798 
799 ///
800 /// The EFI_MTFTP6_PROTOCOL is designed to be used by UEFI drivers and applications to transmit
801 /// and receive data files. The EFI MTFTPv6 Protocol driver uses the underlying EFI UDPv6 Protocol
802 /// driver and EFI IPv6 Protocol driver.
803 ///
804 struct _EFI_MTFTP6_PROTOCOL {
805   EFI_MTFTP6_GET_MODE_DATA     GetModeData;
806   EFI_MTFTP6_CONFIGURE         Configure;
807   EFI_MTFTP6_GET_INFO          GetInfo;
808   EFI_MTFTP6_PARSE_OPTIONS     ParseOptions;
809   EFI_MTFTP6_READ_FILE         ReadFile;
810   EFI_MTFTP6_WRITE_FILE        WriteFile;
811   EFI_MTFTP6_READ_DIRECTORY    ReadDirectory;
812   EFI_MTFTP6_POLL              Poll;
813 };
814 
815 extern EFI_GUID  gEfiMtftp6ServiceBindingProtocolGuid;
816 extern EFI_GUID  gEfiMtftp6ProtocolGuid;
817 
818 #endif
819