refactor(FOC): 添加Doxygen文档注释并优化SVPWM算法性能

添加了完整的Doxygen文档注释到FOC算法模块的所有函数、类和变量，提升了代码可读性和维护性。同时优化了SVPWM算法实现，将atan2f替换为符号法扇区判断，显著提升计算效率（约15周期vs atan2f 300周期），并改进了arm_sin_cos_f32替代sqrtf提高性能。 feat(FOC): 统一电气角度计算避免重复运算重构代码以统一电气角度计算，在各个控制循环中只计算一次电气角度并传递给需要的函数，避免了多次重复的fmodf运算和角度归一化操作，提升了实时控制性能。 refactor(Filter): 改进α-β观测器角度处理精度修改角度卡尔曼滤波器在归一化角度空间[0,360)内工作，避免大累积角度的浮点精度损失问题，确保静止状态下不会产生虚假速度，同时保持与下游代码的兼容性。 refactor: 为算法模块添加完整文档注释为所有算法模块(FOC、Filter、pid、thermal)添加了详细的Doxygen文档注释，包括函数说明、参数描述、返回值说明等，便于代码理解和API文档生成。
2026-05-23 22:46:32 +08:00
parent bec7c11b87
commit 4c4e47e9e3
62 changed files with 10367 additions and 126 deletions
@@ -35,25 +35,37 @@ OF SUCH DAMAGE.
 #include "gd32c10x_adc.h"

 /* discontinuous mode macro*/
+/** @brief ADC_CHANNEL_LENGTH_SUBTRACT_ONE 宏定义 */
 #define  ADC_CHANNEL_LENGTH_SUBTRACT_ONE            ((uint8_t)1U)

 /* ADC regular channel macro */
+/** @brief ADC_REGULAR_CHANNEL_RANK_SIX 宏定义 */
 #define  ADC_REGULAR_CHANNEL_RANK_SIX               ((uint8_t)6U)
+/** @brief ADC_REGULAR_CHANNEL_RANK_TWELVE 宏定义 */
 #define  ADC_REGULAR_CHANNEL_RANK_TWELVE            ((uint8_t)12U)
+/** @brief ADC_REGULAR_CHANNEL_RANK_SIXTEEN 宏定义 */
 #define  ADC_REGULAR_CHANNEL_RANK_SIXTEEN           ((uint8_t)16U)
+/** @brief ADC_REGULAR_CHANNEL_RANK_LENGTH 宏定义 */
 #define  ADC_REGULAR_CHANNEL_RANK_LENGTH            ((uint8_t)5U)

 /* ADC sampling time macro */
+/** @brief ADC_CHANNEL_SAMPLE_TEN 宏定义 */
 #define  ADC_CHANNEL_SAMPLE_TEN                     ((uint8_t)10U)
+/** @brief ADC_CHANNEL_SAMPLE_EIGHTEEN 宏定义 */
 #define  ADC_CHANNEL_SAMPLE_EIGHTEEN                ((uint8_t)18U)
+/** @brief ADC_CHANNEL_SAMPLE_LENGTH 宏定义 */
 #define  ADC_CHANNEL_SAMPLE_LENGTH                  ((uint8_t)3U)

 /* ADC inserted channel macro */
+/** @brief ADC_INSERTED_CHANNEL_RANK_LENGTH 宏定义 */
 #define  ADC_INSERTED_CHANNEL_RANK_LENGTH           ((uint8_t)5U)
+/** @brief ADC_INSERTED_CHANNEL_SHIFT_LENGTH 宏定义 */
 #define  ADC_INSERTED_CHANNEL_SHIFT_LENGTH          ((uint8_t)15U)

 /* ADC inserted channel offset macro */
+/** @brief ADC_OFFSET_LENGTH 宏定义 */
 #define  ADC_OFFSET_LENGTH                          ((uint8_t)3U)
