src/ble/BleConfig.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2014-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 BleLayer, a Bluetooth Low Energy 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 BleProjectConfig.h header and then assert
  28  *      HAVE_BLEPROJECTCONFIG_H via the package configuration tool
  29  *      via --with-chip-ble-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 <ble/BleBuildConfig.h>
  40 #endif
  41
  42 #include <system/SystemConfig.h>
  43
  44 /* Include a project-specific configuration file, if defined.
  45  *
  46  * An application or module that incorporates chip can define a project configuration
  47  * file to override standard BLE Layer configuration with application-specific values.
  48  * The project config file is typically located outside the Openchip source tree,
  49  * alongside the source code for the application.
  50  */
  51 #ifdef BLE_PROJECT_CONFIG_INCLUDE
  52 #include BLE_PROJECT_CONFIG_INCLUDE
  53 #endif
  54
  55 /* Include a platform-specific configuration file, if defined.
  56  *
  57  * A platform configuration file contains overrides to standard BLE Layer configuration
  58  * that are specific to the platform or OS on which chip is running.  It is typically
  59  * provided as apart of an adaptation layer that adapts Openchip to the target
  60  * environment.  This adaptation layer may be included in the Openchip source tree
  61  * itself or implemented externally.
  62  */
  63 #ifdef BLE_PLATFORM_CONFIG_INCLUDE
  64 #include BLE_PLATFORM_CONFIG_INCLUDE
  65 #endif
  66
  67 // clang-format off
  68
  69
  70 /**
  71  *  @def BLE_LAYER_NUM_BLE_ENDPOINTS
  72  *
  73  *  @brief
  74  *    This defines the number of BLEEndPoint objects allocated for use by the
  75  *    BleLayer subsystem. Value should be defined as the minimum of (max number
  76  *    of simultaneous BLE connections the system supports, max number of
  77  *    simultaneous BLE connections the application will establish).
  78  */
  79 #ifndef BLE_LAYER_NUM_BLE_ENDPOINTS
  80 #define BLE_LAYER_NUM_BLE_ENDPOINTS 1
  81 #endif // BLE_LAYER_NUM_BLE_ENDPOINTS
  82
  83 #if (BLE_LAYER_NUM_BLE_ENDPOINTS < 1)
  84 #error "BLE_LAYER_NUM_BLE_ENDPOINTS must be greater than 0. configure options may be used to disable chip over BLE."
  85 #endif
  86
  87 /**
  88  *  @def BLE_CONNECTION_OBJECT
  89  *
  90  *  @brief
  91  *    This defines the type of BLE_CONNECTION_OBJECT parameters passed between
  92  *    BLE platform code and the BleLayer subsystem.
  93  *
  94  *    This type must support operator == such that BLE_CONNECTION_OBJECT instances
  95  *    which refer to the same BLE connection are considered equivalent.
  96  *
  97  *    Most platforms should be able to retain this type's default definition as
  98  *    (void *), and pass [pointers to] connection handles generated by their
  99  *    platform interface where BLE_CONNECTION_OBJECT arguments are required by
 100  *    BleLayer input functions.
 101  *
 102  */
 103 #ifndef BLE_CONNECTION_OBJECT
 104 #define BLE_CONNECTION_OBJECT void*
 105 #endif // BLE_CONNECTION_OBJECT
 106
 107 /**
 108  *  @def BLE_CONFIG_BLUEZ_MTU_FEATURE
 109  *
 110  *  @brief
 111  *    This define if BLUEZ MTU FEATURE is enabled or not
 112  */
 113 #ifndef BLE_CONFIG_BLUEZ_MTU_FEATURE
 114 #define BLE_CONFIG_BLUEZ_MTU_FEATURE 0
 115 #endif // BLE_CONFIG_BLUEZ_MTU_FEATURE
 116
 117 /**
 118  *  @def BLE_CONNECTION_UNINITIALIZED
 119  *
 120  *  @brief
 121  *    This defines the value of an uninitialized BLE_CONNECTION_OBJECT.
 122  *
 123  */
 124 #ifndef BLE_CONNECTION_UNINITIALIZED
 125 #define BLE_CONNECTION_UNINITIALIZED NULL
 126 #endif // BLE_CONNECTION_UNINITIALIZED
 127
 128 /**
 129  *  @def BLE_READ_REQUEST_CONTEXT
 130  *
 131  *  @brief
 132  *    This defines the type of BLE_READ_REQUEST_CONTEXT parameters passed between
 133  *    BLE platform code and the BleLayer subsystem.
 134  *
 135  *    BLE_READ_REQUEST_CONTEXT objects are handed to BleLayer when a read request
 136  *    is received by the BLE platform. BleLayer hands these objects back to the
 137  *    appropriate platform delegate function when sending the read response.
 138  *
 139  */
 140 #ifndef BLE_READ_REQUEST_CONTEXT
 141 #define BLE_READ_REQUEST_CONTEXT void*
 142 #endif // BLE_READ_REQUEST_CONTEXT
 143
 144 /**
 145  *  @def BLE_MAX_RECEIVE_WINDOW_SIZE
 146  *
 147  *  @brief
 148  *    This is the maximum allowed size of a BLE end point's receive window, defined as the number of fragments the
 149  *    end point may reliably receive without BTP-layer acknowledgement. This value should be no larger than the floor
 150  *    of ONE-HALF the total number of slots or buffers reserved for GATT operations at any point along a platform's
 151  *    BLE pipeline. The BLE layer reserves all of these buffers for its own use - one half for incoming GATT writes or
 152  *    indications, and the other half for incoming GATT confirmations.
 153  *
 154  *    This value must be greater than 1, or race condition avoidance logic will prevent send the on remote device. This
 155  *    logic prevents any send with no piggybacked ack when the receiver's window has only 1 slot open. Without this
 156  *    logic, simultaneous data transmissions could fill both receiver's windows, leaving no room for the acks required
 157  *    to re-open them. Both senders would wedge, and the BTP connection would stall.
 158  *
 159  *    This value must also exceed (BLE_CONFIG_IMMEDIATE_ACK_WINDOW_THRESHOLD + 1), or ***immediate*** stand-alone
 160  *    acks will forever be sent without delay in response to one another as each peer's window size dips below
 161  *    BLE_CONFIG_IMMEDIATE_ACK_WINDOW_THRESHOLD with receipt of any single message fragment.
 162  *
 163  *    Default value of 3 is absolute minimum for stable performance, and an attempt to ensure safe window sizes on new
 164  *    platforms.
 165  *
 166  */
 167 #ifndef BLE_MAX_RECEIVE_WINDOW_SIZE
 168 #define BLE_MAX_RECEIVE_WINDOW_SIZE                            3
 169 #endif
 170
 171 #if (BLE_MAX_RECEIVE_WINDOW_SIZE < 3)
 172 #error "BLE_MAX_RECEIVE_WINDOW_SIZE must be greater than 2 for BLE transport protocol stability."
 173 #endif
 174
 175 /**
 176  *  @def BLE_CONFIG_ERROR_TYPE
 177  *
 178  *  @brief
 179  *    This defines the data type used to represent errors for the
 180  *    BleLayer subsystem.
 181  *
 182  */
 183 #ifndef BLE_CONFIG_ERROR_TYPE
 184 #include <stdint.h>
 185 #define BLE_CONFIG_ERROR_TYPE                              int32_t
 186 #endif // BLE_CONFIG_ERROR_TYPE
 187
 188 /**
 189  *  @def BLE_CONFIG_NO_ERROR
 190  *
 191  *  @brief
 192  *    This defines the BleLayer error code for no error or success.
 193  *
 194  */
 195 #ifndef BLE_CONFIG_NO_ERROR
 196 #define BLE_CONFIG_NO_ERROR                                0
 197 #endif // BLE_CONFIG_NO_ERROR
 198
 199 /**
 200  *  @def BLE_CONFIG_ERROR_MIN
 201  *
 202  *  @brief
 203  *    This defines the base or minimum BleLayer error number range.
 204  *
 205  */
 206 #ifndef BLE_CONFIG_ERROR_MIN
 207 #define BLE_CONFIG_ERROR_MIN                               6000
 208 #endif // BLE_CONFIG_ERROR_MIN
 209
 210 /**
 211  *  @def BLE_CONFIG_ERROR_MAX
 212  *
 213  *  @brief
 214  *    This defines the top or maximum BleLayer error number range.
 215  *
 216  */
 217 #ifndef BLE_CONFIG_ERROR_MAX
 218 #define BLE_CONFIG_ERROR_MAX                               6999
 219 #endif // BLE_CONFIG_ERROR_MAX
 220
 221 /**
 222  *  @def _BLE_CONFIG_ERROR
 223  *
 224  *  @brief
 225  *    This defines a mapping function for BleLayer errors that allows
 226  *    mapping such errors into a platform- or system-specific range.
 227  *
 228  */
 229 #ifndef _BLE_CONFIG_ERROR
 230 #define _BLE_CONFIG_ERROR(e)                               (BLE_ERROR_MIN + (e))
 231 #endif // _BLE_CONFIG_ERROR
 232
 233 // clang-format on
 234
 235 #include <core/CHIPConfig.h>