linux/rust/kernel/irq/request.rs

// SPDX-License-Identifier: GPL-2.0
// SPDX-FileCopyrightText: Copyright 2025 Collabora ltd.

//! This module provides types like [`Registration`] and
//! [`ThreadedRegistration`], which allow users to register handlers for a given
//! IRQ line.

use core::marker::{
    PhantomData,
    PhantomPinned, //
};

use crate::{
    device::{
        Bound,
        Device, //
    },
    error::to_result,
    irq::flags::Flags,
    prelude::*,
    str::CStr,
};

/// The value that can be returned from a [`Handler`] or a [`ThreadedHandler`].
#[repr(u32)]
pub enum IrqReturn {
    /// The interrupt was not from this device or was not handled.
    None = bindings::irqreturn_IRQ_NONE,

    /// The interrupt was handled by this device.
    Handled = bindings::irqreturn_IRQ_HANDLED,
}

/// Callbacks for an IRQ handler.
pub trait Handler: Sync {
    /// The hard IRQ handler.
    ///
    /// This is executed in interrupt context, hence all corresponding
    /// limitations do apply.
    ///
    /// All work that does not necessarily need to be executed from
    /// interrupt context, should be deferred to a threaded handler.
    /// See also [`ThreadedRegistration`].
    fn handle(&self) -> IrqReturn;
}

/// A request for an IRQ line for a given device.
///
/// # Invariants
///
/// - `ìrq` is the number of an interrupt source of `dev`.
/// - `irq` has not been registered yet; this is consumed by [`Registration::new()`].
pub struct IrqRequest<'a> {
    irq: u32,
    /// Proves the device is bound at registration time and ties `'a` to the device's bound
    /// lifetime, ensuring the [`Registration`] cannot outlive it.
    _dev: PhantomData<&'a Device<Bound>>,
}

impl<'a> IrqRequest<'a> {
    /// Creates a new IRQ request for the given device and IRQ number.
    ///
    /// # Safety
    ///
    /// - `irq` should be a valid IRQ number for `dev`.
    pub(crate) unsafe fn new(_dev: &'a Device<Bound>, irq: u32) -> Self {
        // INVARIANT: `irq` is a valid IRQ number for `dev`.
        IrqRequest {
            irq,
            _dev: PhantomData,
        }
    }

    /// Returns the IRQ number of an [`IrqRequest`].
    #[inline]
    pub fn irq(&self) -> u32 {
        self.irq
    }
}

/// A registration of an IRQ handler for a given IRQ line.
///
/// # Examples
///
/// The following is an example of using `Registration`. It uses a
/// [`Completion`] to coordinate between the IRQ
/// handler and process context. [`Completion`] uses interior mutability, so the
/// handler can signal with [`Completion::complete_all()`] and the process
/// context can wait with [`Completion::wait_for_completion()`] even though
/// there is no way to get a mutable reference to the any of the fields in
/// `Data`.
///
/// [`Completion`]: kernel::sync::Completion
/// [`Completion::complete_all()`]: kernel::sync::Completion::complete_all
/// [`Completion::wait_for_completion()`]: kernel::sync::Completion::wait_for_completion
///
/// ```
/// use core::pin::Pin;
/// use kernel::{
///     irq::{
///         self,
///         Flags,
///         IrqRequest,
///         IrqReturn,
///         Registration,
///     },
///     prelude::*,
///     sync::Completion,
/// };
///
/// // Data shared between process and IRQ context.
/// #[pin_data]
/// struct Data {
///     #[pin]
///     completion: Completion,
/// }
///
/// impl irq::Handler for Data {
///     // Executed in IRQ context.
///     fn handle(&self) -> IrqReturn {
///         self.completion.complete_all();
///         IrqReturn::Handled
///     }
/// }
///
/// // Registers an IRQ handler for the given IrqRequest.
/// //
/// // This runs in process context and assumes `request` was previously acquired from a device.
/// fn register_irq(
///     request: IrqRequest<'_>,
/// ) -> Result<Pin<KBox<Registration<'_, Data>>>> {
///     // SAFETY: The returned Registration is not leaked.
///     let registration = unsafe {
///         Registration::new(
///             request,
///             Flags::SHARED,
///             c"my_device",
///             try_pin_init!(Data {
///                 completion <- Completion::new(),
///             }? Error),
///         )
///     };
///
///     let registration = KBox::pin_init(registration, GFP_KERNEL)?;
///
///     registration.handler().completion.wait_for_completion();
///
///     Ok(registration)
/// }
/// # Ok::<(), Error>(())
/// ```
///
/// # Invariants
///
/// * We own an irq handler registered via `request_irq` whose cookie is a pointer to `Self`.
#[pin_data(PinnedDrop)]
pub struct Registration<'a, T: Handler> {
    request: IrqRequest<'a>,

    #[pin]
    handler: T,

    /// Pinned because we need address stability so that we can pass a pointer
    /// to the callback.
    #[pin]
    _pin: PhantomPinned,
}

