host/audio_common: Add doxygen comments in the header file
Adds missing structures and macros documentation.
Adds minor corrections to existing entries.
diff --git a/nimble/host/include/host/ble_audio_common.h b/nimble/host/include/host/ble_audio_common.h
index d5e0afb..815d3f4 100644
--- a/nimble/host/include/host/ble_audio_common.h
+++ b/nimble/host/include/host/ble_audio_common.h
@@ -20,10 +20,24 @@
#ifndef H_BLE_AUDIO_COMMON_
#define H_BLE_AUDIO_COMMON_
+/**
+ * @file ble_audio_common.h
+ *
+ * @brief Bluetooth Low Energy Audio Common API
+ *
+ * @defgroup bt_le_audio_common Bluetooth LE Audio Common
+ * @ingroup bt_host
+ * @{
+ */
+
#include "stdint.h"
#include "os/queue.h"
-/** Helper macros for BLE_AUDIO_BUILD_CODEC_CONFIG */
+/**
+ * @cond
+ * Helper macros for BLE_AUDIO_BUILD_CODEC_CONFIG
+ * @{
+ */
#define FIELD_LEN_2(_len, _type, _field) _len, _type, _field,
#define FIELD_LEN_5(_len, _type, _field) _len, _type, _field, \
_field >> 8, _field >> 16, \
@@ -46,58 +60,178 @@
_type, \
__VA_ARGS__)
+/**
+ * @}
+ * @endcond
+ */
+
+/** Broadcast Audio Announcement Service UUID. */
#define BLE_BROADCAST_AUDIO_ANNOUNCEMENT_SVC_UUID 0x1852
#define BLE_BROADCAST_PUBLIC_BROADCAST_ANNOUNCEMENT_SVC_UUID 0x1856
+/**
+ * @defgroup ble_audio_sampling_rates Bluetooth Low Energy Audio Sampling Rates
+ * @{
+ */
+
+/** LE Audio Sampling Rate: 8000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_8000_HZ 0x01
+
+/** LE Audio Sampling Rate: 11025 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_11025_HZ 0x02
+
+/** LE Audio Sampling Rate: 16000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_16000_HZ 0x03
+
+/** LE Audio Sampling Rate: 22050 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_22050_HZ 0x04
+
+/** LE Audio Sampling Rate: 24000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_24000_HZ 0x05
+
+/** LE Audio Sampling Rate: 32000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_32000_HZ 0x06
+
+/** LE Audio Sampling Rate: 44100 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_44100_HZ 0x07
+
+/** LE Audio Sampling Rate: 48000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_48000_HZ 0x08
+
+/** LE Audio Sampling Rate: 88200 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_88200_HZ 0x09
+
+/** LE Audio Sampling Rate: 96000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_96000_HZ 0x0A
+
+/** LE Audio Sampling Rate: 176400 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_176400_HZ 0x0B
+
+/** LE Audio Sampling Rate: 192000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_192000_HZ 0x0C
+
+/** LE Audio Sampling Rate: 384000 Hz. */
#define BLE_AUDIO_SAMPLING_RATE_384000_HZ 0x0D
+/** @} */
+
+/**
+ * @defgroup ble_audio_frame_durations Bluetooth Low Energy Audio Frame Durations
+ * @{
+ */
+
+/** LE Audio Frame Duration: 7.5 ms. */
#define BLE_AUDIO_SELECTED_FRAME_DURATION_7_5_MS 0x00
+
+/** LE Audio Frame Duration: 10 ms. */
#define BLE_AUDIO_SELECTED_FRAME_DURATION_10_MS 0x01
+/** @} */
+
+/**
+ * @defgroup ble_audio_locations Bluetooth Low Energy Audio Locations
+ * @{
+ */
+
+/** LE Audio Location: Front Left. */
#define BLE_AUDIO_LOCATION_FRONT_LEFT (1ULL)
+
+/** LE Audio Location: Front Right. */
#define BLE_AUDIO_LOCATION_FRONT_RIGHT (1ULL << 1)
+
+/** LE Audio Location: Front Center. */
#define BLE_AUDIO_LOCATION_FRONT_CENTER (1ULL << 2)
+
+/** LE Audio Location: Low Frequency Effects 1. */
#define BLE_AUDIO_LOCATION_LOW_FREQ_EFFECTS_1 (1ULL << 3)
+
+/** LE Audio Location: Back Left. */
#define BLE_AUDIO_LOCATION_BACK_LEFT (1ULL << 4)
+
+/** LE Audio Location: Front Left Center. */
#define BLE_AUDIO_LOCATION_FRONT_LEFT_CENTER (1ULL << 5)
+
+/** LE Audio Location: Front Right Center. */
#define BLE_AUDIO_LOCATION_FRONT_RIGHT_CENTER (1ULL << 6)
+
+/** LE Audio Location: Back Center. */
#define BLE_AUDIO_LOCATION_BACK_CENTER (1ULL << 7)
+
+/** LE Audio Location: Low Frequency Effects 2. */
#define BLE_AUDIO_LOCATION_LOW_FREQ_EFFECTS_2 (1ULL << 8)
+
+/** LE Audio Location: Side Left. */
#define BLE_AUDIO_LOCATION_SIDE_LEFT (1ULL << 9)
+
+/** LE Audio Location: Side Right. */
#define BLE_AUDIO_LOCATION_SIDE_RIGHT (1ULL << 10)
+
+/** LE Audio Location: Top Front Left. */
#define BLE_AUDIO_LOCATION_TOP_FRONT_LEFT (1ULL << 11)
+
+/** LE Audio Location: Top Front Right. */
#define BLE_AUDIO_LOCATION_TOP_FRONT_RIGHT (1ULL << 12)
+
+/** LE Audio Location: Top Front Center. */
#define BLE_AUDIO_LOCATION_TOP_FRONT_CENTER (1ULL << 13)
+
+/** LE Audio Location: Top Center. */
#define BLE_AUDIO_LOCATION_TOP_CENTER (1ULL << 14)
+
+/** LE Audio Location: Top Back Left. */
#define BLE_AUDIO_LOCATION_TOP_BACK_LEFT (1ULL << 15)
+
+/** LE Audio Location: Top Back Right. */
#define BLE_AUDIO_LOCATION_TOP_BACK_RIGHT (1ULL << 16)
+
+/** LE Audio Location: Top Side Left. */
#define BLE_AUDIO_LOCATION_TOP_SIDE_LEFT (1ULL << 17)
+
+/** LE Audio Location: Top Side Right. */
#define BLE_AUDIO_LOCATION_TOP_SIDE_RIGHT (1ULL << 18)
+
+/** LE Audio Location: Top Back Center. */
#define BLE_AUDIO_LOCATION_TOP_BACK_CENTER (1ULL << 19)
+
+/** LE Audio Location: Bottom Front Center. */
#define BLE_AUDIO_LOCATION_BOTTOM_FRONT_CENTER (1ULL << 20)
+
+/** LE Audio Location: Bottom Front Left. */
#define BLE_AUDIO_LOCATION_BOTTOM_FRONT_LEFT (1ULL << 21)
+
+/** LE Audio Location: Bottom Front Right. */
#define BLE_AUDIO_LOCATION_BOTTOM_FRONT_RIGHT (1ULL << 22)
+
+/** LE Audio Location: Left Surround. */
#define BLE_AUDIO_LOCATION_LEFT_SURROUND (1ULL << 23)
+
+/** LE Audio Location: Right Surround. */
#define BLE_AUDIO_LOCATION_RIGHT_SURROUND (1ULL << 24)
+/** @} */
+
+/**
+ * @defgroup ble_audio_codec_config Bluetooth Low Energy Audio Codec Specific Config
+ * @{
+ */
+
+/** LE Audio Codec Config Type: Sampling Frequency. */
#define BLE_AUDIO_CODEC_SAMPLING_FREQ_TYPE 0x01
+
+/** LE Audio Codec Config Type: Frame Duration. */
#define BLE_AUDIO_CODEC_FRAME_DURATION_TYPE 0x02
+
+/** LE Audio Codec Config Type: Channel Allocation. */
#define BLE_AUDIO_CODEC_AUDIO_CHANNEL_ALLOCATION_TYPE 0x03
+
+/** LE Audio Codec Config Type: Octets Per Codec Frame. */
#define BLE_AUDIO_CODEC_OCTETS_PER_CODEC_FRAME_TYPE 0x04
+
+/** LE Audio Codec Config Type: Frame Blocks Per SDU. */
#define BLE_AUDIO_CODEC_FRAME_BLOCKS_PER_SDU_TYPE 0x05
+/** @} */
+
/**
* @brief Helper macro used to build LTV array of Codec_Specific_Configuration.
*
@@ -128,8 +262,9 @@
_codec_frame_blocks_per_sdu) \
}
+/** Codec Information */
struct ble_audio_codec_id {
- /** Coding Fromat */
+ /** Coding Format */
uint8_t format;
/** Company ID */
@@ -139,6 +274,7 @@
uint16_t vendor_specific;
};
+/** Broadcast Isochronous Streams (BIS) */
struct ble_audio_bis {
/** Pointer to next BIS in subgroup */
STAILQ_ENTRY(ble_audio_bis) next;
@@ -146,13 +282,14 @@
/** BIS index */
uint8_t idx;
- /** BIS level Codec Specific Configuration */
+ /** BIS level Codec Specific Configuration length */
uint8_t codec_spec_config_len;
- /** BIS level Codec Specific Configuration length */
+ /** BIS level Codec Specific Configuration */
uint8_t *codec_spec_config;
};
+/** Broadcast Isochronous Group (BIG) Subgroup */
struct ble_audio_big_subgroup {
/** Pointer to next subgroup in BIG */
STAILQ_ENTRY(ble_audio_big_subgroup) next;
@@ -179,6 +316,7 @@
STAILQ_HEAD(, ble_audio_bis) bises;
};
+/** Broadcast Audio Source Endpoint */
struct ble_audio_base {
/** Broadcast ID */
uint32_t broadcast_id;
@@ -193,4 +331,8 @@
STAILQ_HEAD(, ble_audio_big_subgroup) subs;
};
+/**
+ * @}
+ */
+
#endif /* H_BLE_AUDIO_COMMON_ */
