bluetooth: host: Add support for processing CS subevent results

Adds support for:
- LE CS Subevent Result event
- LE CS Test End Complete event

For now, recombination of subevent results with more steps than could
fit within a single HCI event is not supported, and such events
are discarded.

Signed-off-by: Olivier Lesage <[email protected]>

Author: olivier-le-sage

include/zephyr/bluetooth/conn.h

@@ -538,6 +538,112 @@ struct bt_conn_le_cs_config {
 	uint8_t channel_map[10];
 };
 
+/** Procedure done status */
+enum bt_conn_le_cs_procedure_done_status {
+	BT_CONN_LE_CS_PROCEDURE_COMPLETE = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_COMPLETE,
+	BT_CONN_LE_CS_PROCEDURE_INCOMPLETE = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_PARTIAL,
+	BT_CONN_LE_CS_PROCEDURE_ABORTED = BT_HCI_LE_CS_PROCEDURE_DONE_STATUS_ABORTED,
+};
+
+/** Subevent done status */
+enum bt_conn_le_cs_subevent_done_status {
+	BT_CONN_LE_CS_SUBEVENT_COMPLETE = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_COMPLETE,
+	BT_CONN_LE_CS_SUBEVENT_INCOMPLETE = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_PARTIAL,
+	BT_CONN_LE_CS_SUBEVENT_ABORTED = BT_HCI_LE_CS_SUBEVENT_DONE_STATUS_ABORTED,
+};
+
+/** Procedure abort reason */
+enum bt_conn_le_cs_procedure_abort_reason {
+	BT_CONN_LE_CS_PROCEDURE_NOT_ABORTED = BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_NO_ABORT,
+	BT_CONN_LE_CS_PROCEDURE_ABORT_REQUESTED =
+		BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_LOCAL_HOST_OR_REMOTE_REQUEST,
+	BT_CONN_LE_CS_PROCEDURE_ABORT_TOO_FEW_CHANNELS =
+		BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_TOO_FEW_CHANNELS,
+	BT_CONN_LE_CS_PROCEDURE_ABORT_CHMAP_INSTANT_PASSED =
+		BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_CHMAP_INSTANT_PASSED,
+	BT_CONN_LE_CS_PROCEDURE_ABORT_UNSPECIFIED = BT_HCI_LE_CS_PROCEDURE_ABORT_REASON_UNSPECIFIED,
+};
+
+/** Subevent abort reason */
+enum bt_conn_le_cs_subevent_abort_reason {
+	BT_CONN_LE_CS_SUBEVENT_NOT_ABORTED = BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_NO_ABORT,
+	BT_CONN_LE_CS_SUBEVENT_ABORT_REQUESTED =
+		BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_LOCAL_HOST_OR_REMOTE_REQUEST,
+	BT_CONN_LE_CS_SUBEVENT_ABORT_NO_CS_SYNC =
+		BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_NO_CS_SYNC_RECEIVED,
+	BT_CONN_LE_CS_SUBEVENT_ABORT_SCHED_CONFLICT =
+		BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_SCHED_CONFLICT,
+	BT_CONN_LE_CS_SUBEVENT_ABORT_UNSPECIFIED = BT_HCI_LE_CS_SUBEVENT_ABORT_REASON_UNSPECIFIED,
+};
+
+/** Subevent data for LE connections supporting CS */
+struct bt_conn_le_cs_subevent_result {
+	struct {
+		/** CS configuration identifier.
+		 *
+		 *  Range: 0 to 3
+		 *
+		 *  If these results were generated by a CS Test,
+		 *  this value will be set to 0 and has no meaning.
+		 */
+		uint8_t config_id;
+		/** Starting ACL connection event counter.
+		 *
+		 *  If these results were generated by a CS Test,
+		 *  this value will be set to 0 and has no meaning.
+		 */
+		uint16_t start_acl_conn_event;
+		/** CS procedure count associated with these results.
+		 *
+		 *  This is the CS procedure count since the completion of
+		 *  the Channel Sounding Security Start procedure.
+		 */
+		uint16_t procedure_counter;
+		/** Frequency compensation value in units of 0.01 ppm.
+		 *
+		 *  This is a 15-bit signed integer in the range [-100, 100] ppm.
+		 *
+		 *  A value of @ref BT_HCI_LE_CS_SUBEVENT_RESULT_FREQ_COMPENSATION_NOT_AVAILABLE
+		 *  indicates that the role is not the initiator, or that the
+		 *  frequency compensation value is unavailable.
+		 */
+		uint16_t frequency_compensation;
+		/** Reference power level in dBm.
+		 *
+		 *  Range: -127 to 20
+		 *
+		 *  A value of @ref BT_HCI_LE_CS_REF_POWER_LEVEL_UNAVAILABLE indicates
+		 *  that the reference power level was not available during a subevent.
+		 */
+		int8_t reference_power_level;
+		/** Procedure status. */
+		enum bt_conn_le_cs_procedure_done_status procedure_done_status;
+		/** Subevent status. */
+		enum bt_conn_le_cs_subevent_done_status subevent_done_status;
+		/** Abort reason.
+		 *
+		 *  If the procedure status is
+		 *  @ref BT_CONN_LE_CS_PROCEDURE_ABORTED, this field will
+		 *  specify the reason for the abortion.
+		 */
+		enum bt_conn_le_cs_procedure_abort_reason procedure_abort_reason;
+		/** Abort reason.
+		 *
+		 *  If the subevent status is
+		 *  @ref BT_CONN_LE_CS_SUBEVENT_ABORTED, this field will
+		 *  specify the reason for the abortion.
+		 */
+		enum bt_conn_le_cs_subevent_abort_reason subevent_abort_reason;
+		/** Number of antenna paths used during the phase measurement stage.
+		 */
+		uint8_t num_antenna_paths;
+		/** Number of CS steps in the subevent.
+		 */
+		uint8_t num_steps_reported;
+	} header;
+	struct net_buf_simple *step_data_buf;
+};
+
 /** @brief Increment a connection's reference count.
  *
  *  Increment the reference count of a connection object.
@@ -1677,6 +1783,17 @@ struct bt_conn_cb {
 	 *  @param config_id ID of the CS configuration that was removed.
 	 */
 	void (*le_cs_config_removed)(struct bt_conn *conn, uint8_t config_id);
