sched/sched: Part 2: Add high-resolution timer (hrtimer) and os tick support with hrtimer to NuttX

[wangchdo]

Summary

This PR is a continuation and optimized implementation, replacing the draft PR #17065 proposed two months ago.

Summary of this PR

• Introduce a high-resolution timer (hrtimer) module to NuttX, providing timers with nanosecond-level resolution.
• Enable coexistence with the existing NuttX timer facility (wdog):
  1. wdog timers will be driven by an hrtimer instance (g_nxsched_hrtimer) when hrtimer is enabled.
  2. both nontickless and tickless scheduler are supported
• Provide three new hrtimer APIs:

1. hrtimer_init() – Initialize a high-resolution timer instance.
2. hrtimer_start() – Start a high-resolution timer in absolute or relative mode.
3. hrtimer_cancel() – Cancel a pending high-resolution timer.

Motivation

In hard real-time applications, nanosecond-level control of task activation is essential for certain scenarios—such as motor control—where tick-level precision is simply inadequate.

For these use cases, the main limitation of wdog is its tick-based resolution, which is typically in milliseconds. Although the tick duration can be reduced, configuring it to microsecond or nanosecond granularity is impractical, as this would lead to an interrupt storm in which the CPU becomes saturated by handling an excessive number of tick interrupts.

Therefore, an independent high-resolution timer (hrtimer) is required to support use cases—such as motor control—that demand true high-precision timing.

Additionally, hrtimer uses an RB-tree (red-black tree) for timer management, which is more efficient than the list-based structure used by wdog when dealing with a large number of timer events. This advantage becomes increasingly important in hard real-time systems, such as vehicle control systems.

Why not use wdog for high-resolution timing

wdog is highly coupled with the scheduler and has inherent limitations:

1. It cannot achieve nanosecond-level resolution due to its tick-based design.
2. While wdog is lightweight, efficient, and stable for all current NuttX functionality, replacing its list-based data structure with a tree would complicate the implementation and potentially reduce scheduler performance or introduce bugs to nuttx components that are designed to rely on the tick-based design of wdog.

Impact

Add a new high-resolution timer (hrtimer) module to NuttX.

• When disabled, it has no impact on any existing NuttX functionality.
• When enabled:
  1. it coexists with wdog , driving wdog by an hrtimer instance (g_nxsched_hrtimer).
  2. It provides three new APIs as described above to support nanosecond-level timers

Testing

ostest passed on board a2g-tc397-5v-tft when hrtimer is enabled

NuttShell (NSH)
nsh>
nsh> uname -a
NuttX 0.0.0 c893c87550 Dec 15 2025 09:27:00 tricore a2g-tc397-5v-tft
nsh>
nsh> ostest

(...)

End of test memory usage:
VARIABLE  BEFORE   AFTER
======== ======== ========
arena       28dfc    28dfc
ordblks         7        6
mxordblk    1f8a8    1f8a8
uordblks     555c     555c
fordblks    238a0    238a0

user_main: nxevent test

End of test memory usage:
VARIABLE  BEFORE   AFTER
======== ======== ========
arena       28dfc    28dfc
ordblks         6        6
mxordblk    1f8a8    1f8a8
uordblks     555c     555c
fordblks    238a0    238a0

Final memory usage:
VARIABLE  BEFORE   AFTER
======== ======== ========
arena       28dfc    28dfc
ordblks         1        6
mxordblk    24220    1f8a8
uordblks     4bdc     555c
fordblks    24220    238a0
user_main: Exiting
ostest_main: Exiting with status 0
nsh>

API test coe is as below

hrtimer_t test_hrtimer_500ms;
uint32_t test_count = 15;

static void test_hrtimer_callback(FAR hrtimer_t *hrtimer)
{
  struct timespec ts;

  clock_systime_timespec(&ts);

  printf("Hrtimer expired! time now in necs is: %lld\n", clock_time2nsec(&ts));

  if (test_count !=0)
  {
    test_count--;
    hrtimer_start(hrtimer, hrtimer->expired + 500 * USEC_PER_MSEC * NSEC_PER_USEC, HRTIMER_MODE_ABS);
  }
  else
  {
    hrtimer_cancel(&test_hrtimer_500ms);
    printf("Hrtimer cancelled after expiration for 15 times !! \n");
  }
}

