git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-TCP/include/FreeRTOS_IP.h

   1 /*\r
   2  * FreeRTOS+TCP V2.0.0\r
   3  * Copyright (C) 2017 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software. If you wish to use our Amazon\r
  14  * FreeRTOS name, please do so in a fair use way that does not cause confusion.\r
  15  *\r
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  18  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  19  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  20  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  22  *\r
  23  * http://www.FreeRTOS.org\r
  24  * http://aws.amazon.com/freertos\r
  25  *\r
  26  * 1 tab == 4 spaces!\r
  27  */\r
  28 \r
  29 #ifndef FREERTOS_IP_H\r
  30 #define FREERTOS_IP_H\r
  31 \r
  32 #ifdef __cplusplus\r
  33 extern "C" {\r
  34 #endif\r
  35 \r
  36 /* Application level configuration options. */\r
  37 #include "FreeRTOSIPConfig.h"\r
  38 #include "FreeRTOSIPConfigDefaults.h"\r
  39 #include "IPTraceMacroDefaults.h"\r
  40 \r
  41 /* Some constants defining the sizes of several parts of a packet */\r
  42 #define ipSIZE_OF_ETH_HEADER                    14u\r
  43 #define ipSIZE_OF_IPv4_HEADER                   20u\r
  44 #define ipSIZE_OF_IGMP_HEADER                   8u\r
  45 #define ipSIZE_OF_ICMP_HEADER                   8u\r
  46 #define ipSIZE_OF_UDP_HEADER                    8u\r
  47 #define ipSIZE_OF_TCP_HEADER                    20u\r
  48 \r
  49 \r
  50 /* The number of octets in the MAC and IP addresses respectively. */\r
  51 #define ipMAC_ADDRESS_LENGTH_BYTES ( 6 )\r
  52 #define ipIP_ADDRESS_LENGTH_BYTES ( 4 )\r
  53 \r
  54 /* IP protocol definitions. */\r
  55 #define ipPROTOCOL_ICMP                 ( 1 )\r
  56 #define ipPROTOCOL_IGMP         ( 2 )\r
  57 #define ipPROTOCOL_TCP                  ( 6 )\r
  58 #define ipPROTOCOL_UDP                  ( 17 )\r
  59 \r
  60 /* Dimensions the buffers that are filled by received Ethernet frames. */\r
  61 #define ipSIZE_OF_ETH_CRC_BYTES                                 ( 4UL )\r
  62 #define ipSIZE_OF_ETH_OPTIONAL_802_1Q_TAG_BYTES ( 4UL )\r
  63 #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 )\r
  64 \r
  65 /*_RB_ Comment may need updating. */\r
  66 /* Space left at the beginning of a network buffer storage area to store a\r
  67 pointer back to the network buffer.  Should be a multiple of 8 to ensure 8 byte\r
  68 alignment is maintained on architectures that require it.\r
  69 \r
  70 In order to get a 32-bit alignment of network packets, an offset of 2 bytes\r
  71 would be desirable, as defined by ipconfigPACKET_FILLER_SIZE.  So the malloc'd\r
  72 buffer will have the following contents:\r
  73         uint32_t pointer;       // word-aligned\r
  74         uchar_8 filler[6];\r
  75         << ETH-header >>        // half-word-aligned\r
  76         uchar_8 dest[6];    // start of pucEthernetBuffer\r
  77         uchar_8 dest[6];\r
  78         uchar16_t type;\r
  79         << IP-header >>         // word-aligned\r
  80         uint8_t ucVersionHeaderLength;\r
  81         etc\r
  82  */\r
  83 #if( ipconfigBUFFER_PADDING != 0 )\r
  84     #define ipBUFFER_PADDING    ipconfigBUFFER_PADDING\r
  85 #else\r
  86     #define ipBUFFER_PADDING    ( 8u + ipconfigPACKET_FILLER_SIZE )\r
  87 #endif\r
  88 \r
  89 /* The structure used to store buffers and pass them around the network stack.\r
  90 Buffers can be in use by the stack, in use by the network interface hardware\r
  91 driver, or free (not in use). */\r
  92 typedef struct xNETWORK_BUFFER\r
  93 {\r
  94         ListItem_t xBufferListItem;     /* Used to reference the buffer form the free buffer list or a socket. */\r
  95         uint32_t ulIPAddress;                   /* Source or destination IP address, depending on usage scenario. */\r
  96         uint8_t *pucEthernetBuffer;     /* Pointer to the start of the Ethernet frame. */\r
  97         size_t xDataLength;                     /* Starts by holding the total Ethernet frame length, then the UDP/TCP payload length. */\r
  98         uint16_t usPort;                                /* Source or destination port, depending on usage scenario. */\r
  99         uint16_t usBoundPort;                   /* The port to which a transmitting socket is bound. */\r
 100         #if( ipconfigUSE_LINKED_RX_MESSAGES != 0 )\r
 101                 struct xNETWORK_BUFFER *pxNextBuffer; /* Possible optimisation for expert users - requires network driver support. */\r
 102         #endif\r
 103 } NetworkBufferDescriptor_t;\r
 104 \r
 105 #include "pack_struct_start.h"\r
 106 struct xMAC_ADDRESS\r
 107 {\r
 108         uint8_t ucBytes[ ipMAC_ADDRESS_LENGTH_BYTES ];\r
 109 }\r
 110 #include "pack_struct_end.h"\r
 111 \r
 112 typedef struct xMAC_ADDRESS MACAddress_t;\r
 113 \r
 114 typedef enum eNETWORK_EVENTS\r
 115 {\r
 116         eNetworkUp,             /* The network is configured. */\r
 117         eNetworkDown    /* The network connection has been lost. */\r
 118 } eIPCallbackEvent_t;\r
 119 \r
 120 typedef enum ePING_REPLY_STATUS\r
 121 {\r
 122         eSuccess = 0,           /* A correct reply has been received for an outgoing ping. */\r
 123         eInvalidChecksum,       /* A reply was received for an outgoing ping but the checksum of the reply was incorrect. */\r
 124         eInvalidData            /* A reply was received to an outgoing ping but the payload of the reply was not correct. */\r
 125 } ePingReplyStatus_t;\r
 126 \r
 127 typedef enum eNETWORK_ADDRESS_TYPE \r
 128 {\r
 129         eNetWorkAddressTypeIPV4,\r
 130         eNetWorkAddressTypeIPV6,\r
 131         eNetWorkAddressTypeHostName\r
 132 } eNetWorkAddressType_t;\r
 133 \r
 134 /* Endian related definitions. */\r
 135 #if( ipconfigBYTE_ORDER == pdFREERTOS_LITTLE_ENDIAN )\r
 136 \r
 137         /* FreeRTOS_htons / FreeRTOS_htonl: some platforms might have built-in versions\r
 138         using a single instruction so allow these versions to be overridden. */\r
 139         #ifndef FreeRTOS_htons\r
 140                 #define FreeRTOS_htons( usIn ) ( (uint16_t) ( ( ( usIn ) << 8U ) | ( ( usIn ) >> 8U ) ) )\r
 141         #endif\r
 142 \r
 143         #ifndef FreeRTOS_htonl\r
 144                 #define FreeRTOS_htonl( ulIn )                                                                                  \\r
 145                         (                                                                                                                                       \\r
 146                                 ( uint32_t )                                                                                                    \\r
 147                                 (                                                                                                                               \\r
 148                                         ( ( ( ( uint32_t ) ( ulIn ) )                ) << 24  ) |       \\r
 149                                         ( ( ( ( uint32_t ) ( ulIn ) ) & 0x0000ff00UL ) <<  8  ) |       \\r
 150                                         ( ( ( ( uint32_t ) ( ulIn ) ) & 0x00ff0000UL ) >>  8  ) |       \\r
 151                                         ( ( ( ( uint32_t ) ( ulIn ) )                ) >> 24  )         \\r
 152                                 )                                                                                                                               \\r
 153                         )\r
 154         #endif\r
 155 \r
 156 #else /* ipconfigBYTE_ORDER */\r
 157 \r
 158         #define FreeRTOS_htons( x ) ( ( uint16_t ) ( x ) )\r
 159         #define FreeRTOS_htonl( x ) ( ( uint32_t ) ( x ) )\r
 160 \r
 161 #endif /* ipconfigBYTE_ORDER == pdFREERTOS_LITTLE_ENDIAN */\r
 162 \r
 163 #define FreeRTOS_ntohs( x ) FreeRTOS_htons( x )\r
 164 #define FreeRTOS_ntohl( x ) FreeRTOS_htonl( x )\r
 165 \r
 166 #if( ipconfigHAS_INLINE_FUNCTIONS == 1 )\r
 167 \r
 168         static portINLINE int32_t  FreeRTOS_max_int32  (int32_t  a, int32_t  b);\r
 169         static portINLINE uint32_t FreeRTOS_max_uint32 (uint32_t a, uint32_t b);\r
 170         static portINLINE int32_t  FreeRTOS_min_int32  (int32_t  a, int32_t  b);\r
 171         static portINLINE uint32_t FreeRTOS_min_uint32 (uint32_t a, uint32_t b);\r
 172         static portINLINE uint32_t FreeRTOS_round_up   (uint32_t a, uint32_t d);\r
 173         static portINLINE uint32_t FreeRTOS_round_down (uint32_t a, uint32_t d);\r
 174         static portINLINE BaseType_t  FreeRTOS_min_BaseType  (BaseType_t  a, BaseType_t  b);\r
 175         static portINLINE BaseType_t  FreeRTOS_max_BaseType  (BaseType_t  a, BaseType_t  b);\r
 176         static portINLINE UBaseType_t FreeRTOS_max_UBaseType (UBaseType_t a, UBaseType_t b);\r
 177         static portINLINE UBaseType_t   FreeRTOS_min_UBaseType (UBaseType_t  a, UBaseType_t  b);\r
 178 \r
 179 \r
 180         static portINLINE int32_t  FreeRTOS_max_int32  (int32_t  a, int32_t  b) { return a >= b ? a : b; }\r
 181         static portINLINE uint32_t FreeRTOS_max_uint32 (uint32_t a, uint32_t b) { return a >= b ? a : b; }\r
 182         static portINLINE int32_t  FreeRTOS_min_int32  (int32_t  a, int32_t  b) { return a <= b ? a : b; }\r
 183         static portINLINE uint32_t FreeRTOS_min_uint32 (uint32_t a, uint32_t b) { return a <= b ? a : b; }\r
 184         static portINLINE uint32_t FreeRTOS_round_up   (uint32_t a, uint32_t d) { return d * ( ( a + d - 1u ) / d ); }\r
 185         static portINLINE uint32_t FreeRTOS_round_down (uint32_t a, uint32_t d) { return d * ( a / d ); }\r
 186 \r
 187         static portINLINE BaseType_t  FreeRTOS_max_BaseType  (BaseType_t  a, BaseType_t  b) { return a >= b ? a : b; }\r
 188         static portINLINE UBaseType_t FreeRTOS_max_UBaseType (UBaseType_t a, UBaseType_t b) { return a >= b ? a : b; }\r
 189         static portINLINE BaseType_t  FreeRTOS_min_BaseType  (BaseType_t  a, BaseType_t  b) { return a <= b ? a : b; }\r
 190         static portINLINE UBaseType_t FreeRTOS_min_UBaseType (UBaseType_t  a, UBaseType_t  b) { return a <= b ? a : b; }\r
 191 \r
 192 #else\r
 193 \r
 194         #define FreeRTOS_max_int32(a,b)  ( ( ( int32_t  ) ( a ) ) >= ( ( int32_t  ) ( b ) ) ? ( ( int32_t  ) ( a ) ) : ( ( int32_t  ) ( b ) ) )\r
 195         #define FreeRTOS_max_uint32(a,b) ( ( ( uint32_t ) ( a ) ) >= ( ( uint32_t ) ( b ) ) ? ( ( uint32_t ) ( a ) ) : ( ( uint32_t ) ( b ) ) )\r
 196 \r
 197         #define FreeRTOS_min_int32(a,b)  ( ( ( int32_t  ) a ) <= ( ( int32_t  ) b ) ? ( ( int32_t  ) a ) : ( ( int32_t  ) b ) )\r
 198         #define FreeRTOS_min_uint32(a,b) ( ( ( uint32_t ) a ) <= ( ( uint32_t ) b ) ? ( ( uint32_t ) a ) : ( ( uint32_t ) b ) )\r
 199 \r
 200         /*  Round-up: a = d * ( ( a + d - 1 ) / d ) */\r
 201         #define FreeRTOS_round_up(a,d)   ( ( ( uint32_t ) ( d ) ) * ( ( ( ( uint32_t ) ( a ) ) + ( ( uint32_t ) ( d ) ) - 1UL ) / ( ( uint32_t ) ( d ) ) ) )\r
 202         #define FreeRTOS_round_down(a,d) ( ( ( uint32_t ) ( d ) ) * ( ( ( uint32_t ) ( a ) ) / ( ( uint32_t ) ( d ) ) ) )\r
 203 \r
 204         #define FreeRTOS_ms_to_tick(ms)  ( ( ms * configTICK_RATE_HZ + 500 ) / 1000 )\r
 205 \r
 206         #define FreeRTOS_max_BaseType(a, b)  ( ( ( BaseType_t  ) ( a ) ) >= ( ( BaseType_t  ) ( b ) ) ? ( ( BaseType_t  ) ( a ) ) : ( ( BaseType_t  ) ( b ) ) )\r
 207         #define FreeRTOS_max_UBaseType(a, b) ( ( ( UBaseType_t ) ( a ) ) >= ( ( UBaseType_t ) ( b ) ) ? ( ( UBaseType_t ) ( a ) ) : ( ( UBaseType_t ) ( b ) ) )\r
 208         #define FreeRTOS_min_BaseType(a, b)  ( ( ( BaseType_t  ) ( a ) ) <= ( ( BaseType_t  ) ( b ) ) ? ( ( BaseType_t  ) ( a ) ) : ( ( BaseType_t  ) ( b ) ) )\r
 209         #define FreeRTOS_min_UBaseType(a, b) ( ( ( UBaseType_t ) ( a ) ) <= ( ( UBaseType_t ) ( b ) ) ? ( ( UBaseType_t ) ( a ) ) : ( ( UBaseType_t ) ( b ) ) )\r
 210 \r
 211 #endif /* ipconfigHAS_INLINE_FUNCTIONS */\r
 212 \r
 213 #define pdMS_TO_MIN_TICKS( xTimeInMs ) ( pdMS_TO_TICKS( ( xTimeInMs ) ) < ( ( TickType_t ) 1 ) ? ( ( TickType_t ) 1 ) : pdMS_TO_TICKS( ( xTimeInMs ) ) )\r
 214 \r
 215 #ifndef pdTRUE_SIGNED\r
 216         /* Temporary solution: eventually the defines below will appear in 'Source\include\projdefs.h' */\r
 217         #define pdTRUE_SIGNED           pdTRUE\r
 218         #define pdFALSE_SIGNED          pdFALSE\r
 219         #define pdTRUE_UNSIGNED         ( ( UBaseType_t ) 1u )\r
 220         #define pdFALSE_UNSIGNED        ( ( UBaseType_t ) 0u )\r
 221 #endif\r
 222 \r
 223 /*\r
 224  * FULL, UP-TO-DATE AND MAINTAINED REFERENCE DOCUMENTATION FOR ALL THESE\r
 225  * FUNCTIONS IS AVAILABLE ON THE FOLLOWING URL:\r
 226  * http://www.FreeRTOS.org/FreeRTOS-Plus/FreeRTOS_Plus_TCP/FreeRTOS_TCP_API_Functions.html\r
 227  */\r
 228 BaseType_t FreeRTOS_IPInit( const uint8_t ucIPAddress[ ipIP_ADDRESS_LENGTH_BYTES ],\r
 229         const uint8_t ucNetMask[ ipIP_ADDRESS_LENGTH_BYTES ],\r
 230         const uint8_t ucGatewayAddress[ ipIP_ADDRESS_LENGTH_BYTES ],\r
 231         const uint8_t ucDNSServerAddress[ ipIP_ADDRESS_LENGTH_BYTES ],\r
 232         const uint8_t ucMACAddress[ ipMAC_ADDRESS_LENGTH_BYTES ] );\r
 233 \r
 234 void * FreeRTOS_GetUDPPayloadBuffer( size_t xRequestedSizeBytes, TickType_t xBlockTimeTicks );\r
 235 void FreeRTOS_GetAddressConfiguration( uint32_t *pulIPAddress, uint32_t *pulNetMask, uint32_t *pulGatewayAddress, uint32_t *pulDNSServerAddress );\r
 236 void FreeRTOS_SetAddressConfiguration( const uint32_t *pulIPAddress, const uint32_t *pulNetMask, const uint32_t *pulGatewayAddress, const uint32_t *pulDNSServerAddress );\r
 237 BaseType_t FreeRTOS_SendPingRequest( uint32_t ulIPAddress, size_t xNumberOfBytesToSend, TickType_t xBlockTimeTicks );\r
 238 void FreeRTOS_ReleaseUDPPayloadBuffer( void *pvBuffer );\r
 239 const uint8_t * FreeRTOS_GetMACAddress( void );\r
 240 void vApplicationIPNetworkEventHook( eIPCallbackEvent_t eNetworkEvent );\r
 241 void vApplicationPingReplyHook( ePingReplyStatus_t eStatus, uint16_t usIdentifier );\r
 242 uint32_t FreeRTOS_GetIPAddress( void );\r
 243 void FreeRTOS_SetIPAddress( uint32_t ulIPAddress );\r
 244 void FreeRTOS_SetNetmask( uint32_t ulNetmask );\r
 245 void FreeRTOS_SetGatewayAddress( uint32_t ulGatewayAddress );\r
 246 uint32_t FreeRTOS_GetGatewayAddress( void );\r
 247 uint32_t FreeRTOS_GetDNSServerAddress( void );\r
 248 uint32_t FreeRTOS_GetNetmask( void );\r
 249 void FreeRTOS_OutputARPRequest( uint32_t ulIPAddress );\r
 250 BaseType_t FreeRTOS_IsNetworkUp( void );\r
 251 \r
 252 #if( ipconfigCHECK_IP_QUEUE_SPACE != 0 )\r
 253         UBaseType_t uxGetMinimumIPQueueSpace( void );\r
 254 #endif\r
 255 \r
 256 /*\r
 257  * Defined in FreeRTOS_Sockets.c\r
 258  * //_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_.\r
 259  * Socket has had activity, reset the timer so it will not be closed\r
 260  * because of inactivity\r
 261  */\r
 262 const char *FreeRTOS_GetTCPStateName( UBaseType_t ulState);\r
 263 \r
 264 /* _HT_ Temporary: show all valid ARP entries\r
 265  */\r
 266 void FreeRTOS_PrintARPCache( void );\r
 267 void FreeRTOS_ClearARP( void );\r
 268 \r
 269 #if( ipconfigDHCP_REGISTER_HOSTNAME == 1 )\r
 270 \r
 271         /* DHCP has an option for clients to register their hostname.  It doesn't\r
 272         have much use, except that a device can be found in a router along with its\r
 273         name. If this option is used the callback below must be provided by the\r
 274         application     writer to return a const string, denoting the device's name. */\r
 275         const char *pcApplicationHostnameHook( void );\r
 276 \r
 277 #endif /* ipconfigDHCP_REGISTER_HOSTNAME */\r
 278 \r
 279 \r
 280 /* For backward compatibility define old structure names to the newer equivalent\r
 281 structure name. */\r
 282 #ifndef ipconfigENABLE_BACKWARD_COMPATIBILITY\r
 283         #define ipconfigENABLE_BACKWARD_COMPATIBILITY   1\r
 284 #endif\r
 285 \r
 286 #if( ipconfigENABLE_BACKWARD_COMPATIBILITY == 1 )\r
 287         #define xIPStackEvent_t                         IPStackEvent_t\r
 288         #define xNetworkBufferDescriptor_t      NetworkBufferDescriptor_t\r
 289         #define xMACAddress_t                           MACAddress_t\r
 290         #define xWinProperties_t                        WinProperties_t\r
 291         #define xSocket_t                                       Socket_t\r
 292         #define xSocketSet_t                            SocketSet_t\r
 293         #define ipSIZE_OF_IP_HEADER                     ipSIZE_OF_IPv4_HEADER\r
 294 \r
 295         /* Since August 2016, the public types and fields below have changed name:\r
 296         abbreviations TCP/UDP are now written in capitals, and type names now end with "_t". */\r
 297         #define FOnConnected                            FOnConnected_t\r
 298         #define FOnTcpReceive                           FOnTCPReceive_t\r
 299         #define FOnTcpSent                                      FOnTCPSent_t\r
 300         #define FOnUdpReceive                           FOnUDPReceive_t\r
 301         #define FOnUdpSent                                      FOnUDPSent_t\r
 302 \r
 303         #define pOnTcpConnected                         pxOnTCPConnected\r
 304         #define pOnTcpReceive                           pxOnTCPReceive\r
 305         #define pOnTcpSent                                      pxOnTCPSent\r
 306         #define pOnUdpReceive                           pxOnUDPReceive\r
 307         #define pOnUdpSent                                      pxOnUDPSent\r
 308 \r
 309         #define FOnUdpSent                                      FOnUDPSent_t\r
 310         #define FOnTcpSent                                      FOnTCPSent_t\r
 311 #endif /* ipconfigENABLE_BACKWARD_COMPATIBILITY */\r
 312 \r
 313 #ifdef __cplusplus\r
 314 } /* extern "C" */\r
 315 #endif\r
 316 \r
 317 #endif /* FREERTOS_IP_H */\r
 318 \r
 319 \r
 320 \r
 321 \r
 322 \r
 323 \r
 324 \r
 325 \r
 326 \r
 327 \r
 328 \r
 329 \r
 330 \r