MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Impl.c

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