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

1 files changed, 190 insertions, 39 deletions

diff --git a/MdeModulePkg/Library/DxeNetLib/DxeNetLib.c b/MdeModulePkg/Library/DxeNetLib/DxeNetLib.c
index bb0ac06851..c8cb71b06f 100644
--- a/MdeModulePkg/Library/DxeNetLib/DxeNetLib.c
+++ b/MdeModulePkg/Library/DxeNetLib/DxeNetLib.c
@@ -78,13 +78,15 @@ IP4_ADDR  gIp4AllMasks[IP4_MASK_NUM] = {
 EFI_IPv4_ADDRESS  mZeroIp4Addr = {{0, 0, 0, 0}};

 

 /**

-  Return the length of the mask. If the mask is invalid,

-  return the invalid length 33, which is IP4_MASK_NUM.

+  Return the length of the mask. 

+  

+  Return the length of the mask, the correct value is from 0 to 32.

+  If the mask is invalid, return the invalid length 33, which is IP4_MASK_NUM.

   NetMask is in the host byte order.

 

   @param[in]  NetMask              The netmask to get the length from.

 

-  @return The length of the netmask, IP4_MASK_NUM if the mask isn't.

+  @return The length of the netmask, IP4_MASK_NUM if the mask is invalid.

   

 **/

 INTN

@@ -107,9 +109,21 @@ NetGetMaskLength (
 

 

 /**

-  Return the class of the address, such as class a, b, c.

+  Return the class of the IP address, such as class A, B, C.

   Addr is in host byte order.

+  

+  The address of class A  starts with 0.

+  If the address belong to class A, return IP4_ADDR_CLASSA.

+  The address of class B  starts with 10. 

+  If the address belong to class B, return IP4_ADDR_CLASSB.

+  The address of class C  starts with 110. 

+  If the address belong to class C, return IP4_ADDR_CLASSC.

+  The address of class D  starts with 1110. 

+  If the address belong to class D, return IP4_ADDR_CLASSD.

+  The address of class E  starts with 1111.

+  If the address belong to class E, return IP4_ADDR_CLASSE.

 

+  

   @param[in]   Addr                  The address to get the class from.

 

   @return IP address class, such as IP4_ADDR_CLASSA.

@@ -146,8 +160,12 @@ NetGetIpClass (
 

 /**

   Check whether the IP is a valid unicast address according to

-  the netmask. If NetMask is zero, use the IP address's class to

-  get the default mask.

+  the netmask. If NetMask is zero, use the IP address's class to get the default mask.

+  

+  If Ip is 0, IP is not a valid unicast address.

+  Class D address is used for multicasting and class E address is reserved for future. If Ip

+  belongs to class D or class E, IP is not a valid unicast address. 

+  If all bits of the host address of IP are 0 or 1, IP is also not a valid unicast address.

 

   @param[in]  Ip                    The IP to check against.

   @param[in]  NetMask               The mask of the IP.

@@ -184,7 +202,11 @@ Ip4IsUnicast (
 

 /**

   Initialize a random seed using current time.

-

+  

+  Get current time first. Then initialize a random seed based on some basic 

+  mathematics operation on the hour, day, minute, second, nanosecond and year 

+  of the current time.

+  

   @return The random seed initialized with current time.

 

 **/

@@ -207,8 +229,10 @@ NetRandomInitSeed (
 

 

 /**

-  Extract a UINT32 from a byte stream, then convert it to host

-  byte order. Use this function to avoid alignment error.

+  Extract a UINT32 from a byte stream.

+  

+  Copy a UINT32 from a byte stream, then converts it from Network 

+  byte order to host byte order. Use this function to avoid alignment error.

 

   @param[in]  Buf                 The buffer to extract the UINT32.

 

@@ -229,8 +253,10 @@ NetGetUint32 (
 

 

 /**

-  Put a UINT32 to the byte stream. Convert it from host byte order

-  to network byte order before putting.

+  Put a UINT32 to the byte stream in network byte order. 

+  

+  Converts a UINT32 from host byte order to network byte order. Then copy it to the 

+  byte stream.

 

   @param[in, out]  Buf          The buffer to put the UINT32.

   @param[in]      Data          The data to put.

@@ -249,11 +275,21 @@ NetPutUint32 (
 

 

 /**

-  Remove the first entry on the list.

+  Remove the first node entry on the list, and return the removed node entry.

+  

+  Removes the first node Entry from a doubly linked list. It is up to the caller of

+  this function to release the memory used by the first node if that is required. On

+  exit, the removed node is returned. 

+

+  If Head is NULL, then ASSERT().

+  If Head was not initialized, then ASSERT().

+  If PcdMaximumLinkedListLength is not zero, and the number of nodes in the

+  linked list including the head node is greater than or equal to PcdMaximumLinkedListLength,

+  then ASSERT().    

 

   @param[in, out]  Head                  The list header.

 

-  @return The entry that is removed from the list, NULL if the list is empty.

+  @return The first node entry that is removed from the list, NULL if the list is empty.

 

 **/

 LIST_ENTRY *

@@ -284,11 +320,21 @@ NetListRemoveHead (
 

 

 /**

-  Remove the last entry on the list.

+  Remove the last node entry on the list and and return the removed node entry.

+

+  Removes the last node entry from a doubly linked list. It is up to the caller of

+  this function to release the memory used by the first node if that is required. On

+  exit, the removed node is returned. 

 

+  If Head is NULL, then ASSERT().

+  If Head was not initialized, then ASSERT().

+  If PcdMaximumLinkedListLength is not zero, and the number of nodes in the

+  linked list including the head node is greater than or equal to PcdMaximumLinkedListLength,

+  then ASSERT(). 

+  

   @param[in, out]  Head                  The list head.

 

-  @return The entry that is removed from the list, NULL if the list is empty.

+  @return The last node entry that is removed from the list, NULL if the list is empty.

 

 **/

 LIST_ENTRY *

@@ -319,8 +365,11 @@ NetListRemoveTail (
 

 

 /**

-  Insert the NewEntry after the PrevEntry.

-

+  Insert a new node entry after a designated node entry of a doubly linked list.

+  

+  Inserts a new node entry donated by NewEntry after the node entry donated by PrevEntry

+  of the doubly linked list.

+ 

   @param[in, out]  PrevEntry             The previous entry to insert after.

   @param[in, out]  NewEntry              The new entry to insert.

 

@@ -340,8 +389,11 @@ NetListInsertAfter (
 

 

 /**

-  Insert the NewEntry before the PostEntry.

-

+  Insert a new node entry before a designated node entry of a doubly linked list.

+  

+  Inserts a new node entry donated by NewEntry after the node entry donated by PostEntry

+  of the doubly linked list.

+ 

   @param[in, out]  PostEntry             The entry to insert before.

   @param[in, out]  NewEntry              The new entry to insert.

 

@@ -362,7 +414,15 @@ NetListInsertBefore (
 

 /**

   Initialize the netmap. Netmap is a reposity to keep the <Key, Value> pairs.

-

+ 

+  Initialize the forward and backward links of two head nodes donated by Map->Used 

+  and Map->Recycled of two doubly linked lists.

+  Initializes the count of the <Key, Value> pairs in the netmap to zero.

+   

+  If Map is NULL, then ASSERT().

+  If the address of Map->Used is NULl, then ASSERT().

+  If the address of Map->Recycled is NULl, then ASSERT().

+ 

   @param[in, out]  Map                   The netmap to initialize.

 

 **/

@@ -382,7 +442,13 @@ NetMapInit (
 

 /**

   To clean up the netmap, that is, release allocated memories.

-

+  

+  Removes all nodes of the Used doubly linked list and free memory of all related netmap items.

+  Removes all nodes of the Recycled doubly linked list and free memory of all related netmap items.

+  The number of the <Key, Value> pairs in the netmap is set to be zero.

+  

+  If Map is NULL, then ASSERT().

+  

   @param[in, out]  Map                   The netmap to clean up.

 

 **/

@@ -421,8 +487,13 @@ NetMapClean (
 

 

 /**

-  Test whether the netmap is empty.

-

+  Test whether the netmap is empty and return true if it is.

+  

+  If the number of the <Key, Value> pairs in the netmap is zero, return TRUE.

+   

+  If Map is NULL, then ASSERT().

+ 

+  

   @param[in]  Map                   The net map to test.

 

   @return TRUE if the netmap is empty, otherwise FALSE.

@@ -458,9 +529,15 @@ NetMapGetCount (
 

 

 /**

-  Allocate an item for the netmap. It will try to allocate.

-  a batch of items and return one.

-

+  Return one allocated item. 

+  

+  If the Recycled doubly linked list of the netmap is empty, it will try to allocate 

+  a batch of items if there are enough resources and add corresponding nodes to the begining

+  of the Recycled doubly linked list of the netmap. Otherwise, it will directly remove

+  the fist node entry of the Recycled doubly linked list and return the corresponding item.

+  

+  If Map is NULL, then ASSERT().

+  

   @param[in, out]  Map          The netmap to allocate item for.

 

   @return                       The allocated item. If NULL, the

@@ -505,7 +582,13 @@ NetMapAllocItem (
 

 /**

   Allocate an item to save the <Key, Value> pair to the head of the netmap.

+  

+  Allocate an item to save the <Key, Value> pair and add corresponding node entry

+  to the beginning of the Used doubly linked list. The number of the <Key, Value> 

+  pairs in the netmap increase by 1.

 

+  If Map is NULL, then ASSERT().

+  

   @param[in, out]  Map                   The netmap to insert into.

   @param[in]       Key                   The user's key.

   @param[in]       Value                 The user's value for the key.

@@ -544,6 +627,12 @@ NetMapInsertHead (
 /**

   Allocate an item to save the <Key, Value> pair to the tail of the netmap.

 

+  Allocate an item to save the <Key, Value> pair and add corresponding node entry

+  to the tail of the Used doubly linked list. The number of the <Key, Value> 

+  pairs in the netmap increase by 1.

+

+  If Map is NULL, then ASSERT().

+  

   @param[in, out]  Map                   The netmap to insert into.

   @param[in]       Key                   The user's key.

   @param[in]       Value                 The user's value for the key.

@@ -581,7 +670,7 @@ NetMapInsertTail (
 

 

 /**

-  Check whther the item is in the Map.

+  Check whether the item is in the Map and return TRUE if it is.

 

   @param[in]  Map                   The netmap to search within.

   @param[in]  Item                  The item to search.

@@ -608,8 +697,13 @@ NetItemInMap (
 

 

 /**

-  Find the key in the netmap.

+  Find the key in the netmap and returns the point to the item contains the Key.

+  

+  Iterate the Used doubly linked list of the netmap to get every item. Compare the key of every 

+  item with the key to search. It returns the point to the item contains the Key if found.

 

+  If Map is NULL, then ASSERT().

+  

   @param[in]  Map                   The netmap to search within.

   @param[in]  Key                   The key to search.

 

@@ -641,8 +735,17 @@ NetMapFindKey (
 

 

 /**

-  Remove the item from the netmap.

-

+  Remove the node entry of the item from the netmap and return the key of the removed item.

+  

+  Remove the node entry of the item from the Used doubly linked list of the netmap. 

+  The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node 

+  entry of the item to the Recycled doubly linked list of the netmap. If Value is not NULL,

+  Value will point to the value of the item. It returns the key of the removed item.

+  

+  If Map is NULL, then ASSERT().

+  If Item is NULL, then ASSERT().

+  if item in not in the netmap, then ASSERT().

+  

   @param[in, out]  Map                   The netmap to remove the item from.

   @param[in, out]  Item                  The item to remove.

   @param[out]      Value                 The variable to receive the value if not NULL.

@@ -674,8 +777,16 @@ NetMapRemoveItem (
 

 

 /**

-  Remove the first entry on the netmap.

+  Remove the first node entry on the netmap and return the key of the removed item.

 

+  Remove the first node entry from the Used doubly linked list of the netmap. 

+  The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node 

+  entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL,

+  parameter Value will point to the value of the item. It returns the key of the removed item.

+  

+  If Map is NULL, then ASSERT().

+  If the Used doubly linked list is empty, then ASSERT().

+  

   @param[in, out]  Map                   The netmap to remove the head from.

   @param[out]      Value                 The variable to receive the value if not NULL.

 

@@ -711,8 +822,16 @@ NetMapRemoveHead (
 

 

 /**

-  Remove the last entry on the netmap.

+  Remove the last node entry on the netmap and return the key of the removed item.

 

+  Remove the last node entry from the Used doubly linked list of the netmap. 

+  The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node 

+  entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL,

+  parameter Value will point to the value of the item. It returns the key of the removed item.

+  

+  If Map is NULL, then ASSERT().

+  If the Used doubly linked list is empty, then ASSERT().

+  

   @param[in, out]  Map                   The netmap to remove the tail from.

   @param[out]      Value                 The variable to receive the value if not NULL.

 

@@ -748,11 +867,15 @@ NetMapRemoveTail (
 

 

 /**

-  Iterate through the netmap and call CallBack for each item. It will

-  contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break

-  from the loop. It returns the CallBack's last return value. This

-  function is delete safe for the current item.

+  Iterate through the netmap and call CallBack for each item.

+  

+  It will contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break

+  from the loop. It returns the CallBack's last return value. This function is 

+  delete safe for the current item.

 

+  If Map is NULL, then ASSERT().

+  If CallBack is NULL, then ASSERT().

+  

   @param[in]  Map                   The Map to iterate through.

   @param[in]  CallBack              The callback function to call for each item.

   @param[in]  Arg                   The opaque parameter to the callback.

@@ -774,8 +897,8 @@ NetMapIterate (
   LIST_ENTRY            *Entry;

   LIST_ENTRY            *Next;

   LIST_ENTRY            *Head;

-  NET_MAP_ITEM              *Item;

-  EFI_STATUS                Result;

+  NET_MAP_ITEM          *Item;

+  EFI_STATUS            Result;

 

   ASSERT ((Map != NULL) && (CallBack != NULL));

 

@@ -801,6 +924,9 @@ NetMapIterate (
 /**

   This is the default unload handle for all the network drivers.

 

+  Disconnect the driver specified by ImageHandle from all the devices in the handle database.

+  Uninstall all the protocols installed in the driver entry point.

+  

   @param[in]  ImageHandle       The drivers' driver image.

 

   @retval EFI_SUCCESS           The image is unloaded.

@@ -914,7 +1040,12 @@ NetLibDefaultUnload (
 

 /**

   Create a child of the service that is identified by ServiceBindingGuid.

+  

+  Get the ServiceBinding Protocol first, then use it to create a child.

 

+  If ServiceBindingGuid is NULL, then ASSERT().

+  If ChildHandle is NULL, then ASSERT().

+  

   @param[in]       Controller            The controller which has the service installed.

   @param[in]       Image                 The image handle used to open service.

   @param[in]       ServiceBindingGuid    The service's Guid.

@@ -965,7 +1096,11 @@ NetLibCreateServiceChild (
 

 /**

   Destory a child of the service that is identified by ServiceBindingGuid.

-

+  

+  Get the ServiceBinding Protocol first, then use it to destroy a child.

+  

+  If ServiceBindingGuid is NULL, then ASSERT().

+  

   @param[in]   Controller            The controller which has the service installed.

   @param[in]   Image                 The image handle used to open service.

   @param[in]   ServiceBindingGuid    The service's Guid.

@@ -1018,6 +1153,11 @@ NetLibDestroyServiceChild (
   SnpHandle to a unicode string. Callers are responsible for freeing the

   string storage.

 

+  Get the mac address of the Simple Network protocol from the SnpHandle. Then convert

+  the mac address into a unicode string. It takes 2 unicode characters to represent 

+  a 1 byte binary buffer. Plus one unicode character for the null-terminator.

+

+

   @param[in]   SnpHandle             The handle where the simple network protocol is

                                      installed on.

   @param[in]   ImageHandle           The image handle used to act as the agent handle to

@@ -1091,6 +1231,11 @@ NetLibGetMacString (
   Check the default address used by the IPv4 driver is static or dynamic (acquired

   from DHCP).

 

+  If the controller handle does not have the NIC Ip4 Config Protocol installed, the 

+  default address is static. If the EFI variable to save the configuration is not found,

+  the default address is static. Otherwise, get the result from the EFI variable which 

+  saving the configuration.

+   

   @param[in]   Controller     The controller handle which has the NIC Ip4 Config Protocol

                               relative with the default address to judge.

 

@@ -1146,6 +1291,11 @@ ON_EXIT:
 

 /**

   Create an IPv4 device path node.

+  

+  The header type of IPv4 device path node is MESSAGING_DEVICE_PATH.

+  The header subtype of IPv4 device path node is MSG_IPv4_DP.

+  The length of the IPv4 device path node in bytes is 19.

+  Get other info from parameters to make up the whole IPv4 device path node.

 

   @param[in, out]  Node                  Pointer to the IPv4 device path node.

   @param[in]       Controller            The handle where the NIC IP4 config protocol resides.

@@ -1192,6 +1342,7 @@ NetLibCreateIPv4DPathNode (
 

 /**

   Find the UNDI/SNP handle from controller and protocol GUID.

+  

   For example, IP will open a MNP child to transmit/receive

   packets, when MNP is stopped, IP should also be stopped. IP

   needs to find its own private data which is related the IP's