sched/hrtimer: refresh code comments to match implementation

Several code comments in the hrtimer subsystem have become outdated
following recent implementation changes. This patch updates them to
accurately describe the current code behavior and algorithms.

Signed-off-by: Chengdong Wang <wangcd91@gmail.com>

include/nuttx/hrtimer.h

@@ -65,7 +65,7 @@ struct hrtimer_s;
 typedef CODE uint64_t (*hrtimer_entry_t)(FAR const struct hrtimer_s *hrtimer,
                                          uint64_t expired);
 
-/* Red-black tree node used to order hrtimers by expiration time */
+/* Hrtimer container node used to order hrtimers by expiration time */
 
 typedef struct hrtimer_node_s
 {
@@ -85,7 +85,7 @@ typedef struct hrtimer_node_s
 
 typedef struct hrtimer_s
 {
-  hrtimer_node_t node;   /* RB-tree node for sorted insertion */
+  hrtimer_node_t node;   /* Container node for sorted insertion */
   hrtimer_entry_t func;  /* Expiration callback function */
   uint64_t expired;      /* Absolute expiration time (ns) */
 } hrtimer_t;

sched/hrtimer/hrtimer.h

@@ -52,7 +52,7 @@ RB_HEAD(hrtimer_tree_s, hrtimer_node_s);
  * Public Data
  ****************************************************************************/
 
-/* Spinlock protecting access to the hrtimer RB-tree and timer state */
+/* Spinlock protecting access to the hrtimer container and timer state */
 
 extern spinlock_t g_hrtimer_spinlock;
 
@@ -162,7 +162,7 @@ int hrtimer_starttimer(uint64_t ns)
  *
  * Description:
  *   Compare two high-resolution timer nodes to determine their ordering
- *   in the red-black tree. Used internally by the RB-tree macros.
+ *   in the container. Used internally by the RB-tree macros.
  *
  * Input Parameters:
  *   a - Pointer to the first hrtimer node.
@@ -202,7 +202,7 @@ RB_PROTOTYPE(hrtimer_tree_s, hrtimer_node_s, entry, hrtimer_compare);
  * Name: hrtimer_is_armed
  *
  * Description:
- *   Test whether a timer is currently armed (inserted into the RB-tree).
+ *   Test whether a timer is currently armed (inserted into the container).
  *
  * Returned Value:
  *   true if armed, false otherwise.
@@ -217,7 +217,7 @@ static inline_function bool hrtimer_is_armed(FAR hrtimer_t *hrtimer)
  * Name: hrtimer_remove
  *
  * Description:
- *   Remove a timer from the RB-tree and mark it as unarmed.
+ *   Remove a timer from the container and mark it as unarmed.
  ****************************************************************************/
 
 static inline_function void hrtimer_remove(FAR hrtimer_t *hrtimer)
@@ -228,7 +228,7 @@ static inline_function void hrtimer_remove(FAR hrtimer_t *hrtimer)
   list_delete_fast(&hrtimer->node.entry);
 #endif
 
-  /* Explicitly clear parent to mark the timer as unarmed */
+  /* Explicitly mark the timer as unarmed */
 
   hrtimer->func = NULL;
 }
@@ -237,7 +237,8 @@ static inline_function void hrtimer_remove(FAR hrtimer_t *hrtimer)
  * Name: hrtimer_insert
  *
  * Description:
- *   Insert a timer into the RB-tree according to its expiration time.
+ *   Insert a timer into the timer container according to its
+ *   expiration time.
  ****************************************************************************/
 
 static inline_function void hrtimer_insert(FAR hrtimer_t *hrtimer)
@@ -286,9 +287,9 @@ static inline_function FAR hrtimer_t *hrtimer_get_first(void)
  *
  * Description:
  *   Test whether the given high-resolution timer is the earliest
- *   expiring timer in the RB-tree.
+ *   expiring timer in the container.
  *
- *   In a red-black tree ordered by expiration time, the earliest timer
+ *   In a container ordered by expiration time, the earliest timer
  *   is represented by the left-most node. Therefore, a timer is the
  *   earliest one if it has no left child.
  *

sched/hrtimer/hrtimer_cancel.c

@@ -86,17 +86,15 @@ static inline_function bool hrtimer_is_active(FAR hrtimer_t *hrtimer)
  *   Cancel a high-resolution timer.
  *
  *   If the timer is currently armed, it will be removed from the active
