sched: Include function document and decoration describing the functi…

…on and parameter
apache · Sep 15, 2023 · 308dc9d · 308dc9d
1 parent 39260d8
commit 308dc9d
Show file tree

Hide file tree

Showing 2 changed files with 153 additions and 0 deletions.
diff --git a/include/nuttx/spinlock.h b/include/nuttx/spinlock.h
@@ -466,10 +466,88 @@ void spin_unlock_irqrestore_wo_note(FAR spinlock_t *lock, irqstate_t flags);
 #endif
 
 #if defined(CONFIG_SMP)
+/****************************************************************************
+ * Name: fair_spinlock_list_init
+ *
+ * Description:
+ *   Initialize the link linsk of fair spinlock.
+ *   If there is any spinlock node, the node will get lock.
+ *
+ * Input Parameters:
+ *   lock_list - A reference to the spinlock list.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   None.
+ *
+ ****************************************************************************/
+
 void fair_spinlock_list_init(fair_spinlock_list_t *lock_list);
+
+/****************************************************************************
+ * Name: fair_spinlock_init
+ *
+ * Description:
+ *   Initialize the fair spinlock. Tje lock state is set as SP_LOCK util
+ *   some give lock to holder.
+ *
+ * Input Parameters:
+ *   lock - A reference to the spinlock object to lock.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   Not running at the interrupt level.
+ *
+ ****************************************************************************/
+
 void fair_spinlock_init(fair_spinlock_t *lock);
+
+/****************************************************************************
+ * Name: fair_spin_lock
+ *
+ * Description:
+ *   Try to lock the spinlock and insert this lock to lock list.
+ *   If list is empty, the caller can get the lock.
+ *   If list is not empty, the lock will be inserted to this list.
+ *
+ * Input Parameters:
+ *   lock_list - A reference to fair lock list and insert this lock to list.
+ *   fair_lock - A reference to the spinlock object to lock.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   Not running at the interrupt level.
+ *
+ ****************************************************************************/
+
 void fair_spin_lock(FAR fair_spinlock_list_t *lock_list,
                     FAR fair_spinlock_t *lock);
+
+/****************************************************************************
+ * Name: fair_spin_unlock
+ *
+ * Description:
+ *   Remove lock from list and release the lock from lock list.
+ *   If there is a caller waiting the lock, give the lock to next one.
+ *
+ * Input Parameters:
+ *   lock_list - A reference to fair lock list and insert this lock to list.
+ *   fair_lock - A reference to the spinlock object to lock.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   Not running at the interrupt level.
+ *
+ ****************************************************************************/
+
 void fair_spin_unlock(FAR  fair_spinlock_list_t *lock_list,
                     FAR fair_spinlock_t *lock);
 #endif

diff --git a/sched/semaphore/spinlock.c b/sched/semaphore/spinlock.c
@@ -384,19 +384,75 @@ void spin_clrbit(FAR volatile cpu_set_t *set, unsigned int cpu,
 }
 #endif
 
+/****************************************************************************
+ * Name: fair_spinlock_list_init
+ *
+ * Description:
+ *   Initialize the link linsk of fair spinlock.
+ *   If there is any spinlock node, the node will get lock.
+ *
+ * Input Parameters:
+ *   lock_list - A reference to the spinlock list.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   None.
+ *
+ ****************************************************************************/
+
 void fair_spinlock_list_init(fair_spinlock_list_t *lock_list)
 {
   lock_list->lock = SP_UNLOCKED;
   list_initialize(&lock_list->list);
 }
 
+/****************************************************************************
+ * Name: fair_spinlock_init
+ *
+ * Description:
+ *   Initialize the fair spinlock. Tje lock state is set as SP_LOCK util
+ *   some give lock to holder.
+ *
+ * Input Parameters:
+ *   lock - A reference to the spinlock object to lock.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   Not running at the interrupt level.
+ *
+ ****************************************************************************/
+
 void fair_spinlock_init(fair_spinlock_t *lock)
 {
   lock->lock = SP_LOCKED;
   lock->holder = this_task();
   list_initialize(&lock->node);
 }
 
+/****************************************************************************
+ * Name: fair_spin_lock
+ *
+ * Description:
+ *   Try to lock the spinlock and insert this lock to lock list.
+ *   If list is empty, the caller can get the lock.
+ *   If list is not empty, the lock will be inserted to this list.
+ *
+ * Input Parameters:
+ *   lock_list - A reference to fair lock list and insert this lock to list.
+ *   fair_lock - A reference to the spinlock object to lock.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   Not running at the interrupt level.
+ *
+ ****************************************************************************/
+
 void fair_spin_lock(FAR fair_spinlock_list_t *lock_list,
                     FAR fair_spinlock_t *fair_lock)
 {
@@ -443,6 +499,25 @@ void fair_spin_lock(FAR fair_spinlock_list_t *lock_list,
     }
 }
 
+/****************************************************************************
+ * Name: fair_spin_unlock
+ *
+ * Description:
+ *   Remove lock from list and release the lock from lock list.
+ *   If there is a caller waiting the lock, give the lock to next one.
+ *
+ * Input Parameters:
+ *   lock_list - A reference to fair lock list and insert this lock to list.
+ *   fair_lock - A reference to the spinlock object to lock.
+ *
+ * Returned Value:
+ *   None
+ *
+ * Assumptions:
+ *   Not running at the interrupt level.
+ *
+ ****************************************************************************/
+
 void fair_spin_unlock(FAR fair_spinlock_list_t *lock_list,
                       FAR fair_spinlock_t *fair_lock)
 {