EspPwm.h

Go to the documentation of this file.

 
#pragma once
 
#include "BasePwm.h"
#include "PlatformMutex.h"
#include "utils/EspTypes_PWM.h"
#include <array>
#include <atomic>
#include <string>
 
#ifdef HF_MCU_FAMILY_ESP32
#include "driver/ledc.h" // For ESP-IDF LEDC callback types
#endif
 
class EspPwm : public BasePwm {
public:
  //==============================================================================
  // CONSTANTS
  //==============================================================================
 
  static constexpr hf_u8_t MAX_CHANNELS = HF_PWM_MAX_CHANNELS;     
  static constexpr hf_u8_t MAX_TIMERS = HF_PWM_MAX_TIMERS;         
  static constexpr hf_u8_t MAX_RESOLUTION = HF_PWM_MAX_RESOLUTION; 
  static constexpr hf_u32_t MIN_FREQUENCY = HF_PWM_MIN_FREQUENCY;  
  static constexpr hf_u32_t MAX_FREQUENCY = HF_PWM_MAX_FREQUENCY;  
 
  //==============================================================================
  // CONSTRUCTOR AND DESTRUCTOR
  //==============================================================================
 
  explicit EspPwm(const hf_pwm_unit_config_t& config = hf_pwm_unit_config_t{}) noexcept;
 
  virtual ~EspPwm() noexcept override;
 
  // Prevent copying and moving
  EspPwm(const EspPwm&) = delete;
  EspPwm& operator=(const EspPwm&) = delete;
  EspPwm(EspPwm&&) = delete;
  EspPwm& operator=(EspPwm&&) = delete;
 
  //==============================================================================
  // LIFECYCLE (BasePwm Interface)
  //==============================================================================
 
  hf_pwm_err_t Initialize() noexcept override;
 
  hf_pwm_err_t Deinitialize() noexcept override;
 
  hf_pwm_err_t SetMode(hf_pwm_mode_t mode) noexcept;
 
  hf_pwm_mode_t GetMode() const noexcept;
 
  //==============================================================================
  // CHANNEL MANAGEMENT (BasePwm Interface)
  //==============================================================================
 
  hf_pwm_err_t ConfigureChannel(hf_channel_id_t channel_id,
                                const hf_pwm_channel_config_t& config) noexcept;
 
  hf_pwm_err_t DeconfigureChannel(hf_channel_id_t channel_id) noexcept;
 
  hf_pwm_err_t EnableChannel(hf_channel_id_t channel_id) noexcept override;
 
  hf_pwm_err_t DisableChannel(hf_channel_id_t channel_id) noexcept override;
 
  bool IsChannelEnabled(hf_channel_id_t channel_id) const noexcept override;
 
  //==============================================================================
  // PWM CONTROL (BasePwm Interface)
  //==============================================================================
 
  hf_pwm_err_t SetDutyCycle(hf_channel_id_t channel_id, float duty_cycle) noexcept override;
 
  hf_pwm_err_t SetDutyCycleRaw(hf_channel_id_t channel_id, hf_u32_t raw_value) noexcept override;
 
  hf_pwm_err_t SetFrequency(hf_channel_id_t channel_id,
                            hf_frequency_hz_t frequency_hz) noexcept override;
 
  hf_pwm_err_t SetPhaseShift(hf_channel_id_t channel_id,
                             float phase_shift_degrees) noexcept override;
 
  //==============================================================================
  // USER-CONTROLLED FREQUENCY/RESOLUTION METHODS
  //==============================================================================
 
  hf_pwm_err_t SetFrequencyWithResolution(hf_channel_id_t channel_id,
                                          hf_frequency_hz_t frequency_hz,
                                          hf_u8_t resolution_bits) noexcept;
 
  hf_pwm_err_t SetFrequencyWithAutoFallback(hf_channel_id_t channel_id,
                                            hf_frequency_hz_t frequency_hz,
                                            hf_u8_t preferred_resolution) noexcept;
 
  hf_pwm_err_t SetResolution(hf_channel_id_t channel_id, hf_u8_t resolution_bits) noexcept;
 
  hf_u8_t GetResolution(hf_channel_id_t channel_id) const noexcept;
 
  hf_pwm_err_t SetFrequencyAndResolution(hf_channel_id_t channel_id, hf_frequency_hz_t frequency_hz,
                                         hf_u8_t resolution_bits) noexcept;
 
