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

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