impl<'a, T: Handler> Registration<'a, T> {
    /// Registers the IRQ handler with the system for the given IRQ number.
    ///
    /// # Safety
    ///
    /// Callers must not `mem::forget()` the returned [`Registration`] or otherwise prevent its
    /// [`Drop`] implementation from running.
    pub unsafe fn new(
        request: IrqRequest<'a>,
        flags: Flags,
        name: &'static CStr,
        handler: impl PinInit<T, Error> + 'a,
    ) -> impl PinInit<Self, Error> + 'a
    where
        T: 'a,
    {
        // INVARIANT: If initialization completes successfully, we own an IRQ handler registered
        // via `request_irq` whose cookie is a pointer to `Self`.
        try_pin_init!(&this in Self {
            handler <- handler,
            request,
            _pin: PhantomPinned,
            _: {
                // SAFETY:
                // - The callbacks are valid for use with request_irq.
                // - If this succeeds, the slot is guaranteed to be valid until the destructor of
                //   Self runs, which will deregister the callbacks before the memory location
                //   becomes invalid.
                // - All fields are already initialized, so it's safe for the callback to be
                //   called immediately.
                to_result(unsafe {
                    bindings::request_irq(
                        request.irq,
                        Some(handle_irq_callback::<T>),
                        flags.into_inner(),
                        name.as_char_ptr(),
                        this.as_ptr().cast::<c_void>(),
                    )
                })?;
            },
        })
    }

    /// Returns a reference to the handler that was registered with the system.
    pub fn handler(&self) -> &T {
        &self.handler
    }

    /// Wait for pending IRQ handlers on other CPUs.
    #[inline]
    pub fn synchronize(&self) {
        // SAFETY: `self.request.irq` is a valid registered IRQ number (type invariant).
        unsafe { bindings::synchronize_irq(self.request.irq) };
    }
}

#[pinned_drop]
impl<T: Handler> PinnedDrop for Registration<'_, T> {
    fn drop(self: Pin<&mut Self>) {
        // SAFETY: The cookie was set to a pointer to `Self` in `Registration::new()`. This blocks
        // until all in-flight handlers complete, so no references to `self` remain after this
        // returns.
        unsafe {
            bindings::free_irq(
                self.request.irq,
                core::ptr::from_mut::<Self>(self.get_unchecked_mut()).cast::<c_void>(),
            )
        };
    }
}

/// # Safety
///
/// This function should be only used as the callback in `request_irq`.
unsafe extern "C" fn handle_irq_callback<T: Handler>(_irq: i32, ptr: *mut c_void) -> c_uint {
    let ptr = ptr.cast_const().cast::<Registration<'_, T>>();
    // SAFETY: `ptr` is a pointer to `Registration<'_, T>` set in `Registration::new()`.
    let registration = unsafe { &*ptr };

    T::handle(&registration.handler) as c_uint
}