  hf_pwm_err_t EnableAutoFallback() noexcept;
 
  hf_pwm_err_t DisableAutoFallback() noexcept;
 
  bool IsAutoFallbackEnabled() const noexcept;
 
  //==============================================================================
  // ADVANCED FEATURES (BasePwm Interface)
  //==============================================================================
 
  hf_pwm_err_t StartAll() noexcept override;
 
  hf_pwm_err_t StopAll() noexcept override;
 
  hf_pwm_err_t UpdateAll() noexcept override;
 
  hf_pwm_err_t SetComplementaryOutput(hf_channel_id_t primary_channel,
                                      hf_channel_id_t complementary_channel,
                                      hf_u32_t deadtime_ns) noexcept override;
 
  //==============================================================================
  // STATUS AND INFORMATION (BasePwm Interface)
  //==============================================================================
 
  float GetDutyCycle(hf_channel_id_t channel_id) const noexcept override;
 
  hf_frequency_hz_t GetFrequency(hf_channel_id_t channel_id) const noexcept override;
 
  hf_pwm_err_t GetChannelStatus(hf_channel_id_t channel_id,
                                hf_pwm_channel_status_t& status) const noexcept;
 
  hf_pwm_err_t GetCapabilities(hf_pwm_capabilities_t& capabilities) const noexcept;
 
  hf_pwm_err_t GetLastError(hf_channel_id_t channel_id) const noexcept;
 
  //==============================================================================
  // CALLBACKS (BasePwm Interface)
  //==============================================================================
 
  hf_pwm_err_t SetChannelFadeCallback(hf_channel_id_t channel_id,
                                      void(*callback)(hf_channel_id_t)) noexcept;
 
  //==============================================================================
  // ESP32C6-SPECIFIC FEATURES
  //==============================================================================
 
  hf_pwm_err_t SetHardwareFade(hf_channel_id_t channel_id, float target_duty_cycle,
                               hf_u32_t fade_time_ms) noexcept;
 
  hf_pwm_err_t StopHardwareFade(hf_channel_id_t channel_id) noexcept;
 
  bool IsFadeActive(hf_channel_id_t channel_id) const noexcept;
 
  hf_pwm_err_t SetIdleLevel(hf_channel_id_t channel_id, hf_u8_t idle_level) noexcept;
 
  int8_t GetTimerAssignment(hf_channel_id_t channel_id) const noexcept;
 
  hf_pwm_err_t ForceTimerAssignment(hf_channel_id_t channel_id, hf_u8_t timer_id) noexcept;
 
  //==============================================================================
  // SAFE EVICTION POLICY MANAGEMENT
  //==============================================================================
 
  hf_pwm_err_t SetEvictionPolicy(hf_pwm_eviction_policy_t policy) noexcept;
 
  hf_pwm_eviction_policy_t GetEvictionPolicy() const noexcept;
 
  hf_pwm_err_t SetEvictionCallback(hf_pwm_eviction_callback_t callback,
                                   void* user_data = nullptr) noexcept;
 
  hf_pwm_err_t SetChannelPriority(hf_channel_id_t channel_id,
                                  hf_pwm_channel_priority_t priority) noexcept;
 
  hf_pwm_channel_priority_t GetChannelPriority(hf_channel_id_t channel_id) const noexcept;
 
  hf_pwm_err_t SetChannelCritical(hf_channel_id_t channel_id, bool is_critical) noexcept;
 
  [[nodiscard]] bool IsChannelCritical(hf_channel_id_t channel_id) const noexcept;
 
  hf_pwm_err_t GetStatistics(hf_pwm_statistics_t& statistics) const noexcept override;
 
  hf_pwm_err_t GetDiagnostics(hf_pwm_diagnostics_t& diagnostics) const noexcept override;
 
private:
  //==============================================================================
  // INTERNAL STRUCTURES
  //==============================================================================
 
  struct ChannelState {
    bool configured;                
    bool enabled;                   
    hf_pwm_channel_config_t config; 
    hf_u8_t assigned_timer;         
    hf_u32_t raw_duty_value;        
    hf_pwm_err_t last_error;        
    bool fade_active;               
    bool needs_reconfiguration;     
 
