diff options
Diffstat (limited to 'components')
| -rw-r--r-- | components/drivers/src/completion.c | 26 |
1 files 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 <rthw.h> @@ -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) { |