sched/hrtimer: Update the comments.

This commit updated the comments.

Signed-off-by: ouyangxiangzhen <ouyangxiangzhen@xiaomi.com>

include/nuttx/hrtimer.h

@@ -113,17 +113,14 @@ extern "C"
  * Name: hrtimer_init
  *
  * Description:
- *   Initialize a high-resolution timer instance. This function sets the
- *   expiration callback and its argument. The timer is initialized in the
- *   inactive state and is not armed until hrtimer_start() is called.
+ *   Initialize a high-resolution timer instance.
  *
  * Input Parameters:
  *   hrtimer - Pointer to the hrtimer instance to be initialized
- *   func    - Expiration callback function
- *   arg     - Argument passed to the callback
  *
  * Returned Value:
  *   None
+ *
  ****************************************************************************/
 
 #define hrtimer_init(hrtimer) memset(hrtimer, 0, sizeof(hrtimer_t))
@@ -132,14 +129,23 @@ extern "C"
  * Name: hrtimer_cancel
  *
  * Description:
- *   Cancel a high-resolution timer asynchronously. This function set the
+ *   Cancel a high-resolution timer asynchronously.
+ *
+ *   If the timer is currently pending, it will be removed from the
+ *   hrtimer queue and will not be executed.
+ *
+ *   If the timer callback is currently executing. This function set the
  *   timer to the cancelled state. The caller will acquire the limited
  *   ownership of the hrtimer, which allow the caller restart the hrtimer,
- *   but the callback function may still be executing on another CPU, which
- *   prevent the caller from freeing the hrtimer. The caller must call
- *   `hrtimer_cancel` to wait for the callback to be finished. Please use
- *   the function with care. Concurrency errors are prone to occur in this
- *   use case.
+ *   but the callback function may still be executing on another CPU,
+ *   which prevent the caller from freeing the hrtimer.
+ *   The caller must call `hrtimer_cancel_sync` to wait for the callback
+ *   to be finished. Please use the function with care.
+ *   Concurrency errors are prone to occur in this use case.
+ *
+ *   If the canceled timer was the earliest expired timer in the queue,
+ *   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.
@@ -151,11 +157,8 @@ extern "C"
  *   OK (0) on success; a negated errno value on failure.
  *   > 0 on if the timer callback is running.
  *
- * Assumptions/Notes:
- *   - This function acquires the global hrtimer spinlock to protect both
- *     the red-black tree and the timer state.
- *   - The caller must ensure that the timer structure is not freed until
- *     it is guaranteed that any running callback has returned.
+ * Assumptions:
+ *   - The hrtimer is not NULL.
  *
  ****************************************************************************/
 
@@ -165,13 +168,16 @@ int hrtimer_cancel(FAR hrtimer_t *hrtimer);
  * Name: hrtimer_cancel_sync
  *
  * Description:
- *   Cancel a high-resolution timer and wait until it becomes inactive.
- *
  *   Cancel a high-resolution timer and synchronously wait the callback to
- *   be finished. This function set the timer to the cancelled state and wait
- *   for all references to be released. The caller will then acquire full
- *   ownership of the hrtimer. After the function returns, the caller can
- *   safely deallocate the hrtimer.
+ *   be finished.
+ *
+ *   If the timer callback is running, this function set the timer to the
+ *   cancelled state and wait for all all references to be released.
+ *   The caller will then acquire full ownership of the hrtimer. After the
+ *   function returns, the caller can safely deallocate the hrtimer.
+ *   - If sleeping is allowed (normal task context), yields CPU briefly
+ *     to avoid busy-waiting.
+ *   - Otherwise (interrupt or idle task context), spins until completion.
  *
  * Input Parameters:
  *   hrtimer - Pointer to the high-resolution timer instance to cancel.
@@ -193,13 +199,14 @@ int hrtimer_cancel_sync(FAR hrtimer_t *hrtimer);
  *   a relative timeout, depending on the selected mode.
  *
  * Input Parameters:
- *   hrtimer - Timer instance to start
+ *   hrtimer - Pointer to high-resolution timer.
  *   func    - Expiration callback function
  *   expired - Expiration time in nanoseconds
  *   mode    - HRTIMER_MODE_ABS or HRTIMER_MODE_REL
  *
  * Returned Value:
  *   OK on success; a negated errno value on failure.
