From e6f5282f6e547c2924c8921dcfacfb13de4f9e60 Mon Sep 17 00:00:00 2001
From: guozhanxin <guozhanxin@rt-thread.com>
Date: Fri, 10 Sep 2021 18:08:30 +0800
Subject: [PATCH] [kernel] Improve the code comment of the cpu.c

---
 src/cpu.c | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 50 insertions(+), 3 deletions(-)

diff --git a/src/cpu.c b/src/cpu.c
index fc1fed5a06..5466a350ae 100644
--- a/src/cpu.c
+++ b/src/cpu.c
@@ -65,12 +65,26 @@ 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.
+ *            It is assumed that storage for the spinlock will be allocated in your application.
+ */
 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 +92,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 +104,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 +127,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 +144,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 +193,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)
 {