rust: irq: add support for threaded IRQs and handlers (135d4052) · Commits · git / linux-net

rust/kernel/irq.rs

+4 −1

Original line number	Diff line number	Diff line
		@@ -18,4 +18,7 @@

		pub use flags::Flags;

		pub use request::{Handler, IrqRequest, IrqReturn, Registration};
		pub use request::{
		Handler, IrqRequest, IrqReturn, Registration, ThreadedHandler, ThreadedIrqReturn,
		ThreadedRegistration,
		};

rust/kernel/irq/request.rs

+228 −4

Original line number	Diff line number	Diff line
		// SPDX-License-Identifier: GPL-2.0
		// SPDX-FileCopyrightText: Copyright 2025 Collabora ltd.

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

		use core::marker::PhantomPinned;

		@@ -15,7 +16,7 @@
		use crate::str::CStr;
		use crate::sync::Arc;

		/// The value that can be returned from a [`Handler`] or a `ThreadedHandler`.
		/// 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.
		@@ -34,7 +35,7 @@ pub trait Handler: Sync {
		///
		/// All work that does not necessarily need to be executed from
		/// interrupt context, should be deferred to a threaded handler.
		/// See also `ThreadedRegistration`.
		/// See also [`ThreadedRegistration`].
		fn handle(&self) -> IrqReturn;
		}

		@@ -263,3 +264,226 @@ pub fn synchronize(&self, dev: &Device<Bound>) -> Result {
		let handler = unsafe { &(ptr as const T) };
		T::handle(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;
		}

		impl<T: ?Sized + ThreadedHandler + Send> ThreadedHandler for Arc<T> {
		fn handle(&self) -> ThreadedIrqReturn {
		T::handle(self)
		}

		fn handle_threaded(&self) -> IrqReturn {
		T::handle_threaded(self)
		}
		}

		impl<T: ?Sized + ThreadedHandler, A: Allocator> ThreadedHandler for Box<T, A> {
		fn handle(&self) -> ThreadedIrqReturn {
		T::handle(self)
		}

		fn handle_threaded(&self) -> IrqReturn {
		T::handle_threaded(self)
		}
		}

		/// 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 kernel::c_str;
		/// use kernel::device::Bound;
		/// use kernel::irq::{
		/// self, Flags, IrqRequest, IrqReturn, ThreadedHandler, ThreadedIrqReturn,
		/// ThreadedRegistration,
		/// };
		/// use kernel::prelude::*;
		/// use kernel::sync::{Arc, 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(
		/// handler: impl PinInit<Data, Error>,
		/// request: IrqRequest<'_>,
		/// ) -> Result<Arc<ThreadedRegistration<Data>>> {
		/// let registration =
		/// ThreadedRegistration::new(request, Flags::SHARED, c_str!("my_device"), handler);
		///
		/// let registration = Arc::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 using `&T` as its private data.
		#[pin_data]
		pub struct ThreadedRegistration<T: ThreadedHandler + 'static> {
		#[pin]
		inner: Devres<RegistrationInner>,

		#[pin]
		handler: T,

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

		impl<T: ThreadedHandler + 'static> ThreadedRegistration<T> {
		/// Registers the IRQ handler with the system for the given IRQ number.
		pub fn new<'a>(
		request: IrqRequest<'a>,
		flags: Flags,
		name: &'static CStr,
		handler: impl PinInit<T, Error> + 'a,
		) -> impl PinInit<Self, Error> + 'a {
		try_pin_init!(&this in Self {
		handler <- handler,
		inner <- Devres::new(
		request.dev,
		try_pin_init!(RegistrationInner {
		// SAFETY: `this` is a valid pointer to the `ThreadedRegistration` instance.
		cookie: unsafe { &raw mut (*this.as_ptr()).handler }.cast(),
		irq: {
		// 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.
		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(),
		(&raw mut (*this.as_ptr()).handler).cast(),
		)
		})?;
		request.irq
		}
		})
		),
		_pin: PhantomPinned,
		})
		}

		/// 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.
		///
		/// This will attempt to access the inner [`Devres`] container.
		pub fn try_synchronize(&self) -> Result {
		let inner = self.inner.try_access().ok_or(ENODEV)?;
		inner.synchronize();
		Ok(())
		}

		/// Wait for pending IRQ handlers on other CPUs.
		pub fn synchronize(&self, dev: &Device<Bound>) -> Result {
		let inner = self.inner.access(dev)?;
		inner.synchronize();
		Ok(())
		}
		}

		/// # 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 {
		// SAFETY: `ptr` is a pointer to T set in `ThreadedRegistration::new`
		let handler = unsafe { &(ptr as const T) };
		T::handle(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 {
		// SAFETY: `ptr` is a pointer to T set in `ThreadedRegistration::new`
		let handler = unsafe { &(ptr as const T) };
		T::handle_threaded(handler) as c_uint
		}