1 /* 2 * Copyright (c) 2006-2025 RT-Thread Development Team 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Change Logs: 7 * Date Author Notes 8 * 2017-05-09 Urey first version 9 * 2019-07-09 Zero-Free improve device ops interface and data flows 10 * 2025-03-04 wumingzi add doxygen comments. 11 */ 12 13 #ifndef __DEV_AUDIO_H__ 14 #define __DEV_AUDIO_H__ 15 16 #include "dev_audio_pipe.h" 17 18 /** 19 * @defgroup group_drivers_audio Audio 20 * @brief Audio driver API. 21 * @ingroup group_device_driver 22 * 23 * @{ 24 */ 25 26 /** 27 * @defgroup group_audio_control AUDIO_CTL 28 * 29 * @brief Control audio device. 30 * 31 * @{ 32 */ 33 34 /** 35 * @brief Generate audio command code with @a a 36 * 37 * @param[in] a offset of command. 38 * 39 * @return audio device control command code. 40 */ 41 #define _AUDIO_CTL(a) (RT_DEVICE_CTRL_BASE(Sound) + a) 42 43 #define AUDIO_CTL_GETCAPS _AUDIO_CTL(1) /**< Get audio device capabilities */ 44 #define AUDIO_CTL_CONFIGURE _AUDIO_CTL(2) /**< Get audio device configuration */ 45 #define AUDIO_CTL_START _AUDIO_CTL(3) /**< Start audio device */ 46 #define AUDIO_CTL_STOP _AUDIO_CTL(4) /**< Stop audio device */ 47 #define AUDIO_CTL_GETBUFFERINFO _AUDIO_CTL(5) /**< Get audio device buffer information */ 48 49 /** @} */ /* End of group_audio_control */ 50 51 /** 52 * @defgroup group_audio_type AUDIO_TYPE 53 * 54 * @brief Audio Device Types 55 * 56 * @{ 57 */ 58 #define AUDIO_TYPE_QUERY 0x00 /**< Query audio device type */ 59 #define AUDIO_TYPE_INPUT 0x01 /**< Set audio device type to input type */ 60 #define AUDIO_TYPE_OUTPUT 0x02 /**< Set audio device type to output type */ 61 #define AUDIO_TYPE_MIXER 0x04 /**< Set audio device type to mixer type */ 62 /** @} */ /* End of group_audio_type */ 63 64 /** 65 * @defgroup group_audio_samp_rates AUDIO_SAMP_RATES 66 * 67 * @brief Supported audio sample rates for the audio device. 68 * 69 * @{ 70 */ 71 #define AUDIO_SAMP_RATE_8K 0x0001 /**< Set audio device sample rate to 8K */ 72 #define AUDIO_SAMP_RATE_11K 0x0002 /**< Set audio device sample rate to 11K */ 73 #define AUDIO_SAMP_RATE_16K 0x0004 /**< Set audio device sample rate to 16K */ 74 #define AUDIO_SAMP_RATE_22K 0x0008 /**< Set audio device sample rate to 22K */ 75 #define AUDIO_SAMP_RATE_32K 0x0010 /**< Set audio device sample rate to 32K */ 76 #define AUDIO_SAMP_RATE_44K 0x0020 /**< Set audio device sample rate to 44K */ 77 #define AUDIO_SAMP_RATE_48K 0x0040 /**< Set audio device sample rate to 48K */ 78 #define AUDIO_SAMP_RATE_96K 0x0080 /**< Set audio device sample rate to 96K */ 79 #define AUDIO_SAMP_RATE_128K 0x0100 /**< Set audio device sample rate to 128K */ 80 #define AUDIO_SAMP_RATE_160K 0x0200 /**< Set audio device sample rate to 160K */ 81 #define AUDIO_SAMP_RATE_172K 0x0400 /**< Set audio device sample rate to 172K */ 82 #define AUDIO_SAMP_RATE_192K 0x0800 /**< Set audio device sample rate to 192K */ 83 /** @} */ /* End of group_audio_samp_rates */ 84 85 /** 86 * @defgroup group_audio_bit_rates AUDIO_BIT_RATES 87 * 88 * @brief Supported bit rates for the audio device. 89 * 90 * @{ 91 */ 92 #define AUDIO_BIT_RATE_22K 0x01 /**< Set audio device bit rates to 22K */ 93 #define AUDIO_BIT_RATE_44K 0x02 /**< Set audio device bit rates to 44K */ 94 #define AUDIO_BIT_RATE_48K 0x04 /**< Set audio device bit rates to 48K */ 95 #define AUDIO_BIT_RATE_96K 0x08 /**< Set audio device bit rates to 96K */ 96 #define AUDIO_BIT_RATE_128K 0x10 /**< Set audio device bit rates to 128K */ 97 #define AUDIO_BIT_RATE_160K 0x20 /**< Set audio device bit rates to 160K */ 98 #define AUDIO_BIT_RATE_172K 0x40 /**< Set audio device bit rates to 172K */ 99 #define AUDIO_BIT_RATE_192K 0x80 /**< Set audio device bit rates to 192K */ 100 /** @} */ /* End of group_audio_bit_rates */ 101 102 103 /** 104 * @defgroup group_audio_dsp AUDIO_DSP 105 * 106 * @brief Support Dsp(input/output) Units controls. The macro group from application level, can 107 * set audio mixer parameters including samplerate, channels etc. 108 * 109 * @{ 110 */ 111 #define AUDIO_DSP_PARAM 0 /**< get/set all params */ 112 #define AUDIO_DSP_SAMPLERATE 1 /**< samplerate */ 113 #define AUDIO_DSP_CHANNELS 2 /**< channels */ 114 #define AUDIO_DSP_SAMPLEBITS 3 /**< sample bits width */ 115 /** @} */ /* End of group_audio_dsp */ 116 117 /** 118 * @defgroup group_audio_mixer AUDIO_MIXER 119 * 120 * @brief Supported Mixer Units controls. The macro group from driver level, can set audio mixer 121 * parameters including volume, frequence db, microphone etc. 122 * 123 * @{ 124 */ 125 #define AUDIO_MIXER_QUERY 0x0000 /**< Query mixer capabilities */ 126 #define AUDIO_MIXER_MUTE 0x0001 /**< Mute audio device */ 127 #define AUDIO_MIXER_VOLUME 0x0002 /**< Set mixer volume */ 128 #define AUDIO_MIXER_BASS 0x0004 /**< Set the low-frequency section of the mixer */ 129 #define AUDIO_MIXER_MID 0x0008 /**< Set the mid-frequency section of the mixer */ 130 #define AUDIO_MIXER_TREBLE 0x0010 /**< Set the high-frequency section of the mixer */ 131 #define AUDIO_MIXER_EQUALIZER 0x0020 /**< Set equalizer option */ 132 #define AUDIO_MIXER_LINE 0x0040 /**< Set line control option */ 133 #define AUDIO_MIXER_DIGITAL 0x0080 /**< Set digital source */ 134 #define AUDIO_MIXER_MIC 0x0100 /**< Set microphone option */ 135 #define AUDIO_MIXER_VITURAL 0x0200 /**< Set virtual audio option */ 136 #define AUDIO_MIXER_EXTEND 0x8000 /**< Extend mixer command */ 137 /** @} */ /* End of group_audio_mixer */ 138 139 #define AUDIO_VOLUME_MAX (100) 140 #define AUDIO_VOLUME_MIN (0) 141 142 #define CFG_AUDIO_REPLAY_QUEUE_COUNT 4 143 144 /** 145 * @enum audio_stream 146 * 147 * @brief Audio stream control command 148 */ 149 enum audio_stream 150 { 151 AUDIO_STREAM_REPLAY = 0, 152 AUDIO_STREAM_RECORD, 153 AUDIO_STREAM_LAST = AUDIO_STREAM_RECORD, 154 }; 155 156 /** 157 * @brief Audio buffer info 158 * 159 * The preferred number and size of audio pipeline buffer for the audio device, it 160 * will be used in rt_audio_replay struct. 161 * 162 */ 163 struct rt_audio_buf_info 164 { 165 rt_uint8_t *buffer; /**< Audio buffer information */ 166 rt_uint16_t block_size; /**< Audio block_size information for replay function */ 167 rt_uint16_t block_count; /**< Audio block_count information for replay function */ 168 rt_uint32_t total_size; /**< Audio total_size which is equal to block_size multiplying 169 * block_count information for replay function */ 170 }; 171 172 struct rt_audio_device; 173 struct rt_audio_caps; 174 struct rt_audio_configure; 175 176 /** 177 * @brief Aduio device operators 178 */ 179 struct rt_audio_ops 180 { 181 /** Get audio capabilities information */ 182 rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps); 183 /** Configure audio devices */ 184 rt_err_t (*configure)(struct rt_audio_device *audio, struct rt_audio_caps *caps); 185 /** Initialize audio device */ 186 rt_err_t (*init)(struct rt_audio_device *audio); 187 /** Turn on the audio device */ 188 rt_err_t (*start)(struct rt_audio_device *audio, int stream); 189 /** Turn off the audio device */ 190 rt_err_t (*stop)(struct rt_audio_device *audio, int stream); 191 /** Transmit data between application and device */ 192 rt_ssize_t (*transmit)(struct rt_audio_device *audio, const void *writeBuf, void *readBuf, rt_size_t size); 193 /** Get page size of codec or private buffer's info */ 194 void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info); 195 }; 196 197 /** 198 * @brief Audio configuration 199 * 200 * The preferred number and size of audio pipeline buffer for the audio device, it 201 * will be used in rt_audio_caps struct. 202 * 203 */ 204 struct rt_audio_configure 205 { 206 rt_uint32_t samplerate; /**< Audio samplerate information */ 207 rt_uint16_t channels; /**< Audio channels information */ 208 rt_uint16_t samplebits; /**< Audio samplebits information */ 209 }; 210 211 /** 212 * @brief Audio capabilities 213 */ 214 struct rt_audio_caps 215 { 216 int main_type; /**< Audio main type, one value of @ref group_audio_type */ 217 int sub_type; /**< Audio sub type, one value of @ref group_audio_dsp or @ref group_audio_mixer */ 218 219 union 220 { 221 rt_uint32_t mask; /**< Capabilities mask */ 222 int value; /**< Capabilities value */ 223 struct rt_audio_configure config; /**< Audio samplebits information */ 224 } udata; /**< User data */ 225 }; 226 227 /** 228 * @brief Audio replay 229 */ 230 struct rt_audio_replay 231 { 232 struct rt_mempool *mp; /**< Memory pool for audio replay */ 233 struct rt_data_queue queue; /**< Replay data queue */ 234 struct rt_mutex lock; /**< Replay mutex lock */ 235 struct rt_completion cmp; /**< Replay completion, it will be */ 236 struct rt_audio_buf_info buf_info; /**< Replay buffer information */ 237 rt_uint8_t *write_data; /**< Pointer to the data to be written into data queue */ 238 rt_uint16_t write_index; /**< Index of pointer write_data.It records how much data 239 * has been written in currently being played block */ 240 rt_uint16_t read_index; /**< Index of replaying data for audio device, it indicates index 241 * of replay in the blocks which is currently being played */ 242 rt_uint32_t pos; /**< Global position of audio replay */ 243 rt_uint8_t event; /**< Event flag */ 244 rt_bool_t activated; /**< Activaty flag */ 245 }; 246 247 /** 248 * @brief Audio record, the audio device pipe container of ringbuffer 249 */ 250 struct rt_audio_record 251 { 252 struct rt_audio_pipe pipe; 253 rt_bool_t activated; 254 }; 255 256 /** 257 * @brief Audio device 258 */ 259 struct rt_audio_device 260 { 261 struct rt_device parent; /**< Audio device parents */ 262 struct rt_audio_ops *ops; /**< Audio device operator */ 263 struct rt_audio_replay *replay; /**< Pointer to audio replay structure */ 264 struct rt_audio_record *record; /**< Pointer to audio record structure */ 265 }; 266 267 rt_err_t rt_audio_register(struct rt_audio_device *audio, const char *name, rt_uint32_t flag, void *data); 268 void rt_audio_tx_complete(struct rt_audio_device *audio); 269 void rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt_size_t len); 270 271 /** 272 * @defgroup group_audio_codec_cmd CODEC_CMD 273 * 274 * @brief Device Control Commands. The macro group from hardware level, can set codec 275 * parametes including volume, EQ and 3D etc. 276 * 277 * @{ 278 */ 279 #define CODEC_CMD_RESET 0 /**< Reset audio device by codec */ 280 #define CODEC_CMD_SET_VOLUME 1 /**< Set volume by codec */ 281 #define CODEC_CMD_GET_VOLUME 2 /**< Get volume by codec */ 282 #define CODEC_CMD_SAMPLERATE 3 /**< Set sample rate by codec */ 283 #define CODEC_CMD_EQ 4 /**< Set equalizer by codec */ 284 #define CODEC_CMD_3D 5 /**< Set 3D effect by codec */ 285 286 #define CODEC_VOLUME_MAX (63) 287 /** @} */ /* End of group_audio_codec_cmd */ 288 289 /** @} group_drivers_audio */ 290 291 #endif /* __DEV_AUDIO_H__ */