Function attach_timer_handler

src/platforms/avr/atmega/isr_avr_atmega.hpp:160–253

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

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

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

    // Check if timer is already in use
    if (g_avr_timer_data != nullptr) {
        FL_WARN("AVR ISR: Timer1 already in use (only one timer supported)");
        return -16;  // Timer already in use
    }

    // Allocate handle data
    auto handle_owner = fl::make_unique<avr_isr_handle_data>();
    auto* handle_data = handle_owner.get();
    if (!handle_data) {
        FL_WARN("AVR ISR: failed to allocate handle data");
        return -3;  // Out of memory
    }

    // Calculate timer configuration
    u8 prescaler_idx;
    u16 ocr_value;
    if (!calculate_timer_config(config.frequency_hz, prescaler_idx, ocr_value)) {
        FL_WARN("AVR ISR: frequency " << config.frequency_hz << " Hz out of range");
        return -2;  // Invalid frequency (out of range)
    }

    // Calculate actual achieved frequency
    u32 actual_freq = calculate_actual_frequency(prescaler_idx, ocr_value);

    // Warn if frequency error is >5%
    i32 freq_error = static_cast<i32>(actual_freq) - static_cast<i32>(config.frequency_hz);
    i32 error_pct = (freq_error * 100) / static_cast<i32>(config.frequency_hz);
    if (error_pct > 5 || error_pct < -5) {
        FL_WARN("AVR ISR: frequency error " << error_pct << "% (requested "
                << config.frequency_hz << " Hz, actual " << actual_freq << " Hz)");
    }

    FL_DBG("AVR ISR: Timer1 config: prescaler=" << PRESCALERS[prescaler_idx].value
           << ", OCR1A=" << ocr_value << ", actual_freq=" << actual_freq << " Hz");

    // Store configuration
    handle_data->mIsTimer = true;
    handle_data->mUserHandler = config.handler;
    handle_data->mUserData = config.user_data;
    handle_data->mFrequencyHz = actual_freq;
    handle_data->mPrescalerIndex = prescaler_idx;
    handle_data->mOcrValue = ocr_value;

    // Release ownership - pointer is now managed by the C API (g_avr_timer_data + out_handle)
    g_avr_timer_data = handle_data;
    handle_owner.release();