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 <allan.stephens@windriver.com>

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 */

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");

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 */

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()`
-
+* :c:macro:`SYS_CLOCK_HW_CYCLES_TO_NS`
-The following kernel clock variables are provided by :file:`kernel.h`:
+* :c:macro:`K_NO_WAIT`
-
+* :c:macro:`K_MSEC`
-:c:data:`sys_clock_ticks_per_sec`
+* :c:macro:`K_SECONDS`
-    The number of system clock ticks in a single second.
+* :c:macro:`K_MINUTES`
-
+* :c:macro:`K_HOURS`
-:c:data:`sys_clock_hw_cycles_per_sec`
+* :c:macro:`K_FOREVER`
-    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.

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 */
     ...

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 <sys_clock.h>
 
-/* 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
+ * @addtogroup clock_apis
- * @ingroup kernel_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
  */
 
 /**

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;
 
 /*