src/inet/InetConfig.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2013-2018 Nest Labs, Inc.
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      This file defines default compile-time configuration constants
  22  *      for the CHIP InetLayer, an Internet Protocol communications
  23  *      abstraction layer.
  24  *
  25  *      Package integrators that wish to override these values should
  26  *      either use preprocessor definitions or create a project-
  27  *      specific InetProjectConfig.h header and then assert
  28  *      HAVE_INETPROJECTCONFIG_H via the package configuration tool
  29  *      via --with-chip-inet-project-includes=DIR where DIR is the
  30  *      directory that contains the header.
  31  *
  32  *  NOTE WELL: On some platforms, this header is included by C-language programs.
  33  *
  34  */
  35
  36 #pragma once
  37
  38 #if CHIP_HAVE_CONFIG_H
  39 #include <inet/InetBuildConfig.h>
  40 #endif
  41
  42 /*--- Include configuration headers ---*/
  43 #include <system/SystemConfig.h>
  44
  45 /*
  46  * If the CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION option is not applicable, then the "InetProjectConfig.h"
  47  * header was not included by <SystemLayer/SystemConfig.h> and therefore it must be included here.
  48  */
  49 #if !CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
  50
  51 /* Include a project-specific configuration file, if defined.
  52  *
  53  * An application or module that incorporates chip can define a project configuration
  54  * file to override standard Inet Layer configuration with application-specific values.
  55  * The project config file is typically located outside the Openchip source tree,
  56  * alongside the source code for the application.
  57  */
  58 #ifdef INET_PROJECT_CONFIG_INCLUDE
  59 #include INET_PROJECT_CONFIG_INCLUDE
  60 #endif // INET_PROJECT_CONFIG_INCLUDE
  61
  62 #endif // !CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
  63
  64 /* Include a platform-specific configuration file, if defined.
  65  *
  66  * A platform configuration file contains overrides to standard Inet Layer configuration
  67  * that are specific to the platform or OS on which chip is running.  It is typically
  68  * provided as apart of an adaptation layer that adapts Openchip to the target
  69  * environment.  This adaptation layer may be included in the Openchip source tree
  70  * itself or implemented externally.
  71  */
  72 #ifdef INET_PLATFORM_CONFIG_INCLUDE
  73 #include INET_PLATFORM_CONFIG_INCLUDE
  74 #endif
  75
  76 // clang-format off
  77
  78 /**
  79  *  @def INET_CONFIG_MAX_IP_AND_UDP_HEADER_SIZE
  80  *
  81  *  @brief
  82  *    The maximum space required for IPv6 and UDP headers.
  83  *    Useful when ensuring a chip message will not exceed a UDP MTU.
  84  *
  85  */
  86 #ifndef INET_CONFIG_MAX_IP_AND_UDP_HEADER_SIZE
  87 #define INET_CONFIG_MAX_IP_AND_UDP_HEADER_SIZE              (40 + 8)
  88 #endif // INET_CONFIG_MAX_IP_AND_UDP_HEADER_SIZE
  89
  90 /**
  91  *  @def INET_CONFIG_ERROR_TYPE
  92  *
  93  *  @brief
  94  *    This defines the data type used to represent errors for the
  95  *    InetLayer subsystem.
  96  *
  97  *  @note
  98  *    By default, this parameter is a copy of CHIP_SYSTEM_CONFIG_ERROR_TYPE.
  99  *
 100  */
 101 #ifndef INET_CONFIG_ERROR_TYPE
 102 #define INET_CONFIG_ERROR_TYPE                              CHIP_SYSTEM_CONFIG_ERROR_TYPE
 103 #endif // !defined(INET_CONFIG_ERROR_TYPE)
 104
 105 /**
 106  *  @def INET_CONFIG_NO_ERROR
 107  *
 108  *  @brief
 109  *    This defines the InetLayer error code for no error or success.
 110  *
 111  *  @note
 112  *    By default, this parameter is a copy of CHIP_SYSTEM_CONFIG_NO_ERROR.
 113  *
 114  */
 115 #ifndef INET_CONFIG_NO_ERROR
 116 #define INET_CONFIG_NO_ERROR                                CHIP_SYSTEM_CONFIG_NO_ERROR
 117 #endif // !defined(INET_CONFIG_NO_ERROR)
 118
 119 /**
 120  *  @def INET_CONFIG_ERROR_MIN
 121  *
 122  *  @brief
 123  *    This defines the base or minimum InetLayer error number range.
 124  *
 125  */
 126 #ifndef INET_CONFIG_ERROR_MIN
 127 #define INET_CONFIG_ERROR_MIN                               1000
 128 #endif // INET_CONFIG_ERROR_MIN
 129
 130 /**
 131  *  @def INET_CONFIG_ERROR_MAX
 132  *
 133  *  @brief
 134  *    This defines the top or maximum InetLayer error number range.
 135  *
 136  */
 137 #ifndef INET_CONFIG_ERROR_MAX
 138 #define INET_CONFIG_ERROR_MAX                               1999
 139 #endif // INET_CONFIG_ERROR_MAX
 140
 141 /**
 142  *  @def _INET_CONFIG_ERROR
 143  *
 144  *  @brief
 145  *    This defines a mapping function for InetLayer errors that allows
 146  *    mapping such errors into a platform- or system-specific range.
 147  *
 148  */
 149 #ifndef _INET_CONFIG_ERROR
 150 #define _INET_CONFIG_ERROR(e)                               (INET_ERROR_MIN + (e))
 151 #endif // _INET_CONFIG_ERROR
 152
 153 /**
 154  *  @def INET_CONFIG_WILL_OVERRIDE_OS_ERROR_FUNCS
 155  *
 156  *  @brief
 157  *    This defines whether (1) or not (0) your platform will override
 158  *    the platform- and system-specific INET_MapOSError,
 159  *    INET_DescribeOSError, and INET_IsOSError functions.
 160  *
 161  */
 162 #ifndef INET_CONFIG_WILL_OVERRIDE_OS_ERROR_FUNCS
 163 #define INET_CONFIG_WILL_OVERRIDE_OS_ERROR_FUNCS            0
 164 #endif // INET_CONFIG_WILL_OVERRIDE_OS_ERROR_FUNCS
 165
 166 /**
 167  *  @def INET_CONFIG_WILL_OVERRIDE_LWIP_ERROR_FUNCS
 168  *
 169  *  @brief
 170  *    This defines whether (1) or not (0) your platform will override
 171  *    the platform- and system-specific INET_MapLwIPError,
 172  *    INET_DescribeLwIPError, and INET_IsLwIPError functions.
 173  *
 174  */
 175 #ifndef INET_CONFIG_WILL_OVERRIDE_LWIP_ERROR_FUNCS
 176 #define INET_CONFIG_WILL_OVERRIDE_LWIP_ERROR_FUNCS          0
 177 #endif // INET_CONFIG_WILL_OVERRIDE_LWIP_ERROR_FUNCS
 178
 179 /**
 180  *  @def INET_CONFIG_WILL_OVERRIDE_PLATFORM_XTOR_FUNCS
 181  *
 182  *  @brief
 183  *    This defines whether (1) or not (0) your platform will override
 184  *    the platform- and system-specific InetLayer WillInit, DidInit,
 185  *    WillShutdown, and DidShutdown.
 186  *
 187  */
 188 #ifndef INET_CONFIG_WILL_OVERRIDE_PLATFORM_XTOR_FUNCS
 189 #define INET_CONFIG_WILL_OVERRIDE_PLATFORM_XTOR_FUNCS       0
 190 #endif // INET_CONFIG_WILL_OVERRIDE_PLATFORM_XTOR_FUNCS
 191
 192 /**
 193  *  @def INET_CONFIG_MAX_DROPPABLE_EVENTS
 194  *
 195  *  @brief
 196  *    This is the maximum number of UDP or raw network transport
 197  *    packet events / messages that may be dropped due to packet
 198  *    buffer starvation.
 199  *
 200  *    In some implementations, there may be a shared event / message
 201  *    queue for the InetLayer used by other system events / messages.
 202  *
 203  *    If the length of that queue is considerably longer than the
 204  *    number of packet buffers available, it may lead to buffer
 205  *    exhaustion. As a result, using the queue itself to implement
 206  *    backpressure is insufficient, and we need an external mechanism
 207  *    to prevent buffer starvation in the rest of the system and
 208  *    getting into deadlock situations.
 209  *
 210  *    For both UDP and raw network transport traffic we can easily
 211  *    drop incoming packets without impacting the correctness of
 212  *    higher level protocols.
 213  *
 214  */
 215 #ifndef INET_CONFIG_MAX_DROPPABLE_EVENTS
 216 #define INET_CONFIG_MAX_DROPPABLE_EVENTS                    0
 217 #endif // INET_CONFIG_MAX_DROPPABLE_EVENTS
 218
 219 /**
 220  *  @def INET_CONFIG_NUM_RAW_ENDPOINTS
 221  *
 222  *  @brief
 223  *    This is the total number of "raw" (direct-IP, non-TCP/-UDP) end
 224  *    point context structures.
 225  *
 226  *    Up to this many outstanding "raw" communication flows may be in
 227  *    use.
 228  *
 229  */
 230 #ifndef INET_CONFIG_NUM_RAW_ENDPOINTS
 231 #define INET_CONFIG_NUM_RAW_ENDPOINTS                       8
 232 #endif // INET_CONFIG_NUM_RAW_ENDPOINTS
 233
 234 /**
 235  *  @def INET_CONFIG_NUM_TCP_ENDPOINTS
 236  *
 237  *  @brief
 238  *    This is the total number of TCP end point context structures.
 239  *
 240  *    Up to this many outstanding TCP communication flows may be in
 241  *    use.
 242  *
 243  */
 244 #ifndef INET_CONFIG_NUM_TCP_ENDPOINTS
 245 #define INET_CONFIG_NUM_TCP_ENDPOINTS                       64
 246 #endif // INET_CONFIG_NUM_TCP_ENDPOINTS
 247
 248 /**
 249  *  @def INET_CONFIG_NUM_UDP_ENDPOINTS
 250  *
 251  *  @brief
 252  *    This is the total number of UDP end point context structures.
 253  *
 254  *    Up to this many outstanding UDP communication flows may be in
 255  *    use.
 256  *
 257  */
 258 #ifndef INET_CONFIG_NUM_UDP_ENDPOINTS
 259 #define INET_CONFIG_NUM_UDP_ENDPOINTS                       64
 260 #endif // INET_CONFIG_NUM_UDP_ENDPOINTS
 261
 262 /**
 263  *  @def INET_CONFIG_NUM_DNS_RESOLVERS
 264  *
 265  *  @brief
 266  *    This is the total number of outstanding DNS resolution request
 267  *    contexts.
 268  *
 269  *    Up to this many DNS resolution requests may be in in use.
 270  *
 271  */
 272 #ifndef INET_CONFIG_NUM_DNS_RESOLVERS
 273 #define INET_CONFIG_NUM_DNS_RESOLVERS                       4
 274 #endif // INET_CONFIG_NUM_DNS_RESOLVERS
 275
 276 /**
 277  *  @def INET_CONFIG_MAX_DNS_ADDRS
 278  *
 279  *  @brief
 280  *    This is the maximum allowable number of addresses that may
 281  *    be returned in a single DNS hostname lookup.
 282  *
 283  */
 284 #ifndef INET_CONFIG_MAX_DNS_ADDRS
 285 #define INET_CONFIG_MAX_DNS_ADDRS                           16
 286 #endif // INET_CONFIG_MAX_DNS_ADDRS
 287
 288 /**
 289  *  @def INET_TCP_IDLE_CHECK_INTERVAL
 290  *
 291  *  @brief
 292  *    This is the interval, in milliseconds, at which checks are made
 293  *    to detect idle TCP connections.
 294  *
 295  */
 296 #ifndef INET_TCP_IDLE_CHECK_INTERVAL
 297 #define INET_TCP_IDLE_CHECK_INTERVAL                        100
 298 #endif // INET_TCP_IDLE_CHECK_INTERVAL
 299
 300 /**
 301  *  @def INET_CONFIG_ENABLE_DNS_RESOLVER
 302  *
 303  *  @brief
 304  *    Defines whether (1) or not (0) to enable the ability
 305  *    to instantiate the DNS resolver.
 306  *
 307  */
 308 #ifndef INET_CONFIG_ENABLE_DNS_RESOLVER
 309 #define INET_CONFIG_ENABLE_DNS_RESOLVER                     0
 310 #endif // INET_CONFIG_ENABLE_DNS_RESOLVER
 311
 312 /**
 313  *  @def INET_CONFIG_ENABLE_RAW_ENDPOINT
 314  *
 315  *  @brief
 316  *    Defines whether (1) or not (0) to enable the ability
 317  *    to instantiate a Raw endpoint.
 318  *
 319  */
 320 #ifndef INET_CONFIG_ENABLE_RAW_ENDPOINT
 321 #define INET_CONFIG_ENABLE_RAW_ENDPOINT                     0
 322 #endif // INET_CONFIG_ENABLE_RAW_ENDPOINT
 323
 324 /**
 325  *  @def INET_CONFIG_ENABLE_TCP_ENDPOINT
 326  *
 327  *  @brief
 328  *    Defines whether (1) or not (0) to enable the ability
 329  *    to instantiate a TCP endpoint.
 330  *
 331  */
 332 #ifndef INET_CONFIG_ENABLE_TCP_ENDPOINT
 333 #define INET_CONFIG_ENABLE_TCP_ENDPOINT                     0
 334 #endif // INET_CONFIG_ENABLE_TCP_ENDPOINT
 335
 336 /**
 337  *  @def INET_CONFIG_ENABLE_UDP_ENDPOINT
 338  *
 339  *  @brief
 340  *    Defines whether (1) or not (0) to enable the ability
 341  *    to instantiate a UDP endpoint.
 342  *
 343  */
 344 #ifndef INET_CONFIG_ENABLE_UDP_ENDPOINT
 345 #define INET_CONFIG_ENABLE_UDP_ENDPOINT                     0
 346 #endif // INET_CONFIG_ENABLE_UDP_ENDPOINT
 347
 348 /**
 349  *  @def INET_CONFIG_EVENT_RESERVED
 350  *
 351  *  @brief
 352  *      This defines the first number in the default chip System Layer event code space reserved for use by the Inet Layer.
 353  *      Event codes used by each layer must not overlap.
 354  */
 355 #ifndef INET_CONFIG_EVENT_RESERVED
 356 #define INET_CONFIG_EVENT_RESERVED                          1000
 357 #endif /* INET_CONFIG_EVENT_RESERVED */
 358
 359 /**
 360  *  @def _INET_CONFIG_EVENT
 361  *
 362  *  @brief
 363  *    This defines a mapping function for InetLayer event types that allows
 364  *    mapping such event types into a platform- or system-specific range.
 365  *
 366  *  @note
 367  *    By default, this definition is a copy of _CHIP_SYSTEM_CONFIG_LWIP_EVENT.
 368  *
 369  */
 370 #ifndef _INET_CONFIG_EVENT
 371 #define _INET_CONFIG_EVENT(e)                               _CHIP_SYSTEM_CONFIG_LWIP_EVENT(INET_CONFIG_EVENT_RESERVED + (e))
 372 #endif // _INET_CONFIG_EVENT
 373
 374 /**
 375  *  @def INET_CONFIG_TEST
 376  *
 377  *  @brief
 378  *    Defines whether (1) or not (0) to enable testing aids
 379  */
 380 #ifndef INET_CONFIG_TEST
 381 #define INET_CONFIG_TEST                                   0
 382 #endif
 383
 384 /**
 385  * @def INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
 386  *
 387  * @brief Enable asynchronous dns name resolution for Linux sockets.
 388  */
 389 #ifndef INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
 390 #define INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS               1
 391 #endif // INET_CONFIG_ENABLE_ASYNC_DNS_SOCKETS
 392
 393 /**
 394  * @def INET_CONFIG_DNS_ASYNC_MAX_THREAD_COUNT
 395  *
 396  * @brief The maximum number of POSIX threads that would be performing
 397  * asynchronous DNS resolution.
 398  */
 399 #ifndef INET_CONFIG_DNS_ASYNC_MAX_THREAD_COUNT
 400 #define INET_CONFIG_DNS_ASYNC_MAX_THREAD_COUNT             2
 401 #endif // INET_CONFIG_DNS_ASYNC_MAX_THREAD_COUNT
 402
 403 /**
 404  *  @def INET_CONFIG_OVERRIDE_SYSTEM_TCP_USER_TIMEOUT
 405  *
 406  *  @brief
 407  *    When this flag is set, the InetLayer implements
 408  *    a mechanism that simulates the TCP_USER_TIMEOUT
 409  *    socket option for Linux sockets.
 410  *
 411  *  @details
 412  *    The TCP_USER_TIMEOUT option specifies the maximum
 413  *    amount of time in milliseconds that transmitted
 414  *    data may remain unacknowledged before TCP will
 415  *    forcibly close the corresponding connection.
 416  *    See RFC 5482, for further details.
 417  *
 418  *    This flag is set to override the usage of the system
 419  *    defined TCP_USER_TIMEOUT socket option for Linux.
 420  *    The reason for having this overriding feature
 421  *    was to overcome some limitations of the system
 422  *    socket option wherein the TCP_USER_TIMEOUT was
 423  *    not taking effect when
 424  *    1) The IP address of the interface of the TCP
 425  *       connection was removed.
 426  *    2) The interface of the TCP connection was
 427  *       brought down.
 428  *
 429  */
 430 #ifndef INET_CONFIG_OVERRIDE_SYSTEM_TCP_USER_TIMEOUT
 431 #define INET_CONFIG_OVERRIDE_SYSTEM_TCP_USER_TIMEOUT       1
 432 #endif // INET_CONFIG_OVERRIDE_SYSTEM_TCP_USER_TIMEOUT
 433
 434 /**
 435  *  @def INET_CONFIG_ENABLE_TCP_SEND_IDLE_CALLBACKS
 436  *
 437  *  @brief
 438  *    When this flag is set, the InetLayer enables
 439  *    callbacks to the upper layer notifying it when
 440  *    the send channel of the TCP connection changes
 441  *    between being idle or not idle.
 442  *
 443  *  @note
 444  *    When enabled, the TCP send queue is actively
 445  *    polled to determine if sent data has been
 446  *    acknowledged.
 447  *
 448  */
 449 #ifndef INET_CONFIG_ENABLE_TCP_SEND_IDLE_CALLBACKS
 450 #define INET_CONFIG_ENABLE_TCP_SEND_IDLE_CALLBACKS         0
 451 #endif // INET_CONFIG_ENABLE_TCP_SEND_IDLE_CALLBACKS
 452
 453 /**
 454  *  @def INET_CONFIG_TCP_SEND_QUEUE_POLL_INTERVAL_MSEC
 455  *
 456  *  @brief
 457  *    The default polling interval to check the progress
 458  *    on the TCP SendQueue to determine if sent data is
 459  *    being acknowledged.
 460  *
 461  *  @details
 462  *    If progress is being made, then the TCP UserTimeout
 463  *    period would be shifted further ahead by resetting
 464  *    the max poll count. If, however, progress is not made,
 465  *    then the next timer would still fire at the next poll
 466  *    interval without resetting the poll count. The
 467  *    connection would be torn down when the poll count
 468  *    reaches zero.
 469  */
 470 #ifndef INET_CONFIG_TCP_SEND_QUEUE_POLL_INTERVAL_MSEC
 471 #define INET_CONFIG_TCP_SEND_QUEUE_POLL_INTERVAL_MSEC      500
 472 #endif // INET_CONFIG_TCP_SEND_QUEUE_POLL_INTERVAL_MSEC
 473
 474 /**
 475  *  @def INET_CONFIG_DEFAULT_TCP_USER_TIMEOUT_MSEC
 476  *
 477  *  @brief
 478  *    The default value of the TCP_USER_TIMEOUT in
 479  *    milliseconds. Set to equivalent of 5 minutes.
 480  *
 481  *
 482  *  @details
 483  *    This value specifies the maximum amount of
 484  *    time in milliseconds that transmitted data may remain
 485  *    unacknowledged before TCP will forcibly close the
 486  *    corresponding connection.
 487  *    See RFC 5482, for further details.
 488  */
 489 #ifndef INET_CONFIG_DEFAULT_TCP_USER_TIMEOUT_MSEC
 490 #define INET_CONFIG_DEFAULT_TCP_USER_TIMEOUT_MSEC          (5 * 60 * 1000)
 491 #endif // INET_CONFIG_DEFAULT_TCP_USER_TIMEOUT_MSEC
 492
 493 /**
 494  *  @def INET_CONFIG_IP_MULTICAST_HOP_LIMIT
 495  *
 496  *  @brief
 497  *    The default value of the Hop Limit field in
 498  *    the IP multicast packet.
 499  *
 500  *
 501  *  @details
 502  *    This value specifies the hop limit that could be set in the
 503  *    outgoing IP packet to override any default settings(made by
 504  *    the kernel) for the hop limit field in the IP header.
 505  *    On Linux platforms, the hoplimit field is set to 1 for
 506  *    multicast packets.
 507  */
 508 #ifndef INET_CONFIG_IP_MULTICAST_HOP_LIMIT
 509 #define INET_CONFIG_IP_MULTICAST_HOP_LIMIT                 (64)
 510 #endif // INET_CONFIG_IP_MULTICAST_HOP_LIMIT
 511 // clang-format on