- *   hrtimer red-black tree and will not be executed.
+ *   hrtimer container (tree or list) and will not be executed.
  *
  *   If the timer callback is currently executing, the timer will be marked
- *   as canceled.  The running callback is allowed to complete, but the timer
+ *   as canceled. The running callback is allowed to complete, but the timer
  *   will not be re-armed or executed again.
  *
- *   If the canceled timer was the earliest (head) timer in the tree, the
- *   expiration of the underlying hardware timer will be updated to:
- *
- *     1. The expiration time of the next earliest timer, or
- *     2. A safe default expiration if no timers remain.
+ *   If the canceled timer was the earliest (head) timer in the container,
+ *   the expiration of the underlying hardware timer will be updated to the
+ *   expiration time of the next earliest timer
  *
  *   This function is non-blocking and does not wait for a running callback
  *   to finish.
@@ -108,8 +106,8 @@ static inline_function bool hrtimer_is_active(FAR hrtimer_t *hrtimer)
  *   OK (0) on success; a negated errno value on failure.
  *
  * Assumptions/Notes:
- *   - This function acquires the global hrtimer spinlock to protect both
- *     the red-black tree and the timer state.
+ *   - This function acquires the global hrtimer spinlock to protect
+ *     the container.
  *   - The caller must ensure that the timer structure is not freed until
  *     it is guaranteed that any running callback has returned.
  *
@@ -123,7 +121,7 @@ int hrtimer_cancel(FAR hrtimer_t *hrtimer)
 
   DEBUGASSERT(hrtimer != NULL);
 
-  /* Enter critical section to protect the hrtimer tree and state */
+  /* Enter critical section to protect the hrtimer container */
 
   flags = spin_lock_irqsave(&g_hrtimer_spinlock);
 
@@ -162,8 +160,7 @@ int hrtimer_cancel(FAR hrtimer_t *hrtimer)
  *   Cancel a high-resolution timer and wait until it becomes inactive.
  *
  *   - Calls hrtimer_cancel() to request timer cancellation.
- *   - If the timer callback is running, waits until it completes and
- *     the timer state transitions to HRTIMER_STATE_INACTIVE.
+ *   - If the timer callback is running, waits until it completes.
  *   - If sleeping is allowed (normal task context), yields CPU briefly
  *     to avoid busy-waiting.
  *   - Otherwise (interrupt or idle task context), spins until completion.
@@ -190,11 +187,10 @@ int hrtimer_cancel_sync(FAR hrtimer_t *hrtimer)
       return ret;
     }
 
-  /* Wait until the timer transitions to the inactive state.
+  /* Wait until all cpu finish running the timer callback.
    *
    * If sleeping is permitted, yield the CPU briefly to avoid
-   * busy-waiting.  Otherwise, spin until the callback completes
-   * and the state becomes inactive.
+   * busy-waiting. Otherwise, spin until the callback completes.
    */
 #ifdef CONFIG_SMP
   while (hrtimer_is_active(hrtimer))

sched/hrtimer/hrtimer_initialize.c

@@ -42,24 +42,29 @@ FAR hrtimer_t *g_hrtimer_running[CONFIG_SMP_NCPUS];
 
 /* Global spinlock protecting the high-resolution timer subsystem.
  *
- * This spinlock serializes access to the hrtimer red-black tree and
+ * This spinlock serializes access to the hrtimer container and
  * protects timer state transitions. It must be held whenever the
- * timer tree or hrtimer state is modified.
+ * timer container is modified.
  */
 
 spinlock_t g_hrtimer_spinlock = SP_UNLOCKED;
 
-/* Red-black tree containing all active high-resolution timers.
+/* Container for all active high-resolution timers.
  *
- * Only timers in the ARMED state are present in this tree. Timers in
- * the RUNNING, CANCELED, or INACTIVE states must not be inserted.
+ * When CONFIG_HRTIMER_TREE is enabled, timers are stored in a container.
+ * When disabled, timers are stored in a linked list.
  *
- * The tree is ordered by absolute expiration time.
+ * The container is ordered by absolute expiration time in
+ * both configurations.
  */
 
 #ifdef CONFIG_HRTIMER_TREE
