Merge pull request #9096 from pan-/fix-enforce-size-limits

BLE: Enforce advertising data payload limits

Author: 0xc0170

features/FEATURE_BLE/ble/gap/AdvertisingParameters.h

@@ -123,13 +123,20 @@ class AdvertisingParameters {
      * @param[in] minInterval, maxInterval Time interval between two advertisement.
      * A range is provided to the LE subsystem, so it can adjust the advertising
      * interval with other transmission happening on the BLE radio.
+     * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
+     *
+     * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
+     * you must use legacy PDU.
      *
      * @note If values in input are out of range, they will be normalized.
+     *
+     * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
      */
     AdvertisingParameters(
         advertising_type_t advType = advertising_type_t::CONNECTABLE_UNDIRECTED,
         adv_interval_t minInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN),
-        adv_interval_t maxInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX)
+        adv_interval_t maxInterval = adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX),
+        bool useLegacyPDU = true
     ) :
         _advType(advType),
         _minInterval(minInterval),
@@ -147,27 +154,91 @@ class AdvertisingParameters {
         _channel39(true),
         _anonymous(false),
         _notifyOnScan(false),
-        _legacyPDU(true),
+        _legacyPDU(useLegacyPDU),
         _includeHeaderTxPower(false)
     {
-        /* Min interval is slightly larger than in other modes. */
-        if (_advType == advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
-            _minInterval = adv_interval_t(std::max(_minInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
-            _maxInterval = adv_interval_t(std::max(_maxInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
-        }
+        normalize();
+    }
+
+    /**
+     * Construct an instance of GapAdvertisingParams.
+     *
+     * @param[in] advType Type of advertising.
+     * @param[in] useLegacyPDU If true legacy PDU shall be used for advertising.
+     *
+     * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
+     * you must use legacy PDU.
+     *
+     * @note If type selected is incompatible with non legacy PDU, legacy PDU will be used.
+     */
+    AdvertisingParameters(
+        advertising_type_t advType,
+        bool useLegacyPDU
+    ) :
+        _advType(advType),
+        _minInterval(adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MIN)),
+        _maxInterval(adv_interval_t(DEFAULT_ADVERTISING_INTERVAL_MAX)),
+        _peerAddressType(target_peer_address_type_t::PUBLIC),
+        _ownAddressType(own_address_type_t::RANDOM),
+        _policy(advertising_filter_policy_t::NO_FILTER),
+        _primaryPhy(phy_t::LE_1M),
+        _secondaryPhy(phy_t::LE_1M),
+        _peerAddress(),
+        _txPower(127),
+        _maxSkip(0),
+        _channel37(true),
+        _channel38(true),
+        _channel39(true),
+        _anonymous(false),
+        _notifyOnScan(false),
+        _legacyPDU(useLegacyPDU),
+        _includeHeaderTxPower(false)
+    {
+        normalize();
     }
 
 public:
+    /**
+     * Update the advertising type and whether to use legacy PDU.
+     *
+     * @note If legacy PDU is not used then you cannot use
+     * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
+     *
+     * @param[in] newAdvType The new advertising type.
+     *
+     * @param[in] legacy If true, legacy PDU will be used.
+     *
+     * @return reference to this object.
+     */
+    AdvertisingParameters &setType(advertising_type_t newAdvType, bool legacy)
+    {
+        if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
+            newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
+            /* these types can only be used with legacy PDUs */
+            MBED_ASSERT(legacy);
+        }
+        _advType = newAdvType;
+        _legacyPDU = legacy;
+        return *this;
+    }
 
     /**
      * Update the advertising type.
      *
+     * @note If legacy PDU is not used then you cannot use
+     * CONNECTABLE_UNDIRECTED nor CONNECTABLE_DIRECTED.
+     *
      * @param[in] newAdvType The new advertising type.
      *
      * @return reference to this object.
      */
     AdvertisingParameters &setType(advertising_type_t newAdvType)
     {
+        if (newAdvType == advertising_type_t::CONNECTABLE_UNDIRECTED ||
+            newAdvType == advertising_type_t::CONNECTABLE_DIRECTED) {
+            /* these types can only be used with legacy PDUs */
+            MBED_ASSERT(_legacyPDU);
+        }
         _advType = newAdvType;
         return *this;
     }
@@ -448,10 +519,19 @@ class AdvertisingParameters {
      *
      * @param enable If true, legacy PDU will be used.
      *
+     * @note If CONNECTABLE_UNDIRECTED or CONNECTABLE_DIRECTED advertising is used
+     * you must use legacy PDU.
+     *
      * @return A reference to this object.
      */
     AdvertisingParameters &setUseLegacyPDU(bool enable = true)
     {
+        if (!enable) {
+            /* these types can only be used with legacy PDUs */
+            MBED_ASSERT((_advType != advertising_type_t::CONNECTABLE_UNDIRECTED) &&
+                        (_advType != advertising_type_t::CONNECTABLE_DIRECTED));
+        }
+
         _legacyPDU = enable;
         return *this;
     }
@@ -490,6 +570,8 @@ class AdvertisingParameters {
      *
      * @param enable Advertising anonymous if true.
      *
+     * @note You may not use anonymous advertising with periodic advertising on the same set.
+     *
      * @return reference to this object.
      */
     AdvertisingParameters &setAnonymousAdvertising(bool enable)
@@ -507,6 +589,23 @@ class AdvertisingParameters {
         return _anonymous;
     }
 
+private:
+    /**
+     * Enforce limits on parameters.
+     */
+    void normalize()
+    {
+        /* Min interval is slightly larger than in other modes. */
+        if (_advType == advertising_type_t::NON_CONNECTABLE_UNDIRECTED) {
+            _minInterval = adv_interval_t(std::max(_minInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
+            _maxInterval = adv_interval_t(std::max(_maxInterval.value(), GAP_ADV_PARAMS_INTERVAL_MIN_NONCON));
+        }
+        if (_advType == advertising_type_t::CONNECTABLE_DIRECTED ||
+            _advType == advertising_type_t::CONNECTABLE_UNDIRECTED) {
+            _legacyPDU = true;
+        }
+    }
+
 private:
     advertising_type_t _advType;
     /* The advertising interval in ADV duration units (in other words, 0.625ms). */

features/FEATURE_BLE/ble/gap/Gap.h

@@ -538,6 +538,18 @@ class Gap {
      */
     virtual uint16_t getMaxAdvertisingDataLength();
 
+    /** Return maximum advertising data length supported for connectable advertising.
+     *
+     * @return Maximum advertising data length supported for connectable advertising.
+     */
+    virtual uint16_t getMaxConnectableAdvertisingDataLength();
+
+    /** Return maximum advertising data length you may set if advertising set is active.
+     *
+     * @return Maximum advertising data length you may set if advertising set is active.
+     */
+    virtual uint16_t getMaxActiveSetAdvertisingDataLength();
+
     /** Create an advertising set and apply the passed in parameters. The handle returned
      *  by this function must be used for all other calls that accept an advertising handle.
      *  When done with advertising, remove from the system using destroyAdvertisingSet().
@@ -583,6 +595,10 @@ class Gap {
      * @param handle Advertising set handle.
      * @param payload Advertising payload.
      *
+     * @note If advertising set is active you may only set payload of length equal or less
+     * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
+     * stop the advertising set, set the payload and restart the set.
+     *
      * @return BLE_ERROR_NONE on success.
      *
      * @see ble::AdvertisingDataBuilder to build a payload.
@@ -598,6 +614,10 @@ class Gap {
      * @param handle Advertising set handle.
      * @param response Advertising scan response.
      *
+     * @note If advertising set is active you may only set payload of length equal or less
+     * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
+     * stop the advertising set, set the payload and restart the set.
+     *
      * @return BLE_ERROR_NONE on success.
      *
      * @see ble::AdvertisingDataBuilder to build a payload.
@@ -663,6 +683,11 @@ class Gap {
      * @param payload Advertising payload.
      * @return BLE_ERROR_NONE on success.
      *
+     * @note If advertising set is active you may only set payload of length equal or less
+     * than getMaxActiveSetAdvertisingDataLength(). If you require a longer payload you must
+     * stop the advertising set, set the payload and restart the set. Stopping the set will
+     * cause peers to lose sync on the periodic set.
+     *
      * @see ble::AdvertisingDataBuilder to build a payload.
      *
      * @version 5+

features/FEATURE_BLE/ble/generic/GenericGap.h

@@ -50,7 +50,6 @@ class GenericGap :
 public:
     /* TODO: move to config */
     static const uint8_t MAX_ADVERTISING_SETS = 15;
-    static const size_t MAX_HCI_DATA_LENGTH = 251;
 
     /**
      * Construct a GenericGap.
@@ -92,6 +91,14 @@ class GenericGap :
      */
     virtual uint16_t getMaxAdvertisingDataLength();
 
+    /** @copydoc Gap::getMaxConnectableAdvertisingDataLength
+     */
+    virtual uint16_t getMaxConnectableAdvertisingDataLength();
+
+    /** @copydoc Gap::getMaxActiveSetAdvertisingDataLength
+     */
+    virtual uint16_t getMaxActiveSetAdvertisingDataLength();
+
     /** @copydoc Gap::createAdvertisingSet
      */
     virtual ble_error_t createAdvertisingSet(
@@ -781,6 +788,8 @@ class GenericGap :
     BitArray<MAX_ADVERTISING_SETS> _existing_sets;
     BitArray<MAX_ADVERTISING_SETS> _active_sets;
     BitArray<MAX_ADVERTISING_SETS> _active_periodic_sets;
+    BitArray<MAX_ADVERTISING_SETS> _connectable_payload_size_exceeded;
+    BitArray<MAX_ADVERTISING_SETS> _set_is_connectable;
 
     // deprecation flags
     mutable bool _deprecated_scan_api_used : 1;

features/FEATURE_BLE/ble/pal/PalGap.h

@@ -764,6 +764,23 @@ struct Gap {
      */
     virtual uint16_t get_maximum_advertising_data_length() = 0;
 
+    /**
+     * Query the maximum data length the controller supports in an advertising set
+     * using connectable advertising.
+     *
+     * @return The length in byte the controller can support in an advertising set
+     * for connectable advertising.
+     */
+    virtual uint16_t get_maximum_connectable_advertising_data_length() = 0;
+
+    /**
+     * Query the maximum payload length for a single HCI packet carrying partial
+     * (or complete if it fits) data for advertising set.
+     *
+     * @return Max size of the HCI packet transporting the data.
+     */
+    virtual uint8_t get_maximum_hci_advertising_data_length() = 0;
+
     /**
      * Query the maximum number of concurrent advertising sets that is supported
      * by the controller.

features/FEATURE_BLE/source/gap/Gap.cpp

@@ -36,6 +36,18 @@ uint16_t Gap::getMaxAdvertisingDataLength()
     return LEGACY_ADVERTISING_MAX_SIZE;
 }
 
+uint16_t Gap::getMaxConnectableAdvertisingDataLength()
+{
+    /* Requesting action from porter(s): override this API if this capability is supported. */
+    return LEGACY_ADVERTISING_MAX_SIZE;
+}
+
+uint16_t Gap::getMaxActiveSetAdvertisingDataLength()
+{
+    /* Requesting action from porter(s): override this API if this capability is supported. */
+    return LEGACY_ADVERTISING_MAX_SIZE;
+}
+
 ble_error_t Gap::createAdvertisingSet(
     advertising_handle_t *handle,
     const AdvertisingParameters &parameters