f3a49523601be666d1fac39e043a7f0a7b2f6cee
[mirror_edk2.git] / MdeModulePkg / Universal / Network / Mtftp4Dxe / Mtftp4Impl.c
1 /** @file
2 Interface routine for Mtftp4.
3
4 Copyright (c) 2006 - 2012, Intel Corporation. All rights reserved.<BR>
5 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<BR>
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 **/
14
15
16 #include "Mtftp4Impl.h"
17
18
19 /**
20 Clean up the MTFTP session to get ready for new operation.
21
22 @param Instance The MTFTP session to clean up
23 @param Result The result to return to the caller who initiated
24 the operation.
25 **/
26 VOID
27 Mtftp4CleanOperation (
28 IN OUT MTFTP4_PROTOCOL *Instance,
29 IN EFI_STATUS Result
30 )
31 {
32 LIST_ENTRY *Entry;
33 LIST_ENTRY *Next;
34 MTFTP4_BLOCK_RANGE *Block;
35 EFI_MTFTP4_TOKEN *Token;
36
37 //
38 // Free various resources.
39 //
40 Token = Instance->Token;
41
42 if (Token != NULL) {
43 Token->Status = Result;
44
45 if (Token->Event != NULL) {
46 gBS->SignalEvent (Token->Event);
47 }
48
49 Instance->Token = NULL;
50 }
51
52 ASSERT (Instance->UnicastPort != NULL);
53 UdpIoCleanIo (Instance->UnicastPort);
54
55 if (Instance->LastPacket != NULL) {
56 NetbufFree (Instance->LastPacket);
57 Instance->LastPacket = NULL;
58 }
59
60 if (Instance->McastUdpPort != NULL) {
61 gBS->CloseProtocol (
62 Instance->McastUdpPort->UdpHandle,
63 &gEfiUdp4ProtocolGuid,
64 gMtftp4DriverBinding.DriverBindingHandle,
65 Instance->Handle
66 );
67 UdpIoFreeIo (Instance->McastUdpPort);
68 Instance->McastUdpPort = NULL;
69 }
70
71 NET_LIST_FOR_EACH_SAFE (Entry, Next, &Instance->Blocks) {
72 Block = NET_LIST_USER_STRUCT (Entry, MTFTP4_BLOCK_RANGE, Link);
73 RemoveEntryList (Entry);
74 FreePool (Block);
75 }
76
77 ZeroMem (&Instance->RequestOption, sizeof (MTFTP4_OPTION));
78
79 Instance->Operation = 0;
80
81 Instance->BlkSize = MTFTP4_DEFAULT_BLKSIZE;
82 Instance->LastBlock = 0;
83 Instance->ServerIp = 0;
84 Instance->ListeningPort = 0;
85 Instance->ConnectedPort = 0;
86 Instance->Gateway = 0;
87 Instance->PacketToLive = 0;
88 Instance->MaxRetry = 0;
89 Instance->CurRetry = 0;
90 Instance->Timeout = 0;
91 Instance->McastIp = 0;
92 Instance->McastPort = 0;
93 Instance->Master = TRUE;
94 }
95
96
97 /**
98 Check packet for GetInfo.
99
100 GetInfo is implemented with EfiMtftp4ReadFile. It use Mtftp4GetInfoCheckPacket
101 to inspect the first packet from server, then abort the session.
102
103 @param This The MTFTP4 protocol instance
104 @param Token The user's token
105 @param PacketLen The length of the packet
106 @param Packet The received packet.
107
108 @retval EFI_ABORTED Abort the ReadFile operation and return.
109
110 **/
111 EFI_STATUS
112 EFIAPI
113 Mtftp4GetInfoCheckPacket (
114 IN EFI_MTFTP4_PROTOCOL *This,
115 IN EFI_MTFTP4_TOKEN *Token,
116 IN UINT16 PacketLen,
117 IN EFI_MTFTP4_PACKET *Packet
118 )
119 {
120 MTFTP4_GETINFO_STATE *State;
121 EFI_STATUS Status;
122 UINT16 OpCode;
123
124 State = (MTFTP4_GETINFO_STATE *) Token->Context;
125 OpCode = NTOHS (Packet->OpCode);
126
127 //
128 // Set the GetInfo's return status according to the OpCode.
129 //
130 switch (OpCode) {
131 case EFI_MTFTP4_OPCODE_ERROR:
132 State->Status = EFI_TFTP_ERROR;
133 break;
134
135 case EFI_MTFTP4_OPCODE_OACK:
136 State->Status = EFI_SUCCESS;
137 break;
138
139 default:
140 State->Status = EFI_PROTOCOL_ERROR;
141 }
142
143 //
144 // Allocate buffer then copy the packet over. Use gBS->AllocatePool
145 // in case AllocatePool will implements something tricky.
146 //
147 Status = gBS->AllocatePool (EfiBootServicesData, PacketLen, (VOID **) State->Packet);
148
149 if (EFI_ERROR (Status)) {
150 State->Status = EFI_OUT_OF_RESOURCES;
151 return EFI_ABORTED;
152 }
153
154 *(State->PacketLen) = PacketLen;
155 CopyMem (*(State->Packet), Packet, PacketLen);
156
157 return EFI_ABORTED;
158 }
159
160
161 /**
162 Check whether the override data is valid.
163
164 It will first validate whether the server is a valid unicast. If a gateway
165 is provided in the Override, it also check that it is a unicast on the
166 connected network.
167
168 @param Instance The MTFTP instance
169 @param Override The override data to validate.
170
171 @retval TRUE The override data is valid
172 @retval FALSE The override data is invalid
173
174 **/
175 BOOLEAN
176 Mtftp4OverrideValid (
177 IN MTFTP4_PROTOCOL *Instance,
178 IN EFI_MTFTP4_OVERRIDE_DATA *Override
179 )
180 {
181 EFI_MTFTP4_CONFIG_DATA *Config;
182 IP4_ADDR Ip;
183 IP4_ADDR Netmask;
184 IP4_ADDR Gateway;
185
186 CopyMem (&Ip, &Override->ServerIp, sizeof (IP4_ADDR));
187 if (!NetIp4IsUnicast (NTOHL (Ip), 0)) {
188 return FALSE;
189 }
190
191 Config = &Instance->Config;
192
193 CopyMem (&Gateway, &Override->GatewayIp, sizeof (IP4_ADDR));
194 Gateway = NTOHL (Gateway);
195
196 if (!Config->UseDefaultSetting && (Gateway != 0)) {
197 CopyMem (&Netmask, &Config->SubnetMask, sizeof (IP4_ADDR));
198 CopyMem (&Ip, &Config->StationIp, sizeof (IP4_ADDR));
199
200 Netmask = NTOHL (Netmask);
201 Ip = NTOHL (Ip);
202
203 if (!NetIp4IsUnicast (Gateway, Netmask) || !IP4_NET_EQUAL (Gateway, Ip, Netmask)) {
204 return FALSE;
205 }
206 }
207
208 return TRUE;
209 }
210
211
212 /**
213 Poll the UDP to get the IP4 default address, which may be retrieved
214 by DHCP.
215
216 The default time out value is 5 seconds. If IP has retrieved the default address,
217 the UDP is reconfigured.
218
219 @param Instance The Mtftp instance
220 @param UdpIo The UDP_IO to poll
221 @param UdpCfgData The UDP configure data to reconfigure the UDP_IO
222
223 @retval TRUE The default address is retrieved and UDP is reconfigured.
224 @retval FALSE Some error occured.
225
226 **/
227 BOOLEAN
228 Mtftp4GetMapping (
229 IN MTFTP4_PROTOCOL *Instance,
230 IN UDP_IO *UdpIo,
231 IN EFI_UDP4_CONFIG_DATA *UdpCfgData
232 )
233 {
234 MTFTP4_SERVICE *Service;
235 EFI_IP4_MODE_DATA Ip4Mode;
236 EFI_UDP4_PROTOCOL *Udp;
237 EFI_STATUS Status;
238
239 ASSERT (Instance->Config.UseDefaultSetting);
240
241 Service = Instance->Service;
242 Udp = UdpIo->Protocol.Udp4;
243
244 Status = gBS->SetTimer (
245 Service->TimerToGetMap,
246 TimerRelative,
247 MTFTP4_TIME_TO_GETMAP * TICKS_PER_SECOND
248 );
249 if (EFI_ERROR (Status)) {
250 return FALSE;
251 }
252
253 while (!EFI_ERROR (gBS->CheckEvent (Service->TimerToGetMap))) {
254 Udp->Poll (Udp);
255
256 if (!EFI_ERROR (Udp->GetModeData (Udp, NULL, &Ip4Mode, NULL, NULL)) &&
257 Ip4Mode.IsConfigured) {
258
259 Udp->Configure (Udp, NULL);
260 return (BOOLEAN) (Udp->Configure (Udp, UdpCfgData) == EFI_SUCCESS);
261 }
262 }
263
264 return FALSE;
265 }
266
267
268 /**
269 Configure the UDP port for unicast receiving.
270
271 @param UdpIo The UDP_IO instance
272 @param Instance The MTFTP session
273
274 @retval EFI_SUCCESS The UDP port is successfully configured for the
275 session to unicast receive.
276
277 **/
278 EFI_STATUS
279 Mtftp4ConfigUnicastPort (
280 IN UDP_IO *UdpIo,
281 IN MTFTP4_PROTOCOL *Instance
282 )
283 {
284 EFI_MTFTP4_CONFIG_DATA *Config;
285 EFI_UDP4_CONFIG_DATA UdpConfig;
286 EFI_STATUS Status;
287 IP4_ADDR Ip;
288
289 Config = &Instance->Config;
290
291 UdpConfig.AcceptBroadcast = FALSE;
292 UdpConfig.AcceptPromiscuous = FALSE;
293 UdpConfig.AcceptAnyPort = FALSE;
294 UdpConfig.AllowDuplicatePort = FALSE;
295 UdpConfig.TypeOfService = 0;
296 UdpConfig.TimeToLive = 64;
297 UdpConfig.DoNotFragment = FALSE;
298 UdpConfig.ReceiveTimeout = 0;
299 UdpConfig.TransmitTimeout = 0;
300 UdpConfig.UseDefaultAddress = Config->UseDefaultSetting;
301 UdpConfig.StationAddress = Config->StationIp;
302 UdpConfig.SubnetMask = Config->SubnetMask;
303 UdpConfig.StationPort = 0;
304 UdpConfig.RemotePort = 0;
305
306 Ip = HTONL (Instance->ServerIp);
307 CopyMem (&UdpConfig.RemoteAddress, &Ip, sizeof (EFI_IPv4_ADDRESS));
308
309 Status = UdpIo->Protocol.Udp4->Configure (UdpIo->Protocol.Udp4, &UdpConfig);
310
311 if ((Status == EFI_NO_MAPPING) && Mtftp4GetMapping (Instance, UdpIo, &UdpConfig)) {
312 return EFI_SUCCESS;
313 }
314
315 if (!Config->UseDefaultSetting && !EFI_IP4_EQUAL (&mZeroIp4Addr, &Config->GatewayIp)) {
316 //
317 // The station IP address is manually configured and the Gateway IP is not 0.
318 // Add the default route for this UDP instance.
319 //
320 Status = UdpIo->Protocol.Udp4->Routes (
321 UdpIo->Protocol.Udp4,
322 FALSE,
323 &mZeroIp4Addr,
324 &mZeroIp4Addr,
325 &Config->GatewayIp
326 );
327 if (EFI_ERROR (Status)) {
328 UdpIo->Protocol.Udp4->Configure (UdpIo->Protocol.Udp4, NULL);
329 }
330 }
331 return Status;
332 }
333
334
335 /**
336 Start the MTFTP session to do the operation, such as read file,
337 write file, and read directory.
338
339 @param This The MTFTP session
340 @param Token The token than encapsues the user's request.
341 @param Operation The operation to do
342
343 @retval EFI_INVALID_PARAMETER Some of the parameters are invalid.
344 @retval EFI_NOT_STARTED The MTFTP session hasn't been configured.
345 @retval EFI_ALREADY_STARTED There is pending operation for the session.
346 @retval EFI_SUCCESS The operation is successfully started.
347
348 **/
349 EFI_STATUS
350 Mtftp4Start (
351 IN EFI_MTFTP4_PROTOCOL *This,
352 IN EFI_MTFTP4_TOKEN *Token,
353 IN UINT16 Operation
354 )
355 {
356 MTFTP4_PROTOCOL *Instance;
357 EFI_MTFTP4_OVERRIDE_DATA *Override;
358 EFI_MTFTP4_CONFIG_DATA *Config;
359 EFI_TPL OldTpl;
360 EFI_STATUS Status;
361
362 //
363 // Validate the parameters
364 //
365 if ((This == NULL) || (Token == NULL) || (Token->Filename == NULL) ||
366 ((Token->OptionCount != 0) && (Token->OptionList == NULL))) {
367 return EFI_INVALID_PARAMETER;
368 }
369
370 //
371 // User must provide at least one method to collect the data for download.
372 //
373 if (((Operation == EFI_MTFTP4_OPCODE_RRQ) || (Operation == EFI_MTFTP4_OPCODE_DIR)) &&
374 ((Token->Buffer == NULL) && (Token->CheckPacket == NULL))) {
375 return EFI_INVALID_PARAMETER;
376 }
377
378 //
379 // User must provide at least one method to provide the data for upload.
380 //
381 if ((Operation == EFI_MTFTP4_OPCODE_WRQ) &&
382 ((Token->Buffer == NULL) && (Token->PacketNeeded == NULL))) {
383 return EFI_INVALID_PARAMETER;
384 }
385
386 Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
387
388 Status = EFI_SUCCESS;
389 OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
390
391 if (Instance->State != MTFTP4_STATE_CONFIGED) {
392 Status = EFI_NOT_STARTED;
393 }
394
395 if (Instance->Operation != 0) {
396 Status = EFI_ACCESS_DENIED;
397 }
398
399 if (EFI_ERROR (Status)) {
400 gBS->RestoreTPL (OldTpl);
401 return Status;
402 }
403
404 //
405 // Set the Operation now to prevent the application start other
406 // operations.
407 //
408 Instance->Operation = Operation;
409 Override = Token->OverrideData;
410
411 if ((Override != NULL) && !Mtftp4OverrideValid (Instance, Override)) {
412 Status = EFI_INVALID_PARAMETER;
413 goto ON_ERROR;
414 }
415
416 if (Token->OptionCount != 0) {
417 Status = Mtftp4ParseOption (
418 Token->OptionList,
419 Token->OptionCount,
420 TRUE,
421 &Instance->RequestOption
422 );
423
424 if (EFI_ERROR (Status)) {
425 goto ON_ERROR;
426 }
427 }
428
429 //
430 // Set the operation parameters from the configuration or override data.
431 //
432 Config = &Instance->Config;
433 Instance->Token = Token;
434 Instance->BlkSize = MTFTP4_DEFAULT_BLKSIZE;
435
436 CopyMem (&Instance->ServerIp, &Config->ServerIp, sizeof (IP4_ADDR));
437 Instance->ServerIp = NTOHL (Instance->ServerIp);
438
439 Instance->ListeningPort = Config->InitialServerPort;
440 Instance->ConnectedPort = 0;
441
442 CopyMem (&Instance->Gateway, &Config->GatewayIp, sizeof (IP4_ADDR));
443 Instance->Gateway = NTOHL (Instance->Gateway);
444
445 Instance->MaxRetry = Config->TryCount;
446 Instance->Timeout = Config->TimeoutValue;
447 Instance->Master = TRUE;
448
449 if (Override != NULL) {
450 CopyMem (&Instance->ServerIp, &Override->ServerIp, sizeof (IP4_ADDR));
451 CopyMem (&Instance->Gateway, &Override->GatewayIp, sizeof (IP4_ADDR));
452
453 Instance->ServerIp = NTOHL (Instance->ServerIp);
454 Instance->Gateway = NTOHL (Instance->Gateway);
455
456 Instance->ListeningPort = Override->ServerPort;
457 Instance->MaxRetry = Override->TryCount;
458 Instance->Timeout = Override->TimeoutValue;
459 }
460
461 if (Instance->ListeningPort == 0) {
462 Instance->ListeningPort = MTFTP4_DEFAULT_SERVER_PORT;
463 }
464
465 if (Instance->MaxRetry == 0) {
466 Instance->MaxRetry = MTFTP4_DEFAULT_RETRY;
467 }
468
469 if (Instance->Timeout == 0) {
470 Instance->Timeout = MTFTP4_DEFAULT_TIMEOUT;
471 }
472
473 //
474 // Config the unicast UDP child to send initial request
475 //
476 Status = Mtftp4ConfigUnicastPort (Instance->UnicastPort, Instance);
477
478 if (EFI_ERROR (Status)) {
479 goto ON_ERROR;
480 }
481
482 //
483 // Set initial status.
484 //
485 Token->Status = EFI_NOT_READY;
486
487 //
488 // Build and send an initial requests
489 //
490 if (Operation == EFI_MTFTP4_OPCODE_WRQ) {
491 Status = Mtftp4WrqStart (Instance, Operation);
492 } else {
493 Status = Mtftp4RrqStart (Instance, Operation);
494 }
495
496 gBS->RestoreTPL (OldTpl);
497
498 if (EFI_ERROR (Status)) {
499 goto ON_ERROR;
500 }
501
502 if (Token->Event != NULL) {
503 return EFI_SUCCESS;
504 }
505
506 //
507 // Return immediately for asynchronous operation or poll the
508 // instance for synchronous operation.
509 //
510 while (Token->Status == EFI_NOT_READY) {
511 This->Poll (This);
512 }
513
514 return Token->Status;
515
516 ON_ERROR:
517 Mtftp4CleanOperation (Instance, Status);
518 gBS->RestoreTPL (OldTpl);
519
520 return Status;
521 }
522
523
524 /**
525 Reads the current operational settings.
526
527 The GetModeData()function reads the current operational settings of this
528 EFI MTFTPv4 Protocol driver instance.
529
530 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
531 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol
532 driver mode data.
533
534 @retval EFI_SUCCESS The configuration data was successfully returned.
535 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
536 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
537
538 **/
539 EFI_STATUS
540 EFIAPI
541 EfiMtftp4GetModeData (
542 IN EFI_MTFTP4_PROTOCOL *This,
543 OUT EFI_MTFTP4_MODE_DATA *ModeData
544 )
545 {
546 MTFTP4_PROTOCOL *Instance;
547 EFI_TPL OldTpl;
548
549 if ((This == NULL) || (ModeData == NULL)) {
550 return EFI_INVALID_PARAMETER;
551 }
552
553 OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
554
555 Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
556 CopyMem(&ModeData->ConfigData, &Instance->Config, sizeof (Instance->Config));
557 ModeData->SupportedOptionCount = MTFTP4_SUPPORTED_OPTIONS;
558 ModeData->SupportedOptoins = (UINT8 **) mMtftp4SupportedOptions;
559 ModeData->UnsupportedOptionCount = 0;
560 ModeData->UnsupportedOptoins = NULL;
561
562 gBS->RestoreTPL (OldTpl);
563
564 return EFI_SUCCESS;
565 }
566
567
568
569 /**
570 Initializes, changes, or resets the default operational setting for this
571 EFI MTFTPv4 Protocol driver instance.
572
573 The Configure() function is used to set and change the configuration data for
574 this EFI MTFTPv4 Protocol driver instance. The configuration data can be reset
575 to startup defaults by calling Configure() with MtftpConfigData set to NULL.
576 Whenever the instance is reset, any pending operation is aborted. By changing
577 the EFI MTFTPv4 Protocol driver instance configuration data, the client can
578 connect to different MTFTPv4 servers. The configuration parameters in
579 MtftpConfigData are used as the default parameters in later MTFTPv4 operations
580 and can be overridden in later operations.
581
582 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
583 @param ConfigData MtftpConfigDataPointer to the configuration data
584 structure
585
586 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured
587 successfully.
588 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
589 1.This is NULL.
590 2.MtftpConfigData.UseDefaultSetting is FALSE and
591 MtftpConfigData.StationIp is not a valid IPv4
592 unicast address.
593 3.MtftpCofigData.UseDefaultSetting is FALSE and
594 MtftpConfigData.SubnetMask is invalid.
595 4.MtftpCofigData.ServerIp is not a valid IPv4
596 unicast address.
597 5.MtftpConfigData.UseDefaultSetting is FALSE and
598 MtftpConfigData.GatewayIp is not a valid IPv4
599 unicast address or is not in the same subnet
600 with station address.
601 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this
602 time because there is one MTFTP background operation
603 in progress.
604 @retval EFI_NO_MAPPING When using a default address, configuration
605 (DHCP, BOOTP, RARP, etc.) has not finished yet.
606 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.)
607 could not be located when clients choose to use
608 the default address settings.
609 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could
610 not be allocated.
611 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
612 The EFI MTFTPv4 Protocol driver instance is not
613 configured.
614
615 **/
616 EFI_STATUS
617 EFIAPI
618 EfiMtftp4Configure (
619 IN EFI_MTFTP4_PROTOCOL *This,
620 IN EFI_MTFTP4_CONFIG_DATA *ConfigData
621 )
622 {
623 MTFTP4_PROTOCOL *Instance;
624 EFI_TPL OldTpl;
625 IP4_ADDR Ip;
626 IP4_ADDR Netmask;
627 IP4_ADDR Gateway;
628 IP4_ADDR ServerIp;
629
630 if (This == NULL) {
631 return EFI_INVALID_PARAMETER;
632 }
633
634 Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
635
636 if (ConfigData == NULL) {
637 //
638 // Reset the operation if ConfigData is NULL
639 //
640 OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
641
642 Mtftp4CleanOperation (Instance, EFI_ABORTED);
643 ZeroMem (&Instance->Config, sizeof (EFI_MTFTP4_CONFIG_DATA));
644 Instance->State = MTFTP4_STATE_UNCONFIGED;
645
646 gBS->RestoreTPL (OldTpl);
647
648 } else {
649 //
650 // Configure the parameters for new operation.
651 //
652 CopyMem (&Ip, &ConfigData->StationIp, sizeof (IP4_ADDR));
653 CopyMem (&Netmask, &ConfigData->SubnetMask, sizeof (IP4_ADDR));
654 CopyMem (&Gateway, &ConfigData->GatewayIp, sizeof (IP4_ADDR));
655 CopyMem (&ServerIp, &ConfigData->ServerIp, sizeof (IP4_ADDR));
656
657 Ip = NTOHL (Ip);
658 Netmask = NTOHL (Netmask);
659 Gateway = NTOHL (Gateway);
660 ServerIp = NTOHL (ServerIp);
661
662 if (!NetIp4IsUnicast (ServerIp, 0)) {
663 return EFI_INVALID_PARAMETER;
664 }
665
666 if (!ConfigData->UseDefaultSetting &&
667 ((!IP4_IS_VALID_NETMASK (Netmask) || !NetIp4IsUnicast (Ip, Netmask)))) {
668
669 return EFI_INVALID_PARAMETER;
670 }
671
672 if ((Gateway != 0) &&
673 (!IP4_NET_EQUAL (Gateway, Ip, Netmask) || !NetIp4IsUnicast (Gateway, Netmask))) {
674
675 return EFI_INVALID_PARAMETER;
676 }
677
678 OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
679
680 if ((Instance->State == MTFTP4_STATE_CONFIGED) && (Instance->Operation != 0)) {
681 gBS->RestoreTPL (OldTpl);
682 return EFI_ACCESS_DENIED;
683 }
684
685 CopyMem(&Instance->Config, ConfigData, sizeof (*ConfigData));;
686 Instance->State = MTFTP4_STATE_CONFIGED;
687
688 gBS->RestoreTPL (OldTpl);
689 }
690
691 return EFI_SUCCESS;
692 }
693
694
695
696 /**
697 Parses the options in an MTFTPv4 OACK packet.
698
699 The ParseOptions() function parses the option fields in an MTFTPv4 OACK packet
700 and returns the number of options that were found and optionally a list of
701 pointers to the options in the packet.
702 If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is
703 returned and *OptionCount and *OptionList stop at the last valid option.
704 The OptionList is allocated by this function, and caller should free it when used.
705
706 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
707 @param PacketLen Length of the OACK packet to be parsed.
708 @param Packet Pointer to the OACK packet to be parsed.
709 @param OptionCount Pointer to the number of options in following OptionList.
710 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the
711 EFI Boot Service FreePool() to release theOptionList
712 if the options in this OptionList are not needed
713 any more
714
715 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
716 OptionList parameters have been updated.
717 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
718 1.PacketLen is 0.
719 2.Packet is NULL or Packet is not a valid MTFTPv4 packet.
720 3.OptionCount is NULL.
721 @retval EFI_NOT_FOUND No options were found in the OACK packet.
722 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
723 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
724
725 **/
726 EFI_STATUS
727 EFIAPI
728 EfiMtftp4ParseOptions (
729 IN EFI_MTFTP4_PROTOCOL *This,
730 IN UINT32 PacketLen,
731 IN EFI_MTFTP4_PACKET *Packet,
732 OUT UINT32 *OptionCount,
733 OUT EFI_MTFTP4_OPTION **OptionList OPTIONAL
734 )
735 {
736 EFI_STATUS Status;
737
738 if ((This == NULL) || (PacketLen < MTFTP4_OPCODE_LEN) ||
739 (Packet == NULL) || (OptionCount == NULL)) {
740
741 return EFI_INVALID_PARAMETER;
742 }
743
744 Status = Mtftp4ExtractOptions (Packet, PacketLen, OptionCount, OptionList);
745
746 if (EFI_ERROR (Status)) {
747 return Status;
748 }
749
750 if (*OptionCount == 0) {
751 return EFI_NOT_FOUND;
752 }
753
754 return EFI_SUCCESS;
755 }
756
757
758 /**
759 Downloads a file from an MTFTPv4 server.
760
761 The ReadFile() function is used to initialize and start an MTFTPv4 download
762 process and optionally wait for completion. When the download operation completes,
763 whether successfully or not, the Token.Status field is updated by the EFI MTFTPv4
764 Protocol driver and then Token.Event is signaled (if it is not NULL).
765 Data can be downloaded from the MTFTPv4 server into either of the following locations:
766 1.A fixed buffer that is pointed to by Token.Buffer
767 2.A download service function that is pointed to by Token.CheckPacket
768 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
769 will be called first. If the call is successful, the packet will be stored in
770 Token.Buffer.
771
772 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
773 @param Token Pointer to the token structure to provide the
774 parameters that are used in this operation.
775
776 @retval EFI_SUCCESS The data file has been transferred successfully.
777 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
778 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded
779 data in downloading process.
780 @retval EFI_ABORTED Current operation is aborted by user.
781 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
782 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
783 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
784 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
785 @retval EFI_NO_MEDIA There was a media error.
786
787 **/
788 EFI_STATUS
789 EFIAPI
790 EfiMtftp4ReadFile (
791 IN EFI_MTFTP4_PROTOCOL *This,
792 IN EFI_MTFTP4_TOKEN *Token
793 )
794 {
795 return Mtftp4Start (This, Token, EFI_MTFTP4_OPCODE_RRQ);
796 }
797
798
799 /**
800 Sends a data file to an MTFTPv4 server. May be unsupported in some EFI implementations
801
802 The WriteFile() function is used to initialize an uploading operation with the
803 given option list and optionally wait for completion. If one or more of the
804 options is not supported by the server, the unsupported options are ignored and
805 a standard TFTP process starts instead. When the upload process completes,
806 whether successfully or not, Token.Event is signaled, and the EFI MTFTPv4 Protocol
807 driver updates Token.Status.
808 The caller can supply the data to be uploaded in the following two modes:
809 1.Through the user-provided buffer
810 2.Through a callback function
811 With the user-provided buffer, the Token.BufferSize field indicates the length
812 of the buffer, and the driver will upload the data in the buffer. With an
813 EFI_MTFTP4_PACKET_NEEDED callback function, the driver will call this callback
814 function to get more data from the user to upload. See the definition of
815 EFI_MTFTP4_PACKET_NEEDED for more information. These two modes cannot be used at
816 the same time. The callback function will be ignored if the user provides the buffer.
817
818 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
819 @param Token Pointer to the token structure to provide the
820 parameters that are used in this function
821
822 @retval EFI_SUCCESS The upload session has started.
823 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
824 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
825 1. This is NULL.
826 2. Token is NULL.
827 3. Token.Filename is NULL.
828 4. Token.OptionCount is not zero and
829 Token.OptionList is NULL.
830 5. One or more options in Token.OptionList have wrong
831 format.
832 6. Token.Buffer and Token.PacketNeeded are both
833 NULL.
834 7. One or more IPv4 addresses in Token.OverrideData
835 are not valid unicast IPv4 addresses if
836 Token.OverrideData is not NULL.
837 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
838 unsupported list of structure EFI_MTFTP4_MODE_DATA.
839 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
840 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
841 BOOTP, RARP, etc.) is not finished yet.
842 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
843 session.
844 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
845 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
846 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
847
848 **/
849 EFI_STATUS
850 EFIAPI
851 EfiMtftp4WriteFile (
852 IN EFI_MTFTP4_PROTOCOL *This,
853 IN EFI_MTFTP4_TOKEN *Token
854 )
855 {
856 return Mtftp4Start (This, Token, EFI_MTFTP4_OPCODE_WRQ);
857 }
858
859
860 /**
861 Downloads a data file "directory" from an MTFTPv4 server.
862 May be unsupported in some EFI implementations
863
864 The ReadDirectory() function is used to return a list of files on the MTFTPv4
865 server that are logically (or operationally) related to Token.Filename. The
866 directory request packet that is sent to the server is built with the option
867 list that was provided by caller, if present.
868 The file information that the server returns is put into either of the following
869 locations:
870 1.A fixed buffer that is pointed to by Token.Buffer
871 2.A download service function that is pointed to by Token.CheckPacket
872 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket will
873 be called first. If the call is successful, the packet will be stored in Token.Buffer.
874 The returned directory listing in the Token.Buffer or EFI_MTFTP4_PACKET consists
875 of a list of two or three variable-length ASCII strings, each terminated by a
876 null character, for each file in the directory. If the multicast option is involved,
877 the first field of each directory entry is the static multicast IP address and
878 UDP port number that is associated with the file name. The format of the field
879 is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its
880 terminating null character are not present.
881 The next field of each directory entry is the file name and the last field is
882 the file information string. The information string contains the file size and
883 the create/modify timestamp. The format of the information string is filesize
884 yyyy-mm-dd hh:mm:ss:ffff. The timestamp is Coordinated Universal Time
885 (UTC; also known as Greenwich Mean Time [GMT]).
886 The only difference between ReadFile and ReadDirectory is the opcode used.
887
888 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
889 @param Token Pointer to the token structure to provide the
890 parameters that are used in this function
891
892 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
893 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
894 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
895 1. This is NULL.
896 2. Token is NULL.
897 3. Token.Filename is NULL.
898 4. Token.OptionCount is not zero and
899 Token.OptionList is NULL.
900 5. One or more options in Token.OptionList have wrong
901 format.
902 6. Token.Buffer and Token.PacketNeeded are both
903 NULL.
904 7. One or more IPv4 addresses in Token.OverrideData
905 are not valid unicast IPv4 addresses if
906 Token.OverrideData is not NULL.
907 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
908 unsupported list of structure EFI_MTFTP4_MODE_DATA.
909 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
910 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
911 BOOTP, RARP, etc.) is not finished yet.
912 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
913 session.
914 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
915 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
916 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
917
918 **/
919 EFI_STATUS
920 EFIAPI
921 EfiMtftp4ReadDirectory (
922 IN EFI_MTFTP4_PROTOCOL *This,
923 IN EFI_MTFTP4_TOKEN *Token
924 )
925 {
926 return Mtftp4Start (This, Token, EFI_MTFTP4_OPCODE_DIR);
927 }
928
929
930 /**
931 Gets information about a file from an MTFTPv4 server.
932
933 The GetInfo() function assembles an MTFTPv4 request packet with options;
934 sends it to the MTFTPv4 server; and may return an MTFTPv4 OACK, MTFTPv4 ERROR,
935 or ICMP ERROR packet. Retries occur only if no response packets are received
936 from the MTFTPv4 server before the timeout expires.
937 It is implemented with EfiMtftp4ReadFile: build a token, then pass it to
938 EfiMtftp4ReadFile. In its check packet callback abort the opertions.
939
940 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
941 @param OverrideData Data that is used to override the existing
942 parameters. If NULL, the default parameters that
943 were set in the EFI_MTFTP4_PROTOCOL.Configure()
944 function are used
945 @param Filename Pointer to null-terminated ASCII file name string
946 @param ModeStr Pointer to null-terminated ASCII mode string. If NULL, "octet"
947 will be used
948 @param OptionCount Number of option/value string pairs in OptionList
949 @param OptionList Pointer to array of option/value string pairs.
950 Ignored if OptionCount is zero
951 @param PacketLength The number of bytes in the returned packet
952 @param Packet PacketThe pointer to the received packet. This
953 buffer must be freed by the caller.
954
955 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in
956 the Buffer.
957 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
958 1.This is NULL.
959 2.Filename is NULL.
960 3.OptionCount is not zero and OptionList is NULL.
961 4.One or more options in OptionList have wrong format.
962 5.PacketLength is NULL.
963 6.One or more IPv4 addresses in OverrideData are
964 not valid unicast IPv4 addresses if OverrideData
965 is not NULL.
966 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
967 unsupported list of structure EFI_MTFTP4_MODE_DATA
968 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
969 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
970 BOOTP, RARP, etc.) has not finished yet.
971 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
972 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
973 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in
974 the Buffer.
975 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and the Packet
976 is set to NULL.
977 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is
978 in the Buffer.
979 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
980 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
981 @retval EFI_NO_MEDIA There was a media error.
982
983 **/
984 EFI_STATUS
985 EFIAPI
986 EfiMtftp4GetInfo (
987 IN EFI_MTFTP4_PROTOCOL *This,
988 IN EFI_MTFTP4_OVERRIDE_DATA *OverrideData OPTIONAL,
989 IN UINT8 *Filename,
990 IN UINT8 *ModeStr OPTIONAL,
991 IN UINT8 OptionCount,
992 IN EFI_MTFTP4_OPTION *OptionList OPTIONAL,
993 OUT UINT32 *PacketLength,
994 OUT EFI_MTFTP4_PACKET **Packet OPTIONAL
995 )
996 {
997 EFI_MTFTP4_TOKEN Token;
998 MTFTP4_GETINFO_STATE State;
999 EFI_STATUS Status;
1000
1001 if ((This == NULL) || (Filename == NULL) || (PacketLength == NULL) ||
1002 ((OptionCount != 0) && (OptionList == NULL))) {
1003 return EFI_INVALID_PARAMETER;
1004 }
1005
1006 if (Packet != NULL) {
1007 *Packet = NULL;
1008 }
1009
1010 *PacketLength = 0;
1011 State.Packet = Packet;
1012 State.PacketLen = PacketLength;
1013 State.Status = EFI_SUCCESS;
1014
1015 //
1016 // Fill in the Token to issue an synchronous ReadFile operation
1017 //
1018 Token.Status = EFI_SUCCESS;
1019 Token.Event = NULL;
1020 Token.OverrideData = OverrideData;
1021 Token.Filename = Filename;
1022 Token.ModeStr = ModeStr;
1023 Token.OptionCount = OptionCount;
1024 Token.OptionList = OptionList;
1025 Token.BufferSize = 0;
1026 Token.Buffer = NULL;
1027 Token.Context = &State;
1028 Token.CheckPacket = Mtftp4GetInfoCheckPacket;
1029 Token.TimeoutCallback = NULL;
1030 Token.PacketNeeded = NULL;
1031
1032 Status = EfiMtftp4ReadFile (This, &Token);
1033
1034 if (EFI_ABORTED == Status) {
1035 return State.Status;
1036 }
1037
1038 return Status;
1039 }
1040
1041 /**
1042 Polls for incoming data packets and processes outgoing data packets.
1043
1044 The Poll() function can be used by network drivers and applications to increase
1045 the rate that data packets are moved between the communications device and the
1046 transmit and receive queues.
1047 In some systems, the periodic timer event in the managed network driver may not
1048 poll the underlying communications device fast enough to transmit and/or receive
1049 all data packets without missing incoming packets or dropping outgoing packets.
1050 Drivers and applications that are experiencing packet loss should try calling
1051 the Poll() function more often.
1052
1053 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
1054
1055 @retval EFI_SUCCESS Incoming or outgoing data was processed.
1056 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
1057 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
1058 BOOTP, RARP, etc.) is not finished yet.
1059 @retval EFI_INVALID_PARAMETER This is NULL.
1060 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
1061 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
1062 queue. Consider increasing the polling rate.
1063
1064 **/
1065 EFI_STATUS
1066 EFIAPI
1067 EfiMtftp4Poll (
1068 IN EFI_MTFTP4_PROTOCOL *This
1069 )
1070 {
1071 MTFTP4_PROTOCOL *Instance;
1072 EFI_UDP4_PROTOCOL *Udp;
1073
1074 if (This == NULL) {
1075 return EFI_INVALID_PARAMETER;
1076 }
1077
1078 Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
1079
1080 if (Instance->State == MTFTP4_STATE_UNCONFIGED) {
1081 return EFI_NOT_STARTED;
1082 } else if (Instance->State == MTFTP4_STATE_DESTROY) {
1083 return EFI_DEVICE_ERROR;
1084 }
1085
1086 Udp = Instance->UnicastPort->Protocol.Udp4;
1087 return Udp->Poll (Udp);
1088 }
1089
1090 EFI_MTFTP4_PROTOCOL gMtftp4ProtocolTemplate = {
1091 EfiMtftp4GetModeData,
1092 EfiMtftp4Configure,
1093 EfiMtftp4GetInfo,
1094 EfiMtftp4ParseOptions,
1095 EfiMtftp4ReadFile,
1096 EfiMtftp4WriteFile,
1097 EfiMtftp4ReadDirectory,
1098 EfiMtftp4Poll
1099 };