bluetooth: host: CS support for various HCI commands

Adds HCI support for:
- LE CS Security Enable
- LE CS Procedure Enable
- LE CS Set Procedure Parameters
- LE CS Set Channel Classification
- LE CS Read Local Supported Capabilities
- LE CS Write Cached Remote Supported Capabilities
- LE CS Write Cached Remote FAE Table

Signed-off-by: Adam Cavender <[email protected]>

Author: adamfc2000

include/zephyr/bluetooth/conn.h

@@ -1518,6 +1518,86 @@ enum bt_security_err {
 	BT_SECURITY_ERR_UNSPECIFIED,
 };
 
+enum bt_conn_le_cs_procedure_enable_state {
+	BT_CONN_LE_CS_PROCEDURES_DISABLED = BT_HCI_OP_LE_CS_PROCEDURES_DISABLED,
+	BT_CONN_LE_CS_PROCEDURES_ENABLED = BT_HCI_OP_LE_CS_PROCEDURES_ENABLED,
+};
+
+/** CS Test Tone Antennna Config Selection.
+ *
+ *  These enum values are indices in the following table, where N_AP is the maximum
+ *  number of antenna paths (in the range [1, 4]).
+ *
+ * +--------------+-------------+-------------------+-------------------+--------+
+ * | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
+ * +--------------+-------------+-------------------+-------------------+--------+
+ * |            0 |           1 |                 1 |                 1 | 1:1    |
+ * |            1 |           2 |                 2 |                 1 | N_AP:1 |
+ * |            2 |           3 |                 3 |                 1 | N_AP:1 |
+ * |            3 |           4 |                 4 |                 1 | N_AP:1 |
+ * |            4 |           2 |                 1 |                 2 | 1:N_AP |
+ * |            5 |           3 |                 1 |                 3 | 1:N_AP |
+ * |            6 |           4 |                 1 |                 4 | 1:N_AP |
+ * |            7 |           4 |                 2 |                 2 | 2:2    |
+ * +--------------+-------------+-------------------+-------------------+--------+
+ *
+ *  There are therefore four groups of possible antenna configurations:
+ *
+ *  - 1:1 configuration, where both A and B support 1 antenna each
+ *  - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
+ *    N_AP is a value in the range [2, 4]
+ *  - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
+ *    N_AP is a value in the range [2, 4]
+ *  - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
+ */
+enum bt_conn_le_cs_tone_antenna_config_selection {
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_ONE = BT_HCI_OP_LE_CS_ACI_0,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_TWO = BT_HCI_OP_LE_CS_ACI_1,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_THREE = BT_HCI_OP_LE_CS_ACI_2,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_FOUR = BT_HCI_OP_LE_CS_ACI_3,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_FIVE = BT_HCI_OP_LE_CS_ACI_4,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_SIX = BT_HCI_OP_LE_CS_ACI_5,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_SEVEN = BT_HCI_OP_LE_CS_ACI_6,
+	BT_LE_CS_TONE_ANTENNA_CONFIGURATION_INDEX_EIGHT = BT_HCI_OP_LE_CS_ACI_7,
+};
+
+struct bt_conn_le_cs_procedure_enable_complete {
+	/* The ID associated with the desired configuration (0 to 3) */
+	uint8_t config_id;
+
+	/* State of the CS procedure */
+	enum bt_conn_le_cs_procedure_enable_state state;
+
+	/* Antenna configuration index */
+	enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
+
+	/* Transmit power level used for CS procedures (-127 to 20 dB; 0x7F if unavailable) */
+	int8_t selected_tx_power;
+
+	/* Duration of each CS subevent in microseconds (1250 us to 4 s) */
+	uint32_t subevent_len;
+
+	/* Number of CS subevents anchored off the same ACL connection event (0x01 to 0x20) */
+	uint8_t subevents_per_event;
+
+	/* Time between consecutive CS subevents anchored off the same ACL connection event in
+	 * units of 0.625 ms
+	 */
+	uint16_t subevent_interval;
+
+	/* Number of ACL connection events between consecutive CS event anchor points */
+	uint16_t event_interval;
+
+	/* Number of ACL connection events between consecutive CS procedure anchor points */
+	uint16_t procedure_interval;
+
+	/* Number of CS procedures to be scheduled (0 if procedures to continue until disabled) */
+	uint16_t procedure_count;
+
+	/* Maximum duration for each procedure in units of 0.625 ms (0x0001 to 0xFFFF) */
+	uint16_t max_procedure_len;
+};
+
 /** @brief Connection callback structure.
  *
  *  This structure is used for tracking the state of a connection.
@@ -1810,6 +1890,27 @@ struct bt_conn_cb {
 	 */
 	void (*le_cs_subevent_data_available)(struct bt_conn *conn,
 					      struct bt_conn_le_cs_subevent_result *result);
