The helper routines to access UDP service. It is used by both\r
DHCP and MTFTP.\r
\r
-Copyright (c) 2006 - 2008, Intel Corporation\r
+Copyright (c) 2006 - 2008, Intel Corporation.<BR>\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution. The full text of the license may be found at\r
+which accompanies this distribution. The full text of the license may be found at<BR>\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
\r
typedef struct _UDP_IO_PORT UDP_IO_PORT;\r
\r
+///\r
+/// Signatures used by UdpIo Library.\r
+///\r
typedef enum {\r
UDP_IO_RX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'R'),\r
UDP_IO_TX_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'T'),\r
UDP_IO_SIGNATURE = SIGNATURE_32 ('U', 'D', 'P', 'I')\r
} UDP_IO_SIGNATURE_TYPE;\r
\r
+///\r
+/// The Udp4 address pair.\r
+///\r
typedef struct {\r
IP4_ADDR LocalAddr;\r
UINT16 LocalPort;\r
UINT16 RemotePort;\r
} UDP_POINTS;\r
\r
-//\r
-// This prototype is used by both receive and transmission.\r
-// When receiving Netbuf is allocated by UDP access point, and\r
-// released by user. When transmitting, the NetBuf is from user,\r
-// and provided to the callback as a reference.\r
-//\r
+/**\r
+ Prototype called when receiving or sending packets from/to a UDP point.\r
+\r
+ This prototype is used by both receive and sending when calling\r
+ UdpIoRecvDatagram or UdpIoSendDatagram. When receiving, Netbuf is allocated by\r
+ UDP access point, and released by user. When sending, the NetBuf is from user,\r
+ and provided to the callback as a reference.\r
+ \r
+ @param Packet Packet received or sent\r
+ @param Points The Udp4 address pair corresponds to the Udp4 IO\r
+ @param IoStatus Packet receiving or sending status\r
+ @param Context User-defined data when calling UdpIoRecvDatagram or\r
+ UdpIoSendDatagram\r
+\r
+ @return None\r
+**/\r
typedef\r
VOID\r
-(*UDP_IO_CALLBACK) (\r
+(EFIAPI *UDP_IO_CALLBACK) (\r
IN NET_BUF *Packet,\r
IN UDP_POINTS *Points,\r
IN EFI_STATUS IoStatus,\r
IN VOID *Context\r
);\r
\r
-//\r
-// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,\r
-// the CallBack will be called. Only one receive request is send to UDP.\r
-// HeadLen gives the length of the application's header. UDP_IO will\r
-// make the application's header continous before delivery up.\r
-//\r
+///\r
+/// This structure is used internally by UdpIo Library.\r
+///\r
+/// Each receive request is wrapped in an UDP_RX_TOKEN. Upon completion,\r
+/// the CallBack will be called. Only one receive request is sent to UDP at a\r
+/// time. HeadLen gives the length of the application's header. UDP_IO will\r
+/// make the application's header continuous before delivering up.\r
+///\r
typedef struct {\r
UINT32 Signature;\r
UDP_IO_PORT *UdpIo;\r
EFI_UDP4_COMPLETION_TOKEN UdpToken;\r
} UDP_RX_TOKEN;\r
\r
-//\r
-// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,\r
-// the CallBack will be called. There can be several transmit requests.\r
-//\r
+///\r
+/// This structure is used internally by UdpIo Library.\r
+///\r
+/// Each transmit request is wrapped in an UDP_TX_TOKEN. Upon completion,\r
+/// the CallBack will be called. There can be several transmit requests and they\r
+/// are linked in a list.\r
+///\r
typedef struct {\r
UINT32 Signature;\r
LIST_ENTRY Link;\r
EFI_UDP4_TRANSMIT_DATA UdpTxData;\r
} UDP_TX_TOKEN;\r
\r
+///\r
+/// Type defined as UDP_IO_PORT.\r
+///\r
+/// The data structure wraps Udp4 instance and its configuration. It is used by\r
+/// UdpIo Library to do all Udp4 operations.\r
+///\r
struct _UDP_IO_PORT {\r
UINT32 Signature;\r
LIST_ENTRY Link;\r
EFI_HANDLE Image;\r
EFI_HANDLE UdpHandle;\r
\r
- EFI_UDP4_PROTOCOL *Udp;\r
+ EFI_UDP4_PROTOCOL *Udp; ///< The wrapped Udp4 instance.\r
EFI_UDP4_CONFIG_DATA UdpConfig;\r
EFI_SIMPLE_NETWORK_MODE SnpMode;\r
\r
- LIST_ENTRY SentDatagram;\r
+ LIST_ENTRY SentDatagram; ///< A list of UDP_TX_TOKEN.\r
UDP_RX_TOKEN *RecvRequest;\r
};\r
\r
+/**\r
+ Prototype called when UdpIo Library configures a Udp4 instance.\r
+ \r
+ The prototype is set and called when creating a UDP_IO_PORT in UdpIoCreatePort.\r
+ \r
+ @param UdpIo The UDP_IO_PORT to configure\r
+ @param Context User-defined data when calling UdpIoCreatePort\r
+ \r
+ @retval EFI_SUCCESS The configure process succeeds\r
+ @retval Others The UDP_IO_PORT fails to configure indicating\r
+ UdpIoCreatePort should fail\r
+**/\r
typedef\r
EFI_STATUS\r
-(*UDP_IO_CONFIG) (\r
+(EFIAPI *UDP_IO_CONFIG) (\r
IN UDP_IO_PORT *UdpIo,\r
IN VOID *Context\r
);\r
\r
+/**\r
+ The select function to decide whether to cancel the UDP_TX_TOKEN. It is used\r
+ \r
+ @param Token The UDP_TX_TOKEN to decide whether to cancel\r
+ @param Context User-defined data in UdpIoCancelDgrams\r
+ \r
+ @retval TRUE To cancel the UDP_TX_TOKEN\r
+ @retval FALSE Do not cancel this UDP_TX_TOKEN\r
+\r
+**/\r
typedef\r
BOOLEAN\r
(*UDP_IO_TO_CANCEL) (\r
);\r
\r
/**\r
- Create a UDP IO port to access the UDP service. It will\r
- create and configure a UDP child.\r
+ Create a UDP_IO_PORT to access the UDP service. It will create and configure\r
+ a UDP child.\r
+ \r
+ The function will locate the UDP service binding prototype on the Controller\r
+ parameter and use it to create a UDP child (aka Udp instance). Then the UDP\r
+ child will be configured by calling Configure function prototype. Any failures\r
+ in creating or configure the UDP child will lead to the failure of UDP_IO_PORT\r
+ creation.\r
\r
@param Controller The controller that has the UDP service binding\r
protocol installed.\r
@param Configure The function to configure the created UDP child\r
@param Context The opaque parameter for the Configure funtion.\r
\r
- @return A point to just created UDP IO port or NULL if some error happened.\r
+ @return Newly-created UDP_IO_PORT or NULL if failed.\r
\r
**/\r
UDP_IO_PORT *\r
);\r
\r
/**\r
- Free the UDP IO port and all its related resources including\r
- all the transmitted packet.\r
+ Free the UDP_IO_PORT and all its related resources.\r
+ \r
+ The function will cancel all sent datagram and receive request.\r
\r
- @param UdpIo The UDP IO port to free.\r
+ @param UdpIo The UDP_IO_PORT to free.\r
\r
- @retval EFI_SUCCESS The UDP IO port is freed.\r
+ @retval EFI_SUCCESS The UDP_IO_PORT is freed.\r
\r
**/\r
EFI_STATUS\r
);\r
\r
/**\r
- Clean up the UDP IO port. It will release all the transmitted\r
- datagrams and receive request. It will also configure NULL the\r
- UDP child.\r
+ Clean up the UDP_IO_PORT without freeing it. The function is called when\r
+ user wants to re-use the UDP_IO_PORT later.\r
+ \r
+ It will release all the transmitted datagrams and receive request. It will\r
+ also configure NULL for the UDP instance.\r
\r
- @param UdpIo UDP IO port to clean up.\r
+ @param UdpIo The UDP_IO_PORT to clean up.\r
\r
**/\r
VOID\r
);\r
\r
/**\r
- Send a packet through the UDP IO port.\r
+ Send a packet through the UDP_IO_PORT.\r
+ \r
+ The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called\r
+ when the packet is sent. The optional parameter EndPoint overrides the default\r
+ address pair if specified.\r
\r
- @param UdpIo The UDP IO Port to send the packet through\r
+ @param UdpIo The UDP_IO_PORT to send the packet through\r
@param Packet The packet to send\r
- @param EndPoint The local and remote access point\r
+ @param EndPoint The local and remote access point. Override the\r
+ default address pair set during configuration.\r
@param Gateway The gateway to use\r
- @param CallBack The call back function to call when packet is\r
+ @param CallBack The function being called when packet is\r
transmitted or failed.\r
- @param Context The opque parameter to the CallBack\r
+ @param Context The opaque parameter passed to CallBack\r
\r
@retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the packet\r
@retval EFI_SUCCESS The packet is successfully delivered to UDP for\r
UdpIoSendDatagram (\r
IN UDP_IO_PORT *UdpIo,\r
IN NET_BUF *Packet,\r
- IN UDP_POINTS *EndPoint, OPTIONAL\r
+ IN UDP_POINTS *EndPoint OPTIONAL,\r
IN IP4_ADDR Gateway,\r
IN UDP_IO_CALLBACK CallBack,\r
IN VOID *Context\r
/**\r
Cancel a single sent datagram.\r
\r
- @param UdpIo The UDP IO port to cancel the packet from\r
+ @param UdpIo The UDP_IO_PORT to cancel the packet from\r
@param Packet The packet to cancel\r
\r
**/\r
);\r
\r
/**\r
- Issue a receive request to the UDP IO port.\r
-\r
- @param UdpIo The UDP IO port to recieve the packet from.\r
- @param CallBack The call back function to execute when receive\r
- finished.\r
- @param Context The opque context to the call back\r
- @param HeadLen The lenght of the application's header\r
+ Issue a receive request to the UDP_IO_PORT.\r
+ \r
+ This function is called when upper-layer needs packet from UDP for processing.\r
+ Only one receive request is acceptable at a time so a common usage model is\r
+ to invoke this function inside its Callback function when the former packet\r
+ is processed.\r
+\r
+ @param UdpIo The UDP_IO_PORT to receive the packet from.\r
+ @param CallBack The call back function to execute when the packet\r
+ is received.\r
+ @param Context The opaque context passed to Callback\r
+ @param HeadLen The length of the upper-layer's protocol header\r
\r
@retval EFI_ALREADY_STARTED There is already a pending receive request. Only\r
- one receive request is supported.\r
- @retval EFI_OUT_OF_RESOURCES Failed to allocate some resource.\r
+ one receive request is supported at a time.\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.\r
@retval EFI_SUCCESS The receive request is issued successfully.\r
\r
**/\r
Copyright (c) 2005 - 2007, Intel Corporation.<BR>\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
-which accompanies this distribution. The full text of the license may be found at\r
+which accompanies this distribution. The full text of the license may be found at<BR>\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
\r
\r
/**\r
- Free a UDP_TX_TOKEN. The event is closed and memory released.\r
+ Free a UDP_TX_TOKEN. The TX event is closed.\r
\r
@param Token The UDP_TX_TOKEN to release.\r
\r
}\r
\r
/**\r
- Free a receive request wrap.\r
+ Free a UDP_RX_TOKEN. The RX event is closed.\r
\r
- @param Token The receive request to release.\r
+ @param Token The UDP_RX_TOKEN to release.\r
\r
**/\r
VOID\r
\r
/**\r
The callback function when the packet is sent by UDP.\r
+ \r
It will remove the packet from the local list then call\r
- the packet owner's callback function.\r
+ the packet owner's callback function set by UdpIoSendDatagram.\r
\r
@param Context The UDP TX Token.\r
\r
}\r
\r
/**\r
- The event handle for UDP receive request. It will build\r
- a NET_BUF from the recieved UDP data, then deliver it\r
+ The event handle for UDP receive request.\r
+ \r
+ It will build a NET_BUF from the recieved UDP data, then deliver it\r
to the receiver.\r
\r
@param Context The UDP RX token.\r
return Token;\r
}\r
\r
-\r
-\r
-\r
/**\r
- Create a UDP IO port to access the UDP service. It will\r
- create and configure a UDP child.\r
+ Create a UDP_IO_PORT to access the UDP service. It will create and configure\r
+ a UDP child.\r
+ \r
+ The function will locate the UDP service binding prototype on the Controller\r
+ parameter and use it to create a UDP child (aka Udp instance). Then the UDP\r
+ child will be configured by calling Configure function prototype. Any failures\r
+ in creating or configure the UDP child will lead to the failure of UDP_IO_PORT\r
+ creation.\r
\r
@param Controller The controller that has the UDP service binding\r
protocol installed.\r
@param Configure The function to configure the created UDP child\r
@param Context The opaque parameter for the Configure funtion.\r
\r
- @return A point to just created UDP IO port or NULL if some error happened.\r
+ @return Newly-created UDP_IO_PORT or NULL if failed.\r
\r
**/\r
UDP_IO_PORT *\r
return NULL;\r
}\r
\r
-\r
/**\r
- Cancel all the sent datagram that pass the selection of ToCancel.\r
+ Cancel all the sent datagram that pass the selection criteria of ToCancel.\r
If ToCancel is NULL, all the datagrams are cancelled.\r
\r
- @param UdpIo The UDP IO port to cancel packet\r
+ @param UdpIo The UDP_IO_PORT to cancel packet\r
@param IoStatus The IoStatus to return to the packet owners.\r
@param ToCancel The select funtion to test whether to cancel this\r
packet or not.\r
}\r
}\r
\r
-\r
/**\r
- Free the UDP IO port and all its related resources including\r
- all the transmitted packet.\r
+ Free the UDP_IO_PORT and all its related resources.\r
+ \r
+ The function will cancel all sent datagram and receive request.\r
\r
- @param UdpIo The UDP IO port to free.\r
+ @param UdpIo The UDP_IO_PORT to free.\r
\r
- @retval EFI_SUCCESS The UDP IO port is freed.\r
+ @retval EFI_SUCCESS The UDP_IO_PORT is freed.\r
\r
**/\r
EFI_STATUS\r
\r
\r
/**\r
- Clean up the UDP IO port. It will release all the transmitted\r
- datagrams and receive request. It will also configure NULL the\r
- UDP child.\r
+ Clean up the UDP_IO_PORT without freeing it. The function is called when\r
+ user wants to re-use the UDP_IO_PORT later.\r
+ \r
+ It will release all the transmitted datagrams and receive request. It will\r
+ also configure NULL for the UDP instance.\r
\r
- @param UdpIo UDP IO port to clean up.\r
+ @param UdpIo The UDP_IO_PORT to clean up.\r
\r
**/\r
VOID\r
}\r
\r
/**\r
- Send a packet through the UDP IO port.\r
+ Send a packet through the UDP_IO_PORT.\r
+ \r
+ The packet will be wrapped in UDP_TX_TOKEN. Function Callback will be called\r
+ when the packet is sent. The optional parameter EndPoint overrides the default\r
+ address pair if specified.\r
\r
- @param UdpIo The UDP IO Port to send the packet through\r
+ @param UdpIo The UDP_IO_PORT to send the packet through\r
@param Packet The packet to send\r
- @param EndPoint The local and remote access point\r
+ @param EndPoint The local and remote access point. Override the\r
+ default address pair set during configuration.\r
@param Gateway The gateway to use\r
- @param CallBack The call back function to call when packet is\r
+ @param CallBack The function being called when packet is\r
transmitted or failed.\r
- @param Context The opque parameter to the CallBack\r
+ @param Context The opaque parameter passed to CallBack\r
\r
@retval EFI_OUT_OF_RESOURCES Failed to allocate resource for the packet\r
@retval EFI_SUCCESS The packet is successfully delivered to UDP for\r
\r
\r
/**\r
- The selection function to cancel a single sent datagram.\r
+ The select function to cancel a single sent datagram.\r
\r
- @param Token The UDP TX token to test againist.\r
- @param Context The context\r
+ @param Token The UDP_TX_TOKEN to test against\r
+ @param Context The NET_BUF of the sent datagram\r
\r
@retval TRUE The packet is to be cancelled.\r
@retval FALSE The packet is not to be cancelled.\r
return FALSE;\r
}\r
\r
-\r
/**\r
Cancel a single sent datagram.\r
\r
- @param UdpIo The UDP IO port to cancel the packet from\r
+ @param UdpIo The UDP_IO_PORT to cancel the packet from\r
@param Packet The packet to cancel\r
\r
**/\r
}\r
\r
/**\r
- Issue a receive request to the UDP IO port.\r
+ Issue a receive request to the UDP_IO_PORT.\r
+ \r
+ This function is called when upper-layer needs packet from UDP for processing.\r
+ Only one receive request is acceptable at a time so a common usage model is\r
+ to invoke this function inside its Callback function when the former packet\r
+ is processed.\r
\r
- @param UdpIo The UDP IO port to recieve the packet from.\r
- @param CallBack The call back function to execute when receive\r
- finished.\r
- @param Context The opque context to the call back\r
- @param HeadLen The lenght of the application's header\r
+ @param UdpIo The UDP_IO_PORT to receive the packet from.\r
+ @param CallBack The call back function to execute when the packet\r
+ is received.\r
+ @param Context The opaque context passed to Callback\r
+ @param HeadLen The length of the upper-layer's protocol header\r
\r
@retval EFI_ALREADY_STARTED There is already a pending receive request. Only\r
- one receive request is supported.\r
- @retval EFI_OUT_OF_RESOURCES Failed to allocate some resource.\r
+ one receive request is supported at a time.\r
+ @retval EFI_OUT_OF_RESOURCES Failed to allocate needed resources.\r
@retval EFI_SUCCESS The receive request is issued successfully.\r
\r
**/\r
projects / mirror_edk2.git / commitdiff