summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorniry <niry@6f19259b-4bc3-4df7-8a09-765794883524>2008-12-25 14:19:52 +0000
committerniry <niry@6f19259b-4bc3-4df7-8a09-765794883524>2008-12-25 14:19:52 +0000
commit7557df4df36b29baa1c3b65dba90d415b7896e05 (patch)
tree75352116eda9bab69fe34f515d5158cb063187cd
parent9bc4edf21a1b02ea4e2958f0e985f9bfd846e0c7 (diff)
downloadedk2-platforms-7557df4df36b29baa1c3b65dba90d415b7896e05.tar.xz
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
-rw-r--r--MdeModulePkg/Include/Library/NetLib.h282
1 files 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.