weave/src/ble/BleConfig.h

/*
 *
 *    Copyright (c) 2014-2017 Nest Labs, Inc.
 *    All rights reserved.
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 */

/**
 *    @file
 *      This file defines default compile-time configuration constants
 *      for the Nest BleLayer, a Bluetooth Low Energy communications
 *      abstraction layer.
 *
 *      Package integrators that wish to override these values should
 *      either use preprocessor definitions or create a project-
 *      specific BleProjectConfig.h header and then assert
 *      HAVE_BLEPROJECTCONFIG_H via the package configuration tool
 *      via --with-weave-ble-project-includes=DIR where DIR is the
 *      directory that contains the header.
 *
 *  NOTE WELL: On some platforms, this header is included by C-language programs.
 *
 */

#ifndef BLECONFIG_H_
#define BLECONFIG_H_

#include <SystemLayer/SystemConfig.h>

#if HAVE_BLEPROJECTCONFIG_H
#include "BleProjectConfig.h"
#endif

/**
 *  @def BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES
 *
 *  @brief
 *    This boolean configuration option is (1) if the obsolescent interfaces
 *    of the BLE layer that now reside elsewhere, for example, in the Weave System
 *    Layer or the INET layer, are aliased for transitional purposes.
 *
 */
#ifndef BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES
#define BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES          1
#endif // BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES

#if BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES
#if !WEAVE_SYSTEM_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES
#error "REQUIRED: if BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES then WEAVE_SYSTEM_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES!"
#endif // !WEAVE_SYSTEM_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES

#include <InetLayer/InetBuffer.h>
#endif // BLE_CONFIG_PROVIDE_OBSOLESCENT_INTERFACES

/**
 *  @def BLE_LAYER_NUM_BLE_ENDPOINTS
 *
 *  @brief
 *    This defines the number of BLEEndPoint objects allocated for use by the
 *    BleLayer subsystem. Value should be defined as the minimum of (max number
 *    of simultaneous BLE connections the system supports, max number of
 *    simultaneous BLE connections the application will establish).
 */
#ifndef BLE_LAYER_NUM_BLE_ENDPOINTS
#define BLE_LAYER_NUM_BLE_ENDPOINTS 1
#endif // BLE_LAYER_NUM_BLE_ENDPOINTS

#if (BLE_LAYER_NUM_BLE_ENDPOINTS < 1)
#error "BLE_LAYER_NUM_BLE_ENDPOINTS must be greater than 0. configure options may be used to disable Weave over BLE."
#endif

/**
 *  @def BLE_CONNECTION_OBJECT
 *
 *  @brief
 *    This defines the type of BLE_CONNECTION_OBJECT parameters passed between
 *    BLE platform code and the BleLayer subsystem.
 *
 *    This type must support operator== such that BLE_CONNECTION_OBJECT instances
 *    which refer to the same BLE connection are considered equivalent.
 *
 *    Most platforms should be able to retain this type's default definition as
 *    (void *), and pass [pointers to] connection handles generated by their
 *    platform interface where BLE_CONNECTION_OBJECT arguments are required by
 *    BleLayer input functions.
 *
 */
#ifndef BLE_CONNECTION_OBJECT
#define BLE_CONNECTION_OBJECT void*
#endif // BLE_CONNECTION_OBJECT

/**
 *  @def BLE_CONNECTION_UNINITIALIZED
 *
 *  @brief
 *    This defines the value of an uninitialized BLE_CONNECTION_OBJECT.
 *
 */
#ifndef BLE_CONNECTION_UNINITIALIZED
#define BLE_CONNECTION_UNINITIALIZED NULL
#endif // BLE_CONNECTION_UNINITIALIZED

/**
 *  @def BLE_READ_REQUEST_CONTEXT
 *
 *  @brief
 *    This defines the type of BLE_READ_REQUEST_CONTEXT parameters passed between
 *    BLE platform code and the BleLayer subsystem.
 *
 *    BLE_READ_REQUEST_CONTEXT objects are handed to BleLayer when a read request
 *    is received by the BLE platform. BleLayer hands these objects back to the
 *    appropriate platform delegate function when sending the read response.
 *
 */
