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->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 (IP4_IS_UNSPECIFIED (NTOHL (Ip)) || IP4_IS_LOCAL_BROADCAST (NTOHL (Ip))) {
 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 ((Netmask != 0 && !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   EFI_STATUS                TokenStatus;
 370
 371   //
 372   // Validate the parameters
 373   //
 374   if ((This == NULL) || (Token == NULL) || (Token->Filename == NULL) ||
 375       ((Token->OptionCount != 0) && (Token->OptionList == NULL))) {
 376     return EFI_INVALID_PARAMETER;
 377   }
 378
 379   //
 380   // User must provide at least one method to collect the data for download.
 381   //
 382   if (((Operation == EFI_MTFTP4_OPCODE_RRQ) || (Operation == EFI_MTFTP4_OPCODE_DIR)) &&
 383       ((Token->Buffer == NULL) && (Token->CheckPacket == NULL))) {
 384     return EFI_INVALID_PARAMETER;
 385   }
 386
 387   //
 388   // User must provide at least one method to provide the data for upload.
 389   //
 390   if ((Operation == EFI_MTFTP4_OPCODE_WRQ) &&
 391      ((Token->Buffer == NULL) && (Token->PacketNeeded == NULL))) {
 392     return EFI_INVALID_PARAMETER;
 393   }
 394
 395   Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
 396
 397   Status      = EFI_SUCCESS;
 398   TokenStatus = EFI_SUCCESS;
 399
 400   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 401
 402   if (Instance->State != MTFTP4_STATE_CONFIGED) {
 403     Status = EFI_NOT_STARTED;
 404   }
 405
 406   if (Instance->Operation != 0) {
 407     Status = EFI_ACCESS_DENIED;
 408   }
 409
 410   if ((Token->OverrideData != NULL) && !Mtftp4OverrideValid (Instance, Token->OverrideData)) {
 411     Status = EFI_INVALID_PARAMETER;
 412   }
 413
 414   if (EFI_ERROR (Status)) {
 415     gBS->RestoreTPL (OldTpl);
 416     return Status;
 417   }
 418
 419   //
 420   // Set the Operation now to prevent the application start other
 421   // operations.
 422   //
 423   Instance->Operation = Operation;
 424   Override            = Token->OverrideData;
 425
 426   if (Token->OptionCount != 0) {
 427     Status = Mtftp4ParseOption (
 428                Token->OptionList,
 429                Token->OptionCount,
 430                TRUE,
 431                &Instance->RequestOption
 432                );
 433
 434     if (EFI_ERROR (Status)) {
 435       TokenStatus = EFI_DEVICE_ERROR;
 436       goto ON_ERROR;
 437     }
 438   }
 439
 440   //
 441   // Set the operation parameters from the configuration or override data.
 442   //
 443   Config                  = &Instance->Config;
 444   Instance->Token         = Token;
 445   Instance->BlkSize       = MTFTP4_DEFAULT_BLKSIZE;
 446
 447   CopyMem (&Instance->ServerIp, &Config->ServerIp, sizeof (IP4_ADDR));
 448   Instance->ServerIp      = NTOHL (Instance->ServerIp);
 449
 450   Instance->ListeningPort = Config->InitialServerPort;
 451   Instance->ConnectedPort = 0;
 452
 453   CopyMem (&Instance->Gateway, &Config->GatewayIp, sizeof (IP4_ADDR));
 454   Instance->Gateway       = NTOHL (Instance->Gateway);
 455
 456   Instance->MaxRetry      = Config->TryCount;
 457   Instance->Timeout       = Config->TimeoutValue;
 458   Instance->Master        = TRUE;
 459
 460   if (Override != NULL) {
 461     CopyMem (&Instance->ServerIp, &Override->ServerIp, sizeof (IP4_ADDR));
 462     CopyMem (&Instance->Gateway, &Override->GatewayIp, sizeof (IP4_ADDR));
 463
 464     Instance->ServerIp      = NTOHL (Instance->ServerIp);
 465     Instance->Gateway       = NTOHL (Instance->Gateway);
 466
 467     Instance->ListeningPort = Override->ServerPort;
 468     Instance->MaxRetry      = Override->TryCount;
 469     Instance->Timeout       = Override->TimeoutValue;
 470   }
 471
 472   if (Instance->ListeningPort == 0) {
 473     Instance->ListeningPort = MTFTP4_DEFAULT_SERVER_PORT;
 474   }
 475
 476   if (Instance->MaxRetry == 0) {
 477     Instance->MaxRetry = MTFTP4_DEFAULT_RETRY;
 478   }
 479
 480   if (Instance->Timeout == 0) {
 481     Instance->Timeout = MTFTP4_DEFAULT_TIMEOUT;
 482   }
 483
 484   //
 485   // Config the unicast UDP child to send initial request
 486   //
 487   Status = Mtftp4ConfigUnicastPort (Instance->UnicastPort, Instance);
 488   if (EFI_ERROR (Status)) {
 489     TokenStatus = EFI_DEVICE_ERROR;
 490     goto ON_ERROR;
 491   }
 492
 493   //
 494   // Set initial status.
 495   //
 496   Token->Status = EFI_NOT_READY;
 497
 498   //
 499   // Build and send an initial requests
 500   //
 501   if (Operation == EFI_MTFTP4_OPCODE_WRQ) {
 502     Status = Mtftp4WrqStart (Instance, Operation);
 503   } else {
 504     Status = Mtftp4RrqStart (Instance, Operation);
 505   }
 506
 507   if (EFI_ERROR (Status)) {
 508     TokenStatus = EFI_DEVICE_ERROR;
 509     goto ON_ERROR;
 510   }
 511
 512   gBS->RestoreTPL(OldTpl);
 513
 514   if (Token->Event != NULL) {
 515     return EFI_SUCCESS;
 516   }
 517
 518   //
 519   // Return immediately for asynchronous operation or poll the
 520   // instance for synchronous operation.
 521   //
 522   while (Token->Status == EFI_NOT_READY) {
 523     This->Poll (This);
 524   }
 525
 526   return Token->Status;
 527
 528 ON_ERROR:
 529   Mtftp4CleanOperation (Instance, TokenStatus);
 530   gBS->RestoreTPL (OldTpl);
 531
 532   return Status;
 533 }
 534
 535
 536 /**
 537   Reads the current operational settings.
 538
 539   The GetModeData()function reads the current operational settings of this
 540   EFI MTFTPv4 Protocol driver instance.
 541
 542   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance.
 543   @param  ModeData               Pointer to storage for the EFI MTFTPv4 Protocol
 544                                  driver mode data.
 545
 546   @retval EFI_SUCCESS            The configuration data was successfully returned.
 547   @retval EFI_OUT_OF_RESOURCES   The required mode data could not be allocated.
 548   @retval EFI_INVALID_PARAMETER  This is NULL or ModeData is NULL.
 549
 550 **/
 551 EFI_STATUS
 552 EFIAPI
 553 EfiMtftp4GetModeData (
 554   IN     EFI_MTFTP4_PROTOCOL    *This,
 555      OUT EFI_MTFTP4_MODE_DATA  *ModeData
 556   )
 557 {
 558   MTFTP4_PROTOCOL  *Instance;
 559   EFI_TPL          OldTpl;
 560
 561   if ((This == NULL) || (ModeData == NULL)) {
 562     return EFI_INVALID_PARAMETER;
 563   }
 564
 565   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 566
 567   Instance                         = MTFTP4_PROTOCOL_FROM_THIS (This);
 568   CopyMem(&ModeData->ConfigData, &Instance->Config, sizeof (Instance->Config));
 569   ModeData->SupportedOptionCount   = MTFTP4_SUPPORTED_OPTIONS;
 570   ModeData->SupportedOptoins       = (UINT8 **) mMtftp4SupportedOptions;
 571   ModeData->UnsupportedOptionCount = 0;
 572   ModeData->UnsupportedOptoins     = NULL;
 573
 574   gBS->RestoreTPL (OldTpl);
 575
 576   return EFI_SUCCESS;
 577 }
 578
 579
 580
 581 /**
 582   Initializes, changes, or resets the default operational setting for this
 583   EFI MTFTPv4 Protocol driver instance.
 584
 585   The Configure() function is used to set and change the configuration data for
 586   this EFI MTFTPv4 Protocol driver instance. The configuration data can be reset
 587   to startup defaults by calling Configure() with MtftpConfigData set to NULL.
 588   Whenever the instance is reset, any pending operation is aborted. By changing
 589   the EFI MTFTPv4 Protocol driver instance configuration data, the client can
 590   connect to different MTFTPv4 servers. The configuration parameters in
 591   MtftpConfigData are used as the default parameters in later MTFTPv4 operations
 592   and can be overridden in later operations.
 593
 594   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance
 595   @param  ConfigData             MtftpConfigDataPointer to the configuration data
 596                                  structure
 597
 598   @retval EFI_SUCCESS            The EFI MTFTPv4 Protocol driver was configured
 599                                  successfully.
 600   @retval EFI_INVALID_PARAMETER  One or more following conditions are TRUE:
 601                                  1.This is NULL.
 602                                  2.MtftpConfigData.UseDefaultSetting is FALSE and
 603                                    MtftpConfigData.StationIp is not a valid IPv4
 604                                    unicast address.
 605                                  3.MtftpCofigData.UseDefaultSetting is FALSE and
 606                                    MtftpConfigData.SubnetMask is invalid.
 607                                  4.MtftpCofigData.ServerIp is not a valid IPv4
 608                                    unicast address.
 609                                  5.MtftpConfigData.UseDefaultSetting is FALSE and
 610                                    MtftpConfigData.GatewayIp is not a valid IPv4
 611                                    unicast address or is not in the same subnet
 612                                    with station address.
 613   @retval EFI_ACCESS_DENIED      The EFI configuration could not be changed at this
 614                                  time because there is one MTFTP background operation
 615                                  in progress.
 616   @retval EFI_NO_MAPPING         When using a default address, configuration
 617                                  (DHCP, BOOTP, RARP, etc.) has not finished yet.
 618   @retval EFI_UNSUPPORTED        A configuration protocol (DHCP, BOOTP, RARP, etc.)
 619                                  could not be located when clients choose to use
 620                                  the default address settings.
 621   @retval EFI_OUT_OF_RESOURCES   The EFI MTFTPv4 Protocol driver instance data could
 622                                  not be allocated.
 623   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 624                                  The EFI MTFTPv4 Protocol driver instance is not
 625                                  configured.
 626
 627 **/
 628 EFI_STATUS
 629 EFIAPI
 630 EfiMtftp4Configure (
 631   IN EFI_MTFTP4_PROTOCOL    *This,
 632   IN EFI_MTFTP4_CONFIG_DATA *ConfigData
 633   )
 634 {
 635   MTFTP4_PROTOCOL           *Instance;
 636   EFI_TPL                   OldTpl;
 637   IP4_ADDR                  Ip;
 638   IP4_ADDR                  Netmask;
 639   IP4_ADDR                  Gateway;
 640   IP4_ADDR                  ServerIp;
 641
 642   if (This == NULL) {
 643     return EFI_INVALID_PARAMETER;
 644   }
 645
 646   Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
 647
 648   if (ConfigData == NULL) {
 649     //
 650     // Reset the operation if ConfigData is NULL
 651     //
 652     OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 653
 654     Mtftp4CleanOperation (Instance, EFI_ABORTED);
 655     ZeroMem (&Instance->Config, sizeof (EFI_MTFTP4_CONFIG_DATA));
 656     Instance->State = MTFTP4_STATE_UNCONFIGED;
 657
 658     gBS->RestoreTPL (OldTpl);
 659
 660   } else {
 661     //
 662     // Configure the parameters for new operation.
 663     //
 664     CopyMem (&Ip, &ConfigData->StationIp, sizeof (IP4_ADDR));
 665     CopyMem (&Netmask, &ConfigData->SubnetMask, sizeof (IP4_ADDR));
 666     CopyMem (&Gateway, &ConfigData->GatewayIp, sizeof (IP4_ADDR));
 667     CopyMem (&ServerIp, &ConfigData->ServerIp, sizeof (IP4_ADDR));
 668
 669     Ip       = NTOHL (Ip);
 670     Netmask  = NTOHL (Netmask);
 671     Gateway  = NTOHL (Gateway);
 672     ServerIp = NTOHL (ServerIp);
 673
 674     if (ServerIp == 0 || IP4_IS_LOCAL_BROADCAST (ServerIp)) {
 675       return EFI_INVALID_PARAMETER;
 676     }
 677
 678     if (!ConfigData->UseDefaultSetting &&
 679         ((!IP4_IS_VALID_NETMASK (Netmask) || (Netmask != 0 && !NetIp4IsUnicast (Ip, Netmask))))) {
 680
 681       return EFI_INVALID_PARAMETER;
 682     }
 683
 684     if ((Gateway != 0) &&
 685         ((Netmask != 0xFFFFFFFF && !IP4_NET_EQUAL (Gateway, Ip, Netmask)) || (Netmask != 0 && !NetIp4IsUnicast (Gateway, Netmask)))) {
 686
 687       return EFI_INVALID_PARAMETER;
 688     }
 689
 690     OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 691
 692     if ((Instance->State == MTFTP4_STATE_CONFIGED) && (Instance->Operation != 0)) {
 693       gBS->RestoreTPL (OldTpl);
 694       return EFI_ACCESS_DENIED;
 695     }
 696
 697     CopyMem(&Instance->Config, ConfigData, sizeof (*ConfigData));;
 698     Instance->State = MTFTP4_STATE_CONFIGED;
 699
 700     gBS->RestoreTPL (OldTpl);
 701   }
 702
 703   return EFI_SUCCESS;
 704 }
 705
 706
 707
 708 /**
 709   Parses the options in an MTFTPv4 OACK packet.
 710
 711   The ParseOptions() function parses the option fields in an MTFTPv4 OACK packet
 712   and returns the number of options that were found and optionally a list of
 713   pointers to the options in the packet.
 714   If one or more of the option fields are not valid, then EFI_PROTOCOL_ERROR is
 715   returned and *OptionCount and *OptionList stop at the last valid option.
 716   The OptionList is allocated by this function, and caller should free it when used.
 717
 718   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance.
 719   @param  PacketLen              Length of the OACK packet to be parsed.
 720   @param  Packet                 Pointer to the OACK packet to be parsed.
 721   @param  OptionCount            Pointer to the number of options in following OptionList.
 722   @param  OptionList             Pointer to EFI_MTFTP4_OPTION storage. Call the
 723                                  EFI Boot Service FreePool() to release theOptionList
 724                                  if the options in this OptionList are not needed
 725                                  any more
 726
 727   @retval EFI_SUCCESS            The OACK packet was valid and the OptionCount and
 728                                  OptionList parameters have been updated.
 729   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 730                                  1.PacketLen is 0.
 731                                  2.Packet is NULL or Packet is not a valid MTFTPv4 packet.
 732                                  3.OptionCount is NULL.
 733   @retval EFI_NOT_FOUND          No options were found in the OACK packet.
 734   @retval EFI_OUT_OF_RESOURCES   Storage for the OptionList array cannot be allocated.
 735   @retval EFI_PROTOCOL_ERROR     One or more of the option fields is invalid.
 736
 737 **/
 738 EFI_STATUS
 739 EFIAPI
 740 EfiMtftp4ParseOptions (
 741   IN     EFI_MTFTP4_PROTOCOL    *This,
 742   IN     UINT32                 PacketLen,
 743   IN     EFI_MTFTP4_PACKET      *Packet,
 744      OUT UINT32                 *OptionCount,
 745      OUT EFI_MTFTP4_OPTION      **OptionList          OPTIONAL
 746   )
 747 {
 748   EFI_STATUS                Status;
 749
 750   if ((This == NULL) || (PacketLen < MTFTP4_OPCODE_LEN) ||
 751       (Packet == NULL) || (OptionCount == NULL)) {
 752
 753     return EFI_INVALID_PARAMETER;
 754   }
 755
 756   Status = Mtftp4ExtractOptions (Packet, PacketLen, OptionCount, OptionList);
 757
 758   if (EFI_ERROR (Status)) {
 759     return Status;
 760   }
 761
 762   if (*OptionCount == 0) {
 763     return EFI_NOT_FOUND;
 764   }
 765
 766   return EFI_SUCCESS;
 767 }
 768
 769
 770 /**
 771   Downloads a file from an MTFTPv4 server.
 772
 773   The ReadFile() function is used to initialize and start an MTFTPv4 download
 774   process and optionally wait for completion. When the download operation completes,
 775   whether successfully or not, the Token.Status field is updated by the EFI MTFTPv4
 776   Protocol driver and then Token.Event is signaled (if it is not NULL).
 777   Data can be downloaded from the MTFTPv4 server into either of the following locations:
 778   1.A fixed buffer that is pointed to by Token.Buffer
 779   2.A download service function that is pointed to by Token.CheckPacket
 780   If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket
 781   will be called first. If the call is successful, the packet will be stored in
 782   Token.Buffer.
 783
 784   @param  This                  Pointer to the EFI_MTFTP4_PROTOCOL instance
 785   @param  Token                 Pointer to the token structure to provide the
 786                                 parameters that are used in this operation.
 787
 788   @retval EFI_SUCCESS           The data file has been transferred successfully.
 789   @retval EFI_OUT_OF_RESOURCES  Required system resources could not be allocated.
 790   @retval EFI_BUFFER_TOO_SMALL  BufferSize is not large enough to hold the downloaded
 791                                 data in downloading process.
 792   @retval EFI_ABORTED           Current operation is aborted by user.
 793   @retval EFI_ICMP_ERROR        An ICMP ERROR packet was received.
 794   @retval EFI_TIMEOUT           No responses were received from the MTFTPv4 server.
 795   @retval EFI_TFTP_ERROR        An MTFTPv4 ERROR packet was received.
 796   @retval EFI_DEVICE_ERROR      An unexpected network error or system error occurred.
 797   @retval EFI_NO_MEDIA          There was a media error.
 798
 799 **/
 800 EFI_STATUS
 801 EFIAPI
 802 EfiMtftp4ReadFile (
 803   IN EFI_MTFTP4_PROTOCOL    *This,
 804   IN EFI_MTFTP4_TOKEN       *Token
 805   )
 806 {
 807   return Mtftp4Start (This, Token, EFI_MTFTP4_OPCODE_RRQ);
 808 }
 809
 810
 811 /**
 812   Sends a data file to an MTFTPv4 server. May be unsupported in some EFI implementations
 813
 814   The WriteFile() function is used to initialize an uploading operation with the
 815   given option list and optionally wait for completion. If one or more of the
 816   options is not supported by the server, the unsupported options are ignored and
 817   a standard TFTP process starts instead. When the upload process completes,
 818   whether successfully or not, Token.Event is signaled, and the EFI MTFTPv4 Protocol
 819   driver updates Token.Status.
 820   The caller can supply the data to be uploaded in the following two modes:
 821   1.Through the user-provided buffer
 822   2.Through a callback function
 823   With the user-provided buffer, the Token.BufferSize field indicates the length
 824   of the buffer, and the driver will upload the data in the buffer. With an
 825   EFI_MTFTP4_PACKET_NEEDED callback function, the driver will call this callback
 826   function to get more data from the user to upload. See the definition of
 827   EFI_MTFTP4_PACKET_NEEDED for more information. These two modes cannot be used at
 828   the same time. The callback function will be ignored if the user provides the buffer.
 829
 830   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance.
 831   @param  Token                  Pointer to the token structure to provide the
 832                                  parameters that are used in this function
 833
 834   @retval EFI_SUCCESS            The upload session has started.
 835   @retval EFI_UNSUPPORTED        The operation is not supported by this implementation.
 836   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 837                                  1. This is NULL.
 838                                  2. Token is NULL.
 839                                  3. Token.Filename is NULL.
 840                                  4. Token.OptionCount is not zero and
 841                                     Token.OptionList is NULL.
 842                                  5. One or more options in Token.OptionList have wrong
 843                                     format.
 844                                  6. Token.Buffer and Token.PacketNeeded are both
 845                                     NULL.
 846                                  7. One or more IPv4 addresses in Token.OverrideData
 847                                     are not valid unicast IPv4 addresses if
 848                                     Token.OverrideData is not NULL.
 849   @retval EFI_UNSUPPORTED        One or more options in the Token.OptionList are in the
 850                                  unsupported list of structure EFI_MTFTP4_MODE_DATA.
 851   @retval EFI_NOT_STARTED        The EFI MTFTPv4 Protocol driver has not been started.
 852   @retval EFI_NO_MAPPING         When using a default address, configuration (DHCP,
 853                                  BOOTP, RARP, etc.) is not finished yet.
 854   @retval EFI_ALREADY_STARTED    This Token is already being used in another MTFTPv4
 855                                  session.
 856   @retval EFI_OUT_OF_RESOURCES   Required system resources could not be allocated.
 857   @retval EFI_ACCESS_DENIED      The previous operation has not completed yet.
 858   @retval EFI_DEVICE_ERROR       An unexpected network error or system error occurred.
 859
 860 **/
 861 EFI_STATUS
 862 EFIAPI
 863 EfiMtftp4WriteFile (
 864   IN EFI_MTFTP4_PROTOCOL    *This,
 865   IN EFI_MTFTP4_TOKEN       *Token
 866   )
 867 {
 868   return Mtftp4Start (This, Token, EFI_MTFTP4_OPCODE_WRQ);
 869 }
 870
 871
 872 /**
 873   Downloads a data file "directory" from an MTFTPv4 server.
 874   May be unsupported in some EFI implementations
 875
 876   The ReadDirectory() function is used to return a list of files on the MTFTPv4
 877   server that are logically (or operationally) related to Token.Filename. The
 878   directory request packet that is sent to the server is built with the option
 879   list that was provided by caller, if present.
 880   The file information that the server returns is put into either of the following
 881   locations:
 882   1.A fixed buffer that is pointed to by Token.Buffer
 883   2.A download service function that is pointed to by Token.CheckPacket
 884   If both Token.Buffer and Token.CheckPacket are used, then Token.CheckPacket will
 885   be called first. If the call is successful, the packet will be stored in Token.Buffer.
 886   The returned directory listing in the Token.Buffer or EFI_MTFTP4_PACKET consists
 887   of a list of two or three variable-length ASCII strings, each terminated by a
 888   null character, for each file in the directory. If the multicast option is involved,
 889   the first field of each directory entry is the static multicast IP address and
 890   UDP port number that is associated with the file name. The format of the field
 891   is ip:ip:ip:ip:port. If the multicast option is not involved, this field and its
 892   terminating null character are not present.
 893   The next field of each directory entry is the file name and the last field is
 894   the file information string. The information string contains the file size and
 895   the create/modify timestamp. The format of the information string is filesize
 896   yyyy-mm-dd hh:mm:ss:ffff. The timestamp is Coordinated Universal Time
 897   (UTC; also known as Greenwich Mean Time [GMT]).
 898   The only difference between ReadFile and ReadDirectory is the opcode used.
 899
 900   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance
 901   @param  Token                  Pointer to the token structure to provide the
 902                                  parameters that are used in this function
 903
 904   @retval EFI_SUCCESS            The MTFTPv4 related file "directory" has been downloaded.
 905   @retval EFI_UNSUPPORTED        The operation is not supported by this implementation.
 906   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 907                                  1. This is NULL.
 908                                  2. Token is NULL.
 909                                  3. Token.Filename is NULL.
 910                                  4. Token.OptionCount is not zero and
 911                                     Token.OptionList is NULL.
 912                                  5. One or more options in Token.OptionList have wrong
 913                                     format.
 914                                  6. Token.Buffer and Token.PacketNeeded are both
 915                                     NULL.
 916                                  7. One or more IPv4 addresses in Token.OverrideData
 917                                     are not valid unicast IPv4 addresses if
 918                                     Token.OverrideData is not NULL.
 919   @retval EFI_UNSUPPORTED        One or more options in the Token.OptionList are in the
 920                                  unsupported list of structure EFI_MTFTP4_MODE_DATA.
 921   @retval EFI_NOT_STARTED        The EFI MTFTPv4 Protocol driver has not been started.
 922   @retval EFI_NO_MAPPING         When using a default address, configuration (DHCP,
 923                                  BOOTP, RARP, etc.) is not finished yet.
 924   @retval EFI_ALREADY_STARTED    This Token is already being used in another MTFTPv4
 925                                  session.
 926   @retval EFI_OUT_OF_RESOURCES   Required system resources could not be allocated.
 927   @retval EFI_ACCESS_DENIED      The previous operation has not completed yet.
 928   @retval EFI_DEVICE_ERROR       An unexpected network error or system error occurred.
 929
 930 **/
 931 EFI_STATUS
 932 EFIAPI
 933 EfiMtftp4ReadDirectory (
 934   IN EFI_MTFTP4_PROTOCOL        *This,
 935   IN EFI_MTFTP4_TOKEN           *Token
 936   )
 937 {
 938   return Mtftp4Start (This, Token, EFI_MTFTP4_OPCODE_DIR);
 939 }
 940
 941
 942 /**
 943   Gets information about a file from an MTFTPv4 server.
 944
 945   The GetInfo() function assembles an MTFTPv4 request packet with options;
 946   sends it to the MTFTPv4 server; and may return an MTFTPv4 OACK, MTFTPv4 ERROR,
 947   or ICMP ERROR packet. Retries occur only if no response packets are received
 948   from the MTFTPv4 server before the timeout expires.
 949   It is implemented with EfiMtftp4ReadFile: build a token, then pass it to
 950   EfiMtftp4ReadFile. In its check packet callback abort the opertions.
 951
 952   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance
 953   @param  OverrideData           Data that is used to override the existing
 954                                  parameters. If NULL, the default parameters that
 955                                  were set in the EFI_MTFTP4_PROTOCOL.Configure()
 956                                  function are used
 957   @param  Filename               Pointer to null-terminated ASCII file name string
 958   @param  ModeStr                Pointer to null-terminated ASCII mode string. If NULL, "octet"
 959                                  will be used
 960   @param  OptionCount            Number of option/value string pairs in OptionList
 961   @param  OptionList             Pointer to array of option/value string pairs.
 962                                  Ignored if OptionCount is zero
 963   @param  PacketLength           The number of bytes in the returned packet
 964   @param  Packet                 PacketThe pointer to the received packet. This
 965                                  buffer must be freed by the caller.
 966
 967   @retval EFI_SUCCESS            An MTFTPv4 OACK packet was received and is in
 968                                  the Buffer.
 969   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is TRUE:
 970                                  1.This is NULL.
 971                                  2.Filename is NULL.
 972                                  3.OptionCount is not zero and OptionList is NULL.
 973                                  4.One or more options in OptionList have wrong format.
 974                                  5.PacketLength is NULL.
 975                                  6.One or more IPv4 addresses in OverrideData are
 976                                    not valid unicast IPv4 addresses if OverrideData
 977                                    is not NULL.
 978   @retval EFI_UNSUPPORTED        One or more options in the OptionList are in the
 979                                  unsupported list of structure EFI_MTFTP4_MODE_DATA
 980   @retval EFI_NOT_STARTED        The EFI MTFTPv4 Protocol driver has not been started.
 981   @retval EFI_NO_MAPPING         When using a default address, configuration (DHCP,
 982                                  BOOTP, RARP, etc.) has not finished yet.
 983   @retval EFI_ACCESS_DENIED      The previous operation has not completed yet.
 984   @retval EFI_OUT_OF_RESOURCES   Required system resources could not be allocated.
 985   @retval EFI_TFTP_ERROR         An MTFTPv4 ERROR packet was received and is in
 986                                  the Buffer.
 987   @retval EFI_ICMP_ERROR         An ICMP ERROR packet was received and the Packet
 988                                  is set to NULL.
 989   @retval EFI_PROTOCOL_ERROR     An unexpected MTFTPv4 packet was received and is
 990                                  in the Buffer.
 991   @retval EFI_TIMEOUT            No responses were received from the MTFTPv4 server.
 992   @retval EFI_DEVICE_ERROR       An unexpected network error or system error occurred.
 993   @retval EFI_NO_MEDIA           There was a media error.
 994
 995 **/
 996 EFI_STATUS
 997 EFIAPI
 998 EfiMtftp4GetInfo (
 999   IN     EFI_MTFTP4_PROTOCOL      *This,
1000   IN     EFI_MTFTP4_OVERRIDE_DATA *OverrideData        OPTIONAL,
1001   IN     UINT8                    *Filename,
1002   IN     UINT8                    *ModeStr             OPTIONAL,
1003   IN     UINT8                    OptionCount,
1004   IN     EFI_MTFTP4_OPTION        *OptionList          OPTIONAL,
1005      OUT UINT32                   *PacketLength,
1006      OUT EFI_MTFTP4_PACKET        **Packet             OPTIONAL
1007   )
1008 {
1009   EFI_MTFTP4_TOKEN          Token;
1010   MTFTP4_GETINFO_STATE      State;
1011   EFI_STATUS                Status;
1012
1013   if ((This == NULL) || (Filename == NULL) || (PacketLength == NULL) ||
1014       ((OptionCount != 0) && (OptionList == NULL))) {
1015     return EFI_INVALID_PARAMETER;
1016   }
1017
1018   if (Packet != NULL) {
1019     *Packet = NULL;
1020   }
1021
1022   *PacketLength         = 0;
1023   State.Packet          = Packet;
1024   State.PacketLen       = PacketLength;
1025   State.Status          = EFI_SUCCESS;
1026
1027   //
1028   // Fill in the Token to issue an synchronous ReadFile operation
1029   //
1030   Token.Status          = EFI_SUCCESS;
1031   Token.Event           = NULL;
1032   Token.OverrideData    = OverrideData;
1033   Token.Filename        = Filename;
1034   Token.ModeStr         = ModeStr;
1035   Token.OptionCount     = OptionCount;
1036   Token.OptionList      = OptionList;
1037   Token.BufferSize      = 0;
1038   Token.Buffer          = NULL;
1039   Token.Context         = &State;
1040   Token.CheckPacket     = Mtftp4GetInfoCheckPacket;
1041   Token.TimeoutCallback = NULL;
1042   Token.PacketNeeded    = NULL;
1043
1044   Status                = EfiMtftp4ReadFile (This, &Token);
1045
1046   if (EFI_ABORTED == Status) {
1047     return State.Status;
1048   }
1049
1050   return Status;
1051 }
1052
1053 /**
1054   Polls for incoming data packets and processes outgoing data packets.
1055
1056   The Poll() function can be used by network drivers and applications to increase
1057   the rate that data packets are moved between the communications device and the
1058   transmit and receive queues.
1059   In some systems, the periodic timer event in the managed network driver may not
1060   poll the underlying communications device fast enough to transmit and/or receive
1061   all data packets without missing incoming packets or dropping outgoing packets.
1062   Drivers and applications that are experiencing packet loss should try calling
1063   the Poll() function more often.
1064
1065   @param  This                   Pointer to the EFI_MTFTP4_PROTOCOL instance
1066
1067   @retval EFI_SUCCESS            Incoming or outgoing data was processed.
1068   @retval EFI_NOT_STARTED        This EFI MTFTPv4 Protocol instance has not been started.
1069   @retval EFI_NO_MAPPING         When using a default address, configuration (DHCP,
1070                                  BOOTP, RARP, etc.) is not finished yet.
1071   @retval EFI_INVALID_PARAMETER  This is NULL.
1072   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
1073   @retval EFI_TIMEOUT            Data was dropped out of the transmit and/or receive
1074                                  queue. Consider increasing the polling rate.
1075
1076 **/
1077 EFI_STATUS
1078 EFIAPI
1079 EfiMtftp4Poll (
1080   IN EFI_MTFTP4_PROTOCOL    *This
1081   )
1082 {
1083   MTFTP4_PROTOCOL           *Instance;
1084   EFI_UDP4_PROTOCOL         *Udp;
1085   EFI_STATUS                Status;
1086
1087   if (This == NULL) {
1088     return EFI_INVALID_PARAMETER;
1089   }
1090
1091   Instance = MTFTP4_PROTOCOL_FROM_THIS (This);
1092
1093   if (Instance->State == MTFTP4_STATE_UNCONFIGED) {
1094     return EFI_NOT_STARTED;
1095   } else if (Instance->State == MTFTP4_STATE_DESTROY) {
1096     return EFI_DEVICE_ERROR;
1097   }
1098
1099   Udp = Instance->UnicastPort->Protocol.Udp4;
1100   Status = Udp->Poll (Udp);
1101   Mtftp4OnTimerTick (NULL, Instance->Service);
1102   return Status;
1103 }
1104
1105 EFI_MTFTP4_PROTOCOL gMtftp4ProtocolTemplate = {
1106   EfiMtftp4GetModeData,
1107   EfiMtftp4Configure,
1108   EfiMtftp4GetInfo,
1109   EfiMtftp4ParseOptions,
1110   EfiMtftp4ReadFile,
1111   EfiMtftp4WriteFile,
1112   EfiMtftp4ReadDirectory,
1113   EfiMtftp4Poll
1114 };