MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Impl.c

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