BasePeriodicTimer.h

Go to the documentation of this file.

 
#pragma once
 
#include "HardwareTypes.h"
#include <cstdint>
#include <string_view>
 
#ifndef HF_TIMESTAMP_US_T_DEFINED
#define HF_TIMESTAMP_US_T_DEFINED
using hf_timestamp_us_t = hf_u64_t;
#endif
 
//--------------------------------------
//  HardFOC Timer Error Codes (Table)
//--------------------------------------
#define HF_TIMER_ERR_LIST(X)                                                                       \
  /* Success codes */                                                                              \
  X(TIMER_SUCCESS, 0, "Success")                                                                   \
  /* General errors */                                                                             \
  X(TIMER_ERR_FAILURE, 1, "General failure")                                                       \
  X(TIMER_ERR_NOT_INITIALIZED, 2, "Not initialized")                                               \
  X(TIMER_ERR_ALREADY_INITIALIZED, 3, "Already initialized")                                       \
  X(TIMER_ERR_INVALID_PARAMETER, 4, "Invalid parameter")                                           \
  X(TIMER_ERR_NULL_POINTER, 5, "Null pointer")                                                     \
  X(TIMER_ERR_OUT_OF_MEMORY, 6, "Out of memory")                                                   \
  /* Timer specific errors */                                                                      \
  X(TIMER_ERR_ALREADY_RUNNING, 7, "Timer already running")                                         \
  X(TIMER_ERR_NOT_RUNNING, 8, "Timer not running")                                                 \
  X(TIMER_ERR_INVALID_PERIOD, 9, "Invalid period")                                                 \
  X(TIMER_ERR_RESOURCE_BUSY, 10, "Timer resource busy")                                            \
  X(TIMER_ERR_HARDWARE_FAULT, 11, "Timer hardware fault")                                          \
  X(TIMER_ERR_UNSUPPORTED_OPERATION, 12, "Unsupported operation")                                  \
  X(TIMER_ERR_UNKNOWN, 13, "Unknown error")
 
// Generate enum class from X-macro
enum class hf_timer_err_t : hf_i32_t {
#define X(name, value, desc) name = value,
  HF_TIMER_ERR_LIST(X)
#undef X
};
 
constexpr std::string_view HfTimerErrToString(hf_timer_err_t err) noexcept {
  switch (err) {
#define X(NAME, VALUE, DESC)                                                                       \
  case hf_timer_err_t::NAME:                                                                       \
    return DESC;
    HF_TIMER_ERR_LIST(X)
#undef X
  default:
    return HfTimerErrToString(hf_timer_err_t::TIMER_ERR_UNKNOWN);
  }
}
 
struct hf_timer_stats_t {
  hf_u64_t start_count;
  hf_u64_t stop_count;
  hf_u64_t callback_count;
  hf_u64_t missed_callbacks;
  hf_timer_err_t last_error;
  hf_timestamp_us_t last_start_us;
 
  hf_timer_stats_t() noexcept
      : start_count(0), stop_count(0), callback_count(0), missed_callbacks(0),
        last_error(hf_timer_err_t::TIMER_SUCCESS), last_start_us(0) {}
};
 
struct hf_timer_statistics_t {
  hf_u32_t totalStarts;           
  hf_u32_t totalStops;            
  hf_u32_t callbackExecutions;    
  hf_u32_t missedCallbacks;       
  hf_u32_t averageCallbackTimeUs; 
  hf_u32_t maxCallbackTimeUs;     
  hf_u32_t minCallbackTimeUs;     
  hf_u64_t totalRunningTimeUs;    
 
  hf_timer_statistics_t()
      : totalStarts(0), totalStops(0), callbackExecutions(0), missedCallbacks(0),
        averageCallbackTimeUs(0), maxCallbackTimeUs(0), minCallbackTimeUs(UINT32_MAX),
        totalRunningTimeUs(0) {}
};
 
struct hf_timer_diagnostics_t {
  bool timerHealthy;            
  hf_timer_err_t lastErrorCode; 
  hf_u32_t lastErrorTimestamp;  
  hf_u32_t consecutiveErrors;   
  bool timerInitialized;        
  bool timerRunning;            
  hf_u64_t currentPeriodUs;     
  hf_u64_t timerResolutionUs;   
 
