[PATCH 0/3] Groundwork for Lock<T> when T is pinned

[PATCH 0/3] Groundwork for Lock<T> when T is pinned

[Daniel Almeida]

It's currently impossible to have a pinned struct within the Lock<T> type.
This is problematic, because drivers might want to do this for various
reasons, specially as they grow in complexity.

A trivial example is:

struct Foo {
  #[pin]
  bar: Mutex<Bar>,
  #[pin]
  p: PhantomPinned,
}

struct Bar {
  #[pin]
  baz: Mutex<Baz>,
  #[pin]
  p: PhantomPinned,
}

Note that Bar is pinned, so having it in a Mutex makes it impossible to
instantiate a Foo that pins the Bar in bar. This is specially undesirable,
since Foo is already pinned, and thus, it could trivially enforce that its
bar field is pinned as well.

This can be trivially solved by using Pin<KBox<Bar>> instead of
structurally pinning, at the cost of an extra (completely unneeded)
allocation and ugly syntax.

This series lays out the groundwork to make the above possible without any
extra allocations.

- Patch 1 structurally pins the 'data' field in Lock<T>
- Patch 2 constrains the DerefMut implementation for safety reasons
- Patch 3 adds an accessor to retrieve a Pin<&mut T>

Note that this is just the beginning of the work needed to make a Pin<&mut
T> actually useful due to pin projections being currently unsupported.

In other words, it is currently impossible (even with the current patch) to
do this:

let mut data: MutexGuard<'_, Data> = mutex.lock();
let mut data: Pin<&mut Data> = data.as_mut();
let foo = &mut data.foo; // <- won't compile

The above is something that Benno is working on.

Thanks Boqun, Benno and the rest of the team for brainstorming the issue
and for and laying out a series of steps to implement a solution.

---
Daniel Almeida (3):
      rust: lock: pin the inner data
      rust: lock: guard: add T: Unpin bound to DerefMut
      rust: lock: add a Pin<&mut T> accessor

 rust/kernel/sync/lock.rs        | 35 +++++++++++++++++++++++++++++++----
 rust/kernel/sync/lock/global.rs |  5 ++++-
 2 files changed, 35 insertions(+), 5 deletions(-)
---
base-commit: dff64b072708ffef23c117fa1ee1ea59eb417807
change-id: 20250730-lock-t-when-t-is-pinned-292474504acb

Best regards,
-- 
Daniel Almeida <daniel.almeida@collabora.com>

[PATCH 1/3] rust: lock: pin the inner data

[Daniel Almeida]

In preparation to support Lock<T> where T is pinned, the first thing that
needs to be done is to structurally pin the 'data' member. This switches
the 't' parameter in Lock<T>::new() to take in an impl PinInit<T> instead
of a plain T. This in turn uses the blanket implementation "impl PinInit<T>
for T".

Subsequent patches will touch on Guard<T>.

Link: https://github.com/Rust-for-Linux/linux/issues/1181
Suggested-by: Benno Lossin <lossin@kernel.org>
Suggested-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
---
 rust/kernel/sync/lock.rs | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index e82fa5be289c169b0c9cfe277e15988958563430..9715463cbab867a2cf59e75f03001d75e91bd7b6 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -11,7 +11,7 @@
     types::{NotThreadSafe, Opaque, ScopeGuard},
 };
 use core::{cell::UnsafeCell, marker::PhantomPinned, pin::Pin};
-use pin_init::{pin_data, pin_init, PinInit};
+use pin_init::{pin_data, pin_init, PinInit, Wrapper};
 
 pub mod mutex;
 pub mod spinlock;
@@ -115,6 +115,7 @@ pub struct Lock<T: ?Sized, B: Backend> {
     _pin: PhantomPinned,
 
     /// The data protected by the lock.
+    #[pin]
     pub(crate) data: UnsafeCell<T>,
 }
 
