[math] Add prescaler + counter algorithm

Author: salkinium

src/modm/math/algorithm/module.lb

@@ -13,7 +13,7 @@
 
 def init(module):
     module.name = ":math:algorithm"
-    module.description = "Math Algorithms"
+    module.description = FileReader("module.md")
 
 def prepare(module, options):
     module.depends(":math:units")

src/modm/math/algorithm/module.md

@@ -0,0 +1,196 @@
+# Algorithms
+
+A collection of useful and lightweight algorithms.
+
+
+## Convenience Iterators
+
+Inspired by Python's built-in `range` and `enumerate` functions, you can use
+`modm::range` and `modm::enumerate` in for loops:
+
+```cpp
+// Iterates over 0 .. 9
+for (auto i : modm::range(10)) {
+    MODM_LOG_INFO << i << modm::endl;
+}
+// Iterates over 10 .. 19
+for (auto i : modm::range(10, 20)) {
+    MODM_LOG_INFO << i << modm::endl;
+}
+// Iterates over 20, 22, 24, 26, 28
+for (auto i : modm::range(20, 30, 2)) {
+    MODM_LOG_INFO << i << modm::endl;
+}
+
+// Iterates over 0 .. N-1, where N = size of iterable
+for (auto [i, item] : modm::enumerate(iterable)) {
+    MODM_LOG_INFO << i << item << modm::endl;
+}
+```
+
+
+## Prescaler Calculators
+
+Peripheral output frequencies are usually generated by dividing an input clock
+with a prescaler in hardware. Finding the closest prescaler value for a desired
+output frequency can be unintuitive, therefore, these classes provide a simple
+interface for a constexpr calculator.
+
+All calculators return a `Result` struct containing desired, input, and output
+frequencies, the relative error of the output vs desired frequency, and the
+prescaler and its index. The prescaler index is typically the value to write
+to the register directly:
+
+```cpp
+// 16-bit linear prescaler [1, 2^16] mapped as [0, 0xffff].
+constexpr auto result = Prescaler::from_linear(10_MHz, 1_kHz, 1, 1ul << 16);
+static_assert(result.input_frequency == 10_MHz);
+static_assert(result.desired_frequency == 1_kHz);
+// Calculator finds an exact match without error
+static_assert(result.frequency == 1_kHz);
+static_assert(result.error == 0);
+// with prescaler 1e4 = 1e7 / 1e3.
+static_assert(result.prescaler == 10'000);
+static_assert(result.index == 9'999);
+PERIPHERAL->PRESCALER = result.index;
+```
+
+The index is particularly useful for non-contiguous prescalers, the most common
+being power-of-two values:
+
+```cpp
+// Power-of-two prescaler with 8 values between [16, 4096].
+constexpr auto result = Prescaler::from_power(32_kHz, 100_Hz, 1ul << 4, 1ul << 12);
+// Calculator cannot find an exact match! Closest has -25% error!
+static_assert(result.frequency == 125_Hz);
+static_assert(result.error == -0.25);
+// Ideal Prescaler is 320, clostest is 256
+static_assert(result.prescaler == 256);
+// Index is 256 = 1ul << (4 + 4)
+static_assert(result.index == 4);
+```
+
+Non-contiguous prescalers can also be created with a modifier function:
+
+```cpp
+// Only even prescalers from [2, 1024]
+constexpr auto result = Prescaler::from_function(
+        110_MHz, 3.5_MHz, 1, 512, [](uint32_t i){ return i*2; });
+// Ideal prescaler is 31.4, closest is 32 with ~2% error.
+static_assert(result.frequency == 3.4375_MHz);
+static_assert(result.error == 0.02);
+static_assert(result.prescaler == 32);
+static_assert(result.index == 15); // 32/2 - 1
+```
+
+For all other cases, prescalers can be passed as an initializer list or as any
+forward range. Note that the prescaler values *must* be sorted, otherwise
+the calculator will compute the wrong prescaler values!
+
+```cpp
+constexpr auto result = Prescaler::from_list(1_MHz, 1_kHz, {2,4,16,256,1024});
+constexpr auto result = Prescaler::from_range(2_kHz, 1_kHz, std::array{1,2,3});
+```
+
+A special case is made of two chained prescalers that are both linear
+powers-of-two. These are often called "fractional prescalers" and act as a
+single binary-scaled linear prescaler and can thus be modeled as such:
+
+```cpp
+// A fractional 12.4-bit prescaler can be modeled as a single 16-bit prescaler.
+constexpr auto result = Prescaler::from_linear(SystemClock::Usart1, 115200, 16, 1ul << 16);
+// The resulting prescaler can be written directly to the register.
+USART1->BRR = result.prescaler;
+```
+
+
+### Prescalers with Counters
+
+However, often chained prescalers cannot be converted to a linear prescaler, for
+example, a timer with a set of power-of-two prescalers and a 16 or 32-bit
+counter. These must be computed with a different class:
+
+```cpp
+// A prescaler with power-of-two values [4, 256] going into a 12-bit down counter.
+constexpr auto result = PrescalerCounter::from_power(32_kHz, 1_Hz, 1ul << 12, 4, 256);
+// Calculator finds an exact match without error
+static_assert(result.frequency == 1_Hz);
+static_assert(result.error == 0);
+// with prescaler 8 and counter 4'000.
+static_assert(result.prescaler == 8);
+static_assert(result.counter == 4'000);
+static_assert(result.index == 1);
+```
+
+The calculator only picks the first prescaler with the lowest error, however,
+in this example, there can be multiple exact solutions:
+
+  32000 = 8 × 4000 = 16 × 2000 = ... = 128 × 250 = 256 × 125
+
+If the prescaler and counter is used to generate a waveform like PWM, then it is
+beneficial to pick the combination with the largest counter value. However, if
+the use case is to preserve power, then a slow running counter requires the
+highest prescaler. Therefore the order of prescalers can be reversed:
+
+```cpp
+constexpr auto result = PrescalerCounter::from_power(32_kHz, 1_Hz, 1ul << 12, 256, 4);
+static_assert(result.prescaler == 256);
+static_assert(result.counter == 125);
+// Index is not the same!
+static_assert(result.index == 0);
+```
+
+The same applies to the `PrescalerCounter::from_linear()` and
+`PrescalerCounter::from_function()` calculators, while the order for lists and
+forward ranges can be entirely arbitrary:
+
+```cpp
+constexpr auto result = PrescalerCounter::from_list(32_kHz, 1_Hz, 1ul << 12, {128,16,256,4});
+static_assert(result.prescaler == 128);
+static_assert(result.counter == 250);
+// Index is relative to the list order now!
+static_assert(result.index == 0);
+```
+
+!!! tip "Time Durations"
+    While the calculator is designed for frequencies, time durations can also be
+    computed by transforming the input as `frequency = 1.0 / duration` and then
+    transforming the output back as `duration = 1.0 / frequency`.
+
+!!! success "Floating-Point Frequencies"
+    You can define the type used for frequency representation by using the
+    `GenericPrescaler<double>` and `GenericPrescalerCounter<double>` classes.
+
+
+### Tolerance of Prescaler Error
+
+Each `Result` has a signed(!), relative error attached, which can be used to
+assert on the quality of the calculation. Note that using `static_assert` on the
+error directly will only print the error values:
+
+```cpp
+static_assert(std::abs(result.error) < 5_pct);
+```
+```
+error: static assertion failed
+ | static_assert(std::abs(result.error) < tolerance);
+ |               ~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~
+note: the comparison reduces to '(0.10 < 0.05)'
+```
+
+However, by using a helper method, the requested and closest available
+frequencies can be displayed to the developer:
+
+```cpp
+// Accidentally used kBaud instead of Baud, which cannot be generated
+constexpr auto result = Prescaler::from_linear(SystemClock::Usart2, 115200_kBd, 16, 1ul << 16);
+modm::assertBaudrateInTolerance<result.frequency, result.desired_frequency, tolerance>();
+```
+```
+In instantiation of 'static void modm::PeripheralDriver::assertBaudrateInTolerance()
+[with long long unsigned int available = 3000000; long long unsigned int requested = 115200000; float tolerance = 0.01f]':
+error: static assertion failed: The closest available baudrate exceeds the tolerance of the requested baudrate!
+ | static_assert(modm::isValueInTolerance(requested, available, tolerance),
+ |               ~~~~~~~~~~~~~~~~~~~~~~~~^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+note: 'modm::isValueInTolerance<long long unsigned int>(115200000, 3000000, 0.01f)' evaluates to false
+```

