From c2f15a4525a28117176de003c02b9b9e86119928 Mon Sep 17 00:00:00 2001 From: Allan Stephens Date: Thu, 17 Nov 2016 12:24:22 -0500 Subject: [PATCH] doc: Add descriptions for clock-related helper macros Also fixes up Kernel Primer examples to use these macros. Change-Id: Ib1bc9e3f85ab75f81986bc3930fb287266a886b5 Signed-off-by: Allan Stephens --- doc/kernel_v2/data_passing/pipes.rst | 2 +- doc/kernel_v2/synchronization/mutexes.rst | 2 +- doc/kernel_v2/synchronization/semaphores.rst | 2 +- doc/kernel_v2/timing/clocks.rst | 21 ++--- doc/kernel_v2/timing/timers.rst | 6 +- include/kernel.h | 85 +++++++++++++++++--- include/sys_clock.h | 20 +++++ 7 files changed, 107 insertions(+), 31 deletions(-) diff --git a/doc/kernel_v2/data_passing/pipes.rst b/doc/kernel_v2/data_passing/pipes.rst index c870d61c08b..499571657ec 100644 --- a/doc/kernel_v2/data_passing/pipes.rst +++ b/doc/kernel_v2/data_passing/pipes.rst @@ -141,7 +141,7 @@ process data items generated by one or more producing threads. while (1) { rc = k_pipe_get(&my_pipe, buffer, sizeof(buffer), &bytes_read, - sizeof(header), 100); + sizeof(header), K_MSEC(100)); if ((rc < 0) || (bytes_read < sizeof (header))) { /* Incomplete message header received */ diff --git a/doc/kernel_v2/synchronization/mutexes.rst b/doc/kernel_v2/synchronization/mutexes.rst index ec7f9bb0524..c01f221bc9d 100644 --- a/doc/kernel_v2/synchronization/mutexes.rst +++ b/doc/kernel_v2/synchronization/mutexes.rst @@ -130,7 +130,7 @@ available, and gives a warning if the mutex does not become availablee. .. code-block:: c - if (k_mutex_lock(&my_mutex, 100) == 0) { + if (k_mutex_lock(&my_mutex, K_MSEC(100)) == 0) { /* mutex successfully locked */ } else { printf("Cannot lock XYZ display\n"); diff --git a/doc/kernel_v2/synchronization/semaphores.rst b/doc/kernel_v2/synchronization/semaphores.rst index ed90026c940..ee1c3a6e462 100644 --- a/doc/kernel_v2/synchronization/semaphores.rst +++ b/doc/kernel_v2/synchronization/semaphores.rst @@ -101,7 +101,7 @@ A warning is issued if the semaphore is not obtained in time. { ... - if (k_sem_take(&my_sem, 50) != 0) { + if (k_sem_take(&my_sem, K_MSEC(50)) != 0) { printk("Input data not available!"); } else { /* fetch available data */ diff --git a/doc/kernel_v2/timing/clocks.rst b/doc/kernel_v2/timing/clocks.rst index 4ddf5e10c6e..fb2017d24f8 100644 --- a/doc/kernel_v2/timing/clocks.rst +++ b/doc/kernel_v2/timing/clocks.rst @@ -164,17 +164,10 @@ The following kernel clock APIs are provided by :file:`kernel.h`: * :cpp:func:`k_uptime_delta()` * :cpp:func:`k_uptime_delta_32()` * :cpp:func:`k_cycle_get_32()` - -The following kernel clock variables are provided by :file:`kernel.h`: - -:c:data:`sys_clock_ticks_per_sec` - The number of system clock ticks in a single second. - -:c:data:`sys_clock_hw_cycles_per_sec` - The number of hardware clock cycles in a single second. - -:c:data:`sys_clock_us_per_tick` - The number of microseconds in a single system clock tick. - -:c:data:`sys_clock_hw_cycles_per_tick` - The number of hardware clock cycles in a single system clock tick. +* :c:macro:`SYS_CLOCK_HW_CYCLES_TO_NS` +* :c:macro:`K_NO_WAIT` +* :c:macro:`K_MSEC` +* :c:macro:`K_SECONDS` +* :c:macro:`K_MINUTES` +* :c:macro:`K_HOURS` +* :c:macro:`K_FOREVER` diff --git a/doc/kernel_v2/timing/timers.rst b/doc/kernel_v2/timing/timers.rst index 5f227998858..87c65b1ec9a 100644 --- a/doc/kernel_v2/timing/timers.rst +++ b/doc/kernel_v2/timing/timers.rst @@ -148,7 +148,7 @@ the timer's expiry function submits a work item to the ... /* start periodic timer that expires once every second */ - k_timer_start(&my_timer, 1000, 1000); + k_timer_start(&my_timer, K_SECONDS(1), K_SECONDS(1)); Reading Timer Status ==================== @@ -163,7 +163,7 @@ if the timer has expired on not. ... /* start one shot timer that expires after 200 ms */ - k_timer_start(&my_status_timer, 200, 0); + k_timer_start(&my_status_timer, K_MSEC(200), 0); /* do work */ ... @@ -194,7 +194,7 @@ are separated by the specified time interval. ... /* start one shot timer that expires after 500 ms */ - k_timer_start(&my_sync_timer, 500, 0); + k_timer_start(&my_sync_timer, K_MSEC(500), 0); /* do other work */ ... diff --git a/include/kernel.h b/include/kernel.h index 7dab3bddc72..5a652b2e08e 100644 --- a/include/kernel.h +++ b/include/kernel.h @@ -46,9 +46,6 @@ extern "C" { #define K_PRIO_COOP(x) (-(CONFIG_NUM_COOP_PRIORITIES - (x))) #define K_PRIO_PREEMPT(x) (x) -#define K_FOREVER (-1) -#define K_NO_WAIT 0 - #define K_ANY NULL #define K_END NULL @@ -547,18 +544,85 @@ extern void *k_thread_custom_data_get(void); * @} end addtogroup thread_apis */ -/** - * kernel timing - */ - #include -/* Convenience helpers to convert durations into milliseconds */ +/** + * @addtogroup clock_apis + * @{ + */ + +/** + * @brief Generate null timeout delay. + * + * This macro generates a timeout delay that that instructs a kernel API + * not to wait if the requested operation cannot be performed immediately. + * + * @return Timeout delay value. + */ +#define K_NO_WAIT 0 + +/** + * @brief Generate timeout delay from milliseconds. + * + * This macro generates a timeout delay that that instructs a kernel API + * to wait up to @a ms milliseconds to perform the requested operation. + * + * @param ms Duration in milliseconds. + * + * @return Timeout delay value. + */ #define K_MSEC(ms) (ms) + +/** + * @brief Generate timeout delay from seconds. + * + * This macro generates a timeout delay that that instructs a kernel API + * to wait up to @a s seconds to perform the requested operation. + * + * @param s Duration in seconds. + * + * @return Timeout delay value. + */ #define K_SECONDS(s) K_MSEC((s) * MSEC_PER_SEC) + +/** + * @brief Generate timeout delay from minutes. + * + * This macro generates a timeout delay that that instructs a kernel API + * to wait up to @a m minutes to perform the requested operation. + * + * @param m Duration in minutes. + * + * @return Timeout delay value. + */ #define K_MINUTES(m) K_SECONDS((m) * 60) + +/** + * @brief Generate timeout delay from hours. + * + * This macro generates a timeout delay that that instructs a kernel API + * to wait up to @a h hours to perform the requested operation. + * + * @param h Duration in hours. + * + * @return Timeout delay value. + */ #define K_HOURS(h) K_MINUTES((h) * 60) +/** + * @brief Generate infinite timeout delay. + * + * This macro generates a timeout delay that that instructs a kernel API + * to wait as long as necessary to perform the requested operation. + * + * @return Timeout delay value. + */ +#define K_FOREVER (-1) + +/** + * @} end addtogroup clock_apis + */ + /** * @cond INTERNAL_HIDDEN */ @@ -794,8 +858,7 @@ extern int32_t k_timer_remaining_get(struct k_timer *timer); */ /** - * @defgroup clock_apis Kernel Clock APIs - * @ingroup kernel_apis + * @addtogroup clock_apis * @{ */ @@ -866,7 +929,7 @@ extern uint32_t k_uptime_delta_32(int64_t *reftime); extern uint32_t k_cycle_get_32(void); /** - * @} end defgroup clock_apis + * @} end addtogroup clock_apis */ /** diff --git a/include/sys_clock.h b/include/sys_clock.h index 3e463be1a2f..b3605234264 100644 --- a/include/sys_clock.h +++ b/include/sys_clock.h @@ -88,8 +88,28 @@ extern int sys_clock_hw_cycles_per_tick; #define SYS_CLOCK_HW_CYCLES_TO_NS_AVG(X, NCYCLES) \ (uint32_t)(SYS_CLOCK_HW_CYCLES_TO_NS64(X) / NCYCLES) +/** + * @defgroup clock_apis Kernel Clock APIs + * @ingroup kernel_apis + * @{ + */ + +/** + * @brief Compute nanoseconds from hardware clock cycles. + * + * This macro converts a time duration expressed in hardware clock cycles + * to the equivalent duration expressed in nanoseconds. + * + * @param X Duration in hardware clock cycles. + * + * @return Duration in nanoseconds. + */ #define SYS_CLOCK_HW_CYCLES_TO_NS(X) (uint32_t)(SYS_CLOCK_HW_CYCLES_TO_NS64(X)) +/** + * @} end defgroup clock_apis + */ + extern int64_t _sys_clock_tick_count; /*