It's mandatory function which should be present in every port. Even if
it's not, in the stdlib intro we waarn users that a particular port can
lack anything of described in the docs.
Now the function properly uses ring arithmetic to return signed value
in range (inclusive):
[-MICROPY_PY_UTIME_TICKS_PERIOD/2, MICROPY_PY_UTIME_TICKS_PERIOD/2-1].
That means that function can properly process 2 time values away from
each other within MICROPY_PY_UTIME_TICKS_PERIOD/2 ticks, but away in
both directions. For example, if tick value 'a' predates tick value 'b',
ticks_diff(a, b) will return negative value, and positive value otherwise.
But at positive value of MICROPY_PY_UTIME_TICKS_PERIOD/2-1, the result
of the function will wrap around to negative -MICROPY_PY_UTIME_TICKS_PERIOD/2,
in other words, if a follows b in more than MICROPY_PY_UTIME_TICKS_PERIOD/2 - 1
ticks, the function will "consider" a to actually predate b.
It's implemented in terms of usleep(), and POSIX doesn't guarantee that
usleep() can sleep for more than a second. This restriction unlikely
applies to any real-world system, but...
Based on the earlier discussed RFC. Practice showed that the most natural
order for arguments corresponds to mathematical subtraction:
ticks_diff(x, y) <=> x - y
Also, practice showed that in real life, it's hard to order events by time
of occurance a priori, events tend to miss deadlines, etc. and the expected
order breaks. And then there's a need to detect such cases. And ticks_diff
can be used exactly for this purpose, if it returns a signed, instead of
unsigned, value. E.g. if x is scheduled time for event, and y is the current
time, then if ticks_diff(x, y) < 0 then event has missed a deadline (and e.g.
needs to executed ASAP or skipped). Returning in this case a large unsigned
number (like ticks_diff behaved previously) doesn't make sense, and such
"large unsigned number" can't be reliably detected per our definition of
ticks_* function (we don't expose to user level maximum value, it can be
anything, relatively small or relatively large).
The integration with Zephyr is fairly clean but as MicroPython Hardware API
requires pin ID to be a single value, but Zephyr operates GPIO in terms of
ports and pins, not just pins, a "hierarchical" ID is required, using tuple
of (port, pin). Port is a string, effectively a device name of a GPIO port,
per Zephyr conventions these are "GPIO_0", "GPIO_1", etc.; pin is integer
number of pin with the port (supposed to be in range 0-31).
Example of pin initialization:
pin = Pin(("GPIO_1", 21), Pin.OUT)
(an LED on FRDM-K64F's Port B, Pin 21).
There is support for in/out pins and pull up/pull down but currently
there is no interrupt support.
Signed-off-by: Daniel Thompson <daniel.thompson@linaro.org>
Signed-off-by: Vincenzo Frascino <vincenzo.frascino@linaro.org>
Signed-off-by: Paul Sokolovsky <paul.sokolovsky@linaro.org>
This happens with some compilers on some architectures, which don't define
size_t as unsigned int. MicroPython's printf() dooesn't support obscure
format specifiers for size_t, so the obvious choice is to explicitly cast
to unsigned, to match %u used in printf().
