diff options
author | jgong5 <jgong5@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-26 09:09:02 +0000 |
---|---|---|
committer | jgong5 <jgong5@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-26 09:09:02 +0000 |
commit | cab450ccda8f8a5a2cc1872ea229f1f7737a62d3 (patch) | |
tree | eb065267402f0e9e2ac5c9927c817b0e40b00445 /MdeModulePkg/Include | |
parent | d17371e86b1be22fb3d810aa0a1045e6d4ec9847 (diff) | |
download | edk2-platforms-cab450ccda8f8a5a2cc1872ea229f1f7737a62d3.tar.xz |
Add more comments
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7138 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdeModulePkg/Include')
-rw-r--r-- | MdeModulePkg/Include/Library/UdpIoLib.h | 166 |
1 files changed, 117 insertions, 49 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.
**/
|