+/* Red-black tree for hrtimer storage (requires CONFIG_HRTIMER_TREE) */
+
 struct hrtimer_tree_s g_hrtimer_tree = RB_INITIALIZER(g_hrtimer_tree);
 #else
+/* Linked list for hrtimer storage (fallback when tree is disabled) */
+
 struct list_node g_hrtimer_list = LIST_INITIAL_VALUE(g_hrtimer_list);
 #endif
 
@@ -71,13 +76,15 @@ struct list_node g_hrtimer_list = LIST_INITIAL_VALUE(g_hrtimer_list);
  * Name: RB_GENERATE
  *
  * Description:
- *   Instantiate the red-black tree helper functions for the hrtimer
+ *   Instantiate the container helper functions for the hrtimer
  *   subsystem.
  *
  *   This macro generates the static inline functions required to
- *   manipulate the hrtimer red-black tree, including insertion,
+ *   manipulate the hrtimer container, including insertion,
  *   removal, and lookup operations.
  *
+ *   Note: This is only compiled when CONFIG_HRTIMER_TREE is enabled.
+ *
  * Assumptions/Notes:
  *   - The tree key is the absolute expiration time stored in
  *     hrtimer_node_s and compared via hrtimer_compare().

sched/hrtimer/hrtimer_process.c

@@ -40,9 +40,10 @@
  *
  * Description:
  *   Process all expired high-resolution timers. This function repeatedly
- *   retrieves the earliest timer from the active timer RB-tree, checks if it
- *   has expired relative to the current time, removes it from the tree,
- *   and invokes its callback function. Processing continues until:
+ *   retrieves the earliest timer from the active timer container, checks
+ *   if it has expired relative to the current time, removes it from the
+ *   container, and invokes its callback function. Processing continues
+ *   until:
  *
  *     1. No additional timers have expired, or
  *     2. The active timer set is empty.
@@ -61,7 +62,7 @@
  *   None.
  *
  * Assumptions/Notes:
- *   - This function acquires a spinlock to protect the timer RB-tree.
+ *   - This function acquires a spinlock to protect the timer container.
  *   - Timer callbacks are invoked with interrupts enabled
  *     to avoid deadlocks.
  *   - DEBUGASSERT ensures that timer callbacks are valid.
@@ -78,7 +79,7 @@ void hrtimer_process(uint64_t now)
   int cpu = this_cpu();
 #endif
 
-  /* Lock the hrtimer RB-tree to protect access */
+  /* Lock the hrtimer container to protect access */
 
   flags = spin_lock_irqsave(&g_hrtimer_spinlock);
 
@@ -103,7 +104,7 @@ void hrtimer_process(uint64_t now)
           break;
         }
 
-      /* Remove the expired timer from the active tree */
+      /* Remove the expired timer from the timer container */
 
       hrtimer_remove(hrtimer);
 
@@ -128,7 +129,7 @@ void hrtimer_process(uint64_t now)
 
       /* If the timer is periodic and has not been rearmed or
        * cancelled concurrently,
-       * compute next expiration and reinsert into RB-tree
+       * compute next expiration and reinsert into container
        */
 
       if (period > 0 && hrtimer->expired == expired)

sched/hrtimer/hrtimer_start.c

@@ -54,7 +54,7 @@
  *
  * Assumptions/Notes:
  *   - This function disables interrupts briefly via spinlock to safely
- *     insert the timer into the RB-tree.
+ *     insert the timer into the container.
  *   - Absolute mode sets the timer to expire at the given absolute time.
  *   - Relative mode sets the timer to expire after 'ns'
  *     nanoseconds from the current time.
@@ -69,7 +69,7 @@ int hrtimer_start(FAR hrtimer_t *hrtimer, hrtimer_entry_t func,
 
   DEBUGASSERT(hrtimer != NULL);
 
-  /* Protect RB-tree manipulation with spinlock and disable interrupts */
+  /* Protect container manipulation with spinlock and disable interrupts */
 
   flags = spin_lock_irqsave(&g_hrtimer_spinlock);
 
@@ -95,7 +95,7 @@ int hrtimer_start(FAR hrtimer_t *hrtimer, hrtimer_entry_t func,
 
   DEBUGASSERT(hrtimer->expired >= expired);
 
-  /* Insert the timer into the RB-tree */
+  /* Insert the timer into the container */
 
   hrtimer_insert(hrtimer);