Adds the `WwClass` type, the first step in supporting
`ww_mutex` in Rust. `WwClass` represents a class of ww
mutexes used for deadlock avoidance for supporting both
wait-die and wound-wait semantics.

Also adds the `define_ww_class!` macro for safely declaring
static instances.

Signed-off-by: Onur Özkan <work@onurozkan.dev>
---
 rust/kernel/sync/lock.rs          |   1 +
 rust/kernel/sync/lock/ww_mutex.rs | 136 ++++++++++++++++++++++++++++++
 2 files changed, 137 insertions(+)
 create mode 100644 rust/kernel/sync/lock/ww_mutex.rs

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 27202beef90c..5b320c2b28c1 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 000000000000..ca5b4525ace6
--- /dev/null
+++ b/rust/kernel/sync/lock/ww_mutex.rs
@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! A kernel Wound/Wait Mutex.
+//!
+//! This module provides Rust abstractions for the Linux kernel's `ww_mutex` implementation,
+//! which provides deadlock avoidance through a wait-wound or wait-die algorithm.
+//!
+//! C header: [`include/linux/ww_mutex.h`](srctree/include/linux/ww_mutex.h)
+//!
+//! For more information: <https://docs.kernel.org/locking/ww-mutex-design.html>
+
+use crate::bindings;
+use crate::prelude::*;
+use crate::types::Opaque;
+
+/// Create static [`WwClass`] instances.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::{c_str, define_ww_class};
+///
+/// define_ww_class!(WOUND_WAIT_GLOBAL_CLASS, wound_wait, c_str!("wound_wait_global_class"));
+/// define_ww_class!(WAIT_DIE_GLOBAL_CLASS, wait_die, c_str!("wait_die_global_class"));
+/// ```
+#[macro_export]
+macro_rules! define_ww_class {
+    ($name:ident, wound_wait, $class_name:expr) => {
+        static $name: $crate::sync::lock::ww_mutex::WwClass =
+            // SAFETY: This is `static`, so address is fixed and won't move.
+            unsafe { $crate::sync::lock::ww_mutex::WwClass::unpinned_new($class_name, false) };
+    };
+    ($name:ident, wait_die, $class_name:expr) => {
+        static $name: $crate::sync::lock::ww_mutex::WwClass =
+            // SAFETY: This is `static`, so address is fixed and won't move.
+            unsafe { $crate::sync::lock::ww_mutex::WwClass::unpinned_new($class_name, true) };
+    };
+}
+
+/// A class used to group mutexes together for deadlock avoidance.
+///
+/// All mutexes that might be acquired together should use the same class.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::sync::lock::ww_mutex::WwClass;
+/// use kernel::c_str;
+/// use pin_init::stack_pin_init;
+///
+/// stack_pin_init!(let _wait_die_class = WwClass::new_wait_die(c_str!("graphics_buffers")));
+/// stack_pin_init!(let _wound_wait_class = WwClass::new_wound_wait(c_str!("memory_pools")));
+///
+/// # Ok::<(), Error>(())
+/// ```
+#[pin_data]
+pub struct WwClass {
+    #[pin]
+    inner: Opaque<bindings::ww_class>,
+}
+
+// SAFETY: [`WwClass`] is set up once and never modified. It's fine to share it across threads.
+unsafe impl Sync for WwClass {}
+// SAFETY: Doesn't hold anything thread-specific. It's safe to send to other threads.
+unsafe impl Send for WwClass {}
+
+impl WwClass {
+    /// Creates an unpinned [`WwClass`].
+    ///
+    /// # Safety
+    ///
+    /// Caller must guarantee that the returned value is not moved after creation.
+    pub const unsafe fn unpinned_new(name: &'static CStr, is_wait_die: bool) -> Self {
+        WwClass {
+            inner: Opaque::new(bindings::ww_class {
+                stamp: bindings::atomic_long_t { counter: 0 },
+                acquire_name: name.as_char_ptr(),
+                mutex_name: name.as_char_ptr(),
+                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.
+                //
+                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
+                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.
+                //
+                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
+                mutex_key: unsafe { core::mem::zeroed() },
+            }),
+        }
+    }
+
+    /// Creates a [`WwClass`].
+    ///
+    /// You should not use this function directly. Use the [`define_ww_class!`]
+    /// macro or call [`WwClass::new_wait_die`] or [`WwClass::new_wound_wait`] instead.
+    const fn new(name: &'static CStr, is_wait_die: bool) -> Self {
+        WwClass {
+            inner: Opaque::new(bindings::ww_class {
+                stamp: bindings::atomic_long_t { counter: 0 },
+                acquire_name: name.as_char_ptr(),
+                mutex_name: name.as_char_ptr(),
+                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.
+                //
+                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
+                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.
+                //
+                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
+                mutex_key: unsafe { core::mem::zeroed() },
+            }),
+        }
+    }
+
+    /// Creates wait-die [`WwClass`].
+    pub fn new_wait_die(name: &'static CStr) -> impl PinInit<Self> {
+        Self::new(name, true)
+    }
+
+    /// Creates wound-wait [`WwClass`].
+    pub fn new_wound_wait(name: &'static CStr) -> impl PinInit<Self> {
+        Self::new(name, false)
+    }
+}
--
2.50.0

