Merge branch 'RT-Thread:master' into rtusingheap

1 files changed, 151 insertions, 89 deletions

diff --git a/src/timer.c b/src/timer.c
index 9b0db6c6a5..25ba175306 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -16,13 +16,14 @@
  * 2012-12-15     Bernard      fix the next timeout issue in soft timer
  * 2014-07-12     Bernard      does not lock scheduler when invoking soft-timer
  *                             timeout function.
+ * 2021-08-15     supperthomas add the comment
  */
 
 #include <rtthread.h>
 #include <rthw.h>
 
 /* hard timer list */
-static rt_list_t rt_timer_list[RT_TIMER_SKIP_LIST_LEVEL];
+static rt_list_t _timer_list[RT_TIMER_SKIP_LIST_LEVEL];
 
 #ifdef RT_USING_TIMER_SOFT
 
@@ -31,20 +32,20 @@ static rt_list_t rt_timer_list[RT_TIMER_SKIP_LIST_LEVEL];
 
 #ifndef RT_TIMER_THREAD_STACK_SIZE
 #define RT_TIMER_THREAD_STACK_SIZE     512
-#endif
+#endif /* RT_TIMER_THREAD_STACK_SIZE */
 
 #ifndef RT_TIMER_THREAD_PRIO
 #define RT_TIMER_THREAD_PRIO           0
-#endif
+#endif /* RT_TIMER_THREAD_PRIO */
 
 /* soft timer status */
-static rt_uint8_t soft_timer_status = RT_SOFT_TIMER_IDLE;
+static rt_uint8_t _soft_timer_status = RT_SOFT_TIMER_IDLE;
 /* soft timer list */
-static rt_list_t rt_soft_timer_list[RT_TIMER_SKIP_LIST_LEVEL];
-static struct rt_thread timer_thread;
+static rt_list_t _soft_timer_list[RT_TIMER_SKIP_LIST_LEVEL];
+static struct rt_thread _timer_thread;
 ALIGN(RT_ALIGN_SIZE)
-static rt_uint8_t timer_thread_stack[RT_TIMER_THREAD_STACK_SIZE];
-#endif
+static rt_uint8_t _timer_thread_stack[RT_TIMER_THREAD_STACK_SIZE];
+#endif /* RT_USING_TIMER_SOFT */
 
 #ifdef RT_USING_HOOK
 extern void (*rt_object_take_hook)(struct rt_object *object);
@@ -59,10 +60,10 @@ static void (*rt_timer_exit_hook)(struct rt_timer *timer);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when enter
- * timer timeout callback function.
+ * @brief This function will set a hook function on timer,
+ *        which will be invoked when enter timer timeout callback function.
  *
- * @param hook the hook function
+ * @param hook is the function point of timer
  */
 void rt_timer_enter_sethook(void (*hook)(struct rt_timer *timer))
 {
@@ -70,10 +71,10 @@ void rt_timer_enter_sethook(void (*hook)(struct rt_timer *timer))
 }
 
 /**
- * This function will set a hook function, which will be invoked when exit
- * timer timeout callback function.
+ * @brief This function will set a hook function, which will be
+ *        invoked when exit timer timeout callback function.
  *
- * @param hook the hook function
+ * @param hook is the function point of timer
  */
 void rt_timer_exit_sethook(void (*hook)(struct rt_timer *timer))
 {
@@ -81,9 +82,27 @@ void rt_timer_exit_sethook(void (*hook)(struct rt_timer *timer))
 }
 
 /**@}*/
-#endif
+#endif /* RT_USING_HOOK */
 
