diff options
author | ywu21 <ywu21@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-29 01:28:11 +0000 |
---|---|---|
committer | ywu21 <ywu21@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-29 01:28:11 +0000 |
commit | b9008c87ebabcdd2bde1b8a7fd6497a8bbb20b1e (patch) | |
tree | daab01ed274c08d29029b721887eef34c35efe53 | |
parent | f381602727922e793de5826ee390344cb907e07a (diff) | |
download | edk2-platforms-b9008c87ebabcdd2bde1b8a7fd6497a8bbb20b1e.tar.xz |
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7144 6f19259b-4bc3-4df7-8a09-765794883524
-rw-r--r-- | MdeModulePkg/Library/DxeNetLib/DxeNetLib.c | 229 |
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
|