diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index b7184d7463..4d280cbeaa 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -233,10 +233,15 @@ typedef struct { uint16_t send_adv_reserved_size; /*!< Controller minimum memory value in bytes. Internal use only */ uint32_t controller_debug_flag; /*!< Controller debug log flag. Internal use only */ uint8_t mode; /*!< Controller mode: + 1: BLE mode + 2: Classic Bluetooth mode + 3: Dual mode + Others: Invalid + Configurable in menuconfig. */ uint8_t ble_max_conn; /*!< Maximum number of BLE connections. Configurable in menuconfig. */ @@ -474,9 +479,9 @@ typedef struct esp_vhci_host_callback { * * If the return value is True, the Host can send the packet to the Controller. * - * @note This function should be called before each `esp_vhci_host_send_packet()`. + * @note This function should be called before each `esp_vhci_host_send_packet()`. * - * @return + * @return * True if the Controller is ready to receive packets; false otherwise */ bool esp_vhci_host_check_send_available(void); @@ -509,18 +514,18 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba * * This function releases the BSS, data and other sections of the Controller to heap. The total size is about 70 KB. * - * If the app calls `esp_bt_controller_enable(ESP_BT_MODE_BLE)` to use BLE only, - * then it is safe to call `esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)` at initialization time to free unused Classic Bluetooth memory. - * - * If the mode is `ESP_BT_MODE_BTDM`, then it may be useful to call API `esp_bt_mem_release(ESP_BT_MODE_BTDM)` instead, - * which internally calls `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` and additionally releases the BSS and data - * consumed by the Classic Bluetooth/BLE Host stack to heap. For more details about usage please refer to the documentation of `esp_bt_mem_release()` function. - * * @note - * 1. This function should be called only before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. - * 2. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 3. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. + * 1. This function is optional and should be called only if you want to free up memory for other components. + * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. + * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * + * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE Controller to heap. + * + * If you intend to use BLE only, calling `esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)` could release the BSS and data consumed by Classic Bluetooth Controller. You can then continue using BLE. + * + * If you intend to use Classic Bluetooth only, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BLE)` could release the BSS and data consumed by BLE Controller. You can then continue using Classic Bluetooth. + * * @param[in] mode The Bluetooth Controller mode * * @return @@ -530,13 +535,22 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba */ esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); -/** @brief Release the Controller memory, BSS and data section of the Classic Bluetooth/BLE Host stack as per the mode +/** + * @brief Release the Controller memory, BSS and data section of the Classic Bluetooth/BLE Host stack as per the mode * - * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`. - * Additionally, if the mode is set to `ESP_BT_MODE_BTDM`, it also releases the BSS and data consumed by the Classic Bluetooth and BLE Host stack to heap. + * @note + * 1. This function is optional and should be called only if you want to free up memory for other components. + * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. + * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * - * If you never intend to use Bluetooth in a current boot-up cycle, you can call `esp_bt_mem_release(ESP_BT_MODE_BTDM)` - * before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. + * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`, then releases Host memory. + * + * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE stack to heap. + * + * If you intend to use BLE only, calling `esp_bt_mem_release(ESP_BT_MODE_CLASSIC_BT)` could release the BSS and data consumed by Classic Bluetooth. You can then continue using BLE. + * + * If you intend to use Classic Bluetooth only, calling `esp_bt_mem_release(ESP_BT_MODE_BLE)` could release the BSS and data consumed by BLE. You can then continue using Classic Bluetooth. * * For example, if you only use Bluetooth for setting the Wi-Fi configuration, and do not use Bluetooth in the rest of the product operation, * after receiving the Wi-Fi configuration, you can disable/de-init Bluetooth and release its memory. @@ -548,11 +562,6 @@ esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); * esp_bt_controller_deinit(); * esp_bt_mem_release(ESP_BT_MODE_BTDM); * - * @note - * 1. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 2. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. - * 3. In case of NimBLE Host, to release BSS and data memory to heap, the mode needs to be set to `ESP_BT_MODE_BTDM` as the Controller is in Dual mode. - * * @param[in] mode The Bluetooth Controller mode * * @return