bluetooth: rename _bt_gatt_ccc and clarify usage

Bluetooth had two public types with similar name _bt_gatt_ccc and
bt_gatt_ccc, but for absolutely different purposes.
That caused misunderstanding of relationship of them and cases
where to use which one.

Commit changes name of _bt_gatt_ccc to more suitable by usage and
improves documentation of it.

Additionally, it changes name of BT_GATT_CCC_INITIALIZER
to correspond the type name.

Signed-off-by: Aleksandr Khromykh <[email protected]>

Author: alxelax

doc/releases/migration-guide-4.2.rst

@@ -243,6 +243,12 @@ Bluetooth Host
   each role may be different. Any existing uses/checks for ``BT_ISO_CHAN_TYPE_CONNECTED``
   can be replaced with an ``||`` of the two. (:github:`75549`)
 
+* The ``struct _bt_gatt_ccc`` in :zephyr_file:`include/zephyr/bluetooth/gatt.h` has been renamed to
+  struct :c:struct:`bt_gatt_ccc_managed_user_data`. (:github:`88652`)
+
+* The macro ``BT_GATT_CCC_INITIALIZER`` in :zephyr_file:`include/zephyr/bluetooth/gatt.h`
+  has been renamed to :c:macro:`BT_GATT_CCC_MANAGED_USER_DATA_INIT`. (:github:`88652`)
+
 Bluetooth Classic
 =================
 

include/zephyr/bluetooth/gatt.h

@@ -1035,8 +1035,14 @@ struct bt_gatt_ccc_cfg {
 	uint16_t value;
 };
 
