tyler.durden
/
audk
mirror of https://github.com/acidanthera/audk.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
niry 2008-12-25 13:39:12 +00:00
parent 679242bef0
commit 32cf7c7383
1 changed files with 200 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

250
MdeModulePkg/Library/DxeNetLib/NetBuffer.c
View File

@ -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,14 +22,16 @@ 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.
@param[in] BlockNum The number of NET_BLOCK in the Vector of net buffer
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
@return Pointer to the allocated NET_BUF. If NULL, the
@return Pointer to the allocated NET_BUF, or NULL if the
allocation failed due to resource limit.
**/
@ -86,7 +88,7 @@ FreeNbuf:
@param[in] Len The length of the block.
@return Pointer to the allocated NET_BUF. If NULL the
@return Pointer to the allocated NET_BUF, or NULL if the
allocation failed due to resource limit.
**/
@ -134,10 +136,13 @@ FreeNBuf:
return NULL;
}
/**
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,7 +188,13 @@ 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,11 +222,14 @@ 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.
**/
@ -256,16 +270,19 @@ NetbufClone (
/**
Create a duplicated copy of Nbuf, data is copied. Also leave some
head space before the data.
Create a duplicated copy of the net buffer with data copied and HeadSpace
bytes of head space reserved.
@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.
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.If NULL, the
allocation failed due to resource limit.
@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] 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,10 +407,12 @@ 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.
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.
@ -428,9 +450,11 @@ 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.
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.
@ -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.
Create a NET_BUF structure which contains Len byte data of Nbuf starting from
Offset.
@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.
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.
@return Pointer to the cloned net buffer.If NULL, the
allocation failed due to resource limit.
@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 *
@ -670,8 +694,13 @@ FreeChild:
/**
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.
Build a net buffer from a list of net buffers.
@param[in] BufList A List of NET_BUF.
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.
@param[in] Arg The argument passed to ExtFree when ExtFree is called.
@return Pointer to the net buffer built from the data
blocks.
@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.
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] Len The length of buffer to be reserved from the header.
**/
VOID
@ -994,15 +1026,15 @@ 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] 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*
@ -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] 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] 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.
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.
@retval UINTN The length of the copied data.
@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,9 +1338,9 @@ 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
@return Pointer to the allocated net buffer queue, or NULL if the
allocation failed due to resource limit.
**/
@ -1329,7 +1366,11 @@ NetbufQueAlloc (
/**
Free a net buffer queue.
@param[in] NbufQue Poitner to the net buffer queue to be freed.
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 Pointer to the net buffer queue to be freed.
**/
VOID
@ -1350,7 +1391,7 @@ 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.
@ -1374,12 +1415,12 @@ 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
@return Pointer to the net buffer removed from the specific queue,
or NULL indicating there is no net buffer in the specific
queue.
**/
@ -1408,15 +1449,19 @@ NetbufQueRemove (
/**
Copy some data from the buffer queue to the destination.
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 copied data. If 0, then the length is zero or offset
suppress the total size of net buffer.
@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.
@ -1715,8 +1763,8 @@ NetbufChecksum (
/**
Compute the checksum for TCP/UDP pseudo header.
Src, Dst are in network byte order. and Len is
in host byte order.
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.