Adds support for receiving IPv4 and IPv6 multicast groups

Modifies eConsiderFrameForProcessing() to allow all multicast ethernet frames when ipconfigSUPPORT_IP_MULTICAST is enabled and ipconfigETHERNET_DRIVER_FILTERS_FRAME_TYPES is disabled.
Adds parsing of IGMP and MLD queries.
Sends IGMPv2 and MLDv1 reports on a schedule that is updated based on received IGMP/MLD queries.
Sends unsolicited IGMP and MLD reports on network-up events and on add-membership socket option.
Adds pxSocket->u.xUDP.xMulticastTTL that can be used for both IPv4 and IPv6
Adds pxSocket->u.xUDP.xMulticastAddress that can be used for both IPv4 and IPv6
Adds pxSocket->u.xUDP.pxMulticastNetIf that specifies the interface on which a sockets wants to receive multicasts.
Adds socket option defines to add/drop membership as well as change the transmit TTL of multicasts.
Makes all 3 multicast socket options (add/drop/ttl) work with both IPv4 and IPv6
Adds a ucMaximumHops field to NetworkBufferDescriptor_t and assigns it to the proper TTL/HopLimit value based on what packet is being sent.
Adds exceptions so that we don't send multicast reports for 224.0.0.1, ff02::1, as well as anything with IPv6 multicast scope of 0 or 1
Adds defines for MLD packets like the Multicast Listener Query and Report.
The MLD report defines are different for transmitted and received packets because the stack strips the optional headers from received MLD packets.
Generates an MLD report for the solicited-node multicast addresses corresponding to all unicast IPv6 addresses
Sends IGMPv2 Leave Group messages whenever the last socket subscribed to a group drops that membership.
On network down, stops receiving the MAC address that corresponds to the solicited node multicast IPv6 address. This balances out the "network-up" calls that allow that MAC address.
Removes the explicit broadcast MAC check in eConsiderFrameForProcessing. Broadcasts are a form of multicasts and will be received when ipconfigSUPPORT_IP_MULTICAST is enabled.

Adds ipconfigSUPPORT_IP_MULTICAST to enable/disable all the functionality described above.
Adds ipconfigPERIODIC_MULTICAST_REPORT_INTERVAL for debug purposes when there is no IGMP/MLD querier

Moves the registration of the IGMP multicast MAC to the network driver init code.
Adds a Multicast Todo list to help keep me on track.

Author: Emil Popov

source/FreeRTOS_DNS_Networking.c

@@ -84,6 +84,11 @@
              * going to be '0' i.e. success. Thus, return value is discarded */
             ( void ) FreeRTOS_setsockopt( xSocket, 0, FREERTOS_SO_SNDTIMEO, &( uxWriteTimeOut_ticks ), sizeof( TickType_t ) );
             ( void ) FreeRTOS_setsockopt( xSocket, 0, FREERTOS_SO_RCVTIMEO, &( uxReadTimeOut_ticks ), sizeof( TickType_t ) );
+            #if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) )
+                /* Since this socket may be used for LLMNR or mDNS, set the multicast TTL to 1. */
+                uint8_t ucMulticastTTL = 1;
+                ( void ) FreeRTOS_setsockopt( xSocket, 0, FREERTOS_SO_IP_MULTICAST_TTL, &( ucMulticastTTL ), sizeof( ucMulticastTTL ) );
+            #endif /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
         }
 
         return xSocket;

source/FreeRTOS_DNS_Parser.c

@@ -896,6 +896,26 @@
                     }
 
                     xUDPPacket_IPv6->xUDPHeader.usLength = FreeRTOS_htons( ( uint16_t ) lNetLength + ipSIZE_OF_UDP_HEADER );
+
+                    if( xUDPPacket_IPv6->xUDPHeader.usDestinationPort == FreeRTOS_ntohs( ipMDNS_PORT ) )
+                    {
+                        /* RFC6762, section 11 */
+                        xUDPPacket_IPv6->xIPHeader.ucHopLimit = 255U;
+                    }
+                    else if( xUDPPacket_IPv6->xUDPHeader.usDestinationPort == FreeRTOS_ntohs( ipLLMNR_PORT ) )
+                    {
+                        /* LLMNR: RFC4795 section 2.5 recommends UDP requests and responses use TTL of 255 */
+
+                        /* Theoretically, LLMNR replies can go "off-link" and create a DDoS scenario. That should be preventable
+                         * by settings our rely's TTL/HopLimit to 1. Please note that in certain situations ( I think unicast
+                         * responses), Wireshark flags some LLMNR packets that have TTL of 1 as too low. */
+                        xUDPPacket_IPv6->xIPHeader.ucHopLimit = 1U;
+                    }
+                    else
+                    {
+                        xUDPPacket_IPv6->xIPHeader.ucHopLimit = ipconfigUDP_TIME_TO_LIVE;
+                    }
+
                     vFlip_16( pxUDPHeader->usSourcePort, pxUDPHeader->usDestinationPort );
                     uxDataLength = ( size_t ) lNetLength + ipSIZE_OF_IPv6_HEADER + ipSIZE_OF_UDP_HEADER + ipSIZE_OF_ETH_HEADER;
                 }