-static void _rt_timer_init(rt_timer_t timer,
+
+/**
+ * @brief [internal] The init funtion of timer
+ *
+ *        The internal called function of rt_timer_init
+ *
+ * @see rt_timer_init
+ *
+ * @param timer is timer object
+ *
+ * @param timeout is the timeout function
+ *
+ * @param parameter is the parameter of timeout function
+ *
+ * @param time is the tick of timer
+ *
+ * @param flag the flag of timer
+ */
+static void _timer_init(rt_timer_t timer,
                            void (*timeout)(void *parameter),
                            void      *parameter,
                            rt_tick_t  time,
@@ -110,8 +129,14 @@ static void _rt_timer_init(rt_timer_t timer,
     }
 }
 
-/* the fist timer always in the last row */
-static rt_tick_t rt_timer_list_next_timeout(rt_list_t timer_list[])
+/**
+ * @brief  Find the next emtpy timer ticks
+ *
+ * @param timer_list is the array of time list
+ *
+ * @return the next timer's ticks
+ */
+static rt_tick_t _timer_list_next_timeout(rt_list_t timer_list[])
 {
     struct rt_timer *timer;
     register rt_base_t level;
@@ -133,7 +158,12 @@ static rt_tick_t rt_timer_list_next_timeout(rt_list_t timer_list[])
     return timeout_tick;
 }
 
-rt_inline void _rt_timer_remove(rt_timer_t timer)
+/**
+ * @brief Remove the timer
+ *
+ * @param timer the point of the timer
+ */
+rt_inline void _timer_remove(rt_timer_t timer)
 {
     int i;
 
@@ -144,7 +174,14 @@ rt_inline void _rt_timer_remove(rt_timer_t timer)
 }
 
 #if RT_DEBUG_TIMER
-static int rt_timer_count_height(struct rt_timer *timer)
+/**
+ * @brief The number of timer
+ *
+ * @param timer the head of timer
+ *
+ * @return count of timer
+ */
+static int _timer_count_height(struct rt_timer *timer)
 {
     int i, cnt = 0;
 
@@ -155,7 +192,11 @@ static int rt_timer_count_height(struct rt_timer *timer)
     }
     return cnt;
 }
-
+/**
+ * @brief dump the all timer information
+ *
+ * @param timer_heads the head of timer
+ */
 void rt_timer_dump(rt_list_t timer_heads[])
 {
     rt_list_t *list;
@@ -167,11 +208,11 @@ void rt_timer_dump(rt_list_t timer_heads[])
         struct rt_timer *timer = rt_list_entry(list,
                                                struct rt_timer,
                                                row[RT_TIMER_SKIP_LIST_LEVEL - 1]);
-        rt_kprintf("%d", rt_timer_count_height(timer));
+        rt_kprintf("%d", _timer_count_height(timer));
     }
     rt_kprintf("\n");
 }
