Function attach_timer_handler

src/platforms/esp/32/isr_esp32_idf5.hpp:128–244

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

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

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

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

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

        // Create general purpose timer
        // For high frequencies (>1MHz), we need higher resolution to avoid rounding to 0
        // Choose resolution dynamically based on requested frequency
        //
        // IMPORTANT: ESP32 timer hardware requires clock divider >= 2
        // With 80MHz source clock, max resolution is 40MHz (80MHz / 2 = 40MHz)
        u32 timer_resolution_hz;
        u64 alarm_count;

        if (config.frequency_hz > 1000000) {
            // For frequencies > 1MHz, use higher resolution
            // Cap at 40MHz to ensure divider >= 2 (80MHz / 40MHz = 2)
            timer_resolution_hz = 40000000;
            alarm_count = timer_resolution_hz / config.frequency_hz;
        } else {
            // For lower frequencies, 1MHz resolution is sufficient
            timer_resolution_hz = 1000000;
            alarm_count = timer_resolution_hz / config.frequency_hz;
        }

        // Ensure alarm_count is at least 1 to avoid ESP_ERR_INVALID_ARG
        if (alarm_count == 0) {
            ESP_LOGW(ESP32_ISR_TAG, "attachTimerHandler: frequency too high (%lu Hz), maximum is %lu Hz",
                     (unsigned long)config.frequency_hz, (unsigned long)timer_resolution_hz);
            return -2;  // Invalid frequency
        }

        gptimer_config_t timer_config = {};
        timer_config.clk_src = GPTIMER_CLK_SRC_DEFAULT;
        timer_config.direction = GPTIMER_COUNT_UP;
        timer_config.resolution_hz = timer_resolution_hz;

        esp_err_t ret = gptimer_new_timer(&timer_config, &handle_data->timer_handle);
        if (ret != ESP_OK) {
            ESP_LOGW(ESP32_ISR_TAG, "attachTimerHandler: gptimer_new_timer failed: %s", esp_err_to_name(ret));