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