From 619fa4d9d8ef12ae11744d412ae00805796fb4b5 Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Sat, 31 Jul 2021 01:37:53 +0800 Subject: [ringbuffer] 采用局部变量，防止出现资源竞争 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/src/ringbuffer.c | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'components/drivers/src') diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c index 29de20b087..8d26fc45da 100644 --- a/components/drivers/src/ringbuffer.c +++ b/components/drivers/src/ringbuffer.c @@ -333,11 +333,15 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb) return rb->buffer_size; case RT_RINGBUFFER_HALFFULL: default: - if (rb->write_index > rb->read_index) - return rb->write_index - rb->read_index; + { + rt_size_t wi = rb->write_index, ri = rb->read_index; + + if (wi > ri) + return wi - ri; else - return rb->buffer_size - (rb->read_index - rb->write_index); - }; + return rb->buffer_size - (ri - wi); + } + } } RTM_EXPORT(rt_ringbuffer_data_len); -- cgit v1.3.1 From 0b4603d581f5d9f16666f0ebc1a28f2db11c70db Mon Sep 17 00:00:00 2001 From: Jackistang Date: Sat, 14 Aug 2021 11:10:43 +0800 Subject: [workqueue] 添加了 workqueue 接口的注释 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/include/ipc/workqueue.h | 7 +++ components/drivers/src/workqueue.c | 86 ++++++++++++++++++++++++++++++ 2 files changed, 93 insertions(+) (limited to 'components/drivers/src') diff --git a/components/drivers/include/ipc/workqueue.h b/components/drivers/include/ipc/workqueue.h index 03904d852e..8cd86896d0 100644 --- a/components/drivers/include/ipc/workqueue.h +++ b/components/drivers/include/ipc/workqueue.h @@ -67,6 +67,13 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time); rt_err_t rt_work_cancel(struct rt_work *work); #endif /* RT_USING_SYSTEM_WORKQUEUE */ +/** + * @brief Init a work item, and bind it with a callback function. + * + * @param work A pointer to work item object. + * @param work_func A callback function will be called when this work item is being executed. + * @param work_data A user data passed to the callback function as it's 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/workqueue.c b/components/drivers/src/workqueue.c index 8fcfd52688..897ee7af0b 100644 --- a/components/drivers/src/workqueue.c +++ b/components/drivers/src/workqueue.c @@ -209,6 +209,15 @@ static void _delayed_work_timeout_handler(void *parameter) } } +/** + * @brief Create a work queue, which contains a thread. + * + * @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. + * + * @return Return a pointer to workqueue object. When the return value is RT_NULL, it means the creation failed. + */ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority) { struct rt_workqueue *queue = RT_NULL; @@ -236,6 +245,13 @@ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_siz return queue; } +/** + * @brief Destroy a work queue. + * + * @param queue A pointer to workqueue object. + * + * @return RT_EOK Success. + */ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) { RT_ASSERT(queue != RT_NULL); @@ -248,6 +264,15 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) return RT_EOK; } +/** + * @brief Submit a work item to the work queue immediately. + * + * @param queue A pointer to workqueue object. + * @param work A pointer to work item object. + * + * @return RT_EOK Success. + * @return -RT_EBUSY This work item is been executing now. + */ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work) { RT_ASSERT(queue != RT_NULL); @@ -256,6 +281,17 @@ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work) return _workqueue_submit_work(queue, work, 0); } +/** + * @brief Submit a work item to the work queue with a delay of time. + * + * @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 tick) before it's been submitted to the work queue. + * + * @return RT_EOK Success. + * @return -RT_EBUSY This work item is been executing now. + * @return -RT_ERROR Time is invalid. + */ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *work, rt_tick_t time) { RT_ASSERT(queue != RT_NULL); @@ -264,6 +300,14 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo return _workqueue_submit_work(queue, work, time); } +/** + * @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. + * + * @param queue A pointer to workqueue object. + * @param work A pointer to work item object. + * + * @return RT_EOK Success. + */ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work *work) { rt_base_t level; @@ -291,6 +335,15 @@ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work * return RT_EOK; } +/** + * @brief Cancel a work item in the work queue. + * + * @param queue A pointer to workqueue object. + * @param work A pointer to work item object. + * + * @return RT_EOK Success. + * @return -RT_EBUSY This work item is been executing now. + */ rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *work) { RT_ASSERT(work != RT_NULL); @@ -298,6 +351,14 @@ rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *wo return _workqueue_cancel_work(queue, work); } +/** + * @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. + * + * @param queue A pointer to workqueue object. + * @param work A pointer to work item object. + * + * @return RT_EOK Success. + */ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_work *work) { RT_ASSERT(queue != RT_NULL); @@ -316,6 +377,13 @@ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_wor return RT_EOK; } +/** + * @brief This function will cancel all work item in work queue. + * + * @param queue A pointer to workqueue object. + * + * @return RT_EOK Success. + */ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue) { struct rt_work *work; @@ -343,11 +411,29 @@ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue) #ifdef RT_USING_SYSTEM_WORKQUEUE static struct rt_workqueue *sys_workq; +/** + * @brief Submit a work item to the system work queue with a delay of time. + * + * @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. + * + * @return RT_EOK Success. + * @return -RT_EBUSY This work item is been executing now. + * @return -RT_ERROR Time is invalid. + */ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) { return rt_workqueue_submit_work(sys_workq, work, time); } +/** + * @brief Cancel a work item in system work queue. + * + * @param work A pointer to work item object. + * + * @return RT_EOK Success. + * @return -RT_EBUSY This work item is been executing now. + */ rt_err_t rt_work_cancel(struct rt_work *work) { return rt_workqueue_cancel_work(sys_workq, work); -- cgit v1.3.1 From 1b7468979f7b697dcbff49dfa5f7f5e92acded75 Mon Sep 17 00:00:00 2001 From: Jackistang Date: Sat, 14 Aug 2021 13:47:05 +0800 Subject: [ringbuffer] 添加 ringbuffer 的接口注释 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/include/ipc/ringbuffer.h | 8 +++ components/drivers/include/ipc/workqueue.h | 1 + components/drivers/src/ringbuffer.c | 91 +++++++++++++++++++++++++---- components/drivers/src/workqueue.c | 1 + 4 files changed, 90 insertions(+), 11 deletions(-) (limited to 'components/drivers/src') diff --git a/components/drivers/include/ipc/ringbuffer.h b/components/drivers/include/ipc/ringbuffer.h index 71c4801253..324d87b9b9 100644 --- a/components/drivers/include/ipc/ringbuffer.h +++ b/components/drivers/include/ipc/ringbuffer.h @@ -5,6 +5,7 @@ * * Change Logs: * Date Author Notes + * 2021-08-14 Jackistang add commets for function inferface. */ #ifndef RINGBUFFER_H__ #define RINGBUFFER_H__ @@ -80,6 +81,13 @@ struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t length); void rt_ringbuffer_destroy(struct rt_ringbuffer *rb); #endif +/** + * @brief Get buffer size of the ringbuffer object. + * + * @param rb A pointer to the ringbuffer object. + * + * @return Buffer size. + */ rt_inline rt_uint16_t rt_ringbuffer_get_size(struct rt_ringbuffer *rb) { RT_ASSERT(rb != RT_NULL); diff --git a/components/drivers/include/ipc/workqueue.h b/components/drivers/include/ipc/workqueue.h index 8cd86896d0..31295c29be 100644 --- a/components/drivers/include/ipc/workqueue.h +++ b/components/drivers/include/ipc/workqueue.h @@ -6,6 +6,7 @@ * Change Logs: * Date Author Notes * 2021-08-01 Meco Man remove rt_delayed_work_init() and rt_delayed_work structure + * 2021-08-14 Jackistang add commets for rt_work_init() */ #ifndef WORKQUEUE_H__ #define WORKQUEUE_H__ diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c index f01a594609..099d48691e 100644 --- a/components/drivers/src/ringbuffer.c +++ b/components/drivers/src/ringbuffer.c @@ -9,6 +9,7 @@ * 2013-05-08 Grissiom reimplement * 2016-08-18 heyuanjie add interface * 2021-07-20 arminker fix write_index bug in function rt_ringbuffer_put_force + * 2021-08-14 Jackistang add commets for function inferface. */ #include @@ -27,6 +28,13 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb return RT_RINGBUFFER_HALFFULL; } +/** + * @brief Init a ringbuffer object with a given buffer. + * + * @param rb A pointer to the ringbuffer object. + * @param pool A pointer to the buffer. + * @param size Size of the buffer in bytes. + */ void rt_ringbuffer_init(struct rt_ringbuffer *rb, rt_uint8_t *pool, rt_int16_t size) @@ -45,7 +53,13 @@ void rt_ringbuffer_init(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_init); /** - * put a block of data into ring buffer + * @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will discard out-of-range data. + * + * @param rb A pointer to the ringbuffer 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 ringbuffer actually. */ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb, const rt_uint8_t *ptr, @@ -92,9 +106,13 @@ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_put); /** - * put a block of data into ring buffer - * - * When the buffer is full, it will discard the old data. + * @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will overwrite the existing data in the ringbuffer. + * + * @param rb A pointer to the ringbuffer 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 ringbuffer actually. */ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb, const rt_uint8_t *ptr, @@ -149,7 +167,13 @@ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_put_force); /** - * get data from ring buffer + * @brief Get a block of data from the ringbuffer. + * + * @param rb A pointer to the ringbuffer. + * @param ptr A pointer to the data buffer. + * @param length The size of data we want to read from the ringbuffer. + * + * @return Return the size of data we read from the ringbuffer actually. */ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb, rt_uint8_t *ptr, @@ -198,6 +222,15 @@ RTM_EXPORT(rt_ringbuffer_get); /** * peak data from ring buffer */ + +/** + * @brief Peak data from the ringbuffer. + * + * @param rb A pointer to the ringbuffer. + * @param ptr When this function return, *ptr is a pointer to the first character of ringbuffer. + * + * @return Return the size of ringbuffer. + */ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr) { RT_ASSERT(rb != RT_NULL); @@ -230,7 +263,12 @@ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr) RTM_EXPORT(rt_ringbuffer_peak); /** - * put a character into ring buffer + * @brief Put a character into the ringbuffer. If ringbuffer is full, This operation will fail. + * + * @param rb A pointer to the ringbuffer object. + * @param ch A character to be put into the ringbuffer. + * + * @return Return the size in bytes put into the ringbuffer. If return 0, it means the ringbuffer if full. If return 1, it means success. */ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch) { @@ -258,9 +296,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch) RTM_EXPORT(rt_ringbuffer_putchar); /** - * put a character into ring buffer - * - * When the buffer is full, it will discard one old data. + * @brief Put a character into the ringbuffer. If ringbuffer is full, it will discard one old data and put into a new data. + * + * @param rb A pointer to the ringbuffer object. + * @param ch A character to be put into the ringbuffer. + * + * @return Return the size in bytes put into the ringbuffer. Always return 1. */ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch) { @@ -297,6 +338,16 @@ RTM_EXPORT(rt_ringbuffer_putchar_force); /** * get a character from a ringbuffer */ + +/** + * @brief Get a character from the ringbuffer. + * + * @param rb The pointer to ringbuffer object. + * @param ch The buffer to store character read from ringbuffer. + * + * @return 0 Ringbuffer is empty. + * @return 1 Success + */ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch) { RT_ASSERT(rb != RT_NULL); @@ -323,7 +374,11 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch) RTM_EXPORT(rt_ringbuffer_getchar); /** - * get the size of data in rb + * @brief Get the size of data in the ringbuffer in bytes. + * + * @param rb The pointer to ringbuffer object. + * + * @return Return the size of data in the ringbuffer in bytes. */ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb) { @@ -344,7 +399,9 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb) RTM_EXPORT(rt_ringbuffer_data_len); /** - * empty the rb + * @brief Reset the ringbuffer object, and clear all contents in the buffer. + * + * @param rb A pointer to the ringbuffer object. */ void rt_ringbuffer_reset(struct rt_ringbuffer *rb) { @@ -359,6 +416,13 @@ RTM_EXPORT(rt_ringbuffer_reset); #ifdef RT_USING_HEAP +/** + * @brief Create a ringbuffer object with a given size. + * + * @param size Size of the buffer in bytes. + * + * @return Return a pointer to ringbuffer object. When the return value is RT_NULL, it means the creation failed. + */ struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size) { struct rt_ringbuffer *rb; @@ -386,6 +450,11 @@ exit: } RTM_EXPORT(rt_ringbuffer_create); +/** + * @brief Destroy a ringbuffer object, which is created by rt_ringbuffer_create() . + * + * @param rb A pointer to the ringbuffer object. + */ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb) { RT_ASSERT(rb != RT_NULL); diff --git a/components/drivers/src/workqueue.c b/components/drivers/src/workqueue.c index 897ee7af0b..e37af37658 100644 --- a/components/drivers/src/workqueue.c +++ b/components/drivers/src/workqueue.c @@ -7,6 +7,7 @@ * Date Author Notes * 2017-02-27 Bernard fix the re-work issue. * 2021-08-01 Meco Man remove rt_delayed_work_init() + * 2021-08-14 Jackistang add commets for function interface. */ #include -- cgit v1.3.1 From 99de1a622003d100c29abc084669cfc1263b1614 Mon Sep 17 00:00:00 2001 From: Jackistang Date: Sat, 14 Aug 2021 14:32:58 +0800 Subject: format code --- components/drivers/include/ipc/ringbuffer.h | 4 +-- components/drivers/include/ipc/workqueue.h | 2 +- components/drivers/src/ringbuffer.c | 44 ++++++++++++++--------------- components/drivers/src/workqueue.c | 44 ++++++++++++++--------------- 4 files changed, 47 insertions(+), 47 deletions(-) (limited to 'components/drivers/src') diff --git a/components/drivers/include/ipc/ringbuffer.h b/components/drivers/include/ipc/ringbuffer.h index 324d87b9b9..a9d74b064d 100644 --- a/components/drivers/include/ipc/ringbuffer.h +++ b/components/drivers/include/ipc/ringbuffer.h @@ -83,9 +83,9 @@ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb); /** * @brief Get buffer size of the ringbuffer object. - * + * * @param rb A pointer to the ringbuffer object. - * + * * @return Buffer size. */ rt_inline rt_uint16_t rt_ringbuffer_get_size(struct rt_ringbuffer *rb) diff --git a/components/drivers/include/ipc/workqueue.h b/components/drivers/include/ipc/workqueue.h index 31295c29be..d479d0ec95 100644 --- a/components/drivers/include/ipc/workqueue.h +++ b/components/drivers/include/ipc/workqueue.h @@ -70,7 +70,7 @@ rt_err_t rt_work_cancel(struct rt_work *work); /** * @brief Init a work item, and bind it with a callback function. - * + * * @param work A pointer to work item object. * @param work_func A callback function will be called when this work item is being executed. * @param work_data A user data passed to the callback function as it's second parameter. diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c index 099d48691e..b42c2ecefc 100644 --- a/components/drivers/src/ringbuffer.c +++ b/components/drivers/src/ringbuffer.c @@ -30,7 +30,7 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb /** * @brief Init a ringbuffer object with a given buffer. - * + * * @param rb A pointer to the ringbuffer object. * @param pool A pointer to the buffer. * @param size Size of the buffer in bytes. @@ -54,11 +54,11 @@ RTM_EXPORT(rt_ringbuffer_init); /** * @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will discard out-of-range data. - * + * * @param rb A pointer to the ringbuffer 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 ringbuffer actually. */ rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb, @@ -107,11 +107,11 @@ RTM_EXPORT(rt_ringbuffer_put); /** * @brief Put a block of data into the ringbuffer. If the size of ringbuffer is not enough, it will overwrite the existing data in the ringbuffer. - * + * * @param rb A pointer to the ringbuffer 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 ringbuffer actually. */ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb, @@ -168,11 +168,11 @@ RTM_EXPORT(rt_ringbuffer_put_force); /** * @brief Get a block of data from the ringbuffer. - * + * * @param rb A pointer to the ringbuffer. * @param ptr A pointer to the data buffer. * @param length The size of data we want to read from the ringbuffer. - * + * * @return Return the size of data we read from the ringbuffer actually. */ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb, @@ -225,10 +225,10 @@ RTM_EXPORT(rt_ringbuffer_get); /** * @brief Peak data from the ringbuffer. - * + * * @param rb A pointer to the ringbuffer. * @param ptr When this function return, *ptr is a pointer to the first character of ringbuffer. - * + * * @return Return the size of ringbuffer. */ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr) @@ -264,10 +264,10 @@ RTM_EXPORT(rt_ringbuffer_peak); /** * @brief Put a character into the ringbuffer. If ringbuffer is full, This operation will fail. - * + * * @param rb A pointer to the ringbuffer object. * @param ch A character to be put into the ringbuffer. - * + * * @return Return the size in bytes put into the ringbuffer. If return 0, it means the ringbuffer if full. If return 1, it means success. */ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch) @@ -297,10 +297,10 @@ RTM_EXPORT(rt_ringbuffer_putchar); /** * @brief Put a character into the ringbuffer. If ringbuffer is full, it will discard one old data and put into a new data. - * + * * @param rb A pointer to the ringbuffer object. * @param ch A character to be put into the ringbuffer. - * + * * @return Return the size in bytes put into the ringbuffer. Always return 1. */ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch) @@ -341,10 +341,10 @@ RTM_EXPORT(rt_ringbuffer_putchar_force); /** * @brief Get a character from the ringbuffer. - * + * * @param rb The pointer to ringbuffer object. * @param ch The buffer to store character read from ringbuffer. - * + * * @return 0 Ringbuffer is empty. * @return 1 Success */ @@ -375,9 +375,9 @@ RTM_EXPORT(rt_ringbuffer_getchar); /** * @brief Get the size of data in the ringbuffer in bytes. - * + * * @param rb The pointer to ringbuffer object. - * + * * @return Return the size of data in the ringbuffer in bytes. */ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb) @@ -400,7 +400,7 @@ RTM_EXPORT(rt_ringbuffer_data_len); /** * @brief Reset the ringbuffer object, and clear all contents in the buffer. - * + * * @param rb A pointer to the ringbuffer object. */ void rt_ringbuffer_reset(struct rt_ringbuffer *rb) @@ -418,12 +418,12 @@ RTM_EXPORT(rt_ringbuffer_reset); /** * @brief Create a ringbuffer object with a given size. - * + * * @param size Size of the buffer in bytes. - * + * * @return Return a pointer to ringbuffer object. When the return value is RT_NULL, it means the creation failed. */ -struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size) +struct rt_ringbuffer *rt_ringbuffer_create(rt_uint16_t size) { struct rt_ringbuffer *rb; rt_uint8_t *pool; @@ -452,7 +452,7 @@ RTM_EXPORT(rt_ringbuffer_create); /** * @brief Destroy a ringbuffer object, which is created by rt_ringbuffer_create() . - * + * * @param rb A pointer to the ringbuffer object. */ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb) diff --git a/components/drivers/src/workqueue.c b/components/drivers/src/workqueue.c index e37af37658..37733a1f65 100644 --- a/components/drivers/src/workqueue.c +++ b/components/drivers/src/workqueue.c @@ -212,11 +212,11 @@ static void _delayed_work_timeout_handler(void *parameter) /** * @brief Create a work queue, which contains a thread. - * + * * @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. - * + * * @return Return a pointer to workqueue object. When the return value is RT_NULL, it means the creation failed. */ struct rt_workqueue *rt_workqueue_create(const char *name, rt_uint16_t stack_size, rt_uint8_t priority) @@ -248,10 +248,10 @@ 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. - * - * @return RT_EOK Success. + * + * @return RT_EOK Success. */ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) { @@ -267,10 +267,10 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) /** * @brief Submit a work item to the work queue immediately. - * + * * @param queue A pointer to workqueue object. * @param work A pointer to work item object. - * + * * @return RT_EOK Success. * @return -RT_EBUSY This work item is been executing now. */ @@ -284,11 +284,11 @@ 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. - * + * * @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 tick) before it's been submitted to the work queue. - * + * * @return RT_EOK Success. * @return -RT_EBUSY This work item is been executing now. * @return -RT_ERROR Time is invalid. @@ -303,11 +303,11 @@ 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. - * + * * @param queue A pointer to workqueue object. * @param work A pointer to work item object. - * - * @return RT_EOK Success. + * + * @return RT_EOK Success. */ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work *work) { @@ -338,10 +338,10 @@ 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. - * + * * @return RT_EOK Success. * @return -RT_EBUSY This work item is been executing now. */ @@ -354,10 +354,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. - * + * * @param queue A pointer to workqueue object. * @param work A pointer to work item object. - * + * * @return RT_EOK Success. */ rt_err_t rt_workqueue_cancel_work_sync(struct rt_workqueue *queue, struct rt_work *work) @@ -380,9 +380,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. - * + * * @param queue A pointer to workqueue object. - * + * * @return RT_EOK Success. */ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue) @@ -414,10 +414,10 @@ static struct rt_workqueue *sys_workq; /** * @brief Submit a work item to the system work queue with a delay of time. - * + * * @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. - * + * * @return RT_EOK Success. * @return -RT_EBUSY This work item is been executing now. * @return -RT_ERROR Time is invalid. @@ -429,9 +429,9 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) /** * @brief Cancel a work item in system work queue. - * + * * @param work A pointer to work item object. - * + * * @return RT_EOK Success. * @return -RT_EBUSY This work item is been executing now. */ -- cgit v1.3.1 From 6173c9d7d5933adbf2ed374034d34608bbdd3c58 Mon Sep 17 00:00:00 2001 From: Jackistang Date: Tue, 17 Aug 2021 22:44:29 +0800 Subject: fix comments error in ringbuffer and workqueue. --- components/drivers/include/ipc/ringbuffer.h | 6 +-- components/drivers/include/ipc/workqueue.h | 8 +-- components/drivers/src/ringbuffer.c | 84 +++++++++++++---------------- components/drivers/src/workqueue.c | 16 +++--- 4 files changed, 53 insertions(+), 61 deletions(-) (limited to 'components/drivers/src') diff --git a/components/drivers/include/ipc/ringbuffer.h b/components/drivers/include/ipc/ringbuffer.h index a9d74b064d..da68c5c1fa 100644 --- a/components/drivers/include/ipc/ringbuffer.h +++ b/components/drivers/include/ipc/ringbuffer.h @@ -5,7 +5,7 @@ * * Change Logs: * Date Author Notes - * 2021-08-14 Jackistang add commets for function inferface. + * 2021-08-14 Jackistang add comments for function interface. */ #ifndef RINGBUFFER_H__ #define RINGBUFFER_H__ @@ -82,9 +82,9 @@ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb); #endif /** - * @brief Get buffer size of the ringbuffer object. + * @brief Get buffer size of the ring buffer object. * - * @param rb A pointer to the ringbuffer object. + * @param rb A pointer to the ring buffer object. * * @return Buffer size. */ diff --git a/components/drivers/include/ipc/workqueue.h b/components/drivers/include/ipc/workqueue.h index d479d0ec95..70744ad668 100644 --- a/components/drivers/include/ipc/workqueue.h +++ b/components/drivers/include/ipc/workqueue.h @@ -6,7 +6,7 @@ * Change Logs: * Date Author Notes * 2021-08-01 Meco Man remove rt_delayed_work_init() and rt_delayed_work structure - * 2021-08-14 Jackistang add commets for rt_work_init() + * 2021-08-14 Jackistang add comments for rt_work_init() */ #ifndef WORKQUEUE_H__ #define WORKQUEUE_H__ @@ -69,10 +69,10 @@ rt_err_t rt_work_cancel(struct rt_work *work); #endif /* RT_USING_SYSTEM_WORKQUEUE */ /** - * @brief Init a work item, and bind it with a callback function. + * @brief Initialize a work item, binding with a callback function. * - * @param work A pointer to work item object. - * @param work_func A callback function will be called when this work item is being executed. + * @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. */ rt_inline void rt_work_init(struct rt_work *work, void (*work_func)(struct rt_work *work, void *work_data), diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c index b42c2ecefc..417982a1b7 100644 --- a/components/drivers/src/ringbuffer.c +++ b/components/drivers/src/ringbuffer.c @@ -9,7 +9,7 @@ * 2013-05-08 Grissiom reimplement * 2016-08-18 heyuanjie add interface * 2021-07-20 arminker fix write_index bug in function rt_ringbuffer_put_force - * 2021-08-14 Jackistang add commets for function inferface. + * 2021-08-14 Jackistang add comments for function interface. */ #include @@ -29,9 +29,9 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb } /** - * @brief Init a ringbuffer object with a given buffer. + * @brief Initialize a ring buffer object with a given buffer. * - * @param rb A pointer to the ringbuffer object. + * @param rb A pointer to the ring buffer object. * @param pool A pointer to the buffer. * @param size Size of the buffer in bytes. */ @@ -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 ringbuffer. If the size of ringbuffer is not enough, it will discard out-of-range data. + * @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. * - * @param rb A pointer to the ringbuffer object. + * @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 ringbuffer actually. + * @return Return the size in bytes put into the ring buffer actually. */ 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 ringbuffer. If the size of ringbuffer is not enough, it will overwrite the existing data in the ringbuffer. + * @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. * - * @param rb A pointer to the ringbuffer object. + * @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 ringbuffer actually. + * @return Return the byte size of the data actually put into the ring buffer. */ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb, const rt_uint8_t *ptr, @@ -167,13 +167,13 @@ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_put_force); /** - * @brief Get a block of data from the ringbuffer. + * @brief Get data from the ring buffer. * - * @param rb A pointer to the ringbuffer. + * @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 ringbuffer. + * @param length The size of data we want to read from the ring buffer. * - * @return Return the size of data we read from the ringbuffer actually. + * @return Return the data size that we read from the ring buffer. */ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb, rt_uint8_t *ptr, @@ -220,16 +220,12 @@ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb, RTM_EXPORT(rt_ringbuffer_get); /** - * peak data from ring buffer - */ - -/** - * @brief Peak data from the ringbuffer. + * @brief Peak data from the ring buffer. * * @param rb A pointer to the ringbuffer. - * @param ptr When this function return, *ptr is a pointer to the first character of 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 ringbuffer. + * @return Return the size of ring buffer. */ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr) { @@ -263,12 +259,12 @@ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr) RTM_EXPORT(rt_ringbuffer_peak); /** - * @brief Put a character into the ringbuffer. If ringbuffer is full, This operation will fail. + * @brief Put a byte into the ring buffer. If ring buffer is full, this operation will fail. * - * @param rb A pointer to the ringbuffer object. - * @param ch A character to be put into the ringbuffer. + * @param rb A pointer to the ring buffer object. + * @param ch A byte to be put into the ring buffer. * - * @return Return the size in bytes put into the ringbuffer. If return 0, it means the ringbuffer if full. If return 1, it means success. + * @return Return the size in bytes 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) { @@ -296,12 +292,12 @@ rt_size_t rt_ringbuffer_putchar(struct rt_ringbuffer *rb, const rt_uint8_t ch) RTM_EXPORT(rt_ringbuffer_putchar); /** - * @brief Put a character into the ringbuffer. If ringbuffer 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 one old data and put into a new data. * - * @param rb A pointer to the ringbuffer object. - * @param ch A character to be put into the ringbuffer. + * @param rb A pointer to the ring buffer object. + * @param ch A byte to be put into the ring buffer. * - * @return Return the size in bytes put into the ringbuffer. Always return 1. + * @return Return the size in bytes put into the ring buffer. Always return 1. */ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t ch) { @@ -336,16 +332,12 @@ rt_size_t rt_ringbuffer_putchar_force(struct rt_ringbuffer *rb, const rt_uint8_t RTM_EXPORT(rt_ringbuffer_putchar_force); /** - * get a character from a ringbuffer - */ - -/** - * @brief Get a character from the ringbuffer. + * @brief Get a byte from the ring buffer. * - * @param rb The pointer to ringbuffer object. - * @param ch The buffer to store character read from ringbuffer. + * @param rb The pointer to ring buffer object. + * @param ch The buffer to store byte read from ring buffer. * - * @return 0 Ringbuffer is empty. + * @return 0 ring buffer is empty. * @return 1 Success */ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch) @@ -356,7 +348,7 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch) if (!rt_ringbuffer_data_len(rb)) return 0; - /* put character */ + /* put byte */ *ch = rb->buffer_ptr[rb->read_index]; if (rb->read_index == rb->buffer_size-1) @@ -374,11 +366,11 @@ rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch) RTM_EXPORT(rt_ringbuffer_getchar); /** - * @brief Get the size of data in the ringbuffer in bytes. + * @brief Get the size of data in the ring buffer in bytes. * - * @param rb The pointer to ringbuffer object. + * @param rb The pointer to ring buffer object. * - * @return Return the size of data in the ringbuffer in bytes. + * @return Return the size of data in the ring buffer in bytes. */ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb) { @@ -399,9 +391,9 @@ rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb) RTM_EXPORT(rt_ringbuffer_data_len); /** - * @brief Reset the ringbuffer object, and clear all contents in the buffer. + * @brief Reset the ring buffer object, and clear all contents in the buffer. * - * @param rb A pointer to the ringbuffer object. + * @param rb A pointer to the ring buffer object. */ void rt_ringbuffer_reset(struct rt_ringbuffer *rb) { @@ -417,11 +409,11 @@ RTM_EXPORT(rt_ringbuffer_reset); #ifdef RT_USING_HEAP /** - * @brief Create a ringbuffer object with a given size. + * @brief Create a ring buffer object with a given size. * * @param size Size of the buffer in bytes. * - * @return Return a pointer to ringbuffer object. When the return value is RT_NULL, it means the creation failed. + * @return Return a pointer to ring buffer object. When the return value is RT_NULL, it means the creation failed. */ struct rt_ringbuffer *rt_ringbuffer_create(rt_uint16_t size) { @@ -451,9 +443,9 @@ exit: RTM_EXPORT(rt_ringbuffer_create); /** - * @brief Destroy a ringbuffer object, which is created by rt_ringbuffer_create() . + * @brief Destroy a ring buffer object, which is created by rt_ringbuffer_create() . * - * @param rb A pointer to the ringbuffer object. + * @param rb A pointer to the ring buffer object. */ void rt_ringbuffer_destroy(struct rt_ringbuffer *rb) { diff --git a/components/drivers/src/workqueue.c b/components/drivers/src/workqueue.c index 37733a1f65..60472d9ca4 100644 --- a/components/drivers/src/workqueue.c +++ b/components/drivers/src/workqueue.c @@ -7,7 +7,7 @@ * Date Author Notes * 2017-02-27 Bernard fix the re-work issue. * 2021-08-01 Meco Man remove rt_delayed_work_init() - * 2021-08-14 Jackistang add commets for function interface. + * 2021-08-14 Jackistang add comments for function interface. */ #include @@ -217,7 +217,7 @@ static void _delayed_work_timeout_handler(void *parameter) * @param stack_size The stack size for work queue thread. * @param priority The priority for work queue thread. * - * @return Return a pointer to workqueue object. When the return value is RT_NULL, it means the creation failed. + * @return Return a pointer to 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) { @@ -272,7 +272,7 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue) * @param work A pointer to work item object. * * @return RT_EOK Success. - * @return -RT_EBUSY This work item is been executing now. + * @return -RT_EBUSY This work item is executing. */ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work) { @@ -287,10 +287,10 @@ rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work) * * @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 tick) before it's been submitted to the work queue. + * @param time This work item will be delayed by time (unit: an OS ticks) before it's been submitted to the work queue. * * @return RT_EOK Success. - * @return -RT_EBUSY This work item is been executing now. + * @return -RT_EBUSY This work item is executing. * @return -RT_ERROR Time is invalid. */ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *work, rt_tick_t time) @@ -343,7 +343,7 @@ rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work * * @param work A pointer to work item object. * * @return RT_EOK Success. - * @return -RT_EBUSY This work item is been executing now. + * @return -RT_EBUSY This work item is executing. */ rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *work) { @@ -419,7 +419,7 @@ static struct rt_workqueue *sys_workq; * @param time This work item will be delayed by time (unit: an OS tick) before it's been submitted to system work queue. * * @return RT_EOK Success. - * @return -RT_EBUSY This work item is been executing now. + * @return -RT_EBUSY This work item is executing. * @return -RT_ERROR Time is invalid. */ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) @@ -433,7 +433,7 @@ rt_err_t rt_work_submit(struct rt_work *work, rt_tick_t time) * @param work A pointer to work item object. * * @return RT_EOK Success. - * @return -RT_EBUSY This work item is been executing now. + * @return -RT_EBUSY This work item is executing. */ rt_err_t rt_work_cancel(struct rt_work *work) { -- cgit v1.3.1 From 3de03a072e3145522546b46117e51e9e444e1b4e Mon Sep 17 00:00:00 2001 From: Jackistang Date: Wed, 18 Aug 2021 09:44:52 +0800 Subject: 修改 ringbuffer 和 workqueue 注释的语法 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(-) (limited to 'components/drivers/src') 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. -- cgit v1.3.1 From 4c6b4028e35814775fbeadb4fcc2d0a5b00a19b7 Mon Sep 17 00:00:00 2001 From: Jackistang Date: Wed, 18 Aug 2021 22:51:00 +0800 Subject: Update the comments for ringbuffer and workqueue. --- components/drivers/src/ringbuffer.c | 4 ++-- components/drivers/src/workqueue.c | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) (limited to 'components/drivers/src') diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c index a8233a7555..31eab4816c 100644 --- a/components/drivers/src/ringbuffer.c +++ b/components/drivers/src/ringbuffer.c @@ -29,7 +29,7 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb } /** - * @brief Initialize the ring buffer object with the given buffer. + * @brief Initialize the ring buffer object. * * @param rb A pointer to the ring buffer object. * @param pool A pointer to the buffer. @@ -415,7 +415,7 @@ RTM_EXPORT(rt_ringbuffer_reset); * * @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. + * @return Return a pointer to ring buffer object. When the return value is RT_NULL, it means this creation failed. */ struct rt_ringbuffer *rt_ringbuffer_create(rt_uint16_t size) { diff --git a/components/drivers/src/workqueue.c b/components/drivers/src/workqueue.c index 4a776ca485..b5d803472b 100644 --- a/components/drivers/src/workqueue.c +++ b/components/drivers/src/workqueue.c @@ -302,7 +302,7 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo } /** - * @brief Submit a work item to the work queue without delay. This work item will be executed 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. * * @param queue A pointer to the workqueue object. * @param work A pointer to the work item object. -- cgit v1.3.1