FreeRTOS_Routing.h

/*
 * FreeRTOS+TCP <DEVELOPMENT BRANCH>
 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * http://aws.amazon.com/freertos
 * http://www.FreeRTOS.org
 */

#ifndef FREERTOS_ROUTING_H
    #define FREERTOS_ROUTING_H

    #include "FreeRTOS.h"
    #include "FreeRTOS_IP.h"
    #include "FreeRTOS_Sockets.h"

    #if ( ipconfigUSE_DHCP != 0 )
        #include "FreeRTOS_DHCP.h"
    #endif

    #if ( ipconfigUSE_IPv6 != 0 )
        #include "FreeRTOS_DHCPv6.h"
    #endif

    #ifdef __cplusplus
    extern "C" {
    #endif

/* Every NetworkInterface needs a set of access functions: */

/* Initialise the interface. */
    typedef BaseType_t ( * NetworkInterfaceInitialiseFunction_t ) ( struct xNetworkInterface * pxDescriptor );

/* Send out an Ethernet packet. */
    typedef BaseType_t ( * NetworkInterfaceOutputFunction_t ) ( struct xNetworkInterface * pxDescriptor,
                                                                NetworkBufferDescriptor_t * const pxNetworkBuffer,
                                                                BaseType_t xReleaseAfterSend );

/* Return true as long as the LinkStatus on the PHY is present. */
    typedef BaseType_t ( * GetPhyLinkStatusFunction_t ) ( struct xNetworkInterface * pxDescriptor );

/* Functions that manipulate what MAC addresses are received by this interface */
    typedef void ( * NetworkInterfaceMACFilterFunction_t ) ( struct xNetworkInterface * pxInterface,
                                                             const uint8_t * pucMacAddressBytes );

/** @brief These NetworkInterface access functions are collected in a struct: */
    typedef struct xNetworkInterface
    {
        const char * pcName;                               /**< Just for logging, debugging. */
        void * pvArgument;                                 /**< Will be passed to the access functions. */
        NetworkInterfaceInitialiseFunction_t pfInitialise; /**< This function will be called upon initialisation and repeated until it returns pdPASS. */
        NetworkInterfaceOutputFunction_t pfOutput;         /**< This function is supposed to send out a packet. */
        GetPhyLinkStatusFunction_t pfGetPhyLinkStatus;     /**< This function will return pdTRUE as long as the PHY Link Status is high. */

        /*
         * pfAddAllowedMAC and pfRemoveAllowedMAC form the network driver's address filtering API.
         * The network stack uses these functions to alter which MAC addresses will be received.
         * The MAC addresses passed to the functions can be unicast or multicast. It is important
         * to note that the stack may call these functions multiple times for the the same MAC address.
         * For example, if two sockets subscribe to the same multicast group, pfAddAllowedMAC()
         * will be called twice with the same MAC address. The network driver is responsible for
         * keeping track of these calls. The network driver should continue receiving that
         * particular MAC address until pfRemoveAllowedMAC() is called the same number of times.
         *
         * Most EMAC hardware nowadays can filter frames based on both specific MAC address matching
         * and hash matching. Specific address matching is ideal because as the name suggests,
         * only frames with the exact MAC address are received. Usually however, the number of
         * specific MAC addresses is limited ( to 4 in many cases ) and is sometimes not enough for
         * all the MAC addresses that the network stack needs to receive.
         * Hash matching is usually based around a 64-bit hash table. For every incoming frame,
         * the EMAC calculates a hash value (mod 64) of the destination MAC address.
         * The hash value is looked up in the 64-bit hash table and if that bit is set, the frame is
         * received. If the bit is clear, the frame is dropped. With hash matching, multiple
         * MAC addresses are represented by a single bit. It is the responsibility of the network
         * driver to manage both the hash address matching and specific address matching capabilities
         * of the EMAC hardware.
         * A quick and dirty implementation option is to receive all MAC addresses and set both
         * pfAddAllowedMAC and pfRemoveAllowedMAC to NULL. This results in an interface running
         * in promiscuous mode and the entire burden of MAC filtering falls on the network stack.
         * For a more realistic implementation, check out
         * "portable/NetworkInterface/DriverSAM/NetworkInterface.c" It demonstrates the use of both
         * specific and hash address matching as well as keeping count of how many time the
         * individual registers/bits have been used. That implementation's init functions also
         * demonstrates the use of prvAddAllowedMACAddress() function to register all end-point's
         * MAC addresses whether the endpoints used the same or different MAC addresses.
         */
        NetworkInterfaceMACFilterFunction_t pfAddAllowedMAC;
        NetworkInterfaceMACFilterFunction_t pfRemoveAllowedMAC;

        struct
        {
            uint32_t
                bInterfaceUp : 1,             /**< Non-zero as soon as the interface is up. */
                bCallDownEvent : 1;           /**< The down-event must be called. */
        } bits;                               /**< A collection of boolean flags. */

        struct xNetworkEndPoint * pxEndPoint; /**< A list of end-points bound to this interface. */
        struct xNetworkInterface * pxNext;    /**< The next interface in a linked list. */
    } NetworkInterface_t;

/*
 *  // As an example:
 *  NetworkInterface_t xZynqDescriptor = {
 *      .pcName					= "Zynq-GEM",
 *      .pvArgument				= ( void * )1,
 *      .pfInitialise           = xZynqGEMInitialise,
 *      .pfOutput               = xZynqGEMOutput,
 *      .pfGetPhyLinkStatus     = xZynqGEMGetPhyLinkStatus,
 *  };
 */

/** @brief The network settings for IPv4. */
    typedef struct xIPV4Parameters
    {
        uint32_t ulIPAddress;                                                /**< The actual IPv4 address. Will be 0 as long as end-point is still down. */
        uint32_t ulNetMask;                                                  /**< The netmask. */
        uint32_t ulGatewayAddress;                                           /**< The IP-address of the gateway. */
        uint32_t ulDNSServerAddresses[ ipconfigENDPOINT_DNS_ADDRESS_COUNT ]; /**< IP-addresses of DNS servers. */
        uint32_t ulBroadcastAddress;                                         /**< The local broadcast address, e.g. '192.168.1.255'. */
        uint8_t ucDNSIndex;                                                  /**< The index of the next DNS address to be used. */
    } IPV4Parameters_t;

    #if ( ipconfigUSE_IPv6 != 0 )
        typedef struct xIPV6Parameters
        {
            IPv6_Address_t xIPAddress;      /* The actual IPv4 address. Will be 0 as long as end-point is still down. */
            size_t uxPrefixLength;          /* Number of valid bytes in the network prefix. */
            IPv6_Address_t xPrefix;         /* The network prefix, e.g. fe80::/10 */
            IPv6_Address_t xGatewayAddress; /* Gateway to the web. */
            IPv6_Address_t xDNSServerAddresses[ ipconfigENDPOINT_DNS_ADDRESS_COUNT ];
            uint8_t ucDNSIndex;             /**< The index of the next DNS address to be used. */
        } IPV6Parameters_t;
    #endif

    #if ( ipconfigUSE_RA != 0 )
/* Router Advertisement (RA). End-points can obtain their IP-address by asking for a RA. */
        typedef enum xRAState
        {
            eRAStateApply,    /* Send a Router Solicitation. */
            eRAStateWait,     /* Wait for a Router Advertisement. */
            eRAStateIPTest,   /* Take a random IP address, test if another device is using it already. */
            eRAStateIPWait,   /* Wait for a reply, if any */
            eRAStatePreLease, /* The device is ready to go to the 'eRAStateLease' state. */
            eRAStateLease,    /* The device is up, repeat the RA-process when timer expires. */
            eRAStateFailed
        } eRAState_t;

        struct xRA_DATA
        {
            struct
            {
                uint32_t
                    bRouterReplied : 1,
                    bIPAddressInUse : 1;
            }
            bits;
            TickType_t ulPreferredLifeTime;
            UBaseType_t uxRetryCount;
            /* Maintains the RA state machine state. */
            eRAState_t eRAState;
        };

        typedef struct xRA_DATA RAData_t;
    #endif /* ( ipconfigUSE_RA != 0 ) */

/** @brief The description of an end-point. */
    typedef struct xNetworkEndPoint
    {
        #if ( ipconfigUSE_IPv4 != 0 )
            IPV4Parameters_t ipv4_settings; /**< Actual IPv4 settings used by the end-point. */
            IPV4Parameters_t ipv4_defaults; /**< Use values form "ipv4_defaults" in case DHCP has failed. */
        #endif
        #if ( ipconfigUSE_IPv6 != 0 )
            IPV6Parameters_t ipv6_settings; /**< Actual IPv6 settings used by the end-point. */
            IPV6Parameters_t ipv6_defaults; /**< Use values form "ipv6_defaults" in case DHCP has failed. */
        #endif
        MACAddress_t xMACAddress;           /**< The MAC-address assigned to this end-point. */
        struct
        {
            uint32_t
                bIsDefault : 1, /**< This bit will be removed. */
            #if ( ipconfigUSE_DHCP != 0 ) || ( ipconfigUSE_DHCPv6 != 0 )
                bWantDHCP : 1,  /**< This end-point wants to use DHCPv4 to obtain an IP-address. */
            #endif /* ipconfigUSE_DHCP */
            #if ( ipconfigUSE_RA != 0 )
                bWantRA : 1,         /**< This end-point wants to use RA/SLAAC to obtain an IP-address. */
            #endif /* ipconfigUSE_RA */
            bIPv6 : 1,               /**< This end-point has an IP-address of type IPv6. */
            #if ( ipconfigUSE_NETWORK_EVENT_HOOK != 0 )
                bCallDownHook : 1,   /**< The network down hook-must be called for this end-point. */
            #endif /* ipconfigUSE_NETWORK_EVENT_HOOK */
            bEndPointUp : 1;         /**< The end-point is up. */
        } bits;                      /**< A collection of boolean properties. */
        uint8_t usDNSType;           /**< A LLMNR/mDNS lookup is being done for an IPv6 address.
                                      * This field is only valid while xApplicationDNSQueryHook() is called. */
        #if ( ipconfigUSE_DHCP != 0 ) || ( ipconfigUSE_RA != 0 )
            IPTimer_t xDHCP_RATimer; /**<  The timer used to call the DHCP/DHCPv6/RA state machine. */
        #endif /* ( ipconfigUSE_DHCP != 0 ) || ( ipconfigUSE_RA != 0 ) */
        #if ( ipconfigUSE_DHCP != 0 ) || ( ipconfigUSE_DHCPv6 != 0 )
            DHCPData_t xDHCPData; /**< A description of the DHCP client state machine. */
        #endif /* ( ipconfigUSE_DHCP != 0 ) || ( ipconfigUSE_DHCPv6 != 0 ) */
        #if ( ipconfigUSE_IPv6 != 0 )
            DHCPMessage_IPv6_t * pxDHCPMessage; /**< A description of the DHCPv6 client state machine. */
        #endif
        #if ( ipconfigUSE_RA != 0 )
            RAData_t xRAData;                    /**< A description of the Router Advertisement ( RA ) client state machine. */
        #endif /* ( ipconfigUSE_RA != 0 ) */
        NetworkInterface_t * pxNetworkInterface; /**< The network interface that owns this end-point. */
        struct xNetworkEndPoint * pxNext;        /**< The next end-point in the chain. */
    } NetworkEndPoint_t;

    #define END_POINT_USES_DHCP( pxEndPoint )    ( ( pxEndPoint )->bits.bWantDHCP != pdFALSE_UNSIGNED )
    #define END_POINT_USES_RA( pxEndPoint )      ( ( ( pxEndPoint )->bits.bIPv6 != pdFALSE_UNSIGNED ) && ( ( pxEndPoint )->bits.bWantRA != pdFALSE_UNSIGNED ) )

    #define ENDPOINT_IS_IPv4( pxEndPoint )       ( ( ( pxEndPoint ) != NULL ) && ( ( pxEndPoint )->bits.bIPv6 == 0U ) )
    #define ENDPOINT_IS_IPv6( pxEndPoint )       ( ( ( pxEndPoint ) != NULL ) && ( ( pxEndPoint )->bits.bIPv6 != 0U ) )


/*
 * Add a new physical Network Interface.  The object pointed to by 'pxInterface'
 * must continue to exist.
 * Only the Network Interface function xx_FillInterfaceDescriptor() shall call this function.
 */
    NetworkInterface_t * FreeRTOS_AddNetworkInterface( NetworkInterface_t * pxInterface );

/*
 * Get the first Network Interface.
 */
    NetworkInterface_t * FreeRTOS_FirstNetworkInterface( void );

/*
 * Get the next Network Interface.
 */
    NetworkInterface_t * FreeRTOS_NextNetworkInterface( const NetworkInterface_t * pxInterface );

/*
 * Get the first end-point belonging to a given interface.  When pxInterface is
 * NULL, the very first end-point will be returned.
 */
    NetworkEndPoint_t * FreeRTOS_FirstEndPoint( const NetworkInterface_t * pxInterface );

/*
 * Get the next end-point.  When pxInterface is null, all end-points can be
 * iterated.
 */
    NetworkEndPoint_t * FreeRTOS_NextEndPoint( const NetworkInterface_t * pxInterface,
                                               NetworkEndPoint_t * pxEndPoint );

/*
 * Find the end-point with given IP-address.
 */
    NetworkEndPoint_t * FreeRTOS_FindEndPointOnIP_IPv4( uint32_t ulIPAddress );

    #if ( ipconfigUSE_IPv6 != 0 )
        /* Find the end-point with given IP-address. */
        NetworkEndPoint_t * FreeRTOS_FindEndPointOnIP_IPv6( const IPv6_Address_t * pxIPAddress );
    #endif /* ipconfigUSE_IPv6 */

/*
 * Find the end-point with given MAC-address.
 * The search can be limited by supplying a particular interface.
 */
    NetworkEndPoint_t * FreeRTOS_FindEndPointOnMAC( const MACAddress_t * pxMACAddress,
                                                    const NetworkInterface_t * pxInterface );

/*
 * Find the best fitting end-point to reach a given IP-address.
 * Find an end-point whose IP-address is in the same network as the IP-address provided.
 */
    NetworkEndPoint_t * FreeRTOS_FindEndPointOnNetMask( uint32_t ulIPAddress );

/*
 * Find the best fitting IPv4 end-point to reach a given IP-address on a given interface
 */
    NetworkEndPoint_t * FreeRTOS_InterfaceEndPointOnNetMask( const NetworkInterface_t * pxInterface,
                                                             uint32_t ulIPAddress );

/*
 * Finds an endpoint on the given interface which is in the same subnet as the
 * given IP address. If NULL is passed for pxInterface, it looks through all the
 * interfaces to find an endpoint in the same subnet as the given IP address.
 */
    NetworkEndPoint_t * FreeRTOS_InterfaceEPInSameSubnet_IPv6( const NetworkInterface_t * pxInterface,
                                                               const IPv6_Address_t * pxIPAddress );

    #if ( ipconfigUSE_IPv6 != 0 )
        NetworkEndPoint_t * FreeRTOS_FindEndPointOnNetMask_IPv6( const IPv6_Address_t * pxIPv6Address );
    #endif /* ipconfigUSE_IPv6 */

    #if ( ipconfigUSE_IPv6 != 0 )

/* Get the first end-point belonging to a given interface.
 * When pxInterface is NULL, the very first end-point will be returned. */
        NetworkEndPoint_t * FreeRTOS_FirstEndPoint_IPv6( const NetworkInterface_t * pxInterface );
    #endif /* ipconfigUSE_IPv6 */

/* A ethernet packet has come in on a certain network interface.
 * Find the best matching end-point. */
    NetworkEndPoint_t * FreeRTOS_MatchingEndpoint( const NetworkInterface_t * pxNetworkInterface,
                                                   const uint8_t * pucEthernetBuffer );

/* Find an end-point that has a defined gateway.
 * xIPType should equal ipTYPE_IPv4 or ipTYPE_IPv6. */
    NetworkEndPoint_t * FreeRTOS_FindGateWay( BaseType_t xIPType );

/* Fill-in the end-point structure. */
    void FreeRTOS_FillEndPoint( NetworkInterface_t * pxNetworkInterface,
                                NetworkEndPoint_t * pxEndPoint,
                                const uint8_t ucIPAddress[ ipIP_ADDRESS_LENGTH_BYTES ],
                                const uint8_t ucNetMask[ ipIP_ADDRESS_LENGTH_BYTES ],
                                const uint8_t ucGatewayAddress[ ipIP_ADDRESS_LENGTH_BYTES ],
                                const uint8_t ucDNSServerAddress[ ipIP_ADDRESS_LENGTH_BYTES ],
                                const uint8_t ucMACAddress[ ipMAC_ADDRESS_LENGTH_BYTES ] );

    #if ( ipconfigUSE_IPv6 != 0 )
        /* Fill-in the end-point structure. */
        void FreeRTOS_FillEndPoint_IPv6( NetworkInterface_t * pxNetworkInterface,
                                         NetworkEndPoint_t * pxEndPoint,
                                         const IPv6_Address_t * pxIPAddress,
                                         const IPv6_Address_t * pxNetPrefix,
                                         size_t uxPrefixLength,
                                         const IPv6_Address_t * pxGatewayAddress,
                                         const IPv6_Address_t * pxDNSServerAddress, /* Not used yet. */
                                         const uint8_t ucMACAddress[ ipMAC_ADDRESS_LENGTH_BYTES ] );
    #endif

    NetworkEndPoint_t * pxGetSocketEndpoint( ConstSocket_t xSocket );
    void vSetSocketEndpoint( Socket_t xSocket,
                             NetworkEndPoint_t * pxEndPoint );

    #if ( ( ipconfigHAS_PRINTF != 0 ) || ( ipconfigHAS_DEBUG_PRINTF != 0 ) )
        const char * pcEndpointName( const NetworkEndPoint_t * pxEndPoint,
                                     char * pcBuffer,
                                     size_t uxSize );
    #endif /* ( ( ipconfigHAS_PRINTF != 0 ) || ( ipconfigHAS_DEBUG_PRINTF != 0 ) ) */

    typedef enum
    {
        eIPv6_Global,      /* 001           */
        eIPv6_LinkLocal,   /* 1111 1110 10  */
        eIPv6_SiteLocal,   /* 1111 1110 11  */
        eIPv6_UniqueLocal, /* 1111 110      */
        eIPv6_Multicast,   /* 1111 1111     */
        eIPv6_Loopback,    /* 1111 (::1)    */
        eIPv6_Unknown      /* Not implemented. */
    }
    IPv6_Type_t;

    #if ( ipconfigUSE_IPv6 != 0 )

/**
 * @brief Check the type of an IPv16 address.
 *
 * @return A value from enum IPv6_Type_t.
 */
        IPv6_Type_t xIPv6_GetIPType( const IPv6_Address_t * pxAddress );
    #endif

    BaseType_t xCheckRequiresResolution( const NetworkBufferDescriptor_t * pxNetworkBuffer );

    typedef enum
    {
        eResolutionCacheMiss = 0, /* 0 A cache lookup did not find a valid entry. */
        eResolutionCacheHit,      /* 1 A cache lookup found a valid entry. */
        eResolutionFailed         /* 2 There is no IP address, or a resolution is still in progress, so the packet cannot be sent. */
    } eResolutionLookupResult_t;

    #ifdef __cplusplus
}     /* extern "C" */
    #endif

#endif /* FREERTOS_ROUTING_H */