-#endif
+#endif /* RT_DEBUG_TIMER */
 
 /**
  * @addtogroup Clock
@@ -180,15 +221,20 @@ void rt_timer_dump(rt_list_t timer_heads[])
 /**@{*/
 
 /**
- * This function will initialize a timer, normally this function is used to
- * initialize a static timer object.
+ * @brief This function will initialize a timer
+ *        normally this function is used to initialize a static timer object.
  *
- * @param timer the static timer object
- * @param name the name of timer
- * @param timeout the timeout function
- * @param parameter the parameter of timeout function
- * @param time the tick of timer
- * @param flag the flag of timer
+ * @param timer is the point of timer
+ *
+ * @param name is a pointer to the name of the timer
+ *
+ * @param timeout is the callback of timer
+ *
+ * @param parameter is the param of the callback
+ *
+ * @param time is the ticks of timer
+ *
+ * @param flag is the flag of timer
  */
 void rt_timer_init(rt_timer_t  timer,
                    const char *name,
@@ -203,16 +249,16 @@ void rt_timer_init(rt_timer_t  timer,
     /* timer object initialization */
     rt_object_init(&(timer->parent), RT_Object_Class_Timer, name);
 
-    _rt_timer_init(timer, timeout, parameter, time, flag);
+    _timer_init(timer, timeout, parameter, time, flag);
 }
 RTM_EXPORT(rt_timer_init);
 
 /**
- * This function will detach a timer from timer management.
+ * @brief This function will detach a timer from timer management.
  *
- * @param timer the static timer object
+ * @param timer is the timer to be detached
  *
- * @return the operation status, RT_EOK on OK; RT_ERROR on error
+ * @return the status of detach
  */
 rt_err_t rt_timer_detach(rt_timer_t timer)
 {
@@ -226,7 +272,7 @@ rt_err_t rt_timer_detach(rt_timer_t timer)
     /* disable interrupt */
     level = rt_hw_interrupt_disable();
 
-    _rt_timer_remove(timer);
+    _timer_remove(timer);
     /* stop timer */
     timer->parent.flag &= ~RT_TIMER_FLAG_ACTIVATED;
 
@@ -241,12 +287,16 @@ RTM_EXPORT(rt_timer_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a timer
+ * @brief This function will create a timer
  *
  * @param name the name of timer
+ *
  * @param timeout the timeout function
+ *
  * @param parameter the parameter of timeout function
+ *
  * @param time the tick of timer
+ *
  * @param flag the flag of timer
  *
  * @return the created timer object
@@ -266,14 +316,14 @@ rt_timer_t rt_timer_create(const char *name,
         return RT_NULL;
     }
 
-    _rt_timer_init(timer, timeout, parameter, time, flag);
+    _timer_init(timer, timeout, parameter, time, flag);
 
     return timer;
 }
 RTM_EXPORT(rt_timer_create);
 
 /**
- * This function will delete a timer and release timer memory
+ * @brief This function will delete a timer and release timer memory
  *
  * @param timer the timer to be deleted
  *
@@ -291,7 +341,7 @@ rt_err_t rt_timer_delete(rt_timer_t timer)
     /* disable interrupt */
     level = rt_hw_interrupt_disable();
 
-    _rt_timer_remove(timer);
+    _timer_remove(timer);
     /* stop timer */
     timer->parent.flag &= ~RT_TIMER_FLAG_ACTIVATED;
 
@@ -303,10 +353,10 @@ rt_err_t rt_timer_delete(rt_timer_t timer)
     return RT_EOK;
 }
 RTM_EXPORT(rt_timer_delete);
-#endif
+#endif /* RT_USING_HEAP */
 
 /**
- * This function will start the timer
+ * @brief This function will start the timer
  *
  * @param timer the timer to be started
  *
@@ -317,6 +367,7 @@ rt_err_t rt_timer_start(rt_timer_t timer)
     unsigned int row_lvl;
     rt_list_t *timer_list;
     register rt_base_t level;
+    register rt_bool_t need_schedule;
     rt_list_t *row_head[RT_TIMER_SKIP_LIST_LEVEL];
     unsigned int tst_nr;
     static unsigned int random_nr;
@@ -325,10 +376,12 @@ rt_err_t rt_timer_start(rt_timer_t timer)
     RT_ASSERT(timer != RT_NULL);
     RT_ASSERT(rt_object_get_type(&timer->parent) == RT_Object_Class_Timer);
 
+    need_schedule = RT_FALSE;
+
     /* stop timer firstly */
     level = rt_hw_interrupt_disable();
     /* remove timer from list */
-    _rt_timer_remove(timer);
+    _timer_remove(timer);
     /* change status of timer */
     timer->parent.flag &= ~RT_TIMER_FLAG_ACTIVATED;
 
@@ -345,13 +398,13 @@ rt_err_t rt_timer_start(rt_timer_t timer)
     if (timer->parent.flag & RT_TIMER_FLAG_SOFT_TIMER)
     {
         /* insert timer to soft timer list */
-        timer_list = rt_soft_timer_list;
+        timer_list = _soft_timer_list;
     }
     else
-#endif
+#endif /* RT_USING_TIMER_SOFT */
     {
         /* insert timer to system timer list */
-        timer_list = rt_timer_list;
+        timer_list = _timer_list;
     }
 
     row_head[0]  = &timer_list[0];
@@ -407,29 +460,34 @@ rt_err_t rt_timer_start(rt_timer_t timer)
 
     timer->parent.flag |= RT_TIMER_FLAG_ACTIVATED;
 
-    /* enable interrupt */
-    rt_hw_interrupt_enable(level);
-
 #ifdef RT_USING_TIMER_SOFT
     if (timer->parent.flag & RT_TIMER_FLAG_SOFT_TIMER)
     {
         /* check whether timer thread is ready */
-        if ((soft_timer_status == RT_SOFT_TIMER_IDLE) &&
-           ((timer_thread.stat & RT_THREAD_STAT_MASK) == RT_THREAD_SUSPEND))
+        if ((_soft_timer_status == RT_SOFT_TIMER_IDLE) &&
+           ((_timer_thread.stat & RT_THREAD_STAT_MASK) == RT_THREAD_SUSPEND))
         {
             /* resume timer thread to check soft timer */
-            rt_thread_resume(&timer_thread);
-            rt_schedule();
+            rt_thread_resume(&_timer_thread);
+            need_schedule = RT_TRUE;
         }
     }
-#endif
+#endif /* RT_USING_TIMER_SOFT */
+
+    /* enable interrupt */
+    rt_hw_interrupt_enable(level);
+
+    if (need_schedule)
+    {
+        rt_schedule();
+    }
 
     return RT_EOK;
 }
 RTM_EXPORT(rt_timer_start);
 
 /**
- * This function will stop the timer
+ * @brief This function will stop the timer
  *
  * @param timer the timer to be stopped
  *
@@ -451,7 +509,7 @@ rt_err_t rt_timer_stop(rt_timer_t timer)
     /* disable interrupt */
     level = rt_hw_interrupt_disable();
 