int main(int argc, FAR char *argv[])
{

  hrtimer_init(&test_hrtimer_500ms, test_hrtimer_callback, NULL);

  printf("Start hrtimer to make it expire every 500ms !! \n");
  hrtimer_start(&test_hrtimer_500ms, 500 * USEC_PER_MSEC * NSEC_PER_USEC, HRTIMER_MODE_REL);

  return 0;
}

API test log for board a2g-tc397-5v-tft is as below

nsh> hello
Start hrtimer to make it expire every 500ms !!
nsh> Hrtimer expired! time now in necs is: 15466744230
Hrtimer expired! time now in necs is: 15966744310
Hrtimer expired! time now in necs is: 16466744300
Hrtimer expired! time now in necs is: 16966744300
Hrtimer expired! time now in necs is: 17466744300
Hrtimer expired! time now in necs is: 17966744300
Hrtimer expired! time now in necs is: 18466744300
Hrtimer expired! time now in necs is: 18966744300
Hrtimer expired! time now in necs is: 19466744300
Hrtimer expired! time now in necs is: 19966744300
Hrtimer expired! time now in necs is: 20466744300
Hrtimer expired! time now in necs is: 20966744300
Hrtimer expired! time now in necs is: 21466744300
Hrtimer expired! time now in necs is: 21966744300
Hrtimer expired! time now in necs is: 22466744300
Hrtimer expired! time now in necs is: 22966744300
Hrtimer cancelled after expiration for 15 times !!

[acassis]

@wangchdo please add Documentation about this new feature

[wangchdo]

@wangchdo please add Documentation about this new feature
@acassis Documentation added, please check

[wangchdo]

This is a great initiative!

Only thing what I don't quite understand is, why is tick handling mixed with the hr timer?

While the hr timer already manages a tree of timer expirations, why can't os tick just be one subscription to the hrtimer, on "ticked" systems?

That is, on ticked systems, the OS tick could be just another registration to the hr timer, and hrtimer itself could just unconditionally manage interrupts and call the registered callbacks..

Yes, the os tick is a hr timer now, you can see from the implementation: when hrtimer is enabled an hrtimer instance(g_nxsched_hrtimer) will be used to provide OS tick

[acassis]

@wangchdo I suggest to include the Motivation from this Summary to the Documentation, it makes our documentation more "human-like" and people reading it will understand where and why to use hrtimer.

[wangchdo]

In hard real-time applications, nanosecond-level control of task activation is essential for certain scenarios—such as motor control—where tick-level precision is simply inadequate.

For these use cases, the main limitation of wdog is its tick-based resolution, which is typically in milliseconds. Although the tick duration can be reduced, configuring it to microsecond or nanosecond granularity is impractical, as this would lead to an interrupt storm in which the CPU becomes saturated by handling an excessive number of tick interrupts.

Therefore, an independent high-resolution timer (hrtimer) is required to support use cases—such as motor control—that demand true high-precision timing.

Additionally, hrtimer uses an RB-tree (red-black tree) for timer management, which is more efficient than the list-based structure used by wdog when dealing with a large number of timer events. This advantage becomes increasingly important in hard real-time systems, such as vehicle control systems.

Done, please take a look at the latest upload or this PR.

[cederom]

Thank you @wangchdo :-)

[anchao]

LGTM

[wangchdo]

@xiaoxiang781216 @acassis @anchao @jerpelea @cederom @simbit18

Shall we first review and merge #17517 , and then proceed with this PR?

[acassis]

@wangchdo #17517 was merged already

[cederom]

I have restarted CI to check current status :-)

[wangchdo]

@cederom @acassis @xiaoxiang781216 @anchao

This PR has been split into two parts. Part 1 #17517 has already been merged after SMP-specific optimizations. The remaining changes are now submitted as Part 2 in a separate PR:
#17573

To avoid duplicate review effort, this PR is marked as draft. Please continue to review Part 2 #17573 instead.

Once Part 2 #17573 is merged, all functionality originally planned for this PR will be completed, and this PR will be closed.

[xiaoxiang781216]

@cederom @acassis @xiaoxiang781216 @anchao

This PR has been split into two parts. Part 1 #17517 has already been merged after SMP-specific optimizations. The remaining changes are now submitted as Part 2 in a separate PR: #17573

To avoid duplicate review effort, this PR is marked as draft. Please continue to review Part 2 #17573 instead.

Once Part 2 #17573 is merged, all functionality originally planned for this PR will be completed, and this PR will be closed.

so, let's close this pr directly and continue on #17573. If you want, we can reopen it at anytime.