From 26df457d7f2dd1ed5af7dd156d0c5e4fb12e3bba Mon Sep 17 00:00:00 2001 From: Wojciech Pietraszewski Date: Mon, 19 Feb 2024 17:29:24 +0100 Subject: [PATCH] host/audio_common: Add doxygen comments in the header file Adds missing structures and macros documentation. Adds minor corrections to existing entries. --- nimble/host/include/host/ble_audio_common.h | 150 +++++++++++++++++++- 1 file changed, 146 insertions(+), 4 deletions(-) diff --git a/nimble/host/include/host/ble_audio_common.h b/nimble/host/include/host/ble_audio_common.h index d5e0afb68c..815d3f4c0d 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 @@ struct ble_audio_codec_id { 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 @@ struct ble_audio_bis { /** 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 @@ struct ble_audio_big_subgroup { STAILQ_HEAD(, ble_audio_bis) bises; }; +/** Broadcast Audio Source Endpoint */ struct ble_audio_base { /** Broadcast ID */ uint32_t broadcast_id; @@ -193,4 +331,8 @@ struct ble_audio_base { STAILQ_HEAD(, ble_audio_big_subgroup) subs; }; +/** + * @} + */ + #endif /* H_BLE_AUDIO_COMMON_ */