On Wed, Sep 03, 2025 at 04:13:08PM +0300, Onur Özkan wrote:
> Adds the `WwClass` type, the first step in supporting
> `ww_mutex` in Rust. `WwClass` represents a class of ww
> mutexes used for deadlock avoidance for supporting both
> wait-die and wound-wait semantics.
> 
> Also adds the `define_ww_class!` macro for safely declaring
> static instances.
> 
> Signed-off-by: Onur Özkan <work@onurozkan.dev>
> ---
>  rust/kernel/sync/lock.rs          |   1 +
>  rust/kernel/sync/lock/ww_mutex.rs | 136 ++++++++++++++++++++++++++++++
>  2 files changed, 137 insertions(+)
>  create mode 100644 rust/kernel/sync/lock/ww_mutex.rs
> 
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index 27202beef90c..5b320c2b28c1 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 000000000000..ca5b4525ace6
> --- /dev/null
> +++ b/rust/kernel/sync/lock/ww_mutex.rs
> @@ -0,0 +1,136 @@
> +// SPDX-License-Identifier: GPL-2.0
> +
> +//! A kernel Wound/Wait Mutex.
> +//!
> +//! This module provides Rust abstractions for the Linux kernel's `ww_mutex` implementation,
> +//! which provides deadlock avoidance through a wait-wound or wait-die algorithm.
> +//!
> +//! C header: [`include/linux/ww_mutex.h`](srctree/include/linux/ww_mutex.h)
> +//!
> +//! For more information: <https://docs.kernel.org/locking/ww-mutex-design.html>
> +
> +use crate::bindings;
> +use crate::prelude::*;
> +use crate::types::Opaque;
> +
> +/// Create static [`WwClass`] instances.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// use kernel::{c_str, define_ww_class};
> +///
> +/// define_ww_class!(WOUND_WAIT_GLOBAL_CLASS, wound_wait, c_str!("wound_wait_global_class"));
> +/// define_ww_class!(WAIT_DIE_GLOBAL_CLASS, wait_die, c_str!("wait_die_global_class"));
> +/// ```
> +#[macro_export]
> +macro_rules! define_ww_class {
> +    ($name:ident, wound_wait, $class_name:expr) => {
> +        static $name: $crate::sync::lock::ww_mutex::WwClass =
> +            // SAFETY: This is `static`, so address is fixed and won't move.
> +            unsafe { $crate::sync::lock::ww_mutex::WwClass::unpinned_new($class_name, false) };
> +    };
> +    ($name:ident, wait_die, $class_name:expr) => {
> +        static $name: $crate::sync::lock::ww_mutex::WwClass =
> +            // SAFETY: This is `static`, so address is fixed and won't move.
> +            unsafe { $crate::sync::lock::ww_mutex::WwClass::unpinned_new($class_name, true) };
> +    };
> +}
> +
> +/// A class used to group mutexes together for deadlock avoidance.
> +///
> +/// All mutexes that might be acquired together should use the same class.
> +///
> +/// # Examples
> +///
> +/// ```
> +/// use kernel::sync::lock::ww_mutex::WwClass;
> +/// use kernel::c_str;
> +/// use pin_init::stack_pin_init;
> +///
> +/// stack_pin_init!(let _wait_die_class = WwClass::new_wait_die(c_str!("graphics_buffers")));
> +/// stack_pin_init!(let _wound_wait_class = WwClass::new_wound_wait(c_str!("memory_pools")));
> +///
> +/// # Ok::<(), Error>(())
> +/// ```
> +#[pin_data]
> +pub struct WwClass {
> +    #[pin]
> +    inner: Opaque<bindings::ww_class>,
> +}
> +
> +// SAFETY: [`WwClass`] is set up once and never modified. It's fine to share it across threads.
> +unsafe impl Sync for WwClass {}
> +// SAFETY: Doesn't hold anything thread-specific. It's safe to send to other threads.
> +unsafe impl Send for WwClass {}
> +
> +impl WwClass {
> +    /// Creates an unpinned [`WwClass`].
> +    ///
> +    /// # Safety
> +    ///
> +    /// Caller must guarantee that the returned value is not moved after creation.
> +    pub const unsafe fn unpinned_new(name: &'static CStr, is_wait_die: bool) -> Self {
> +        WwClass {
> +            inner: Opaque::new(bindings::ww_class {
> +                stamp: bindings::atomic_long_t { counter: 0 },
> +                acquire_name: name.as_char_ptr(),
> +                mutex_name: name.as_char_ptr(),
> +                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.
> +                //
> +                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>

Please don't use internet to reference the code in the same repo ;-) You
can just say "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.
> +                //
> +                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
> +                mutex_key: unsafe { core::mem::zeroed() },
> +            }),
> +        }
> +    }
> +
> +    /// Creates a [`WwClass`].
> +    ///
> +    /// You should not use this function directly. Use the [`define_ww_class!`]
> +    /// macro or call [`WwClass::new_wait_die`] or [`WwClass::new_wound_wait`] instead.
> +    const fn new(name: &'static CStr, is_wait_die: bool) -> Self {
> +        WwClass {
> +            inner: Opaque::new(bindings::ww_class {

You cannot use Opaque::new() here, it'll move the object when new()
returns. You should change the function signature to a `... ->
PinInit<Self>`, and use pin_init!() macro + Opaque::ffi_init(), like:

    const fn new(...) -> PinInit<Self> {
        pin_init!{
	    Self {
	        inner <- Opaque::ffi_init(|class| {
		    ...
		});
	    }
	}
    }

Regards,
Boqun

> +                stamp: bindings::atomic_long_t { counter: 0 },
> +                acquire_name: name.as_char_ptr(),
> +                mutex_name: name.as_char_ptr(),
> +                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.
> +                //
> +                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
> +                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.
> +                //
> +                // Ref: <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
> +                mutex_key: unsafe { core::mem::zeroed() },
> +            }),
> +        }
> +    }
> +
> +    /// Creates wait-die [`WwClass`].
> +    pub fn new_wait_die(name: &'static CStr) -> impl PinInit<Self> {
> +        Self::new(name, true)
> +    }
> +
> +    /// Creates wound-wait [`WwClass`].
> +    pub fn new_wound_wait(name: &'static CStr) -> impl PinInit<Self> {
> +        Self::new(name, false)
> +    }
> +}
> --
> 2.50.0
> 

