ztimer: add ztimer_ondemand module for implicit power management

sys/include/ztimer.h

@@ -361,6 +361,20 @@ typedef struct {
      * @param   clock       ztimer clock to cancel a pending alarm, if any
      */
     void (*cancel)(ztimer_clock_t *clock);
+
+#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
+    /**
+     * @brief   Starts the underlying timer
+     * @param   clock       ztimer clock to start
+     */
+    void (*start)(ztimer_clock_t *clock);
+
+    /**
+     * @brief   Stops the underlying timer
+     * @param   clock       ztimer clock to stop
+     */
+    void (*stop)(ztimer_clock_t *clock);
+#endif
 } ztimer_ops_t;
 
 /**
@@ -373,14 +387,21 @@ struct ztimer_clock {
     uint16_t adjust_set;            /**< will be subtracted on every set()  */
     uint16_t adjust_sleep;          /**< will be subtracted on every sleep(),
                                          in addition to adjust_set          */
+#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
+    uint16_t adjust_clock_start;    /**< will be subtracted on every set(),
+                                         if the underlying periph is in
+                                         stopped state                      */
+    uint16_t users;                 /**< user count of this clock */
+#endif
 #if MODULE_ZTIMER_EXTEND || MODULE_ZTIMER_NOW64 || DOXYGEN
     /* values used for checkpointed intervals and 32bit extension */
     uint32_t max_value;             /**< maximum relative timer value       */
     uint32_t lower_last;            /**< timer value at last now() call     */
     ztimer_now_t checkpoint;        /**< cumulated time at last now() call  */
 #endif
-#if MODULE_PM_LAYERED || DOXYGEN
-    uint8_t block_pm_mode;          /**< min. pm mode to block for the clock to run */
+#if MODULE_PM_LAYERED && !MODULE_ZTIMER_ONDEMAND || DOXYGEN
+    uint8_t block_pm_mode;          /**< min. pm mode to block for the clock to run
+                                         don't use in combination with ztimer_ondemand! */
 #endif
 };
 