  hf_timer_diagnostics_t()
      : timerHealthy(true), lastErrorCode(hf_timer_err_t::TIMER_SUCCESS), lastErrorTimestamp(0),
        consecutiveErrors(0), timerInitialized(false), timerRunning(false), currentPeriodUs(0),
        timerResolutionUs(0) {}
};
 
using hf_timer_callback_t = void (*)(void* user_data);
 
class BasePeriodicTimer {
public:
  virtual ~BasePeriodicTimer() noexcept = default;
 
  // Disable copy constructor and assignment operator for safety
  BasePeriodicTimer(const BasePeriodicTimer&) = delete;
  BasePeriodicTimer& operator=(const BasePeriodicTimer&) = delete;
 
  //==============================================//
  // PURE VIRTUAL FUNCTIONS (MUST BE IMPLEMENTED) //
  //==============================================//
 
  virtual hf_timer_err_t Initialize() noexcept = 0;
 
  virtual hf_timer_err_t Deinitialize() noexcept = 0;
 
  virtual hf_timer_err_t Start(hf_u64_t period_us) noexcept = 0;
 
  virtual hf_timer_err_t Stop() noexcept = 0;
 
  virtual hf_timer_err_t SetPeriod(hf_u64_t period_us) noexcept = 0;
 
  virtual hf_timer_err_t GetPeriod(hf_u64_t& period_us) noexcept = 0;
 
  virtual hf_timer_err_t GetStats(hf_u64_t& callback_count, hf_u64_t& missed_callbacks,
                                  hf_timer_err_t& last_error) noexcept = 0;
 
  virtual hf_timer_err_t ResetStats() noexcept = 0;
 
  //==============================================//
  // PUBLIC INTERFACE (IMPLEMENTED)               //
  //==============================================//
 
  bool IsInitialized() const noexcept {
    return initialized_;
  }
 
  bool IsRunning() const noexcept {
    return running_;
  }
 
  virtual const char* GetDescription() const noexcept = 0;
 
  virtual hf_u64_t GetMaxPeriod() const noexcept = 0;
 
  virtual hf_u64_t GetMinPeriod() const noexcept = 0;
 
  virtual hf_u64_t GetResolution() const noexcept = 0;
 
  hf_timer_err_t SetCallback(hf_timer_callback_t callback, void* user_data = nullptr) noexcept {
    if (IsRunning()) {
      return hf_timer_err_t::TIMER_ERR_ALREADY_RUNNING;
    }
    callback_ = callback;
    user_data_ = user_data;
    return hf_timer_err_t::TIMER_SUCCESS;
  }
 
  void* GetUserData() const noexcept {
    return user_data_;
  }
 
  //==============================================//
  // STATISTICS AND DIAGNOSTICS
  //==============================================//
 
  virtual hf_timer_err_t ResetStatistics() noexcept {
    statistics_ = hf_timer_statistics_t{}; // Reset statistics to default values
    return hf_timer_err_t::TIMER_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_timer_err_t ResetDiagnostics() noexcept {
    diagnostics_ = hf_timer_diagnostics_t{}; // Reset diagnostics to default values
    return hf_timer_err_t::TIMER_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_timer_err_t GetStatistics(hf_timer_statistics_t& statistics) const noexcept {
    statistics = statistics_; // Return statistics by default
    return hf_timer_err_t::TIMER_ERR_UNSUPPORTED_OPERATION;
  }
 
  virtual hf_timer_err_t GetDiagnostics(hf_timer_diagnostics_t& diagnostics) const noexcept {
    diagnostics = diagnostics_; // Return diagnostics by default
    return hf_timer_err_t::TIMER_ERR_UNSUPPORTED_OPERATION;
  }
 
protected:
  explicit BasePeriodicTimer(hf_timer_callback_t callback, void* user_data = nullptr) noexcept
      : callback_(callback), user_data_(user_data), initialized_(false), running_(false),
        statistics_{}, diagnostics_{} {}
 
  void SetInitialized(bool initialized) noexcept {
    initialized_ = initialized;
  }
 
  void SetRunning(bool running) noexcept {
    running_ = running;
  }
 
  void ExecuteCallback() noexcept {
    if (callback_) {
      callback_(user_data_);
    }
  }
 
  bool HasValidCallback() const noexcept {
    return static_cast<bool>(callback_);
  }
 
  hf_timer_callback_t callback_;       
  void* user_data_;                    
  bool initialized_;                   
  bool running_;                       
  hf_timer_statistics_t statistics_;   
  hf_timer_diagnostics_t diagnostics_; 
};