rust: add ww_mutex support

Some of the kernel's ww_mutex functions are implemented as static inline, so they are inaccessible from Rust as bindgen can't generate code on them. This patch provides C function wrappers around these inline implementations, so bindgen can see them and generate the corresponding Rust code.

Reviewed-by Daniel Almeida <[email protected]>

Reviewed-by Alice Ryhl <[email protected]>

Reviewed-by Lyude Paul <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

---
 MAINTAINERS             |  1 +
 rust/helpers/helpers.c  |  1 +
 rust/helpers/ww_mutex.c | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 rust/helpers/ww_mutex.c

Removes DEBUG_WW_MUTEXES guard around the ww_class field in struct ww_mutex and struct ww_acquire_ctx to always initialize it.

Keeping the class pointer available unconditionally allows Rust abstractions to keep from_raw() simple on Mutex and AcquireCtx and validate Mutex and AcquireCtx class pairing in much simpler way.

Link https://lore.kernel.org/all/[email protected]/ open here

Reviewed-by Daniel Almeida <[email protected]>

Reviewed-by Alice Ryhl <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

Quoted 8 lines · Onur Özkan

Removes DEBUG_WW_MUTEXES guard around the ww_class field in struct ww_mutex and struct ww_acquire_ctx to always initialize it.

Keeping the class pointer available unconditionally allows Rust abstractions to keep from_raw() simple on Mutex and AcquireCtx and validate Mutex and AcquireCtx class pairing in much simpler way.

Is a mismatch a memory safety issue or just a bug?

Best,
Gary

Quoted 5 lines

Link https://lore.kernel.org/all/[email protected]/ open here

Reviewed-by Daniel Almeida <[email protected]>

Reviewed-by Alice Ryhl <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

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 <[email protected]>

Reviewed-by Daniel Almeida <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

---
 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

rust/kernel/sync/lock.rs +1 -0

index 10b6b5e9b024f..f509250822c55 100644
@@ -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};

rust/kernel/sync/lock/ww_mutex.rs new file +7 -0

new file mode 100644
index 0000000000000..727c51cc73af8
@@ -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;

rust/kernel/sync/lock/ww_mutex/class.rs new file +84 -0

new file mode 100644
index 0000000000000..58a4467552700
@@ -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]

rust/kernel/sync/lock/ww_mutex/class.rs new file +24 -0

+    ///
+    /// # 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".

rust/kernel/sync/lock/ww_mutex/class.rs new file +23 -0

+            }),
+        }
+    }
+
+    /// 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 {}

Quoted 10 lines · Onur Özkan

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 <[email protected]>

Reviewed-by Daniel Almeida <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

Reviewed-by Gary Guo <[email protected]>

With some nits below.

Quoted 127 lines

---
 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

rust/kernel/sync/lock.rs +1 -0

index 10b6b5e9b024f..f509250822c55 100644
@@ -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};

rust/kernel/sync/lock/ww_mutex.rs new file +7 -0

new file mode 100644
index 0000000000000..727c51cc73af8
@@ -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;

rust/kernel/sync/lock/ww_mutex/class.rs new file +88 -0

new file mode 100644
index 0000000000000..58a4467552700
@@ -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 {

rust/kernel/sync/lock/ww_mutex/class.rs line 94

Quoted 6 lines

rust/kernel/sync/lock/ww_mutex/class.rs new file +6 -0

+    /// 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)]?

Quoted 25 lines

rust/kernel/sync/lock/ww_mutex/class.rs new file +24 -0

+    ///
+    /// # 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".

rust/kernel/sync/lock/ww_mutex/class.rs line 128

Quoted 10 lines

rust/kernel/sync/lock/ww_mutex/class.rs new file +10 -0

+                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?

Best,
Gary

Quoted 23 lines

rust/kernel/sync/lock/ww_mutex/class.rs new file +23 -0

+            }),
+        }
+    }
+
+    /// 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 {}

Covers the low-level locking API (lock, try_lock and interruptible variants) and integration with kernel bindings.

Reviewed-by Alice Ryhl <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

---
 rust/kernel/sync/lock/ww_mutex.rs             | 434 ++++++++++++++++++
 rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs | 149 ++++++
 2 files changed, 583 insertions(+)
 create mode 100644 rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs

rust/kernel/sync/lock/ww_mutex.rs +51 -0

index 727c51cc73af8..2423f89a7e762 100644
@@ -1,7 +1,441 @@
 // SPDX-License-Identifier: GPL-2.0
 
 //! Rust abstractions for the kernel's wound-wait locking primitives.
+//!
+//! It is designed to avoid deadlocks when locking multiple [`Mutex`]es
+//! that belong to the same [`Class`]. Each lock acquisition uses an
+//! [`AcquireCtx`] to track ordering and ensure forward progress.
+//!
+//! See srctree/Documentation/locking/ww-mutex-design.rst for more details.
 
+use crate::{
+    bindings,
+    container_of,
+    error::to_result,
+    prelude::*,
+    types::{
+        NotThreadSafe,
+        Opaque, //
+    }, //
+};
+use core::{
+    cell::UnsafeCell,
+    marker::PhantomData, //
+};
+
+pub use acquire_ctx::AcquireCtx;
 pub use class::Class;
 
+mod acquire_ctx;
 mod class;
+
+/// A wound-wait (ww) mutex that is powered with deadlock avoidance
+/// when acquiring multiple locks of the same [`Class`].
+///
+/// Each mutex belongs to a [`Class`], which the wound-wait algorithm
+/// uses to figure out the order of acquisition and prevent deadlocks.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::{
+///     define_ww_class,
+///     sync::{
+///         lock::ww_mutex::{
+///             AcquireCtx,
+///             Class,
+///             Mutex, //
+///         },
+///         Arc,
+///     },
+/// };
+/// use pin_init::stack_pin_init;
+///
+/// define_ww_class!(SOME_WW_CLASS);
+///
+/// let mutex = Arc::pin_init(Mutex::new(42, &SOME_WW_CLASS), GFP_KERNEL)?;
+/// let ctx = KBox::pin_init(AcquireCtx::new(&SOME_WW_CLASS), GFP_KERNEL)?;
+///

rust/kernel/sync/lock/ww_mutex.rs +36 -0

