diff options
author | jgong5 <jgong5@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-30 12:12:46 +0000 |
---|---|---|
committer | jgong5 <jgong5@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-12-30 12:12:46 +0000 |
commit | e29a2e7e8003e824d77a68f980daf0d614fc3bf5 (patch) | |
tree | e91234b5938c843f0876ad8ea15d3847eba93013 /MdeModulePkg/Include | |
parent | 5b8adaa558dd0259ede5dad042d80ad2de5cd035 (diff) | |
download | edk2-platforms-e29a2e7e8003e824d77a68f980daf0d614fc3bf5.tar.xz |
Enhance function header
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7156 6f19259b-4bc3-4df7-8a09-765794883524
Diffstat (limited to 'MdeModulePkg/Include')
-rw-r--r-- | MdeModulePkg/Include/Library/IpIoLib.h | 232 |
1 files changed, 157 insertions, 75 deletions
diff --git a/MdeModulePkg/Include/Library/IpIoLib.h b/MdeModulePkg/Include/Library/IpIoLib.h index 0ef93ed9e5..1f983c9be2 100644 --- a/MdeModulePkg/Include/Library/IpIoLib.h +++ b/MdeModulePkg/Include/Library/IpIoLib.h @@ -42,11 +42,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #define ICMP_CODE_UNREACH_TOSNET 11
#define ICMP_CODE_UNREACH_TOSHOST 12
-//
-// this error will be delivered to the
-// listening transportation layer protocol
-// consuming IpIO
-//
+///
+/// This error will be delivered to the
+/// listening transportation layer protocol
+/// that consumes IpIO.
+///
typedef enum {
ICMP_ERR_UNREACH_NET = 0,
ICMP_ERR_UNREACH_HOST,
@@ -60,93 +60,140 @@ typedef enum { ICMP_ERR_PARAMPROB
} ICMP_ERROR;
+///
+/// The helper struct for IpIoGetIcmpErrStatus(). It is internal-use only.
+///
typedef struct _ICMP_ERROR_INFO {
BOOLEAN IsHard;
BOOLEAN Notify;
} ICMP_ERROR_INFO;
+/**
+ Get the IP header length from EFI_IP4_HEADER struct.
+
+ @param HdrPtr A pointer to EFI_IP4_HEADER
+
+ @return The IP header length
+**/
#define EFI_IP4_HEADER_LEN(HdrPtr) ((HdrPtr)->HeaderLength << 2)
extern EFI_IP4_CONFIG_DATA mIpIoDefaultIpConfigData;
+///
+/// The IP session for an IP receive packet.
+///
typedef struct _EFI_NET_SESSION_DATA {
- IP4_ADDR Source;
- IP4_ADDR Dest;
- EFI_IP4_HEADER *IpHdr;
+ IP4_ADDR Source; ///< Source IP of the received packet
+ IP4_ADDR Dest; ///< Destination IP of the received packet
+ EFI_IP4_HEADER *IpHdr; ///< IP4 header of the received packet
} EFI_NET_SESSION_DATA;
+/**
+ The prototype is called back when an IP packet is received.
+
+ @param Status Result of the receive request
+ @param IcmpErr Valid when Status is EFI_ICMP_ERROR
+ @param NetSession The IP session for the received packet
+ @param Pkt Packet received
+ @param Context The data provided by user for the received packet when
+ the callback is registered in IP_IO_OPEN_DATA::RcvdContext.
+
+**/
typedef
VOID
(*PKT_RCVD_NOTIFY) (
- IN EFI_STATUS Status, // rcvd pkt result
- IN ICMP_ERROR IcmpErr, // if Status == EFI_ICMP_ERROR, this
- // field is valid for user
- IN EFI_NET_SESSION_DATA *NetSession, // the communication point
- IN NET_BUF *Pkt, // packet received
- IN VOID *Context // the Context provided by user for receive data
+ IN EFI_STATUS Status,
+ IN ICMP_ERROR IcmpErr,
+ IN EFI_NET_SESSION_DATA *NetSession,
+ IN NET_BUF *Pkt,
+ IN VOID *Context
);
+/**
+ The prototype is called back when an IP packet is sent.
+
+ @param Status Result of the sending
+ @param Context The data provided by user for the received packet when
+ the callback is registered in IP_IO_OPEN_DATA::SndContext.
+ @param Sender A pointer to EFI_IP4_PROTOCOL for sender
+ @param NotifyData Context data specified when calling IpIoSend()
+
+**/
typedef
VOID
(*PKT_SENT_NOTIFY) (
- IN EFI_STATUS Status, // sent pkt result
- IN VOID *Context, // the context provided by user for sending data
- IN VOID *Sender, // the sender to be notified
- IN VOID *NotifyData // sent pkt related data to notify
+ IN EFI_STATUS Status,
+ IN VOID *Context,
+ IN VOID *Sender,
+ IN VOID *NotifyData
);
+///
+/// The data structure wraps Ip4 instance. It is used by IpIo Library to do all
+/// Ip4 operations.
+///
typedef struct _IP_IO {
-
- //
- // the node used to link this IpIo to the active IpIo list.
- //
+ ///
+ /// The node used to link this IpIo to the active IpIo list.
+ ///
LIST_ENTRY Entry;
- // the list used to maintain the IP instance for different sending purpose.
- //
+ ///
+ /// The list used to maintain the IP instance for different sending purpose.
+ ///
LIST_ENTRY IpList;
-
- //
- // the ip instance consumed by this IP IO
- //
+
EFI_HANDLE Controller;
EFI_HANDLE Image;
EFI_HANDLE ChildHandle;
+ //
+ // The IP instance consumed by this IP_IO
+ //
EFI_IP4_PROTOCOL *Ip;
BOOLEAN IsConfigured;
- //
- // some ip config data can be changed
- //
+ ///
+ /// some ip config data can be changed
+ ///
UINT8 Protocol;
- //
- // token and event used to get data from IP
- //
+ ///
+ /// Token and event used to get data from IP
+ ///
EFI_IP4_COMPLETION_TOKEN RcvToken;
- //
- // list entry used to link the token passed to IP_IO
- //
+ ///
+ /// List entry used to link the token passed to IP_IO
+ ///
LIST_ENTRY PendingSndList;
//
// User interface used to get notify from IP_IO
//
- VOID *RcvdContext;
- VOID *SndContext;
- PKT_RCVD_NOTIFY PktRcvdNotify;
- PKT_SENT_NOTIFY PktSentNotify;
+ VOID *RcvdContext; ///< See IP_IO_OPEN_DATA::RcvdContext
+ VOID *SndContext; ///< See IP_IO_OPEN_DATA::SndContext
+ PKT_RCVD_NOTIFY PktRcvdNotify; ///< See IP_IO_OPEN_DATA::PktRcvdNotify
+ PKT_SENT_NOTIFY PktSentNotify; ///< See IP_IO_OPEN_DATA::PktSentNotify
} IP_IO;
+///
+/// The struct is used for user to pass IP configuration and callbacks to IP_IO.
+/// It is used by IpIoOpen().
+///
typedef struct _IP_IO_OPEN_DATA {
- EFI_IP4_CONFIG_DATA IpConfigData;
- VOID *RcvdContext;
- VOID *SndContext;
- PKT_RCVD_NOTIFY PktRcvdNotify;
- PKT_SENT_NOTIFY PktSentNotify;
+ EFI_IP4_CONFIG_DATA IpConfigData; ///< Configuration of the IP instance
+ VOID *RcvdContext; ///< Context data used by receive callback
+ VOID *SndContext; ///< Context data used by send callback
+ PKT_RCVD_NOTIFY PktRcvdNotify; ///< Receive callback
+ PKT_SENT_NOTIFY PktSentNotify; ///< Send callback
} IP_IO_OPEN_DATA;
+///
+/// Internal struct book-keeping send request of IP_IO.
+///
+/// An IP_IO_SEND_ENTRY will be created each time a send request is issued to
+/// IP_IO via IpIoSend().
+///
typedef struct _IP_IO_SEND_ENTRY {
LIST_ENTRY Entry;
IP_IO *IpIo;
@@ -159,6 +206,10 @@ typedef struct _IP_IO_SEND_ENTRY { typedef EFI_IP4_OVERRIDE_DATA IP_IO_OVERRIDE;
+///
+/// The IP_IO_IP_INFO is used in IpIoSend() to override the default IP instance
+/// in IP_IO.
+///
typedef struct _IP_IO_IP_INFO {
IP4_ADDR Addr;
IP4_ADDR SubnetMask;
@@ -171,12 +222,16 @@ typedef struct _IP_IO_IP_INFO { /**
Create a new IP_IO instance.
+
+ This function uses IP4 service binding protocol in Controller to create an IP4
+ child (aka IP4 instance).
- @param Image The image handle of an IP_IO consumer protocol.
- @param Controller The controller handle of an IP_IO consumer protocol
- installed on.
+ @param Image The image handle of the driver or application that
+ consumes IP_IO.
+ @param Controller The controller handle that has IP4 service binding
+ protocol installed.
- @return Pointer to a newly created IP_IO instance.
+ @return Pointer to a newly created IP_IO instance, or NULL if failed.
**/
IP_IO *
@@ -188,12 +243,15 @@ IpIoCreate ( /**
Destroy an IP_IO instance.
+
+ This function is paired with IpIoCreate(). The IP_IO will be closed first.
+ Resource will be freed afterwards. See IpIoClose().
- @param IpIo Pointer to the IP_IO instance that needs to
- destroy.
+ @param IpIo Pointer to the IP_IO instance that needs to be
+ destroyed.
@retval EFI_SUCCESS The IP_IO instance destroyed successfully.
- @retval other Error condition occurred.
+ @retval Other Error condition occurred.
**/
EFI_STATUS
@@ -204,11 +262,14 @@ IpIoDestroy ( /**
Stop an IP_IO instance.
+
+ This function is paired with IpIoOpen(). The IP_IO will be unconfigured and all
+ the pending send/receive tokens will be canceled.
@param IpIo Pointer to the IP_IO instance that needs to stop.
@retval EFI_SUCCESS The IP_IO instance stopped successfully.
- @retval other Error condition occurred.
+ @retval Other Error condition occurred.
**/
EFI_STATUS
@@ -219,16 +280,22 @@ IpIoStop ( /**
Open an IP_IO instance for use.
+
+ This function is called after IpIoCreate(). It is used for configuring the IP
+ instance and register the callbacks and their context data for sending and
+ receiving IP packets.
@param IpIo Pointer to an IP_IO instance that needs to open.
- @param OpenData The configuration data for the IP_IO instance.
+ @param OpenData The configuration data and callbacks for the IP_IO
+ instance.
@retval EFI_SUCCESS The IP_IO instance opened with OpenData
successfully.
- @retval other Error condition occurred.
+ @retval Other Error condition occurred.
**/
EFI_STATUS
+EFIAPI
IpIoOpen (
IN IP_IO *IpIo,
IN IP_IO_OPEN_DATA *OpenData
@@ -236,13 +303,18 @@ IpIoOpen ( /**
Send out an IP packet.
+
+ This function is called after IpIoOpen(). The data to be sent are wrapped in
+ Pkt. The IP instance wrapped in IpIo is used for sending by default but can be
+ overriden by Sender. Other sending configs, like source address and gateway
+ address etc., are specified in OverrideData.
@param IpIo Pointer to an IP_IO instance used for sending IP
packet.
@param Pkt Pointer to the IP packet to be sent.
@param Sender The IP protocol instance used for sending.
- @param Context
- @param NotifyData
+ @param Context Optional context data
+ @param NotifyData Optional notify data
@param Dest The destination IP address to send this packet to.
@param OverrideData The data to override some configuration of the IP
instance used for sending.
@@ -257,18 +329,18 @@ EFIAPI IpIoSend (
IN IP_IO *IpIo,
IN NET_BUF *Pkt,
- IN IP_IO_IP_INFO *Sender,
- IN VOID *Context OPTIONAL,
- IN VOID *NotifyData OPTIONAL,
+ IN IP_IO_IP_INFO *Sender OPTIONAL,
+ IN VOID *Context OPTIONAL,
+ IN VOID *NotifyData OPTIONAL,
IN IP4_ADDR Dest,
- IN IP_IO_OVERRIDE *OverrideData
+ IN IP_IO_OVERRIDE *OverrideData OPTIONAL
);
/**
Cancel the IP transmit token which wraps this Packet.
@param IpIo Pointer to the IP_IO instance.
- @param Packet Pointer to the packet to cancel.
+ @param Packet Pointer to the packet of NET_BUF to cancel.
**/
VOID
@@ -280,11 +352,15 @@ IpIoCancelTxToken ( /**
Add a new IP instance for sending data.
+
+ The function is used to add the IP_IO to the IP_IO sending list. The caller
+ can later use IpIoFindSender() to get the IP_IO and call IpIoSend() to send
+ data.
@param IpIo Pointer to a IP_IO instance to add a new IP
instance for sending purpose.
- @return Pointer to the created IP_IO_IP_INFO structure, NULL is failed.
+ @return Pointer to the created IP_IO_IP_INFO structure, NULL if failed.
**/
IP_IO_IP_INFO *
@@ -298,14 +374,15 @@ IpIoAddIp ( is not NULL.
@param IpInfo Pointer to the IP_IO_IP_INFO instance.
- @param Ip4ConfigData The IP4 configure data used to configure the ip
- instance, if NULL the ip instance is reseted. If
+ @param Ip4ConfigData The IP4 configure data used to configure the IP
+ instance, if NULL the IP instance is reset. If
UseDefaultAddress is set to TRUE, and the configure
operation succeeds, the default address information
is written back in this Ip4ConfigData.
@retval EFI_STATUS The status returned by IP4->Configure or
IP4->Receive.
+ @retval Other Configuration fails.
**/
EFI_STATUS
@@ -318,12 +395,14 @@ IpIoConfigIp ( /**
Destroy an IP instance maintained in IpIo->IpList for
sending purpose.
+
+ This function pairs with IpIoAddIp(). The IpInfo is previously created by
+ IpIoAddIp(). The IP_IO_IP_INFO::RefCnt is decremented and the IP instance
+ will be dstroyed if the RefCnt is zero.
@param IpIo Pointer to the IP_IO instance.
@param IpInfo Pointer to the IpInfo to be removed.
- @return None.
-
**/
VOID
EFIAPI
@@ -335,12 +414,15 @@ IpIoRemoveIp ( /**
Find the first IP protocol maintained in IpIo whose local
address is the same with Src.
+
+ This function is called when the caller needs the IpIo to send data to the
+ specified Src. The IpIo was added previously by IpIoAddIp().
@param IpIo Pointer to the pointer of the IP_IO instance.
@param Src The local IP address.
@return Pointer to the IP protocol can be used for sending purpose and its local
- @return address is the same with Src.
+ address is the same with Src.
**/
IP_IO_IP_INFO *
@@ -351,10 +433,10 @@ IpIoFindSender ( );
/**
- Get the ICMP error map information, the ErrorStatus will be returned.
- The IsHard and Notify are optional. If they are not NULL, this rouine will
- fill them.
- We move IcmpErrMap[] to local variable to enable EBC build.
+ Get the ICMP error map information.
+
+ The ErrorStatus will be returned. The IsHard and Notify are optional. If they
+ are not NULL, this routine will fill them.
@param IcmpError IcmpError Type
@param IsHard Whether it is a hard error
@@ -367,8 +449,8 @@ EFI_STATUS EFIAPI
IpIoGetIcmpErrStatus (
IN ICMP_ERROR IcmpError,
- OUT BOOLEAN *IsHard, OPTIONAL
- OUT BOOLEAN *Notify OPTIONAL
+ OUT BOOLEAN *IsHard OPTIONAL,
+ OUT BOOLEAN *Notify OPTIONAL
);
#endif
|