diff options
| -rw-r--r-- | MdeModulePkg/Include/Library/UdpIoLib.h | 166 | ||||
| -rw-r--r-- | MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c | 101 |
2 files changed, 175 insertions, 92 deletions
diff --git a/MdeModulePkg/Include/Library/UdpIoLib.h b/MdeModulePkg/Include/Library/UdpIoLib.h index 0be5b57..40ea089 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.
**/
diff --git a/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c b/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c index 6efb37e..d6ac652 100644 --- a/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c +++ b/MdeModulePkg/Library/DxeUdpIoLib/DxeUdpIoLib.c @@ -4,7 +4,7 @@ Copyright (c) 2005 - 2007, 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,
@@ -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.
**/
|