+    #[pin]
+    inner: Opaque<bindings::ww_mutex>,
+    data: UnsafeCell<T>,
+}
+
+impl<'class, T> Mutex<'class, T> {
+    /// Initializes [`Mutex`] with the given `data` and [`Class`].
+    pub fn new(data: T, class: &'class Class) -> impl PinInit<Self> {
+        let class_ptr = class.inner.get();
+        pin_init!(Mutex {
+            inner <- Opaque::ffi_init(|slot: *mut bindings::ww_mutex| {
+                // SAFETY: `class` is valid for the lifetime `'class` captured by `Self`.
+                unsafe { bindings::ww_mutex_init(slot, class_ptr) }
+            }),
+            data: UnsafeCell::new(data),
+            _p: PhantomData
+        })
+    }
+}
+
+impl<'class, T: ?Sized> Mutex<'class, T> {
+    /// Checks if this [`Mutex`] is currently locked.
+    ///
+    /// The returned value is racy as another thread can acquire
+    /// or release the lock immediately after this call returns.
+    #[inline]
+    pub fn is_locked(&self) -> bool {
+        // SAFETY: It's safe to call `ww_mutex_is_locked` on
+        // a valid mutex.
+        unsafe { bindings::ww_mutex_is_locked(self.inner.get()) }
+    }
+
+    /// Locks this [`Mutex`] without [`AcquireCtx`].
+    pub fn lock(&self) -> Result<MutexGuard<'_, T>> {
+        lock_common(self, None, LockKind::Regular)
+    }

rust/kernel/sync/lock/ww_mutex.rs +85 -0

+        lock_common(self, None, LockKind::Try)
+    }
+}
+
+impl<'class> Mutex<'class, ()> {
+    /// Creates a [`Mutex`] from a raw pointer.
+    ///
+    /// This function is intended for interoperability with C code.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that:
+    ///
+    /// - `ptr` is a valid pointer to a `ww_mutex`.
+    /// - `ptr` must remain valid for the lifetime `'a`.
+    /// - ww_class associated with this mutex must be valid for
+    ///   the lifetime `'class`.
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::ww_mutex) -> &'a Self {
+        // SAFETY: By the safety contract, the caller guarantees that `ptr`
+        // points to a valid `ww_mutex` which is the `inner` field of `Mutex`,
+        // that it remains valid for the lifetime `'a` and the associated
+        // ww_class outlives `'class`.
+        //
+        // Because [`Mutex`] is `#[repr(C)]`, the `inner` field sits at a
+        // stable offset that `container_of!` can safely rely on.
+        unsafe { &*container_of!(Opaque::cast_from(ptr), Self, inner) }
+    }
+}
+
+// SAFETY: `Mutex` can be sent to another thread if the protected
+// data `T` can be.
+unsafe impl<T: ?Sized + Send> Send for Mutex<'_, T> {}
+
+// SAFETY: `Mutex` serialises access to the protected data, so it is
+// `Sync` as long as the data is `Send`.
+unsafe impl<T: ?Sized + Send> Sync for Mutex<'_, T> {}
+
+/// A guard that provides exclusive access to the data protected
+/// by a [`Mutex`].
+///
+/// # Invariants
+///
+/// The guard holds an exclusive lock on the associated [`Mutex`]. The lock is held
+/// for the entire lifetime of this guard and is automatically released when the
+/// guard is dropped.
+#[must_use = "the lock unlocks immediately when the guard is unused"]
+pub struct MutexGuard<'a, T: ?Sized> {
+    mutex: &'a Mutex<'a, T>,
+    _not_send: NotThreadSafe,
+}
+
+impl<'a, T: ?Sized> MutexGuard<'a, T> {
+    /// Creates a new guard for the given [`Mutex`].
+    fn new(mutex: &'a Mutex<'a, T>) -> Self {
+        assert!(mutex.is_locked());
+
+        // INVARIANT: `lock_common` and `from_raw` ensure that the current task holds the mutex
+        // and transfer sole responsibility for unlocking it to this guard.
+        Self {
+            mutex,
+            _not_send: NotThreadSafe,
+        }
+    }
+}
+
+impl<'a> MutexGuard<'a, ()> {
+    /// Creates a [`MutexGuard`] from a raw pointer.
+    ///
+    /// If the given pointer refers to a mutex that is not locked,
+    /// returns [`EINVAL`].
+    ///
+    /// This function is intended for interoperability with C code.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that:
+    ///
+    /// - `ptr` is a valid pointer to a `ww_mutex`.
+    /// - `ptr` must remain valid for the lifetime `'b`.
+    /// - The `ww_class` associated with the `ww_mutex` must be valid for the lifetime `'b`.
+    /// - The current task holds the mutex.
+    /// - The caller transfers responsibility for unlocking the mutex to the returned guard
+    ///   and must not unlock it separately (including through another guard).
+    /// - Any associated acquire context remains valid until the mutex is unlocked,
+    ///   even if the returned guard is forgotten. The context must not be finalized or

rust/kernel/sync/lock/ww_mutex.rs +38 -0

+    fn deref(&self) -> &Self::Target {
+        // SAFETY: self.mutex is locked, so we have exclusive access.
+        unsafe { &*self.mutex.data.get() }
+    }
+}
+
+impl<T: ?Sized + Unpin> core::ops::DerefMut for MutexGuard<'_, T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        // SAFETY: self.mutex is locked, so we have exclusive access.
+        unsafe { &mut *self.mutex.data.get() }
+    }
+}
+
+impl<T: ?Sized> Drop for MutexGuard<'_, T> {
+    #[inline]
+    fn drop(&mut self) {
+        // SAFETY: self.mutex is locked and are about to release it.
+        unsafe { bindings::ww_mutex_unlock(self.mutex.inner.get()) };
+    }
+}
+
+// SAFETY: `MutexGuard` can be shared between threads if the data can.
+unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
+
+/// Locking kinds used by [`lock_common`] to unify the internal
+/// locking logic.
+///
+/// It's best not to expose this type (and [`lock_common`]) to the
+/// kernel, as it allows internal API changes without worrying
+/// about breaking external compatibility.
+#[derive(Copy, Clone, Debug)]
+enum LockKind {
+    /// Blocks until lock is acquired.
+    Regular,
+    /// Blocks but can be interrupted by signals.
+    Interruptible,
+    /// Does not block, returns immediately if busy.
+    Try,

rust/kernel/sync/lock/ww_mutex.rs +8 -0

+    let mutex_ptr = mutex.inner.get();
+
+    let ctx_ptr = match ctx {
+        Some(acquire_ctx) => {
+            let ctx_ptr = acquire_ctx.inner.get();
+
+            // SAFETY: `ctx_ptr` is a valid pointer for the entire
+            // lifetime of `ctx`.

rust/kernel/sync/lock/ww_mutex.rs +36 -0

+
+            ctx_ptr
+        }
+        None => core::ptr::null_mut(),
+    };
+
+    match kind {
+        LockKind::Regular => {
+            // SAFETY: `Mutex` is always pinned. If `AcquireCtx` is `Some`, it is pinned,
+            // if `None`, it is set to `core::ptr::null_mut()`. Both cases are safe.
+            let ret = unsafe { bindings::ww_mutex_lock(mutex_ptr, ctx_ptr) };
+
+            to_result(ret)?;
+        }
+        LockKind::Interruptible => {
+            // SAFETY: `Mutex` is always pinned. If `AcquireCtx` is `Some`, it is pinned,
+            // if `None`, it is set to `core::ptr::null_mut()`. Both cases are safe.
+            let ret = unsafe { bindings::ww_mutex_lock_interruptible(mutex_ptr, ctx_ptr) };
+
+            to_result(ret)?;
+        }
+        LockKind::Try => {
+            // SAFETY: `Mutex` is always pinned. If `AcquireCtx` is `Some`, it is pinned,
+            // if `None`, it is set to `core::ptr::null_mut()`. Both cases are safe.
+            let ret = unsafe { bindings::ww_mutex_trylock(mutex_ptr, ctx_ptr) };
+
+            if ret == 0 {
+                return Err(EBUSY);
+            } else {
+                to_result(ret)?;
+            }
+        }
+    };
+
+    Ok(MutexGuard::new(mutex))
+}
 