@@ -911,8 +931,18 @@
                 /* HT:endian: should not be translated, copying from packet to packet */
                 if( pxIPHeader->ulDestinationIPAddress == ipMDNS_IP_ADDRESS )
                 {
+                    /* RFC6762, section 11 */
                     pxIPHeader->ucTimeToLive = ipMDNS_TIME_TO_LIVE;
                 }
+                else if( pxUDPHeader->usDestinationPort == FreeRTOS_ntohs( ipLLMNR_PORT ) )
+                {
+                    /* LLMNR: RFC4795 section 2.5 recommends UDP requests and responses use TTL of 255 */
+
+                    /* Theoretically, LLMNR replies can go "off-link" and create a DDoS scenario. That should be preventable
+                     * by settings our rely's TTL/HopLimit to 1. Please note that in certain situations ( I think unicast
+                     * responses), Wireshark flags some LLMNR packets that have TTL of 1 as too low. */
+                    pxIPHeader->ucTimeToLive = 1;
+                }
                 else
                 {
                     pxIPHeader->ulDestinationIPAddress = pxIPHeader->ulSourceIPAddress;

source/FreeRTOS_IP.c

@@ -59,6 +59,9 @@
 #include "FreeRTOS_DNS.h"
 #include "FreeRTOS_Routing.h"
 #include "FreeRTOS_ND.h"
+#if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) )
+    #include "FreeRTOS_IGMP.h"
+#endif /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
 
 /** @brief Time delay between repeated attempts to initialise the network hardware. */
 #ifndef ipINITIALISATION_RETRY_DELAY
@@ -460,6 +463,20 @@ static void prvProcessIPEventsAndTimers( void )
             /* xQueueReceive() returned because of a normal time-out. */
             break;
 
+            #if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) )
+                case eSocketOptAddMembership:
+                case eSocketOptDropMembership:
+                   {
+                       MulticastAction_t * pxMCA = ( MulticastAction_t * ) xReceivedEvent.pvData;
+                       vModifyMulticastMembership( pxMCA, xReceivedEvent.eEventType );
+                       break;
+                   }
+
+                case eMulticastTimerEvent:
+                    vIPMulticast_HandleTimerEvent();
+                    break;
+            #endif /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
+
         default:
             /* Should not get here. */
             break;
@@ -519,6 +536,11 @@ static void prvIPTask_Initialise( void )
     }
     #endif /* ( ( ipconfigUSE_DNS_CACHE != 0 ) && ( ipconfigUSE_DNS != 0 ) ) */
 
+    /* Init the list that will hold scheduled IGMP reports. */
+    #if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) )
+        ( void ) vIPMulticast_Init();
+    #endif /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
+
     /* Initialisation is complete and events can now be processed. */
     xIPTaskInitialised = pdTRUE;
 }
@@ -632,6 +654,16 @@ void vIPNetworkUpCalls( struct xNetworkEndPoint * pxEndPoint )
         #endif
     }
 
+    #if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) )
+
+        /* Reschedule all multicast reports associated with this end-point.
+         * Note: countdown is in increments of ipIGMP_TIMER_PERIOD_MS. It's a good idea to spread out all reports a little.
+         * 200 to 500ms ( xMaxCountdown of 2 - 5 ) should be a good happy medium. If the network we just connected to has a IGMP/MLD querier,
+         * they will soon ask us for reports anyways, so sending these unsolicited reports is not required. It simply enhances the user
+         * experience by shortening the time it takes before we begin receiving the multicasts that we care for. */
+        vRescheduleAllMulticastReports( pxEndPoint->pxNetworkInterface, 5 );
+    #endif /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
+
     pxEndPoint->bits.bEndPointUp = pdTRUE_UNSIGNED;
 
     #if ( ipconfigUSE_NETWORK_EVENT_HOOK == 1 )
@@ -1321,6 +1353,7 @@ void FreeRTOS_ReleaseUDPPayloadBuffer( void const * pvBuffer )
                 pxNetworkBuffer->pucEthernetBuffer[ ipSOCKET_OPTIONS_OFFSET ] = FREERTOS_SO_UDPCKSUM_OUT;
                 pxNetworkBuffer->xIPAddress.ulIP_IPv4 = ulIPAddress;
                 pxNetworkBuffer->usPort = ipPACKET_CONTAINS_ICMP_DATA;
+                pxNetworkBuffer->ucMaximumHops = ipconfigICMP_TIME_TO_LIVE;
                 /* xDataLength is the size of the total packet, including the Ethernet header. */
                 pxNetworkBuffer->xDataLength = uxTotalLength;
 
@@ -1477,34 +1510,50 @@ eFrameProcessingResult_t eConsiderFrameForProcessing( const uint8_t * const pucE
             /* The packet was directed to this node - process it. */
             eReturn = eProcessBuffer;
         }
