This is an automated email from the ASF dual-hosted git repository. ligd pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 24651af90c60006b2ccea01fd960a2caa9c9a921 Author: wangchengdong <[email protected]> AuthorDate: Tue Jan 6 12:24:09 2026 +0800 [EXPERIMENTAL]sched/hrtimer: update hrtimer document Update the hrtimer documentation to describe the hrtimer state machine, which is introduced to handle safe cancellation and execution in SMP environments. Signed-off-by: Chengdong Wang <[email protected]> --- .../reference/os/hrtimer_state_machine.png | Bin 0 -> 357712 bytes Documentation/reference/os/time_clock.rst | 21 +++++++++++++++++---- 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/Documentation/reference/os/hrtimer_state_machine.png b/Documentation/reference/os/hrtimer_state_machine.png new file mode 100644 index 00000000000..27fa6474710 Binary files /dev/null and b/Documentation/reference/os/hrtimer_state_machine.png differ diff --git a/Documentation/reference/os/time_clock.rst b/Documentation/reference/os/time_clock.rst index 7b09710ca17..86d35955827 100644 --- a/Documentation/reference/os/time_clock.rst +++ b/Documentation/reference/os/time_clock.rst @@ -675,14 +675,28 @@ The callback runs in the timer interrupt context, so only limited NuttX interfac are available, such as ``mq_send()``, ``sigqueue()``, ``nxevent_post()``, or ``kill()``, to communicate with tasks. +High-resolution timers (hrtimers) use a spinlock to protect internal timer data structures, +allowing them to be safely accessed from interrupt context. This design makes hrtimers +suitable for high-frequency timer operations. + +However, in SMP systems, a potential issue arises when a user cancels a timer that is currently +executing: the timer instance may be freed prematurely while its callback is still running. +To address this problem, a state machine is introduced in the hrtimer implementation: + +.. image:: hrtimer_state_machine.png + :alt: hrtimer state machine + +Users may call ``hrtimer_cancel_sync()`` to synchronously cancel a timer and wait until the +timer becomes fully inactive. In contrast, ``hrtimer_cancel()`` is a non-blocking variant +that returns immediately without waiting for the timer to stop executing. + - :c:func:`hrtimer_init` - :c:func:`hrtimer_cancel` - :c:func:`hrtimer_cancel_sync` - :c:func:`hrtimer_start` - High-resolution Timer Callback -.. c:function:: void hrtimer_init(FAR hrtimer_t *hrtimer, hrtentry_t func, \ - FAR void *arg) +.. c:function:: void hrtimer_init(FAR hrtimer_t *hrtimer, hrtentry_t func) This function initializes a high-resolution timer instance. Sets the expiration callback and its argument. The timer is @@ -690,7 +704,6 @@ to communicate with tasks. :param hrtimer: Pointer to hrtimer instance :param func: Expiration callback function - :param arg: Callback argument :return: None. @@ -745,7 +758,7 @@ to communicate with tasks. **POSIX Compatibility:** This is a NON-POSIX interface. -.. c:type:: void (*hrtentry_t)(FAR struct hrtimer_s *) +.. c:type:: uint64_t (*hrtimer_cb)(FAR hrtimer_t *hrtimer, uint64_t expired) **High-resolution Timer Callback**: when a hrtimer expires, the callback function with this type is called.
