supervisor: Add a function to get "wrapping" milliseconds

[jepler]

As discussed in #3410, this is a micropython-compatible (though differently named) function that allows creation of useful time and deadline functions in pure python.

Closes: #3410

An alternative to #4935 which only adds the wrapped ticks and doesn't change the monotonic reference time.

supervisor.ticks_ms() → int

Return the time in milliseconds since an unspecified reference point, wrapping after 2**29ms.

The value is initialized so that the first overflow occurs about 65 seconds after power-on, making it feasible to check that your program works properly around an overflow.

The wrap value was chosen so that it is always possible to add or subtract two ticks_ms values without overflow on a board without long ints (or without allocating any long integer objects, on boards with long ints).

This ticks value comes from a low-accuracy clock internal to the microcontroller, just like time.monotonic. Due to its low accuracy and the fact that it “wraps around” every few days, it is intended for working with short term events like advancing an LED animation, not for long term events like counting down the time until a holiday.

Addition, subtraction, and comparison of ticks values can be done with routines like the following:

_TICKS_PERIOD = const(1<<29)
_TICKS_MAX = const(_TICKS_PERIOD-1)
_TICKS_HALFPERIOD = const(_TICKS_PERIOD//2)

def ticks_add(ticks, delta):
    "Add a delta to a base number of ticks, performing wraparound at 2**29ms."
    return (a + b) % _TICKS_PERIOD

def ticks_diff(ticks1, ticks2):
    "Compute the signed difference between two ticks values, assuming that they are within 2**28 ticks"
    diff = (ticks1 - ticks2) & _TICKS_MAX
    diff = ((diff + _TICKS_HALFPERIOD) & _TICKS_MAX) - _TICKS_HALFPERIOD
    return diff

def ticks_less(ticks1, ticks2):
    "Return true iff ticks1 is less than ticks2, assuming that they are within 2**28 ticks"
    return ticks_diff(ticks1, ticks2) < 0

[dhalbert]

Looks good! But given the simplicity of the Python code you suggest in the documentation, should we:

1. Make a simple library?
2. Implement those routines in a native module? Perhaps a new ticks module, or added to supervisor?

Once #4903 is merged, we will have the room.

[dhalbert]

Either #4935 or #4936 is OK with me. @jepler do you have a preference after thinking about it?

[jepler]

I think that I'd rather leave monotonic as is, and add this new functionality only. I studied the LED animation library and I think it's pretty easy to adapt it to wrapping ticks (made harder by the need for compatibility with 6.x). If that's typical of libraries that like to count intervals, then this is the way to go and the other complication is not needed.

We still need to address the problem with this not fitting on a couple of boards, though, and decide whether to offer this as 1 function in supervisor or 3 or 4 functions in a new module.

[dhalbert]

I am OK with adding this to supervisor per the PR, and then writing a small Python library. It's most important on small boards that are tight on space already. @tannewt, what do you think?

[tannewt]

I am OK with adding this to supervisor per the PR, and then writing a small Python library. It's most important on small boards that are tight on space already. @tannewt, what do you think?

Single function here + small python library sounds good. The reason to make a new module would be that we could make it available on some boards but not others then. That's also ok with me.

[Neradoc]

How will it work with Blinka if libraries are updated with it ?
Does Blinka have supervisor or will it require some conditional coding, like 6.x compatibility ?

[jepler]

Blinka has microcontroller but not supervisor. So we could either add supervisor to blinka, or move this to a location where blinka already provides a module, such as microcontroller.

Yes, we'll want to add this to blinka at https://github.com/adafruit/Adafruit_Blinka/blob/main/src/microcontroller/__init__.py

[jepler]

@makermelissa do you have an opinion about the placement of this proposed ticks_us function in circuitpython, for best results in blinka?