#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
UDP access point, and released by user. When sending, the NetBuf is from user,\r
and provided to the callback as a reference.\r
\r
- @param Packet Packet received or sent\r
- @param Points The Udp4 address pair corresponds to the Udp4 IO\r
- @param IoStatus Packet receiving or sending status\r
- @param Context User-defined data when calling UdpIoRecvDatagram() or\r
- UdpIoSendDatagram()\r
-\r
- @return None\r
+ @param[in] Packet Packet received or sent\r
+ @param[in] Points The Udp4 address pair corresponds to the Udp4 IO\r
+ @param[in] IoStatus Packet receiving or sending status\r
+ @param[in] Context User-defined data when calling UdpIoRecvDatagram() or\r
+ UdpIoSendDatagram()\r
**/\r
typedef\r
VOID\r
\r
The prototype is set and called when creating a UDP_IO_PORT in UdpIoCreatePort().\r
\r
- @param UdpIo The UDP_IO_PORT to configure\r
- @param Context User-defined data when calling UdpIoCreatePort()\r
+ @param[in] UdpIo The UDP_IO_PORT to configure\r
+ @param[in] Context User-defined data when calling UdpIoCreatePort()\r
\r
@retval EFI_SUCCESS The configure process succeeds\r
@retval Others The UDP_IO_PORT fails to configure indicating\r
);\r
\r
/**\r
- The select function to decide whether to cancel the UDP_TX_TOKEN. It is used\r
+ The select function to decide whether to cancel the UDP_TX_TOKEN. \r
\r
- @param Token The UDP_TX_TOKEN to decide whether to cancel\r
- @param Context User-defined data in UdpIoCancelDgrams()\r
+ @param[in] Token The UDP_TX_TOKEN to decide whether to cancel\r
+ @param[in] Context User-defined data in UdpIoCancelDgrams()\r
\r
@retval TRUE To cancel the UDP_TX_TOKEN\r
@retval FALSE Do not cancel this UDP_TX_TOKEN\r
in creating or configure the UDP child will lead to the failure of UDP_IO_PORT\r
creation.\r
\r
- @param Controller The controller that has the UDP service binding\r
- protocol installed.\r
- @param Image The image handle for the driver.\r
- @param Configure The function to configure the created UDP child\r
- @param Context The opaque parameter for the Configure funtion.\r
+ @param[in] Controller The controller that has the UDP service binding.\r
+ protocol installed.\r
+ @param[in] Image The image handle for the driver.\r
+ @param[in] Configure The function to configure the created UDP child.\r
+ @param[in] Context The opaque parameter for the Configure funtion.\r
\r
@return Newly-created UDP_IO_PORT or NULL if failed.\r
\r
\r
The function will cancel all sent datagram and receive request.\r
\r
- @param UdpIo The UDP_IO_PORT to free.\r
+ @param[in] UdpIo The UDP_IO_PORT to free.\r
\r
@retval EFI_SUCCESS The UDP_IO_PORT is freed.\r
\r
It will release all the transmitted datagrams and receive request. It will\r
also configure NULL for the UDP instance.\r
\r
- @param UdpIo The UDP_IO_PORT to clean up.\r
+ @param[in] UdpIo The UDP_IO_PORT to clean up.\r
\r
**/\r
VOID\r
when the packet is sent. The optional parameter EndPoint overrides the default\r
address pair if specified.\r
\r
- @param UdpIo The UDP_IO_PORT to send the packet through\r
- @param Packet The packet to send\r
- @param EndPoint The local and remote access point. Override the\r
- default address pair set during configuration.\r
- @param Gateway The gateway to use\r
- @param CallBack The function being called when packet is\r
- transmitted or failed.\r
- @param Context The opaque parameter passed to CallBack\r
+ @param[in] UdpIo The UDP_IO_PORT to send the packet through.\r
+ @param[in] Packet The packet to send.\r
+ @param[in] EndPoint The local and remote access point. Override the\r
+ default address pair set during configuration.\r
+ @param[in] Gateway The gateway to use.\r
+ @param[in] CallBack The function being called when packet is\r
+ transmitted or failed.\r
+ @param[in] Context The opaque parameter passed to CallBack.\r
\r
- @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the packet\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the packet.\r
@retval EFI_SUCCESS The packet is successfully delivered to UDP for\r
transmission.\r
\r
UdpIoSendDatagram (\r
IN UDP_IO_PORT *UdpIo,\r
IN NET_BUF *Packet,\r
- IN UDP_POINTS *EndPoint OPTIONAL,\r
+ IN UDP_POINTS *EndPoint, OPTIONAL\r
IN IP4_ADDR Gateway,\r
IN UDP_IO_CALLBACK CallBack,\r
IN VOID *Context\r
/**\r
Cancel a single sent datagram.\r
\r
- @param UdpIo The UDP_IO_PORT to cancel the packet from\r
- @param Packet The packet to cancel\r
+ @param[in] UdpIo The UDP_IO_PORT to cancel the packet from\r
+ @param[in] Packet The packet to cancel\r
\r
**/\r
VOID\r
to invoke this function inside its Callback function when the former packet\r
is processed.\r
\r
- @param UdpIo The UDP_IO_PORT to receive the packet from.\r
- @param CallBack The call back function to execute when the packet\r
- is received.\r
- @param Context The opaque context passed to Callback\r
- @param HeadLen The length of the upper-layer's protocol header\r
+ @param[in] UdpIo The UDP_IO_PORT to receive the packet from.\r
+ @param[in] CallBack The call back function to execute when the packet\r
+ is received.\r
+ @param[in] Context The opaque context passed to Callback.\r
+ @param[in] HeadLen The length of the upper-layer's protocol header.\r
\r
@retval EFI_ALREADY_STARTED There is already a pending receive request. Only\r
one receive request is supported at a time.\r
projects / mirror_edk2.git / commitdiff