388 lines
19 KiB
C
388 lines
19 KiB
C
/*
|
|
* FreeRTOS+TCP
|
|
* 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_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 */
|