wangchdo commented on code in PR #17675: URL: https://github.com/apache/nuttx/pull/17675#discussion_r2647702282
########## 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 Review Comment: We don’t need a separate `hrtimer_restart`, which would require users to input `arg, time, and mode `again. **Restarting** essentially starts the hrtimer with a new expiry. If users want to **refresh** the hrtimer, they can simply call `hrtimer_init()` first. So, in practice, the following functions are sufficient for users to manage hrtimers: `hrtimer_init(), hrtimer_start(), hrtimer_cancel(), and hrtimer_cancel_sync().` -- 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]