On Wed, 3 Sep 2025 09:06:03 -0700
Boqun Feng <boqun.feng@gmail.com> wrote:

> On Wed, Sep 03, 2025 at 04:13:08PM +0300, Onur Özkan wrote:
> > Adds the `WwClass` type, the first step in supporting
> > `ww_mutex` in Rust. `WwClass` represents a class of ww
> > mutexes used for deadlock avoidance for supporting both
> > wait-die and wound-wait semantics.
> > 
> > Also adds the `define_ww_class!` macro for safely declaring
> > static instances.
> > 
> > Signed-off-by: Onur Özkan <work@onurozkan.dev>
> > ---
> >  rust/kernel/sync/lock.rs          |   1 +
> >  rust/kernel/sync/lock/ww_mutex.rs | 136
> > ++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+)
> >  create mode 100644 rust/kernel/sync/lock/ww_mutex.rs
> > 
> > diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> > index 27202beef90c..5b320c2b28c1 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 000000000000..ca5b4525ace6
> > --- /dev/null
> > +++ b/rust/kernel/sync/lock/ww_mutex.rs
> > @@ -0,0 +1,136 @@
> > +// SPDX-License-Identifier: GPL-2.0
> > +
> > +//! A kernel Wound/Wait Mutex.
> > +//!
> > +//! This module provides Rust abstractions for the Linux kernel's
> > `ww_mutex` implementation, +//! which provides deadlock avoidance
> > through a wait-wound or wait-die algorithm. +//!
> > +//! C header:
> > [`include/linux/ww_mutex.h`](srctree/include/linux/ww_mutex.h) +//!
> > +//! For more information:
> > <https://docs.kernel.org/locking/ww-mutex-design.html> +
> > +use crate::bindings;
> > +use crate::prelude::*;
> > +use crate::types::Opaque;
> > +
> > +/// Create static [`WwClass`] instances.
> > +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// use kernel::{c_str, define_ww_class};
> > +///
> > +/// define_ww_class!(WOUND_WAIT_GLOBAL_CLASS, wound_wait,
> > c_str!("wound_wait_global_class")); +///
> > define_ww_class!(WAIT_DIE_GLOBAL_CLASS, wait_die,
> > c_str!("wait_die_global_class")); +/// ``` +#[macro_export]
> > +macro_rules! define_ww_class {
> > +    ($name:ident, wound_wait, $class_name:expr) => {
> > +        static $name: $crate::sync::lock::ww_mutex::WwClass =
> > +            // SAFETY: This is `static`, so address is fixed and
> > won't move.
> > +            unsafe {
> > $crate::sync::lock::ww_mutex::WwClass::unpinned_new($class_name,
> > false) };
> > +    };
> > +    ($name:ident, wait_die, $class_name:expr) => {
> > +        static $name: $crate::sync::lock::ww_mutex::WwClass =
> > +            // SAFETY: This is `static`, so address is fixed and
> > won't move.
> > +            unsafe {
> > $crate::sync::lock::ww_mutex::WwClass::unpinned_new($class_name,
> > true) };
> > +    };
> > +}
> > +
> > +/// A class used to group mutexes together for deadlock avoidance.
> > +///
> > +/// All mutexes that might be acquired together should use the
> > same class. +///
> > +/// # Examples
> > +///
> > +/// ```
> > +/// use kernel::sync::lock::ww_mutex::WwClass;
> > +/// use kernel::c_str;
> > +/// use pin_init::stack_pin_init;
> > +///
> > +/// stack_pin_init!(let _wait_die_class =
> > WwClass::new_wait_die(c_str!("graphics_buffers"))); +///
> > stack_pin_init!(let _wound_wait_class =
> > WwClass::new_wound_wait(c_str!("memory_pools"))); +/// +/// #
> > Ok::<(), Error>(()) +/// ```
> > +#[pin_data]
> > +pub struct WwClass {
> > +    #[pin]
> > +    inner: Opaque<bindings::ww_class>,
> > +}
> > +
> > +// SAFETY: [`WwClass`] is set up once and never modified. It's
> > fine to share it across threads. +unsafe impl Sync for WwClass {}
> > +// SAFETY: Doesn't hold anything thread-specific. It's safe to
> > send to other threads. +unsafe impl Send for WwClass {}
> > +
> > +impl WwClass {
> > +    /// Creates an unpinned [`WwClass`].
> > +    ///
> > +    /// # Safety
> > +    ///
> > +    /// Caller must guarantee that the returned value is not moved
> > after creation.
> > +    pub const unsafe fn unpinned_new(name: &'static CStr,
> > is_wait_die: bool) -> Self {
> > +        WwClass {
> > +            inner: Opaque::new(bindings::ww_class {
> > +                stamp: bindings::atomic_long_t { counter: 0 },
> > +                acquire_name: name.as_char_ptr(),
> > +                mutex_name: name.as_char_ptr(),
> > +                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.
> > +                //
> > +                // Ref:
> > <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
> 
> Please don't use internet to reference the code in the same repo ;-)
> You can just say "see __WW_CLASS_INITIALIZER() in
> include/linux/ww_mutex.h".
> 

I don't know why I did that tbh :D I guess I wanted to have a permament
ref, but it doesn't make much sense yeah.

> > +                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.
> > +                //
> > +                // Ref:
> > <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/ww_mutex.h?h=v6.16-rc2#n85>
> > +                mutex_key: unsafe { core::mem::zeroed() },
> > +            }),
> > +        }
> > +    }
> > +
> > +    /// Creates a [`WwClass`].
> > +    ///
> > +    /// You should not use this function directly. Use the
> > [`define_ww_class!`]
> > +    /// macro or call [`WwClass::new_wait_die`] or
> > [`WwClass::new_wound_wait`] instead.
> > +    const fn new(name: &'static CStr, is_wait_die: bool) -> Self {
> > +        WwClass {
> > +            inner: Opaque::new(bindings::ww_class {
> 
> You cannot use Opaque::new() here, it'll move the object when new()
> returns. You should change the function signature to a `... ->
> PinInit<Self>`, and use pin_init!() macro + Opaque::ffi_init(), like:
> 
>     const fn new(...) -> PinInit<Self> {
>         pin_init!{
> 	    Self {
> 	        inner <- Opaque::ffi_init(|class| {
> 		    ...
> 		});
> 	    }
> 	}
>     }
> 
> Regards,
> Boqun

I didn't know that, will do that in the following patch.

Thanks,
Onur