From 4590b4bb34d897360049ad7cf4f8150805c878e0 Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Thu, 29 Jan 2026 20:43:55 +0800 Subject: [PATCH] doc(ble/bluedroid): clarify callback notes to avoid time-consuming ops --- .../bt/host/bluedroid/api/include/api/esp_gap_ble_api.h | 6 +++++- .../bt/host/bluedroid/api/include/api/esp_gattc_api.h | 6 +++++- .../bt/host/bluedroid/api/include/api/esp_gatts_api.h | 8 ++++++-- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h index da5df368a1a..4fc217c36c4 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h @@ -2902,7 +2902,11 @@ typedef void (* esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_p * * @param[in] callback: callback function * - * @note Avoid performing time-consuming operations within the callback functions. + * @note Do NOT perform time-consuming operations in the callback. Time-consuming operations + * include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with + * long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash + * read/write/erase. Such operations may block the Bluetooth stack and lead to + * instability or deadlock. Defer heavy work to a separate task if needed. * * @return * - ESP_OK : success diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index 70953609ee6..9129edb6f4d 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -280,7 +280,11 @@ typedef void (* esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_ * * @param[in] callback The pointer to the application callback function * - * @note Avoid performing time-consuming operations within the callback functions. + * @note Do NOT perform time-consuming operations in the callback. Time-consuming operations + * include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with + * long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash + * read/write/erase. Such operations may block the Bluetooth stack and lead to + * instability or deadlock. Defer heavy work to a separate task if needed. * * @return * - ESP_OK: Success diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h index 642222104ad..875ddbc9a11 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -283,7 +283,11 @@ typedef void (* esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_ * * @param[in] callback The pointer to the application callback function * - * @note Avoid performing time-consuming operations within the callback functions. + * @note Do NOT perform time-consuming operations in the callback. Time-consuming operations + * include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with + * long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash + * read/write/erase. Such operations may block the Bluetooth stack and lead to + * instability or deadlock. Defer heavy work to a separate task if needed. * * @return * - ESP_OK: Success