MdeModulePkg/Universal/Network/MnpDxe/MnpMain.c

   1 /** @file
   2   Implementation of Managed Network Protocol public services.
   3
   4 Copyright (c) 2005 - 2016, Intel Corporation. All rights reserved.<BR>
   5 This program and the accompanying materials
   6 are licensed and made available under the terms and conditions
   7 of the BSD License which accompanies this distribution.  The full
   8 text of the license may be found at<BR>
   9 http://opensource.org/licenses/bsd-license.php
  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 #include "MnpImpl.h"
  17
  18 /**
  19   Returns the operational parameters for the current MNP child driver. May also
  20   support returning the underlying SNP driver mode data.
  21
  22   The GetModeData() function is used to read the current mode data (operational
  23   parameters) from the MNP or the underlying SNP.
  24
  25   @param[in]  This          Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
  26   @param[out] MnpConfigData Pointer to storage for MNP operational parameters. Type
  27                             EFI_MANAGED_NETWORK_CONFIG_DATA is defined in "Related
  28                             Definitions" below.
  29   @param[out] SnpModeData   Pointer to storage for SNP operational parameters. This
  30                             feature may be unsupported. Type EFI_SIMPLE_NETWORK_MODE
  31                             is defined in the EFI_SIMPLE_NETWORK_PROTOCOL.
  32
  33   @retval EFI_SUCCESS           The operation completed successfully.
  34   @retval EFI_INVALID_PARAMETER This is NULL.
  35   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this
  36                                 MNP implementation.
  37   @retval EFI_NOT_STARTED       This MNP child driver instance has not been
  38                                 configured. The default values are returned in
  39                                 MnpConfigData if it is not NULL.
  40   @retval Others                The mode data could not be read.
  41
  42 **/
  43 EFI_STATUS
  44 EFIAPI
  45 MnpGetModeData (
  46   IN     EFI_MANAGED_NETWORK_PROTOCOL      *This,
  47      OUT EFI_MANAGED_NETWORK_CONFIG_DATA   *MnpConfigData OPTIONAL,
  48      OUT EFI_SIMPLE_NETWORK_MODE           *SnpModeData OPTIONAL
  49   )
  50 {
  51   MNP_INSTANCE_DATA           *Instance;
  52   EFI_SIMPLE_NETWORK_PROTOCOL *Snp;
  53   EFI_TPL                     OldTpl;
  54   EFI_STATUS                  Status;
  55   UINT32                      InterruptStatus;
  56
  57   if (This == NULL) {
  58     return EFI_INVALID_PARAMETER;
  59   }
  60
  61   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
  62
  63   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
  64
  65   if (MnpConfigData != NULL) {
  66     //
  67     // Copy the instance configuration data.
  68     //
  69     CopyMem (MnpConfigData, &Instance->ConfigData, sizeof (*MnpConfigData));
  70   }
  71
  72   if (SnpModeData != NULL) {
  73     //
  74     // Copy the underlayer Snp mode data.
  75     //
  76     Snp = Instance->MnpServiceData->MnpDeviceData->Snp;
  77
  78     //
  79     // Upon successful return of GetStatus(), the Snp->Mode->MediaPresent
  80     // will be updated to reflect any change of media status
  81     //
  82     Snp->GetStatus (Snp, &InterruptStatus, NULL);
  83     CopyMem (SnpModeData, Snp->Mode, sizeof (*SnpModeData));
  84   }
  85
  86   if (!Instance->Configured) {
  87     Status = EFI_NOT_STARTED;
  88   } else {
  89     Status = EFI_SUCCESS;
  90   }
  91
  92   gBS->RestoreTPL (OldTpl);
  93
  94   return Status;
  95 }
  96
  97
  98 /**
  99   Sets or clears the operational parameters for the MNP child driver.
 100
 101   The Configure() function is used to set, change, or reset the operational
 102   parameters for the MNP child driver instance. Until the operational parameters
 103   have been set, no network traffic can be sent or received by this MNP child
 104   driver instance. Once the operational parameters have been reset, no more
 105   traffic can be sent or received until the operational parameters have been set
 106   again.
 107   Each MNP child driver instance can be started and stopped independently of
 108   each other by setting or resetting their receive filter settings with the
 109   Configure() function.
 110   After any successful call to Configure(), the MNP child driver instance is
 111   started. The internal periodic timer (if supported) is enabled. Data can be
 112   transmitted and may be received if the receive filters have also been enabled.
 113   Note: If multiple MNP child driver instances will receive the same packet
 114   because of overlapping receive filter settings, then the first MNP child
 115   driver instance will receive the original packet and additional instances will
 116   receive copies of the original packet.
 117   Note: Warning: Receive filter settings that overlap will consume extra
 118   processor and/or DMA resources and degrade system and network performance.
 119
 120   @param[in]  This           Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 121   @param[in]  MnpConfigData  Pointer to configuration data that will be assigned
 122                              to the MNP child driver instance. If NULL, the MNP
 123                              child driver instance is reset to startup defaults
 124                              and all pending transmit and receive requests are
 125                              flushed. Type EFI_MANAGED_NETWORK_CONFIG_DATA is
 126                              defined in EFI_MANAGED_NETWORK_PROTOCOL.GetModeData().
 127
 128   @retval EFI_SUCCESS            The operation completed successfully.
 129   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is
 130                                  TRUE:
 131                                  * This is NULL.
 132                                  * MnpConfigData.ProtocolTypeFilter is not
 133                                    valid.
 134                                  The operational data for the MNP child driver
 135                                  instance is unchanged.
 136   @retval EFI_OUT_OF_RESOURCES   Required system resources (usually memory)
 137                                  could not be allocated.
 138                                  The MNP child driver instance has been reset to
 139                                  startup defaults.
 140   @retval EFI_UNSUPPORTED        The requested feature is unsupported in
 141                                  this [MNP] implementation. The operational data
 142                                  for the MNP child driver instance is unchanged.
 143   @retval EFI_DEVICE_ERROR       An unexpected network or system error
 144                                  occurred. The MNP child driver instance has
 145                                  been reset to startup defaults.
 146   @retval Others                 The MNP child driver instance has been reset to
 147                                  startup defaults.
 148
 149 **/
 150 EFI_STATUS
 151 EFIAPI
 152 MnpConfigure (
 153   IN EFI_MANAGED_NETWORK_PROTOCOL        *This,
 154   IN EFI_MANAGED_NETWORK_CONFIG_DATA     *MnpConfigData OPTIONAL
 155   )
 156 {
 157   MNP_INSTANCE_DATA  *Instance;
 158   EFI_TPL            OldTpl;
 159   EFI_STATUS         Status;
 160
 161   if ((This == NULL) ||
 162       ((MnpConfigData != NULL) &&
 163        (MnpConfigData->ProtocolTypeFilter > 0) &&
 164        (MnpConfigData->ProtocolTypeFilter <= 1500))
 165      ) {
 166     return EFI_INVALID_PARAMETER;
 167   }
 168
 169   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
 170
 171   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 172
 173   if ((MnpConfigData == NULL) && (!Instance->Configured)) {
 174     //
 175     // If the instance is not configured and a reset is requested, just return.
 176     //
 177     Status = EFI_SUCCESS;
 178     goto ON_EXIT;
 179   }
 180
 181   //
 182   // Configure the instance.
 183   //
 184   Status = MnpConfigureInstance (Instance, MnpConfigData);
 185
 186 ON_EXIT:
 187   gBS->RestoreTPL (OldTpl);
 188
 189   return Status;
 190 }
 191
 192
 193 /**
 194   Translates an IP multicast address to a hardware (MAC) multicast address. This
 195   function may be unsupported in some MNP implementations.
 196
 197   The McastIpToMac() function translates an IP multicast address to a hardware
 198   (MAC) multicast address. This function may be implemented by calling the
 199   underlying EFI_SIMPLE_NETWORK. MCastIpToMac() function, which may also be
 200   unsupported in some MNP implementations.
 201
 202   @param[in]  This        Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 203   @param[in]  Ipv6Flag    Set to TRUE to if IpAddress is an IPv6 multicast address.
 204                           Set to FALSE if IpAddress is an IPv4 multicast address.
 205   @param[in]  IpAddress   Pointer to the multicast IP address (in network byte
 206                           order) to convert.
 207   @param[out] MacAddress  Pointer to the resulting multicast MAC address.
 208
 209   @retval EFI_SUCCESS           The operation completed successfully.
 210   @retval EFI_INVALID_PARAMETER One of the following conditions is TRUE:
 211                                  * This is NULL.
 212                                  * IpAddress is NULL.
 213                                  * IpAddress is not a valid multicast IP
 214                                    address.
 215                                  * MacAddress is NULL.
 216   @retval EFI_NOT_STARTED       This MNP child driver instance has not been
 217                                 configured.
 218   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this
 219                                 MNP implementation.
 220   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 221   @retval Others                The address could not be converted.
 222 **/
 223 EFI_STATUS
 224 EFIAPI
 225 MnpMcastIpToMac (
 226   IN     EFI_MANAGED_NETWORK_PROTOCOL    *This,
 227   IN     BOOLEAN                         Ipv6Flag,
 228   IN     EFI_IP_ADDRESS                  *IpAddress,
 229      OUT EFI_MAC_ADDRESS                 *MacAddress
 230   )
 231 {
 232   EFI_STATUS                  Status;
 233   MNP_INSTANCE_DATA           *Instance;
 234   EFI_SIMPLE_NETWORK_PROTOCOL *Snp;
 235   EFI_TPL                     OldTpl;
 236   EFI_IPv6_ADDRESS            *Ip6Address;
 237
 238   if ((This == NULL) || (IpAddress == NULL) || (MacAddress == NULL)) {
 239     return EFI_INVALID_PARAMETER;
 240   }
 241
 242   Ip6Address = &IpAddress->v6;
 243
 244   if ((Ipv6Flag && !IP6_IS_MULTICAST (Ip6Address)) ||
 245       (!Ipv6Flag && !IP4_IS_MULTICAST (EFI_NTOHL (*IpAddress)))
 246       ) {
 247     //
 248     // The IP address passed in is not a multicast address.
 249     //
 250     return EFI_INVALID_PARAMETER;
 251   }
 252
 253   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
 254
 255   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 256
 257   if (!Instance->Configured) {
 258
 259     Status = EFI_NOT_STARTED;
 260     goto ON_EXIT;
 261   }
 262
 263   Snp = Instance->MnpServiceData->MnpDeviceData->Snp;
 264   ASSERT (Snp != NULL);
 265
 266   ZeroMem (MacAddress, sizeof (EFI_MAC_ADDRESS));
 267
 268   if (Snp->Mode->IfType == NET_IFTYPE_ETHERNET) {
 269     if (!Ipv6Flag) {
 270       //
 271       // Translate the IPv4 address into a multicast MAC address if the NIC is an
 272       // ethernet NIC according to RFC1112..
 273       //
 274       MacAddress->Addr[0] = 0x01;
 275       MacAddress->Addr[1] = 0x00;
 276       MacAddress->Addr[2] = 0x5E;
 277       MacAddress->Addr[3] = (UINT8) (IpAddress->v4.Addr[1] & 0x7F);
 278       MacAddress->Addr[4] = IpAddress->v4.Addr[2];
 279       MacAddress->Addr[5] = IpAddress->v4.Addr[3];
 280     } else {
 281       //
 282       // Translate the IPv6 address into a multicast MAC address if the NIC is an
 283       // ethernet NIC according to RFC2464.
 284       //
 285
 286       MacAddress->Addr[0] = 0x33;
 287       MacAddress->Addr[1] = 0x33;
 288       MacAddress->Addr[2] = Ip6Address->Addr[12];
 289       MacAddress->Addr[3] = Ip6Address->Addr[13];
 290       MacAddress->Addr[4] = Ip6Address->Addr[14];
 291       MacAddress->Addr[5] = Ip6Address->Addr[15];
 292     }
 293
 294     Status = EFI_SUCCESS;
 295   } else {
 296     //
 297     // Invoke Snp to translate the multicast IP address.
 298     //
 299     Status = Snp->MCastIpToMac (
 300                     Snp,
 301                     Ipv6Flag,
 302                     IpAddress,
 303                     MacAddress
 304                     );
 305   }
 306
 307 ON_EXIT:
 308   gBS->RestoreTPL (OldTpl);
 309
 310   return Status;
 311 }
 312
 313 /**
 314   Enables and disables receive filters for multicast address. This function may
 315   be unsupported in some MNP implementations.
 316
 317   The Groups() function only adds and removes multicast MAC addresses from the
 318   filter list. The MNP driver does not transmit or process Internet Group
 319   Management Protocol (IGMP) packets. If JoinFlag is FALSE and MacAddress is
 320   NULL, then all joined groups are left.
 321
 322   @param[in]  This        Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 323   @param[in]  JoinFlag    Set to TRUE to join this multicast group.
 324                           Set to FALSE to leave this multicast group.
 325   @param[in]  MacAddress  Pointer to the multicast MAC group (address) to join or
 326                           leave.
 327
 328   @retval EFI_SUCCESS           The requested operation completed successfully.
 329   @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
 330                                 * This is NULL.
 331                                 * JoinFlag is TRUE and MacAddress is NULL.
 332                                 * MacAddress is not a valid multicast MAC
 333                                   address.
 334                                 * The MNP multicast group settings are
 335                                   unchanged.
 336   @retval EFI_NOT_STARTED       This MNP child driver instance has not been
 337                                 configured.
 338   @retval EFI_ALREADY_STARTED   The supplied multicast group is already joined.
 339   @retval EFI_NOT_FOUND         The supplied multicast group is not joined.
 340   @retval EFI_DEVICE_ERROR      An unexpected network or system error occurred.
 341                                 The MNP child driver instance has been reset to
 342                                 startup defaults.
 343   @retval EFI_UNSUPPORTED       The requested feature is unsupported in this MNP
 344                                 implementation.
 345   @retval Others                The requested operation could not be completed.
 346                                 The MNP multicast group settings are unchanged.
 347
 348 **/
 349 EFI_STATUS
 350 EFIAPI
 351 MnpGroups (
 352   IN EFI_MANAGED_NETWORK_PROTOCOL    *This,
 353   IN BOOLEAN                         JoinFlag,
 354   IN EFI_MAC_ADDRESS                 *MacAddress OPTIONAL
 355   )
 356 {
 357   MNP_INSTANCE_DATA       *Instance;
 358   EFI_SIMPLE_NETWORK_MODE *SnpMode;
 359   MNP_GROUP_CONTROL_BLOCK *GroupCtrlBlk;
 360   MNP_GROUP_ADDRESS       *GroupAddress;
 361   LIST_ENTRY              *ListEntry;
 362   BOOLEAN                 AddressExist;
 363   EFI_TPL                 OldTpl;
 364   EFI_STATUS              Status;
 365
 366   if (This == NULL || (JoinFlag && (MacAddress == NULL))) {
 367     //
 368     // This is NULL, or it's a join operation but MacAddress is NULL.
 369     //
 370     return EFI_INVALID_PARAMETER;
 371   }
 372
 373   Instance  = MNP_INSTANCE_DATA_FROM_THIS (This);
 374   SnpMode   = Instance->MnpServiceData->MnpDeviceData->Snp->Mode;
 375
 376   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 377
 378   if (!Instance->Configured) {
 379     Status = EFI_NOT_STARTED;
 380     goto ON_EXIT;
 381   }
 382
 383   if ((!Instance->ConfigData.EnableMulticastReceive) ||
 384     ((MacAddress != NULL) && !NET_MAC_IS_MULTICAST (MacAddress, &SnpMode->BroadcastAddress, SnpMode->HwAddressSize))) {
 385     //
 386     // The instance isn't configured to do mulitcast receive. OR
 387     // the passed in MacAddress is not a mutlticast mac address.
 388     //
 389     Status = EFI_INVALID_PARAMETER;
 390     goto ON_EXIT;
 391   }
 392
 393   Status       = EFI_SUCCESS;
 394   AddressExist = FALSE;
 395   GroupCtrlBlk = NULL;
 396
 397   if (MacAddress != NULL) {
 398     //
 399     // Search the instance's GroupCtrlBlkList to find the specific address.
 400     //
 401     NET_LIST_FOR_EACH (ListEntry, &Instance->GroupCtrlBlkList) {
 402
 403       GroupCtrlBlk = NET_LIST_USER_STRUCT (
 404                       ListEntry,
 405                       MNP_GROUP_CONTROL_BLOCK,
 406                       CtrlBlkEntry
 407                       );
 408       GroupAddress = GroupCtrlBlk->GroupAddress;
 409       if (0 == CompareMem (
 410                 MacAddress,
 411                 &GroupAddress->Address,
 412                 SnpMode->HwAddressSize
 413                 )) {
 414         //
 415         // There is already the same multicast mac address configured.
 416         //
 417         AddressExist = TRUE;
 418         break;
 419       }
 420     }
 421
 422     if (JoinFlag && AddressExist) {
 423       //
 424       // The multicast mac address to join already exists.
 425       //
 426       Status = EFI_ALREADY_STARTED;
 427     }
 428
 429     if (!JoinFlag && !AddressExist) {
 430       //
 431       // The multicast mac address to leave doesn't exist in this instance.
 432       //
 433       Status = EFI_NOT_FOUND;
 434     }
 435
 436     if (EFI_ERROR (Status)) {
 437       goto ON_EXIT;
 438     }
 439   } else if (IsListEmpty (&Instance->GroupCtrlBlkList)) {
 440     //
 441     // The MacAddress is NULL and there is no configured multicast mac address,
 442     // just return.
 443     //
 444     goto ON_EXIT;
 445   }
 446
 447   //
 448   // OK, it is time to take action.
 449   //
 450   Status = MnpGroupOp (Instance, JoinFlag, MacAddress, GroupCtrlBlk);
 451
 452 ON_EXIT:
 453   gBS->RestoreTPL (OldTpl);
 454
 455   return Status;
 456 }
 457
 458 /**
 459   Places asynchronous outgoing data packets into the transmit queue.
 460
 461   The Transmit() function places a completion token into the transmit packet
 462   queue. This function is always asynchronous.
 463   The caller must fill in the Token.Event and Token.TxData fields in the
 464   completion token, and these fields cannot be NULL. When the transmit operation
 465   completes, the MNP updates the Token.Status field and the Token.Event is
 466   signaled.
 467   Note: There may be a performance penalty if the packet needs to be
 468   defragmented before it can be transmitted by the network device. Systems in
 469   which performance is critical should review the requirements and features of
 470   the underlying communications device and drivers.
 471
 472
 473   @param[in]  This    Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 474   @param[in]  Token   Pointer to a token associated with the transmit data
 475                       descriptor. Type EFI_MANAGED_NETWORK_COMPLETION_TOKEN
 476                       is defined in "Related Definitions" below.
 477
 478   @retval EFI_SUCCESS            The transmit completion token was cached.
 479   @retval EFI_NOT_STARTED        This MNP child driver instance has not been
 480                                  configured.
 481   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is
 482                                  TRUE:
 483                                  * This is NULL.
 484                                  * Token is NULL.
 485                                  * Token.Event is NULL.
 486                                  * Token.TxData is NULL.
 487                                  * Token.TxData.DestinationAddress is not
 488                                    NULL and Token.TxData.HeaderLength is zero.
 489                                  * Token.TxData.FragmentCount is zero.
 490                                  * (Token.TxData.HeaderLength +
 491                                    Token.TxData.DataLength) is not equal to the
 492                                    sum of the
 493                                    Token.TxData.FragmentTable[].FragmentLength
 494                                    fields.
 495                                  * One or more of the
 496                                    Token.TxData.FragmentTable[].FragmentLength
 497                                    fields is zero.
 498                                  * One or more of the
 499                                    Token.TxData.FragmentTable[].FragmentBufferfields
 500                                    is NULL.
 501                                  * Token.TxData.DataLength is greater than MTU.
 502   @retval EFI_ACCESS_DENIED      The transmit completion token is already in the
 503                                  transmit queue.
 504   @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a
 505                                  lack of system resources (usually memory).
 506   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 507                                  The MNP child driver instance has been reset to
 508                                  startup defaults.
 509   @retval EFI_NOT_READY          The transmit request could not be queued because
 510                                  the transmit queue is full.
 511
 512 **/
 513 EFI_STATUS
 514 EFIAPI
 515 MnpTransmit (
 516   IN EFI_MANAGED_NETWORK_PROTOCOL            *This,
 517   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token
 518   )
 519 {
 520   EFI_STATUS        Status;
 521   MNP_INSTANCE_DATA *Instance;
 522   MNP_SERVICE_DATA  *MnpServiceData;
 523   UINT8             *PktBuf;
 524   UINT32            PktLen;
 525   EFI_TPL           OldTpl;
 526
 527   if ((This == NULL) || (Token == NULL)) {
 528     return EFI_INVALID_PARAMETER;
 529   }
 530
 531   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
 532
 533   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 534
 535   if (!Instance->Configured) {
 536
 537     Status = EFI_NOT_STARTED;
 538     goto ON_EXIT;
 539   }
 540
 541   if (!MnpIsValidTxToken (Instance, Token)) {
 542     //
 543     // The Token is invalid.
 544     //
 545     Status = EFI_INVALID_PARAMETER;
 546     goto ON_EXIT;
 547   }
 548
 549   MnpServiceData = Instance->MnpServiceData;
 550   NET_CHECK_SIGNATURE (MnpServiceData, MNP_SERVICE_DATA_SIGNATURE);
 551
 552   //
 553   // Build the tx packet
 554   //
 555   Status = MnpBuildTxPacket (MnpServiceData, Token->Packet.TxData, &PktBuf, &PktLen);
 556   if (EFI_ERROR (Status)) {
 557     goto ON_EXIT;
 558   }
 559
 560   //
 561   //  OK, send the packet synchronously.
 562   //
 563   Status = MnpSyncSendPacket (MnpServiceData, PktBuf, PktLen, Token);
 564
 565 ON_EXIT:
 566   gBS->RestoreTPL (OldTpl);
 567
 568   return Status;
 569 }
 570
 571
 572 /**
 573   Places an asynchronous receiving request into the receiving queue.
 574
 575   The Receive() function places a completion token into the receive packet
 576   queue. This function is always asynchronous.
 577   The caller must fill in the Token.Event field in the completion token, and
 578   this field cannot be NULL. When the receive operation completes, the MNP
 579   updates the Token.Status and Token.RxData fields and the Token.Event is
 580   signaled.
 581
 582   @param[in]  This      Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 583   @param[in]  Token     Pointer to a token associated with the receive
 584                         data descriptor. Type
 585                         EFI_MANAGED_NETWORK_COMPLETION_TOKEN is defined in
 586                         EFI_MANAGED_NETWORK_PROTOCOL.Transmit().
 587
 588   @retval EFI_SUCCESS            The receive completion token was cached.
 589   @retval EFI_NOT_STARTED        This MNP child driver instance has not been
 590                                  configured.
 591   @retval EFI_INVALID_PARAMETER  One or more of the following conditions is
 592                                  TRUE:
 593                                  * This is NULL.
 594                                  * Token is NULL.
 595                                  * Token.Event is NULL
 596   @retval EFI_OUT_OF_RESOURCES   The transmit data could not be queued due to a
 597                                  lack of system resources (usually memory).
 598   @retval EFI_DEVICE_ERROR       An unexpected system or network error occurred.
 599                                  The MNP child driver instance has been reset to
 600                                  startup defaults.
 601   @retval EFI_ACCESS_DENIED      The receive completion token was already in the
 602                                  receive queue.
 603   @retval EFI_NOT_READY          The receive request could not be queued because
 604                                  the receive queue is full.
 605
 606 **/
 607 EFI_STATUS
 608 EFIAPI
 609 MnpReceive (
 610   IN EFI_MANAGED_NETWORK_PROTOCOL            *This,
 611   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token
 612   )
 613 {
 614   EFI_STATUS         Status;
 615   MNP_INSTANCE_DATA  *Instance;
 616   EFI_TPL            OldTpl;
 617
 618   if ((This == NULL) || (Token == NULL) || (Token->Event == NULL)) {
 619     return EFI_INVALID_PARAMETER;
 620   }
 621
 622   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
 623
 624   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 625
 626   if (!Instance->Configured) {
 627     Status = EFI_NOT_STARTED;
 628     goto ON_EXIT;
 629   }
 630
 631   //
 632   // Check whether this token(event) is already in the rx token queue.
 633   //
 634   Status = NetMapIterate (&Instance->RxTokenMap, MnpTokenExist, (VOID *) Token);
 635   if (EFI_ERROR (Status)) {
 636     goto ON_EXIT;
 637   }
 638
 639   //
 640   // Insert the Token into the RxTokenMap.
 641   //
 642   Status = NetMapInsertTail (&Instance->RxTokenMap, (VOID *) Token, NULL);
 643   if (!EFI_ERROR (Status)) {
 644     //
 645     // Try to deliver any buffered packets.
 646     //
 647     Status = MnpInstanceDeliverPacket (Instance);
 648
 649     //
 650     // Dispatch the DPC queued by the NotifyFunction of Token->Event.
 651     //
 652     DispatchDpc ();
 653   }
 654
 655 ON_EXIT:
 656   gBS->RestoreTPL (OldTpl);
 657
 658   return Status;
 659 }
 660
 661 /**
 662   Aborts an asynchronous transmit or receive request.
 663
 664   The Cancel() function is used to abort a pending transmit or receive request.
 665   If the token is in the transmit or receive request queues, after calling this
 666   function, Token.Status will be set to EFI_ABORTED and then Token.Event will be
 667   signaled. If the token is not in one of the queues, which usually means that
 668   the asynchronous operation has completed, this function will not signal the
 669   token and EFI_NOT_FOUND is returned.
 670
 671   @param[in]  This     Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 672   @param[in]  Token    Pointer to a token that has been issued by
 673                        EFI_MANAGED_NETWORK_PROTOCOL.Transmit() or
 674                        EFI_MANAGED_NETWORK_PROTOCOL.Receive(). If NULL, all
 675                        pending tokens are aborted.
 676
 677   @retval EFI_SUCCESS            The asynchronous I/O request was aborted and
 678                                  Token.Event was signaled. When Token is NULL,
 679                                  all pending requests were aborted and their
 680                                  events were signaled.
 681   @retval EFI_NOT_STARTED        This MNP child driver instance has not been
 682                                  configured.
 683   @retval EFI_INVALID_PARAMETER  This is NULL.
 684   @retval EFI_NOT_FOUND          When Token is not NULL, the asynchronous I/O
 685                                  request was not found in the transmit or
 686                                  receive queue. It has either completed or was
 687                                  not issued by Transmit() and Receive().
 688
 689 **/
 690 EFI_STATUS
 691 EFIAPI
 692 MnpCancel (
 693   IN EFI_MANAGED_NETWORK_PROTOCOL            *This,
 694   IN EFI_MANAGED_NETWORK_COMPLETION_TOKEN    *Token OPTIONAL
 695   )
 696 {
 697   EFI_STATUS         Status;
 698   MNP_INSTANCE_DATA  *Instance;
 699   EFI_TPL            OldTpl;
 700
 701   if (This == NULL) {
 702     return EFI_INVALID_PARAMETER;
 703   }
 704
 705   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
 706
 707   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 708
 709   if (!Instance->Configured) {
 710     Status = EFI_NOT_STARTED;
 711     goto ON_EXIT;
 712   }
 713
 714   //
 715   // Iterate the RxTokenMap to cancel the specified Token.
 716   //
 717   Status = NetMapIterate (&Instance->RxTokenMap, MnpCancelTokens, (VOID *) Token);
 718   if (Token != NULL) {
 719     Status = (Status == EFI_ABORTED) ? EFI_SUCCESS : EFI_NOT_FOUND;
 720   }
 721
 722   //
 723   // Dispatch the DPC queued by the NotifyFunction of the cancled token's events.
 724   //
 725   DispatchDpc ();
 726
 727 ON_EXIT:
 728   gBS->RestoreTPL (OldTpl);
 729
 730   return Status;
 731 }
 732
 733 /**
 734   Polls for incoming data packets and processes outgoing data packets.
 735
 736   The Poll() function can be used by network drivers and applications to
 737   increase the rate that data packets are moved between the communications
 738   device and the transmit and receive queues.
 739   Normally, a periodic timer event internally calls the Poll() function. But, in
 740   some systems, the periodic timer event may not call Poll() fast enough to
 741   transmit and/or receive all data packets without missing packets. Drivers and
 742   applications that are experiencing packet loss should try calling the Poll()
 743   function more often.
 744
 745   @param[in]  This         Pointer to the EFI_MANAGED_NETWORK_PROTOCOL instance.
 746
 747   @retval EFI_SUCCESS      Incoming or outgoing data was processed.
 748   @retval EFI_NOT_STARTED  This MNP child driver instance has not been
 749                            configured.
 750   @retval EFI_DEVICE_ERROR An unexpected system or network error occurred. The
 751                            MNP child driver instance has been reset to startup
 752                            defaults.
 753   @retval EFI_NOT_READY    No incoming or outgoing data was processed. Consider
 754                            increasing the polling rate.
 755   @retval EFI_TIMEOUT      Data was dropped out of the transmit and/or receive
 756                            queue. Consider increasing the polling rate.
 757
 758 **/
 759 EFI_STATUS
 760 EFIAPI
 761 MnpPoll (
 762   IN EFI_MANAGED_NETWORK_PROTOCOL    *This
 763   )
 764 {
 765   EFI_STATUS         Status;
 766   MNP_INSTANCE_DATA  *Instance;
 767   EFI_TPL            OldTpl;
 768
 769   if (This == NULL) {
 770     return EFI_INVALID_PARAMETER;
 771   }
 772
 773   Instance = MNP_INSTANCE_DATA_FROM_THIS (This);
 774
 775   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 776
 777   if (!Instance->Configured) {
 778     Status = EFI_NOT_STARTED;
 779     goto ON_EXIT;
 780   }
 781
 782   //
 783   // Try to receive packets.
 784   //
 785   Status = MnpReceivePacket (Instance->MnpServiceData->MnpDeviceData);
 786
 787   //
 788   // Dispatch the DPC queued by the NotifyFunction of rx token's events.
 789   //
 790   DispatchDpc ();
 791
 792 ON_EXIT:
 793   gBS->RestoreTPL (OldTpl);
 794
 795   return Status;
 796 }