From 2ff2921247ab4cf5eaa6a0b0358a531e6bfacbcb Mon Sep 17 00:00:00 2001 From: jgong5 Date: Tue, 18 Nov 2008 09:29:44 +0000 Subject: [PATCH] synced function header git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@6595 6f19259b-4bc3-4df7-8a09-765794883524 --- .../Universal/Network/Ip4Dxe/Ip4Common.h | 134 ++++++++++++++++-- .../Universal/Network/Ip4Dxe/Ip4Driver.c | 13 ++ .../Universal/Network/Ip4Dxe/Ip4Driver.h | 109 +++++++++++++- .../Universal/Network/Ip4Dxe/Ip4Icmp.h | 21 ++- MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.c | 113 ++++++++++++--- MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.h | 114 ++++++++++++++- .../Universal/Network/Ip4Dxe/Ip4Igmp.h | 133 ++++++++++++++--- .../Universal/Network/Ip4Dxe/Ip4Impl.c | 5 +- .../Universal/Network/Ip4Dxe/Ip4Impl.h | 98 ++++++++++++- .../Universal/Network/Ip4Dxe/Ip4Input.h | 95 ++++++++++++- .../Universal/Network/Ip4Dxe/Ip4Option.h | 41 +++++- .../Universal/Network/Ip4Dxe/Ip4Output.h | 68 ++++++++- .../Universal/Network/Ip4Dxe/Ip4Route.h | 108 ++++++++++++-- 13 files changed, 954 insertions(+), 98 deletions(-) diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Common.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Common.h index 9142e1df42..553714e89b 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Common.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Common.h @@ -86,38 +86,111 @@ typedef enum { /// #define IP4_US_TO_SEC(Us) (((Us) + 999999) / 1000000) +/** + Return the cast type (Unicast/Boradcast) specific to an + interface. All the addresses are host byte ordered. + + @param IpAddr The IP address to classify in host byte order + @param IpIf The interface that IpAddr received from + + @return The cast type of this IP address specific to the interface. + @retval IP4_LOCAL_HOST The IpAddr equals to the interface's address + @retval IP4_SUBNET_BROADCAST The IpAddr is a directed subnet boradcast to the + interface + @retval IP4_NET_BROADCAST The IpAddr is a network broadcast to the interface + @retval 0 Otherwise. + +**/ INTN Ip4GetNetCast ( - IN IP4_ADDR IpAddr, - IN IP4_INTERFACE *IpIf + IN IP4_ADDR IpAddr, + IN IP4_INTERFACE *IpIf ); +/** + Find the cast type of the packet related to the local host. + This isn't the same as link layer cast type. For example, DHCP + server may send local broadcast to the local unicast MAC. + + @param IpSb The IP4 service binding instance that received the + packet + @param Dst The destination address in the packet (host byte + order) + @param Src The source address in the packet (host byte order) + + @return The cast type for the Dst, it will return on the first non-promiscuous + cast type to a configured interface. If the packet doesn't match any of + the interface, multicast address and local broadcast address are checked. + +**/ INTN Ip4GetHostCast ( - IN IP4_SERVICE *IpSb, - IN IP4_ADDR Dst, - IN IP4_ADDR Src + IN IP4_SERVICE *IpSb, + IN IP4_ADDR Dst, + IN IP4_ADDR Src ); +/** + Find an interface whose configured IP address is Ip. + + @param IpSb The IP4 service binding instance + @param Ip The Ip address (host byte order) to find + + @return The IP4_INTERFACE point if found, otherwise NULL + +**/ IP4_INTERFACE * Ip4FindInterface ( - IN IP4_SERVICE *IpService, - IN IP4_ADDR Addr + IN IP4_SERVICE *IpSb, + IN IP4_ADDR Ip ); +/** + Find an interface that Ip is on that connected network. + + @param IpSb The IP4 service binding instance + @param Ip The Ip address (host byte order) to find + + @return The IP4_INTERFACE point if found, otherwise NULL + +**/ IP4_INTERFACE * Ip4FindNet ( - IN IP4_SERVICE *IpService, - IN IP4_ADDR Addr + IN IP4_SERVICE *IpSb, + IN IP4_ADDR Ip ); +/** + Find an interface of the service with the same Ip/Netmask pair. + + @param IpSb Ip4 service binding instance + @param Ip The Ip adress to find (host byte order) + @param Netmask The network to find (host byte order) + + @return The IP4_INTERFACE point if found, otherwise NULL + +**/ IP4_INTERFACE * Ip4FindStationAddress ( - IN IP4_SERVICE *IpSb, - IN IP4_ADDR Ip, - IN IP4_ADDR Netmask + IN IP4_SERVICE *IpSb, + IN IP4_ADDR Ip, + IN IP4_ADDR Netmask ); +/** + Get the MAC address for a multicast IP address. Call + Mnp's McastIpToMac to find the MAC address in stead of + hard code the NIC to be Ethernet. + + @param Mnp The Mnp instance to get the MAC address. + @param Multicast The multicast IP address to translate. + @param Mac The buffer to hold the translated address. + + @retval EFI_SUCCESS if the multicast IP is successfully translated to a + multicast MAC address. + @retval other Otherwise some error. + +**/ EFI_STATUS Ip4GetMulticastMac ( IN EFI_MANAGED_NETWORK_PROTOCOL *Mnp, @@ -125,19 +198,50 @@ Ip4GetMulticastMac ( OUT EFI_MAC_ADDRESS *Mac ); +/** + Convert the multibyte field in IP header's byter order. + In spite of its name, it can also be used to convert from + host to network byte order. + + @param Head The IP head to convert + + @return Point to the converted IP head + +**/ IP4_HEAD * Ip4NtohHead ( - IN IP4_HEAD *Head + IN IP4_HEAD *Head ); +/** + Set the Ip4 variable data. + + Save the list of all of the IPv4 addresses and subnet masks that are currently + being used to volatile variable storage. + + @param IpSb Ip4 service binding instance + + @retval EFI_SUCCESS Successfully set variable. + @retval EFI_OUT_OF_RESOURCES There are not enough resources to set the variable. + @retval other Set variable failed. + +**/ EFI_STATUS Ip4SetVariableData ( - IN IP4_SERVICE *IpSb + IN IP4_SERVICE *IpSb ); +/** + Clear the variable and free the resource. + + @param IpSb Ip4 service binding instance + + @return None. + +**/ VOID Ip4ClearVariableData ( - IN IP4_SERVICE *IpSb + IN IP4_SERVICE *IpSb ); #endif diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.c b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.c index f36394a009..a43145e162 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.c +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.c @@ -122,6 +122,19 @@ Ip4DriverBindingSupported ( return Status; } +/** + Clean up a IP4 service binding instance. It will release all + the resource allocated by the instance. The instance may be + partly initialized, or partly destroyed. If a resource is + destroyed, it is marked as that in case the destory failed and + being called again later. + + @param IpSb The IP4 serviceing binding instance to clean up + + @retval EFI_SUCCESS The resource used by the instance are cleaned up + @retval other Failed to clean up some of the resources. + +**/ EFI_STATUS Ip4CleanService ( IN IP4_SERVICE *IpSb diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.h index 6ff56f0e94..4d5cbe68f6 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Driver.h @@ -31,6 +31,21 @@ extern EFI_COMPONENT_NAME2_PROTOCOL gIp4ComponentName2; // // Function prototype for the driver's entry point // +/** + 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 IP4 driver which install the driver + binding and component name protocol on its image. + + @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 Ip4DriverEntryPoint ( @@ -41,22 +56,76 @@ Ip4DriverEntryPoint ( // // Function prototypes for the Drivr Binding Protocol // +/** + 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 EFIAPI Ip4DriverBindingSupported ( - IN EFI_DRIVER_BINDING_PROTOCOL *This, + IN EFI_DRIVER_BINDING_PROTOCOL * This, IN EFI_HANDLE ControllerHandle, - IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL + IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL ); +/** + 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 EFIAPI Ip4DriverBindingStart ( - IN EFI_DRIVER_BINDING_PROTOCOL *This, + IN EFI_DRIVER_BINDING_PROTOCOL * This, IN EFI_HANDLE ControllerHandle, - IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL + IN EFI_DEVICE_PATH_PROTOCOL * RemainingDevicePath OPTIONAL ); +/** + 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 EFIAPI Ip4DriverBindingStop ( @@ -69,13 +138,43 @@ Ip4DriverBindingStop ( // // Function ptototypes for the ServiceBinding Prococol // +/** + 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. + + @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 EFIAPI Ip4ServiceBindingCreateChild ( IN EFI_SERVICE_BINDING_PROTOCOL *This, - IN EFI_HANDLE *ChildHandle + IN OUT EFI_HANDLE *ChildHandle ); +/** + Destroys a child handle with a set of I/O services. + + @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 + +**/ EFI_STATUS EFIAPI Ip4ServiceBindingDestroyChild ( diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Icmp.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Icmp.h index 0246f9c042..5b7b1a67b3 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Icmp.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Icmp.h @@ -90,10 +90,25 @@ typedef struct { extern IP4_ICMP_CLASS mIcmpClass[]; extern EFI_IP4_ICMP_TYPE mIp4SupportedIcmp[]; +/** + Handle the ICMP packet. First validate the message format, + then according to the message types, process it as query or + error packet. + + @param IpSb The IP service that receivd the packet + @param Head The IP head of the ICMP query packet + @param Packet The content of the ICMP query with IP head + removed. + + @retval EFI_INVALID_PARAMETER The packet is malformated. + @retval EFI_SUCCESS The ICMP message is successfully processed. + @retval Others Failed to handle ICMP packet. + +**/ EFI_STATUS Ip4IcmpHandle ( - IN IP4_SERVICE *IpSb, - IN IP4_HEAD *Header, - IN NET_BUF *Packet + IN IP4_SERVICE *IpSb, + IN IP4_HEAD *Head, + IN NET_BUF *Packet ); #endif diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.c b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.c index dfd58406c2..1a47fa9478 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.c +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.c @@ -29,25 +29,64 @@ Abstract: // EFI_MAC_ADDRESS mZeroMacAddress; +/** + Callback funtion when frame transmission is finished. It will + call the frame owner's callback function to tell it the result. + + @param Context Context which is point to the token. + + @return None. + +**/ VOID EFIAPI Ip4OnFrameSentDpc ( - IN VOID *Context + IN VOID *Context ); +/** + Request Ip4OnFrameSentDpc as a DPC at TPL_CALLBACK. + + @param Event The transmit token's event. + @param Context Context which is point to the token. + + @return None + +**/ VOID EFIAPI Ip4OnFrameSent ( - IN EFI_EVENT Event, - IN VOID *Context + IN EFI_EVENT Event, + IN VOID *Context ); +/** + Callback function when ARP request are finished. It will cancelled + all the queued frame if the ARP requests failed. Or transmit them + if the request succeed. + + @param Context The context of the callback, a point to the ARP + queue + + @return None + +**/ VOID EFIAPI Ip4OnArpResolvedDpc ( IN VOID *Context ); +/** + Request Ip4OnArpResolvedDpc as a DPC at TPL_CALLBACK. + + @param Event The Arp request event. + @param Context The context of the callback, a point to the ARP + queue. + + @return None + +**/ VOID EFIAPI Ip4OnArpResolved ( @@ -55,19 +94,55 @@ Ip4OnArpResolved ( IN VOID *Context ); +/** + Received a frame from MNP, wrap it in net buffer then deliver + it to IP's input function. The ownship of the packet also + transferred to IP. When Ip is finished with this packet, it + will call NetbufFree to release the packet, NetbufFree will + again call the Ip4RecycleFrame to signal MNP's event and free + the token used. + + @param Context Context for the callback. + + @return None. + +**/ VOID EFIAPI Ip4OnFrameReceivedDpc ( - IN VOID *Context + IN VOID *Context ); +/** + + Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK. + + @param Event The receive event delivered to MNP for receive. + @param Context Context for the callback. + + @return None. + +**/ VOID EFIAPI Ip4OnFrameReceived ( - IN EFI_EVENT Event, - IN VOID *Context + IN EFI_EVENT Event, + IN VOID *Context ); +/** + Remove all the frames on the ARP queue that pass the FrameToCancel, + that is, either FrameToCancel is NULL or it returns true for the frame. + + @param ArpQue ARP frame to remove the frames from. + @param IoStatus The status returned to the cancelled frames' + callback function. + @param FrameToCancel Function to select which frame to cancel. + @param Context Opaque parameter to the FrameToCancel. + + @return NONE + +**/ VOID Ip4CancelFrameArp ( IN IP4_ARP_QUE *ArpQue, @@ -1142,28 +1217,22 @@ Ip4OnFrameReceivedDpc ( Token->CallBack (Token->IpInstance, Packet, EFI_SUCCESS, Flag, Token->Context); } +/** + + Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK. + + @param Event The receive event delivered to MNP for receive. + @param Context Context for the callback. + + @return None. + +**/ VOID EFIAPI Ip4OnFrameReceived ( IN EFI_EVENT Event, IN VOID *Context ) -/*++ - -Routine Description: - - Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK - -Arguments: - - Event - The receive event delivered to MNP for receive. - Context - Context for the callback. - -Returns: - - None. - ---*/ { // // Request Ip4OnFrameReceivedDpc as a DPC at TPL_CALLBACK diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.h index d02e7d1d6e..8c06cfc55b 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4If.h @@ -198,6 +198,19 @@ struct _IP4_INTERFACE { BOOLEAN PromiscRecv; }; +/** + Create an IP4_INTERFACE. Delay the creation of ARP instance until + the interface is configured. + + @param Mnp The shared MNP child of this IP4 service binding + instance + @param Controller The controller this IP4 service binding instance + is installed. Most like the UNDI handle. + @param ImageHandle This driver's image handle + + @return Point to the created IP4_INTERFACE, otherwise NULL. + +**/ IP4_INTERFACE * Ip4CreateInterface ( IN EFI_MANAGED_NETWORK_PROTOCOL *Mnp, @@ -205,19 +218,68 @@ Ip4CreateInterface ( IN EFI_HANDLE ImageHandle ); +/** + Set the interface's address, create and configure + the ARP child if necessary. + + @param Interface The interface to set the address + @param IpAddr The interface's IP address + @param SubnetMask The interface's netmask + + @retval EFI_SUCCESS The interface is configured with Ip/netmask pair, + and a ARP is created for it. + @retval Others Failed to set the interface's address. + +**/ EFI_STATUS Ip4SetAddress ( - IN IP4_INTERFACE *Interface, - IN IP4_ADDR IpAddr, - IN IP4_ADDR SubnetMask + IN OUT IP4_INTERFACE *Interface, + IN IP4_ADDR IpAddr, + IN IP4_ADDR SubnetMask ); +/** + Free the interface used by IpInstance. All the IP instance with + the same Ip/Netmask pair share the same interface. It is reference + counted. All the frames haven't been sent will be cancelled. + Because the IpInstance is optional, the caller must remove + IpInstance from the interface's instance list itself. + + @param Interface The interface used by the IpInstance + @param IpInstance The Ip instance that free the interface. NULL if + the Ip driver is releasing the default interface. + + @retval EFI_SUCCESS The interface use IpInstance is freed. + +**/ EFI_STATUS Ip4FreeInterface ( IN IP4_INTERFACE *Interface, - IN IP4_PROTOCOL *IpInstance OPTIONAL + IN IP4_PROTOCOL *IpInstance OPTIONAL ); +/** + Send a frame from the interface. If the next hop is broadcast or + multicast address, it is transmitted immediately. If the next hop + is a unicast, it will consult ARP to resolve the NextHop's MAC. + If some error happened, the CallBack won't be called. So, the caller + must test the return value, and take action when there is an error. + + @param Interface The interface to send the frame from + @param IpInstance The IP child that request the transmission. NULL + if it is the IP4 driver itself. + @param Packet The packet to transmit. + @param NextHop The immediate destination to transmit the packet + to. + @param CallBack Function to call back when transmit finished. + @param Context Opaque parameter to the call back. + + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource to send the frame + @retval EFI_NO_MAPPING Can't resolve the MAC for the nexthop + @retval EFI_SUCCESS The packet is successfully transmitted. + @retval other Other error occurs. + +**/ EFI_STATUS Ip4SendFrame ( IN IP4_INTERFACE *Interface, @@ -228,6 +290,21 @@ Ip4SendFrame ( IN VOID *Context ); +/** + Remove all the frames on the interface that pass the FrameToCancel, + either queued on ARP queues or that have already been delivered to + MNP and not yet recycled. + + @param Interface Interface to remove the frames from + @param IoStatus The transmit status returned to the frames' + callback + @param FrameToCancel Function to select the frame to cancel, NULL to + select all + @param Context Opaque parameters passed to FrameToCancel + + @return NONE + +**/ VOID Ip4CancelFrames ( IN IP4_INTERFACE *Interface, @@ -236,11 +313,40 @@ Ip4CancelFrames ( IN VOID *Context ); +/** + If there is a pending receive request, cancel it. Don't call + the receive request's callback because this function can be only + called if the instance or driver is tearing itself down. It + doesn't make sense to call it back. But it is necessary to call + the transmit token's callback to give it a chance to free the + packet and update the upper layer's transmit request status, say + that from the UDP. + + @param Interface The interface used by the IpInstance + + @return None + +**/ VOID Ip4CancelReceive ( IN IP4_INTERFACE *Interface ); +/** + Request to receive the packet from the interface. + + @param Interface The interface to receive the frames from + @param IpInstance The instance that requests the receive. NULL for + the driver itself. + @param CallBack Function to call when receive finished. + @param Context Opaque parameter to the callback + + @retval EFI_ALREADY_STARTED There is already a pending receive request. + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource to receive + @retval EFI_SUCCESS The recieve request has been started. + @retval other Other error occurs. + +**/ EFI_STATUS Ip4ReceiveFrame ( IN IP4_INTERFACE *Interface, diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Igmp.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Igmp.h index 6c48d6aca8..7dd75740e7 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Igmp.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Igmp.h @@ -69,52 +69,151 @@ typedef enum { IGMP_UNSOLICIATED_REPORT = 10 } IGMP_ENUM_TYPES; +/** + Init the IGMP control data of the IP4 service instance, configure + MNP to receive ALL SYSTEM multicast. + + @param IpSb The IP4 service whose IGMP is to be initialized. + + @retval EFI_SUCCESS IGMP of the IpSb is successfully initialized. + @retval EFI_OUT_OF_RESOURCES Failed to allocate resource to initialize IGMP. + @retval Others Failed to initialize the IGMP of IpSb. + +**/ EFI_STATUS Ip4InitIgmp ( - IN IP4_SERVICE *IpService + IN OUT IP4_SERVICE *IpSb ); +/** + Join the multicast group on behalf of this IP4 child + + @param IpInstance The IP4 child that wants to join the group + @param Address The group to join + + @retval EFI_SUCCESS Successfully join the multicast group + @retval EFI_OUT_OF_RESOURCES Failed to allocate resources + @retval Others Failed to join the multicast group. + +**/ EFI_STATUS Ip4JoinGroup ( - IN IP4_PROTOCOL *IpInstance, - IN IP4_ADDR Address + IN IP4_PROTOCOL *IpInstance, + IN IP4_ADDR Address ); +/** + Leave the IP4 multicast group on behalf of IpInstance. + + @param IpInstance The IP4 child that wants to leave the group + address + @param Address The group address to leave + + @retval EFI_NOT_FOUND The IP4 service instance isn't in the group + @retval EFI_SUCCESS Successfully leave the multicast group. + @retval Others Failed to leave the multicast group. + +**/ EFI_STATUS Ip4LeaveGroup ( - IN IP4_PROTOCOL *IpInstance, - IN IP4_ADDR Address + IN IP4_PROTOCOL *IpInstance, + IN IP4_ADDR Address ); +/** + Handle the received IGMP message for the IP4 service instance. + + @param IpSb The IP4 service instance that received the message + @param Head The IP4 header of the received message + @param Packet The IGMP message, without IP4 header + + @retval EFI_INVALID_PARAMETER The IGMP message is malformated. + @retval EFI_SUCCESS The IGMP message is successfully processed. + +**/ EFI_STATUS Ip4IgmpHandle ( - IN IP4_SERVICE *IpService, - IN IP4_HEAD *Head, - IN NET_BUF *Packet + IN IP4_SERVICE *IpSb, + IN IP4_HEAD *Head, + IN NET_BUF *Packet ); +/** + The periodical timer function for IGMP. It does the following + things: + 1. Decrease the Igmpv1QuerySeen to make it possible to refresh + the IGMP server type. + 2. Decrease the report timer for each IGMP group in "delaying + member" state. + + @param IpSb The IP4 service instance that is ticking + + @return None + +**/ VOID Ip4IgmpTicking ( - IN IP4_SERVICE *IpService + IN IP4_SERVICE *IpSb ); +/** + Add a group address to the array of group addresses. + The caller should make sure that no duplicated address + existed in the array. Although the function doesn't + assume the byte order of the both Source and Addr, the + network byte order is used by the caller. + + @param Source The array of group addresses to add to + @param Count The number of group addresses in the Source + @param Addr The IP4 multicast address to add + + @return NULL if failed to allocate memory for the new groups, + otherwise the new combined group addresses. + +**/ IP4_ADDR * Ip4CombineGroups ( - IN IP4_ADDR *SourceGroups, - IN UINT32 Count, - IN IP4_ADDR Addr + IN IP4_ADDR *Source, + IN UINT32 Count, + IN IP4_ADDR Addr ); +/** + Remove a group address from the array of group addresses. + Although the function doesn't assume the byte order of the + both Groups and Addr, the network byte order is used by + the caller. + + @param Groups The array of group addresses to remove from + @param Count The number of group addresses in the Groups + @param Addr The IP4 multicast address to remove + + @return The nubmer of group addresses in the Groups after remove. + It is Count if the Addr isn't in the Groups. + +**/ INTN Ip4RemoveGroupAddr ( - IN IP4_ADDR *Group, - IN UINT32 GroupCnt, - IN IP4_ADDR Addr + IN OUT IP4_ADDR *Groups, + IN UINT32 Count, + IN IP4_ADDR Addr ); +/** + Find the IGMP_GROUP structure which contains the status of multicast + group Address in this IGMP control block + + @param IgmpCtrl The IGMP control block to search from + @param Address The multicast address to search + + @return NULL if the multicast address isn't in the IGMP control block. Otherwise + the point to the IGMP_GROUP which contains the status of multicast group + for Address. + +**/ IGMP_GROUP * Ip4FindGroup ( - IN IGMP_SERVICE_DATA *IgmpCtrl, - IN IP4_ADDR Address + IN IGMP_SERVICE_DATA *IgmpCtrl, + IN IP4_ADDR Address ); #endif diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.c b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.c index 2026bcc7d4..8017932e7f 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.c +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.c @@ -691,7 +691,8 @@ ON_EXIT: gBS->FreePool (Data); } -/*++ +/** + Request Ip4AutoConfigCallBackDpc as a DPC at TPL_CALLBACK. @param Event The event that is signalled. @@ -699,7 +700,7 @@ ON_EXIT: @return None. -++*/ +**/ VOID EFIAPI Ip4AutoConfigCallBack ( diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.h index 3f19167631..08ca3708dd 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Impl.h @@ -216,36 +216,112 @@ struct _IP4_SERVICE { extern EFI_IP4_PROTOCOL mEfiIp4ProtocolTemplete; +/** + Config the MNP parameter used by IP. The IP driver use one MNP + child to transmit/receive frames. By default, it configures MNP + to receive unicast/multicast/broadcast. And it will enable/disable + the promiscous receive according to whether there is IP child + enable that or not. If Force is FALSE, it will iterate through + all the IP children to check whether the promiscuous receive + setting has been changed. If it hasn't been changed, it won't + reconfigure the MNP. If Force is TRUE, the MNP is configured no + matter whether that is changed or not. + + @param IpSb The IP4 service instance that is to be changed. + @param Force Force the configuration or not. + + @retval EFI_SUCCESS The MNP is successfully configured/reconfigured. + @retval Others Configuration failed. + +**/ EFI_STATUS Ip4ServiceConfigMnp ( IN IP4_SERVICE *IpSb, IN BOOLEAN Force ); +/** + Intiialize the IP4_PROTOCOL structure to the unconfigured states. + + @param IpSb The IP4 service instance. + @param IpInstance The IP4 child instance. + + @return None + +**/ VOID Ip4InitProtocol ( - IN IP4_SERVICE *IpSb, - IN IP4_PROTOCOL *IpInstance + IN IP4_SERVICE *IpSb, + IN OUT IP4_PROTOCOL *IpInstance ); +/** + Clean up the IP4 child, release all the resources used by it. + + @param IpInstance The IP4 child to clean up. + + @retval EFI_SUCCESS The IP4 child is cleaned up + @retval EFI_DEVICE_ERROR Some resources failed to be released + +**/ EFI_STATUS Ip4CleanProtocol ( IN IP4_PROTOCOL *IpInstance ); +/** + Cancel the user's receive/transmit request. + + @param IpInstance The IP4 child + @param Token The token to cancel. If NULL, all token will be + cancelled. + + @retval EFI_SUCCESS The token is cancelled + @retval EFI_NOT_FOUND The token isn't found on either the + transmit/receive queue + @retval EFI_DEVICE_ERROR Not all token is cancelled when Token is NULL. + +**/ EFI_STATUS Ip4Cancel ( IN IP4_PROTOCOL *IpInstance, - IN EFI_IP4_COMPLETION_TOKEN *Token + IN EFI_IP4_COMPLETION_TOKEN *Token OPTIONAL ); +/** + Change the IP4 child's multicast setting. The caller + should make sure that the parameters is valid. + + @param IpInstance The IP4 child to change the setting. + @param JoinFlag TRUE to join the group, otherwise leave it + @param GroupAddress The target group address + + @retval EFI_ALREADY_STARTED Want to join the group, but already a member of it + @retval EFI_OUT_OF_RESOURCES Failed to allocate some resources. + @retval EFI_DEVICE_ERROR Failed to set the group configuraton + @retval EFI_SUCCESS Successfully updated the group setting. + @retval EFI_NOT_FOUND Try to leave the group which it isn't a member. + +**/ EFI_STATUS Ip4Groups ( IN IP4_PROTOCOL *IpInstance, IN BOOLEAN JoinFlag, - IN EFI_IPv4_ADDRESS *GroupAddress + IN EFI_IPv4_ADDRESS *GroupAddress OPTIONAL ); +/** + The heart beat timer of IP4 service instance. It times out + all of its IP4 children's received-but-not-delivered and + transmitted-but-not-recycle packets, and provides time input + for its IGMP protocol. + + @param Event The IP4 service instance's heart beat timer. + @param Context The IP4 service instance. + + @return None + +**/ VOID EFIAPI Ip4TimerTicking ( @@ -253,6 +329,20 @@ Ip4TimerTicking ( IN VOID *Context ); +/** + Decrease the life of the transmitted packets. If it is + decreased to zero, cancel the packet. This function is + called by Ip4PacketTimerTicking which time out both the + received-but-not-delivered and transmitted-but-not-recycle + packets. + + @param Map The IP4 child's transmit map. + @param Item Current transmitted packet + @param Context Not used. + + @retval EFI_SUCCESS Always returns EFI_SUCCESS + +**/ EFI_STATUS Ip4SentPacketTicking ( IN NET_MAP *Map, diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Input.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Input.h index fcbfb01699..43833af8c4 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Input.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Input.h @@ -91,16 +91,49 @@ typedef struct { #define IP4_RXDATA_WRAP_SIZE(NumFrag) \ (sizeof (IP4_RXDATA_WRAP) + sizeof (EFI_IP4_FRAGMENT_DATA) * ((NumFrag) - 1)) +/** + Initialize an already allocated assemble table. This is generally + the assemble table embedded in the IP4 service instance. + + @param Table The assemble table to initialize. + + @return NONE + +**/ VOID Ip4InitAssembleTable ( - IN IP4_ASSEMBLE_TABLE *Table + IN OUT IP4_ASSEMBLE_TABLE *Table ); +/** + Clean up the assemble table: remove all the fragments + and assemble entries. + + @param Table The assemble table to clean up + + @return None + +**/ VOID Ip4CleanAssembleTable ( IN IP4_ASSEMBLE_TABLE *Table ); +/** + The IP4 input routine. It is called by the IP4_INTERFACE when a + IP4 fragment is received from MNP. + + @param Ip4Instance The IP4 child that request the receive, most like + it is NULL. + @param Packet The IP4 packet received. + @param IoStatus The return status of receive request. + @param Flag The link layer flag for the packet received, such + as multicast. + @param Context The IP4 service instance that own the MNP. + + @return None + +**/ VOID Ip4AccpetFrame ( IN IP4_PROTOCOL *Ip4Instance, @@ -110,26 +143,78 @@ Ip4AccpetFrame ( IN VOID *Context ); +/** + Demultiple the packet. the packet delivery is processed in two + passes. The first pass will enque a shared copy of the packet + to each IP4 child that accepts the packet. The second pass will + deliver a non-shared copy of the packet to each IP4 child that + has pending receive requests. Data is copied if more than one + child wants to consume the packet because each IP child needs + its own copy of the packet to make changes. + + @param IpSb The IP4 service instance that received the packet + @param Head The header of the received packet + @param Packet The data of the received packet + + @retval EFI_NOT_FOUND No IP child accepts the packet + @retval EFI_SUCCESS The packet is enqueued or delivered to some IP + children. + +**/ EFI_STATUS Ip4Demultiplex ( - IN IP4_SERVICE *SbInstance, + IN IP4_SERVICE *IpSb, IN IP4_HEAD *Head, IN NET_BUF *Packet ); +/** + Enqueue a received packet to all the IP children that share + the same interface. + + @param IpSb The IP4 service instance that receive the packet + @param Head The header of the received packet + @param Packet The data of the received packet + @param IpIf The interface to enqueue the packet to + + @return The number of the IP4 children that accepts the packet + +**/ INTN Ip4InterfaceEnquePacket ( - IN IP4_SERVICE *SbInstance, + IN IP4_SERVICE *IpSb, IN IP4_HEAD *Head, IN NET_BUF *Packet, - IN IP4_INTERFACE *Interface + IN IP4_INTERFACE *IpIf ); +/** + Deliver the received packets to upper layer if there are both received + requests and enqueued packets. If the enqueued packet is shared, it will + duplicate it to a non-shared packet, release the shared packet, then + deliver the non-shared packet up. + + @param IpInstance The IP child to deliver the packet up. + + @retval EFI_OUT_OF_RESOURCES Failed to allocate resources to deliver the + packets. + @retval EFI_SUCCESS All the enqueued packets that can be delivered + are delivered up. + +**/ EFI_STATUS Ip4InstanceDeliverPacket ( - IN IP4_PROTOCOL *Ip4Instance + IN IP4_PROTOCOL *IpInstance ); +/** + Timeout the fragment and enqueued packets. + + @param IpSb The IP4 service instance to timeout + + @return None + +**/ VOID Ip4PacketTimerTicking ( IN IP4_SERVICE *IpSb diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Option.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Option.h index fa173fb086..546bf8ca6d 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Option.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Option.h @@ -34,19 +34,50 @@ typedef enum { IP4_OPTION_COPY_MASK = 0x80 } IP4_OPTION_ENUM_TYPES; +/** + Validate the IP4 option format for both the packets we received + and will transmit. It will compute the ICMP error message fields + if the option is mal-formated. But this information isn't used. + + @param Option The first byte of the option + @param OptionLen The length of the whole option + @param Rcvd The option is from the packet we received if TRUE, + otherwise the option we wants to transmit. + + @retval TRUE The option is properly formatted + @retval FALSE The option is mal-formated + +**/ BOOLEAN Ip4OptionIsValid ( IN UINT8 *Option, - IN UINT32 OptLen, + IN UINT32 OptionLen, IN BOOLEAN Rcvd ); +/** + Copy the option from the original option to buffer. It + handles the details such as: + 1. whether copy the single IP4 option to the first/non-first + fragments. + 2. Pad the options copied over to aligned to 4 bytes. + + @param Option The original option to copy from + @param OptionLen The length of the original option + @param FirstFragment Whether it is the first fragment + @param Buf The buffer to copy options to. NULL + @param BufLen The length of the buffer + + @retval EFI_SUCCESS The options are copied over + @retval EFI_BUFFER_TOO_SMALL Buf is NULL or BufLen provided is too small. + +**/ EFI_STATUS Ip4CopyOption ( - IN UINT8 *Option, - IN UINT32 OptLen, - IN BOOLEAN Fragment, - IN UINT8 *Buf, OPTIONAL + IN UINT8 *Option, + IN UINT32 OptionLen, + IN BOOLEAN FirstFragment, + IN OUT UINT8 *Buf, OPTIONAL IN OUT UINT32 *BufLen ); #endif diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Output.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Output.h index 991f10cbc0..8e64446461 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Output.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Output.h @@ -21,20 +21,66 @@ Abstract: #ifndef __EFI_IP4_OUTPUT_H__ #define __EFI_IP4_OUTPUT_H__ +/** + The default callback function for system generated packet. + It will free the packet. + + @param Ip4Instance The IP4 child that issued the transmission. It most + like is NULL. + @param Packet The packet that transmitted. + @param IoStatus The result of the transmission, succeeded or failed. + @param LinkFlag Not used when transmission. check IP4_FRAME_CALLBACK + for reference. + @param Context The context provided by us + + @return None + +**/ VOID Ip4SysPacketSent ( IP4_PROTOCOL *Ip4Instance, NET_BUF *Packet, EFI_STATUS IoStatus, - UINT32 Flag, + UINT32 LinkFlag, VOID *Context ); +/** + Transmit an IP4 packet. The packet comes either from the IP4 + child's consumer (IpInstance != NULL) or the IP4 driver itself + (IpInstance == NULL). It will route the packet, fragment it, + then transmit all the fragments through some interface. + + @param IpSb The IP4 service instance to transmit the packet + @param IpInstance The IP4 child that issues the transmission. It is + NULL if the packet is from the system. + @param Packet The user data to send, excluding the IP header. + @param Head The caller supplied header. The caller should set + the following header fields: Tos, TotalLen, Id, tl, + Fragment, Protocol, Src and Dst. All the fields are + in host byte order. This function will fill in the + Ver, HeadLen, Fragment, and checksum. The Fragment + only need to include the DF flag. Ip4Output will + compute the MF and offset for you. + @param Option The original option to append to the IP headers + @param OptLen The length of the option + @param GateWay The next hop address to transmit packet to. + 255.255.255.255 means broadcast. + @param Callback The callback function to issue when transmission + completed. + @param Context The opaque context for the callback + + @retval EFI_NO_MAPPING There is no interface to the destination. + @retval EFI_NOT_FOUND There is no route to the destination + @retval EFI_SUCCESS The packet is successfully transmitted. + @retval Others Failed to transmit the packet. + +**/ EFI_STATUS Ip4Output ( IN IP4_SERVICE *IpSb, - IN IP4_PROTOCOL *IpInstance, OPTIONAL - IN NET_BUF *Data, + IN IP4_PROTOCOL *IpInstance, OPTIONAL + IN NET_BUF *Packet, IN IP4_HEAD *Head, IN UINT8 *Option, IN UINT32 OptLen, @@ -43,11 +89,21 @@ Ip4Output ( IN VOID *Context ); +/** + Cancel the Packet and all its fragments. + + @param IpIf The interface from which the Packet is sent + @param Packet The Packet to cancel + @param IoStatus The status returns to the sender. + + @return None + +**/ VOID Ip4CancelPacket ( - IN IP4_INTERFACE *IpIf, - IN NET_BUF *Packet, - IN EFI_STATUS IoStatus + IN IP4_INTERFACE *IpIf, + IN NET_BUF *Packet, + IN EFI_STATUS IoStatus ); extern UINT16 mIp4Id; diff --git a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Route.h b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Route.h index bc396f94b4..5ba2b578ef 100644 --- a/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Route.h +++ b/MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Route.h @@ -99,32 +99,89 @@ struct _IP4_ROUTE_TABLE { IP4_ROUTE_CACHE Cache; }; -IP4_ROUTE_TABLE* +/** + Create an empty route table, includes its internal route cache + + @return NULL if failed to allocate memory for the route table, otherwise + the point to newly created route table. + +**/ +IP4_ROUTE_TABLE * Ip4CreateRouteTable ( VOID ); +/** + Free the route table and its associated route cache. Route + table is reference counted. + + @param RtTable The route table to free. + + @return None + +**/ VOID Ip4FreeRouteTable ( - IN IP4_ROUTE_TABLE *RouteTable + IN IP4_ROUTE_TABLE *RtTable ); +/** + Add a route entry to the route table. All the IP4_ADDRs are in + host byte order. + + @param RtTable Route table to add route to + @param Dest The destination of the network + @param Netmask The netmask of the destination + @param Gateway The next hop address + + @retval EFI_ACCESS_DENIED The same route already exists + @retval EFI_OUT_OF_RESOURCES Failed to allocate memory for the entry + @retval EFI_SUCCESS The route is added successfully. + +**/ EFI_STATUS Ip4AddRoute ( - IN IP4_ROUTE_TABLE *RtTable, - IN IP4_ADDR Dest, - IN IP4_ADDR Netmask, - IN IP4_ADDR Gateway + IN OUT IP4_ROUTE_TABLE *RtTable, + IN IP4_ADDR Dest, + IN IP4_ADDR Netmask, + IN IP4_ADDR Gateway ); +/** + Remove a route entry and all the route caches spawn from it. + + @param RtTable The route table to remove the route from + @param Dest The destination network + @param Netmask The netmask of the Dest + @param Gateway The next hop address + + @retval EFI_SUCCESS The route entry is successfully removed + @retval EFI_NOT_FOUND There is no route entry in the table with that + properity. + +**/ EFI_STATUS Ip4DelRoute ( - IN IP4_ROUTE_TABLE *RtTable, - IN IP4_ADDR Dest, - IN IP4_ADDR Netmask, - IN IP4_ADDR Gateway + IN OUT IP4_ROUTE_TABLE *RtTable, + IN IP4_ADDR Dest, + IN IP4_ADDR Netmask, + IN IP4_ADDR Gateway ); +/** + Find a route cache with the dst and src. This is used by ICMP + redirect messasge process. All kinds of redirect is treated as + host redirect according to RFC1122. So, only route cache entries + are modified according to the ICMP redirect message. + + @param RtTable The route table to search the cache for + @param Dest The destination address + @param Src The source address + + @return NULL if no route entry to the (Dest, Src). Otherwise the point + to the correct route cache entry. + +**/ IP4_ROUTE_CACHE_ENTRY * Ip4FindRouteCache ( IN IP4_ROUTE_TABLE *RtTable, @@ -132,11 +189,31 @@ Ip4FindRouteCache ( IN IP4_ADDR Src ); +/** + Free the route cache entry. It is reference counted. + + @param RtCacheEntry The route cache entry to free. + + @return None + +**/ VOID Ip4FreeRouteCacheEntry ( IN IP4_ROUTE_CACHE_ENTRY *RtCacheEntry ); +/** + Search the route table to route the packet. Return/create a route + cache if there is a route to the destination. + + @param RtTable The route table to search from + @param Dest The destination address to search for + @param Src The source address to search for + + @return NULL if failed to route packet, otherwise a route cache + entry that can be used to route packet. + +**/ IP4_ROUTE_CACHE_ENTRY * Ip4Route ( IN IP4_ROUTE_TABLE *RtTable, @@ -144,6 +221,17 @@ Ip4Route ( IN IP4_ADDR Src ); +/** + Build a EFI_IP4_ROUTE_TABLE to be returned to the caller of + GetModeData. The EFI_IP4_ROUTE_TABLE is clumsy to use in the + internal operation of the IP4 driver. + + @param IpInstance The IP4 child that requests the route table. + + @retval EFI_SUCCESS The route table is successfully build + @retval EFI_OUT_OF_RESOURCES Failed to allocate the memory for the rotue table. + +**/ EFI_STATUS Ip4BuildEfiRouteTable ( IN IP4_PROTOCOL *IpInstance -- 2.39.2