diff options
author | niry <niry@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-25 13:39:12 +0000 |
---|---|---|
committer | niry <niry@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-25 13:39:12 +0000 |
commit | 32cf7c738394e5e77c98e3e7759c9e129cb9b204 (patch) | |
tree | fa662c454fb0420c0bb1b4e1b0b19e16538e2223 /MdeModulePkg | |
parent | 679242bef071a8666e613c744688040a96c5704b (diff) | |
download | edk2-platforms-32cf7c738394e5e77c98e3e7759c9e129cb9b204.tar.xz |
Add more comments to describe the net buffer operation functions.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7124 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdeModulePkg')
-rw-r--r-- | MdeModulePkg/Library/DxeNetLib/NetBuffer.c | 368 |
1 files changed, 208 insertions, 160 deletions
diff --git a/MdeModulePkg/Library/DxeNetLib/NetBuffer.c b/MdeModulePkg/Library/DxeNetLib/NetBuffer.c index 897152946e..fcfb0936bc 100644 --- a/MdeModulePkg/Library/DxeNetLib/NetBuffer.c +++ b/MdeModulePkg/Library/DxeNetLib/NetBuffer.c @@ -1,5 +1,5 @@ /** @file
- Network library.
+ Network library functions providing net buffer operation support.
Copyright (c) 2005 - 2006, Intel Corporation.<BR>
All rights reserved. This program and the accompanying materials
@@ -22,15 +22,17 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. /**
- Allocate and build up the sketch for a NET_BUF. The net buffer allocated
- has the BlockOpNum's NET_BLOCK_OP, and its associated NET_VECTOR has the
- BlockNum's NET_BLOCK.
+ Allocate and build up the sketch for a NET_BUF.
+
+ The net buffer allocated has the BlockOpNum's NET_BLOCK_OP, and its associated
+ NET_VECTOR has the BlockNum's NET_BLOCK. But all the NET_BLOCK_OP and
+ NET_BLOCK remain un-initialized.
- @param[in] BlockNum The number of NET_BLOCK in the Vector of net buffer
- @param[in] BlockOpNum The number of NET_BLOCK_OP in the net buffer
+ @param[in] BlockNum The number of NET_BLOCK in the vector of net buffer
+ @param[in] BlockOpNum The number of NET_BLOCK_OP in the net buffer
- @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 *
@@ -86,8 +88,8 @@ FreeNbuf: @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 *
@@ -134,9 +136,12 @@ FreeNBuf: return NULL;
}
-
/**
- Free the vector.
+ Free the vector.
+
+ Decrease the reference count of the vector by one. The real resource free
+ operation isn't performed until the reference count of the vector is decreased
+ to 0.
@param[in] Vector Pointer to the NET_VECTOR to be freed.
@@ -183,8 +188,14 @@ NetbufFreeVector ( /**
- 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
+ vector and itself if the reference count of the net buffer is decreased to 0.
+ The vector free operation just decrease the reference count of the vector by
+ one and do the real resource free operation when the reference count of the
+ vector is 0.
+
@param[in] Nbuf Pointer to the NET_BUF to be freed.
**/
@@ -211,15 +222,18 @@ NetbufFree ( /**
- 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
@@ -256,16 +270,19 @@ NetbufClone ( /**
- 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 *
@@ -306,7 +323,7 @@ NetbufDuplicate ( Free a list of net buffers.
@param[in, out] Head Pointer to the head of linked net buffers.
-
+NOT YET
**/
VOID
EFIAPI
@@ -333,17 +350,20 @@ NetbufFreeList ( /**
- 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 nth byte of data in the net buffer, or NULL
+ indicating there is no such data in the net buffer.
**/
UINT8 *
@@ -387,17 +407,19 @@ NetbufGetByte ( /**
- Set the NET_BLOCK and corresponding NET_BLOCK_OP in
- the buffer. All the pointers in NET_BLOCK and NET_BLOCK_OP
- are set to the bulk's head and tail respectively. So, this
- function alone can't be used by NetbufAlloc.
-
- @param[in, out] Nbuf Pointer to the net buffer.
- @param[in] Bulk Pointer to the data.
- @param[in] Len Length of the bulk data.
- @param[in] Index The data block index in the net buffer the bulk
- data should belong to.
-
+ Set the NET_BLOCK and corresponding NET_BLOCK_OP in the net buffer and
+ corresponding net vector according to the bulk pointer and bulk length.
+
+ All the pointers in the Index'th NET_BLOCK and NET_BLOCK_OP are set to the
+ bulk's head and tail respectively. So, this function alone can't be used by
+ NetbufAlloc.
+
+ @param[in, out] Nbuf Pointer to the net buffer.
+ @param[in] Bulk Pointer to the data.
+ @param[in] Len Length of the bulk data.
+ @param[in] Index The data block index in the net buffer the bulk
+ data should belong to.
+
**/
VOID
NetbufSetBlock (
@@ -428,15 +450,17 @@ NetbufSetBlock ( /**
- Set the NET_BLOCK_OP in the buffer. The corresponding NET_BLOCK
- structure is left untouched. Some times, there is no 1:1 relationship
- between NET_BLOCK and NET_BLOCK_OP. For example, that in NetbufGetFragment.
-
- @param[in, out] Nbuf Pointer to the net buffer.
- @param[in] Bulk Pointer to the data.
- @param[in] Len Length of the bulk data.
- @param[in] Index The data block index in the net buffer the bulk
- data should belong to.
+ Set the NET_BLOCK_OP in the net buffer. The corresponding NET_BLOCK
+ structure is left untouched.
+
+ Some times, there is no 1:1 relationship between NET_BLOCK and NET_BLOCK_OP.
+ For example, that in NetbufGetFragment.
+
+ @param[in, out] Nbuf Pointer to the net buffer.
+ @param[in] Bulk Pointer to the data.
+ @param[in] Len Length of the bulk data.
+ @param[in] Index The data block index in the net buffer the bulk
+ data should belong to.
**/
VOID
@@ -468,7 +492,7 @@ NetbufSetBlockOp ( the old NET_VECTOR.
@param[in] Arg Point to the old NET_VECTOR.
-
+NOT YET
**/
VOID
NetbufGetFragmentFree (
@@ -484,20 +508,20 @@ NetbufGetFragmentFree ( /**
- 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 indicating
+ the allocation failed due to resource limit.
**/
NET_BUF *
@@ -668,10 +692,15 @@ FreeChild: /**
- 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.
@@ -679,8 +708,9 @@ FreeChild: @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 indicating the allocation failed due to
+ resource limit.
**/
NET_BUF *
@@ -843,15 +873,16 @@ FreeFirstBlock: /**
- 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
@@ -887,18 +918,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 *
@@ -961,16 +994,15 @@ NetbufFromBufList ( /**
- 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.
- @param[in, out] Nbuf Pointer to the net buffer.
- @param[in] Len The length of buffer to be reserverd.
+ 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 reserved from the header.
**/
VOID
@@ -994,18 +1026,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 indicating there is no sufficient space.
**/
-UINT8 *
+UINT8*
EFIAPI
NetbufAllocSpace (
IN OUT NET_BUF *Nbuf,
@@ -1086,12 +1118,12 @@ NetbufAllocSpace ( /**
- Trim a single NET_BLOCK.
+ Trim a single NET_BLOCK by Len bytes from the header or tail.
- @param[in, out] BlockOp Pointer to the NET_BLOCK.
- @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] BlockOp Pointer to the NET_BLOCK.
+ @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).
**/
VOID
@@ -1101,7 +1133,7 @@ NetblockTrim ( IN BOOLEAN FromHead
)
{
- ASSERT (BlockOp && (BlockOp->Size >= Len));
+ ASSERT ((BlockOp != NULL) && (BlockOp->Size >= Len));
BlockOp->Size -= Len;
@@ -1114,14 +1146,15 @@ NetblockTrim ( /**
- 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
@@ -1179,14 +1212,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
@@ -1281,7 +1318,7 @@ NetbufCopy ( /**
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
@@ -1301,10 +1338,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 *
@@ -1327,9 +1364,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
@@ -1350,10 +1391,10 @@ NetbufQueFree ( /**
- 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
@@ -1374,13 +1415,13 @@ NetbufQueAppend ( /**
- 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 indicating there is no net buffer in the specific
+ queue.
**/
NET_BUF *
@@ -1408,15 +1449,19 @@ NetbufQueRemove ( /**
- 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 indicating the offset
+ specified exceeds the total size of net buffer queue.
**/
UINT32
@@ -1506,13 +1551,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
@@ -1588,7 +1636,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.
@@ -1714,9 +1762,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.
|