+
+	/** @brief Subevent Results from a CS procedure are available.
+	 *
+	 * This callback notifies the user that CS subevent results are
+	 * available for the given connection object.
+	 *
+	 * @param conn Connection objects.
+	 * @param result Subevent results
+	 */
+	void (*le_cs_subevent_data_available)(struct bt_conn *conn,
+					      struct bt_conn_le_cs_subevent_result *result);
 #endif
 
 	/** @internal Internally used field for list handling */

include/zephyr/bluetooth/cs.h

@@ -517,6 +517,29 @@ struct bt_le_cs_create_config_params {
 	uint8_t channel_map[10];
 };
 
+/** Callbacks for CS Test */
+struct bt_le_cs_test_cb {
+	/**@brief CS Test Subevent data.
+	 *
+	 * @param[in] Subevent results.
+	 */
+	void (*le_cs_test_subevent_data_available)(struct bt_conn_le_cs_subevent_result *data);
+	/**@brief CS Test End Complete. */
+	void (*le_cs_test_end_complete)(void);
+};
+
+/** Subevent result step */
+struct bt_le_cs_subevent_step {
+	/** CS step mode. */
+	uint8_t mode;
+	/** CS step channel index. */
+	uint8_t channel;
+	/** Length of role- and mode-specific information being reported. */
+	uint8_t data_len;
+	/** Pointer to role- and mode-specific information. */
+	const uint8_t *data;
+};
+
 /** @brief Set all valid channel map bits
  *
  * This command is used to enable all valid channels in a
@@ -567,6 +590,17 @@ int bt_le_cs_set_default_settings(struct bt_conn *conn,
  */
 int bt_le_cs_read_remote_fae_table(struct bt_conn *conn);
 
+/** @brief Register callbacks for the CS Test mode.
+ *
+ * Existing callbacks can be unregistered by providing NULL function
+ * pointers.
+ *
+ * @param cs_test_cb Set of callbacks to be used with CS Test
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_test_cb_register(struct bt_le_cs_test_cb cs_test_cb);
+
 /** @brief Start a CS test
  *
  * This command is used to start a CS test where the IUT is placed in the role
@@ -620,6 +654,37 @@ int bt_le_cs_create_config(struct bt_conn *conn, struct bt_le_cs_create_config_p
  */
 int bt_le_cs_remove_config(struct bt_conn *conn, uint8_t config_id);
 
+/** @brief Stop ongoing CS Test
+ *
+ * This command is used to stop any CS test that is in progress.
+ *
+ * The controller is expected to finish reporting any subevent results
+ * before completing this termination.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_stop_test(void);
+
+/** @brief Parse CS Test Subevent Results
+ *
+ * A helper for parsing HCI-formatted step data found in channel sounding subevent results.
+ *
+ * A typical use-case is filtering out data which does not meet certain packet quality or NADM
+ * requirements.
+ *
+ * @warning This function will consume the data when parsing.
+ *
+ * @param step_data_buf Pointer to a buffer containing the step data.
+ * @param func Callback function which will be called for each step data found.
+ *             The callback should return true to continue parsing, or false to stop.
+ * @param user_data User data to be passed to the callback.
+ */
+void bt_le_cs_step_data_parse(struct net_buf_simple *step_data_buf,
+			      bool (*func)(struct bt_le_cs_subevent_step *step, void *user_data),
+			      void *user_data);
+
 #ifdef __cplusplus
 }
 #endif