xref: /FreeRTOS-Plus-TCP-v4.0.0/source/include/FreeRTOS_ND.h (revision df5aed9e58a72e2489b6c1936788885672c62981) 
1 /*
2  * FreeRTOS+TCP V2.3.1
3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy of
6  * this software and associated documentation files (the "Software"), to deal in
7  * the Software without restriction, including without limitation the rights to
8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9  * the Software, and to permit persons to whom the Software is furnished to do so,
10  * subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in all
13  * copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
21  *
22  * http://aws.amazon.com/freertos
23  * http://www.FreeRTOS.org
24  */
25 
26 #ifndef FREERTOS_ND_H
27 #define FREERTOS_ND_H
28 
29 #include "FreeRTOS.h"
30 
31 /* Application level configuration options. */
32 #include "FreeRTOSIPConfig.h"
33 #include "FreeRTOSIPConfigDefaults.h"
34 #include "IPTraceMacroDefaults.h"
35 
36 #include "FreeRTOS_ARP.h"
37 
38 /* *INDENT-OFF* */
39 #ifdef __cplusplus
40     extern "C" {
41 #endif
42 /* *INDENT-ON* */
43 
44 #if ( ipconfigUSE_IPv6 != 0 )
45 /*-----------------------------------------------------------*/
46 /* Miscellaneous structure and definitions. */
47 /*-----------------------------------------------------------*/
48 
49 /**
50  * @brief 'NDCacheRow_t' defines one row in the ND address cache.
51  * @note About A value that is periodically decremented but can
52  *       also be refreshed by active communication.  The ND cache entry
53  *       is removed if the value reaches zero.
54  */
55     typedef struct xND_CACHE_TABLE_ROW
56     {
57         IPv6_Address_t xIPAddress;            /**< The IP address of an ND cache entry. */
58         MACAddress_t xMACAddress;             /**< The MAC address of an ND cache entry. */
59         struct xNetworkEndPoint * pxEndPoint; /**< The end-point on which the
60                                                * remote device had responded. */
61         uint8_t ucAge;                        /**< See here above. */
62         uint8_t ucValid;                      /**< pdTRUE: xMACAddress is valid, pdFALSE: waiting for ND reply */
63     } NDCacheRow_t;
64 
65 /*
66  * If ulIPAddress is already in the ND cache table then reset the age of the
67  * entry back to its maximum value.  If ulIPAddress is not already in the ND
68  * cache table then add it - replacing the oldest current entry if there is not
69  * a free space available.
70  */
71     void vNDRefreshCacheEntry( const MACAddress_t * pxMACAddress,
72                                const IPv6_Address_t * pxIPAddress,
73                                NetworkEndPoint_t * pxEndPoint );
74 
75 /** @brief Options that can be sent in a ROuter Advertisement packet. */
76     #define ndICMP_SOURCE_LINK_LAYER_ADDRESS    1
77     #define ndICMP_TARGET_LINK_LAYER_ADDRESS    2
78     #define ndICMP_PREFIX_INFORMATION           3
79     #define ndICMP_REDIRECTED_HEADER            4
80     #define ndICMP_MTU_OPTION                   5
81 
82 /*
83  * @brief Send a neighbour solicitation.
84  * @param[in] pxIPAddress: A network buffer big enough to hold the ICMP packet.
85  * @param[in,out] pxMACAddress: When found, the array of 6 bytes will be filled
86  *                with the MAC-address.
87  * @param[in,out] ppxEndPoint: The pointer to a pointer will point to an
88  *                             end-point to which the device has responded.
89  *
90  * @note Look for ulIPAddress in the ND cache.  If the IP address exists, copy the
91  * associated MAC address into pxMACAddress, refresh the ND cache entry's
92  * age, and return eARPCacheHit.  If the IP address does not exist in the ND
93  * cache return eARPCacheMiss.  If the packet cannot be sent for any reason
94  * (maybe DHCP is still in process, or the addressing needs a gateway but there
95  * isn't a gateway defined) then return eCantSendPacket.
96  */
97     eARPLookupResult_t eNDGetCacheEntry( IPv6_Address_t * pxIPAddress,
98                                          MACAddress_t * const pxMACAddress,
99                                          struct xNetworkEndPoint ** ppxEndPoint );
100 
101 /**
102  * @brief Reduce the age counter in each entry within the ND cache.  An entry is no
103  * longer considered valid and is deleted if its age reaches zero.
104  * Just before getting to zero, 3 times a neighbour solicitation will be sent.
105  */
106     void vNDAgeCache( void );
107 
108 /**
109  * @brief Send a neighbour solicitation.
110  * @param[in] pxNetworkBuffer: A network buffer big enough to hold the ICMP packet.
111  * @param[in] pxIPAddress: The IPv6 address of the target device.
112  *
113  * @note Send out an ND request for the IPv6 address contained in pxNetworkBuffer, and
114  * add an entry into the ND table that indicates that an ND reply is
115  * outstanding so re-transmissions can be generated.
116  */
117     void vNDSendNeighbourSolicitation( NetworkBufferDescriptor_t * pxNetworkBuffer,
118                                        const IPv6_Address_t * pxIPAddress );
119 
120     #if ( ipconfigUSE_RA != 0 )
121 
122 /**
123  * @brief Send a router solicitation.
124  * @param[in] pxNetworkBuffer: A network buffer big enough to hold the ICMP packet.
125  * @param[in] pxIPAddress: The multi-cast address of the routers ( normally ff02::2 ).
126  */
127         void vNDSendRouterSolicitation( NetworkBufferDescriptor_t * pxNetworkBuffer,
128                                         IPv6_Address_t * pxIPAddress );
129     #endif /* ( ipconfigUSE_RA != 0 ) */
130 
131     #if ( ipconfigUSE_RA != 0 )
132 
133 /**
134  * @brief Work on the RA/SLAAC processing.
135  * @param[in] xDoReset: WHen true, the state-machine will be reset and initialised.
136  * @param[in] pxEndPoint: The end-point for which the RA/SLAAC process should be done..
137  */
138         void vRAProcess( BaseType_t xDoReset,
139                          NetworkEndPoint_t * pxEndPoint );
140     #endif /* ( ipconfigUSE_RA != 0 ) */
141 
142 /**
143  * @brief Send an ND advertisement.
144  * @param[in] pxEndPoint: The end-point for which an ND advertisement should be sent.
145  */
146     void FreeRTOS_OutputAdvertiseIPv6( NetworkEndPoint_t * pxEndPoint );
147     #if ( ipconfigSUPPORT_OUTGOING_PINGS == 1 )
148 
149 /**
150  * @brief Send an IPv6 ping message to a remote device.
151  * @param[in] pxIPAddress: The IPv6 address of the other device.
152  * @param[in] uxNumberOfBytesToSend: The number of bytes to be echoed.
153  * @param[in] uxBlockTimeTicks: The number of clock-tick to wait
154  *            for space in the IP-task queue.
155  * @return pdTRUE when a packets was successfully created
156  *         and passed to the IP-task.
157  */
158         BaseType_t FreeRTOS_SendPingRequestIPv6( const IPv6_Address_t * pxIPAddress,
159                                                  size_t uxNumberOfBytesToSend,
160                                                  TickType_t uxBlockTimeTicks );
161     #endif
162 
163 /**
164  * @brief Create an IPv16 address, based on a prefix.
165  *
166  * @param[out] pxIPAddress: The location where the new IPv6 address
167  *                          will be stored.
168  * @param[in] pxPrefix: The prefix to be used.
169  * @param[in] uxPrefixLength: The length of the prefix.
170  * @param[in] xDoRandom: A non-zero value if the bits after the
171  *                       prefix should have a random value.
172  *
173  * @return pdPASS if the operation was successful. Or pdFAIL in
174  *         case xApplicationGetRandomNumber()
175  *         returned an error.
176  */
177     BaseType_t FreeRTOS_CreateIPv6Address( IPv6_Address_t * pxIPAddress,
178                                            const IPv6_Address_t * pxPrefix,
179                                            size_t uxPrefixLength,
180                                            BaseType_t xDoRandom );
181 
182 /* Receive a Neighbour Advertisement. */
183 
184     #if ( ipconfigUSE_RA != 0 )
185 
186 /** @brief A neighbour advertisement has been received. Store its
187  *         address in the ND address cache.
188  *  @param[in] pxNetworkBuffer The buffer containing the packet.
189  */
190         void vReceiveNA( const NetworkBufferDescriptor_t * pxNetworkBuffer );
191     #endif
192 
193 /* Receive a Router Advertisement. */
194     #if ( ipconfigUSE_RA != 0 )
195 
196 /** @brief A router advertisement has been received.  See if it is
197  *         applicable for this device.
198  *  @param[in] pxNetworkBuffer The buffer containing the packet.
199  */
200         void vReceiveRA( const NetworkBufferDescriptor_t * pxNetworkBuffer );
201     #endif
202 
203     #if ( ( ipconfigHAS_PRINTF != 0 ) || ( ipconfigHAS_DEBUG_PRINTF != 0 ) )
204 /** @brief Print the contents of the ND cache, for debugging only. */
205         void FreeRTOS_PrintNDCache( void );
206     #endif
207 
208 #endif /* ipconfigUSE_IPv6 != 0 */
209 
210 
211 /* *INDENT-OFF* */
212 #ifdef __cplusplus
213     }
214 #endif
215 /* *INDENT-ON* */
216 
217 #endif /* FREERTOS_ND_H */
218