Add more comments

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7138 6f19259b-4bc3-4df7-8a09-765794883524

2 files changed, 175 insertions, 92 deletions

diff --git a/MdeModulePkg/Include/Library/UdpIoLib.h b/MdeModulePkg/Include/Library/UdpIoLib.h
index 0be5b577c3..40ea089ef8 100644
--- a/MdeModulePkg/Include/Library/UdpIoLib.h
+++ b/MdeModulePkg/Include/Library/UdpIoLib.h
@@ -2,10 +2,10 @@
   The helper routines to access UDP service. It is used by both

   DHCP and MTFTP.

 

-Copyright (c) 2006 - 2008, Intel Corporation

+Copyright (c) 2006 - 2008, Intel Corporation.<BR>

 All rights reserved. This program and the accompanying materials

 are licensed and made available under the terms and conditions of the BSD License

-which accompanies this distribution.  The full text of the license may be found at

+which accompanies this distribution.  The full text of the license may be found at<BR>

 http://opensource.org/licenses/bsd-license.php

 

 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

@@ -23,12 +23,18 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 typedef struct _UDP_IO_PORT UDP_IO_PORT;

 

+///

+/// Signatures used by UdpIo Library.

+///

 typedef enum {

   UDP_IO_RX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'R'),

   UDP_IO_TX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'T'),

   UDP_IO_SIGNATURE    = SIGNATURE_32 ('U', 'D', 'P', 'I')

 } UDP_IO_SIGNATURE_TYPE;

 

+///

+/// The Udp4 address pair.

