From 68ea33aa17ffb075d2c7135560e410092b5a676d Mon Sep 17 00:00:00 2001 From: Aleksander Wasaznik Date: Tue, 14 May 2024 10:02:15 +0200 Subject: [PATCH] Bluetooth: Deprecate adv auto-resume The host-based adv auto-resume function has both a problematic implementation and disagreement in the community around how it should behave. See the issue linked resolved below for details. This patch makes the deprecation visible to the user. The user will be better served by a auto-resume tailored their applications use case, based on more primitive host API like `conn_cb.recycled`, which has obvious behavior that is unlikely to change. Resolves: https://github.com/zephyrproject-rtos/zephyr/issues/72567 Signed-off-by: Aleksander Wasaznik --- include/zephyr/bluetooth/bluetooth.h | 30 +++++++++++++++++++++++++--- subsys/bluetooth/host/adv.c | 7 +++++++ 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/include/zephyr/bluetooth/bluetooth.h b/include/zephyr/bluetooth/bluetooth.h index 59689974b876365..62ca742bc90cfac 100644 --- a/include/zephyr/bluetooth/bluetooth.h +++ b/include/zephyr/bluetooth/bluetooth.h @@ -518,12 +518,30 @@ enum { * advertising is determined by providing scan response data. * The advertiser address is determined by the type of advertising * and/or enabling privacy @kconfig{CONFIG_BT_PRIVACY}. + * + * Starting connectable advertising preallocates a connection + * object. If this fails, the API returns @c -ENOMEM. + * + * When an advertiser set results in a connection creation, the + * controller will automatically disable that advertising set. + * + * If the advertising set was started with @ref bt_le_adv_start + * without @ref BT_LE_ADV_OPT_ONE_TIME, the host will attempt to + * resume the advertiser under some conditions. This behavior is + * deprecated and will be removed in the future. */ BT_LE_ADV_OPT_CONNECTABLE = BIT(0), /** * @brief Advertise one time. * + * This option is now mandatory for non-directed connectable + * advertisers when using @ref bt_le_adv_start. This means the + * entirety of the old automatic resume feature is deprecated. + * Applications should instead choose an implementation of an + * advertiser manager that fits their use case. See the extended + * advertising sample for an example. + * * Don't try to resume connectable advertising after a connection. * This option is only meaningful when used together with * BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped @@ -908,9 +926,15 @@ struct bt_le_per_adv_param { _peer) -#define BT_LE_ADV_CONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, \ - BT_GAP_ADV_FAST_INT_MIN_2, \ - BT_GAP_ADV_FAST_INT_MAX_2, NULL) +/** + * @deprecated It is now mandatory to use @ref BT_LE_ADV_OPT_ONE_TIME + * for connectable advertising. Please use @ref BT_LE_ADV_CONN_ONE_TIME + * instead. + */ +#define BT_LE_ADV_CONN \ + BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, BT_GAP_ADV_FAST_INT_MIN_2, \ + BT_GAP_ADV_FAST_INT_MAX_2, NULL) \ + __DEPRECATED_MACRO /** This is the recommended default for connectable advertisers. */ diff --git a/subsys/bluetooth/host/adv.c b/subsys/bluetooth/host/adv.c index a6d62bd6db9ea50..1d3cc0f97b6a2d9 100644 --- a/subsys/bluetooth/host/adv.c +++ b/subsys/bluetooth/host/adv.c @@ -1363,6 +1363,13 @@ int bt_le_adv_start(const struct bt_le_adv_param *param, struct bt_le_ext_adv *adv = adv_get_legacy(); int err; + if (!(param->options & BT_LE_ADV_OPT_ONE_TIME) && + (param->options & BT_LE_ADV_OPT_CONNECTABLE) && !param->peer) { + LOG_WRN("Deprecation warning: %s BT_LE_ADV_OPT_CONNECTABLE without " + "BT_LE_ADV_OPT_ONE_TIME", + __func__); + } + if (!adv) { return -ENOMEM; }