/// The value that can be returned from [`ThreadedHandler::handle`].
#[repr(u32)]
pub enum ThreadedIrqReturn {
    /// The interrupt was not from this device or was not handled.
    None = bindings::irqreturn_IRQ_NONE,

    /// The interrupt was handled by this device.
    Handled = bindings::irqreturn_IRQ_HANDLED,

    /// The handler wants the handler thread to wake up.
    WakeThread = bindings::irqreturn_IRQ_WAKE_THREAD,
}

/// Callbacks for a threaded IRQ handler.
pub trait ThreadedHandler: Sync {
    /// The hard IRQ handler.
    ///
    /// This is executed in interrupt context, hence all corresponding
    /// limitations do apply. All work that does not necessarily need to be
    /// executed from interrupt context, should be deferred to the threaded
    /// handler, i.e. [`ThreadedHandler::handle_threaded`].
    ///
    /// The default implementation returns [`ThreadedIrqReturn::WakeThread`].
    fn handle(&self) -> ThreadedIrqReturn {
        ThreadedIrqReturn::WakeThread
    }

    /// The threaded IRQ handler.
    ///
    /// This is executed in process context. The kernel creates a dedicated
    /// `kthread` for this purpose.
    fn handle_threaded(&self) -> IrqReturn;
}

/// A registration of a threaded IRQ handler for a given IRQ line.
///
/// Two callbacks are required: one to handle the IRQ, and one to handle any
/// other work in a separate thread.
///
/// The thread handler is only called if the IRQ handler returns
/// [`ThreadedIrqReturn::WakeThread`].
///
/// # Examples
///
/// The following is an example of using [`ThreadedRegistration`]. It uses a
/// [`Mutex`](kernel::sync::Mutex) to provide interior mutability.
///
/// ```
/// use core::pin::Pin;
/// use kernel::{
///     irq::{
///         self,
///         Flags,
///         IrqRequest,
///         IrqReturn,
///         ThreadedHandler,
///         ThreadedIrqReturn,
///         ThreadedRegistration,
///     },
///     prelude::*,
///     sync::Mutex,
/// };
///
/// // Declare a struct that will be passed in when the interrupt fires. The u32
/// // merely serves as an example of some internal data.
/// //
/// // [`irq::ThreadedHandler::handle`] takes `&self`. This example
/// // illustrates how interior mutability can be used when sharing the data
/// // between process context and IRQ context.
/// #[pin_data]
/// struct Data {
///     #[pin]
///     value: Mutex<u32>,
/// }
///
/// impl ThreadedHandler for Data {
///     // This will run (in a separate kthread) if and only if
///     // [`ThreadedHandler::handle`] returns [`WakeThread`], which it does by
///     // default.
///     fn handle_threaded(&self) -> IrqReturn {
///         let mut data = self.value.lock();
///         *data += 1;
///         IrqReturn::Handled
///     }
/// }
///
/// // Registers a threaded IRQ handler for the given [`IrqRequest`].
/// //
/// // This is executing in process context and assumes that `request` was
/// // previously acquired from a device.
/// fn register_threaded_irq(
///     request: IrqRequest<'_>,
/// ) -> Result<Pin<KBox<ThreadedRegistration<'_, Data>>>> {
///     // SAFETY: The returned Registration is not leaked.
///     let registration = unsafe {
///         ThreadedRegistration::new(
///             request,
///             Flags::SHARED,
///             c"my_device",
///             try_pin_init!(Data {
///                 value <- kernel::new_mutex!(0),
///             }? Error),
///         )
///     };
///
///     let registration = KBox::pin_init(registration, GFP_KERNEL)?;
///
///     {
///         // The data can be accessed from process context too.
///         let mut data = registration.handler().value.lock();
///         *data += 1;
///     }
///
///     Ok(registration)
/// }
/// # Ok::<(), Error>(())
/// ```
///
/// # Invariants
///
/// * We own an irq handler registered via `request_threaded_irq` whose cookie is a pointer to
///   `Self`.
#[pin_data(PinnedDrop)]
pub struct ThreadedRegistration<'a, T: ThreadedHandler> {
    request: IrqRequest<'a>,

    #[pin]
    handler: T,

    /// Pinned because we need address stability so that we can pass a pointer
    /// to the callback.
    #[pin]
    _pin: PhantomPinned,
}