-    _rt_timer_remove(timer);
+    _timer_remove(timer);
     /* change status */
     timer->parent.flag &= ~RT_TIMER_FLAG_ACTIVATED;
 
@@ -463,13 +521,13 @@ rt_err_t rt_timer_stop(rt_timer_t timer)
 RTM_EXPORT(rt_timer_stop);
 
 /**
- * This function will get or set some options of the timer
+ * @brief This function will get or set some options of the timer
  *
  * @param timer the timer to be get or set
  * @param cmd the control command
  * @param arg the argument
  *
- * @return RT_EOK
+ * @return the statu of control
  */
 rt_err_t rt_timer_control(rt_timer_t timer, int cmd, void *arg)
 {
@@ -521,10 +579,10 @@ rt_err_t rt_timer_control(rt_timer_t timer, int cmd, void *arg)
 RTM_EXPORT(rt_timer_control);
 
 /**
- * This function will check timer list, if a timeout event happens, the
- * corresponding timeout function will be invoked.
+ * @brief This function will check timer list, if a timeout event happens,
+ *        the corresponding timeout function will be invoked.
  *
- * @note this function shall be invoked in operating system timer interrupt.
+ * @note This function shall be invoked in operating system timer interrupt.
  */
 void rt_timer_check(void)
 {
@@ -542,9 +600,9 @@ void rt_timer_check(void)
     /* disable interrupt */
     level = rt_hw_interrupt_disable();
 
-    while (!rt_list_isempty(&rt_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1]))
+    while (!rt_list_isempty(&_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1]))
     {
-        t = rt_list_entry(rt_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1].next,
+        t = rt_list_entry(_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1].next,
                           struct rt_timer, row[RT_TIMER_SKIP_LIST_LEVEL - 1]);
 
         /*
@@ -556,7 +614,7 @@ void rt_timer_check(void)
             RT_OBJECT_HOOK_CALL(rt_timer_enter_hook, (t));
 
             /* remove timer from timer list firstly */
