Merge branch 'master' of https://github.com/RT-Thread/rt-thread into nuvoton

5 files changed, 213 insertions, 31 deletions

diff --git a/components/drivers/src/completion.c b/components/drivers/src/completion.c
index b91ae3d6dc..f13718f9b3 100644
--- a/components/drivers/src/completion.c
+++ b/components/drivers/src/completion.c
@@ -6,6 +6,7 @@
  * Change Logs:
  * Date           Author       Notes
  * 2012-09-30     Bernard      first version.
+ * 2021-08-18     chenyingchun add comments
  */
 
 #include <rthw.h>
@@ -15,6 +16,11 @@
 #define RT_COMPLETED    1
 #define RT_UNCOMPLETED  0
 
+/**
+ * @brief This function will initialize a completion object.
+ *
+ * @param completion is a pointer to a completion object.
+ */
 void rt_completion_init(struct rt_completion *completion)
 {
     rt_base_t level;
@@ -27,6 +33,22 @@ void rt_completion_init(struct rt_completion *completion)
 }
 RTM_EXPORT(rt_completion_init);
 
+/**
+ * @brief This function will wait for a completion, if the completion is unavailable, the thread shall wait for
+ *        the completion up to a specified time.
+ *
+ * @param completion is a pointer to a completion object.
+ *
+ * @param timeout is a timeout period (unit: OS ticks). If the completion is unavailable, the thread will wait for
+ *                the completion done up to the amount of time specified by the argument.
+ *                NOTE: Generally, we use the macro RT_WAITING_FOREVER to set this parameter, which means that when the
+ *                completion is unavailable, the thread will be waitting forever.
+ *
+ * @return Return the operation status. ONLY when the return value is RT_EOK, the operation is successful.
+ *         If the return value is any other values, it means that the completion wait failed.
+ *
+ * @warning This function can ONLY be called in the thread context. It MUST NOT be called in interrupt context.
+ */
 rt_err_t rt_completion_wait(struct rt_completion *completion,
                             rt_int32_t            timeout)
 {
@@ -94,6 +116,11 @@ __exit:
 }
 RTM_EXPORT(rt_completion_wait);
 
