From e39bf293214f13825e677257a7d0da609c8f449d Mon Sep 17 00:00:00 2001 From: Andy Ross Date: Thu, 19 Mar 2020 10:30:33 -0700 Subject: [PATCH] kernel/timeout: Doc cleanup Add a doc string for k_timeout_t. Rephrase a few other items for clarity. Fix some syntax goofs. Signed-off-by: Andy Ross --- include/kernel.h | 33 +++++++++++++++++---------------- include/sys_clock.h | 12 ++++++++++++ 2 files changed, 29 insertions(+), 16 deletions(-) diff --git a/include/kernel.h b/include/kernel.h index e7be91cc23e..1af6f089b18 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -1060,7 +1060,7 @@ extern k_ticks_t z_timeout_remaining(struct _timeout *timeout); #ifdef CONFIG_SYS_CLOCK_EXISTS /** - * @brief Get time when a thread wakes up, in ticks + * @brief Get time when a thread wakes up, in system ticks * * This routine computes the system uptime when a waiting thread next * executes, in units of system ticks. If the thread is not waiting, @@ -1075,7 +1075,7 @@ static inline k_ticks_t z_impl_k_thread_timeout_expires_ticks( } /** - * @brief Get time remaining before a thread wakes up, in ticks + * @brief Get time remaining before a thread wakes up, in system ticks * * This routine computes the time remaining before a waiting thread * next executes, in units of system ticks. If the thread is not @@ -1593,7 +1593,7 @@ const char *k_thread_state_str(k_tid_t thread_id); * Note that timer precision is limited to the tick rate, not the * requested value. * - * @paramt Duration in nanoseconds. + * @param t Duration in nanoseconds. * * @return Timeout delay value. */ @@ -1607,7 +1607,7 @@ const char *k_thread_state_str(k_tid_t thread_id); * Note that timer precision is limited to the tick rate, not the * requested value. * - * @paramt Duration in microseconds. + * @param t Duration in microseconds. * * @return Timeout delay value. */ @@ -1619,7 +1619,7 @@ const char *k_thread_state_str(k_tid_t thread_id); * This macro generates a timeout delay that instructs a kernel API * to wait up to @a t cycles to perform the requested operation. * - * @paramt Duration in cycles. + * @param t Duration in cycles. * * @return Timeout delay value. */ @@ -1631,7 +1631,7 @@ const char *k_thread_state_str(k_tid_t thread_id); * This macro generates a timeout delay that instructs a kernel API * to wait up to @a t ticks to perform the requested operation. * - * @paramt Duration in system ticks. + * @param t Duration in system ticks. * * @return Timeout delay value. */ @@ -1698,10 +1698,10 @@ const char *k_thread_state_str(k_tid_t thread_id); #ifdef CONFIG_TIMEOUT_64BIT /** - * @brief Generates an absolute/uptime timeout value in ticks + * @brief Generates an absolute/uptime timeout value from system ticks * * This macro generates a timeout delay that represents an expiration - * at the absolute uptime value specified, in ticks. That is, the + * at the absolute uptime value specified, in system ticks. That is, the * timeout will expire immediately after the system uptime reaches the * specified tick count. * @@ -1711,7 +1711,7 @@ const char *k_thread_state_str(k_tid_t thread_id); #define K_TIMEOUT_ABS_TICKS(t) Z_TIMEOUT_TICKS(Z_TICK_ABS(MAX(t, 0))) /** - * @brief Generates an absolute/uptime timeout value in ms + * @brief Generates an absolute/uptime timeout value from milliseconds * * This macro generates a timeout delay that represents an expiration * at the absolute uptime value specified, in milliseconds. That is, @@ -1724,7 +1724,7 @@ const char *k_thread_state_str(k_tid_t thread_id); #define K_TIMEOUT_ABS_MS(t) K_TIMEOUT_ABS_TICKS(k_ms_to_ticks_ceil64(t)) /** - * @brief Generates an absolute/uptime timeout value in us + * @brief Generates an absolute/uptime timeout value from microseconds * * This macro generates a timeout delay that represents an expiration * at the absolute uptime value specified, in microseconds. That is, @@ -1738,7 +1738,7 @@ const char *k_thread_state_str(k_tid_t thread_id); #define K_TIMEOUT_ABS_US(t) K_TIMEOUT_ABS_TICKS(k_us_to_ticks_ceil64(t)) /** - * @brief Generates an absolute/uptime timeout value in ns + * @brief Generates an absolute/uptime timeout value from nanoseconds * * This macro generates a timeout delay that represents an expiration * at the absolute uptime value specified, in nanoseconds. That is, @@ -1752,7 +1752,7 @@ const char *k_thread_state_str(k_tid_t thread_id); #define K_TIMEOUT_ABS_NS(t) K_TIMEOUT_ABS_TICKS(k_ns_to_ticks_ceil64(t)) /** - * @brief Generates an absolute/uptime timeout value in cycles + * @brief Generates an absolute/uptime timeout value from system cycles * * This macro generates a timeout delay that represents an expiration * at the absolute uptime value specified, in cycles. That is, the @@ -1964,7 +1964,7 @@ __syscall u32_t k_timer_status_sync(struct k_timer *timer); #ifdef CONFIG_SYS_CLOCK_EXISTS /** - * @brief Get next expiration time of a timer, in ticks + * @brief Get next expiration time of a timer, in system ticks * * This routine returns the future system uptime reached at the next * time of expiration of the timer, in units of system ticks. If the @@ -1981,7 +1981,7 @@ static inline k_ticks_t z_impl_k_timer_expires_ticks(struct k_timer *timer) } /** - * @brief Get time remaining before a timer next expires, in ticks + * @brief Get time remaining before a timer next expires, in system ticks * * This routine computes the time remaining before a running timer * next expires, in units of system ticks. If the timer is not @@ -2058,7 +2058,7 @@ static inline void *z_impl_k_timer_user_data_get(struct k_timer *timer) */ /** - * @brief Get system uptime, in ticks. + * @brief Get system uptime, in system ticks. * * This routine returns the elapsed time since the system booted, in * ticks (c.f. :option:`CONFIG_SYS_CLOCK_TICKS_PER_SEC`), which is the @@ -3479,7 +3479,8 @@ static inline k_ticks_t k_delayed_work_expires_ticks( } /** - * @brief Get time remaining before a delayed work gets scheduled, in ticks + * @brief Get time remaining before a delayed work gets scheduled, in + * system ticks * * This routine computes the time remaining before a delayed work gets * executed. If the delayed work is not waiting to be scheduled, it diff --git a/include/sys_clock.h b/include/sys_clock.h index 43d5277b98b..2d6a3903eca 100644 --- a/include/sys_clock.h +++ b/include/sys_clock.h @@ -52,6 +52,18 @@ typedef u32_t k_ticks_t; #ifndef CONFIG_LEGACY_TIMEOUT_API +/** + * @brief Kernel timeout type + * + * Timeout arguments presented to kernel APIs are stored in this + * opaque type, which is capable of representing times in various + * formats and units. It should be constructed from application data + * using one of the macros defined for this purpose (e.g. `K_MSEC()`, + * `K_TIMEOUT_ABS_TICKS()`, etc...), or be one of the two constants + * K_NO_WAIT or K_FOREVER. Applications should not inspect the + * internal data once constructed. Timeout values may be compared for + * equality with the `K_TIMEOUT_EQ()` macro. + */ typedef struct { k_ticks_t ticks; } k_timeout_t;