[snip]

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +68 -0

new file mode 100644
index 0000000000000..18f4654e7df26
@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Provides [`AcquireCtx`] for managing multiple wound/wait
+//! mutexes from the same [`Class`].
+
+use super::{
+    lock_common,
+    Class,
+    LockKind,
+    Mutex,
+    MutexGuard, //
+};
+use crate::{
+    bindings,
+    prelude::*,
+    types::Opaque, //
+};
+use core::marker::PhantomData;
+
+/// Groups multiple [`Mutex`]es for deadlock avoidance when acquired
+/// with the same [`Class`].
+///
+/// # Examples
+///
+/// ```
+/// use kernel::{
+///     define_ww_class,
+///     sync::{
+///         lock::ww_mutex::{
+///             AcquireCtx,
+///             Class,
+///             Mutex, //
+///         },
+///         Arc,
+///     },
+/// };
+/// use pin_init::stack_pin_init;
+///
+/// define_ww_class!(SOME_WW_CLASS);
+///
+/// // Create mutexes.
+/// let mutex1 = Arc::pin_init(Mutex::new(1, &SOME_WW_CLASS), GFP_KERNEL)?;
+/// let mutex2 = Arc::pin_init(Mutex::new(2, &SOME_WW_CLASS), GFP_KERNEL)?;
+///
+/// // Create acquire context for deadlock avoidance.
+/// let ctx = KBox::pin_init(AcquireCtx::new(&SOME_WW_CLASS), GFP_KERNEL)?;
+///
+/// // SAFETY: The guard is dropped before `ctx`.
+/// let guard1 = unsafe { ctx.lock(&mutex1) }?;
+/// // SAFETY: The guard is dropped before `ctx`.
+/// let guard2 = unsafe { ctx.lock(&mutex2) }?;
+///
+/// // Mark acquisition phase as complete.
+/// ctx.done();
+///
+/// # Ok::<(), Error>(())
+/// ```
+#[pin_data(PinnedDrop)]
+#[repr(transparent)]
+pub struct AcquireCtx<'a> {
+    #[pin]
+    pub(super) inner: Opaque<bindings::ww_acquire_ctx>,
+    _p: PhantomData<&'a Class>,
+}
+
+impl<'class> AcquireCtx<'class> {
+    /// Initializes a new [`AcquireCtx`] with the given [`Class`].
+    pub fn new(class: &'class Class) -> impl PinInit<Self> {

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +56 -0

+
+    /// Creates a [`AcquireCtx`] from a raw pointer.
+    ///
+    /// This function is intended for interoperability with C code.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` is a valid pointer to the `inner` field
+    /// of [`AcquireCtx`] and that it remains valid for the lifetime `'a`.
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::ww_acquire_ctx) -> &'a Self {
+        // SAFETY: By the safety contract, `ptr` is valid to construct `AcquireCtx`.
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Marks the end of the acquire phase.
+    ///
+    /// Calling this function is optional. It is just useful to document
+    /// the code and clearly designated the acquire phase from actually
+    /// using the locked data structures.
+    ///
+    /// After calling this function, no more mutexes can be acquired with
+    /// this context.
+    #[inline]
+    pub fn done(&self) {
+        // SAFETY: `self.inner` contains a valid, initialized acquire context.
+        unsafe { bindings::ww_acquire_done(self.inner.get()) };
+    }
+
+    /// Locks the given [`Mutex`] on this [`AcquireCtx`].
+    ///
+    /// # Safety
+    ///
+    /// On success, the caller must keep this context valid until the mutex is unlocked,
+    /// even if the returned guard is forgotten. The context must not be finalized or
+    /// reinitialized while the mutex remains locked.
+    pub unsafe fn lock<'a, T>(&'a self, mutex: &'a Mutex<'a, T>) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Regular)
+    }
+
+    /// Similar to [`Self::lock`], but can be interrupted by signals.
+    ///
+    /// # Safety
+    ///
+    /// The same requirements as [`Self::lock`] apply.
+    pub unsafe fn lock_interruptible<'a, T>(
+        &'a self,
+        mutex: &'a Mutex<'a, T>,
+    ) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Interruptible)
+    }
+
+    /// Tries to lock the [`Mutex`] on this [`AcquireCtx`] without blocking.
+    ///
+    /// Unlike [`Self::lock`], no deadlock handling is performed.
+    ///
+    /// # Safety

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +5 -0

