[doxygen][rsoc]add pwm touch can i2c spi driver example for doxygen

components/drivers/include/drivers/dev_can.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -66,9 +66,143 @@ enum CANBAUD
 /**
  * @addtogroup  Drivers          RTTHREAD Driver
  * @defgroup    CAN_Device          CAN Driver
+ *
+ * @brief       CAN driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * #include <rtthread.h>
+ * #include "rtdevice.h"
+ *
+ * #define CAN_DEV_NAME       "can1"      // CAN 设备名称
+ *
+ * static struct rt_semaphore rx_sem;     // 用于接收消息的信号量
+ * static rt_device_t can_dev;            // CAN 设备句柄
+ *
+ * // 接收数据回调函数
+ * static rt_err_t can_rx_call(rt_device_t dev, rt_size_t size)
+ * {
+ *     // CAN 接收到数据后产生中断，调用此回调函数，然后发送接收信号量
+ *     rt_sem_release(&rx_sem);
+ *
+ *     return RT_EOK;
+ * }
+ *
+ * static void can_rx_thread(void *parameter)
+ * {
+ *     int i;
+ *     rt_err_t res;
+ *     struct rt_can_msg rxmsg = {0};
+ *
+ *     // 设置接收回调函数
+ *     rt_device_set_rx_indicate(can_dev, can_rx_call);
+ *
+ * #ifdef RT_CAN_USING_HDR
+ *     struct rt_can_filter_item items[5] =
+ *     {
+ *         RT_CAN_FILTER_ITEM_INIT(0x100, 0, 0, 0, 0x700, RT_NULL, RT_NULL), // std,match ID:0x100~0x1ff，hdr 为 - 1，设置默认过滤表
+ *         RT_CAN_FILTER_ITEM_INIT(0x300, 0, 0, 0, 0x700, RT_NULL, RT_NULL), // std,match ID:0x300~0x3ff，hdr 为 - 1
+ *         RT_CAN_FILTER_ITEM_INIT(0x211, 0, 0, 0, 0x7ff, RT_NULL, RT_NULL), // std,match ID:0x211，hdr 为 - 1
+ *         RT_CAN_FILTER_STD_INIT(0x486, RT_NULL, RT_NULL),                  // std,match ID:0x486，hdr 为 - 1
+ *         {0x555, 0, 0, 0, 0x7ff, 7,}                                       // std,match ID:0x555，hdr 为 7，指定设置 7 号过滤表
+ *     };
+ *     struct rt_can_filter_config cfg = {5, 1, items}; // 一共有 5 个过滤表
+ *     // 设置硬件过滤表
+ *     res = rt_device_control(can_dev, RT_CAN_CMD_SET_FILTER, &cfg);
+ *     RT_ASSERT(res == RT_EOK);
+ * #endif
+ *
+ *     while (1)
+ *     {
+ *         // hdr 值为 - 1，表示直接从 uselist 链表读取数据
+ *         rxmsg.hdr = -1;
+ *         // 阻塞等待接收信号量
+ *         rt_sem_take(&rx_sem, RT_WAITING_FOREVER);
+ *         // 从 CAN 读取一帧数据
+ *         rt_device_read(can_dev, 0, &rxmsg, sizeof(rxmsg));
+ *         // 打印数据 ID 及内容
+ *         rt_kprintf("ID:%x", rxmsg.id);
+ *         for (i = 0; i < 8; i++)
+ *         {
+ *             rt_kprintf("%2x", rxmsg.data[i]);
+ *         }
+ *
+ *         rt_kprintf("\n");
+ *     }
+ * }
+ *
+ * int can_sample(int argc, char *argv[])
+ * {
+ *     struct rt_can_msg msg = {0};
+ *     rt_err_t res;
+ *     rt_size_t  size;
+ *     rt_thread_t thread;
+ *     char can_name[RT_NAME_MAX];
+ *
+ *     if (argc == 2)
+ *     {
+ *         rt_strncpy(can_name, argv[1], RT_NAME_MAX);
+ *     }
+ *     else
+ *     {
+ *         rt_strncpy(can_name, CAN_DEV_NAME, RT_NAME_MAX);
+ *     }
+ *     // 查找 CAN 设备
+ *     can_dev = rt_device_find(can_name);
+ *     if (!can_dev)
+ *     {
+ *         rt_kprintf("find %s failed!\n", can_name);
+ *         return -RT_ERROR;
+ *     }
+ *
+ *     // 初始化 CAN 接收信号量
+ *     rt_sem_init(&rx_sem, "rx_sem", 0, RT_IPC_FLAG_FIFO);
+ *
+ *     // 以中断接收及发送方式打开 CAN 设备
+ *     res = rt_device_open(can_dev, RT_DEVICE_FLAG_INT_TX | RT_DEVICE_FLAG_INT_RX);
+ *     RT_ASSERT(res == RT_EOK);
+ *     // 创建数据接收线程
+ *     thread = rt_thread_create("can_rx", can_rx_thread, RT_NULL, 1024, 25, 10);
+ *     if (thread != RT_NULL)
+ *     {
+ *         rt_thread_startup(thread);
+ *     }
+ *     else
+ *     {
+ *         rt_kprintf("create can_rx thread failed!\n");
+ *     }
+ *
+ *     msg.id = 0x78;              // ID 为 0x78
+ *     msg.ide = RT_CAN_STDID;     // 标准格式
+ *     msg.rtr = RT_CAN_DTR;       // 数据帧
+ *     msg.len = 8;                // 数据长度为 8
+ *     // 待发送的 8 字节数据
+ *     msg.data[0] = 0x00;
+ *     msg.data[1] = 0x11;
+ *     msg.data[2] = 0x22;
+ *     msg.data[3] = 0x33;
+ *     msg.data[4] = 0x44;
+ *     msg.data[5] = 0x55;
+ *     msg.data[6] = 0x66;
+ *     msg.data[7] = 0x77;
+ *     // 发送一帧 CAN 数据
+ *     size = rt_device_write(can_dev, 0, &msg, sizeof(msg));
+ *     if (size == 0)
+ *     {
+ *         rt_kprintf("can dev write data failed!\n");
+ *     }
+ *
+ *     return res;
+ * }
+ * // 导出到 msh 命令列表中
+ * MSH_CMD_EXPORT(can_sample, can device sample);
+ * @endcode
+ *
  * @ingroup     Drivers
+ *
  */
 
+
 /*!
  * @addtogroup CAN_Device
  * @{
@@ -76,6 +210,9 @@ enum CANBAUD
 #define CAN_RX_FIFO0                (0x00000000U)  /*!< CAN receive FIFO 0 */
 #define CAN_RX_FIFO1                (0x00000001U)  /*!< CAN receive FIFO 1 */
 
+/**
+ * @brief CAN filter item
+ */
 struct rt_can_filter_item
 {
     rt_uint32_t id  : 29;
@@ -125,6 +262,10 @@ struct rt_can_filter_item
      RT_CAN_FILTER_ITEM_INIT(id,1,0,1,0xFFFFFFFF)
 #endif
 
+
+/**
+ * @brief CAN filter configuration
+ */
 struct rt_can_filter_config
 {
     rt_uint32_t count;
@@ -132,6 +273,9 @@ struct rt_can_filter_config
     struct rt_can_filter_item *items;
 };
 
+/**
+ * @brief CAN timing configuration
+ */
 struct rt_can_bit_timing
 {
     rt_uint16_t prescaler;  /* Pre-scaler */
@@ -142,8 +286,8 @@ struct rt_can_bit_timing
 };
 
 /**
- * CAN bit timing configuration list
- * NOTE:
+ * @brief CAN bit timing configuration list
+ * @note
  *  items[0] always for CAN2.0/CANFD Arbitration Phase
  *  items[1] always for CANFD (if it exists)
  */
@@ -153,6 +297,10 @@ struct rt_can_bit_timing_config
     struct rt_can_bit_timing *items;
 };
 
