/** @file\r
- Network library.\r
+ Network library functions providing net buffer operation support.\r
\r
Copyright (c) 2005 - 2006, Intel Corporation.<BR>\r
All rights reserved. This program and the accompanying materials\r
\r
\r
/**\r
- Allocate and build up the sketch for a NET_BUF. The net buffer allocated\r
- has the BlockOpNum's NET_BLOCK_OP, and its associated NET_VECTOR has the\r
- BlockNum's NET_BLOCK.\r
+ Allocate and build up the sketch for a NET_BUF. \r
+ \r
+ The net buffer allocated has the BlockOpNum's NET_BLOCK_OP, and its associated \r
+ NET_VECTOR has the BlockNum's NET_BLOCK. But all the NET_BLOCK_OP and\r
+ NET_BLOCK remain un-initialized.\r
\r
- @param[in] BlockNum The number of NET_BLOCK in the Vector of net buffer\r
- @param[in] BlockOpNum The number of NET_BLOCK_OP in the net buffer\r
+ @param[in] BlockNum The number of NET_BLOCK in the vector of net buffer\r
+ @param[in] BlockOpNum The number of NET_BLOCK_OP in the net buffer\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
@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
return NULL;\r
}\r
\r
-\r
/**\r
- Free the vector.\r
+ Free the vector. \r
+ \r
+ Decrease the reference count of the vector by one. The real resource free \r
+ operation isn't performed until the reference count of the vector is decreased \r
+ to 0.\r
\r
@param[in] Vector Pointer to the NET_VECTOR to be freed.\r
\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\r
+ vector and itself if the reference count of the net buffer is decreased to 0.\r
+ The vector free operation just decrease the reference count of the vector by\r
+ one and do the real resource free operation when the reference count of the\r
+ vector is 0.\r
+ \r
@param[in] Nbuf Pointer to the NET_BUF to be freed.\r
\r
**/\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
Free a list of net buffers.\r
\r
@param[in, out] Head Pointer to the head of linked net buffers.\r
-\r
+NOT YET\r
**/\r
VOID\r
EFIAPI\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
+ This can be used to, for example, retrieve the IP header in the packet. It \r
+ also can be used to get the fragment that contains the byte which is 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 nth byte of data in the net buffer, or NULL \r
+ indicating there is no such data in the net buffer.\r
\r
**/\r
UINT8 *\r
\r
\r
/**\r
- Set the NET_BLOCK and corresponding NET_BLOCK_OP in\r
- the buffer. All the pointers in NET_BLOCK and NET_BLOCK_OP\r
- are set to the bulk's head and tail respectively. So, this\r
- function alone can't be used by NetbufAlloc.\r
-\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
- @param[in] Bulk Pointer to the data.\r
- @param[in] Len Length of the bulk data.\r
- @param[in] Index The data block index in the net buffer the bulk\r
- data should belong to.\r
- \r
+ Set the NET_BLOCK and corresponding NET_BLOCK_OP in the net buffer and \r
+ corresponding net vector according to the bulk pointer and bulk length.\r
+ \r
+ All the pointers in the Index'th NET_BLOCK and NET_BLOCK_OP are set to the \r
+ bulk's head and tail respectively. So, this function alone can't be used by \r
+ NetbufAlloc. \r
+\r
+ @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in] Bulk Pointer to the data.\r
+ @param[in] Len Length of the bulk data.\r
+ @param[in] Index The data block index in the net buffer the bulk\r
+ data should belong to.\r
+\r
**/\r
VOID\r
NetbufSetBlock (\r
\r
\r
/**\r
- Set the NET_BLOCK_OP in the buffer. The corresponding NET_BLOCK\r
- structure is left untouched. Some times, there is no 1:1 relationship\r
- between NET_BLOCK and NET_BLOCK_OP. For example, that in NetbufGetFragment.\r
-\r
- @param[in, out] Nbuf Pointer to the net buffer.\r
- @param[in] Bulk Pointer to the data.\r
- @param[in] Len Length of the bulk data.\r
- @param[in] Index The data block index in the net buffer the bulk\r
- data should belong to.\r
+ Set the NET_BLOCK_OP in the net buffer. The corresponding NET_BLOCK\r
+ structure is left untouched. \r
+ \r
+ Some times, there is no 1:1 relationship between NET_BLOCK and NET_BLOCK_OP. \r
+ For example, that in NetbufGetFragment. \r
+\r
+ @param[in, out] Nbuf Pointer to the net buffer.\r
+ @param[in] Bulk Pointer to the data.\r
+ @param[in] Len Length of the bulk data.\r
+ @param[in] Index The data block index in the net buffer the bulk \r
+ data should belong to.\r
\r
**/\r
VOID\r
the old NET_VECTOR.\r
\r
@param[in] Arg Point to the old NET_VECTOR.\r
-\r
+NOT YET\r
**/\r
VOID\r
NetbufGetFragmentFree (\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 indicating \r
+ the allocation failed due to resource limit.\r
\r
**/\r
NET_BUF *\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. 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] 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 indicating the allocation failed due to\r
+ resource 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 block 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, 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 called.\r
+\r
+ @return Pointer to the net buffer built from the list of net \r
+ buffers.\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
- @param[in, out] Nbuf Pointer to the net buffer.\r
- @param[in] Len The length of buffer to be reserverd.\r
+ Upon allocation, all the space are 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 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 indicating 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 a single NET_BLOCK.\r
+ Trim a single NET_BLOCK by Len bytes from the header or tail.\r
\r
- @param[in, out] BlockOp Pointer to the NET_BLOCK.\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] BlockOp Pointer to the NET_BLOCK.\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
**/\r
VOID\r
IN BOOLEAN FromHead\r
)\r
{\r
- ASSERT (BlockOp && (BlockOp->Size >= Len));\r
+ ASSERT ((BlockOp != NULL) && (BlockOp->Size >= Len));\r
\r
BlockOp->Size -= Len;\r
\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 is possible to be less \r
+ than Len because 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 the 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 exceeds the total size of net buffer.\r
\r
**/\r
UINT32\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
- 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
- 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 indicating there is no net buffer in the specific\r
+ queue.\r
\r
**/\r
NET_BUF *\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 indicating 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, release any of the net buffer \r
+ whom 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