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