+
+/**
+ * @brief CAN configuration
+ */
 struct can_configure
 {
     rt_uint32_t baud_rate;
@@ -218,6 +366,9 @@ enum RT_CAN_BUS_ERR
     RT_CAN_BUS_CRC_ERR = 6,
 };
 
+/**
+ * @brief CAN status
+ */
 struct rt_can_status
 {
     rt_uint32_t rcverrcnt;
@@ -248,6 +399,7 @@ struct rt_can_hdr
 #endif
 struct rt_can_device;
 typedef rt_err_t (*rt_canstatus_ind)(struct rt_can_device *, void *);
+
 typedef struct rt_can_status_ind_type
 {
     rt_canstatus_ind ind;
@@ -354,6 +506,9 @@ struct rt_can_tx_fifo
     struct rt_list_node freelist;
 };
 
+/**
+ * @brief CAN operators
+ */
 struct rt_can_ops
 {
     rt_err_t (*configure)(struct rt_can_device *can, struct can_configure *cfg);
@@ -362,13 +517,29 @@ struct rt_can_ops
     rt_ssize_t (*recvmsg)(struct rt_can_device *can, void *buf, rt_uint32_t boxno);
 };
 
+/**
+ * @brief Register a CAN device to device list
+ *
+ * @param can   the CAN device object
+ * @param name  the name of CAN device
+ * @param ops   the CAN device operators
+ * @param data  the private data of CAN device
+ *
+ * @return the error code, RT_EOK on successfully
+ */
 rt_err_t rt_hw_can_register(struct rt_can_device    *can,
                             const char              *name,
                             const struct rt_can_ops *ops,
                             void                    *data);
+
+/**
+ * @brief CAN interrupt service routine
+ *
+ * @param can    the CAN device
+ * @param event  the event mask
+ */
 void rt_hw_can_isr(struct rt_can_device *can, int event);
 
-/*! @}
-*/
+/*! @}*/
 
-#endif /*__DEV_CAN_H*/
+#endif /*__DEV_CAN_H*/

components/drivers/include/drivers/dev_i2c.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -13,18 +13,180 @@
 #define __DEV_I2C_H__
 
 #include <rtthread.h>
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    I2C              I2C
+ *
+ * @brief       I2C driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * #include <rtthread.h>
+ * #include <rtdevice.h>
+ *
+ * #define AHT10_I2C_BUS_NAME          "i2c1"  // 传感器连接的I2C总线设备名称
+ * #define AHT10_ADDR                  0x38    // 从机地址
+ * #define AHT10_CALIBRATION_CMD       0xE1    // 校准命令
+ * #define AHT10_NORMAL_CMD            0xA8    // 一般命令
+ * #define AHT10_GET_DATA              0xAC    // 获取数据命令
+ *
+ * static struct rt_i2c_bus_device *i2c_bus = RT_NULL;     // I2C总线设备句柄
+ * static rt_bool_t initialized = RT_FALSE;                // 传感器初始化状态
+ *
+ * // 写传感器寄存器
+ * static rt_err_t write_reg(struct rt_i2c_bus_device *bus, rt_uint8_t reg, rt_uint8_t *data)
+ * {
+ *     rt_uint8_t buf[3];
+ *     struct rt_i2c_msg msgs;
+ *     rt_uint32_t buf_size = 1;
+ *
+ *     buf[0] = reg; //cmd
+ *     if (data != RT_NULL)
+ *     {
+ *         buf[1] = data[0];
+ *         buf[2] = data[1];
+ *         buf_size = 3;
+ *     }
+ *
+ *     msgs.addr = AHT10_ADDR;
+ *     msgs.flags = RT_I2C_WR;
+ *     msgs.buf = buf;
+ *     msgs.len = buf_size;
+ *
+ *     // 调用I2C设备接口传输数据
+ *     if (rt_i2c_transfer(bus, &msgs, 1) == 1)
+ *     {
+ *         return RT_EOK;
+ *     }
+ *     else
+ *     {
+ *         return -RT_ERROR;
+ *     }
+ * }
+ *
+ * // 读传感器寄存器数据
+ * static rt_err_t read_regs(struct rt_i2c_bus_device *bus, rt_uint8_t len, rt_uint8_t *buf)
+ * {
+ *     struct rt_i2c_msg msgs;
+ *
+ *     msgs.addr = AHT10_ADDR;
+ *     msgs.flags = RT_I2C_RD;
+ *     msgs.buf = buf;
+ *     msgs.len = len;
+ *
+ *     // 调用I2C设备接口传输数据
+ *     if (rt_i2c_transfer(bus, &msgs, 1) == 1)
+ *     {
+ *         return RT_EOK;
+ *     }
+ *     else
+ *     {
+ *         return -RT_ERROR;
+ *     }
+ * }
+ *
+ * static void read_temp_humi(float *cur_temp, float *cur_humi)
+ * {
+ *     rt_uint8_t temp[6];
+ *
+ *     write_reg(i2c_bus, AHT10_GET_DATA, RT_NULL);      // 发送命令
+ *     rt_thread_mdelay(400);
+ *     read_regs(i2c_bus, 6, temp);                // 获取传感器数据
+ *
+ *     // 湿度数据转换
+ *     *cur_humi = (temp[1] << 12 | temp[2] << 4 | (temp[3] & 0xf0) >> 4) * 100.0 / (1 << 20);
+ *     // 温度数据转换
+ *     *cur_temp = ((temp[3] & 0xf) << 16 | temp[4] << 8 | temp[5]) * 200.0 / (1 << 20) - 50;
+ * }
+ *
+ * static void aht10_init(const char *name)
+ * {
+ *     rt_uint8_t temp[2] = {0, 0};
+ *
+ *     // 查找I2C总线设备，获取I2C总线设备句柄
+ *     i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name);
+ *
+ *     if (i2c_bus == RT_NULL)
+ *     {
+ *         rt_kprintf("can't find %s device!\n", name);
+ *     }
+ *     else
+ *     {
+ *         write_reg(i2c_bus, AHT10_NORMAL_CMD, temp);
+ *         rt_thread_mdelay(400);
+ *
+ *         temp[0] = 0x08;
+ *         temp[1] = 0x00;
+ *         write_reg(i2c_bus, AHT10_CALIBRATION_CMD, temp);
+ *         rt_thread_mdelay(400);
+ *         initialized = RT_TRUE;
+ *     }
+ * }
+ *
+ * static void i2c_aht10_sample(int argc, char *argv[])
+ * {
+ *     float humidity, temperature;
+ *     char name[RT_NAME_MAX];
+ *
+ *     humidity = 0.0;
+ *     temperature = 0.0;
+ *
+ *     if (argc == 2)
+ *     {
+ *         rt_strncpy(name, argv[1], RT_NAME_MAX);
+ *     }
+ *     else
+ *     {
+ *         rt_strncpy(name, AHT10_I2C_BUS_NAME, RT_NAME_MAX);
+ *     }
+ *
+ *     if (!initialized)
+ *     {
+ *         // 传感器初始化
+ *         aht10_init(name);
+ *     }
+ *     if (initialized)
+ *     {
+ *         // 读取温湿度数据
+ *         read_temp_humi(&temperature, &humidity);
+ *
+ *         rt_kprintf("read aht10 sensor humidity   : %d.%d %%\n", (int)humidity, (int)(humidity * 10) % 10);
+ *         if( temperature >= 0 )
+ *         {
+ *             rt_kprintf("read aht10 sensor temperature: %d.%d°C\n", (int)temperature, (int)(temperature * 10) % 10);
+ *         }
+ *         else
+ *         {
+ *             rt_kprintf("read aht10 sensor temperature: %d.%d°C\n", (int)temperature, (int)(-temperature * 10) % 10);
+ *         }
+ *     }
+ *     else
+ *     {
+ *         rt_kprintf("initialize sensor failed!\n");
+ *     }
+ * }
+ * // 导出到 msh 命令列表中
+ * MSH_CMD_EXPORT(i2c_aht10_sample, i2c aht10 sample);
+ * @endcode
+ *
+ * @ingroup     Drivers
+ */
 
