From 3de03a072e3145522546b46117e51e9e444e1b4e Mon Sep 17 00:00:00 2001 From: Jackistang Date: Wed, 18 Aug 2021 09:44:52 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E6=94=B9=20ringbuffer=20=E5=92=8C=20w?= =?UTF-8?q?orkqueue=20=E6=B3=A8=E9=87=8A=E7=9A=84=E8=AF=AD=E6=B3=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/include/ipc/ringbuffer.h | 2 +- components/drivers/include/ipc/workqueue.h | 4 +- components/drivers/src/ringbuffer.c | 44 +++++++-------- components/drivers/src/workqueue.c | 60 ++++++++++----------- 4 files changed, 56 insertions(+), 54 deletions(-) diff --git a/components/drivers/include/ipc/ringbuffer.h b/components/drivers/include/ipc/ringbuffer.h index da68c5c1fa..7da50225b3 100644 --- a/components/drivers/include/ipc/ringbuffer.h +++ b/components/drivers/include/ipc/ringbuffer.h @@ -82,7 +82,7 @@ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb); #endif /** - * @brief Get buffer size of the ring buffer object. + * @brief Get the buffer size of the ring buffer object. * * @param rb A pointer to the ring buffer object. * diff --git a/components/drivers/include/ipc/workqueue.h b/components/drivers/include/ipc/workqueue.h index 70744ad668..776709a8ab 100644 --- a/components/drivers/include/ipc/workqueue.h +++ b/components/drivers/include/ipc/workqueue.h @@ -72,8 +72,8 @@ rt_err_t rt_work_cancel(struct rt_work *work); * @brief Initialize a work item, binding with a callback function. * * @param work A pointer to the work item object. - * @param work_func A callback function will be called when this work item is executed. - * @param work_data A user data passed to the callback function as it's second parameter. + * @param work_func A callback function that will be called when this work item is executed. + * @param work_data A user data passed to the callback function as the second parameter. */ rt_inline void rt_work_init(struct rt_work *work, void (*work_func)(struct rt_work *work, void *work_data), void *work_data) diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c index 417982a1b7..a8233a7555 100644 --- a/components/drivers/src/ringbuffer.c +++ b/components/drivers/src/ringbuffer.c @@ -29,11 +29,11 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb } /** - * @brief Initialize a ring buffer object with a given buffer. + * @brief Initialize the ring buffer object with the given buffer. * * @param rb A pointer to the ring buffer object. * @param pool A pointer to the buffer. - * @param size Size of the buffer in bytes. + * @param size The size of the buffer in bytes. */ void rt_ringbuffer_init(struct rt_ringbuffer *rb, rt_uint8_t *pool, @@ -53,13 +53,13 @@ void rt_ringbuffer_init(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_init); /** - * @brief Put a block of data into the ring buffer. If the size of ring buffer is not enough, it will discard out-of-range data. + * @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will discard out-of-range data. * * @param rb A pointer to the ring buffer object. * @param ptr A pointer to the data buffer. * @param length The size of data in bytes. * - * @return Return the size in bytes put into the ring buffer actually. + * @return Return the data size we put into the ring buffer. */ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb, const rt_uint8_t *ptr, @@ -106,13 +106,13 @@ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_put); /** - * @brief Put a block of data into the ring buffer. If the size of ring buffer is not enough, it will overwrite the existing data in the ring buffer. + * @brief Put a block of data into the ring buffer. If the capacity of ring buffer is insufficient, it will overwrite the existing data in the ring buffer. * * @param rb A pointer to the ring buffer object. * @param ptr A pointer to the data buffer. * @param length The size of data in bytes. * - * @return Return the byte size of the data actually put into the ring buffer. + * @return Return the data size we put into the ring buffer. */ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb, const rt_uint8_t *ptr, @@ -171,9 +171,9 @@ RTM_EXPORT(rt_ringbuffer_put_force); * * @param rb A pointer to the ring buffer. * @param ptr A pointer to the data buffer. - * @param length The size of data we want to read from the ring buffer. + * @param length The size of the data we want to read from the ring buffer. * - * @return Return the data size that we read from the ring buffer. + * @return Return the data size we read from the ring buffer. */ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb, rt_uint8_t *ptr, @@ -220,12 +220,14 @@ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_get); /** - * @brief Peak data from the ring buffer. + * @brief Get the first readable byte of the ring buffer. * * @param rb A pointer to the ringbuffer. * @param ptr When this function return, *ptr is a pointer to the first readable byte of the ring buffer. * - * @return Return the size of ring buffer. + * @note It is recommended to read only one byte, otherwise it may cause buffer overflow. + * + * @return Return the size of the ring buffer. */ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr) { @@ -262,9 +264,9 @@ RTM_EXPORT(rt_ringbuffer_peak); * @brief Put a byte into the ring buffer. If ring buffer is full, this operation will fail. * * @param rb A pointer to the ring buffer object. - * @param ch A byte to be put into the ring buffer. + * @param ch A byte put into the ring buffer. * - * @return Return the size in bytes put into the ring buffer. The ring buffer is full if returns 0. Otherwise, it will return 1. + * @return Return the data size we put into the ring buffer. The ring buffer is full if returns 0. Otherwise, it will return 1. */ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch) { @@ -292,12 +294,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch) RTM_EXPORT(rt_ringbuffer_putchar); /** - * @brief Put a byte into the ring buffer. If ring buffer is full, it will discard one old data and put into a new data. + * @brief Put a byte into the ring buffer. If ring buffer is full, it will discard an old data and put into a new data. * * @param rb A pointer to the ring buffer object. - * @param ch A byte to be put into the ring buffer. + * @param ch A byte put into the ring buffer. * - * @return Return the size in bytes put into the ring buffer. Always return 1. + * @return Return the data size we put into the ring buffer. Always return 1. */ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch) { @@ -334,10 +336,10 @@ RTM_EXPORT(rt_ringbuffer_putchar_force); /** * @brief Get a byte from the ring buffer. * - * @param rb The pointer to ring buffer object. - * @param ch The buffer to store byte read from ring buffer. + * @param rb The pointer to the ring buffer object. + * @param ch A pointer to the buffer, used to store one byte. * - * @return 0 ring buffer is empty. + * @return 0 The ring buffer is empty. * @return 1 Success */ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch) @@ -368,7 +370,7 @@ RTM_EXPORT(rt_ringbuffer_getchar); /** * @brief Get the size of data in the ring buffer in bytes. * - * @param rb The pointer to ring buffer object. + * @param rb The pointer to the ring buffer object. * * @return Return the size of data in the ring buffer in bytes. */ @@ -411,7 +413,7 @@ RTM_EXPORT(rt_ringbuffer_reset); /** * @brief Create a ring buffer object with a given size. * - * @param size Size of the buffer in bytes. + * @param size The size of the buffer in bytes. * * @return Return a pointer to ring buffer object. When the return value is RT_NULL, it means the creation failed. */ @@ -443,7 +445,7 @@ exit: RTM_EXPORT(rt_ringbuffer_create); /** - * @brief Destroy a ring buffer object, which is created by rt_ringbuffer_create() . + * @brief Destroy the ring buffer object, which is created by rt_ringbuffer_create() . * * @param rb A pointer to the ring buffer object. */ diff --git a/components/drivers/src/workqueue.c b/components/drivers/src/workqueue.c index 60472d9ca4..4a776ca485 100644 --- a/components/drivers/src/workqueue.c +++ b/components/drivers/src/workqueue.c @@ -211,13 +211,13 @@ static void _delayed_work_timeout_handler(void *parameter) } /** - * @brief Create a work queue, which contains a thread. + * @brief Create a work queue with a thread inside. * - * @param name The name for work queue thread. - * @param stack_size The stack size for work queue thread. - * @param priority The priority for work queue thread. + * @param name The name of the work queue thread. + * @param stack_size The stack size of the work queue thread. + * @param priority The priority of the work queue thread. * - * @return Return a pointer to workqueue object. It will return RT_NULL if failed. + * @return Return A pointer to the workqueue object. It will return RT_NULL if failed. */ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority) { @@ -249,7 +249,7 @@ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_siz /** * @brief Destroy a work queue. * - * @param queue A pointer to workqueue object. + * @param queue A pointer to the workqueue object. * * @return RT_EOK Success. */ @@ -266,10 +266,10 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) } /** - * @brief Submit a work item to the work queue immediately. + * @brief Submit a work item to the work queue without delay. * - * @param queue A pointer to workqueue object. - * @param work A pointer to work item object. + * @param queue A pointer to the workqueue object. + * @param work A pointer to the work item object. * * @return RT_EOK Success. * @return -RT_EBUSY This work item is executing. @@ -283,15 +283,15 @@ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work) } /** - * @brief Submit a work item to the work queue with a delay of time. + * @brief Submit a work item to the work queue with a delay. * - * @param queue A pointer to workqueue object. - * @param work A pointer to work item object. - * @param time This work item will be delayed by time (unit: an OS ticks) before it's been submitted to the work queue. + * @param queue A pointer to the workqueue object. + * @param work A pointer to the work item object. + * @param time The delay time (unit: OS ticks) for the work item to be submitted to the work queue. * * @return RT_EOK Success. * @return -RT_EBUSY This work item is executing. - * @return -RT_ERROR Time is invalid. + * @return -RT_ERROR The time parameter is invalid. */ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *work, rt_tick_t time) { @@ -302,10 +302,10 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo } /** - * @brief This function submit a work item to the work queue. This work item will be executed immediately after the current work item is executed. + * @brief Submit a work item to the work queue without delay. This work item will be executed after the current work item is executed. * - * @param queue A pointer to workqueue object. - * @param work A pointer to work item object. + * @param queue A pointer to the workqueue object. + * @param work A pointer to the work item object. * * @return RT_EOK Success. */ @@ -339,8 +339,8 @@ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work * /** * @brief Cancel a work item in the work queue. * - * @param queue A pointer to workqueue object. - * @param work A pointer to work item object. + * @param queue A pointer to the workqueue object. + * @param work A pointer to the work item object. * * @return RT_EOK Success. * @return -RT_EBUSY This work item is executing. @@ -353,10 +353,10 @@ rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *wo } /** - * @brief Cancel a work item in the work queue. If the work item is been executing now, this function will block until it is done. + * @brief Cancel a work item in the work queue. If the work item is executing, this function will block until it is done. * - * @param queue A pointer to workqueue object. - * @param work A pointer to work item object. + * @param queue A pointer to the workqueue object. + * @param work A pointer to the work item object. * * @return RT_EOK Success. */ @@ -379,9 +379,9 @@ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_wor } /** - * @brief This function will cancel all work item in work queue. + * @brief This function will cancel all work items in work queue. * - * @param queue A pointer to workqueue object. + * @param queue A pointer to the workqueue object. * * @return RT_EOK Success. */ @@ -413,14 +413,14 @@ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue) static struct rt_workqueue *sys_workq; /** - * @brief Submit a work item to the system work queue with a delay of time. + * @brief Submit a work item to the system work queue with a delay. * - * @param work A pointer to work item object. - * @param time This work item will be delayed by time (unit: an OS tick) before it's been submitted to system work queue. + * @param work A pointer to the work item object. + * @param time The delay time (unit: OS ticks) for the work item to be submitted to the work queue. * * @return RT_EOK Success. * @return -RT_EBUSY This work item is executing. - * @return -RT_ERROR Time is invalid. + * @return -RT_ERROR The time parameter is invalid. */ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) { @@ -428,9 +428,9 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) } /** - * @brief Cancel a work item in system work queue. + * @brief Cancel a work item in the system work queue. * - * @param work A pointer to work item object. + * @param work A pointer to the work item object. * * @return RT_EOK Success. * @return -RT_EBUSY This work item is executing. -- GitLab