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/Ip4Route.h

@@ -99,32 +99,89 @@ struct _IP4_ROUTE_TABLE {
   IP4_ROUTE_CACHE           Cache;
 };
 
-IP4_ROUTE_TABLE*
+/**
+  Create an empty route table, includes its internal route cache
+
+  @return NULL if failed to allocate memory for the route table, otherwise
+          the point to newly created route table.
+
+**/
+IP4_ROUTE_TABLE *
 Ip4CreateRouteTable (
   VOID
   );
 
+/**
+  Free the route table and its associated route cache. Route
+  table is reference counted.
+
+  @param  RtTable               The route table to free.
+
+  @return None
+
+**/
 VOID
 Ip4FreeRouteTable (
-  IN IP4_ROUTE_TABLE        *RouteTable
+  IN IP4_ROUTE_TABLE        *RtTable
   );
 
+/**
+  Add a route entry to the route table. All the IP4_ADDRs are in
+  host byte order.
+
+  @param  RtTable               Route table to add route to
+  @param  Dest                  The destination of the network
+  @param  Netmask               The netmask of the destination
+  @param  Gateway               The next hop address
+
+  @retval EFI_ACCESS_DENIED     The same route already exists
+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate memory for the entry
+  @retval EFI_SUCCESS           The route is added successfully.
+
+**/
 EFI_STATUS
 Ip4AddRoute (
-  IN IP4_ROUTE_TABLE        *RtTable,
-  IN IP4_ADDR               Dest,
-  IN IP4_ADDR               Netmask,
-  IN IP4_ADDR               Gateway
+  IN OUT IP4_ROUTE_TABLE        *RtTable,
+  IN     IP4_ADDR               Dest,
+  IN     IP4_ADDR               Netmask,
+  IN     IP4_ADDR               Gateway
   );
 
+/**
+  Remove a route entry and all the route caches spawn from it.
+
+  @param  RtTable               The route table to remove the route from
+  @param  Dest                  The destination network
+  @param  Netmask               The netmask of the Dest
+  @param  Gateway               The next hop address
+
+  @retval EFI_SUCCESS           The route entry is successfully removed
+  @retval EFI_NOT_FOUND         There is no route entry in the table with that
+                                properity.
+
+**/
 EFI_STATUS
 Ip4DelRoute (
-  IN IP4_ROUTE_TABLE        *RtTable,
-  IN IP4_ADDR               Dest,
-  IN IP4_ADDR               Netmask,
-  IN IP4_ADDR               Gateway
+  IN OUT IP4_ROUTE_TABLE      *RtTable,
+  IN     IP4_ADDR             Dest,
+  IN     IP4_ADDR             Netmask,
+  IN     IP4_ADDR             Gateway
   );
 
+/**
+  Find a route cache with the dst and src. This is used by ICMP
+  redirect messasge process. All kinds of redirect is treated as
+  host redirect according to RFC1122. So, only route cache entries
+  are modified according to the ICMP redirect message.
+
+  @param  RtTable               The route table to search the cache for
+  @param  Dest                  The destination address
+  @param  Src                   The source address
+
+  @return NULL if no route entry to the (Dest, Src). Otherwise the point
+          to the correct route cache entry.
+
+**/
 IP4_ROUTE_CACHE_ENTRY *
 Ip4FindRouteCache (
   IN IP4_ROUTE_TABLE        *RtTable,
@@ -132,11 +189,31 @@ Ip4FindRouteCache (
   IN IP4_ADDR               Src
   );
 
+/**
+  Free the route cache entry. It is reference counted.
+
+  @param  RtCacheEntry          The route cache entry to free.
+
+  @return None
+
+**/
 VOID
 Ip4FreeRouteCacheEntry (
   IN IP4_ROUTE_CACHE_ENTRY  *RtCacheEntry
   );
 
+/**
+  Search the route table to route the packet. Return/create a route
+  cache if there is a route to the destination.
+
+  @param  RtTable               The route table to search from
+  @param  Dest                  The destination address to search for
+  @param  Src                   The source address to search for
+
+  @return NULL if failed to route packet, otherwise a route cache
+          entry that can be used to route packet.
+
+**/
 IP4_ROUTE_CACHE_ENTRY *
 Ip4Route (
   IN IP4_ROUTE_TABLE        *RtTable,
@@ -144,6 +221,17 @@ Ip4Route (
   IN IP4_ADDR               Src
   );
 
+/**
+  Build a EFI_IP4_ROUTE_TABLE to be returned to the caller of
+  GetModeData. The EFI_IP4_ROUTE_TABLE is clumsy to use in the
+  internal operation of the IP4 driver.
+
+  @param  IpInstance            The IP4 child that requests the route table.
+
+  @retval EFI_SUCCESS           The route table is successfully build
+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate the memory for the rotue table.
+
+**/
 EFI_STATUS
 Ip4BuildEfiRouteTable (
   IN IP4_PROTOCOL           *IpInstance