Merge pull request #20581 from maribu/timer_get_closest_freq

drivers/periph_timer: add `timer_get_closest_freq()`

Author: maribu

drivers/include/periph/timer.h

@@ -267,7 +267,7 @@ uword_t timer_query_channel_numof(tim_t dev);
 /**
  * @brief   Iterate over supported frequencies
  *
- * @param   dev     Timer to get the next supported frequency of
+ * @param   dev     The timer to get the next supported frequency of
  * @param   index   Index of the frequency to get
  * @return          The @p index highest frequency supported by the timer
  * @retval  0       @p index is too high
@@ -296,6 +296,24 @@ uword_t timer_query_channel_numof(tim_t dev);
  */
 uint32_t timer_query_freqs(tim_t dev, uword_t index);
 
+/**
+ * @brief   Search the frequency supported by the timer that is closest to
+ *          a given target frequency, efficiently
+ *
+ * @param   dev     The timer to get the closest supported frequency for
+ * @param   target  Ideal frequency to match
+ * @return          The frequency supported by the timer @p dev that is
+ *                  closest to @p target
+ *
+ * @details This will use binary search internally to have an O(log(n))
+ *          runtime. This can be relevant on hardware with 16 bit or 32 bit
+ *          prescaler registers.
+ *
+ * @note    Add `FEATURES_REQUIRED += periph_timer_query_freqs` to your
+ *          `Makefile`.
+ */
+uint32_t timer_get_closest_freq(tim_t dev, uint32_t target);
+
 #if defined(DOXYGEN)
 /**
  * @brief Check whether a compare channel has matched

drivers/periph_common/timer.c

@@ -38,4 +38,53 @@ uword_t timer_query_channel_numof(tim_t dev)
     (void)dev;
     return TIMER_CHANNEL_NUMOF;
 }
+
+uint32_t timer_get_closest_freq(tim_t dev, uint32_t target)
+{
+    uint32_t freq;
+    uword_t idx_max = timer_query_freqs_numof(dev) - 1;
+
+    /* use binary search to find one of the three possibilities:
+     * 1. If an exact match is possible: The exact match is found
+     * 2. Otherwise the closest frequency is found, which might be either
+     *      a) the highest frequency below the target, or
+     *      b) the lowest frequency above the target
+     */
+    uword_t idx_lower = 0;
+    uword_t idx_upper = idx_max;
+    while (idx_lower != idx_upper) {
+        uword_t idx_mid = (idx_lower + idx_upper) >> 1;
+        freq = timer_query_freqs(dev, idx_mid);
+        if (freq > target) {
+            idx_lower = idx_mid + 1;
+        }
+        else {
+            idx_upper = idx_mid;
+        }
+    }
+
+    freq = timer_query_freqs(dev, idx_lower);
+    if ((freq < target) && (idx_lower > 0)) {
+        /* binary search yielded the closest frequency below the target. But
+         * maybe the closest frequency above the target is actually better. */
+        uint32_t diff = target - freq;
+        uint32_t alternative = timer_query_freqs(dev, idx_lower - 1);
+        if (target + diff > alternative) {
+            /* the alternative is better */
+            return alternative;
+        }
+    }
+    else if ((freq > target) && (idx_lower < idx_max)) {
+        /* Got a frequency above the target, maybe the one below would be
+         * a closer match */
+        uint32_t diff = freq - target;
+        uint32_t alternative = timer_query_freqs(dev, idx_lower + 1);
+        if (target < alternative + diff) {
+            return alternative;
+        }
+    }
+
+    /* either we got an exact match, or the other candidate was no closer */
+    return freq;
+}
 #endif

tests/periph/timer/main.c

@@ -202,7 +202,7 @@ static int test_timer(unsigned num, uint32_t timer_freq)
         return 0;
     }
 
-    printf("    OK (no spurious IRQs)\n");
+    printf("    [OK] (no spurious IRQs)\n");
 
     return 1;
 }
@@ -249,8 +249,47 @@ static void print_supported_frequencies(tim_t dev)
                "    %u: %" PRIu32 "\n",
                (unsigned)(end - 1), timer_query_freqs(dev, end - 1));
     }
+}
+
+static void test_querying(tim_t dev)
+{
+    uword_t last = query_freq_numof(dev) - 1;
+
+    puts("Testing timer_get_closest_freq()...");
+    for (uword_t i = 0; i <= MIN(last, 255); i++) {
+        uint32_t closest;
+        uint32_t freq = timer_query_freqs(dev, i);
+
+        /* Searching for a supported freq should yield the supported freq: */
+        expect(freq == timer_get_closest_freq(dev, freq));
+
+        /* Assuming that no other frequency close to `freq` are supported,
+         * we would assume that asking for `freq - 1` and for `freq + 1` would
+         * also return `freq`. There are some corner cases, though. Let's look
+         * at asking for `freq - 1` here first:
+         *
+         * - `freq - 1` is actually also supported. In that case
+         *   `timer_get_closest_freq(dev, freq - 1)` should actually return
+         *   `freq - 1`
+         * - `freq - 2` is also supported (but not `freq - 1`). In this case
+         *   returning either `freq - 2` or `freq` would be valid for
+         *   `timer_get_closest_freq(dev, freq - 1)`.
+         *
+         * Therefore, we just except `freq - 2`, `freq - 1`, and `freq` as
+         * results for `timer_get_closest_freq(dev, freq - 1)`. */
+        closest = timer_get_closest_freq(dev, freq - 1);
+        expect((freq >= closest) && closest >= freq - 2);
+
+        /* Now same with `freq + 1` as target. Due to the same corner cases,
+         * we accept `freq`, `freq + 1`, and `freq + 2` here. */
+        closest = timer_get_closest_freq(dev, freq + 1);
+        expect((freq <= closest) && closest <= freq + 2);
+    }
 
-    expect(timer_query_freqs(dev, end) == 0);
+    puts("[OK]\n"
+         "Testing timer_query_freqs() for out of bound index...");
+    expect(timer_query_freqs(dev, last + 1) == 0);
+    puts("[OK]");
 }
 
 int main(void)
@@ -265,6 +304,12 @@ int main(void)
         printf("\nTIMER %u\n"
                  "=======\n\n", i);
         print_supported_frequencies(TIMER_DEV(i));
+
+        /* test querying of frequencies, but only if supported by the driver */
+        if (IS_USED(MODULE_PERIPH_TIMER_QUERY_FREQS)) {
+            test_querying(TIMER_DEV(i));
+        }
+
         uword_t end = query_freq_numof(TIMER_DEV(i));
 
         /* Test only up to three frequencies and only the fastest once.