An Old Timer's Tears [FWT-243]

CMakeLists.txt

@@ -60,7 +60,8 @@ if(COMPDEFS MATCHES "(.*)STM32F3xx(.*)")
     src/core/io/platform/f3xx/UARTf3xx.cpp
     src/core/io/platform/f3xx/SPIf3xx.cpp
     src/core/dev/platform/f3xx/IWDGf3xx.cpp
-    src/core/dev/platform/f3xx/RTCf3xx.cpp)
+    src/core/dev/platform/f3xx/RTCf3xx.cpp
+    )
 elseif(COMPDEFS MATCHES "(.*)STM32F4xx(.*)")
     target_sources(${PROJECT_NAME} PRIVATE
     src/core/utils/platform/f4xx/timef4xx.cpp

include/core/dev/MCUTimer.hpp

@@ -9,39 +9,38 @@
 #endif
 
 namespace core::dev {
-
 /**
  * Enum for all the hardware timers available on the current MCU
  */
 enum class MCUTimer {
 #if defined(STM32F302x8)
     Timer1,
     Timer2,
-    Timer6,
     Timer15,
     Timer16,
     Timer17,
 #elif defined(STM32F334x8)
     Timer1,
     Timer2,
     Timer3,
-    Timer6,
-    Timer7,
     Timer15,
     Timer16,
     Timer17,
 #elif defined(STM32F446xx)
+    Timer1,
     Timer2,
     Timer3,
     Timer4,
     Timer5,
+    Timer8,
     Timer9,
     Timer10,
     Timer11,
     Timer12,
     Timer13,
     Timer14,
 #endif
+    None
 };
 
 /**
@@ -50,7 +49,7 @@ enum class MCUTimer {
  * @param mcuTimer MCUTimer of which to get the HAL equivalent
  * @return HAL equivalent of mcuTimer
  */
-TIM_TypeDef* getTIM(MCUTimer mcuTimer) {
+inline TIM_TypeDef* getTIM(const MCUTimer mcuTimer) {
     TIM_TypeDef* timPeriph;
     switch (mcuTimer) {
 #if defined(STM32F302x8)
@@ -60,9 +59,6 @@ TIM_TypeDef* getTIM(MCUTimer mcuTimer) {
     case MCUTimer::Timer2:
         timPeriph = TIM2;
         break;
-    case MCUTimer::Timer6:
-        timPeriph = TIM6;
-        break;
     case MCUTimer::Timer15:
         timPeriph = TIM15;
         break;
@@ -82,12 +78,6 @@ TIM_TypeDef* getTIM(MCUTimer mcuTimer) {
     case MCUTimer::Timer3:
         timPeriph = TIM3;
         break;
-    case MCUTimer::Timer6:
-        timPeriph = TIM6;
-        break;
-    case MCUTimer::Timer7:
-        timPeriph = TIM7;
-        break;
     case MCUTimer::Timer15:
         timPeriph = TIM15;
         break;
@@ -98,10 +88,9 @@ TIM_TypeDef* getTIM(MCUTimer mcuTimer) {
         timPeriph = TIM17;
         break;
 #elif defined(STM32F446xx)
-    /*
-     * Timers 1 and 8 are advanced timers
-     * so they are not included in this switch statement
-     */
+    case MCUTimer::Timer1:
+        timPeriph = TIM1;
+        break;
     case MCUTimer::Timer2:
         timPeriph = TIM2;
         break;
@@ -114,6 +103,9 @@ TIM_TypeDef* getTIM(MCUTimer mcuTimer) {
     case MCUTimer::Timer5:
         timPeriph = TIM5;
         break;
+    case MCUTimer::Timer8:
+        timPeriph = TIM8;
+        break;
     case MCUTimer::Timer9:
         timPeriph = TIM9;
         break;
@@ -132,6 +124,9 @@ TIM_TypeDef* getTIM(MCUTimer mcuTimer) {
     case MCUTimer::Timer14:
         timPeriph = TIM14;
         break;
+    default:
+        timPeriph = TIM1;
+        break;
 #endif
     }
 

include/core/dev/RTCTimer.hpp

@@ -40,7 +40,7 @@ class RTCTimer : public Timer {
 
     void reloadTimer() override;
 
-    void setPeriod(uint32_t clock) override;
+    void setPeriod(uint32_t clock, uint32_t clockPrescaler) override;
 
     /**
      * Gets the time since the RTC clock began in seconds

include/core/dev/Timer.hpp

@@ -3,14 +3,68 @@
 
 #include <cstdint>
 
-namespace core::dev {
+/**
+ * If AUTO_PRESCALER is sent as a prescaler the timer will calculate its own Prescaler.
+ * Yes, this is a negative in an uint32_t, but it ends up just causing an underflow, and making it the max of an
+ * uint32_t.
+ */
+#define AUTO_PRESCALER uint32_t(-1)
 
+namespace core::dev {
 /**
- * This class will represent an internal general purpose timer device for the STM32.
- * It is capable of triggering interrupts with a given frequency
+ * @brief A timer configuration provides a timer with all configuration variables needed to be set up..
  */
+typedef struct {
+    /**
+     * Specifies how the timer will count.
+     * This parameter can be a value of @ref TIM_Counter_Mode
+     * Maps to a timer's @ref TIM_Base_InitTypeDef:CounterMode
+     */
+    uint32_t counterMode{};
+
+    /**
+     * Specifies the clock division.
+     * This parameter can be a value of @ref TIM_ClockDivision
+     * Maps to a timer's @ref TIM_Base_InitTypeDef:ClockDivision
+     */
+    uint32_t clockDivision{};
+
+    /**
+     * Specifies the auto reload preload value, which controls whether @ref TIMx_ARR is buffered or not.
+     * This parameter can be a value of @ref TIM_AutoReloadPreload
+     * Maps to a timer's @ref TIM_Base_InitTypeDef:AutoReloadPreload
+     */
+    uint32_t autoReloadPreload{};
+
+    /**
+     * Timer clock source
+     * This parameter can be a value of @ref TIM_Clock_Source
+     * Maps to @ref TIM_ClockConfigTypeDef:ClockSource
+     */
+    uint32_t clockSource{};
+
+    /**
+     * Trigger output (TRGO) selection.
+     * This parameter can be a value of @ref TIM_Master_Mode_Selection
+     * Maps to @ref TIM_MasterConfigTypeDef:MasterOutputTrigger
+     */
+    uint32_t masterOutputTrigger{};
+
+    /**
+     * Master/slave mode selection.
+     * This parameter can be a value of @ref TIM_Master_Slave_Mode
+     * Maps to @ref TIM_MasterConfigTypeDef:MasterSlaveMode
+     */
+    uint32_t masterSlaveMode{};
+} TimerConfiguration_t;
+
 class Timer {
 public:
+    /**
+     * Virtual destructor required by C++.
+     */
+    virtual ~Timer() = default;
+
     /**
      * Starts the given timer and registers the given interrupt pointer to trigger when the timer overflows
      * @param[in] irqHandler The IRQ Handler function pointer.  Sets a new interrupt handler function
@@ -36,11 +90,14 @@ class Timer {
      * Set the clock period for the timer.  Will stop the timer, re-initialize the device with the updated period.
      * You must call startTimer again to continue timer operation.
      *
-     * @param[in] clockPeriod the clock period in ms.  An interrupt will be triggered at that frequency.
+     * @param[in] clockPeriod the clock period in ticks (ms when using AUTO_PRESCALER).  An interrupt will be triggered
+     * at that frequency.
+     * @param [in] clockPrescaler the prescaler used by the timer. Divides the system clock frequency to get it within
+     * an acceptable range for use with the required period. If set to @ref AUTO_PRESCALER, the function implementation
+     * will calculate its own prescaler.
      */
-    virtual void setPeriod(uint32_t clockPeriod) = 0;
+    virtual void setPeriod(uint32_t clockPeriod, uint32_t clockPrescaler = AUTO_PRESCALER) = 0;
 };
-
 } // namespace core::dev
 
 #endif // EVT_TIMER_HPP

include/core/dev/platform/f3xx/Timerf3xx.hpp

@@ -10,10 +10,20 @@
 namespace core::dev {
 
 /**
- * Implementation of the Timer class for STM32f3xx MCUs
+ * Concrete implementation of the Timer class for STM32f3xx MCUs.
  */
-class Timerf3xx : public Timer {
+class TimerF3xx : public Timer {
 public:
+    /**
+     * The default configuration for an F3 timer.
+     */
+    static constexpr TimerConfiguration_t defaultConfig = {TIM_COUNTERMODE_UP,
+                                                           TIM_CLOCKDIVISION_DIV1,
+                                                           TIM_AUTORELOAD_PRELOAD_ENABLE,
+                                                           TIM_CLOCKSOURCE_INTERNAL,
+                                                           TIM_TRGO_RESET,
+                                                           TIM_MASTERSLAVEMODE_DISABLE};
+
     /**
      * Will initialize the timer device on the STM with the given period and the given IRQ Handler
      * that triggers with the given period.  Starts the timer
@@ -22,34 +32,76 @@ class Timerf3xx : public Timer {
      * do not occur.
      *
      * @param[in] timerPeripheral The timer to use
-     * @param[in] clockPeriod the clock period in ms.  An interrupt will be triggered at that frequency.
+     * @param[in] clockPeriod the clock period in ticks (ms when using AUTO_PRESCALER). An interrupt will be triggered
+     * at this frequency.
+     * @param[in] configuration the configuration tells the timer how to configure itself. Defaults to @ref
+     * TimerF3xx::defaultConfig.
+     * @param[in] clockPrescaler the prescaler that the clock will use. If clockPrescaler is set to @ref AUTO_PRESCALER,
+     * this function will calculate its own prescaler value.
      */
-    explicit Timerf3xx(TIM_TypeDef* timerPeripheral, uint32_t clockPeriod);
+    explicit TimerF3xx(TIM_TypeDef* timerPeripheral, uint32_t clockPeriod,
+                       const TimerConfiguration_t& configuration = defaultConfig,
+                       uint32_t clockPrescaler                   = AUTO_PRESCALER);
 
+    /**
+     * Starts the given timer and registers the given interrupt pointer to trigger when the timer overflows
+     * @param[in] irqHandler The IRQ Handler function pointer.  Sets a new interrupt handler function
+     */
     void startTimer(void (*irqHandler)(void* htim)) override;
 
+    /**
+     * Starts the given timer using the IRQ Handler already assigned to that timer.
+     */
     void startTimer() override;
 
+    /**
+     * Stops the current timer from running.  Does not complete its current counting sequence.
+     */
     void stopTimer() override;
 
+    /**
+     * Resets the timer counter.
+     */
     void reloadTimer() override;
 
-    void setPeriod(uint32_t clockPeriod) override;
+    /**
+     * Set the clock period for the timer. Will stop the timer, re-initialize the device with the updated period.
+     * You must call startTimer again to continue timer operation.
+     *
+     * @param[in] clockPeriod the clock period in ticks (ms when using AUTO_PRESCALER). An interrupt will be triggered
+     * at that frequency.
+     * @param [in] clockPrescaler the prescaler used by the clock. Divides the system clock frequency to get it within
+     * an acceptable range for clocking. If set to @ref AUTO_PRESCALER, the function implementation should calculate its
+     * own prescaler.
+     */
+    void setPeriod(uint32_t clockPeriod, uint32_t clockPrescaler = AUTO_PRESCALER) override;
 
-private:
-    // Pointer to the halTimer struct stored in the global array in Timerf3xx.cpp
+protected:
+    /**
+     * Pointer to the halTimer struct stored in the global array in Timerf4xx.cpp
+     */
     TIM_HandleTypeDef* halTimer;
 
-    // Timer clock period
-    uint32_t clockPeriod;
+    /**
+     * Timer clock period
+     */
+    uint32_t clockPeriod{};
+
+    /**
+     * The configuration that this timer will use.
+     */
+    TimerConfiguration_t configuration;
 
     /**
      * Handles the initialization of the timer module.  Actually configures the device and enables it.
      * @param[in] timerPeripheral  The timer peripheral to configure.  Possible options for this board are
      * TIM2, TIM15, TIM16, TIM17.  It is up to the user to verify that resource conflicts do not occur.
-     * @param[in] clockPeriod the clock period in ms.  An interrupt will be triggered at that frequency.
+     * @param[in] clockPeriod the clock period in ticks (ms when using AUTO_PRESCALER).  An interrupt will be triggered
+     * at that frequency.
+     * @param[in] clockPrescaler the prescaler that the clock will use. If clockPrescaler is set to @ref AUTO_PRESCALER,
+     * this function will calculate its own prescaler value.
      */
-    void initTimer(TIM_TypeDef* timerPeripheral, uint32_t clockPeriod);
+    void initTimer(TIM_TypeDef* timerPeripheral, uint32_t clockPeriod, uint32_t clockPrescaler);
 };
 
 } // namespace core::dev