-            _rt_timer_remove(t);
+            _timer_remove(t);
             if (!(t->parent.flag & RT_TIMER_FLAG_PERIODIC))
             {
                 t->parent.flag &= ~RT_TIMER_FLAG_ACTIVATED;
@@ -596,19 +654,19 @@ void rt_timer_check(void)
 }
 
 /**
- * This function will return the next timeout tick in the system.
+ * @brief This function will return the next timeout tick in the system.
  *
  * @return the next timeout tick in the system
  */
 rt_tick_t rt_timer_next_timeout_tick(void)
 {
-    return rt_timer_list_next_timeout(rt_timer_list);
+    return _timer_list_next_timeout(_timer_list);
 }
 
 #ifdef RT_USING_TIMER_SOFT
 /**
- * This function will check software-timer list, if a timeout event happens, the
- * corresponding timeout function will be invoked.
+ * @brief This function will check software-timer list, if a timeout event happens, the
+ *        corresponding timeout function will be invoked.
  */
 void rt_soft_timer_check(void)
 {
@@ -624,9 +682,9 @@ void rt_soft_timer_check(void)
     /* disable interrupt */
     level = rt_hw_interrupt_disable();
 
-    while (!rt_list_isempty(&rt_soft_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1]))
+    while (!rt_list_isempty(&_soft_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1]))
     {
-        t = rt_list_entry(rt_soft_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1].next,
+        t = rt_list_entry(_soft_timer_list[RT_TIMER_SKIP_LIST_LEVEL - 1].next,
                             struct rt_timer, row[RT_TIMER_SKIP_LIST_LEVEL - 1]);
 
         current_tick = rt_tick_get();
@@ -640,7 +698,7 @@ void rt_soft_timer_check(void)
             RT_OBJECT_HOOK_CALL(rt_timer_enter_hook, (t));
 
             /* remove timer from timer list firstly */
-            _rt_timer_remove(t);
+            _timer_remove(t);
             if (!(t->parent.flag & RT_TIMER_FLAG_PERIODIC))
             {
                 t->parent.flag &= ~RT_TIMER_FLAG_ACTIVATED;
@@ -648,7 +706,7 @@ void rt_soft_timer_check(void)
             /* add timer to temporary list  */
             rt_list_insert_after(&list, &(t->row[RT_TIMER_SKIP_LIST_LEVEL - 1]));
 
-            soft_timer_status = RT_SOFT_TIMER_BUSY;
+            _soft_timer_status = RT_SOFT_TIMER_BUSY;
             /* enable interrupt */
             rt_hw_interrupt_enable(level);
 
@@ -661,7 +719,7 @@ void rt_soft_timer_check(void)
             /* disable interrupt */
             level = rt_hw_interrupt_disable();
 
-            soft_timer_status = RT_SOFT_TIMER_IDLE;
+            _soft_timer_status = RT_SOFT_TIMER_IDLE;
             /* Check whether the timer object is detached or started again */
             if (rt_list_isempty(&list))
             {
@@ -684,15 +742,19 @@ void rt_soft_timer_check(void)
     RT_DEBUG_LOG(RT_DEBUG_TIMER, ("software timer check leave\n"));
 }
 
-/* system timer thread entry */
-static void rt_thread_timer_entry(void *parameter)
+/**
+ * @brief System timer thread entry
+ *
+ * @param parameter is the arg of the thread
+ */
+static void _timer_thread_entry(void *parameter)
 {
     rt_tick_t next_timeout;
 
     while (1)
     {
         /* get the next timeout tick */
-        next_timeout = rt_timer_list_next_timeout(rt_soft_timer_list);
+        next_timeout = _timer_list_next_timeout(_soft_timer_list);
         if (next_timeout == RT_TICK_MAX)
         {
             /* no software timer exist, suspend self. */
@@ -718,27 +780,27 @@ static void rt_thread_timer_entry(void *parameter)
         rt_soft_timer_check();
     }
 }
-#endif
+#endif /* RT_USING_TIMER_SOFT */
 
 /**
  * @ingroup SystemInit
  *
- * This function will initialize system timer
+ * @brief This function will initialize system timer
  */
 void rt_system_timer_init(void)
 {
     int i;
 
-    for (i = 0; i < sizeof(rt_timer_list) / sizeof(rt_timer_list[0]); i++)
+    for (i = 0; i < sizeof(_timer_list) / sizeof(_timer_list[0]); i++)
     {
-        rt_list_init(rt_timer_list + i);
+        rt_list_init(_timer_list + i);
     }
 }
 
 /**
  * @ingroup SystemInit
  *
- * This function will initialize system timer thread
+ * @brief This function will initialize system timer thread
  */
 void rt_system_timer_thread_init(void)
 {
@@ -746,25 +808,25 @@ void rt_system_timer_thread_init(void)
     int i;
 
     for (i = 0;
-         i < sizeof(rt_soft_timer_list) / sizeof(rt_soft_timer_list[0]);
+         i < sizeof(_soft_timer_list) / sizeof(_soft_timer_list[0]);
          i++)
     {
-        rt_list_init(rt_soft_timer_list + i);
+        rt_list_init(_soft_timer_list + i);
     }
 
     /* start software timer thread */
-    rt_thread_init(&timer_thread,
+    rt_thread_init(&_timer_thread,
                    "timer",
-                   rt_thread_timer_entry,
+                   _timer_thread_entry,
                    RT_NULL,
-                   &timer_thread_stack[0],
-                   sizeof(timer_thread_stack),
+                   &_timer_thread_stack[0],
+                   sizeof(_timer_thread_stack),
                    RT_TIMER_THREAD_PRIO,
                    10);
 
     /* startup */
-    rt_thread_startup(&timer_thread);
-#endif
+    rt_thread_startup(&_timer_thread);
+#endif /* RT_USING_TIMER_SOFT */
 }
 
 /**@}*/