@@ -393,6 +414,47 @@ struct ztimer_clock {
 void ztimer_handler(ztimer_clock_t *clock);
 
 /* User API */
+/**
+ * @brief   Acquire a clock
+ *
+ * This will indicate the the underlying clock is required to be running.
+ * If time differences are measured using @ref ztimer_now this will make
+ * sure ztimer won't turn of the clock source.
+ *
+ * @param[in]   clock       ztimer clock to operate on
+ *
+ * @return true if this was the first acquisition on this this clock
+ */
+#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
+bool ztimer_acquire(ztimer_clock_t *clock);
+#else
+static inline bool ztimer_acquire(ztimer_clock_t *clock)
+{
+    (void) clock;
+    return false;
+}
+#endif
+
+/**
+ * @brief   Release a clock
+ *
+ * This will indicate the the underlying clock isn't required to be running
+ * anymore and may be turned off.
+ *
+ * @param[in]   clock       ztimer clock to operate on
+ *
+ * @return true if this was the last clock user
+ */
+#if MODULE_ZTIMER_ONDEMAND || DOXYGEN
+bool ztimer_release(ztimer_clock_t *clock);
+#else
+static inline bool ztimer_release(ztimer_clock_t *clock)
+{
+    (void) clock;
+    return false;
+}
+#endif
+
 /**
  * @brief   Set a timer on a clock
  *
@@ -492,6 +554,17 @@ int ztimer_msg_receive_timeout(ztimer_clock_t *clock, msg_t *msg,
  */
 ztimer_now_t _ztimer_now_extend(ztimer_clock_t *clock);
 
+/**
+ * @brief asserts the given clock to be active
+ *
+ * @internal
+ *
+ * @note  This function is internal
+ *
+ * @param[in]   clock          ztimer clock to operate on
+ */
+void _ztimer_assert_clock_active(ztimer_clock_t *clock);
+
 /**
  * @brief   Get the current time from a clock
  *
@@ -511,14 +584,18 @@ ztimer_now_t _ztimer_now_extend(ztimer_clock_t *clock);
  * * Two values can only be compared when the clock has been continuously
  *   active between the first and the second reading.
  *
- *   A clock is guaranteed to be active from the time any timer is set (the
- *   first opportunity to get a "now" value from it is the return value of @ref
- *   ztimer_set) until the time the timer's callback returns. The clock also
- *   stays active when timers are set back-to-back (which is the case when the
- *   first timer's callback sets the second timer), or when they overlap (which
- *   can be known by starting the second timer and afterwards observing that
- *   @ref ztimer_is_set or @ref ztimer_remove returns true in a low-priority
- *   context).
+ *   Calling @ref ztimer_acquire before using `ztimer_now()` is the preferred
+ *   way to guarantee that a clock is continuously active. Make sure to call
+ *   the corresponding @ref ztimer_release after the last `ztimer_now()` call.
+ *
+ *   A clock is also guaranteed to be active from the time any timer is set
+ *   (the first opportunity to get a "now" value from it is the return value of
+ *   @ref ztimer_set) until the time the timer's callback returns. The clock
+ *   also stays active when timers are set back-to-back (which is the case when
+ *   the first timer's callback sets the second timer), or when they overlap
+ *   (which can be known by starting the second timer and afterwards observing
+ *   that @ref ztimer_is_set or @ref ztimer_remove returns true in a
+ *   low-priority context).
  *
  *   In contrast, the clock is not guaranteed to be active if a timer is
  *   removed and then a second one is started (even if the thread does not
@@ -593,12 +670,19 @@ ztimer_now_t _ztimer_now_extend(ztimer_clock_t *clock);
  *          unrelated components are altered that change the systems's power
  *          management behavior.
  *
+ * @warning Make sure to call @ref ztimer_acquire(@p clock) before fetching
+ *          the clock's current time.
+ *
  * @param[in]   clock          ztimer clock to operate on
  *
  * @return  Current count on @p clock
  */
 static inline ztimer_now_t ztimer_now(ztimer_clock_t *clock)
 {
+#if MODULE_ZTIMER_ONDEMAND && DEVELHELP
+    _ztimer_assert_clock_active(clock);
+#endif
+
 #if MODULE_ZTIMER_NOW64
     if (1) {
 #elif MODULE_ZTIMER_EXTEND
@@ -627,6 +711,10 @@ static inline ztimer_now_t ztimer_now(ztimer_clock_t *clock)
  * If the time (@p last_wakeup + @p period) has already passed, the function
  * sets @p last_wakeup to @p last_wakeup + @p period and returns immediately.
  *
+ * @warning Make sure to call @ref ztimer_acquire(@p clock) before making use
+ *          of @ref ztimer_periodic_wakeup. After usage
+ *          @ref ztimer_release(@p clock) should be called.
+ *
  * @param[in]   clock           ztimer clock to operate on
  * @param[in]   last_wakeup     base time stamp for the wakeup
  * @param[in]   period          time in ticks that will be added to @p last_wakeup
@@ -652,11 +740,13 @@ void ztimer_sleep(ztimer_clock_t *clock, uint32_t duration);
  */
 static inline void ztimer_spin(ztimer_clock_t *clock, uint32_t duration)
 {
+    ztimer_acquire(clock);
     uint32_t end = ztimer_now(clock) + duration;
 
     /* Rely on integer overflow. `end - now` will be smaller than `duration`,
      * counting down, until it underflows to UINT32_MAX. Loop ends then. */
     while ((end - ztimer_now(clock)) <= duration) {}
+    ztimer_release(clock);
 }
 
 /**

sys/include/ztimer/config.h

@@ -150,6 +150,19 @@ extern "C" {
 #  endif
 #endif
 
+/**
+ * @brief   An offset for ZTIMER_USEC allowing to compensate for the offset
+ *          introduced by turning on the underlying peripheral.
+ *
+ * @note    This value can be measured with the
+ *          `tests/ztimer_ondemand_benchmark` tool.
+ *
+ *          This value should be configured in the board.h.
+ */
+#ifndef CONFIG_ZTIMER_USEC_ADJUST_CLOCK_START
+#define CONFIG_ZTIMER_USEC_ADJUST_CLOCK_START   0
+#endif
+
 /**
  * @brief   An offset for ZTIMER_USEC allowing to compensate for the offset
  *          of @ref ztimer_set(). It can be measured with @ref ztimer_overhead_set()

sys/include/ztimer/convert.h

@@ -71,6 +71,24 @@ void ztimer_convert_init(ztimer_convert_t *ztimer_convert,
  */
 void ztimer_convert_cancel(ztimer_clock_t *clock);
 
+/**
+ * @brief   ztimer_convert common start() op
+ *
+ * Used by some conversion modules as ztimer_clock_t::ops.start().
+ *
+ * @param[in]       clock   ztimer clock to operate on
+ */
+void ztimer_convert_start(ztimer_clock_t *clock);
+
+/**
+ * @brief   ztimer_convert common stop() op
+ *
+ * Used by some conversion modules as ztimer_clock_t::ops.stop().
+ *
+ * @param[in]       clock   ztimer clock to operate on
+ */
+void ztimer_convert_stop(ztimer_clock_t *clock);
+
 #ifdef __cplusplus
 }
 #endif

sys/include/ztimer/mock.h

@@ -43,11 +43,14 @@ typedef struct {
     uint32_t now;           /**< current counter value */
     uint32_t target;        /**< ticks left until alarm is hit */
     unsigned armed;         /**< flag for checking if a target has been set */
+    unsigned running;       /**< flag for checking if the timer is running */
 
     struct {
         unsigned now;       /**< Number of calls to ztimer_ops_t::now */
         unsigned set;       /**< Number of calls to ztimer_ops_t::set */
         unsigned cancel;    /**< Number of calls to ztimer_ops_t::cancel */
+        unsigned start;     /**< Number of calls to ztimer_ops_t::start */
+        unsigned stop;      /**< Number of calls to ztimer_ops_t::stop */
     } calls;                /**< Struct holding number of calls to each
                                  operation */
 } ztimer_mock_t;

sys/ztimer/Kconfig

@@ -228,6 +228,42 @@ config MODULE_ZTIMER_MOCK
         manually fired to simulate different scenarios and test the ztimer
         implementation using this as a backing timer.
 
+menuconfig MODULE_ZTIMER_ONDEMAND
+    bool "Run ztimer clocks only on demand"
+    help
+        This ztimer extensions keeps track of ztimer users and may disable
+        underlying peripherals if not users are requiring a ztimer clock.
+
+if MODULE_ZTIMER_ONDEMAND
+
+config MODULE_ZTIMER_ONDEMAND_STRICT
+    bool "Strict ztimer on demand"
+    help
+        Enforce ztimer clocks to be running before calling ztimer_now().
+
+config MODULE_ZTIMER_ONDEMAND_TIMER
+    bool "Run Timer only on demand"
+    depends on MODULE_ZTIMER_PERIPH_TIMER
+    help
+        Turn off the underlying Timer peripheral if related ztimer clocks
+        have no users.
+
+config MODULE_ZTIMER_ONDEMAND_RTT
+    bool "Run RTT only on demand"
+    depends on MODULE_ZTIMER_PERIPH_RTT
+    help
+        Turn off the underlying RTT peripheral if related ztimer clocks
+        have no users.
+
+config MODULE_ZTIMER_ONDEMAND_RTC
+    bool "Run RTC only on demand"
+    depends on MODULE_ZTIMER_PERIPH_RTC
+    help
+        Turn off the underlying RTC peripheral if related ztimer clocks
+        have no users.
+
+endif # MODULE_ZTIMER_ONDEMAND
+
 config MODULE_ZTIMER_INIT
     bool
 

sys/ztimer/Makefile.dep

@@ -37,6 +37,10 @@ ifneq (,$(filter ztimer_%,$(USEMODULE)))
   USEMODULE += ztimer_extend
 endif
 
+ifneq (,$(filter ztimer_ondemand_%,$(USEMODULE)))
+  USEMODULE += ztimer_ondemand
+endif
+
 ifneq (,$(filter ztimer_convert_%,$(USEMODULE)))
   USEMODULE += ztimer_convert
 endif

sys/ztimer/convert.c

@@ -35,6 +35,20 @@ void ztimer_convert_cancel(ztimer_clock_t *clock)
     ztimer_remove(ztimer_convert->lower, &ztimer_convert->lower_entry);
 }
 
+void ztimer_convert_start(ztimer_clock_t *clock)
+{
+    ztimer_convert_t *ztimer_convert = (ztimer_convert_t *)clock;
+
+    ztimer_acquire(ztimer_convert->lower);
+}
+
+void ztimer_convert_stop(ztimer_clock_t *clock)
+{
+    ztimer_convert_t *ztimer_convert = (ztimer_convert_t *)clock;
+
+    ztimer_release(ztimer_convert->lower);
+}
+
 void ztimer_convert_init(ztimer_convert_t *ztimer_convert,
                          ztimer_clock_t *lower,
                          uint32_t max_value)
@@ -46,7 +60,7 @@ void ztimer_convert_init(ztimer_convert_t *ztimer_convert,
             .arg = ztimer_convert,
         },
         .super.max_value = max_value,
-#  ifdef MODULE_PM_LAYERED
+#  if MODULE_PM_LAYERED && !MODULE_ZTIMER_ONDEMAND
         .super.block_pm_mode = ZTIMER_CLOCK_NO_REQUIRED_PM_MODE,
 #  endif
     };

