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. + 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. + @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. + @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. + 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. + @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 + @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. + 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. - @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. + @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 pair found or not. + @retval TRUE The specified 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 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 - 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. + Reads the current operational settings. - @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. + 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. - @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. + @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. + 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 mode - data. + @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: 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. + @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. + 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. + @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. + @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. + 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. + @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. + @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. + 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. + @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. + @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. + 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. + @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. + @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. + 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(). + @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 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(). + @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. + 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. - @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. + @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