Commit 4cdbfbf9 authored by Allan Stephens's avatar Allan Stephens Committed by Anas Nashif
Browse files

doc: Add descriptions for clock-related helper macros


Also fixes up Kernel Primer examples to use these macros.

Change-Id: Ib1bc9e3f85ab75f81986bc3930fb287266a886b5
Signed-off-by: default avatarAllan Stephens <allan.stephens@windriver.com>
parent c38888bc
Showing with 105 additions and 29 deletions
+105 -29
......@@ -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 */
......
......@@ -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");
......
......@@ -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 */
......
......@@ -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`
......@@ -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 */
...
......
......@@ -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
*/
#include <sys_clock.h>
/**
* kernel timing
* @addtogroup clock_apis
* @{
*/
#include <sys_clock.h>
/**
* @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
/* Convenience helpers to convert durations into milliseconds */
/**
* @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
*/
/**
......
......@@ -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;
/*
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment