Re: [PATCH v6 2/7] rust: implement `WwClass` for ww_mutex support

Boqun Feng
2025-09-03T16:06:08Z

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
>