src/system/SystemConfig.h

   1 /*
   2  *
   3  *    Copyright (c) 2020-2021 Project CHIP Authors
   4  *    Copyright (c) 2016-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 contains default compile-time configuration
  22  *      constants for the  CHIP System Layer, a common
  23  *      abstraction layer for the system networking components
  24  *      underlying the various CHIP target network layers.
  25  *
  26  *      Package integrators that wish to override these values should
  27  *      either use preprocessor definitions or create a project-
  28  *      specific SystemProjectConfig.h header and then assert
  29  *      HAVE_SYSTEMPROJECTCONFIG_H via the package configuration tool
  30  *      via --with-chip-system-project-includes=DIR where DIR is
  31  *      the directory that contains the header.
  32  *
  33  *      NOTE WELL: On some platforms, this header is included by
  34  *      C-language programs.
  35  */
  36
  37 #pragma once
  38
  39 /* Platform include headers */
  40 #if CHIP_HAVE_CONFIG_H
  41 #include <system/SystemBuildConfig.h>
  42 #endif
  43
  44 /* Include a CHIP project-specific configuration file, if defined.
  45  *
  46  * An application or module that incorporates CHIP can define a project
  47  * configuration file to override standard CHIP configuration with
  48  * application-specific values.  The CHIPProjectConfig.h file is typically
  49  * located outside the CHIP source tree, alongside the source code for the
  50  * application.  The config file is included here to enable certain system-wide
  51  * configuration options, primarily related to logging and error reporting.
  52  */
  53 #ifdef CHIP_PROJECT_CONFIG_INCLUDE
  54 #include CHIP_PROJECT_CONFIG_INCLUDE
  55 #endif
  56
  57 /* Include a CHIP platform-specific configuration file, if defined.
  58  *
  59  * A platform configuration file contains overrides to standard CHIP
  60  * configuration that are specific to the platform or OS on which CHIP is
  61  * running.  It is typically provided as apart of an adaptation layer that
  62  * adapts CHIP to the target environment.  This adaptation layer may be
  63  * included in the CHIP source tree itself or implemented externally.  The
  64  * config file is included here to enable certain system-wide configuration
  65  * options, primarily related to logging and error reporting.
  66  */
  67 #ifdef CHIP_PLATFORM_CONFIG_INCLUDE
  68 #include CHIP_PLATFORM_CONFIG_INCLUDE
  69 #endif
  70
  71 /* Include a SystemLayer project-specific configuration file, if defined.
  72  *
  73  * An application or module that incorporates CHIP can define a project configuration
  74  * file to override standard System Layer configuration with application-specific values.
  75  * The project config file is typically located outside the CHIP source tree,
  76  * alongside the source code for the application.
  77  */
  78 #ifdef SYSTEM_PROJECT_CONFIG_INCLUDE
  79 #include SYSTEM_PROJECT_CONFIG_INCLUDE
  80 #endif // SYSTEM_PROJECT_CONFIG_INCLUDE
  81
  82 /* Include a SystemLayer platform-specific configuration file, if defined.
  83  *
  84  * A platform configuration file contains overrides to standard System Layer configuration
  85  * that are specific to the platform or OS on which CHIP is running.  It is typically
  86  * provided as apart of an adaptation layer that adapts CHIP to the target
  87  * environment.  This adaptation layer may be included in the CHIP source tree
  88  * itself or implemented externally.
  89  */
  90 #ifdef SYSTEM_PLATFORM_CONFIG_INCLUDE
  91 #include SYSTEM_PLATFORM_CONFIG_INCLUDE
  92 #endif
  93
  94 /*--- Sanity check on the build configuration logic. ---*/
  95
  96 #if !(CHIP_SYSTEM_CONFIG_USE_LWIP || CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK)
  97 #error "REQUIRED: CHIP_SYSTEM_CONFIG_USE_LWIP || CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK"
  98 #endif // !(CHIP_SYSTEM_CONFIG_USE_LWIP || CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_USE_NETWORK_FRAMEWORK)
  99
 100 #if CHIP_SYSTEM_CONFIG_USE_LWIP && CHIP_SYSTEM_CONFIG_USE_SOCKETS
 101 #error "FORBIDDEN: CHIP_SYSTEM_CONFIG_USE_LWIP && CHIP_SYSTEM_CONFIG_USE_SOCKETS"
 102 #endif // CHIP_SYSTEM_CONFIG_USE_LWIP && CHIP_SYSTEM_CONFIG_USE_SOCKETS
 103
 104 #if CHIP_SYSTEM_CONFIG_USE_LWIP && CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK
 105 #error "FORBIDDEN: CHIP_SYSTEM_CONFIG_USE_LWIP && CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK"
 106 #endif // CHIP_SYSTEM_CONFIG_USE_LWIP && CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK
 107
 108 #if CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK && CHIP_SYSTEM_CONFIG_USE_SOCKETS
 109 #error "FORBIDDEN: CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK && CHIP_SYSTEM_CONFIG_USE_SOCKETS"
 110 #endif // CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK && CHIP_SYSTEM_CONFIG_USE_SOCKETS
 111
 112 // clang-format off
 113
 114 /**
 115  *  @def CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
 116  *
 117  *  @brief
 118  *      Define as 1 to transfer the project configuration variable definitions from InetProjectConfig.h into the corresponding
 119  *      variables for the CHIP System Layer.
 120  */
 121 #ifndef CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
 122 #define CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION 0
 123 #endif // CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
 124
 125 #if CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
 126 #ifdef INET_PROJECT_CONFIG_INCLUDE
 127 #include INET_PROJECT_CONFIG_INCLUDE
 128 #endif // INET_PROJECT_CONFIG_INCLUDE
 129
 130 #if !defined(CHIP_SYSTEM_CONFIG_POSIX_LOCKING) && defined(INET_CONFIG_POSIX_LOCKING)
 131 #define CHIP_SYSTEM_CONFIG_POSIX_LOCKING INET_CONFIG_POSIX_LOCKING
 132 #endif // !defined(CHIP_SYSTEM_CONFIG_POSIX_LOCKING) && defined(INET_CONFIG_POSIX_LOCKING)
 133
 134 #if !defined(CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING) && defined(INET_CONFIG_FREERTOS_LOCKING)
 135 #define CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING INET_CONFIG_FREERTOS_LOCKING
 136 #endif // !defined(CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING) && defined(INET_CONFIG_FREERTOS_LOCKING)
 137
 138 #if !defined(CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE) && defined(INET_CONFIG_NUM_BUFS)
 139 #define CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE INET_CONFIG_NUM_BUFS
 140 #endif // !defined(CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE) && defined(INET_CONFIG_NUM_BUFS)
 141
 142 #if !defined(CHIP_SYSTEM_CONFIG_NUM_TIMERS) && defined(INET_CONFIG_NUM_TIMERS)
 143 #define CHIP_SYSTEM_CONFIG_NUM_TIMERS INET_CONFIG_NUM_TIMERS
 144 #endif // !defined(CHIP_SYSTEM_CONFIG_NUM_TIMERS) && defined(INET_CONFIG_NUM_TIMERS)
 145
 146 #endif // CHIP_SYSTEM_CONFIG_TRANSFER_INETLAYER_PROJECT_CONFIGURATION
 147
 148 /* Standard include headers */
 149 #ifndef CHIP_SYSTEM_CONFIG_ERROR_TYPE
 150 #include <stdint.h>
 151 #endif /* CHIP_SYSTEM_CONFIG_ERROR_TYPE */
 152
 153 #if CHIP_SYSTEM_CONFIG_USE_LWIP
 154 #include <lwip/opt.h>
 155 #endif // CHIP_SYSTEM_CONFIG_USE_LWIP
 156
 157 /* Configuration option variables defined below */
 158
 159 /**
 160  *  @def CHIP_SYSTEM_CONFIG_NO_LOCKING
 161  *
 162  *  @brief
 163  *      Disable the use of locking within the system layer.
 164  *
 165  *      Unless you are simulating an LwIP-based system on a Unix-style host, this value should be left at its default.
 166  */
 167 #ifndef CHIP_SYSTEM_CONFIG_NO_LOCKING
 168 #define CHIP_SYSTEM_CONFIG_NO_LOCKING 0
 169 #endif /* CHIP_SYSTEM_CONFIG_NO_LOCKING */
 170
 171 /**
 172  *  @def CHIP_SYSTEM_CONFIG_POSIX_LOCKING
 173  *
 174  *  @brief
 175  *      Use POSIX locking. This is enabled by default when not compiling for BSD sockets.
 176  *
 177  *      Unless you are simulating an LwIP-based system on a Unix-style host, this value should be left at its default.
 178  */
 179 #ifndef CHIP_SYSTEM_CONFIG_POSIX_LOCKING
 180 #define CHIP_SYSTEM_CONFIG_POSIX_LOCKING 1
 181 #endif /* CHIP_SYSTEM_CONFIG_POSIX_LOCKING */
 182
 183 /**
 184  *  @def CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING
 185  *
 186  *  @brief
 187  *      Use FreeRTOS locking.
 188  *
 189  *      This should be generally asserted (1) for FreeRTOS + LwIP-based systems and deasserted (0) for BSD sockets-based systems.
 190  *
 191  *      However, if you are simulating an LwIP-based system atop POSIX threads and BSD sockets, this should also be deasserted (0).
 192  */
 193 #ifndef CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING
 194 #define CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING 0
 195 #endif /* CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING */
 196
 197 /**
 198  *  @def CHIP_SYSTEM_CONFIG_NO_LOCKING
 199  *
 200  *  @brief
 201  *      Disable the use of locking within the system layer.
 202  *
 203  *      This value is mutually exclusive with CHIP_SYSTEM_CONFIG_POSIX_LOCKING and CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING.
 204  */
 205 #ifndef CHIP_SYSTEM_CONFIG_NO_LOCKING
 206 #define CHIP_SYSTEM_CONFIG_NO_LOCKING 0
 207 #endif /* CHIP_SYSTEM_CONFIG_NO_LOCKING */
 208
 209 #if !(CHIP_SYSTEM_CONFIG_POSIX_LOCKING || CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING || CHIP_SYSTEM_CONFIG_NO_LOCKING)
 210 #error "REQUIRED: CHIP_SYSTEM_CONFIG_POSIX_LOCKING || CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING || CHIP_SYSTEM_CONFIG_NO_LOCKING"
 211 #endif // !(CHIP_SYSTEM_CONFIG_POSIX_LOCKING || CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING || CHIP_SYSTEM_CONFIG_NO_LOCKING)
 212
 213 #if CHIP_SYSTEM_CONFIG_NO_LOCKING && (CHIP_SYSTEM_CONFIG_POSIX_LOCKING || CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING)
 214 #error "FORBIDDEN: CHIP_SYSTEM_CONFIG_NO_LOCKING && (CHIP_SYSTEM_CONFIG_POSIX_LOCKING || CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING)"
 215 #endif // CHIP_SYSTEM_CONFIG_NO_LOCKING && (CHIP_SYSTEM_CONFIG_POSIX_LOCKING || CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING)
 216
 217 #if CHIP_SYSTEM_CONFIG_POSIX_LOCKING && CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING
 218 #error "FORBIDDEN: CHIP_SYSTEM_CONFIG_POSIX_LOCKING && CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING"
 219 #endif // CHIP_SYSTEM_CONFIG_POSIX_LOCKING && CHIP_SYSTEM_CONFIG_FREERTOS_LOCKING
 220
 221 #ifndef CHIP_SYSTEM_CONFIG_ERROR_TYPE
 222
 223 /**
 224  *  @def CHIP_SYSTEM_CONFIG_ERROR_TYPE
 225  *
 226  *  @brief
 227  *      This defines the data type used to represent errors for the CHIP System Layer subsystem.
 228  */
 229 #define CHIP_SYSTEM_CONFIG_ERROR_TYPE int32_t
 230
 231 /**
 232  *  @def CHIP_SYSTEM_CONFIG_NO_ERROR
 233  *
 234  *  @brief
 235  *      This defines the CHIP System Layer error code for no error or success.
 236  */
 237 #ifndef CHIP_SYSTEM_CONFIG_NO_ERROR
 238 #define CHIP_SYSTEM_CONFIG_NO_ERROR 0
 239 #endif /* CHIP_SYSTEM_CONFIG_NO_ERROR */
 240
 241 /**
 242  *  @def CHIP_SYSTEM_CONFIG_ERROR_MIN
 243  *
 244  *  @brief
 245  *      This defines the base or minimum CHIP System Layer error number range.
 246  */
 247 #ifndef CHIP_SYSTEM_CONFIG_ERROR_MIN
 248 #define CHIP_SYSTEM_CONFIG_ERROR_MIN 7000
 249 #endif /* CHIP_SYSTEM_CONFIG_ERROR_MIN */
 250
 251 /**
 252  *  @def CHIP_SYSTEM_CONFIG_ERROR_MAX
 253  *
 254  *  @brief
 255  *      This defines the top or maximum CHIP System Layer error number range.
 256  */
 257 #ifndef CHIP_SYSTEM_CONFIG_ERROR_MAX
 258 #define CHIP_SYSTEM_CONFIG_ERROR_MAX 7999
 259 #endif /* CHIP_SYSTEM_CONFIG_ERROR_MAX */
 260
 261 /**
 262  *  @def _CHIP_SYSTEM_CONFIG_ERROR
 263  *
 264  *  @brief
 265  *      This defines a mapping function for CHIP System Layer errors that allows mapping such errors into a platform- or
 266  *      system-specific range.
 267  */
 268 #ifndef _CHIP_SYSTEM_CONFIG_ERROR
 269 #define _CHIP_SYSTEM_CONFIG_ERROR(e) (CHIP_SYSTEM_CONFIG_ERROR_MIN + (e))
 270 #endif /* _CHIP_SYSTEM_CONFIG_ERROR */
 271
 272 #endif /* CHIP_SYSTEM_CONFIG_ERROR_TYPE */
 273
 274 /**
 275  *  @def CHIP_SYSTEM_HEADER_RESERVE_SIZE
 276  *
 277  *  @brief
 278  *      The number of bytes to reserve in a network packet buffer to contain
 279  *      the CHIP message and exchange headers.
 280  *
 281  *      This number was calculated as follows:
 282  *
 283  *      CHIP Crypto Header:
 284  *
 285  *          4 -- Length of encrypted block
 286  *          4 -- Reserve
 287  *          8 -- Initialization Vector
 288  *          8 -- Encryption Tag
 289  */
 290 #ifndef CHIP_SYSTEM_CRYPTO_HEADER_RESERVE_SIZE
 291 #define CHIP_SYSTEM_CRYPTO_HEADER_RESERVE_SIZE 24
 292 #endif
 293
 294 /**
 295  *  @def CHIP_SYSTEM_HEADER_RESERVE_SIZE
 296  *
 297  *  @brief
 298  *      The number of bytes to reserve in a network packet buffer to contain
 299  *      the CHIP message and exchange headers.
 300  *
 301  *      This number was calculated as follows:
 302  *
 303  *      CHIP Message Header:
 304  *
 305  *          2 -- Frame Length
 306  *          2 -- Message Header
 307  *          4 -- Message Id
 308  *          8 -- Source Node Id
 309  *          8 -- Destination Node Id
 310  *          2 -- Key Id
 311  *
 312  *      CHIP Exchange Header:
 313  *
 314  *          1 -- Application Version
 315  *          1 -- Message Type
 316  *          2 -- Exchange Id
 317  *          4 -- Profile Id
 318  *          4 -- Acknowleged Message Id
 319  *
 320  *    @note A number of these fields are optional or not presently used. So most headers will be considerably smaller than this.
 321  */
 322 #ifndef CHIP_SYSTEM_HEADER_RESERVE_SIZE
 323 #define CHIP_SYSTEM_HEADER_RESERVE_SIZE (38 + CHIP_SYSTEM_CRYPTO_HEADER_RESERVE_SIZE)
 324 #endif /* CHIP_SYSTEM_HEADER_RESERVE_SIZE */
 325
 326 /**
 327  *  @def CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE
 328  *
 329  *  @brief
 330  *      This is the total number of packet buffers for the BSD sockets configuration.
 331  *
 332  *      This may be set to zero (0) to enable unbounded dynamic allocation using malloc.
 333  */
 334 #ifndef CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE
 335 #define CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE 15
 336 #endif /* CHIP_SYSTEM_CONFIG_PACKETBUFFER_POOL_SIZE */
 337
 338 /**
 339  *  @def CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX
 340  *
 341  *  @brief
 342  *      The maximum size an application can use with \c PacketBuffer. This is not the raw memory size consumed by
 343  *      a \c PacketBuffer object.
 344  *
 345  *  @note
 346  *      Only socket platforms can override the default value. On LwIP-based platforms, the size is derived from the PBUF size
 347  *      and overriding the value will result in a compile-time error.
 348  *
 349  *      This value should be set large enough to accomodate the usage of PacketBuffer in the system. In particular, for the use
 350  *      in CHIP, the value should be set to accomodate the desired path MTU (i.e. the largest IP packet that can be sent over
 351  *      the network interface) plus any protocol overhead.
 352  *
 353  *      For example, sending an IP packet over the tunnel requires additional overheads that depend on platform's network
 354  *      interface. On socket platforms, the tunnel protocol overhead is 47 bytes; on LwIP platforms the overhead is 101 bytes,
 355  *      plus any "sub-Ethernet" data structure space (e.g. the linked list pointers used by some interfaces to queue packets).
 356  *
 357  *      The overheads are calculated as follows:
 358  *
 359  *          (variable) -- "Sub-Ethernet" data structures (LwIP-only)
 360  *          14 -- Ethernet Header (LwIP-only)
 361  *          20 -- IPv4 Header (LwIP-only)
 362  *          20 -- TCP Header (LwIP-only)
 363  *          2  -- CHIP Message Length
 364  *          24 -- CHIP Header
 365  *          1  -- Tunnel Header
 366  *          20 -- Crypto Trailer
 367  *
 368  *      The size of PacketBuffer structure does not need to be included in this value.
 369  */
 370 #if CHIP_SYSTEM_CONFIG_USE_LWIP && !defined(DOXYGEN)
 371 #ifdef CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX
 372 #error "CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX cannot be defined on an LwIP-based platform."
 373 #endif /* CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX */
 374 #else /* !CHIP_SYSTEM_CONFIG_USE_LWIP */
 375 #ifndef CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX
 376 #define CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX 1583
 377 #endif /* CHIP_SYSTEM_CONFIG_PACKETBUFFER_CAPACITY_MAX */
 378 #endif /* !CHIP_SYSTEM_CONFIG_USE_LWIP */
 379
 380 #if CHIP_SYSTEM_CONFIG_USE_LWIP
 381
 382 /**
 383  *  @def CHIP_SYSTEM_CONFIG_LWIP_EVENT_TYPE
 384  *
 385  *  @brief
 386  *      This defines the type for CHIP System Layer event types, typically an integral type.
 387  */
 388 #ifndef CHIP_SYSTEM_CONFIG_LWIP_EVENT_TYPE
 389 #define CHIP_SYSTEM_CONFIG_LWIP_EVENT_TYPE int
 390 #endif /* CHIP_SYSTEM_CONFIG_LWIP_EVENT_TYPE */
 391
 392 /**
 393  *  @def CHIP_SYSTEM_CONFIG_LWIP_EVENT_UNRESERVED_CODE
 394  *
 395  *  @brief
 396  *      This defines the first number in the default event code space not reserved for use by the CHIP System Layer.
 397  *      Event codes used by each layer must not overlap.
 398  */
 399 #ifndef CHIP_SYSTEM_CONFIG_LWIP_EVENT_UNRESERVED_CODE
 400 #define CHIP_SYSTEM_CONFIG_LWIP_EVENT_UNRESERVED_CODE  32
 401 #endif /* CHIP_SYSTEM_CONFIG_LWIP_EVENT_UNRESERVED_CODE */
 402
 403 /**
 404  *  @def _CHIP_SYSTEM_CONFIG_LWIP_EVENT
 405  *
 406  *  @brief
 407  *      This defines a mapping function for CHIP System Layer codes for describing the types of events for the LwIP dispatcher,
 408  *      which allows mapping such event types into a platform- or system-specific range.
 409  */
 410 #ifndef _CHIP_SYSTEM_CONFIG_LWIP_EVENT
 411 #define _CHIP_SYSTEM_CONFIG_LWIP_EVENT(e) (e)
 412 #endif /* _CHIP_SYSTEM_CONFIG_LWIP_EVENT */
 413
 414 /**
 415  *  @def CHIP_SYSTEM_CONFIG_LWIP_EVENT_OBJECT_TYPE
 416  *
 417  *  @brief
 418  *      This defines the type of CHIP System Layer event objects or "messages" for the LwIP dispatcher.
 419  *
 420  *      Such types are not directly used by the CHIP System Layer but are "passed through". Consequently a forward declaration and
 421  *      a const pointer or reference are appropriate.
 422  */
 423 #ifndef CHIP_SYSTEM_CONFIG_LWIP_EVENT_OBJECT_TYPE
 424 namespace chip {
 425 namespace System {
 426
 427 struct LwIPEvent;
 428
 429 } // namespace System
 430 } // namespace chip
 431
 432 #define CHIP_SYSTEM_CONFIG_LWIP_EVENT_OBJECT_TYPE const struct chip::System::LwIPEvent*
 433 #endif /* CHIP_SYSTEM_CONFIG_LWIP_EVENT_OBJECT_TYPE */
 434
 435 #endif /* CHIP_SYSTEM_CONFIG_USE_LWIP */
 436
 437 /**
 438  *  @def CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_POSIX_ERROR_FUNCTIONS
 439  *
 440  *  @brief
 441  *      This defines whether (1) or not (0) your platform will provide the following platform- and system-specific functions:
 442  *      - chip::System::MapErrorPOSIX
 443  *      - chip::System::DescribeErrorPOSIX
 444  *      - chip::System::IsErrorPOSIX
 445  */
 446 #ifndef CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_POSIX_ERROR_FUNCTIONS
 447 #define CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_POSIX_ERROR_FUNCTIONS 0
 448 #endif /* CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_POSIX_ERROR_FUNCTIONS */
 449
 450 /**
 451  *  @def CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_LWIP_ERROR_FUNCTIONS
 452  *
 453  *  @brief
 454  *      This defines whether (1) or not (0) your platform will provide the following system-specific functions:
 455  *      - chip::System::MapErrorLwIP
 456  *      - chip::System::DescribeErrorLwIP
 457  *      - chip::System::IsErrorLwIP
 458  */
 459 #ifndef CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_LWIP_ERROR_FUNCTIONS
 460 #define CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_LWIP_ERROR_FUNCTIONS 0
 461 #endif /* CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_LWIP_ERROR_FUNCTIONS */
 462
 463 /**
 464  *  @def CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS
 465  *
 466  *  @brief
 467  *      This defines whether (1) or not (0) your platform will provide the following platform-specific functions:
 468  *      - chip::System::Platform::Layer::WillInit
 469  *      - chip::System::Platform::Layer::WillShutdown
 470  *      - chip::System::Platform::Layer::DidInit
 471  *      - chip::System::Platform::Layer::DidShutdown
 472  */
 473 #ifndef CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS
 474 #define CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS 0
 475 #endif /* CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_XTOR_FUNCTIONS */
 476
 477 /**
 478  *  @def CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS
 479  *
 480  *  @brief
 481  *      This defines whether (1) or not (0) your platform will provide the following platform-specific functions:
 482  *      - chip::System::Platform::Layer::PostEvent
 483  *      - chip::System::Platform::Layer::DispatchEvents
 484  *      - chip::System::Platform::Layer::DispatchEvent
 485  *      - chip::System::Platform::Layer::StartTimer
 486  */
 487 #ifndef CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS
 488 #define CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS 0
 489 #endif /* CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_EVENT_FUNCTIONS */
 490
 491 /**
 492  *  @def CHIP_SYSTEM_CONFIG_NUM_TIMERS
 493  *
 494  *  @brief
 495  *      This is the total number of available timers.
 496  */
 497 #ifndef CHIP_SYSTEM_CONFIG_NUM_TIMERS
 498 #define CHIP_SYSTEM_CONFIG_NUM_TIMERS 32
 499 #endif /* CHIP_SYSTEM_CONFIG_NUM_TIMERS */
 500
 501 /**
 502  *  @def CHIP_SYSTEM_CONFIG_PROVIDE_STATISTICS
 503  *
 504  *  @brief
 505  *      This defines whether (1) or not (0) the CHIP System Layer provides logic for gathering and reporting statistical
 506  *      information for diagnostic purposes.
 507  */
 508 #ifndef CHIP_SYSTEM_CONFIG_PROVIDE_STATISTICS
 509 #define CHIP_SYSTEM_CONFIG_PROVIDE_STATISTICS 0
 510 #endif // CHIP_SYSTEM_CONFIG_PROVIDE_STATISTICS
 511
 512 /**
 513  *  @def CHIP_SYSTEM_CONFIG_TEST
 514  *
 515  *  @brief
 516  *    Defines whether (1) or not (0) to enable testing aids.
 517  */
 518 #ifndef CHIP_SYSTEM_CONFIG_TEST
 519 #define CHIP_SYSTEM_CONFIG_TEST 0
 520 #endif
 521
 522 // clang-format on
 523
 524 // Configuration parameters with header inclusion dependencies
 525
 526 /**
 527  * @def CHIP_SYSTEM_CONFIG_HEADER_RESERVE_SIZE
 528  *
 529  * @brief
 530  *  The number of bytes to reserve in a network packet buffer to contain all the possible protocol encapsulation headers before the
 531  *  application message text. On POSIX sockets, this is CHIP_SYSTEM_HEADER_RESERVE_SIZE. On LwIP, additional space is required for
 532  *  the all the headers from layer-2 up to the TCP or UDP header.
 533  */
 534 #ifndef CHIP_SYSTEM_CONFIG_HEADER_RESERVE_SIZE
 535 #if CHIP_SYSTEM_CONFIG_USE_LWIP
 536 #define CHIP_SYSTEM_CONFIG_HEADER_RESERVE_SIZE                                                                                     \
 537     (PBUF_LINK_HLEN + PBUF_IP_HLEN + PBUF_TRANSPORT_HLEN + CHIP_SYSTEM_HEADER_RESERVE_SIZE)
 538 #else /* !CHIP_SYSTEM_CONFIG_USE_LWIP */
 539 #define CHIP_SYSTEM_CONFIG_HEADER_RESERVE_SIZE (CHIP_SYSTEM_HEADER_RESERVE_SIZE)
 540 #endif /* !CHIP_SYSTEM_CONFIG_USE_LWIP */
 541 #endif /* CHIP_SYSTEM_CONFIG_HEADER_RESERVE_SIZE */
 542
 543 /**
 544  *  @def CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME
 545  *
 546  *  @brief
 547  *      Use platform-supplied functions for System Layer clock functions.
 548  *
 549  *  Determines whether (1) or not (0) the underlying platform provides implementations for
 550  *  the System Layer GetClock/SetClock functions.
 551  */
 552 #ifndef CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME
 553 #define CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME 0
 554 #endif // CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME
 555
 556 /**
 557  *  @def CHIP_SYSTEM_CONFIG_USE_POSIX_TIME_FUNCTS
 558  *
 559  *  @brief
 560  *      Use the POSIX time functions for System Layer clock functions.
 561  *
 562  *  Use the POSIX time functions (clock_gettime, gettimeofday, etc.) to implement the
 563  *  System Layer GetClock/SetClock functions.
 564  *
 565  *  Defaults to enabled if the system is using sockets.
 566  *
 567  *  This configuration is overridden if CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME is set.
 568  */
 569 #ifndef CHIP_SYSTEM_CONFIG_USE_POSIX_TIME_FUNCTS
 570 #if CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK
 571 #define CHIP_SYSTEM_CONFIG_USE_POSIX_TIME_FUNCTS 1
 572 #else // CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK
 573 #define CHIP_SYSTEM_CONFIG_USE_POSIX_TIME_FUNCTS 0
 574 #endif // CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK
 575 #endif // CHIP_SYSTEM_CONFIG_USE_POSIX_TIME_FUNCTS
 576
 577 /**
 578  *  @def CHIP_SYSTEM_CONFIG_USE_LWIP_MONOTONIC_TIME
 579  *
 580  *  @brief
 581  *      Use LwIP time function for System Layer monotonic clock functions.
 582  *
 583  *  Use the LwIP sys_now() function to implement the System Layer GetClock_Monotonic... functions.
 584  *
 585  *  Defaults to enabled if the system is using LwIP and not sockets.
 586  *
 587  *  This configuration is overridden if CHIP_SYSTEM_CONFIG_PLATFORM_PROVIDES_TIME is set.
 588  */
 589 #ifndef CHIP_SYSTEM_CONFIG_USE_LWIP_MONOTONIC_TIME
 590 #if CHIP_SYSTEM_CONFIG_USE_LWIP && !CHIP_SYSTEM_CONFIG_USE_SOCKETS
 591 #define CHIP_SYSTEM_CONFIG_USE_LWIP_MONOTONIC_TIME 1
 592 #else
 593 #define CHIP_SYSTEM_CONFIG_USE_LWIP_MONOTONIC_TIME 0
 594 #endif
 595 #endif // CHIP_SYSTEM_CONFIG_USE_LWIP_MONOTONIC_TIME
 596
 597 /**
 598  *  @def CHIP_SYSTEM_CONFIG_VALID_REAL_TIME_THRESHOLD
 599  *
 600  *  @brief
 601  *      The earliest time at which the real time clock is considered to be valid.
 602  *
 603  *  The value is given in Unix time scaled to seconds.
 604  *
 605  *  The default value corresponds to 2000/01/01 00:00:00
 606  */
 607 #ifndef CHIP_SYSTEM_CONFIG_VALID_REAL_TIME_THRESHOLD
 608 #define CHIP_SYSTEM_CONFIG_VALID_REAL_TIME_THRESHOLD 946684800
 609 #endif // CHIP_SYSTEM_CONFIG_VALID_REAL_TIME_THRESHOLD
 610
 611 /**
 612  *  @def CHIP_SYSTEM_CONFIG_USE_POSIX_PIPE
 613  *
 614  *  @brief
 615  *      Use the POSIX pipe() function.
 616  *
 617  *  Use the POSIX pipe() function to create an anonymous data stream.
 618  *
 619  *  Defaults to enabled if the system is using sockets (except for Zephyr RTOS).
 620  */
 621 #ifndef CHIP_SYSTEM_CONFIG_USE_POSIX_PIPE
 622 #if (CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK) && !__ZEPHYR__
 623 #define CHIP_SYSTEM_CONFIG_USE_POSIX_PIPE 1
 624 #endif
 625 #endif // CHIP_SYSTEM_CONFIG_USE_POSIX_PIPE
 626
 627 #ifndef CHIP_SYSTEM_CONFIG_USE_ZEPHYR_SOCKET_EXTENSIONS
 628 #if CHIP_SYSTEM_CONFIG_USE_SOCKETS && __ZEPHYR__
 629 /**
 630  *  @def CHIP_SYSTEM_CONFIG_USE_ZEPHYR_SOCKET_EXTENSIONS
 631  *
 632  *  @brief
 633  *      Include missing functions for Zephyr sockets
 634  *
 635  *  Zephyr socket API lacks some of the functions required by CHIP, e.g. getsockname, recvmsg.
 636  *  If this value is set CHIP will provide the missing functions.
 637  *
 638  *  Defaults to enabled on Zephyr platforms using sockets
 639  */
 640 #define CHIP_SYSTEM_CONFIG_USE_ZEPHYR_SOCKET_EXTENSIONS 1
 641 #endif
 642 #endif // CHIP_SYSTEM_CONFIG_USE_ZEPHYR_SOCKET_EXTENSIONS
 643
 644 #ifndef CHIP_SYSTEM_CONFIG_USE_ZEPHYR_NET_IF
 645 #if CHIP_SYSTEM_CONFIG_USE_SOCKETS && __ZEPHYR__
 646 /**
 647  *  @def CHIP_SYSTEM_CONFIG_USE_ZEPHYR_NET_IF
 648  *
 649  *  @brief
 650  *      Use Zephyr net_if API to enumerate available network interfaces
 651  *
 652  *  Defaults to enabled on Zephyr platforms using sockets
 653  */
 654 #define CHIP_SYSTEM_CONFIG_USE_ZEPHYR_NET_IF 1
 655 #endif
 656 #endif // CHIP_SYSTEM_CONFIG_USE_ZEPHYR_NET_IF
 657
 658 /**
 659  *  @def CHIP_SYSTEM_CONFIG_USE_BSD_IFADDRS
 660  *
 661  *  @brief
 662  *      Use BSD ifaddrs.h API to enumerate available network interfaces
 663  *
 664  *  Defaults to enabled on Unix/Linux platforms using sockets
 665  */
 666 #ifndef CHIP_SYSTEM_CONFIG_USE_BSD_IFADDRS
 667 #if (CHIP_SYSTEM_CONFIG_USE_SOCKETS || CHIP_SYSTEM_CONFIG_USE_NETWORK_FRAMEWORK) && !__ZEPHYR__
 668 #define CHIP_SYSTEM_CONFIG_USE_BSD_IFADDRS 1
 669 #else
 670 #define CHIP_SYSTEM_CONFIG_USE_BSD_IFADDRS 0
 671 #endif
 672 #endif // CHIP_SYSTEM_CONFIG_USE_BSD_IFADDRS