+        // SAFETY: The locking methods require callers to release all acquired locks
+        // before this context is dropped.
+        unsafe { bindings::ww_acquire_fini(self.inner.get()) };
+    }
+}

Quoted 74 lines · Onur Özkan

Covers the low-level locking API (lock, try_lock and interruptible variants) and integration with kernel bindings.

Reviewed-by Alice Ryhl <[email protected]>

Signed-off-by Onur Özkan <[email protected]>

---
 rust/kernel/sync/lock/ww_mutex.rs             | 434 ++++++++++++++++++
 rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs | 149 ++++++
 2 files changed, 583 insertions(+)
 create mode 100644 rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs

rust/kernel/sync/lock/ww_mutex.rs +51 -0

index 727c51cc73af8..2423f89a7e762 100644
@@ -1,7 +1,441 @@
 // SPDX-License-Identifier: GPL-2.0
 
 //! Rust abstractions for the kernel's wound-wait locking primitives.
+//!
+//! It is designed to avoid deadlocks when locking multiple [`Mutex`]es
+//! that belong to the same [`Class`]. Each lock acquisition uses an
+//! [`AcquireCtx`] to track ordering and ensure forward progress.
+//!
+//! See srctree/Documentation/locking/ww-mutex-design.rst for more details.
 
+use crate::{
+    bindings,
+    container_of,
+    error::to_result,
+    prelude::*,
+    types::{
+        NotThreadSafe,
+        Opaque, //
+    }, //
+};
+use core::{
+    cell::UnsafeCell,
+    marker::PhantomData, //
+};
+
+pub use acquire_ctx::AcquireCtx;
 pub use class::Class;
 
+mod acquire_ctx;
 mod class;
+
+/// A wound-wait (ww) mutex that is powered with deadlock avoidance
+/// when acquiring multiple locks of the same [`Class`].
+///
+/// Each mutex belongs to a [`Class`], which the wound-wait algorithm
+/// uses to figure out the order of acquisition and prevent deadlocks.
+///
+/// # Examples
+///
+/// ```
+/// use kernel::{
+///     define_ww_class,
+///     sync::{
+///         lock::ww_mutex::{
+///             AcquireCtx,
+///             Class,
+///             Mutex, //
+///         },
+///         Arc,
+///     },
+/// };
+/// use pin_init::stack_pin_init;
+///
+/// define_ww_class!(SOME_WW_CLASS);
+///
+/// let mutex = Arc::pin_init(Mutex::new(42, &SOME_WW_CLASS), GFP_KERNEL)?;
+/// let ctx = KBox::pin_init(AcquireCtx::new(&SOME_WW_CLASS), GFP_KERNEL)?;
+///

rust/kernel/sync/lock/ww_mutex.rs line 68

Quoted 10 lines

rust/kernel/sync/lock/ww_mutex.rs +10 -0

+/// // SAFETY: The guard is dropped before `ctx`.
+/// let guard = unsafe { ctx.lock(&mutex) }?;
+/// assert_eq!(*guard, 42);
+///
+/// # Ok::<(), Error>(())
+/// ```
+#[pin_data]
+#[repr(C)]
+pub struct Mutex<'a, T: ?Sized> {
+    _p: PhantomData<&'a Class>,

Do you expect any users that have non-static class?

So far all in-kernel user of ww mutex has a static class.

Quoted 41 lines

rust/kernel/sync/lock/ww_mutex.rs +40 -0

+    #[pin]
+    inner: Opaque<bindings::ww_mutex>,
+    data: UnsafeCell<T>,
+}
+
+impl<'class, T> Mutex<'class, T> {
+    /// Initializes [`Mutex`] with the given `data` and [`Class`].
+    pub fn new(data: T, class: &'class Class) -> impl PinInit<Self> {
+        let class_ptr = class.inner.get();
+        pin_init!(Mutex {
+            inner <- Opaque::ffi_init(|slot: *mut bindings::ww_mutex| {
+                // SAFETY: `class` is valid for the lifetime `'class` captured by `Self`.
+                unsafe { bindings::ww_mutex_init(slot, class_ptr) }
+            }),
+            data: UnsafeCell::new(data),
+            _p: PhantomData
+        })
+    }
+}
+
+impl<'class, T: ?Sized> Mutex<'class, T> {
+    /// Checks if this [`Mutex`] is currently locked.
+    ///
+    /// The returned value is racy as another thread can acquire
+    /// or release the lock immediately after this call returns.
+    #[inline]
+    pub fn is_locked(&self) -> bool {
+        // SAFETY: It's safe to call `ww_mutex_is_locked` on
+        // a valid mutex.
+        unsafe { bindings::ww_mutex_is_locked(self.inner.get()) }
+    }
+
+    /// Locks this [`Mutex`] without [`AcquireCtx`].
+    pub fn lock(&self) -> Result<MutexGuard<'_, T>> {
+        lock_common(self, None, LockKind::Regular)
+    }
+
+    /// Similar to [`Self::lock`], but can be interrupted by signals.
+    pub fn lock_interruptible(&self) -> Result<MutexGuard<'_, T>> {
+        lock_common(self, None, LockKind::Interruptible)

rust/kernel/sync/lock/ww_mutex.rs line 114

Quoted 6 lines

rust/kernel/sync/lock/ww_mutex.rs +6 -0

+    }
+
+    /// Tries to lock this [`Mutex`] with no [`AcquireCtx`] and without blocking.
+    ///
+    /// Unlike [`Self::lock`], no deadlock handling is performed.
+    pub fn try_lock(&self) -> Result<MutexGuard<'_, T>> {

try_lock failure should return Option instead.

Quoted 92 lines

rust/kernel/sync/lock/ww_mutex.rs +91 -0