+ *
  ****************************************************************************/
 
 int hrtimer_start_absolute(FAR hrtimer_t *hrtimer, hrtimer_entry_t func,

sched/hrtimer/hrtimer.h

@@ -116,7 +116,8 @@ extern uintptr_t g_hrtimer_running[CONFIG_SMP_NCPUS];
  *   now - The current time (nsecs).
  *
  * Returned Value:
- *   None
+ *   None.
+ *
  ****************************************************************************/
 
 void hrtimer_process(uint64_t now);
@@ -141,6 +142,7 @@ void hrtimer_process(uint64_t now);
  *
  * Assumptions:
  *   The underlying timer start function returns 0 on success.
+ *
  ****************************************************************************/
 
 static inline_function void hrtimer_reprogram(uint64_t next_expired)
@@ -174,15 +176,21 @@ static inline_function void hrtimer_reprogram(uint64_t next_expired)
  *
  * Description:
  *   Compare two high-resolution timer nodes to determine their ordering
- *   in the container. Used internally by the RB-tree macros.
+ *   in the hrtimer queue. Used internally by the RB-tree macros.
+ *
+ *   Note that RB-tree can not guarantee that timers with the same expired
+ *   time will be processed in a FIFO order. However, this violation
+ *   of the sorted queue invariant is acceptable and can not affect the
+ *   functional correctness for the hrtimer.
  *
  * Input Parameters:
  *   a - Pointer to the first hrtimer node.
  *   b - Pointer to the second hrtimer node.
  *
  * Returned Value:
- *   <0 if a expires before b
- *   >=0 if a expires after b
+ *   <0 if a expires before b.
+ *   >=0 if a expires after b.
+ *
  ****************************************************************************/
 
 #ifdef CONFIG_HRTIMER_TREE
@@ -304,6 +312,7 @@ static inline_function bool hrtimer_insert(FAR hrtimer_t *hrtimer)
  *
  * Returned Value:
  *   Pointer to the earliest timer, or NULL if none are pending.
+ *
  ****************************************************************************/
 
 static inline_function FAR hrtimer_t *hrtimer_get_first(void)
@@ -324,7 +333,7 @@ static inline_function FAR hrtimer_t *hrtimer_get_first(void)
  *   of the value you are reading.
  *
  * Input Parameters:
- *   ptr   - The pointer to be read.
+ *   ptr - The pointer to be read.
  *
  * Returned Value:
  *   The value in the queue.

sched/hrtimer/hrtimer_cancel.c

@@ -67,11 +67,8 @@
  *   OK (0) on success; a negated errno value on failure.
  *   > 0 on if the timer callback is running.
  *
- * Assumptions/Notes:
- *   - 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.
+ * Assumptions:
+ *   - The hrtimer is not NULL.
  *
  ****************************************************************************/
 

sched/hrtimer/hrtimer_initialize.c

@@ -42,19 +42,19 @@ uintptr_t g_hrtimer_running[CONFIG_SMP_NCPUS];
 
 /* Global spinlock protecting the high-resolution timer subsystem.
  *
- * This spinlock serializes access to the hrtimer container and
+ * This spinlock serializes access to the hrtimer queue and
  * protects timer state transitions. It must be held whenever the
- * timer container is modified.
+ * timer queue is modified.
  */
 
 seqcount_t g_hrtimer_lock = SEQLOCK_INITIALIZER;
 
-/* Container for all active high-resolution timers.
+/* HRTimer queue for all active high-resolution timers.
  *
- * When CONFIG_HRTIMER_TREE is enabled, timers are stored in a container.
+ * When CONFIG_HRTIMER_TREE is enabled, timers are stored in a queue.
  * When disabled, timers are stored in a linked list.
  *
- * The container is ordered by absolute expiration time in
+ * The queue is ordered by absolute expiration time in
  * both configurations.
  */
 
@@ -90,11 +90,11 @@ struct list_node g_hrtimer_list =
  * Name: RB_GENERATE
  *
  * Description:
- *   Instantiate the container helper functions for the hrtimer
+ *   Instantiate the queue helper functions for the hrtimer
  *   subsystem.
  *
  *   This macro generates the static inline functions required to
- *   manipulate the hrtimer container, including insertion,
+ *   manipulate the hrtimer queue, including insertion,
  *   removal, and lookup operations.
  *
  *   Note: This is only compiled when CONFIG_HRTIMER_TREE is enabled.

sched/hrtimer/hrtimer_process.c

@@ -40,9 +40,9 @@
  *
  * Description:
  *   Process all expired high-resolution timers. This function repeatedly
- *   retrieves the earliest timer from the active timer container, checks
+ *   retrieves the earliest timer from the active timer queue, checks
  *   if it has expired relative to the current time, removes it from the
- *   container, and invokes its callback function. Processing continues
+ *   queue, and invokes its callback function. Processing continues
  *   until:
  *
  *     1. No additional timers have expired, or
@@ -62,7 +62,7 @@
  *   None.
  *
  * Assumptions/Notes:
- *   - This function acquires a spinlock to protect the timer container.
+ *   - This function acquires a spinlock to protect the timer queue.
  *   - Timer callbacks are invoked with interrupts enabled
  *     to avoid deadlocks.
  *   - DEBUGASSERT ensures that timer callbacks are valid.

sched/hrtimer/hrtimer_start.c

@@ -43,20 +43,16 @@
  *   in nanoseconds.
  *
  * Input Parameters:
- *   hrtimer - Pointer to the hrtimer structure.
+ *   hrtimer - Pointer to the hrtimer.
  *   func    - Expiration callback function.
- *   expired - Expiration time in nanoseconds. Interpretation
- *             depends on mode.
+ *   expired - Expiration time in nanoseconds.
  *
  * Returned Value:
  *   OK (0) on success, or a negated errno value on failure.
  *
- * Assumptions/Notes:
- *   - This function disables interrupts briefly via spinlock to safely
- *     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.
+ * Assumptions:
+ *   - hrtimer is not NULL and func is not NULL.
+ *
  ****************************************************************************/
 
 int hrtimer_start_absolute(FAR hrtimer_t *hrtimer, hrtimer_entry_t func,
@@ -72,7 +68,7 @@ int hrtimer_start_absolute(FAR hrtimer_t *hrtimer, hrtimer_entry_t func,
 
   flags = write_seqlock_irqsave(&g_hrtimer_lock);
 
-  /* Ensure no core can write the hrtimer. */
+  /* Ensure no running core can write the hrtimer. */
 
   hrtimer_cancel_running(hrtimer);