From 6a79436f05075a7d835ff208e523f44d798bc36b Mon Sep 17 00:00:00 2001 From: Peter Bigot Date: Fri, 22 May 2020 14:17:01 -0500 Subject: [PATCH] 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 --- include/kernel.h | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/include/kernel.h b/include/kernel.h index cc646216325..5dfbf0fc9db 100644 --- a/include/kernel.h +++ b/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);