    // Channel protection and priority for safe eviction
    hf_pwm_channel_priority_t priority; 
    bool is_critical;                   
    const char* description;            
 
    // Per-channel fade callback support (ESP-IDF LEDC native support)
    void(*fade_callback)(hf_channel_id_t); 
 
    ChannelState() noexcept
        : configured(false), enabled(false), assigned_timer(0xFF), raw_duty_value(0),
          last_error(hf_pwm_err_t::PWM_SUCCESS), fade_active(false), needs_reconfiguration(false),
          priority(hf_pwm_channel_priority_t::PRIORITY_NORMAL), is_critical(false),
          description(nullptr), fade_callback(nullptr) {}
  };
 
  struct TimerState {
    bool in_use;                        
    hf_u32_t frequency_hz;              
    hf_u8_t resolution_bits;            
    hf_u8_t channel_count;              
    hf_pwm_clock_source_t clock_source; 
    bool has_hardware_conflicts;        
 
    TimerState() noexcept
        : in_use(false), frequency_hz(0), resolution_bits(0), channel_count(0),
          clock_source(hf_pwm_clock_source_t::HF_PWM_CLK_SRC_DEFAULT),
          has_hardware_conflicts(false) {}
  };
 
  struct ComplementaryPair {
    hf_u8_t primary_channel;       
    hf_u8_t complementary_channel; 
    hf_u32_t deadtime_ns;          
    bool active;                   
 
    ComplementaryPair() noexcept
        : primary_channel(0xFF), complementary_channel(0xFF), deadtime_ns(0), active(false) {}
  };
 
  //==============================================================================
  // INTERNAL METHODS
  //==============================================================================
 
  bool IsValidChannelId(hf_channel_id_t channel_id) const noexcept;
 
  hf_i8_t FindOrAllocateTimer(hf_u32_t frequency_hz, hf_u8_t resolution_bits,
                              hf_pwm_clock_source_t clock_source) noexcept;
 
  void ReleaseTimerIfUnused(hf_u8_t timer_id) noexcept;
 
  hf_pwm_err_t ConfigurePlatformTimer(hf_u8_t timer_id, hf_u32_t frequency_hz,
                                      hf_u8_t resolution_bits,
                                      hf_pwm_clock_source_t clock_source) noexcept;
 
  hf_pwm_err_t ConfigurePlatformChannel(hf_channel_id_t channel_id,
                                        const hf_pwm_channel_config_t& config,
                                        hf_u8_t timer_id) noexcept;
 
  hf_pwm_err_t UpdatePlatformDuty(hf_channel_id_t channel_id, hf_u32_t raw_duty_value) noexcept;
 
  void SetChannelError(hf_channel_id_t channel_id, hf_pwm_err_t error) noexcept;
 
  static void IRAM_ATTR InterruptHandler(hf_channel_id_t channel_id, void* user_data) noexcept;
 
  void HandleFadeComplete(hf_channel_id_t channel_id) noexcept;
 
  hf_pwm_err_t RegisterLedcFadeCallback(hf_channel_id_t channel_id) noexcept;
 
  hf_pwm_err_t UnregisterLedcFadeCallback(hf_channel_id_t channel_id) noexcept;
 
  static bool IRAM_ATTR LedcFadeEndCallback(const ledc_cb_param_t* param, void* user_arg) noexcept;
 
  hf_pwm_err_t InitializeFadeFunctionality() noexcept;
 
  hf_pwm_err_t InitializeTimers() noexcept;
 
  hf_pwm_err_t InitializeChannels() noexcept;
 
  hf_pwm_err_t EnableFade() noexcept;
 
  [[nodiscard]] hf_u32_t CalculateClockDivider(hf_u32_t frequency_hz,
                                               hf_u8_t resolution_bits) const noexcept;
 
  //==============================================================================
  // ENHANCED VALIDATION SYSTEM
  //==============================================================================
 
  struct ValidationContext {
    hf_u32_t frequency_hz;              
    hf_u8_t resolution_bits;            
    hf_pwm_clock_source_t clock_source; 
    hf_i8_t timer_id;                   
 
    ValidationContext(hf_u32_t freq, hf_u8_t res,
                      hf_pwm_clock_source_t clk = hf_pwm_clock_source_t::HF_PWM_CLK_SRC_APB,
                      hf_i8_t timer = -1) noexcept
        : frequency_hz(freq), resolution_bits(res), clock_source(clk), timer_id(timer) {}
  };
 
