/** @file\r
- This library provides basic function for UEFI network stack.\r
+ Ihis library is only intended to be used by UEFI network stack modules.\r
+ It provides basic functions for the UEFI network stack.\r
\r
Copyright (c) 2005 - 2008, Intel Corporation\r
All rights reserved. This program and the accompanying materials\r
#ifndef _NET_LIB_H_\r
#define _NET_LIB_H_\r
\r
-#include <Library/BaseMemoryLib.h>\r
-#include <Library/MemoryAllocationLib.h>\r
-#include <Protocol/DriverBinding.h>\r
-#include <Protocol/ComponentName.h>\r
-#include <Protocol/DriverConfiguration.h>\r
-#include <Protocol/DriverDiagnostics.h>\r
-#include <Protocol/Dpc.h>\r
-\r
typedef UINT32 IP4_ADDR;\r
typedef UINT32 TCP_SEQNO;\r
typedef UINT16 TCP_PORTNO;\r
\r
\r
//\r
-// ICMP head definition. ICMP message is categoried as either an error\r
+// ICMP head definition. Each ICMP message is categorized as either an error\r
// message or query message. Two message types have their own head format.\r
//\r
typedef struct {\r
#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. Valid values are 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, or IP4_MASK_NUM (33) 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 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
\r
- @return TRUE if IP is a valid unicast address on the network, otherwise FALSE.\r
+ @return TRUE if Ip is a valid unicast address on the network, otherwise FALSE.\r
\r
**/\r
BOOLEAN\r
IN IP4_ADDR NetMask\r
);\r
\r
-extern IP4_ADDR gIp4AllMasks [IP4_MASK_NUM];\r
+extern IP4_ADDR gIp4AllMasks[IP4_MASK_NUM];\r
\r
\r
extern EFI_IPv4_ADDRESS mZeroIp4Addr;\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
+ This function copies a UINT32 from a byte stream, and 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
+ Puts a UINT32 into the byte stream in network byte order. \r
+ \r
+ Converts a UINT32 from host byte order to network byte order, and then copies 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
- @return The random seed initialized with current time.\r
+ \r
+ Get current time first. Then initialize a random seed based on some basic \r
+ mathematical operations 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
UINT32\r
CR(Entry, Type, Field, Sig)\r
\r
//\r
-// Iterate through the doule linked list. It is NOT delete safe\r
+// Iterate through the double linked list. It is NOT delete safe\r
//\r
#define NET_LIST_FOR_EACH(Entry, ListHead) \\r
for(Entry = (ListHead)->ForwardLink; Entry != (ListHead); Entry = Entry->ForwardLink)\r
\r
//\r
-// Iterate through the doule linked list. This is delete-safe.\r
+// Iterate through the double linked list. This is delete-safe.\r
// Don't touch NextEntry. Also, don't use this macro if list\r
// entries other than the Entry may be deleted when processing\r
// the current Entry.\r
)\r
\r
//\r
-// Make sure the list isn't empty before get the frist/last record.\r
+// Make sure the list isn't empty before getting the first/last record.\r
//\r
#define NET_LIST_HEAD(ListHead, Type, Field) \\r
NET_LIST_USER_STRUCT((ListHead)->ForwardLink, Type, Field)\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 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
- @param[in, out] PrevEntry The previous entry to insert after.\r
+ Insert a new node entry after a designated node entry of a doubly linked list.\r
+ \r
+ Inserts a new node entry designated by NewEntry after the node entry designated by PrevEntry\r
+ of the doubly linked list.\r
+ \r
+ @param[in, out] PrevEntry The entry after which to insert. \r
@param[in, out] NewEntry The new entry to insert.\r
\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 designated by NewEntry before the node entry designated 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 frees 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 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
+ Finds the key in the netmap and returns the point to the item containing 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 created child.\r
\r
- @retval EFI_SUCCESS The child is successfully created.\r
+ @retval EFI_SUCCESS The child was successfully created.\r
@retval Others Failed to create the child.\r
\r
**/\r
);\r
\r
/**\r
- Destory a child of the service that is identified by ServiceBindingGuid.\r
-\r
+ Destroy a child of the service that is identified by ServiceBindingGuid.\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 destroy.\r
\r
- @retval EFI_SUCCESS The child is successfully destoried.\r
- @retval Others Failed to destory the child.\r
+ @retval EFI_SUCCESS The child is successfully destroyed.\r
+ @retval Others Failed to destroy the child.\r
\r
**/\r
EFI_STATUS\r
SnpHandle to a unicode string. Callers are responsible for freeing the\r
string storage.\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
+ 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 on which the simple network protocol is\r
+ installed.\r
+ @param[in] ImageHandle The image handle to act as the agent handle to\r
get the simple network protocol.\r
@param[out] MacString The pointer to store the address of the string\r
representation of the mac address.\r
\r
- @retval EFI_SUCCESS Convert the mac address a unicode string successfully.\r
- @retval EFI_OUT_OF_RESOURCES There are not enough memory resource.\r
+ @retval EFI_SUCCESS Converted the mac address a unicode string successfully.\r
+ @retval EFI_OUT_OF_RESOURCES There are not enough memory resources.\r
@retval Others Failed to open the simple network protocol.\r
\r
**/\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
- For example, IP will open a MNP child to transmit/receive\r
- packets, when MNP is stopped, IP should also be stopped. IP\r
+ \r
+ For example, IP will open an 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
service binding instance that is install on UNDI/SNP handle.\r
Now, the controller is either a MNP or ARP child handle. But\r
IN EFI_GUID *ProtocolGuid\r
);\r
\r
-/**\r
- Add a Deferred Procedure Call to the end of the DPC queue.\r
-\r
- @param[in] DpcTpl The EFI_TPL that the DPC should be invoked.\r
- @param[in] DpcProcedure Pointer to the DPC's function.\r
- @param[in] DpcContext Pointer to the DPC's context. Passed to DpcProcedure\r
- when DpcProcedure is invoked.\r
-\r
- @retval EFI_SUCCESS The DPC was queued.\r
- @retval EFI_INVALID_PARAMETER DpcTpl is not a valid EFI_TPL, or DpcProcedure\r
- is NULL.\r
- @retval EFI_OUT_OF_RESOURCES There are not enough resources available to\r
- add the DPC to the queue.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-NetLibQueueDpc (\r
- IN EFI_TPL DpcTpl,\r
- IN EFI_DPC_PROCEDURE DpcProcedure,\r
- IN VOID *DpcContext OPTIONAL\r
- );\r
-\r
-/**\r
- Dispatch the queue of DPCs. ALL DPCs that have been queued with a DpcTpl\r
- value greater than or equal to the current TPL are invoked in the order that\r
- they were queued. DPCs with higher DpcTpl values are invoked before DPCs with\r
- lower DpcTpl values.\r
-\r
- @retval EFI_SUCCESS One or more DPCs were invoked.\r
- @retval EFI_NOT_FOUND No DPCs were invoked.\r
-\r
-**/\r
-EFI_STATUS\r
-EFIAPI\r
-NetLibDispatchDpc (\r
- VOID\r
- );\r
-\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
} NET_VECTOR;\r
\r
//\r
-//NET_BLOCK_OP operate on the NET_BLOCK, It specifies\r
-//where the actual fragment begins and where it ends\r
+//NET_BLOCK_OP operates on the NET_BLOCK. It specifies\r
+//where the actual fragment begins and ends\r
//\r
typedef struct {\r
UINT8 *BlockHead; // Block's head, or the smallest valid Head\r
\r
//\r
//NET_BUF is the buffer manage structure used by the\r
-//network stack. Every network packet may be fragmented,\r
-//and contains multiple fragments. The Vector points to\r
-//memory blocks used by the each fragment, and BlockOp\r
+//network stack. Every network packet may be fragmented. The Vector points to\r
+//memory blocks used by each fragment, and BlockOp\r
//specifies where each fragment begins and ends.\r
//\r
-//It also contains a opaque area for protocol to store\r
-//per-packet informations. Protocol must be caution not\r
+//It also contains an opaque area for the protocol to store\r
+//per-packet information. Protocol must be careful not\r
//to overwrite the members after that.\r
//\r
typedef struct {\r
\r
\r
//\r
-//A queue of NET_BUFs, It is just a thin extension of\r
+//A queue of NET_BUFs. It is a thin extension of\r
//NET_BUF functions.\r
//\r
typedef struct {\r
\r
@param[in] Len The length of the block.\r
\r
- @return Pointer to the allocated NET_BUF. If NULL the\r
- allocation failed due to resource limit.\r
+ @return Pointer to the allocated NET_BUF, or NULL if the \r
+ allocation failed due to resource limit.\r
\r
**/\r
NET_BUF *\r
);\r
\r
/**\r
- Free the buffer and its associated NET_VECTOR.\r
-\r
+ Free the net buffer and its associated NET_VECTOR.\r
+ \r
+ Decrease the reference count of the net buffer by one. Free the associated net\r
+ vector and itself if the reference count of the net buffer is decreased to 0. \r
+ The net vector free operation decreases the reference count of the net \r
+ vector by one, and performs the resource free operation when the reference count\r
+ of the net vector is 0. \r
+ \r
@param[in] Nbuf Pointer to the NET_BUF to be freed.\r
\r
**/\r
);\r
\r
/**\r
- Get the position of some byte in the net buffer. This can be used\r
- to, for example, retrieve the IP header in the packet. It also\r
- returns the fragment that contains the byte which is used mainly by\r
- the buffer implementation itself.\r
+ Get the index of NET_BLOCK_OP that contains the byte at Offset in the net \r
+ buffer. \r
+ \r
+ For example, this function can be used to retrieve the IP header in the packet. It \r
+ also can be used to get the fragment that contains the byte used \r
+ mainly by the library implementation itself. \r
\r
- @param[in] Nbuf Pointer to the net buffer.\r
- @param[in] Offset The index or offset of the byte.\r
- @param[out] Index Index of the fragment that contains the block.\r
+ @param[in] Nbuf Pointer to the net buffer.\r
+ @param[in] Offset The offset of the byte.\r
+ @param[out] Index Index of the NET_BLOCK_OP that contains the byte at \r
+ Offset.\r
\r
- @return * Pointer to the nth byte of data in the net buffer.\r
- If NULL, there is no such data in the net buffer.\r
+ @return Pointer to the Offset'th byte of data in the net buffer, or NULL\r
+ if there is no such data in the net buffer.\r
\r
**/\r
UINT8 *\r
);\r
\r
/**\r
- Create a copy of NET_BUF that share the associated NET_DATA.\r
+ Create a copy of the net buffer that shares the associated net vector. \r
+ \r
+ The reference count of the newly created net buffer is set to 1. The reference \r
+ count of the associated net vector is increased by one. \r
\r
@param[in] Nbuf Pointer to the net buffer to be cloned.\r
\r
- @return Pointer to the cloned net buffer.If NULL, the\r
+ @return Pointer to the cloned net buffer, or NULL if the\r
allocation failed due to resource limit.\r
\r
**/\r
-NET_BUF *\r
+NET_BUF *\r
EFIAPI\r
NetbufClone (\r
IN NET_BUF *Nbuf\r
);\r
\r
/**\r
- Create a duplicated copy of Nbuf, data is copied. Also leave some\r
- head space before the data.\r
-\r
- @param[in] Nbuf Pointer to the net buffer to be cloned.\r
- @param[in, out] Duplicate Pointer to the net buffer to duplicate to, if NULL\r
- a new net buffer is allocated.\r
- @param[in] HeadSpace Length of the head space to reserve.\r
-\r
- @return Pointer to the duplicated net buffer.If NULL, the\r
- allocation failed due to resource limit.\r
+ Create a duplicated copy of the net buffer with data copied and HeadSpace\r
+ bytes of head space reserved.\r
+ \r
+ The duplicated net buffer will allocate its own memory to hold the data of the\r
+ source net buffer.\r
+ \r
+ @param[in] Nbuf Pointer to the net buffer to be duplicated from.\r
+ @param[in, out] Duplicate Pointer to the net buffer to duplicate to, if \r
+ NULL a new net buffer is allocated.\r
+ @param[in] HeadSpace Length of the head space to reserve.\r
+\r
+ @return Pointer to the duplicated net buffer, or NULL if\r
+ the allocation failed due to resource limit.\r
\r
**/\r
NET_BUF *\r
);\r
\r
/**\r
- Create a NET_BUF structure which contains Len byte data of\r
- Nbuf starting from Offset. A new NET_BUF structure will be\r
- created but the associated data in NET_VECTOR is shared.\r
- This function exists to do IP packet fragmentation.\r
-\r
- @param[in] Nbuf Pointer to the net buffer to be cloned.\r
- @param[in] Offset Starting point of the data to be included in new\r
- buffer.\r
- @param[in] Len How many data to include in new data.\r
- @param[in] HeadSpace How many bytes of head space to reserve for\r
- protocol header.\r
-\r
- @return Pointer to the cloned net buffer.If NULL, the\r
- allocation failed due to resource limit.\r
+ Create a NET_BUF structure which contains Len byte data of Nbuf starting from \r
+ Offset. \r
+ \r
+ A new NET_BUF structure will be created but the associated data in NET_VECTOR \r
+ is shared. This function exists to do IP packet fragmentation. \r
+\r
+ @param[in] Nbuf Pointer to the net buffer to be extracted.\r
+ @param[in] Offset Starting point of the data to be included in the new \r
+ net buffer.\r
+ @param[in] Len Bytes of data to be included in the new net buffer. \r
+ @param[in] HeadSpace Bytes of head space to reserve for protocol header. \r
+\r
+ @return Pointer to the cloned net buffer, or NULL if the \r
+ allocation failed due to resource limit.\r
\r
**/\r
NET_BUF *\r
);\r
\r
/**\r
- Reserve some space in the header room of the buffer.\r
- Upon allocation, all the space are in the tail room\r
- of the buffer. Call this function to move some space\r
- to the header room. This function is quite limited in\r
- that it can only reserver space from the first block\r
- of an empty NET_BUF not built from the external. But\r
- it should be enough for the network stack.\r
+ Reserve some space in the header room of the net buffer.\r
+\r
+ Upon allocation, all the space is in the tail room of the buffer. Call this \r
+ function to move some space to the header room. This function is quite limited\r
+ in that it can only reserve space from the first block of an empty NET_BUF not \r
+ built from the external. But it should be enough for the network stack. \r
\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
- @param[in] Len The length of buffer to be reserverd.\r
+ @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in] Len The length of buffer to be reserved from the header.\r
\r
**/\r
VOID\r
);\r
\r
/**\r
- Allocate some space from the header or tail of the buffer.\r
+ Allocate Len bytes of space from the header or tail of the buffer. \r
\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
- @param[in] Len The length of the buffer to be allocated.\r
- @param [in] FromHead The flag to indicate whether reserve the data from\r
- head or tail. TRUE for from head, and FALSE for\r
- from tail.\r
+ @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in] Len The length of the buffer to be allocated.\r
+ @param[in] FromHead The flag to indicate whether reserve the data \r
+ from head (TRUE) or tail (FALSE).\r
\r
- @return Pointer to the first byte of the allocated buffer.\r
+ @return Pointer to the first byte of the allocated buffer, \r
+ or NULL if there is no sufficient space.\r
\r
**/\r
-UINT8 *\r
+UINT8*\r
EFIAPI\r
NetbufAllocSpace (\r
IN OUT NET_BUF *Nbuf,\r
);\r
\r
/**\r
- Trim some data from the header or tail of the buffer.\r
+ Trim Len bytes from the header or tail of the net buffer. \r
\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
- @param[in] Len The length of the data to be trimmed.\r
- @param[in] FromHead The flag to indicate whether trim data from head or\r
- tail. TRUE for from head, and FALSE for from tail.\r
+ @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in] Len The length of the data to be trimmed.\r
+ @param[in] FromHead The flag to indicate whether trim data from head \r
+ (TRUE) or tail (FALSE).\r
\r
- @return Length of the actually trimmed data.\r
+ @return Length of the actually trimmed data, which may be less \r
+ than Len if the TotalSize of Nbuf is less than Len.\r
\r
**/\r
UINT32\r
);\r
\r
/**\r
- Copy the data from the specific offset to the destination.\r
-\r
- @param[in] Nbuf Pointer to the net buffer.\r
- @param[in] Offset The sequence number of the first byte to copy.\r
- @param[in] Len Length of the data to copy.\r
- @param[in] Dest The destination of the data to copy to.\r
-\r
- @retval UINTN The length of the copied data.\r
+ Copy Len bytes of data from the specific offset of the net buffer to the \r
+ destination memory.\r
+ \r
+ The Len bytes of data may cross several fragments of the net buffer.\r
+ \r
+ @param[in] Nbuf Pointer to the net buffer.\r
+ @param[in] Offset The sequence number of the first byte to copy.\r
+ @param[in] Len Length of the data to copy.\r
+ @param[in] Dest The destination of the data to copy to.\r
+\r
+ @return The length of the actual copied data, or 0 if the offset\r
+ specified exceeds the total size of net buffer.\r
\r
**/\r
UINT32\r
);\r
\r
/**\r
- Build a NET_BUF from external blocks.\r
+ Build a NET_BUF from external blocks. \r
+ \r
+ A new NET_BUF structure will be created from external blocks. An additional block\r
+ of memory will be allocated to hold reserved HeadSpace bytes of header room\r
+ and existing HeadLen bytes of header, but the external blocks are shared by the\r
+ net buffer to avoid data copying.\r
\r
@param[in] ExtFragment Pointer to the data block.\r
- @param[in] ExtNum The number of the data block.\r
+ @param[in] ExtNum The number of the data blocks.\r
@param[in] HeadSpace The head space to be reserved.\r
- @param[in] HeadLen The length of the protocol header, This function\r
- will pull that number of data into a linear block.\r
- @param[in] ExtFree Pointer to the caller provided free function.\r
+ @param[in] HeadLen The length of the protocol header. The function\r
+ pulls this amount of data into a linear block.\r
+ @param[in] ExtFree Pointer to the caller-provided free function.\r
@param[in] Arg The argument passed to ExtFree when ExtFree is\r
called.\r
\r
- @return Pointer to the net buffer built from the data blocks.\r
- If NULL, the allocation failed due to resource limit.\r
+ @return Pointer to the net buffer built from the data blocks, \r
+ or NULL if the allocation failed due to resource\r
+ limit.\r
\r
**/\r
NET_BUF *\r
);\r
\r
/**\r
- Build a fragment table to contain the fragments in the\r
- buffer. This is the opposite of the NetbufFromExt.\r
-\r
+ Build a fragment table to contain the fragments in the net buffer. This is the\r
+ opposite operation of the NetbufFromExt. \r
+ \r
@param[in] Nbuf Point to the net buffer.\r
@param[in, out] ExtFragment Pointer to the data block.\r
- @param[in, out] ExtNum The number of the data block.\r
+ @param[in, out] ExtNum The number of the data blocks.\r
\r
- @retval EFI_BUFFER_TOO_SMALL The number of non-empty block is bigger than ExtNum.\r
- @retval EFI_SUCCESS Fragment table built.\r
+ @retval EFI_BUFFER_TOO_SMALL The number of non-empty blocks is bigger than \r
+ ExtNum.\r
+ @retval EFI_SUCCESS Fragment table is built successfully.\r
\r
**/\r
EFI_STATUS\r
);\r
\r
/**\r
- Build a NET_BUF from a list of NET_BUF.\r
-\r
- @param[in] BufList A List of NET_BUF.\r
- @param[in] HeadSpace The head space to be reserved.\r
- @param[in] HeaderLen The length of the protocol header, This function\r
- will pull that number of data into a linear block.\r
- @param[in] ExtFree Pointer to the caller provided free function.\r
- @param[in] Arg The argument passed to ExtFree when ExtFree is\r
- called.\r
-\r
- @return Pointer to the net buffer built from the data\r
- blocks.\r
+ Build a net buffer from a list of net buffers.\r
+ \r
+ All the fragments will be collected from the list of NEW_BUF and then a new \r
+ net buffer will be created through NetbufFromExt. \r
+ \r
+ @param[in] BufList A List of the net buffer.\r
+ @param[in] HeadSpace The head space to be reserved.\r
+ @param[in] HeaderLen The length of the protocol header. The function\r
+ pulls this amount of data into a linear block.\r
+ @param[in] ExtFree Pointer to the caller provided free function.\r
+ @param[in] Arg The argument passed to ExtFree when ExtFree is called.\r
+\r
+ @return Pointer to the net buffer built from the list of net \r
+ buffers.\r
\r
**/\r
NET_BUF *\r
/**\r
Initiate the net buffer queue.\r
\r
- @param[in, out] NbufQue Pointer to the net buffer queue to be initiated.\r
+ @param[in, out] NbufQue Pointer to the net buffer queue to be initialized.\r
\r
**/\r
VOID\r
);\r
\r
/**\r
- Allocate an initialized net buffer queue.\r
+ Allocate and initialize a net buffer queue.\r
\r
- @return Pointer to the allocated net buffer queue.If NULL, the\r
- allocation failed due to resource limit.\r
+ @return Pointer to the allocated net buffer queue, or NULL if the\r
+ allocation failed due to resource limit.\r
\r
**/\r
NET_BUF_QUEUE *\r
);\r
\r
/**\r
- Free a net buffer queue.\r
+ Free a net buffer queue. \r
+ \r
+ Decrease the reference count of the net buffer queue by one. The real resource\r
+ free operation isn't performed until the reference count of the net buffer \r
+ queue is decreased to 0.\r
\r
- @param[in] NbufQue Poitner to the net buffer queue to be freed.\r
+ @param[in] NbufQue Pointer to the net buffer queue to be freed.\r
\r
**/\r
VOID\r
);\r
\r
/**\r
- Remove a net buffer from head in the specific queue.\r
+ Remove a net buffer from the head in the specific queue and return it.\r
\r
@param[in, out] NbufQue Pointer to the net buffer queue.\r
\r
- @return Pointer to the net buffer removed from the specific\r
- queue. If NULL, there is no net buffer in the specific\r
- queue.\r
+ @return Pointer to the net buffer removed from the specific queue, \r
+ or NULL if there is no net buffer in the specific queue.\r
\r
**/\r
NET_BUF *\r
);\r
\r
/**\r
- Append a buffer to the end of the queue.\r
+ Append a net buffer to the net buffer queue.\r
\r
- @param[in, out] NbufQue Pointer to the net buffer queue.\r
- @param[in, out] Nbuf Pointer to the net buffer to be appended.\r
+ @param[in, out] NbufQue Pointer to the net buffer queue.\r
+ @param[in, out] Nbuf Pointer to the net buffer to be appended.\r
\r
**/\r
VOID\r
);\r
\r
/**\r
- Copy some data from the buffer queue to the destination.\r
-\r
- @param[in] NbufQue Pointer to the net buffer queue.\r
- @param[in] Offset The sequence number of the first byte to copy.\r
- @param[in] Len Length of the data to copy.\r
- @param[out] Dest The destination of the data to copy to.\r
-\r
- @return The length of the copied data. If 0, then the length is zero or offset \r
- suppress the total size of net buffer.\r
+ Copy Len bytes of data from the net buffer queue at the specific offset to the\r
+ destination memory.\r
+ \r
+ The copying operation is the same as NetbufCopy but applies to the net buffer\r
+ queue instead of the net buffer.\r
+ \r
+ @param[in] NbufQue Pointer to the net buffer queue.\r
+ @param[in] Offset The sequence number of the first byte to copy.\r
+ @param[in] Len Length of the data to copy.\r
+ @param[out] Dest The destination of the data to copy to.\r
+\r
+ @return The length of the actual copied data, or 0 if the offset \r
+ specified exceeds the total size of net buffer queue.\r
\r
**/\r
UINT32\r
);\r
\r
/**\r
- Trim some data from the queue header, release the buffer if\r
- whole buffer is trimmed.\r
+ Trim Len bytes of data from the queue header and release any net buffer \r
+ that is trimmed wholely.\r
+ \r
+ The trimming operation is the same as NetbufTrim but applies to the net buffer\r
+ queue instead of the net buffer.\r
\r
@param[in, out] NbufQue Pointer to the net buffer queue.\r
@param[in] Len Length of the data to trim.\r
\r
- @return The length of the data trimmed, or 0 if length of the data to trim is zero.\r
+ @return The actual length of the data trimmed.\r
\r
**/\r
UINT32\r
);\r
\r
/**\r
- Compute checksum for a bulk of data.\r
+ Compute the checksum for a bulk of data.\r
\r
@param[in] Bulk Pointer to the data.\r
@param[in] Len Length of the data, in bytes.\r
);\r
\r
/**\r
- Compute the checksum for TCP/UDP pseudo header.\r
- Src, Dst are in network byte order. and Len is\r
- in host byte order.\r
+ Compute the checksum for TCP/UDP pseudo header. \r
+ \r
+ Src and Dst are in network byte order, and Len is in host byte order.\r
\r
@param[in] Src The source address of the packet.\r
@param[in] Dst The destination address of the packet.\r
projects / mirror_edk2.git / blobdiff