+/**
+ * @brief This function indicates a completion has done.
+ *
+ * @param completion is a pointer to a completion object.
+ */
 void rt_completion_done(struct rt_completion *completion)
 {
     rt_base_t level;
diff --git a/components/drivers/src/pipe.c b/components/drivers/src/pipe.c
index 7fa5eb067d..af90f13c6f 100644
--- a/components/drivers/src/pipe.c
+++ b/components/drivers/src/pipe.c
@@ -16,7 +16,7 @@
 #ifdef RT_USING_POSIX
 #include <dfs_file.h>
 #include <dfs_posix.h>
-#include <dfs_poll.h>
+#include <poll.h>
 #include <sys/ioctl.h>
 
 static int pipe_fops_open(struct dfs_fd *fd)
diff --git a/components/drivers/src/ringblk_buf.c b/components/drivers/src/ringblk_buf.c
index c6688b3d2b..b966da3d36 100644
--- a/components/drivers/src/ringblk_buf.c
+++ b/components/drivers/src/ringblk_buf.c
@@ -44,6 +44,8 @@ void rt_rbb_init(rt_rbb_t rbb, rt_uint8_t *buf, rt_size_t buf_size, rt_rbb_blk_t
 }
 RTM_EXPORT(rt_rbb_init);
 
+#ifdef RT_USING_HEAP
+
 /**
  * ring block buffer object create
  *
@@ -102,6 +104,8 @@ void rt_rbb_destroy(rt_rbb_t rbb)
 }
 RTM_EXPORT(rt_rbb_destroy);
 
+#endif
+
 static rt_rbb_blk_t find_empty_blk_in_set(rt_rbb_t rbb)
 {
     rt_size_t i;
diff --git a/components/drivers/src/ringbuffer.c b/components/drivers/src/ringbuffer.c
index 29de20b087..e33f533db0 100644
--- a/components/drivers/src/ringbuffer.c
+++ b/components/drivers/src/ringbuffer.c
@@ -8,6 +8,8 @@
  * 2012-09-30     Bernard      first version.
  * 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 comments for function interface.
  */
 
 #include <rtthread.h>
@@ -26,6 +28,13 @@ rt_inline enum rt_ringbuffer_state rt_ringbuffer_status(struct rt_ringbuffer *rb
     return RT_RINGBUFFER_HALFFULL;
 }
 
+/**
+ * @brief Initialize the ring buffer object.
+ *
+ * @param rb        A pointer to the ring buffer object.
+ * @param pool      A pointer to the buffer.
+ * @param size      The size of the buffer in bytes.
+ */
 void rt_ringbuffer_init(struct rt_ringbuffer *rb,
                         rt_uint8_t           *pool,
                         rt_int16_t            size)
@@ -44,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 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 data size we put into the ring buffer.
  */
 rt_size_t rt_ringbuffer_put(struct rt_ringbuffer *rb,
                             const rt_uint8_t     *ptr,
@@ -91,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
+ * @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.
  *
- * When the buffer is full, it will discard the old data.
+ * @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,
@@ -138,7 +157,8 @@ rt_size_t rt_ringbuffer_put_force(struct rt_ringbuffer *rb,
 
     if (length > space_length)
     {
-        rb->read_mirror = ~rb->read_mirror;
+        if (rb->write_index <= rb->read_index)
+            rb->read_mirror = ~rb->read_mirror;
         rb->read_index = rb->write_index;
     }
 
@@ -147,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 data from the ring buffer.
+ *
+ * @param rb            A pointer to the ring buffer.
+ * @param ptr           A pointer to the data buffer.
+ * @param length        The size of the data we want to 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,
@@ -194,7 +220,14 @@ rt_size_t rt_ringbuffer_get(struct rt_ringbuffer *rb,
 RTM_EXPORT(rt_ringbuffer_get);
 
 /**
- *  peak data from 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.
+ *
+ * @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)
 {
@@ -211,7 +244,7 @@ rt_size_t rt_ringbuffer_peak(struct rt_ringbuffer *rb, rt_uint8_t **ptr)
 
     *ptr = &rb->buffer_ptr[rb->read_index];
 
-    if(rb->buffer_size - rb->read_index > size)
+    if((rt_size_t)(rb->buffer_size - rb->read_index) > size)
     {
         rb->read_index += size;
         return size;
@@ -228,7 +261,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 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 put into the ring buffer.
+ *
+ * @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)
 {
@@ -256,9 +294,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
+ * @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 put into the ring buffer.
  *
- * When the buffer is full, it will discard one old data.
+ * @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)
 {
@@ -293,7 +334,13 @@ 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 byte from the 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    The ring buffer is empty.
+ * @return 1    Success
  */
 rt_size_t rt_ringbuffer_getchar(struct rt_ringbuffer *rb, rt_uint8_t *ch)
 {
@@ -303,7 +350,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)
@@ -321,7 +368,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 ring buffer in bytes.
+ *
+ * @param rb        The pointer to the ring buffer object.
+ *
+ * @return Return the size of data in the ring buffer in bytes.
  */
 rt_size_t rt_ringbuffer_data_len(struct rt_ringbuffer *rb)
 {
@@ -333,16 +384,22 @@ 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);
 
 /**
- * empty the rb
+ * @brief Reset the ring buffer object, and clear all contents in the buffer.
+ *
+ * @param rb        A pointer to the ring buffer object.
  */
 void rt_ringbuffer_reset(struct rt_ringbuffer *rb)
 {
@@ -357,7 +414,14 @@ RTM_EXPORT(rt_ringbuffer_reset);
 
 #ifdef RT_USING_HEAP
 
-struct rt_ringbuffer* rt_ringbuffer_create(rt_uint16_t size)
+/**
+ * @brief Create a ring buffer object with a given size.
+ *
+ * @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 this creation failed.
+ */
+struct rt_ringbuffer *rt_ringbuffer_create(rt_uint16_t size)
 {
     struct rt_ringbuffer *rb;
     rt_uint8_t *pool;
@@ -384,6 +448,11 @@ exit:
 }
 RTM_EXPORT(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.
+ */
 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 f195dad927..6dbb0da627 100644
--- a/components/drivers/src/workqueue.c
+++ b/components/drivers/src/workqueue.c
@@ -5,7 +5,9 @@
  *
  * Change Logs:
  * Date           Author       Notes
- * 2017-02-27     bernard      fix the re-work issue.
+ * 2017-02-27     Bernard      fix the re-work issue.
+ * 2021-08-01     Meco Man     remove rt_delayed_work_init()
+ * 2021-08-14     Jackistang   add comments for function interface.
  */
 
 #include <rthw.h>
@@ -208,6 +210,15 @@ static void _delayed_work_timeout_handler(void *parameter)
     }
 }
 
+/**
+ * @brief Create a work queue with a thread inside.
+ *
+ * @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 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)
 {
     struct rt_workqueue *queue = RT_NULL;
@@ -235,6 +246,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 the workqueue object.
+ *
+ * @return RT_EOK       Success.
+ */
 rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
 {
     RT_ASSERT(queue != RT_NULL);
@@ -247,6 +265,15 @@ rt_err_t rt_workqueue_destroy(struct rt_workqueue *queue)
     return RT_EOK;
 }
 
+/**
+ * @brief Submit a work item to the work queue without delay.
+ *
+ * @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.
+ */
 rt_err_t rt_workqueue_dowork(struct rt_workqueue *queue, struct rt_work *work)
 {
     RT_ASSERT(queue != RT_NULL);
@@ -255,6 +282,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.
+ *
+ * @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    The time parameter 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);
@@ -263,7 +301,15 @@ rt_err_t rt_workqueue_submit_work(struct rt_workqueue *queue, struct rt_work *wo
     return _workqueue_submit_work(queue, work, time);
 }
 
-rt_err_t rt_workqueue_critical_work(struct rt_workqueue *queue, struct rt_work *work)
+/**
+ * @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.
+ *
+ * @return RT_EOK   Success.
+ */
+rt_err_t rt_workqueue_urgent_work(struct rt_workqueue *queue, struct rt_work *work)
 {
     rt_base_t level;
     RT_ASSERT(queue != RT_NULL);
@@ -290,6 +336,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 the workqueue object.
+ * @param work      A pointer to the work item object.
+ *
+ * @return RT_EOK       Success.
+ * @return -RT_EBUSY    This work item is executing.
+ */
 rt_err_t rt_workqueue_cancel_work(struct rt_workqueue *queue, struct rt_work *work)
 {
     RT_ASSERT(work != RT_NULL);
@@ -297,6 +352,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 executing, this function will block until it is done.
+ *
+ * @param queue     A pointer to the workqueue object.
+ * @param work      A pointer to the 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);
@@ -315,6 +378,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 items in work queue.
+ *
+ * @param queue     A pointer to the workqueue object.
+ *
+ * @return RT_EOK       Success.
+ */
 rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue)
 {
     struct rt_work *work;
@@ -339,26 +409,38 @@ rt_err_t rt_workqueue_cancel_all_work(struct rt_workqueue *queue)
     return RT_EOK;
 }
 
-void rt_delayed_work_init(struct rt_delayed_work *work, void (*work_func)(struct rt_work *work,
-                          void *work_data), void *work_data)
-{
-    rt_work_init(&work->work, work_func, work_data);
-}
-
 #ifdef RT_USING_SYSTEM_WORKQUEUE
 static struct rt_workqueue *sys_workq;
 
+/**
+ * @brief Submit a work item to the system work queue with a delay.
+ *
+ * @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    The time parameter 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 the system work queue.
+ *
+ * @param work      A pointer to the work item object.
+ *
+ * @return RT_EOK       Success.
+ * @return -RT_EBUSY    This work item is executing.
+ */
 rt_err_t rt_work_cancel(struct rt_work *work)
 {
     return rt_workqueue_cancel_work(sys_workq, work);
 }
 
-int rt_work_sys_workqueue_init(void)
+static int rt_work_sys_workqueue_init(void)
 {
     if (sys_workq != RT_NULL)
         return RT_EOK;
@@ -370,5 +452,5 @@ int rt_work_sys_workqueue_init(void)
     return RT_EOK;
 }
 INIT_PREV_EXPORT(rt_work_sys_workqueue_init);
-#endif
-#endif
+#endif /* RT_USING_SYSTEM_WORKQUEUE */
+#endif /* RT_USING_HEAP */