rust-embedded/rust-raspberrypi-OS-tutorials · critical

Error during driver interrupt handler registration: {}: {}

Error message

Error during driver interrupt handler registration: {}: {}

What it means

In the IRQ phase of init_drivers_and_irqs, every descriptor carrying an irq_number gets register_and_enable_irq_handler called on its driver; if that returns Err the manager panics with the driver's compatible name and the error string. This is the final step of wiring a driver's interrupt into the system, so failure is fatal.

Source

Thrown at 20_timer_callbacks/kernel/src/driver.rs:159

                    if let Err(x) = callback() {
                        panic!(
                            "Error during driver post-init callback: {}: {}",
                            descriptor.device_driver.compatible(),
                            x
                        );
                    }
                }
            }

            // 3. After all post-init callbacks were done, the interrupt controller should be
            //    registered and functional. So let drivers register with it now.
            for descriptor in descriptors {
                if let Some(irq_number) = &descriptor.irq_number {
                    if let Err(x) = descriptor
                        .device_driver
                        .register_and_enable_irq_handler(irq_number)
                    {
                        panic!(
                            "Error during driver interrupt handler registration: {}: {}",
                            descriptor.device_driver.compatible(),
                            x
                        );
                    }
                }
            }
        })
    }

    /// Enumerate all registered device drivers.
    pub fn enumerate(&self) {
        self.descriptors.read(|descriptors| {
            for (i, desc) in descriptors.iter().enumerate() {
                info!("      {}. {}", i + 1, desc.device_driver.compatible());
            }
        });
    }

View on GitHub (pinned to 644474cc09)

Solutions

  1. Check the panic message for the compatible name and error to find the failing driver and reason.
  2. Verify the irq_number on the descriptor matches the hardware's interrupt line for that device.
  3. Ensure the real IRQ manager is registered before init_drivers_and_irqs runs (otherwise the null manager or error paths trigger).
  4. Confirm the driver's register_and_enable_irq_handler implementation returns Ok on success and only errors on genuine failures.

Example fix

// before
let desc = DeviceDriverDescriptor::new(driver, Some(post_init))
    .with_irq_number(IRQNumber::new(99)); // wrong line for this device

// after
let desc = DeviceDriverDescriptor::new(driver, Some(post_init))
    .with_irq_number(IRQNumber::new(1)); // correct IRQ line
Defensive patterns

Strategy: validation

Validate before calling

// cross-check IRQ numbers against a board table before bring-up:
let expected = board_irq_for(driver.compatible());
assert_eq!(descriptor.irq_number.map(|n| n.get()), expected, "IRQ number mismatch for {}", driver.compatible());

Try / catch

// make registration failures non-fatal when appropriate:
if let Err(x) = descriptor.device_driver.register_and_enable_irq_handler(irq_number) {
    log_warn("IRQ registration failed for {}: {}", descriptor.device_driver.compatible(), x);
}

Prevention

When it happens

Trigger: A descriptor has Some(irq_number) and its device_driver's register_and_enable_irq_handler returns Err — e.g. the underlying IRQ manager registration or the handler registration fails, or the default panicking trait stub returns via a driver that reports errors.

Common situations: The IRQ number in the descriptor does not match what the driver/IRQ manager expects; the driver's handler registration returns Err because the IRQ manager is not registered or the line is already claimed; copy-pasted descriptor gives one driver another driver's IRQ number.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of rust-embedded/rust-raspberrypi-OS-tutorials@644474cc09 (2026-09-06). Data as JSON: /api/errors/0f2bf0f244265cae. Report an issue: GitHub.