From 96f773ffa9a66650e8e3ca0172f498d10f2eb247 Mon Sep 17 00:00:00 2001 From: chenyingchun0312 Date: Sun, 15 Aug 2021 21:27:14 +0800 Subject: 【doc】add the annotation of device-ipc completion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/src/completion.c | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/components/drivers/src/completion.c b/components/drivers/src/completion.c index b91ae3d6dc..eb44007915 100644 --- a/components/drivers/src/completion.c +++ b/components/drivers/src/completion.c @@ -15,6 +15,11 @@ #define RT_COMPLETED 1 #define RT_UNCOMPLETED 0 +/** + * @brief initialize the completion object + * + * @param completion the point of completion object + */ void rt_completion_init(struct rt_completion *completion) { rt_base_t level; @@ -27,6 +32,19 @@ void rt_completion_init(struct rt_completion *completion) } RTM_EXPORT(rt_completion_init); +/** + * @brief waitting for the completion done + * NOTE: We should not use this api when + * + * @param completion the point of completion object + * @param timeout is a timeout period (unit: an OS tick). If the completion is unavailable, the thread will wait for + * the completion 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. + */ rt_err_t rt_completion_wait(struct rt_completion *completion, rt_int32_t timeout) { @@ -94,6 +112,11 @@ __exit: } RTM_EXPORT(rt_completion_wait); +/** + * @brief indicate the completion has done + * + * @param completion the point of completion object + */ void rt_completion_done(struct rt_completion *completion) { rt_base_t level; -- cgit v1.3.1 From 7f2aaa210cea2c58d6fecf3d2ae57fca0b8a35cd Mon Sep 17 00:00:00 2001 From: chenyingchun0312 Date: Mon, 16 Aug 2021 13:10:26 +0800 Subject: 【doc】format drivers/src/completion.c MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/src/completion.c | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/components/drivers/src/completion.c b/components/drivers/src/completion.c index eb44007915..37fa514613 100644 --- a/components/drivers/src/completion.c +++ b/components/drivers/src/completion.c @@ -17,7 +17,7 @@ /** * @brief initialize the completion object - * + * * @param completion the point of completion object */ void rt_completion_init(struct rt_completion *completion) @@ -34,14 +34,14 @@ RTM_EXPORT(rt_completion_init); /** * @brief waitting for the completion done - * NOTE: We should not use this api when - * + * NOTE: We should not use this api when + * * @param completion the point of completion object * @param timeout is a timeout period (unit: an OS tick). If the completion is unavailable, the thread will wait for * the completion 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. */ @@ -114,7 +114,7 @@ RTM_EXPORT(rt_completion_wait); /** * @brief indicate the completion has done - * + * * @param completion the point of completion object */ void rt_completion_done(struct rt_completion *completion) -- cgit v1.3.1 From a6870449ba81179ac2d71f72392b9919e2f13477 Mon Sep 17 00:00:00 2001 From: chenyingchun0312 Date: Wed, 18 Aug 2021 14:10:50 +0800 Subject: 【doc】update completion.c comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/src/completion.c | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/components/drivers/src/completion.c b/components/drivers/src/completion.c index 37fa514613..09f51bb9df 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 @@ -16,9 +17,9 @@ #define RT_UNCOMPLETED 0 /** - * @brief initialize the completion object + * @brief This function will initialize a completion object. * - * @param completion the point of completion object + * @param completion is a pointer to a completion object. */ void rt_completion_init(struct rt_completion *completion) { @@ -33,17 +34,20 @@ void rt_completion_init(struct rt_completion *completion) RTM_EXPORT(rt_completion_init); /** - * @brief waitting for the completion done - * NOTE: We should not use this api when + * @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 the point of completion object - * @param timeout is a timeout period (unit: an OS tick). If the completion is unavailable, the thread will wait for - * the completion 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. + * @param completion is a pointer to a completion object. + * + * @param timeout is a timeout period (unit: an 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) @@ -113,9 +117,9 @@ __exit: RTM_EXPORT(rt_completion_wait); /** - * @brief indicate the completion has done + * @brief This function indicate a completion has done. * - * @param completion the point of completion object + * @param completion is a pointer to a completion object. */ void rt_completion_done(struct rt_completion *completion) { -- cgit v1.3.1 From 5e02709c5533b5741b7ae8eae4945c8c43f86beb Mon Sep 17 00:00:00 2001 From: chenyingchun0312 Date: Mon, 23 Aug 2021 18:52:31 +0800 Subject: 【doc】update completion.c comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- components/drivers/src/completion.c | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/components/drivers/src/completion.c b/components/drivers/src/completion.c index 09f51bb9df..f13718f9b3 100644 --- a/components/drivers/src/completion.c +++ b/components/drivers/src/completion.c @@ -39,15 +39,15 @@ RTM_EXPORT(rt_completion_init); * * @param completion is a pointer to a completion object. * - * @param timeout is a timeout period (unit: an OS ticks). If the completion is unavailable, the thread will wait for + * @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. + * @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. + * @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) @@ -117,7 +117,7 @@ __exit: RTM_EXPORT(rt_completion_wait); /** - * @brief This function indicate a completion has done. + * @brief This function indicates a completion has done. * * @param completion is a pointer to a completion object. */ -- cgit v1.3.1