+
+	/** @brief LE CS Security Enabled.
+	 *
+	 *  This callback notifies the application that a Channel Sounding
+	 *  Security Enable procedure has completed
+	 *
+	 *  @param conn Connection object.
+	 */
+	void (*le_cs_security_enabled)(struct bt_conn *conn);
+
+	/** @brief LE CS Procedure Enabled.
+	 *
+	 *  This callback notifies the application that a Channel Sounding
+	 *  Procedure Enable procedure has completed
+	 *
+	 *  @param conn Connection object.
+	 *  @param params CS Procedure Enable parameters
+	 */
+	void (*le_cs_procedure_enabled)(
+		struct bt_conn *conn, struct bt_conn_le_cs_procedure_enable_complete *params);
+
 #endif
 
 	/** @internal Internally used field for list handling */

include/zephyr/bluetooth/cs.h

@@ -88,62 +88,24 @@ enum bt_le_cs_test_cs_sync_antenna_selection {
 	BT_LE_CS_TEST_CS_SYNC_ANTENNA_SELECTION_FOUR = BT_HCI_OP_LE_CS_ANTENNA_SEL_FOUR,
 };
 
-/** CS Test Tone Antennna Config Selection.
- *
- *  These enum values are indices in the following table, where N_AP is the maximum
- *  number of antenna paths (in the range [1, 4]).
- *
- * +--------------+-------------+-------------------+-------------------+--------+
- * | Config Index | Total Paths | Dev A: # Antennas | Dev B: # Antennas | Config |
- * +--------------+-------------+-------------------+-------------------+--------+
- * |            0 |           1 |                 1 |                 1 | 1:1    |
- * |            1 |           2 |                 2 |                 1 | N_AP:1 |
- * |            2 |           3 |                 3 |                 1 | N_AP:1 |
- * |            3 |           4 |                 4 |                 1 | N_AP:1 |
- * |            4 |           2 |                 1 |                 2 | 1:N_AP |
- * |            5 |           3 |                 1 |                 3 | 1:N_AP |
- * |            6 |           4 |                 1 |                 4 | 1:N_AP |
- * |            7 |           4 |                 2 |                 2 | 2:2    |
- * +--------------+-------------+-------------------+-------------------+--------+
- *
- *  There are therefore four groups of possible antenna configurations:
- *
- *  - 1:1 configuration, where both A and B support 1 antenna each
- *  - 1:N_AP configuration, where A supports 1 antenna, B supports N_AP antennas, and
- *    N_AP is a value in the range [2, 4]
- *  - N_AP:1 configuration, where A supports N_AP antennas, B supports 1 antenna, and
- *    N_AP is a value in the range [2, 4]
- *  - 2:2 configuration, where both A and B support 2 antennas and N_AP = 4
- */
-enum bt_le_cs_test_tone_antenna_config_selection {
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_ONE = BT_HCI_OP_LE_CS_TEST_ACI_0,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_TWO = BT_HCI_OP_LE_CS_TEST_ACI_1,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_THREE = BT_HCI_OP_LE_CS_TEST_ACI_2,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_FOUR = BT_HCI_OP_LE_CS_TEST_ACI_3,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_FIVE = BT_HCI_OP_LE_CS_TEST_ACI_4,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_SIX = BT_HCI_OP_LE_CS_TEST_ACI_5,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_SEVEN = BT_HCI_OP_LE_CS_TEST_ACI_6,
-	BT_LE_CS_TEST_TONE_ANTENNA_CONFIGURATION_INDEX_EIGHT = BT_HCI_OP_LE_CS_TEST_ACI_7,
-};
-
 /** CS Test Initiator SNR control options */
