2 Interface routine for Mtftp4.
4 (C) Copyright 2014 Hewlett-Packard Development Company, L.P.<BR>
5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php<BR>
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 #include "Mtftp4Impl.h"
21 Clean up the MTFTP session to get ready for new operation.
23 @param Instance The MTFTP session to clean up
24 @param Result The result to return to the caller who initiated
28 Mtftp4CleanOperation (
29 IN OUT MTFTP4_PROTOCOL
*Instance
,
35 MTFTP4_BLOCK_RANGE
*Block
;
36 EFI_MTFTP4_TOKEN
*Token
;
39 // Free various resources.
41 Token
= Instance
->Token
;
44 Token
->Status
= Result
;
46 if (Token
->Event
!= NULL
) {
47 gBS
->SignalEvent (Token
->Event
);
50 Instance
->Token
= NULL
;
53 ASSERT (Instance
->UnicastPort
!= NULL
);
54 UdpIoCleanIo (Instance
->UnicastPort
);
56 if (Instance
->LastPacket
!= NULL
) {
57 NetbufFree (Instance
->LastPacket
);
58 Instance
->LastPacket
= NULL
;
61 if (Instance
->McastUdpPort
!= NULL
) {
63 Instance
->McastUdpPort
->UdpHandle
,
64 &gEfiUdp4ProtocolGuid
,
65 gMtftp4DriverBinding
.DriverBindingHandle
,
68 UdpIoFreeIo (Instance
->McastUdpPort
);
69 Instance
->McastUdpPort
= NULL
;
72 NET_LIST_FOR_EACH_SAFE (Entry
, Next
, &Instance
->Blocks
) {
73 Block
= NET_LIST_USER_STRUCT (Entry
, MTFTP4_BLOCK_RANGE
, Link
);
74 RemoveEntryList (Entry
);
78 ZeroMem (&Instance
->RequestOption
, sizeof (MTFTP4_OPTION
));
80 Instance
->Operation
= 0;
82 Instance
->BlkSize
= MTFTP4_DEFAULT_BLKSIZE
;
83 Instance
->LastBlock
= 0;
84 Instance
->ServerIp
= 0;
85 Instance
->ListeningPort
= 0;
86 Instance
->ConnectedPort
= 0;
87 Instance
->Gateway
= 0;
88 Instance
->PacketToLive
= 0;
89 Instance
->MaxRetry
= 0;
90 Instance
->CurRetry
= 0;
91 Instance
->Timeout
= 0;
92 Instance
->McastIp
= 0;
93 Instance
->McastPort
= 0;
94 Instance
->Master
= TRUE
;
99 Check packet for GetInfo.
101 GetInfo is implemented with EfiMtftp4ReadFile. It use Mtftp4GetInfoCheckPacket
102 to inspect the first packet from server, then abort the session.
104 @param This The MTFTP4 protocol instance
105 @param Token The user's token
106 @param PacketLen The length of the packet
107 @param Packet The received packet.
109 @retval EFI_ABORTED Abort the ReadFile operation and return.
114 Mtftp4GetInfoCheckPacket (
115 IN EFI_MTFTP4_PROTOCOL
*This
,
116 IN EFI_MTFTP4_TOKEN
*Token
,
118 IN EFI_MTFTP4_PACKET
*Packet
121 MTFTP4_GETINFO_STATE
*State
;
124 EFI_MTFTP4_ERROR_HEADER
*ErrorHeader
;
126 State
= (MTFTP4_GETINFO_STATE
*) Token
->Context
;
127 OpCode
= NTOHS (Packet
->OpCode
);
130 // Set the GetInfo's return status according to the OpCode.
133 case EFI_MTFTP4_OPCODE_ERROR
:
134 ErrorHeader
= (EFI_MTFTP4_ERROR_HEADER
*) Packet
;
135 if (ErrorHeader
->ErrorCode
== EFI_MTFTP4_ERRORCODE_FILE_NOT_FOUND
) {
136 DEBUG ((EFI_D_ERROR
, "TFTP error code 1 (File Not Found)\n"));
138 DEBUG ((EFI_D_ERROR
, "TFTP error code %d\n", ErrorHeader
->ErrorCode
));
140 State
->Status
= EFI_TFTP_ERROR
;
143 case EFI_MTFTP4_OPCODE_OACK
:
144 State
->Status
= EFI_SUCCESS
;
148 State
->Status
= EFI_PROTOCOL_ERROR
;
152 // Allocate buffer then copy the packet over. Use gBS->AllocatePool
153 // in case AllocatePool will implements something tricky.
155 Status
= gBS
->AllocatePool (EfiBootServicesData
, PacketLen
, (VOID
**) State
->Packet
);
157 if (EFI_ERROR (Status
)) {
158 State
->Status
= EFI_OUT_OF_RESOURCES
;
162 *(State
->PacketLen
) = PacketLen
;
163 CopyMem (*(State
->Packet
), Packet
, PacketLen
);
170 Check whether the override data is valid.
172 It will first validate whether the server is a valid unicast. If a gateway
173 is provided in the Override, it also check that it is a unicast on the
176 @param Instance The MTFTP instance
177 @param Override The override data to validate.
179 @retval TRUE The override data is valid
180 @retval FALSE The override data is invalid
184 Mtftp4OverrideValid (
185 IN MTFTP4_PROTOCOL
*Instance
,
186 IN EFI_MTFTP4_OVERRIDE_DATA
*Override
189 EFI_MTFTP4_CONFIG_DATA
*Config
;
194 CopyMem (&Ip
, &Override
->ServerIp
, sizeof (IP4_ADDR
));
195 if (IP4_IS_UNSPECIFIED (NTOHL (Ip
)) || IP4_IS_LOCAL_BROADCAST (NTOHL (Ip
))) {
199 Config
= &Instance
->Config
;
201 CopyMem (&Gateway
, &Override
->GatewayIp
, sizeof (IP4_ADDR
));
202 Gateway
= NTOHL (Gateway
);
204 if (!Config
->UseDefaultSetting
&& (Gateway
!= 0)) {
205 CopyMem (&Netmask
, &Config
->SubnetMask
, sizeof (IP4_ADDR
));
206 CopyMem (&Ip
, &Config
->StationIp
, sizeof (IP4_ADDR
));
208 Netmask
= NTOHL (Netmask
);
211 if ((Netmask
!= 0 && !NetIp4IsUnicast (Gateway
, Netmask
)) || !IP4_NET_EQUAL (Gateway
, Ip
, Netmask
)) {
221 Poll the UDP to get the IP4 default address, which may be retrieved
224 The default time out value is 5 seconds. If IP has retrieved the default address,
225 the UDP is reconfigured.
227 @param Instance The Mtftp instance
228 @param UdpIo The UDP_IO to poll
229 @param UdpCfgData The UDP configure data to reconfigure the UDP_IO
231 @retval TRUE The default address is retrieved and UDP is reconfigured.
232 @retval FALSE Some error occured.
237 IN MTFTP4_PROTOCOL
*Instance
,
239 IN EFI_UDP4_CONFIG_DATA
*UdpCfgData
242 MTFTP4_SERVICE
*Service
;
243 EFI_IP4_MODE_DATA Ip4Mode
;
244 EFI_UDP4_PROTOCOL
*Udp
;
247 ASSERT (Instance
->Config
.UseDefaultSetting
);
249 Service
= Instance
->Service
;
250 Udp
= UdpIo
->Protocol
.Udp4
;
252 Status
= gBS
->SetTimer (
253 Service
->TimerToGetMap
,
255 MTFTP4_TIME_TO_GETMAP
* TICKS_PER_SECOND
257 if (EFI_ERROR (Status
)) {
261 while (EFI_ERROR (gBS
->CheckEvent (Service
->TimerToGetMap
))) {
264 if (!EFI_ERROR (Udp
->GetModeData (Udp
, NULL
, &Ip4Mode
, NULL
, NULL
)) &&
265 Ip4Mode
.IsConfigured
) {
267 Udp
->Configure (Udp
, NULL
);
268 return (BOOLEAN
) (Udp
->Configure (Udp
, UdpCfgData
) == EFI_SUCCESS
);
277 Configure the UDP port for unicast receiving.
279 @param UdpIo The UDP_IO instance
280 @param Instance The MTFTP session
282 @retval EFI_SUCCESS The UDP port is successfully configured for the
283 session to unicast receive.
287 Mtftp4ConfigUnicastPort (
289 IN MTFTP4_PROTOCOL
*Instance
292 EFI_MTFTP4_CONFIG_DATA
*Config
;
293 EFI_UDP4_CONFIG_DATA UdpConfig
;
297 Config
= &Instance
->Config
;
299 UdpConfig
.AcceptBroadcast
= FALSE
;
300 UdpConfig
.AcceptPromiscuous
= FALSE
;
301 UdpConfig
.AcceptAnyPort
= FALSE
;
302 UdpConfig
.AllowDuplicatePort
= FALSE
;
303 UdpConfig
.TypeOfService
= 0;
304 UdpConfig
.TimeToLive
= 64;
305 UdpConfig
.DoNotFragment
= FALSE
;
306 UdpConfig
.ReceiveTimeout
= 0;
307 UdpConfig
.TransmitTimeout
= 0;
308 UdpConfig
.UseDefaultAddress
= Config
->UseDefaultSetting
;
309 IP4_COPY_ADDRESS (&UdpConfig
.StationAddress
, &Config
->StationIp
);
310 IP4_COPY_ADDRESS (&UdpConfig
.SubnetMask
, &Config
->SubnetMask
);
311 UdpConfig
.StationPort
= 0;
312 UdpConfig
.RemotePort
= 0;
314 Ip
= HTONL (Instance
->ServerIp
);
315 IP4_COPY_ADDRESS (&UdpConfig
.RemoteAddress
, &Ip
);
317 Status
= UdpIo
->Protocol
.Udp4
->Configure (UdpIo
->Protocol
.Udp4
, &UdpConfig
);
319 if ((Status
== EFI_NO_MAPPING
) && Mtftp4GetMapping (Instance
, UdpIo
, &UdpConfig
)) {
323 if (!Config
->UseDefaultSetting
&& !EFI_IP4_EQUAL (&mZeroIp4Addr
, &Config
->GatewayIp
)) {
325 // The station IP address is manually configured and the Gateway IP is not 0.
326 // Add the default route for this UDP instance.
328 Status
= UdpIo
->Protocol
.Udp4
->Routes (
329 UdpIo
->Protocol
.Udp4
,
335 if (EFI_ERROR (Status
)) {
336 UdpIo
->Protocol
.Udp4
->Configure (UdpIo
->Protocol
.Udp4
, NULL
);
344 Start the MTFTP session to do the operation, such as read file,
345 write file, and read directory.
347 @param This The MTFTP session
348 @param Token The token than encapsues the user's request.
349 @param Operation The operation to do
351 @retval EFI_INVALID_PARAMETER Some of the parameters are invalid.
352 @retval EFI_NOT_STARTED The MTFTP session hasn't been configured.
353 @retval EFI_ALREADY_STARTED There is pending operation for the session.
354 @retval EFI_SUCCESS The operation is successfully started.
359 IN EFI_MTFTP4_PROTOCOL
*This
,
360 IN EFI_MTFTP4_TOKEN
*Token
,
364 MTFTP4_PROTOCOL
*Instance
;
365 EFI_MTFTP4_OVERRIDE_DATA
*Override
;
366 EFI_MTFTP4_CONFIG_DATA
*Config
;
371 // Validate the parameters
373 if ((This
== NULL
) || (Token
== NULL
) || (Token
->Filename
== NULL
) ||
374 ((Token
->OptionCount
!= 0) && (Token
->OptionList
== NULL
))) {
375 return EFI_INVALID_PARAMETER
;
379 // User must provide at least one method to collect the data for download.
381 if (((Operation
== EFI_MTFTP4_OPCODE_RRQ
) || (Operation
== EFI_MTFTP4_OPCODE_DIR
)) &&
382 ((Token
->Buffer
== NULL
) && (Token
->CheckPacket
== NULL
))) {
383 return EFI_INVALID_PARAMETER
;
387 // User must provide at least one method to provide the data for upload.
389 if ((Operation
== EFI_MTFTP4_OPCODE_WRQ
) &&
390 ((Token
->Buffer
== NULL
) && (Token
->PacketNeeded
== NULL
))) {
391 return EFI_INVALID_PARAMETER
;
394 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
396 Status
= EFI_SUCCESS
;
397 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
399 if (Instance
->State
!= MTFTP4_STATE_CONFIGED
) {
400 Status
= EFI_NOT_STARTED
;
403 if (Instance
->Operation
!= 0) {
404 Status
= EFI_ACCESS_DENIED
;
407 if (EFI_ERROR (Status
)) {
408 gBS
->RestoreTPL (OldTpl
);
412 if ((Token
->OverrideData
!= NULL
) && !Mtftp4OverrideValid (Instance
, Token
->OverrideData
)) {
413 Status
= EFI_INVALID_PARAMETER
;
414 gBS
->RestoreTPL (OldTpl
);
419 // Set the Operation now to prevent the application start other
422 Instance
->Operation
= Operation
;
423 Override
= Token
->OverrideData
;
425 if (Token
->OptionCount
!= 0) {
426 Status
= Mtftp4ParseOption (
430 &Instance
->RequestOption
433 if (EFI_ERROR (Status
)) {
434 Status
= EFI_DEVICE_ERROR
;
440 // Set the operation parameters from the configuration or override data.
442 Config
= &Instance
->Config
;
443 Instance
->Token
= Token
;
444 Instance
->BlkSize
= MTFTP4_DEFAULT_BLKSIZE
;
446 CopyMem (&Instance
->ServerIp
, &Config
->ServerIp
, sizeof (IP4_ADDR
));
447 Instance
->ServerIp
= NTOHL (Instance
->ServerIp
);
449 Instance
->ListeningPort
= Config
->InitialServerPort
;
450 Instance
->ConnectedPort
= 0;
452 CopyMem (&Instance
->Gateway
, &Config
->GatewayIp
, sizeof (IP4_ADDR
));
453 Instance
->Gateway
= NTOHL (Instance
->Gateway
);
455 Instance
->MaxRetry
= Config
->TryCount
;
456 Instance
->Timeout
= Config
->TimeoutValue
;
457 Instance
->Master
= TRUE
;
459 if (Override
!= NULL
) {
460 CopyMem (&Instance
->ServerIp
, &Override
->ServerIp
, sizeof (IP4_ADDR
));
461 CopyMem (&Instance
->Gateway
, &Override
->GatewayIp
, sizeof (IP4_ADDR
));
463 Instance
->ServerIp
= NTOHL (Instance
->ServerIp
);
464 Instance
->Gateway
= NTOHL (Instance
->Gateway
);
466 Instance
->ListeningPort
= Override
->ServerPort
;
467 Instance
->MaxRetry
= Override
->TryCount
;
468 Instance
->Timeout
= Override
->TimeoutValue
;
471 if (Instance
->ListeningPort
== 0) {
472 Instance
->ListeningPort
= MTFTP4_DEFAULT_SERVER_PORT
;
475 if (Instance
->MaxRetry
== 0) {
476 Instance
->MaxRetry
= MTFTP4_DEFAULT_RETRY
;
479 if (Instance
->Timeout
== 0) {
480 Instance
->Timeout
= MTFTP4_DEFAULT_TIMEOUT
;
484 // Config the unicast UDP child to send initial request
486 Status
= Mtftp4ConfigUnicastPort (Instance
->UnicastPort
, Instance
);
488 if (EFI_ERROR (Status
)) {
489 Status
= EFI_DEVICE_ERROR
;
494 // Set initial status.
496 Token
->Status
= EFI_NOT_READY
;
499 // Build and send an initial requests
501 if (Operation
== EFI_MTFTP4_OPCODE_WRQ
) {
502 Status
= Mtftp4WrqStart (Instance
, Operation
);
504 Status
= Mtftp4RrqStart (Instance
, Operation
);
507 if (EFI_ERROR (Status
)) {
508 Status
= EFI_DEVICE_ERROR
;
512 if (Token
->Event
!= NULL
) {
513 gBS
->RestoreTPL (OldTpl
);
518 // Return immediately for asynchronous operation or poll the
519 // instance for synchronous operation.
521 while (Token
->Status
== EFI_NOT_READY
) {
525 gBS
->RestoreTPL (OldTpl
);
526 return Token
->Status
;
529 Mtftp4CleanOperation (Instance
, Status
);
530 gBS
->RestoreTPL (OldTpl
);
537 Reads the current operational settings.
539 The GetModeData()function reads the current operational settings of this
540 EFI MTFTPv4 Protocol driver instance.
542 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
543 @param ModeData Pointer to storage for the EFI MTFTPv4 Protocol
546 @retval EFI_SUCCESS The configuration data was successfully returned.
547 @retval EFI_OUT_OF_RESOURCES The required mode data could not be allocated.
548 @retval EFI_INVALID_PARAMETER This is NULL or ModeData is NULL.
553 EfiMtftp4GetModeData (
554 IN EFI_MTFTP4_PROTOCOL
*This
,
555 OUT EFI_MTFTP4_MODE_DATA
*ModeData
558 MTFTP4_PROTOCOL
*Instance
;
561 if ((This
== NULL
) || (ModeData
== NULL
)) {
562 return EFI_INVALID_PARAMETER
;
565 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
567 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
568 CopyMem(&ModeData
->ConfigData
, &Instance
->Config
, sizeof (Instance
->Config
));
569 ModeData
->SupportedOptionCount
= MTFTP4_SUPPORTED_OPTIONS
;
570 ModeData
->SupportedOptoins
= (UINT8
**) mMtftp4SupportedOptions
;
571 ModeData
->UnsupportedOptionCount
= 0;
572 ModeData
->UnsupportedOptoins
= NULL
;
574 gBS
->RestoreTPL (OldTpl
);
582 Initializes, changes, or resets the default operational setting for this
583 EFI MTFTPv4 Protocol driver instance.
585 The Configure() function is used to set and change the configuration data for
586 this EFI MTFTPv4 Protocol driver instance. The configuration data can be reset
587 to startup defaults by calling Configure() with MtftpConfigData set to NULL.
588 Whenever the instance is reset, any pending operation is aborted. By changing
589 the EFI MTFTPv4 Protocol driver instance configuration data, the client can
590 connect to different MTFTPv4 servers. The configuration parameters in
591 MtftpConfigData are used as the default parameters in later MTFTPv4 operations
592 and can be overridden in later operations.
594 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
595 @param ConfigData MtftpConfigDataPointer to the configuration data
598 @retval EFI_SUCCESS The EFI MTFTPv4 Protocol driver was configured
600 @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
602 2.MtftpConfigData.UseDefaultSetting is FALSE and
603 MtftpConfigData.StationIp is not a valid IPv4
605 3.MtftpCofigData.UseDefaultSetting is FALSE and
606 MtftpConfigData.SubnetMask is invalid.
607 4.MtftpCofigData.ServerIp is not a valid IPv4
609 5.MtftpConfigData.UseDefaultSetting is FALSE and
610 MtftpConfigData.GatewayIp is not a valid IPv4
611 unicast address or is not in the same subnet
612 with station address.
613 @retval EFI_ACCESS_DENIED The EFI configuration could not be changed at this
614 time because there is one MTFTP background operation
616 @retval EFI_NO_MAPPING When using a default address, configuration
617 (DHCP, BOOTP, RARP, etc.) has not finished yet.
618 @retval EFI_UNSUPPORTED A configuration protocol (DHCP, BOOTP, RARP, etc.)
619 could not be located when clients choose to use
620 the default address settings.
621 @retval EFI_OUT_OF_RESOURCES The EFI MTFTPv4 Protocol driver instance data could
623 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
624 The EFI MTFTPv4 Protocol driver instance is not
631 IN EFI_MTFTP4_PROTOCOL
*This
,
632 IN EFI_MTFTP4_CONFIG_DATA
*ConfigData
635 MTFTP4_PROTOCOL
*Instance
;
643 return EFI_INVALID_PARAMETER
;
646 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
648 if (ConfigData
== NULL
) {
650 // Reset the operation if ConfigData is NULL
652 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
654 Mtftp4CleanOperation (Instance
, EFI_ABORTED
);
655 ZeroMem (&Instance
->Config
, sizeof (EFI_MTFTP4_CONFIG_DATA
));
656 Instance
->State
= MTFTP4_STATE_UNCONFIGED
;
658 gBS
->RestoreTPL (OldTpl
);
662 // Configure the parameters for new operation.
664 CopyMem (&Ip
, &ConfigData
->StationIp
, sizeof (IP4_ADDR
));
665 CopyMem (&Netmask
, &ConfigData
->SubnetMask
, sizeof (IP4_ADDR
));
666 CopyMem (&Gateway
, &ConfigData
->GatewayIp
, sizeof (IP4_ADDR
));
667 CopyMem (&ServerIp
, &ConfigData
->ServerIp
, sizeof (IP4_ADDR
));
670 Netmask
= NTOHL (Netmask
);
671 Gateway
= NTOHL (Gateway
);
672 ServerIp
= NTOHL (ServerIp
);
674 if (ServerIp
== 0 || IP4_IS_LOCAL_BROADCAST (ServerIp
)) {
675 return EFI_INVALID_PARAMETER
;
678 if (!ConfigData
->UseDefaultSetting
&&
679 ((!IP4_IS_VALID_NETMASK (Netmask
) || (Netmask
!= 0 && !NetIp4IsUnicast (Ip
, Netmask
))))) {
681 return EFI_INVALID_PARAMETER
;
684 if ((Gateway
!= 0) &&
685 (!IP4_NET_EQUAL (Gateway
, Ip
, Netmask
) || (Netmask
!= 0 && !NetIp4IsUnicast (Gateway
, Netmask
)))) {
687 return EFI_INVALID_PARAMETER
;
690 OldTpl
= gBS
->RaiseTPL (TPL_CALLBACK
);
692 if ((Instance
->State
== MTFTP4_STATE_CONFIGED
) && (Instance
->Operation
!= 0)) {
693 gBS
->RestoreTPL (OldTpl
);
694 return EFI_ACCESS_DENIED
;
697 CopyMem(&Instance
->Config
, ConfigData
, sizeof (*ConfigData
));;
698 Instance
->State
= MTFTP4_STATE_CONFIGED
;
700 gBS
->RestoreTPL (OldTpl
);
709 Parses the options in an MTFTPv4 OACK packet.
711 The ParseOptions() function parses the option fields in an MTFTPv4 OACK packet
712 and returns the number of options that were found and optionally a list of
713 pointers to the options in the packet.
714 If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is
715 returned and *OptionCount and *OptionList stop at the last valid option.
716 The OptionList is allocated by this function, and caller should free it when used.
718 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
719 @param PacketLen Length of the OACK packet to be parsed.
720 @param Packet Pointer to the OACK packet to be parsed.
721 @param OptionCount Pointer to the number of options in following OptionList.
722 @param OptionList Pointer to EFI_MTFTP4_OPTION storage. Call the
723 EFI Boot Service FreePool() to release theOptionList
724 if the options in this OptionList are not needed
727 @retval EFI_SUCCESS The OACK packet was valid and the OptionCount and
728 OptionList parameters have been updated.
729 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
731 2.Packet is NULL or Packet is not a valid MTFTPv4 packet.
732 3.OptionCount is NULL.
733 @retval EFI_NOT_FOUND No options were found in the OACK packet.
734 @retval EFI_OUT_OF_RESOURCES Storage for the OptionList array cannot be allocated.
735 @retval EFI_PROTOCOL_ERROR One or more of the option fields is invalid.
740 EfiMtftp4ParseOptions (
741 IN EFI_MTFTP4_PROTOCOL
*This
,
743 IN EFI_MTFTP4_PACKET
*Packet
,
744 OUT UINT32
*OptionCount
,
745 OUT EFI_MTFTP4_OPTION
**OptionList OPTIONAL
750 if ((This
== NULL
) || (PacketLen
< MTFTP4_OPCODE_LEN
) ||
751 (Packet
== NULL
) || (OptionCount
== NULL
)) {
753 return EFI_INVALID_PARAMETER
;
756 Status
= Mtftp4ExtractOptions (Packet
, PacketLen
, OptionCount
, OptionList
);
758 if (EFI_ERROR (Status
)) {
762 if (*OptionCount
== 0) {
763 return EFI_NOT_FOUND
;
771 Downloads a file from an MTFTPv4 server.
773 The ReadFile() function is used to initialize and start an MTFTPv4 download
774 process and optionally wait for completion. When the download operation completes,
775 whether successfully or not, the Token.Status field is updated by the EFI MTFTPv4
776 Protocol driver and then Token.Event is signaled (if it is not NULL).
777 Data can be downloaded from the MTFTPv4 server into either of the following locations:
778 1.A fixed buffer that is pointed to by Token.Buffer
779 2.A download service function that is pointed to by Token.CheckPacket
780 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
781 will be called first. If the call is successful, the packet will be stored in
784 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
785 @param Token Pointer to the token structure to provide the
786 parameters that are used in this operation.
788 @retval EFI_SUCCESS The data file has been transferred successfully.
789 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
790 @retval EFI_BUFFER_TOO_SMALL BufferSize is not large enough to hold the downloaded
791 data in downloading process.
792 @retval EFI_ABORTED Current operation is aborted by user.
793 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received.
794 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
795 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received.
796 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
797 @retval EFI_NO_MEDIA There was a media error.
803 IN EFI_MTFTP4_PROTOCOL
*This
,
804 IN EFI_MTFTP4_TOKEN
*Token
807 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_RRQ
);
812 Sends a data file to an MTFTPv4 server. May be unsupported in some EFI implementations
814 The WriteFile() function is used to initialize an uploading operation with the
815 given option list and optionally wait for completion. If one or more of the
816 options is not supported by the server, the unsupported options are ignored and
817 a standard TFTP process starts instead. When the upload process completes,
818 whether successfully or not, Token.Event is signaled, and the EFI MTFTPv4 Protocol
819 driver updates Token.Status.
820 The caller can supply the data to be uploaded in the following two modes:
821 1.Through the user-provided buffer
822 2.Through a callback function
823 With the user-provided buffer, the Token.BufferSize field indicates the length
824 of the buffer, and the driver will upload the data in the buffer. With an
825 EFI_MTFTP4_PACKET_NEEDED callback function, the driver will call this callback
826 function to get more data from the user to upload. See the definition of
827 EFI_MTFTP4_PACKET_NEEDED for more information. These two modes cannot be used at
828 the same time. The callback function will be ignored if the user provides the buffer.
830 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance.
831 @param Token Pointer to the token structure to provide the
832 parameters that are used in this function
834 @retval EFI_SUCCESS The upload session has started.
835 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
836 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
839 3. Token.Filename is NULL.
840 4. Token.OptionCount is not zero and
841 Token.OptionList is NULL.
842 5. One or more options in Token.OptionList have wrong
844 6. Token.Buffer and Token.PacketNeeded are both
846 7. One or more IPv4 addresses in Token.OverrideData
847 are not valid unicast IPv4 addresses if
848 Token.OverrideData is not NULL.
849 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
850 unsupported list of structure EFI_MTFTP4_MODE_DATA.
851 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
852 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
853 BOOTP, RARP, etc.) is not finished yet.
854 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
856 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
857 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
858 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
864 IN EFI_MTFTP4_PROTOCOL
*This
,
865 IN EFI_MTFTP4_TOKEN
*Token
868 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_WRQ
);
873 Downloads a data file "directory" from an MTFTPv4 server.
874 May be unsupported in some EFI implementations
876 The ReadDirectory() function is used to return a list of files on the MTFTPv4
877 server that are logically (or operationally) related to Token.Filename. The
878 directory request packet that is sent to the server is built with the option
879 list that was provided by caller, if present.
880 The file information that the server returns is put into either of the following
882 1.A fixed buffer that is pointed to by Token.Buffer
883 2.A download service function that is pointed to by Token.CheckPacket
884 If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket will
885 be called first. If the call is successful, the packet will be stored in Token.Buffer.
886 The returned directory listing in the Token.Buffer or EFI_MTFTP4_PACKET consists
887 of a list of two or three variable-length ASCII strings, each terminated by a
888 null character, for each file in the directory. If the multicast option is involved,
889 the first field of each directory entry is the static multicast IP address and
890 UDP port number that is associated with the file name. The format of the field
891 is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its
892 terminating null character are not present.
893 The next field of each directory entry is the file name and the last field is
894 the file information string. The information string contains the file size and
895 the create/modify timestamp. The format of the information string is filesize
896 yyyy-mm-dd hh:mm:ss:ffff. The timestamp is Coordinated Universal Time
897 (UTC; also known as Greenwich Mean Time [GMT]).
898 The only difference between ReadFile and ReadDirectory is the opcode used.
900 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
901 @param Token Pointer to the token structure to provide the
902 parameters that are used in this function
904 @retval EFI_SUCCESS The MTFTPv4 related file "directory" has been downloaded.
905 @retval EFI_UNSUPPORTED The operation is not supported by this implementation.
906 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
909 3. Token.Filename is NULL.
910 4. Token.OptionCount is not zero and
911 Token.OptionList is NULL.
912 5. One or more options in Token.OptionList have wrong
914 6. Token.Buffer and Token.PacketNeeded are both
916 7. One or more IPv4 addresses in Token.OverrideData
917 are not valid unicast IPv4 addresses if
918 Token.OverrideData is not NULL.
919 @retval EFI_UNSUPPORTED One or more options in the Token.OptionList are in the
920 unsupported list of structure EFI_MTFTP4_MODE_DATA.
921 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
922 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
923 BOOTP, RARP, etc.) is not finished yet.
924 @retval EFI_ALREADY_STARTED This Token is already being used in another MTFTPv4
926 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
927 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
928 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
933 EfiMtftp4ReadDirectory (
934 IN EFI_MTFTP4_PROTOCOL
*This
,
935 IN EFI_MTFTP4_TOKEN
*Token
938 return Mtftp4Start (This
, Token
, EFI_MTFTP4_OPCODE_DIR
);
943 Gets information about a file from an MTFTPv4 server.
945 The GetInfo() function assembles an MTFTPv4 request packet with options;
946 sends it to the MTFTPv4 server; and may return an MTFTPv4 OACK, MTFTPv4 ERROR,
947 or ICMP ERROR packet. Retries occur only if no response packets are received
948 from the MTFTPv4 server before the timeout expires.
949 It is implemented with EfiMtftp4ReadFile: build a token, then pass it to
950 EfiMtftp4ReadFile. In its check packet callback abort the opertions.
952 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
953 @param OverrideData Data that is used to override the existing
954 parameters. If NULL, the default parameters that
955 were set in the EFI_MTFTP4_PROTOCOL.Configure()
957 @param Filename Pointer to null-terminated ASCII file name string
958 @param ModeStr Pointer to null-terminated ASCII mode string. If NULL, "octet"
960 @param OptionCount Number of option/value string pairs in OptionList
961 @param OptionList Pointer to array of option/value string pairs.
962 Ignored if OptionCount is zero
963 @param PacketLength The number of bytes in the returned packet
964 @param Packet PacketThe pointer to the received packet. This
965 buffer must be freed by the caller.
967 @retval EFI_SUCCESS An MTFTPv4 OACK packet was received and is in
969 @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
972 3.OptionCount is not zero and OptionList is NULL.
973 4.One or more options in OptionList have wrong format.
974 5.PacketLength is NULL.
975 6.One or more IPv4 addresses in OverrideData are
976 not valid unicast IPv4 addresses if OverrideData
978 @retval EFI_UNSUPPORTED One or more options in the OptionList are in the
979 unsupported list of structure EFI_MTFTP4_MODE_DATA
980 @retval EFI_NOT_STARTED The EFI MTFTPv4 Protocol driver has not been started.
981 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
982 BOOTP, RARP, etc.) has not finished yet.
983 @retval EFI_ACCESS_DENIED The previous operation has not completed yet.
984 @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.
985 @retval EFI_TFTP_ERROR An MTFTPv4 ERROR packet was received and is in
987 @retval EFI_ICMP_ERROR An ICMP ERROR packet was received and the Packet
989 @retval EFI_PROTOCOL_ERROR An unexpected MTFTPv4 packet was received and is
991 @retval EFI_TIMEOUT No responses were received from the MTFTPv4 server.
992 @retval EFI_DEVICE_ERROR An unexpected network error or system error occurred.
993 @retval EFI_NO_MEDIA There was a media error.
999 IN EFI_MTFTP4_PROTOCOL
*This
,
1000 IN EFI_MTFTP4_OVERRIDE_DATA
*OverrideData OPTIONAL
,
1002 IN UINT8
*ModeStr OPTIONAL
,
1003 IN UINT8 OptionCount
,
1004 IN EFI_MTFTP4_OPTION
*OptionList OPTIONAL
,
1005 OUT UINT32
*PacketLength
,
1006 OUT EFI_MTFTP4_PACKET
**Packet OPTIONAL
1009 EFI_MTFTP4_TOKEN Token
;
1010 MTFTP4_GETINFO_STATE State
;
1013 if ((This
== NULL
) || (Filename
== NULL
) || (PacketLength
== NULL
) ||
1014 ((OptionCount
!= 0) && (OptionList
== NULL
))) {
1015 return EFI_INVALID_PARAMETER
;
1018 if (Packet
!= NULL
) {
1023 State
.Packet
= Packet
;
1024 State
.PacketLen
= PacketLength
;
1025 State
.Status
= EFI_SUCCESS
;
1028 // Fill in the Token to issue an synchronous ReadFile operation
1030 Token
.Status
= EFI_SUCCESS
;
1032 Token
.OverrideData
= OverrideData
;
1033 Token
.Filename
= Filename
;
1034 Token
.ModeStr
= ModeStr
;
1035 Token
.OptionCount
= OptionCount
;
1036 Token
.OptionList
= OptionList
;
1037 Token
.BufferSize
= 0;
1038 Token
.Buffer
= NULL
;
1039 Token
.Context
= &State
;
1040 Token
.CheckPacket
= Mtftp4GetInfoCheckPacket
;
1041 Token
.TimeoutCallback
= NULL
;
1042 Token
.PacketNeeded
= NULL
;
1044 Status
= EfiMtftp4ReadFile (This
, &Token
);
1046 if (EFI_ABORTED
== Status
) {
1047 return State
.Status
;
1054 Polls for incoming data packets and processes outgoing data packets.
1056 The Poll() function can be used by network drivers and applications to increase
1057 the rate that data packets are moved between the communications device and the
1058 transmit and receive queues.
1059 In some systems, the periodic timer event in the managed network driver may not
1060 poll the underlying communications device fast enough to transmit and/or receive
1061 all data packets without missing incoming packets or dropping outgoing packets.
1062 Drivers and applications that are experiencing packet loss should try calling
1063 the Poll() function more often.
1065 @param This Pointer to the EFI_MTFTP4_PROTOCOL instance
1067 @retval EFI_SUCCESS Incoming or outgoing data was processed.
1068 @retval EFI_NOT_STARTED This EFI MTFTPv4 Protocol instance has not been started.
1069 @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
1070 BOOTP, RARP, etc.) is not finished yet.
1071 @retval EFI_INVALID_PARAMETER This is NULL.
1072 @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
1073 @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive
1074 queue. Consider increasing the polling rate.
1080 IN EFI_MTFTP4_PROTOCOL
*This
1083 MTFTP4_PROTOCOL
*Instance
;
1084 EFI_UDP4_PROTOCOL
*Udp
;
1087 return EFI_INVALID_PARAMETER
;
1090 Instance
= MTFTP4_PROTOCOL_FROM_THIS (This
);
1092 if (Instance
->State
== MTFTP4_STATE_UNCONFIGED
) {
1093 return EFI_NOT_STARTED
;
1094 } else if (Instance
->State
== MTFTP4_STATE_DESTROY
) {
1095 return EFI_DEVICE_ERROR
;
1098 Udp
= Instance
->UnicastPort
->Protocol
.Udp4
;
1099 return Udp
->Poll (Udp
);
1102 EFI_MTFTP4_PROTOCOL gMtftp4ProtocolTemplate
= {
1103 EfiMtftp4GetModeData
,
1106 EfiMtftp4ParseOptions
,
1109 EfiMtftp4ReadDirectory
,