From 7557df4df36b29baa1c3b65dba90d415b7896e05 Mon Sep 17 00:00:00 2001 From: niry Date: Thu, 25 Dec 2008 14:19:52 +0000 Subject: [PATCH] Add more comments for Netbuf* functions in NetLib.h git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7126 6f19259b-4bc3-4df7-8a09-765794883524 --- MdeModulePkg/Include/Library/NetLib.h | 282 +++++++++++++++----------- 1 file changed, 160 insertions(+), 122 deletions(-) diff --git a/MdeModulePkg/Include/Library/NetLib.h b/MdeModulePkg/Include/Library/NetLib.h index c234defe11..c317f76899 100644 --- a/MdeModulePkg/Include/Library/NetLib.h +++ b/MdeModulePkg/Include/Library/NetLib.h @@ -893,8 +893,8 @@ typedef struct { @param[in] Len The length of the block. - @return Pointer to the allocated NET_BUF. If NULL the - allocation failed due to resource limit. + @return Pointer to the allocated NET_BUF, or NULL if the + allocation failed due to resource limit. **/ NET_BUF * @@ -904,8 +904,14 @@ NetbufAlloc ( ); /** - Free the buffer and its associated NET_VECTOR. - + Free the net buffer and its associated NET_VECTOR. + + Decrease the reference count of the net buffer by one. Free the associated net + vector and itself if the reference count of the net buffer is decreased to 0. + The net vector free operation just decrease the reference count of the net + vector by one and do the real resource free operation when the reference count + of the net vector is 0. + @param[in] Nbuf Pointer to the NET_BUF to be freed. **/ @@ -916,17 +922,20 @@ NetbufFree ( ); /** - Get the position of some byte in the net buffer. This can be used - to, for example, retrieve the IP header in the packet. It also - returns the fragment that contains the byte which is used mainly by - the buffer implementation itself. + Get the index of NET_BLOCK_OP that contains the byte at Offset in the net + buffer. + + This can be used to, for example, retrieve the IP header in the packet. It + also can be used to get the fragment that contains the byte which is used + mainly by the library implementation itself. - @param[in] Nbuf Pointer to the net buffer. - @param[in] Offset The index or offset of the byte. - @param[out] Index Index of the fragment that contains the block. + @param[in] Nbuf Pointer to the net buffer. + @param[in] Offset The offset of the byte. + @param[out] Index Index of the NET_BLOCK_OP that contains the byte at + Offset. - @return * Pointer to the nth byte of data in the net buffer. - If NULL, there is no such data in the net buffer. + @return Pointer to the Offset'th byte of data in the net buffer, or NULL + if there is no such data in the net buffer. **/ UINT8 * @@ -938,31 +947,37 @@ NetbufGetByte ( ); /** - Create a copy of NET_BUF that share the associated NET_DATA. + Create a copy of the net buffer that shares the associated net vector. + + The reference count of the newly created net buffer is set to 1. The reference + count of the associated net vector is increased by one. @param[in] Nbuf Pointer to the net buffer to be cloned. - @return Pointer to the cloned net buffer.If NULL, the + @return Pointer to the cloned net buffer, or NULL if the allocation failed due to resource limit. **/ -NET_BUF * +NET_BUF * EFIAPI NetbufClone ( IN NET_BUF *Nbuf ); /** - Create a duplicated copy of Nbuf, data is copied. Also leave some - head space before the data. - - @param[in] Nbuf Pointer to the net buffer to be cloned. - @param[in, out] Duplicate Pointer to the net buffer to duplicate to, if NULL - a new net buffer is allocated. - @param[in] HeadSpace Length of the head space to reserve. - - @return Pointer to the duplicated net buffer.If NULL, the - allocation failed due to resource limit. + Create a duplicated copy of the net buffer with data copied and HeadSpace + bytes of head space reserved. + + The duplicated net buffer will allocate its own memory to hold the data of the + source net buffer. + + @param[in] Nbuf Pointer to the net buffer to be duplicated from. + @param[in, out] Duplicate Pointer to the net buffer to duplicate to, if + NULL a new net buffer is allocated. + @param[in] HeadSpace Length of the head space to reserve. + + @return Pointer to the duplicated net buffer, or NULL if + the allocation failed due to resource limit. **/ NET_BUF * @@ -974,20 +989,20 @@ NetbufDuplicate ( ); /** - Create a NET_BUF structure which contains Len byte data of - Nbuf starting from Offset. A new NET_BUF structure will be - created but the associated data in NET_VECTOR is shared. - This function exists to do IP packet fragmentation. - - @param[in] Nbuf Pointer to the net buffer to be cloned. - @param[in] Offset Starting point of the data to be included in new - buffer. - @param[in] Len How many data to include in new data. - @param[in] HeadSpace How many bytes of head space to reserve for - protocol header. - - @return Pointer to the cloned net buffer.If NULL, the - allocation failed due to resource limit. + Create a NET_BUF structure which contains Len byte data of Nbuf starting from + Offset. + + A new NET_BUF structure will be created but the associated data in NET_VECTOR + is shared. This function exists to do IP packet fragmentation. + + @param[in] Nbuf Pointer to the net buffer to be extracted. + @param[in] Offset Starting point of the data to be included in the new + net buffer. + @param[in] Len Bytes of data to be included in the new net buffer. + @param[in] HeadSpace Bytes of head space to reserve for protocol header. + + @return Pointer to the cloned net buffer, or NULL if the + allocation failed due to resource limit. **/ NET_BUF * @@ -1000,16 +1015,15 @@ NetbufGetFragment ( ); /** - Reserve some space in the header room of the buffer. - Upon allocation, all the space are in the tail room - of the buffer. Call this function to move some space - to the header room. This function is quite limited in - that it can only reserver space from the first block - of an empty NET_BUF not built from the external. But - it should be enough for the network stack. + Reserve some space in the header room of the net buffer. + + Upon allocation, all the space are in the tail room of the buffer. Call this + function to move some space to the header room. This function is quite limited + in that it can only reserve space from the first block of an empty NET_BUF not + built from the external. But it should be enough for the network stack. - @param[in, out] Nbuf Pointer to the net buffer. - @param[in] Len The length of buffer to be reserverd. + @param[in, out] Nbuf Pointer to the net buffer. + @param[in] Len The length of buffer to be reserved from the header. **/ VOID @@ -1020,18 +1034,18 @@ NetbufReserve ( ); /** - Allocate some space from the header or tail of the buffer. + Allocate Len bytes of space from the header or tail of the buffer. - @param[in, out] Nbuf Pointer to the net buffer. - @param[in] Len The length of the buffer to be allocated. - @param [in] FromHead The flag to indicate whether reserve the data from - head or tail. TRUE for from head, and FALSE for - from tail. + @param[in, out] Nbuf Pointer to the net buffer. + @param[in] Len The length of the buffer to be allocated. + @param[in] FromHead The flag to indicate whether reserve the data + from head (TRUE) or tail (FALSE). - @return Pointer to the first byte of the allocated buffer. + @return Pointer to the first byte of the allocated buffer, + or NULL if there is no sufficient space. **/ -UINT8 * +UINT8* EFIAPI NetbufAllocSpace ( IN OUT NET_BUF *Nbuf, @@ -1040,14 +1054,15 @@ NetbufAllocSpace ( ); /** - Trim some data from the header or tail of the buffer. + Trim Len bytes from the header or tail of the net buffer. - @param[in, out] Nbuf Pointer to the net buffer. - @param[in] Len The length of the data to be trimmed. - @param[in] FromHead The flag to indicate whether trim data from head or - tail. TRUE for from head, and FALSE for from tail. + @param[in, out] Nbuf Pointer to the net buffer. + @param[in] Len The length of the data to be trimmed. + @param[in] FromHead The flag to indicate whether trim data from head + (TRUE) or tail (FALSE). - @return Length of the actually trimmed data. + @return Length of the actually trimmed data, which is possible to be less + than Len because the TotalSize of Nbuf is less than Len. **/ UINT32 @@ -1059,14 +1074,18 @@ NetbufTrim ( ); /** - Copy the data from the specific offset to the destination. - - @param[in] Nbuf Pointer to the net buffer. - @param[in] Offset The sequence number of the first byte to copy. - @param[in] Len Length of the data to copy. - @param[in] Dest The destination of the data to copy to. - - @retval UINTN The length of the copied data. + Copy Len bytes of data from the specific offset of the net buffer to the + destination memory. + + The Len bytes of data may cross the several fragments of the net buffer. + + @param[in] Nbuf Pointer to the net buffer. + @param[in] Offset The sequence number of the first byte to copy. + @param[in] Len Length of the data to copy. + @param[in] Dest The destination of the data to copy to. + + @return The length of the actual copied data, or 0 if the offset + specified exceeds exceeds the total size of net buffer. **/ UINT32 @@ -1079,10 +1098,15 @@ NetbufCopy ( ); /** - Build a NET_BUF from external blocks. + Build a NET_BUF from external blocks. + + A new NET_BUF structure will be created from external blocks. Additional block + of memory will be allocated to hold reserved HeadSpace bytes of header room + and existing HeadLen bytes of header but the external blocks are shared by the + net buffer to avoid data copying. @param[in] ExtFragment Pointer to the data block. - @param[in] ExtNum The number of the data block. + @param[in] ExtNum The number of the data blocks. @param[in] HeadSpace The head space to be reserved. @param[in] HeadLen The length of the protocol header, This function will pull that number of data into a linear block. @@ -1090,8 +1114,9 @@ NetbufCopy ( @param[in] Arg The argument passed to ExtFree when ExtFree is called. - @return Pointer to the net buffer built from the data blocks. - If NULL, the allocation failed due to resource limit. + @return Pointer to the net buffer built from the data blocks, + or NULL if the allocation failed due to resource + limit. **/ NET_BUF * @@ -1106,15 +1131,16 @@ NetbufFromExt ( ); /** - Build a fragment table to contain the fragments in the - buffer. This is the opposite of the NetbufFromExt. - + Build a fragment table to contain the fragments in the net buffer. This is the + opposite operation of the NetbufFromExt. + @param[in] Nbuf Point to the net buffer. @param[in, out] ExtFragment Pointer to the data block. - @param[in, out] ExtNum The number of the data block. + @param[in, out] ExtNum The number of the data blocks. - @retval EFI_BUFFER_TOO_SMALL The number of non-empty block is bigger than ExtNum. - @retval EFI_SUCCESS Fragment table built. + @retval EFI_BUFFER_TOO_SMALL The number of non-empty block is bigger than + ExtNum. + @retval EFI_SUCCESS Fragment table is built successfully. **/ EFI_STATUS @@ -1126,18 +1152,20 @@ NetbufBuildExt ( ); /** - Build a NET_BUF from a list of NET_BUF. - - @param[in] BufList A List of NET_BUF. - @param[in] HeadSpace The head space to be reserved. - @param[in] HeaderLen The length of the protocol header, This function - will pull that number of data into a linear block. - @param[in] ExtFree Pointer to the caller provided free function. - @param[in] Arg The argument passed to ExtFree when ExtFree is - called. - - @return Pointer to the net buffer built from the data - blocks. + Build a net buffer from a list of net buffers. + + All the fragments will be collected from the list of NEW_BUF and then a new + net buffer will be created through NetbufFromExt. + + @param[in] BufList A List of the net buffer. + @param[in] HeadSpace The head space to be reserved. + @param[in] HeaderLen The length of the protocol header, This function + will pull that number of data into a linear block. + @param[in] ExtFree Pointer to the caller provided free function. + @param[in] Arg The argument passed to ExtFree when ExtFree is called. + + @return Pointer to the net buffer built from the list of net + buffers. **/ NET_BUF * @@ -1165,7 +1193,7 @@ NetbufFreeList ( /** Initiate the net buffer queue. - @param[in, out] NbufQue Pointer to the net buffer queue to be initiated. + @param[in, out] NbufQue Pointer to the net buffer queue to be initialized. **/ VOID @@ -1175,10 +1203,10 @@ NetbufQueInit ( ); /** - Allocate an initialized net buffer queue. + Allocate and initialize a net buffer queue. - @return Pointer to the allocated net buffer queue.If NULL, the - allocation failed due to resource limit. + @return Pointer to the allocated net buffer queue, or NULL if the + allocation failed due to resource limit. **/ NET_BUF_QUEUE * @@ -1188,9 +1216,13 @@ NetbufQueAlloc ( ); /** - Free a net buffer queue. + Free a net buffer queue. + + Decrease the reference count of the net buffer queue by one. The real resource + free operation isn't performed until the reference count of the net buffer + queue is decreased to 0. - @param[in] NbufQue Poitner to the net buffer queue to be freed. + @param[in] NbufQue Pointer to the net buffer queue to be freed. **/ VOID @@ -1200,13 +1232,12 @@ NetbufQueFree ( ); /** - Remove a net buffer from head in the specific queue. + Remove a net buffer from the head in the specific queue and return it. @param[in, out] NbufQue Pointer to the net buffer queue. - @return Pointer to the net buffer removed from the specific - queue. If NULL, there is no net buffer in the specific - queue. + @return Pointer to the net buffer removed from the specific queue, + or NULL if there is no net buffer in the specific queue. **/ NET_BUF * @@ -1216,10 +1247,10 @@ NetbufQueRemove ( ); /** - Append a buffer to the end of the queue. + Append a net buffer to the net buffer queue. - @param[in, out] NbufQue Pointer to the net buffer queue. - @param[in, out] Nbuf Pointer to the net buffer to be appended. + @param[in, out] NbufQue Pointer to the net buffer queue. + @param[in, out] Nbuf Pointer to the net buffer to be appended. **/ VOID @@ -1230,15 +1261,19 @@ NetbufQueAppend ( ); /** - Copy some data from the buffer queue to the destination. - - @param[in] NbufQue Pointer to the net buffer queue. - @param[in] Offset The sequence number of the first byte to copy. - @param[in] Len Length of the data to copy. - @param[out] Dest The destination of the data to copy to. - - @return The length of the copied data. If 0, then the length is zero or offset - suppress the total size of net buffer. + Copy Len bytes of data from the net buffer queue at the specific offset to the + destination memory. + + The copying operation is the same as NetbufCopy but applies to the net buffer + queue instead of the net buffer. + + @param[in] NbufQue Pointer to the net buffer queue. + @param[in] Offset The sequence number of the first byte to copy. + @param[in] Len Length of the data to copy. + @param[out] Dest The destination of the data to copy to. + + @return The length of the actual copied data, or 0 if the offset + specified exceeds the total size of net buffer queue. **/ UINT32 @@ -1251,13 +1286,16 @@ NetbufQueCopy ( ); /** - Trim some data from the queue header, release the buffer if - whole buffer is trimmed. + Trim Len bytes of data from the queue header, release any of the net buffer + whom is trimmed wholely. + + The trimming operation is the same as NetbufTrim but applies to the net buffer + queue instead of the net buffer. @param[in, out] NbufQue Pointer to the net buffer queue. @param[in] Len Length of the data to trim. - @return The length of the data trimmed, or 0 if length of the data to trim is zero. + @return The actual length of the data trimmed. **/ UINT32 @@ -1281,7 +1319,7 @@ NetbufQueFlush ( ); /** - Compute checksum for a bulk of data. + Compute the checksum for a bulk of data. @param[in] Bulk Pointer to the data. @param[in] Len Length of the data, in bytes. @@ -1327,9 +1365,9 @@ NetbufChecksum ( ); /** - Compute the checksum for TCP/UDP pseudo header. - Src, Dst are in network byte order. and Len is - in host byte order. + Compute the checksum for TCP/UDP pseudo header. + + Src and Dst are in network byte order, and Len is in host byte order. @param[in] Src The source address of the packet. @param[in] Dst The destination address of the packet. -- 2.39.2