]> git.proxmox.com Git - mirror_edk2.git/blob - Tools/Source/TianoTools/Include/Protocol/Mtftp4.h
Remove the dependence to MdePkg
[mirror_edk2.git] / Tools / Source / TianoTools / Include / Protocol / Mtftp4.h
1 /** @file
2 EFI Multicast Trivial File Tranfer Protocol Definition
3
4 Copyright (c) 2006, Intel Corporation
5 All rights reserved. This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 Module Name: Mtftp4.h
14
15 **/
16
17 #ifndef __EFI_MTFTP4_PROTOCOL_H__
18 #define __EFI_MTFTP4_PROTOCOL_H__
19
20 #define EFI_MTFTP4_SERVICE_BINDING_PROTOCOL_GUID \
21 { \
22 0x2FE800BE, 0x8F01, 0x4aa6, {0x94, 0x6B, 0xD7, 0x13, 0x88, 0xE1, 0x83, 0x3F } \
23 }
24
25 #define EFI_MTFTP4_PROTOCOL_GUID \
26 { \
27 0x3ad9df29, 0x4501, 0x478d, {0xb1, 0xf8, 0x7f, 0x7f, 0xe7, 0x0e, 0x50, 0xf3 } \
28 }
29
30 typedef struct _EFI_MTFTP4_PROTOCOL EFI_MTFTP4_PROTOCOL;
31 typedef struct _EFI_MTFTP4_TOKEN EFI_MTFTP4_TOKEN;
32
33 //
34 //MTFTP4 packet opcode definition
35 //
36 #define EFI_MTFTP4_OPCODE_RRQ 1
37 #define EFI_MTFTP4_OPCODE_WRQ 2
38 #define EFI_MTFTP4_OPCODE_DATA 3
39 #define EFI_MTFTP4_OPCODE_ACK 4
40 #define EFI_MTFTP4_OPCODE_ERROR 5
41 #define EFI_MTFTP4_OPCODE_OACK 6
42 #define EFI_MTFTP4_OPCODE_DIR 7
43 #define EFI_MTFTP4_OPCODE_DATA8 8
44 #define EFI_MTFTP4_OPCODE_ACK8 9
45
46 //
47 // MTFTP4 error code definition
48 //
49 #define EFI_MTFTP4_ERRORCODE_NOT_DEFINED 0
50 #define EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND 1
51 #define EFI_MTFTP4_ERRORCODE_ACCESS_VIOLATION 2
52 #define EFI_MTFTP4_ERRORCODE_DISK_FULL 3
53 #define EFI_MTFTP4_ERRORCODE_ILLEGAL_OPERATION 4
54 #define EFI_MTFTP4_ERRORCODE_UNKNOWN_TRANSFER_ID 5
55 #define EFI_MTFTP4_ERRORCODE_FILE_ALREADY_EXISTS 6
56 #define EFI_MTFTP4_ERRORCODE_NO_SUCH_USER 7
57 #define EFI_MTFTP4_ERRORCODE_REQUEST_DENIED 8
58
59 //
60 // MTFTP4 pacekt definitions
61 //
62 #pragma pack(1)
63
64 typedef struct {
65 UINT16 OpCode;
66 UINT8 Filename[1];
67 } EFI_MTFTP4_REQ_HEADER;
68
69 typedef struct {
70 UINT16 OpCode;
71 UINT8 Data[1];
72 } EFI_MTFTP4_OACK_HEADER;
73
74 typedef struct {
75 UINT16 OpCode;
76 UINT16 Block;
77 UINT8 Data[1];
78 } EFI_MTFTP4_DATA_HEADER;
79
80 typedef struct {
81 UINT16 OpCode;
82 UINT16 Block[1];
83 } EFI_MTFTP4_ACK_HEADER;
84
85 typedef struct {
86 UINT16 OpCode;
87 UINT64 Block;
88 UINT8 Data[1];
89 } EFI_MTFTP4_DATA8_HEADER;
90
91 typedef struct {
92 UINT16 OpCode;
93 UINT64 Block[1];
94 } EFI_MTFTP4_ACK8_HEADER;
95
96 typedef struct {
97 UINT16 OpCode;
98 UINT16 ErrorCode;
99 UINT8 ErrorMessage[1];
100 } EFI_MTFTP4_ERROR_HEADER;
101
102 typedef union {
103 UINT16 OpCode;
104 EFI_MTFTP4_REQ_HEADER Rrq;
105 EFI_MTFTP4_REQ_HEADER Wrq;
106 EFI_MTFTP4_OACK_HEADER Oack;
107 EFI_MTFTP4_DATA_HEADER Data;
108 EFI_MTFTP4_ACK_HEADER Ack;
109 EFI_MTFTP4_DATA8_HEADER Data8;
110 EFI_MTFTP4_ACK8_HEADER Ack8;
111 EFI_MTFTP4_ERROR_HEADER Error;
112 } EFI_MTFTP4_PACKET;
113
114 #pragma pack()
115
116 //
117 // MTFTP4 option definition
118 //
119 typedef struct {
120 UINT8 *OptionStr;
121 UINT8 *ValueStr;
122 } EFI_MTFTP4_OPTION;
123
124
125 typedef struct {
126 BOOLEAN UseDefaultSetting;
127 EFI_IPv4_ADDRESS StationIp;
128 EFI_IPv4_ADDRESS SubnetMask;
129 UINT16 LocalPort;
130 EFI_IPv4_ADDRESS GatewayIp;
131 EFI_IPv4_ADDRESS ServerIp;
132 UINT16 InitialServerPort;
133 UINT16 TryCount;
134 UINT16 TimeoutValue;
135 } EFI_MTFTP4_CONFIG_DATA;
136
137
138 typedef struct {
139 EFI_MTFTP4_CONFIG_DATA ConfigData;
140 UINT8 SupportedOptionCount;
141 UINT8 **SupportedOptoins;
142 UINT8 UnsupportedOptionCount;
143 UINT8 **UnsupportedOptoins;
144 } EFI_MTFTP4_MODE_DATA;
145
146
147 typedef struct {
148 EFI_IPv4_ADDRESS GatewayIp;
149 EFI_IPv4_ADDRESS ServerIp;
150 UINT16 ServerPort;
151 UINT16 TryCount;
152 UINT16 TimeoutValue;
153 } EFI_MTFTP4_OVERRIDE_DATA;
154
155 //
156 // Protocol interfaces definition
157 //
158
159 /**
160 a callback function that is provided by the caller to intercept
161 the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the
162 EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept
163 EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to
164 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().
165
166 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
167 @param Token The token that the caller provided in the
168 EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile()
169 or ReadDirectory() function.
170 @param PacketLen Indicates the length of the packet.
171 @param Packet Pointer to an MTFTPv4 packet.
172
173 @retval EFI_SUCCESS Operation sucess
174 @retval Others Abort transfer process
175
176 **/
177 typedef
178 EFI_STATUS
179 (EFIAPI *EFI_MTFTP4_CHECK_PACKET)(
180 IN EFI_MTFTP4_PROTOCOL *This,
181 IN EFI_MTFTP4_TOKEN *Token,
182 IN UINT16 PacketLen,
183 IN EFI_MTFTP4_PACKET *Paket
184 )
185 ;
186
187 /**
188 Timeout callback funtion.
189
190 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
191 @param Token The token that is provided in the
192 EFI_MTFTP4_PROTOCOL.ReadFile() or
193 EFI_MTFTP4_PROTOCOL.WriteFile() or
194 EFI_MTFTP4_PROTOCOL.ReadDirectory() functions
195 by the caller.
196
197 @retval EFI_SUCCESS Operation sucess
198 @retval Others Aborts download process.
199
200 **/
201 typedef
202 EFI_STATUS
203 (EFIAPI *EFI_MTFTP4_TIMEOUT_CALLBACK)(
204 IN EFI_MTFTP4_PROTOCOL *This,
205 IN EFI_MTFTP4_TOKEN *Token
206 )
207 ;
208
209 /**
210 a callback function that the caller provides to feed data to the
211 EFI_MTFTP4_PROTOCOL.WriteFile() function.
212
213 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
214 @param Token The token provided in the
215 EFI_MTFTP4_PROTOCOL.WriteFile() by the caller.
216 @param Length Indicates the length of the raw data wanted on input, and the
217 length the data available on output.
218 @param Buffer Pointer to the buffer where the data is stored.
219
220 @retval EFI_SUCCESS Operation sucess
221 @retval Others Aborts session.
222
223 **/
224 typedef
225 EFI_STATUS
226 (EFIAPI *EFI_MTFTP4_PACKET_NEEDED)(
227 IN EFI_MTFTP4_PROTOCOL *This,
228 IN EFI_MTFTP4_TOKEN *Token,
229 IN OUT UINT16 *Length,
230 OUT VOID **Buffer
231 )
232 ;
233
234
235 /**
236 Submits an asynchronous interrupt transfer to an interrupt endpoint of a USB device.
237
238 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
239 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol driver mode data.
240
241 @retval EFI_SUCCESS The configuration data was successfully returned.
242 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
243 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
244
245 **/
246 typedef
247 EFI_STATUS
248 (EFIAPI *EFI_MTFTP4_GET_MODE_DATA)(
249 IN EFI_MTFTP4_PROTOCOL *This,
250 OUT EFI_MTFTP4_MODE_DATA *ModeData
251 )
252 ;
253
254
255 /**
256 Initializes, changes, or resets the default operational setting for this
257 EFI MTFTPv4 Protocol driver instance.
258
259 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
260 @param MtftpConfigData Pointer to the configuration data structure.
261
262 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured successfully.
263 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
264 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this time because
265 there is one MTFTP background operation in progress.
266 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
267 RARP, etc.) has not finished yet.
268 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.) could not
269 be located when clients choose to use the default address
270 settings.
271 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could not be
272 allocated.
273 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The EFI
274 MTFTPv4 Protocol driver instance is not configured.
275
276 **/
277 typedef
278 EFI_STATUS
279 (EFIAPI *EFI_MTFTP4_CONFIGURE)(
280 IN EFI_MTFTP4_PROTOCOL *This,
281 IN EFI_MTFTP4_CONFIG_DATA *MtftpConfigData OPTIONAL
282 )
283 ;
284
285
286 /**
287 Gets information about a file from an MTFTPv4 server.
288
289 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
290 @param OverrideData Data that is used to override the existing parameters. If NULL,
291 the default parameters that were set in the
292 EFI_MTFTP4_PROTOCOL.Configure() function are used.
293 @param Filename Pointer to ASCIIZ file name string.
294 @param ModeStr Pointer to ASCIIZ mode string. If NULL, ¡°octet¡± will be used.
295 @param OptionCount Number of option/value string pairs in OptionList.
296 @param OptionList Pointer to array of option/value string pairs. Ignored if
297 OptionCount is zero.
298 @param PacketLength The number of bytes in the returned packet.
299 @param Packet The pointer to the received packet. This buffer must be freed by
300 the caller.
301
302 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in the Buffer.
303 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
304 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
305 unsupported list of structure EFI_MTFTP4_MODE_DATA.
306
307 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
308 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
309 RARP, etc.) has not finished yet.
310 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
311 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
312 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in the buffer.
313 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and is in the Buffer.
314 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is in the buffer.
315 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
316 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
317
318 **/
319 typedef
320 EFI_STATUS
321 (EFIAPI *EFI_MTFTP4_GET_INFO)(
322 IN EFI_MTFTP4_PROTOCOL *This,
323 IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData OPTIONAL,
324 IN UINT8 *Filename,
325 IN UINT8 *ModeStr OPTIONAL,
326 IN UINT8 OptionCount,
327 IN EFI_MTFTP4_OPTION *OptionList,
328 OUT UINT32 *PacketLength,
329 OUT EFI_MTFTP4_PACKET **Packet OPTIONAL
330 )
331 ;
332
333 /**
334 Parses the options in an MTFTPv4 OACK packet.
335
336 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
337 @param PacketLen Length of the OACK packet to be parsed.
338 @param Packet Pointer to the OACK packet to be parsed.
339 @param OptionCount Pointer to the number of options in following OptionList.
340 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the EFI Boot
341 Service FreePool() to release each option if they are not
342 needed any more.
343
344 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
345 OptionList parameters have been updated.
346 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
347 - PacketLen is 0.
348 - Packet is NULL or Packet is not a valid MTFTPv4 packet.
349 - OptionCount is NULL.
350 @retval EFI_NOT_FOUND No options were found in the OACK packet.
351 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
352 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
353
354 **/
355 typedef
356 EFI_STATUS
357 (EFIAPI *EFI_MTFTP4_PARSE_OPTIONS)(
358 IN EFI_MTFTP4_PROTOCOL *This,
359 IN UINT32 PacketLen,
360 IN EFI_MTFTP4_PACKET *Packet,
361 OUT UINT32 *OptionCount,
362 OUT EFI_MTFTP4_OPTION **OptionList OPTIONAL
363 )
364 ;
365
366
367 /**
368 Downloads a file from an MTFTPv4 server.
369
370 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
371 @param Token Pointer to the token structure to provide the parameters that are
372 used in this operation.
373
374 @retval EFI_SUCCESS The data file has been transferred successfully.
375 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
376 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded data
377 in downloading process.
378 @retval EFI_ABORTED Current operation is aborted by user.
379 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
380 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
381 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
382 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
383
384 **/
385 typedef
386 EFI_STATUS
387 (EFIAPI *EFI_MTFTP4_READ_FILE)(
388 IN EFI_MTFTP4_PROTOCOL *This,
389 IN EFI_MTFTP4_TOKEN *Token
390 )
391 ;
392
393
394
395 /**
396 Sends a file to an MTFTPv4 server.
397
398 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
399 @param Token Pointer to the token structure to provide the parameters that are
400 used in this operation.
401
402 @retval EFI_SUCCESS The upload session has started.
403 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
404 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
405 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
406 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
407 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
408 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
409 RARP, etc.) is not finished yet.
410 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
411 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
412 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
413 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
414
415 **/
416 typedef
417 EFI_STATUS
418 (EFIAPI *EFI_MTFTP4_WRITE_FILE)(
419 IN EFI_MTFTP4_PROTOCOL *This,
420 IN EFI_MTFTP4_TOKEN *Token
421 )
422 ;
423
424
425 /**
426 Downloads a data file ¡°directory¡± from an MTFTPv4 server. May be unsupported in some EFI
427 implementations.
428
429 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
430 @param Token Pointer to the token structure to provide the parameters that are
431 used in this operation.
432
433 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
434 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
435 @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
436 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in
437 the unsupported list of structure EFI_MTFTP4_MODE_DATA.
438 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
439 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
440 RARP, etc.) is not finished yet.
441 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4 session.
442 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
443 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
444 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
445
446 **/
447 typedef
448 EFI_STATUS
449 (EFIAPI *EFI_MTFTP4_READ_DIRECTORY)(
450 IN EFI_MTFTP4_PROTOCOL *This,
451 IN EFI_MTFTP4_TOKEN *Token
452 )
453 ;
454
455 /**
456 Polls for incoming data packets and processes outgoing data packets.
457
458 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
459
460 @retval EFI_SUCCESS Incoming or outgoing data was processed.
461 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
462 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
463 RARP, etc.) is not finished yet.
464 @retval EFI_INVALID_PARAMETER This is NULL.
465 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
466 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
467 Consider increasing the polling rate.
468
469 **/
470 typedef
471 EFI_STATUS
472 (EFIAPI *EFI_MTFTP4_POLL) (
473 IN EFI_MTFTP4_PROTOCOL *This
474 )
475 ;
476
477
478 struct _EFI_MTFTP4_PROTOCOL {
479 EFI_MTFTP4_GET_MODE_DATA GetModeData;
480 EFI_MTFTP4_CONFIGURE Configure;
481 EFI_MTFTP4_GET_INFO GetInfo;
482 EFI_MTFTP4_PARSE_OPTIONS ParseOptions;
483 EFI_MTFTP4_READ_FILE ReadFile;
484 EFI_MTFTP4_WRITE_FILE WriteFile;
485 EFI_MTFTP4_READ_DIRECTORY ReadDirectory;
486 EFI_MTFTP4_POLL Poll;
487 };
488
489 struct _EFI_MTFTP4_TOKEN {
490 OUT EFI_STATUS Status;
491 IN EFI_EVENT Event;
492 IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData;
493 IN UINT8 *Filename;
494 IN UINT8 *ModeStr;
495 IN UINT32 OptionCount;
496 IN EFI_MTFTP4_OPTION *OptionList;
497 IN OUT UINT64 BufferSize;
498 IN OUT VOID *Buffer;
499 IN EFI_MTFTP4_CHECK_PACKET CheckPacket;
500 IN EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;
501 IN EFI_MTFTP4_PACKET_NEEDED PacketNeeded;
502 };
503
504 extern EFI_GUID gEfiMtftp4ServiceBindingProtocolGuid;
505 extern EFI_GUID gEfiMtftp4ProtocolGuid;
506
507 #endif
508