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