libs/rt-thread
libs
/
rt-thread
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

[doxygen] add driver example for doxygen (#9446)

This commit is contained in:
Supper Thomas 2024-09-15 08:22:44 +08:00 committed by GitHub
parent 379aece6dc
commit 6320f184f5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 316 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
.github/workflows/doxygen.yml vendored
View File

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

14
components/drivers/include/drivers/dev_can.h
View File

@ -63,7 +63,14 @@ 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 */
@ -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*/

131
components/drivers/include/drivers/dev_serial.h
View File

@ -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
*
@ -15,7 +15,105 @@
#define __DEV_SERIAL_H__
#include <rtthread.h>
/**
* @addtogroup Drivers RTTHREAD Driver
* @defgroup Serial Serial
*
* @brief Serial driver api
*
* <b>Example</b>
* @code {.c}
*
* #include <rtthread.h>
*
* #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
@ -105,7 +203,6 @@
/**
* @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

166
components/drivers/include/drivers/dev_serial_v2.h
View File

@ -13,6 +13,122 @@
#include <rtthread.h>
/**
* @addtogroup Drivers RTTHREAD Driver
* @defgroup Serial_v2 Serial v2
*
* @brief Serial v2 driver api
*
* <b>Example</b>
* @code {.c}
*
* #include <rtthread.h>
* #include <rtdevice.h>
*
* #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
* @brief Serial receive indicate hook function type
*
* @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);
@ -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

21
components/finsh/finsh.h
View File

@ -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, \

1
documentation/doxygen/Doxyfile
View File

@ -868,6 +868,7 @@ INPUT = ../../src \
../../include \
. \
../../components/finsh \
../../components/drivers/include/drivers \
../../components/dfs/dfs_v2/src \
../../components/dfs/dfs_v2/include