+/** @brief ADC_OFFSET_SHIFT_LENGTH 宏定义 */
 #define  ADC_OFFSET_SHIFT_LENGTH                    ((uint8_t)4U)

 /*!
@@ -97,6 +109,11 @@ void adc_deinit(uint32_t adc_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_mode_config 函数
+ * @param[in] mode 参数
+ * @return void
+ */
 void adc_mode_config(uint32_t mode)
 {
    ADC_CTL0(ADC0) &= ~(ADC_CTL0_SYNCM);
@@ -286,6 +303,14 @@ void adc_resolution_config(uint32_t adc_periph , uint32_t resolution)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_oversample_mode_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] mode 参数
+ * @param[in] shift 参数
+ * @param[in] ratio 参数
+ * @return void
+ */
 void adc_oversample_mode_config(uint32_t adc_periph, uint32_t mode, uint16_t shift, uint8_t ratio)
 {
    if(ADC_OVERSAMPLING_ONE_CONVERT == mode){
@@ -357,6 +382,13 @@ void adc_dma_mode_disable(uint32_t adc_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_discontinuous_mode_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] adc_channel_group 参数
+ * @param[in] length 参数
+ * @return void
+ */
 void adc_discontinuous_mode_config(uint32_t adc_periph, uint8_t adc_channel_group, uint8_t length)
 {
    /* disable discontinuous mode of regular & inserted channel */
@@ -393,6 +425,13 @@ void adc_discontinuous_mode_config(uint32_t adc_periph, uint8_t adc_channel_grou
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_channel_length_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] adc_channel_group 参数
+ * @param[in] length 参数
+ * @return void
+ */
 void adc_channel_length_config(uint32_t adc_periph, uint8_t adc_channel_group, uint32_t length)
 {
    switch(adc_channel_group){
@@ -431,6 +470,14 @@ void adc_channel_length_config(uint32_t adc_periph, uint8_t adc_channel_group, u
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_regular_channel_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] rank 参数
+ * @param[in] adc_channel 参数
+ * @param[in] sample_time 参数
+ * @return void
+ */
 void adc_regular_channel_config(uint32_t adc_periph , uint8_t rank , uint8_t adc_channel , uint32_t sample_time)
 {
    uint32_t rsq,sampt;
@@ -499,6 +546,14 @@ void adc_regular_channel_config(uint32_t adc_periph , uint8_t rank , uint8_t adc
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_inserted_channel_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] rank 参数
+ * @param[in] adc_channel 参数
+ * @param[in] sample_time 参数
+ * @return void
+ */
 void adc_inserted_channel_config(uint32_t adc_periph , uint8_t rank , uint8_t adc_channel , uint32_t sample_time)
 {
    uint8_t inserted_length;
@@ -544,6 +599,13 @@ void adc_inserted_channel_config(uint32_t adc_periph , uint8_t rank , uint8_t ad
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_inserted_channel_offset_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] inserted_channel 参数
+ * @param[in] offset 参数
+ * @return void
+ */
 void adc_inserted_channel_offset_config(uint32_t adc_periph , uint8_t inserted_channel , uint16_t offset)
 {
    uint8_t inserted_length;
@@ -592,6 +654,13 @@ void adc_inserted_channel_offset_config(uint32_t adc_periph , uint8_t inserted_c
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_external_trigger_source_config 函数
+ * @param[in] adc_periph 参数
+ * @param[in] adc_channel_group 参数
+ * @param[in] external_trigger_source 参数
+ * @return void
+ */
 void adc_external_trigger_source_config(uint32_t adc_periph, uint8_t adc_channel_group, uint32_t external_trigger_source)
 {   
    switch(adc_channel_group){
@@ -817,6 +886,12 @@ void adc_watchdog_threshold_config(uint32_t adc_periph , uint16_t low_threshold
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief adc_flag_get 函数
+ * @param[in] adc_periph 参数
+ * @param[in] adc_flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus adc_flag_get(uint32_t adc_periph , uint32_t adc_flag)
 {
    FlagStatus reval = RESET;
@@ -839,6 +914,12 @@ FlagStatus adc_flag_get(uint32_t adc_periph , uint32_t adc_flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief adc_flag_clear 函数
+ * @param[in] adc_periph 参数
+ * @param[in] adc_flag 参数
+ * @return void
+ */
 void adc_flag_clear(uint32_t adc_periph , uint32_t adc_flag)
 {
    ADC_STAT(adc_periph) &= ~((uint32_t)adc_flag);
@@ -35,6 +35,7 @@ OF SUCH DAMAGE.
 #include "gd32c10x_bkp.h"

 /* BKP register bits offset */
+/** @brief BKP_TAMPER_BITS_OFFSET 宏定义 */
 #define BKP_TAMPER_BITS_OFFSET          ((uint32_t)8U)

 /*!
@@ -35,6 +35,7 @@ OF SUCH DAMAGE.
 #include "gd32c10x_can.h"
 #include <stdlib.h>

+/** @brief CAN_ERROR_HANDLE 宏定义 */
 #define CAN_ERROR_HANDLE(s)         do{}while(1)

 /* This table can be used to calculate data length in FD mode */
@@ -71,6 +72,12 @@ void can_deinit(uint32_t can_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_struct_para_init 函数
+ * @param[in] type 参数
+ * @param[in] p_struct 参数
+ * @return void
+ */
 void can_struct_para_init(can_struct_type_enum type, void *p_struct)
 {
    uint8_t i;
@@ -183,6 +190,12 @@ void can_struct_para_init(can_struct_type_enum type, void *p_struct)
    \param[out] none
    \retval     ErrStatus: SUCCESS or ERROR
 */
+/**
+ * @brief can_init 函数
+ * @param[in] can_periph 参数
+ * @param[in] can_parameter_init 参数
+ * @return ErrStatus 返回值
+ */
 ErrStatus can_init(uint32_t can_periph, can_parameter_struct *can_parameter_init)
 {
    uint32_t timeout = CAN_TIMEOUT;
@@ -296,6 +309,12 @@ ErrStatus can_init(uint32_t can_periph, can_parameter_struct *can_parameter_init
    \param[out] none
    \retval     ErrStatus: SUCCESS or ERROR
 */
+/**
+ * @brief can_fd_init 函数
+ * @param[in] can_periph 参数
+ * @param[in] can_fdframe_init 参数
+ * @return ErrStatus 返回值
+ */
 ErrStatus can_fd_init(uint32_t can_periph, can_fdframe_struct *can_fdframe_init)
 {
    uint32_t timeout = CAN_TIMEOUT;
@@ -388,6 +407,11 @@ ErrStatus can_fd_init(uint32_t can_periph, can_fdframe_struct *can_fdframe_init)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_filter_init 函数
+ * @param[in] can_filter_parameter_init 参数
+ * @return void
+ */
 void can_filter_init(can_filter_parameter_struct *can_filter_parameter_init)
 {
    uint32_t val = 0U;
@@ -470,6 +494,14 @@ void can_filter_init(can_filter_parameter_struct *can_filter_parameter_init)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_filter_mask_mode_init 函数
+ * @param[in] id 参数
+ * @param[in] mask 参数
+ * @param[in] format_fifo 参数
+ * @param[in] filter_number 参数
+ * @return void
+ */
 void can_filter_mask_mode_init(uint32_t id, uint32_t mask, can_format_fifo_enum format_fifo, uint16_t filter_number)
 {
    can_filter_parameter_struct can_filter;
@@ -556,6 +588,12 @@ void can_filter_mask_mode_init(uint32_t id, uint32_t mask, can_format_fifo_enum
    \param[out] none
    \retval     ErrStatus: SUCCESS or ERROR
 */
+/**
+ * @brief can_monitor_mode_set 函数
+ * @param[in] can_periph 参数
+ * @param[in] mode 参数
+ * @return ErrStatus 返回值
+ */
 ErrStatus can_monitor_mode_set(uint32_t can_periph, uint8_t mode)
 {
    ErrStatus reval = SUCCESS;
@@ -728,6 +766,12 @@ void can_time_trigger_mode_disable(uint32_t can_periph)
    \param[out] none
    \retval     mailbox_number
 */
+/**
+ * @brief can_message_transmit 函数
+ * @param[in] can_periph 参数
+ * @param[in] transmit_message 参数
+ * @return uint8_t 返回值
+ */
 uint8_t can_message_transmit(uint32_t can_periph, can_trasnmit_message_struct *transmit_message)
 {
    uint8_t mailbox_number = CAN_MAILBOX0;
@@ -975,6 +1019,13 @@ ErrStatus can_transmission_stop(uint32_t can_periph, uint8_t mailbox_number)
      \arg        rx_fi: 0 - 27
    \retval     none
 */
+/**
+ * @brief can_message_receive 函数
+ * @param[in] can_periph 参数
+ * @param[in] fifo_number 参数
+ * @param[in] receive_message 参数
+ * @return void
+ */
 void can_message_receive(uint32_t can_periph, uint8_t fifo_number, can_receive_message_struct *receive_message)
 {
    uint32_t canfd_en = 0U;
@@ -1214,6 +1265,11 @@ ErrStatus can_wakeup(uint32_t can_periph)
      \arg        CAN_ERROR_CRC: CRC error
      \arg        CAN_ERROR_SOFTWARECFG: software configure
 */
+/**
+ * @brief can_error_get 函数
+ * @param[in] can_periph 参数
+ * @return can_error_enum 返回值
+ */
 can_error_enum can_error_get(uint32_t can_periph)
 {
    can_error_enum error;
@@ -1278,6 +1334,12 @@ uint8_t can_transmit_error_number_get(uint32_t can_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_interrupt_enable 函数
+ * @param[in] can_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void can_interrupt_enable(uint32_t can_periph, uint32_t interrupt)
 {
    CAN_INTEN(can_periph) |= interrupt;
@@ -1306,6 +1368,12 @@ void can_interrupt_enable(uint32_t can_periph, uint32_t interrupt)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_interrupt_disable 函数
+ * @param[in] can_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void can_interrupt_disable(uint32_t can_periph, uint32_t interrupt)
 {
    CAN_INTEN(can_periph) &= ~interrupt;
@@ -1354,6 +1422,12 @@ void can_interrupt_disable(uint32_t can_periph, uint32_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief can_flag_get 函数
+ * @param[in] can_periph 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus can_flag_get(uint32_t can_periph, can_flag_enum flag)
 {
    FlagStatus retval;
@@ -1394,6 +1468,12 @@ FlagStatus can_flag_get(uint32_t can_periph, can_flag_enum flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_flag_clear 函数
+ * @param[in] can_periph 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void can_flag_clear(uint32_t can_periph, can_flag_enum flag)
 {
    CAN_REG_VAL(can_periph, flag) |= BIT(CAN_BIT_POS(flag));
@@ -1424,6 +1504,12 @@ void can_flag_clear(uint32_t can_periph, can_flag_enum flag)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief can_interrupt_flag_get 函数
+ * @param[in] can_periph 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus can_interrupt_flag_get(uint32_t can_periph, can_interrupt_flag_enum flag)
 {
    FlagStatus retval;
@@ -1469,6 +1555,12 @@ FlagStatus can_interrupt_flag_get(uint32_t can_periph, can_interrupt_flag_enum f
    \param[out] none
    \retval     none
 */
+/**
+ * @brief can_interrupt_flag_clear 函数
+ * @param[in] can_periph 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void can_interrupt_flag_clear(uint32_t can_periph, can_interrupt_flag_enum flag)
 {
    CAN_REG_VALS(can_periph, flag) |= BIT(CAN_BIT_POS0(flag));
@@ -34,7 +34,9 @@ OF SUCH DAMAGE.

 #include "gd32c10x_crc.h"

+/** @brief CRC_DATA_RESET_VALUE 宏定义 */
 #define CRC_DATA_RESET_VALUE      ((uint32_t)0xFFFFFFFFU)
+/** @brief CRC_FDATA_RESET_VALUE 宏定义 */
 #define CRC_FDATA_RESET_VALUE     ((uint32_t)0x00000000U)

 /*!
@@ -34,12 +34,17 @@ OF SUCH DAMAGE.

 #include "gd32c10x_ctc.h"

+/** @brief CTC_FLAG_MASK 宏定义 */
 #define CTC_FLAG_MASK            ((uint32_t)0x00000700U)

 /* CTC register bit offset */
+/** @brief CTC_TRIMVALUE_OFFSET 宏定义 */
 #define CTC_TRIMVALUE_OFFSET     ((uint32_t)8U)
+/** @brief CTC_TRIM_VALUE_OFFSET 宏定义 */
 #define CTC_TRIM_VALUE_OFFSET    ((uint32_t)8U)
+/** @brief CTC_REFCAP_OFFSET 宏定义 */
 #define CTC_REFCAP_OFFSET        ((uint32_t)16U)
+/** @brief CTC_LIMIT_VALUE_OFFSET 宏定义 */
 #define CTC_LIMIT_VALUE_OFFSET   ((uint32_t)16U)

 /*!
@@ -163,6 +168,11 @@ void ctc_refsource_signal_select(uint32_t refs)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief ctc_refsource_prescaler_config 函数
+ * @param[in] prescaler 参数
+ * @return void
+ */
 void ctc_refsource_prescaler_config(uint32_t prescaler)
 {
    CTC_CTL1 &= (uint32_t)(~CTC_CTL1_REFPSC);
@@ -300,6 +310,11 @@ void ctc_interrupt_disable(uint32_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief ctc_interrupt_flag_get 函数
+ * @param[in] interrupt 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus ctc_interrupt_flag_get(uint32_t interrupt)
 {
    uint32_t intflag = 0U, intenable = 0U;
@@ -337,6 +352,11 @@ FlagStatus ctc_interrupt_flag_get(uint32_t interrupt)
    \param[out] none
    \retval     none
 */ 
+/**
+ * @brief ctc_interrupt_flag_clear 函数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void ctc_interrupt_flag_clear(uint32_t interrupt)
 {
    if(RESET != (interrupt & CTC_FLAG_MASK)){
@@ -360,6 +380,11 @@ void ctc_interrupt_flag_clear(uint32_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief ctc_flag_get 函数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus ctc_flag_get(uint32_t flag)
 {
    FlagStatus ret;
@@ -386,6 +411,11 @@ FlagStatus ctc_flag_get(uint32_t flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief ctc_flag_clear 函数
+ * @param[in] flag 参数
+ * @return void
+ */
 void ctc_flag_clear(uint32_t flag)
 {
    if(RESET != (flag & CTC_FLAG_MASK)){
@@ -35,8 +35,11 @@ OF SUCH DAMAGE.
 #include "gd32c10x_dac.h"

 /* DAC register bit offset */
+/** @brief OUT1_REG_OFFSET 宏定义 */
 #define OUT1_REG_OFFSET           ((uint32_t)0x00000010U)
+/** @brief DH_12BIT_OFFSET 宏定义 */
 #define DH_12BIT_OFFSET           ((uint32_t)0x00000010U)
+/** @brief DH_8BIT_OFFSET 宏定义 */
 #define DH_8BIT_OFFSET            ((uint32_t)0x00000008U)

 /*!
@@ -203,6 +206,14 @@ uint16_t dac_output_value_get(uint32_t dac_periph, uint8_t dac_out)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dac_data_set 函数
+ * @param[in] dac_periph 参数
+ * @param[in] dac_out 参数
+ * @param[in] dac_align 参数
+ * @param[in] data 参数
+ * @return void
+ */
 void dac_data_set(uint32_t dac_periph, uint8_t dac_out, uint32_t dac_align, uint16_t data)
 {
    /* DAC_OUT0 data alignment */
@@ -299,6 +310,13 @@ void dac_trigger_disable(uint32_t dac_periph, uint8_t dac_out)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dac_trigger_source_config 函数
+ * @param[in] dac_periph 参数
+ * @param[in] dac_out 参数
+ * @param[in] triggersource 参数
+ * @return void
+ */
 void dac_trigger_source_config(uint32_t dac_periph, uint8_t dac_out, uint32_t triggersource)
 {
    if(DAC_OUT0 == dac_out){
@@ -380,6 +398,13 @@ void dac_wave_mode_config(uint32_t dac_periph, uint8_t dac_out, uint32_t wave_mo
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dac_lfsr_noise_config 函数
+ * @param[in] dac_periph 参数
+ * @param[in] dac_out 参数
+ * @param[in] unmask_bits 参数
+ * @return void
+ */
 void dac_lfsr_noise_config(uint32_t dac_periph, uint8_t dac_out, uint32_t unmask_bits)
 {
    if(DAC_OUT0 == dac_out){
@@ -416,6 +441,13 @@ void dac_lfsr_noise_config(uint32_t dac_periph, uint8_t dac_out, uint32_t unmask
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dac_triangle_noise_config 函数
+ * @param[in] dac_periph 参数
+ * @param[in] dac_out 参数
+ * @param[in] amplitude 参数
+ * @return void
+ */
 void dac_triangle_noise_config(uint32_t dac_periph, uint8_t dac_out, uint32_t amplitude)
 {
    if(DAC_OUT0 == dac_out){
@@ -514,6 +546,14 @@ void dac_concurrent_output_buffer_disable(uint32_t dac_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dac_concurrent_data_set 函数
+ * @param[in] dac_periph 参数
+ * @param[in] dac_align 参数
+ * @param[in] data0 参数
+ * @param[in] data1 参数
+ * @return void
+ */
 void dac_concurrent_data_set(uint32_t dac_periph, uint32_t dac_align, uint16_t data0, uint16_t data1)
 {
    uint32_t data = 0U;
@@ -35,9 +35,16 @@ OF SUCH DAMAGE.
 #include "gd32c10x_dma.h"
 #include <stdio.h>

+/** @brief DMA_WRONG_HANDLE 宏定义 */
 #define DMA_WRONG_HANDLE        while(1){}

 /* check whether peripheral matches channels or not */
+/**
+ * @brief dma_periph_and_channel_check 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @return ErrStatus 返回值
+ */
 static ErrStatus dma_periph_and_channel_check(uint32_t dma_periph, dma_channel_enum channelx);

 /*!
@@ -110,6 +117,13 @@ void dma_struct_para_init(dma_parameter_struct* init_struct)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_init 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] init_struct 参数
+ * @return void
+ */
 void dma_init(uint32_t dma_periph, dma_channel_enum channelx, dma_parameter_struct* init_struct)
 {
    uint32_t ctl;
@@ -365,6 +379,13 @@ uint32_t dma_transfer_number_get(uint32_t dma_periph, dma_channel_enum channelx)
    \param[out] none
    \retval     none 
 */
+/**
+ * @brief dma_priority_config 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] priority 参数
+ * @return void
+ */
 void dma_priority_config(uint32_t dma_periph, dma_channel_enum channelx, uint32_t priority)
 {
    uint32_t ctl;
@@ -396,6 +417,13 @@ void dma_priority_config(uint32_t dma_periph, dma_channel_enum channelx, uint32_
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_memory_width_config 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] mwidth 参数
+ * @return void
+ */
 void dma_memory_width_config(uint32_t dma_periph, dma_channel_enum channelx, uint32_t mwidth)
 {
    uint32_t ctl;
@@ -427,6 +455,13 @@ void dma_memory_width_config(uint32_t dma_periph, dma_channel_enum channelx, uin
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_periph_width_config 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] pwidth 参数
+ * @return void
+ */
 void dma_periph_width_config(uint32_t dma_periph, dma_channel_enum channelx, uint32_t pwidth)
 {
    uint32_t ctl;
@@ -533,6 +568,13 @@ void dma_periph_increase_disable(uint32_t dma_periph, dma_channel_enum channelx)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_transfer_direction_config 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] direction 参数
+ * @return void
+ */
 void dma_transfer_direction_config(uint32_t dma_periph, dma_channel_enum channelx, uint32_t direction)
 {
    if(ERROR == dma_periph_and_channel_check(dma_periph, channelx)){
@@ -561,6 +603,13 @@ void dma_transfer_direction_config(uint32_t dma_periph, dma_channel_enum channel
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief dma_flag_get 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus dma_flag_get(uint32_t dma_periph, dma_channel_enum channelx, uint32_t flag)
 {
    FlagStatus reval;
@@ -591,6 +640,13 @@ FlagStatus dma_flag_get(uint32_t dma_periph, dma_channel_enum channelx, uint32_t
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_flag_clear 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void dma_flag_clear(uint32_t dma_periph, dma_channel_enum channelx, uint32_t flag)
 {
    DMA_INTC(dma_periph) |= DMA_FLAG_ADD(flag, channelx);
@@ -611,6 +667,13 @@ void dma_flag_clear(uint32_t dma_periph, dma_channel_enum channelx, uint32_t fla
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief dma_interrupt_flag_get 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus dma_interrupt_flag_get(uint32_t dma_periph, dma_channel_enum channelx, uint32_t flag)
 {
    uint32_t interrupt_enable = 0U, interrupt_flag = 0U;
@@ -661,6 +724,13 @@ FlagStatus dma_interrupt_flag_get(uint32_t dma_periph, dma_channel_enum channelx
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_interrupt_flag_clear 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void dma_interrupt_flag_clear(uint32_t dma_periph, dma_channel_enum channelx, uint32_t flag)
 {
    DMA_INTC(dma_periph) |= DMA_FLAG_ADD(flag, channelx);
@@ -681,6 +751,13 @@ void dma_interrupt_flag_clear(uint32_t dma_periph, dma_channel_enum channelx, ui
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_interrupt_enable 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] source 参数
+ * @return void
+ */
 void dma_interrupt_enable(uint32_t dma_periph, dma_channel_enum channelx, uint32_t source)
 {
    if(ERROR == dma_periph_and_channel_check(dma_periph, channelx)){
@@ -705,6 +782,13 @@ void dma_interrupt_enable(uint32_t dma_periph, dma_channel_enum channelx, uint32
    \param[out] none
    \retval     none
 */
+/**
+ * @brief dma_interrupt_disable 函数
+ * @param[in] dma_periph 参数
+ * @param[in] channelx 参数
+ * @param[in] source 参数
+ * @return void
+ */
 void dma_interrupt_disable(uint32_t dma_periph, dma_channel_enum channelx, uint32_t source)
 {
    if(ERROR == dma_periph_and_channel_check(dma_periph, channelx)){
@@ -35,25 +35,41 @@ OF SUCH DAMAGE.
 #include "gd32c10x_exmc.h"

 /* EXMC bank0 register reset value */
+/** @brief BANK0_SNCTL_RESET 宏定义 */
 #define BANK0_SNCTL_RESET                 ((uint32_t)0x000030DBU)
+/** @brief BANK0_SNTCFG_RESET 宏定义 */
 #define BANK0_SNTCFG_RESET                ((uint32_t)0x0FFFFFFFU)
+/** @brief BANK0_SNWTCFG_RESET 宏定义 */
 #define BANK0_SNWTCFG_RESET               ((uint32_t)0x0FFFFFFFU)

 /* EXMC register bit offset */
+/** @brief SNCTL_NRMUX_OFFSET 宏定义 */
 #define SNCTL_NRMUX_OFFSET                ((uint32_t)1U)
+/** @brief SNCTL_SBRSTEN_OFFSET 宏定义 */
 #define SNCTL_SBRSTEN_OFFSET              ((uint32_t)8U)
+/** @brief SNCTL_WRAPEN_OFFSET 宏定义 */
 #define SNCTL_WRAPEN_OFFSET               ((uint32_t)10U)
+/** @brief SNCTL_WREN_OFFSET 宏定义 */
 #define SNCTL_WREN_OFFSET                 ((uint32_t)12U)
+/** @brief SNCTL_NRWTEN_OFFSET 宏定义 */
 #define SNCTL_NRWTEN_OFFSET               ((uint32_t)13U)
+/** @brief SNCTL_EXMODEN_OFFSET 宏定义 */
 #define SNCTL_EXMODEN_OFFSET              ((uint32_t)14U)
+/** @brief SNCTL_ASYNCWAIT_OFFSET 宏定义 */
 #define SNCTL_ASYNCWAIT_OFFSET            ((uint32_t)15U)

+/** @brief SNTCFG_AHLD_OFFSET 宏定义 */
 #define SNTCFG_AHLD_OFFSET                ((uint32_t)4U)
+/** @brief SNTCFG_DSET_OFFSET 宏定义 */
 #define SNTCFG_DSET_OFFSET                ((uint32_t)8U)
+/** @brief SNTCFG_BUSLAT_OFFSET 宏定义 */
 #define SNTCFG_BUSLAT_OFFSET              ((uint32_t)16U)

+/** @brief SNWTCFG_WAHLD_OFFSET 宏定义 */
 #define SNWTCFG_WAHLD_OFFSET              ((uint32_t)4U)
+/** @brief SNWTCFG_WDSET_OFFSET 宏定义 */
 #define SNWTCFG_WDSET_OFFSET              ((uint32_t)8U)
+/** @brief SNWTCFG_WBUSLAT_OFFSET 宏定义 */
 #define SNWTCFG_WBUSLAT_OFFSET            ((uint32_t)16U)

 /*!
@@ -130,6 +146,11 @@ void exmc_norsram_struct_para_init(exmc_norsram_parameter_struct* exmc_norsram_i
    \param[out] none
    \retval     none
 */
+/**
+ * @brief exmc_norsram_init 函数
+ * @param[in] exmc_norsram_init_struct 参数
+ * @return void
+ */
 void exmc_norsram_init(exmc_norsram_parameter_struct* exmc_norsram_init_struct)
 {
    uint32_t snctl = 0x00000000U, sntcfg = 0x00000000U, snwtcfg = 0x00000000U;
@@ -34,6 +34,7 @@ OF SUCH DAMAGE.

 #include "gd32c10x_exti.h"

+/** @brief EXTI_REG_RESET_VALUE 宏定义 */
 #define EXTI_REG_RESET_VALUE            ((uint32_t)0x00000000U)

 /*!
@@ -69,6 +70,13 @@ void exti_deinit(void)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief exti_init 函数
+ * @param[in] linex 参数
+ * @param[in] mode 参数
+ * @param[in] trig_type 参数
+ * @return void
+ */
 void exti_init(exti_line_enum linex, exti_mode_enum mode, exti_trig_type_enum trig_type)
 {
    /* reset the EXTI line x */
@@ -35,25 +35,45 @@ OF SUCH DAMAGE.
 #include "gd32c10x_fmc.h"

 /* FMC mask */
+/** @brief LOW_8BITS_MASK 宏定义 */
 #define LOW_8BITS_MASK             ((uint32_t)0x000000FFU)
+/** @brief HIGH_8BITS_MASK 宏定义 */
 #define HIGH_8BITS_MASK            ((uint32_t)0x0000FF00U)
+/** @brief LOW_8BITS_MASK1 宏定义 */
 #define LOW_8BITS_MASK1            ((uint32_t)0x00FF0000U)
+/** @brief HIGH_8BITS_MASK1 宏定义 */
 #define HIGH_8BITS_MASK1           ((uint32_t)0xFF000000U)
+/** @brief LOW_16BITS_MASK 宏定义 */
 #define LOW_16BITS_MASK            ((uint32_t)0x0000FFFFU)
+/** @brief HIGH_16BITS_MASK 宏定义 */
 #define HIGH_16BITS_MASK           ((uint32_t)0xFFFF0000U)

 /* USER of option bytes mask */
+/** @brief OB_USER_MASK 宏定义 */
 #define OB_USER_MASK               ((uint8_t)0xF8U)

 /* OB_WP mask */
+/** @brief OB_WP0_MASK 宏定义 */
 #define OB_WP0_MASK                ((uint32_t)0x000000FFU)
+/** @brief OB_WP1_MASK 宏定义 */
 #define OB_WP1_MASK                ((uint32_t)0x0000FF00U)
+/** @brief OB_WP2_MASK 宏定义 */
 #define OB_WP2_MASK                ((uint32_t)0x00FF0000U)
+/** @brief OB_WP3_MASK 宏定义 */
 #define OB_WP3_MASK                ((uint32_t)0xFF000000U)

 /* return the FMC state */
+/**
+ * @brief fmc_state_get 函数
+ * @return fmc_state_enum 返回值
+ */
 static fmc_state_enum fmc_state_get(void);
 /* check FMC ready or not */
+/**
+ * @brief fmc_ready_wait 函数
+ * @param[in] timeout 参数
+ * @return fmc_state_enum 返回值
+ */
 static fmc_state_enum fmc_ready_wait(uint32_t timeout);

 /* FMC main memory programming functions */
@@ -446,6 +466,11 @@ fmc_state_enum ob_erase(void)
      \arg        FMC_PGAERR: program alignment error
      \arg        FMC_TOERR: timeout error
 */
+/**
+ * @brief ob_write_protection_enable 函数
+ * @param[in] ob_wp 参数
+ * @return fmc_state_enum 返回值
+ */
 fmc_state_enum ob_write_protection_enable(uint32_t ob_wp)
 {
    uint32_t i;
@@ -505,6 +530,11 @@ fmc_state_enum ob_write_protection_enable(uint32_t ob_wp)
      \arg        FMC_PGAERR: program alignment error
      \arg        FMC_TOERR: timeout error
 */
+/**
+ * @brief ob_security_protection_config 函数
+ * @param[in] ob_spc 参数
+ * @return fmc_state_enum 返回值
+ */
 fmc_state_enum ob_security_protection_config(uint8_t ob_spc)
 {
    uint32_t i;
@@ -571,6 +601,13 @@ fmc_state_enum ob_security_protection_config(uint8_t ob_spc)
      \arg        FMC_PGAERR: program alignment error
      \arg        FMC_TOERR: timeout error
 */
+/**
+ * @brief ob_user_write 函数
+ * @param[in] ob_fwdgt 参数
+ * @param[in] ob_deepsleep 参数
+ * @param[in] ob_stdby 参数
+ * @return fmc_state_enum 返回值
+ */
 fmc_state_enum ob_user_write(uint8_t ob_fwdgt, uint8_t ob_deepsleep, uint8_t ob_stdby)
 {
    uint32_t i;
@@ -700,6 +737,11 @@ uint16_t fmc_ecc_address_get(void)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief fmc_ecc_flag_get 函数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus fmc_ecc_flag_get(uint32_t flag)
 {
    FlagStatus status = RESET;
@@ -725,6 +767,11 @@ FlagStatus fmc_ecc_flag_get(uint32_t flag)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief fmc_ecc_flag_clear 函数
+ * @param[in] flag 参数
+ * @return void
+ */
 void fmc_ecc_flag_clear(uint32_t flag)
 {
    FMC_ECCCS |= flag;
@@ -81,6 +81,11 @@ void fwdgt_enable(void)
    \param[out] none
    \retval     ErrStatus: ERROR or SUCCESS
 */
+/**
+ * @brief fwdgt_prescaler_value_config 函数
+ * @param[in] prescaler_value 参数
+ * @return ErrStatus 返回值
+ */
 ErrStatus fwdgt_prescaler_value_config(uint16_t prescaler_value)
 {
    uint32_t timeout = FWDGT_PSC_TIMEOUT;
@@ -161,6 +166,12 @@ void fwdgt_counter_reload(void)
    \param[out] none
    \retval     ErrStatus: ERROR or SUCCESS
 */
+/**
+ * @brief fwdgt_config 函数
+ * @param[in] reload_value 参数
+ * @param[in] prescaler_value 参数
+ * @return ErrStatus 返回值
+ */
 ErrStatus fwdgt_config(uint16_t reload_value, uint8_t prescaler_value)
 {
    uint32_t timeout = FWDGT_PSC_TIMEOUT;
@@ -34,6 +34,7 @@ OF SUCH DAMAGE.

 #include "gd32c10x_gpio.h"

+/** @brief AFIO_EXTI_SOURCE_MASK 宏定义 */
 #define AFIO_EXTI_SOURCE_MASK              ((uint8_t)0x03U)         /*!< AFIO exti source selection mask*/  
 #define AFIO_EXTI_SOURCE_FIELDS            ((uint8_t)0x04U)         /*!< select AFIO exti source registers */
 #define LSB_16BIT_MASK                     ((uint16_t)0xFFFFU)      /*!< LSB 16-bit mask */
@@ -120,6 +121,14 @@ void gpio_afio_deinit(void)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief gpio_init 函数
+ * @param[in] gpio_periph 参数
+ * @param[in] mode 参数
+ * @param[in] speed 参数
+ * @param[in] pin 参数
+ * @return void
+ */
 void gpio_init(uint32_t gpio_periph, uint32_t mode, uint32_t speed, uint32_t pin)
 {
    uint16_t i;
@@ -352,6 +361,12 @@ uint16_t gpio_output_port_get(uint32_t gpio_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief gpio_pin_remap_config 函数
+ * @param[in] remap 参数
+ * @param[in] newvalue 参数
+ * @return void
+ */
 void gpio_pin_remap_config(uint32_t remap, ControlStatus newvalue)
 {
    uint32_t remap1 = 0U, remap2 = 0U, temp_reg = 0U, temp_mask = 0U;
@@ -409,6 +424,12 @@ void gpio_pin_remap_config(uint32_t remap, ControlStatus newvalue)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief gpio_exti_source_select 函数
+ * @param[in] output_port 参数
+ * @param[in] output_pin 参数
+ * @return void
+ */
 void gpio_exti_source_select(uint8_t output_port, uint8_t output_pin)
 {
    uint32_t source = 0U;
@@ -449,6 +470,12 @@ void gpio_exti_source_select(uint8_t output_port, uint8_t output_pin)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief gpio_event_output_config 函数
+ * @param[in] output_port 参数
+ * @param[in] output_pin 参数
+ * @return void
+ */
 void gpio_event_output_config(uint8_t output_port, uint8_t output_pin)
 {
    uint32_t reg = 0U;
@@ -35,6 +35,7 @@ OF SUCH DAMAGE.
 #include "gd32c10x_i2c.h"

 /* I2C register bit mask */
+/** @brief I2CCLK_MAX 宏定义 */
 #define I2CCLK_MAX                    ((uint32_t)0x0000003FU)             /*!< i2cclk maximum value */
 #define I2CCLK_MIN                    ((uint32_t)0x00000002U)             /*!< i2cclk minimum value */
 #define I2C_FLAG_MASK                 ((uint32_t)0x0000FFFFU)             /*!< i2c flag mask */
@@ -42,6 +43,7 @@ OF SUCH DAMAGE.
 #define I2C_ADDRESS2_MASK             ((uint32_t)0x000000FEU)             /*!< the second i2c address mask */

 /* I2C register bit offset */
+/** @brief STAT1_PECV_OFFSET 宏定义 */
 #define STAT1_PECV_OFFSET             ((uint32_t)0x00000008U)             /*!< bit offset of PECV in I2C_STAT1 */

 /*!
@@ -167,6 +169,14 @@ void i2c_clock_config(uint32_t i2c_periph, uint32_t clkspeed, uint32_t dutycyc)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2c_mode_addr_config 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] mode 参数
+ * @param[in] addformat 参数
+ * @param[in] addr 参数
+ * @return void
+ */
 void i2c_mode_addr_config(uint32_t i2c_periph, uint32_t mode, uint32_t addformat, uint32_t addr)
 {
    /* SMBus/I2C mode selected */
@@ -633,6 +643,12 @@ void i2c_sam_timeout_disable(uint32_t i2c_periph)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief i2c_flag_get 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus i2c_flag_get(uint32_t i2c_periph, i2c_flag_enum flag)
 {
    FlagStatus status = RESET;
@@ -664,6 +680,12 @@ FlagStatus i2c_flag_get(uint32_t i2c_periph, i2c_flag_enum flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2c_flag_clear 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void i2c_flag_clear(uint32_t i2c_periph, i2c_flag_enum flag)
 {
    if(I2C_FLAG_ADDSEND == flag){
@@ -690,6 +712,12 @@ void i2c_flag_clear(uint32_t i2c_periph, i2c_flag_enum flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2c_interrupt_enable 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void i2c_interrupt_enable(uint32_t i2c_periph, i2c_interrupt_enum interrupt)
 {
    I2C_REG_VAL(i2c_periph, interrupt) |= BIT(I2C_BIT_POS(interrupt));
@@ -710,6 +738,12 @@ void i2c_interrupt_enable(uint32_t i2c_periph, i2c_interrupt_enum interrupt)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2c_interrupt_disable 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void i2c_interrupt_disable(uint32_t i2c_periph, i2c_interrupt_enum interrupt)
 {
    I2C_REG_VAL(i2c_periph, interrupt) &= ~BIT(I2C_BIT_POS(interrupt));
@@ -741,6 +775,12 @@ void i2c_interrupt_disable(uint32_t i2c_periph, i2c_interrupt_enum interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief i2c_interrupt_flag_get 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] int_flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus i2c_interrupt_flag_get(uint32_t i2c_periph, i2c_interrupt_flag_enum int_flag)
 {
    uint32_t intenable = 0U, flagstatus = 0U, bufie;
@@ -789,6 +829,12 @@ FlagStatus i2c_interrupt_flag_get(uint32_t i2c_periph, i2c_interrupt_flag_enum i
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2c_interrupt_flag_clear 函数
+ * @param[in] i2c_periph 参数
+ * @param[in] int_flag 参数
+ * @return void
+ */
 void i2c_interrupt_flag_clear(uint32_t i2c_periph, i2c_interrupt_flag_enum int_flag)
 {
    if(I2C_INT_FLAG_ADDSEND == int_flag){
@@ -62,6 +62,11 @@ void pmu_deinit(void)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief pmu_lvd_select 函数
+ * @param[in] lvdt_n 参数
+ * @return void
+ */
 void pmu_lvd_select(uint32_t lvdt_n)
 {
    /* disable LVD */
@@ -139,6 +144,12 @@ void pmu_to_sleepmode(uint8_t sleepmodecmd)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief pmu_to_deepsleepmode 函数
+ * @param[in] ldo 参数
+ * @param[in] deepsleepmodecmd 参数
+ * @return void
+ */
 void pmu_to_deepsleepmode(uint32_t ldo,uint8_t deepsleepmodecmd)
 {
    static uint32_t reg_snap[4];
@@ -35,24 +35,34 @@ OF SUCH DAMAGE.
 #include "gd32c10x_rcu.h"

 /* define clock source */
+/** @brief SEL_IRC8M 宏定义 */
 #define SEL_IRC8M                   ((uint16_t)0U)  /* IRC8M is selected as CK_SYS */
+/** @brief SEL_HXTAL 宏定义 */
 #define SEL_HXTAL                   ((uint16_t)1U)  /* HXTAL is selected as CK_SYS */
+/** @brief SEL_PLL 宏定义 */
 #define SEL_PLL                     ((uint16_t)2U)  /* PLL is selected as CK_SYS */

 /* define startup timeout count */
+/** @brief OSC_STARTUP_TIMEOUT 宏定义 */
 #define OSC_STARTUP_TIMEOUT         ((uint32_t)0x000FFFFFU)
+/** @brief LXTAL_STARTUP_TIMEOUT 宏定义 */
 #define LXTAL_STARTUP_TIMEOUT       ((uint32_t)0x03FFFFFFU)

 /* ADC clock prescaler offset */
+/** @brief RCU_ADC_PSC_OFFSET 宏定义 */
 #define RCU_ADC_PSC_OFFSET          ((uint32_t)14U)

 /* RCU IRC8M adjust value mask and offset*/
+/** @brief RCU_IRC8M_ADJUST_MASK 宏定义 */
 #define RCU_IRC8M_ADJUST_MASK       ((uint8_t)0x1FU)
+/** @brief RCU_IRC8M_ADJUST_OFFSET 宏定义 */
 #define RCU_IRC8M_ADJUST_OFFSET     ((uint32_t)3U)

 /* RCU PLL1 clock multiplication factor offset */
+/** @brief RCU_CFG1_PLL1MF_OFFSET 宏定义 */
 #define RCU_CFG1_PLL1MF_OFFSET      ((uint32_t)8U)
 /* RCU PREDV1 division factor offset*/
+/** @brief RCU_CFG1_PREDV1_OFFSET 宏定义 */
 #define RCU_CFG1_PREDV1_OFFSET      ((uint32_t)4U)

 /*!
@@ -115,6 +125,11 @@ void rcu_deinit(void)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_periph_clock_enable 函数
+ * @param[in] periph 参数
+ * @return void
+ */
 void rcu_periph_clock_enable(rcu_periph_enum periph)
 {
    RCU_REG_VAL(periph) |= BIT(RCU_BIT_POS(periph));
@@ -146,6 +161,11 @@ void rcu_periph_clock_enable(rcu_periph_enum periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_periph_clock_disable 函数
+ * @param[in] periph 参数
+ * @return void
+ */
 void rcu_periph_clock_disable(rcu_periph_enum periph)
 {
    RCU_REG_VAL(periph) &= ~BIT(RCU_BIT_POS(periph));
@@ -201,6 +221,11 @@ void rcu_periph_clock_sleep_disable(rcu_periph_sleep_enum periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_periph_reset_enable 函数
+ * @param[in] periph_reset 参数
+ * @return void
+ */
 void rcu_periph_reset_enable(rcu_periph_reset_enum periph_reset)
 {
    RCU_REG_VAL(periph_reset) |= BIT(RCU_BIT_POS(periph_reset));
@@ -228,6 +253,11 @@ void rcu_periph_reset_enable(rcu_periph_reset_enum periph_reset)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_periph_reset_disable 函数
+ * @param[in] periph_reset 参数
+ * @return void
+ */
 void rcu_periph_reset_disable(rcu_periph_reset_enum periph_reset)
 {
    RCU_REG_VAL(periph_reset) &= ~BIT(RCU_BIT_POS(periph_reset));
@@ -371,6 +401,11 @@ void rcu_apb2_clock_config(uint32_t ck_apb2)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_ckout0_config 函数
+ * @param[in] ckout0_src 参数
+ * @return void
+ */
 void rcu_ckout0_config(uint32_t ckout0_src)
 {
    uint32_t reg;
@@ -520,6 +555,11 @@ void rcu_pll2_config(uint32_t pll_mul)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_adc_clock_config 函数
+ * @param[in] adc_psc 参数
+ * @return void
+ */
 void rcu_adc_clock_config(uint32_t adc_psc)
 {
    uint32_t reg0,reg1;
@@ -577,6 +617,11 @@ void rcu_adc_clock_config(uint32_t adc_psc)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_usb_clock_config 函数
+ * @param[in] usb_psc 参数
+ * @return void
+ */
 void rcu_usb_clock_config(uint32_t usb_psc)
 {
    uint32_t reg;
@@ -688,6 +733,11 @@ void rcu_ck48m_clock_config(uint32_t ck48m_clock_source)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_flag_get 函数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus rcu_flag_get(rcu_flag_enum flag)
 {
    FlagStatus rcu_flag = RESET;
@@ -729,6 +779,11 @@ void rcu_all_reset_flag_clear(void)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief rcu_interrupt_flag_get 函数
+ * @param[in] int_flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus rcu_interrupt_flag_get(rcu_int_flag_enum int_flag)
 {
    FlagStatus rcu_int_flag = RESET;
@@ -759,6 +814,11 @@ FlagStatus rcu_interrupt_flag_get(rcu_int_flag_enum int_flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_interrupt_flag_clear 函数
+ * @param[in] int_flag_clear 参数
+ * @return void
+ */
 void rcu_interrupt_flag_clear(rcu_int_flag_clear_enum int_flag_clear)
 {
    RCU_REG_VAL(int_flag_clear) |= BIT(RCU_BIT_POS(int_flag_clear));
@@ -779,6 +839,11 @@ void rcu_interrupt_flag_clear(rcu_int_flag_clear_enum int_flag_clear)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_interrupt_enable 函数
+ * @param[in] stab_int 参数
+ * @return void
+ */
 void rcu_interrupt_enable(rcu_int_enum stab_int)
 {
    RCU_REG_VAL(stab_int) |= BIT(RCU_BIT_POS(stab_int));
@@ -799,6 +864,11 @@ void rcu_interrupt_enable(rcu_int_enum stab_int)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_interrupt_disable 函数
+ * @param[in] stab_int 参数
+ * @return void
+ */
 void rcu_interrupt_disable(rcu_int_enum stab_int)
 {
    RCU_REG_VAL(stab_int) &= ~BIT(RCU_BIT_POS(stab_int));
@@ -841,6 +911,11 @@ void rcu_lxtal_drive_capability_config(uint32_t lxtal_dricap)
    \param[out] none
    \retval     ErrStatus: SUCCESS or ERROR
 */
+/**
+ * @brief rcu_osci_stab_wait 函数
+ * @param[in] osci 参数
+ * @return ErrStatus 返回值
+ */
 ErrStatus rcu_osci_stab_wait(rcu_osci_type_enum osci)
 {
    uint32_t stb_cnt = 0U;
@@ -974,6 +1049,11 @@ ErrStatus rcu_osci_stab_wait(rcu_osci_type_enum osci)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_osci_on 函数
+ * @param[in] osci 参数
+ * @return void
+ */
 void rcu_osci_on(rcu_osci_type_enum osci)
 {
    RCU_REG_VAL(osci) |= BIT(RCU_BIT_POS(osci));
@@ -994,6 +1074,11 @@ void rcu_osci_on(rcu_osci_type_enum osci)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief rcu_osci_off 函数
+ * @param[in] osci 参数
+ * @return void
+ */
 void rcu_osci_off(rcu_osci_type_enum osci)
 {
    RCU_REG_VAL(osci) &= ~BIT(RCU_BIT_POS(osci));
@@ -35,10 +35,13 @@ OF SUCH DAMAGE.
 #include "gd32c10x_rtc.h"

 /* RTC register high / low bits mask */
+/** @brief RTC_HIGH_BITS_MASK 宏定义 */
 #define RTC_HIGH_BITS_MASK         ((uint32_t)0x000F0000U)  /* RTC high bits mask */
+/** @brief RTC_LOW_BITS_MASK 宏定义 */
 #define RTC_LOW_BITS_MASK          ((uint32_t)0x0000FFFFU)  /* RTC low bits mask */

 /* RTC register high bits offset */
+/** @brief RTC_HIGH_BITS_OFFSET 宏定义 */
 #define RTC_HIGH_BITS_OFFSET       ((uint32_t)16U)

 /*!
@@ -34,21 +34,31 @@ OF SUCH DAMAGE.

 #include "gd32c10x_spi.h"

+/** @brief SPI_ERROR_HANDLE 宏定义 */
 #define SPI_ERROR_HANDLE(s)             do{}while(1)

 /* SPI/I2S parameter initialization mask */
+/** @brief SPI_INIT_MASK 宏定义 */
 #define SPI_INIT_MASK                   ((uint32_t)0x00003040U)  /* SPI parameter initialization mask */
+/** @brief I2S_INIT_MASK 宏定义 */
 #define I2S_INIT_MASK                   ((uint32_t)0x0000F047U)  /* I2S parameter initialization mask */

 /* I2S clock source selection, multiplication and division mask */
+/** @brief I2S1_CLOCK_SEL 宏定义 */
 #define I2S1_CLOCK_SEL                  ((uint32_t)0x00020000U)  /* I2S1 clock source selection */
+/** @brief I2S2_CLOCK_SEL 宏定义 */
 #define I2S2_CLOCK_SEL                  ((uint32_t)0x00040000U)  /* I2S2 clock source selection */
+/** @brief I2S_CLOCK_MUL_MASK 宏定义 */
 #define I2S_CLOCK_MUL_MASK              ((uint32_t)0x0000F000U)  /* I2S clock multiplication mask */
+/** @brief I2S_CLOCK_DIV_MASK 宏定义 */
 #define I2S_CLOCK_DIV_MASK              ((uint32_t)0x000000F0U)  /* I2S clock division mask */

 /* default value and offset */
+/** @brief SPI_I2SPSC_DEFAULT_VALUE 宏定义 */
 #define SPI_I2SPSC_DEFAULT_VALUE        ((uint32_t)0x00000002U)  /* default value of SPI_I2SPSC register */
+/** @brief RCU_CFG1_PREDV1_OFFSET 宏定义 */
 #define RCU_CFG1_PREDV1_OFFSET          4U                       /* PREDV1 offset in RCU_CFG1 */
+/** @brief RCU_CFG1_PLL2MF_OFFSET 宏定义 */
 #define RCU_CFG1_PLL2MF_OFFSET          12U                      /* PLL2MF offset in RCU_CFG1 */

 /*!
@@ -115,6 +125,12 @@ void spi_struct_para_init(spi_parameter_struct* spi_struct)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief spi_init 函数
+ * @param[in] spi_periph 参数
+ * @param[in] spi_struct 参数
+ * @return void
+ */
 void spi_init(uint32_t spi_periph, spi_parameter_struct* spi_struct)
 {   
    uint32_t reg = 0U;
@@ -187,6 +203,14 @@ void spi_disable(uint32_t spi_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2s_init 函数
+ * @param[in] spi_periph 参数
+ * @param[in] mode 参数
+ * @param[in] standard 参数
+ * @param[in] ckpl 参数
+ * @return void
+ */
 void i2s_init(uint32_t spi_periph, uint32_t mode, uint32_t standard, uint32_t ckpl)
 {
    uint32_t reg = 0U;
@@ -233,6 +257,14 @@ void i2s_init(uint32_t spi_periph, uint32_t mode, uint32_t standard, uint32_t ck
    \param[out] none
    \retval     none
 */
+/**
+ * @brief i2s_psc_config 函数
+ * @param[in] spi_periph 参数
+ * @param[in] audiosample 参数
+ * @param[in] frameformat 参数
+ * @param[in] mckout 参数
+ * @return void
+ */
 void i2s_psc_config(uint32_t spi_periph, uint32_t audiosample, uint32_t frameformat, uint32_t mckout)
 {
    uint32_t i2sdiv = 2U, i2sof = 0U;
@@ -752,6 +784,12 @@ void spi_i2s_interrupt_disable(uint32_t spi_periph, uint8_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief spi_i2s_interrupt_flag_get 函数
+ * @param[in] spi_periph 参数
+ * @param[in] interrupt 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus spi_i2s_interrupt_flag_get(uint32_t spi_periph, uint8_t interrupt)
 {
    FlagStatus status = RESET;
@@ -829,6 +867,12 @@ FlagStatus spi_i2s_interrupt_flag_get(uint32_t spi_periph, uint8_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief spi_i2s_flag_get 函数
+ * @param[in] spi_periph 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus spi_i2s_flag_get(uint32_t spi_periph, uint32_t flag)
 {
    FlagStatus status = RESET;
@@ -35,6 +35,7 @@ OF SUCH DAMAGE.
 #include "gd32c10x_timer.h"

 /* TIMER init parameter mask */
+/** @brief ALIGNEDMODE_MASK 宏定义 */
 #define ALIGNEDMODE_MASK            ((uint32_t)0x00000060U)   /*!< TIMER init parameter aligne dmode mask */
 #define COUNTERDIRECTION_MASK       ((uint32_t)0x00000010U)   /*!< TIMER init parameter counter direction mask */
 #define CLOCKDIVISION_MASK          ((uint32_t)0x00000300U)   /*!< TIMER init parameter clock division value mask */
@@ -154,6 +155,12 @@ void timer_struct_para_init(timer_parameter_struct* initpara)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_init 函数
+ * @param[in] timer_periph 参数
+ * @param[in] initpara 参数
+ * @return void
+ */
 void timer_init(uint32_t timer_periph, timer_parameter_struct* initpara)
 {
    /* configure the counter prescaler value */
@@ -431,6 +438,12 @@ void timer_update_source_config(uint32_t timer_periph, uint32_t update)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_dma_enable 函数
+ * @param[in] timer_periph 参数
+ * @param[in] dma 参数
+ * @return void
+ */
 void timer_dma_enable(uint32_t timer_periph, uint16_t dma)
 {
    TIMER_DMAINTEN(timer_periph) |= (uint32_t) dma; 
@@ -451,6 +464,12 @@ void timer_dma_enable(uint32_t timer_periph, uint16_t dma)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_dma_disable 函数
+ * @param[in] timer_periph 参数
+ * @param[in] dma 参数
+ * @return void
+ */
 void timer_dma_disable(uint32_t timer_periph, uint16_t dma)
 {
    TIMER_DMAINTEN(timer_periph) &= (~(uint32_t)(dma)); 
@@ -507,6 +526,13 @@ void timer_channel_dma_request_source_select(uint32_t timer_periph, uint32_t dma
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_dma_transfer_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] dma_baseaddr 参数
+ * @param[in] dma_lenth 参数
+ * @return void
+ */
 void timer_dma_transfer_config(uint32_t timer_periph, uint32_t dma_baseaddr, uint32_t dma_lenth)
 {
    TIMER_DMACFG(timer_periph) &= (~(uint32_t)(TIMER_DMACFG_DMATA | TIMER_DMACFG_DMATC));
@@ -529,6 +555,12 @@ void timer_dma_transfer_config(uint32_t timer_periph, uint32_t dma_baseaddr, uin
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_event_software_generate 函数
+ * @param[in] timer_periph 参数
+ * @param[in] event 参数
+ * @return void
+ */
 void timer_event_software_generate(uint32_t timer_periph, uint16_t event)
 {
    TIMER_SWEVG(timer_periph) |= (uint32_t)event;
@@ -566,6 +598,12 @@ void timer_break_struct_para_init(timer_break_parameter_struct* breakpara)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_break_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] breakpara 参数
+ * @return void
+ */
 void timer_break_config(uint32_t timer_periph, timer_break_parameter_struct* breakpara)
 {
    TIMER_CCHP(timer_periph) = (uint32_t)(((uint32_t)(breakpara->runoffstate)) |
@@ -710,6 +748,13 @@ void timer_channel_output_struct_para_init(timer_oc_parameter_struct* ocpara)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocpara 参数
+ * @return void
+ */
 void timer_channel_output_config(uint32_t timer_periph, uint16_t channel, timer_oc_parameter_struct* ocpara)
 {
    switch(channel){
@@ -852,6 +897,13 @@ void timer_channel_output_config(uint32_t timer_periph, uint16_t channel, timer_
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_mode_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocmode 参数
+ * @return void
+ */
 void timer_channel_output_mode_config(uint32_t timer_periph, uint16_t channel, uint16_t ocmode)
 {
    switch(channel){
@@ -893,6 +945,13 @@ void timer_channel_output_mode_config(uint32_t timer_periph, uint16_t channel, u
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_pulse_value_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] pulse 参数
+ * @return void
+ */
 void timer_channel_output_pulse_value_config(uint32_t timer_periph, uint16_t channel, uint32_t pulse)
 {
    switch(channel){
@@ -933,6 +992,13 @@ void timer_channel_output_pulse_value_config(uint32_t timer_periph, uint16_t cha
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_shadow_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocshadow 参数
+ * @return void
+ */
 void timer_channel_output_shadow_config(uint32_t timer_periph, uint16_t channel, uint16_t ocshadow)
 {
    switch(channel){
@@ -977,6 +1043,13 @@ void timer_channel_output_shadow_config(uint32_t timer_periph, uint16_t channel,
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_fast_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocfast 参数
+ * @return void
+ */
 void timer_channel_output_fast_config(uint32_t timer_periph, uint16_t channel, uint16_t ocfast)
 {
    switch(channel){
@@ -1021,6 +1094,13 @@ void timer_channel_output_fast_config(uint32_t timer_periph, uint16_t channel, u
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_clear_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] occlear 参数
+ * @return void
+ */
 void timer_channel_output_clear_config(uint32_t timer_periph, uint16_t channel, uint16_t occlear)
 {
    switch(channel){
@@ -1065,6 +1145,13 @@ void timer_channel_output_clear_config(uint32_t timer_periph, uint16_t channel,
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_polarity_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocpolarity 参数
+ * @return void
+ */
 void timer_channel_output_polarity_config(uint32_t timer_periph, uint16_t channel, uint16_t ocpolarity)
 {
    switch(channel){
@@ -1108,6 +1195,13 @@ void timer_channel_output_polarity_config(uint32_t timer_periph, uint16_t channe
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_complementary_output_polarity_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocnpolarity 参数
+ * @return void
+ */
 void timer_channel_complementary_output_polarity_config(uint32_t timer_periph, uint16_t channel, uint16_t ocnpolarity)
 {
    switch(channel){
@@ -1147,6 +1241,13 @@ void timer_channel_complementary_output_polarity_config(uint32_t timer_periph, u
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_output_state_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] state 参数
+ * @return void
+ */
 void timer_channel_output_state_config(uint32_t timer_periph, uint16_t channel, uint32_t state)
 {
    switch(channel){
@@ -1190,6 +1291,13 @@ void timer_channel_output_state_config(uint32_t timer_periph, uint16_t channel,
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_complementary_output_state_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] ocnstate 参数
+ * @return void
+ */
 void timer_channel_complementary_output_state_config(uint32_t timer_periph, uint16_t channel, uint16_t ocnstate)
 {
    switch(channel){
@@ -1248,6 +1356,13 @@ void timer_channel_input_struct_para_init(timer_ic_parameter_struct* icpara)
    \param[out]  none
    \retval      none
 */
+/**
+ * @brief timer_input_capture_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] icpara 参数
+ * @return void
+ */
 void timer_input_capture_config(uint32_t timer_periph, uint16_t channel, timer_ic_parameter_struct* icpara)
 {
    switch(channel){
@@ -1353,6 +1468,13 @@ void timer_input_capture_config(uint32_t timer_periph, uint16_t channel, timer_i
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_channel_input_capture_prescaler_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] prescaler 参数
+ * @return void
+ */
 void timer_channel_input_capture_prescaler_config(uint32_t timer_periph, uint16_t channel, uint16_t prescaler)
 {
    switch(channel){
@@ -1436,6 +1558,13 @@ uint32_t timer_channel_capture_value_register_read(uint32_t timer_periph, uint16
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_input_pwm_capture_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] channel 参数
+ * @param[in] icpwm 参数
+ * @return void
+ */
 void timer_input_pwm_capture_config(uint32_t timer_periph, uint16_t channel, timer_ic_parameter_struct* icpwm)
 {
    uint16_t icpolarity  = 0x0U;
@@ -1570,6 +1699,12 @@ void timer_hall_mode_config(uint32_t timer_periph, uint32_t hallmode)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_input_trigger_source_select 函数
+ * @param[in] timer_periph 参数
+ * @param[in] intrigger 参数
+ * @return void
+ */
 void timer_input_trigger_source_select(uint32_t timer_periph, uint32_t intrigger)
 {
    TIMER_SMCFG(timer_periph) &= (~(uint32_t)TIMER_SMCFG_TRGS);
@@ -1592,6 +1727,12 @@ void timer_input_trigger_source_select(uint32_t timer_periph, uint32_t intrigger
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_master_output_trigger_source_select 函数
+ * @param[in] timer_periph 参数
+ * @param[in] outrigger 参数
+ * @return void
+ */
 void timer_master_output_trigger_source_select(uint32_t timer_periph, uint32_t outrigger)
 {
    TIMER_CTL1(timer_periph) &= (~(uint32_t)TIMER_CTL1_MMC);
@@ -1615,6 +1756,12 @@ void timer_master_output_trigger_source_select(uint32_t timer_periph, uint32_t o
    \retval     none
 */

+/**
+ * @brief timer_slave_mode_select 函数
+ * @param[in] timer_periph 参数
+ * @param[in] slavemode 参数
+ * @return void
+ */
 void timer_slave_mode_select(uint32_t timer_periph, uint32_t slavemode)
 {
    TIMER_SMCFG(timer_periph) &= (~(uint32_t)TIMER_SMCFG_SMC);
@@ -1659,6 +1806,14 @@ void timer_master_slave_mode_config(uint32_t timer_periph, uint32_t masterslave)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_external_trigger_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] extprescaler 参数
+ * @param[in] extpolarity 参数
+ * @param[in] extfilter 参数
+ * @return void
+ */
 void timer_external_trigger_config(uint32_t timer_periph, uint32_t extprescaler, uint32_t extpolarity, uint32_t extfilter)
 {
    TIMER_SMCFG(timer_periph) &= (~(uint32_t)(TIMER_SMCFG_ETP | TIMER_SMCFG_ETPSC | TIMER_SMCFG_ETFC));
@@ -1685,6 +1840,14 @@ void timer_external_trigger_config(uint32_t timer_periph, uint32_t extprescaler,
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_quadrature_decoder_mode_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] decomode 参数
+ * @param[in] ic0polarity 参数
+ * @param[in] ic1polarity 参数
+ * @return void
+ */
 void timer_quadrature_decoder_mode_config(uint32_t timer_periph, uint32_t decomode, uint16_t ic0polarity, uint16_t ic1polarity)
 {
    /* configure the quadrature decoder mode */
@@ -1745,6 +1908,14 @@ void timer_internal_trigger_as_external_clock_config(uint32_t timer_periph, uint
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_external_trigger_as_external_clock_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] extrigger 参数
+ * @param[in] extpolarity 参数
+ * @param[in] extfilter 参数
+ * @return void
+ */
 void timer_external_trigger_as_external_clock_config(uint32_t timer_periph, uint32_t extrigger, uint16_t extpolarity, uint32_t extfilter)
 {
    if(TIMER_SMCFG_TRGSEL_CI1FE1 == extrigger){
@@ -1807,6 +1978,14 @@ void timer_external_trigger_as_external_clock_config(uint32_t timer_periph, uint
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_external_clock_mode0_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] extprescaler 参数
+ * @param[in] extpolarity 参数
+ * @param[in] extfilter 参数
+ * @return void
+ */
 void timer_external_clock_mode0_config(uint32_t timer_periph, uint32_t extprescaler, uint32_t extpolarity, uint32_t extfilter)
 {
    /* configure TIMER external trigger input */
@@ -1834,6 +2013,14 @@ void timer_external_clock_mode0_config(uint32_t timer_periph, uint32_t extpresca
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_external_clock_mode1_config 函数
+ * @param[in] timer_periph 参数
+ * @param[in] extprescaler 参数
+ * @param[in] extpolarity 参数
+ * @param[in] extfilter 参数
+ * @return void
+ */
 void timer_external_clock_mode1_config(uint32_t timer_periph, uint32_t extprescaler, uint32_t extpolarity, uint32_t extfilter)
 {
    /* configure TIMER external trigger input */
@@ -1910,6 +2097,12 @@ void timer_output_value_selection_config(uint32_t timer_periph, uint16_t outsel)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_interrupt_enable 函数
+ * @param[in] timer_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void timer_interrupt_enable(uint32_t timer_periph, uint32_t interrupt)
 {
    TIMER_DMAINTEN(timer_periph) |= (uint32_t) interrupt; 
@@ -1931,6 +2124,12 @@ void timer_interrupt_enable(uint32_t timer_periph, uint32_t interrupt)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_interrupt_disable 函数
+ * @param[in] timer_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void timer_interrupt_disable(uint32_t timer_periph, uint32_t interrupt)
 {
    TIMER_DMAINTEN(timer_periph) &= (~(uint32_t)interrupt); 
@@ -1952,6 +2151,12 @@ void timer_interrupt_disable(uint32_t timer_periph, uint32_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief timer_interrupt_flag_get 函数
+ * @param[in] timer_periph 参数
+ * @param[in] interrupt 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus timer_interrupt_flag_get(uint32_t timer_periph, uint32_t interrupt)
 {
    uint32_t val;
@@ -1981,6 +2186,12 @@ FlagStatus timer_interrupt_flag_get(uint32_t timer_periph, uint32_t interrupt)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_interrupt_flag_clear 函数
+ * @param[in] timer_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void timer_interrupt_flag_clear(uint32_t timer_periph, uint32_t interrupt)
 {
    TIMER_INTF(timer_periph) = (~(uint32_t)interrupt);
@@ -2006,6 +2217,12 @@ void timer_interrupt_flag_clear(uint32_t timer_periph, uint32_t interrupt)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief timer_flag_get 函数
+ * @param[in] timer_periph 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus timer_flag_get(uint32_t timer_periph, uint32_t flag)
 {
    FlagStatus ret;
@@ -2037,6 +2254,12 @@ FlagStatus timer_flag_get(uint32_t timer_periph, uint32_t flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief timer_flag_clear 函数
+ * @param[in] timer_periph 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void timer_flag_clear(uint32_t timer_periph, uint32_t flag)
 {
    TIMER_INTF(timer_periph) = (~(uint32_t)flag);
@@ -35,8 +35,11 @@ OF SUCH DAMAGE.
 #include "gd32c10x_usart.h"

 /* USART register bit offset */
+/** @brief GP_GUAT_OFFSET 宏定义 */
 #define GP_GUAT_OFFSET            ((uint32_t)8U)       /* bit offset of GUAT in USART_GP */
+/** @brief CTL3_SCRTNUM_OFFSET 宏定义 */
 #define CTL3_SCRTNUM_OFFSET       ((uint32_t)1U)       /* bit offset of SCRTNUM in USART_CTL3 */
+/** @brief RT_BL_OFFSET 宏定义 */
 #define RT_BL_OFFSET              ((uint32_t)24U)      /* bit offset of BL in USART_RT */

 /*!
@@ -261,6 +264,12 @@ void usart_data_first_config(uint32_t usart_periph, uint32_t msbf)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief usart_invert_config 函数
+ * @param[in] usart_periph 参数
+ * @param[in] invertpara 参数
+ * @return void
+ */
 void usart_invert_config(uint32_t usart_periph, usart_invert_enum invertpara)
 {
    /* inverted or not the specified signal */
@@ -514,6 +523,14 @@ void usart_synchronous_clock_disable(uint32_t usart_periph)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief usart_synchronous_clock_config 函数
+ * @param[in] usart_periph 参数
+ * @param[in] clen 参数
+ * @param[in] cph 参数
+ * @param[in] cpl 参数
+ * @return void
+ */
 void usart_synchronous_clock_config(uint32_t usart_periph, uint32_t clen, uint32_t cph, uint32_t cpl)
 {
    USART_CTL1(usart_periph) &= ~(USART_CTL1_CLEN | USART_CTL1_CPH | USART_CTL1_CPL);
@@ -755,6 +772,12 @@ void usart_hardware_flow_coherence_config(uint32_t usart_periph, uint32_t hcm)
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief usart_flag_get 函数
+ * @param[in] usart_periph 参数
+ * @param[in] flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus usart_flag_get(uint32_t usart_periph, usart_flag_enum flag)
 {
    FlagStatus ret;
@@ -782,6 +805,12 @@ FlagStatus usart_flag_get(uint32_t usart_periph, usart_flag_enum flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief usart_flag_clear 函数
+ * @param[in] usart_periph 参数
+ * @param[in] flag 参数
+ * @return void
+ */
 void usart_flag_clear(uint32_t usart_periph, usart_flag_enum flag)
 {
    if(USART_FLAG_EPERR == flag) {
@@ -809,6 +838,12 @@ void usart_flag_clear(uint32_t usart_periph, usart_flag_enum flag)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief usart_interrupt_enable 函数
+ * @param[in] usart_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void usart_interrupt_enable(uint32_t usart_periph, usart_interrupt_enum interrupt)
 {
    USART_REG_VAL(usart_periph, interrupt) |= BIT(USART_BIT_POS(interrupt));
@@ -832,6 +867,12 @@ void usart_interrupt_enable(uint32_t usart_periph, usart_interrupt_enum interrup
    \param[out] none
    \retval     none
 */
+/**
+ * @brief usart_interrupt_disable 函数
+ * @param[in] usart_periph 参数
+ * @param[in] interrupt 参数
+ * @return void
+ */
 void usart_interrupt_disable(uint32_t usart_periph, usart_interrupt_enum interrupt)
 {
    USART_REG_VAL(usart_periph, interrupt) &= ~BIT(USART_BIT_POS(interrupt));
@@ -858,6 +899,12 @@ void usart_interrupt_disable(uint32_t usart_periph, usart_interrupt_enum interru
    \param[out] none
    \retval     FlagStatus: SET or RESET
 */
+/**
+ * @brief usart_interrupt_flag_get 函数
+ * @param[in] usart_periph 参数
+ * @param[in] int_flag 参数
+ * @return FlagStatus 返回值
+ */
 FlagStatus usart_interrupt_flag_get(uint32_t usart_periph, usart_interrupt_flag_enum int_flag)
 {
    uint32_t intenable = 0U, flagstatus = 0U;
@@ -889,6 +936,12 @@ FlagStatus usart_interrupt_flag_get(uint32_t usart_periph, usart_interrupt_flag_
    \param[out] none
    \retval     none
 */
+/**
+ * @brief usart_interrupt_flag_clear 函数
+ * @param[in] usart_periph 参数
+ * @param[in] int_flag 参数
+ * @return void
+ */
 void usart_interrupt_flag_clear(uint32_t usart_periph, usart_interrupt_flag_enum int_flag)
 {
    USART_REG_VAL2(usart_periph, int_flag) = ~BIT(USART_BIT_POS2(int_flag));
@@ -81,6 +81,13 @@ void wwdgt_counter_update(uint16_t counter_value)
    \param[out] none
    \retval     none
 */
+/**
+ * @brief wwdgt_config 函数
+ * @param[in] counter 参数
+ * @param[in] window 参数
+ * @param[in] prescaler 参数
+ * @return void
+ */
 void wwdgt_config(uint16_t counter, uint16_t window, uint32_t prescaler)
 {
    WWDGT_CTL = (uint32_t)(CTL_CNT(counter));
@@ -1,3 +1,9 @@
+/**
+ * @file RTE/Device/GD32C103CB/regions_GD32C103CB.h
+ * @brief GD32 RTE 外设库或运行时配置源文件
+ * @note 本文件仅补充 Doxygen 文档注释，不改变代码逻辑。
+ */
+
 #ifndef REGIONS_GD32C103CB_H
 #define REGIONS_GD32C103CB_H

@@ -42,6 +42,7 @@
 #define __SYS_OSC_CLK     (__IRC8M)                /* main oscillator frequency */

 /* Vector Table base offset */
+/** @brief APP_BASE 宏定义 */
 #define APP_BASE            ((uint32_t)0x08012000U)        /*!< main FLASH base address          */
 #define VECT_TAB_OFFSET  (uint32_t)APP_BASE-FLASH_BASE                    /* This value must be a multiple of 0x200. */

@@ -62,6 +63,7 @@

 /* The following is to prevent Vcore fluctuations caused by frequency switching. 
   It is strongly recommended to include it to avoid issues caused by self-removal. */
+/** @brief RCU_MODIFY_4 宏定义 */
 #define RCU_MODIFY_4(__delay)   do{                                     \
                                    volatile uint32_t i, reg;           \
                                    if(0 != __delay){                   \
@@ -103,49 +105,101 @@
                                    }                                   \
                                }while(0)

+/** @brief SEL_IRC8M 宏定义 */
 #define SEL_IRC8M       0x00U
+/** @brief SEL_HXTAL 宏定义 */
 #define SEL_HXTAL       0x01U
+/** @brief SEL_PLL 宏定义 */
 #define SEL_PLL         0x02U

 /* set the system clock frequency and declare the system clock configuration function */
 #ifdef __SYSTEM_CLOCK_IRC8M
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_IRC8M;
+/**
+ * @brief system_clock_8m_irc8m 函数
+ * @return void
+ */
 static void system_clock_8m_irc8m(void);
 #elif defined (__SYSTEM_CLOCK_48M_PLL_IRC8M)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_48M_PLL_IRC8M;
+/**
+ * @brief system_clock_48m_irc8m 函数
+ * @return void
+ */
 static void system_clock_48m_irc8m(void);
 #elif defined (__SYSTEM_CLOCK_72M_PLL_IRC8M)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_72M_PLL_IRC8M;
+/**
+ * @brief system_clock_72m_irc8m 函数
+ * @return void
+ */
 static void system_clock_72m_irc8m(void);
 #elif defined (__SYSTEM_CLOCK_108M_PLL_IRC8M)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_108M_PLL_IRC8M;
+/**
+ * @brief system_clock_108m_irc8m 函数
+ * @return void
+ */
 static void system_clock_108m_irc8m(void);
 #elif defined (__SYSTEM_CLOCK_120M_PLL_IRC8M)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_120M_PLL_IRC8M;
+/**
+ * @brief system_clock_120m_irc8m 函数
+ * @return void
+ */
 static void system_clock_120m_irc8m(void);

 #elif defined (__SYSTEM_CLOCK_HXTAL)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_HXTAL;
+/**
+ * @brief system_clock_hxtal 函数
+ * @return void
+ */
 static void system_clock_hxtal(void);
 #elif defined (__SYSTEM_CLOCK_48M_PLL_HXTAL)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_48M_PLL_HXTAL;
+/**
+ * @brief system_clock_48m_hxtal 函数
+ * @return void
+ */
 static void system_clock_48m_hxtal(void);
 #elif defined (__SYSTEM_CLOCK_72M_PLL_HXTAL)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_72M_PLL_HXTAL;
+/**
+ * @brief system_clock_72m_hxtal 函数
+ * @return void
+ */
 static void system_clock_72m_hxtal(void);
 #elif defined (__SYSTEM_CLOCK_108M_PLL_HXTAL)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_108M_PLL_HXTAL;
+/**
+ * @brief system_clock_108m_hxtal 函数
+ * @return void
+ */
 static void system_clock_108m_hxtal(void);
 #elif defined (__SYSTEM_CLOCK_120M_PLL_HXTAL)
 uint32_t SystemCoreClock = __SYSTEM_CLOCK_120M_PLL_HXTAL;
+/**
+ * @brief system_clock_120m_hxtal 函数
+ * @return void
+ */
 static void system_clock_120m_hxtal(void);
 #endif /* __SYSTEM_CLOCK_IRC8M */

 /* configure the system clock */
+/**
+ * @brief system_clock_config 函数
+ * @return void
+ */
 static void system_clock_config(void);

 /* software delay to prevent the impact of Vcore fluctuations.
   It is strongly recommended to include it to avoid issues caused by self-removal. */
+/**
+ * @brief _soft_delay_ 函数
+ * @param[in] time 参数
+ * @return void
+ */
 static void _soft_delay_(uint32_t time)
 {
    __IO uint32_t i;