synced function header

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6595 6f19259b-4bc3-4df7-8a09-765794883524

MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.h

@@ -198,6 +198,19 @@ struct _IP4_INTERFACE {
   BOOLEAN                       PromiscRecv;
 };
 
+/**
+  Create an IP4_INTERFACE. Delay the creation of ARP instance until
+  the interface is configured.
+
+  @param  Mnp                   The shared MNP child of this IP4 service binding
+                                instance
+  @param  Controller            The controller this IP4 service binding instance
+                                is installed. Most like the UNDI handle.
+  @param  ImageHandle           This driver's image handle
+
+  @return Point to the created IP4_INTERFACE, otherwise NULL.
+
+**/
 IP4_INTERFACE *
 Ip4CreateInterface (
   IN  EFI_MANAGED_NETWORK_PROTOCOL  *Mnp,
@@ -205,19 +218,68 @@ Ip4CreateInterface (
   IN  EFI_HANDLE                    ImageHandle
   );
 
+/**
+  Set the interface's address, create and configure
+  the ARP child if necessary.
+
+  @param  Interface             The interface to set the address
+  @param  IpAddr                The interface's IP address
+  @param  SubnetMask            The interface's netmask
+
+  @retval EFI_SUCCESS           The interface is configured with Ip/netmask pair,
+                                and a ARP is created for it.
+  @retval Others                Failed to set the interface's address.
+
+**/
 EFI_STATUS
 Ip4SetAddress (
-  IN  IP4_INTERFACE         *Interface,
-  IN  IP4_ADDR              IpAddr,
-  IN  IP4_ADDR              SubnetMask
+  IN OUT IP4_INTERFACE      *Interface,
+  IN     IP4_ADDR           IpAddr,
+  IN     IP4_ADDR           SubnetMask
   );
 
+/**
+  Free the interface used by IpInstance. All the IP instance with
+  the same Ip/Netmask pair share the same interface. It is reference
+  counted. All the frames haven't been sent will be cancelled.
+  Because the IpInstance is optional, the caller must remove
+  IpInstance from the interface's instance list itself.
+
+  @param  Interface             The interface used by the IpInstance
+  @param  IpInstance            The Ip instance that free the interface. NULL if
+                                the Ip driver is releasing the default interface.
+
+  @retval EFI_SUCCESS           The interface use IpInstance is freed.
+
+**/
 EFI_STATUS
 Ip4FreeInterface (
   IN  IP4_INTERFACE         *Interface,
-  IN  IP4_PROTOCOL          *IpInstance       OPTIONAL
+  IN  IP4_PROTOCOL          *IpInstance           OPTIONAL
   );
 
+/**
+  Send a frame from the interface. If the next hop is broadcast or
+  multicast address, it is transmitted immediately. If the next hop
+  is a unicast, it will consult ARP to resolve the NextHop's MAC.
+  If some error happened, the CallBack won't be called. So, the caller
+  must test the return value, and take action when there is an error.
+
+  @param  Interface             The interface to send the frame from
+  @param  IpInstance            The IP child that request the transmission.  NULL
+                                if it is the IP4 driver itself.
+  @param  Packet                The packet to transmit.
+  @param  NextHop               The immediate destination to transmit the packet
+                                to.
+  @param  CallBack              Function to call back when transmit finished.
+  @param  Context               Opaque parameter to the call back.
+
+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource to send the frame
+  @retval EFI_NO_MAPPING        Can't resolve the MAC for the nexthop
+  @retval EFI_SUCCESS           The packet is successfully transmitted.
+  @retval other                 Other error occurs.
+
+**/
 EFI_STATUS
 Ip4SendFrame (
   IN  IP4_INTERFACE         *Interface,
@@ -228,6 +290,21 @@ Ip4SendFrame (
   IN  VOID                  *Context
   );
 
+/**
+  Remove all the frames on the interface that pass the FrameToCancel,
+  either queued on ARP queues or that have already been delivered to
+  MNP and not yet recycled.
+
+  @param  Interface             Interface to remove the frames from
+  @param  IoStatus              The transmit status returned to the frames'
+                                callback
+  @param  FrameToCancel         Function to select the frame to cancel, NULL to
+                                select all
+  @param  Context               Opaque parameters passed to FrameToCancel
+
+  @return NONE
+
+**/
 VOID
 Ip4CancelFrames (
   IN IP4_INTERFACE          *Interface,
@@ -236,11 +313,40 @@ Ip4CancelFrames (
   IN VOID                   *Context
   );
 
+/**
+  If there is a pending receive request, cancel it. Don't call
+  the receive request's callback because this function can be only
+  called if the instance or driver is tearing itself down. It
+  doesn't make sense to call it back. But it is necessary to call
+  the transmit token's callback to give it a chance to free the
+  packet and update the upper layer's transmit request status, say
+  that from the UDP.
+
+  @param  Interface             The interface used by the IpInstance
+
+  @return None
+
+**/
 VOID
 Ip4CancelReceive (
   IN IP4_INTERFACE          *Interface
   );
 
+/**
+  Request to receive the packet from the interface.
+
+  @param  Interface             The interface to receive the frames from
+  @param  IpInstance            The instance that requests the receive. NULL for
+                                the driver itself.
+  @param  CallBack              Function to call when receive finished.
+  @param  Context               Opaque parameter to the callback
+
+  @retval EFI_ALREADY_STARTED   There is already a pending receive request.
+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource to receive
+  @retval EFI_SUCCESS           The recieve request has been started.
+  @retval other                 Other error occurs.
+
+**/
 EFI_STATUS
 Ip4ReceiveFrame (
   IN  IP4_INTERFACE         *Interface,