sys_clock: Make clock_always_on true by default

This flag is an indication to the timer driver that the OS doesn't
care about rollover conditions of the tick count while idling, so the
system doesn't need to wake up once per counter flip[1].  Obviously in
that circumstance values returned from k_uptime_get_32() are going to
be wrong, so the implementation had an assert to check for misuse.

But no one understood that from the docs, so the only place these APIs
were used in practice were as "guards" around code that needed to call
k_uptime_get_32(), even though that's 100% wrong per docs!

Clarify the docs.  Remove the incorrect guards.  Change the flag to
initialize to true so that uptime isn't broken-by-default in tickless
mode.  Also move the implemenations of the functions out of the
header, as there's no good reason for these to need to be inlined.

[1] Which can be significant.  A 100MHz ARM using the 24 bit SysTick
    counter rolls over at about 6 Hz, and if it had to come out of
    idle at that rate it would be a significant power issue that would
    swamp the gains from tickless.  Obviously systems with slow
    counters like nRF or 64 bit ones like RISC-V or x86's TSC aren't
    as affected.

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>

include/kernel.h

@@ -1562,26 +1562,16 @@ __syscall s64_t k_uptime_get(void);
 /**
  * @brief Enable clock always on in tickless kernel
  *
- * This routine enables keeping the clock running when
- * there are no timer events programmed in tickless kernel
- * scheduling. This is necessary if the clock is used to track
- * passage of time.
+ * This routine enables keeping the clock running (that is, it always
+ * keeps an active timer interrupt scheduled) when there are no timer
+ * events programmed in tickless kernel scheduling. This is necessary
+ * if the clock is used to track passage of time (e.g. via
+ * k_uptime_get_32()), otherwise the internal hardware counter may
+ * roll over between interrupts.
  *
  * @retval prev_status Previous status of always on flag
  */
-static inline int k_enable_sys_clock_always_on(void)
-{
-#ifdef CONFIG_TICKLESS_KERNEL
-	int prev_status = _sys_clock_always_on;
-
-	_sys_clock_always_on = 1;
-	_enable_sys_clock();
-
-	return prev_status;
-#else
-	return -ENOTSUP;
-#endif
-}
+int k_enable_sys_clock_always_on(void);
 
 /**
  * @brief Disable clock always on in tickless kernel
@@ -1591,12 +1581,7 @@ static inline int k_enable_sys_clock_always_on(void)
  * scheduling. To save power, this routine should be called
  * immediately when clock is not used to track time.
  */
-static inline void k_disable_sys_clock_always_on(void)
-{
-#ifdef CONFIG_TICKLESS_KERNEL
-	_sys_clock_always_on = 0;
-#endif
-}
+void k_disable_sys_clock_always_on(void);
 
 /**
  * @brief Get system uptime (32-bit version).

kernel/sys_clock.c

@@ -42,7 +42,7 @@ volatile u64_t _sys_clock_tick_count;
  * system clock to track passage of time without interruption.
  * To save power, this should be turned on only when required.
  */
-int _sys_clock_always_on;
+int _sys_clock_always_on = 1;
 
 static u32_t next_ts;
 #endif
@@ -341,3 +341,24 @@ void _nano_sys_clock_tick_announce(s32_t ticks)
 	}
 #endif
 }
+
+int k_enable_sys_clock_always_on(void)
+{
+#ifdef CONFIG_TICKLESS_KERNEL
+	int prev_status = _sys_clock_always_on;
+
+	_sys_clock_always_on = 1;
+	_enable_sys_clock();
+
+	return prev_status;
+#else
+	return -ENOTSUP;
+#endif
+}
+
+void k_disable_sys_clock_always_on(void)
+{
+#ifdef CONFIG_TICKLESS_KERNEL
+	_sys_clock_always_on = 0;
+#endif
+}

samples/philosophers/src/main.c

@@ -141,9 +141,7 @@ static s32_t get_random_delay(int id, int period_in_ms)
 	 * and the current uptime to create some pseudo-randomness. It produces
 	 * a value between 0 and 31.
 	 */
-	k_enable_sys_clock_always_on();
 	s32_t delay = (k_uptime_get_32()/100 * (id + 1)) & 0x1f;
-	k_disable_sys_clock_always_on();
 
 	/* add 1 to not generate a delay of 0 */
 	s32_t ms = (delay + 1) * period_in_ms;

subsys/net/lib/sntp/sntp.c

@@ -149,9 +149,7 @@ static u32_t get_uptime_in_sec(void)
 {
 	u64_t time;
 
-	k_enable_sys_clock_always_on();
 	time = k_uptime_get_32();
-	k_disable_sys_clock_always_on();
 
 	return time / MSEC_PER_SEC;
 }