michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: Host: Deprecate auto name in AD

Browse source 
Deprecate the advertiser options `BT_LE_ADV_OPT_USE_NAME` and
`BT_LE_ADV_OPT_FORCE_NAME_IN_AD`.

Reasons:

- It is out of place in the advertiser options, as it acts on
  advertising data and not configuration
- The behavior is not clear. All of these are trick questions:
  - where does the data for the name go?
  - do I have to allocate memory for this?
  - does it work the same in legacy vs extended advertising?
- The trade-off between UX improvement and extra complexity in the host
  is debatable. Hundreds of lines in the stack to avoid making the user
  type out less than ten.

Also deprecate the following macros that uses those options:

- `BT_LE_ADV_CONN_NAME`
- `BT_LE_ADV_CONN_NAME_AD`
- `BT_LE_ADV_NCONN_NAME`
- `BT_LE_EXT_ADV_CONN_NAME`
- `BT_LE_EXT_ADV_SCAN_NAME`
- `BT_LE_EXT_ADV_NCONN_NAME`
- `BT_LE_EXT_ADV_CODED_NCONN_NAME`

Update the migration guide and the release note for Zephyr 3.7 to
describe those changes.

Signed-off-by: Théo Battrel <theo.battrel@nordicsemi.no>
This commit is contained in:
Théo Battrel 2024-04-17 16:36:12 +02:00 • committed by Carles Cufí
commit 909ad8170c
3 changed files with 113 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

14
doc/releases/migration-guide-3.7.rst
View file

@ -208,6 +208,20 @@ Bluetooth Classic
Removed the :kconfig:option:`CONFIG_BT_BREDR`. It is replaced by new option
:kconfig:option:`CONFIG_BT_CLASSIC`. (:github:`69651`)
Bluetooth Host
==============
* The advertiser options :code:`BT_LE_ADV_OPT_USE_NAME` and :code:`BT_LE_ADV_OPT_FORCE_NAME_IN_AD`
are deprecated in this release. The application need to include the device name explicitly. One
way to do it is by adding the following to the advertising data or scan response data passed to
the host:
.. code-block:: c
BT_DATA(BT_DATA_NAME_COMPLETE, CONFIG_BT_DEVICE_NAME, sizeof(CONFIG_BT_DEVICE_NAME) - 1)
(:github:`71686`)
Networking
**********

21
doc/releases/release-notes-3.7.rst
View file

@ -28,6 +28,27 @@ https://docs.zephyrproject.org/latest/security/vulnerabilities.html
* CVE-2024-3077 `Zephyr project bug tracker GHSA-gmfv-4vfh-2mh8
<https://github.com/zephyrproject-rtos/zephyr/security/advisories/GHSA-gmfv-4vfh-2mh8>`_
API Changes
***********
Deprecated in this release
==========================
* Bluetooth advertiser options :code:`BT_LE_ADV_OPT_USE_NAME` and
:code:`BT_LE_ADV_OPT_FORCE_NAME_IN_AD` are now deprecated. That means the following macro are
deprecated:
* :c:macro:`BT_LE_ADV_CONN_NAME`
* :c:macro:`BT_LE_ADV_CONN_NAME_AD`
* :c:macro:`BT_LE_ADV_NCONN_NAME`
* :c:macro:`BT_LE_EXT_ADV_CONN_NAME`
* :c:macro:`BT_LE_EXT_ADV_SCAN_NAME`
* :c:macro:`BT_LE_EXT_ADV_NCONN_NAME`
* :c:macro:`BT_LE_EXT_ADV_CODED_NCONN_NAME`
Application developer will now need to set the advertised name themselves by updating the advertising data
or the scan response data.
Architectures
*************

110
include/zephyr/bluetooth/bluetooth.h
View file

