Function attach_timer_handler

src/platforms/arm/rp/isr_rp2040.hpp:226–305

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

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

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

    // Check frequency bounds (practical limits for RP2040)
    if (config.frequency_hz > 1000000) {
        FL_WARN("attachTimerHandler: frequency " << config.frequency_hz << " Hz exceeds 1 MHz limit");
        return -2;  // Invalid frequency
    }

    // Allocate a hardware alarm
    i8 alarm_num = allocate_alarm();
    if (alarm_num < 0) {
        FL_WARN("attachTimerHandler: no free hardware alarms (max 4)");
        return -3;  // Out of resources
    }

    // Allocate handle data
    auto handle_owner = fl::make_unique<rp2040_isr_handle_data>();
    auto* handle_data = handle_owner.get();
    if (!handle_data) {
        free_alarm(alarm_num);
        FL_WARN("attachTimerHandler: failed to allocate handle data");
        return -5;  // Out of memory
    }

    handle_data->is_timer = true;
    handle_data->alarm_num = alarm_num;
    handle_data->frequency_hz = config.frequency_hz;
    handle_data->user_handler = config.handler;
    handle_data->user_data = config.user_data;
    handle_data->core_num = get_core_num();

    // Store handle for ISR access
    alarm_handles[alarm_num] = handle_data;

    // Calculate interval in microseconds
    i64 interval_us = 1000000 / config.frequency_hz;

    // Add repeating timer using Pico SDK
    handle_data->alarm_id = add_alarm_in_us(interval_us, alarm_callback_wrapper,
                                             handle_data, true);

    if (handle_data->alarm_id == 0 || handle_data->alarm_id == -1) {
        // Alarm creation failed
        free_alarm(alarm_num);
        alarm_handles[alarm_num] = nullptr;
        FL_WARN("attachTimerHandler: add_alarm_in_us failed");
        return -4;  // Internal error
    }