Function attach_timer_handler

src/platforms/esp/32/isr_esp32_idf4.hpp:166–310

// =============================================================================

inline int attach_timer_handler(const isr_config_t& config, isr_handle_t* out_handle) FL_NOEXCEPT {
    if (!config.handler) {
        ESP_LOGW(ESP32_IDF4_ISR_TAG, "attachTimerHandler: handler is null");
        return -1;  // Invalid parameter
    }

    if (config.frequency_hz == 0) {
        ESP_LOGW(ESP32_IDF4_ISR_TAG, "attachTimerHandler: frequency_hz is 0");
        return -2;  // Invalid frequency
    }

    // Allocate handle data
    auto handle_owner = fl::make_unique<esp32_idf4_isr_handle_data>();
    auto* handle_data = handle_owner.get();
    if (!handle_data) {
        ESP_LOGW(ESP32_IDF4_ISR_TAG, "attachTimerHandler: failed to allocate handle data");
        return -3;  // Out of memory
    }

    // Allocate a timer
    if (!allocate_timer(&handle_data->timer_group, &handle_data->timer_idx)) {
        ESP_LOGW(ESP32_IDF4_ISR_TAG, "attachTimerHandler: no free timers available");
        return -4;  // No timers available
    }

    handle_data->is_timer = true;
    handle_data->user_handler = config.handler;
    handle_data->user_data = config.user_data;

    // Calculate timer divider and alarm value
    // ESP32 APB clock is typically 80MHz
    // Timer clock = APB_CLK / divider
    // We want: alarm_value = timer_clock / frequency_hz
    //
    // For flexibility, use a divider that gives good resolution
    // Divider range: 2 to 65536
    // Using divider=80 gives 1MHz timer clock (1us resolution)
    // Using divider=8 gives 10MHz timer clock (0.1us resolution)

    u16 divider;
    u64 alarm_value;

    if (config.frequency_hz > 1000000) {
        // For high frequencies, use smaller divider for better resolution
        divider = 8;  // 10MHz timer clock
        u32 timer_clock = 80000000 / divider;  // 10MHz
        alarm_value = timer_clock / config.frequency_hz;
    } else {
        // For lower frequencies, use divider=80 for 1MHz (1us resolution)
        divider = 80;  // 1MHz timer clock
        u32 timer_clock = 80000000 / divider;  // 1MHz
        alarm_value = timer_clock / config.frequency_hz;
    }

    // Ensure alarm_value is at least 1
    if (alarm_value == 0) {
        ESP_LOGW(ESP32_IDF4_ISR_TAG, "attachTimerHandler: frequency too high (%lu Hz)",
                 (unsigned long)config.frequency_hz);