[riot-notifications] [RIOT-OS/RIOT] doc: XTIMER_BACKOFF inconsistency (#11522)

Francisco notifications at github.com
Mon May 13 19:19:20 CEST 2019


### Description

Looking into XTIMER_BACKOFF documentation I've run upon some inconsistency over the meaning of the value.

In multiple places XTIMER_BACKOFF is refered to as having usec units, eg:

https://github.com/RIOT-OS/RIOT/blob/568a3514557fe301aaf8b2413b76c701dac98492/sys/include/xtimer.h#L474-L484

https://github.com/RIOT-OS/RIOT/blob/568a3514557fe301aaf8b2413b76c701dac98492/sys/include/xtimer.h#L136-L145

But it is also referred  as ticks:

https://github.com/RIOT-OS/RIOT/blob/568a3514557fe301aaf8b2413b76c701dac98492/sys/include/xtimer.h#L160-L169

But when looking at where it is used, e.g tracing ` xtimer_usleep()`. We can actually see that the value is used a ticks since it is converted from usec to ticks inmediatly.

```
static inline void xtimer_usleep(uint32_t microseconds)
{
    _xtimer_tsleep32(_xtimer_ticks_from_usec(microseconds));
}
```

And when tracing the value from `_xtimer_tsleep32() `to  `_xtimer_tsleep()` to `_xtimer_set64() ` to `_xtimer_set()` we end up seeing that XTIMER_OFFSET is compared against ticks.

https://github.com/RIOT-OS/RIOT/blob/568a3514557fe301aaf8b2413b76c701dac98492/sys/xtimer/xtimer_core.c#L136-L155

This leads to unclear definition of XTIMER_BACKOFF since documentation makes you think of usec and not ticks. This has an impact on some tests, eg https://github.com/RIOT-OS/RIOT/blob/568a3514557fe301aaf8b2413b76c701dac98492/tests/ps_schedstatistics/main.c#L48

Where a variable representing ticks is passed to a function requesting usec. This had already been brought up in #8969.

### Proposed steps to solve the problem

- [ ] change documentation to make sure XTIMER_BACKOFF has a clear unit ( ticks or usec), or add XTIMER_BACKOFF_US
- [ ] fix tests that use XTIMER_BACKOFF as an unproper reference ([tests/ps_schechstatistics](https://github.com/RIOT-OS/RIOT/tree/master/tests/ps_schedstatistics), [tests/thread_float](https://github.com/RIOT-OS/RIOT/tree/master/tests/thread_float), etc.)
- [ ] fix XTIMER_BACKOFF definition for concerned boards [frdmk-kw41z](https://github.com/RIOT-OS/RIOT/blob/master/boards/frdm-kw41z/include/board.h)

#### Related Issues

#8969

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/issues/11522
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190513/b48add6b/attachment-0001.html>


More information about the notifications mailing list