src/modm/math/algorithm/prescaler.hpp

@@ -15,10 +15,8 @@
 #include <modm/math/units.hpp>
 
 #include <algorithm>
-#include <cmath>
-#include <concepts>
 #include <cstdint>
-#include <initializer_list>
+#include <ranges>
 
 namespace modm
 {
@@ -29,50 +27,49 @@ namespace modm
  * @note For ranges the end is *inclusive*: [begin, end]!
  * @ingroup	modm_math_algorithm
  */
-template<std::unsigned_integral T>
+template<typename T>
 class
 GenericPrescaler
 {
 public:
 	struct Result
 	{
-		constexpr Result(T input_frequency,
-		                 T desired_frequency,
-		                 uint32_t index, uint32_t prescaler) :
+		constexpr Result(T input_frequency, T desired_frequency,
+						 uint32_t index, uint32_t prescaler) :
 			index{index}, prescaler{prescaler},
 			frequency{input_frequency / prescaler},
 			input_frequency{input_frequency},
 			desired_frequency{desired_frequency},
-			error{1.f - float(input_frequency / prescaler) / desired_frequency}
+			error{1.f - float(input_frequency) / float(prescaler * desired_frequency)}
 		{}
 		/// Zero-indexed prescaler result
-		const uint32_t index;
+		uint32_t index;
 		/// Prescaler value
-		const uint32_t prescaler;
+		uint32_t prescaler;
 		/// Generated frequency
-		const T frequency;
+		T frequency;
 		/// Input frequency
-		const T input_frequency;
+		T input_frequency;
 		/// Desired Frequency
-		const T desired_frequency;
+		T desired_frequency;
 		/// Relative Frequency Error
-		const float error;
+		float error;
 	};
 
 public:
-	/// From any iterable container.
-	/// @note container must have `begin()`, `end()` and `size()` function!
-	template<class Iterator>
+	/// From any forward range.
+	/// @pre The container must be sorted from low to high numbers!
 	static constexpr Result
-	from_iterator(T input_frequency,
-				  T desired_frequency,
-				  Iterator prescalers)
+	from_range(T input_frequency, T desired_frequency,
+			   std::ranges::forward_range auto&& prescalers)
 	{
 		const double desired = double(input_frequency) / desired_frequency;
-		uint32_t prescaler_floor{*prescalers.begin()};
-		uint32_t prescaler_ceiling{*prescalers.begin()};
+		const size_t prescaler_size = std::ranges::distance(
+				std::ranges::begin(prescalers), std::ranges::end(prescalers));
+		uint32_t prescaler_floor{*std::ranges::begin(prescalers)};
+		uint32_t prescaler_ceiling{*std::ranges::begin(prescalers)};
 		uint32_t ii_floor{0}, ii_ceiling{0};
-		if (desired <= prescaler_floor or prescalers.size() == 1)
+		if (desired <= prescaler_floor or prescaler_size == 1)
 			return {input_frequency, desired_frequency, 0, prescaler_floor};
 		for (uint32_t prescaler : prescalers)
 		{
@@ -91,54 +88,62 @@ GenericPrescaler
 	}
 
 	/// From a initializer list.
+	/// @pre The list must be sorted from low to high numbers!
 	static constexpr Result
-	from_list(T input_frequency,
-			  T desired_frequency,
+	from_list(T input_frequency, T desired_frequency,
 			  std::initializer_list<uint32_t> prescalers)
 	{
-		return from_iterator(input_frequency, desired_frequency, prescalers);
+		return from_range(input_frequency, desired_frequency, prescalers);
 	}
 
 	/// From any linear range via modifier function.
 	/// @note the range end is *inclusive*: [begin, end].
+	/// @pre begin must be smaller or equal than end!
 	template< typename Function >
 	static constexpr Result
-	from_function(T input_frequency,
-			      T desired_frequency,
-			      uint32_t begin, uint32_t end,
-			      Function prescaler_modifier)
+	from_function(T input_frequency, T desired_frequency,
+				  uint32_t begin, uint32_t end, Function prescaler_modifier)
 	{
 		struct linear_range_iterator
 		{
+			using iterator_category [[maybe_unused]] = std::forward_iterator_tag;
+			using value_type [[maybe_unused]] = uint32_t;
+			using difference_type [[maybe_unused]] = int32_t;
+			using pointer [[maybe_unused]] = value_type*;
+			using reference [[maybe_unused]] = value_type&;
+
 			uint32_t state;
-			const Function modifier;
-			constexpr uint32_t operator*() const { return modifier(state); }
+			Function *modifier;
+
+			constexpr value_type operator*() const { return (*modifier)(state); }
 			constexpr linear_range_iterator& operator++() { state++; return *this; }
-			constexpr bool operator!=(const linear_range_iterator &o) const { return state != o.state; }
+			constexpr linear_range_iterator operator++(int) { auto old(*this); ++*this; return old; }
+			constexpr bool operator==(const linear_range_iterator &o) const { return state == o.state; }
+			constexpr difference_type operator-(const linear_range_iterator &o) const { return state - o.state; }
 		};
 		struct linear_range
 		{
-			const uint32_t m_begin;
-			const uint32_t m_end;
-			const Function modifier;
-			constexpr linear_range_iterator begin() const { return linear_range_iterator{m_begin, modifier}; }
-			constexpr linear_range_iterator end() const { return linear_range_iterator{m_end, modifier}; }
+			uint32_t m_begin;
+			uint32_t m_end;
+			Function *modifier;
+
+			constexpr linear_range_iterator begin() const { return {m_begin, modifier}; }
+			constexpr linear_range_iterator end() const { return {m_end, modifier}; }
 			constexpr size_t size() const { return m_end - m_begin; }
 		};
-		linear_range range{begin, end+1, prescaler_modifier};
-		return from_iterator(input_frequency, desired_frequency, range);
+		linear_range range{begin, end+1, &prescaler_modifier};
+		return from_range(input_frequency, desired_frequency, range);
 	}
 
 	/// From any linear range.
 	/// @note the range end is *inclusive*: [begin, end].
+	/// @pre begin must be smaller or equal than end!
 	static constexpr Result
-	from_range(T input_frequency,
-			   T desired_frequency,
-			   uint32_t begin, uint32_t end)
+	from_linear(T input_frequency, T desired_frequency, uint32_t begin, uint32_t end)
 	{
 		const double desired = double(input_frequency) / desired_frequency;
-		const uint32_t prescaler_floor = std::max(uint32_t(std::floor(desired)), begin);
-		const uint32_t prescaler_ceiling = std::min(uint32_t(std::ceil(desired)), end);
+		const uint32_t prescaler_floor = std::max(uint32_t(desired), begin);
+		const uint32_t prescaler_ceiling = std::min(uint32_t(desired) + 1, end);
 		const T baud_lower = input_frequency / prescaler_ceiling;
 		const T baud_upper = input_frequency / prescaler_floor;
 		const double baud_middle = (baud_upper + baud_lower) / 2.0;
@@ -149,12 +154,10 @@ GenericPrescaler
 
 	/// From any 2-logarithmic range.
 	/// @note the range end is *inclusive*: [begin, end].
-	/// @param begin	must be a power-of-two!
-	/// @param end		must be a power-of-two!
+	/// @pre `begin` and `end` must be powers of two!
+	/// @pre `begin` must be smaller or equal than `end`!
 	static constexpr Result
-	from_power(T input_frequency,
-			   T desired_frequency,
-			   uint32_t begin, uint32_t end)
+	from_power(T input_frequency, T desired_frequency, uint32_t begin, uint32_t end)
 	{
 		const double desired = double(input_frequency) / desired_frequency;
 		uint32_t ii{0}; uint32_t power{begin};