[mirror_edk2.git] / NetworkPkg / Ip4Dxe / Ip4If.c

/** @file\r
  Implement IP4 pseudo interface.\r
\r
Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include "Ip4Impl.h"\r
\r
//\r
// Mac address with all zero, used to determine whether the ARP\r
// resolve succeeded. Failed ARP requests zero the MAC address buffer.\r
//\r
EFI_MAC_ADDRESS  mZeroMacAddress;\r
\r
/**\r
  Callback function when frame transmission is finished. It will\r
  call the frame owner's callback function to tell it the result.\r
\r
  @param[in]  Context            Context which is point to the token.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameSentDpc (\r
  IN VOID  *Context\r
  );\r
\r
/**\r
  Request Ip4OnFrameSentDpc as a DPC at TPL_CALLBACK.\r
\r
  @param[in]  Event              The transmit token's event.\r
  @param[in]  Context            Context which is point to the token.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameSent (\r
  IN EFI_EVENT  Event,\r
  IN VOID       *Context\r
  );\r
\r
/**\r
  Callback function when ARP request are finished. It will cancelled\r
  all the queued frame if the ARP requests failed. Or transmit them\r
  if the request succeed.\r
\r
  @param[in]  Context           The context of the callback, a point to the ARP\r
                                queue\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnArpResolvedDpc (\r
  IN VOID  *Context\r
  );\r
\r
/**\r
  Request Ip4OnArpResolvedDpc as a DPC at TPL_CALLBACK.\r
\r
  @param  Event             The Arp request event.\r
  @param  Context           The context of the callback, a point to the ARP\r
                            queue.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnArpResolved (\r
  IN EFI_EVENT  Event,\r
  IN VOID       *Context\r
  );\r
\r
/**\r
  Received a frame from MNP, wrap it in net buffer then deliver\r
  it to IP's input function. The ownship of the packet also\r
  transferred to IP. When Ip is finished with this packet, it\r
  will call NetbufFree to release the packet, NetbufFree will\r
  again call the Ip4RecycleFrame to signal MNP's event and free\r
  the token used.\r
\r
  @param  Context               Context for the callback.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameReceivedDpc (\r
  IN VOID  *Context\r
  );\r
\r
/**\r
  Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK.\r
\r
  @param Event      The receive event delivered to MNP for receive.\r
  @param Context    Context for the callback.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameReceived (\r
  IN EFI_EVENT  Event,\r
  IN VOID       *Context\r
  );\r
\r
/**\r
  Remove all the frames on the ARP queue that pass the FrameToCancel,\r
  that is, either FrameToCancel is NULL or it returns true for the frame.\r
\r
  @param[in]  ArpQue            ARP frame to remove the frames from.\r
  @param[in]  IoStatus          The status returned to the cancelled frames'\r
                                callback function.\r
  @param[in]  FrameToCancel     Function to select which frame to cancel.\r
  @param[in]  Context           Opaque parameter to the FrameToCancel.\r
\r
**/\r
VOID\r
Ip4CancelFrameArp (\r
  IN IP4_ARP_QUE          *ArpQue,\r
  IN EFI_STATUS           IoStatus,\r
  IN IP4_FRAME_TO_CANCEL  FrameToCancel  OPTIONAL,\r
  IN VOID                 *Context\r
  );\r