+        lock_common(self, None, LockKind::Try)
+    }
+}
+
+impl<'class> Mutex<'class, ()> {
+    /// Creates a [`Mutex`] from a raw pointer.
+    ///
+    /// This function is intended for interoperability with C code.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that:
+    ///
+    /// - `ptr` is a valid pointer to a `ww_mutex`.
+    /// - `ptr` must remain valid for the lifetime `'a`.
+    /// - ww_class associated with this mutex must be valid for
+    ///   the lifetime `'class`.
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::ww_mutex) -> &'a Self {
+        // SAFETY: By the safety contract, the caller guarantees that `ptr`
+        // points to a valid `ww_mutex` which is the `inner` field of `Mutex`,
+        // that it remains valid for the lifetime `'a` and the associated
+        // ww_class outlives `'class`.
+        //
+        // Because [`Mutex`] is `#[repr(C)]`, the `inner` field sits at a
+        // stable offset that `container_of!` can safely rely on.
+        unsafe { &*container_of!(Opaque::cast_from(ptr), Self, inner) }
+    }
+}
+
+// SAFETY: `Mutex` can be sent to another thread if the protected
+// data `T` can be.
+unsafe impl<T: ?Sized + Send> Send for Mutex<'_, T> {}
+
+// SAFETY: `Mutex` serialises access to the protected data, so it is
+// `Sync` as long as the data is `Send`.
+unsafe impl<T: ?Sized + Send> Sync for Mutex<'_, T> {}
+
+/// A guard that provides exclusive access to the data protected
+/// by a [`Mutex`].
+///
+/// # Invariants
+///
+/// The guard holds an exclusive lock on the associated [`Mutex`]. The lock is held
+/// for the entire lifetime of this guard and is automatically released when the
+/// guard is dropped.
+#[must_use = "the lock unlocks immediately when the guard is unused"]
+pub struct MutexGuard<'a, T: ?Sized> {
+    mutex: &'a Mutex<'a, T>,
+    _not_send: NotThreadSafe,
+}
+
+impl<'a, T: ?Sized> MutexGuard<'a, T> {
+    /// Creates a new guard for the given [`Mutex`].
+    fn new(mutex: &'a Mutex<'a, T>) -> Self {
+        assert!(mutex.is_locked());
+
+        // INVARIANT: `lock_common` and `from_raw` ensure that the current task holds the mutex
+        // and transfer sole responsibility for unlocking it to this guard.
+        Self {
+            mutex,
+            _not_send: NotThreadSafe,
+        }
+    }
+}
+
+impl<'a> MutexGuard<'a, ()> {
+    /// Creates a [`MutexGuard`] from a raw pointer.
+    ///
+    /// If the given pointer refers to a mutex that is not locked,
+    /// returns [`EINVAL`].
+    ///
+    /// This function is intended for interoperability with C code.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that:
+    ///
+    /// - `ptr` is a valid pointer to a `ww_mutex`.
+    /// - `ptr` must remain valid for the lifetime `'b`.
+    /// - The `ww_class` associated with the `ww_mutex` must be valid for the lifetime `'b`.
+    /// - The current task holds the mutex.
+    /// - The caller transfers responsibility for unlocking the mutex to the returned guard
+    ///   and must not unlock it separately (including through another guard).
+    /// - Any associated acquire context remains valid until the mutex is unlocked,
+    ///   even if the returned guard is forgotten. The context must not be finalized or
+    ///   reinitialized before then.
+    pub unsafe fn from_raw<'b>(ptr: *mut bindings::ww_mutex) -> Result<MutexGuard<'b, ()>> {
+        // SAFETY: By this function's safety contract, the caller guarantees that `ptr` points to a
+        // valid `ww_mutex` which is the `inner` field of a `Mutex`. The caller also guarantees
+        // that both `ptr` and the associated `ww_class` are valid for the lifetime `'b`.
+        let mutex = unsafe { Mutex::from_raw(ptr) };

rust/kernel/sync/lock/ww_mutex.rs line 209

Quoted 4 lines

rust/kernel/sync/lock/ww_mutex.rs +4 -0

+
+        if !mutex.is_locked() {
+            return Err(EINVAL);
+        }

Why is this checked despite being an unsafe function. Do you expect users to call this without knowing the lock is already locked? I think that's unlikely. Perhaps make this a debug_assert instead?

rust/kernel/sync/lock/ww_mutex.rs line 217

Quoted 9 lines

rust/kernel/sync/lock/ww_mutex.rs +8 -0

+
+        Ok(MutexGuard::new(mutex))
+    }
+}
+
+impl<T: ?Sized> core::ops::Deref for MutexGuard<'_, T> {
+    type Target = T;
+

#[inline] for this and others.

Quoted 38 lines

rust/kernel/sync/lock/ww_mutex.rs +38 -0

+    fn deref(&self) -> &Self::Target {
+        // SAFETY: self.mutex is locked, so we have exclusive access.
+        unsafe { &*self.mutex.data.get() }
+    }
+}
+
+impl<T: ?Sized + Unpin> core::ops::DerefMut for MutexGuard<'_, T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        // SAFETY: self.mutex is locked, so we have exclusive access.
+        unsafe { &mut *self.mutex.data.get() }
+    }
+}
+
+impl<T: ?Sized> Drop for MutexGuard<'_, T> {
+    #[inline]
+    fn drop(&mut self) {
+        // SAFETY: self.mutex is locked and are about to release it.
+        unsafe { bindings::ww_mutex_unlock(self.mutex.inner.get()) };
+    }
+}
+
+// SAFETY: `MutexGuard` can be shared between threads if the data can.
+unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
+
+/// Locking kinds used by [`lock_common`] to unify the internal
+/// locking logic.
+///
+/// It's best not to expose this type (and [`lock_common`]) to the
+/// kernel, as it allows internal API changes without worrying
+/// about breaking external compatibility.
+#[derive(Copy, Clone, Debug)]
+enum LockKind {
+    /// Blocks until lock is acquired.
+    Regular,
+    /// Blocks but can be interrupted by signals.
+    Interruptible,
+    /// Does not block, returns immediately if busy.
+    Try,

rust/kernel/sync/lock/ww_mutex.rs line 265

Quoted 10 lines

rust/kernel/sync/lock/ww_mutex.rs +10 -0

+}
+
+/// Internal helper that unifies the different locking kinds.
+///
+/// Returns [`EINVAL`] if the [`Mutex`] has a different [`Class`].
+fn lock_common<'a, T: ?Sized>(
+    mutex: &'a Mutex<'a, T>,
+    ctx: Option<&AcquireCtx<'_>>,
+    kind: LockKind,
+) -> Result<MutexGuard<'a, T>> {