-enum bt_le_cs_test_initiator_snr_control {
-	BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_18,
-	BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_21,
-	BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_24,
-	BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_27,
-	BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_30,
-	BT_LE_CS_TEST_INITIATOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_TEST_INITIATOR_SNR_NOT_USED,
+enum bt_le_cs_initiator_snr_control {
+	BT_LE_CS_INITIATOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_18,
+	BT_LE_CS_INITIATOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_21,
+	BT_LE_CS_INITIATOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_24,
+	BT_LE_CS_INITIATOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_27,
+	BT_LE_CS_INITIATOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_INITIATOR_SNR_30,
+	BT_LE_CS_INITIATOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_INITIATOR_SNR_NOT_USED,
 };
 
 /** CS Test Reflector SNR control options */
-enum bt_le_cs_test_reflector_snr_control {
-	BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_18,
-	BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_21,
-	BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_24,
-	BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_27,
-	BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_30,
-	BT_LE_CS_TEST_REFLECTOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_TEST_REFLECTOR_SNR_NOT_USED,
+enum bt_le_cs_reflector_snr_control {
+	BT_LE_CS_REFLECTOR_SNR_CONTROL_18dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_18,
+	BT_LE_CS_REFLECTOR_SNR_CONTROL_21dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_21,
+	BT_LE_CS_REFLECTOR_SNR_CONTROL_24dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_24,
+	BT_LE_CS_REFLECTOR_SNR_CONTROL_27dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_27,
+	BT_LE_CS_REFLECTOR_SNR_CONTROL_30dB = BT_HCI_OP_LE_CS_REFLECTOR_SNR_30,
+	BT_LE_CS_REFLECTOR_SNR_CONTROL_NOT_USED = BT_HCI_OP_LE_CS_REFLECTOR_SNR_NOT_USED,
 };
 
 /** CS Test Override 3 T_PM Tone Extension */
@@ -351,11 +313,11 @@ struct bt_le_cs_test_param {
 	/** Antenna Configuration Index used during antenna switching during
 	 *  the tone phases of CS steps.
 	 */
-	enum bt_le_cs_test_tone_antenna_config_selection tone_antenna_config_selection;
+	enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
 	/** Initiator SNR control options */
-	enum bt_le_cs_test_initiator_snr_control initiator_snr_control;
+	enum bt_le_cs_initiator_snr_control initiator_snr_control;
 	/** Reflector SNR control options */
-	enum bt_le_cs_test_reflector_snr_control reflector_snr_control;
+	enum bt_le_cs_reflector_snr_control reflector_snr_control;
 	/** Determines octets 14 and 15 of the initial value of the DRBG nonce. */
 	uint16_t drbg_nonce;
 
@@ -687,6 +649,178 @@ 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);
 
+/** @brief CS Security Enable
+ *
+ * This commmand is used to start or restart the Channel Sounding Security
+ * Start procedure in the local Controller for the ACL connection identified
+ * in the conn parameter.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param conn   Connection Object.
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_security_enable(struct bt_conn *conn);
+
+struct bt_le_cs_procedure_enable_param {
+	uint8_t config_id;
+	enum bt_conn_le_cs_procedure_enable_state enable;
+};
+
+/** @brief CS Procedure Enable
+ *
+ *  This command is used to enable or disable the scheduling of CS procedures
+ *  by the local Controller, with the remote device identified in the conn
+ *  parameter.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param conn   Connection Object.
+ * @param params Parameters for the CS Procedure Enable command.
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_procedure_enable(struct bt_conn *conn,
+			      const struct bt_le_cs_procedure_enable_param *params);
+
+enum bt_le_cs_procedure_phy {
+	BT_LE_CS_PROCEDURE_PHY_1M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_1M,
+	BT_LE_CS_PROCEUDRE_PHY_2M = BT_HCI_OP_LE_CS_PROCEDURE_PHY_2M,
+	BT_LE_CS_PROCEDURE_PHY_CODED_S8 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S8,
+	BT_LE_CS_PROCEDURE_PHY_CODED_S2 = BT_HCI_OP_LE_CS_PROCEDURE_PHY_CODED_S2,
+};
+
+#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_1 BIT(0)
+#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_2 BIT(1)
+#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_3 BIT(2)
+#define BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_4 BIT(3)
+
+struct bt_le_cs_set_procedure_parameters_param {
+	/* The ID associated with the desired configuration (0 to 3) */
+	uint8_t config_id;
+
+	/* Max. duration for each CS procedure, where T = N * 0.625 ms (0x0001 to 0xFFFF) */
+	uint16_t max_procedure_len;
+
+	/* Min. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
+	uint16_t min_procedure_interval;
+
+	/* Max. number of connection events between consecutive CS procedures (0x0001 to 0xFFFF) */
+	uint16_t max_procedure_interval;
+
+	/* Max. number of procedures to be scheduled (0x0000 for no limit; otherwise 0x0001
+	 * to 0xFFFF)
+	 */
+	uint16_t max_procedure_count;
+
+	/* Min. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
+	uint32_t min_subevent_len;
+
+	/* Max. suggested duration for each CS subevent in microseconds (1250 us to 4 s) */
+	uint32_t max_subevent_len;
+
+	/* Antenna configuration index */
+	enum bt_conn_le_cs_tone_antenna_config_selection tone_antenna_config_selection;
+
+	/* Phy */
+	enum bt_le_cs_procedure_phy phy;
+
+	/* Transmit power delta, in signed dB, to indicate the recommended difference between the
+	 * remote device's power level for the CS tones and RTT packets and the existing power
+	 * level for the Phy indicated by the Phy parameter (0x80 for no recommendation)
+	 */
+	int8_t tx_power_delta;
+
+	/* Preferred peer antenna (Bitmask of BT_LE_CS_PROCEDURE_PREFERRED_PEER_ANTENNA_*) */
+	uint8_t preferred_peer_antenna;
+
+	/* Initiator SNR control adjustment */
+	enum bt_le_cs_initiator_snr_control snr_control_initiator;
+
+	/* Reflector SNR control adjustment */
+	enum bt_le_cs_reflector_snr_control snr_control_reflector;
+};
+
+/** @brief CS Set Procedure Parameters
+ *
+ * This command is used to set the parameters for the scheduling of one
+ * or more CS procedures by the local controller.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param conn Connection Object.
+ * @param params Parameters for the CS Set Procedure Parameters command.
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_set_procedure_parameters(struct bt_conn *conn,
+				      const struct bt_le_cs_set_procedure_parameters_param *params);
+
+/** @brief CS Set Channel Classification
+ *
+ * This command is used to update the channel classification based on
+ * its local information.
+ *
+ * The nth bitfield (in the range 0 to 78) contains the value for the CS
+ * channel index n. Channel Enabled = 1; Channel Disabled = 0.
+ *
+ * Channels n = 0, 1, 23, 24, 25, 77, and 78 shall be reserved for future
+ * use and shall be set to zero. At least 15 channels shall be enabled.
+ *
+ * The most significant bit (bit 79) is reserved for future use.
+ *
+ * @note To use this API, @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param channel_classification Bit fields
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_set_channel_classification(uint8_t channel_classification[10]);
+
+/** @brief CS Read Local Supported Capabilities
+ *
+ *  This command is used to read the CS capabilities that are supported
+ *  by the local Controller.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param ret Return values for the CS Procedure Enable command.
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_read_local_supported_capabilities(struct bt_conn_le_cs_capabilities *ret);
+
+/** @brief CS Write Cached Remote Supported Capabilities
+ *
+ *  This command is used to write the cached copy of the CS capabilities
+ *  that are supported by the remote Controller for the connection
+ *  identified.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param conn   Connection Object.
+ * @param params Parameters for the CS Write Cached Remote Supported Capabilities command.
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_write_cached_remote_supported_capabilities(
+	struct bt_conn *conn, const struct bt_conn_le_cs_capabilities *params);
+
+/** @brief CS Write Cached Remote FAE Table
+ *
+ *  This command is used to write a cached copy of the per-channel mode-0
+ *  Frequency Actuation Error table of the remote device in the local Controller.
+ *
+ * @note To use this API @kconfig{CONFIG_BT_CHANNEL_SOUNDING} must be set.
+ *
+ * @param conn   Connection Object.
+ * @param remote_fae_table Per-channel mode-0 FAE table of the local Controller
+ *
+ * @return Zero on success or (negative) error code on failure.
+ */
+int bt_le_cs_write_cached_remote_fae_table(struct bt_conn *conn, uint8_t remote_fae_table[72]);
+
 #ifdef __cplusplus
 }
 #endif