From 02331fd30d1f1ca8c886aac4db6c8c111987913c Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Mon, 17 May 2021 21:00:40 +0800 Subject: revert #3647 --- src/ipc.c | 42 ------------------------------------------ 1 file changed, 42 deletions(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index 111d724c23..27ee92e3fd 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -38,7 +38,6 @@ * event without pending * 2020-10-11 Meco Man add value overflow-check code * 2021-01-03 Meco Man add rt_mb_urgent() - * 2021-01-20 hupu fix priority inversion bug of mutex */ #include @@ -192,31 +191,6 @@ rt_inline rt_err_t rt_ipc_list_resume_all(rt_list_t *list) return RT_EOK; } -/** - * This function will get the highest priority from the specified - * list of threads - * - * @param list of the threads - * - * @return the highest priority - */ -rt_uint8_t rt_ipc_get_highest_priority(rt_list_t *list) -{ - struct rt_list_node *n; - struct rt_thread *sthread; - rt_uint8_t priority = RT_THREAD_PRIORITY_MAX - 1; - - for (n = list->next; n != list; n = n->next) - { - sthread = rt_list_entry(n, struct rt_thread, tlist); - - priority = priority < sthread->current_priority ? - priority : - sthread->current_priority; - } - return priority; -} - #ifdef RT_USING_SEMAPHORE /** * This function will initialize a semaphore and put it under control of @@ -855,7 +829,6 @@ rt_err_t rt_mutex_release(rt_mutex_t mutex) register rt_base_t temp; struct rt_thread *thread; rt_bool_t need_schedule; - rt_uint8_t max_priority_in_queue = RT_THREAD_PRIORITY_MAX - 1; /* parameter check */ RT_ASSERT(mutex != RT_NULL); @@ -917,21 +890,6 @@ rt_err_t rt_mutex_release(rt_mutex_t mutex) mutex->owner = thread; mutex->original_priority = thread->current_priority; - /* Priority adjustment occurs only when the following conditions - * are met simultaneously: - * 1.The type of mutex is RT_IPC_FLAG_FIFO; - * 2.The priority of the thread to be resumed is not equal to the - * highest priority in the queue; - */ - max_priority_in_queue = rt_ipc_get_highest_priority(&mutex->parent.suspend_thread); - if (mutex->parent.parent.flag == RT_IPC_FLAG_FIFO && - thread->current_priority != max_priority_in_queue) - { - rt_thread_control(thread, - RT_THREAD_CTRL_CHANGE_PRIORITY, - &(max_priority_in_queue)); - } - if(mutex->hold < RT_MUTEX_HOLD_MAX) { mutex->hold ++; -- cgit v1.3.1 From d9367468061113b31df5e3488dced157e1d0dabf Mon Sep 17 00:00:00 2001 From: tangyuxin Date: Fri, 28 May 2021 10:28:00 +0800 Subject: [kernel] Improve kernel stability --- src/ipc.c | 1 + src/thread.c | 8 ++++++++ 2 files changed, 9 insertions(+) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index 111d724c23..22e0f06bc6 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -124,6 +124,7 @@ rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t *list, break; default: + RT_ASSERT(0); break; } diff --git a/src/thread.c b/src/thread.c index 34e96077d1..e03c027eff 100644 --- a/src/thread.c +++ b/src/thread.c @@ -358,6 +358,8 @@ RTM_EXPORT(rt_thread_startup); */ rt_err_t rt_thread_detach(rt_thread_t thread) { + rt_base_t lock; + /* thread check */ RT_ASSERT(thread != RT_NULL); RT_ASSERT(rt_object_get_type((rt_object_t)thread) == RT_Object_Class_Thread); @@ -377,12 +379,18 @@ rt_err_t rt_thread_detach(rt_thread_t thread) /* release thread timer */ rt_timer_detach(&(thread->thread_timer)); + /* disable interrupt */ + lock = rt_hw_interrupt_disable(); + /* change stat */ thread->stat = RT_THREAD_CLOSE; /* detach thread object */ rt_object_detach((rt_object_t)thread); + /* enable interrupt */ + rt_hw_interrupt_enable(lock); + return RT_EOK; } RTM_EXPORT(rt_thread_detach); -- cgit v1.3.1 From 8b82b834826249dff299353da44188429d18dde2 Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Sun, 30 May 2021 11:43:44 +0800 Subject: [kernel] 增加rt_mutex_trytake MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- include/rtthread.h | 1 + src/ipc.c | 18 ++++++++++++++++-- 2 files changed, 17 insertions(+), 2 deletions(-) (limited to 'src/ipc.c') diff --git a/include/rtthread.h b/include/rtthread.h index 784b208a76..ccd2d147a8 100644 --- a/include/rtthread.h +++ b/include/rtthread.h @@ -322,6 +322,7 @@ rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag); rt_err_t rt_mutex_delete(rt_mutex_t mutex); rt_err_t rt_mutex_take(rt_mutex_t mutex, rt_int32_t time); +rt_err_t rt_mutex_trytake(rt_mutex_t mutex); rt_err_t rt_mutex_release(rt_mutex_t mutex); rt_err_t rt_mutex_control(rt_mutex_t mutex, int cmd, void *arg); #endif diff --git a/src/ipc.c b/src/ipc.c index 22e0f06bc6..6cd38b74ab 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -37,7 +37,8 @@ * 2020-07-29 Meco Man fix thread->event_set/event_info when received an * event without pending * 2020-10-11 Meco Man add value overflow-check code - * 2021-01-03 Meco Man add rt_mb_urgent() + * 2021-01-03 Meco Man implement rt_mb_urgent() + * 2021-05-30 Meco Man implement rt_mutex_trytake() * 2021-01-20 hupu fix priority inversion bug of mutex */ @@ -452,7 +453,7 @@ RTM_EXPORT(rt_sem_take); */ rt_err_t rt_sem_trytake(rt_sem_t sem) { - return rt_sem_take(sem, 0); + return rt_sem_take(sem, RT_WAITING_NO); } RTM_EXPORT(rt_sem_trytake); @@ -843,6 +844,19 @@ __again: } RTM_EXPORT(rt_mutex_take); +/** + * This function will try to take a mutex and immediately return + * + * @param mutex the mutex object + * + * @return the error code + */ +rt_err_t rt_mutex_trytake(rt_mutex_t mutex) +{ + return rt_mutex_take(mutex, RT_WAITING_NO); +} +RTM_EXPORT(rt_mutex_trytake); + /** * This function will release a mutex, if there are threads suspended on mutex, * it will be waked up. -- cgit v1.3.1 From 2b6762e85955a10e0150a3f32b869104a106acbd Mon Sep 17 00:00:00 2001 From: Meco Jianting Man <920369182@qq.com> Date: Sat, 5 Jun 2021 13:05:11 +0800 Subject: remove fix priority inversion bug of mutex --- src/ipc.c | 1 - 1 file changed, 1 deletion(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index 74b47df3b6..bda32dbf26 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -39,7 +39,6 @@ * 2020-10-11 Meco Man add value overflow-check code * 2021-01-03 Meco Man implement rt_mb_urgent() * 2021-05-30 Meco Man implement rt_mutex_trytake() - * 2021-01-20 hupu fix priority inversion bug of mutex */ #include -- cgit v1.3.1 From e019a57ff30b9fda5aa43fdc97eac5cca80bbc3b Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Thu, 10 Jun 2021 17:58:31 +0800 Subject: [kernel] 补充endif后缀注释(2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/ipc.c | 30 ++++++++++++++--------------- src/irq.c | 6 ++---- src/kservice.c | 60 +++++++++++++++++++++++++++++----------------------------- 3 files changed, 47 insertions(+), 49 deletions(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index bda32dbf26..c981aabe43 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -48,7 +48,7 @@ extern void (*rt_object_trytake_hook)(struct rt_object *object); extern void (*rt_object_take_hook)(struct rt_object *object); extern void (*rt_object_put_hook)(struct rt_object *object); -#endif +#endif /* RT_USING_HOOK */ /** * @addtogroup IPC @@ -93,7 +93,7 @@ rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t *list, { case RT_IPC_FLAG_FIFO: rt_list_insert_before(list, &(thread->tlist)); - break; + break; /* RT_IPC_FLAG_FIFO */ case RT_IPC_FLAG_PRIO: { @@ -121,7 +121,7 @@ rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t *list, if (n == list) rt_list_insert_before(list, &(thread->tlist)); } - break; + break;/* RT_IPC_FLAG_PRIO */ default: RT_ASSERT(0); @@ -319,7 +319,7 @@ rt_err_t rt_sem_delete(rt_sem_t sem) return RT_EOK; } RTM_EXPORT(rt_sem_delete); -#endif +#endif /* RT_USING_HEAP */ /** * This function will take a semaphore, if the semaphore is unavailable, the @@ -533,7 +533,7 @@ rt_err_t rt_sem_control(rt_sem_t sem, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_sem_control); -#endif /* end of RT_USING_SEMAPHORE */ +#endif /* RT_USING_SEMAPHORE */ #ifdef RT_USING_MUTEX /** @@ -659,7 +659,7 @@ rt_err_t rt_mutex_delete(rt_mutex_t mutex) return RT_EOK; } RTM_EXPORT(rt_mutex_delete); -#endif +#endif /* RT_USING_HEAP */ /** * This function will take a mutex, if the mutex is unavailable, the @@ -714,7 +714,7 @@ rt_err_t rt_mutex_take(rt_mutex_t mutex, rt_int32_t time) { #ifdef RT_USING_SIGNALS __again: -#endif /* end of RT_USING_SIGNALS */ +#endif /* RT_USING_SIGNALS */ /* The value of mutex is 1 in initial status. Therefore, if the * value is great than 0, it indicates the mutex is avaible. */ @@ -794,7 +794,7 @@ __again: #ifdef RT_USING_SIGNALS /* interrupt by signal, try it again */ if (thread->error == -RT_EINTR) goto __again; -#endif /* end of RT_USING_SIGNALS */ +#endif /* RT_USING_SIGNALS */ /* return error */ return thread->error; @@ -968,7 +968,7 @@ rt_err_t rt_mutex_control(rt_mutex_t mutex, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_mutex_control); -#endif /* end of RT_USING_MUTEX */ +#endif /* RT_USING_MUTEX */ #ifdef RT_USING_EVENT /** @@ -1084,7 +1084,7 @@ rt_err_t rt_event_delete(rt_event_t event) return RT_EOK; } RTM_EXPORT(rt_event_delete); -#endif +#endif /* RT_USING_HEAP */ /** * This function will send an event to the event object, if there are threads @@ -1361,7 +1361,7 @@ rt_err_t rt_event_control(rt_event_t event, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_event_control); -#endif /* end of RT_USING_EVENT */ +#endif /* RT_USING_EVENT */ #ifdef RT_USING_MAILBOX /** @@ -1512,7 +1512,7 @@ rt_err_t rt_mb_delete(rt_mailbox_t mb) return RT_EOK; } RTM_EXPORT(rt_mb_delete); -#endif +#endif /* RT_USING_HEAP */ /** * This function will send a mail to mailbox object. If the mailbox is full, @@ -1919,7 +1919,7 @@ rt_err_t rt_mb_control(rt_mailbox_t mb, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_mb_control); -#endif /* end of RT_USING_MAILBOX */ +#endif /* RT_USING_MAILBOX */ #ifdef RT_USING_MESSAGEQUEUE struct rt_mq_message @@ -2121,7 +2121,7 @@ rt_err_t rt_mq_delete(rt_mq_t mq) return RT_EOK; } RTM_EXPORT(rt_mq_delete); -#endif +#endif /* RT_USING_HEAP */ /** * This function will send a message to message queue object. If the message queue is full, @@ -2625,6 +2625,6 @@ rt_err_t rt_mq_control(rt_mq_t mq, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_mq_control); -#endif /* end of RT_USING_MESSAGEQUEUE */ +#endif /* RT_USING_MESSAGEQUEUE */ /**@}*/ diff --git a/src/irq.c b/src/irq.c index 65fc2ea5e0..e89b8504dc 100644 --- a/src/irq.c +++ b/src/irq.c @@ -39,9 +39,7 @@ void rt_interrupt_leave_sethook(void (*hook)(void)) { rt_interrupt_leave_hook = hook; } -#endif - -/* #define IRQ_DEBUG */ +#endif /* RT_USING_HOOK */ /** * @addtogroup Kernel @@ -53,7 +51,7 @@ void rt_interrupt_leave_sethook(void (*hook)(void)) #define rt_interrupt_nest rt_cpu_self()->irq_nest #else volatile rt_uint8_t rt_interrupt_nest = 0; -#endif +#endif /* RT_USING_SMP */ /** * This function will be invoked by BSP, when enter interrupt service routine diff --git a/src/kservice.c b/src/kservice.c index 7ed05b6651..c4bbdd9151 100644 --- a/src/kservice.c +++ b/src/kservice.c @@ -25,7 +25,7 @@ #ifdef RT_USING_MODULE #include -#endif +#endif /* RT_USING_MODULE */ /* use precision */ #define RT_PRINTF_PRECISION @@ -194,7 +194,7 @@ RT_WEAK void *rt_memset(void *s, int c, rt_ubase_t count) #undef LBLOCKSIZE #undef UNALIGNED #undef TOO_SMALL -#endif +#endif /* RT_KSERVICE_USING_TINY_SIZE */ } RTM_EXPORT(rt_memset); @@ -277,7 +277,7 @@ RT_WEAK void *rt_memcpy(void *dst, const void *src, rt_ubase_t count) #undef BIGBLOCKSIZE #undef LITTLEBLOCKSIZE #undef TOO_SMALL -#endif +#endif /* RT_KSERVICE_USING_TINY_SIZE */ } RTM_EXPORT(rt_memcpy); @@ -509,7 +509,7 @@ rt_size_t rt_strlen(const char *s) } RTM_EXPORT(rt_strlen); -#endif /*RT_KSERVICE_USING_STDLIB*/ +#endif /* RT_KSERVICE_USING_STDLIB */ #ifdef RT_USING_HEAP /** @@ -535,7 +535,7 @@ RTM_EXPORT(rt_strdup); #if defined(__CC_ARM) || defined(__CLANG_ARM) char *strdup(const char *s) __attribute__((alias("rt_strdup"))); #endif -#endif +#endif /* RT_USING_HEAP */ /** * This function will show the version of rt-thread rtos @@ -591,7 +591,7 @@ rt_inline int divide(long *n, int base) return res; } -#endif +#endif /* RT_PRINTF_LONGLONG */ rt_inline int skip_atoi(const char **s) { @@ -617,7 +617,7 @@ static char *print_number(char *buf, long long num, #else long num, -#endif +#endif /* RT_PRINTF_LONGLONG */ int base, int s, int precision, @@ -629,18 +629,18 @@ static char *print_number(char *buf, long long num, #else long num, -#endif +#endif /* RT_PRINTF_LONGLONG */ int base, int s, int type) -#endif +#endif /* RT_PRINTF_PRECISION */ { char c, sign; #ifdef RT_PRINTF_LONGLONG char tmp[32]; #else char tmp[16]; -#endif +#endif /* RT_PRINTF_LONGLONG */ int precision_bak = precision; const char *digits; static const char small_digits[] = "0123456789abcdef"; @@ -679,7 +679,7 @@ static char *print_number(char *buf, else if (base == 8) size--; } -#endif +#endif /* RT_PRINTF_SPECIAL */ i = 0; if (num == 0) @@ -696,7 +696,7 @@ static char *print_number(char *buf, size -= precision; #else size -= i; -#endif +#endif /* RT_PRINTF_PRECISION */ if (!(type & (ZEROPAD | LEFT))) { @@ -742,7 +742,7 @@ static char *print_number(char *buf, ++ buf; } } -#endif +#endif /* RT_PRINTF_SPECIAL */ /* no align to the left */ if (!(type & LEFT)) @@ -762,7 +762,7 @@ static char *print_number(char *buf, *buf = '0'; ++ buf; } -#endif +#endif /* RT_PRINTF_PRECISION */ /* put number in the temporary buffer */ while (i-- > 0 && (precision_bak != 0)) @@ -791,7 +791,7 @@ rt_int32_t rt_vsnprintf(char *buf, unsigned long long num; #else rt_uint32_t num; -#endif +#endif /* RT_PRINTF_LONGLONG */ int i, len; char *str, *end, c; const char *s; @@ -803,7 +803,7 @@ rt_int32_t rt_vsnprintf(char *buf, #ifdef RT_PRINTF_PRECISION int precision; /* min. # of digits for integers and max for a string */ -#endif +#endif /* RT_PRINTF_PRECISION */ str = buf; end = buf + size; @@ -870,14 +870,14 @@ rt_int32_t rt_vsnprintf(char *buf, } if (precision < 0) precision = 0; } -#endif +#endif /* RT_PRINTF_PRECISION */ /* get the conversion qualifier */ qualifier = 0; #ifdef RT_PRINTF_LONGLONG if (*fmt == 'h' || *fmt == 'l' || *fmt == 'L') #else if (*fmt == 'h' || *fmt == 'l') -#endif +#endif /* RT_PRINTF_LONGLONG */ { qualifier = *fmt; ++ fmt; @@ -887,7 +887,7 @@ rt_int32_t rt_vsnprintf(char *buf, qualifier = 'L'; ++ fmt; } -#endif +#endif /* RT_PRINTF_LONGLONG */ } /* the default base */ @@ -925,7 +925,7 @@ rt_int32_t rt_vsnprintf(char *buf, for (len = 0; (len != field_width) && (s[len] != '\0'); len++); #ifdef RT_PRINTF_PRECISION if (precision > 0 && len > precision) len = precision; -#endif +#endif /* RT_PRINTF_PRECISION */ if (!(flags & LEFT)) { @@ -964,7 +964,7 @@ rt_int32_t rt_vsnprintf(char *buf, str = print_number(str, end, (long)va_arg(args, void *), 16, field_width, flags); -#endif +#endif /* RT_PRINTF_PRECISION */ continue; case '%': @@ -1010,7 +1010,7 @@ rt_int32_t rt_vsnprintf(char *buf, else if (qualifier == 'l') #else if (qualifier == 'l') -#endif +#endif /* RT_PRINTF_LONGLONG */ { num = va_arg(args, rt_uint32_t); if (flags & SIGN) num = (rt_int32_t)num; @@ -1029,7 +1029,7 @@ rt_int32_t rt_vsnprintf(char *buf, str = print_number(str, end, num, base, field_width, precision, flags); #else str = print_number(str, end, num, base, field_width, flags); -#endif +#endif /* RT_PRINTF_PRECISION */ } if (size > 0) @@ -1152,7 +1152,7 @@ rt_device_t rt_console_set_device(const char *name) return old_device; } RTM_EXPORT(rt_console_set_device); -#endif +#endif /* RT_USING_DEVICE */ RT_WEAK void rt_hw_console_output(const char *str) { @@ -1184,7 +1184,7 @@ void rt_kputs(const char *str) } #else rt_hw_console_output(str); -#endif +#endif /* RT_USING_DEVICE */ } /** @@ -1222,11 +1222,11 @@ RT_WEAK void rt_kprintf(const char *fmt, ...) } #else rt_hw_console_output(rt_log_buf); -#endif +#endif /* RT_USING_DEVICE */ va_end(args); } RTM_EXPORT(rt_kprintf); -#endif +#endif /* RT_USING_CONSOLE */ #ifdef RT_USING_HEAP /** @@ -1292,7 +1292,7 @@ void rt_free_align(void *ptr) rt_free(real_ptr); } RTM_EXPORT(rt_free_align); -#endif +#endif /* RT_USING_HEAP */ #ifndef RT_USING_CPU_FFS const rt_uint8_t __lowest_bit_bitmap[] = @@ -1340,7 +1340,7 @@ int __rt_ffs(int value) return __lowest_bit_bitmap[(value & 0xff000000) >> 24] + 25; } -#endif +#endif /* RT_USING_CPU_FFS */ #ifdef RT_DEBUG /* RT_ASSERT(EX)'s hook */ @@ -1377,7 +1377,7 @@ void rt_assert_handler(const char *ex_string, const char *func, rt_size_t line) dlmodule_exit(-1); } else -#endif +#endif /*RT_USING_MODULE*/ { rt_kprintf("(%s) assertion failed at function:%s, line number:%d \n", ex_string, func, line); while (dummy == 0); -- cgit v1.3.1 From ec3c1d4d0085c57d996a5c6acc21e7dbde85b30f Mon Sep 17 00:00:00 2001 From: 杨澄 <36236188+Eureka1024@users.noreply.github.com> Date: Wed, 23 Jun 2021 21:23:07 +0800 Subject: [kernel] Fix comment error for rt_mutex_detach(). --- src/ipc.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index c981aabe43..959f0fb522 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -588,7 +588,7 @@ rt_err_t rt_mutex_detach(rt_mutex_t mutex) /* wakeup all suspended threads */ rt_ipc_list_resume_all(&(mutex->parent.suspend_thread)); - /* detach semaphore object */ + /* detach mutex object */ rt_object_detach(&(mutex->parent.parent)); return RT_EOK; -- cgit v1.3.1 From edcdd126edf86b9990e15449ab69c8554da9e274 Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Wed, 7 Jul 2021 03:30:01 +0800 Subject: [kernel][ipc] 移除mutex RT_IPC_FLAG_FIFO 功能 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/ipc.c | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index 959f0fb522..6a038cd2b6 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -548,6 +548,8 @@ RTM_EXPORT(rt_sem_control); */ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag) { + (void)flag; + /* parameter check */ RT_ASSERT(mutex != RT_NULL); @@ -562,8 +564,8 @@ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag) mutex->original_priority = 0xFF; mutex->hold = 0; - /* set flag */ - mutex->parent.parent.flag = flag; + /* set flag and it can only be RT_IPC_FLAG_PRIO */ + mutex->parent.parent.flag = RT_IPC_FLAG_PRIO; return RT_EOK; } @@ -609,6 +611,7 @@ RTM_EXPORT(rt_mutex_detach); rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag) { struct rt_mutex *mutex; + (void)flag; RT_DEBUG_NOT_IN_INTERRUPT; @@ -625,8 +628,8 @@ rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag) mutex->original_priority = 0xFF; mutex->hold = 0; - /* set flag */ - mutex->parent.parent.flag = flag; + /* set flag and it can only be RT_IPC_FLAG_PRIO */ + mutex->parent.parent.flag = RT_IPC_FLAG_PRIO; return mutex; } -- cgit v1.3.1 From 6e334416e3c855ef17a2a59eba816408ac296a75 Mon Sep 17 00:00:00 2001 From: Meco Man <920369182@qq.com> Date: Wed, 7 Jul 2021 10:16:49 +0800 Subject: [ipc][mutex] 补充注释 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/ipc.c | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index 6a038cd2b6..6bc9c079b9 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -564,7 +564,7 @@ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag) mutex->original_priority = 0xFF; mutex->hold = 0; - /* set flag and it can only be RT_IPC_FLAG_PRIO */ + /* flag can only be RT_IPC_FLAG_PRIO. RT_IPC_FLAG_FIFO cannot solve the unbounded priority inversion problem */ mutex->parent.parent.flag = RT_IPC_FLAG_PRIO; return RT_EOK; @@ -628,7 +628,7 @@ rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag) mutex->original_priority = 0xFF; mutex->hold = 0; - /* set flag and it can only be RT_IPC_FLAG_PRIO */ + /* flag can only be RT_IPC_FLAG_PRIO. RT_IPC_FLAG_FIFO cannot solve the unbounded priority inversion problem */ mutex->parent.parent.flag = RT_IPC_FLAG_PRIO; return mutex; -- cgit v1.3.1 From 9f3e349f69c66fb27496492d0f0c3cefa0bb891b Mon Sep 17 00:00:00 2001 From: chenjh Date: Fri, 9 Jul 2021 10:54:51 +0800 Subject: [comment] Optimize the comment for ipc --- src/ipc.c | 1079 ++++++++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 848 insertions(+), 231 deletions(-) (limited to 'src/ipc.c') diff --git a/src/ipc.c b/src/ipc.c index 6bc9c079b9..8acfd831d7 100755 --- a/src/ipc.c +++ b/src/ipc.c @@ -57,11 +57,16 @@ extern void (*rt_object_put_hook)(struct rt_object *object); /**@{*/ /** - * This function will initialize an IPC object + * @brief This function will initialize an IPC object, such as semaphore, mutex, messagequeue and mailbox. * - * @param ipc the IPC object + * @note Executing this function will complete an initialization of the suspend thread list of the ipc object. * - * @return the operation status, RT_EOK on successful + * @param ipc is a pointer to the IPC object. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * When the return value is any other values, it means the initialization failed. + * + * @warning This function can be called from all IPC initialization and creation. */ rt_inline rt_err_t rt_ipc_object_init(struct rt_ipc_object *ipc) { @@ -71,16 +76,35 @@ rt_inline rt_err_t rt_ipc_object_init(struct rt_ipc_object *ipc) return RT_EOK; } + /** - * This function will suspend a thread to a specified list. IPC object or some - * double-queue object (mailbox etc.) contains this kind of list. + * @brief This function will suspend a thread to a IPC object list. + * + * @param list is a pointer to a suspended thread list of the IPC object. + * + * @param thread is a pointer to the thread object to be suspended. + * + * @param flag is a flag for the thread object to be suspended. It determines how the thread is suspended. + * The flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. + * + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to use + * RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this semaphore will become non-real-time threads. * - * @param list the IPC suspended thread list - * @param thread the thread object to be suspended - * @param flag the IPC object flag, - * which shall be RT_IPC_FLAG_FIFO/RT_IPC_FLAG_PRIO. + * @return Return the operation status. When the return value is RT_EOK, the function is successfully executed. + * When the return value is any other values, it means the initialization failed. * - * @return the operation status, RT_EOK on successful + * @warning This function can ONLY be called in the thread context, you can use RT_DEBUG_IN_THREAD_CONTEXT to + * check the context. + * In addition, this function is generally called by the following functions: + * rt_sem_take(), rt_mutex_take(), rt_event_recv(), rt_mb_send_wait(), + * rt_mb_recv(), rt_mq_recv(), rt_mq_send_wait() */ rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t *list, struct rt_thread *thread, @@ -131,14 +155,25 @@ rt_inline rt_err_t rt_ipc_list_suspend(rt_list_t *list, return RT_EOK; } + /** - * This function will resume the first thread in the list of a IPC object: - * - remove the thread from suspend queue of IPC object - * - put the thread into system ready queue + * @brief This function will resume a thread. + * + * @note This function will resume the first thread in the list of a IPC object. + * 1. remove the thread from suspend queue of a IPC object. + * 2. put the thread into system ready queue. + * + * By contrast, the rt_ipc_list_resume_all() function will resume all suspended threads + * in the list of a IPC object. + * + * @param list is a pointer to a suspended thread list of the IPC object. * - * @param list the thread list + * @return Return the operation status. When the return value is RT_EOK, the function is successfully executed. + * When the return value is any other values, it means this operation failed. * - * @return the operation status, RT_EOK on successful + * @warning This function is generally called by the following functions: + * rt_sem_release(), rt_mutex_release(), rt_mb_send_wait(), rt_mq_send_wait(), + * rt_mb_urgent(), rt_mb_recv(), rt_mq_urgent(), rt_mq_recv(), */ rt_inline rt_err_t rt_ipc_list_resume(rt_list_t *list) { @@ -155,13 +190,19 @@ rt_inline rt_err_t rt_ipc_list_resume(rt_list_t *list) return RT_EOK; } + /** - * This function will resume all suspended threads in a list, including - * suspend list of IPC object and private list of mailbox etc. + * @brief This function will resume all suspended threads in the IPC object list, + * including the suspended list of IPC object, and private list of mailbox etc. + * + * @note This function will resume all threads in the IPC object list. + * By contrast, the rt_ipc_list_resume() function will resume a suspended thread in the list of a IPC object. * - * @param list of the threads to resume + * @param list is a pointer to a suspended thread list of the IPC object. + * + * @return Return the operation status. When the return value is RT_EOK, the function is successfully executed. + * When the return value is any other values, it means this operation failed. * - * @return the operation status, RT_EOK on successful */ rt_inline rt_err_t rt_ipc_list_resume_all(rt_list_t *list) { @@ -193,17 +234,51 @@ rt_inline rt_err_t rt_ipc_list_resume_all(rt_list_t *list) return RT_EOK; } +/**@}*/ + #ifdef RT_USING_SEMAPHORE /** - * This function will initialize a semaphore and put it under control of - * resource management. + * @addtogroup semaphore + */ + +/**@{*/ +/** + * @brief This function will initialize a static semaphore object. + * + * @note For the static semaphore object, its memory space is allocated by the compiler during compiling, + * and shall placed on the read-write data segment or on the uninitialized data segment. + * By contrast, the rt_sem_create() function will allocate memory space automatically and initialize + * the semaphore. + * + * @see rt_sem_create() + * + * @param sem is a pointer to the semaphore to initialize. It is assumed that storage for the semaphore will be + * allocated in your application. * - * @param sem the semaphore object - * @param name the name of semaphore - * @param value the initial value of semaphore - * @param flag the flag of semaphore + * @param name is a pointer to the name you would like to give the semaphore. * - * @return the operation status, RT_EOK on successful + * @param value is the initial value for the semaphore. + * If used to share resources, you should initialize the value as the number of available resources. + * If used to signal the occurrence of an event, you should initialize the value as 0. + * + * @param flag is the semaphore flag, which determines the queuing way of how multiple threads wait + * when the semaphore is not available. + * The semaphore flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. + * + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this semaphore will become non-real-time threads. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it represents the initialization failed. + * + * @warning This function can ONLY be called from threads. */ rt_err_t rt_sem_init(rt_sem_t sem, const char *name, @@ -229,14 +304,24 @@ rt_err_t rt_sem_init(rt_sem_t sem, } RTM_EXPORT(rt_sem_init); + /** - * This function will detach a semaphore from resource management + * @brief This function will detach a static semaphore object. + * + * @note This function is used to detach a static semaphore object which is initialized by rt_sem_init() function. + * By contrast, the rt_sem_delete() function will delete a semaphore object. + * When the semaphore is successfully detached, it will resume all suspended threads in the semaphore list. * - * @param sem the semaphore object + * @see rt_sem_delete() * - * @return the operation status, RT_EOK on successful + * @param sem is a pointer to a semaphore object to be detached. * - * @see rt_sem_delete + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it means that the semaphore detach failed. + * + * @warning This function can ONLY detach a static semaphore initialized by the rt_sem_init() function. + * If the semaphore is created by the rt_sem_create() function, you MUST NOT USE this function to detach it, + * ONLY USE the rt_sem_delete() function to complete the deletion. */ rt_err_t rt_sem_detach(rt_sem_t sem) { @@ -257,15 +342,36 @@ RTM_EXPORT(rt_sem_detach); #ifdef RT_USING_HEAP /** - * This function will create a semaphore from system resource + * @brief Creating a semaphore object. + * + * @note For the semaphore object, its memory space is allocated automatically. + * By contrast, the rt_sem_init() function will initialize a static semaphore object. + * + * @see rt_sem_init() + * + * @param name is a pointer to the name you would like to give the semaphore. + * + * @param value is the initial value for the semaphore. + * If used to share resources, you should initialize the value as the number of available resources. + * If used to signal the occurrence of an event, you should initialize the value as 0. * - * @param name the name of semaphore - * @param value the initial value of semaphore - * @param flag the flag of semaphore + * @param flag is the semaphore flag, which determines the queuing way of how multiple threads wait + * when the semaphore is not available. + * The semaphore flag can be ONE of the following values: * - * @return the created semaphore, RT_NULL on error happen + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. * - * @see rt_sem_init + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this semaphore will become non-real-time threads. + * + * @return Return a pointer to the semaphore object. When the return value is RT_NULL, it means the creation failed. + * + * @warning This function can NOT be called in interrupt context. You can use macor RT_DEBUG_NOT_IN_INTERRUPT to check it. */ rt_sem_t rt_sem_create(const char *name, rt_uint32_t value, rt_uint8_t flag) { @@ -292,14 +398,24 @@ rt_sem_t rt_sem_create(const char *name, rt_uint32_t value, rt_uint8_t flag) } RTM_EXPORT(rt_sem_create); + /** - * This function will delete a semaphore object and release the memory + * @brief This function will delete a semaphore object and release the memory space. * - * @param sem the semaphore object + * @note This function is used to delete a semaphore object which is created by the rt_sem_create() function. + * By contrast, the rt_sem_detach() function will detach a static semaphore object. + * When the semaphore is successfully deleted, it will resume all suspended threads in the semaphore list. * - * @return the error code + * @see rt_sem_detach() * - * @see rt_sem_detach + * @param sem is a pointer to a semaphore object to be deleted. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the semaphore detach failed. + * + * @warning This function can ONLY delete a semaphore initialized by the rt_sem_create() function. + * If the semaphore is initialized by the rt_sem_init() function, you MUST NOT USE this function to delete it, + * ONLY USE the rt_sem_detach() function to complete the detachment. */ rt_err_t rt_sem_delete(rt_sem_t sem) { @@ -321,14 +437,29 @@ rt_err_t rt_sem_delete(rt_sem_t sem) RTM_EXPORT(rt_sem_delete); #endif /* RT_USING_HEAP */ + /** - * This function will take a semaphore, if the semaphore is unavailable, the - * thread shall wait for a specified time. + * @brief This function will take a semaphore, if the semaphore is unavailable, the thread shall wait for + * the semaphore up to a specified time. + * + * @note When this function is called, the count value of the sem->value will decrease 1 until it is equal to 0. + * When the sem->value is 0, it means that the semaphore is unavailable. At this time, it will suspend the + * thread preparing to take the semaphore. + * On the contrary, the rt_sem_release() function will increase the count value of sem->value by 1 each time. * - * @param sem the semaphore object - * @param time the waiting time + * @see rt_sem_trytake() * - * @return the error code + * @param sem is a pointer to a semaphore object. + * + * @param time is a timeout period (unit: an OS tick). If the semaphore is unavailable, the thread will wait for + * the semaphore 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 + * semaphore 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 semaphore take failed. + * + * @warning This function can ONLY be called in the thread context. It MUST NOT BE called in interrupt context. */ rt_err_t rt_sem_take(rt_sem_t sem, rt_int32_t time) { @@ -418,12 +549,20 @@ rt_err_t rt_sem_take(rt_sem_t sem, rt_int32_t time) } RTM_EXPORT(rt_sem_take); + /** - * This function will try to take a semaphore and immediately return + * @brief This function will try to take a semaphore, if the semaphore is unavailable, the thread returns immediately. * - * @param sem the semaphore object + * @note This function is very similar to the rt_sem_take() function, when the semaphore is not available, + * the rt_sem_trytake() function will return immediately without waiting for a timeout. + * In other words, rt_sem_trytake(sem) has the same effect as rt_sem_take(sem, 0). * - * @return the error code + * @see rt_sem_take() + * + * @param sem is a pointer to a semaphore object. + * + * @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 semaphore take failed. */ rt_err_t rt_sem_trytake(rt_sem_t sem) { @@ -431,13 +570,18 @@ rt_err_t rt_sem_trytake(rt_sem_t sem) } RTM_EXPORT(rt_sem_trytake); + /** - * This function will release a semaphore, if there are threads suspended on - * semaphore, it will be waked up. + * @brief This function will release a semaphore. If there is thread suspended on the semaphore, it will get resumed. + * + * @note If there are threads suspended on this semaphore, the first thread in the list of this semaphore object + * will be resumed, and a thread scheduling (rt_schedule) will be executed. + * If no threads are suspended on this semaphore, the count value sem->value of this semaphore will increase by 1. * - * @param sem the semaphore object + * @param sem is a pointer to a semaphore object. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the semaphore release failed. */ rt_err_t rt_sem_release(rt_sem_t sem) { @@ -490,14 +634,20 @@ rt_err_t rt_sem_release(rt_sem_t sem) } RTM_EXPORT(rt_sem_release); + /** - * This function can get or set some extra attributions of a semaphore object. + * @brief This function will set some extra attributions of a semaphore object. + * + * @note Currently this function only supports the RT_IPC_CMD_RESET command to reset the semaphore. + * + * @param sem is a pointer to a semaphore object. + * + * @param cmd is a command word used to configure some attributions of the semaphore. * - * @param sem the semaphore object - * @param cmd the execution command - * @param arg the execution argument + * @param arg is the argument of the function to execute the command. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that this function failed to execute. */ rt_err_t rt_sem_control(rt_sem_t sem, int cmd, void *arg) { @@ -533,18 +683,41 @@ rt_err_t rt_sem_control(rt_sem_t sem, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_sem_control); + +/**@}*/ #endif /* RT_USING_SEMAPHORE */ #ifdef RT_USING_MUTEX /** - * This function will initialize a mutex and put it under control of resource - * management. + * @addtogroup mutex + */ + +/**@{*/ + +/** + * @brief Initialize a static mutex object. + * + * @note For the static mutex object, its memory space is allocated by the compiler during compiling, + * and shall placed on the read-write data segment or on the uninitialized data segment. + * By contrast, the rt_mutex_create() function will automatically allocate memory space + * and initialize the mutex. * - * @param mutex the mutex object - * @param name the name of mutex - * @param flag the flag of mutex + * @see rt_mutex_create() * - * @return the operation status, RT_EOK on successful + * @param mutex is a pointer to the mutex to initialize. It is assumed that storage for the mutex will be + * allocated in your application. + * + * @param name is a pointer to the name that given to the mutex. + * + * @param flag is the mutex flag, which determines the queuing way of how multiple threads wait + * when the mutex is not available. + * NOTE: The mutex flag can ONLY be RT_IPC_FLAG_PRIO. Using RT_IPC_FLAG_FIFO will seriously affect + * the real-time performance of the system. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it represents the initialization failed. + * + * @warning This function can ONLY be called from threads. */ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag) { @@ -571,14 +744,24 @@ rt_err_t rt_mutex_init(rt_mutex_t mutex, const char *name, rt_uint8_t flag) } RTM_EXPORT(rt_mutex_init); + /** - * This function will detach a mutex from resource management + * @brief This function will detach a static mutex object. * - * @param mutex the mutex object + * @note This function is used to detach a static mutex object which is initialized by rt_mutex_init() function. + * By contrast, the rt_mutex_delete() function will delete a mutex object. + * When the mutex is successfully detached, it will resume all suspended threads in the mutex list. * - * @return the operation status, RT_EOK on successful + * @see rt_mutex_delete() * - * @see rt_mutex_delete + * @param mutex is a pointer to a mutex object to be detached. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it means that the mutex detach failed. + * + * @warning This function can ONLY detach a static mutex initialized by the rt_mutex_init() function. + * If the mutex is created by the rt_mutex_create() function, you MUST NOT USE this function to detach it, + * ONLY USE the rt_mutex_delete() function to complete the deletion. */ rt_err_t rt_mutex_detach(rt_mutex_t mutex) { @@ -599,14 +782,23 @@ RTM_EXPORT(rt_mutex_detach); #ifdef RT_USING_HEAP /** - * This function will create a mutex from system resource + * @brief This function will create a mutex object. + * + * @note For the mutex object, its memory space is automatically allocated. + * By contrast, the rt_mutex_init() function will initialize a static mutex object. + * + * @see rt_mutex_init() * - * @param name the name of mutex - * @param flag the flag of mutex + * @param name is a pointer to the name that given to the mutex. * - * @return the created mutex, RT_NULL on error happen + * @param flag is the mutex flag, which determines the queuing way of how multiple threads wait + * when the mutex is not available. + * NOTE: The mutex flag can ONLY be RT_IPC_FLAG_PRIO. Using RT_IPC_FLAG_FIFO will seriously affect + * the real-time performance of the system. * - * @see rt_mutex_init + * @return Return a pointer to the mutex object. When the return value is RT_NULL, it means the creation failed. + * + * @warning This function can ONLY be called from threads. */ rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag) { @@ -635,14 +827,24 @@ rt_mutex_t rt_mutex_create(const char *name, rt_uint8_t flag) } RTM_EXPORT(rt_mutex_create); + /** - * This function will delete a mutex object and release the memory + * @brief This function will delete a mutex object and release this memory space. + * + * @note This function is used to delete a mutex object which is created by the rt_mutex_create() function. + * By contrast, the rt_mutex_detach() function will detach a static mutex object. + * When the mutex is successfully deleted, it will resume all suspended threads in the mutex list. + * + * @see rt_mutex_detach() * - * @param mutex the mutex object + * @param mutex is a pointer to a mutex object to be deleted. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mutex detach failed. * - * @see rt_mutex_detach + * @warning This function can ONLY delete a mutex initialized by the rt_mutex_create() function. + * If the mutex is initialized by the rt_mutex_init() function, you MUST NOT USE this function to delete it, + * ONLY USE the rt_mutex_detach() function to complete the detachment. */ rt_err_t rt_mutex_delete(rt_mutex_t mutex) { @@ -664,14 +866,29 @@ rt_err_t rt_mutex_delete(rt_mutex_t mutex) RTM_EXPORT(rt_mutex_delete); #endif /* RT_USING_HEAP */ + /** - * This function will take a mutex, if the mutex is unavailable, the - * thread shall wait for a specified time. + * @brief This function will take a mutex, if the mutex is unavailable, the thread shall wait for + * the mutex up to a specified time. + * + * @note When this function is called, the count value of the sem->value will decrease 1 until it is equal to 0. + * When the sem->value is 0, it means that the mutex is unavailable. At this time, it will suspend the + * thread preparing to take the mutex. + * On the contrary, the rt_sem_release() function will increase the count value of sem->value by 1 each time. + * + * @see rt_mutex_trytake() + * + * @param mutex is a pointer to a mutex object. * - * @param mutex the mutex object - * @param time the waiting time + * @param time is a timeout period (unit: an OS tick). If the mutex is unavailable, the thread will wait for + * the mutex up to the amount of time specified by the argument. + * NOTE: Generally, we set this parameter to RT_WAITING_FOREVER, which means that when the mutex is unavailable, + * the thread will be waitting forever. * - * @return the error code + * @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 mutex take failed. + * + * @warning This function can ONLY be called in the thread context. It MUST NOT BE called in interrupt context. */ rt_err_t rt_mutex_take(rt_mutex_t mutex, rt_int32_t time) { @@ -821,12 +1038,21 @@ __again: } RTM_EXPORT(rt_mutex_take); + /** - * This function will try to take a mutex and immediately return + * @brief This function will try to take a mutex, if the mutex is unavailable, the thread returns immediately. + * + * @note This function is very similar to the rt_mutex_take() function, when the mutex is not available, + * except that rt_mutex_trytake() will return immediately without waiting for a timeout + * when the mutex is not available. + * In other words, rt_mutex_trytake(mutex) has the same effect as rt_mutex_take(mutex, 0). + * + * @see rt_mutex_take() * - * @param mutex the mutex object + * @param mutex is a pointer to a mutex object. * - * @return the error code + * @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 mutex take failed. */ rt_err_t rt_mutex_trytake(rt_mutex_t mutex) { @@ -834,13 +1060,18 @@ rt_err_t rt_mutex_trytake(rt_mutex_t mutex) } RTM_EXPORT(rt_mutex_trytake); + /** - * This function will release a mutex, if there are threads suspended on mutex, - * it will be waked up. + * @brief This function will release a mutex. If there is thread suspended on the mutex, the thread will be resumed. + * + * @note If there are threads suspended on this mutex, the first thread in the list of this mutex object + * will be resumed, and a thread scheduling (rt_schedule) will be executed. + * If no threads are suspended on this mutex, the count value mutex->value of this mutex will increase by 1. * - * @param mutex the mutex object + * @param mutex is a pointer to a mutex object. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mutex release failed. */ rt_err_t rt_mutex_release(rt_mutex_t mutex) { @@ -953,14 +1184,20 @@ rt_err_t rt_mutex_release(rt_mutex_t mutex) } RTM_EXPORT(rt_mutex_release); + /** - * This function can get or set some extra attributions of a mutex object. + * @brief This function will set some extra attributions of a mutex object. + * + * @note Currently this function does not implement the control function. * - * @param mutex the mutex object - * @param cmd the execution command - * @param arg the execution argument + * @param mutex is a pointer to a mutex object. * - * @return the error code + * @param cmd is a command word used to configure some attributions of the mutex. + * + * @param arg is the argument of the function to execute the command. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that this function failed to execute. */ rt_err_t rt_mutex_control(rt_mutex_t mutex, int cmd, void *arg) { @@ -971,18 +1208,54 @@ rt_err_t rt_mutex_control(rt_mutex_t mutex, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_mutex_control); + +/**@}*/ #endif /* RT_USING_MUTEX */ #ifdef RT_USING_EVENT /** - * This function will initialize an event and put it under control of resource - * management. + * @addtogroup event + */ + +/**@{*/ + +/** + * @brief The function will initialize a static event object. + * + * @note For the static event object, its memory space is allocated by the compiler during compiling, + * and shall placed on the read-write data segment or on the uninitialized data segment. + * By contrast, the rt_event_create() function will allocate memory space automatically + * and initialize the event. + * + * @see rt_event_create() + * + * @param event is a pointer to the event to initialize. It is assumed that storage for the event + * will be allocated in your application. + * + * @param name is a pointer to the name that given to the event. + * + * @param value is the initial value for the event. + * If want to share resources, you should initialize the value as the number of available resources. + * If want to signal the occurrence of an event, you should initialize the value as 0. + * + * @param flag is the event flag, which determines the queuing way of how multiple threads wait + * when the event is not available. + * The event flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. * - * @param event the event object - * @param name the name of event - * @param flag the flag of event + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). * - * @return the operation status, RT_EOK on successful + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this event will become non-real-time threads. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it represents the initialization failed. + * + * @warning This function can ONLY be called from threads. */ rt_err_t rt_event_init(rt_event_t event, const char *name, rt_uint8_t flag) { @@ -1005,12 +1278,24 @@ rt_err_t rt_event_init(rt_event_t event, const char *name, rt_uint8_t flag) } RTM_EXPORT(rt_event_init); + /** - * This function will detach an event object from resource management + * @brief This function will detach a static event object. + * + * @note This function is used to detach a static event object which is initialized by rt_event_init() function. + * By contrast, the rt_event_delete() function will delete an event object. + * When the event is successfully detached, it will resume all suspended threads in the event list. * - * @param event the event object + * @see rt_event_delete() * - * @return the operation status, RT_EOK on successful + * @param event is a pointer to an event object to be detached. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it means that the event detach failed. + * + * @warning This function can ONLY detach a static event initialized by the rt_event_init() function. + * If the event is created by the rt_event_create() function, you MUST NOT USE this function to detach it, + * ONLY USE the rt_event_delete() function to complete the deletion. */ rt_err_t rt_event_detach(rt_event_t event) { @@ -1031,12 +1316,32 @@ RTM_EXPORT(rt_event_detach); #ifdef RT_USING_HEAP /** - * This function will create an event object from system resource + * @brief Creating an event object. + * + * @note For the event object, its memory space is allocated automatically. + * By contrast, the rt_event_init() function will initialize a static event object. + * + * @see rt_event_init() * - * @param name the name of event - * @param flag the flag of event + * @param name is a pointer to the name that given to the event. * - * @return the created event, RT_NULL on error happen + * @param flag is the event flag, which determines the queuing way of how multiple threads wait when the event + * is not available. + * The event flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. + * + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this event will become non-real-time threads. + * + * @return Return a pointer to the event object. When the return value is RT_NULL, it means the creation failed. + * + * @warning This function can ONLY be called from threads. */ rt_event_t rt_event_create(const char *name, rt_uint8_t flag) { @@ -1062,12 +1367,24 @@ rt_event_t rt_event_create(const char *name, rt_uint8_t flag) } RTM_EXPORT(rt_event_create); + /** - * This function will delete an event object and release the memory + * @brief This function will delete an event object and release the memory space. + * + * @note This function is used to delete an event object which is created by the rt_event_create() function. + * By contrast, the rt_event_detach() function will detach a static event object. + * When the event is successfully deleted, it will resume all suspended threads in the event list. + * + * @see rt_event_detach() * - * @param event the event object + * @param event is a pointer to an event object to be deleted. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the event detach failed. + * + * @warning This function can ONLY delete an event initialized by the rt_event_create() function. + * If the event is initialized by the rt_event_init() function, you MUST NOT USE this function to delete it, + * ONLY USE the rt_event_detach() function to complete the detachment. */ rt_err_t rt_event_delete(rt_event_t event) { @@ -1089,14 +1406,23 @@ rt_err_t rt_event_delete(rt_event_t event) RTM_EXPORT(rt_event_delete); #endif /* RT_USING_HEAP */ + /** - * This function will send an event to the event object, if there are threads - * suspended on event object, it will be waked up. + * @brief This function will send an event to the event object. + * If there is a thread suspended on the event, the thread will be resumed. + * + * @note When using this function, you need to use the parameter (set) to specify the event flag of the event object, + * then the function will traverse the list of suspended threads waiting on the event object. + * If there is a thread suspended on the event, and the thread's event_info and the event flag of + * the current event object matches, the thread will be resumed. + * + * @param event is a pointer to the event object to be sent. * - * @param event the event object - * @param set the event set + * @param set is a flag that you will set for this event's flag. + * You can set an event flag, or you can set multiple flags through OR logic operation. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the event detach failed. */ rt_err_t rt_event_send(rt_event_t event, rt_uint32_t set) { @@ -1190,18 +1516,38 @@ rt_err_t rt_event_send(rt_event_t event, rt_uint32_t set) } RTM_EXPORT(rt_event_send); + /** - * This function will receive an event from event object, if the event is - * unavailable, the thread shall wait for a specified time. + * @brief This function will receive an event from event object. if the event is unavailable, the thread shall wait for + * the event up to a specified time. + * + * @note If there are threads suspended on this semaphore, the first thread in the list of this semaphore object + * will be resumed, and a thread scheduling (rt_schedule) will be executed. + * If no threads are suspended on this semaphore, the count value sem->value of this semaphore will increase by 1. + * + * @param event is a pointer to the event object to be received. + * + * @param set is a flag that you will set for this event's flag. + * You can set an event flag, or you can set multiple flags through OR logic operation. * - * @param event the fast event object - * @param set the interested event set - * @param option the receive option, either RT_EVENT_FLAG_AND or - * RT_EVENT_FLAG_OR should be set. - * @param timeout the waiting time - * @param recved the received event, if you don't care, RT_NULL can be set. + * @param option is the option of this receiving event, it indicates how the receiving event is operated. + * The option can be one or more of the following values, When selecting multiple values,use logical OR to operate. + * (NOTE: RT_EVENT_FLAG_OR and RT_EVENT_FLAG_AND can only select one): * - * @return the error code + * + * RT_EVENT_FLAG_OR The thread select to use logical OR to receive the event. + * + * RT_EVENT_FLAG_AND The thread select to use logical OR to receive the event. + * + * RT_EVENT_FLAG_CLEAR When the thread receives the corresponding event, the function + * determines whether to clear the event flag. + * + * @param timeout is a timeout period (unit: an OS tick). + * + * @param recved is a pointer to the received event. If you don't care about this value, you can use RT_NULL to set. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the semaphore release failed. */ rt_err_t rt_event_recv(rt_event_t event, rt_uint32_t set, @@ -1325,14 +1671,20 @@ rt_err_t rt_event_recv(rt_event_t event, } RTM_EXPORT(rt_event_recv); + /** - * This function can get or set some extra attributions of an event object. + * @brief This function will set some extra attributions of an event object. + * + * @note Currently this function only supports the RT_IPC_CMD_RESET command to reset the event. + * + * @param event is a pointer to an event object. * - * @param event the event object - * @param cmd the execution command - * @param arg the execution argument + * @param cmd is a command word used to configure some attributions of the event. * - * @return the error code + * @param arg is the argument of the function to execute the command. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that this function failed to execute. */ rt_err_t rt_event_control(rt_event_t event, int cmd, void *arg) { @@ -1364,20 +1716,55 @@ rt_err_t rt_event_control(rt_event_t event, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_event_control); + +/**@}*/ #endif /* RT_USING_EVENT */ #ifdef RT_USING_MAILBOX /** - * This function will initialize a mailbox and put it under control of resource - * management. + * @addtogroup mailbox + */ + +/**@{*/ + +/** + * @brief Initialize a static mailbox object. * - * @param mb the mailbox object - * @param name the name of mailbox - * @param msgpool the begin address of buffer to save received mail - * @param size the size of mailbox - * @param flag the flag of mailbox + * @note For the static mailbox object, its memory space is allocated by the compiler during compiling, + * and shall placed on the read-write data segment or on the uninitialized data segment. + * By contrast, the rt_mb_create() function will allocate memory space automatically and initialize the mailbox. * - * @return the operation status, RT_EOK on successful + * @see rt_mb_create() + * + * @param mb is a pointer to the mailbox to initialize. + * It is assumed that storage for the mailbox will be allocated in your application. + * + * @param name is a pointer to the name that given to the mailbox. + * + * @param msgpoll is a pointer to the starting address of the memory space you allocated for the mailbox in advance. + * In other words, msgpoll is a pointer to the mailbox buffer of the starting address. + * + * @param size is the maximum number of mails in the mailbox. + * For example, when the mailbox buffer capacity is N, size is N/4. + * + * @param flag is the mailbox flag, which determines the queuing way of how multiple threads wait + * when the mailbox is not available. + * The mailbox flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. + * + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this mailbox will become non-real-time threads. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it represents the initialization failed. + * + * @warning This function can ONLY be called from threads. */ rt_err_t rt_mb_init(rt_mailbox_t mb, const char *name, @@ -1410,12 +1797,24 @@ rt_err_t rt_mb_init(rt_mailbox_t mb, } RTM_EXPORT(rt_mb_init); + /** - * This function will detach a mailbox from resource management + * @brief This function will detach a static mailbox object. + * + * @note This function is used to detach a static mailbox object which is initialized by rt_mb_init() function. + * By contrast, the rt_mb_delete() function will delete a mailbox object. + * When the mailbox is successfully detached, it will resume all suspended threads in the mailbox list. * - * @param mb the mailbox object + * @see rt_mb_delete() * - * @return the operation status, RT_EOK on successful + * @param mb is a pointer to a mailbox object to be detached. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it means that the mailbox detach failed. + * + * @warning This function can ONLY detach a static mailbox initialized by the rt_mb_init() function. + * If the mailbox is created by the rt_mb_create() function, you MUST NOT USE this function to detach it, + * ONLY USE the rt_mb_delete() function to complete the deletion. */ rt_err_t rt_mb_detach(rt_mailbox_t mb) { @@ -1438,13 +1837,35 @@ RTM_EXPORT(rt_mb_detach); #ifdef RT_USING_HEAP /** - * This function will create a mailbox object from system resource + * @brief Creating a mailbox object. + * + * @note For the mailbox object, its memory space is allocated automatically. + * By contrast, the rt_mb_init() function will initialize a static mailbox object. + * + * @see rt_mb_init() * - * @param name the name of mailbox - * @param size the size of mailbox - * @param flag the flag of mailbox + * @param name is a pointer that given to the mailbox. * - * @return the created mailbox, RT_NULL on error happen + * @param size is the maximum number of mails in the mailbox. + * For example, when mailbox buffer capacity is N, size is N/4. + * + * @param flag is the mailbox flag, which determines the queuing way of how multiple threads wait + * when the mailbox is not available. + * The mailbox flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. + * + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this mailbox will become non-real-time threads. + * + * @return Return a pointer to the mailbox object. When the return value is RT_NULL, it means the creation failed. + * + * @warning This function can ONLY be called from threads. */ rt_mailbox_t rt_mb_create(const char *name, rt_size_t size, rt_uint8_t flag) { @@ -1484,12 +1905,24 @@ rt_mailbox_t rt_mb_create(const char *name, rt_size_t size, rt_uint8_t flag) } RTM_EXPORT(rt_mb_create); + /** - * This function will delete a mailbox object and release the memory + * @brief This function will delete a mailbox object and release the memory space. + * + * @note This function is used to delete a mailbox object which is created by the rt_mb_create() function. + * By contrast, the rt_mb_detach() function will detach a static mailbox object. + * When the mailbox is successfully deleted, it will resume all suspended threads in the mailbox list. * - * @param mb the mailbox object + * @see rt_mb_detach() * - * @return the error code + * @param mb is a pointer to a mailbox object to be deleted. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox detach failed. + * + * @warning This function can only delete mailbox created by the rt_mb_create() function. + * If the mailbox is initialized by the rt_mb_init() function, you MUST NOT USE this function to delete it, + * ONLY USE the rt_mb_detach() function to complete the detachment. */ rt_err_t rt_mb_delete(rt_mailbox_t mb) { @@ -1517,15 +1950,29 @@ rt_err_t rt_mb_delete(rt_mailbox_t mb) RTM_EXPORT(rt_mb_delete); #endif /* RT_USING_HEAP */ + /** - * This function will send a mail to mailbox object. If the mailbox is full, - * current thread will be suspended until timeout. + * @brief This function will send an mail to the mailbox object. If there is a thread suspended on the mailbox, + * the thread will be resumed. + * + * @note When using this function to send a mail, if the mailbox if fully used, the current thread will + * wait for a timeout. If the set timeout time is reached and there is still no space available, + * the sending thread will be resumed and an error code will be returned. + * By contrast, the rt_mb_send() function will return an error code immediately without waiting time + * when the mailbox if fully used. + * + * @see rt_mb_send() + * + * @param mb is a pointer to the mailbox object to be sent. + * + * @param value is a value to the content of the mail you want to send. + * + * @param timeout is a timeout period (unit: an OS tick). * - * @param mb the mailbox object - * @param value the mail - * @param timeout the waiting time + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox detach failed. * - * @return the error code + * @warning This function can be called in interrupt context and thread context. */ rt_err_t rt_mb_send_wait(rt_mailbox_t mb, rt_ubase_t value, @@ -1657,15 +2104,23 @@ rt_err_t rt_mb_send_wait(rt_mailbox_t mb, } RTM_EXPORT(rt_mb_send_wait); + /** - * This function will send a mail to mailbox object, if there are threads - * suspended on mailbox object, it will be waked up. This function will return - * immediately, if you want blocking send, use rt_mb_send_wait instead. + * @brief This function will send an mail to the mailbox object. If there is a thread suspended on the mailbox, + * the thread will be resumed. + * + * @note When using this function to send a mail, if the mailbox is fully used, this function will return an error + * code immediately without waiting time. + * By contrast, the rt_mb_send_wait() function is set a timeout to wait for the mail to be sent. + * + * @see rt_mb_send_wait() + * + * @param mb is a pointer to the mailbox object to be sent. * - * @param mb the mailbox object - * @param value the mail + * @param value is a value to the content of the mail you want to send. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox detach failed. */ rt_err_t rt_mb_send(rt_mailbox_t mb, rt_ubase_t value) { @@ -1673,15 +2128,22 @@ rt_err_t rt_mb_send(rt_mailbox_t mb, rt_ubase_t value) } RTM_EXPORT(rt_mb_send); + /** - * This function will send an urgent mail to mailbox object, if there are threads - * suspended on mailbox object, it will be waked up. This function will return - * immediately. + * @brief This function will send an urgent mail to the mailbox object. + * + * @note This function is almost the same as the rt_mb_send() function. The only difference is that + * when sending an urgent mail, the mail will be placed at the head of the mail queue so that + * the recipient can receive the urgent mail first. + * + * @see rt_mb_send() + * + * @param mb is a pointer to the mailbox object to be sent. * - * @param mb the mailbox object - * @param value the mail + * @param value is the content of the mail you want to send. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox detach failed. */ rt_err_t rt_mb_urgent(rt_mailbox_t mb, rt_ubase_t value) { @@ -1738,15 +2200,24 @@ rt_err_t rt_mb_urgent(rt_mailbox_t mb, rt_ubase_t value) } RTM_EXPORT(rt_mb_urgent); + /** - * This function will receive a mail from mailbox object, if there is no mail - * in mailbox object, the thread shall wait for a specified time. + * @brief This function will receive a mail from mailbox object, if there is no mail in mailbox object, + * the thread shall wait for a specified time. + * + * @note Only when there is mail in the mailbox, the receiving thread can get the mail immediately and + * return RT_EOK, otherwise the receiving thread will be suspended until the set timeout. If the mail + * is still not received within the specified time, it will return-RT_ETIMEOUT. + * + * @param mb is a pointer to the mailbox object to be received. + * + * @param value is a flag that you will set for this mailbox's flag. + * You can set an mailbox flag, or you can set multiple flags through OR logic operations. * - * @param mb the mailbox object - * @param value the received mail will be saved in - * @param timeout the waiting time + * @param timeout is a timeout period (unit: an OS tick). * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox release failed. */ rt_err_t rt_mb_recv(rt_mailbox_t mb, rt_ubase_t *value, rt_int32_t timeout) { @@ -1879,14 +2350,20 @@ rt_err_t rt_mb_recv(rt_mailbox_t mb, rt_ubase_t *value, rt_int32_t timeout) } RTM_EXPORT(rt_mb_recv); + /** - * This function can get or set some extra attributions of a mailbox object. + * @brief This function will set some extra attributions of a mailbox object. + * + * @note Currently this function only supports the RT_IPC_CMD_RESET command to reset the mailbox. + * + * @param mb is a pointer to a mailbox object. + * + * @param cmd is a command used to configure some attributions of the mailbox. * - * @param mb the mailbox object - * @param cmd the execution command - * @param arg the execution argument + * @param arg is the argument of the function to execute the command. * - * @return the error code + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that this function failed to execute. */ rt_err_t rt_mb_control(rt_mailbox_t mb, int cmd, void *arg) { @@ -1922,26 +2399,64 @@ rt_err_t rt_mb_control(rt_mailbox_t mb, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_mb_control); + +/**@}*/ #endif /* RT_USING_MAILBOX */ #ifdef RT_USING_MESSAGEQUEUE +/** + * @addtogroup messagequeue + */ + +/**@{*/ + struct rt_mq_message { struct rt_mq_message *next; }; + /** - * This function will initialize a message queue and put it under control of - * resource management. + * @brief Initialize a static messagequeue object. + * + * @note For the static messagequeue object, its memory space is allocated by the compiler during compiling, + * and shall placed on the read-write data segment or on the uninitialized data segment. + * By contrast, the rt_mq_create() function will allocate memory space automatically + * and initialize the messagequeue. + * + * @see rt_mq_create() + * + * @param mq is a pointer to the messagequeue to initialize. It is assumed that storage for + * the messagequeue will be allocated in your application. + * + * @param name is a pointer to the name that given to the messagequeue. + * + * @param msgpool is a pointer to the starting address of the memory space you allocated for + * the messagequeue in advance. + * In other words, msgpool is a pointer to the messagequeue buffer of the starting address. + * + * @param msg_size is the maximum length of a message in the messagequeue (Unit: Byte). + * + * @param pool_size is the size of the memory space allocated for the messagequeue in advance. + * + * @param flag is the messagequeue flag, which determines the queuing way of how multiple threads wait + * when the messagequeue is not available. + * The messagequeue flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. * - * @param mq the message object - * @param name the name of message queue - * @param msgpool the beginning address of buffer to save messages - * @param msg_size the maximum size of message - * @param pool_size the size of buffer to save messages - * @param flag the flag of message queue + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). * - * @return the operation status, RT_EOK on successful + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this messagequeue will become non-real-time threads. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it represents the initialization failed. + * + * @warning This function can ONLY be called from threads. */ rt_err_t rt_mq_init(rt_mq_t mq, const char *name, @@ -1996,12 +2511,24 @@ rt_err_t rt_mq_init(rt_mq_t mq, } RTM_EXPORT(rt_mq_init); + /** - * This function will detach a message queue object from resource management + * @brief This function will detach a static messagequeue object. + * + * @note This function is used to detach a static messagequeue object which is initialized by rt_mq_init() function. + * By contrast, the rt_mq_delete() function will delete a messagequeue object. + * When the messagequeue is successfully detached, it will resume all suspended threads in the messagequeue list. * - * @param mq the message queue object + * @see rt_mq_delete() * - * @return the operation status, RT_EOK on successful + * @param mq is a pointer to a messagequeue object to be detached. + * + * @return Return the operation status. When the return value is RT_EOK, the initialization is successful. + * If the return value is any other values, it means that the messagequeue detach failed. + * + * @warning This function can ONLY detach a static messagequeue initialized by the rt_mq_init() function. + * If the messagequeue is created by the rt_mq_create() function, you MUST NOT USE this function to detach it, + * and ONLY USE the rt_mq_delete() function to complete the deletion. */ rt_err_t rt_mq_detach(rt_mq_t mq) { @@ -2024,14 +2551,36 @@ RTM_EXPORT(rt_mq_detach); #ifdef RT_USING_HEAP /** - * This function will create a message queue object from system resource + * @brief Creating a messagequeue object. + * + * @note For the messagequeue object, its memory space is allocated automatically. + * By contrast, the rt_mq_init() function will initialize a static messagequeue object. + * + * @see rt_mq_init() * - * @param name the name of message queue - * @param msg_size the size of message - * @param max_msgs the maximum number of message in queue - * @param flag the flag of message queue + * @param name is a pointer that given to the messagequeue. * - * @return the created message queue, RT_NULL on error happen + * @param msg_size is the maximum length of a message in the messagequeue (Unit: Byte). + * + * @param max_msgs is the maximum number of messages in the messagequeue. + * + * @param flag is the messagequeue flag, which determines the queuing way of how multiple threads wait + * when the messagequeue is not available. + * The messagequeue flag can be ONE of the following values: + * + * RT_IPC_FLAG_PRIO The pending threads will queue in order of priority. + * + * RT_IPC_FLAG_FIFO The pending threads will queue in the first-in-first-out method + * (also known as first-come-first-served (FCFS) scheduling strategy). + * + * NOTE: RT_IPC_FLAG_FIFO is a non-real-time scheduling mode. It is strongly recommended to + * use RT_IPC_FLAG_PRIO to ensure the thread is real-time UNLESS your applications concern about + * the first-in-first-out principle, and you clearly understand that all threads involved in + * this messagequeue will become non-real-time threads. + * + * @return Return a pointer to the messagequeue object. When the return value is RT_NULL, it means the creation failed. + * + * @warning This function can NOT be called in interrupt context. You can use macor RT_DEBUG_NOT_IN_INTERRUPT to check it. */ rt_mq_t rt_mq_create(const char *name, rt_size_t msg_size, @@ -2094,12 +2643,25 @@ rt_mq_t rt_mq_create(const char *name, } RTM_EXPORT(rt_mq_create); + /** - * This function will delete a message queue object and release the memory + * @brief This function will delete a messagequeue object and release the memory. * - * @param mq the message queue object + * @note This function is used to delete a messagequeue object which is created by the rt_mq_create() function. + * By contrast, the rt_mq_detach() function will detach a static messagequeue object. + * When the messagequeue is successfully deleted, it will resume all suspended threads in the messagequeue list. * - * @return the error code + * @see rt_mq_detach() + * + * @param mq is a pointer to a messagequeue object to be deleted. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the messagequeue detach failed. + * + * @warning This function can ONLY delete a messagequeue initialized by the rt_mq_create() function. + * If the messagequeue is initialized by the rt_mq_init() function, you MUST NOT USE this function to delete it, + * ONLY USE the rt_mq_detach() function to complete the detachment. + * for example,the rt_mq_create() function, it cannot be called in interrupt context. */ rt_err_t rt_mq_delete(rt_mq_t mq) { @@ -2126,16 +2688,35 @@ rt_err_t rt_mq_delete(rt_mq_t mq) RTM_EXPORT(rt_mq_delete); #endif /* RT_USING_HEAP */ + /** - * This function will send a message to message queue object. If the message queue is full, - * current thread will be suspended until timeout. + * @brief This function will send a message to the messagequeue object. If + * there is a thread suspended on the messagequeue, the thread will be + * resumed. + * + * @note When using this function to send a message, if the messagequeue is + * fully used, the current thread will wait for a timeout. If reaching + * the timeout and there is still no space available, the sending + * thread will be resumed and an error code will be returned. By + * contrast, the rt_mq_send() function will return an error code + * immediately without waiting when the messagequeue if fully used. + * + * @see rt_mq_send() + * + * @param mq is a pointer to the messagequeue object to be sent. + * + * @param buffer is the content of the message. * - * @param mq the message queue object - * @param buffer the message - * @param size the size of buffer - * @param timeout the waiting time + * @param size is the length of the message(Unit: Byte). * - * @return the error code + * @param timeout is a timeout period (unit: an OS tick). + * + * @return Return the operation status. When the return value is RT_EOK, the + * operation is successful. If the return value is any other values, + * it means that the messagequeue detach failed. + * + * @warning This function can be called in interrupt context and thread + * context. */ rt_err_t rt_mq_send_wait(rt_mq_t mq, const void *buffer, @@ -2298,15 +2879,28 @@ rt_err_t rt_mq_send_wait(rt_mq_t mq, } RTM_EXPORT(rt_mq_send_wait) + /** - * This function will send a message to message queue object, if there are - * threads suspended on message queue object, it will be waked up. + * @brief This function will send a message to the messagequeue object. + * If there is a thread suspended on the messagequeue, the thread will be resumed. + * + * @note When using this function to send a message, if the messagequeue is fully used, + * the current thread will wait for a timeout. + * By contrast, when the messagequeue is fully used, the rt_mq_send_wait() function will + * return an error code immediately without waiting. + * + * @see rt_mq_send_wait() + * + * @param mq is a pointer to the messagequeue object to be sent. + * + * @param buffer is the content of the message. + * + * @param size is the length of the message(Unit: Byte). * - * @param mq the message queue object - * @param buffer the message - * @param size the size of buffer + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the messagequeue detach failed. * - * @return the error code + * @warning This function can be called in interrupt context and thread context. */ rt_err_t rt_mq_send(rt_mq_t mq, const void *buffer, rt_size_t size) { @@ -2314,16 +2908,24 @@ rt_err_t rt_mq_send(rt_mq_t mq, const void *buffer, rt_size_t size) } RTM_EXPORT(rt_mq_send); + /** - * This function will send an urgent message to message queue object, which - * means the message will be inserted to the head of message queue. If there - * are threads suspended on message queue object, it will be waked up. + * @brief This function will send an urgent message to the messagequeue object. + * + * @note This function is almost the same as the rt_mq_send() function. The only difference is that + * when sending an urgent message, the message is placed at the head of the messagequeue so that + * the recipient can receive the urgent message first. + * + * @see rt_mq_send() + * + * @param mq is a pointer to the messagequeue object to be sent. * - * @param mq the message queue object - * @param buffer the message - * @param size the size of buffer + * @param buffer is the content of the message. * - * @return the error code + * @param size is the length of the message(Unit: Byte). + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox detach failed. */ rt_err_t rt_mq_urgent(rt_mq_t mq, const void *buffer, rt_size_t size) { @@ -2406,17 +3008,25 @@ rt_err_t rt_mq_urgent(rt_mq_t mq, const void *buffer, rt_size_t size) } RTM_EXPORT(rt_mq_urgent); + /** - * This function will receive a message from message queue object, if there is - * no message in message queue object, the thread shall wait for a specified - * time. + * @brief This function will receive a message from message queue object, + * if there is no message in messagequeue object, the thread shall wait for a specified time. + * + * @note Only when there is mail in the mailbox, the receiving thread can get the mail immediately and return RT_EOK, + * otherwise the receiving thread will be suspended until timeout. + * If the mail is not received within the specified time, it will return -RT_ETIMEOUT. + * + * @param mq is a pointer to the messagequeue object to be received. * - * @param mq the message queue object - * @param buffer the received message will be saved in - * @param size the size of buffer - * @param timeout the waiting time + * @param buffer is the content of the message. * - * @return the error code + * @param size is the length of the message(Unit: Byte). + * + * @param timeout is a timeout period (unit: an OS tick). + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that the mailbox release failed. */ rt_err_t rt_mq_recv(rt_mq_t mq, void *buffer, @@ -2568,15 +3178,20 @@ rt_err_t rt_mq_recv(rt_mq_t mq, } RTM_EXPORT(rt_mq_recv); + /** - * This function can get or set some extra attributions of a message queue - * object. + * @brief This function will set some extra attributions of a messagequeue object. + * + * @note Currently this function only supports the RT_IPC_CMD_RESET command to reset the messagequeue. * - * @param mq the message queue object - * @param cmd the execution command - * @param arg the execution argument + * @param mq is a pointer to a messagequeue object. * - * @return the error code + * @param cmd is a command used to configure some attributions of the messagequeue. + * + * @param arg is the argument of the function to execute the command. + * + * @return Return the operation status. When the return value is RT_EOK, the operation is successful. + * If the return value is any other values, it means that this function failed to execute. */ rt_err_t rt_mq_control(rt_mq_t mq, int cmd, void *arg) { @@ -2628,6 +3243,8 @@ rt_err_t rt_mq_control(rt_mq_t mq, int cmd, void *arg) return -RT_ERROR; } RTM_EXPORT(rt_mq_control); + +/**@}*/ #endif /* RT_USING_MESSAGEQUEUE */ /**@}*/ -- cgit v1.3.1