I think we should have 3 helpers, to avoid having to branch on kind which is compile-tiome known information.

The only part between the 3 kinds that is shared is the ctx_ptr computation. I think it should be extracted to its own helper, and be used for 3 types of locking.

Quoted 13 lines

rust/kernel/sync/lock/ww_mutex.rs +12 -0

+    let mutex_ptr = mutex.inner.get();
+
+    let ctx_ptr = match ctx {
+        Some(acquire_ctx) => {
+            let ctx_ptr = acquire_ctx.inner.get();
+
+            // SAFETY: `ctx_ptr` is a valid pointer for the entire
+            // lifetime of `ctx`.
+            let ctx_class = unsafe { (*ctx_ptr).ww_class };
+
+            // SAFETY: `mutex_ptr` is a valid pointer for the entire
+            // lifetime of `mutex`.

rust/kernel/sync/lock/ww_mutex.rs line 283

Quoted 6 lines

rust/kernel/sync/lock/ww_mutex.rs +6 -0

+            let mutex_class = unsafe { (*mutex_ptr).ww_class };
+
+            // `ctx` and `mutex` must use the same class.
+            if ctx_class != mutex_class {
+                return Err(EINVAL);
+            }

This is supposed to be a error condition?

Quoted 114 lines

rust/kernel/sync/lock/ww_mutex.rs +36 -0

+
+            ctx_ptr
+        }
+        None => core::ptr::null_mut(),
+    };
+
+    match kind {
+        LockKind::Regular => {
+            // SAFETY: `Mutex` is always pinned. If `AcquireCtx` is `Some`, it is pinned,
+            // if `None`, it is set to `core::ptr::null_mut()`. Both cases are safe.
+            let ret = unsafe { bindings::ww_mutex_lock(mutex_ptr, ctx_ptr) };
+
+            to_result(ret)?;
+        }
+        LockKind::Interruptible => {
+            // SAFETY: `Mutex` is always pinned. If `AcquireCtx` is `Some`, it is pinned,
+            // if `None`, it is set to `core::ptr::null_mut()`. Both cases are safe.
+            let ret = unsafe { bindings::ww_mutex_lock_interruptible(mutex_ptr, ctx_ptr) };
+
+            to_result(ret)?;
+        }
+        LockKind::Try => {
+            // SAFETY: `Mutex` is always pinned. If `AcquireCtx` is `Some`, it is pinned,
+            // if `None`, it is set to `core::ptr::null_mut()`. Both cases are safe.
+            let ret = unsafe { bindings::ww_mutex_trylock(mutex_ptr, ctx_ptr) };
+
+            if ret == 0 {
+                return Err(EBUSY);
+            } else {
+                to_result(ret)?;
+            }
+        }
+    };
+
+    Ok(MutexGuard::new(mutex))
+}
 
[snip]

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +68 -0

new file mode 100644
index 0000000000000..18f4654e7df26
@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Provides [`AcquireCtx`] for managing multiple wound/wait
+//! mutexes from the same [`Class`].
+
+use super::{
+    lock_common,
+    Class,
+    LockKind,
+    Mutex,
+    MutexGuard, //
+};
+use crate::{
+    bindings,
+    prelude::*,
+    types::Opaque, //
+};
+use core::marker::PhantomData;
+
+/// Groups multiple [`Mutex`]es for deadlock avoidance when acquired
+/// with the same [`Class`].
+///
+/// # Examples
+///
+/// ```
+/// use kernel::{
+///     define_ww_class,
+///     sync::{
+///         lock::ww_mutex::{
+///             AcquireCtx,
+///             Class,
+///             Mutex, //
+///         },
+///         Arc,
+///     },
+/// };
+/// use pin_init::stack_pin_init;
+///
+/// define_ww_class!(SOME_WW_CLASS);
+///
+/// // Create mutexes.
+/// let mutex1 = Arc::pin_init(Mutex::new(1, &SOME_WW_CLASS), GFP_KERNEL)?;
+/// let mutex2 = Arc::pin_init(Mutex::new(2, &SOME_WW_CLASS), GFP_KERNEL)?;
+///
+/// // Create acquire context for deadlock avoidance.
+/// let ctx = KBox::pin_init(AcquireCtx::new(&SOME_WW_CLASS), GFP_KERNEL)?;
+///
+/// // SAFETY: The guard is dropped before `ctx`.
+/// let guard1 = unsafe { ctx.lock(&mutex1) }?;
+/// // SAFETY: The guard is dropped before `ctx`.
+/// let guard2 = unsafe { ctx.lock(&mutex2) }?;
+///
+/// // Mark acquisition phase as complete.
+/// ctx.done();
+///
+/// # Ok::<(), Error>(())
+/// ```
+#[pin_data(PinnedDrop)]
+#[repr(transparent)]
+pub struct AcquireCtx<'a> {
+    #[pin]
+    pub(super) inner: Opaque<bindings::ww_acquire_ctx>,
+    _p: PhantomData<&'a Class>,
+}
+
+impl<'class> AcquireCtx<'class> {
+    /// Initializes a new [`AcquireCtx`] with the given [`Class`].
+    pub fn new(class: &'class Class) -> impl PinInit<Self> {

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs line 78

Quoted 10 lines

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +10 -0

+        let class_ptr = class.inner.get();
+        pin_init!(AcquireCtx {
+            inner <- Opaque::ffi_init(|slot: *mut bindings::ww_acquire_ctx| {
+                // SAFETY: `class` is valid for the lifetime `'class` captured
+                // by `AcquireCtx`.
+                unsafe { bindings::ww_acquire_init(slot, class_ptr) }
+            }),
+            _p: PhantomData
+        })
+    }

I wonder if a better API would be

class.new_context()

vs.

AcquireCtx::new(&class)

?

Quoted 57 lines

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +56 -0

+
+    /// Creates a [`AcquireCtx`] from a raw pointer.
+    ///
+    /// This function is intended for interoperability with C code.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that `ptr` is a valid pointer to the `inner` field
+    /// of [`AcquireCtx`] and that it remains valid for the lifetime `'a`.
+    pub unsafe fn from_raw<'a>(ptr: *mut bindings::ww_acquire_ctx) -> &'a Self {
+        // SAFETY: By the safety contract, `ptr` is valid to construct `AcquireCtx`.
+        unsafe { &*ptr.cast() }
+    }
+
+    /// Marks the end of the acquire phase.
+    ///
+    /// Calling this function is optional. It is just useful to document
+    /// the code and clearly designated the acquire phase from actually
+    /// using the locked data structures.
+    ///
+    /// After calling this function, no more mutexes can be acquired with
+    /// this context.
+    #[inline]
+    pub fn done(&self) {
+        // SAFETY: `self.inner` contains a valid, initialized acquire context.
+        unsafe { bindings::ww_acquire_done(self.inner.get()) };
+    }
+
+    /// Locks the given [`Mutex`] on this [`AcquireCtx`].
+    ///
+    /// # Safety
+    ///
+    /// On success, the caller must keep this context valid until the mutex is unlocked,
+    /// even if the returned guard is forgotten. The context must not be finalized or
+    /// reinitialized while the mutex remains locked.
+    pub unsafe fn lock<'a, T>(&'a self, mutex: &'a Mutex<'a, T>) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Regular)
+    }
+
+    /// Similar to [`Self::lock`], but can be interrupted by signals.
+    ///
+    /// # Safety
+    ///
+    /// The same requirements as [`Self::lock`] apply.
+    pub unsafe fn lock_interruptible<'a, T>(
+        &'a self,
+        mutex: &'a Mutex<'a, T>,
+    ) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Interruptible)
+    }
+
+    /// Tries to lock the [`Mutex`] on this [`AcquireCtx`] without blocking.
+    ///
+    /// Unlike [`Self::lock`], no deadlock handling is performed.
+    ///
+    /// # Safety

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs line 144