#ifndef BLE_READ_REQUEST_CONTEXT
#define BLE_READ_REQUEST_CONTEXT void*
#endif // BLE_READ_REQUEST_CONTEXT

/**
 *  @def BLE_MAX_RECEIVE_WINDOW_SIZE
 *
 *  @brief
 *    This is the maximum allowed size of a BLE end point's receive window, defined as the number of fragments the
 *    end point may reliably receive without BTP-layer acknowledgement. This value should be no larger than the floor
 *    of ONE-HALF the total number of slots or buffers reserved for GATT operations at any point along a platform's
 *    BLE pipeline. The BLE layer reserves all of these buffers for its own use - one half for incoming GATT writes or
 *    indications, and the other half for incoming GATT confirmations.
 *
 *    This value must be greater than 1, or race condition avoidance logic will prevent send the on remote device. This
 *    logic prevents any send with no piggybacked ack when the receiver's window has only 1 slot open. Without this
 *    logic, simultaneous data transmissions could fill both receiver's windows, leaving no room for the acks required
 *    to re-open them. Both senders would wedge, and the BTP connection would stall.
 *
 *    This value must also exceed (BLE_CONFIG_IMMEDIATE_ACK_WINDOW_THRESHOLD + 1), or ***immediate*** stand-alone
 *    acks will forever be sent without delay in response to one another as each peer's window size dips below
 *    BLE_CONFIG_IMMEDIATE_ACK_WINDOW_THRESHOLD with receipt of any single message fragment.
 *
 *    Default value of 3 is absolute minimum for stable performance, and an attempt to ensure safe window sizes on new
 *    platforms.
 *
 */
#ifndef BLE_MAX_RECEIVE_WINDOW_SIZE
#define BLE_MAX_RECEIVE_WINDOW_SIZE                            3
#endif

#if (BLE_MAX_RECEIVE_WINDOW_SIZE < 3)
#error "BLE_MAX_RECEIVE_WINDOW_SIZE must be greater than 2 for BLE transport protocol stability."
#endif

/**
 *  @def BLE_CONFIG_ERROR_TYPE
 *
 *  @brief
 *    This defines the data type used to represent errors for the
 *    BleLayer subsystem.
 *
 */
#ifndef BLE_CONFIG_ERROR_TYPE
#include <stdint.h>
#define BLE_CONFIG_ERROR_TYPE                              int32_t
#endif // BLE_CONFIG_ERROR_TYPE

/**
 *  @def BLE_CONFIG_NO_ERROR
 *
 *  @brief
 *    This defines the BleLayer error code for no error or success.
 *
 */
#ifndef BLE_CONFIG_NO_ERROR
#define BLE_CONFIG_NO_ERROR                                0
#endif // BLE_CONFIG_NO_ERROR

/**
 *  @def BLE_CONFIG_ERROR_MIN
 *
 *  @brief
 *    This defines the base or minimum BleLayer error number range.
 *
 */
#ifndef BLE_CONFIG_ERROR_MIN
#define BLE_CONFIG_ERROR_MIN                               6000
#endif // BLE_CONFIG_ERROR_MIN

/**
 *  @def BLE_CONFIG_ERROR_MAX
 *
 *  @brief
 *    This defines the top or maximum BleLayer error number range.
 *
 */
#ifndef BLE_CONFIG_ERROR_MAX
#define BLE_CONFIG_ERROR_MAX                               6999
#endif // BLE_CONFIG_ERROR_MAX

/**
 *  @def BLE_CONFIG_ERROR
 *
 *  @brief
 *    This defines a mapping function for BleLayer errors that allows
 *    mapping such errors into a platform- or system-specific range.
 *
 */
#ifndef _BLE_CONFIG_ERROR
#define _BLE_CONFIG_ERROR(e)                               (BLE_ERROR_MIN + (e))
#endif // _BLE_CONFIG_ERROR

#include <Weave/Core/WeaveConfig.h>

#endif /* BLECONFIG_H_ */