MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Impl.c

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