This is an automated email from the ASF dual-hosted git repository. jiuzhudong pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit dac48484ce4c97dbb9e893c95d0113b22eca2097 Author: ouyangxiangzhen <[email protected]> AuthorDate: Wed Jan 28 14:43:19 2026 +0800 sched/hrtimer: Update the comments. This commit updated the comments. Signed-off-by: ouyangxiangzhen <[email protected]> --- include/nuttx/hrtimer.h | 53 +++++++++++++++++++++----------------- sched/hrtimer/hrtimer.h | 19 ++++++++++---- sched/hrtimer/hrtimer_cancel.c | 7 ++--- sched/hrtimer/hrtimer_initialize.c | 14 +++++----- sched/hrtimer/hrtimer_process.c | 6 ++--- sched/hrtimer/hrtimer_start.c | 16 +++++------- 6 files changed, 62 insertions(+), 53 deletions(-) diff --git a/include/nuttx/hrtimer.h b/include/nuttx/hrtimer.h index b85413a02b1..e25cf2eb7f8 100644 --- a/include/nuttx/hrtimer.h +++ b/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, diff --git a/sched/hrtimer/hrtimer.h b/sched/hrtimer/hrtimer.h index 478ff90a88a..10b01323435 100644 --- a/sched/hrtimer/hrtimer.h +++ b/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. diff --git a/sched/hrtimer/hrtimer_cancel.c b/sched/hrtimer/hrtimer_cancel.c index 53ba5020814..50de9e15981 100644 --- a/sched/hrtimer/hrtimer_cancel.c +++ b/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. * ****************************************************************************/ diff --git a/sched/hrtimer/hrtimer_initialize.c b/sched/hrtimer/hrtimer_initialize.c index d6066e4cb78..77f9af5bce2 100644 --- a/sched/hrtimer/hrtimer_initialize.c +++ b/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. diff --git a/sched/hrtimer/hrtimer_process.c b/sched/hrtimer/hrtimer_process.c index 8f29622d172..66dc6e6a817 100644 --- a/sched/hrtimer/hrtimer_process.c +++ b/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. diff --git a/sched/hrtimer/hrtimer_start.c b/sched/hrtimer/hrtimer_start.c index 73364e3df95..f994fd3ef3a 100644 --- a/sched/hrtimer/hrtimer_start.c +++ b/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);
