Merge pull request #5039 from Guozhanxin/kernel_comment

Improve the Kernel comment

3 files changed, 85 insertions, 19 deletions

diff --git a/src/clock.c b/src/clock.c
index 77516b3775..fb7ee447d2 100644
--- a/src/clock.c
+++ b/src/clock.c
@@ -33,9 +33,9 @@ static volatile rt_tick_t rt_tick = 0;
 /**@{*/
 
 /**
- * This function will return current tick from operating system startup
+ * @brief    This function will return current tick from operating system startup
  *
- * @return current tick
+ * @return   Return current tick
  */
 rt_tick_t rt_tick_get(void)
 {
@@ -45,7 +45,9 @@ rt_tick_t rt_tick_get(void)
 RTM_EXPORT(rt_tick_get);
 
 /**
- * This function will set current tick
+ * @brief    This function will set current tick
+ *
+ * @param    tick is the value that you will set.
  */
 void rt_tick_set(rt_tick_t tick)
 {
@@ -57,8 +59,8 @@ void rt_tick_set(rt_tick_t tick)
 }
 
 /**
- * This function will notify kernel there is one tick passed. Normally,
- * this function is invoked by clock ISR.
+ * @brief    This function will notify kernel there is one tick passed.
+ *           Normally, this function is invoked by clock ISR.
  */
 void rt_tick_increase(void)
 {
@@ -97,14 +99,14 @@ void rt_tick_increase(void)
 }
 
 /**
- * This function will calculate the tick from millisecond.
+ * @brief    This function will calculate the tick from millisecond.
  *
- * @param ms the specified millisecond
- *           - Negative Number wait forever
- *           - Zero not wait
- *           - Max 0x7fffffff
+ * @param    ms is the specified millisecond
+ *              - Negative Number wait forever
+ *              - Zero not wait
+ *              - Max 0x7fffffff
  *
- * @return the calculated tick
+ * @return   Return the calculated tick
  */
 rt_tick_t rt_tick_from_millisecond(rt_int32_t ms)
 {
@@ -126,9 +128,13 @@ rt_tick_t rt_tick_from_millisecond(rt_int32_t ms)
 RTM_EXPORT(rt_tick_from_millisecond);
 
 /**
- * This function will provide the passed millisecond from boot.
+ * @brief    This function will return the passed millisecond from boot.
+ *
+ * @note     if the value of RT_TICK_PER_SECOND is lower than 1000 or
+ *           is not an integral multiple of 1000, this function will not
+ *           provide the correct 1ms-based tick.
  *
- * @return passed millisecond from boot
+ * @return   Return passed millisecond from boot
  */
 RT_WEAK rt_tick_t rt_tick_get_millisecond(void)
 {
diff --git a/src/components.c b/src/components.c
index e156b783e4..9433b7457c 100644
--- a/src/components.c
+++ b/src/components.c
@@ -78,7 +78,9 @@ static int rti_end(void)
 INIT_EXPORT(rti_end, "6.end");
 
 /**
- * RT-Thread Components Initialization for board
+ * @brief  Onboard components initialization. In this function, the board-level
+ *         initialization function will be called to complete the initialization
+ *         of the on-board peripherals.
  */
 void rt_components_board_init(void)
 {
@@ -102,7 +104,7 @@ void rt_components_board_init(void)
 }
 
 /**
- * RT-Thread Components Initialization
+ * @brief  RT-Thread Components Initialization.
  */
 void rt_components_init(void)
 {
@@ -169,7 +171,11 @@ static rt_uint8_t main_stack[RT_MAIN_THREAD_STACK_SIZE];
 struct rt_thread main_thread;
 #endif /* RT_USING_HEAP */
 
-/* the system main thread */
+/**
+ * @brief  The system main thread. In this thread will call the rt_components_init()
+ *         for initialization of RT-Thread Components and call the user's programming
+ *         entry main().
+ */
 void main_thread_entry(void *parameter)
 {
     extern int main(void);
@@ -193,6 +199,10 @@ void main_thread_entry(void *parameter)
 #endif
 }
 
+/**
+ * @brief  This function will create and start the main thread, but this thread
+ *         will not run until the scheduler starts.
+ */
 void rt_application_init(void)
 {
     rt_thread_t tid;
@@ -216,6 +226,10 @@ void rt_application_init(void)
     rt_thread_startup(tid);
 }
 
+/**
+ * @brief  This function will call all levels of initialization functions to complete
+ *         the initialization of the system, and finally start the scheduler.
+ */
 int rtthread_startup(void)
 {
     rt_hw_interrupt_disable();
diff --git a/src/cpu.c b/src/cpu.c
index fc1fed5a06..b689ecf2d7 100644
--- a/src/cpu.c
+++ b/src/cpu.c
@@ -65,12 +65,25 @@ static void _cpu_preempt_enable(void)
     rt_hw_local_irq_enable(level);
 }
 
+/**
+ * @brief   Initialize a static spinlock object.
+ *
+ * @param   lock is a pointer to the spinlock to initialize.
+ */
 void rt_spin_lock_init(struct rt_spinlock *lock)
 {
     rt_hw_spin_lock_init(&lock->lock);
 }
 RTM_EXPORT(rt_spin_lock_init)
 
+/**
+ * @brief   This function will lock the spinlock.
+ *
+ * @note    If the spinlock is locked, the current CPU will keep polling the spinlock state
+ *          until the spinlock is unlocked.
+ *
+ * @param   lock is a pointer to the spinlock.
+ */
 void rt_spin_lock(struct rt_spinlock *lock)
 {
     _cpu_preempt_disable();
@@ -78,6 +91,11 @@ void rt_spin_lock(struct rt_spinlock *lock)
 }
 RTM_EXPORT(rt_spin_lock)
 
+/**
+ * @brief   This function will unlock the spinlock.
+ *
+ * @param   lock is a pointer to the spinlock.
+ */
 void rt_spin_unlock(struct rt_spinlock *lock)
 {
     rt_hw_spin_unlock(&lock->lock);
@@ -85,6 +103,16 @@ void rt_spin_unlock(struct rt_spinlock *lock)
 }
 RTM_EXPORT(rt_spin_unlock)
 
+/**
+ * @brief   This function will disable the local interrupt and then lock the spinlock.
+ *
+ * @note    If the spinlock is locked, the current CPU will keep polling the spinlock state
+ *          until the spinlock is unlocked.
+ *
+ * @param   lock is a pointer to the spinlock.
+ *
+ * @return  Return current cpu interrupt status.
+ */
 rt_base_t rt_spin_lock_irqsave(struct rt_spinlock *lock)
 {
     unsigned long level;
@@ -98,6 +126,13 @@ rt_base_t rt_spin_lock_irqsave(struct rt_spinlock *lock)
 }
 RTM_EXPORT(rt_spin_lock_irqsave)
 
+/**
+ * @brief   This function will unlock the spinlock and then restore current cpu interrupt status.
+ *
+ * @param   lock is a pointer to the spinlock.
+ *
+ * @param   level is interrupt status returned by rt_spin_lock_irqsave().
+ */
 void rt_spin_unlock_irqrestore(struct rt_spinlock *lock, rt_base_t level)
 {
     rt_hw_spin_unlock(&lock->lock);
@@ -108,20 +143,29 @@ void rt_spin_unlock_irqrestore(struct rt_spinlock *lock, rt_base_t level)
 RTM_EXPORT(rt_spin_unlock_irqrestore)
 
 /**
- * This fucntion will return current cpu.
+ * @brief   This fucntion will return current cpu object.
+ *
+ * @return  Return a pointer to the current cpu object.
  */
 struct rt_cpu *rt_cpu_self(void)
 {
     return &_cpus[rt_hw_cpu_id()];
 }
 
+/**
+ * @brief   This fucntion will return the cpu object corresponding to index.
+ *
+ * @return  Return a pointer to the cpu object corresponding to index.
+ */
 struct rt_cpu *rt_cpu_index(int index)
 {
     return &_cpus[index];
 }
 
 /**
- * This function will lock all cpus's scheduler and disable local irq.
+ * @brief   This function will lock all cpus's scheduler and disable local irq.
+ *
+ * @return  Return current cpu interrupt status.
  */
 rt_base_t rt_cpus_lock(void)
 {
@@ -148,7 +192,9 @@ rt_base_t rt_cpus_lock(void)
 RTM_EXPORT(rt_cpus_lock);
 
 /**
- * This function will restore all cpus's scheduler and restore local irq.
+ * @brief   This function will restore all cpus's scheduler and restore local irq.
+ *
+ * @param   level is interrupt status returned by rt_cpus_lock().
  */
 void rt_cpus_unlock(rt_base_t level)
 {