RT-Thread
/
rt-thread
mirror of https://github.com/RT-Thread/rt-thread
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[doxygen][audio] Fix doxygen comments for audio component 

Added comments for data structure and rt_audio_ops in dev_audio.h.
Enriched comments for macro group. Moved and renamed folder audio.

Signed-off-by: 1078249029 <1078249029@qq.com>
This commit is contained in:
1078249029 2025-03-04 20:07:36 +08:00 committed by Rbb666
parent e75c49a17b
commit ed8d0bc36b
5 changed files with 69 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
components/drivers/audio/dev_audio.c
View File

@ -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 <stdio.h>
@ -23,7 +24,7 @@
#endif
/**
* @addtogroup group_AudioPipe
* @addtogroup group_Audio
*/
/** @{ */

1
components/drivers/audio/dev_audio_pipe.c
View File

@ -6,6 +6,7 @@
* Change Logs:
* Date Author Notes
* 2012-09-30 Bernard first version.
* 2025-03-04 wumingzi add doxygen comments.
*/
#include <rthw.h>

1
components/drivers/audio/dev_audio_pipe.h
View File

@ -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__

138
components/drivers/include/drivers/dev_audio.h
View File

@ -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 */

0
documentation/device/adudio/audio.md → documentation/5.device/audio/audio.md
View File