integer_math.hpp

Go to the documentation of this file.

/**
 * @file integer_math.hpp
 * @brief Integer math utilities for embedded systems
 * @ingroup primitives
 * 
 * Provides efficient integer math operations optimized for ARM Cortex-M.
 * No floating point operations - suitable for M0+ without FPU.
 */
 
#ifndef SBL_PRIMITIVES_MATH_INTEGER_MATH_HPP_
#define SBL_PRIMITIVES_MATH_INTEGER_MATH_HPP_
 
#include <cstdint>
 
namespace sbl {
namespace primitives {
namespace math {
 
/**
 * @brief Integer math utilities optimized for ARM Cortex-M
 * 
 * Static utility functions for common mathematical operations
 * using only integer arithmetic.
 */
class IntegerMath {
public:
    /**
     * @brief Calculate greatest common divisor
     * 
     * @param a First value
     * @param b Second value
     * @return Greatest common divisor
     */
    static constexpr uint32_t gcd(uint32_t a, uint32_t b) {
        while (b != 0) {
            uint32_t temp = b;
            b = a % b;
            a = temp;
        }
        return a;
    }
    
    /**
     * @brief Calculate least common multiple
     * 
     * @param a First value
     * @param b Second value
     * @return Least common multiple
     */
    static constexpr uint32_t lcm(uint32_t a, uint32_t b) {
        return (a / gcd(a, b)) * b;  // Avoid overflow by dividing first
    }
    
    /**
     * @brief Integer division with rounding
     * 
     * @param dividend Value to divide
     * @param divisor Value to divide by
     * @return Rounded result
     */
    static constexpr uint32_t divideRounded(uint32_t dividend, uint32_t divisor) {
        return (dividend + divisor / 2) / divisor;
    }
    
    /**
     * @brief Calculate timer prescaler for desired frequency
     * 
     * Given a base clock frequency and desired output frequency,
     * calculate the best prescaler value.
     * 
     * @param base_freq Base clock frequency (Hz)
     * @param target_freq Desired output frequency (Hz)
     * @return Prescaler value (1-65536)
     */
    static constexpr uint32_t calculatePrescaler(uint32_t base_freq, uint32_t target_freq) {
        if (target_freq == 0 || target_freq > base_freq) {
            return 1;
        }
        
        uint32_t prescaler = divideRounded(base_freq, target_freq);
        
        // Clamp to typical ARM timer prescaler limits
        if (prescaler > 65536) {
            return 65536;
        } else if (prescaler < 1) {
            return 1;
        }
        
        return prescaler;
    }
    
    /**
     * @brief Calculate timer reload value for interval
     * 
     * Given timer frequency and desired interval, calculate reload value.
     * 
     * @param timer_freq Timer tick frequency (Hz)
     * @param interval_us Desired interval (microseconds)
     * @return Timer reload value
     */
    static constexpr uint32_t calculateTimerReload(uint32_t timer_freq, uint32_t interval_us) {
        // Convert microseconds to timer ticks
        // ticks = (timer_freq * interval_us) / 1000000
        // Use 64-bit to avoid overflow
        uint64_t ticks = (static_cast<uint64_t>(timer_freq) * interval_us) / 1000000;
        
        // Clamp to 32-bit range
        if (ticks > 0xFFFFFFFF) {
            return 0xFFFFFFFF;
        }
        
        return static_cast<uint32_t>(ticks);
    }
    
    /**
     * @brief Clamp value to range
     * 
     * @param value Value to clamp
     * @param min Minimum value
     * @param max Maximum value
     * @return Clamped value
     */
    template<typename T>
    static constexpr T clamp(T value, T min, T max) {
        return (value < min) ? min : (value > max) ? max : value;
    }
    
    /**
     * @brief Get minimum of two values
     * 
     * @param a First value
     * @param b Second value
     * @return Minimum value
     */
    template<typename T>
    static constexpr T min(T a, T b) {
        return (a < b) ? a : b;
    }
    
    /**
     * @brief Get maximum of two values
     * 
     * @param a First value
     * @param b Second value
     * @return Maximum value
     */
    template<typename T>
    static constexpr T max(T a, T b) {
        return (a > b) ? a : b;
    }
    
    /**
     * @brief Check if value is power of two
     * 
     * @param value Value to check
     * @return true if power of two
     */
    static constexpr bool isPowerOfTwo(uint32_t value) {
        return value && !(value & (value - 1));
    }
    
    /**
     * @brief Get next power of two
     * 
     * @param value Input value
     * @return Next power of two >= value
     */
    static constexpr uint32_t nextPowerOfTwo(uint32_t value) {
        if (value == 0) return 1;
        
        value--;
        value |= value >> 1;
        value |= value >> 2;
        value |= value >> 4;
        value |= value >> 8;
        value |= value >> 16;
        value++;
        
        return value;
    }
};
 
} // namespace math
} // namespace primitives
} // namespace sbl
 
#endif // SBL_PRIMITIVES_MATH_INTEGER_MATH_HPP_