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

1 files changed, 208 insertions, 160 deletions

diff --git a/MdeModulePkg/Library/DxeNetLib/NetBuffer.c b/MdeModulePkg/Library/DxeNetLib/NetBuffer.c
index 8971529..fcfb093 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.