kernel: document that busy-wait clock may differ from timeout clock

Some tests assumed that a delay with k_busy_wait() could be precisely
timed by a tick or cycle count, and vice versa.  This is not true for
all clock configurations on all Zephyr targets, so highlight the
potential variation.

As an example: on some platforms busy-wait is performed by a loop with
known duration in cycles of a known CPU frequency.  The CPU clock may
be unrelated to the clock that drives the system timer.

Signed-off-by: Peter Bigot <peter.bigot@nordicsemi.no>

include/kernel.h

@@ -933,6 +933,12 @@ __syscall s32_t k_usleep(s32_t us);
  * This routine causes the current thread to execute a "do nothing" loop for
  * @a usec_to_wait microseconds.
  *
+ * @note The clock used for the microsecond-resolution delay here may
+ * be skewed relative to the clock used for system timeouts like
+ * k_sleep().  For example k_busy_wait(1000) may take slightly more or
+ * less time than k_sleep(K_MSEC(1)), with the offset dependent on
+ * clock tolerances.
+ *
  * @return N/A
  */
 __syscall void k_busy_wait(u32_t usec_to_wait);