  struct ValidationResult {
    bool is_valid;                     
    hf_pwm_err_t error_code;           
    const char* reason;                
    hf_u8_t max_achievable_resolution; 
    hf_u32_t max_achievable_frequency; 
    uint64_t required_clock_hz;        
    uint64_t available_clock_hz;       
 
    ValidationResult() noexcept
        : is_valid(false), error_code(hf_pwm_err_t::PWM_ERR_INVALID_PARAMETER),
          reason("Unknown error"), max_achievable_resolution(0), max_achievable_frequency(0),
          required_clock_hz(0), available_clock_hz(0) {}
  };
 
  [[nodiscard]] ValidationResult ValidateFrequencyResolutionComplete(
      const ValidationContext& context) const noexcept;
 
  [[nodiscard]] hf_u32_t GetSourceClockFrequency(hf_pwm_clock_source_t clock_source) const noexcept;
 
  [[nodiscard]] hf_u8_t CalculateMaxResolution(
      hf_u32_t frequency_hz, hf_pwm_clock_source_t clock_source =
                                 hf_pwm_clock_source_t::HF_PWM_CLK_SRC_APB) const noexcept;
 
  [[nodiscard]] hf_u32_t CalculateMaxFrequency(
      hf_u8_t resolution_bits, hf_pwm_clock_source_t clock_source =
                                   hf_pwm_clock_source_t::HF_PWM_CLK_SRC_APB) const noexcept;
 
  [[nodiscard]] bool ValidateDutyCycleRange(hf_u32_t raw_duty,
                                            hf_u8_t resolution_bits) const noexcept;
 
  [[nodiscard]] bool IsClockSourceCompatible(hf_pwm_clock_source_t timer_clock,
                                             hf_pwm_clock_source_t requested_clock) const noexcept;
 
  [[nodiscard]] hf_u8_t FindBestAlternativeResolutionDynamic(
      hf_u32_t frequency_hz, hf_u8_t preferred_resolution,
      hf_pwm_clock_source_t clock_source =
          hf_pwm_clock_source_t::HF_PWM_CLK_SRC_APB) const noexcept;
 
  void NotifyTimerReconfiguration(hf_u8_t timer_id, hf_u32_t new_frequency,
                                  hf_u8_t resolution_bits) noexcept;
 
  std::string GetTimerUsageInfo(hf_u8_t timer_id) const noexcept;
 
  hf_u8_t PerformTimerHealthCheck() noexcept;
 
  hf_i8_t AttemptSafeEviction(hf_u32_t frequency_hz, hf_u8_t resolution_bits) noexcept;
 
  hf_i8_t AttemptEvictionWithConsent(hf_u32_t frequency_hz, hf_u8_t resolution_bits) noexcept;
 
  hf_i8_t AttemptEvictionNonCritical(hf_u32_t frequency_hz, hf_u8_t resolution_bits) noexcept;
 
  hf_i8_t AttemptForceEviction(hf_u32_t frequency_hz, hf_u8_t resolution_bits) noexcept;
 
  //==============================================================================
  // MEMBER VARIABLES
  //==============================================================================
 
  mutable PlatformMutex mutex_;            
  std::atomic<bool> initialized_;      
  hf_u32_t base_clock_hz_;             
  hf_pwm_clock_source_t clock_source_; 
 
  std::array<ChannelState, MAX_CHANNELS> channels_;                     
  std::array<TimerState, MAX_TIMERS> timers_;                           
  std::array<ComplementaryPair, MAX_CHANNELS / 2> complementary_pairs_; 
 
  hf_pwm_err_t last_global_error_;    
  bool fade_functionality_installed_; 
 
  // New member variables for enhanced functionality
  hf_pwm_unit_config_t unit_config_; 
  hf_pwm_mode_t current_mode_;       
  hf_pwm_statistics_t statistics_;   
  hf_pwm_diagnostics_t diagnostics_; 
  bool auto_fallback_enabled_;       
 
  // Safe eviction policy management
  hf_pwm_eviction_policy_t
      eviction_policy_; 
  hf_pwm_eviction_callback_t eviction_callback_; 
  void* eviction_callback_user_data_;            
};