Quoted 10 lines

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +10 -0

+    ///
+    /// The same requirements as [`Self::lock`] apply.
+    pub unsafe fn try_lock<'a, T>(&'a self, mutex: &'a Mutex<'a, T>) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Try)
+    }
+}
+
+#[pinned_drop]
+impl PinnedDrop for AcquireCtx<'_> {
+    fn drop(self: Pin<&mut Self>) {

I wonder if we can just do

    let acquired = unsafe { (*self.inner.get()).acquired };
    assert!(!acquired);

to get rid of the unsafe. Somewhat similar to what we do with srcu. Of course, ultimately we want to use !Leak for this and can remove the check.

Thoughts?

Best,
Gary

Quoted 5 lines

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +5 -0

+        // SAFETY: The locking methods require callers to release all acquired locks
+        // before this context is dropped.
+        unsafe { bindings::ww_acquire_fini(self.inner.get()) };
+    }
+}

Quoted 31 lines

Quoted 18 lines

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +18 -0

+
+    /// Similar to [`Self::lock`], but can be interrupted by signals.
+    ///
+    /// # Safety
+    ///
+    /// The same requirements as [`Self::lock`] apply.
+    pub unsafe fn lock_interruptible<'a, T>(
+        &'a self,
+        mutex: &'a Mutex<'a, T>,
+    ) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Interruptible)
+    }
+
+    /// Tries to lock the [`Mutex`] on this [`AcquireCtx`] without blocking.
+    ///
+    /// Unlike [`Self::lock`], no deadlock handling is performed.
+    ///
+    /// # Safety

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs line 144

Quoted 10 lines

rust/kernel/sync/lock/ww_mutex/acquire_ctx.rs new file +10 -0

