bluetooth: host: Add support for LE Connection Subrating

Adds support for LE Connection Subrating as defined in Core 5.4
Vol 6, Part B, Section 5.1.19.
As this is primarily a controller feature, the host support is mostly
a wrapper around the relevant HCI commands.

Note that subrating provides a new method to update the connection's
peripheral latency and supervision timeout alongside subrating parameters.

Signed-off-by: Aleksandar Stanoev <[email protected]>

Author: alexstanoev-nordic

include/zephyr/bluetooth/conn.h

@@ -196,6 +196,57 @@ struct bt_conn_le_data_len_param {
 	BT_CONN_LE_DATA_LEN_PARAM(BT_GAP_DATA_LEN_MAX, \
 				  BT_GAP_DATA_TIME_MAX)
 
+/** Connection subrating parameters for LE connections */
+struct bt_conn_le_subrate_param {
+	/** Minimum subrate factor. */
+	uint16_t subrate_min;
+	/** Maximum subrate factor. */
+	uint16_t subrate_max;
+	/** Maximum Peripheral latency in units of subrated connection intervals. */
+	uint16_t max_latency;
+	/** Minimum number of underlying connection events to remain active
+	 *  after a packet containing a Link Layer PDU with a non-zero Length
+	 *  field is sent or received.
+	 */
+	uint16_t continuation_number;
+	/** Connection Supervision timeout (N * 10 ms).
+	 *  If using @ref bt_conn_le_subrate_set_defaults, this is the
+	 *  maximum supervision timeout allowed in requests by a peripheral.
+	 */
+	uint16_t supervision_timeout;
+};
+
+/** Subrating information for LE connections */
+struct bt_conn_le_subrating_info {
+	/** Connection subrate factor. */
+	uint16_t factor;
+	/** Number of underlying connection events to remain active after
+	 *  a packet containing a Link Layer PDU with a non-zero Length
+	 *  field is sent or received.
+	 */
+	uint16_t continuation_number;
+};
+
+/** Updated subrating connection parameters for LE connections */
+struct bt_conn_le_subrate_changed {
+	/** HCI Status from LE Subrate Changed event.
+	 *  The remaining parameters will be unchanged if status is not
+	 *  BT_HCI_ERR_SUCCESS.
+	 */
+	uint8_t status;
+	/** Connection subrate factor. */
+	uint16_t factor;
+	/** Number of underlying connection events to remain active after
+	 *  a packet containing a Link Layer PDU with a non-zero Length
+	 *  field is sent or received.
+	 */
+	uint16_t continuation_number;
+	/** Peripheral latency in units of subrated connection intervals. */
+	uint16_t peripheral_latency;
+	/** Connection Supervision timeout (N * 10 ms). */
+	uint16_t supervision_timeout;
+};
+
 /** Connection Type */
 enum __packed bt_conn_type {
 	/** LE Connection Type */
@@ -310,6 +361,11 @@ struct bt_conn_le_info {
 	/* Connection maximum single fragment parameters */
 	const struct bt_conn_le_data_len_info *data_len;
 #endif /* defined(CONFIG_BT_USER_DATA_LEN_UPDATE) */
+
+#if defined(CONFIG_BT_SUBRATING)
+	/* Connection subrating parameters */
+	const struct bt_conn_le_subrating_info *subrate;
+#endif /* defined(CONFIG_BT_SUBRATING) */
 };
 
 /** @brief Convert connection interval to milliseconds
@@ -676,6 +732,36 @@ int bt_conn_le_set_path_loss_mon_param(struct bt_conn *conn,
  */
 int bt_conn_le_set_path_loss_mon_enable(struct bt_conn *conn, bool enable);
 
+/** @brief Set Default Connection Subrating Parameters.
+ *
+ *  Change the default subrating parameters for all future
+ *  ACL connections where the local device is the central.
+ *  This command does not affect any existing connection.
+ *  Parameters set for specific connection will always have precedence.
+ *
+ *  @note To use this API @kconfig{CONFIG_BT_SUBRATING} and
+ *        @kconfig{CONFIG_BT_CENTRAL} must be set.
+ *
+ *  @param params Subrating parameters.
+ *
+ *  @return Zero on success or (negative) error code on failure.
+ */
+int bt_conn_le_subrate_set_defaults(const struct bt_conn_le_subrate_param *params);
+
+/** @brief Request New Subrating Parameters.
+ *
+ *  Request a change to the subrating parameters of a connection.
+ *
+ *  @note To use this API @kconfig{CONFIG_BT_SUBRATING} must be set.
+ *
+ *  @param conn   Connection object.
+ *  @param params Subrating parameters.
+ *
+ *  @return Zero on success or (negative) error code on failure.
+ */
+int bt_conn_le_subrate_request(struct bt_conn *conn,
+			       const struct bt_conn_le_subrate_param *params);
+
 /** @brief Update the connection parameters.
  *
  *  If the local device is in the peripheral role then updating the connection
@@ -1244,6 +1330,21 @@ struct bt_conn_cb {
 				const struct bt_conn_le_path_loss_threshold_report *report);
 #endif /* CONFIG_BT_PATH_LOSS_MONITORING */
 
+#if defined(CONFIG_BT_SUBRATING)
+	/** @brief LE Subrate Changed event.
+	 *
+	 *  This callback notifies the application that the subrating parameters
+	 *  of the connection may have changed.
+	 *  The connection subrating parameters will be unchanged
+	 *  if status is not BT_HCI_ERR_SUCCESS.
+	 *
+	 *  @param conn   Connection object.
+	 *  @param params New subrating parameters.
+	 */
+	void (*subrate_changed)(struct bt_conn *conn,
+				const struct bt_conn_le_subrate_changed *params);
+#endif /* CONFIG_BT_SUBRATING */
+
 	/** @internal Internally used field for list handling */
 	sys_snode_t _node;
 };

include/zephyr/bluetooth/hci_types.h

@@ -704,6 +704,26 @@ struct bt_hci_cp_le_set_path_loss_reporting_enable {
 #define BT_HCI_LE_PATH_LOSS_REPORTING_ENABLE        0x01
 #define BT_HCI_OP_LE_SET_PATH_LOSS_REPORTING_ENABLE BT_OP(BT_OGF_LE, 0x0079) /* 0x2079 */
 
+struct bt_hci_cp_le_set_default_subrate {
+	uint16_t subrate_min;
+	uint16_t subrate_max;
+	uint16_t max_latency;
+	uint16_t continuation_number;
+	uint16_t supervision_timeout;
+} __packed;
+
+struct bt_hci_cp_le_subrate_request {
+	uint16_t handle;
+	uint16_t subrate_min;
+	uint16_t subrate_max;
+	uint16_t max_latency;
+	uint16_t continuation_number;
+	uint16_t supervision_timeout;
+} __packed;
+
+#define BT_HCI_OP_LE_SET_DEFAULT_SUBRATE BT_OP(BT_OGF_LE, 0x007D) /* 0x207D */
+#define BT_HCI_OP_LE_SUBRATE_REQUEST     BT_OP(BT_OGF_LE, 0x007E) /* 0x207E */
+
 #define BT_HCI_CTL_TO_HOST_FLOW_DISABLE         0x00
 #define BT_HCI_CTL_TO_HOST_FLOW_ENABLE          0x01
 #define BT_HCI_OP_SET_CTL_TO_HOST_FLOW          BT_OP(BT_OGF_BASEBAND, 0x0031) /* 0x0c31 */
@@ -3098,6 +3118,16 @@ struct bt_hci_evt_le_biginfo_adv_report {
 	uint8_t  encryption;
 } __packed;
 
+#define BT_HCI_EVT_LE_SUBRATE_CHANGE            0x23
+struct bt_hci_evt_le_subrate_change {
+	uint8_t status;
+	uint16_t handle;
+	uint16_t subrate_factor;
+	uint16_t peripheral_latency;
+	uint16_t continuation_number;
+	uint16_t supervision_timeout;
+} __packed;
+
 /* Event mask bits */
 
 #define BT_EVT_BIT(n) (1ULL << (n))
@@ -3178,6 +3208,7 @@ struct bt_hci_evt_le_biginfo_adv_report {
 #define BT_EVT_MASK_LE_PATH_LOSS_THRESHOLD       BT_EVT_BIT(31)
 #define BT_EVT_MASK_LE_TRANSMIT_POWER_REPORTING  BT_EVT_BIT(32)
 #define BT_EVT_MASK_LE_BIGINFO_ADV_REPORT        BT_EVT_BIT(33)
+#define BT_EVT_MASK_LE_SUBRATE_CHANGE            BT_EVT_BIT(34)
 
 #define BT_EVT_MASK_LE_PER_ADV_SYNC_ESTABLISHED_V2 BT_EVT_BIT(35)
 #define BT_EVT_MASK_LE_PER_ADVERTISING_REPORT_V2   BT_EVT_BIT(36)

subsys/bluetooth/host/conn.c

@@ -2753,6 +2753,9 @@ int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info)
 #endif
 #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
 		info->le.data_len = &conn->le.data_len;
+#endif
+#if defined(CONFIG_BT_SUBRATING)
+		info->le.subrate = &conn->le.subrate;
 #endif
 		if (conn->le.keys && (conn->le.keys->flags & BT_KEYS_SC)) {
 			info->security.flags |= BT_SECURITY_FLAG_SC;
@@ -3038,6 +3041,109 @@ int bt_conn_le_set_path_loss_mon_enable(struct bt_conn *conn, bool reporting_ena
 }
 #endif /* CONFIG_BT_PATH_LOSS_MONITORING */
 
+#if defined(CONFIG_BT_SUBRATING)
+void notify_subrate_change(struct bt_conn *conn,
+			   const struct bt_conn_le_subrate_changed params)
+{
+	struct bt_conn_cb *callback;
+
+	SYS_SLIST_FOR_EACH_CONTAINER(&conn_cbs, callback, _node) {
+		if (callback->subrate_changed) {
+			callback->subrate_changed(conn, &params);
+		}
+	}
+
+	STRUCT_SECTION_FOREACH(bt_conn_cb, cb)
+	{
+		if (cb->subrate_changed) {
+			cb->subrate_changed(conn, &params);
+		}
+	}
+}
+
+static bool le_subrate_common_params_valid(const struct bt_conn_le_subrate_param *param)
+{
+	/* All limits according to BT Core spec 5.4 [Vol 4, Part E, 7.8.123] */
+
+	if (param->subrate_min < 0x0001 || param->subrate_min > 0x01F4 ||
+	    param->subrate_max < 0x0001 || param->subrate_max > 0x01F4 ||
+	    param->subrate_min > param->subrate_max) {
+		return false;
+	}
+
+	if (param->max_latency > 0x01F3 ||
+	    param->subrate_max * (param->max_latency + 1) > 500) {
+		return false;
+	}
+
+	if (param->continuation_number > 0x01F3 ||
+	    param->continuation_number >= param->subrate_max) {
+		return false;
+	}
+
+	if (param->supervision_timeout < 0x000A ||
+	    param->supervision_timeout > 0xC80) {
+		return false;
+	}
+
+	return true;
+}
+
+int bt_conn_le_subrate_set_defaults(const struct bt_conn_le_subrate_param *params)
+{
+	struct bt_hci_cp_le_set_default_subrate *cp;
+	struct net_buf *buf;
+
+	if (!IS_ENABLED(CONFIG_BT_CENTRAL)) {
+		return -ENOTSUP;
+	}
+
+	if (!le_subrate_common_params_valid(params)) {
+		return -EINVAL;
+	}
+
+	buf = bt_hci_cmd_create(BT_HCI_OP_LE_SET_DEFAULT_SUBRATE, sizeof(*cp));
+	if (!buf) {
+		return -ENOBUFS;
+	}
+
+	cp = net_buf_add(buf, sizeof(*cp));
+	cp->subrate_min = sys_cpu_to_le16(params->subrate_min);
+	cp->subrate_max = sys_cpu_to_le16(params->subrate_max);
+	cp->max_latency = sys_cpu_to_le16(params->max_latency);
+	cp->continuation_number = sys_cpu_to_le16(params->continuation_number);
+	cp->supervision_timeout = sys_cpu_to_le16(params->supervision_timeout);
+
+	return bt_hci_cmd_send_sync(BT_HCI_OP_LE_SET_DEFAULT_SUBRATE, buf, NULL);
+}
+
+int bt_conn_le_subrate_request(struct bt_conn *conn,
+			       const struct bt_conn_le_subrate_param *params)
+{
+	struct bt_hci_cp_le_subrate_request *cp;
+	struct net_buf *buf;
+
+	if (!le_subrate_common_params_valid(params)) {
+		return -EINVAL;
+	}
+
+	buf = bt_hci_cmd_create(BT_HCI_OP_LE_SUBRATE_REQUEST, sizeof(*cp));
+	if (!buf) {
+		return -ENOBUFS;
+	}
+
+	cp = net_buf_add(buf, sizeof(*cp));
+	cp->handle = sys_cpu_to_le16(conn->handle);
+	cp->subrate_min = sys_cpu_to_le16(params->subrate_min);
+	cp->subrate_max = sys_cpu_to_le16(params->subrate_max);
+	cp->max_latency = sys_cpu_to_le16(params->max_latency);
+	cp->continuation_number = sys_cpu_to_le16(params->continuation_number);
+	cp->supervision_timeout = sys_cpu_to_le16(params->supervision_timeout);
+
+	return bt_hci_cmd_send_sync(BT_HCI_OP_LE_SUBRATE_REQUEST, buf, NULL);
+}
+#endif /* CONFIG_BT_SUBRATING */
+
 int bt_conn_le_param_update(struct bt_conn *conn,
 			    const struct bt_le_conn_param *param)
 {

subsys/bluetooth/host/conn_internal.h

@@ -114,6 +114,10 @@ struct bt_conn_le {
 #if defined(CONFIG_BT_USER_DATA_LEN_UPDATE)
 	struct bt_conn_le_data_len_info data_len;
 #endif
+
+#if defined(CONFIG_BT_SUBRATING)
+	struct bt_conn_le_subrating_info subrate;
+#endif
 };
 
 #if defined(CONFIG_BT_CLASSIC)
@@ -479,6 +483,9 @@ void notify_tx_power_report(struct bt_conn *conn,
 void notify_path_loss_threshold_report(struct bt_conn *conn,
 				       struct bt_conn_le_path_loss_threshold_report report);
 
+void notify_subrate_change(struct bt_conn *conn,
+			   struct bt_conn_le_subrate_changed params);
+
 #if defined(CONFIG_BT_SMP)
 /* If role specific LTK is present */
 bool bt_conn_ltk_present(const struct bt_conn *conn);