From: jgong5 Date: Tue, 30 Dec 2008 12:12:46 +0000 (+0000) Subject: Enhance function header X-Git-Tag: edk2-stable201903~19091 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=e29a2e7e8003e824d77a68f980daf0d614fc3bf5 Enhance function header git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@7156 6f19259b-4bc3-4df7-8a09-765794883524 --- 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