diff --git a/components/drivers/audio/dev_audio.c b/components/drivers/audio/dev_audio.c index fd5bc47206..64e847a1fd 100644 --- a/components/drivers/audio/dev_audio.c +++ b/components/drivers/audio/dev_audio.c @@ -7,6 +7,7 @@ * Date Author Notes * 2017-05-09 Urey first version * 2019-07-09 Zero-Free improve device ops interface and data flows + * 2025-03-04 wumingzi add doxygen comments. */ #include @@ -23,7 +24,7 @@ #endif /** - * @addtogroup group_AudioPipe + * @addtogroup group_Audio */ /** @{ */ diff --git a/components/drivers/audio/dev_audio_pipe.c b/components/drivers/audio/dev_audio_pipe.c index 80f671b8c2..686b053c1e 100644 --- a/components/drivers/audio/dev_audio_pipe.c +++ b/components/drivers/audio/dev_audio_pipe.c @@ -6,6 +6,7 @@ * Change Logs: * Date Author Notes * 2012-09-30 Bernard first version. + * 2025-03-04 wumingzi add doxygen comments. */ #include diff --git a/components/drivers/audio/dev_audio_pipe.h b/components/drivers/audio/dev_audio_pipe.h index 5050c7baa8..af7c507109 100644 --- a/components/drivers/audio/dev_audio_pipe.h +++ b/components/drivers/audio/dev_audio_pipe.h @@ -5,6 +5,7 @@ * * Change Logs: * Date Author Notes + * 2025-03-04 wumingzi add doxygen comments. */ #ifndef __DEV_AUDIO_PIPE_H__ #define __DEV_AUDIO_PIPE_H__ diff --git a/components/drivers/include/drivers/dev_audio.h b/components/drivers/include/drivers/dev_audio.h index 9d9e1af632..b9e9f7055c 100644 --- a/components/drivers/include/drivers/dev_audio.h +++ b/components/drivers/include/drivers/dev_audio.h @@ -7,7 +7,7 @@ * Date Author Notes * 2017-05-09 Urey first version * 2019-07-09 Zero-Free improve device ops interface and data flows - * + * 2025-03-04 wumingzi add doxygen comments. */ #ifndef __DEV_AUDIO_H__ @@ -21,10 +21,7 @@ * @ingroup group_Drivers RT-Thread Drivers * * @brief Audio driver API. - */ - -/** - * @addtogroup group_Audio + * * @{ */ @@ -32,10 +29,7 @@ * @defgroup audio_control AUDIO_CTL * * @brief Control audio device. - */ - -/** - * @addtogroup audio_control + * * @{ */ @@ -54,32 +48,26 @@ #define AUDIO_CTL_STOP _AUDIO_CTL(4) /**< Stop audio device */ #define AUDIO_CTL_GETBUFFERINFO _AUDIO_CTL(5) /**< Get audio device buffer information */ -/** @} */ /* End of audio_control*/ +/** @} */ /* End of audio_control */ /** * @defgroup audio_type AUDIO_TYPE * * @brief Audio Device Types - */ - -/** - * @addtogroup audio_type + * * @{ */ #define AUDIO_TYPE_QUERY 0x00 /**< Query audio device type */ #define AUDIO_TYPE_INPUT 0x01 /**< Set audio device type to input type */ #define AUDIO_TYPE_OUTPUT 0x02 /**< Set audio device type to output type */ #define AUDIO_TYPE_MIXER 0x04 /**< Set audio device type to mixer type */ -/** @} */ /* End of audio_type*/ +/** @} */ /* End of audio_type */ /** * @defgroup audio_samp_rates AUDIO_SAMP_RATES * * @brief Supported audio sample rates for the audio device. - */ - -/** - * @addtogroup audio_samp_rates + * * @{ */ #define AUDIO_SAMP_RATE_8K 0x0001 /**< Set audio device sample rate to 8K */ @@ -94,16 +82,13 @@ #define AUDIO_SAMP_RATE_160K 0x0200 /**< Set audio device sample rate to 160K */ #define AUDIO_SAMP_RATE_172K 0x0400 /**< Set audio device sample rate to 172K */ #define AUDIO_SAMP_RATE_192K 0x0800 /**< Set audio device sample rate to 192K */ -/** @} */ /* End of audio_samp_rates*/ +/** @} */ /* End of audio_samp_rates */ /** * @defgroup audio_bit_rates AUDIO_BIT_RATES * * @brief Supported bit rates for the audio device. - */ - -/** - * @addtogroup audio_bit_rates + * * @{ */ #define AUDIO_BIT_RATE_22K 0x01 /**< Set audio device bit rates to 22K */ @@ -114,40 +99,36 @@ #define AUDIO_BIT_RATE_160K 0x20 /**< Set audio device bit rates to 160K */ #define AUDIO_BIT_RATE_172K 0x40 /**< Set audio device bit rates to 172K */ #define AUDIO_BIT_RATE_192K 0x80 /**< Set audio device bit rates to 192K */ -/** @} */ /* End of audio_bit_rates*/ +/** @} */ /* End of audio_bit_rates */ /** * @defgroup audio_dsp AUDIO_DSP * - * @brief Support Dsp(input/output) Units controls - */ - -/** - * @addtogroup audio_dsp + * @brief Support Dsp(input/output) Units controls. The macro group from application level, can + * set audio mixer parameters including samplerate, channels etc. + * * @{ */ #define AUDIO_DSP_PARAM 0 /**< get/set all params */ #define AUDIO_DSP_SAMPLERATE 1 /**< samplerate */ #define AUDIO_DSP_CHANNELS 2 /**< channels */ #define AUDIO_DSP_SAMPLEBITS 3 /**< sample bits width */ -/** @} */ /* End of audio_dsp*/ +/** @} */ /* End of audio_dsp */ /** * @defgroup audio_mixer AUDIO_MIXER * - * @brief Supported Mixer Units controls - */ - -/** - * @addtogroup audio_mixer + * @brief Supported Mixer Units controls. The macro group from driver level, can set audio mixer + * parameters including volume, frequence db, microphone etc. + * * @{ */ #define AUDIO_MIXER_QUERY 0x0000 /**< Query mixer capabilities */ #define AUDIO_MIXER_MUTE 0x0001 /**< Mute audio device */ #define AUDIO_MIXER_VOLUME 0x0002 /**< Set mixer volume */ #define AUDIO_MIXER_BASS 0x0004 /**< Set the low-frequency section of the mixer */ -#define AUDIO_MIXER_MID 0x0008 /**< Set the mid-frequency section of the mixer*/ +#define AUDIO_MIXER_MID 0x0008 /**< Set the mid-frequency section of the mixer */ #define AUDIO_MIXER_TREBLE 0x0010 /**< Set the high-frequency section of the mixer */ #define AUDIO_MIXER_EQUALIZER 0x0020 /**< Set equalizer option */ #define AUDIO_MIXER_LINE 0x0040 /**< Set line control option */ @@ -155,7 +136,7 @@ #define AUDIO_MIXER_MIC 0x0100 /**< Set microphone option */ #define AUDIO_MIXER_VITURAL 0x0200 /**< Set virtual audio option */ #define AUDIO_MIXER_EXTEND 0x8000 /**< Extend mixer command */ -/** @} */ /* End of audio_mixer*/ +/** @} */ /* End of audio_mixer */ #define AUDIO_VOLUME_MAX (100) #define AUDIO_VOLUME_MIN (0) @@ -181,24 +162,35 @@ enum */ struct rt_audio_buf_info { - rt_uint8_t *buffer; - rt_uint16_t block_size; - rt_uint16_t block_count; - rt_uint32_t total_size; + rt_uint8_t *buffer; /**< Audio buffer information */ + rt_uint16_t block_size; /**< Audio block_size information for replay function */ + rt_uint16_t block_count; /**< Audio block_count information for replay function */ + rt_uint32_t total_size; /**< Audio total_size which is equal to block_size multiplying + * block_count information for replay function */ }; struct rt_audio_device; struct rt_audio_caps; struct rt_audio_configure; + +/** + * @brief Aduio device operators + */ struct rt_audio_ops { + /** Get audio capabilities information */ rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps); + /** Configure audio devices */ rt_err_t (*configure)(struct rt_audio_device *audio, struct rt_audio_caps *caps); + /** Initialize audio device */ rt_err_t (*init)(struct rt_audio_device *audio); + /** Turn on the audio device */ rt_err_t (*start)(struct rt_audio_device *audio, int stream); + /** Turn off the audio device */ rt_err_t (*stop)(struct rt_audio_device *audio, int stream); + /** Transmit data between application and device */ rt_ssize_t (*transmit)(struct rt_audio_device *audio, const void *writeBuf, void *readBuf, rt_size_t size); - /* get page size of codec or private buffer's info */ + /** Get page size of codec or private buffer's info */ void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info); }; @@ -211,9 +203,9 @@ struct rt_audio_ops */ struct rt_audio_configure { - rt_uint32_t samplerate; - rt_uint16_t channels; - rt_uint16_t samplebits; + rt_uint32_t samplerate; /**< Audio samplerate information */ + rt_uint16_t channels; /**< Audio channels information */ + rt_uint16_t samplebits; /**< Audio samplebits information */ }; /** @@ -221,15 +213,15 @@ struct rt_audio_configure */ struct rt_audio_caps { - int main_type; - int sub_type; + int main_type; /**< Audio main type, one value of @ref audio_type */ + int sub_type; /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */ union { - rt_uint32_t mask; - int value; - struct rt_audio_configure config; - } udata; + rt_uint32_t mask; /**< Capabilities mask */ + int value; /**< Capabilities value */ + struct rt_audio_configure config; /**< Audio samplebits information */ + } udata; /**< User data */ }; /** @@ -237,17 +229,19 @@ struct rt_audio_caps */ struct rt_audio_replay { - struct rt_mempool *mp; - struct rt_data_queue queue; - struct rt_mutex lock; - struct rt_completion cmp; - struct rt_audio_buf_info buf_info; - rt_uint8_t *write_data; - rt_uint16_t write_index; - rt_uint16_t read_index; - rt_uint32_t pos; - rt_uint8_t event; - rt_bool_t activated; + struct rt_mempool *mp; /**< Memory pool for audio replay */ + struct rt_data_queue queue; /**< Replay data queue */ + struct rt_mutex lock; /**< Replay mutex lock */ + struct rt_completion cmp; /**< Replay completion, it will be */ + struct rt_audio_buf_info buf_info; /**< Replay buffer information */ + rt_uint8_t *write_data; /**< Pointer to the data to be written into data queue */ + rt_uint16_t write_index; /**< Index of pointer write_data.It records how much data + * has been written in currently being played block */ + rt_uint16_t read_index; /**< Index of replaying data for audio device, it indicates index + * of replay in the blocks which is currently being played */ + rt_uint32_t pos; /**< Global position of audio replay */ + rt_uint8_t event; /**< Event flag */ + rt_bool_t activated; /**< Activaty flag */ }; /** @@ -264,10 +258,10 @@ struct rt_audio_record */ struct rt_audio_device { - struct rt_device parent; - struct rt_audio_ops *ops; - struct rt_audio_replay *replay; - struct rt_audio_record *record; + struct rt_device parent; /**< Audio device parents */ + struct rt_audio_ops *ops; /**< Audio device operator */ + struct rt_audio_replay *replay; /**< Pointer to audio replay structure */ + struct rt_audio_record *record; /**< Pointer to audio record structure */ }; rt_err_t rt_audio_register(struct rt_audio_device *audio, const char *name, rt_uint32_t flag, void *data); @@ -277,11 +271,9 @@ void rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt /** * @defgroup audio_codec_cmd CODEC_CMD * - * @brief Device Control Commands - */ - -/** - * @addtogroup audio_codec_cmd + * @brief Device Control Commands. The macro group from hardware level, can set codec + * parametes including volume, EQ and 3D etc. + * * @{ */ #define CODEC_CMD_RESET 0 /**< Reset audio device by codec */ @@ -292,7 +284,7 @@ void rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt #define CODEC_CMD_3D 5 /**< Set 3D effect by codec */ #define CODEC_VOLUME_MAX (63) -/** @} */ /* End of audio_codec_cmd*/ +/** @} */ /* End of audio_codec_cmd */ /** @} group_Audio */ diff --git a/documentation/device/adudio/audio.md b/documentation/5.device/audio/audio.md similarity index 100% rename from documentation/device/adudio/audio.md rename to documentation/5.device/audio/audio.md