Clearly document semantics of ltimer set_timeout functionality

[bennoleslie]

The parameters for the set_timeout function are documented in platsupport/ltimer.h however the semantics are not very clear.

Specifically, what is the correct behaviour if called with a time that is in the past (and/or called with a time that is in the past by the time the callee completes, consider the function could be interrupted by a higher priority thread at any point in time).

In addition, the semantics associated with IRQs may come in earlier than requested due to implementation details seems difficult for a caller to use correctly. It seems like the caller would then need to call get_time or something to check. In my experience most timeout APIs guarantee to wait for at least the specified time, but don't make guarantees about how soon after the requested expiry the actual callback is made. I suggest that this might be more useful set of semantics to consider specifying instead.