From c353fdfa0f039321c7eea06a967804ad6a102045 Mon Sep 17 00:00:00 2001 From: Joakim Andersson Date: Mon, 13 Jan 2020 14:39:30 +0100 Subject: [PATCH] Bluetooth: host: Document connection object behaviour Add documentation for why connection objects are still in use during the disconnected callback and document error code when starting connectable advertiser with no free connection object available. Signed-off-by: Joakim Andersson --- include/bluetooth/bluetooth.h | 11 +++++++---- include/bluetooth/conn.h | 10 ++++++++++ 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/include/bluetooth/bluetooth.h b/include/bluetooth/bluetooth.h index ab8fe320f0c..8f4f96d19c7 100644 --- a/include/bluetooth/bluetooth.h +++ b/include/bluetooth/bluetooth.h @@ -363,11 +363,14 @@ struct bt_le_adv_param { * @param sd_len Number of elements in sd * * @return Zero on success or (negative) error code otherwise. + * @return -ENOMEM No free connection objects available for connectable + * advertiser. * @return -ECONNREFUSED When connectable advertising is requested and there - * is already maximum number of connections established. - * This error code is only guaranteed when using Zephyr - * controller, for other controllers code returned in - * this case may be -EIO. + * is already maximum number of connections established + * in the controller. + * This error code is only guaranteed when using Zephyr + * controller, for other controllers code returned in + * this case may be -EIO. */ int bt_le_adv_start(const struct bt_le_adv_param *param, const struct bt_data *ad, size_t ad_len, diff --git a/include/bluetooth/conn.h b/include/bluetooth/conn.h index 11dc05948f8..ad81a19ee9a 100644 --- a/include/bluetooth/conn.h +++ b/include/bluetooth/conn.h @@ -304,6 +304,7 @@ struct bt_conn *bt_conn_create_le(const bt_addr_le_t *peer, * @param param Initial connection parameters. * * @return Zero on success or (negative) error code on failure. + * @return -ENOMEM No free connection object available. */ int bt_conn_create_auto_le(const struct bt_le_conn_param *param); @@ -492,6 +493,15 @@ struct bt_conn_cb { * This callback notifies the application that a connection * has been disconnected. * + * When this callback is called the stack still has one reference to + * the connection object. If the application in this callback tries to + * start either a connectable advertiser or create a new connection + * this might fail because there are no free connection objects + * available. + * To avoid this issue it is recommended to either start connectable + * advertise or create a new connection using @ref k_work_submit or + * increase :option:`CONFIG_BT_MAX_CONN`. + * * @param conn Connection object. * @param reason HCI reason for the disconnection. */