From 2053a3d21f1bb6b5d692c771f40e058919b8502e Mon Sep 17 00:00:00 2001 From: Supper Thomas <78900636@qq.com> Date: Sat, 14 Sep 2024 15:16:00 +0800 Subject: [PATCH 1/3] [doxygen] add driver example for doxygen --- .github/workflows/doxygen.yml | 18 +- components/drivers/include/drivers/dev_can.h | 18 +- .../drivers/include/drivers/dev_serial.h | 131 +++++++++++++- .../drivers/include/drivers/dev_serial_v2.h | 168 +++++++++++++++++- components/finsh/finsh.h | 21 +-- 5 files changed, 315 insertions(+), 41 deletions(-) diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 447c66634c8..a4580be1be1 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -3,27 +3,13 @@ on: # Runs at 16:00 UTC (BeiJing 00:00) on the 30st of every month schedule: - cron: '0 16 30 * *' - push: - branches: - - master - paths-ignore: - - '**/README.md' - - '**/README_zh.md' - pull_request: - branches: - - master - paths-ignore: - - bsp/** - - examples/** - - .github/** - - '**/README.md' - - '**/README_zh.md' + workflow_dispatch: jobs: build: runs-on: ubuntu-latest name: doxygen_doc generate - if: github.repository_owner == 'RT-Thread' && false + if: github.repository_owner == 'RT-Thread' steps: - uses: actions/checkout@v4 with: diff --git a/components/drivers/include/drivers/dev_can.h b/components/drivers/include/drivers/dev_can.h index 9f2d7c06778..6881d5d613a 100644 --- a/components/drivers/include/drivers/dev_can.h +++ b/components/drivers/include/drivers/dev_can.h @@ -63,9 +63,16 @@ enum CANBAUD #define RT_CAN_MODE_PRIV 0x01 #define RT_CAN_MODE_NOPRIV 0x00 -/** @defgroup CAN_receive_FIFO_number CAN Receive FIFO Number - * @{ - */ +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup CAN_Device CAN Driver + * @ingroup Drivers + */ + +/*! + * @addtogroup CAN_Device + * @{ + */ #define CAN_RX_FIFO0 (0x00000000U) /*!< CAN receive FIFO 0 */ #define CAN_RX_FIFO1 (0x00000001U) /*!< CAN receive FIFO 1 */ @@ -360,5 +367,8 @@ rt_err_t rt_hw_can_register(struct rt_can_device *can, const struct rt_can_ops *ops, void *data); void rt_hw_can_isr(struct rt_can_device *can, int event); -#endif /*__DEV_CAN_H*/ +/*! @} +*/ + +#endif /*__DEV_CAN_H*/ \ No newline at end of file diff --git a/components/drivers/include/drivers/dev_serial.h b/components/drivers/include/drivers/dev_serial.h index 418c25fa1d9..02bb3ffdb0f 100644 --- a/components/drivers/include/drivers/dev_serial.h +++ b/components/drivers/include/drivers/dev_serial.h @@ -15,7 +15,105 @@ #define __DEV_SERIAL_H__ #include +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup Serial Serial + * + * @brief Serial driver api + * + * Example + * @code {.c} + * + * #include + * + * #define SAMPLE_UART_NAME "uart2" + * static struct rt_semaphore rx_sem; + * static rt_device_t serial; + * + * static rt_err_t uart_input(rt_device_t dev, rt_size_t size) + * { + * + * rt_sem_release(&rx_sem); + * + * return RT_EOK; + * } + * + * static void serial_thread_entry(void *parameter) + * { + * char ch; + * + * while (1) + * { + * + * while (rt_device_read(serial, -1, &ch, 1) != 1) + * { + * + * rt_sem_take(&rx_sem, RT_WAITING_FOREVER); + * } + * + * ch = ch + 1; + * rt_device_write(serial, 0, &ch, 1); + * } + * } + * + * static int uart_sample(int argc, char *argv[]) + * { + * rt_err_t ret = RT_EOK; + * char uart_name[RT_NAME_MAX]; + * char str[] = "hello RT-Thread!\r\n"; + * + * if (argc == 2) + * { + * rt_strncpy(uart_name, argv[1], RT_NAME_MAX); + * } + * else + * { + * rt_strncpy(uart_name, SAMPLE_UART_NAME, RT_NAME_MAX); + * } + * + * + * serial = rt_device_find(uart_name); + * if (!serial) + * { + * rt_kprintf("find %s failed!\n", uart_name); + * return RT_ERROR; + * } + * + * + * rt_sem_init(&rx_sem, "rx_sem", 0, RT_IPC_FLAG_FIFO); + * + * rt_device_open(serial, RT_DEVICE_FLAG_INT_RX); + * + * rt_device_set_rx_indicate(serial, uart_input); + * + * rt_device_write(serial, 0, str, (sizeof(str) - 1)); + * + * + * rt_thread_t thread = rt_thread_create("serial", serial_thread_entry, RT_NULL, 1024, 25, 10); + * + * if (thread != RT_NULL) + * { + * rt_thread_startup(thread); + * } + * else + * { + * ret = RT_ERROR; + * } + * + * return ret; + * } + * + * MSH_CMD_EXPORT(uart_sample, uart device sample); + * @endcode + * + * @ingroup Drivers + */ + +/*! + * @addtogroup Serial + * @{ + */ #define BAUD_RATE_2400 2400 #define BAUD_RATE_4800 4800 #define BAUD_RATE_9600 9600 @@ -104,8 +202,7 @@ /** * @brief Sets a hook function when RX indicate is called - * - * @param thread is the target thread that initializing + * */ typedef void (*rt_hw_serial_rxind_hookproto_t)(rt_device_t dev, rt_size_t size); RT_OBJECT_HOOKLIST_DECLARE(rt_hw_serial_rxind_hookproto_t, rt_hw_serial_rxind); @@ -173,7 +270,7 @@ struct rt_serial_device typedef struct rt_serial_device rt_serial_t; /** - * uart operators + * @brief Configure the serial device */ struct rt_uart_ops { @@ -186,13 +283,41 @@ struct rt_uart_ops rt_ssize_t (*dma_transmit)(struct rt_serial_device *serial, rt_uint8_t *buf, rt_size_t size, int direction); }; +/** + * @brief Serial interrupt service routine + * @param serial serial device + * @param event event mask + * @ingroup Serial + */ void rt_hw_serial_isr(struct rt_serial_device *serial, int event); +/** + * @brief Register a serial device to device list + * + * @param serial serial device + * @param name device name + * @param flag device flag + * @param data device private data + * @return rt_err_t error code + * @note This function will register a serial device to system device list, + * and add a device object to system object list. + * @ingroup Serial + */ rt_err_t rt_hw_serial_register(struct rt_serial_device *serial, const char *name, rt_uint32_t flag, void *data); +/** + * @brief register a serial device to system device list and add a device object to system object list + * + * @param serial serial device + * @return rt_err_t error code + * + * @ingroup Serial + */ rt_err_t rt_hw_serial_register_tty(struct rt_serial_device *serial); +/*! @}*/ + #endif diff --git a/components/drivers/include/drivers/dev_serial_v2.h b/components/drivers/include/drivers/dev_serial_v2.h index 0c3d095ab31..0bdc51b7baf 100644 --- a/components/drivers/include/drivers/dev_serial_v2.h +++ b/components/drivers/include/drivers/dev_serial_v2.h @@ -13,6 +13,122 @@ #include + +/** + * @addtogroup Drivers RTTHREAD Driver + * @defgroup Serial_v2 Serial v2 + * + * @brief Serial v2 driver api + * + * Example + * @code {.c} + * + * #include + * #include + * + * #define SAMPLE_UART_NAME "uart1" + * + * struct rx_msg + * { + * rt_device_t dev; + * rt_size_t size; + * }; + * static rt_device_t serial; + * static struct rt_messagequeue rx_mq; + * + * static rt_err_t uart_input(rt_device_t dev, rt_size_t size) + * { + * struct rx_msg msg; + * rt_err_t result; + * msg.dev = dev; + * msg.size = size; + * + * result = rt_mq_send(&rx_mq, &msg, sizeof(msg)); + * if (result == -RT_EFULL) + * { + * rt_kprintf("message queue full！\n"); + * } + * return result; + * } + * + * static void serial_thread_entry(void *parameter) + * { + * struct rx_msg msg; + * rt_err_t result; + * rt_uint32_t rx_length; + * static char rx_buffer[BSP_UART1_RX_BUFSIZE + 1]; + * + * while (1) + * { + * rt_memset(&msg, 0, sizeof(msg)); + * result = rt_mq_recv(&rx_mq, &msg, sizeof(msg), RT_WAITING_FOREVER); + * if (result > 0) + * { + * rx_length = rt_device_read(msg.dev, 0, rx_buffer, msg.size); + * rx_buffer[rx_length] = '\0'; + * rt_device_write(serial, 0, rx_buffer, rx_length); + * rt_kprintf("%s\n",rx_buffer); + * } + * } + * } + * + * static int uart_dma_sample(int argc, char *argv[]) + * { + * rt_err_t ret = RT_EOK; + * char uart_name[RT_NAME_MAX]; + * static char msg_pool[256]; + * char str[] = "hello RT-Thread!\r\n"; + * + * if (argc == 2) + * { + * rt_strncpy(uart_name, argv[1], RT_NAME_MAX); + * } + * else + * { + * rt_strncpy(uart_name, SAMPLE_UART_NAME, RT_NAME_MAX); + * } + * + * serial = rt_device_find(uart_name); + * if (!serial) + * { + * rt_kprintf("find %s failed!\n", uart_name); + * return RT_ERROR; + * } + * + * rt_mq_init(&rx_mq, "rx_mq", + * msg_pool, + * sizeof(struct rx_msg), + * sizeof(msg_pool), + * RT_IPC_FLAG_FIFO); + * + * rt_device_open(serial, RT_DEVICE_FLAG_RX_NON_BLOCKING | RT_DEVICE_FLAG_TX_BLOCKING); + * rt_device_set_rx_indicate(serial, uart_input); + * rt_device_write(serial, 0, str, (sizeof(str) - 1)); + * + * rt_thread_t thread = rt_thread_create("serial", serial_thread_entry, RT_NULL, 1024, 25, 10); + * if (thread != RT_NULL) + * { + * rt_thread_startup(thread); + * } + * else + * { + * ret = RT_ERROR; + * } + * + * return ret; + * } + * MSH_CMD_EXPORT(uart_dma_sample, uart device dma sample); + * @endcode + * + * @ingroup Drivers + */ + + +/*! + * @addtogroup Serial_v2 + * @{ + */ + #define BAUD_RATE_2400 2400 #define BAUD_RATE_4800 4800 #define BAUD_RATE_9600 9600 @@ -104,9 +220,8 @@ } /** - * @brief Sets a hook function when RX indicate is called - * - * @param thread is the target thread that initializing + * @brief Serial receive indicate hook function type + * */ typedef void (*rt_hw_serial_rxind_hookproto_t)(rt_device_t dev, rt_size_t size); RT_OBJECT_HOOKLIST_DECLARE(rt_hw_serial_rxind_hookproto_t, rt_hw_serial_rxind); @@ -126,8 +241,8 @@ struct serial_configure rt_uint32_t reserved :5; }; -/* - * Serial Receive FIFO mode +/** + * @brief Serial Receive FIFO mode */ struct rt_serial_rx_fifo { @@ -141,8 +256,9 @@ struct rt_serial_rx_fifo rt_uint8_t buffer[]; }; -/* - * Serial Transmit FIFO mode +/** + * @brief Serial Transmit FIFO mode + * */ struct rt_serial_tx_fifo { @@ -158,6 +274,10 @@ struct rt_serial_tx_fifo rt_uint8_t buffer[]; }; +/** + * @brief serial device structure + * + */ struct rt_serial_device { struct rt_device parent; @@ -172,7 +292,8 @@ struct rt_serial_device }; /** - * uart operators + * @brief uart device operations + * */ struct rt_uart_ops { @@ -192,12 +313,43 @@ struct rt_uart_ops rt_uint32_t tx_flag); }; +/** + * @brief Serial interrupt service routine + * @param serial serial device + * @param event event mask + * @ingroup Serial_v2 + */ void rt_hw_serial_isr(struct rt_serial_device *serial, int event); + +/** + * @brief Register a serial device to device list + * + * @param serial serial device + * @param name device name + * @param flag device flag + * @param data device private data + * @return rt_err_t error code + * @note This function will register a serial device to system device list, + * and add a device object to system object list. + * @ingroup Serial_v2 + */ rt_err_t rt_hw_serial_register(struct rt_serial_device *serial, const char *name, rt_uint32_t flag, void *data); +/** + * @brief register a serial device to system device list and add a device object to system object list + * + * @param serial serial device + * @return rt_err_t error code + * + * @ingroup Serial_v2 + */ rt_err_t rt_hw_serial_register_tty(struct rt_serial_device *serial); + + +/*! @}*/ + #endif diff --git a/components/finsh/finsh.h b/components/finsh/finsh.h index 9fe36fae5a2..530ab9baae7 100644 --- a/components/finsh/finsh.h +++ b/components/finsh/finsh.h @@ -130,13 +130,13 @@ typedef long (*syscall_func)(void); #define FINSH_FUNCTION_EXPORT_ALIAS(name, alias, desc) /** - * @ingroup msh + * @ingroup finsh * * This macro exports a command to module shell. * - * @param command is the name of the command. - * @param desc is the description of the command, which will show in help list. - * @param opt This is an option, enter any content to enable option completion + * param command is the name of the command. + * param desc is the description of the command, which will show in help list. + * param opt This is an option, enter any content to enable option completion */ /* MSH_CMD_EXPORT(command, desc) or MSH_CMD_EXPORT(command, desc, opt) */ #define MSH_CMD_EXPORT(...) \ @@ -144,17 +144,18 @@ typedef long (*syscall_func)(void); _MSH_FUNCTION_CMD2)(__VA_ARGS__) /** - * @ingroup msh + * @ingroup finsh * * This macro exports a command with alias to module shell. * - * @param command is the name of the command. - * @param alias is the alias of the command. - * @param desc is the description of the command, which will show in help list. - * @param opt This is an option, enter any content to enable option completion - * @note + * param command is the name of the command. + * param alias is the alias of the command. + * param desc is the description of the command, which will show in help list. + * param opt This is an option, enter any content to enable option completion + * @code * #define MSH_CMD_EXPORT_ALIAS(command, alias, desc) or * #define MSH_CMD_EXPORT_ALIAS(command, alias, desc, opt) + * @endcode */ #define MSH_CMD_EXPORT_ALIAS(...) \ __MSH_GET_EXPORT_MACRO(__VA_ARGS__, _MSH_FUNCTION_EXPORT_CMD3_OPT, \ From 3c7435a4d62a2fcb3f4e7cc309494a0bcfbbc98e Mon Sep 17 00:00:00 2001 From: Supper Thomas <78900636@qq.com> Date: Sat, 14 Sep 2024 15:25:11 +0800 Subject: [PATCH 2/3] [doxygen] add driver fold --- documentation/doxygen/Doxyfile | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/doxygen/Doxyfile b/documentation/doxygen/Doxyfile index 412d93d0dc9..44a09c85d10 100644 --- a/documentation/doxygen/Doxyfile +++ b/documentation/doxygen/Doxyfile @@ -868,6 +868,7 @@ INPUT = ../../src \ ../../include \ . \ ../../components/finsh \ + ../../components/drivers/include/drivers \ ../../components/dfs/dfs_v2/src \ ../../components/dfs/dfs_v2/include From 76f749fd8712414e425e5fa008b5fb687f6a183d Mon Sep 17 00:00:00 2001 From: Supper Thomas <78900636@qq.com> Date: Sat, 14 Sep 2024 16:48:21 +0800 Subject: [PATCH 3/3] formatting --- .../drivers/include/drivers/dev_serial.h | 64 +++++++++---------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/components/drivers/include/drivers/dev_serial.h b/components/drivers/include/drivers/dev_serial.h index 02bb3ffdb0f..df2a62030aa 100644 --- a/components/drivers/include/drivers/dev_serial.h +++ b/components/drivers/include/drivers/dev_serial.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2006-2024, RT-Thread Development Team + * Copyright (c) 2006-2024 RT-Thread Development Team * * SPDX-License-Identifier: Apache-2.0 * @@ -17,51 +17,51 @@ #include /** * @addtogroup Drivers RTTHREAD Driver - * @defgroup Serial Serial + * @defgroup Serial Serial * * @brief Serial driver api - * + * * Example * @code {.c} - * + * * #include - * + * * #define SAMPLE_UART_NAME "uart2" * static struct rt_semaphore rx_sem; * static rt_device_t serial; - * + * * static rt_err_t uart_input(rt_device_t dev, rt_size_t size) * { - * + * * rt_sem_release(&rx_sem); - * + * * return RT_EOK; * } - * + * * static void serial_thread_entry(void *parameter) * { * char ch; - * + * * while (1) * { - * + * * while (rt_device_read(serial, -1, &ch, 1) != 1) * { - * + * * rt_sem_take(&rx_sem, RT_WAITING_FOREVER); * } - * + * * ch = ch + 1; * rt_device_write(serial, 0, &ch, 1); * } * } - * + * * static int uart_sample(int argc, char *argv[]) * { * rt_err_t ret = RT_EOK; * char uart_name[RT_NAME_MAX]; * char str[] = "hello RT-Thread!\r\n"; - * + * * if (argc == 2) * { * rt_strncpy(uart_name, argv[1], RT_NAME_MAX); @@ -70,27 +70,27 @@ * { * rt_strncpy(uart_name, SAMPLE_UART_NAME, RT_NAME_MAX); * } - * - * + * + * * serial = rt_device_find(uart_name); * if (!serial) * { * rt_kprintf("find %s failed!\n", uart_name); * return RT_ERROR; * } - * - * + * + * * rt_sem_init(&rx_sem, "rx_sem", 0, RT_IPC_FLAG_FIFO); - * + * * rt_device_open(serial, RT_DEVICE_FLAG_INT_RX); - * + * * rt_device_set_rx_indicate(serial, uart_input); - * + * * rt_device_write(serial, 0, str, (sizeof(str) - 1)); - * - * + * + * * rt_thread_t thread = rt_thread_create("serial", serial_thread_entry, RT_NULL, 1024, 25, 10); - * + * * if (thread != RT_NULL) * { * rt_thread_startup(thread); @@ -99,13 +99,13 @@ * { * ret = RT_ERROR; * } - * + * * return ret; * } - * + * * MSH_CMD_EXPORT(uart_sample, uart device sample); * @endcode - * + * * @ingroup Drivers */ @@ -202,7 +202,7 @@ /** * @brief Sets a hook function when RX indicate is called - * + * */ typedef void (*rt_hw_serial_rxind_hookproto_t)(rt_device_t dev, rt_size_t size); RT_OBJECT_HOOKLIST_DECLARE(rt_hw_serial_rxind_hookproto_t, rt_hw_serial_rxind); @@ -293,7 +293,7 @@ void rt_hw_serial_isr(struct rt_serial_device *serial, int event); /** * @brief Register a serial device to device list - * + * * @param serial serial device * @param name device name * @param flag device flag @@ -310,10 +310,10 @@ rt_err_t rt_hw_serial_register(struct rt_serial_device *serial, /** * @brief register a serial device to system device list and add a device object to system object list - * + * * @param serial serial device * @return rt_err_t error code - * + * * @ingroup Serial */ rt_err_t rt_hw_serial_register_tty(struct rt_serial_device *serial);