/**
 * @file pwm_driver.h
 * @brief PWM driver interface
 */

#ifndef PWM_DRIVER_H
#define PWM_DRIVER_H

#include <stdint.h>
#include <stdbool.h>
#include "kernel.h"

/* PWM Configuration Constants */
#define PWM_MAX_INSTANCES       8
#define PWM_MAX_CHANNELS        4
#define PWM_MAX_DUTY_CYCLE      10000  /* 100.00% in 0.01% steps */

/* PWM Alignment Modes */
typedef enum {
    PWM_ALIGNMENT_EDGE = 0,
    PWM_ALIGNMENT_CENTER = 1
} PwmAlignment_t;

/* PWM Polarity */
typedef enum {
    PWM_POLARITY_ACTIVE_HIGH = 0,
    PWM_POLARITY_ACTIVE_LOW = 1
} PwmPolarity_t;

/* PWM Modes */
typedef enum {
    PWM_MODE_NORMAL = 0,
    PWM_MODE_COMPLEMENTARY = 1,
    PWM_MODE_COMBINED = 2
} PwmMode_t;

/* PWM Dead Time */
typedef struct {
    uint16_t rising_edge_delay_ns;
    uint16_t falling_edge_delay_ns;
} PwmDeadTime_t;

/* PWM Fault Actions */
typedef enum {
    PWM_FAULT_DISABLE = 0,
    PWM_FAULT_ENABLE = 1,
    PWM_FAULT_HIGH_Z = 2
} PwmFaultAction_t;

/* PWM Callbacks */
typedef void (*PwmPeriodElapsedCallback_t)(uint8_t instance);
typedef void (*PwmFaultCallback_t)(uint8_t instance, uint32_t fault_flags);

/* PWM Channel Configuration */
typedef struct {
    uint8_t channel;
    uint32_t duty_cycle;  /* 0 to PWM_MAX_DUTY_CYCLE */
    PwmPolarity_t polarity;
    PwmMode_t mode;
    PwmDeadTime_t dead_time;
} PwmChannelConfig_t;

/* PWM Configuration */
typedef struct {
    uint32_t frequency_hz;
    PwmAlignment_t alignment;
    uint32_t period_ticks;
    uint8_t prescaler;
    PwmChannelConfig_t channels[PWM_MAX_CHANNELS];
    uint8_t channel_count;
    bool enable_fault_protection;
    PwmFaultAction_t fault_action;
    PwmPeriodElapsedCallback_t period_elapsed_callback;
    PwmFaultCallback_t fault_callback;
} PwmConfig_t;

/* PWM Statistics */
typedef struct {
    uint32_t period_elapsed_count;
    uint32_t fault_events;
    uint32_t duty_cycle_updates;
    uint32_t overcurrent_events;
    uint32_t overvoltage_events;
} PwmStatistics_t;

/* PWM Driver Interface */
KernelStatus_t pwm_init(uint8_t instance, PwmConfig_t* config);
KernelStatus_t pwm_deinit(uint8_t instance);
KernelStatus_t pwm_start(uint8_t instance);
KernelStatus_t pwm_stop(uint8_t instance);
KernelStatus_t pwm_set_duty_cycle(uint8_t instance, uint8_t channel, uint32_t duty_cycle);
KernelStatus_t pwm_set_frequency(uint8_t instance, uint32_t frequency_hz);
KernelStatus_t pwm_set_period(uint8_t instance, uint32_t period_ticks);
KernelStatus_t pwm_set_dead_time(uint8_t instance, uint8_t channel,
                                 const PwmDeadTime_t* dead_time);
KernelStatus_t pwm_enable_channel(uint8_t instance, uint8_t channel);
KernelStatus_t pwm_disable_channel(uint8_t instance, uint8_t channel);
KernelStatus_t pwm_configure_fault(uint8_t instance, PwmFaultAction_t action);
KernelStatus_t pwm_clear_fault(uint8_t instance);
KernelStatus_t pwm_get_statistics(uint8_t instance, PwmStatistics_t* stats);
uint32_t pwm_get_duty_cycle(uint8_t instance, uint8_t channel);
uint32_t pwm_get_frequency(uint8_t instance);
void pwm_process_interrupt(uint8_t instance);

#endif /* PWM_DRIVER_H */