-        else if( memcmp( xBroadcastMACAddress.ucBytes, pxEthernetHeader->xDestinationAddress.ucBytes, sizeof( MACAddress_t ) ) == 0 )
-        {
-            /* The packet was a broadcast - process it. */
-            eReturn = eProcessBuffer;
-        }
-        else
-        #if ( ( ipconfigUSE_LLMNR == 1 ) && ( ipconfigUSE_DNS != 0 ) )
-            if( memcmp( xLLMNR_MacAddress.ucBytes, pxEthernetHeader->xDestinationAddress.ucBytes, sizeof( MACAddress_t ) ) == 0 )
+
+        #if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) )
+
+            /*
+             * With ipconfigSUPPORT_IP_MULTICAST enabled, FreeRTOS+TCP needs access to all
+             * multicast packets. It is too early to filter them out here because we don't
+             * know which socket needs which multicast address. Another thing to consider is
+             * that unless this function returns eProcessBuffer, eApplicationProcessCustomFrameHook()
+             * will not be called, so handling custom multicast frames would be impossible.
+             * Note that the broadcast MAC is a type of multicast so the multicast check covers it.
+             */
+            else if( MAC_IS_MULTICAST( pxEthernetHeader->xDestinationAddress.ucBytes ) )
             {
-                /* The packet is a request for LLMNR - process it. */
                 eReturn = eProcessBuffer;
             }
-            else
-        #endif /* ipconfigUSE_LLMNR */
-        #if ( ( ipconfigUSE_MDNS == 1 ) && ( ipconfigUSE_DNS != 0 ) )
-            if( memcmp( xMDNS_MacAddress.ucBytes, pxEthernetHeader->xDestinationAddress.ucBytes, sizeof( MACAddress_t ) ) == 0 )
+        #else /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
+            else if( memcmp( xBroadcastMACAddress.ucBytes, pxEthernetHeader->xDestinationAddress.ucBytes, sizeof( MACAddress_t ) ) == 0 )
             {
-                /* The packet is a request for MDNS - process it. */
+                /* The packet was a broadcast - process it. */
                 eReturn = eProcessBuffer;
             }
-            else
-        #endif /* ipconfigUSE_MDNS */
-        if( ( pxEthernetHeader->xDestinationAddress.ucBytes[ 0 ] == ipMULTICAST_MAC_ADDRESS_IPv6_0 ) &&
-            ( pxEthernetHeader->xDestinationAddress.ucBytes[ 1 ] == ipMULTICAST_MAC_ADDRESS_IPv6_1 ) )
-        {
-            /* The packet is a request for LLMNR - process it. */
-            eReturn = eProcessBuffer;
-        }
+            #if ( ( ipconfigUSE_LLMNR == 1 ) && ( ipconfigUSE_DNS != 0 ) )
+                else if( memcmp( xLLMNR_MacAddress.ucBytes, pxEthernetHeader->xDestinationAddress.ucBytes, sizeof( MACAddress_t ) ) == 0 )
+                {
+                    /* The packet is a request for LLMNR - process it. */
+                    eReturn = eProcessBuffer;
+                }
+            #endif /* ipconfigUSE_LLMNR */
+            #if ( ( ipconfigUSE_MDNS == 1 ) && ( ipconfigUSE_DNS != 0 ) )
+                else if( memcmp( xMDNS_MacAddress.ucBytes, pxEthernetHeader->xDestinationAddress.ucBytes, sizeof( MACAddress_t ) ) == 0 )
+                {
+                    /* The packet is a request for MDNS - process it. */
+                    eReturn = eProcessBuffer;
+                }
+            #endif /* ipconfigUSE_MDNS */
+            #if ( ipconfigIS_ENABLED( ipconfigUSE_IPv6 ) )
+                else if( ( pxEthernetHeader->xDestinationAddress.ucBytes[ 0 ] == ipMULTICAST_MAC_ADDRESS_IPv6_0 ) &&
+                         ( pxEthernetHeader->xDestinationAddress.ucBytes[ 1 ] == ipMULTICAST_MAC_ADDRESS_IPv6_1 ) )
+                {
+                    /* The packet is an IPv6 multicast - process it. */
+                    eReturn = eProcessBuffer;
+                }
+            #endif /* ipconfigIS_ENABLED( ipconfigUSE_IPv6 ) */
+        #endif /* ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) */
         else
         {
             /* The packet was not a broadcast, or for this node, just release
@@ -2009,6 +2058,13 @@ static eFrameProcessingResult_t prvProcessIPPacket( const IPPacket_t * pxIPPacke
                             break;
                     #endif /* ( ipconfigUSE_IPv6 != 0 ) */
 
+                    #if ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) && ipconfigIS_ENABLED( ipconfigUSE_IPv4 ) )
+                        case ipPROTOCOL_IGMP:
+                            /* The IP packet contained an IGMP frame.  */
+                            eReturn = eProcessIGMPPacket( pxNetworkBuffer );
+                            break;
+                    #endif /* ( ipconfigIS_ENABLED( ipconfigSUPPORT_IP_MULTICAST ) && ipconfigIS_ENABLED( ipconfigUSE_IPv4 ) ) */
+
                     case ipPROTOCOL_UDP:
                         /* The IP packet contained a UDP frame. */