+/*!
+ * @addtogroup I2C
+ * @{
+ */
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-#define RT_I2C_WR                0x0000
-#define RT_I2C_RD               (1u << 0)
-#define RT_I2C_ADDR_10BIT       (1u << 2)  /* this is a ten bit chip address */
-#define RT_I2C_NO_START         (1u << 4)
-#define RT_I2C_IGNORE_NACK      (1u << 5)
+#define RT_I2C_WR                0x0000    /*!< i2c wirte flag */
+#define RT_I2C_RD               (1u << 0)  /*!< i2c read flag  */
+#define RT_I2C_ADDR_10BIT       (1u << 2)  /*!< this is a ten bit chip address */
+#define RT_I2C_NO_START         (1u << 4)  /*!< do not generate START condition */
+#define RT_I2C_IGNORE_NACK      (1u << 5)  /*!< ignore NACK from slave */
 #define RT_I2C_NO_READ_ACK      (1u << 6)  /* when I2C reading, we do not ACK */
-#define RT_I2C_NO_STOP          (1u << 7)
+#define RT_I2C_NO_STOP          (1u << 7)  /*!< do not generate STOP condition */
 
 #define RT_I2C_DEV_CTRL_10BIT        (RT_DEVICE_CTRL_BASE(I2CBUS) + 0x01)
 #define RT_I2C_DEV_CTRL_ADDR         (RT_DEVICE_CTRL_BASE(I2CBUS) + 0x02)
