wangchdo commented on code in PR #17675: URL: https://github.com/apache/nuttx/pull/17675#discussion_r2647696432
########## Documentation/reference/os/time_clock.rst: ########## @@ -665,87 +665,183 @@ require nanosecond-level task timing, which tick-based timers like wdog cannot provide. Reducing the tick interval to micro- or nanoseconds is impractical, as it would overload the CPU with interrupts. -To address this, NuttX provides a high-resolution timer (hrtimer), -which delivers true nanosecond-level precision. Unlike wdog’s list-based timers, -hrtimer uses a red-black tree for efficient management of large numbers of timers, -an important advantage in hard real-time systems like vehicle control. +High-resolution Timer (HRTimer) is a timer abstraction capable of achieving +nanosecond-level timing precision, primarily used in scenarios requiring +high-precision clock events. With the advancement of integrated circuit +technology, modern high-precision timer hardware, such as the typical x86 +HPET, can already meet sub-nanosecond timing requirements and offer +femtosecond-level jitter control. + +Although the current hardware timer abstraction (`up_alarm/up_timer`) +in the NuttX kernel already supports nanosecond-level timing, its software +timer abstraction, wdog, and the timer timeout interrupt handling process +remain at microsecond-level (tick) precision, which falls short of +high-precision timing demands. Therefore, it is necessary to implement a +new timer abstraction, HRTimer, to address the precision limitations of +wdog. HRTimer primarily provides the following functional interfaces: + +**Set a timer in nanoseconds**: Configure a software timer to trigger at + a specified nanosecond time. + +**Cancel a timer**: Cancel the software timer. + +**Handle timer timeout**: Execute timeout processing after the timer event + is triggered. + +The new NuttX HRTimer is designed to address the issues of insufficient +precision in the current NuttX wdog. It draws on the strengths of the Linux +HRTimer design while improving upon its weaknesses. +The HRTimer design is divided into two parts: the `HRTimer Queue` and the +`HRTimer`. The `HRTimer Queue` is a reusable component that allows users to +freely customize their own `HRTimer` interface by pairing it with a private +timer driver, without needing to modify the kernel code. + +The HRTimer Queue is a zero-performance-overhead, composable, and +customizable abstraction that provides only asynchronous-style interfaces: + +**hrtimer_queue_start(queue, timer)**: Asynchronously sends an HRTimer to + HRTimer queue. + +**hrtimer_queue_async_cancel(queue, timer)**: + Asynchronously cancels anHRTimer and returns the current reference count + of the timer. + +**hrtimer_queue_wait(queue, timer)**: + Waits for the release of all references to the HRTimer to obtain ownership + of the HRTimer data structure. + +All other user interfaces can be composed based on these three interfaces. + +On top of the `HRTimer Queue`, users only need to implement the following +interfaces to customize their own HRTimer implementation: + +**hrtimer_expiry(current)**: Handles timer expiration, typically called + within the execution path of the corresponding timer hardware + interrupt handler. + +**hrtimer_reprogram(queue, next_expired)**: Sets the next timer event. + +**hrtimer_current()**: Gets the current time to set relative timers. + +After implementing the above three interfaces, users can include one of the +`hrtimer_type_xxx.h` implementation to compose their own hrtimer +implementation, which mainly includes the following interfaces: + +**hrtimer_start(timer, func, arg, time, mode)**: Starts a timer. + The mode parameter indicates whether it is a relative or absolute timer. + +**hrtimer_restart(timer, func, arg, time, mode)**: Restarts a timer that has +been asynchronously canceled (its callback function might still be executing). +This interface is designed to explicitly remind users to be aware of +concurrency issues,as concurrency problems are prone to occur in actual +programming and are very difficult to locate. Providing such an interface +facilitates quick identification of concurrency issues. + +**hrtimer_async_cancel(timer)**: Asynchronously cancels a timer. Note that + the semantics of this interface are completely different from Linux's + `try_to_cancel`. It ensures that the timer can definitely be canceled + successfully, but may need to wait for its callback function to finish + execution. + +**hrtimer_cancel(timer)**: Synchronously cancels a timer. If the timer's + callback function is still executing, this function will spin-wait until + the callback completes. It ensures that the user can always obtain + ownership of the timer. -A user can register an hrtimer callback to execute after a specified delay. -The callback runs in the timer interrupt context, so only limited NuttX interfaces -are available, such as ``mq_send()``, ``sigqueue()``, ``nxevent_post()``, or ``kill()``, -to communicate with tasks. - -- :c:func:`hrtimer_init` -- :c:func:`hrtimer_cancel` -- :c:func:`hrtimer_cancel_sync` - :c:func:`hrtimer_start` -- High-resolution Timer Callback +- :c:func:`hrtimer_async_cancel` +- :c:func:`hrtimer_cancel` +- :c:func:`hrtimer_gettime` +- :c:type:`hrtimer_callback_t` + +.. c:function:: int hrtimer_restart(hrtimer_t *timer, hrtimer_callback_t func, FAR void *arg, uint64_t time, uint32_t mode) + + Restart a high-resolution timer with new parameters. + + For relative mode timers, converts relative time to absolute expiration time. + The expiration time is capped at HRTIMER_MAX_DELAY. + + **Note:** This function is static inline and intended for internal use. + + :param timer: Timer instance to restart + :param func: Expiration callback function + :param arg: Argument passed to callback function + :param time: Expiration time in nanoseconds (relative or absolute) + :param mode: Timer mode (HRTIMER_MODE_REL or HRTIMER_MODE_ABS) + + :return: Zero on success; error code on failure. + + **Assumptions:** + - The caller has ownership of the timer. + - Mode parameter is valid (0 or 1). + +.. c:function:: int hrtimer_start(FAR hrtimer_t *timer, hrtimer_callback_t func, FAR void *arg, uint64_t time, uint32_t mode) Review Comment: mode should be enum type, so compiler can do type checking for you. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
