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);