+///

 typedef struct {

   IP4_ADDR                  LocalAddr;

   UINT16                    LocalPort;

@@ -36,27 +42,39 @@ typedef struct {
   UINT16                    RemotePort;

 } UDP_POINTS;

 

-//

-// This prototype is used by both receive and transmission.

-// When receiving Netbuf is allocated by UDP access point, and

-// released by user. When transmitting, the NetBuf is from user,

-// and provided to the callback as a reference.

-//

+/**

+  Prototype called when receiving or sending packets from/to a UDP point.

+

+  This prototype is used by both receive and sending when calling

+  UdpIoRecvDatagram or UdpIoSendDatagram. When receiving, Netbuf is allocated by

+  UDP access point, and released by user. When sending, the NetBuf is from user,

+  and provided to the callback as a reference.

+  

+  @param Packet       Packet received or sent

+  @param Points       The Udp4 address pair corresponds to the Udp4 IO

+  @param IoStatus     Packet receiving or sending status

+  @param Context      User-defined data when calling UdpIoRecvDatagram or

+                      UdpIoSendDatagram

+

+  @return None

+**/

 typedef

 VOID

-(*UDP_IO_CALLBACK) (

+(EFIAPI *UDP_IO_CALLBACK) (

   IN NET_BUF                *Packet,

   IN UDP_POINTS             *Points,

   IN EFI_STATUS             IoStatus,

   IN VOID                   *Context

   );

 

-//

-// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,

-// the CallBack will be called. Only one receive request is send to UDP.

-// HeadLen gives the length of the application's header. UDP_IO will

-// make the application's header continous before delivery up.

-//

+///

+/// This structure is used internally by UdpIo Library.

+///

+/// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,

+/// the CallBack will be called. Only one receive request is sent to UDP at a

+/// time. HeadLen gives the length of the application's header. UDP_IO will

+/// make the application's header continuous before delivering up.

+///

 typedef struct {

   UINT32                    Signature;

   UDP_IO_PORT               *UdpIo;

@@ -68,10 +86,13 @@ typedef struct {
   EFI_UDP4_COMPLETION_TOKEN UdpToken;

 } UDP_RX_TOKEN;

 

-//

-// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,

-// the CallBack will be called. There can be several transmit requests.

-//

+///

+/// This structure is used internally by UdpIo Library.

+///

+/// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,

+/// the CallBack will be called. There can be several transmit requests and they

+/// are linked in a list.

+///

 typedef struct {

   UINT32                    Signature;

   LIST_ENTRY                Link;

@@ -88,6 +109,12 @@ typedef struct {
   EFI_UDP4_TRANSMIT_DATA    UdpTxData;

 } UDP_TX_TOKEN;

 

+///

+/// Type defined as UDP_IO_PORT.

+///

+/// The data structure wraps Udp4 instance and its configuration. It is used by

+/// UdpIo Library to do all Udp4 operations.

+///

 struct _UDP_IO_PORT {

   UINT32                    Signature;

   LIST_ENTRY                Link;

@@ -100,21 +127,43 @@ struct _UDP_IO_PORT {
   EFI_HANDLE                Image;

   EFI_HANDLE                UdpHandle;

 

-  EFI_UDP4_PROTOCOL         *Udp;

+  EFI_UDP4_PROTOCOL         *Udp;           ///< The wrapped Udp4 instance.

   EFI_UDP4_CONFIG_DATA      UdpConfig;

   EFI_SIMPLE_NETWORK_MODE   SnpMode;

 

-  LIST_ENTRY                SentDatagram;

+  LIST_ENTRY                SentDatagram;   ///< A list of UDP_TX_TOKEN.

   UDP_RX_TOKEN              *RecvRequest;

 };

 

+/**

+  Prototype called when UdpIo Library configures a Udp4 instance.

+  

+  The prototype is set and called when creating a UDP_IO_PORT in UdpIoCreatePort.

+  

+  @param UdpIo         The UDP_IO_PORT to configure

+  @param Context       User-defined data when calling UdpIoCreatePort

+  

+  @retval EFI_SUCCESS  The configure process succeeds

+  @retval Others       The UDP_IO_PORT fails to configure indicating

+                       UdpIoCreatePort should fail

+**/

 typedef

 EFI_STATUS

-(*UDP_IO_CONFIG) (

+(EFIAPI *UDP_IO_CONFIG) (

   IN UDP_IO_PORT            *UdpIo,

   IN VOID                   *Context

   );

 

+/**

+  The select function to decide whether to cancel the UDP_TX_TOKEN. It is used

+  

+  @param Token        The UDP_TX_TOKEN to decide whether to cancel

+  @param Context      User-defined data in UdpIoCancelDgrams

+  

+  @retval TRUE        To cancel the UDP_TX_TOKEN

+  @retval FALSE       Do not cancel this UDP_TX_TOKEN

+

+**/

 typedef

 BOOLEAN

 (*UDP_IO_TO_CANCEL) (

@@ -123,8 +172,14 @@ BOOLEAN
   );

 

 /**

-  Create a UDP IO port to access the UDP service. It will

-  create and configure a UDP child.

+  Create a UDP_IO_PORT to access the UDP service. It will create and configure

+  a UDP child.

+  

+  The function will locate the UDP service binding prototype on the Controller

+  parameter and use it to create a UDP child (aka Udp instance). Then the UDP

+  child will be configured by calling Configure function prototype. Any failures

+  in creating or configure the UDP child will lead to the failure of UDP_IO_PORT

+  creation.

 

   @param  Controller            The controller that has the UDP service binding

                                 protocol installed.

@@ -132,7 +187,7 @@ BOOLEAN
   @param  Configure             The function to configure the created UDP child

   @param  Context               The opaque parameter for the Configure funtion.

 

-  @return A point to just created UDP IO port or NULL if some error happened.

+  @return Newly-created UDP_IO_PORT or NULL if failed.

 

 **/

 UDP_IO_PORT *

@@ -145,12 +200,13 @@ UdpIoCreatePort (
   );

 

 /**

-  Free the UDP IO port and all its related resources including

-  all the transmitted packet.

+  Free the UDP_IO_PORT and all its related resources.

+  

+  The function will cancel all sent datagram and receive request.

 

-  @param  UdpIo                 The UDP IO port to free.

+  @param  UdpIo                 The UDP_IO_PORT to free.

 

-  @retval EFI_SUCCESS           The UDP IO port is freed.

+  @retval EFI_SUCCESS           The UDP_IO_PORT is freed.

 

 **/

 EFI_STATUS

@@ -160,11 +216,13 @@ UdpIoFreePort (
   );

 

 /**

-  Clean up the UDP IO port. It will release all the transmitted

-  datagrams and receive request. It will also configure NULL the

-  UDP child.

+  Clean up the UDP_IO_PORT without freeing it. The function is called when

+  user wants to re-use the UDP_IO_PORT later.

+  

+  It will release all the transmitted datagrams and receive request. It will

+  also configure NULL for the UDP instance.

 

-  @param  UdpIo                 UDP IO port to clean up.

+  @param  UdpIo                 The UDP_IO_PORT to clean up.

 

 **/

 VOID

@@ -174,15 +232,20 @@ UdpIoCleanPort (
   );

 

 /**

-  Send a packet through the UDP IO port.

+  Send a packet through the UDP_IO_PORT.

+  

+  The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called

+  when the packet is sent. The optional parameter EndPoint overrides the default

+  address pair if specified.

 

-  @param  UdpIo                 The UDP IO Port to send the packet through

+  @param  UdpIo                 The UDP_IO_PORT to send the packet through

   @param  Packet                The packet to send

-  @param  EndPoint              The local and remote access point

+  @param  EndPoint              The local and remote access point. Override the

+                                default address pair set during configuration.

   @param  Gateway               The gateway to use

-  @param  CallBack              The call back function to call when packet is

+  @param  CallBack              The function being called when packet is

                                 transmitted or failed.

-  @param  Context               The opque parameter to the CallBack

+  @param  Context               The opaque parameter passed to CallBack

 

   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet

   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for

@@ -194,7 +257,7 @@ EFIAPI
 UdpIoSendDatagram (

   IN  UDP_IO_PORT           *UdpIo,

   IN  NET_BUF               *Packet,

-  IN  UDP_POINTS            *EndPoint, OPTIONAL

+  IN  UDP_POINTS            *EndPoint  OPTIONAL,

   IN  IP4_ADDR              Gateway,

   IN  UDP_IO_CALLBACK       CallBack,

   IN  VOID                  *Context

@@ -203,7 +266,7 @@ UdpIoSendDatagram (
 /**

   Cancel a single sent datagram.

 

-  @param  UdpIo                 The UDP IO port to cancel the packet from

+  @param  UdpIo                 The UDP_IO_PORT to cancel the packet from

   @param  Packet                The packet to cancel

 

 **/

@@ -215,17 +278,22 @@ UdpIoCancelSentDatagram (
   );

 

 /**

-  Issue a receive request to the UDP IO port.

-

-  @param  UdpIo                 The UDP IO port to recieve the packet from.

-  @param  CallBack              The call back function to execute when receive

-                                finished.

-  @param  Context               The opque context to the call back

-  @param  HeadLen               The lenght of the application's header

+  Issue a receive request to the UDP_IO_PORT.

+  

+  This function is called when upper-layer needs packet from UDP for processing.

+  Only one receive request is acceptable at a time so a common usage model is

+  to invoke this function inside its Callback function when the former packet

+  is processed.

+

+  @param  UdpIo                 The UDP_IO_PORT to receive the packet from.

+  @param  CallBack              The call back function to execute when the packet

+                                is received.

+  @param  Context               The opaque context passed to Callback

+  @param  HeadLen               The length of the upper-layer's protocol header

 

   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only

-                                one receive request is supported.

-  @retval EFI_OUT_OF_RESOURCES  Failed to allocate some resource.

+                                one receive request is supported at a time.

+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.

   @retval EFI_SUCCESS           The receive request is issued successfully.

 

 **/

diff --git a/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c b/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c
index 6efb37ecd4..d6ac652783 100644
--- a/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c
+++ b/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c
@@ -4,7 +4,7 @@
 Copyright (c) 2005 - 2007, Intel Corporation.<BR>

 All rights reserved. This program and the accompanying materials

 are licensed and made available under the terms and conditions of the BSD License

-which accompanies this distribution.  The full text of the license may be found at

+which accompanies this distribution.  The full text of the license may be found at<BR>

 http://opensource.org/licenses/bsd-license.php

 

 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

@@ -24,7 +24,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

 

 /**

-  Free a UDP_TX_TOKEN. The event is closed and memory released.

+  Free a UDP_TX_TOKEN. The TX event is closed.

 

   @param  Token                 The UDP_TX_TOKEN to release.

 

@@ -39,9 +39,9 @@ UdpIoFreeTxToken (
 }

 

 /**

-  Free a receive request wrap.

+  Free a UDP_RX_TOKEN. The RX event is closed.

 

-  @param  Token                 The receive request to release.

+  @param  Token                 The UDP_RX_TOKEN to release.

 

 **/

 VOID

@@ -55,8 +55,9 @@ UdpIoFreeRxToken (
 

 /**

   The callback function when the packet is sent by UDP.

+  

   It will remove the packet from the local list then call

-  the packet owner's callback function.

+  the packet owner's callback function set by UdpIoSendDatagram.

 

   @param  Context               The UDP TX Token.

 

@@ -117,8 +118,9 @@ UdpIoRecycleDgram (
 }

 

 /**

-  The event handle for UDP receive request. It will build

-  a NET_BUF from the recieved UDP data, then deliver it

+  The event handle for UDP receive request.

+  

+  It will build a NET_BUF from the recieved UDP data, then deliver it

   to the receiver.

 

   @param  Context               The UDP RX token.

@@ -363,12 +365,15 @@ UdpIoWrapTx (
   return Token;

 }

 

-

-

-

 /**

-  Create a UDP IO port to access the UDP service. It will

-  create and configure a UDP child.

+  Create a UDP_IO_PORT to access the UDP service. It will create and configure

+  a UDP child.

+  

+  The function will locate the UDP service binding prototype on the Controller

+  parameter and use it to create a UDP child (aka Udp instance). Then the UDP

+  child will be configured by calling Configure function prototype. Any failures

+  in creating or configure the UDP child will lead to the failure of UDP_IO_PORT

+  creation.

 

   @param  Controller            The controller that has the UDP service binding

                                 protocol installed.

@@ -376,7 +381,7 @@ UdpIoWrapTx (
   @param  Configure             The function to configure the created UDP child

   @param  Context               The opaque parameter for the Configure funtion.

 

-  @return A point to just created UDP IO port or NULL if some error happened.

+  @return Newly-created UDP_IO_PORT or NULL if failed.

 

 **/

 UDP_IO_PORT *

@@ -465,12 +470,11 @@ FREE_MEM:
   return NULL;

 }

 

-

 /**

-  Cancel all the sent datagram that pass the selection of ToCancel.

+  Cancel all the sent datagram that pass the selection criteria of ToCancel.

   If ToCancel is NULL, all the datagrams are cancelled.

 

-  @param  UdpIo                 The UDP IO port to cancel packet

+  @param  UdpIo                 The UDP_IO_PORT to cancel packet

   @param  IoStatus              The IoStatus to return to the packet owners.

   @param  ToCancel              The select funtion to test whether to cancel this

                                 packet or not.

@@ -498,14 +502,14 @@ UdpIoCancelDgrams (
   }

 }

 

-

 /**

-  Free the UDP IO port and all its related resources including

-  all the transmitted packet.

+  Free the UDP_IO_PORT and all its related resources.

+  

+  The function will cancel all sent datagram and receive request.

 

-  @param  UdpIo                 The UDP IO port to free.

+  @param  UdpIo                 The UDP_IO_PORT to free.

 

-  @retval EFI_SUCCESS           The UDP IO port is freed.

+  @retval EFI_SUCCESS           The UDP_IO_PORT is freed.

 

 **/

 EFI_STATUS

@@ -557,11 +561,13 @@ UdpIoFreePort (
 

 

 /**

-  Clean up the UDP IO port. It will release all the transmitted

-  datagrams and receive request. It will also configure NULL the

-  UDP child.

+  Clean up the UDP_IO_PORT without freeing it. The function is called when

+  user wants to re-use the UDP_IO_PORT later.

+  

+  It will release all the transmitted datagrams and receive request. It will

+  also configure NULL for the UDP instance.

 

-  @param  UdpIo                 UDP IO port to clean up.

+  @param  UdpIo                 The UDP_IO_PORT to clean up.

 

 **/

 VOID

@@ -585,15 +591,20 @@ UdpIoCleanPort (
 }

 

 /**

-  Send a packet through the UDP IO port.

+  Send a packet through the UDP_IO_PORT.

+  

+  The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called

+  when the packet is sent. The optional parameter EndPoint overrides the default

+  address pair if specified.

 

-  @param  UdpIo                 The UDP IO Port to send the packet through

+  @param  UdpIo                 The UDP_IO_PORT to send the packet through

   @param  Packet                The packet to send

-  @param  EndPoint              The local and remote access point

+  @param  EndPoint              The local and remote access point. Override the

+                                default address pair set during configuration.

   @param  Gateway               The gateway to use

-  @param  CallBack              The call back function to call when packet is

+  @param  CallBack              The function being called when packet is

                                 transmitted or failed.

-  @param  Context               The opque parameter to the CallBack

+  @param  Context               The opaque parameter passed to CallBack

 

   @retval EFI_OUT_OF_RESOURCES  Failed to allocate resource for the packet

   @retval EFI_SUCCESS           The packet is successfully delivered to UDP  for

@@ -637,10 +648,10 @@ UdpIoSendDatagram (
 

 

 /**

-  The selection function to cancel a single sent datagram.

+  The select function to cancel a single sent datagram.

 

-  @param  Token                 The UDP TX token to test againist.

-  @param  Context               The context

+  @param  Token                 The UDP_TX_TOKEN to test against

+  @param  Context               The NET_BUF of the sent datagram

 

   @retval TRUE              The packet is to be cancelled.

   @retval FALSE             The packet is not to be cancelled.

@@ -662,11 +673,10 @@ UdpIoCancelSingleDgram (
   return FALSE;

 }

 

-

 /**

   Cancel a single sent datagram.

 

-  @param  UdpIo                 The UDP IO port to cancel the packet from

+  @param  UdpIo                 The UDP_IO_PORT to cancel the packet from

   @param  Packet                The packet to cancel

 

 **/

@@ -681,17 +691,22 @@ UdpIoCancelSentDatagram (
 }

 

 /**

-  Issue a receive request to the UDP IO port.

+  Issue a receive request to the UDP_IO_PORT.

+  

+  This function is called when upper-layer needs packet from UDP for processing.

+  Only one receive request is acceptable at a time so a common usage model is

+  to invoke this function inside its Callback function when the former packet

+  is processed.

 

-  @param  UdpIo                 The UDP IO port to recieve the packet from.

-  @param  CallBack              The call back function to execute when receive

-                                finished.

-  @param  Context               The opque context to the call back

-  @param  HeadLen               The lenght of the application's header

+  @param  UdpIo                 The UDP_IO_PORT to receive the packet from.

+  @param  CallBack              The call back function to execute when the packet

+                                is received.

+  @param  Context               The opaque context passed to Callback

+  @param  HeadLen               The length of the upper-layer's protocol header

 

   @retval EFI_ALREADY_STARTED   There is already a pending receive request. Only

-                                one receive request is supported.

-  @retval EFI_OUT_OF_RESOURCES  Failed to allocate some resource.

+                                one receive request is supported at a time.

+  @retval EFI_OUT_OF_RESOURCES  Failed to allocate needed resources.

   @retval EFI_SUCCESS           The receive request is issued successfully.

 

 **/