-/** Internal representation of CCC value */
-struct _bt_gatt_ccc {
+/** Macro to keep old name for deprecation period. */
+#define _bt_gatt_ccc bt_gatt_ccc_managed_user_data __DEPRECATED_MACRO
+
+/** @brief Internal representation of CCC value.
+ *
+ * @note Only use this as an argument for @ref BT_GATT_CCC_MANAGED
+ */
+struct bt_gatt_ccc_managed_user_data {
 	/** Configuration for each connection */
 	struct bt_gatt_ccc_cfg cfg[BT_GATT_CCC_MAX];
 
@@ -1092,8 +1098,8 @@ struct _bt_gatt_ccc {
  *          case of error.
  */
 /** @cond INTERNAL_HIDDEN
- *  @note Only use this with attributes which user_data is a _bt_gatt_ccc.
- *  _bt_gatt_ccc being the internal representation of CCC value.
+ *  @note Only use this with attributes which user_data is a bt_gatt_ccc_managed_user_data.
+ *        @ref bt_gatt_ccc_managed_user_data being the internal representation of CCC value.
  */
  /** @endcond */
 ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
@@ -1115,14 +1121,17 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
  *          case of error.
  */
 /** @cond INTERNAL_HIDDEN
- *  @note Only use this with attributes which user_data is a _bt_gatt_ccc.
- *  _bt_gatt_ccc being the internal representation of CCC value.
+ *  @note Only use this with attributes which user_data is a bt_gatt_ccc_managed_user_data.
+ *        @ref bt_gatt_ccc_managed_user_data being the internal representation of CCC value.
  */
 /** @endcond */
 ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
 			       const struct bt_gatt_attr *attr, const void *buf,
 			       uint16_t len, uint16_t offset, uint8_t flags);
 
+/** Macro to keep old name for deprecation period. */
+#define BT_GATT_CCC_INITIALIZER BT_GATT_CCC_MANAGED_USER_DATA_INIT __DEPRECATED_MACRO
+
 /**
  *  @brief Initialize Client Characteristic Configuration Declaration Macro.
  *
@@ -1132,20 +1141,23 @@ ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
  *  @param _write Configuration write callback.
  *  @param _match Configuration match callback.
  */
-#define BT_GATT_CCC_INITIALIZER(_changed, _write, _match) \
-	{                                            \
-		.cfg = {},                           \
-		.cfg_changed = _changed,             \
-		.cfg_write = _write,                 \
-		.cfg_match = _match,                 \
+#define BT_GATT_CCC_MANAGED_USER_DATA_INIT(_changed, _write, _match)                               \
+	{                                                                                          \
+		.cfg = {},                                                                         \
+		.cfg_changed = _changed,                                                           \
+		.cfg_write = _write,                                                               \
+		.cfg_match = _match,                                                               \
 	}
 
 /**
  *  @brief Managed Client Characteristic Configuration Declaration Macro.
  *
  *  Helper macro to declare a Managed CCC attribute.
  *
- *  @param _ccc CCC attribute user data, shall point to a _bt_gatt_ccc.
+ *  @param _ccc A new @ref bt_gatt_ccc_managed_user_data object with the same lifetime
+ *              as the results of the call to BT_GATT_CCC_MANAGED.
+ *              See the documentation of @ref bt_gatt_ccc_managed_user_data on how
+ *              to initialize it.
  *  @param _perm CCC access permissions,
  *               a bitmap of @ref bt_gatt_perm values.
  */
@@ -1163,9 +1175,10 @@ ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
  *  @param _perm CCC access permissions,
  *               a bitmap of @ref bt_gatt_perm values.
  */
-#define BT_GATT_CCC(_changed, _perm)				\
-	BT_GATT_CCC_MANAGED(((struct _bt_gatt_ccc[])			\
-		{BT_GATT_CCC_INITIALIZER(_changed, NULL, NULL)}), _perm)
+#define BT_GATT_CCC(_changed, _perm)                                                               \
+	BT_GATT_CCC_MANAGED(((struct bt_gatt_ccc_managed_user_data[]){                             \
+				    BT_GATT_CCC_MANAGED_USER_DATA_INIT(_changed, NULL, NULL)}),    \
+			    _perm)
 
 /**
  *  @brief Client Characteristic Configuration Declaration Macro with write callback.
@@ -1177,9 +1190,10 @@ ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
  *  @param _perm CCC access permissions,
  *               a bitmap of @ref bt_gatt_perm values.
  */
-#define BT_GATT_CCC_WITH_WRITE_CB(_changed, _write, _perm)		\
-	BT_GATT_CCC_MANAGED(((struct _bt_gatt_ccc[])			\
-		{BT_GATT_CCC_INITIALIZER(_changed, _write, NULL) }), _perm)
+#define BT_GATT_CCC_WITH_WRITE_CB(_changed, _write, _perm)                                         \
+	BT_GATT_CCC_MANAGED(((struct bt_gatt_ccc_managed_user_data[]){                             \
+				    BT_GATT_CCC_MANAGED_USER_DATA_INIT(_changed, _write, NULL)}),  \
+			    _perm)
 
 /** @brief Read Characteristic Extended Properties Attribute helper
  *

subsys/bluetooth/audio/audio_internal.h

@@ -61,9 +61,10 @@ ssize_t bt_audio_ccc_cfg_write(struct bt_conn *conn, const struct bt_gatt_attr *
 			       uint16_t value);
 
 /** Helper to define LE Audio CCC descriptor. */
-#define BT_AUDIO_CCC(_changed)								\
-	BT_GATT_CCC_MANAGED(((struct _bt_gatt_ccc[])					\
-		{BT_GATT_CCC_INITIALIZER(_changed, bt_audio_ccc_cfg_write, NULL)}),	\
+#define BT_AUDIO_CCC(_changed)                                                                     \
+	BT_GATT_CCC_MANAGED(                                                                       \
+		((struct bt_gatt_ccc_managed_user_data[]){BT_GATT_CCC_MANAGED_USER_DATA_INIT(      \
+			_changed, bt_audio_ccc_cfg_write, NULL)}),                                 \
 		(BT_GATT_PERM_READ | BT_GATT_PERM_WRITE_ENCRYPT))
 
 static inline const char *bt_audio_dir_str(enum bt_audio_dir dir)

subsys/bluetooth/host/gatt.c

@@ -486,9 +486,8 @@ static ssize_t sc_ccc_cfg_write(struct bt_conn *conn,
 	return sizeof(value);
 }
 
-static struct _bt_gatt_ccc sc_ccc = BT_GATT_CCC_INITIALIZER(NULL,
-							    sc_ccc_cfg_write,
-							    NULL);
+static struct bt_gatt_ccc_managed_user_data sc_ccc =
+	BT_GATT_CCC_MANAGED_USER_DATA_INIT(NULL, sc_ccc_cfg_write, NULL);
 
 /* Do not shuffle the values in this enum, they are used as bit offsets when
  * saving the CF flags to NVS (i.e. NVS persists between FW upgrades).
@@ -1118,7 +1117,7 @@ struct addr_match {
 static uint8_t convert_to_id_on_match(const struct bt_gatt_attr *attr,
 				      uint16_t handle, void *user_data)
 {
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	struct addr_match *match = user_data;
 
 	if (!is_host_managed_ccc(attr)) {
@@ -1644,7 +1643,7 @@ static void db_changed(void)
 #endif
 }
 
-static void gatt_unregister_ccc(struct _bt_gatt_ccc *ccc)
+static void gatt_unregister_ccc(struct bt_gatt_ccc_managed_user_data *ccc)
 {
 	ccc->value = 0;
 
@@ -2127,7 +2126,7 @@ struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr)
 }
 
 static struct bt_gatt_ccc_cfg *find_ccc_cfg(const struct bt_conn *conn,
-					    struct _bt_gatt_ccc *ccc)
+					    struct bt_gatt_ccc_managed_user_data *ccc)
 {
 	for (size_t i = 0; i < ARRAY_SIZE(ccc->cfg); i++) {
 		struct bt_gatt_ccc_cfg *cfg = &ccc->cfg[i];
@@ -2149,7 +2148,7 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
 			      const struct bt_gatt_attr *attr, void *buf,
 			      uint16_t len, uint16_t offset)
 {
-	struct _bt_gatt_ccc *ccc = attr->user_data;
+	struct bt_gatt_ccc_managed_user_data *ccc = attr->user_data;
 	const struct bt_gatt_ccc_cfg *cfg;
 	uint16_t value;
 
@@ -2166,7 +2165,7 @@ ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn,
 }
 
 static void gatt_ccc_changed(const struct bt_gatt_attr *attr,
-			     struct _bt_gatt_ccc *ccc)
+			     struct bt_gatt_ccc_managed_user_data *ccc)
 {
 	int i;
 	uint16_t value = 0x0000;
@@ -2200,7 +2199,7 @@ ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn,
 			       const struct bt_gatt_attr *attr, const void *buf,
 			       uint16_t len, uint16_t offset, uint8_t flags)
 {
-	struct _bt_gatt_ccc *ccc = attr->user_data;
+	struct bt_gatt_ccc_managed_user_data *ccc = attr->user_data;
 	struct bt_gatt_ccc_cfg *cfg;
 	bool value_changed;
 	uint16_t value;
@@ -2732,7 +2731,7 @@ static uint8_t notify_cb(const struct bt_gatt_attr *attr, uint16_t handle,
 			 void *user_data)
 {
 	struct notify_data *data = user_data;
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	size_t i;
 
 	if (!is_host_managed_ccc(attr)) {
@@ -3321,7 +3320,7 @@ static uint8_t update_ccc(const struct bt_gatt_attr *attr, uint16_t handle,
 {
 	struct conn_data *data = user_data;
 	struct bt_conn *conn = data->conn;
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	size_t i;
 	uint8_t err;
 
@@ -3383,7 +3382,7 @@ static uint8_t disconnected_cb(const struct bt_gatt_attr *attr, uint16_t handle,
 			       void *user_data)
 {
 	struct bt_conn *conn = user_data;
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	bool value_used;
 	size_t i;
 
@@ -5724,7 +5723,7 @@ static struct bt_gatt_exchange_params gatt_exchange_params = {
 #define CCC_STORE_MAX 0
 #endif /* defined(CONFIG_BT_SETTINGS_CCC_STORE_MAX) */
 
-static struct bt_gatt_ccc_cfg *ccc_find_cfg(struct _bt_gatt_ccc *ccc,
+static struct bt_gatt_ccc_cfg *ccc_find_cfg(struct bt_gatt_ccc_managed_user_data *ccc,
 					    const bt_addr_le_t *addr,
 					    uint8_t id)
 {
@@ -5749,7 +5748,7 @@ struct ccc_load {
 	size_t count;
 };
 
-static void ccc_clear(struct _bt_gatt_ccc *ccc,
+static void ccc_clear(struct bt_gatt_ccc_managed_user_data *ccc,
 		      const bt_addr_le_t *addr,
 		      uint8_t id)
 {
@@ -5768,7 +5767,7 @@ static uint8_t ccc_load(const struct bt_gatt_attr *attr, uint16_t handle,
 			void *user_data)
 {
 	struct ccc_load *load = user_data;
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	struct bt_gatt_ccc_cfg *cfg;
 
 	if (!is_host_managed_ccc(attr)) {
@@ -6107,7 +6106,7 @@ static uint8_t ccc_save(const struct bt_gatt_attr *attr, uint16_t handle,
 			void *user_data)
 {
 	struct ccc_save *save = user_data;
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	struct bt_gatt_ccc_cfg *cfg;
 
 	if (!is_host_managed_ccc(attr)) {
@@ -6390,7 +6389,7 @@ static uint8_t remove_peer_from_attr(const struct bt_gatt_attr *attr,
 				     uint16_t handle, void *user_data)
 {
 	const struct addr_with_id *addr_with_id = user_data;
-	struct _bt_gatt_ccc *ccc;
+	struct bt_gatt_ccc_managed_user_data *ccc;
 	struct bt_gatt_ccc_cfg *cfg;
 
 	if (!is_host_managed_ccc(attr)) {

subsys/bluetooth/host/shell/gatt.c

@@ -740,7 +740,7 @@ static int cmd_show_db(const struct shell *sh, size_t argc, char *argv[])
 	total_len = stats.svc_count * sizeof(struct bt_gatt_service);
 	total_len += stats.chrc_count * sizeof(struct bt_gatt_chrc);
 	total_len += stats.attr_count * sizeof(struct bt_gatt_attr);
-	total_len += stats.ccc_count * sizeof(struct _bt_gatt_ccc);
+	total_len += stats.ccc_count * sizeof(struct bt_gatt_ccc_managed_user_data);
 
 	shell_print(sh, "=================================================");
 	shell_print(sh, "Total: %u services %u attributes (%zu bytes)",

subsys/bluetooth/mesh/pb_gatt_srv.c

@@ -149,8 +149,8 @@ static ssize_t prov_ccc_write(struct bt_conn *conn,
 }
 
 /* Mesh Provisioning Service Declaration */
-static struct _bt_gatt_ccc prov_ccc =
-	BT_GATT_CCC_INITIALIZER(prov_ccc_changed, prov_ccc_write, NULL);
+static struct bt_gatt_ccc_managed_user_data prov_ccc =
+	BT_GATT_CCC_MANAGED_USER_DATA_INIT(prov_ccc_changed, prov_ccc_write, NULL);
 
 static struct bt_gatt_attr prov_attrs[] = {
 	BT_GATT_PRIMARY_SERVICE(BT_UUID_MESH_PROV),

subsys/bluetooth/mesh/proxy_srv.c

@@ -937,8 +937,8 @@ static ssize_t proxy_ccc_write(struct bt_conn *conn,
 }
 
 /* Mesh Proxy Service Declaration */
-static struct _bt_gatt_ccc proxy_ccc =
-	BT_GATT_CCC_INITIALIZER(proxy_ccc_changed, proxy_ccc_write, NULL);
+static struct bt_gatt_ccc_managed_user_data proxy_ccc =
+	BT_GATT_CCC_MANAGED_USER_DATA_INIT(proxy_ccc_changed, proxy_ccc_write, NULL);
 
 static struct bt_gatt_attr proxy_attrs[] = {
 	BT_GATT_PRIMARY_SERVICE(BT_UUID_MESH_PROXY),

subsys/bluetooth/services/ots/ots_internal.h

@@ -120,7 +120,7 @@ struct bt_gatt_ots_object {
 struct bt_gatt_ots_indicate {
 	struct bt_gatt_indicate_params params;
 	struct bt_gatt_attr attr;
-	struct _bt_gatt_ccc ccc;
+	struct bt_gatt_ccc_managed_user_data ccc;
 	bool is_enabled;
 	struct k_work work;
 	uint8_t res[OACP_OLCP_RES_MAX_SIZE];

subsys/bluetooth/services/ots/ots_oacp.c

@@ -728,7 +728,7 @@ void bt_gatt_ots_oacp_cfg_changed(const struct bt_gatt_attr *attr,
 				      uint16_t value)
 {
 	struct bt_gatt_ots_indicate *oacp_ind =
-	    CONTAINER_OF((struct _bt_gatt_ccc *) attr->user_data,
+	    CONTAINER_OF((struct bt_gatt_ccc_managed_user_data *) attr->user_data,
 			 struct bt_gatt_ots_indicate, ccc);
 
 	LOG_DBG("Object Action Control Point CCCD value: 0x%04X", value);

subsys/bluetooth/services/ots/ots_olcp.c

@@ -311,7 +311,7 @@ void bt_gatt_ots_olcp_cfg_changed(const struct bt_gatt_attr *attr,
 				      uint16_t value)
 {
 	struct bt_gatt_ots_indicate *olcp_ind =
-	    CONTAINER_OF((struct _bt_gatt_ccc *) attr->user_data,
+	    CONTAINER_OF((struct bt_gatt_ccc_managed_user_data *) attr->user_data,
 			 struct bt_gatt_ots_indicate, ccc);
 
 	LOG_DBG("Object List Control Point CCCD value: 0x%04X", value);

tests/bsim/bluetooth/ll/edtt/gatt_test_app/src/gatt/gatt_macs.h

@@ -138,7 +138,7 @@ extern "C" {
  *
  *  Helper macro to declare a Managed CCC attribute.
  *
- *  @param _ccc    CCC attribute user data, shall point to a _bt_gatt_ccc.
+ *  @param _ccc    CCC attribute user data, shall point to a bt_gatt_ccc_managed_user_data.
  *  @param _perm   CCC access permissions.
  *  @param _handle Descriptor attribute handle.
  */
@@ -161,7 +161,7 @@ extern "C" {
  *         BT_GATT_PERM_READ | BT_GATT_PERM_WRITE, \
  *         bt_gatt_attr_read_ccc, \
  *         bt_gatt_attr_write_ccc, \
- *         (&(struct _bt_gatt_ccc) { \
+ *         (&(struct bt_gatt_ccc_managed_user_data) { \
  *             .cfg = _cfg, \
  *             .cfg_len = ARRAY_SIZE(_cfg), \
  *             .cfg_changed = _cfg_changed \
@@ -177,10 +177,10 @@ extern "C" {
  *  @param _cfg_changed Configuration changed callback.
  *  @param _handle      Descriptor attribute handle.
  */
-#define BT_GATT_H_CCC(_cfg, _cfg_changed, _handle) \
-		BT_GATT_H_MANAGED((&(struct _bt_gatt_ccc) \
-			BT_GATT_CCC_INITIALIZER(_cfg_changed, NULL, NULL)),\
-			BT_GATT_PERM_READ | BT_GATT_PERM_WRITE, _handle)
+#define BT_GATT_H_CCC(_cfg, _cfg_changed, _handle)                                                 \
+	BT_GATT_H_MANAGED((&(struct bt_gatt_ccc_managed_user_data)                                 \
+				   BT_GATT_CCC_MANAGED_USER_DATA_INIT(_cfg_changed, NULL, NULL)),  \
+			  BT_GATT_PERM_READ | BT_GATT_PERM_WRITE, _handle)
 
 /**
  *  @brief Characteristic Extended Properties Declaration Macro.