sys/ztimer/convert_frac.c

@@ -74,6 +74,10 @@ static const ztimer_ops_t ztimer_convert_frac_ops = {
     .set = ztimer_convert_frac_op_set,
     .now = ztimer_convert_frac_op_now,
     .cancel = ztimer_convert_cancel,
+#if MODULE_ZTIMER_ONDEMAND
+    .start = ztimer_convert_start,
+    .stop = ztimer_convert_stop,
+#endif
 };
 
 static void ztimer_convert_frac_compute_scale(ztimer_convert_frac_t *self,
@@ -103,15 +107,20 @@ void ztimer_convert_frac_init(ztimer_convert_frac_t *self,
     ztimer_convert_frac_compute_scale(self, freq_self, freq_lower);
     if (freq_self < freq_lower) {
         self->super.super.max_value = frac_scale(&self->scale_now, UINT32_MAX);
+#if !MODULE_ZTIMER_ONDEMAND
+        /* extend lower clock only if the ondemand driver isn't selected
+         * otherwise, the clock extension will be called with the first
+         * ztimer_acquire() call */
         ztimer_init_extend(&self->super.super);
+#endif
     }
     else {
         DEBUG("ztimer_convert_frac_init: rounding up val:%" PRIu32 "\n",
               (uint32_t)(freq_self / freq_lower));
         self->round = freq_self / freq_lower;
         self->super.super.max_value = UINT32_MAX;
     }
-#ifdef MODULE_PM_LAYERED
+#if MODULE_PM_LAYERED && !MODULE_ZTIMER_ONDEMAND
     self->super.super.block_pm_mode = ZTIMER_CLOCK_NO_REQUIRED_PM_MODE;
 #endif
 }

sys/ztimer/convert_muldiv64.c

@@ -98,6 +98,10 @@ static const ztimer_ops_t _ztimer_convert_muldiv64_ops = {
     .set = _ztimer_convert_muldiv64_set,
     .now = _ztimer_convert_muldiv64_now,
     .cancel = ztimer_convert_cancel,
+#if MODULE_ZTIMER_ONDEMAND
+    .start = ztimer_convert_start,
+    .stop = ztimer_convert_stop,
+#endif
 };
 
 void ztimer_convert_muldiv64_init(
@@ -121,5 +125,10 @@ void ztimer_convert_muldiv64_init(
     ztimer_convert_muldiv64->super.super.ops = &_ztimer_convert_muldiv64_ops;
     ztimer_convert_muldiv64->div = div;
     ztimer_convert_muldiv64->mul = mul;
+#if !MODULE_ZTIMER_ONDEMAND
+    /* extend lower clock only if the ondemand driver isn't selected
+     * otherwise, the clock extension will be called with the first
+     * ztimer_acquire() call */
     ztimer_init_extend(&ztimer_convert_muldiv64->super.super);
+#endif
 }

sys/ztimer/convert_shift.c

@@ -78,6 +78,10 @@ static const ztimer_ops_t _ztimer_convert_shift_ops_up = {
     .set = _ztimer_convert_shift_up_set,
     .now = _ztimer_convert_shift_up_now,
     .cancel = ztimer_convert_cancel,
+#if MODULE_ZTIMER_ONDEMAND
+    .start = ztimer_convert_start,
+    .stop = ztimer_convert_stop,
+#endif
 };
 
 void ztimer_convert_shift_up_init(ztimer_convert_shift_t *clock,