Ambiguous use of TICKS_MAX in time.ticks_diff and time.ticks_add given the time.ticks_ms has different resolution from _us and _cpu and it could cover different ranges in time and values
https://docs.micropython.org/en/v1.20.0/library/time.html
Scenario:
user uses ticks_ms() reads the docs about TICKS_MAX and the rolling over part... learns that he has to use ticks_diff() and ticks_add() to work with the values properly.
BUT
ticks_us() is described as: "Just like ticks_ms() above, but in microseconds."
The issue is, that it is not clarified if TICKS_MAX is the same (or not) for ticks_ms than ticks_us (maybe it should be TICKS_MAX_MS and TICKS_MAX_US and TICKS_MAX_CPU).
If the TICKS_MAX is the same for us, ms and cpu variants that means the maximum time interval these functions handle are wildly different, and this needs to be clarified. (Also there should be a lower bound to this say it won't roll over for "at least a second" to design the application for)
If the TICKS_MAX is different for ticks_ms() and ticks_us() (and ticks_cpu()) then there should be a different ticks_diff_ms() and ticks_add_ms() and ticks_diff_us() to properly handle the difference.
Based on the current text in the docs one could ASSUME that TICKS_MAX is the same for all three resolutions available, but it is not explicitly declared. Also this might not be true in the future. So maybe adding ticks_add_us() and ticks_diff_us() would be beneficial even if they are the same in all current implementations.
Changing semantics of utime.ticks_diff()
Point 1: usabality/cosmetics
Initially, it seemed pretty natural for that func to have signature utime.ticks_diff(time_before, time_after). However, that function is intended to replace expression time_after - time_before, so it's kinda actually more natural to have it utime.ticks_diff(time_after, time_before).
Point 2: functionality
ticks_diff() is defined to return unsigned number. This allows to use full range of ticks_ms/us values, but misses ability to detect real-world useful condition of "deadline missed". This issue is being raised as a result of trying to convert uasyncio to use ticks_ms(). Lack of ability to properly detect missed deadline is a blocker for such conversion (currently, missed deadline results in a very large time difference, such difference used as a wait delay).
Note re: Point 1: It is NOT too late to fix that issue. But it may become too late at some time, and then may become a regular source of confusion (I judge by myself, again, initially it seemed quite natural to use (time_after, time_before), the problem is that it's not always immediately clear which time is "before", and in real-world cases time_after may be before "time_before" (missed deadline); so, relying on pure mathematical order of subtraction arguments turns out to be a better idea).