#define EFI_IP4_EQUAL(Ip1, Ip2) (CompareMem ((Ip1), (Ip2), sizeof (EFI_IPv4_ADDRESS)) == 0)\r
\r
/**\r
- Return the length of the mask. If the mask is invalid,\r
- return the invalid length 33, which is IP4_MASK_NUM.\r
+ Return the length of the mask. \r
+ \r
+ Return the length of the mask, the correct value is from 0 to 32.\r
+ If the mask is invalid, return the invalid length 33, which is IP4_MASK_NUM.\r
NetMask is in the host byte order.\r
\r
@param[in] NetMask The netmask to get the length from.\r
\r
- @return The length of the netmask, IP4_MASK_NUM if the mask isn't.\r
+ @return The length of the netmask, IP4_MASK_NUM if the mask is invalid.\r
\r
**/\r
INTN\r
);\r
\r
/**\r
- Return the class of the address, such as class a, b, c.\r
+ Return the class of the IP address, such as class A, B, C.\r
Addr is in host byte order.\r
+ \r
+ The address of class A starts with 0.\r
+ If the address belong to class A, return IP4_ADDR_CLASSA.\r
+ The address of class B starts with 10. \r
+ If the address belong to class B, return IP4_ADDR_CLASSB.\r
+ The address of class C starts with 110. \r
+ If the address belong to class C, return IP4_ADDR_CLASSC.\r
+ The address of class D starts with 1110. \r
+ If the address belong to class D, return IP4_ADDR_CLASSD.\r
+ The address of class E starts with 1111.\r
+ If the address belong to class E, return IP4_ADDR_CLASSE.\r
\r
+ \r
@param[in] Addr The address to get the class from.\r
\r
@return IP address class, such as IP4_ADDR_CLASSA.\r
\r
/**\r
Check whether the IP is a valid unicast address according to\r
- the netmask. If NetMask is zero, use the IP address's class to\r
- get the default mask.\r
+ the netmask. If NetMask is zero, use the IP address's class to get the default mask.\r
+ \r
+ If Ip is 0, IP is not a valid unicast address.\r
+ Class D address is used for multicasting and class E address is reserved for future. If Ip\r
+ belongs to class D or class E, IP is not a valid unicast address. \r
+ If all bits of the host address of IP are 0 or 1, IP is also not a valid unicast address.\r
\r
@param[in] Ip The IP to check against.\r
@param[in] NetMask The mask of the IP.\r
#define NET_RANDOM(Seed) ((UINT32) ((UINT32) (Seed) * 1103515245UL + 12345) % 4294967295UL)\r
\r
/**\r
- Extract a UINT32 from a byte stream, then convert it to host\r
- byte order. Use this function to avoid alignment error.\r
+ Extract a UINT32 from a byte stream.\r
+ \r
+ Copy a UINT32 from a byte stream, then converts it from Network \r
+ byte order to host byte order. Use this function to avoid alignment error.\r
\r
@param[in] Buf The buffer to extract the UINT32.\r
\r
);\r
\r
/**\r
- Put a UINT32 to the byte stream. Convert it from host byte order\r
- to network byte order before putting.\r
+ Put a UINT32 to the byte stream in network byte order. \r
+ \r
+ Converts a UINT32 from host byte order to network byte order. Then copy it to the \r
+ byte stream.\r
\r
@param[in, out] Buf The buffer to put the UINT32.\r
@param[in] Data The data to put.\r
\r
/**\r
Initialize a random seed using current time.\r
-\r
+ \r
+ Get current time first. Then initialize a random seed based on some basic \r
+ mathematics operation on the hour, day, minute, second, nanosecond and year \r
+ of the current time.\r
+ \r
@return The random seed initialized with current time.\r
\r
**/\r
\r
\r
/**\r
- Remove the first entry on the list.\r
+ Remove the first node entry on the list, and return the removed node entry.\r
+ \r
+ Removes the first node Entry from a doubly linked list. It is up to the caller of\r
+ this function to release the memory used by the first node if that is required. On\r
+ exit, the removed node is returned. \r
+\r
+ If Head is NULL, then ASSERT().\r
+ If Head was not initialized, then ASSERT().\r
+ If PcdMaximumLinkedListLength is not zero, and the number of nodes in the\r
+ linked list including the head node is greater than or equal to PcdMaximumLinkedListLength,\r
+ then ASSERT(). \r
\r
@param[in, out] Head The list header.\r
\r
- @return The entry that is removed from the list, NULL if the list is empty.\r
+ @return The first node entry that is removed from the list, NULL if the list is empty.\r
\r
**/\r
LIST_ENTRY *\r
);\r
\r
/**\r
- Remove the last entry on the list.\r
+ Remove the last node entry on the list and and return the removed node entry.\r
+\r
+ Removes the last node entry from a doubly linked list. It is up to the caller of\r
+ this function to release the memory used by the first node if that is required. On\r
+ exit, the removed node is returned. \r
\r
+ If Head is NULL, then ASSERT().\r
+ If Head was not initialized, then ASSERT().\r
+ If PcdMaximumLinkedListLength is not zero, and the number of nodes in the\r
+ linked list including the head node is greater than or equal to PcdMaximumLinkedListLength,\r
+ then ASSERT(). \r
+ \r
@param[in, out] Head The list head.\r
\r
- @return The entry that is removed from the list, NULL if the list is empty.\r
+ @return The last node entry that is removed from the list, NULL if the list is empty.\r
\r
**/\r
LIST_ENTRY *\r
);\r
\r
/**\r
- Insert the NewEntry after the PrevEntry.\r
-\r
+ Insert a new node entry after a designated node entry of a doubly linked list.\r
+ \r
+ Inserts a new node entry donated by NewEntry after the node entry donated by PrevEntry\r
+ of the doubly linked list.\r
+ \r
@param[in, out] PrevEntry The previous entry to insert after.\r
@param[in, out] NewEntry The new entry to insert.\r
\r
);\r
\r
/**\r
- Insert the NewEntry before the PostEntry.\r
-\r
+ Insert a new node entry before a designated node entry of a doubly linked list.\r
+ \r
+ Inserts a new node entry donated by NewEntry after the node entry donated by PostEntry\r
+ of the doubly linked list.\r
+ \r
@param[in, out] PostEntry The entry to insert before.\r
@param[in, out] NewEntry The new entry to insert.\r
\r
\r
/**\r
Initialize the netmap. Netmap is a reposity to keep the <Key, Value> pairs.\r
-\r
+ \r
+ Initialize the forward and backward links of two head nodes donated by Map->Used \r
+ and Map->Recycled of two doubly linked lists.\r
+ Initializes the count of the <Key, Value> pairs in the netmap to zero.\r
+ \r
+ If Map is NULL, then ASSERT().\r
+ If the address of Map->Used is NULL, then ASSERT().\r
+ If the address of Map->Recycled is NULl, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to initialize.\r
\r
**/\r
\r
/**\r
To clean up the netmap, that is, release allocated memories.\r
-\r
+ \r
+ Removes all nodes of the Used doubly linked list and free memory of all related netmap items.\r
+ Removes all nodes of the Recycled doubly linked list and free memory of all related netmap items.\r
+ The number of the <Key, Value> pairs in the netmap is set to be zero.\r
+ \r
+ If Map is NULL, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to clean up.\r
\r
**/\r
);\r
\r
/**\r
- Test whether the netmap is empty.\r
-\r
+ Test whether the netmap is empty and return true if it is.\r
+ \r
+ If the number of the <Key, Value> pairs in the netmap is zero, return TRUE.\r
+ \r
+ If Map is NULL, then ASSERT().\r
+ \r
+ \r
@param[in] Map The net map to test.\r
\r
@return TRUE if the netmap is empty, otherwise FALSE.\r
\r
/**\r
Allocate an item to save the <Key, Value> pair to the head of the netmap.\r
+ \r
+ Allocate an item to save the <Key, Value> pair and add corresponding node entry\r
+ to the beginning of the Used doubly linked list. The number of the <Key, Value> \r
+ pairs in the netmap increase by 1.\r
\r
+ If Map is NULL, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to insert into.\r
@param[in] Key The user's key.\r
@param[in] Value The user's value for the key.\r
/**\r
Allocate an item to save the <Key, Value> pair to the tail of the netmap.\r
\r
+ Allocate an item to save the <Key, Value> pair and add corresponding node entry\r
+ to the tail of the Used doubly linked list. The number of the <Key, Value> \r
+ pairs in the netmap increase by 1.\r
+\r
+ If Map is NULL, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to insert into.\r
@param[in] Key The user's key.\r
@param[in] Value The user's value for the key.\r
);\r
\r
/**\r
- Find the key in the netmap.\r
+ Find the key in the netmap and returns the point to the item contains the Key.\r
+ \r
+ Iterate the Used doubly linked list of the netmap to get every item. Compare the key of every \r
+ item with the key to search. It returns the point to the item contains the Key if found.\r
\r
+ If Map is NULL, then ASSERT().\r
+ \r
@param[in] Map The netmap to search within.\r
@param[in] Key The key to search.\r
\r
);\r
\r
/**\r
- Remove the item from the netmap.\r
-\r
+ Remove the node entry of the item from the netmap and return the key of the removed item.\r
+ \r
+ Remove the node entry of the item from the Used doubly linked list of the netmap. \r
+ The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node \r
+ entry of the item to the Recycled doubly linked list of the netmap. If Value is not NULL,\r
+ Value will point to the value of the item. It returns the key of the removed item.\r
+ \r
+ If Map is NULL, then ASSERT().\r
+ If Item is NULL, then ASSERT().\r
+ if item in not in the netmap, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to remove the item from.\r
@param[in, out] Item The item to remove.\r
@param[out] Value The variable to receive the value if not NULL.\r
);\r
\r
/**\r
- Remove the first entry on the netmap.\r
+ Remove the first node entry on the netmap and return the key of the removed item.\r
\r
+ Remove the first node entry from the Used doubly linked list of the netmap. \r
+ The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node \r
+ entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL,\r
+ parameter Value will point to the value of the item. It returns the key of the removed item.\r
+ \r
+ If Map is NULL, then ASSERT().\r
+ If the Used doubly linked list is empty, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to remove the head from.\r
@param[out] Value The variable to receive the value if not NULL.\r
\r
);\r
\r
/**\r
- Remove the last entry on the netmap.\r
+ Remove the last node entry on the netmap and return the key of the removed item.\r
\r
+ Remove the last node entry from the Used doubly linked list of the netmap. \r
+ The number of the <Key, Value> pairs in the netmap decrease by 1. Then add the node \r
+ entry to the Recycled doubly linked list of the netmap. If parameter Value is not NULL,\r
+ parameter Value will point to the value of the item. It returns the key of the removed item.\r
+ \r
+ If Map is NULL, then ASSERT().\r
+ If the Used doubly linked list is empty, then ASSERT().\r
+ \r
@param[in, out] Map The netmap to remove the tail from.\r
@param[out] Value The variable to receive the value if not NULL.\r
\r
);\r
\r
/**\r
- Iterate through the netmap and call CallBack for each item. It will\r
- contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break\r
- from the loop. It returns the CallBack's last return value. This\r
- function is delete safe for the current item.\r
+ Iterate through the netmap and call CallBack for each item.\r
+ \r
+ It will contiue the traverse if CallBack returns EFI_SUCCESS, otherwise, break\r
+ from the loop. It returns the CallBack's last return value. This function is \r
+ delete safe for the current item.\r
\r
+ If Map is NULL, then ASSERT().\r
+ If CallBack is NULL, then ASSERT().\r
+ \r
@param[in] Map The Map to iterate through.\r
@param[in] CallBack The callback function to call for each item.\r
@param[in] Arg The opaque parameter to the callback.\r
//\r
/**\r
Create a child of the service that is identified by ServiceBindingGuid.\r
+ \r
+ Get the ServiceBinding Protocol first, then use it to create a child.\r
\r
+ If ServiceBindingGuid is NULL, then ASSERT().\r
+ If ChildHandle is NULL, then ASSERT().\r
+ \r
@param[in] Controller The controller which has the service installed.\r
@param[in] Image The image handle used to open service.\r
@param[in] ServiceBindingGuid The service's Guid.\r
- @param[in, out] ChildHandle The handle to receive the create child\r
+ @param[in, out] ChildHandle The handle to receive the create child.\r
\r
@retval EFI_SUCCESS The child is successfully created.\r
@retval Others Failed to create the child.\r
\r
/**\r
Destory a child of the service that is identified by ServiceBindingGuid.\r
-\r
+ \r
+ Get the ServiceBinding Protocol first, then use it to destroy a child.\r
+ \r
+ If ServiceBindingGuid is NULL, then ASSERT().\r
+ \r
@param[in] Controller The controller which has the service installed.\r
@param[in] Image The image handle used to open service.\r
@param[in] ServiceBindingGuid The service's Guid.\r
- @param[in] ChildHandle The child to destory\r
+ @param[in] ChildHandle The child to destory.\r
\r
@retval EFI_SUCCESS The child is successfully destoried.\r
@retval Others Failed to destory the child.\r
SnpHandle to a unicode string. Callers are responsible for freeing the\r
string storage.\r
\r
+ Get the mac address of the Simple Network protocol from the SnpHandle. Then convert\r
+ the mac address into a unicode string. It takes 2 unicode characters to represent \r
+ a 1 byte binary buffer. Plus one unicode character for the null-terminator.\r
+\r
+\r
@param[in] SnpHandle The handle where the simple network protocol is\r
installed on.\r
@param[in] ImageHandle The image handle used to act as the agent handle to\r
\r
/**\r
Create an IPv4 device path node.\r
+ \r
+ The header type of IPv4 device path node is MESSAGING_DEVICE_PATH.\r
+ The header subtype of IPv4 device path node is MSG_IPv4_DP.\r
+ The length of the IPv4 device path node in bytes is 19.\r
+ Get other info from parameters to make up the whole IPv4 device path node.\r
\r
@param[in, out] Node Pointer to the IPv4 device path node.\r
@param[in] Controller The handle where the NIC IP4 config protocol resides.\r
\r
/**\r
Find the UNDI/SNP handle from controller and protocol GUID.\r
+ \r
For example, IP will open a MNP child to transmit/receive\r
packets, when MNP is stopped, IP should also be stopped. IP\r
needs to find its own private data which is related the IP's\r
/**\r
This is the default unload handle for all the network drivers.\r
\r
+ Disconnect the driver specified by ImageHandle from all the devices in the handle database.\r
+ Uninstall all the protocols installed in the driver entry point.\r
+ \r
@param[in] ImageHandle The drivers' driver image.\r
\r
@retval EFI_SUCCESS The image is unloaded.\r
projects / mirror_edk2.git / blobdiff