\r
/**\r
  Wrap a transmit request into a newly allocated IP4_LINK_TX_TOKEN.\r
\r
  @param[in]  Interface         The interface to send out to.\r
  @param[in]  IpInstance        The IpInstance that transmit the packet.  NULL if\r
                                the packet is sent by the IP4 driver itself.\r
  @param[in]  Packet            The packet to transmit\r
  @param[in]  CallBack          Call back function to execute if transmission\r
                                finished.\r
  @param[in]  Context           Opaque parameter to the call back.\r
  @param[in]  IpSb              The pointer to the IP4 service binding instance.\r
\r
  @retval   Token               The wrapped token if succeed\r
  @retval   NULL                The wrapped token if NULL\r
\r
**/\r
IP4_LINK_TX_TOKEN *\r
Ip4WrapLinkTxToken (\r
  IN IP4_INTERFACE       *Interface,\r
  IN IP4_PROTOCOL        *IpInstance     OPTIONAL,\r
  IN NET_BUF             *Packet,\r
  IN IP4_FRAME_CALLBACK  CallBack,\r
  IN VOID                *Context,\r
  IN IP4_SERVICE         *IpSb\r
  )\r
{\r
  EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *MnpToken;\r
  EFI_MANAGED_NETWORK_TRANSMIT_DATA     *MnpTxData;\r
  IP4_LINK_TX_TOKEN                     *Token;\r
  EFI_STATUS                            Status;\r
  UINT32                                Count;\r
\r
  Token = AllocatePool (\r
            sizeof (IP4_LINK_TX_TOKEN) + \\r
            (Packet->BlockOpNum - 1) * sizeof (EFI_MANAGED_NETWORK_FRAGMENT_DATA)\r
            );\r
\r
  if (Token == NULL) {\r
    return NULL;\r
  }\r
\r
  Token->Signature = IP4_FRAME_TX_SIGNATURE;\r
  InitializeListHead (&Token->Link);\r
\r
  Token->Interface  = Interface;\r
  Token->IpInstance = IpInstance;\r
  Token->IpSb       = IpSb;\r
  Token->CallBack   = CallBack;\r
  Token->Packet     = Packet;\r
  Token->Context    = Context;\r
  CopyMem (&Token->DstMac, &mZeroMacAddress, sizeof (Token->DstMac));\r
  CopyMem (&Token->SrcMac, &Interface->Mac, sizeof (Token->SrcMac));\r
\r
  MnpToken         = &(Token->MnpToken);\r
  MnpToken->Status = EFI_NOT_READY;\r
\r
  Status = gBS->CreateEvent (\r
                  EVT_NOTIFY_SIGNAL,\r
                  TPL_NOTIFY,\r
                  Ip4OnFrameSent,\r
                  Token,\r
                  &MnpToken->Event\r
                  );\r
\r
  if (EFI_ERROR (Status)) {\r
    FreePool (Token);\r
    return NULL;\r
  }\r
\r
  MnpTxData               = &Token->MnpTxData;\r
  MnpToken->Packet.TxData = MnpTxData;\r
\r
  MnpTxData->DestinationAddress = &Token->DstMac;\r
  MnpTxData->SourceAddress      = &Token->SrcMac;\r
  MnpTxData->ProtocolType       = IP4_ETHER_PROTO;\r
  MnpTxData->DataLength         = Packet->TotalSize;\r
  MnpTxData->HeaderLength       = 0;\r
\r
  Count = Packet->BlockOpNum;\r
\r
  NetbufBuildExt (Packet, (NET_FRAGMENT *)MnpTxData->FragmentTable, &Count);\r
  MnpTxData->FragmentCount = (UINT16)Count;\r
\r
  return Token;\r
}\r
\r
/**\r
  Free the link layer transmit token. It will close the event\r
  then free the memory used.\r
\r
  @param[in]  Token                 Token to free\r
\r
**/\r
VOID\r
Ip4FreeLinkTxToken (\r
  IN IP4_LINK_TX_TOKEN  *Token\r
  )\r
{\r
  NET_CHECK_SIGNATURE (Token, IP4_FRAME_TX_SIGNATURE);\r
\r
  gBS->CloseEvent (Token->MnpToken.Event);\r
  FreePool (Token);\r
}\r
\r
/**\r
  Create an IP_ARP_QUE structure to request ARP service.\r
\r
  @param[in]  Interface         The interface to send ARP from.\r
  @param[in]  DestIp            The destination IP (host byte order) to request MAC\r
                                for\r
\r
  @return Point to newly created IP4_ARP_QUE if succeed, otherwise NULL.\r
\r
**/\r
IP4_ARP_QUE *\r
Ip4CreateArpQue (\r
  IN IP4_INTERFACE  *Interface,\r
  IN IP4_ADDR       DestIp\r
  )\r
{\r
  IP4_ARP_QUE  *ArpQue;\r
  EFI_STATUS   Status;\r
\r
  ArpQue = AllocatePool (sizeof (IP4_ARP_QUE));\r
\r
  if (ArpQue == NULL) {\r
    return NULL;\r
  }\r
\r
  ArpQue->Signature = IP4_FRAME_ARP_SIGNATURE;\r
  InitializeListHead (&ArpQue->Link);\r
\r
  InitializeListHead (&ArpQue->Frames);\r
  ArpQue->Interface = Interface;\r
\r
  Status = gBS->CreateEvent (\r
                  EVT_NOTIFY_SIGNAL,\r
                  TPL_NOTIFY,\r
                  Ip4OnArpResolved,\r
                  ArpQue,\r
                  &ArpQue->OnResolved\r
                  );\r
\r
  if (EFI_ERROR (Status)) {\r
    FreePool (ArpQue);\r
    return NULL;\r
  }\r
\r
  ArpQue->Ip = DestIp;\r
  CopyMem (&ArpQue->Mac, &mZeroMacAddress, sizeof (ArpQue->Mac));\r
\r
  return ArpQue;\r
}\r
\r
/**\r
  Remove all the transmit requests queued on the ARP queue, then free it.\r
\r
  @param[in]  ArpQue            Arp queue to free\r
  @param[in]  IoStatus          The transmit status returned to transmit requests'\r
                                callback.\r
\r
**/\r
VOID\r
Ip4FreeArpQue (\r
  IN IP4_ARP_QUE  *ArpQue,\r
  IN EFI_STATUS   IoStatus\r
  )\r
{\r
  NET_CHECK_SIGNATURE (ArpQue, IP4_FRAME_ARP_SIGNATURE);\r
\r
  //\r
  // Remove all the frame waiting the ARP response\r
  //\r
  Ip4CancelFrameArp (ArpQue, IoStatus, NULL, NULL);\r
\r
  gBS->CloseEvent (ArpQue->OnResolved);\r
  FreePool (ArpQue);\r
}\r
\r
/**\r
  Create a link layer receive token to wrap the receive request\r
\r
  @param[in]  Interface         The interface to receive from\r
  @param[in]  IpInstance        The instance that request the receive (NULL for IP4\r
                                driver itself)\r
  @param[in]  CallBack          Call back function to execute when finished.\r
  @param[in]  Context           Opaque parameters to the callback\r
\r
  @return Point to created IP4_LINK_RX_TOKEN if succeed, otherwise NULL.\r
\r
**/\r
IP4_LINK_RX_TOKEN *\r
Ip4CreateLinkRxToken (\r
  IN IP4_INTERFACE       *Interface,\r
  IN IP4_PROTOCOL        *IpInstance,\r
  IN IP4_FRAME_CALLBACK  CallBack,\r
  IN VOID                *Context\r
  )\r
{\r
  EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *MnpToken;\r
  IP4_LINK_RX_TOKEN                     *Token;\r
  EFI_STATUS                            Status;\r
\r
  Token = AllocatePool (sizeof (IP4_LINK_RX_TOKEN));\r
  if (Token == NULL) {\r
    return NULL;\r
  }\r
\r
  Token->Signature  = IP4_FRAME_RX_SIGNATURE;\r
  Token->Interface  = Interface;\r
  Token->IpInstance = IpInstance;\r
  Token->CallBack   = CallBack;\r
  Token->Context    = Context;\r
\r
  MnpToken         = &Token->MnpToken;\r
  MnpToken->Status = EFI_NOT_READY;\r
\r
  Status = gBS->CreateEvent (\r
                  EVT_NOTIFY_SIGNAL,\r
                  TPL_NOTIFY,\r
                  Ip4OnFrameReceived,\r
                  Token,\r
                  &MnpToken->Event\r
                  );\r
\r
  if (EFI_ERROR (Status)) {\r
    FreePool (Token);\r
    return NULL;\r
  }\r
\r
  MnpToken->Packet.RxData = NULL;\r
  return Token;\r
}\r
\r
/**\r
  Free the link layer request token. It will close the event\r
  then free the memory used.\r
\r
  @param[in]  Token                 Request token to free.\r
\r
**/\r
VOID\r
Ip4FreeFrameRxToken (\r
  IN IP4_LINK_RX_TOKEN  *Token\r
  )\r
{\r
  NET_CHECK_SIGNATURE (Token, IP4_FRAME_RX_SIGNATURE);\r
\r
  gBS->CloseEvent (Token->MnpToken.Event);\r
  FreePool (Token);\r
}\r
\r
/**\r
  Remove all the frames on the ARP queue that pass the FrameToCancel,\r
  that is, either FrameToCancel is NULL or it returns true for the frame.\r
\r
  @param[in]  ArpQue            ARP frame to remove the frames from.\r
  @param[in]  IoStatus          The status returned to the cancelled frames'\r
                                callback function.\r
  @param[in]  FrameToCancel     Function to select which frame to cancel.\r
  @param[in]  Context           Opaque parameter to the FrameToCancel.\r
\r
**/\r
VOID\r
Ip4CancelFrameArp (\r
  IN IP4_ARP_QUE          *ArpQue,\r
  IN EFI_STATUS           IoStatus,\r
  IN IP4_FRAME_TO_CANCEL  FrameToCancel  OPTIONAL,\r
  IN VOID                 *Context\r
  )\r
{\r
  LIST_ENTRY         *Entry;\r
  LIST_ENTRY         *Next;\r
  IP4_LINK_TX_TOKEN  *Token;\r
\r
  NET_LIST_FOR_EACH_SAFE (Entry, Next, &ArpQue->Frames) {\r
    Token = NET_LIST_USER_STRUCT (Entry, IP4_LINK_TX_TOKEN, Link);\r
\r
    if ((FrameToCancel == NULL) || FrameToCancel (Token, Context)) {\r
      RemoveEntryList (Entry);\r
\r
      Token->CallBack (Token->IpInstance, Token->Packet, IoStatus, 0, Token->Context);\r
      Ip4FreeLinkTxToken (Token);\r
    }\r
  }\r
}\r
\r
/**\r
  Remove all the frames on the interface that pass the FrameToCancel,\r
  either queued on ARP queues or that have already been delivered to\r
  MNP and not yet recycled.\r
\r
  @param[in]  Interface         Interface to remove the frames from.\r
  @param[in]  IoStatus          The transmit status returned to the frames'\r
                                callback.\r
  @param[in]  FrameToCancel     Function to select the frame to cancel, NULL to\r
                                select all.\r
  @param[in]  Context           Opaque parameters passed to FrameToCancel.\r
\r
**/\r
VOID\r
Ip4CancelFrames (\r
  IN IP4_INTERFACE        *Interface,\r
  IN EFI_STATUS           IoStatus,\r
  IN IP4_FRAME_TO_CANCEL  FrameToCancel    OPTIONAL,\r
  IN VOID                 *Context\r
  )\r
{\r
  LIST_ENTRY         *Entry;\r
  LIST_ENTRY         *Next;\r
  IP4_ARP_QUE        *ArpQue;\r
  IP4_LINK_TX_TOKEN  *Token;\r
\r
  //\r
  // Cancel all the pending frames on ARP requests\r
  //\r
  NET_LIST_FOR_EACH_SAFE (Entry, Next, &Interface->ArpQues) {\r
    ArpQue = NET_LIST_USER_STRUCT (Entry, IP4_ARP_QUE, Link);\r
\r
    Ip4CancelFrameArp (ArpQue, IoStatus, FrameToCancel, Context);\r
\r
    if (IsListEmpty (&ArpQue->Frames)) {\r
      Interface->Arp->Cancel (Interface->Arp, &ArpQue->Ip, ArpQue->OnResolved);\r
    }\r
  }\r
\r
  //\r
  // Cancel all the frames that have been delivered to MNP\r
  // but not yet recycled.\r
  //\r
  NET_LIST_FOR_EACH_SAFE (Entry, Next, &Interface->SentFrames) {\r
    Token = NET_LIST_USER_STRUCT (Entry, IP4_LINK_TX_TOKEN, Link);\r
\r
    if ((FrameToCancel == NULL) || FrameToCancel (Token, Context)) {\r
      Interface->Mnp->Cancel (Interface->Mnp, &Token->MnpToken);\r
    }\r
  }\r
}\r
\r
/**\r
  Create an IP4_INTERFACE. Delay the creation of ARP instance until\r
  the interface is configured.\r
\r
  @param[in]  Mnp               The shared MNP child of this IP4 service binding\r
                                instance.\r
  @param[in]  Controller        The controller this IP4 service binding instance\r
                                is installed. Most like the UNDI handle.\r
  @param[in]  ImageHandle       This driver's image handle.\r
\r
  @return Point to the created IP4_INTERFACE, otherwise NULL.\r
\r
**/\r
IP4_INTERFACE *\r
Ip4CreateInterface (\r
  IN  EFI_MANAGED_NETWORK_PROTOCOL  *Mnp,\r
  IN  EFI_HANDLE                    Controller,\r
  IN  EFI_HANDLE                    ImageHandle\r
  )\r
{\r
  IP4_INTERFACE            *Interface;\r
  EFI_SIMPLE_NETWORK_MODE  SnpMode;\r
\r
  if (Mnp == NULL) {\r
    return NULL;\r
  }\r
\r
  Interface = AllocatePool (sizeof (IP4_INTERFACE));\r
\r
  if (Interface == NULL) {\r
    return NULL;\r
  }\r
\r
  Interface->Signature = IP4_INTERFACE_SIGNATURE;\r
  InitializeListHead (&Interface->Link);\r
  Interface->RefCnt = 1;\r
\r
  Interface->Ip         = IP4_ALLZERO_ADDRESS;\r
  Interface->SubnetMask = IP4_ALLZERO_ADDRESS;\r
  Interface->Configured = FALSE;\r
\r
  Interface->Controller = Controller;\r
  Interface->Image      = ImageHandle;\r
  Interface->Mnp        = Mnp;\r
  Interface->Arp        = NULL;\r
  Interface->ArpHandle  = NULL;\r
\r
  InitializeListHead (&Interface->ArpQues);\r
  InitializeListHead (&Interface->SentFrames);\r
\r
  Interface->RecvRequest = NULL;\r
\r
  //\r
  // Get the interface's Mac address and broadcast mac address from SNP\r
  //\r
  if (EFI_ERROR (Mnp->GetModeData (Mnp, NULL, &SnpMode))) {\r
    FreePool (Interface);\r
    return NULL;\r
  }\r
\r
  CopyMem (&Interface->Mac, &SnpMode.CurrentAddress, sizeof (Interface->Mac));\r
  CopyMem (&Interface->BroadcastMac, &SnpMode.BroadcastAddress, sizeof (Interface->BroadcastMac));\r
  Interface->HwaddrLen = SnpMode.HwAddressSize;\r
\r
  InitializeListHead (&Interface->IpInstances);\r
  Interface->PromiscRecv = FALSE;\r
\r
  return Interface;\r
}\r
\r
/**\r
  Set the interface's address, create and configure\r
  the ARP child if necessary.\r
\r
  @param  Interface         The interface to set the address.\r
  @param  IpAddr            The interface's IP address.\r
  @param  SubnetMask        The interface's netmask.\r
\r
  @retval EFI_SUCCESS           The interface is configured with Ip/netmask pair,\r
                                and a ARP is created for it.\r
  @retval Others                Failed to set the interface's address.\r
\r
**/\r
EFI_STATUS\r
Ip4SetAddress (\r
  IN OUT IP4_INTERFACE  *Interface,\r
  IN     IP4_ADDR       IpAddr,\r
  IN     IP4_ADDR       SubnetMask\r
  )\r
{\r
  EFI_ARP_CONFIG_DATA  ArpConfig;\r
  EFI_STATUS           Status;\r
\r
  NET_CHECK_SIGNATURE (Interface, IP4_INTERFACE_SIGNATURE);\r
\r
  //\r
  // Set the ip/netmask, then compute the subnet broadcast\r
  // and network broadcast for easy access. When computing\r
  // network broadcast, the subnet mask is most like longer\r
  // than the default netmask (not subneted) as defined in\r
  // RFC793. If that isn't the case, we are aggregating the\r
  // networks, use the subnet's mask instead.\r
  //\r
  Interface->Ip            = IpAddr;\r
  Interface->SubnetMask    = SubnetMask;\r
  Interface->SubnetBrdcast = (IpAddr | ~SubnetMask);\r
  Interface->NetBrdcast    = (IpAddr | ~SubnetMask);\r
\r
  //\r
  // Do clean up for Arp child\r
  //\r
  if (Interface->ArpHandle != NULL) {\r
    if (Interface->Arp != NULL) {\r
      gBS->CloseProtocol (\r
             Interface->ArpHandle,\r
             &gEfiArpProtocolGuid,\r
             Interface->Image,\r
             Interface->Controller\r
             );\r
\r
      Interface->Arp = NULL;\r
    }\r
\r
    NetLibDestroyServiceChild (\r
      Interface->Controller,\r
      Interface->Image,\r
      &gEfiArpServiceBindingProtocolGuid,\r
      Interface->ArpHandle\r
      );\r
\r
    Interface->ArpHandle = NULL;\r
  }\r
\r
  //\r
  // If the address is NOT all zero, create then configure an ARP child.\r
  // Pay attention: DHCP configures its station address as 0.0.0.0/0\r
  //\r
  if (IpAddr != IP4_ALLZERO_ADDRESS) {\r
    Status = NetLibCreateServiceChild (\r
               Interface->Controller,\r
               Interface->Image,\r
               &gEfiArpServiceBindingProtocolGuid,\r
               &Interface->ArpHandle\r
               );\r
\r
    if (EFI_ERROR (Status)) {\r
      return Status;\r
    }\r
\r
    Status = gBS->OpenProtocol (\r
                    Interface->ArpHandle,\r
                    &gEfiArpProtocolGuid,\r
                    (VOID **)&Interface->Arp,\r
                    Interface->Image,\r
                    Interface->Controller,\r
                    EFI_OPEN_PROTOCOL_BY_DRIVER\r
                    );\r
\r
    if (EFI_ERROR (Status)) {\r
      goto ON_ERROR;\r
    }\r
\r
    IpAddr                    = HTONL (IpAddr);\r
    ArpConfig.SwAddressType   = IP4_ETHER_PROTO;\r
    ArpConfig.SwAddressLength = 4;\r
    ArpConfig.StationAddress  = &IpAddr;\r
    ArpConfig.EntryTimeOut    = 0;\r
    ArpConfig.RetryCount      = 0;\r
    ArpConfig.RetryTimeOut    = 0;\r
\r
    Status = Interface->Arp->Configure (Interface->Arp, &ArpConfig);\r
\r
    if (EFI_ERROR (Status)) {\r
      gBS->CloseProtocol (\r
             Interface->ArpHandle,\r
             &gEfiArpProtocolGuid,\r
             Interface->Image,\r
             Interface->Controller\r
             );\r
\r
      goto ON_ERROR;\r
    }\r
  }\r
\r
  Interface->Configured = TRUE;\r
  return EFI_SUCCESS;\r
\r
ON_ERROR:\r
  NetLibDestroyServiceChild (\r
    Interface->Controller,\r
    Interface->Image,\r
    &gEfiArpServiceBindingProtocolGuid,\r
    Interface->ArpHandle\r
    );\r
\r
  return Status;\r
}\r
\r
/**\r
  Filter function to cancel all the frame related to an IP instance.\r
\r
  @param[in]  Frame             The transmit request to test whether to cancel\r
  @param[in]  Context           The context which is the Ip instance that issued\r
                                the transmit.\r
\r
  @retval TRUE                  The frame belongs to this instance and is to be\r
                                removed\r
  @retval FALSE                 The frame doesn't belong to this instance.\r
\r
**/\r
BOOLEAN\r
Ip4CancelInstanceFrame (\r
  IN IP4_LINK_TX_TOKEN  *Frame,\r
  IN VOID               *Context\r
  )\r
{\r
  if (Frame->IpInstance == (IP4_PROTOCOL *)Context) {\r
    return TRUE;\r
  }\r
\r
  return FALSE;\r
}\r
\r
/**\r
  If there is a pending receive request, cancel it. Don't call\r
  the receive request's callback because this function can be only\r
  called if the instance or driver is tearing itself down. It\r
  doesn't make sense to call it back. But it is necessary to call\r
  the transmit token's callback to give it a chance to free the\r
  packet and update the upper layer's transmit request status, say\r
  that from the UDP.\r
\r
  @param[in]  Interface         The interface used by the IpInstance\r
\r
**/\r
VOID\r
Ip4CancelReceive (\r
  IN IP4_INTERFACE  *Interface\r
  )\r
{\r
  EFI_TPL            OldTpl;\r
  IP4_LINK_RX_TOKEN  *Token;\r
\r
  if ((Token = Interface->RecvRequest) != NULL) {\r
    OldTpl = gBS->RaiseTPL (TPL_CALLBACK);\r
\r
    Interface->RecvRequest = NULL;\r
    Interface->Mnp->Cancel (Interface->Mnp, &Token->MnpToken);\r
\r
    gBS->RestoreTPL (OldTpl);\r
  }\r
}\r
\r
/**\r
  Free the interface used by IpInstance. All the IP instance with\r
  the same Ip/Netmask pair share the same interface. It is reference\r
  counted. All the frames haven't been sent will be cancelled.\r
  Because the IpInstance is optional, the caller must remove\r
  IpInstance from the interface's instance list itself.\r
\r
  @param[in]  Interface         The interface used by the IpInstance.\r
  @param[in]  IpInstance        The Ip instance that free the interface. NULL if\r
                                the Ip driver is releasing the default interface.\r
\r
  @retval EFI_SUCCESS           The interface use IpInstance is freed.\r
\r
**/\r
EFI_STATUS\r
Ip4FreeInterface (\r
  IN  IP4_INTERFACE  *Interface,\r
  IN  IP4_PROTOCOL   *IpInstance           OPTIONAL\r
  )\r
{\r
  NET_CHECK_SIGNATURE (Interface, IP4_INTERFACE_SIGNATURE);\r
  ASSERT (Interface->RefCnt > 0);\r
\r
  //\r
  // Remove all the pending transmit token related to this IP instance.\r
  //\r
  Ip4CancelFrames (Interface, EFI_ABORTED, Ip4CancelInstanceFrame, IpInstance);\r
\r
  if (--Interface->RefCnt > 0) {\r
    return EFI_SUCCESS;\r
  }\r
\r
  //\r
  // Destroy the interface if this is the last IP instance that\r
  // has the address. Remove all the system transmitted packets\r
  // from this interface, cancel the receive request if there is\r
  // one, and destroy the ARP requests.\r
  //\r
  Ip4CancelFrames (Interface, EFI_ABORTED, Ip4CancelInstanceFrame, NULL);\r
  Ip4CancelReceive (Interface);\r
\r
  ASSERT (IsListEmpty (&Interface->IpInstances));\r
  ASSERT (IsListEmpty (&Interface->ArpQues));\r
  ASSERT (IsListEmpty (&Interface->SentFrames));\r
\r
  if (Interface->Arp != NULL) {\r
    gBS->CloseProtocol (\r
           Interface->ArpHandle,\r
           &gEfiArpProtocolGuid,\r
           Interface->Image,\r
           Interface->Controller\r
           );\r
\r
    NetLibDestroyServiceChild (\r
      Interface->Controller,\r
      Interface->Image,\r
      &gEfiArpServiceBindingProtocolGuid,\r
      Interface->ArpHandle\r
      );\r
  }\r
\r
  RemoveEntryList (&Interface->Link);\r
  FreePool (Interface);\r
\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  This function tries to send all the queued frames in ArpQue to the default gateway if\r
  the ARP resolve for direct destination address is failed when using /32 subnet mask.\r
\r
  @param[in]   ArpQue           The ARP queue of a failed request.\r
\r
  @retval EFI_SUCCESS           All the queued frames have been send to the default route.\r
  @retval Others                Failed to send the queued frames.\r
\r
**/\r
EFI_STATUS\r
Ip4SendFrameToDefaultRoute (\r
  IN  IP4_ARP_QUE  *ArpQue\r
  )\r
{\r
  LIST_ENTRY             *Entry;\r
  LIST_ENTRY             *Next;\r
  IP4_ROUTE_CACHE_ENTRY  *RtCacheEntry;\r
  IP4_LINK_TX_TOKEN      *Token;\r
  IP4_ADDR               Gateway;\r
  EFI_STATUS             Status;\r
  IP4_ROUTE_ENTRY        *DefaultRoute;\r
\r
  //\r
  // ARP resolve failed when using /32 subnet mask.\r
  //\r
  NET_LIST_FOR_EACH_SAFE (Entry, Next, &ArpQue->Frames) {\r
    RemoveEntryList (Entry);\r
    Token = NET_LIST_USER_STRUCT (Entry, IP4_LINK_TX_TOKEN, Link);\r
    ASSERT (Token->Interface->SubnetMask == IP4_ALLONE_ADDRESS);\r
    //\r
    // Find the default gateway IP address. The default route was saved to the RtCacheEntry->Tag in Ip4Route().\r
    //\r
    RtCacheEntry = NULL;\r
    if (Token->IpInstance != NULL) {\r
      RtCacheEntry = Ip4FindRouteCache (Token->IpInstance->RouteTable, NTOHL (ArpQue->Ip), Token->Interface->Ip);\r
    }\r
\r
    if (RtCacheEntry == NULL) {\r
      RtCacheEntry = Ip4FindRouteCache (Token->IpSb->DefaultRouteTable, NTOHL (ArpQue->Ip), Token->Interface->Ip);\r
    }\r
\r
    if (RtCacheEntry == NULL) {\r
      Status = EFI_NO_MAPPING;\r
      goto ON_ERROR;\r
    }\r
\r
    DefaultRoute = (IP4_ROUTE_ENTRY *)RtCacheEntry->Tag;\r
    if (DefaultRoute == NULL) {\r
      Status = EFI_NO_MAPPING;\r
      goto ON_ERROR;\r
    }\r
\r
    //\r
    // Try to send the frame to the default route.\r
    //\r
    Gateway = DefaultRoute->NextHop;\r
    if (ArpQue->Ip == Gateway) {\r
      //\r
      // ARP resolve for the default route is failed, return error to caller.\r
      //\r
      Status = EFI_NO_MAPPING;\r
      goto ON_ERROR;\r
    }\r
\r
    RtCacheEntry->NextHop = Gateway;\r
    Status                = Ip4SendFrame (Token->Interface, Token->IpInstance, Token->Packet, Gateway, Token->CallBack, Token->Context, Token->IpSb);\r
    if (EFI_ERROR (Status)) {\r
      Status = EFI_NO_MAPPING;\r
      goto ON_ERROR;\r
    }\r
\r
    Ip4FreeRouteCacheEntry (RtCacheEntry);\r
  }\r
\r
  return EFI_SUCCESS;\r
\r
ON_ERROR:\r
  if (RtCacheEntry != NULL) {\r
    Ip4FreeRouteCacheEntry (RtCacheEntry);\r
  }\r
\r
  Token->CallBack (Token->IpInstance, Token->Packet, Status, 0, Token->Context);\r
  Ip4FreeLinkTxToken (Token);\r
  return Status;\r
}\r
\r
/**\r
  Callback function when ARP request are finished. It will cancel\r
  all the queued frame if the ARP requests failed. Or transmit them\r
  if the request succeed.\r
\r
  @param[in]  Context           The context of the callback, a point to the ARP\r
                                queue\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnArpResolvedDpc (\r
  IN VOID  *Context\r
  )\r
{\r
  LIST_ENTRY         *Entry;\r
  LIST_ENTRY         *Next;\r
  IP4_ARP_QUE        *ArpQue;\r
  IP4_INTERFACE      *Interface;\r
  IP4_LINK_TX_TOKEN  *Token;\r
  EFI_STATUS         Status;\r
  EFI_STATUS         IoStatus;\r
\r
  ArpQue = (IP4_ARP_QUE *)Context;\r
  NET_CHECK_SIGNATURE (ArpQue, IP4_FRAME_ARP_SIGNATURE);\r
\r
  RemoveEntryList (&ArpQue->Link);\r
\r
  //\r
  // ARP resolve failed for some reason.\r
  //\r
  if (NET_MAC_EQUAL (&ArpQue->Mac, &mZeroMacAddress, ArpQue->Interface->HwaddrLen)) {\r
    if (ArpQue->Interface->SubnetMask != IP4_ALLONE_ADDRESS) {\r
      //\r
      // Release all the frame and ARP queue itself. Ip4FreeArpQue will call the frame's\r
      // owner back.\r
      //\r
      IoStatus = EFI_NO_MAPPING;\r
    } else {\r
      //\r
      // ARP resolve failed when using 32bit subnet mask, try to send the packets to the\r
      // default route.\r
      //\r
      IoStatus = Ip4SendFrameToDefaultRoute (ArpQue);\r
    }\r
\r
    goto ON_EXIT;\r
  }\r
\r
  //\r
  // ARP resolve succeeded, Transmit all the frame. Release the ARP\r
  // queue. It isn't necessary for us to cache the ARP binding because\r
  // we always check the ARP cache first before transmit.\r
  //\r
  IoStatus  = EFI_SUCCESS;\r
  Interface = ArpQue->Interface;\r
\r
  NET_LIST_FOR_EACH_SAFE (Entry, Next, &ArpQue->Frames) {\r
    RemoveEntryList (Entry);\r
\r
    Token = NET_LIST_USER_STRUCT (Entry, IP4_LINK_TX_TOKEN, Link);\r
    CopyMem (&Token->DstMac, &ArpQue->Mac, sizeof (Token->DstMac));\r
\r
    //\r
    // Insert the tx token before transmitting it via MNP as the FrameSentDpc\r
    // may be called before Mnp->Transmit returns which will remove this tx\r
    // token from the SentFrames list. Remove it from the list if the returned\r
    // Status of Mnp->Transmit is not EFI_SUCCESS as in this case the\r
    // FrameSentDpc won't be queued.\r
    //\r
    InsertTailList (&Interface->SentFrames, &Token->Link);\r
\r
    Status = Interface->Mnp->Transmit (Interface->Mnp, &Token->MnpToken);\r
    if (EFI_ERROR (Status)) {\r
      RemoveEntryList (&Token->Link);\r
      Token->CallBack (Token->IpInstance, Token->Packet, Status, 0, Token->Context);\r
\r
      Ip4FreeLinkTxToken (Token);\r
      continue;\r
    }\r
  }\r
\r
ON_EXIT:\r
  Ip4FreeArpQue (ArpQue, IoStatus);\r
}\r
\r
/**\r
  Request Ip4OnArpResolvedDpc as a DPC at TPL_CALLBACK.\r
\r
  @param  Event             The Arp request event.\r
  @param  Context           The context of the callback, a point to the ARP\r
                            queue.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnArpResolved (\r
  IN EFI_EVENT  Event,\r
  IN VOID       *Context\r
  )\r
{\r
  //\r
  // Request Ip4OnArpResolvedDpc as a DPC at TPL_CALLBACK\r
  //\r
  QueueDpc (TPL_CALLBACK, Ip4OnArpResolvedDpc, Context);\r
}\r
\r
/**\r
  Callback function when frame transmission is finished. It will\r
  call the frame owner's callback function to tell it the result.\r
\r
  @param[in]  Context            Context which is point to the token.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameSentDpc (\r
  IN VOID  *Context\r
  )\r
{\r
  IP4_LINK_TX_TOKEN  *Token;\r
\r
  Token = (IP4_LINK_TX_TOKEN *)Context;\r
  NET_CHECK_SIGNATURE (Token, IP4_FRAME_TX_SIGNATURE);\r
\r
  RemoveEntryList (&Token->Link);\r
\r
  Token->CallBack (\r
           Token->IpInstance,\r
           Token->Packet,\r
           Token->MnpToken.Status,\r
           0,\r
           Token->Context\r
           );\r
\r
  Ip4FreeLinkTxToken (Token);\r
}\r
\r
/**\r
  Request Ip4OnFrameSentDpc as a DPC at TPL_CALLBACK.\r
\r
  @param[in]  Event              The transmit token's event.\r
  @param[in]  Context            Context which is point to the token.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameSent (\r
  IN EFI_EVENT  Event,\r
  IN VOID       *Context\r
  )\r
{\r
  //\r
  // Request Ip4OnFrameSentDpc as a DPC at TPL_CALLBACK\r
  //\r
  QueueDpc (TPL_CALLBACK, Ip4OnFrameSentDpc, Context);\r
}\r
\r
/**\r
  Send a frame from the interface. If the next hop is broadcast or\r
  multicast address, it is transmitted immediately. If the next hop\r
  is a unicast, it will consult ARP to resolve the NextHop's MAC.\r
  If some error happened, the CallBack won't be called. So, the caller\r
  must test the return value, and take action when there is an error.\r
\r
  @param[in]  Interface         The interface to send the frame from\r
  @param[in]  IpInstance        The IP child that request the transmission.  NULL\r
                                if it is the IP4 driver itself.\r
  @param[in]  Packet            The packet to transmit.\r
  @param[in]  NextHop           The immediate destination to transmit the packet\r
                                to.\r
  @param[in]  CallBack          Function to call back when transmit finished.\r
  @param[in]  Context           Opaque parameter to the call back.\r
  @param[in]  IpSb              The pointer to the IP4 service binding instance.\r
\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource to send the frame\r
  @retval EFI_NO_MAPPING        Can't resolve the MAC for the nexthop\r
  @retval EFI_SUCCESS           The packet is successfully transmitted.\r
  @retval other                 Other error occurs.\r
\r
**/\r
EFI_STATUS\r
Ip4SendFrame (\r
  IN  IP4_INTERFACE       *Interface,\r
  IN  IP4_PROTOCOL        *IpInstance       OPTIONAL,\r
  IN  NET_BUF             *Packet,\r
  IN  IP4_ADDR            NextHop,\r
  IN  IP4_FRAME_CALLBACK  CallBack,\r
  IN  VOID                *Context,\r
  IN IP4_SERVICE          *IpSb\r
  )\r
{\r
  IP4_LINK_TX_TOKEN  *Token;\r
  LIST_ENTRY         *Entry;\r
  IP4_ARP_QUE        *ArpQue;\r
  EFI_ARP_PROTOCOL   *Arp;\r
  EFI_STATUS         Status;\r
\r
  ASSERT (Interface->Configured);\r
\r
  Token = Ip4WrapLinkTxToken (Interface, IpInstance, Packet, CallBack, Context, IpSb);\r
\r
  if (Token == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  //\r
  // Get the destination MAC address for multicast and broadcasts.\r
  // Don't depend on ARP to solve the address since there maybe no\r
  // ARP at all. Ip4Output has set NextHop to 255.255.255.255 for\r
  // all the broadcasts.\r
  //\r
  if (NextHop == IP4_ALLONE_ADDRESS) {\r
    CopyMem (&Token->DstMac, &Interface->BroadcastMac, sizeof (Token->DstMac));\r
    goto SEND_NOW;\r
  } else if (IP4_IS_MULTICAST (NextHop)) {\r
    Status = Ip4GetMulticastMac (Interface->Mnp, NextHop, &Token->DstMac);\r
\r
    if (EFI_ERROR (Status)) {\r
      goto ON_ERROR;\r
    }\r
\r
    goto SEND_NOW;\r
  }\r
\r
  //\r
  // Can only send out multicast/broadcast if the IP address is zero\r
  //\r
  if ((Arp = Interface->Arp) == NULL) {\r
    Status = EFI_NO_MAPPING;\r
    goto ON_ERROR;\r
  }\r
\r
  //\r
  // First check whether this binding is in the ARP cache.\r
  //\r
  NextHop = HTONL (NextHop);\r
  Status  = Arp->Request (Arp, &NextHop, NULL, &Token->DstMac);\r
\r
  if (Status == EFI_SUCCESS) {\r
    goto SEND_NOW;\r
  } else if (Status != EFI_NOT_READY) {\r
    goto ON_ERROR;\r
  }\r
\r
  //\r
  // Have to do asynchronous ARP resolution. First check\r
  // whether there is already a pending request.\r
  //\r
  ArpQue = NULL;\r
\r
  NET_LIST_FOR_EACH (Entry, &Interface->ArpQues) {\r
    ArpQue = NET_LIST_USER_STRUCT (Entry, IP4_ARP_QUE, Link);\r
\r
    if (ArpQue->Ip == NextHop) {\r
      break;\r
    }\r
  }\r
\r
  //\r
  // Found a pending ARP request, enqueue the frame then return\r
  //\r
  if (Entry != &Interface->ArpQues) {\r
    InsertTailList (&ArpQue->Frames, &Token->Link);\r
    return EFI_SUCCESS;\r
  }\r
\r
  //\r
  // First frame to NextHop, issue an asynchronous ARP requests\r
  //\r
  ArpQue = Ip4CreateArpQue (Interface, NextHop);\r
\r
  if (ArpQue == NULL) {\r
    Status = EFI_OUT_OF_RESOURCES;\r
    goto ON_ERROR;\r
  }\r
\r
  Status = Arp->Request (Arp, &ArpQue->Ip, ArpQue->OnResolved, ArpQue->Mac.Addr);\r
\r
  if (EFI_ERROR (Status) && (Status != EFI_NOT_READY)) {\r
    Ip4FreeArpQue (ArpQue, EFI_NO_MAPPING);\r
    goto ON_ERROR;\r
  }\r
\r
  InsertHeadList (&ArpQue->Frames, &Token->Link);\r
  InsertHeadList (&Interface->ArpQues, &ArpQue->Link);\r
  return EFI_SUCCESS;\r
\r
SEND_NOW:\r
  //\r
  // Insert the tx token into the SentFrames list before calling Mnp->Transmit.\r
  // Remove it if the returned status is not EFI_SUCCESS.\r
  //\r
  InsertTailList (&Interface->SentFrames, &Token->Link);\r
  Status = Interface->Mnp->Transmit (Interface->Mnp, &Token->MnpToken);\r
  if (EFI_ERROR (Status)) {\r
    RemoveEntryList (&Token->Link);\r
    goto ON_ERROR;\r
  }\r
\r
  return EFI_SUCCESS;\r
\r
ON_ERROR:\r
  Ip4FreeLinkTxToken (Token);\r
  return Status;\r
}\r
\r
/**\r
  Call back function when the received packet is freed.\r
  Check Ip4OnFrameReceived for information.\r
\r
  @param  Context          Context, which is the IP4_LINK_RX_TOKEN.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4RecycleFrame (\r
  IN VOID  *Context\r
  )\r
{\r
  IP4_LINK_RX_TOKEN  *Frame;\r
\r
  Frame = (IP4_LINK_RX_TOKEN *)Context;\r
  NET_CHECK_SIGNATURE (Frame, IP4_FRAME_RX_SIGNATURE);\r
\r
  gBS->SignalEvent (Frame->MnpToken.Packet.RxData->RecycleEvent);\r
  Ip4FreeFrameRxToken (Frame);\r
}\r
\r
/**\r
  Received a frame from MNP, wrap it in net buffer then deliver\r
  it to IP's input function. The ownship of the packet also\r
  transferred to IP. When Ip is finished with this packet, it\r
  will call NetbufFree to release the packet, NetbufFree will\r
  again call the Ip4RecycleFrame to signal MNP's event and free\r
  the token used.\r
\r
  @param  Context               Context for the callback.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameReceivedDpc (\r
  IN VOID  *Context\r
  )\r
{\r
  EFI_MANAGED_NETWORK_COMPLETION_TOKEN  *MnpToken;\r
  EFI_MANAGED_NETWORK_RECEIVE_DATA      *MnpRxData;\r
  IP4_LINK_RX_TOKEN                     *Token;\r
  NET_FRAGMENT                          Netfrag;\r
  NET_BUF                               *Packet;\r
  UINT32                                Flag;\r
\r
  Token = (IP4_LINK_RX_TOKEN *)Context;\r
  NET_CHECK_SIGNATURE (Token, IP4_FRAME_RX_SIGNATURE);\r
\r
  //\r
  // First clear the interface's receive request in case the\r
  // caller wants to call Ip4ReceiveFrame in the callback.\r
  //\r
  Token->Interface->RecvRequest = NULL;\r
\r
  MnpToken  = &Token->MnpToken;\r
  MnpRxData = MnpToken->Packet.RxData;\r
\r
  if (EFI_ERROR (MnpToken->Status) || (MnpRxData == NULL)) {\r
    Token->CallBack (Token->IpInstance, NULL, MnpToken->Status, 0, Token->Context);\r
    Ip4FreeFrameRxToken (Token);\r
\r
    return;\r
  }\r
\r
  //\r
  // Wrap the frame in a net buffer then deliver it to IP input.\r
  // IP will reassemble the packet, and deliver it to upper layer\r
  //\r
  Netfrag.Len  = MnpRxData->DataLength;\r
  Netfrag.Bulk = MnpRxData->PacketData;\r
\r
  Packet = NetbufFromExt (&Netfrag, 1, 0, IP4_MAX_HEADLEN, Ip4RecycleFrame, Token);\r
\r
  if (Packet == NULL) {\r
    gBS->SignalEvent (MnpRxData->RecycleEvent);\r
\r
    Token->CallBack (Token->IpInstance, NULL, EFI_OUT_OF_RESOURCES, 0, Token->Context);\r
    Ip4FreeFrameRxToken (Token);\r
\r
    return;\r
  }\r
\r
  Flag  = (MnpRxData->BroadcastFlag ? IP4_LINK_BROADCAST : 0);\r
  Flag |= (MnpRxData->MulticastFlag ? IP4_LINK_MULTICAST : 0);\r
  Flag |= (MnpRxData->PromiscuousFlag ? IP4_LINK_PROMISC : 0);\r
\r
  Token->CallBack (Token->IpInstance, Packet, EFI_SUCCESS, Flag, Token->Context);\r
}\r
\r
/**\r
  Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK.\r
\r
  @param Event      The receive event delivered to MNP for receive.\r
  @param Context    Context for the callback.\r
\r
**/\r
VOID\r
EFIAPI\r
Ip4OnFrameReceived (\r
  IN EFI_EVENT  Event,\r
  IN VOID       *Context\r
  )\r
{\r
  //\r
  // Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK\r
  //\r
  QueueDpc (TPL_CALLBACK, Ip4OnFrameReceivedDpc, Context);\r
}\r
\r
/**\r
  Request to receive the packet from the interface.\r
\r
  @param[in]  Interface         The interface to receive the frames from.\r
  @param[in]  IpInstance        The instance that requests the receive. NULL for\r
                                the driver itself.\r
  @param[in]  CallBack          Function to call when receive finished.\r
  @param[in]  Context           Opaque parameter to the callback.\r
\r
  @retval EFI_ALREADY_STARTED   There is already a pending receive request.\r
  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource to receive.\r
  @retval EFI_SUCCESS           The receive request has been started.\r
  @retval other                 Other error occurs.\r
\r
**/\r
EFI_STATUS\r
Ip4ReceiveFrame (\r
  IN  IP4_INTERFACE       *Interface,\r
  IN  IP4_PROTOCOL        *IpInstance       OPTIONAL,\r
  IN  IP4_FRAME_CALLBACK  CallBack,\r
  IN  VOID                *Context\r
  )\r
{\r
  IP4_LINK_RX_TOKEN  *Token;\r
  EFI_STATUS         Status;\r
\r
  NET_CHECK_SIGNATURE (Interface, IP4_INTERFACE_SIGNATURE);\r
\r
  if (Interface->RecvRequest != NULL) {\r
    return EFI_ALREADY_STARTED;\r
  }\r
\r
  Token = Ip4CreateLinkRxToken (Interface, IpInstance, CallBack, Context);\r
\r
  if (Token == NULL) {\r
    return EFI_OUT_OF_RESOURCES;\r
  }\r
\r
  Interface->RecvRequest = Token;\r
  Status                 = Interface->Mnp->Receive (Interface->Mnp, &Token->MnpToken);\r
  if (EFI_ERROR (Status)) {\r
    Interface->RecvRequest = NULL;\r
    Ip4FreeFrameRxToken (Token);\r
    return Status;\r
  }\r
\r
  return EFI_SUCCESS;\r
}\r