Re: [PATCH v12 3/6] rust: implement Class for ww_class support

[Onur Özkan]

On Mon, 12 Oct 2026 12:03:04 +0100
Gary Guo <gary@xxxxxxxxxxx> wrote:

> On Mon Oct 12, 2026 at 11:26 AM BST, Onur Özkan wrote:
> > Adds the Class type, the first step in supporting ww_mutex in Rust.
> > Class represents ww_class, used for deadlock avoidance for supporting
> > both wait-die and wound-wait semantics.
> >
> > Also adds the define_ww_class and define_wd_class macros for safely
> > declaring static instances.
> >
> > Reviewed-by: Alice Ryhl <aliceryhl@xxxxxxxxxx>
> > Reviewed-by: Daniel Almeida <daniel.almeida@xxxxxxxxxxxxx>
> > Signed-off-by: Onur Özkan <work@xxxxxxxxxxxxx>
> 
> Reviewed-by: Gary Guo <gary@xxxxxxxxxxx>
> 
> With some nits below.
> 
> > ---
> >  rust/kernel/sync/lock.rs                |   1 +
> >  rust/kernel/sync/lock/ww_mutex.rs       |   7 ++
> >  rust/kernel/sync/lock/ww_mutex/class.rs | 151 ++++++++++++++++++++++++
> >  3 files changed, 159 insertions(+)
> >  create mode 100644 rust/kernel/sync/lock/ww_mutex.rs
> >  create mode 100644 rust/kernel/sync/lock/ww_mutex/class.rs
> >
> > diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> > index 10b6b5e9b024f..f509250822c55 100644
> > --- a/rust/kernel/sync/lock.rs
> > +++ b/rust/kernel/sync/lock.rs
> > @@ -15,6 +15,7 @@
> >  
> >  pub mod mutex;
> >  pub mod spinlock;
> > +pub mod ww_mutex;
> >  
> >  pub(super) mod global;
> >  pub use global::{GlobalGuard, GlobalLock, GlobalLockBackend, GlobalLockedBy};
> > diff --git a/rust/kernel/sync/lock/ww_mutex.rs b/rust/kernel/sync/lock/ww_mutex.rs
> > new file mode 100644
> > index 0000000000000..727c51cc73af8
> > --- /dev/null
> > +++ b/rust/kernel/sync/lock/ww_mutex.rs
> > @@ -0,0 +1,7 @@
> > +// SPDX-License-Identifier: GPL-2.0
> > +
> > +//! Rust abstractions for the kernel's wound-wait locking primitives.
> > +
> > +pub use class::Class;
> > +
> > +mod class;
> > diff --git a/rust/kernel/sync/lock/ww_mutex/class.rs b/rust/kernel/sync/lock/ww_mutex/class.rs
> > new file mode 100644
> > index 0000000000000..58a4467552700
> > --- /dev/null
> > +++ b/rust/kernel/sync/lock/ww_mutex/class.rs
> > @@ -0,0 +1,151 @@
> > +// SPDX-License-Identifier: GPL-2.0
> > +
> > +//! Provides [`Class`] to group wound/wait mutexes to be acquired together
> > +//! and specifies which deadlock avoidance algorithm to use (e.g., wound-wait
> > +//! or wait-die).
> > +//!
> > +//! The [`define_ww_class!`] and [`define_wd_class!`] macros provide safe
> > +//! ways to create classes.
> > +
> > +use crate::{
> > +    bindings,
> > +    prelude::*,
> > +    types::Opaque, //
> > +};
> > +
> > +/// Defines a static wound-wait [`Class`].
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// use kernel::define_ww_class;
> > +///
> > +/// define_ww_class!(SOME_WW_CLASS);
> > +/// ```
> > +#[macro_export]
> > +macro_rules! define_ww_class {
> > +    ($name:ident) => {
> > +        static $name: $crate::sync::lock::ww_mutex::Class =
> > +            // SAFETY: This is `static`, so address is fixed and won't move.
> > +            unsafe {
> > +                $crate::sync::lock::ww_mutex::Class::new_unpinned(
> > +                    $crate::c_str!(::core::concat!(::core::stringify!($name), "_acquire")),
> > +                    $crate::c_str!(::core::concat!(::core::stringify!($name), "_mutex")),
> > +                    false,
> > +                )
> > +            };
> > +    };
> > +}
> > +
> > +/// Defines a static wait-die [`Class`].
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// use kernel::define_wd_class;
> > +///
> > +/// define_wd_class!(SOME_WD_CLASS);
> > +/// ```
> > +#[macro_export]
> > +macro_rules! define_wd_class {
> > +    ($name:ident) => {
> > +        static $name: $crate::sync::lock::ww_mutex::Class =
> > +            // SAFETY: This is `static`, so address is fixed and won't move.
> > +            unsafe {
> > +                $crate::sync::lock::ww_mutex::Class::new_unpinned(
> > +                    $crate::c_str!(::core::concat!(::core::stringify!($name), "_acquire")),
> > +                    $crate::c_str!(::core::concat!(::core::stringify!($name), "_mutex")),
> > +                    true,
> > +                )
> > +            };
> > +    };
> > +}
> > +
> > +/// Used to group mutexes together for deadlock avoidance.
> > +///
> > +/// All mutexes that might be acquired together should use the same class.
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// use kernel::{
> > +///     define_wd_class,
> > +///     define_ww_class, //
> > +/// };
> > +///
> > +/// define_ww_class!(SOME_WW_CLASS);
> > +/// define_wd_class!(SOME_WD_CLASS);
> > +///
> > +/// # Ok::<(), Error>(())
> > +/// ```
> > +#[pin_data]
> > +#[repr(transparent)]
> > +pub struct Class {
> > +    #[pin]
> > +    pub(super) inner: Opaque<bindings::ww_class>,
> > +}
> > +
> > +impl Class {
> > +    /// Creates an unpinned [`Class`].
> > +    ///
> > +    /// You should prefer using [`define_ww_class!`] and [`define_wd_class!`]
> > +    /// macros. This function is `pub` only so that those macros can use it.
> > +    /// The alternative would be to expose the private fields of [`Class`]
> > +    /// which is less desirable.
> 
> Replace the paragraph with `#[doc(hidden)]`?

Good idea.

> 
> > +    ///
> > +    /// # Safety
> > +    ///
> > +    /// Caller must guarantee that the returned value must be pinned before
> > +    /// its first use.
> > +    pub const unsafe fn new_unpinned(
> > +        acquire_name: &'static CStr,
> > +        mutex_name: &'static CStr,
> > +        is_wait_die: bool,
> > +    ) -> Self {
> > +        Class {
> > +            inner: Opaque::new(bindings::ww_class {
> > +                stamp: bindings::atomic_long_t { counter: 0 },
> > +                acquire_name: crate::str::as_char_ptr_in_const_context(acquire_name),
> > +                mutex_name: crate::str::as_char_ptr_in_const_context(mutex_name),
> > +                is_wait_die: is_wait_die as u32,
> > +                // TODO: Replace with `bindings::lock_class_key::default()` once
> > +                // stabilized for `const`.
> > +                //
> > +                // SAFETY: This is always zero-initialized when defined with
> > +                // `DEFINE_WD_CLASS` globally on C side.
> > +                //
> > +                // For reference, see __WW_CLASS_INITIALIZER() in
> > +                // "include/linux/ww_mutex.h".
> > +                acquire_key: unsafe { core::mem::zeroed() },
> > +                // TODO: Replace with `bindings::lock_class_key::default()` once
> > +                // stabilized for `const`.
> > +                //
> > +                // SAFETY: This is always zero-initialized when defined with
> > +                // `DEFINE_WD_CLASS` globally on C side.
> > +                //
> > +                // For reference, see __WW_CLASS_INITIALIZER() in
> > +                // "include/linux/ww_mutex.h".
> > +                mutex_key: unsafe { core::mem::zeroed() },
> 
> Does `..pin_init::zeroed()` work in this case?

It does.

Thanks,
Onur

> 
> Best,
> Gary
> 
> > +            }),
> > +        }
> > +    }
> > +
> > +    /// Creates a [`Class`] from a raw pointer.
> > +    ///
> > +    /// This function is intended for interoperability with C code.
> > +    ///
> > +    /// # Safety
> > +    ///
> > +    /// The caller must ensure that `ptr` points to the `inner` field of
> > +    /// [`Class`] and that it remains valid for the lifetime `'a`.
> > +    #[inline]
> > +    pub const unsafe fn from_raw<'a>(ptr: *mut bindings::ww_class) -> &'a Self {
> > +        // SAFETY: By the safety contract, `ptr` is valid to construct `Class`.
> > +        unsafe { &*ptr.cast() }
> > +    }
> > +}
> > +
> > +// SAFETY: [`Class`] is immutable except for its atomic stamp. It's fine to share it across threads.
> > +unsafe impl Sync for Class {}
> > +// SAFETY: Doesn't hold anything thread-specific. It's safe to send to other threads.
> > +unsafe impl Send for Class {}
> 
>