We should firm up the semantics of `userlib::sleep*`

[cbiffle]

So, we've kind of avoided dealing with the timebase problem. (Well, okay, mostly me.)

Currently we express time in all APIs as "system ticks," where the system tick is set for the application (board+image) to whatever you want .... but in practice is milliseconds. And basically all code assumes it's milliseconds.

There are two problems with this.

1. We often need timing more precise than milliseconds, but changing the tick frequency, while easy, would break basically all drivers.
2. The userlib time-related APIs don't actually do what you'd expect.

On that second point -- if you call sleep_for(1), you will (in the absence of higher priority tasks keeping you from being scheduled at all) sleep for somewhere between 0ms and 1ms. In other words, it's really sleep_for_at_most_ms. Often, we actually want at least.

The actual kernel time API is based on absolute deadlines rather than intervals (basically to keep the kernel out of this argument) so I think we could fix this part in userlib.

[jamesmunns]

Marking this as still relevant, as I believe it is still developing (or has started developing again).

• Docs: Update timer syscalls with correct units #2465 codified that system ticks are indeed milliseconds
• Consider requiring a higher resolution platform-specific timer #2506 discusses adding a higher resolution system timer
  • Conscript TIM5 for early boot #2571 added a higher resolution system for STM32H7 systems
  • Kernel accounting of task CPU usage #2592 begins using this higher resolution timer for CPU usage accounting

AFAIK we haven't attempted to address "sleep is actually At Most not At Least".

[jamesmunns]

It is not clear currently whether the high resolution timer would actually help for "sleep at least", as that would likely just want to sleep for N+1 milliseconds. It also may not help with "sleep exactly", as currently the high resolution timer has no "set alarm" functionality, as you would expect from a Timer Queue or Timer Wheel, allowing for timekeeping/scheduling outside of a millisecond SysTick event. That could be possible, if we were to take the high resolution platform concept further, much closer to how embassy-time(-driver) operates. But that is a larger conversation to have.

It is possible we could expose "get high resolution time" as a syscall, but without kernel cooperation, that would mean a LOT of system calls to obtain it, and busylooping in a task for at least the last millisecond of a delay. This is likely not ideal in the general case at least.