impl<'a, T: ThreadedHandler> ThreadedRegistration<'a, T> {
    /// Registers the IRQ handler with the system for the given IRQ number.
    ///
    /// # Safety
    ///
    /// Callers must not `mem::forget()` the returned [`ThreadedRegistration`] or otherwise prevent
    /// its [`Drop`] implementation from running.
    pub unsafe fn new(
        request: IrqRequest<'a>,
        flags: Flags,
        name: &'static CStr,
        handler: impl PinInit<T, Error> + 'a,
    ) -> impl PinInit<Self, Error> + 'a
    where
        T: 'a,
    {
        // INVARIANT: If initialization completes successfully, we own an IRQ handler registered
        // via `request_threaded_irq` whose cookie is a pointer to `Self`.
        try_pin_init!(&this in Self {
            handler <- handler,
            request,
            _pin: PhantomPinned,
            _: {
                // SAFETY:
                // - The callbacks are valid for use with request_threaded_irq.
                // - If this succeeds, the slot is guaranteed to be valid until the destructor of
                //   Self runs, which will deregister the callbacks before the memory location
                //   becomes invalid.
                // - All fields are already initialized, so it's safe for the callbacks to be
                //   called immediately.
                to_result(unsafe {
                    bindings::request_threaded_irq(
                        request.irq,
                        Some(handle_threaded_irq_callback::<T>),
                        Some(thread_fn_callback::<T>),
                        flags.into_inner(),
                        name.as_char_ptr(),
                        this.as_ptr().cast::<c_void>(),
                    )
                })?;
            },
        })
    }

    /// Returns a reference to the handler that was registered with the system.
    pub fn handler(&self) -> &T {
        &self.handler
    }

    /// Wait for pending IRQ handlers on other CPUs.
    #[inline]
    pub fn synchronize(&self) {
        // SAFETY: `self.request.irq` is a valid registered IRQ number (type invariant).
        unsafe { bindings::synchronize_irq(self.request.irq) };
    }
}

#[pinned_drop]
impl<T: ThreadedHandler> PinnedDrop for ThreadedRegistration<'_, T> {
    fn drop(self: Pin<&mut Self>) {
        // SAFETY: The cookie was set to a pointer to `Self` in `ThreadedRegistration::new()`. This
        // blocks until all in-flight handlers complete, so no references to `self` remain after
        // this returns.
        unsafe {
            bindings::free_irq(
                self.request.irq,
                core::ptr::from_mut::<Self>(self.get_unchecked_mut()).cast::<c_void>(),
            )
        };
    }
}

/// # Safety
///
/// This function should be only used as the callback in `request_threaded_irq`.
unsafe extern "C" fn handle_threaded_irq_callback<T: ThreadedHandler>(
    _irq: i32,
    ptr: *mut c_void,
) -> c_uint {
    let ptr = ptr.cast_const().cast::<ThreadedRegistration<'_, T>>();
    // SAFETY: `ptr` is a pointer to `ThreadedRegistration<'_, T>` set in
    // `ThreadedRegistration::new()`.
    let registration = unsafe { &*ptr };

    T::handle(&registration.handler) as c_uint
}

/// # Safety
///
/// This function should be only used as the callback in `request_threaded_irq`.
unsafe extern "C" fn thread_fn_callback<T: ThreadedHandler>(_irq: i32, ptr: *mut c_void) -> c_uint {
    let ptr = ptr.cast_const().cast::<ThreadedRegistration<'_, T>>();
    // SAFETY: `ptr` is a pointer to `ThreadedRegistration<'_, T>` set in
    // `ThreadedRegistration::new()`.
    let registration = unsafe { &*ptr };

    T::handle_threaded(&registration.handler) as c_uint
}