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 };