@@ -127,9 +128,13 @@ unsafe impl<T: ?Sized + Send, B: Backend> Sync for Lock<T, B> {}
 
 impl<T, B: Backend> Lock<T, B> {
     /// Constructs a new lock initialiser.
-    pub fn new(t: T, name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> {
+    pub fn new(
+        t: impl PinInit<T>,
+        name: &'static CStr,
+        key: Pin<&'static LockClassKey>,
+    ) -> impl PinInit<Self> {
         pin_init!(Self {
-            data: UnsafeCell::new(t),
+            data <- UnsafeCell::pin_init(t),
             _pin: PhantomPinned,
             // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have
             // static lifetimes so they live indefinitely.

-- 
2.50.1

Re: [PATCH 1/3] rust: lock: pin the inner data

[Benno Lossin]

On Wed Jul 30, 2025 at 7:14 PM CEST, Daniel Almeida wrote:
> In preparation to support Lock<T> where T is pinned, the first thing that
> needs to be done is to structurally pin the 'data' member. This switches
> the 't' parameter in Lock<T>::new() to take in an impl PinInit<T> instead
> of a plain T. This in turn uses the blanket implementation "impl PinInit<T>
> for T".
>
> Subsequent patches will touch on Guard<T>.
>
> Link: https://github.com/Rust-for-Linux/linux/issues/1181
> Suggested-by: Benno Lossin <lossin@kernel.org>
> Suggested-by: Boqun Feng <boqun.feng@gmail.com>
> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>

Reviewed-by: Benno Lossin <lossin@kernel.org>

---
Cheers,
Benno

> ---
>  rust/kernel/sync/lock.rs | 11 ++++++++---
>  1 file changed, 8 insertions(+), 3 deletions(-)

[PATCH 2/3] rust: lock: guard: add T: Unpin bound to DerefMut

[Daniel Almeida]

A core property of pinned types is not handing a mutable reference to the
inner data in safe code, as this trivially allows that data to be moved.

Enforce this condition by adding a bound on lock::Guard's DerefMut
implementation, so that it's only implemented for pinning-agnostic types.

Link: https://github.com/Rust-for-Linux/linux/issues/1181
Suggested-by: Benno Lossin <lossin@kernel.org>
Suggested-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
---
 rust/kernel/sync/lock.rs        | 5 ++++-
 rust/kernel/sync/lock/global.rs | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 9715463cbab867a2cf59e75f03001d75e91bd7b6..087bc0391f92a73b9af18ca31461b513bb5a9bcd 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -254,7 +254,10 @@ fn deref(&self) -> &Self::Target {
     }
 }
 
-impl<T: ?Sized, B: Backend> core::ops::DerefMut for Guard<'_, T, B> {
+impl<T: ?Sized, B: Backend> core::ops::DerefMut for Guard<'_, T, B>
+where
+    T: Unpin,
+{
     fn deref_mut(&mut self) -> &mut Self::Target {
         // SAFETY: The caller owns the lock, so it is safe to deref the protected data.
         unsafe { &mut *self.lock.data.get() }
diff --git a/rust/kernel/sync/lock/global.rs b/rust/kernel/sync/lock/global.rs
index d65f94b5caf2668586088417323496629492932f..38b44803279986275616eef499fd40b8d4e97fdf 100644
--- a/rust/kernel/sync/lock/global.rs
+++ b/rust/kernel/sync/lock/global.rs
@@ -106,7 +106,10 @@ fn deref(&self) -> &Self::Target {
     }
 }
 
-impl<B: GlobalLockBackend> core::ops::DerefMut for GlobalGuard<B> {
+impl<B: GlobalLockBackend> core::ops::DerefMut for GlobalGuard<B>
+where
+    B::Item: Unpin,
+{
     fn deref_mut(&mut self) -> &mut Self::Target {
         &mut self.inner
     }

-- 
2.50.1

Re: [PATCH 2/3] rust: lock: guard: add T: Unpin bound to DerefMut

[Benno Lossin]

On Wed Jul 30, 2025 at 7:14 PM CEST, Daniel Almeida wrote:
> A core property of pinned types is not handing a mutable reference to the
> inner data in safe code, as this trivially allows that data to be moved.
>
> Enforce this condition by adding a bound on lock::Guard's DerefMut
> implementation, so that it's only implemented for pinning-agnostic types.

This patch should probably be the first one in this series, as only
applying patch 1, but not this one is unsound...

> Link: https://github.com/Rust-for-Linux/linux/issues/1181
> Suggested-by: Benno Lossin <lossin@kernel.org>
> Suggested-by: Boqun Feng <boqun.feng@gmail.com>
> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>

With this moved:

Reviewed-by: Benno Lossin <lossin@kernel.org>

---
Cheers,
Benno

> ---
>  rust/kernel/sync/lock.rs        | 5 ++++-
>  rust/kernel/sync/lock/global.rs | 5 ++++-
>  2 files changed, 8 insertions(+), 2 deletions(-)

[PATCH 3/3] rust: lock: add a Pin<&mut T> accessor

[Daniel Almeida]

In order for callers to be able to access the inner T safely if T: !Unpin,
there needs to be a way to get a Pin<&mut T>. Add this accessor and a
corresponding example to tell users how it works.

This is not useful on its own for now, because we do not support pin
projections yet. This means that the following is not going to compile:

    let mut data: MutexGuard<'_, Data> = mutex.lock();
    let mut data: Pin<&mut Data> = data.as_mut();
    let foo = &mut data.foo;

A future patch can enable the behavior above by implementing support for
pin projections.

Link: https://github.com/Rust-for-Linux/linux/issues/1181
Suggested-by: Benno Lossin <lossin@kernel.org>
Suggested-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
---
 rust/kernel/sync/lock.rs | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
index 087bc0391f92a73b9af18ca31461b513bb5a9bcd..27857659a7f1ba4a8b844bb18d009d037e0c5b03 100644
--- a/rust/kernel/sync/lock.rs
+++ b/rust/kernel/sync/lock.rs
@@ -243,6 +243,25 @@ pub(crate) fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
 
         cb()
     }
+
+    /// Returns a pinned mutable reference to the protected data.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    ///     # use kernel::sync::{Mutex, MutexGuard};
+    ///     # use core::pin::Pin;
+    ///     struct Data;
+    ///
+    ///     fn example(mutex: &Mutex<Data>) {
+    ///         let mut data: MutexGuard<'_, Data> = mutex.lock();
+    ///         let mut data: Pin<&mut Data> = data.as_mut();
+    ///     }
+    /// ```
+    pub fn as_mut(&mut self) -> Pin<&mut T> {
+        // SAFETY: `self.lock.data` is structurally pinned.
+        unsafe { Pin::new_unchecked(&mut *self.lock.data.get()) }
+    }
 }
 
 impl<T: ?Sized, B: Backend> core::ops::Deref for Guard<'_, T, B> {

-- 
2.50.1

Re: [PATCH 3/3] rust: lock: add a Pin<&mut T> accessor

[Benno Lossin]

On Wed Jul 30, 2025 at 7:14 PM CEST, Daniel Almeida wrote:
> In order for callers to be able to access the inner T safely if T: !Unpin,
> there needs to be a way to get a Pin<&mut T>. Add this accessor and a
> corresponding example to tell users how it works.
>
> This is not useful on its own for now, because we do not support pin
> projections yet. This means that the following is not going to compile:
>
>     let mut data: MutexGuard<'_, Data> = mutex.lock();
>     let mut data: Pin<&mut Data> = data.as_mut();
>     let foo = &mut data.foo;
>
> A future patch can enable the behavior above by implementing support for
> pin projections.

I am currently working on a patch that adds pin projections to
`#[pin_data]`. It will most likely land in v6.18.

> Link: https://github.com/Rust-for-Linux/linux/issues/1181
> Suggested-by: Benno Lossin <lossin@kernel.org>
> Suggested-by: Boqun Feng <boqun.feng@gmail.com>
> Signed-off-by: Daniel Almeida <daniel.almeida@collabora.com>
> ---
>  rust/kernel/sync/lock.rs | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
>
> diff --git a/rust/kernel/sync/lock.rs b/rust/kernel/sync/lock.rs
> index 087bc0391f92a73b9af18ca31461b513bb5a9bcd..27857659a7f1ba4a8b844bb18d009d037e0c5b03 100644
> --- a/rust/kernel/sync/lock.rs
> +++ b/rust/kernel/sync/lock.rs
> @@ -243,6 +243,25 @@ pub(crate) fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
>  
>          cb()
>      }
> +
> +    /// Returns a pinned mutable reference to the protected data.
> +    ///

I would mention that the guard implements `DerefMut` when `T: Unpin`, so
in that case it is probably easier to use that instead of calling this
function.

> +    /// # Examples
> +    ///
> +    /// ```
> +    ///     # use kernel::sync::{Mutex, MutexGuard};
> +    ///     # use core::pin::Pin;
> +    ///     struct Data;
> +    ///
> +    ///     fn example(mutex: &Mutex<Data>) {
> +    ///         let mut data: MutexGuard<'_, Data> = mutex.lock();
> +    ///         let mut data: Pin<&mut Data> = data.as_mut();
> +    ///     }

No need to indent the code in the example.

---
Cheers,
Benno

> +    /// ```
> +    pub fn as_mut(&mut self) -> Pin<&mut T> {
> +        // SAFETY: `self.lock.data` is structurally pinned.
> +        unsafe { Pin::new_unchecked(&mut *self.lock.data.get()) }
> +    }
>  }
>  
>  impl<T: ?Sized, B: Backend> core::ops::Deref for Guard<'_, T, B> {

Re: [PATCH 0/3] Groundwork for Lock<T> when T is pinned

[Alice Ryhl]

On Wed, Jul 30, 2025 at 02:14:43PM -0300, Daniel Almeida wrote:
> It's currently impossible to have a pinned struct within the Lock<T> type.
> This is problematic, because drivers might want to do this for various
> reasons, specially as they grow in complexity.
> 
> A trivial example is:
> 
> struct Foo {
>   #[pin]
>   bar: Mutex<Bar>,
>   #[pin]
>   p: PhantomPinned,
> }
> 
> struct Bar {
>   #[pin]
>   baz: Mutex<Baz>,
>   #[pin]
>   p: PhantomPinned,
> }
> 
> Note that Bar is pinned, so having it in a Mutex makes it impossible to
> instantiate a Foo that pins the Bar in bar. This is specially undesirable,
> since Foo is already pinned, and thus, it could trivially enforce that its
> bar field is pinned as well.
> 
> This can be trivially solved by using Pin<KBox<Bar>> instead of
> structurally pinning, at the cost of an extra (completely unneeded)
> allocation and ugly syntax.
> 
> This series lays out the groundwork to make the above possible without any
> extra allocations.
> 
> - Patch 1 structurally pins the 'data' field in Lock<T>
> - Patch 2 constrains the DerefMut implementation for safety reasons
> - Patch 3 adds an accessor to retrieve a Pin<&mut T>
> 
> Note that this is just the beginning of the work needed to make a Pin<&mut
> T> actually useful due to pin projections being currently unsupported.
> 
> In other words, it is currently impossible (even with the current patch) to
> do this:
> 
> let mut data: MutexGuard<'_, Data> = mutex.lock();
> let mut data: Pin<&mut Data> = data.as_mut();
> let foo = &mut data.foo; // <- won't compile
> 
> The above is something that Benno is working on.
> 
> Thanks Boqun, Benno and the rest of the team for brainstorming the issue
> and for and laying out a series of steps to implement a solution.
> 
> ---
> Daniel Almeida (3):
>       rust: lock: pin the inner data
>       rust: lock: guard: add T: Unpin bound to DerefMut
>       rust: lock: add a Pin<&mut T> accessor

With the things that Benno said fixed:

Reviewed-by: Alice Ryhl <aliceryhl@google.com>