From: jgong5 Date: Fri, 26 Dec 2008 09:09:02 +0000 (+0000) Subject: Add more comments X-Git-Tag: edk2-stable201903~19109 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=cab450ccda8f8a5a2cc1872ea229f1f7737a62d3 Add more comments git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7138 6f19259b-4bc3-4df7-8a09-765794883524 --- 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.
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
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.
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
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. **/