1 /* 2 * FreeRTOS+TCP V3.1.0 3 * Copyright (C) 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. 4 * 5 * SPDX-License-Identifier: MIT 6 * 7 * Permission is hereby granted, free of charge, to any person obtaining a copy of 8 * this software and associated documentation files (the "Software"), to deal in 9 * the Software without restriction, including without limitation the rights to 10 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 11 * the Software, and to permit persons to whom the Software is furnished to do so, 12 * subject to the following conditions: 13 * 14 * The above copyright notice and this permission notice shall be included in all 15 * copies or substantial portions of the Software. 16 * 17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 20 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 21 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 23 * 24 * http://aws.amazon.com/freertos 25 * http://www.FreeRTOS.org 26 */ 27 28 #ifndef FREERTOS_IP_H 29 #define FREERTOS_IP_H 30 31 /* *INDENT-OFF* */ 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 /* *INDENT-ON* */ 36 37 #include "FreeRTOS.h" 38 #include "task.h" 39 40 /* Application level configuration options. */ 41 #include "FreeRTOSIPConfig.h" 42 #include "FreeRTOSIPConfigDefaults.h" 43 #include "IPTraceMacroDefaults.h" 44 45 /* Constants defining the current version of the FreeRTOS+TCP 46 * network stack. */ 47 #define ipFR_TCP_VERSION_NUMBER "V3.1.0" 48 #define ipFR_TCP_VERSION_MAJOR 3 49 #define ipFR_TCP_VERSION_MINOR 1 50 /* Development builds are always version 999. */ 51 #define ipFR_TCP_VERSION_BUILD 0 52 53 /* Some constants defining the sizes of several parts of a packet. 54 * These defines come before including the configuration header files. */ 55 56 /* The size of the Ethernet header is 14, meaning that 802.1Q VLAN tags 57 * are not ( yet ) supported. */ 58 #define ipSIZE_OF_ETH_HEADER 14U 59 #define ipSIZE_OF_IPv4_HEADER 20U 60 #define ipSIZE_OF_IGMP_HEADER 8U 61 #define ipSIZE_OF_ICMP_HEADER 8U 62 #define ipSIZE_OF_UDP_HEADER 8U 63 #define ipSIZE_OF_TCP_HEADER 20U 64 65 #define ipSIZE_OF_IPv4_ADDRESS 4U 66 67 /* 68 * Generate a randomized TCP Initial Sequence Number per RFC. 69 * This function must be provided by the application builder. 70 */ 71 /* This function is defined generally by the application. */ 72 extern uint32_t ulApplicationGetNextSequenceNumber( uint32_t ulSourceAddress, 73 uint16_t usSourcePort, 74 uint32_t ulDestinationAddress, 75 uint16_t usDestinationPort ); 76 77 /* The number of octets in the MAC and IP addresses respectively. */ 78 #define ipMAC_ADDRESS_LENGTH_BYTES ( 6U ) 79 #define ipIP_ADDRESS_LENGTH_BYTES ( 4U ) 80 81 /* IP protocol definitions. */ 82 #define ipPROTOCOL_ICMP ( 1U ) 83 #define ipPROTOCOL_IGMP ( 2U ) 84 #define ipPROTOCOL_TCP ( 6U ) 85 #define ipPROTOCOL_UDP ( 17U ) 86 87 /* The character used to fill ICMP echo requests, and therefore also the 88 * character expected to fill ICMP echo replies. */ 89 #define ipECHO_DATA_FILL_BYTE 'x' 90 91 /* Dimensions the buffers that are filled by received Ethernet frames. */ 92 #define ipSIZE_OF_ETH_CRC_BYTES ( 4UL ) 93 #define ipSIZE_OF_ETH_OPTIONAL_802_1Q_TAG_BYTES ( 4UL ) 94 #define ipTOTAL_ETHERNET_FRAME_SIZE ( ( ( uint32_t ) ipconfigNETWORK_MTU ) + ( ( uint32_t ) ipSIZE_OF_ETH_HEADER ) + ipSIZE_OF_ETH_CRC_BYTES + ipSIZE_OF_ETH_OPTIONAL_802_1Q_TAG_BYTES ) 95 96 97 /* Space left at the beginning of a network buffer storage area to store a 98 * pointer back to the network buffer. Should be a multiple of 8 to ensure 8 byte 99 * alignment is maintained on architectures that require it. 100 * 101 * In order to get a 32-bit alignment of network packets, an offset of 2 bytes 102 * would be desirable, as defined by ipconfigPACKET_FILLER_SIZE. So the malloc'd 103 * buffer will have the following contents: 104 * uint32_t pointer; // word-aligned 105 * uchar_8 filler[6]; 106 * << ETH-header >> // half-word-aligned 107 * uchar_8 dest[6]; // start of pucEthernetBuffer 108 * uchar_8 dest[6]; 109 * uchar16_t type; 110 * << IP-header >> // word-aligned 111 * uint8_t ucVersionHeaderLength; 112 * etc 113 */ 114 115 #if ( ipconfigBUFFER_PADDING != 0 ) 116 #define ipBUFFER_PADDING ipconfigBUFFER_PADDING 117 #else 118 #define ipBUFFER_PADDING ( 8U + ipconfigPACKET_FILLER_SIZE ) 119 #endif 120 121 /* The offset of ucTCPFlags within the TCP header. */ 122 #define ipTCP_FLAGS_OFFSET 13U 123 124 #define ipFIRST_LOOPBACK_IPv4 0x7F000000UL /**< Lowest IPv4 loopback address (including). */ 125 #define ipLAST_LOOPBACK_IPv4 0x80000000UL /**< Highest IPv4 loopback address (excluding). */ 126 127 /** @brief Returned to indicate a valid checksum. */ 128 #define ipCORRECT_CRC 0xffffU 129 130 /** @brief Returned to indicate incorrect checksum. */ 131 #define ipWRONG_CRC 0x0000U 132 133 /** @brief Returned as the (invalid) checksum when the length of the data being checked 134 * had an invalid length. */ 135 #define ipINVALID_LENGTH 0x1234U 136 137 /** @brief Returned as the (invalid) checksum when the protocol being checked is not 138 * handled. The value is chosen simply to be easy to spot when debugging. */ 139 #define ipUNHANDLED_PROTOCOL 0x4321U 140 141 /** @brief The maximum time the IP task is allowed to remain in the Blocked state if no 142 * events are posted to the network event queue. */ 143 #ifndef ipconfigMAX_IP_TASK_SLEEP_TIME 144 #define ipconfigMAX_IP_TASK_SLEEP_TIME ( pdMS_TO_TICKS( 10000UL ) ) 145 #endif 146 147 /* Trace macros to aid in debugging, disabled if ipconfigHAS_PRINTF != 1 */ 148 #if ( ipconfigHAS_PRINTF == 1 ) 149 #define DEBUG_DECLARE_TRACE_VARIABLE( type, var, init ) type var = ( init ) /**< Trace macro to set "type var = init". */ 150 #define DEBUG_SET_TRACE_VARIABLE( var, value ) var = ( value ) /**< Trace macro to set var = value. */ 151 #else 152 #define DEBUG_DECLARE_TRACE_VARIABLE( type, var, init ) /**< Empty definition since ipconfigHAS_PRINTF != 1. */ 153 #define DEBUG_SET_TRACE_VARIABLE( var, value ) /**< Empty definition since ipconfigHAS_PRINTF != 1. */ 154 #endif 155 156 157 /** 158 * The structure used to store buffers and pass them around the network stack. 159 * Buffers can be in use by the stack, in use by the network interface hardware 160 * driver, or free (not in use). 161 */ 162 typedef struct xNETWORK_BUFFER 163 { 164 ListItem_t xBufferListItem; /**< Used to reference the buffer form the free buffer list or a socket. */ 165 uint32_t ulIPAddress; /**< Source or destination IP address, depending on usage scenario. */ 166 uint8_t * pucEthernetBuffer; /**< Pointer to the start of the Ethernet frame. */ 167 size_t xDataLength; /**< Starts by holding the total Ethernet frame length, then the UDP/TCP payload length. */ 168 uint16_t usPort; /**< Source or destination port, depending on usage scenario. */ 169 uint16_t usBoundPort; /**< The port to which a transmitting socket is bound. */ 170 #if ( ipconfigUSE_LINKED_RX_MESSAGES != 0 ) 171 struct xNETWORK_BUFFER * pxNextBuffer; /**< Possible optimisation for expert users - requires network driver support. */ 172 #endif 173 } NetworkBufferDescriptor_t; 174 175 #include "pack_struct_start.h" 176 177 /** 178 * MAC address structure. 179 */ 180 struct xMAC_ADDRESS 181 { 182 uint8_t ucBytes[ ipMAC_ADDRESS_LENGTH_BYTES ]; /**< Byte array of the MAC address */ 183 } 184 #include "pack_struct_end.h" 185 186 typedef struct xMAC_ADDRESS MACAddress_t; 187 188 typedef enum eNETWORK_EVENTS 189 { 190 eNetworkUp, /* The network is configured. */ 191 eNetworkDown /* The network connection has been lost. */ 192 } eIPCallbackEvent_t; 193 194 /* MISRA check: some modules refer to this typedef even though 195 * ipconfigSUPPORT_OUTGOING_PINGS is not enabled. */ 196 typedef enum ePING_REPLY_STATUS 197 { 198 eSuccess = 0, /**< A correct reply has been received for an outgoing ping. */ 199 eInvalidChecksum, /**< A reply was received for an outgoing ping but the checksum of the reply was incorrect. */ 200 eInvalidData /**< A reply was received to an outgoing ping but the payload of the reply was not correct. */ 201 } ePingReplyStatus_t; 202 203 /** 204 * The software timer struct for various IP functions 205 */ 206 typedef struct xIP_TIMER 207 { 208 uint32_t 209 bActive : 1, /**< This timer is running and must be processed. */ 210 bExpired : 1; /**< Timer has expired and a task must be processed. */ 211 TimeOut_t xTimeOut; /**< The timeout value. */ 212 TickType_t ulRemainingTime; /**< The amount of time remaining. */ 213 TickType_t ulReloadTime; /**< The value of reload time. */ 214 } IPTimer_t; 215 216 217 /* Endian related definitions. */ 218 #if ( ipconfigBYTE_ORDER == pdFREERTOS_LITTLE_ENDIAN ) 219 220 /* FreeRTOS_htons / FreeRTOS_htonl: some platforms might have built-in versions 221 * using a single instruction so allow these versions to be overridden. */ 222 #ifndef FreeRTOS_htons 223 #define FreeRTOS_htons( usIn ) ( ( uint16_t ) ( ( ( usIn ) << 8U ) | ( ( usIn ) >> 8U ) ) ) 224 #endif 225 226 #ifndef FreeRTOS_htonl 227 #define FreeRTOS_htonl( ulIn ) \ 228 ( \ 229 ( uint32_t ) \ 230 ( \ 231 ( ( ( ( uint32_t ) ( ulIn ) ) ) << 24 ) | \ 232 ( ( ( ( uint32_t ) ( ulIn ) ) & 0x0000ff00U ) << 8 ) | \ 233 ( ( ( ( uint32_t ) ( ulIn ) ) & 0x00ff0000U ) >> 8 ) | \ 234 ( ( ( ( uint32_t ) ( ulIn ) ) ) >> 24 ) \ 235 ) \ 236 ) 237 #endif /* ifndef FreeRTOS_htonl */ 238 239 #else /* ipconfigBYTE_ORDER */ 240 241 #define FreeRTOS_htons( x ) ( ( uint16_t ) ( x ) ) 242 #define FreeRTOS_htonl( x ) ( ( uint32_t ) ( x ) ) 243 244 #endif /* ipconfigBYTE_ORDER == pdFREERTOS_LITTLE_ENDIAN */ 245 246 #define FreeRTOS_ntohs( x ) FreeRTOS_htons( x ) 247 #define FreeRTOS_ntohl( x ) FreeRTOS_htonl( x ) 248 249 /* Some simple helper functions. */ 250 int32_t FreeRTOS_max_int32( int32_t a, 251 int32_t b ); 252 253 uint32_t FreeRTOS_max_uint32( uint32_t a, 254 uint32_t b ); 255 256 size_t FreeRTOS_max_size_t( size_t a, 257 size_t b ); 258 259 int32_t FreeRTOS_min_int32( int32_t a, 260 int32_t b ); 261 262 uint32_t FreeRTOS_min_uint32( uint32_t a, 263 uint32_t b ); 264 265 size_t FreeRTOS_min_size_t( size_t a, 266 size_t b ); 267 268 uint32_t FreeRTOS_round_up( uint32_t a, 269 uint32_t d ); 270 uint32_t FreeRTOS_round_down( uint32_t a, 271 uint32_t d ); 272 273 #define ipMS_TO_MIN_TICKS( xTimeInMs ) ( ( pdMS_TO_TICKS( ( xTimeInMs ) ) < ( ( TickType_t ) 1U ) ) ? ( ( TickType_t ) 1U ) : pdMS_TO_TICKS( ( xTimeInMs ) ) ) 274 275 /* For backward compatibility. */ 276 #define pdMS_TO_MIN_TICKS( xTimeInMs ) ipMS_TO_MIN_TICKS( xTimeInMs ) 277 278 #ifndef pdTRUE_SIGNED 279 /* Temporary solution: eventually the defines below will appear in 'Source\include\projdefs.h' */ 280 #define pdTRUE_SIGNED pdTRUE 281 #define pdFALSE_SIGNED pdFALSE 282 #define pdTRUE_UNSIGNED ( 1U ) 283 #define pdFALSE_UNSIGNED ( 0U ) 284 #define ipTRUE_BOOL ( 1 == 1 ) 285 #define ipFALSE_BOOL ( 1 == 2 ) 286 #endif 287 288 /* 289 * FULL, UP-TO-DATE AND MAINTAINED REFERENCE DOCUMENTATION FOR ALL THESE 290 * FUNCTIONS IS AVAILABLE ON THE FOLLOWING URL: 291 * http://www.FreeRTOS.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/FreeRTOS_TCP_API_Functions.html 292 */ 293 BaseType_t FreeRTOS_IPInit( const uint8_t ucIPAddress[ ipIP_ADDRESS_LENGTH_BYTES ], 294 const uint8_t ucNetMask[ ipIP_ADDRESS_LENGTH_BYTES ], 295 const uint8_t ucGatewayAddress[ ipIP_ADDRESS_LENGTH_BYTES ], 296 const uint8_t ucDNSServerAddress[ ipIP_ADDRESS_LENGTH_BYTES ], 297 const uint8_t ucMACAddress[ ipMAC_ADDRESS_LENGTH_BYTES ] ); 298 299 TaskHandle_t FreeRTOS_GetIPTaskHandle( void ); 300 301 void * FreeRTOS_GetUDPPayloadBuffer( size_t uxRequestedSizeBytes, 302 TickType_t uxBlockTimeTicks ); 303 void FreeRTOS_GetAddressConfiguration( uint32_t * pulIPAddress, 304 uint32_t * pulNetMask, 305 uint32_t * pulGatewayAddress, 306 uint32_t * pulDNSServerAddress ); 307 308 void FreeRTOS_SetAddressConfiguration( const uint32_t * pulIPAddress, 309 const uint32_t * pulNetMask, 310 const uint32_t * pulGatewayAddress, 311 const uint32_t * pulDNSServerAddress ); 312 313 /* MISRA defining 'FreeRTOS_SendPingRequest' should be dependent on 'ipconfigSUPPORT_OUTGOING_PINGS'. 314 * In order not to break some existing project, define it unconditionally. */ 315 BaseType_t FreeRTOS_SendPingRequest( uint32_t ulIPAddress, 316 size_t uxNumberOfBytesToSend, 317 TickType_t uxBlockTimeTicks ); 318 319 void FreeRTOS_ReleaseUDPPayloadBuffer( void const * pvBuffer ); 320 const uint8_t * FreeRTOS_GetMACAddress( void ); 321 void FreeRTOS_UpdateMACAddress( const uint8_t ucMACAddress[ ipMAC_ADDRESS_LENGTH_BYTES ] ); 322 #if ( ipconfigUSE_NETWORK_EVENT_HOOK == 1 ) 323 /* This function shall be defined by the application. */ 324 void vApplicationIPNetworkEventHook( eIPCallbackEvent_t eNetworkEvent ); 325 #endif 326 #if ( ipconfigSUPPORT_OUTGOING_PINGS == 1 ) 327 void vApplicationPingReplyHook( ePingReplyStatus_t eStatus, 328 uint16_t usIdentifier ); 329 #endif 330 uint32_t FreeRTOS_GetIPAddress( void ); 331 void FreeRTOS_SetIPAddress( uint32_t ulIPAddress ); 332 void FreeRTOS_SetNetmask( uint32_t ulNetmask ); 333 void FreeRTOS_SetGatewayAddress( uint32_t ulGatewayAddress ); 334 uint32_t FreeRTOS_GetGatewayAddress( void ); 335 uint32_t FreeRTOS_GetDNSServerAddress( void ); 336 uint32_t FreeRTOS_GetNetmask( void ); 337 BaseType_t xARPWaitResolution( uint32_t ulIPAddress, 338 TickType_t uxTicksToWait ); 339 340 BaseType_t FreeRTOS_IsNetworkUp( void ); 341 342 #if ( ipconfigCHECK_IP_QUEUE_SPACE != 0 ) 343 UBaseType_t uxGetMinimumIPQueueSpace( void ); 344 #endif 345 346 BaseType_t xIsNetworkDownEventPending( void ); 347 348 /* 349 * Defined in FreeRTOS_Sockets.c 350 * //_RB_ Don't think this comment is correct. If this is for internal use only it should appear after all the public API functions and not start with FreeRTOS_. 351 * Socket has had activity, reset the timer so it will not be closed 352 * because of inactivity 353 */ 354 #if ( ( ipconfigHAS_DEBUG_PRINTF != 0 ) || ( ipconfigHAS_PRINTF != 0 ) ) 355 const char * FreeRTOS_GetTCPStateName( UBaseType_t ulState ); 356 #endif 357 358 /* _HT_ Temporary: show all valid ARP entries 359 */ 360 #if ( ipconfigHAS_PRINTF != 0 ) || ( ipconfigHAS_DEBUG_PRINTF != 0 ) 361 void FreeRTOS_PrintARPCache( void ); 362 #endif 363 364 void FreeRTOS_ClearARP( void ); 365 366 /* Return pdTRUE if the IPv4 address is a multicast address. */ 367 BaseType_t xIsIPv4Multicast( uint32_t ulIPAddress ); 368 369 /* Set the MAC-address that belongs to a given IPv4 multi-cast address. */ 370 void vSetMultiCastIPv4MacAddress( uint32_t ulIPAddress, 371 MACAddress_t * pxMACAddress ); 372 373 #if ( ipconfigDHCP_REGISTER_HOSTNAME == 1 ) 374 375 /* DHCP has an option for clients to register their hostname. It doesn't 376 * have much use, except that a device can be found in a router along with its 377 * name. If this option is used the callback below must be provided by the 378 * application writer to return a const string, denoting the device's name. */ 379 /* Typically this function is defined in a user module. */ 380 const char * pcApplicationHostnameHook( void ); 381 382 #endif /* ipconfigDHCP_REGISTER_HOSTNAME */ 383 384 385 /* This xApplicationGetRandomNumber() will set *pulNumber to a random number, 386 * and return pdTRUE. When the random number generator is broken, it shall return 387 * pdFALSE. 388 * The function is defined in 'iot_secure_sockets.c'. 389 * If that module is not included in the project, the application must provide an 390 * implementation of it. 391 * The macro's ipconfigRAND32() and configRAND32() are not in use anymore. */ 392 393 /* "xApplicationGetRandomNumber" is declared but never defined, because it may 394 * be defined in a user module. */ 395 BaseType_t xApplicationGetRandomNumber( uint32_t * pulNumber ); 396 397 /** @brief The pointer to buffer with packet waiting for ARP resolution. This variable 398 * is defined in FreeRTOS_IP.c. 399 * This pointer is for internal use only. */ 400 extern NetworkBufferDescriptor_t * pxARPWaitingNetworkBuffer; 401 402 /* For backward compatibility define old structure names to the newer equivalent 403 * structure name. */ 404 #ifndef ipconfigENABLE_BACKWARD_COMPATIBILITY 405 #define ipconfigENABLE_BACKWARD_COMPATIBILITY 1 406 #endif 407 408 #if ( ipconfigENABLE_BACKWARD_COMPATIBILITY == 1 ) 409 #define xIPStackEvent_t IPStackEvent_t 410 #define xNetworkBufferDescriptor_t NetworkBufferDescriptor_t 411 #define xMACAddress_t MACAddress_t 412 #define xWinProperties_t WinProperties_t 413 #define xSocket_t Socket_t 414 #define xSocketSet_t SocketSet_t 415 #define ipSIZE_OF_IP_HEADER ipSIZE_OF_IPv4_HEADER 416 417 /* Since August 2016, the public types and fields below have changed name: 418 * abbreviations TCP/UDP are now written in capitals, and type names now end with "_t". */ 419 #define FOnConnected FOnConnected_t 420 #define FOnTcpReceive FOnTCPReceive_t 421 #define FOnTcpSent FOnTCPSent_t 422 #define FOnUdpReceive FOnUDPReceive_t 423 #define FOnUdpSent FOnUDPSent_t 424 425 #define pOnTcpConnected pxOnTCPConnected 426 #define pOnTcpReceive pxOnTCPReceive 427 #define pOnTcpSent pxOnTCPSent 428 #define pOnUdpReceive pxOnUDPReceive 429 #define pOnUdpSent pxOnUDPSent 430 431 #define FOnUdpSent FOnUDPSent_t 432 #define FOnTcpSent FOnTCPSent_t 433 #endif /* ipconfigENABLE_BACKWARD_COMPATIBILITY */ 434 435 #if ( ipconfigHAS_PRINTF != 0 ) 436 extern void vPrintResourceStats( void ); 437 #else 438 #define vPrintResourceStats() do {} while( ipFALSE_BOOL ) /**< ipconfigHAS_PRINTF is not defined. Define vPrintResourceStats to a do-while( 0 ). */ 439 #endif 440 441 #if ( ipconfigUSE_TCP != 0 ) 442 443 /** @brief Set to a non-zero value if one or more TCP message have been processed 444 * within the last round. */ 445 extern BaseType_t xProcessedTCPMessage; 446 #endif 447 448 #include "FreeRTOS_IP_Utils.h" 449 450 /* *INDENT-OFF* */ 451 #ifdef __cplusplus 452 } /* extern "C" */ 453 #endif 454 /* *INDENT-ON* */ 455 456 #endif /* FREERTOS_IP_H */ 457