+    ///
+    /// The same requirements as [`Self::lock`] apply.
+    pub unsafe fn try_lock<'a, T>(&'a self, mutex: &'a Mutex<'a, T>) -> Result<MutexGuard<'a, T>> {
+        lock_common(mutex, Some(self), LockKind::Try)
+    }
+}
+
+#[pinned_drop]
+impl PinnedDrop for AcquireCtx<'_> {
+    fn drop(self: Pin<&mut Self>) {

I wonder if we can just do

Quoted 5 lines

    let acquired = unsafe { (*self.inner.get()).acquired };
    assert!(!acquired);

to get rid of the unsafe. Somewhat similar to what we do with srcu. Of course, ultimately we want to use !Leak for this and can remove the check.

I didn't understand this. You also wrote an unsafe code?

LockSet is a high-level and safe API built on top of ww_mutex which provides a safe and easy to use API while keeping the ww_mutex semantics.

When EDEADLK is hit it drops all held locks and waits for the contended mutex. It then retries the given (by the user) locking algorithm with that mutex held and the same acquire context until it succeeds.

Signed-off-by Onur Özkan <[email protected]>

---
 rust/kernel/sync/lock/ww_mutex.rs          |   6 +
 rust/kernel/sync/lock/ww_mutex/lock_set.rs | 449 +++++++++++++++++++++
 2 files changed, 455 insertions(+)
 create mode 100644 rust/kernel/sync/lock/ww_mutex/lock_set.rs

Quoted 8 lines · Onur Özkan

LockSet is a high-level and safe API built on top of ww_mutex which provides a safe and easy to use API while keeping the ww_mutex semantics.

When EDEADLK is hit it drops all held locks and waits for the contended mutex. It then retries the given (by the user) locking algorithm with that mutex held and the same acquire context until it succeeds.

Do we really need this, or this can be achieved by simple retry loops?

    fn retry_if_deadlock<R>(f: impl FnOnce() -> Result<R>) -> Result<R> {
        loop {
            match f() {
                Err(EDEADLK) => (),
                e => return e,
            }
        }
    }

    stack_pin_init!(let acq_ctx = AcquireCtx::new(&class));
    retry_if_deadlock(|| {
        let mut gaurd1 = acq_ctx.lock(&mutex1)?;
        let mut guard2 = acq_ctx.lock(&mutex2)?;

        acq_ctx.done();

        *guard1 += 1;
        *guard2 += 1;
    });

I think the only difference is that the LockSet acquires the contending mutex first. However, I imagine we can solve this by having a wrapped AcquireCtx that provides that.

Best,
Gary

Quoted 7 lines

Signed-off-by Onur Özkan <[email protected]>

---
 rust/kernel/sync/lock/ww_mutex.rs          |   6 +
 rust/kernel/sync/lock/ww_mutex/lock_set.rs | 449 +++++++++++++++++++++
 2 files changed, 455 insertions(+)
 create mode 100644 rust/kernel/sync/lock/ww_mutex/lock_set.rs

Quoted 32 lines · On Mon, 12 Oct 2026 13:02:15 +0100 Gary Guo <[email protected]> wrote:

Quoted 8 lines · Onur Özkan

LockSet is a high-level and safe API built on top of ww_mutex which provides a safe and easy to use API while keeping the ww_mutex semantics.

When EDEADLK is hit it drops all held locks and waits for the contended mutex. It then retries the given (by the user) locking algorithm with that mutex held and the same acquire context until it succeeds.

Do we really need this, or this can be achieved by simple retry loops?

    fn retry_if_deadlock<R>(f: impl FnOnce() -> Result<R>) -> Result<R> {
        loop {
            match f() {
                Err(EDEADLK) => (),
                e => return e,
            }
        }
    }

    stack_pin_init!(let acq_ctx = AcquireCtx::new(&class));
    retry_if_deadlock(|| {
        let mut gaurd1 = acq_ctx.lock(&mutex1)?;
        let mut guard2 = acq_ctx.lock(&mutex2)?;

        acq_ctx.done();

        *guard1 += 1;
        *guard2 += 1;
    });

Quoted 3 lines

I think the only difference is that the LockSet acquires the contending mutex first. However, I imagine we can solve this by having a wrapped AcquireCtx that provides that.

That's what LockSet already is. How would you design that wrapped AcquireCtx and what would we gain by replacing LockSet with another wrapper?

You need to remember the contended mutex, release all acquired locks before waiting for it and retry with that mutex held and the same acquire context.

Also for a dynamic set, you also need to keep the acquired locks held across loop iterations and helper calls and handle repeated objects. With ordinary guards, that bookkeeping falls on the caller unless the wrapper handles it. LockSet already does all this.

Quoted 35 lines · Onur Özkan

Quoted 32 lines · On Mon, 12 Oct 2026 13:02:15 +0100 Gary Guo <[email protected]> wrote:

Quoted 8 lines · Onur Özkan

LockSet is a high-level and safe API built on top of ww_mutex which provides a safe and easy to use API while keeping the ww_mutex semantics.

When EDEADLK is hit it drops all held locks and waits for the contended mutex. It then retries the given (by the user) locking algorithm with that mutex held and the same acquire context until it succeeds.

Do we really need this, or this can be achieved by simple retry loops?

    fn retry_if_deadlock<R>(f: impl FnOnce() -> Result<R>) -> Result<R> {
        loop {
            match f() {
                Err(EDEADLK) => (),
                e => return e,
            }
        }
    }

    stack_pin_init!(let acq_ctx = AcquireCtx::new(&class));
    retry_if_deadlock(|| {
        let mut gaurd1 = acq_ctx.lock(&mutex1)?;
        let mut guard2 = acq_ctx.lock(&mutex2)?;

        acq_ctx.done();

        *guard1 += 1;
        *guard2 += 1;
    });

Quoted 6 lines

Quoted 3 lines

I think the only difference is that the LockSet acquires the contending mutex first. However, I imagine we can solve this by having a wrapped AcquireCtx that provides that.

That's what LockSet already is. How would you design that wrapped AcquireCtx and what would we gain by replacing LockSet with another wrapper?

The LockSet API have multiple issues that I consider problematic:

* It always allocate, even if you don't need a dynamic set.

* Accessing data searches through the vec. To access all data, you will have O(n^2) complexity spent just on vec traversal.

* There's no way of getting multiple mutable borrow of the distinct locks.

My example above has none of the issue.

If you do not need the "acquire the contended lock first" behaviour, then there's no need for wrapper, even. Also, if this behaviour is truly universal, perhaps it should become part of AcquireCtx's default behaviour instead.

Quoted 4 lines

You need to remember the contended mutex, release all acquired locks before waiting for it and retry with that mutex held and the same acquire context.

My example above doesn't have these issues. Releasing acquired locks if free with ?. Retrying is done by the helper function and not handled by user. Acquire context if really easy to be misued, can be done by the helper function too:

    fn ww_transaction<R>(
        class: &Class, f: impl FnOnce(&AcquireCtx) -> Result<R>
    ) -> Result<R> {
        stack_pin_init!(let acq_ctx = AcquireCtx::new(&class));
        loop {
            match f(&acq_Ctx) {
                Err(EDEADLK) => (),
                e => return e,
            }
        }
    }

    ww_transaction(&class, |acq_ctx| {

        let mut guard1 = acq_ctx.lock(&mutex1)?;
        let mut guard2 = acq_ctx.lock(&mutex2)?;

        acq_ctx.done();

        *guard1 += 1;
        *guard2 += 1;
    })

Quoted 5 lines

Also for a dynamic set, you also need to keep the acquired locks held across loop iterations and helper calls and handle repeated objects. With ordinary guards, that bookkeeping falls on the caller unless the wrapper handles it. LockSet already does all this.

You can make dynamic lock set just a data structure and not do everything at once, something like:

    ww_transaction(&class, |acq_ctx| {
        let dynset = DynLockSet::new()?;

        // Check if already inside the set, if not, lock it.
        dynset.lock(acq_ctx, &mutex1)?;
        dynset.lock(acq_ctx, &mutex2)?;

        acq_ctx.done();

        dynset.with_locked(&mutex1, |guard1| *guard1 += 1)?;
        dynset.with_locked(&mutex2, |guard2| *guard2 += 1)?;
    })

Best,
Gary

Quoted 3 lines · On Thu, 15 Oct 2026 12:53:10 +0100 Gary Guo <[email protected]> wrote:

If you do not need the "acquire the contended lock first" behaviour, then there's no need for wrapper, even. Also, if this behaviour is truly universal, perhaps it should become part of AcquireCtx's default behaviour instead.

We need that functionality for the DRM use-case, it's not something that should be applied to the ww mutex primitives but I would like to hear @Daniel's opinion on this.

[snip]

This still needs the contended-lock backoff when retrying the full transaction. Simply restarting the callback can repeatedly hit EDEADLK, so the proposed code is not going to work.