diff options
| -rw-r--r-- | MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Driver.c | 143 | ||||
| -rw-r--r-- | MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Impl.c | 105 | ||||
| -rw-r--r-- | MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Main.c | 402 |
3 files changed, 345 insertions, 305 deletions
diff --git a/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Driver.c b/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Driver.c index 0c54364127..50959671e8 100644 --- a/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Driver.c +++ b/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Driver.c @@ -37,15 +37,21 @@ EFI_SERVICE_BINDING_PROTOCOL mUdp4ServiceBinding = { /**
- Test to see if this driver supports ControllerHandle.
-
- @param This Protocol instance pointer.
- @param ControllerHandle Handle of device to test.
- @param RemainingDevicePath Optional parameter use to pick a specific child
- device to start.
-
- @retval EFI_SUCCES This driver supports this device.
- @retval EFI_ALREADY_STARTED This driver is already running on this device.
+ Test to see if this driver supports ControllerHandle. This service
+ is called by the EFI boot service ConnectController(). In
+ order to make drivers as small as possible, there are a few calling
+ restrictions for this service. ConnectController() must
+ follow these calling restrictions. If any other agent wishes to call
+ Supported() it must also follow these calling restrictions.
+
+ @param This Protocol instance pointer.
+ @param ControllerHandle Handle of device to test
+ @param RemainingDevicePath Optional parameter use to pick a specific child
+ device to start.
+
+ @retval EFI_SUCCESS This driver supports this device
+ @retval EFI_ALREADY_STARTED This driver is already running on this device
+ @retval other This driver does not support this device
**/
EFI_STATUS
@@ -90,16 +96,21 @@ Udp4DriverBindingSupported ( /**
- Start this driver on ControllerHandle.
-
- @param This Protocol instance pointer.
- @param ControllerHandle Handle of device to bind driver to
- @param RemainingDevicePath Optional parameter use to pick a specific child
- device to start.
-
- @retval EFI_SUCCES This driver is added to ControllerHandle
- @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle
- @retval other This driver does not support this device
+ Start this driver on ControllerHandle. This service is called by the
+ EFI boot service ConnectController(). In order to make
+ drivers as small as possible, there are a few calling restrictions for
+ this service. ConnectController() must follow these
+ calling restrictions. If any other agent wishes to call Start() it
+ must also follow these calling restrictions.
+
+ @param This Protocol instance pointer.
+ @param ControllerHandle Handle of device to bind driver to
+ @param RemainingDevicePath Optional parameter use to pick a specific child
+ device to start.
+
+ @retval EFI_SUCCESS This driver is added to ControllerHandle
+ @retval EFI_ALREADY_STARTED This driver is already running on ControllerHandle
+ @retval other This driver does not support this device
**/
EFI_STATUS
@@ -148,16 +159,21 @@ Udp4DriverBindingStart ( /**
- Stop this driver on ControllerHandle.
-
- @param This Protocol instance pointer.
- @param ControllerHandle Handle of device to stop driver on
- @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number
- of children is zero stop the entire bus driver.
- @param ChildHandleBuffer List of Child Handles to Stop.
-
- @retval EFI_SUCCES This driver is removed ControllerHandle.
- @retval other This driver was not removed from this device.
+ Stop this driver on ControllerHandle. This service is called by the
+ EFI boot service DisconnectController(). In order to
+ make drivers as small as possible, there are a few calling
+ restrictions for this service. DisconnectController()
+ must follow these calling restrictions. If any other agent wishes
+ to call Stop() it must also follow these calling restrictions.
+
+ @param This Protocol instance pointer.
+ @param ControllerHandle Handle of device to stop driver on
+ @param NumberOfChildren Number of Handles in ChildHandleBuffer. If number of
+ children is zero stop the entire bus driver.
+ @param ChildHandleBuffer List of Child Handles to Stop.
+
+ @retval EFI_SUCCESS This driver is removed ControllerHandle
+ @retval other This driver was not removed from this device
**/
EFI_STATUS
@@ -230,16 +246,16 @@ Udp4DriverBindingStop ( /**
Creates a child handle with a set of I/O services.
- @param This Protocol instance pointer.
- @param ChildHandle Pointer to the handle of the child to create. If
- it is NULL, then a new handle is created. If it
- is not NULL, then the I/O services are added to
- the existing child handle.
+ @param This Protocol instance pointer.
+ @param ChildHandle Pointer to the handle of the child to create. If it is NULL,
+ then a new handle is created. If it is not NULL, then the
+ I/O services are added to the existing child handle.
- @retval EFI_SUCCES The child handle was created with the I/O services
- @retval EFI_OUT_OF_RESOURCES There are not enough resources availabe to create
- the child
- @retval other The child handle was not created
+ @retval EFI_SUCCES The child handle was created with the I/O services
+ @retval EFI_INVALID_PARAMETER ChildHandle is NULL.
+ @retval EFI_OUT_OF_RESOURCES There are not enough resources availabe to create
+ the child
+ @retval other The child handle was not created
**/
EFI_STATUS
@@ -348,17 +364,16 @@ ON_ERROR: /**
Destroys a child handle with a set of I/O services.
- @param This Protocol instance pointer.
- @param ChildHandle Handle of the child to destroy
+ @param This Protocol instance pointer.
+ @param ChildHandle Handle of the child to destroy
- @retval EFI_SUCCES The I/O services were removed from the child
- handle
- @retval EFI_UNSUPPORTED The child handle does not support the I/O services
- that are being removed
- @retval EFI_INVALID_PARAMETER Child handle is not a valid EFI Handle.
- @retval EFI_ACCESS_DENIED The child handle could not be destroyed because
- its I/O services are being used.
- @retval other The child handle was not destroyed
+ @retval EFI_SUCCES The I/O services were removed from the child handle
+ @retval EFI_UNSUPPORTED The child handle does not support the I/O services
+ that are being removed.
+ @retval EFI_INVALID_PARAMETER Child handle is not a valid EFI Handle.
+ @retval EFI_ACCESS_DENIED The child handle could not be destroyed because its
+ I/O services are being used.
+ @retval other The child handle was not destroyed
**/
EFI_STATUS
@@ -460,31 +475,27 @@ Udp4ServiceBindingDestroyChild ( return EFI_SUCCESS;
}
+/**
+ This is the declaration of an EFI image entry point. This entry point is
+ the same for UEFI Applications, UEFI OS Loaders, and UEFI Drivers including
+ both device drivers and bus drivers.
+
+ The entry point for Udp4 driver which installs the driver binding
+ and component name protocol on its ImageHandle.
+
+ @param ImageHandle The firmware allocated handle for the UEFI image.
+ @param SystemTable A pointer to the EFI System Table.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
+**/
EFI_STATUS
EFIAPI
Udp4DriverEntryPoint (
IN EFI_HANDLE ImageHandle,
IN EFI_SYSTEM_TABLE *SystemTable
)
-/*++
-
-Routine Description:
-
- The entry point for Udp4 driver which installs the driver binding
- and component name protocol on its ImageHandle.
-
-Arguments:
-
- ImageHandle - The image handle of the driver.
- SystemTable - The system table.
-
-Returns:
-
- EFI_SUCCESS - if the driver binding and component name protocols are
- successfully installed, otherwise if failed.
-
---*/
{
EFI_STATUS Status;
diff --git a/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Impl.c b/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Impl.c index ab50830b68..d9372ba1b8 100644 --- a/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Impl.c +++ b/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Impl.c @@ -128,13 +128,14 @@ Udp4SendPortUnreach ( @retval EFI_SUCCESS The udp4 service context data is created and
initialized.
@retval EFI_OUT_OF_RESOURCES Cannot allocate memory.
+ @retval other Other error occurs.
**/
EFI_STATUS
Udp4CreateService (
- IN UDP4_SERVICE_DATA *Udp4Service,
- IN EFI_HANDLE ImageHandle,
- IN EFI_HANDLE ControllerHandle
+ IN OUT UDP4_SERVICE_DATA *Udp4Service,
+ IN EFI_HANDLE ImageHandle,
+ IN EFI_HANDLE ControllerHandle
)
{
EFI_STATUS Status;
@@ -251,7 +252,7 @@ Udp4CleanService ( service context.
@param Event The event this function registered to.
- @param Conext The context data registered during the creation of
+ @param Context The context data registered during the creation of
the Event.
@return None.
@@ -318,8 +319,8 @@ Udp4CheckTimeout ( **/
VOID
Udp4InitInstance (
- IN UDP4_SERVICE_DATA *Udp4Service,
- IN UDP4_INSTANCE_DATA *Instance
+ IN UDP4_SERVICE_DATA *Udp4Service,
+ IN OUT UDP4_INSTANCE_DATA *Instance
)
{
//
@@ -380,7 +381,8 @@ Udp4CleanInstance ( @param Address Pointer to the specified IPv4 address.
@param Port The udp port number.
- @return Is the specified <Address, Port> pair found or not.
+ @retval TRUE The specified <Address, Port> pair is found.
+ @retval FALSE Otherwise.
**/
BOOLEAN
@@ -427,12 +429,13 @@ Udp4FindInstanceByPort ( /**
This function tries to bind the udp instance according to the configured port
- allocation stragety.
+ allocation strategy.
@param InstanceList Pointer to the head of the list linking the udp
instances.
@param ConfigData Pointer to the ConfigData of the instance to be
- bound.
+ bound. ConfigData->StationPort will be assigned
+ with an available port value on success.
@retval EFI_SUCCESS The bound operation is completed successfully.
@retval EFI_ACCESS_DENIED The <Address, Port> specified by the ConfigData is
@@ -442,8 +445,8 @@ Udp4FindInstanceByPort ( **/
EFI_STATUS
Udp4Bind (
- IN LIST_ENTRY *InstanceList,
- IN EFI_UDP4_CONFIG_DATA *ConfigData
+ IN LIST_ENTRY *InstanceList,
+ IN OUT EFI_UDP4_CONFIG_DATA *ConfigData
)
{
EFI_IPv4_ADDRESS *StationAddress;
@@ -514,7 +517,8 @@ Udp4Bind ( uses.
@param NewConfigData Pointer to the new ConfigData.
- @return The instance is reconfigurable or not according to the NewConfigData.
+ @retval TRUE The instance is reconfigurable.
+ @retval FALSE Otherwise.
**/
BOOLEAN
@@ -523,10 +527,11 @@ Udp4IsReconfigurable ( IN EFI_UDP4_CONFIG_DATA *NewConfigData
)
{
- if ((NewConfigData->AcceptAnyPort != OldConfigData->AcceptAnyPort) ||
- (NewConfigData->AcceptBroadcast != OldConfigData->AcceptBroadcast) ||
- (NewConfigData->AcceptPromiscuous != OldConfigData->AcceptPromiscuous) ||
- (NewConfigData->AllowDuplicatePort != OldConfigData->AllowDuplicatePort)) {
+ if ((NewConfigData->AcceptAnyPort != OldConfigData->AcceptAnyPort) ||
+ (NewConfigData->AcceptBroadcast != OldConfigData->AcceptBroadcast) ||
+ (NewConfigData->AcceptPromiscuous != OldConfigData->AcceptPromiscuous) ||
+ (NewConfigData->AllowDuplicatePort != OldConfigData->AllowDuplicatePort)
+ ) {
//
// The receiving filter parameters cannot be changed.
//
@@ -534,7 +539,8 @@ Udp4IsReconfigurable ( }
if ((!NewConfigData->AcceptAnyPort) &&
- (NewConfigData->StationPort != OldConfigData->StationPort)) {
+ (NewConfigData->StationPort != OldConfigData->StationPort)
+ ) {
//
// The port is not changeable.
//
@@ -551,8 +557,9 @@ Udp4IsReconfigurable ( }
if (!NewConfigData->UseDefaultAddress &&
- (!EFI_IP4_EQUAL (&NewConfigData->StationAddress, &OldConfigData->StationAddress) ||
- !EFI_IP4_EQUAL (&NewConfigData->SubnetMask, &OldConfigData->SubnetMask))) {
+ (!EFI_IP4_EQUAL (&NewConfigData->StationAddress, &OldConfigData->StationAddress) ||
+ !EFI_IP4_EQUAL (&NewConfigData->SubnetMask, &OldConfigData->SubnetMask))
+ ) {
//
// If the instance doesn't use the default address, and the new address or
// new subnet mask is different from the old values.
@@ -568,7 +575,9 @@ Udp4IsReconfigurable ( return FALSE;
}
- if (!EFI_IP4_EQUAL (&NewConfigData->RemoteAddress, &mZeroIp4Addr) && (NewConfigData->RemotePort != OldConfigData->RemotePort)) {
+ if (!EFI_IP4_EQUAL (&NewConfigData->RemoteAddress, &mZeroIp4Addr) &&
+ NewConfigData->RemotePort != OldConfigData->RemotePort
+ ) {
//
// The RemotePort differs if it's designated in the configdata.
//
@@ -593,8 +602,8 @@ Udp4IsReconfigurable ( **/
VOID
Udp4BuildIp4ConfigData (
- IN EFI_UDP4_CONFIG_DATA *Udp4ConfigData,
- IN EFI_IP4_CONFIG_DATA *Ip4ConfigData
+ IN EFI_UDP4_CONFIG_DATA *Udp4ConfigData,
+ IN OUT EFI_IP4_CONFIG_DATA *Ip4ConfigData
)
{
CopyMem (Ip4ConfigData, &mIpIoDefaultIpConfigData, sizeof (*Ip4ConfigData));
@@ -818,8 +827,8 @@ Udp4Checksum ( **/
EFI_STATUS
Udp4RemoveToken (
- IN NET_MAP *TokenMap,
- IN EFI_UDP4_COMPLETION_TOKEN *Token
+ IN OUT NET_MAP *TokenMap,
+ IN EFI_UDP4_COMPLETION_TOKEN *Token
)
{
NET_MAP_ITEM *Item;
@@ -943,9 +952,9 @@ Udp4DgramRcvd ( **/
EFI_STATUS
Udp4LeaveGroup (
- IN NET_MAP *Map,
- IN NET_MAP_ITEM *Item,
- IN VOID *Arg OPTIONAL
+ IN OUT NET_MAP *Map,
+ IN NET_MAP_ITEM *Item,
+ IN VOID *Arg OPTIONAL
)
{
EFI_IPv4_ADDRESS *McastIp;
@@ -977,12 +986,13 @@ Udp4LeaveGroup ( /**
- This function cancle the token specified by Arg in the Map.
+ This function cancels the token specified by Arg in the Map. This is a callback
+ used by Udp4InstanceCancelToken().
@param Map Pointer to the NET_MAP.
@param Item Pointer to the NET_MAP_ITEM.
- @param Arg Pointer to the token to be cancelled, if NULL, all
- the tokens in this Map will be cancelled.
+ @param Arg Pointer to the token to be cancelled, if NULL,
+ the token specified by Item is cancelled.
@retval EFI_SUCCESS The token is cancelled if Arg is NULL or the token
is not the same as that in the Item if Arg is not
@@ -1039,7 +1049,7 @@ Udp4CancelTokens ( /**
This function removes all the Wrap datas in the RcvdDgramQue.
- @param RcvdDgramQue Pointer to the list containing all the Wrap datas.
+ @param Instance Pointer to the udp instance context data.
@return None.
@@ -1067,6 +1077,7 @@ Udp4FlushRcvdDgram ( /**
+ Cancel Udp4 tokens from the Udp4 instance.
@param Instance Pointer to the udp instance context data.
@param Token Pointer to the token to be canceled, if NULL, all
@@ -1085,7 +1096,7 @@ Udp4InstanceCancelToken ( EFI_STATUS Status;
//
- // Cancle this token from the TxTokens map.
+ // Cancel this token from the TxTokens map.
//
Status = NetMapIterate (&Instance->TxTokens, Udp4CancelTokens, Token);
@@ -1125,7 +1136,9 @@ Udp4InstanceCancelToken ( @param Udp4Session Pointer to the EFI_UDP4_SESSION_DATA abstracted
from the received udp datagram.
- @return The udp datagram matches the receiving requirments of the Instance or not.
+ @retval TRUE The udp datagram matches the receiving requirments of the
+ udp Instance.
+ @retval FALSE Otherwise.
**/
BOOLEAN
@@ -1147,7 +1160,8 @@ Udp4MatchDgram ( }
if ((!ConfigData->AcceptAnyPort && (Udp4Session->DestinationPort != ConfigData->StationPort)) ||
- ((ConfigData->RemotePort != 0) && (Udp4Session->SourcePort != ConfigData->RemotePort))) {
+ ((ConfigData->RemotePort != 0) && (Udp4Session->SourcePort != ConfigData->RemotePort))
+ ) {
//
// The local port or the remote port doesn't match.
//
@@ -1155,7 +1169,8 @@ Udp4MatchDgram ( }
if (!EFI_IP4_EQUAL (&ConfigData->RemoteAddress, &mZeroIp4Addr) &&
- !EFI_IP4_EQUAL (&ConfigData->RemoteAddress, &Udp4Session->SourceAddress)) {
+ !EFI_IP4_EQUAL (&ConfigData->RemoteAddress, &Udp4Session->SourceAddress)
+ ) {
//
// This datagram doesn't come from the instance's specified sender.
//
@@ -1163,9 +1178,10 @@ Udp4MatchDgram ( }
if (EFI_IP4_EQUAL (&ConfigData->StationAddress, &mZeroIp4Addr) ||
- EFI_IP4_EQUAL (&Udp4Session->DestinationAddress, &ConfigData->StationAddress)) {
+ EFI_IP4_EQUAL (&Udp4Session->DestinationAddress, &ConfigData->StationAddress)
+ ) {
//
- // The instance is configured to receive datagrams destinated to any station IP or
+ // The instance is configured to receive datagrams destined to any station IP or
// the destination address of this datagram matches the configured station IP.
//
return TRUE;
@@ -1181,7 +1197,8 @@ Udp4MatchDgram ( }
if (IP4_IS_MULTICAST (NTOHL (Destination)) &&
- (NULL != NetMapFindKey (&Instance->McastIps, (VOID *) (UINTN) Destination))) {
+ NetMapFindKey (&Instance->McastIps, (VOID *) (UINTN) Destination) != NULL
+ ) {
//
// It's a multicast packet and the multicast address is accepted by this instance.
//
@@ -1365,7 +1382,7 @@ Udp4InstanceDeliverDgram ( EFI_TPL OldTpl;
if (!IsListEmpty (&Instance->RcvdDgramQue) &&
- !NetMapIsEmpty (&Instance->RxTokens)) {
+ !NetMapIsEmpty (&Instance->RxTokens)) {
Wrap = NET_LIST_HEAD (&Instance->RcvdDgramQue, UDP4_RXDATA_WRAP, Link);
@@ -1381,7 +1398,7 @@ Udp4InstanceDeliverDgram ( NetbufFree (Wrap->Packet);
Wrap->Packet = Dup;
- }
+ }
NetListRemoveHead (&Instance->RcvdDgramQue);
@@ -1678,9 +1695,10 @@ Udp4IcmpHandler ( Instance = NET_LIST_USER_STRUCT (Entry, UDP4_INSTANCE_DATA, Link);
if (!Instance->Configured ||
- Instance->ConfigData.AcceptPromiscuous ||
- Instance->ConfigData.AcceptAnyPort ||
- EFI_IP4_EQUAL (&Instance->ConfigData.StationAddress, &mZeroIp4Addr)) {
+ Instance->ConfigData.AcceptPromiscuous ||
+ Instance->ConfigData.AcceptAnyPort ||
+ EFI_IP4_EQUAL (&Instance->ConfigData.StationAddress, &mZeroIp4Addr)
+ ) {
//
// Don't try to deliver the ICMP error to this instance if it is not configured,
// or it's configured to be promiscuous or accept any port or accept all the
@@ -1780,6 +1798,7 @@ Udp4NetVectorExtFree ( @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the
variable.
+ @retval EFI_SUCCESS Set variable successfully.
@retval other Set variable failed.
**/
diff --git a/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Main.c b/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Main.c index eb013e9150..d46a0de20e 100644 --- a/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Main.c +++ b/MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Main.c @@ -20,8 +20,6 @@ Abstract: #include "Udp4Impl.h"
-#include <Protocol/Ip4.h>
-
EFI_UDP4_PROTOCOL mUdp4Protocol = {
Udp4GetModeData,
Udp4Configure,
@@ -35,24 +33,23 @@ EFI_UDP4_PROTOCOL mUdp4Protocol = { /**
- This function copies the current operational settings of this EFI UDPv4 Protocol
- instance into user-supplied buffers. This function is used optionally to retrieve
- the operational mode data of underlying networks or drivers.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param Udp4ConfigData Pointer to the buffer to receive the current
- configuration data.
- @param Ip4ModeData Pointer to the EFI IPv4 Protocol mode data
- structure.
- @param MnpConfigData Pointer to the managed network configuration data
- structure.
- @param SnpModeData Pointer to the simple network mode data structure.
-
- @retval EFI_SUCCESS The mode data was read.
- @retval EFI_NOT_STARTED When Udp4ConfigData is queried, no configuration
- data is available because this instance has not
- been started.
- @retval EFI_INVALID_PARAMETER This is NULL.
+ Reads the current operational settings.
+
+ The GetModeData() function copies the current operational settings of this EFI
+ UDPv4 Protocol instance into user-supplied buffers. This function is used
+ optionally to retrieve the operational mode data of underlying networks or
+ drivers.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param Udp4ConfigData Pointer to the buffer to receive the current configuration data.
+ @param Ip4ModeData Pointer to the EFI IPv4 Protocol mode data structure.
+ @param MnpConfigData Pointer to the managed network configuration data structure.
+ @param SnpModeData Pointer to the simple network mode data structure.
+
+ @retval EFI_SUCCESS The mode data was read.
+ @retval EFI_NOT_STARTED When Udp4ConfigData is queried, no configuration data is
+ available because this instance has not been started.
+ @retval EFI_INVALID_PARAMETER This is NULL.
**/
EFI_STATUS
@@ -103,39 +100,36 @@ Udp4GetModeData ( /**
- This function is used to do the following:
- Initialize and start this instance of the EFI UDPv4 Protocol.
- Change the filtering rules and operational parameters.
- Reset this instance of the EFI UDPv4 Protocol.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param UdpConfigData Pointer to the buffer to receive the current mode
- data.
-
- @retval EFI_SUCCESS The configuration settings were set, changed, or
- reset successfully.
- @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
- BOOTP, RARP, etc.) is not finished yet.
- @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE: This is
- NULL. UdpConfigData.StationAddress is not a valid
- unicast IPv4 address. UdpConfigData.SubnetMask is
- not a valid IPv4 address mask.
- UdpConfigData.RemoteAddress is not a valid unicast
- IPv4 address if it is not zero.
- @retval EFI_ALREADY_STARTED The EFI UDPv4 Protocol instance is already
- started/configured and must be stopped/reset
- before it can be reconfigured. Only TypeOfService,
- TimeToLive, DoNotFragment, ReceiveTimeout, and
- TransmitTimeout can be reconfigured without
- stopping the current instance of the EFI UDPv4
- Protocol.
- @retval EFI_ACCESS_DENIED UdpConfigData.AllowDuplicatePort is FALSE and
- UdpConfigData.StationPort is already used by other
- instance.
- @retval EFI_OUT_OF_RESOURCES The EFI UDPv4 Protocol driver cannot allocate
- memory for this EFI UDPv4 Protocol instance.
- @retval EFI_DEVICE_ERROR An unexpected network or system error occurred and
- this instance was not opened.
+ Initializes, changes, or resets the operational parameters for this instance of the EFI UDPv4
+ Protocol.
+
+ The Configure() function is used to do the following:
+ * Initialize and start this instance of the EFI UDPv4 Protocol.
+ * Change the filtering rules and operational parameters.
+ * Reset this instance of the EFI UDPv4 Protocol.
+ Until these parameters are initialized, no network traffic can be sent or
+ received by this instance. This instance can be also reset by calling Configure()
+ with UdpConfigData set to NULL. Once reset, the receiving queue and transmitting
+ queue are flushed and no traffic is allowed through this instance.
+ With different parameters in UdpConfigData, Configure() can be used to bind
+ this instance to specified port.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param UdpConfigData Pointer to the buffer to receive the current configuration data.
+
+ @retval EFI_SUCCESS The configuration settings were set, changed, or reset successfully.
+ @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
+ RARP, etc.) is not finished yet.
+ @retval EFI_INVALID_PARAMETER One or more following conditions are TRUE:
+ @retval EFI_ALREADY_STARTED The EFI UDPv4 Protocol instance is already started/configured
+ and must be stopped/reset before it can be reconfigured.
+ @retval EFI_ACCESS_DENIED UdpConfigData. AllowDuplicatePort is FALSE
+ and UdpConfigData.StationPort is already used by
+ other instance.
+ @retval EFI_OUT_OF_RESOURCES The EFI UDPv4 Protocol driver cannot allocate memory for this
+ EFI UDPv4 Protocol instance.
+ @retval EFI_DEVICE_ERROR An unexpected network or system error occurred and this instance
+ was not opened.
**/
EFI_STATUS
@@ -305,30 +299,32 @@ ON_EXIT: /**
- This function is used to enable and disable the multicast group filtering.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param JoinFlag Set to TRUE to join a multicast group. Set to
- FALSE to leave one or all multicast groups.
- @param MulticastAddress Pointer to multicast group address to join or
- leave.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_NOT_STARTED The EFI UDPv4 Protocol instance has not been
- started.
- @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
- BOOTP, RARP, etc.) is not finished yet.
- @retval EFI_OUT_OF_RESOURCES Could not allocate resources to join the group.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL. JoinFlag is TRUE and
- MulticastAddress is NULL. JoinFlag is TRUE and
- *MulticastAddress is not a valid multicast
- address.
- @retval EFI_ALREADY_STARTED The group address is already in the group table
- (when JoinFlag is TRUE).
- @retval EFI_NOT_FOUND The group address is not in the group table (when
- JoinFlag is FALSE).
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
+ Joins and leaves multicast groups.
+
+ The Groups() function is used to enable and disable the multicast group
+ filtering. If the JoinFlag is FALSE and the MulticastAddress is NULL, then all
+ currently joined groups are left.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param JoinFlag Set to TRUE to join a multicast group. Set to FALSE to leave one
+ or all multicast groups.
+ @param MulticastAddress Pointer to multicast group address to join or leave.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_NOT_STARTED The EFI UDPv4 Protocol instance has not been started.
+ @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
+ RARP, etc.) is not finished yet.
+ @retval EFI_OUT_OF_RESOURCES Could not allocate resources to join the group.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ - This is NULL.
+ - JoinFlag is TRUE and MulticastAddress is NULL.
+ - JoinFlag is TRUE and *MulticastAddress is not
+ a valid multicast address.
+ @retval EFI_ALREADY_STARTED The group address is already in the group table (when
+ JoinFlag is TRUE).
+ @retval EFI_NOT_FOUND The group address is not in the group table (when JoinFlag is
+ FALSE).
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
**/
EFI_STATUS
@@ -385,7 +381,7 @@ Udp4Groups ( // Keep a local copy of the configured multicast IPs because IpIo receives
// datagrams from the 0 station address IP instance and then UDP delivers to
// the matched instance. This copy of multicast IPs is used to avoid receive
- // the mutlicast datagrams destinated to multicast IPs the other instances configured.
+ // the mutlicast datagrams destined to multicast IPs the other instances configured.
//
if (JoinFlag) {
@@ -404,31 +400,41 @@ ON_EXIT: /**
- This function adds a route to or deletes a route from the routing table.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param DeleteRoute Set to TRUE to delete this route from the routing
- table. Set to FALSE to add this route to the
- routing table.
- @param SubnetAddress The destination network address that needs to be
- routed.
- @param SubnetMask The subnet mask of SubnetAddress.
- @param GatewayAddress The gateway IP address for this route.
-
- @retval EFI_SUCCESS The operation completed successfully.
- @retval EFI_NOT_STARTED The EFI UDPv4 Protocol instance has not been
- started.
- @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
- BOOTP, RARP, etc.) is not finished yet.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL. SubnetAddress is NULL. SubnetMask is
- NULL. GatewayAddress is NULL. SubnetAddress is not
- a valid subnet address. SubnetMask is not a valid
- subnet mask. GatewayAddress is not a valid unicast
- IP address.
- @retval EFI_OUT_OF_RESOURCES Could not add the entry to the routing table.
- @retval EFI_NOT_FOUND This route is not in the routing table.
- @retval EFI_ACCESS_DENIED The route is already defined in the routing table.
+ Adds and deletes routing table entries.
+
+ The Routes() function adds a route to or deletes a route from the routing table.
+ Routes are determined by comparing the SubnetAddress with the destination IP
+ address and arithmetically AND-ing it with the SubnetMask. The gateway address
+ must be on the same subnet as the configured station address.
+ The default route is added with SubnetAddress and SubnetMask both set to 0.0.0.0.
+ The default route matches all destination IP addresses that do not match any
+ other routes.
+ A zero GatewayAddress is a nonroute. Packets are sent to the destination IP
+ address if it can be found in the Address Resolution Protocol (ARP) cache or
+ on the local subnet. One automatic nonroute entry will be inserted into the
+ routing table for outgoing packets that are addressed to a local subnet
+ (gateway address of 0.0.0.0).
+ Each instance of the EFI UDPv4 Protocol has its own independent routing table.
+ Instances of the EFI UDPv4 Protocol that use the default IP address will also
+ have copies of the routing table provided by the EFI_IP4_CONFIG_PROTOCOL. These
+ copies will be updated automatically whenever the IP driver reconfigures its
+ instances; as a result, the previous modification to these copies will be lost.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param DeleteRoute Set to TRUE to delete this route from the routing table.
+ Set to FALSE to add this route to the routing table.
+ @param SubnetAddress The destination network address that needs to be routed.
+ @param SubnetMask The subnet mask of SubnetAddress.
+ @param GatewayAddress The gateway IP address for this route.
+
+ @retval EFI_SUCCESS The operation completed successfully.
+ @retval EFI_NOT_STARTED The EFI UDPv4 Protocol instance has not been started.
+ @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
+ - RARP, etc.) is not finished yet.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_OUT_OF_RESOURCES Could not add the entry to the routing table.
+ @retval EFI_NOT_FOUND This route is not in the routing table.
+ @retval EFI_ACCESS_DENIED The route is already defined in the routing table.
**/
EFI_STATUS
@@ -468,44 +474,33 @@ Udp4Routes ( /**
- This function places a sending request to this instance of the EFI UDPv4 Protocol,
- alongside the transmit data that was filled by the user.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param Token Pointer to the completion token that will be
- placed into the transmit queue.
-
- @retval EFI_SUCCESS The data has been queued for transmission.
- @retval EFI_NOT_STARTED This EFI UDPv4 Protocol instance has not been
- started.
- @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
- BOOTP, RARP, etc.) is not finished yet.
- @retval EFI_INVALID_PARAMETER One or more of the following are TRUE: This is
- NULL. Token is NULL. Token.Event is NULL.
- Token.Packet.TxData is NULL.
- Token.Packet.TxData.FragmentCount is zero.
- Token.Packet.TxData.DataLength is not equal to the
- sum of fragment lengths. One or more of the
- Token.Packet.TxData.FragmentTable[].
- FragmentLength fields is zero. One or more of the
- Token.Packet.TxData.FragmentTable[].
- FragmentBuffer fields is NULL.
- Token.Packet.TxData. GatewayAddress is not a
- unicast IPv4 address if it is not NULL. One or
- more IPv4 addresses in Token.Packet.TxData.
- UdpSessionData are not valid unicast IPv4
- addresses if the UdpSessionData is not NULL.
- @retval EFI_ACCESS_DENIED The transmit completion token with the same
- Token.Event is already in the transmit queue.
- @retval EFI_NOT_READY The completion token could not be queued because
- the transmit queue is full.
- @retval EFI_OUT_OF_RESOURCES Could not queue the transmit data.
- @retval EFI_NOT_FOUND There is no route to the destination network or
- address.
- @retval EFI_BAD_BUFFER_SIZE The data length is greater than the maximum UDP
- packet size. Or the length of the IP header + UDP
- header + data length is greater than MTU if
- DoNotFragment is TRUE.
+ Queues outgoing data packets into the transmit queue.
+
+ The Transmit() function places a sending request to this instance of the EFI
+ UDPv4 Protocol, alongside the transmit data that was filled by the user. Whenever
+ the packet in the token is sent out or some errors occur, the Token.Event will
+ be signaled and Token.Status is updated. Providing a proper notification function
+ and context for the event will enable the user to receive the notification and
+ transmitting status.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param Token Pointer to the completion token that will be placed into the
+ transmit queue.
+
+ @retval EFI_SUCCESS The data has been queued for transmission.
+ @retval EFI_NOT_STARTED This EFI UDPv4 Protocol instance has not been started.
+ @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP,
+ RARP, etc.) is not finished yet.
+ @retval EFI_INVALID_PARAMETER One or more parameters are invalid.
+ @retval EFI_ACCESS_DENIED The transmit completion token with the same
+ Token.Event was already in the transmit queue.
+ @retval EFI_NOT_READY The completion token could not be queued because the
+ transmit queue is full.
+ @retval EFI_OUT_OF_RESOURCES Could not queue the transmit data.
+ @retval EFI_NOT_FOUND There is no route to the destination network or address.
+ @retval EFI_BAD_BUFFER_SIZE The data length is greater than the maximum UDP packet
+ size. Or the length of the IP header + UDP header + data
+ length is greater than MTU if DoNotFragment is TRUE.
**/
EFI_STATUS
@@ -704,30 +699,32 @@ ON_EXIT: /**
- This function places a completion token into the receive packet queue. This function
- is always asynchronous.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param Token Pointer to a token that is associated with the
- receive data descriptor.
-
- @retval EFI_SUCCESS The receive completion token is cached.
- @retval EFI_NOT_STARTED This EFI UDPv4 Protocol instance has not been
- started.
- @retval EFI_NO_MAPPING When using a default address, configuration (DHCP,
- BOOTP, RARP, etc.) is not finished yet.
- @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
- This is NULL. Token is NULL. Token.Event is NULL.
- @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued
- due to a lack of system resources (usually
- memory).
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
- The EFI UDPv4 Protocol instance has been reset to
- startup defaults.
- @retval EFI_ACCESS_DENIED A receive completion token with the same
- Token.Event is already in the receive queue.
- @retval EFI_NOT_READY The receive request could not be queued because
- the receive queue is full.
+ Places an asynchronous receive request into the receiving queue.
+
+ The Receive() function places a completion token into the receive packet queue.
+ This function is always asynchronous.
+ The caller must fill in the Token.Event field in the completion token, and this
+ field cannot be NULL. When the receive operation completes, the EFI UDPv4 Protocol
+ driver updates the Token.Status and Token.Packet.RxData fields and the Token.Event
+ is signaled. Providing a proper notification function and context for the event
+ will enable the user to receive the notification and receiving status. That
+ notification function is guaranteed to not be re-entered.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param Token Pointer to a token that is associated with the receive data
+ descriptor.
+
+ @retval EFI_SUCCESS The receive completion token was cached.
+ @retval EFI_NOT_STARTED This EFI UDPv4 Protocol instance has not been started.
+ @retval EFI_NO_MAPPING When using a default address, configuration (DHCP, BOOTP, RARP, etc.)
+ is not finished yet.
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is TRUE:
+ @retval EFI_OUT_OF_RESOURCES The receive completion token could not be queued due to a lack of system
+ resources (usually memory).
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
+ @retval EFI_ACCESS_DENIED A receive completion token with the same Token.Event was already in
+ the receive queue.
+ @retval EFI_NOT_READY The receive request could not be queued because the receive queue is full.
**/
EFI_STATUS
@@ -784,7 +781,7 @@ Udp4Receive ( Udp4ReportIcmpError (Instance);
//
- // Try to delivered the received datagrams.
+ // Try to deliver the received datagrams.
//
Udp4InstanceDeliverDgram (Instance);
@@ -802,25 +799,31 @@ ON_EXIT: /**
- This function is used to abort a pending transmit or receive request.
-
- @param This Pointer to the EFI_UDP4_PROTOCOL instance.
- @param Token Pointer to a token that has been issued by
- EFI_UDP4_PROTOCOL.Transmit() or
- EFI_UDP4_PROTOCOL.Receive().
-
- @retval EFI_SUCCESS The asynchronous I/O request is aborted and
- Token.Event is signaled. When Token is NULL, all
- pending requests are aborted and their events are
- signaled.
- @retval EFI_INVALID_PARAMETER This is NULL.
- @retval EFI_NOT_STARTED This instance has not been started.
- @retval EFI_NO_MAPPING When using the default address, configuration
- (DHCP, BOOTP, RARP, etc.) is not finished yet.
- @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O
- request is not found in the transmit or receive
- queue. It is either completed or not issued by
- Transmit() or Receive().
+ Aborts an asynchronous transmit or receive request.
+
+ The Cancel() function is used to abort a pending transmit or receive request.
+ If the token is in the transmit or receive request queues, after calling this
+ function, Token.Status will be set to EFI_ABORTED and then Token.Event will be
+ signaled. If the token is not in one of the queues, which usually means that
+ the asynchronous operation has completed, this function will not signal the
+ token and EFI_NOT_FOUND is returned.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+ @param Token Pointer to a token that has been issued by
+ EFI_UDP4_PROTOCOL.Transmit() or
+ EFI_UDP4_PROTOCOL.Receive().If NULL, all pending
+ tokens are aborted.
+
+ @retval EFI_SUCCESS The asynchronous I/O request was aborted and Token.Event
+ was signaled. When Token is NULL, all pending requests are
+ aborted and their events are signaled.
+ @retval EFI_INVALID_PARAMETER This is NULL.
+ @retval EFI_NOT_STARTED This instance has not been started.
+ @retval EFI_NO_MAPPING When using the default address, configuration (DHCP, BOOTP,
+ RARP, etc.) is not finished yet.
+ @retval EFI_NOT_FOUND When Token is not NULL, the asynchronous I/O request was
+ not found in the transmit or receive queue. It has either completed
+ or was not issued by Transmit() and Receive().
**/
EFI_STATUS
@@ -856,7 +859,7 @@ Udp4Cancel ( Status = Udp4InstanceCancelToken (Instance, Token);
//
- // Dispatch the DPC queued by the NotifyFunction of the canceled token's events.
+ // Dispatch the DPC queued by the NotifyFunction of the cancelled token's events.
//
NetLibDispatchDpc ();
@@ -867,16 +870,23 @@ Udp4Cancel ( /**
- This function can be used by network drivers and applications to increase the rate that
- data packets are moved between the communications device and the transmit/receive queues.
- Argumens:
- This - Pointer to the EFI_UDP4_PROTOCOL instance.
-
- @retval EFI_SUCCESS Incoming or outgoing data was processed.
- @retval EFI_INVALID_PARAMETER This is NULL.
- @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
- @retval EFI_TIMEOUT Data was dropped out of the transmit and/or
- receive queue.
+ Polls for incoming data packets and processes outgoing data packets.
+
+ The Poll() function can be used by network drivers and applications to increase
+ the rate that data packets are moved between the communications device and the
+ transmit and receive queues.
+ In some systems, the periodic timer event in the managed network driver may not
+ poll the underlying communications device fast enough to transmit and/or receive
+ all data packets without missing incoming packets or dropping outgoing packets.
+ Drivers and applications that are experiencing packet loss should try calling
+ the Poll() function more often.
+
+ @param This Pointer to the EFI_UDP4_PROTOCOL instance.
+
+ @retval EFI_SUCCESS Incoming or outgoing data was processed.
+ @retval EFI_INVALID_PARAMETER This is NULL.
+ @retval EFI_DEVICE_ERROR An unexpected system or network error occurred.
+ @retval EFI_TIMEOUT Data was dropped out of the transmit and/or receive queue.
**/
EFI_STATUS
|