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

1 files changed, 142 insertions, 111 deletions

diff --git a/src/thread.c b/src/thread.c
index 60e6ab91d1..ab5264053e 100644
--- a/src/thread.c
+++ b/src/thread.c
@@ -38,12 +38,11 @@ static void (*rt_thread_resume_hook) (rt_thread_t thread);
 static void (*rt_thread_inited_hook) (rt_thread_t thread);
 
 /**
- * @ingroup Hook
- * This function sets a hook function when the system suspend a thread.
+ * @brief   This function sets a hook function when the system suspend a thread.
  *
- * @param hook the specified hook function
+ * @note    The hook function must be simple and never be blocked or suspend.
  *
- * @note the hook function must be simple and never be blocked or suspend.
+ * @param   hook is the specified hook function.
  */
 void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread))
 {
@@ -51,12 +50,11 @@ void rt_thread_suspend_sethook(void (*hook)(rt_thread_t thread))
 }
 
 /**
- * @ingroup Hook
- * This function sets a hook function when the system resume a thread.
+ * @brief   This function sets a hook function when the system resume a thread.
  *
- * @param hook the specified hook function
+ * @note    The hook function must be simple and never be blocked or suspend.
  *
- * @note the hook function must be simple and never be blocked or suspend.
+ * @param   hook is the specified hook function.
  */
 void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread))
 {
@@ -64,10 +62,9 @@ void rt_thread_resume_sethook(void (*hook)(rt_thread_t thread))
 }
 
 /**
- * @ingroup Hook
- * This function sets a hook function when a thread is initialized.
+ * @brief   This function sets a hook function when a thread is initialized.
  *
- * @param hook the specified hook function
+ * @param   hook is the specified hook function.
  */
 void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread))
 {
@@ -76,8 +73,7 @@ void rt_thread_inited_sethook(void (*hook)(rt_thread_t thread))
 
 #endif /* RT_USING_HOOK */
 
-/* must be invoke witch rt_hw_interrupt_disable */
-static void _rt_thread_cleanup_execute(rt_thread_t thread)
+static void _thread_cleanup_execute(rt_thread_t thread)
 {
     register rt_base_t level;
 #ifdef RT_USING_MODULE
@@ -101,7 +97,7 @@ static void _rt_thread_cleanup_execute(rt_thread_t thread)
     rt_hw_interrupt_enable(level);
 }
 
-static void _rt_thread_exit(void)
+static void _thread_exit(void)
 {
     struct rt_thread *thread;
     register rt_base_t level;
@@ -112,7 +108,7 @@ static void _rt_thread_exit(void)
     /* disable interrupt */
     level = rt_hw_interrupt_disable();
 
-    _rt_thread_cleanup_execute(thread);
+    _thread_cleanup_execute(thread);
 
     /* remove from schedule */
     rt_schedule_remove_thread(thread);
@@ -139,14 +135,14 @@ static void _rt_thread_exit(void)
     rt_hw_interrupt_enable(level);
 }
 
-static rt_err_t _rt_thread_init(struct rt_thread *thread,
-                                const char       *name,
-                                void (*entry)(void *parameter),
-                                void             *parameter,
-                                void             *stack_start,
-                                rt_uint32_t       stack_size,
-                                rt_uint8_t        priority,
-                                rt_uint32_t       tick)
+static rt_err_t _thread_init(struct rt_thread *thread,
+                             const char       *name,
+                             void (*entry)(void *parameter),
+                             void             *parameter,
+                             void             *stack_start,
+                             rt_uint32_t       stack_size,
+                             rt_uint8_t        priority,
+                             rt_uint32_t       tick)
 {
     /* init thread list */
     rt_list_init(&(thread->tlist));
@@ -163,11 +159,11 @@ static rt_err_t _rt_thread_init(struct rt_thread *thread,
 #ifdef ARCH_CPU_STACK_GROWS_UPWARD
     thread->sp = (void *)rt_hw_stack_init(thread->entry, thread->parameter,
                                           (void *)((char *)thread->stack_addr),
-                                          (void *)_rt_thread_exit);
+                                          (void *)_thread_exit);
 #else
     thread->sp = (void *)rt_hw_stack_init(thread->entry, thread->parameter,
                                           (rt_uint8_t *)((char *)thread->stack_addr + thread->stack_size - sizeof(rt_ubase_t)),
-                                          (void *)_rt_thread_exit);
+                                          (void *)_thread_exit);
 #endif /* ARCH_CPU_STACK_GROWS_UPWARD */
 
     /* priority init */
@@ -244,19 +240,27 @@ static rt_err_t _rt_thread_init(struct rt_thread *thread,
 /**@{*/
 
 /**
- * This function will initialize a thread, normally it's used to initialize a
- * static thread object.
+ * @brief   This function will initialize a thread. It's used to initialize a
+ *          static thread object.
+ *
+ * @param   thread is the static thread object.
+ *
+ * @param   name is the name of thread, which shall be unique.
+ *
+ * @param   entry is the entry function of thread.
+ *
+ * @param   parameter is the parameter of thread enter function.
+ *
+ * @param   stack_start is the start address of thread stack.
  *
- * @param thread the static thread object
- * @param name the name of thread, which shall be unique
- * @param entry the entry function of thread
- * @param parameter the parameter of thread enter function
- * @param stack_start the start address of thread stack
- * @param stack_size the size of thread stack
- * @param priority the priority of thread
- * @param tick the time slice if there are same priority thread
+ * @param   stack_size is the size of thread stack.
  *
- * @return the operation status, RT_EOK on OK, -RT_ERROR on error
+ * @param   priority is the priority of thread.
+ *
+ * @param   tick is the time slice if there are same priority thread.
+ *
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_init(struct rt_thread *thread,
                         const char       *name,
@@ -274,21 +278,21 @@ rt_err_t rt_thread_init(struct rt_thread *thread,
     /* initialize thread object */
     rt_object_init((rt_object_t)thread, RT_Object_Class_Thread, name);
 
-    return _rt_thread_init(thread,
-                           name,
-                           entry,
-                           parameter,
-                           stack_start,
-                           stack_size,
-                           priority,
-                           tick);
+    return _thread_init(thread,
+                        name,
+                        entry,
+                        parameter,
+                        stack_start,
+                        stack_size,
+                        priority,
+                        tick);
 }
 RTM_EXPORT(rt_thread_init);
 
 /**
- * This function will return self thread object
+ * @brief   This function will return self thread object.
  *
- * @return the self thread object
+ * @return  The self thread object.
  */
 rt_thread_t rt_thread_self(void)
 {
@@ -309,11 +313,12 @@ rt_thread_t rt_thread_self(void)
 RTM_EXPORT(rt_thread_self);
 
 /**
- * This function will start a thread and put it to system ready queue
+ * @brief   This function will start a thread and put it to system ready queue.
  *
- * @param thread the thread to be started
+ * @param   thread is the thread to be started.
  *
- * @return the operation status, RT_EOK on OK, -RT_ERROR on error
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_startup(rt_thread_t thread)
 {
@@ -351,12 +356,13 @@ rt_err_t rt_thread_startup(rt_thread_t thread)
 RTM_EXPORT(rt_thread_startup);
 
 /**
- * This function will detach a thread. The thread object will be removed from
- * thread queue and detached/deleted from system object management.
+ * @brief   This function will detach a thread. The thread object will be removed from
+ *          thread queue and detached/deleted from the system object management.
  *
- * @param thread the thread to be deleted
+ * @param   thread is the thread to be deleted.
  *
- * @return the operation status, RT_EOK on OK, -RT_ERROR on error
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_detach(rt_thread_t thread)
 {
@@ -376,7 +382,7 @@ rt_err_t rt_thread_detach(rt_thread_t thread)
         rt_schedule_remove_thread(thread);
     }
 
-    _rt_thread_cleanup_execute(thread);
+    _thread_cleanup_execute(thread);
 
     /* release thread timer */
     rt_timer_detach(&(thread->thread_timer));
@@ -404,17 +410,23 @@ RTM_EXPORT(rt_thread_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a thread object and allocate thread object memory
- * and stack.
+ * @brief   This function will create a thread object and allocate thread object memory.
+ *          and stack.
+ *
+ * @param   name is the name of thread, which shall be unique.
+ *
+ * @param   entry is the entry function of thread.
+ *
+ * @param   parameter is the parameter of thread enter function.
  *
- * @param name the name of thread, which shall be unique
- * @param entry the entry function of thread
- * @param parameter the parameter of thread enter function
- * @param stack_size the size of thread stack
- * @param priority the priority of thread
- * @param tick the time slice if there are same priority thread
+ * @param   stack_size is the size of thread stack.
  *
- * @return the created thread object
+ * @param   priority is the priority of thread.
+ *
+ * @param   tick is the time slice if there are same priority thread.
+ *
+ * @return  If the return value is a rt_thread structure pointer, the function is successfully executed.
+ *          If the return value is RT_NULL, it means this operation failed.
  */
 rt_thread_t rt_thread_create(const char *name,
                              void (*entry)(void *parameter),
@@ -440,7 +452,7 @@ rt_thread_t rt_thread_create(const char *name,
         return RT_NULL;
     }
 
-    _rt_thread_init(thread,
+    _thread_init(thread,
                     name,
                     entry,
                     parameter,
@@ -454,12 +466,13 @@ rt_thread_t rt_thread_create(const char *name,
 RTM_EXPORT(rt_thread_create);
 
 /**
- * This function will delete a thread. The thread object will be removed from
- * thread queue and deleted from system object management in the idle thread.
+ * @brief   This function will delete a thread. The thread object will be removed from
+ *          thread queue and deleted from system object management in the idle thread.
  *
- * @param thread the thread to be deleted
+ * @param   thread is the thread to be deleted.
  *
- * @return the operation status, RT_EOK on OK, -RT_ERROR on error
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_delete(rt_thread_t thread)
 {
@@ -479,7 +492,7 @@ rt_err_t rt_thread_delete(rt_thread_t thread)
         rt_schedule_remove_thread(thread);
     }
 
-    _rt_thread_cleanup_execute(thread);
+    _thread_cleanup_execute(thread);
 
     /* release thread timer */
     rt_timer_detach(&(thread->thread_timer));
@@ -502,11 +515,12 @@ RTM_EXPORT(rt_thread_delete);
 #endif /* RT_USING_HEAP */
 
 /**
- * This function will let current thread yield processor, and scheduler will
- * choose a highest thread to run. After yield processor, the current thread
- * is still in READY state.
+ * @brief   This function will let current thread yield processor, and scheduler will
+ *          choose the highest thread to run. After yield processor, the current thread
+ *          is still in READY state.
  *
- * @return RT_EOK
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_yield(void)
 {
@@ -525,11 +539,13 @@ rt_err_t rt_thread_yield(void)
 RTM_EXPORT(rt_thread_yield);
 
 /**
- * This function will let current thread sleep for some ticks.
+ * @brief   This function will let current thread sleep for some ticks. Change current thread state to suspend,
+ *          when the thread timer reaches the tick value, scheduler will awaken this thread.
  *
- * @param tick the sleep ticks
+ * @param   tick is the sleep ticks.
  *
- * @return RT_EOK
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_sleep(rt_tick_t tick)
 {
@@ -564,11 +580,12 @@ rt_err_t rt_thread_sleep(rt_tick_t tick)
 }
 
 /**
- * This function will let current thread delay for some ticks.
+ * @brief   This function will let current thread delay for some ticks.
  *
- * @param tick the delay ticks
+ * @param   tick is the delay ticks.
  *
- * @return RT_EOK
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_delay(rt_tick_t tick)
 {
@@ -577,12 +594,14 @@ rt_err_t rt_thread_delay(rt_tick_t tick)
 RTM_EXPORT(rt_thread_delay);
 
 /**
- * This function will let current thread delay until (*tick + inc_tick).
+ * @brief   This function will let current thread delay until (*tick + inc_tick).
+ *
+ * @param   tick is the tick of last wakeup.
  *
- * @param tick the tick of last wakeup.
- * @param inc_tick the increment tick
+ * @param   inc_tick is the increment tick.
  *
- * @return RT_EOK
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick)
 {
@@ -637,11 +656,12 @@ rt_err_t rt_thread_delay_until(rt_tick_t *tick, rt_tick_t inc_tick)
 RTM_EXPORT(rt_thread_delay_until);
 
 /**
- * This function will let current thread delay for some milliseconds.
+ * @brief   This function will let current thread delay for some milliseconds.
  *
- * @param ms the delay ms time
+ * @param   ms is the delay ms time.
  *
- * @return RT_EOK
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_mdelay(rt_int32_t ms)
 {
@@ -654,17 +674,24 @@ rt_err_t rt_thread_mdelay(rt_int32_t ms)
 RTM_EXPORT(rt_thread_mdelay);
 
 /**
- * This function will control thread behaviors according to control command.
+ * @brief   This function will control thread behaviors according to control command.
+ *
+ * @param   thread is the specified thread to be controlled.
+ *
+ * @param   cmd is the control command, which includes.
  *
- * @param thread the specified thread to be controlled
- * @param cmd the control command, which includes
- *  RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread;
- *  RT_THREAD_CTRL_STARTUP for starting a thread;
- *  RT_THREAD_CTRL_CLOSE for delete a thread;
- *  RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.
- * @param arg the argument of control command
+ *              RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread.
  *
- * @return RT_EOK
+ *              RT_THREAD_CTRL_STARTUP for starting a thread.
+ *
+ *              RT_THREAD_CTRL_CLOSE for delete a thread.
+ *
+ *              RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.
+ *
+ * @param   arg is the argument of control command.
+ *
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg)
 {
@@ -755,7 +782,7 @@ rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg)
                 return RT_ERROR;
             }
 
-            cpu = (rt_uint8_t)(size_t)arg;
+            cpu = (rt_uint8_t)(rt_size_t)arg;
             thread->bind_cpu = cpu > RT_CPUS_NR? RT_CPUS_NR : cpu;
             break;
         }
@@ -770,14 +797,15 @@ rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg)
 RTM_EXPORT(rt_thread_control);
 
 /**
- * This function will suspend the specified thread.
+ * @brief   This function will suspend the specified thread and change it to suspend state.
  *
- * @param thread the thread to be suspended
+ * @note    If suspend self thread, after this function call, the
+ *          rt_schedule() must be invoked.
  *
- * @return the operation status, RT_EOK on OK, -RT_ERROR on error
+ * @param   thread is the thread to be suspended.
  *
- * @note if suspend self thread, after this function call, the
- * rt_schedule() must be invoked.
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_suspend(rt_thread_t thread)
 {
@@ -822,11 +850,12 @@ rt_err_t rt_thread_suspend(rt_thread_t thread)
 RTM_EXPORT(rt_thread_suspend);
 
 /**
- * This function will resume a thread and put it to system ready queue.
+ * @brief   This function will resume a thread and put it to system ready queue.
  *
- * @param thread the thread to be resumed
+ * @param   thread is the thread to be resumed.
  *
- * @return the operation status, RT_EOK on OK, -RT_ERROR on error
+ * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_resume(rt_thread_t thread)
 {
@@ -866,10 +895,10 @@ rt_err_t rt_thread_resume(rt_thread_t thread)
 RTM_EXPORT(rt_thread_resume);
 
 /**
- * This function is the timeout function for thread, normally which is invoked
- * when thread is timeout to wait some resource.
+ * @brief   This function is the timeout function for thread, normally which is invoked
+ *          when thread is timeout to wait some resource.
  *
- * @param parameter the parameter of thread timeout function
+ * @param   parameter is the parameter of thread timeout function
  */
 void rt_thread_timeout(void *parameter)
 {
@@ -904,18 +933,20 @@ void rt_thread_timeout(void *parameter)
 RTM_EXPORT(rt_thread_timeout);
 
 /**
- * This function will find the specified thread.
+ * @brief   This function will find the specified thread.
  *
- * @param name the name of thread finding
+ * @note    Please don't invoke this function in interrupt status.
  *
- * @return the found thread
+ * @param   name is the name of thread finding.
  *
- * @note please don't invoke this function in interrupt status.
+ * @return  If the return value is a rt_thread structure pointer, the function is successfully executed.
+ *          If the return value is RT_NULL, it means this operation failed.
  */
 rt_thread_t rt_thread_find(char *name)
 {
     return (rt_thread_t)rt_object_find(name, RT_Object_Class_Thread);
 }
+
 RTM_EXPORT(rt_thread_find);
 
 /**@}*/