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