@@ -36,12 +198,18 @@ extern "C" {
 #define RT_I2C_DEV_CTRL_GET_MODE     (RT_DEVICE_CTRL_BASE(I2CBUS) + 0x08)
 #define RT_I2C_DEV_CTRL_GET_ERROR    (RT_DEVICE_CTRL_BASE(I2CBUS) + 0x09)
 
+/**
+ * @brief I2C Private Data
+ */
 struct rt_i2c_priv_data
 {
     struct rt_i2c_msg  *msgs;
     rt_size_t  number;
 };
 
+/**
+ * @brief I2C Message
+ */
 struct rt_i2c_msg
 {
     rt_uint16_t addr;
@@ -52,6 +220,9 @@ struct rt_i2c_msg
 
 struct rt_i2c_bus_device;
 
+/**
+ * @brief I2C Bus Device Operations
+ */
 struct rt_i2c_bus_device_ops
 {
     rt_ssize_t (*master_xfer)(struct rt_i2c_bus_device *bus,
@@ -65,7 +236,9 @@ struct rt_i2c_bus_device_ops
                                 void *args);
 };
 
-/*for i2c bus driver*/
+/**
+ * @brief I2C Bus Device
+ */
 struct rt_i2c_bus_device
 {
     struct rt_device parent;
@@ -77,6 +250,9 @@ struct rt_i2c_bus_device
     void *priv;
 };
 
+/**
+ * @brief I2C Client
+ */
 struct rt_i2c_client
 {
 #ifdef RT_USING_DM
@@ -115,23 +291,91 @@ rt_err_t rt_i2c_device_register(struct rt_i2c_client *client);
 #define RT_I2C_DRIVER_EXPORT(driver)  RT_DRIVER_EXPORT(driver, i2c, BUILIN)
 #endif /* RT_USING_DM */
 
+/**
+ * @brief I2C Bus Device Initialization
+ *
+ * @param bus the I2C bus device
+ * @param name the name of I2C bus device
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_i2c_bus_device_device_init(struct rt_i2c_bus_device *bus,
                                        const char               *name);
 
+/**
+ * @brief I2C Bus Device Register
+ *
+ * @param bus the I2C bus device
+ * @param bus_name the name of I2C bus device
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_i2c_bus_device_register(struct rt_i2c_bus_device *bus,
                                     const char               *bus_name);
+
+/**
+ * @brief I2C Bus Device Find
+ *
+ * @param bus_name the name of I2C bus device
+ *
+ * @return rt_i2c_bus_device the I2C bus device
+ */
 struct rt_i2c_bus_device *rt_i2c_bus_device_find(const char *bus_name);
+
+/**
+ * @brief I2C data transmission.
+ *
+ * @param bus the I2C bus device
+ * @param msgs the I2C message list
+ * @param num the number of I2C message
+ *
+ * @return rt_ssize_t the actual length of transmitted
+ */
 rt_ssize_t rt_i2c_transfer(struct rt_i2c_bus_device *bus,
                           struct rt_i2c_msg         msgs[],
                           rt_uint32_t               num);
+
+/**
+ * @brief I2C Control
+ *
+ * @param bus the I2C bus device
+ * @param cmd the I2C control command
+ * @param args the I2C control arguments
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_i2c_control(struct rt_i2c_bus_device *bus,
                         int cmd,
                         void *args);
+
+/**
+ * @brief I2C Master Send
+ *
+ * @param bus the I2C bus device
+ * @param addr the I2C slave address
+ * @param flags the I2C flags
+ * @param buf the I2C send buffer
+ * @param count the I2C send buffer length
+ *
+ * @return rt_ssize_t the actual length of transmitted
+ */
 rt_ssize_t rt_i2c_master_send(struct rt_i2c_bus_device *bus,
                              rt_uint16_t               addr,
                              rt_uint16_t               flags,
                              const rt_uint8_t         *buf,
                              rt_uint32_t               count);
+
+/**
+ * @brief I2C Master Receive
+ *
+ * @param bus the I2C bus device
+ * @param addr the I2C slave address
+ * @param flags the I2C flags
+ * @param buf the I2C receive buffer
+ * @param count the I2C receive buffer length
+ *
+ * @return rt_ssize_t the actual length of received
+ */
 rt_ssize_t rt_i2c_master_recv(struct rt_i2c_bus_device *bus,
                              rt_uint16_t               addr,
                              rt_uint16_t               flags,
@@ -152,4 +396,6 @@ rt_inline rt_err_t rt_i2c_bus_unlock(struct rt_i2c_bus_device *bus)
 }
 #endif
 
+/*! @}*/
+
 #endif

components/drivers/include/drivers/dev_pin.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -19,13 +19,13 @@
  * @defgroup    Pin              Pin
  *
  * @brief       Pin driver api
- * 
+ *
  * <b>Example</b>
  * @code {.c}
  * #include <rtthread.h>
  * #include <rtdevice.h>
- * 
- * 
+ *
+ *
  * #ifndef BEEP_PIN_NUM
  *     #define BEEP_PIN_NUM            35  // PB0
  * #endif
@@ -35,39 +35,39 @@
  * #ifndef KEY1_PIN_NUM
  *     #define KEY1_PIN_NUM            56  // PD9
  * #endif
- * 
+ *
  * void beep_on(void *args)
  * {
  *     rt_kprintf("turn on beep!\n");
- * 
+ *
  *     rt_pin_write(BEEP_PIN_NUM, PIN_HIGH);
  * }
- * 
+ *
  * void beep_off(void *args)
  * {
  *     rt_kprintf("turn off beep!\n");
- * 
+ *
  *     rt_pin_write(BEEP_PIN_NUM, PIN_LOW);
  * }
- * 
+ *
  * static void pin_beep_sample(void)
  * {
  *     rt_pin_mode(BEEP_PIN_NUM, PIN_MODE_OUTPUT);
  *     rt_pin_write(BEEP_PIN_NUM, PIN_LOW);
- * 
+ *
  *     rt_pin_mode(KEY0_PIN_NUM, PIN_MODE_INPUT_PULLUP);
  *     rt_pin_attach_irq(KEY0_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_on, RT_NULL);
  *     rt_pin_irq_enable(KEY0_PIN_NUM, PIN_IRQ_ENABLE);
- * 
- * 
+ *
+ *
  *     rt_pin_mode(KEY1_PIN_NUM, PIN_MODE_INPUT_PULLUP);
  *     rt_pin_attach_irq(KEY1_PIN_NUM, PIN_IRQ_MODE_FALLING, beep_off, RT_NULL);
  *     rt_pin_irq_enable(KEY1_PIN_NUM, PIN_IRQ_ENABLE);
  * }
- * 
+ *
  * MSH_CMD_EXPORT(pin_beep_sample, pin beep sample);
  * @endcode
- * 
+ *
  * @ingroup     Drivers
  */
 
@@ -105,14 +105,14 @@ struct rt_device_pin
 
 #define PIN_NONE                (-1)
 
-#define PIN_LOW                 0x00
-#define PIN_HIGH                0x01
+#define PIN_LOW                 0x00 /*!< low level */
+#define PIN_HIGH                0x01 /*!< high level */
 
-#define PIN_MODE_OUTPUT         0x00
-#define PIN_MODE_INPUT          0x01
-#define PIN_MODE_INPUT_PULLUP   0x02
-#define PIN_MODE_INPUT_PULLDOWN 0x03
-#define PIN_MODE_OUTPUT_OD      0x04
+#define PIN_MODE_OUTPUT         0x00 /*!< output mode */
+#define PIN_MODE_INPUT          0x01 /*!< input mode */
+#define PIN_MODE_INPUT_PULLUP   0x02 /*!< input mode with pull-up */
+#define PIN_MODE_INPUT_PULLDOWN 0x03 /*!< input mode with pull-down */
+#define PIN_MODE_OUTPUT_OD      0x04 /*!< output mode with open-drain */
 
 #ifdef RT_USING_PINCTRL
 enum
@@ -147,16 +147,16 @@ enum
 };
 #endif /* RT_USING_PINCTRL */
 
-#define PIN_IRQ_MODE_RISING             0x00
-#define PIN_IRQ_MODE_FALLING            0x01
-#define PIN_IRQ_MODE_RISING_FALLING     0x02
-#define PIN_IRQ_MODE_HIGH_LEVEL         0x03
-#define PIN_IRQ_MODE_LOW_LEVEL          0x04
+#define PIN_IRQ_MODE_RISING             0x00 /*!< rising edge trigger */
+#define PIN_IRQ_MODE_FALLING            0x01 /*!< falling edge trigger */
+#define PIN_IRQ_MODE_RISING_FALLING     0x02 /*!< rising and falling edge trigger */
+#define PIN_IRQ_MODE_HIGH_LEVEL         0x03 /*!< high level trigger */
+#define PIN_IRQ_MODE_LOW_LEVEL          0x04 /*!< low level trigger */
 
-#define PIN_IRQ_DISABLE                 0x00
-#define PIN_IRQ_ENABLE                  0x01
+#define PIN_IRQ_DISABLE                 0x00 /*!< disable irq */
+#define PIN_IRQ_ENABLE                  0x01 /*!< enable irq */
 
-#define PIN_IRQ_PIN_NONE                PIN_NONE
+#define PIN_IRQ_PIN_NONE                PIN_NONE /*!< no pin irq */
 
 /**
  * @brief pin mode structure

components/drivers/include/drivers/dev_pwm.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -13,7 +13,78 @@
 #define __DEV_PWM_H__
 
 #include <rtthread.h>
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    PWM              PWM
+ *
+ * @brief       PWM driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * #include <rtthread.h>
+ * #include <rtdevice.h>
+ *
+ * #define PWM_DEV_NAME        "pwm3"  // PWM设备名称
+ * #define PWM_DEV_CHANNEL     4       // PWM通道
+ *
+ * struct rt_device_pwm *pwm_dev;      // PWM设备句柄
+ *
+ * static int pwm_led_sample(int argc, char *argv[])
+ * {
+ *     rt_uint32_t period, pulse, dir;
+ *
+ *     period = 500000;    // 周期为0.5ms，单位为纳秒ns
+ *     dir = 1;            // PWM脉冲宽度值的增减方向
+ *     pulse = 0;          // PWM脉冲宽度值，单位为纳秒ns
+ *
+ *     // 查找设备
+ *     pwm_dev = (struct rt_device_pwm *)rt_device_find(PWM_DEV_NAME);
+ *     if (pwm_dev == RT_NULL)
+ *     {
+ *         rt_kprintf("pwm sample run failed! can't find %s device!\n", PWM_DEV_NAME);
+ *         return -RT_ERROR;
+ *     }
+ *
+ *     // 设置PWM周期和脉冲宽度默认值
+ *     rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse);
+ *     // 使能设备
+ *     rt_pwm_enable(pwm_dev, PWM_DEV_CHANNEL);
+ *
+ *     while (1)
+ *     {
+ *         rt_thread_mdelay(50);
+ *         if (dir)
+ *         {
+ *             pulse += 5000;      // 从0值开始每次增加5000ns
+ *         }
+ *         else
+ *         {
+ *             pulse -= 5000;      // 从最大值开始每次减少5000ns
+ *         }
+ *         if (pulse >= period)
+ *         {
+ *             dir = 0;
+ *         }
+ *         if (0 == pulse)
+ *         {
+ *             dir = 1;
+ *         }
+ *
+ *         // 设置PWM周期和脉冲宽度
+ *         rt_pwm_set(pwm_dev, PWM_DEV_CHANNEL, period, pulse);
+ *     }
+ * }
+ *
+ * MSH_CMD_EXPORT(pwm_led_sample, pwm sample);
+ * @endcode
+ *
+ * @ingroup     Drivers
+ */
 
+/*!
+ * @addtogroup PWM
+ * @{
+ */
 #define PWM_CMD_ENABLE      (RT_DEVICE_CTRL_BASE(PWM) + 0)
 #define PWM_CMD_DISABLE     (RT_DEVICE_CTRL_BASE(PWM) + 1)
 #define PWM_CMD_SET         (RT_DEVICE_CTRL_BASE(PWM) + 2)
@@ -27,6 +98,9 @@
 #define PWM_CMD_ENABLE_IRQ  (RT_DEVICE_CTRL_BASE(PWM) + 10)
 #define PWM_CMD_DISABLE_IRQ  (RT_DEVICE_CTRL_BASE(PWM) + 11)
 
+/**
+ * @brief PWM configuration
+ */
 struct rt_pwm_configuration
 {
     rt_uint32_t channel; /* 0 ~ n or 0 ~ -n, which depends on specific MCU requirements */
@@ -42,25 +116,94 @@ struct rt_pwm_configuration
 };
 
 struct rt_device_pwm;
+/**
+ * @brief PWM operations
+ */
 struct rt_pwm_ops
 {
     rt_err_t (*control)(struct rt_device_pwm *device, int cmd, void *arg);
 };
 
+/**
+ * @brief PWM device
+ */
 struct rt_device_pwm
 {
     struct rt_device parent;
     const struct rt_pwm_ops *ops;
 };
-
+/**
+ * @brief register a PWM device
+ * @param device the PWM device
+ * @param name the name of PWM device
+ * @param ops the operations of PWM device
+ * @param user_data the user data of PWM device
+ * @return rt_err_t error code
+ */
 rt_err_t rt_device_pwm_register(struct rt_device_pwm *device, const char *name, const struct rt_pwm_ops *ops, const void *user_data);
 
+/**
+ * @brief enable the PWM channel
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @return rt_err_t error code
+ */
 rt_err_t rt_pwm_enable(struct rt_device_pwm *device, int channel);
+
+/**
+ * @brief disable the PWM channel
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @return rt_err_t error code
+ */
 rt_err_t rt_pwm_disable(struct rt_device_pwm *device, int channel);
+
+/**
+ * @brief set the PWM channel
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @param period the period of PWM
+ * @param pulse the pulse of PWM
+ * @return rt_err_t error code
+ */
 rt_err_t rt_pwm_set(struct rt_device_pwm *device, int channel, rt_uint32_t period, rt_uint32_t pulse);
+
+/**
+ * @brief set the PWM channel period
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @param period the period of PWM
+ * @return rt_err_t error code
+*/
 rt_err_t rt_pwm_set_period(struct rt_device_pwm *device, int channel, rt_uint32_t period);
+
+/**
+ * @brief set the PWM channel pulse
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @param pulse the period of PWM
+ * @return rt_err_t error code
+*/
 rt_err_t rt_pwm_set_pulse(struct rt_device_pwm *device, int channel, rt_uint32_t pulse);
+
+/**
+ * @brief set the dead zone time of PWM
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @param dead_time dead zone time
+ * @return rt_err_t error code
+*/
 rt_err_t rt_pwm_set_dead_time(struct rt_device_pwm *device, int channel, rt_uint32_t dead_time);
+
+/**
+ * @brief set the phase of PWM
+ * @param device the PWM device
+ * @param channel the channel of PWM
+ * @param phase phase
+ * @return rt_err_t error code
+*/
 rt_err_t rt_pwm_set_phase(struct rt_device_pwm *device, int channel, rt_uint32_t phase);
 
+/*! @}*/
+
 #endif /* __DEV_PWM_H__ */

components/drivers/include/drivers/dev_spi.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -16,7 +16,80 @@
 #include <stdlib.h>
 #include <rtthread.h>
 #include <drivers/dev_pin.h>
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    SPI              SPI
+ *
+ * @brief       SPI driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * #include <rtthread.h>
+ * #include <rtdevice.h>
+ *
+ * #define W25Q_SPI_DEVICE_NAME     "qspi10"
+ *
+ * static void spi_w25q_sample(int argc, char *argv[])
+ * {
+ *     struct rt_spi_device *spi_dev_w25q;
+ *     char name[RT_NAME_MAX];
+ *     rt_uint8_t w25x_read_id = 0x90;
+ *     rt_uint8_t id[5] = {0};
+ *
+ *     if (argc == 2)
+ *     {
+ *         rt_strncpy(name, argv[1], RT_NAME_MAX);
+ *     }
+ *     else
+ *     {
+ *         rt_strncpy(name, W25Q_SPI_DEVICE_NAME, RT_NAME_MAX);
+ *     }
+ *
+ *     // 查找 spi 设备获取设备句柄
+ *     spi_dev_w25q = (struct rt_spi_device *)rt_device_find(name);
+ *     if (!spi_dev_w25q)
+ *     {
+ *         rt_kprintf("spi sample run failed! can't find %s device!\n", name);
+ *     }
+ *     else
+ *     {
+ *         // 方式1：使用 rt_spi_send_then_recv()发送命令读取ID
+ *         rt_spi_send_then_recv(spi_dev_w25q, &w25x_read_id, 1, id, 5);
+ *         rt_kprintf("use rt_spi_send_then_recv() read w25q ID is:%x%x\n", id[3], id[4]);
+ *
+ *         // 方式2：使用 rt_spi_transfer_message()发送命令读取ID
+ *         struct rt_spi_message msg1, msg2;
+ *
+ *         msg1.send_buf   = &w25x_read_id;
+ *         msg1.recv_buf   = RT_NULL;
+ *         msg1.length     = 1;
+ *         msg1.cs_take    = 1;
+ *         msg1.cs_release = 0;
+ *         msg1.next       = &msg2;
+ *
+ *         msg2.send_buf   = RT_NULL;
+ *         msg2.recv_buf   = id;
+ *         msg2.length     = 5;
+ *         msg2.cs_take    = 0;
+ *         msg2.cs_release = 1;
+ *         msg2.next       = RT_NULL;
+ *
+ *         rt_spi_transfer_message(spi_dev_w25q, &msg1);
+ *         rt_kprintf("use rt_spi_transfer_message() read w25q ID is:%x%x\n", id[3], id[4]);
+ *
+ *     }
+ * }
+ * // 导出到 msh 命令列表中
+ * MSH_CMD_EXPORT(spi_w25q_sample, spi w25q sample);
+ * @endcode
+ *
+ * @ingroup     Drivers
+ */
 
+/*!
+ * @addtogroup SPI
+ * @{
+ */
 #ifdef __cplusplus
 extern "C"{
 #endif
@@ -33,32 +106,32 @@ extern "C"{
  *  - For CPHA=1, data are captured on clock's rising edge and data are propagated
  *    on a falling edge.
  */
-#define RT_SPI_CPHA     (1<<0)                             /* bit[0]:CPHA, clock phase */
-#define RT_SPI_CPOL     (1<<1)                             /* bit[1]:CPOL, clock polarity */
+#define RT_SPI_CPHA     (1<<0)                             /*!< bit[0]:CPHA, clock phase */
+#define RT_SPI_CPOL     (1<<1)                             /*!< bit[1]:CPOL, clock polarity */
 
-#define RT_SPI_LSB      (0<<2)                             /* bit[2]: 0-LSB */
-#define RT_SPI_MSB      (1<<2)                             /* bit[2]: 1-MSB */
+#define RT_SPI_LSB      (0<<2)                             /*!< bit[2]: 0-LSB */
+#define RT_SPI_MSB      (1<<2)                             /*!< bit[2]: 1-MSB */
 
-#define RT_SPI_MASTER   (0<<3)                             /* SPI master device */
-#define RT_SPI_SLAVE    (1<<3)                             /* SPI slave device */
+#define RT_SPI_MASTER   (0<<3)                             /*!< SPI master device */
+#define RT_SPI_SLAVE    (1<<3)                             /*!< SPI slave device */
 
-#define RT_SPI_CS_HIGH  (1<<4)                             /* Chipselect active high */
-#define RT_SPI_NO_CS    (1<<5)                             /* No chipselect */
-#define RT_SPI_3WIRE    (1<<6)                             /* SI/SO pin shared */
-#define RT_SPI_READY    (1<<7)                             /* Slave pulls low to pause */
+#define RT_SPI_CS_HIGH  (1<<4)                             /*!< Chipselect active high */
+#define RT_SPI_NO_CS    (1<<5)                             /*!< No chipselect */
+#define RT_SPI_3WIRE    (1<<6)                             /*!< SI/SO pin shared */
+#define RT_SPI_READY    (1<<7)                             /*!< Slave pulls low to pause */
 
 #define RT_SPI_MODE_MASK    (RT_SPI_CPHA | RT_SPI_CPOL | RT_SPI_MSB | RT_SPI_SLAVE | RT_SPI_CS_HIGH | RT_SPI_NO_CS | RT_SPI_3WIRE | RT_SPI_READY)
 
-#define RT_SPI_MODE_0       (0 | 0)                        /* CPOL = 0, CPHA = 0 */
-#define RT_SPI_MODE_1       (0 | RT_SPI_CPHA)              /* CPOL = 0, CPHA = 1 */
-#define RT_SPI_MODE_2       (RT_SPI_CPOL | 0)              /* CPOL = 1, CPHA = 0 */
-#define RT_SPI_MODE_3       (RT_SPI_CPOL | RT_SPI_CPHA)    /* CPOL = 1, CPHA = 1 */
+#define RT_SPI_MODE_0       (0 | 0)                        /*!< CPOL = 0, CPHA = 0 */
+#define RT_SPI_MODE_1       (0 | RT_SPI_CPHA)              /*!< CPOL = 0, CPHA = 1 */
+#define RT_SPI_MODE_2       (RT_SPI_CPOL | 0)              /*!< CPOL = 1, CPHA = 0 */
+#define RT_SPI_MODE_3       (RT_SPI_CPOL | RT_SPI_CPHA)    /*!< CPOL = 1, CPHA = 1 */
 
 #define RT_SPI_BUS_MODE_SPI         (1<<0)
 #define RT_SPI_BUS_MODE_QSPI        (1<<1)
 
 /**
- * SPI message structure
+ * @brief SPI message structure
  */
 struct rt_spi_message
 {
@@ -72,7 +145,7 @@ struct rt_spi_message
 };
 
 /**
- * SPI configuration structure
+ * @brief SPI configuration structure
  */
 struct rt_spi_configuration
 {
@@ -84,6 +157,10 @@ struct rt_spi_configuration
 };
 
 struct rt_spi_ops;
+
+/**
+ * @brief SPI bus structure
+ */
 struct rt_spi_bus
 {
     struct rt_device parent;
@@ -95,7 +172,7 @@ struct rt_spi_bus
 };
 
 /**
- * SPI operators
+ * @brief SPI operators
  */
 struct rt_spi_ops
 {
@@ -104,7 +181,7 @@ struct rt_spi_ops
 };
 
 /**
- * SPI Virtual BUS, one device must connected to a virtual BUS
+ * @brief SPI Virtual BUS, one device must connected to a virtual BUS
  */
 struct rt_spi_device
 {
@@ -116,6 +193,9 @@ struct rt_spi_device
     void   *user_data;
 };
 
+/**
+ * @brief QSPI message structure
+ */
 struct rt_qspi_message
 {
     struct rt_spi_message parent;
@@ -142,6 +222,9 @@ struct rt_qspi_message
     rt_uint8_t qspi_data_lines;
 };
 
+/**
+ * @brief QSPI configuration structure
+ */
 struct rt_qspi_configuration
 {
     struct rt_spi_configuration parent;
@@ -153,6 +236,9 @@ struct rt_qspi_configuration
     rt_uint8_t qspi_dl_width ;
 };
 
+/**
+ * @brief QSPI operators
+ */
 struct rt_qspi_device
 {
     struct rt_spi_device parent;
@@ -166,18 +252,47 @@ struct rt_qspi_device
 
 #define SPI_DEVICE(dev) ((struct rt_spi_device *)(dev))
 
-/* register a SPI bus */
+/**
+ * @brief register a SPI bus
+ *
+ * @param bus the SPI bus
+ * @param name the name of SPI bus
+ * @param ops the operations of SPI bus
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_spi_bus_register(struct rt_spi_bus       *bus,
                              const char              *name,
                              const struct rt_spi_ops *ops);
 
-/* attach a device on SPI bus */
+
+/**
+ * @brief attach a device on SPI bus
+ *
+ * @param device the SPI device
+ * @param name the name of SPI device
+ * @param bus_name the name of SPI bus
+ * @param user_data the user data of SPI device
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_spi_bus_attach_device(struct rt_spi_device *device,
                                   const char           *name,
                                   const char           *bus_name,
                                   void                 *user_data);
 
-/* attach a device on SPI bus with CS pin */
+
+/**
+ * @brief attach a device on SPI bus with CS pin
+ *
+ * @param device the SPI device
+ * @param name the name of SPI device
+ * @param bus_name the name of SPI bus
+ * @param cs_pin the CS pin of SPI device
+ * @param user_data the user data of SPI device
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_spi_bus_attach_device_cspin(struct rt_spi_device *device,
                                         const char           *name,
                                         const char           *bus_name,
@@ -186,6 +301,7 @@ rt_err_t rt_spi_bus_attach_device_cspin(struct rt_spi_device *device,
 
 /**
  * @brief  Reconfigure the SPI bus for the specified device.
+ *
  * @param  device: Pointer to the SPI device attached to the SPI bus.
  * @retval RT_EOK if the SPI device was successfully released and the bus was configured.
  *         RT_EBUSY if the SPI bus is currently in use; the new configuration will take effect once the device releases the bus.
@@ -200,7 +316,7 @@ rt_err_t rt_spi_bus_attach_device_cspin(struct rt_spi_device *device,
 rt_err_t rt_spi_bus_configure(struct rt_spi_device *device);
 
 /**
- * This function takes SPI bus.
+ * @brief This function takes SPI bus.
  *
  * @param device the SPI device attached to SPI bus
  *
@@ -209,7 +325,7 @@ rt_err_t rt_spi_bus_configure(struct rt_spi_device *device);
 rt_err_t rt_spi_take_bus(struct rt_spi_device *device);
 
 /**
- * This function releases SPI bus.
+ * @brief This function releases SPI bus.
  *
  * @param device the SPI device attached to SPI bus
  *
@@ -218,7 +334,7 @@ rt_err_t rt_spi_take_bus(struct rt_spi_device *device);
 rt_err_t rt_spi_release_bus(struct rt_spi_device *device);
 
 /**
- * This function take SPI device (takes CS of SPI device).
+ * @brief This function take SPI device (takes CS of SPI device).
  *
  * @param device the SPI device attached to SPI bus
  *
@@ -227,7 +343,7 @@ rt_err_t rt_spi_release_bus(struct rt_spi_device *device);
 rt_err_t rt_spi_take(struct rt_spi_device *device);
 
 /**
- * This function releases SPI device (releases CS of SPI device).
+ * @brief This function releases SPI device (releases CS of SPI device).
  *
  * @param device the SPI device attached to SPI bus
  *
@@ -237,8 +353,10 @@ rt_err_t rt_spi_release(struct rt_spi_device *device);
 
 /**
  * @brief  This function can set configuration on SPI device.
+ *
  * @param  device: the SPI device attached to SPI bus
  * @param  cfg: the configuration pointer.
+ *
  * @retval RT_EOK on release SPI device successfully.
  *         RT_EBUSY is not an error condition and the configuration will take effect once the device has the bus
  *         others on taken SPI bus failed.
@@ -246,13 +364,35 @@ rt_err_t rt_spi_release(struct rt_spi_device *device);
 rt_err_t rt_spi_configure(struct rt_spi_device        *device,
                           struct rt_spi_configuration *cfg);
 
-/* send data then receive data from SPI device */
+
+/**
+ * @brief This function can send data then receive data from SPI device.
+ *
+ * @param device the SPI device attached to SPI bus
+ * @param send_buf the buffer to be transmitted to SPI device.
+ * @param send_length the number of data to be transmitted.
+ * @param recv_buf the buffer to be recivied from SPI device.
+ * @param recv_length the data to be recivied.
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_spi_send_then_recv(struct rt_spi_device *device,
                                const void           *send_buf,
                                rt_size_t             send_length,
                                void                 *recv_buf,
                                rt_size_t             recv_length);
 
+/**
+ * @brief This function can send data then send data from SPI device.
+ *
+ * @param device the SPI device attached to SPI bus
+ * @param send_buf1 the buffer to be transmitted to SPI device.
+ * @param send_length1 the number of data to be transmitted.
+ * @param send_buf2 the buffer to be transmitted to SPI device.
+ * @param send_length2 the number of data to be transmitted.
+ *
+ * @return the status of transmit.
+ */
 rt_err_t rt_spi_send_then_send(struct rt_spi_device *device,
                                const void           *send_buf1,
                                rt_size_t             send_length1,
@@ -260,7 +400,7 @@ rt_err_t rt_spi_send_then_send(struct rt_spi_device *device,
                                rt_size_t             send_length2);
 
 /**
- * This function transmits data to SPI device.
+ * @brief This function transmits data to SPI device.
  *
  * @param device the SPI device attached to SPI bus
  * @param send_buf the buffer to be transmitted to SPI device.
@@ -274,16 +414,34 @@ rt_ssize_t rt_spi_transfer(struct rt_spi_device *device,
                            void                 *recv_buf,
                            rt_size_t             length);
 
+/**
+ * @brief The SPI device transmits 8 bytes of data
+ *
+ * @param device the SPI device attached to SPI bus
+ * @param senddata send data buffer
+ * @param recvdata receive data buffer
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_spi_sendrecv8(struct rt_spi_device *device,
                           rt_uint8_t            senddata,
                           rt_uint8_t           *recvdata);
 
+/**
+ * @brief The SPI device transmits 16 bytes of data
+ *
+ * @param device the SPI device attached to SPI bus
+ * @param senddata send data buffer
+ * @param recvdata receive data buffer
+ *
+ * @return rt_err_t error code
+ */
 rt_err_t rt_spi_sendrecv16(struct rt_spi_device *device,
                            rt_uint16_t           senddata,
                            rt_uint16_t          *recvdata);
 
 /**
- * This function transfers a message list to the SPI device.
+ * @brief This function transfers a message list to the SPI device.
  *
  * @param device the SPI device attached to SPI bus
  * @param message the message list to be transmitted to SPI device
@@ -294,6 +452,15 @@ rt_err_t rt_spi_sendrecv16(struct rt_spi_device *device,
 struct rt_spi_message *rt_spi_transfer_message(struct rt_spi_device  *device,
                                                struct rt_spi_message *message);
 
+/**
+ * @brief This function receives data from SPI device.
+ *
+ * @param device the SPI device attached to SPI bus
+ * @param recv_buf the buffer to be recivied from SPI device.
+ * @param length the data to be recivied.
+ *
+ * @return the actual length of received.
+*/
 rt_inline rt_size_t rt_spi_recv(struct rt_spi_device *device,
                                 void                 *recv_buf,
                                 rt_size_t             length)
@@ -301,6 +468,15 @@ rt_inline rt_size_t rt_spi_recv(struct rt_spi_device *device,
     return rt_spi_transfer(device, RT_NULL, recv_buf, length);
 }
 
+/**
+ * @brief This function sends data to SPI device.
+ *
+ * @param device the SPI device attached to SPI bus
+ * @param send_buf the buffer to be transmitted to SPI device.
+ * @param length the number of data to be transmitted.
+ *
+ * @return the actual length of send.
+ */
 rt_inline rt_size_t rt_spi_send(struct rt_spi_device *device,
                                 const void           *send_buf,
                                 rt_size_t             length)
@@ -309,7 +485,7 @@ rt_inline rt_size_t rt_spi_send(struct rt_spi_device *device,
 }
 
 /**
- * This function appends a message to the SPI message list.
+ * @brief This function appends a message to the SPI message list.
  *
  * @param list the SPI message list header.
  * @param message the message pointer to be appended to the message list.
@@ -331,7 +507,7 @@ rt_inline void rt_spi_message_append(struct rt_spi_message *list,
 }
 
 /**
- * This function can set configuration on QSPI device.
+ * @brief This function can set configuration on QSPI device.
  *
  * @param device the QSPI device attached to QSPI bus.
  * @param cfg the configuration pointer.
@@ -341,7 +517,7 @@ rt_inline void rt_spi_message_append(struct rt_spi_message *list,
 rt_err_t rt_qspi_configure(struct rt_qspi_device *device, struct rt_qspi_configuration *cfg);
 
 /**
- * This function can register a SPI bus for QSPI mode.
+ * @brief This function can register a SPI bus for QSPI mode.
  *
  * @param bus the SPI bus for QSPI mode.
  * @param name The name of the spi bus.
@@ -352,7 +528,7 @@ rt_err_t rt_qspi_configure(struct rt_qspi_device *device, struct rt_qspi_configu
 rt_err_t rt_qspi_bus_register(struct rt_spi_bus *bus, const char *name, const struct rt_spi_ops *ops);
 
 /**
- * This function transmits data to QSPI device.
+ * @brief This function transmits data to QSPI device.
  *
  * @param device the QSPI device attached to QSPI bus.
  * @param message the message pointer.
@@ -362,7 +538,7 @@ rt_err_t rt_qspi_bus_register(struct rt_spi_bus *bus, const char *name, const st
 rt_size_t rt_qspi_transfer_message(struct rt_qspi_device  *device, struct rt_qspi_message *message);
 
 /**
- * This function can send data then receive data from QSPI device
+ * @brief This function can send data then receive data from QSPI device
  *
  * @param device the QSPI device attached to QSPI bus.
  * @param send_buf the buffer to be transmitted to QSPI device.
@@ -375,7 +551,7 @@ rt_size_t rt_qspi_transfer_message(struct rt_qspi_device  *device, struct rt_qsp
 rt_err_t rt_qspi_send_then_recv(struct rt_qspi_device *device, const void *send_buf, rt_size_t send_length,void *recv_buf, rt_size_t recv_length);
 
 /**
- * This function can send data to QSPI device
+ * @brief This function can send data to QSPI device
  *
  * @param device the QSPI device attached to QSPI bus.
  * @param send_buf the buffer to be transmitted to QSPI device.
@@ -389,4 +565,6 @@ rt_err_t rt_qspi_send(struct rt_qspi_device *device, const void *send_buf, rt_si
 }
 #endif
 
+/*! @}*/
+
 #endif

components/drivers/include/drivers/dev_touch.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2024 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -13,7 +13,112 @@
 
 #include <rtthread.h>
 #include "dev_pin.h"
+/**
+ * @addtogroup  Drivers          RTTHREAD Driver
+ * @defgroup    Touch            Touch
+ *
+ * @brief       Touch driver api
+ *
+ * <b>Example</b>
+ * @code {.c}
+ * #include <rtthread.h>
+ * #include "rtdevice.h"
+ *
+ * static rt_thread_t  gt9147_thread = RT_NULL;
+ * static rt_sem_t     gt9147_sem = RT_NULL;
+ * static rt_device_t  dev = RT_NULL;
+ * static struct       rt_touch_data *read_data;
+ *
+ * // 读取数据线程入口函数
+ * static void gt9147_entry(void *parameter)
+ * {
+ *     struct rt_touch_data *read_data;
+ *     read_data = (struct rt_touch_data *)rt_malloc(sizeof(struct rt_touch_data) * 5);
+ *
+ *     while (1)
+ *     {
+ *         // 请求信号量
+ *         rt_sem_take(gt9147_sem, RT_WAITING_FOREVER);
+ *         // 读取五个点的触摸信息
+ *         if (rt_device_read(dev, 0, read_data, 5) == 5)
+ *         {
+ *             for (rt_uint8_t i = 0; i < 5; i++)
+ *             {
+ *                 if (read_data[i].event == RT_TOUCH_EVENT_DOWN || read_data[i].event == RT_TOUCH_EVENT_MOVE)
+ *                 {
+ *                     rt_kprintf("%d %d %d %d %d\n",
+ *                                 read_data[i].track_id,
+ *                                 read_data[i].x_coordinate,
+ *                                 read_data[i].y_coordinate,
+ *                                 read_data[i].timestamp,
+ *                                 read_data[i].width);
+ *                 }
+ *             }
+ *         }
+ *         // 打开中断
+ *         rt_device_control(dev, RT_TOUCH_CTRL_ENABLE_INT, RT_NULL);
+ *     }
+ * }
+ *
+ * // 接收回调函数
+ * static rt_err_t rx_callback(rt_device_t dev, rt_size_t size)
+ * {
+ *     // 关闭中断
+ *     rt_device_control(dev, RT_TOUCH_CTRL_DISABLE_INT, RT_NULL);
+ *     // 释放信号量
+ *     rt_sem_release(gt9147_sem);
+ *     return 0;
+ * }
+ *
+ * static int gt9147_sample(void)
+ * {
+ *     // 查找 Touch 设备
+ *     dev = rt_device_find("touch");
+ *
+ *     if (dev == RT_NULL)
+ *     {
+ *         rt_kprintf("can't find device:%s\n", "touch");
+ *         return -1;
+ *     }
+ *     // 以中断的方式打开设备
+ *     if (rt_device_open(dev, RT_DEVICE_FLAG_INT_RX) != RT_EOK)
+ *     {
+ *         rt_kprintf("open device failed!");
+ *         return -1;
+ *     }
+ *     // 设置接收回调
+ *     rt_device_set_rx_indicate(dev, rx_callback);
+ *     // 创建信号量
+ *     gt9147_sem = rt_sem_create("dsem", 0, RT_IPC_FLAG_PRIO);
+ *
+ *     if (gt9147_sem == RT_NULL)
+ *     {
+ *         rt_kprintf("create dynamic semaphore failed.\n");
+ *         return -1;
+ *     }
+ *     // 创建读取数据线程
+ *     gt9147_thread = rt_thread_create("thread1",
+ *                                      gt9147_entry,
+ *                                      RT_NULL,
+ *                                      THREAD_STACK_SIZE,
+ *                                      THREAD_PRIORITY,
+ *                                      THREAD_TIMESLICE);
+ *     // 启动线程
+ *     if (gt9147_thread != RT_NULL)
+ *         rt_thread_startup(gt9147_thread);
+ *
+ *     return 0;
+ * }
+ * MSH_CMD_EXPORT(gt9147_sample, gt9147 sample);
+ * @endcode
+ *
+ * @ingroup     Drivers
+ */
 
+/*!
+ * @addtogroup Touch
+ * @{
+ */
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -53,6 +158,9 @@ extern "C" {
 #define RT_TOUCH_EVENT_DOWN              (2)   /* Touch down event */
 #define RT_TOUCH_EVENT_MOVE              (3)   /* Touch move event */
 
+/**
+ * @brief Touch information
+*/
 struct rt_touch_info
 {
     rt_uint8_t     type;                       /* The touch type */
@@ -62,6 +170,9 @@ struct rt_touch_info
     rt_int32_t     range_y;                    /* Y coordinate range */
 };
 
+/**
+ * @brief Touch configuration
+*/
 struct rt_touch_config
 {
 #ifdef RT_TOUCH_PIN_IRQ
@@ -72,6 +183,9 @@ struct rt_touch_config
 };
 
 typedef struct rt_touch_device *rt_touch_t;
+/**
+ * @brief Touch device
+*/
 struct rt_touch_device
 {
     struct rt_device            parent;        /* The standard device */
@@ -82,6 +196,9 @@ struct rt_touch_device
     rt_err_t (*irq_handle)(rt_touch_t touch);  /* Called when an interrupt is generated, registered by the driver */
 };
 
+/**
+ * @brief Touch data
+*/
 struct rt_touch_data
 {
     rt_uint8_t          event;                 /* The touch event of the data */
@@ -92,22 +209,40 @@ struct rt_touch_data
     rt_tick_t           timestamp;             /* The timestamp when the data was received */
 };
 
+/**
+ * @brief Touch device operations
+*/
 struct rt_touch_ops
 {
     rt_size_t (*touch_readpoint)(struct rt_touch_device *touch, void *buf, rt_size_t touch_num);
     rt_err_t (*touch_control)(struct rt_touch_device *touch, int cmd, void *arg);
 };
 
+/**
+ * @brief register a touch device
+ * @param touch the touch device
+ * @param name the name of touch device
+ * @param flag the flag of touch device
+ * @param data the user data of touch device
+ * @return rt_err_t error code
+ */
 int rt_hw_touch_register(rt_touch_t    touch,
                          const char    *name,
                          rt_uint32_t   flag,
                          void          *data);
 
-/* if you doesn't use pin device. you must call this function in your touch irq callback */
+/**
+ * @brief Touch irq handle
+ * @param touch the touch device
+ *
+ * @note If you doesn't use pin device. you must call this function in your touch irq callback
+ */
 void rt_hw_touch_isr(rt_touch_t touch);
 
 #ifdef __cplusplus
 }
 #endif
 
+/*! @}*/
+
 #endif /* __DEV_TOUCH_H__ */