@ -549,25 +549,29 @@ enum {
*/
BT_LE_ADV_OPT_USE_IDENTITY = BIT(2),
/** Advertise using GAP device name.
/**
* @deprecated This option will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* Include the GAP device name automatically when advertising.
* By default the GAP device name is put at the end of the scan
* response data.
* When advertising using @ref BT_LE_ADV_OPT_EXT_ADV and not
* @ref BT_LE_ADV_OPT_SCANNABLE then it will be put at the end of the
* advertising data.
* If the GAP device name does not fit into advertising data it will be
* converted to a shortened name if possible.
* @ref BT_LE_ADV_OPT_FORCE_NAME_IN_AD can be used to force the device
* name to appear in the advertising data of an advert with scan
* response data.
* @brief Advertise using GAP device name.
*
* The application can set the device name itself by including the
* following in the advertising data.
* @code
* BT_DATA(BT_DATA_NAME_COMPLETE, name, sizeof(name) - 1)
* @endcode
* Include the GAP device name automatically when advertising.
* By default the GAP device name is put at the end of the scan
* response data.
* When advertising using @ref BT_LE_ADV_OPT_EXT_ADV and not
* @ref BT_LE_ADV_OPT_SCANNABLE then it will be put at the end of the
* advertising data.
* If the GAP device name does not fit into advertising data it will be
* converted to a shortened name if possible.
* @ref BT_LE_ADV_OPT_FORCE_NAME_IN_AD can be used to force the device
* name to appear in the advertising data of an advert with scan
* response data.
*
* The application can set the device name itself by including the
* following in the advertising data.
* @code
* BT_DATA(BT_DATA_NAME_COMPLETE, name, sizeof(name) - 1)
* @endcode
*/
BT_LE_ADV_OPT_USE_NAME = BIT(3),
@ -691,10 +695,13 @@ enum {
BT_LE_ADV_OPT_DISABLE_CHAN_39 = BIT(17),
/**
* @deprecated This option will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* @brief Put GAP device name into advert data
*
* Will place the GAP device name into the advertising data rather
* than the scan response data.
* Will place the GAP device name into the advertising data rather than
* the scan response data.
*
* @note Requires @ref BT_LE_ADV_OPT_USE_NAME
*/
@ -905,16 +912,26 @@ struct bt_le_per_adv_param {
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*/
#define BT_LE_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
BT_LE_ADV_OPT_USE_NAME, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
BT_GAP_ADV_FAST_INT_MAX_2, NULL) \
__DEPRECATED_MACRO
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*/
#define BT_LE_ADV_CONN_NAME_AD BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \
BT_LE_ADV_OPT_USE_NAME | \
BT_LE_ADV_OPT_FORCE_NAME_IN_AD, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
BT_GAP_ADV_FAST_INT_MAX_2, NULL) \
__DEPRECATED_MACRO
#define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | BT_LE_ADV_OPT_ONE_TIME | \
@ -926,10 +943,16 @@ struct bt_le_per_adv_param {
#define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
/** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_NAME */
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_NAME
*/
#define BT_LE_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_NAME, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
BT_GAP_ADV_FAST_INT_MAX_2, NULL) \
__DEPRECATED_MACRO
/** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
#define BT_LE_ADV_NCONN_IDENTITY BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_IDENTITY, \
@ -944,13 +967,19 @@ struct bt_le_per_adv_param {
BT_GAP_ADV_FAST_INT_MAX_2, \
NULL)
/** Connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* Connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME
*/
#define BT_LE_EXT_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
BT_LE_ADV_OPT_CONNECTABLE | \
BT_LE_ADV_OPT_USE_NAME, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, \
NULL)
NULL) \
__DEPRECATED_MACRO
/** Scannable extended advertising */
#define BT_LE_EXT_ADV_SCAN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
@ -959,25 +988,37 @@ struct bt_le_per_adv_param {
BT_GAP_ADV_FAST_INT_MAX_2, \
NULL)
/** Scannable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* Scannable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME
*/
#define BT_LE_EXT_ADV_SCAN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
BT_LE_ADV_OPT_SCANNABLE | \
BT_LE_ADV_OPT_USE_NAME, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, \
NULL)
NULL) \
__DEPRECATED_MACRO
/** Non-connectable extended advertising with private address */
#define BT_LE_EXT_ADV_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
/** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME
*/
#define BT_LE_EXT_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \
BT_LE_ADV_OPT_USE_NAME, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, \
NULL)
NULL) \
__DEPRECATED_MACRO
/** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */
#define BT_LE_EXT_ADV_NCONN_IDENTITY \
@ -993,14 +1034,19 @@ struct bt_le_per_adv_param {
BT_GAP_ADV_FAST_INT_MAX_2, \
NULL)
/** Non-connectable extended advertising on coded PHY with
* @ref BT_LE_ADV_OPT_USE_NAME
/**
* @deprecated This macro will be removed in the near future, see
* https://github.com/zephyrproject-rtos/zephyr/issues/71686
*
* Non-connectable extended advertising on coded PHY with
* @ref BT_LE_ADV_OPT_USE_NAME
*/
#define BT_LE_EXT_ADV_CODED_NCONN_NAME \
BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CODED | \
BT_LE_ADV_OPT_USE_NAME, \
BT_GAP_ADV_FAST_INT_MIN_2, \
BT_GAP_ADV_FAST_INT_MAX_2, NULL)
BT_GAP_ADV_FAST_INT_MAX_2, NULL) \
__DEPRECATED_MACRO
/** Non-connectable extended advertising on coded PHY with
* @ref BT_LE_ADV_OPT_USE_IDENTITY